@sapiom/tools 0.4.0 → 0.5.0

package/src/content-generation/README.md

@@ -0,0 +1,61 @@
+# contentGeneration
+
+Generate media — images today (video and audio to come) — with an optional
+`storage` param that persists each output to Sapiom file storage, so you get a
+durable `fileId` back inline.
+
+```typescript
+import { createClient } from "@sapiom/tools";
+const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });
+
+const out = await sapiom.contentGeneration.images.create({
+  prompt: "a red bicycle",
+  storage: { visibility: "private" }, // optional — persist outputs to file storage
+});
+
+out.images[0].url; // hosted URL of the generated image
+out.images[0].fileId; // present when `storage` was passed — use with `fileStorage`
+```
+
+Ambient import works too: `import { contentGeneration } from "@sapiom/tools"`.
+
+## The optional `storage` param
+
+Pass `storage` and each generated output is persisted to your tenant's file
+storage as it returns — no extra round-trip. Each item in `images` is then
+annotated with its own `fileId`:
+
+```typescript
+const out = await sapiom.contentGeneration.images.create({
+  prompt: "four color swatches",
+  numImages: 4,
+  storage: { visibility: "public" },
+});
+for (const img of out.images ?? []) {
+  if (img.fileId) {
+    const { downloadUrl } = await sapiom.fileStorage.getDownloadUrl(img.fileId);
+  }
+}
+```
+
+Persisting is best-effort per image: if one fails, that image carries a
+`storageError` string instead of a `fileId` while the others still succeed.
+
+## Input
+
+- `prompt` (required) — the text prompt.
+- `numImages` (optional) — how many images to generate.
+- `storage` (optional) — persist outputs; `{ visibility: "private" | "public" }`.
+- `model` (optional) — defaults to a fast image model; most callers omit it.
+- `params` (optional) — advanced, model-specific parameters (e.g. `image_size`,
+  `seed`, `guidance_scale`).
+
+Each returned image is `{ url, contentType?, width?, height?, fileId?,
+storageError? }`; any additional model-specific fields (e.g. `seed`) are returned
+on the result as-is.
+
+## Gotchas
+
+- **Failed requests throw `ContentGenerationHttpError`** (carries `status` +
+  parsed `body`), exported from `@sapiom/tools`.
+- **`storage` is reserved** — a same-named field in `params` is ignored.

package/src/file-storage/README.md

@@ -1,20 +1,20 @@
 # fileStorage
 
-Tenant-scoped object storage on top of presigned GCS URLs. The same file-storage
-capability your agents call over MCP, callable directly from your code.
+Tenant-scoped object storage with presigned URLs. The same file-storage capability
+your agents call over MCP, callable directly from your code.
 
 ```typescript
 import { createClient } from "@sapiom/tools";
 const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });
 
-// 1. Ask for a presigned upload URL (control plane).
+// 1. Ask for a presigned upload URL.
 const { fileId, uploadUrl, requiredHeaders } = await sapiom.fileStorage.upload({
   contentType: "image/png",
   fileName: "photo.png",
   visibility: "private", // or "public"
 });
 
-// 2. PUT the bytes straight to GCS yourself.
+// 2. PUT the bytes to the upload URL yourself.
 await fetch(uploadUrl, { method: "PUT", headers: requiredHeaders, body: bytes });
 
 // 3. Later: a presigned download URL, list, visibility, delete.
@@ -26,18 +26,18 @@ await sapiom.fileStorage.delete(fileId);
 
 Ambient import works too: `import { fileStorage } from "@sapiom/tools"`.
 
-## Control plane only — you move the bytes
+## You move the bytes
 
-`upload()` and `getDownloadUrl()` return **presigned GCS URLs**; this client never
+`upload()` and `getDownloadUrl()` return **presigned URLs**; this client never
 transfers file bytes. You `PUT` to the upload URL and `GET` from the download URL
 yourself, so you own streaming, progress, and resumable-upload behavior. `upload()`
 returns `requiredHeaders` you **must** include on the `PUT` (notably `Content-Type`).
 
 ## Lifecycle
 
-After you `PUT` the bytes, a gateway sweep verifies the object and flips its
-`status` from `pending_upload` → `uploaded` (usually within seconds) and records
-`actualFileSize`. Until then, `getDownloadUrl()` on a still-pending file is rejected.
+After you `PUT` the bytes, the file's `status` moves from `pending_upload` →
+`uploaded` (usually within seconds) and `actualFileSize` is recorded. Until then,
+`getDownloadUrl()` on a still-pending file is rejected.
 
 ## Visibility
 
@@ -50,12 +50,9 @@ files; another tenant cannot read your private files.
 ## Gotchas
 
 - **Sizes are strings.** `expectedFileSize` / `actualFileSize` on returned metadata
-  are `string | null` — the gateway serializes int64 byte counts as strings to
-  avoid JS `Number` precision loss on large files. (`expectedFileSize` on the
-  `upload()` *input* is a regular `number`.)
+  are `string | null` to avoid JS `Number` precision loss on large files.
+  (`expectedFileSize` on the `upload()` *input* is a regular `number`.)
 - **`delete` is idempotent** — deleting an already-deleted file resolves without
   error.
-- **Non-2xx responses throw `FileStorageHttpError`** (carries `status` + parsed
+- **Failed requests throw `FileStorageHttpError`** (carries `status` + parsed
   `body`), exported from `@sapiom/tools`.
-- **Base URL** defaults to the production gateway; override with the
-  `SAPIOM_FILE_STORAGE_URL` env var (e.g. to target a staging gateway).