@permute/sdk 0.1.1 → 0.2.0

package/README.md

@@ -4,10 +4,103 @@ TypeScript client for the Permute public API.
 
 The SDK supports Node.js 20 and newer and includes TypeScript declarations.
 
+See the [changelog](https://permute.ai/docs/changelog) for release notes and upgrade guidance.
+
+## Dashboard source authoring
+
+API-key clients with dashboard write access can read and replace the complete
+TSX source for an existing dashboard. Pass the returned dashboard revision and
+data run back on the write so Permute can reject stale edits:
+
+```ts
+const dashboard = await client.dashboards.getSource('oper_...');
+
+await client.dashboards.updateSource(dashboard.dashboardId, {
+  source: updatedSource,
+  expectedRevision: dashboard.revision,
+  expectedDataRunId: dashboard.dataRunId,
+});
+```
+
+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
 ```
 
+## Author data flows with external agents
+
+For a runnable example from sample input through publication, see
+[Build and publish a data flow](https://permute.ai/docs/guides/data-flow).
+
+Use `operations.list({ kind: 'dataFlow' })` to discover flows, `dataFlows.get(id)`
+to read their edges and operation IDs, and `operations.list({ dataFlowId })` to
+inspect the member operations. Drafts are included (they do not need published output).
+Fetch each operation’s code with `operations.getSource(id)` as needed.
+
+```typescript
+const flow = await client.dataFlows.create({
+  name: 'Revenue',
+  description: 'Revenue by customer',
+  dataSourceIds: ['data_...'],
+});
+
+await client.dataFlows.command(flow.operation.id, {
+  command: {
+    type: 'addTransform',
+    expectedRevision: flow.revision,
+    input: {
+      name: 'Revenue by customer',
+      instruction: 'Sum revenue by customer using the agreed revenue definition.',
+      inputIds: ['data_...'],
+    },
+  },
+});
+const updatedFlow = await client.dataFlows.get(flow.operation.id);
+const operationId = updatedFlow.operationIds[0];
+const current = await client.operations.getSource(operationId);
+await client.operations.updateSource(operationId, {
+  source: handlerSource,
+  expectedRevision: current.revision,
+  expectedDataFlowRevision: current.dataFlowRevision,
+  expectedUpdatedAt: current.updatedAt,
+});
+const started = await client.operations.run(flow.operation.id, { version: 'draft' });
+
+// Poll until the selected workflow's run completes or fails.
+const runs = await client.operations.listRuns(operationId);
+const completed = runs.items.find((run) => run.workflowId === started.workflowId && run.status === 'completed');
+if (completed) {
+  const preview = await client.operations.getRunOutput(operationId, completed.id);
+  console.log(preview.schemas, preview.tables); // At most 1,000 rows per table.
+}
+```
+
+`handlerSource` is JavaScript using `module.exports = { handler }`. The async
+handler receives `event.query(sql)` for local tables, `event.remoteQuery(connectorId, sql)`
+for live SQL connectors, and `event.currentDate` for relative dates. Imports,
+`require()`, and external package calls are unavailable. Inspect source tables
+before writing SQL. Return arrays of flat row objects or an object of named tables;
+Data Flow operations produce one table. Parent outputs retain their table names;
+inspect a completed parent run with `getRunOutput` before writing dependent SQL.
+
+Source updates replace the complete handler and save a draft without starting
+Permute’s coding agent, running code, or publishing. Partial source patches are
+not supported. Read with `getSource` before editing and pass back its `revision`,
+`dataFlowRevision`, and `updatedAt` (as shown above). On a 409 conflict, fetch again
+and reconcile your edits before retrying; do not attach fresh tokens to an old
+replacement without checking the changes. Graph commands use `get`’s numeric flow revision. They support
+`updateFlow`, `addTransform`, `updateNode`, `deleteNode`, `connectNodes`,
+`disconnectNodes`, `publish`, and `deleteFlow`. Fetch the flow after every command.
+Publishing requires a successful run of the current flow version. Deleting a flow
+requires admin access; its owned operations are deleted with it.
+
+Data Flow and operation authoring are REST/SDK only. MCP serves end users reading
+and analyzing governed outputs; it does not expose code editing, draft inspection,
+execution, or publication. Hosted connectors also restrict access to selected sources. Flow scheduling and standalone operation
+creation are not part of this surface.
+
 ## Configure
 
 ```ts
@@ -80,6 +173,26 @@ Blobs. REST callers provide `sizeBytes`, then send a raw `PUT` to the returned
 `client.datasets.get(result.id)` for processing status; 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).
+Permute selects the limit from the submitted `contentType` and rejects an
+oversized file before issuing its signed upload target.
+
+Request a signed URL for the original uploaded file, or delete one file or custom
+dataset when the API key has dataset admin access:
+
+```ts
+const downloadUrl = await client.datasets.download(uploaded.id);
+const response = await fetch(downloadUrl);
+const bytes = await response.arrayBuffer();
+console.log(response.headers.get('content-type'), bytes.byteLength);
+
+await client.datasets.delete(uploaded.id);
+```
+
+For large files, consume `response.body` as a stream instead of buffering the full
+response. Signed download URLs expire after 15 minutes.
+
 ## Manage Custom Datasets
 
 Create a custom dataset by a stable workspace key when one logical source
@@ -176,7 +289,10 @@ 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.
+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.
 
 ```ts
 const details = await client.sources.get(sourceIds[0]);
@@ -201,6 +317,7 @@ try {
   });
 } catch (error) {
   if (error instanceof PermuteApiError) {
+    // Invalid SQL returns status 400 with an actionable message when available.
     console.error(error.status, error.code, error.message, error.requestId);
   }
   throw error;

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Workspace, WorkspaceCreateRequest, WorkspaceDeleteResponse, WorkspaceList, WorkspaceUpdateRequest, AnswerRequest, AnswerJobResponse, AnswerResponse, PermuteClientOptions, PermuteRequestOptions, QueryRequest, QueryResponse, SearchRequest, SearchResponse, SourceDetail, SourceList, CustomDatasetCreateRequest, DatasetResponse, FileDatasetCreateRequest, FileDatasetResponse, DatasetRows, CustomDatasetResponse } from './types.js';
+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;
@@ -60,7 +60,38 @@ export declare class PermuteFileDataset {
     get status(): FileDatasetResponse['status'];
     refresh(options?: PermuteRequestOptions): Promise<this>;
 }
+export interface SkillsClient {
+    list(options?: PermuteRequestOptions): Promise<SkillList>;
+    get(path: string, options?: PermuteRequestOptions): Promise<SkillContent>;
+    update(path: string, request: SkillWriteRequest, options?: PermuteRequestOptions): Promise<KnowledgeWriteResponse>;
+    delete(path: string, options?: PermuteRequestOptions): Promise<KnowledgeWriteResponse>;
+}
 export declare class PermuteClient {
+    readonly revisions: {
+        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>;
+    };
+    readonly facts: {
+        list(options?: PermuteRequestOptions): Promise<FactList>;
+        get(factId: string, options?: PermuteRequestOptions): Promise<Fact>;
+        create(request: FactWriteRequest, options?: PermuteRequestOptions): Promise<Fact>;
+        update(factId: string, request: FactWriteRequest, options?: PermuteRequestOptions): Promise<Fact>;
+        delete(factId: string, options?: PermuteRequestOptions): Promise<KnowledgeWriteResponse>;
+    };
+    readonly skills: SkillsClient;
+    readonly organizationSkills: SkillsClient;
+    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>;
+        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 workspaces: {
         list: (options?: PermuteRequestOptions) => Promise<WorkspaceList>;
         create: (request: WorkspaceCreateRequest, options?: PermuteRequestOptions) => Promise<Workspace>;
@@ -72,6 +103,28 @@ export declare class PermuteClient {
         list: (options?: PermuteRequestOptions) => Promise<SourceList>;
         get: (sourceId: string, options?: PermuteRequestOptions) => Promise<SourceDetail>;
     };
+    readonly operations: {
+        list: (query?: OperationListQuery, options?: PermuteRequestOptions) => Promise<OperationList>;
+        get: (operationId: string, options?: PermuteRequestOptions) => Promise<Operation>;
+        update: (operationId: string, request: OperationUpdateRequest, options?: PermuteRequestOptions) => Promise<Operation>;
+        getSource: (operationId: string, options?: PermuteRequestOptions) => Promise<OperationSource>;
+        updateSource: (operationId: string, request: OperationSourceUpdateRequest, options?: PermuteRequestOptions) => Promise<OperationSource>;
+        getRunOutput: (operationId: string, runId: string, options?: PermuteRequestOptions) => Promise<OperationRunOutput>;
+        listRuns: {
+            (operationId: string, options?: PermuteRequestOptions): Promise<OperationRunList>;
+            (query: OperationRunQuery, options?: PermuteRequestOptions): Promise<OperationRunGroup>;
+        };
+        run: (operationId: string, request: OperationRunRequest, options?: PermuteRequestOptions) => Promise<OperationRunStarted>;
+    };
+    readonly dataFlows: {
+        create: (request: DataFlowCreateRequest, options?: PermuteRequestOptions) => Promise<DataFlow>;
+        get: (dataFlowId: string, options?: PermuteRequestOptions) => Promise<DataFlow>;
+        command: (dataFlowId: string, request: DataFlowCommandRequest, options?: PermuteRequestOptions) => Promise<DataFlowCommandResponse>;
+    };
+    readonly dashboards: {
+        getSource: (dashboardId: string, options?: PermuteRequestOptions) => Promise<DashboardSource>;
+        updateSource: (dashboardId: string, request: DashboardSourceUpdateRequest, options?: PermuteRequestOptions) => Promise<DashboardSource>;
+    };
     readonly datasets: {
         create: {
             (request: CustomDatasetCreateRequest, options?: PermuteRequestOptions): Promise<PermuteDataset>;
@@ -79,6 +132,8 @@ export declare class PermuteClient {
         };
         getByKey: (key: string, options?: PermuteRequestOptions) => Promise<PermuteDataset | PermuteFileDataset>;
         get: (datasetId: string, options?: PermuteRequestOptions) => Promise<PermuteDataset | PermuteFileDataset>;
+        download: (datasetId: string, options?: PermuteRequestOptions) => Promise<string>;
+        delete: (datasetId: string, options?: PermuteRequestOptions) => Promise<DatasetDeleteResponse>;
     };
     private readonly apiKey;
     private readonly baseUrl;

package/dist/client.js

@@ -262,8 +262,16 @@ export class PermuteFileDataset {
     }
 }
 export class PermuteClient {
+    revisions;
+    facts;
+    skills;
+    organizationSkills;
+    databases;
     workspaces;
     sources;
+    operations;
+    dataFlows;
+    dashboards;
     datasets;
     apiKey;
     baseUrl;
@@ -292,6 +300,37 @@ export class PermuteClient {
         this.workspaceId = options.workspaceId;
         this.defaultHeaders = options.headers ?? {};
         this.fetchImpl = fetchImpl.bind(globalThis);
+        this.revisions = {
+            list: (resourceId, options) => this.request('resourceRevisionsList', { pathParams: { resourceId } }, options),
+            get: (resourceId, revisionId, options) => this.request('resourceRevisionsGet', { pathParams: { resourceId, revisionId } }, options),
+            restore: (resourceId, revisionId, body, options) => this.request('resourceRevisionsRestore', { pathParams: { resourceId, revisionId }, body }, options),
+            publish: (resourceId, body, options) => this.request('resourcesPublish', { pathParams: { resourceId }, body }, options),
+        };
+        this.facts = {
+            list: (options) => this.request('factsList', {}, options),
+            get: (factId, options) => this.request('factsGet', { pathParams: { factId } }, options),
+            create: (body, options) => this.request('factsCreate', { body }, options),
+            update: (factId, body, options) => this.request('factsUpdate', { pathParams: { factId }, body }, options),
+            delete: (factId, options) => this.request('factsDelete', { pathParams: { factId } }, options),
+        };
+        const skillsClient = (prefix) => ({
+            list: (options) => this.request(`${prefix}List`, {}, options),
+            get: (path, options) => this.request(`${prefix}Get`, { pathParams: { path } }, options),
+            update: (path, body, options) => this.request(`${prefix}Update`, { pathParams: { path }, body }, options),
+            delete: (path, options) => this.request(`${prefix}Delete`, { pathParams: { path } }, options),
+        });
+        this.skills = skillsClient('skills');
+        this.organizationSkills = skillsClient('organizationSkills');
+        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),
+            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.workspaces = {
             list: (requestOptions) => this.request('workspacesList', {}, requestOptions),
             create: (request, requestOptions) => this.request('workspacesCreate', { body: request }, requestOptions),
@@ -303,6 +342,27 @@ export class PermuteClient {
             list: (requestOptions) => this.request('sourcesList', {}, requestOptions),
             get: (sourceId, requestOptions) => this.request('sourcesGet', { pathParams: { sourceId } }, requestOptions),
         };
+        this.operations = {
+            list: (query = {}, options) => this.request('operationsList', { query }, options),
+            get: (operationId, options) => this.request('operationsGet', { pathParams: { operationId } }, options),
+            update: (operationId, body, options) => this.request('operationsUpdate', { pathParams: { operationId }, body }, options),
+            getSource: (operationId, options) => this.request('operationsSourceGet', { pathParams: { operationId } }, options),
+            updateSource: (operationId, body, options) => this.request('operationsSourceUpdate', { pathParams: { operationId }, body }, options),
+            getRunOutput: (operationId, runId, options) => this.request('operationsRunOutput', { pathParams: { operationId, runId } }, options),
+            listRuns: ((input, options) => typeof input === 'string'
+                ? this.request('operationsRunsList', { pathParams: { operationId: input } }, options)
+                : this.request('operationRunsList', { query: input }, options)),
+            run: (operationId, body, options) => this.request('operationsRun', { pathParams: { operationId }, body }, options),
+        };
+        this.dataFlows = {
+            create: (body, options) => this.request('dataFlowsCreate', { body }, options),
+            get: (dataFlowId, options) => this.request('dataFlowsGet', { pathParams: { dataFlowId } }, options),
+            command: (dataFlowId, body, options) => this.request('dataFlowsCommand', { pathParams: { dataFlowId }, body }, options),
+        };
+        this.dashboards = {
+            getSource: (dashboardId, requestOptions) => this.request('dashboardsSourceGet', { pathParams: { dashboardId } }, requestOptions),
+            updateSource: (dashboardId, request, requestOptions) => this.request('dashboardsSourceUpdate', { pathParams: { dashboardId }, body: request }, requestOptions),
+        };
         const readDataset = (datasetId, requestOptions) => this.request('datasetsGet', { pathParams: { datasetId } }, requestOptions);
         const writeDatasetTables = async (datasetId, request, requestOptions) => {
             const encoded = encodeDatasetWrite(request);
@@ -428,6 +488,11 @@ export class PermuteClient {
                 const dataset = await readDataset(datasetId, requestOptions);
                 return wrapDataset(dataset);
             },
+            download: async (datasetId, requestOptions) => {
+                const { url } = await this.request('datasetsDownload', { pathParams: { datasetId } }, requestOptions);
+                return url;
+            },
+            delete: (datasetId, requestOptions) => this.request('datasetsDelete', { pathParams: { datasetId } }, requestOptions),
         };
     }
     async search(request, options) {
@@ -494,7 +559,7 @@ export class PermuteClient {
         }
         const url = new URL(`${this.baseUrl.replace(/\/+$/, '')}${buildPath(route, input.pathParams)}`);
         for (const [key, value] of Object.entries(query))
-            url.searchParams.set(key, value);
+            url.searchParams.set(key, String(value));
         const response = await this.fetchImpl(url.toString(), {
             method: route.method,
             headers,
@@ -548,6 +613,6 @@ export class PermuteClient {
         if (!queryValidator(requestQuery)) {
             throw validationError(operationId, 'request', queryValidator.errors);
         }
-        return requestQuery;
+        return Object.fromEntries(Object.entries(requestQuery).map(([key, value]) => [key, String(value)]));
     }
 }