@permute/sdk 0.6.0 → 0.7.0

package/README.md

@@ -224,10 +224,36 @@ console.log(uploaded.sourceId, uploaded.status);
 ```
 
 The SDK infers `sizeBytes` for strings, buffers, typed arrays, ArrayBuffers, and
-Blobs. REST callers provide `sizeBytes`, then send a raw `PUT` to the returned
+Blobs. Omit `data` and provide `sizeBytes` to create the dataset and return its
+upload target without sending bytes. This lets an action approve upload metadata
+while the browser uploads a file directly to storage (outside action limits):
+
+```ts
+const prepared = await client.datasets.create({
+  type: 'file',
+  fileName: file.name,
+  contentType: file.type,
+  sizeBytes: file.size,
+});
+const upload = prepared.data.upload;
+if (!upload) throw new Error('Missing upload target');
+const response = await fetch(upload.url, {
+  method: upload.method,
+  headers: upload.headers,
+  body: file,
+});
+if (!response.ok) throw new Error('Upload failed');
+```
+
+For browser uploads, prepare the target on the server or inside a Business Action,
+then return the dataset ID and target to the browser. The storage PUT uses the
+signed target without an API key; keep API-key SDK clients on the server.
+
+Use every header returned with the target. REST callers provide `sizeBytes`, then send a raw `PUT` to the returned
 `data.upload.url` with every header in `data.upload.headers`. Poll
-`client.datasets.get(result.id)` for processing status; there is no completion
-API call.
+`client.datasets.get(result.id)` for processing status with dataset read permission.
+If the caller has only action invocation access, use a separate status action.
+There is no completion API call.
 
 CSV, TSV, JSON, NDJSON, and Parquet files can be up to 1 GiB (1,073,741,824
 bytes). Other supported file types can be up to 100 MiB (104,857,600 bytes).
@@ -382,7 +408,11 @@ the same transaction after an uncertain response.
 Schema definitions use `client.databases.definition(id)` and
 `client.databases.saveDefinition(id, { definition, expectedDraft })`. Save the
 complete table list, then publish the exact draft through `client.revisions`.
-Published schemas only support adding tables; rows are not part of schema history.
+Publication supports new tables and new nullable columns on existing tables.
+Set `nullable: true` for added columns; existing rows read `NULL` and keep their
+record-version tokens. Preserve existing columns, types, nullability and primary
+keys. Rows are not part of schema history. Publication applies DDL before moving
+the published ref; after a partial failure, retry the same definition to resume.
 
 **Upgrading from 0.3.x:** `createTable` now saves a draft. Publish the database
 before using the new table. Direct `transact` calls require database admin
@@ -425,7 +455,22 @@ const files = await client.apps.uploadFiles(app.id, [
   { path: 'index.html', data: await readFile('dist/index.html') },
   { path: 'assets/main.js', data: await readFile('dist/assets/main.js') },
 ]);
+const sourceFiles = await client.apps.uploadFiles(app.id, [
+  { path: 'package.json', data: await readFile('package.json') },
+  { path: 'bun.lock', data: await readFile('bun.lock') },
+  { path: 'src/main.tsx', data: await readFile('src/main.tsx') },
+  { path: 'index.html', data: await readFile('index.html') },
+  { path: 'vite.config.ts', data: await readFile('vite.config.ts') },
+]);
 const saved = await client.apps.saveSite(app.id, {
+  source: {
+    files: sourceFiles,
+    build: {
+      command: 'bun run build --base=./',
+      outputDirectory: 'dist',
+      runtime: 'bun@1.3.12',
+    },
+  },
   site: { files, spa: true },
   expectedDraft: app.draft,
 });
@@ -436,40 +481,62 @@ if (state.draft?.revisionId !== saved.draft.revisionId || state.draft.sequence !
 await client.revisions.publish(app.id, { expectedVersion: state.version });
 ```
 
-Import `readFile` from `node:fs/promises`. Supply the complete build directory; the filenames above are illustrative. Uploads hash the bytes and use signed, conditional S3 PUTs without forwarding API credentials. Uploading does not create a draft. `saveSite` verifies the uploaded files and saves the complete manifest as a draft revision; `revisions.publish` makes that draft live. The limits are 200 files, 4 MiB per file, and 50 MiB total.
+Import `readFile` from `node:fs/promises`. Supply complete source and compiled manifests, including every file required for a standalone build; the filenames above are illustrative. Uploads hash the bytes and use signed, conditional S3 PUTs without forwarding API credentials. Uploading does not create a draft. `saveSite` verifies the uploaded files and saves source, build instructions and compiled output as one draft revision; `revisions.publish` makes that draft live. Source allows 1,000 files; compiled output allows 200. Each manifest allows 4 MiB per file and 50 MiB total. Optional source-file `executable: true` preserves script permissions. Keep secrets outside source and browser bundles.
 
 Identical contents reuse existing files. Changed contents at the same path are stored separately, preserving earlier versions for rollback. Each save replaces the complete manifest (including unchanged files); omitted paths disappear from the live app when published. Resolve a 409 conflict against the current draft before retrying.
 
+Customize login appearance with `apps.update(app.id, { login, expectedDraft: app.draft })`. The optional `login` object accepts `header`, `subheader`, `title`, `subtitle`, `primaryColor` and `secondaryColor` (six-digit hex colors). For `sidePanelImage`, upload a PNG, JPEG or WebP image up to 2 MiB with `apps.uploadFiles` and pass the returned file descriptor. Publish the saved draft through `revisions.publish` to apply the same appearance to Permute sign-in and shared-password access. Set `login: null` to restore default styling. Images displayed before sign-in are public; normal site files stay gated.
+
+Set an app favicon with `apps.update(app.id, { favicon, expectedDraft: app.draft })`, where `favicon` is the descriptor returned by uploading a PNG up to 256 KiB through `apps.uploadFiles`. Publish to apply it to browser tabs and sign-in screens (independent of custom login styling). The configured icon overrides bundled icons; `favicon: null` removes the override. Only the current published icon is public before sign-in; historical published icons require an app session. Organization defaults are not supported.
+
 Visitors sign in through Permute and need app read permission. HTML receives a revision-specific base URL; use relative URLs for bundled and public assets. Inline scripts, external requests, workers, and server runtimes are not supported. Keep API keys and secrets out of compiled browser files. Restore a historical revision with `client.revisions.restore`, then publish the resulting draft to roll back. See the [complete app guide](https://permute.ai/docs/guides/deploy-app) for creation, directory uploads, updates, and rollback.
 
-### Deploy a build directory (SDK 0.6.0)
+### Deploy source and compiled output (SDK 0.7.0)
 
 The Node/Bun entry `@permute/sdk/deploy` combines validation, upload, draft save,
-and publication for an existing live app. Use SDK 0.6.0 for the grant-based app
-API shown here.
+and publication for an existing live app. Use SDK 0.7.0 for source-backed app saves. Builds still run locally.
 
 ```ts
 import { deployApp } from '@permute/sdk/deploy';
 
-const deployed = await deployApp(client, { appId, directory: './dist' });
+const deployed = await deployApp(client, {
+  appId,
+  directory: './dist',
+  expectedDraft: app.draft,
+  source: {
+    directory: '.',
+    build: {
+      command: 'bun run build --base=./',
+      outputDirectory: 'dist',
+      runtime: 'bun@1.3.12',
+    },
+  },
+});
 console.log(deployed.url, deployed.revisionId, deployed.changed);
 ```
 
 The helper rejects symbolic links, unsupported paths, missing `index.html`, and
-oversized builds before uploading. It requires the current draft to be published;
-after reviewing an existing draft, pass its exact `expectedDraft` to approve
-replacing it. Omitted `actions` preserve current bindings (an empty array clears them). To change action bindings, supply explicit published revisions:
+oversized builds before uploading. Pass the `expectedDraft` token from checkout or a reviewed app read. A stale token stops deployment before uploads; the helper never adopts a newer remote draft as the base of local files. Omitted `actions` preserve current bindings (an empty array clears them). To change action bindings, supply explicit published revisions:
 
 ```ts
 await deployApp(client, {
   appId,
+  expectedDraft: app.draft,
   directory: './dist',
+  source: {
+    directory: '.',
+    build: {
+      command: 'bun run build --base=./',
+      outputDirectory: 'dist',
+      runtime: 'bun@1.3.12',
+    },
+  },
   actions: [{ actionId, revisionId: publishedActionRevisionId }],
 });
 ```
 
 An unchanged build returns `changed: false` without uploading, saving, or publishing
-(files, SPA mode, and any supplied bindings must match). It rechecks refs before
+(source, build instructions, compiled files, SPA mode, and supplied bindings must match). It rechecks refs before
 reporting no change. An approved unpublished draft is still published so settings
 edits are preserved. Changed deployments return `changed: true`.
 
@@ -480,23 +547,100 @@ publication may already have completed. `deployment_conflict` requires review;
 when saving a draft for later review. The helper does not build, provision, or wait
 for hosting, and must not be imported into browser code.
 
+### Shared source checkpoints and checkout
+
+Source and compiled output share one App history. Source checkpoints advance the draft without publishing; publication checks that the saved build matches current source and build instructions. Settings-only edits reuse matching builds. Restore recovers both manifests together; older compiled-only revisions have no downloadable source.
+
+Invited editors can use **Download source** in App details with their Permute user session (no API key required). The ZIP contains project files under `source/` and a separate `app-source.json` with build instructions, the exact revision and the observed draft token. The SDK uses an API key with its own App write grant; a user editing invitation does not grant access to any API key.
+
+```ts
+import { checkoutApp, saveAppSource } from '@permute/sdk/deploy';
+
+const checkout = await checkoutApp(client, { appId, directory: './app-project' });
+// Edit the downloaded files. Retain the token from checkout for your save.
+if (!checkout.expectedDraft) throw new Error('Review the current draft first');
+const saved = await saveAppSource(client, {
+  appId,
+  expectedDraft: checkout.expectedDraft,
+  source: { directory: './app-project', build: checkout.source.build },
+});
+// Run the stored build command, then use deployApp with expectedDraft: saved.draft.
+```
+
+Checkout requires a new folder and verifies every downloaded file against its hash and size. Pass `revisionId` to select historical source; historical checkout returns no draft token unless it is also the current draft. A failed checkout may leave a partial folder; inspect it and choose a new folder before retrying.
+
+Source helpers apply root and nested `.gitignore` rules, including directory patterns and `!` exceptions, using [`ignore` 7.0.5](https://github.com/kaelzhang/node-ignore/tree/7.0.5). Visited `.gitignore` files stay in the source snapshot. Rules apply to all local files, including files tracked by Git; the Git index, local/global excludes and rules outside the selected source root are not consulted. Git installation and commits are unnecessary.
+
+Mandatory exclusions cover dependencies, credential files, common caches, the declared build output directory, and personal agent state (including `CLAUDE.local.md`, `.claude/settings.local.json`, agent worktrees, authentication files and session logs). Ignore exceptions cannot override these exclusions. Keep shared instructions, skills, setup scripts, lockfiles, tests and configuration inside the source root. Environment templates ending in `.example`, `.sample` or `.template` are allowed; remove actual secrets from their contents. Filename exclusions do not scan for secrets embedded in ordinary files.
+
+Internal source symlinks are copied as ordinary files or directories, and checkout restores executable scripts. External, dangling, cyclic and excluded-target links fail before uploads; compiled output rejects symlinks. Unsafe paths, case collisions and oversized manifests also fail. Checkout never executes project hooks or scripts. Build the exact source you intend to save and keep it unchanged while deploying; build pairing records the uploader’s declaration and does not independently verify compilation.
+
+App write/admin permission is required for source files and complete revision reads. App admins can grant editing access through Share; app read permission continues to govern hosted compiled files. Source files never enter hosted-file delivery.
+
 ### Inside a hosted app
 
 Use the browser entry with the app's existing sign-in session (no API key in frontend code):
 
+Use `app.sources.list()`, `app.sources.get(sourceId)`, and `app.query()` for ordinary
+reads, including counts, lists, filters, and aggregates. Create read actions only
+for deliberate delegated contracts, reusable business rules, or live connector
+calls outside the query API. The built-in assistant queries permitted sources
+directly; invoking any bound action requires viewer confirmation.
+
+Source reads require whole-resource read permission for both the app and viewer,
+including databases, datasets, connectors, and operation outputs. Table, row,
+and column grants are unsupported; subResourceId is available only to revoke an
+existing scoped grant. Test source discovery and
+a bounded query as the intended viewer before testing the assistant; an empty
+source list describes that viewer's app access, not the workspace's contents.
+
+Plan app and viewer permissions separately. Use `client.apps.setGrant()` for exact
+approved app source IDs; an administrator uses Permute sharing for viewer app and
+source access. The public SDK has no general user-permission mutation methods.
+Inspect the complete source before approval (a database may contain other apps’
+tables); never widen a rejected table grant automatically. Apps and keys do not
+inherit their creators’ access. The public
+[app guide](https://permute.ai/docs/guides/deploy-app#app-grants) includes the permission matrix.
+
+Use the built-in assistant rather than adding another AI backend or chat overlay.
+When migrating ordinary read actions, update their callers to the source/query API,
+publish without those bindings, revoke their app grants, and delete the actions
+after confirming no remaining callers. Keep approved write actions and revision pins.
+
 ```ts
 import { PermuteAppClient } from '@permute/sdk/app';
 
 const app = new PermuteAppClient();
+const user = await app.me(); // { id, name, email } for the current signed-in viewer
 const result = await app.query({
   sourceIds: ['dbas_example'],
   sql: 'SELECT * FROM app.contacts',
   limit: 100,
 });
+// Optional: only for an explicitly requested operation with a pinned action.
 const request = { requestId: crypto.randomUUID(), input: { name: 'Ada' } };
 const receipt = await app.actions.invoke('actn_example', request);
 ```
 
+`app.me()` returns the current user’s `id`, `name` and `email`, after checking the app session, membership and app access. Requests use the public API on the app origin (including custom domains), with the HttpOnly cookie and a validated `X-Permute-App-Revision` header. Source reads and lists intersect current user permissions and app grants; action invocation retains the served release’s pinned binding. Password demos cannot call these APIs.
+
+```ts
+const sources = await app.sources.list();
+const chat = await app.chats.create({
+  action: 'send_message',
+  clientRequestId: crypto.randomUUID(),
+  message: 'Show the pipeline',
+});
+const state = await app.chats.get(chat.id);
+await app.chats.send(chat.id, {
+  action: 'send_message',
+  clientRequestId: crypto.randomUUID(),
+  message: 'Group it by stage',
+});
+```
+
+`/v1/chats` preserves conversation and supports turns, cancellation and action decisions. `/v1/answer-jobs` remains one-shot analysis. Chat and basic-profile routes require user authentication; API keys cannot own chats. Other API routes retain their declared authentication requirements. Legacy hosted `__me`, `__queries` and `__actions/{actionId}/invoke` URLs forward to these public handlers. Port older apps by updating the SDK, rebuilding and publishing their bundles so these aliases can be removed. Existing users must sign in again when migrating from opaque cookies to app-scoped JWTs.
+
 The client reads the hosted page's revision-pinned base URL. Save
 `actions: [{ actionId, revisionId }]` with its site manifest, then publish the app revision.
 Queries require current app and user read permissions. The query request selects its
@@ -520,13 +664,51 @@ operation only after resolving any earlier uncertain write.
 
 ## Business actions
 
+Action handlers can receive a declared `platform` SDK facade. Add `platform.methods`
+and `platform.permissions` to the definition, then call
+`platform.withStep('upload').datasets.create({ type: 'file', fileName: input.fileName, contentType: input.contentType, sizeBytes: input.sizeBytes })`.
+Without `data`, the call returns dataset metadata and an upload target; the handler
+can return that target for the browser to upload bytes. Providing `data` also
+uploads bytes inside the action and must fit its execution and payload limits.
+The server runs the real SDK using the action's delegated grants (callers need
+only action invocation permission). Saving and publishing require resource admin
+authority. Every SDK call needs a distinct, deterministic step ID, including reads.
+Completed calls replay their saved results; reusing an ID with a different method
+or arguments returns `request_conflict`. Calls with uncertain outcomes return
+`outcome_unknown` and block automatic resend. Earlier SDK effects aren't rolled
+back if the action fails.
+Calls share action time and payload limits; dataset helpers return plain data.
+See the [business-actions guide](https://permute.ai/docs/guides/business-actions)
+for supported methods, limits, and authoring examples.
+
 Use `client.actions.create`, `definition`, and `saveDefinition` to author a typed
-handler with selected database tables or connector accounts. Publish with
+handler with declared database, connector, or SDK capabilities. SDK-only and
+connector-only actions need no managed database. Publish with
 `client.revisions.publish`, then call `client.actions.invoke` with a stable
 `requestId` and input. `list` exposes published contracts; reading definitions
 requires admin permission. See the [business action guide](https://permute.ai/docs/guides/business-actions)
 for the complete create, save, publish, and invoke workflow.
 
+Permute authenticates callers and checks the action’s required invocation
+permission. Hosted app calls also require app access, an app invocation grant,
+and the action revision pinned in the served release. Administrators approve
+delegated resources when authoring and publishing the action.
+
+Execution uses the action’s approved delegated capabilities; callers do not need
+direct access to the underlying sources. A bound connector uses the connected
+account’s access even when the caller has no connector access. Permute enforces
+declared execution capabilities and validates input/output schemas; the handler
+defines the operation exposed to callers.
+
+Handlers receive trusted `caller: { id, type }` (`type` is `user` or `apiKey`).
+An action can use that identity and server-side business data to check or deny a
+request when its rules warrant it (such as an ownership rule or allowed state transition).
+Apply those checks before the affected reads or writes. They supplement the
+platform checks. Permute does not require callers to hold the action’s underlying
+source permissions. Browser-supplied actor IDs or roles are not proof of identity
+or authority. The caller object contains no membership roles or general
+permission lookup API.
+
 ### Expected failures in handlers
 
 Use `reject(code, message, details?)` for a deliberate business rejection:
@@ -540,7 +722,7 @@ exports.handler = ({ input, db, reject }) => {
 ```
 
 Rejection stops the handler and discards staged database writes. It cannot undo
-connector calls already sent. Messages and details are public to callers; never
+connector or SDK effects already sent. Messages and details are public to callers; never
 put credentials or private diagnostic data in them. A rejection message permits
 1–1,000 characters, with up to 20 string detail fields (keys 1–100 characters,
 values up to 500). Invalid rejections and unexpected exceptions return a safe
@@ -626,3 +808,31 @@ step IDs stable in code. The first attempt pins the revision; successful externa
 replay saved responses. Steps with uncertain outcomes block automatic resend and require
 provider-state reconciliation. There is no automatic rollback, reconciliation API, or
 long-running workflow runner. Connector-only actions can use `sources: []`.
+
+## Hosted app visitor access (next release)
+
+App admins can read `client.apps.access(appId)` and update access with
+`client.apps.setAccess(appId, { mode, expectedVersion, password? })`. Use the
+version returned by the read. `mode: 'password'` requires a new password on each
+save; `mode: 'permute'` clears it. These methods are not in SDK 0.6.0.
+
+Access changes take effect immediately and invalidate app sessions (without
+publishing a site revision). Shared passwords gate published frontend files only,
+including older releases. Use mocked data; demo sessions cannot query sources or
+invoke Business Actions. Permute sign-in retains existing permissions and app grants.
+
+### Custom app addresses
+
+An organization admin first connects a namespace in Organization Settings → App domains and completes the displayed DNS validation. App admins can then assign a name without a new build or CloudFront rollout (the generated Permute URL stays available):
+
+```ts
+const current = await client.apps.address(app.id);
+const namespace = current.namespaces[0]; // Ready namespaces in this organization.
+if (!namespace) throw new Error('Connect an organization app domain first.');
+await client.apps.setAddress(app.id, {
+  address: { namespaceId: namespace.id, label: 'crm' },
+  expectedUrl: current.address?.url ?? null,
+});
+```
+
+Set `address: null` with the currently observed URL to remove it. Stale edits and occupied names return 409. Each hostname uses its own app session; permissions and password-demo restrictions apply on every address. Namespace ownership management is restricted to signed-in organization admins, while these app-level methods support API keys with app admin permission.

package/dist/app.d.ts

@@ -1,6 +1,6 @@
-import type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse } from './types.js';
+import type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse, AppUser, ChatSendRequest, ChatDecisionRequest, ChatResponse, SourceList, SourceDetail } from './types.js';
 export { PermuteApiError } from './errors.js';
-export type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse } from './types.js';
+export type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse, AppUser, ChatSendRequest, ChatDecisionRequest, ChatResponse, SourceList, SourceDetail, } from './types.js';
 export interface PermuteAppClientOptions {
     /** Defaults to the hosted page's revision-pinned document.baseURI. */
     baseUrl?: string;
@@ -12,12 +12,26 @@ export interface AppRequestOptions {
 /** Browser client authenticated by the hosted app's HttpOnly session cookie. */
 export declare class PermuteAppClient {
     private readonly baseUrl;
+    private readonly revisionId;
     private readonly fetcher;
     constructor(options?: PermuteAppClientOptions);
     readonly actions: {
         /** Keep requestId and input unchanged when retrying an uncertain result. */
         invoke: (actionId: string, request: ActionRequest, options?: AppRequestOptions) => Promise<ActionReceipt>;
     };
+    readonly sources: {
+        list: (options?: AppRequestOptions) => Promise<SourceList>;
+        get: (sourceId: string, options?: AppRequestOptions) => Promise<SourceDetail>;
+    };
+    readonly chats: {
+        create: (request: ChatSendRequest, options?: AppRequestOptions) => Promise<ChatResponse>;
+        get: (chatId: string, options?: AppRequestOptions) => Promise<ChatResponse>;
+        send: (chatId: string, request: ChatSendRequest, options?: AppRequestOptions) => Promise<ChatResponse>;
+        stop: (chatId: string, options?: AppRequestOptions) => Promise<ChatResponse>;
+        decide: (chatId: string, request: ChatDecisionRequest, options?: AppRequestOptions) => Promise<ChatResponse>;
+    };
     query(request: QueryRequest, options?: AppRequestOptions): Promise<QueryResponse>;
+    /** Basic profile of the current Permute user. Password demos have no user identity. */
+    me(options?: AppRequestOptions): Promise<AppUser>;
     private request;
 }

package/dist/app.js

@@ -3,6 +3,7 @@ export { PermuteApiError } from './errors.js';
 /** Browser client authenticated by the hosted app's HttpOnly session cookie. */
 export class PermuteAppClient {
     baseUrl;
+    revisionId;
     fetcher;
     constructor(options = {}) {
         const base = options.baseUrl ?? (typeof document !== 'undefined' ? document.baseURI : undefined);
@@ -14,23 +15,42 @@ export class PermuteAppClient {
             throw new Error('Use a revision-pinned hosted app URL.');
         if (typeof location !== 'undefined' && url.origin !== location.origin)
             throw new Error('App requests must use the current origin.');
-        this.baseUrl = `${url.origin}${revision[0]}`;
+        this.baseUrl = `${url.origin}/v1/`;
+        this.revisionId = revision[1];
         this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
     }
     actions = {
         /** Keep requestId and input unchanged when retrying an uncertain result. */
-        invoke: (actionId, request, options) => this.request(`__actions/${encodeURIComponent(actionId)}/invoke`, request, options),
+        invoke: (actionId, request, options) => this.request(`actions/${encodeURIComponent(actionId)}/invoke`, request, options),
+    };
+    sources = {
+        list: (options) => this.request('sources', undefined, options),
+        get: (sourceId, options) => this.request(`sources/${encodeURIComponent(sourceId)}`, undefined, options),
+    };
+    chats = {
+        create: (request, options) => this.request('chats', request, options),
+        get: (chatId, options) => this.request(`chats/${encodeURIComponent(chatId)}`, undefined, options),
+        send: (chatId, request, options) => this.request(`chats/${encodeURIComponent(chatId)}/turns`, request, options),
+        stop: (chatId, options) => this.request(`chats/${encodeURIComponent(chatId)}/stop`, {}, options),
+        decide: (chatId, request, options) => this.request(`chats/${encodeURIComponent(chatId)}/decisions`, request, options),
     };
     query(request, options) {
-        return this.request('__queries', request, options);
+        return this.request('queries', request, options);
+    }
+    /** Basic profile of the current Permute user. Password demos have no user identity. */
+    me(options) {
+        return this.request('me', undefined, options);
     }
     async request(path, body, options) {
         const response = await this.fetcher(`${this.baseUrl}${path}`, {
-            method: 'POST',
+            method: body === undefined ? 'GET' : 'POST',
             credentials: 'same-origin',
             mode: 'same-origin',
             redirect: 'error',
-            headers: { 'Content-Type': 'application/json' },
+            headers: {
+                'X-Permute-App-Revision': this.revisionId,
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
             body: JSON.stringify(body),
             signal: options?.signal,
         });

package/dist/bridge.d.ts

@@ -0,0 +1,10 @@
+import { PermuteClient } from './client.js';
+import type { PublicApiOperationId } from './generated/runtime-contract.js';
+/** Executes the SDK itself behind a JSON RPC boundary; it does not implement API operations. */
+export declare class PermuteSdkBridge {
+    private readonly client;
+    constructor(client: PermuteClient);
+    supports(method: string, acceptsOperation?: (operationId: PublicApiOperationId) => boolean): boolean;
+    invoke(method: string, args: unknown[]): Promise<unknown>;
+    private resolve;
+}

package/dist/bridge.js

@@ -0,0 +1,62 @@
+import { PermuteDataset, PermuteFileDataset } from './client.js';
+import { SdkMethodFactory } from './method.js';
+const safeName = (name) => /^[A-Za-z][A-Za-z0-9_]*$/.test(name) && !['constructor', 'prototype', '__proto__'].includes(name);
+function decode(value) {
+    if (!value || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(decode);
+    const item = value;
+    if (Object.keys(item).length === 1 && Array.isArray(item.__permuteSdkBytes)) {
+        if (!item.__permuteSdkBytes.every((byte) => typeof byte === 'number' && Number.isInteger(byte) && byte >= 0 && byte <= 255))
+            throw new Error('Invalid SDK byte data.');
+        return new Uint8Array(item.__permuteSdkBytes);
+    }
+    return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, decode(child)]));
+}
+/** Executes the SDK itself behind a JSON RPC boundary; it does not implement API operations. */
+export class PermuteSdkBridge {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    supports(method, acceptsOperation) {
+        const selected = this.resolve(method);
+        if (!selected)
+            return false;
+        const operations = SdkMethodFactory.operationsFor(selected.fn);
+        return !!operations?.length && (!acceptsOperation || operations.every(acceptsOperation));
+    }
+    async invoke(method, args) {
+        const selected = this.resolve(method);
+        if (!selected)
+            throw new Error(`Unsupported SDK method: ${method}`);
+        const value = await Reflect.apply(selected.fn, selected.owner, args.map(decode));
+        // Resource helpers contain callbacks. Their public data is the portable result of an RPC.
+        const data = value instanceof PermuteDataset || value instanceof PermuteFileDataset ? value.data : value;
+        return JSON.parse(JSON.stringify(data ?? null));
+    }
+    resolve(method) {
+        const names = method.split('.');
+        if (names.some((name) => !safeName(name)) || names.length > 2)
+            return null;
+        const client = this.client;
+        if (names.length === 1) {
+            const name = names[0];
+            const fn = client[name];
+            return typeof fn === 'function' && SdkMethodFactory.operationsFor(fn)
+                ? { owner: this.client, fn: fn }
+                : null;
+        }
+        const namespace = client[names[0]];
+        if (!Object.hasOwn(client, names[0]) ||
+            !namespace ||
+            typeof namespace !== 'object' ||
+            !Object.hasOwn(namespace, names[1]))
+            return null;
+        const fn = namespace[names[1]];
+        return typeof fn === 'function' && SdkMethodFactory.operationsFor(fn)
+            ? { owner: namespace, fn: fn }
+            : null;
+    }
+}