> For the complete documentation index, see [llms.txt](https://osl.mistium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://osl.mistium.com/packages/web/s3.md).

# s3

> S3-compatible object storage client

Use `s3` for S3-compatible object storage: buckets, objects, metadata, presigned URLs, and multipart-style helpers.

```javascript
import "osl/s3"
```

## API reference

### `s3` values

Methods available on `s3` values returned by this package or constructed by the language.

| Method                   | Returns     | Description          |
| ------------------------ | ----------- | -------------------- |
| `value.new(cfg: object)` | `*s3Client` | Creates a new value. |

### `s3Client` values

Methods available on `s3Client` values returned by this package or constructed by the language.

| Method                                                                    | Returns  | Description                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value.cfgStr(k: string)`                                                 | `string` | Runs the cfg str operation.                                                                                                                                                                                                                                                                                                            |
| `value.cfgDef(v: any, d: string)`                                         | `string` | Runs the cfg def operation.                                                                                                                                                                                                                                                                                                            |
| `value.endpoint()`                                                        | `string` | Runs the endpoint operation.                                                                                                                                                                                                                                                                                                           |
| `value.bucket()`                                                          | `string` | Runs the bucket operation.                                                                                                                                                                                                                                                                                                             |
| `value.access()`                                                          | `string` | Runs the access operation.                                                                                                                                                                                                                                                                                                             |
| `value.secret()`                                                          | `string` | Runs the secret operation.                                                                                                                                                                                                                                                                                                             |
| `value.region()`                                                          | `string` | Runs the region operation.                                                                                                                                                                                                                                                                                                             |
| `value.host()`                                                            | `string` | Runs the host operation.                                                                                                                                                                                                                                                                                                               |
| `value.public(key: string)`                                               | `string` | Runs the public operation.                                                                                                                                                                                                                                                                                                             |
| `value.toBytes(v: any)`                                                   | `bytes`  | Converts to bytes.                                                                                                                                                                                                                                                                                                                     |
| `value.sha256hex(b: bytes)`                                               | `string` | Runs the sha256hex operation.                                                                                                                                                                                                                                                                                                          |
| `value.amzDate(t: time.Time)`                                             | `string` | Runs the amz date operation.                                                                                                                                                                                                                                                                                                           |
| `value.shortDate(t: time.Time)`                                           | `string` | Runs the short date operation.                                                                                                                                                                                                                                                                                                         |
| `value.sign(method: string, key: string, payload: string, query: string)` | `string` | Runs the sign operation.                                                                                                                                                                                                                                                                                                               |
| `value.sortQuery(q: object)`                                              | `string` | Runs the sort query operation.                                                                                                                                                                                                                                                                                                         |
| `value.put(input: object)`                                                | `object` | Runs the put operation.                                                                                                                                                                                                                                                                                                                |
| `value.get(input: object)`                                                | `object` | Returns a value.                                                                                                                                                                                                                                                                                                                       |
| `value.remove(input: object)`                                             | `object` | Removes a value or resource.                                                                                                                                                                                                                                                                                                           |
| `value.presign(input: object)`                                            | `object` | Generates a presigned URL. Input keys: `key` (required), `expires` (seconds, default 3600), `method` (HTTP method to sign for, default `GET`; pass `PUT` for direct uploads), `content_length` (optional; signs the Content-Length header so the upload must be exactly that many bytes). Returns `{ok, url}` or `{ok: false, error}`. |

## Examples

```javascript
import "osl/s3"

client = s3.new({
    "endpoint": "https://accountid.r2.cloudflarestorage.com",
    "bucket": "my-bucket",
    "access_key_id": "...",
    "secret_access_key": "...",
    "region": "auto"
})

download = client.presign({"key": "files/report.pdf", "expires": 3600})
upload = client.presign({"key": "files/report.pdf", "expires": 900, "method": "PUT", "content_length": 52428})
```

## Notes

* Standard-library imports accept both `import "osl/s3"` and `import "s3"`.
* Return values such as `array` and `object` are regular OSL values unless a returned object section says otherwise.