@nitida/sdk 0.20.0

package/AGENTS.md

@@ -0,0 +1,48 @@
+# @nitida/sdk — for coding agents
+
+**Read `skills/nitida-sdk/SKILL.md` in this package first.** It is the canonical guide and it
+ships inside the tarball, so it is already on disk in `node_modules/@nitida/sdk/skills/`. It
+carries the things that cost real incidents to learn — the base36 tenant prefix, the width ladder,
+the `original`-preset trap, the R2 CORS boundary — not just the API shape.
+
+**Then read `src/`.** This package publishes its TypeScript sources (`files: ["dist/**", "src/**"]`),
+so the source *is* the reference: every public method carries TSDoc, and the ones worth copying
+carry `@example` blocks. Read the source for the canonical, version-pinned answer rather than
+recalling an API from training data — this SDK moves.
+
+## The five-minute version
+
+```ts
+import { AquienpzClient } from "@nitida/sdk/server";   // uploads: server-only, holds the amk_rt_* key
+import { getTransformUrl, setCdnBase, setTenantId } from "@nitida/asset-client"; // URLs: anywhere
+```
+
+- **Uploading** → `aq.upload(file, { fileName, contentType, presets })`. One call does compress →
+  sha256 → presign → direct-to-R2 PUT → `/assets/process` → wait-until-ready.
+- **Image URLs** → `getTransformUrl({ sha }, { format: "webp", width })`. The width MUST be on
+  `TRANSFORM_WIDTHS` or the edge answers **400**.
+- **Video URLs** → `getAssetUrl({ sha }, "video")` after `setTenantId(id)`. The path segment is
+  **base36** (`tenant 12 → /c/v/…`); a decimal prefix 404s.
+
+## The four things that bite hardest
+
+1. **`presets` decides what exists forever.** Omit it and you get `original` only. Ask for
+   `["thumb"]` and the bytes you PUT are *not* retrievable. A variant not requested at the FIRST
+   ingest cannot be added later once the cleanup job reaps `raw/`.
+2. **The `amk_rt_*` key is server-only.** The browser talks to *your* route; your server talks to
+   aquienpz. A runtime key in a client bundle is a write key to a paid platform.
+3. **The PUT goes browser → R2 directly, so R2 answers the CORS preflight.** An origin missing from
+   the bucket policy cannot be fixed in this SDK, in your app, or in `storefront_origins`. Symptom:
+   `R2 PUT failed: network error` with every earlier step green.
+4. **Video is not image.** `/assets/process` filters video presets to
+   `{poster, video, aiproxy, probe}` — `original` is silently dropped — and a video finalizes
+   ASYNCHRONOUSLY: the call answers `{ assetId, status: "processing" }` and a Cloud Run Job flips it
+   to `ready` 1–2 min later, so `processAndWait` needs a `timeoutMs` of at least `300_000`.
+
+## Related packages
+
+| Package | Job |
+|---|---|
+| `@nitida/asset-client` | URL builders + preset tables. No network, no key. |
+| `@nitida/asset-compressor-web` | Browser image compression (worker → OffscreenCanvas → WebP). |
+| `@aquienpz/asset-uploader-web` | Per-file transport: multipart, resume via IndexedDB, progress. |