@nxgt/s3 0.2.0 → 0.3.0

package/docs/guide/writes.md

@@ -0,0 +1,273 @@
+# Writing
+
+Storing an object, saying what it is and how it should be served back, and
+getting a refusal **before** anything goes over the wire.
+
+## The smallest thing that works
+
+```ts
+import { bindBucket, defineBucket } from '@nxgt/s3';
+
+const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+	contentType: ['image/png', 'image/jpeg'],
+	maxSize: 2 * 1024 * 1024,
+});
+
+const store = bindBucket(avatars);
+
+await store.put({ userId: 'u1' }, png, { type: 'image/png' });
+await store.delete({ userId: 'u1' });
+```
+
+Describing the bucket is [Buckets](buckets.md). `put` resolves when the
+object is stored, and gives back nothing: S3 has nothing to say beyond that.
+
+## The signatures
+
+```ts
+import type { S3Client, S3Options } from 'bun';
+
+/** A string, bytes, a Blob, a Bun.file, a stream, a Response… */
+type PutBody = Parameters<S3Client['write']>[1];
+
+type PutOptions = Pick<
+	S3Options,
+	'type' | 'acl' | 'storageClass' | 'contentDisposition' | 'contentEncoding'
+>;
+
+put(params: P, body: PutBody, options?: PutOptions): Promise<void>;
+delete(params: P): Promise<void>;
+```
+
+## What a body may be
+
+Anything Bun's own `write` takes:
+
+```ts
+await store.put({ userId: 'u1' }, 'a,b\n1,2\n', { type: 'text/csv' });
+await store.put({ userId: 'u1' }, new Uint8Array([1, 2, 3]), { type: 'image/png' });
+await store.put({ userId: 'u1' }, Bun.file('ada.png')); // the type comes from the file
+await store.put({ userId: 'u1' }, await fetch(url));    // only without `maxSize`
+```
+
+A `Blob` — `Bun.file` included — carries its own content type, so a write
+that names none is still checked against one. A string is measured in
+**bytes**, not characters.
+
+## What a write may say about the object
+
+Every option here describes **the object being stored**. A write says nothing
+about where it goes or how it gets there: the bucket, the endpoint, the
+region and the credentials belong to the bound bucket.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `type` | `string` | the body's own, for a `Blob` | the content type. It is the one the guard checks **and** the one the service receives — they can never be two different answers |
+| `acl` | `'private' \| 'public-read' \| 'public-read-write' \| 'aws-exec-read' \| 'authenticated-read' \| 'bucket-owner-read' \| 'bucket-owner-full-control' \| 'log-delivery-write'` | the client's, else the service's | who may read the object, where the service implements ACLs |
+| `storageClass` | `'STANDARD' \| 'STANDARD_IA' \| 'ONEZONE_IA' \| 'INTELLIGENT_TIERING' \| 'GLACIER' \| 'GLACIER_IR' \| 'DEEP_ARCHIVE' \| 'REDUCED_REDUNDANCY' \| 'EXPRESS_ONEZONE' \| 'OUTPOSTS' \| 'SNOW'` | the client's, else `STANDARD` | what it costs to keep it; comes back as `x-amz-storage-class` |
+| `contentDisposition` | `string` | none | how a reader should present it; comes back on a `GET` |
+| `contentEncoding` | `string` | none | how the body is encoded; comes back on a `GET` |
+
+```ts
+await store.put({ userId: 'u1' }, png, {
+	type: 'image/png',
+	contentDisposition: 'attachment; filename="ada.png"',
+	contentEncoding: 'identity',
+	storageClass: 'STANDARD_IA',
+	acl: 'public-read',
+});
+```
+
+Measured against a real service: `contentDisposition` and `contentEncoding`
+come back as the headers of the same name on a read, and `storageClass` as
+`x-amz-storage-class`.
+
+These are Bun's own names, picked out of its `S3Options`, so a Bun release
+that changes one is a compile error here rather than a silent drift. Given
+both here and to `bindBucket`, the one on the write wins: it is the last
+thing handed to the client.
+
+### An option's *value* is checked here too
+
+`acl` and `storageClass` are unions, and the values listed above are the only
+ones the service takes. A bag off a request body never met those types, so
+the value is checked at run time as well — before anything is sent, with the
+content type and the size, and as the same `S3Error`:
+
+```ts
+import { S3Error, type PutOptions } from '@nxgt/s3';
+
+const bad = { type: 'text/plain', storageClass: 'CHEAP' } as unknown as PutOptions;
+
+const error = (await store
+	.put({ userId: 'u1' }, 'a,b\n', bad)
+	.catch((reason: unknown) => reason)) as S3Error;
+
+error instanceof S3Error; // true
+error.code;               // 'WRONG_OPTION'
+error.message;            // 'storageClass must be one of STANDARD, DEEP_ARCHIVE, …; got "CHEAP"'
+error.key;                // 'u1.png' — the key, never the body
+// Nothing was stored: `await store.exists({ userId: 'u1' })` is still false.
+```
+
+Bun checks both values as well, and refuses with a plain `TypeError`
+(measured on bun 1.4.2). That left one `put` with two classes of refusal —
+an `S3Error` with a code for the content type and the size, a `TypeError`
+with only a sentence for these two. Checking here means one `put` has one
+class of refusal, with a code to switch on. `contentDisposition` and `contentEncoding` are free strings
+and are never refused, by this package or by Bun.
+
+The same allowlist holds `acl` on a
+[presigned URL](presigned-urls.md#options), so a wrong value is the same
+`WRONG_OPTION` whichever call a consumer reached for.
+
+### A write cannot change where it goes
+
+`PutOptions` carries no `bucket`, `endpoint`, `region` or credential, and the
+run time forwards only the five keys above — a key that is not in that list
+is dropped, never sent.
+
+```ts
+// A bag off a request body never met the types.
+const smuggled = {
+	type: 'text/plain',
+	bucket: 'somewhere-else',
+	accessKeyId: 'someone-else',
+} as PutOptions;
+
+await store.put({ userId: 'u1' }, 'x', smuggled);
+// Stored in `avatars`, with the credentials the bucket was bound with.
+```
+
+Measured before that filter existed, spreading the caller's options straight
+through let a `bucket` key store the object in another bucket — and report
+success.
+
+### A `put` is one PUT
+
+`partSize`, `queueSize` and `retry` are not `PutOptions`: they belong to
+[`bindBucket`](buckets.md), where they are the client's own. Measured on bun
+1.4.2 against a 12 MiB body, a `put` with `partSize` set and one without come
+back with the **same** ETag, and neither carries the `-<parts>` suffix a
+multipart upload leaves. For a body that wants parts, use
+`store.file(params).writer()`.
+
+## The guards
+
+`contentType` and `maxSize` on the definition are checked in `put`, before
+the request goes out. A refused body is never sent.
+
+```ts
+import { S3Error } from '@nxgt/s3';
+
+try {
+	await store.put({ userId: 'u1' }, pdf, { type: 'application/pdf' });
+} catch (error) {
+	if (error instanceof S3Error) {
+		error.code; // 'WRONG_TYPE'
+		error.key;  // 'u1.png' — the key, never the body
+	}
+}
+```
+
+| `S3ErrorCode` | When |
+| --- | --- |
+| `WRONG_TYPE` | the type is not one this bucket accepts — or the write named none and the body carries none, while the bucket names some |
+| `TOO_LARGE` | the body is bigger than `maxSize`. The limit is inclusive: with `maxSize: 1024`, 1024 bytes passes and 1025 does not |
+| `UNMEASURABLE` | `maxSize` is set and the body's size cannot be known before sending |
+| `WRONG_OPTION` | the write's `acl` or `storageClass` is not a value the service accepts — see [above](#an-options-value-is-checked-here-too) |
+
+A content type is compared on its **essence**: parameters and case are
+ignored, and nothing else is. A bucket that accepts `text/csv` accepts
+`text/csv;charset=utf-8` and `TEXT/CSV`, because that is what real bodies
+carry — measured, `Bun.file` labels `.txt` as `text/plain;charset=utf-8` and
+`.csv` as the bare `text/csv`.
+
+```ts
+const reports = defineBucket({
+	bucket: 'reports',
+	key: (id: string) => `${id}.csv`,
+	contentType: 'text/csv',
+});
+const csv = bindBucket(reports);
+
+await csv.put('q1', Bun.file('q1.csv'));  // stored
+await csv.put('q1', Bun.file('note.txt')); // S3Error WRONG_TYPE, nothing sent
+```
+
+`UNMEASURABLE` is the one that surprises: with `maxSize` set, a `Response`, a
+`Request`, a stream or another `S3File` is **refused, not streamed** —
+nothing can check a length it has not read, and an `S3File` reports its size
+as `NaN` until the service has been asked. Read it into memory first, or
+leave `maxSize` out and let the service refuse an oversized body.
+
+```ts
+const answer = await fetch(url);
+const body = new Uint8Array(await answer.arrayBuffer()); // now it has a length
+await store.put({ userId: 'u1' }, body, { type: 'image/png' });
+```
+
+The guards are `put`'s, not the bucket's: `store.file(params).writer()`,
+`store.client` and anyone holding a [presigned PUT](presigned-urls.md) write
+whatever they are given. Set the service's own policy too where it matters.
+
+## Deleting
+
+```ts
+await store.delete({ userId: 'u1' });
+```
+
+S3 does not say whether anything was there, and nor does this. Call `exists`
+first when it matters — see [Reading](reads.md).
+
+## A real one: an upload route
+
+```ts
+import { Hono } from 'hono';
+import { bindBucket, defineBucket, S3Error } from '@nxgt/s3';
+
+const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+	contentType: ['image/png', 'image/jpeg'],
+	maxSize: 2 * 1024 * 1024,
+});
+
+const store = bindBucket(avatars);
+const app = new Hono();
+
+app.put('/users/:id/avatar', async (c) => {
+	const userId = c.req.param('id');
+	const body = await c.req.blob(); // a Blob: it carries its own type
+
+	try {
+		await store.put({ userId }, body, {
+			contentDisposition: `inline; filename="${userId}.png"`,
+		});
+	} catch (error) {
+		if (error instanceof S3Error && error.code === 'WRONG_TYPE') {
+			return c.json({ error: 'Send a PNG or a JPEG' }, 415);
+		}
+		if (error instanceof S3Error && error.code === 'TOO_LARGE') {
+			return c.json({ error: 'That file is too big' }, 413);
+		}
+		throw error;
+	}
+
+	return c.json({ key: store.keyFor({ userId }) }, 201);
+});
+```
+
+Every `S3Error` is thrown before the request goes out, so a 413 costs no
+bandwidth. Bun names **its own** S3 failures `S3Error` too, with S3's codes:
+discriminate with `instanceof S3Error` on this package's class, never with
+`error.name`.
+
+## Next
+
+- [Reading](reads.md) — reading back what was written.
+- [Presigned URLs](presigned-urls.md) — letting a browser upload directly,
+  and what that does *not* constrain.
+- [Troubleshooting](../troubleshooting.md) — each error with its fix.

package/docs/roadmap.md

@@ -0,0 +1,64 @@
+# Roadmap
+
+Where `@nxgt/s3` is going. A direction, not a commitment: the version an item
+shipped in is the only number on this page.
+
+## Now
+
+_Nothing in progress._
+
+## Next
+
+_Nothing queued._
+
+## Later
+
+- **Copy and move** — once Bun's own `S3Client` has them. Until then
+  `store.client` is where they live.
+
+## Not planned
+
+- **Running on Node** — the client is Bun's own `S3Client`, which is why this
+  package installs no AWS SDK at all. There is nothing to swap for Node, and a
+  build for it is not coming: it needs Bun 1.4 or later.
+- **Multipart upload** — a body goes out in one `put`. For anything bigger,
+  `store.file(params)` hands back Bun's own file handle and its `writer()`.
+- **Bucket administration** — creating, deleting or configuring a bucket is
+  not this package's, and Bun's client has no `createBucket` either.
+- **Retries or a cache of its own** — Bun's client already retries (three
+  attempts by default, and `retry` is passed through on `bindBucket`), and a
+  failed request comes back with S3's own error, as `S3Error`.
+- **Upload tuning on a `put`** — a `put` is a single PUT: measured against a
+  12 MiB body, `partSize` changes nothing, right down to the ETag carrying no
+  `-<parts>` suffix. `PutOptions` describes the object, not the transfer.
+- **An option that says where a write goes** — `bucket`, `endpoint`, `region`
+  and the credentials belong to the bound bucket, and are refused by the types
+  and again at run time. Measured: passing them through let a bag store the
+  object in a different bucket and report success, and redirected a signed URL
+  the same way.
+
+## Shipped
+
+- **An option's own value is refused before anything is sent or signed** —
+  `code: 'WRONG_OPTION'` for an `acl` or a `storageClass` a write names, for
+  an `acl` on a presigned URL, and for an `expiresIn` outside the seven days
+  S3 itself allows. Every refusal of a write or a signed URL is one class with
+  a code to switch on, rather than an `S3Error` for the content type and the
+  size and the client's own `TypeError` for the rest — 0.3.0.
+- **Documentation that travels with the package** — a guide page for the
+  bucket definition, writes, reads and presigned URLs, a troubleshooting page
+  whose headings are the exact error text, and this roadmap, installed in
+  `docs/` rather than left on GitHub — 0.2.1.
+- **What a write may say about the object** — `contentDisposition`,
+  `contentEncoding`, `acl` and `storageClass` on `put`, with Bun's own names;
+  an option naming another bucket, endpoint, region or credential is refused,
+  on `put` and on both `presign` calls — 0.2.0.
+- **First release** — `defineBucket` naming the bucket, the key-building
+  function, the content types it accepts and the biggest body it takes, and
+  `bindBucket` giving `put`, `bytes`, `text`, `exists`, `stat`, `delete`, a
+  cursor `list` and `presignGet` / `presignPut`; the content type and the size
+  are checked before the request goes out, and its one error is `S3Error` —
+  0.1.0.
+
+Everything released is in [`CHANGELOG.md`](https://github.com/softistx/nxgt-data/blob/develop/packages/s3/CHANGELOG.md) — it is not in
+the published package, only in the repository.

package/docs/troubleshooting.md

@@ -0,0 +1,328 @@
+# Troubleshooting
+
+This package throws one error of its own, `S3Error`, with a `code` of
+`WRONG_TYPE`, `TOO_LARGE`, `UNMEASURABLE` or `WRONG_OPTION`, and the object
+`key` it was about — never the body. Every one of them is raised **before**
+anything is sent, so a refused write stored nothing. The service's own
+failures come back as Bun raises them; the entries below say which is which.
+A wrong `acl` is this package's own refusal on a `put` **and** on a
+`presign`, so one class and one code cover both. Bun names its own *service*
+failures `S3Error` as well, so it is `instanceof S3Error` against the class
+this package exports that tells those apart — never `error.name`. (Bun's
+refusal of a wrong argument is a different thing again: a plain `TypeError`,
+named `"TypeError"`.) The Bun messages were measured on Bun 1.4.2.
+
+- **Install and import**
+  - [`Cannot find package 'bun'`](#cannot-find-package-bun)
+  - [`Cannot find module 'bun' or its corresponding type declarations.`](#cannot-find-module-bun-or-its-corresponding-type-declarations)
+- **Configuration**
+  - [`defineBucket: a bucket definition needs a bucket`](#definebucket-a-bucket-definition-needs-a-bucket)
+  - [`defineBucket: "avatars" has a maxSize of 0; it is a number of bytes, and must be above zero`](#definebucket-avatars-has-a-maxsize-of-0-it-is-a-number-of-bytes-and-must-be-above-zero)
+  - [`defineBucket: "avatars" accepts an empty list of content types, so nothing could ever be written. …`](#definebucket-avatars-accepts-an-empty-list-of-content-types-so-nothing-could-ever-be-written-)
+- **Writes refused before they are sent**
+  - [`"avatars" accepts image/png, image/jpeg, not application/pdf`](#avatars-accepts-imagepng-imagejpeg-not-applicationpdf)
+  - [``"avatars" accepts image/png, image/jpeg, and this write names no content type. Pass `type` ``](#avatars-accepts-imagepng-imagejpeg-and-this-write-names-no-content-type-pass-type-)
+  - [`"avatars" accepts 2097152 bytes at most, and this body is 5242880`](#avatars-accepts-2097152-bytes-at-most-and-this-body-is-5242880)
+  - [`"avatars" has a maxSize, and this body's size cannot be known before sending it. …`](#avatars-has-a-maxsize-and-this-bodys-size-cannot-be-known-before-sending-it-)
+  - [`storageClass must be one of STANDARD, DEEP_ARCHIVE, EXPRESS_ONEZONE, …; got "CHEAP"`](#storageclass-must-be-one-of-standard-deep_archive-express_onezone--got-cheap)
+  - [`acl must be one of private, public-read, public-read-write, …; got "everyone"`](#acl-must-be-one-of-private-public-read-public-read-write--got-everyone)
+  - [`expiresIn is seconds, and must be above 0 and at most 604800 …`](#expiresin-is-seconds-and-must-be-above-0-and-at-most-604800-seven-days-which-is-s3s-own-limit-got-1000000000000)
+- **The service**
+  - [`Missing S3 credentials. 'accessKeyId', 'secretAccessKey', 'bucket', and 'endpoint' are required`](#missing-s3-credentials-accesskeyid-secretaccesskey-bucket-and-endpoint-are-required)
+  - [`The AWS Access Key Id you provided does not exist in our records.`](#the-aws-access-key-id-you-provided-does-not-exist-in-our-records)
+  - [A presigned upload stored a body the bucket would have refused](#a-presigned-upload-stored-a-body-the-bucket-would-have-refused)
+  - [A listing came back short with a cursor still set](#a-listing-came-back-short-with-a-cursor-still-set)
+
+## Install and import
+
+### `Cannot find package 'bun'`
+
+**When:** importing `@nxgt/s3` under Node — the full line names the file it
+was imported from.
+**Why:** the client is Bun's own `S3Client`, which is why there is no AWS SDK
+to install and why this package does not run on Node. Measured on Node 22.
+**Fix:**
+
+```sh
+bun run ./src/index.ts   # Bun 1.4 or later
+```
+
+### `Cannot find module 'bun' or its corresponding type declarations.`
+
+**When:** typechecking, on the first file that imports `@nxgt/s3`.
+**Why:** the shipped declarations import `S3Client`, `S3File` and `S3Options`
+from `bun`, so your project needs Bun's types. They are not a dependency of
+this package.
+**Fix:**
+
+```sh
+bun add -d @types/bun
+```
+
+## Configuration
+
+### `defineBucket: a bucket definition needs a bucket`
+
+**When:** at `defineBucket`, with an empty `bucket`.
+**Why:** the bucket name is what every key is written under; an empty one
+cannot be meant.
+**Fix:**
+
+```ts
+export const avatars = defineBucket({
+	bucket: 'avatars',
+	key: (p: { userId: string }) => `${p.userId}.png`,
+});
+```
+
+### `defineBucket: "avatars" has a maxSize of 0; it is a number of bytes, and must be above zero`
+
+**When:** at `defineBucket`.
+**Why:** `maxSize` is a number of **bytes**, and it is inclusive: 1024 passes
+and 1025 does not. A string body is measured in bytes, not in characters.
+**Fix:**
+
+```ts
+defineBucket({ bucket: 'avatars', key, maxSize: 2 * 1024 * 1024 });
+```
+
+### `defineBucket: "avatars" accepts an empty list of content types, so nothing could ever be written. …`
+
+**When:** at `defineBucket`, with `contentType: []`.
+**Why:** an empty list refuses every write. The message ends with the way out,
+``Leave `contentType` out to accept anything``: leaving the option out is what
+accepts anything, and `[]` is never what was meant.
+**Fix:**
+
+```ts
+defineBucket({ bucket: 'avatars', key, contentType: ['image/png', 'image/jpeg'] });
+```
+
+## Writes refused before they are sent
+
+### `"avatars" accepts image/png, image/jpeg, not application/pdf`
+
+**When:** `put`, with a `type` the definition does not list. A presigned URL
+is never checked against it — `PresignOptions` has no `type`, and a signed
+PUT constrains the key and the deadline and nothing else.
+**Why:** an `S3Error` with `code: 'WRONG_TYPE'`. Nothing was sent. The type
+is compared on its **essence**: `text/csv` accepts `text/csv;charset=utf-8`
+and `TEXT/CSV`, because that is what real bodies carry — parameters and case
+are ignored, nothing else is.
+**Fix:**
+
+```ts
+import { S3Error } from '@nxgt/s3';
+
+try {
+	await avatars.put({ userId }, body, { type: file.type });
+} catch (error) {
+	if (error instanceof S3Error && error.code === 'WRONG_TYPE') return badRequest();
+	throw error;
+}
+```
+
+### ``"avatars" accepts image/png, image/jpeg, and this write names no content type. Pass `type` ``
+
+**When:** `put` on a bucket with `contentType`, for a body that carries no
+type of its own — a string, a typed array, a stream.
+**Why:** the guard cannot accept what it cannot read, so an unnamed type is
+refused rather than guessed. `code: 'WRONG_TYPE'`.
+**Fix:**
+
+```ts
+await avatars.put({ userId }, bytes, { type: 'image/png' });
+```
+
+`Bun.file(path)` carries its own type, and does not need the option.
+
+### `"avatars" accepts 2097152 bytes at most, and this body is 5242880`
+
+**When:** `put`, for a body whose size is known and above `maxSize`.
+**Why:** an `S3Error` with `code: 'TOO_LARGE'`, raised before the request goes
+out.
+**Fix:**
+
+```ts
+if (error instanceof S3Error && error.code === 'TOO_LARGE') return payloadTooLarge();
+```
+
+### `"avatars" has a maxSize, and this body's size cannot be known before sending it. …`
+
+**When:** `put` with `maxSize` set, for a `Response`, a `Request`, a stream or
+another `S3File`.
+**Why:** nothing can check a length it has not read — an `S3File` reports its
+size as `NaN` until the service has been asked — so the write is refused
+rather than streamed unchecked. `code: 'UNMEASURABLE'`. The message ends with
+the two ways out, ``Read it into memory first, or drop `maxSize` and let the
+service refuse it``.
+**Fix:**
+
+```ts
+await avatars.put({ userId }, await response.bytes()); // read it in first
+```
+
+Or drop `maxSize` from the definition and let the service refuse an oversized
+body.
+
+### `storageClass must be one of STANDARD, DEEP_ARCHIVE, EXPRESS_ONEZONE, …; got "CHEAP"`
+
+The whole line names every class the service takes, then the one it was
+given:
+
+```text
+storageClass must be one of STANDARD, DEEP_ARCHIVE, EXPRESS_ONEZONE, GLACIER,
+GLACIER_IR, INTELLIGENT_TIERING, ONEZONE_IA, OUTPOSTS, REDUCED_REDUNDANCY,
+SNOW, STANDARD_IA; got "CHEAP"
+```
+
+**When:** `put` with a `storageClass` that is not one of those — usually a
+value read off a request body or an environment variable, where the types
+were not there to refuse it.
+**Why:** an `S3Error` with `code: 'WRONG_OPTION'`, raised before the request
+goes out, like the content type and the size. Since 0.3.0 this package
+checks the two guarded options itself rather than letting the client refuse
+them, so one `catch` covers every refusal of a `put`.
+**Fix:** narrow the value against the option's own type before it reaches the
+call:
+
+```ts
+import { S3Error, type PutOptions } from '@nxgt/s3';
+
+// the classes this application allows, proved against the option's type
+const CLASSES = ['STANDARD', 'STANDARD_IA'] as const satisfies readonly NonNullable<
+	PutOptions['storageClass']
+>[];
+
+function storageClassOf(value: string | undefined): PutOptions['storageClass'] {
+	return CLASSES.find((known) => known === value); // undefined: the bucket's default
+}
+
+try {
+	await avatars.put({ userId }, bytes, { storageClass: storageClassOf(input) });
+} catch (error) {
+	if (error instanceof S3Error && error.code === 'WRONG_OPTION') return badRequest();
+	throw error;
+}
+```
+
+### `acl must be one of private, public-read, public-read-write, …; got "everyone"`
+
+```text
+acl must be one of private, public-read, public-read-write, aws-exec-read,
+authenticated-read, bucket-owner-read, bucket-owner-full-control,
+log-delivery-write; got "everyone"
+```
+
+**When:** `put`, `presignGet` or `presignPut` with an `acl` that is not one
+of those. Both paths go through the same allowlist since 0.3.0; before it,
+`presign` handed the value to the client, which refused it with a plain
+`TypeError` that quoted **every accepted value** (`must be one of "private",
+"public-read", …`). This one quotes only the value it was given, so a message
+with the allowed values in quotes means the package is older than 0.3.0.
+**Why:** the same `code: 'WRONG_OPTION'`, before anything is sent or signed.
+The two guarded options are `acl` and `storageClass`; `contentDisposition`
+and `contentEncoding` are plain strings to the service and accept anything.
+`presign` takes no `storageClass` — nothing is stored by signing a URL.
+**Fix:**
+
+```ts
+await avatars.put({ userId }, bytes, { acl: 'public-read' });
+const url = avatars.presignPut({ userId }, { acl: 'private', expiresIn: 300 });
+```
+
+### `expiresIn is seconds, and must be above 0 and at most 604800 (seven days, which is S3's own limit); got 1000000000000`
+
+**When:** `presignGet` or `presignPut` with an `expiresIn` that is not a
+finite number of seconds inside S3's range.
+**Why:** an `S3Error` with `code: 'WRONG_OPTION'`, raised before anything is
+signed. Measured on bun 1.4.2, the client refuses `0` and below with a
+`TypeError` of its own and **signs** `1e12` happily — a URL the service then
+rejects when somebody uses it, long after this package reported success.
+**Fix:** pass seconds, and no more than a week:
+
+```ts
+const url = avatars.presignPut({ userId }, { expiresIn: 300 }); // five minutes
+```
+
+Sign for the time the page actually needs: a day is a long life for a URL
+anyone can forward.
+
+## The service
+
+### `Missing S3 credentials. 'accessKeyId', 'secretAccessKey', 'bucket', and 'endpoint' are required`
+
+**When:** the first call, when neither `bindBucket`'s options nor the
+environment gave the client credentials. Bun's error, `code:
+'ERR_S3_MISSING_CREDENTIALS'`.
+**Why:** `bindBucket` creates the `S3Client` for you and passes your options
+through; with none, Bun falls back to the environment, and to AWS's endpoint.
+**Fix:**
+
+```ts
+export const avatars = bindBucket(avatarsDefinition, {
+	endpoint: process.env.S3_ENDPOINT,
+	accessKeyId: process.env.S3_KEY,
+	secretAccessKey: process.env.S3_SECRET,
+	virtualHostedStyle: false, // for a service that is not AWS
+});
+```
+
+### `The AWS Access Key Id you provided does not exist in our records.`
+
+**When:** the first call, with credentials the service refuses — or with no
+`endpoint`, which sends the request to AWS whatever your service is.
+**Why:** it is the **service's** answer, raised by Bun as an error whose
+`name` is `S3Error` and whose `code` is the S3 code (`InvalidAccessKeyId`,
+`SignatureDoesNotMatch`, `NoSuchBucket`, `AccessDenied`). It is **not** this
+package's `S3Error` class: `instanceof S3Error` is false for it.
+**Fix:**
+
+```ts
+try {
+	await avatars.put({ userId }, bytes);
+} catch (error) {
+	if (error instanceof S3Error) return badRequest(error.code); // ours: the guards
+	throw error; // the service's, or Bun's: log the code it carries
+}
+```
+
+`bytes`, `text` and `stat` are the exception: they turn S3's own `NoSuchKey`
+into `undefined`, so `undefined` means "no such object" and nothing else.
+Every other failure comes back as the error it is.
+
+### A presigned upload stored a body the bucket would have refused
+
+**When:** after handing out a `presignPut` URL. No error anywhere.
+**Why:** a presigned PUT constrains the key and the deadline, and nothing
+else. Measured on Bun 1.4: `X-Amz-SignedHeaders` stays `host`, so the
+uploader's `Content-Type` is never signed and the size is never checked —
+which is why `presignPut` takes no `type` at all. The guards are `put`'s;
+`file(params).writer()` and `client` are Bun's own and write whatever they
+are given.
+**Fix:**
+
+```ts
+const url = avatars.presignPut({ userId }, { expiresIn: 300 });
+// after the upload, check what actually landed
+const stat = await avatars.stat({ userId });
+if (!stat || stat.size > maxSize) await avatars.delete({ userId });
+```
+
+Set the service's own bucket policy too where it matters.
+
+### A listing came back short with a cursor still set
+
+**When:** `list`, on an eventually consistent service.
+**Why:** `limit` is a maximum, not a promise.
+**Fix:**
+
+```ts
+let cursor: string | null = null;
+do {
+	const page = await avatars.list({ prefix, limit: 100, cursor });
+	cursor = page.nextCursor;
+} while (cursor !== null);
+```
+
+Page until `nextCursor` is `null`, never until a page is short.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/s3",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "S3 on Bun's own client: buckets described once, keys built by a typed function, uploads refused before they are sent, and presigned URLs from the same definition",
 	"license": "MIT",
 	"type": "module",
@@ -8,6 +8,7 @@
 	"types": "./dist/index.d.ts",
 	"files": [
 		"dist",
+		"docs",
 		"README.md",
 		"package.json",
 		"LICENSE"