@permute/sdk 0.1.2 → 0.3.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
@@ -58,6 +151,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
@@ -109,13 +225,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({
@@ -126,6 +242,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.

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, DatasetDeleteResponse, DatasetResponse, FileDatasetCreateRequest, FileDatasetResponse, DatasetRows, CustomDatasetResponse } from './types.js';
+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;
@@ -60,7 +60,42 @@ 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 connectorSessions: {
+        create(request: ConnectorSessionCreateRequest, options?: PermuteRequestOptions): Promise<ConnectorSessionCreated>;
+        get(sessionId: string, options?: PermuteRequestOptions): Promise<ConnectorSession>;
+    };
     readonly workspaces: {
         list: (options?: PermuteRequestOptions) => Promise<WorkspaceList>;
         create: (request: WorkspaceCreateRequest, options?: PermuteRequestOptions) => Promise<Workspace>;
@@ -72,6 +107,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>;

package/dist/client.js

@@ -262,8 +262,17 @@ export class PermuteFileDataset {
     }
 }
 export class PermuteClient {
+    revisions;
+    facts;
+    skills;
+    organizationSkills;
+    databases;
+    connectorSessions;
     workspaces;
     sources;
+    operations;
+    dataFlows;
+    dashboards;
     datasets;
     apiKey;
     baseUrl;
@@ -292,6 +301,41 @@ 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.connectorSessions = {
+            create: (body, options) => this.request('connectorSessionsCreate', { body }, options),
+            get: (sessionId, options) => this.request('connectorSessionsGet', { pathParams: { sessionId } }, options),
+        };
         this.workspaces = {
             list: (requestOptions) => this.request('workspacesList', {}, requestOptions),
             create: (request, requestOptions) => this.request('workspacesCreate', { body: request }, requestOptions),
@@ -303,6 +347,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);
@@ -499,7 +564,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,
@@ -553,6 +618,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)]));
     }
 }