@mindstudio-ai/agent 0.1.83 → 0.1.84

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 file storage for the app — the twin of the `db` namespace. Define a store at module scope, then read/write objects. 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 are resizable 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.84",
   "description": "TypeScript SDK for MindStudio direct step execution",
   "type": "module",
   "main": "./dist/index.js",