@permute/sdk 0.3.0 → 0.5.0

package/README.md

@@ -26,7 +26,7 @@ The server validates source safety and derives the dashboard data contract from
 the referenced run. Clients cannot supply an authoritative contract.
 
 ```sh
-npm install @permute/sdk
+bun add @permute/sdk
 ```
 
 ## Author data flows with external agents
@@ -101,6 +101,39 @@ and analyzing governed outputs; it does not expose code editing, draft inspectio
 execution, or publication. Hosted connectors also restrict access to selected sources. Flow scheduling and standalone operation
 creation are not part of this surface.
 
+## Publish write syncs
+
+Use `client.writeSyncs.destinations()` to discover writable destination objects
+and fields, then create a paused sync with `writeSyncs.create({ definition })`.
+For operation sources, use `client.sources.get(operationId)` to inspect tables
+and fields, then read `client.operations.get(operationId)` and use its
+`published.revisionId` in the definition. Publish and run the operation before
+configuring its sync. Definition edits use `writeSyncs.update(id, {
+definition, expectedVersion })`, with the version from the latest read.
+
+`writeSyncs.preview(id)` queues a read-only capture, including when the sync is
+enabled. Poll `writeSyncs.getRun(id, runId)` until `previewComplete` or
+`previewError`, then inspect every page with `getRun(id, runId, { page })`
+(pages start at zero) before approving delivery.
+
+```ts
+// After reviewing every page of a completed preview:
+const history = await client.revisions.list(writeSyncId);
+await client.revisions.publish(writeSyncId, {
+  expectedVersion: history.version,
+  runId,
+});
+```
+
+Publishing approves that preview, starts external delivery now, and schedules
+new captures every 24 hours under the same API key that captured the preview.
+New captures include `definitionRevisionId`, which identifies the exact saved
+definition used by that run; older captures may omit it.
+For an enabled sync, `writeSyncs.execute(id, runId)` sends a selected completed
+preview captured by that same key without refreshing its values or changing the
+schedule. Poll `getRun` for delivery results and inspect per-record outcomes.
+Use `writeSyncs.pause(id)` to stop future writes; requests already sent may finish.
+
 ## Configure
 
 ```ts
@@ -314,24 +347,51 @@ const evidence = await client.search({
 console.log(evidence.items);
 ```
 
-Use SQL only when table names are known and exact rows matter. SQL requests must
-include `sourceIds`; call `client.sources.get()` first when table names are not
-known, and use the returned table names exactly. Warehouse-backed sources use
-DuckDB SQL and can be queried together. Live remote database connectors use
-their native dialect—GoogleSQL for BigQuery and PostgreSQL for Supabase—and
-must be queried one at a time without other sources.
+Use SQL when table names are known and exact rows matter. SQL requests need
+`sourceIds`. List a source's tables first, then describe the table you plan to
+query (materialized connector fields come from the stored SQL table). Warehouse
+sources use DuckDB SQL and can be queried together. Live remote sources use
+their native SQL dialect and must be queried one at a time.
 
 ```ts
-const details = await client.sources.get(sourceIds[0]);
+const dataset = sources.items.find((source) => source.type === 'dataset');
+if (!dataset) throw new Error('No dataset is available');
+const tables = await client.sources.listTables(dataset.id);
+const table = await client.sources.describeTable(dataset.id, tables[0].id);
 
 const rows = await client.query({
-  sourceIds: [details.source.id],
-  sql: `SELECT * FROM "${details.tables[0].name}" LIMIT 10`,
+  sourceIds: [dataset.id],
+  sql: `SELECT * FROM "${table.id}" LIMIT 10`,
 });
 
-console.log(rows.rows);
+console.log(table.fields, rows.rows, rows.timings);
 ```
 
+`timings` separates source validation, DuckDB startup, source loading, and SQL
+execution. Compare `totalMs` with the caller's elapsed time to find delay
+outside the query action (including transport and response handling).
+
+## Managed databases
+
+`client.databases` can create a database, define tables, read current records,
+and submit atomic inserts, updates, or deletes. Use `client.query()` for filtered
+SQL reads. Managed records include `__version`; updates and deletes need that
+token, and a stale version returns 409. Reuse a `requestId` only when retrying
+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.
+
+**Upgrading from 0.3.x:** `createTable` now saves a draft. Publish the database
+before using the new table. Direct `transact` calls require database admin
+permission; use a business action for a delegated write.
+
+See the [managed database guide](https://permute.ai/docs/guides/managed-database)
+for a complete example (including provisioning, filtered reads, and conflict
+handling).
+
 ## Error Handling
 
 ```ts
@@ -354,3 +414,216 @@ try {
 ## License
 
 Apache-2.0. Copyright 2026 Permute, Inc.
+
+## Hosted apps
+
+Create an app with `client.apps.create({ name, key, description })`, then poll `client.apps.get(id)` until its deployment is live. Build your frontend locally with relative asset URLs (for Vite, `bun run build --base=./`).
+
+```typescript
+const app = await client.apps.get(appId);
+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 saved = await client.apps.saveSite(app.id, {
+  site: { files, spa: true },
+  expectedDraft: app.draft,
+});
+const state = await client.revisions.list(app.id);
+if (state.draft?.revisionId !== saved.draft.revisionId || state.draft.sequence !== saved.draft.sequence) {
+  throw new Error('The draft changed; review before publishing');
+}
+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.
+
+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.
+
+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.5.0+)
+
+The Node/Bun entry `@permute/sdk/deploy` combines validation, upload, draft save,
+and publication for an existing live app. Available in SDK 0.5.0 and later; the
+individual calls above remain available for separate draft review and publication.
+
+```ts
+import { deployApp } from '@permute/sdk/deploy';
+
+const deployed = await deployApp(client, { appId, directory: './dist' });
+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` and `sourceIds` preserve current bindings (an empty
+array clears them). To change action bindings, supply explicit published revisions:
+
+```ts
+await deployApp(client, {
+  appId,
+  directory: './dist',
+  actions: [{ actionId, revisionId: publishedActionRevisionId }],
+  sourceIds: [databaseId],
+});
+```
+
+An unchanged build returns `changed: false` without uploading, saving, or publishing
+(files, SPA mode, and any 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`.
+
+It stops if refs change and never retries mutations. After a failed or lost response,
+inspect app history before retrying: uploads may exist, a draft may be saved, or
+publication may already have completed. `deployment_conflict` requires review;
+`invalid_build` requires fixing the local build. Use the individual calls above
+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.
+
+### Inside a hosted app
+
+Use the browser entry with the app's existing sign-in session (no API key in frontend code):
+
+```ts
+import { PermuteAppClient } from '@permute/sdk/app';
+
+const app = new PermuteAppClient();
+const result = await app.query({
+  sourceIds: ['dbas_example'],
+  sql: 'SELECT * FROM app.contacts',
+  limit: 100,
+});
+const request = { requestId: crypto.randomUUID(), input: { name: 'Ada' } };
+const receipt = await app.actions.invoke('actn_example', request);
+```
+
+The client reads the hosted page's revision-pinned base URL. Save the app's `sourceIds` and
+`actions: [{ actionId, revisionId }]` with its site manifest, then publish the app revision.
+Queries require a declared source and the signed-in user's current read permission;
+actions use the pinned published action revision and the user's invocation permission.
+Read scope is source-level; client-supplied SQL is not a row-level authorization policy.
+Keep the same request ID and input when retrying an uncertain action response. The client
+does not retry writes automatically. A 401 requires signing in again.
+
+For recovery across reloads, retain `{ baseUrl: document.baseURI, actionId, request }`
+before sending (using storage appropriate to the input's sensitivity). After sign-in
+or a newer app release, create `new PermuteAppClient({ baseUrl: pending.baseUrl })`
+and invoke `pending.actionId` with `pending.request` as the same user. This keeps
+the original app/action revision as well as the request ID and input. Never store
+session cookies or API credentials with pending requests.
+
+A later 401, 403, or 409 does not prove that an earlier attempt failed to commit.
+Keep an uncertain request until its outcome is reconciled; do not silently clear
+it, change its input, or generate a replacement ID. An edited payload is a new
+operation only after resolving any earlier uncertain write.
+
+## Business actions
+
+Use `client.actions.create`, `definition`, and `saveDefinition` to author a typed
+handler with selected database tables or connector accounts. 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.
+
+### Expected failures in handlers
+
+Use `reject(code, message, details?)` for a deliberate business rejection:
+
+```js
+exports.handler = ({ input, db, reject }) => {
+  if (!input.name.trim()) reject('validation_failed', 'Enter a name.', { field: 'name' });
+  db.insert('customers', input);
+  return input;
+};
+```
+
+Rejection stops the handler and discards staged database writes. It cannot undo
+connector calls 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
+`execution_failed` response; exception text stays in server logs.
+
+Both SDK entries expose `PermuteApiError.code`, `.status`, and `.details`.
+Branch on the code (not message text):
+
+| Code                             | HTTP     | Recovery                                                              |
+| -------------------------------- | -------- | --------------------------------------------------------------------- |
+| `validation_failed`              | 400      | Correct input; submit the changed input as a new request.             |
+| `record_conflict`                | 409      | Reload current data and resolve the stale edit.                       |
+| `invalid_transition`             | 409      | Choose an allowed transition from the current state.                  |
+| `permission_denied`, `not_found` | 403, 404 | Check current access or the selected record.                          |
+| `request_conflict`               | 409      | This ID already identifies different input; do not reuse it.          |
+| `request_in_progress`            | 409      | Wait, then retry the identical request.                               |
+| `outcome_unknown`                | 409      | Retain the request ID; inspect external effects before any new write. |
+| `execution_failed`               | 500      | Inspect server logs; retry only with the same request ID and input.   |
+
+Handlers may reject with the first five codes. Transport/authentication failures
+can still use the API's general error codes. A rejection after an external call
+does not establish that nothing happened; reconcile provider state first.
+
+### Connector bindings
+
+An action definition can bind multiple connector accounts by name alongside its database
+schema bindings. Save and publish require admin permission on each selected resource.
+The action runs with those delegated capabilities; callers need its invocation permission.
+
+```ts
+await client.actions.saveDefinition(actionId, {
+  expectedDraft: null, // Use the current draft ref when updating.
+  definition: {
+    source: handlerSource,
+    inputSchema,
+    outputSchema,
+    invokePermission: 'write',
+    sources: databaseBindings,
+    connectors: {
+      salesCrm: 'conn_aaaaaaaaaaaaaaaaaaaaaaaa',
+      partnerCrm: 'conn_bbbbbbbbbbbbbbbbbbbbbbbb',
+    },
+  },
+});
+```
+
+Both names can refer to HubSpot accounts. Handler code uses the bound name; credentials
+stay in the trusted proxy. The following handler creates a HubSpot deal and stages a local
+record (the action must declare `crm_deals` in its writable database binding):
+
+```js
+exports.handler = async ({ input, connectors, db }) => {
+  const deal = await connectors.salesCrm.request({
+    stepId: 'create-deal',
+    method: 'POST',
+    path: '/crm/v3/objects/deals',
+    body: {
+      properties: {
+        dealname: input.name,
+        dealstage: input.hubspotStageId,
+        pipeline: input.hubspotPipelineId,
+      },
+    },
+  });
+  db.insert('crm_deals', { id: input.id, name: input.name, hubspot_id: deal.id });
+  return { id: input.id, hubspotId: deal.id };
+};
+```
+
+`db.insert/update/delete` stages the local mutations until the handler finishes and its
+output validates. Existing `{ mutations, output }` handlers remain supported. External
+requests run when awaited and cannot be rolled back if the local commit later fails.
+
+HTTP providers expose `request({ stepId, method, path, headers?, body?, service? })` using
+provider-relative paths and current authentication. Supabase and BigQuery expose
+`query(sql, params, { stepId })`; S3 exposes `putObject({ stepId, key, body, contentType? })`
+for text objects in the configured bucket. The connected account's grants apply without
+an action-level endpoint allowlist. The SEC integration has no action transport because
+it uses a shared Permute service key.
+
+Reuse the same invocation `requestId` and input after a failed or lost response, and keep
+step IDs stable in code. The first attempt pins the revision; successful external steps
+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: []`.

package/dist/app.d.ts

@@ -0,0 +1,23 @@
+import type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse } from './types.js';
+export { PermuteApiError } from './errors.js';
+export type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse } from './types.js';
+export interface PermuteAppClientOptions {
+    /** Defaults to the hosted page's revision-pinned document.baseURI. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface AppRequestOptions {
+    signal?: AbortSignal;
+}
+/** Browser client authenticated by the hosted app's HttpOnly session cookie. */
+export declare class PermuteAppClient {
+    private readonly baseUrl;
+    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>;
+    };
+    query(request: QueryRequest, options?: AppRequestOptions): Promise<QueryResponse>;
+    private request;
+}

package/dist/app.js

@@ -0,0 +1,65 @@
+import { PermuteApiError } from './errors.js';
+export { PermuteApiError } from './errors.js';
+/** Browser client authenticated by the hosted app's HttpOnly session cookie. */
+export class PermuteAppClient {
+    baseUrl;
+    fetcher;
+    constructor(options = {}) {
+        const base = options.baseUrl ?? (typeof document !== 'undefined' ? document.baseURI : undefined);
+        if (!base)
+            throw new Error('A hosted app revision URL is required.');
+        const url = new URL(base);
+        const revision = /^\/__revisions\/(rvsn_[a-z0-9]+)\//.exec(url.pathname);
+        if (!revision || !['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+            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.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),
+    };
+    query(request, options) {
+        return this.request('__queries', request, options);
+    }
+    async request(path, body, options) {
+        const response = await this.fetcher(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            credentials: 'same-origin',
+            mode: 'same-origin',
+            redirect: 'error',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        const text = await response.text();
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            /* Gateways can return plain-text errors. */
+        }
+        if (!response.ok) {
+            const error = payload?.error;
+            throw new PermuteApiError({
+                status: response.status,
+                code: error?.code ?? (response.status === 401 ? 'unauthenticated' : 'request_failed'),
+                message: (typeof error === 'string' ? error : error?.message) ??
+                    (response.headers.get('content-type')?.startsWith('text/plain') ? text : null) ??
+                    `App request failed (${response.status}).`,
+                details: error?.details,
+                requestId: error?.requestId,
+            });
+        }
+        if (!payload || typeof payload !== 'object' || !Object.hasOwn(payload, 'data'))
+            throw new PermuteApiError({
+                status: response.status,
+                code: 'invalid_response',
+                message: 'Invalid app response.',
+            });
+        return payload.data;
+    }
+}

package/dist/client.d.ts

@@ -1,17 +1,6 @@
-import type { ConnectorSession, ConnectorSessionCreated, ConnectorSessionCreateRequest, Database, DatabaseList, DatabaseCreateRequest, DatabaseTables, DatabaseTableCreateRequest, DatabaseTableCreated, DatabaseRecords, DatabaseRecordsQuery, DatabaseTransactionRequest, DatabaseTransactionReceipt, ResourceVersionState, ResourceRevisionList, ResourceRevision, ResourceVersionRequest, Fact, FactList, FactWriteRequest, SkillList, SkillContent, SkillWriteRequest, KnowledgeWriteResponse, OperationRunGroup, OperationRunQuery, Operation, OperationList, OperationListQuery, OperationSource, OperationSourceUpdateRequest, OperationUpdateRequest, OperationRunRequest, OperationRunStarted, OperationRunList, OperationRunOutput, DataFlow, DataFlowCreateRequest, DataFlowCommandRequest, DataFlowCommandResponse, Workspace, WorkspaceCreateRequest, WorkspaceDeleteResponse, WorkspaceList, WorkspaceUpdateRequest, AnswerRequest, AnswerJobResponse, AnswerResponse, PermuteClientOptions, PermuteRequestOptions, QueryRequest, QueryResponse, SearchRequest, SearchResponse, SourceDetail, SourceList, CustomDatasetCreateRequest, DatasetDeleteResponse, DatasetResponse, FileDatasetCreateRequest, FileDatasetResponse, DatasetRows, CustomDatasetResponse, DashboardSource, DashboardSourceUpdateRequest } from './types.js';
-export declare class PermuteApiError extends Error {
-    readonly status: number;
-    readonly code: string;
-    readonly details?: unknown;
-    readonly requestId?: string;
-    constructor(input: {
-        status: number;
-        code: string;
-        message: string;
-        details?: unknown;
-        requestId?: string;
-    });
-}
+export { PermuteApiError } from './errors.js';
+import type { BusinessAction, BusinessActionList, ActionCreateRequest, ActionDefinition, ActionDefinitionSaveRequest, ActionDefinitionSaved, ActionRequest, ActionReceipt } from './types.js';
+import type { ConnectorSession, ConnectorSessionCreated, ConnectorSessionCreateRequest, Database, AppDraft, AppDraftList, AppCreateRequest, AppUpdateRequest, AppDeleted, AppUploadsRequest, AppUploads, AppSiteSaveRequest, AppUploadFile, DatabaseList, DatabaseCreateRequest, DatabaseDefinition, DatabaseDefinitionSaveRequest, DatabaseDefinitionSaved, DatabaseTables, DatabaseTableCreateRequest, DatabaseTableCreated, DatabaseRecords, DatabaseRecordsQuery, DatabaseTransactionRequest, DatabaseTransactionReceipt, WriteSync, WriteSyncCreateRequest, WriteSyncUpdateRequest, WriteSyncDetail, WriteSyncList, WriteSyncDeleted, WriteSyncDestinations, WriteSyncRun, WriteSyncRunList, WriteSyncRunQuery, WriteSyncExecution, ResourceVersionState, ResourceRevisionList, ResourceRevision, ResourceVersionRequest, ResourcePublishRequest, Fact, FactList, FactWriteRequest, SkillList, SkillContent, SkillWriteRequest, KnowledgeWriteResponse, OperationRunGroup, OperationRunQuery, Operation, OperationList, OperationListQuery, OperationSource, OperationSourceUpdateRequest, OperationUpdateRequest, OperationRunRequest, OperationRunStarted, OperationRunList, OperationRunOutput, DataFlow, DataFlowCreateRequest, DataFlowCommandRequest, DataFlowCommandResponse, Workspace, WorkspaceCreateRequest, WorkspaceDeleteResponse, WorkspaceList, WorkspaceUpdateRequest, AnswerRequest, AnswerJobResponse, AnswerResponse, PermuteClientOptions, PermuteRequestOptions, QueryRequest, QueryResponse, SearchRequest, SearchResponse, SourceDetail, CatalogTable, SourceList, CustomDatasetCreateRequest, DatasetDeleteResponse, DatasetResponse, FileDatasetCreateRequest, FileDatasetResponse, DatasetRows, CustomDatasetResponse, DashboardSource, DashboardSourceUpdateRequest } from './types.js';
 type DatasetWriteInput = {
     tables: Record<string, DatasetRows>;
     mode: 'replace';
@@ -71,7 +60,7 @@ export declare class PermuteClient {
         list(resourceId: string, options?: PermuteRequestOptions): Promise<ResourceRevisionList>;
         get(resourceId: string, revisionId: string, options?: PermuteRequestOptions): Promise<ResourceRevision>;
         restore(resourceId: string, revisionId: string, request: ResourceVersionRequest, options?: PermuteRequestOptions): Promise<ResourceVersionState>;
-        publish(resourceId: string, request: ResourceVersionRequest, options?: PermuteRequestOptions): Promise<ResourceVersionState>;
+        publish(resourceId: string, request: ResourcePublishRequest, options?: PermuteRequestOptions): Promise<ResourceVersionState>;
     };
     readonly facts: {
         list(options?: PermuteRequestOptions): Promise<FactList>;
@@ -82,20 +71,54 @@ export declare class PermuteClient {
     };
     readonly skills: SkillsClient;
     readonly organizationSkills: SkillsClient;
+    readonly actions: {
+        list(options?: PermuteRequestOptions): Promise<BusinessActionList>;
+        create(body: ActionCreateRequest, options?: PermuteRequestOptions): Promise<BusinessAction>;
+        get(actionId: string, options?: PermuteRequestOptions): Promise<BusinessAction>;
+        delete(actionId: string, options?: PermuteRequestOptions): Promise<BusinessAction>;
+        definition(actionId: string, options?: PermuteRequestOptions): Promise<ActionDefinition>;
+        saveDefinition(actionId: string, body: ActionDefinitionSaveRequest, options?: PermuteRequestOptions): Promise<ActionDefinitionSaved>;
+        invoke(actionId: string, body: ActionRequest, options?: PermuteRequestOptions): Promise<ActionReceipt>;
+    };
     readonly databases: {
         list(options?: PermuteRequestOptions): Promise<DatabaseList>;
         create(body: DatabaseCreateRequest, options?: PermuteRequestOptions): Promise<Database>;
         get(databaseId: string, options?: PermuteRequestOptions): Promise<Database>;
         delete(databaseId: string, options?: PermuteRequestOptions): Promise<Database>;
+        definition(databaseId: string, options?: PermuteRequestOptions): Promise<DatabaseDefinition>;
+        saveDefinition(databaseId: string, body: DatabaseDefinitionSaveRequest, options?: PermuteRequestOptions): Promise<DatabaseDefinitionSaved>;
         tables(databaseId: string, options?: PermuteRequestOptions): Promise<DatabaseTables>;
         createTable(databaseId: string, body: DatabaseTableCreateRequest, options?: PermuteRequestOptions): Promise<DatabaseTableCreated>;
         records(databaseId: string, table: string, query?: Partial<DatabaseRecordsQuery>, options?: PermuteRequestOptions): Promise<DatabaseRecords>;
         transact(databaseId: string, body: DatabaseTransactionRequest, options?: PermuteRequestOptions): Promise<DatabaseTransactionReceipt>;
     };
+    readonly apps: {
+        list(options?: PermuteRequestOptions): Promise<AppDraftList>;
+        create(body: AppCreateRequest, options?: PermuteRequestOptions): Promise<AppDraft>;
+        get(applicationId: string, options?: PermuteRequestOptions): Promise<AppDraft>;
+        update(applicationId: string, body: AppUpdateRequest, options?: PermuteRequestOptions): Promise<AppDraft>;
+        delete(applicationId: string, options?: PermuteRequestOptions): Promise<AppDeleted>;
+        prepareUploads(applicationId: string, body: AppUploadsRequest, options?: PermuteRequestOptions): Promise<AppUploads>;
+        uploadFiles(applicationId: string, files: AppUploadFile[], options?: PermuteRequestOptions): Promise<AppUploadsRequest['files']>;
+        saveSite(applicationId: string, body: AppSiteSaveRequest, options?: PermuteRequestOptions): Promise<AppDraft>;
+    };
     readonly connectorSessions: {
         create(request: ConnectorSessionCreateRequest, options?: PermuteRequestOptions): Promise<ConnectorSessionCreated>;
         get(sessionId: string, options?: PermuteRequestOptions): Promise<ConnectorSession>;
     };
+    readonly writeSyncs: {
+        list(options?: PermuteRequestOptions): Promise<WriteSyncList>;
+        create(request: WriteSyncCreateRequest, options?: PermuteRequestOptions): Promise<WriteSync>;
+        get(writeSyncId: string, options?: PermuteRequestOptions): Promise<WriteSyncDetail>;
+        update(writeSyncId: string, request: WriteSyncUpdateRequest, options?: PermuteRequestOptions): Promise<WriteSync>;
+        delete(writeSyncId: string, options?: PermuteRequestOptions): Promise<WriteSyncDeleted>;
+        destinations(options?: PermuteRequestOptions): Promise<WriteSyncDestinations>;
+        preview(writeSyncId: string, options?: PermuteRequestOptions): Promise<WriteSyncRun>;
+        pause(writeSyncId: string, options?: PermuteRequestOptions): Promise<WriteSync>;
+        listRuns(writeSyncId: string, options?: PermuteRequestOptions): Promise<WriteSyncRunList>;
+        getRun(writeSyncId: string, runId: string, query?: WriteSyncRunQuery, options?: PermuteRequestOptions): Promise<WriteSyncRun>;
+        execute(writeSyncId: string, runId: string, options?: PermuteRequestOptions): Promise<WriteSyncExecution>;
+    };
     readonly workspaces: {
         list: (options?: PermuteRequestOptions) => Promise<WorkspaceList>;
         create: (request: WorkspaceCreateRequest, options?: PermuteRequestOptions) => Promise<Workspace>;
@@ -106,6 +129,8 @@ export declare class PermuteClient {
     readonly sources: {
         list: (options?: PermuteRequestOptions) => Promise<SourceList>;
         get: (sourceId: string, options?: PermuteRequestOptions) => Promise<SourceDetail>;
+        listTables: (sourceId: string, options?: PermuteRequestOptions) => Promise<CatalogTable[]>;
+        describeTable: (sourceId: string, tableId: string, options?: PermuteRequestOptions) => Promise<CatalogTable>;
     };
     readonly operations: {
         list: (query?: OperationListQuery, options?: PermuteRequestOptions) => Promise<OperationList>;
@@ -156,4 +181,3 @@ export declare class PermuteClient {
     private validateRequestBody;
     private validateRequestQuery;
 }
-export {};

package/dist/client.js

@@ -1,22 +1,10 @@
+import { PermuteApiError } from './errors.js';
+export { PermuteApiError } from './errors.js';
 import { Ajv } from 'ajv';
 import { createHash } from 'node:crypto';
 import { publicApiRoutes } from './generated/runtime-contract.js';
 const DEFAULT_BASE_URL = 'https://api.permute.ai';
 const DEFAULT_POLL_TIMEOUT_MS = 20 * 60 * 1000;
-export class PermuteApiError extends Error {
-    status;
-    code;
-    details;
-    requestId;
-    constructor(input) {
-        super(input.message);
-        this.name = 'PermuteApiError';
-        this.status = input.status;
-        this.code = input.code;
-        this.details = input.details;
-        this.requestId = input.requestId;
-    }
-}
 function routeFor(operationId) {
     const route = publicApiRoutes[operationId];
     if (!route) {
@@ -266,8 +254,11 @@ export class PermuteClient {
     facts;
     skills;
     organizationSkills;
+    actions;
     databases;
+    apps;
     connectorSessions;
+    writeSyncs;
     workspaces;
     sources;
     operations;
@@ -322,20 +313,88 @@ export class PermuteClient {
         });
         this.skills = skillsClient('skills');
         this.organizationSkills = skillsClient('organizationSkills');
+        this.actions = {
+            list: (options) => this.request('actionsList', {}, options),
+            create: (body, options) => this.request('actionsCreate', { body }, options),
+            get: (actionId, options) => this.request('actionsGet', { pathParams: { actionId } }, options),
+            delete: (actionId, options) => this.request('actionsDelete', { pathParams: { actionId } }, options),
+            definition: (actionId, options) => this.request('actionDefinitionGet', { pathParams: { actionId } }, options),
+            saveDefinition: (actionId, body, options) => this.request('actionDefinitionSave', { pathParams: { actionId }, body }, options),
+            invoke: (actionId, body, options) => this.request('actionsInvoke', { pathParams: { actionId }, body }, options),
+        };
         this.databases = {
             list: (options) => this.request('databasesList', {}, options),
             create: (body, options) => this.request('databasesCreate', { body }, options),
             get: (databaseId, options) => this.request('databasesGet', { pathParams: { databaseId } }, options),
             delete: (databaseId, options) => this.request('databasesDelete', { pathParams: { databaseId } }, options),
+            definition: (databaseId, options) => this.request('databaseDefinitionGet', { pathParams: { databaseId } }, options),
+            saveDefinition: (databaseId, body, options) => this.request('databaseDefinitionSave', { pathParams: { databaseId }, body }, options),
             tables: (databaseId, options) => this.request('databaseTablesList', { pathParams: { databaseId } }, options),
             createTable: (databaseId, body, options) => this.request('databaseTablesCreate', { pathParams: { databaseId }, body }, options),
             records: (databaseId, table, query = {}, options) => this.request('databaseRecordsList', { pathParams: { databaseId, table }, query }, options),
             transact: (databaseId, body, options) => this.request('databaseTransactionsCreate', { pathParams: { databaseId }, body }, options),
         };
+        this.apps = {
+            prepareUploads: (applicationId, body, options) => this.request('appsUploadsCreate', { pathParams: { applicationId }, body }, options),
+            uploadFiles: async (applicationId, files, options) => {
+                const contents = await Promise.all(files.map(async (file) => ({
+                    path: file.path,
+                    bytes: typeof file.data === 'string'
+                        ? Buffer.from(file.data)
+                        : file.data instanceof Blob
+                            ? Buffer.from(await file.data.arrayBuffer())
+                            : Buffer.from(file.data),
+                })));
+                const manifest = contents.map(({ path, bytes }) => ({
+                    path,
+                    sha256: createHash('sha256').update(bytes).digest('hex'),
+                    size: bytes.length,
+                }));
+                const { uploads } = await this.apps.prepareUploads(applicationId, { files: manifest }, options);
+                for (const target of uploads) {
+                    const file = contents.find((item) => item.path === target.path);
+                    if (!file)
+                        throw new Error('Unexpected app upload path');
+                    const uploaded = await this.fetchImpl(target.url, {
+                        method: 'PUT',
+                        headers: target.headers,
+                        body: new Blob([new Uint8Array(file.bytes)]),
+                        signal: options?.signal,
+                    });
+                    // A retry or another identical file can win the conditional PUT. Save verifies the stored checksum.
+                    if (!uploaded.ok && uploaded.status !== 412)
+                        throw new PermuteApiError({
+                            status: uploaded.status,
+                            code: 'upload_failed',
+                            message: `App upload failed for ${target.path}`,
+                        });
+                }
+                return manifest;
+            },
+            saveSite: (applicationId, body, options) => this.request('appsSiteUpdate', { pathParams: { applicationId }, body }, options),
+            list: (options) => this.request('appsList', {}, options),
+            create: (body, options) => this.request('appsCreate', { body }, options),
+            get: (applicationId, options) => this.request('appsGet', { pathParams: { applicationId } }, options),
+            update: (applicationId, body, options) => this.request('appsUpdate', { pathParams: { applicationId }, body }, options),
+            delete: (applicationId, options) => this.request('appsDelete', { pathParams: { applicationId } }, options),
+        };
         this.connectorSessions = {
             create: (body, options) => this.request('connectorSessionsCreate', { body }, options),
             get: (sessionId, options) => this.request('connectorSessionsGet', { pathParams: { sessionId } }, options),
         };
+        this.writeSyncs = {
+            list: (options) => this.request('writeSyncsList', {}, options),
+            create: (body, options) => this.request('writeSyncsCreate', { body }, options),
+            get: (writeSyncId, options) => this.request('writeSyncsGet', { pathParams: { writeSyncId } }, options),
+            update: (writeSyncId, body, options) => this.request('writeSyncsUpdate', { pathParams: { writeSyncId }, body }, options),
+            delete: (writeSyncId, options) => this.request('writeSyncsDelete', { pathParams: { writeSyncId } }, options),
+            destinations: (options) => this.request('writeSyncsDestinations', {}, options),
+            preview: (writeSyncId, options) => this.request('writeSyncsPreview', { pathParams: { writeSyncId } }, options),
+            pause: (writeSyncId, options) => this.request('writeSyncsPause', { pathParams: { writeSyncId } }, options),
+            listRuns: (writeSyncId, options) => this.request('writeSyncsListRuns', { pathParams: { writeSyncId } }, options),
+            getRun: (writeSyncId, runId, query = {}, options) => this.request('writeSyncsGetRun', { pathParams: { writeSyncId, runId }, query }, options),
+            execute: (writeSyncId, runId, options) => this.request('writeSyncsExecute', { pathParams: { writeSyncId, runId } }, options),
+        };
         this.workspaces = {
             list: (requestOptions) => this.request('workspacesList', {}, requestOptions),
             create: (request, requestOptions) => this.request('workspacesCreate', { body: request }, requestOptions),
@@ -346,6 +405,14 @@ export class PermuteClient {
         this.sources = {
             list: (requestOptions) => this.request('sourcesList', {}, requestOptions),
             get: (sourceId, requestOptions) => this.request('sourcesGet', { pathParams: { sourceId } }, requestOptions),
+            listTables: async (sourceId, requestOptions) => (await this.request('sourcesGet', {
+                pathParams: { sourceId },
+                query: { includeFields: 'false' },
+            }, requestOptions)).tables,
+            describeTable: async (sourceId, tableId, requestOptions) => (await this.request('sourcesGet', {
+                pathParams: { sourceId },
+                query: { tableId },
+            }, requestOptions)).tables[0],
         };
         this.operations = {
             list: (query = {}, options) => this.request('operationsList', { query }, options),