@permute/sdk 0.2.0 → 0.3.0

package/README.md

@@ -151,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
@@ -202,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({
@@ -219,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 { 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';
+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;
@@ -92,6 +92,10 @@ export declare class PermuteClient {
         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>;

package/dist/client.js

@@ -267,6 +267,7 @@ export class PermuteClient {
     skills;
     organizationSkills;
     databases;
+    connectorSessions;
     workspaces;
     sources;
     operations;
@@ -331,6 +332,10 @@ export class PermuteClient {
             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),

package/dist/generated/openapi.d.ts

@@ -124,6 +124,54 @@ export interface components {
             name: string;
             provider?: string;
         };
+        /** @enum {string} */
+        ConnectorProviderId: 'acumatica' | 'attio' | 'autodesk' | 'bigquery' | 'billcom' | 'brex' | 'double' | 'fireflies' | 'googleads' | 'granola' | 'hubspot' | 'klaviyo' | 'mercury' | 'meta_ads' | 'monday' | 'procore' | 'quickbooks' | 'quo' | 's3' | 'salesforce' | 'shopify' | 'stripe' | 'supabase' | 'xero';
+        ConnectorSession: {
+            connectorId: string;
+            connectorStatus: string;
+            /** Format: date-time */
+            expiresAt: string;
+            id: string;
+            provider: string;
+            /** @enum {string} */
+            status: 'pending' | 'in_progress' | 'authorized' | 'completed' | 'expired';
+        };
+        ConnectorSessionCreated: {
+            connectorId: string;
+            connectorStatus: string;
+            /** Format: date-time */
+            expiresAt: string;
+            id: string;
+            provider: string;
+            /** @enum {string} */
+            status: 'pending' | 'in_progress' | 'authorized' | 'completed' | 'expired';
+            /** Format: uri */
+            url: string;
+        };
+        ConnectorSessionCreateRequest: {
+            config?: {
+                [key: string]: unknown;
+            };
+            connectorId?: string;
+            name?: string;
+            /** @enum {string} */
+            provider: 'acumatica' | 'attio' | 'autodesk' | 'bigquery' | 'billcom' | 'brex' | 'double' | 'fireflies' | 'googleads' | 'granola' | 'hubspot' | 'klaviyo' | 'mercury' | 'meta_ads' | 'monday' | 'procore' | 'quickbooks' | 'quo' | 's3' | 'salesforce' | 'shopify' | 'stripe' | 'supabase' | 'xero';
+            /** Format: uri */
+            returnUrl?: string;
+        } | {
+            config?: {
+                [key: string]: unknown;
+            };
+            connectorId: string;
+            name?: string;
+            /** @enum {string} */
+            provider?: 'acumatica' | 'attio' | 'autodesk' | 'bigquery' | 'billcom' | 'brex' | 'double' | 'fireflies' | 'googleads' | 'granola' | 'hubspot' | 'klaviyo' | 'mercury' | 'meta_ads' | 'monday' | 'procore' | 'quickbooks' | 'quo' | 's3' | 'salesforce' | 'shopify' | 'stripe' | 'supabase' | 'xero';
+            /** Format: uri */
+            returnUrl?: string;
+        };
+        ConnectorSessionIdParams: {
+            sessionId: string;
+        };
         CustomDatasetResponse: {
             context: string[];
             /** Format: date-time */

package/dist/generated/runtime-contract.d.ts

@@ -8,5 +8,31 @@ export interface RuntimeRoute {
     querySchema: JsonSchema | null;
     responseSchema: JsonSchema;
 }
-export type PublicApiOperationId = 'resourceRevisionsList' | 'resourceRevisionsGet' | 'resourceRevisionsRestore' | 'resourcesPublish' | 'workspacesList' | 'workspacesCreate' | 'workspacesGet' | 'workspacesUpdate' | 'workspacesDelete' | 'sourcesList' | 'sourcesGet' | 'dashboardsSourceGet' | 'dashboardsSourceUpdate' | 'datasetsCreate' | 'datasetsGetByKey' | 'datasetsGet' | 'datasetsDelete' | 'datasetsDownload' | 'datasetsWriteTables' | 'searchCreate' | 'answerJobsCreate' | 'answerJobsGet' | 'queriesCreate' | 'operationRunsList' | 'operationsList' | 'operationsGet' | 'operationsUpdate' | 'operationsSourceGet' | 'operationsSourceUpdate' | 'operationsRunsList' | 'operationsRun' | 'operationsRunOutput' | 'dataFlowsCreate' | 'dataFlowsGet' | 'dataFlowsCommand' | 'factsList' | 'factsCreate' | 'factsGet' | 'factsUpdate' | 'factsDelete' | 'skillsList' | 'skillsGet' | 'skillsUpdate' | 'skillsDelete' | 'organizationSkillsList' | 'organizationSkillsGet' | 'organizationSkillsUpdate' | 'organizationSkillsDelete' | 'databasesList' | 'databasesCreate' | 'databasesGet' | 'databasesDelete' | 'databaseTablesList' | 'databaseTablesCreate' | 'databaseRecordsList' | 'databaseTransactionsCreate';
+export type PublicApiOperationId = 'connectorSessionsCreate' | 'connectorSessionsGet' | 'resourceRevisionsList' | 'resourceRevisionsGet' | 'resourceRevisionsRestore' | 'resourcesPublish' | 'workspacesList' | 'workspacesCreate' | 'workspacesGet' | 'workspacesUpdate' | 'workspacesDelete' | 'sourcesList' | 'sourcesGet' | 'dashboardsSourceGet' | 'dashboardsSourceUpdate' | 'datasetsCreate' | 'datasetsGetByKey' | 'datasetsGet' | 'datasetsDelete' | 'datasetsDownload' | 'datasetsWriteTables' | 'searchCreate' | 'answerJobsCreate' | 'answerJobsGet' | 'queriesCreate' | 'operationRunsList' | 'operationsList' | 'operationsGet' | 'operationsUpdate' | 'operationsSourceGet' | 'operationsSourceUpdate' | 'operationsRunsList' | 'operationsRun' | 'operationsRunOutput' | 'dataFlowsCreate' | 'dataFlowsGet' | 'dataFlowsCommand' | 'factsList' | 'factsCreate' | 'factsGet' | 'factsUpdate' | 'factsDelete' | 'skillsList' | 'skillsGet' | 'skillsUpdate' | 'skillsDelete' | 'organizationSkillsList' | 'organizationSkillsGet' | 'organizationSkillsUpdate' | 'organizationSkillsDelete' | 'databasesList' | 'databasesCreate' | 'databasesGet' | 'databasesDelete' | 'databaseTablesList' | 'databaseTablesCreate' | 'databaseRecordsList' | 'databaseTransactionsCreate';
 export declare const publicApiRoutes: Record<PublicApiOperationId, RuntimeRoute>;
+export declare const Providers: {
+    readonly ACUMATICA: "acumatica";
+    readonly ATTIO: "attio";
+    readonly AUTODESK: "autodesk";
+    readonly BIGQUERY: "bigquery";
+    readonly BILLCOM: "billcom";
+    readonly BREX: "brex";
+    readonly DOUBLE: "double";
+    readonly FIREFLIES: "fireflies";
+    readonly GOOGLEADS: "googleads";
+    readonly GRANOLA: "granola";
+    readonly HUBSPOT: "hubspot";
+    readonly KLAVIYO: "klaviyo";
+    readonly MERCURY: "mercury";
+    readonly META_ADS: "meta_ads";
+    readonly MONDAY: "monday";
+    readonly PROCORE: "procore";
+    readonly QUICKBOOKS: "quickbooks";
+    readonly QUO: "quo";
+    readonly S3: "s3";
+    readonly SALESFORCE: "salesforce";
+    readonly SHOPIFY: "shopify";
+    readonly STRIPE: "stripe";
+    readonly SUPABASE: "supabase";
+    readonly XERO: "xero";
+};

package/dist/generated/runtime-contract.js

@@ -1,5 +1,190 @@
 // This file is generated by scripts/generate-contract.ts. Do not edit.
 export const publicApiRoutes = {
+    connectorSessionsCreate: {
+        operationId: 'connectorSessionsCreate',
+        method: 'POST',
+        path: '/v1/connector-sessions',
+        scope: 'workspace',
+        bodySchema: {
+            anyOf: [
+                {
+                    type: 'object',
+                    properties: {
+                        provider: {
+                            type: 'string',
+                            enum: [
+                                'acumatica',
+                                'attio',
+                                'autodesk',
+                                'bigquery',
+                                'billcom',
+                                'brex',
+                                'double',
+                                'fireflies',
+                                'googleads',
+                                'granola',
+                                'hubspot',
+                                'klaviyo',
+                                'mercury',
+                                'meta_ads',
+                                'monday',
+                                'procore',
+                                'quickbooks',
+                                'quo',
+                                's3',
+                                'salesforce',
+                                'shopify',
+                                'stripe',
+                                'supabase',
+                                'xero',
+                            ],
+                        },
+                        name: {
+                            type: 'string',
+                            minLength: 1,
+                            maxLength: 255,
+                        },
+                        connectorId: {
+                            type: 'string',
+                            pattern: '^conn_[a-z0-9]{24}$',
+                        },
+                        config: {
+                            type: 'object',
+                            additionalProperties: {},
+                        },
+                        returnUrl: {
+                            type: 'string',
+                            maxLength: 2047,
+                            format: 'uri',
+                        },
+                    },
+                    required: ['provider'],
+                    additionalProperties: false,
+                },
+                {
+                    type: 'object',
+                    properties: {
+                        provider: {
+                            type: 'string',
+                            enum: [
+                                'acumatica',
+                                'attio',
+                                'autodesk',
+                                'bigquery',
+                                'billcom',
+                                'brex',
+                                'double',
+                                'fireflies',
+                                'googleads',
+                                'granola',
+                                'hubspot',
+                                'klaviyo',
+                                'mercury',
+                                'meta_ads',
+                                'monday',
+                                'procore',
+                                'quickbooks',
+                                'quo',
+                                's3',
+                                'salesforce',
+                                'shopify',
+                                'stripe',
+                                'supabase',
+                                'xero',
+                            ],
+                        },
+                        name: {
+                            type: 'string',
+                            minLength: 1,
+                            maxLength: 255,
+                        },
+                        connectorId: {
+                            type: 'string',
+                            pattern: '^conn_[a-z0-9]{24}$',
+                        },
+                        config: {
+                            type: 'object',
+                            additionalProperties: {},
+                        },
+                        returnUrl: {
+                            type: 'string',
+                            maxLength: 2047,
+                            format: 'uri',
+                        },
+                    },
+                    required: ['connectorId'],
+                    additionalProperties: false,
+                },
+            ],
+        },
+        querySchema: null,
+        responseSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                },
+                connectorId: {
+                    type: 'string',
+                },
+                provider: {
+                    type: 'string',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'authorized', 'completed', 'expired'],
+                },
+                expiresAt: {
+                    type: 'string',
+                    format: 'date-time',
+                },
+                connectorStatus: {
+                    type: 'string',
+                },
+                url: {
+                    type: 'string',
+                    format: 'uri',
+                },
+            },
+            required: ['id', 'connectorId', 'provider', 'status', 'expiresAt', 'connectorStatus', 'url'],
+            additionalProperties: false,
+        },
+    },
+    connectorSessionsGet: {
+        operationId: 'connectorSessionsGet',
+        method: 'GET',
+        path: '/v1/connector-sessions/{sessionId}',
+        scope: 'workspace',
+        bodySchema: null,
+        querySchema: null,
+        responseSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                },
+                connectorId: {
+                    type: 'string',
+                },
+                provider: {
+                    type: 'string',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'authorized', 'completed', 'expired'],
+                },
+                expiresAt: {
+                    type: 'string',
+                    format: 'date-time',
+                },
+                connectorStatus: {
+                    type: 'string',
+                },
+            },
+            required: ['id', 'connectorId', 'provider', 'status', 'expiresAt', 'connectorStatus'],
+            additionalProperties: false,
+        },
+    },
     resourceRevisionsList: {
         operationId: 'resourceRevisionsList',
         method: 'GET',
@@ -5515,3 +5700,29 @@ export const publicApiRoutes = {
         },
     },
 };
+export const Providers = {
+    ACUMATICA: 'acumatica',
+    ATTIO: 'attio',
+    AUTODESK: 'autodesk',
+    BIGQUERY: 'bigquery',
+    BILLCOM: 'billcom',
+    BREX: 'brex',
+    DOUBLE: 'double',
+    FIREFLIES: 'fireflies',
+    GOOGLEADS: 'googleads',
+    GRANOLA: 'granola',
+    HUBSPOT: 'hubspot',
+    KLAVIYO: 'klaviyo',
+    MERCURY: 'mercury',
+    META_ADS: 'meta_ads',
+    MONDAY: 'monday',
+    PROCORE: 'procore',
+    QUICKBOOKS: 'quickbooks',
+    QUO: 'quo',
+    S3: 's3',
+    SALESFORCE: 'salesforce',
+    SHOPIFY: 'shopify',
+    STRIPE: 'stripe',
+    SUPABASE: 'supabase',
+    XERO: 'xero',
+};

package/dist/index.d.ts

@@ -1,19 +1,20 @@
 export * from './types.js';
 export * from './client.js';
-export declare const CONTEXT: {
-    readonly Acumatica: "acumatica";
-    readonly QuickBooks: "quickbooks";
-    readonly HubSpot: "hubspot";
-    readonly Attio: "attio";
-    readonly BigQuery: "bigquery";
-    readonly Billcom: "billcom";
-    readonly Brex: "brex";
-    readonly Double: "double";
-    readonly Fireflies: "fireflies";
-    readonly Klaviyo: "klaviyo";
-    readonly Mercury: "mercury";
-    readonly Monday: "monday";
-    readonly Shopify: "shopify";
-    readonly Stripe: "stripe";
-    readonly Xero: "xero";
+export { Providers } from './generated/runtime-contract.js';
+export declare const Context: {
+    readonly ACUMATICA: "acumatica";
+    readonly QUICKBOOKS: "quickbooks";
+    readonly HUBSPOT: "hubspot";
+    readonly ATTIO: "attio";
+    readonly BIGQUERY: "bigquery";
+    readonly BILLCOM: "billcom";
+    readonly BREX: "brex";
+    readonly DOUBLE: "double";
+    readonly FIREFLIES: "fireflies";
+    readonly KLAVIYO: "klaviyo";
+    readonly MERCURY: "mercury";
+    readonly MONDAY: "monday";
+    readonly SHOPIFY: "shopify";
+    readonly STRIPE: "stripe";
+    readonly XERO: "xero";
 };

package/dist/index.js

@@ -1,19 +1,20 @@
 export * from './types.js';
 export * from './client.js';
-export const CONTEXT = {
-    Acumatica: 'acumatica',
-    QuickBooks: 'quickbooks',
-    HubSpot: 'hubspot',
-    Attio: 'attio',
-    BigQuery: 'bigquery',
-    Billcom: 'billcom',
-    Brex: 'brex',
-    Double: 'double',
-    Fireflies: 'fireflies',
-    Klaviyo: 'klaviyo',
-    Mercury: 'mercury',
-    Monday: 'monday',
-    Shopify: 'shopify',
-    Stripe: 'stripe',
-    Xero: 'xero',
+export { Providers } from './generated/runtime-contract.js';
+export const Context = {
+    ACUMATICA: 'acumatica',
+    QUICKBOOKS: 'quickbooks',
+    HUBSPOT: 'hubspot',
+    ATTIO: 'attio',
+    BIGQUERY: 'bigquery',
+    BILLCOM: 'billcom',
+    BREX: 'brex',
+    DOUBLE: 'double',
+    FIREFLIES: 'fireflies',
+    KLAVIYO: 'klaviyo',
+    MERCURY: 'mercury',
+    MONDAY: 'monday',
+    SHOPIFY: 'shopify',
+    STRIPE: 'stripe',
+    XERO: 'xero',
 };

package/dist/types.d.ts

@@ -1,5 +1,9 @@
 import type { components } from './generated/openapi.js';
 type PublicApiSchema<Name extends keyof components['schemas']> = components['schemas'][Name];
+export type ConnectorSession = PublicApiSchema<'ConnectorSession'>;
+export type ConnectorSessionCreated = PublicApiSchema<'ConnectorSessionCreated'>;
+export type ConnectorSessionCreateRequest = PublicApiSchema<'ConnectorSessionCreateRequest'>;
+export type ConnectorProviderId = PublicApiSchema<'ConnectorProviderId'>;
 export type Workspace = PublicApiSchema<'Workspace'>;
 export type WorkspaceList = PublicApiSchema<'WorkspaceList'>;
 export type WorkspaceCreateRequest = PublicApiSchema<'WorkspaceCreateRequest'>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@permute/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript client for the Permute public API",
   "type": "module",
   "license": "Apache-2.0",