@permute/sdk 0.2.0 → 0.4.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
@@ -151,6 +184,29 @@ const client = new PermuteClient({
 grant access. The selected ID is available as `client.workspaceId`. Organization
 APIs such as `client.workspaces.list()` do not send a workspace header.
 
+## Connect Customer Sources
+
+Create a hosted setup link from your server after authorizing the customer's
+workspace. Use `Providers` for provider IDs (for example, `Providers.HUBSPOT`).
+
+```ts
+import { Providers } from '@permute/sdk';
+
+const session = await client.connectorSessions.create({
+  provider: Providers.HUBSPOT,
+  name: 'CRM',
+});
+// Send session.url to the authorized customer to open in a new tab or popup.
+
+// Reconnect an existing source; its provider is inferred.
+const reconnect = await client.connectorSessions.create({
+  connectorId: savedConnectorId,
+});
+```
+
+See the [hosted connector setup guide](https://permute.ai/docs/connector-sessions)
+for completion checks and return URLs.
+
 ## Upload Files
 
 Use the one-call helper when you have file bytes in process. It creates a file
@@ -202,13 +258,13 @@ data. The SDK accepts JavaScript objects, encodes them as chunked NDJSON, and
 uploads the result to a signed S3 target; callers do not need temporary files.
 
 ```ts
-import { CONTEXT, PermuteClient } from '@permute/sdk';
+import { Context, PermuteClient } from '@permute/sdk';
 
 const dataset = await client.datasets.create({
   type: 'custom',
   key: 'quickbooks',
   name: 'QuickBooks',
-  context: [CONTEXT.QuickBooks],
+  context: [Context.QUICKBOOKS],
 });
 
 await dataset.replace({
@@ -219,6 +275,10 @@ await dataset.replace({
 console.log(dataset.sourceId, dataset.version, dataset.data.tables);
 ```
 
+Dataset `context` accepts string identifiers, with `Context` providing named
+constants for known contexts (such as `Context.QUICKBOOKS`). It is not restricted
+to the connector provider list. Use `Providers` when selecting a connector.
+
 `replace()` sends the complete dataset snapshot. Tables omitted from the call
 are removed, while tables with the same name keep their stable identity for
 reports and dashboards. Retrying an identical replacement is a no-op.
@@ -287,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
@@ -327,3 +414,127 @@ 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.
+
+### 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.
+
+## 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.
+
+### 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 { 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,16 +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>;
@@ -102,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>;
@@ -152,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,7 +254,11 @@ export class PermuteClient {
     facts;
     skills;
     organizationSkills;
+    actions;
     databases;
+    apps;
+    connectorSessions;
+    writeSyncs;
     workspaces;
     sources;
     operations;
@@ -321,16 +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),
@@ -341,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),

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+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;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+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;
+    }
+}