@mindstudio-ai/agent 0.1.83 → 0.1.85

package/llms.txt

@@ -1803,3 +1803,40 @@ const { url } = await mindstudio.uploadFile(readFileSync('photo.png'), { extensi
 - `options.type`: string (optional) — MIME type (e.g. `"image/png"`). Determines which CDN subdomain is used.
 
 Output: `{ url: string }` — The permanent public CDN URL.
+
+#### `files` — per-app file storage (private by default)
+Typed per-app file storage: user uploads, generated documents, images, marketing assets. Think of a store as a CDN-backed bucket the app talks to — NOT app-defined state like a `db` table. The API is *shaped* like the `db` namespace (define a store at module scope, then read/write), but its contents aren't modeled by code, and one store is shared across dev and prod (a file uploaded in the dev editor is already live in prod at the same URL). Creates are safe by default because keys default to unique (UUID, or a content-addressed hash); the operations to treat with care are `delete(key)` and overwriting a fixed key. Files are served on the app's own domain: private stores (the default) are signed / session-authorized; public stores are world-readable, CDN-served, and images resize via query params (e.g. `?w=400&h=300&fit=cover`). Prefer this over the deprecated `uploadFile()` for app storage.
+
+```typescript
+import { files } from '@mindstudio-ai/agent';
+
+// Define stores at module scope (access is pinned here).
+export const Uploads = files.defineStore('uploads');                  // private (default)
+export const Assets  = files.defineStore('assets', { access: 'public' });
+
+// Store bytes and get a ready-to-use URL.
+const file = await Uploads.put(buffer, { contentType: 'application/pdf', filename: 'report.pdf' });
+file.url;              // stable on-domain URL for a logged-in user (drop into <img>/<a download>)
+await file.shareUrl(); // absolute signed URL that works with NO session (email/embed); default 24h
+```
+
+Store methods:
+- `put(content, { key?, contentType?, filename?, contentAddressed? })` → `StoredFile`. `content` is `Buffer | Uint8Array | string`. Omit `key` for a random UUID; `contentAddressed: true` derives an immutable `<sha256>.<ext>` key.
+- `get(key)` → `Buffer` · `head(key)` → `StoredFile` · `exists(key)` → `boolean`
+- `list({ prefix?, cursor?, limit? })` → `{ files: StoredFile[]; cursor? }`
+- `delete(key)` → `void`
+- `shareUrl(key, { expiresIn? })` → signed absolute URL (private stores; no session needed)
+
+`StoredFile`: `{ store, key, access, size?, contentType?, updatedAt?, url, shareUrl() }`.
+
+`defineStore(name, options?)` options: `access: 'public' | 'private'` (default private), `maxSize` (bytes; cap for client-direct uploads), `contentTypes` (allowlist for client-direct uploads).
+
+User uploads (client-direct — bytes go straight to storage, never through the app backend): a backend method mints a token, the frontend submits it with `@mindstudio-ai/interface`.
+```typescript
+// backend method
+const token = await Uploads.createUploadToken({ contentType, maxSize: 25 * 1024 * 1024 });
+return token;
+// frontend (@mindstudio-ai/interface)
+import { platform } from '@mindstudio-ai/interface';
+const { url } = await platform.upload(token, file, { onProgress });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/agent",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "description": "TypeScript SDK for MindStudio direct step execution",
   "type": "module",
   "main": "./dist/index.js",