@narrative.io/data-collaboration-sdk-ts 3.8.0 → 4.0.0-beta.1

package/build/connections/index.d.ts

@@ -1,12 +1,13 @@
 import { BaseApi } from "../base-api";
 import type { ApiRecords } from "../types";
-import type { Connection, ConnectionStatus, ConnectionV2 } from "./types";
+import type { ConnectionAppRef, ConnectionFilters, ConnectionProfileRef, ConnectionQueryType, ConnectionStatus, ConnectionType, ConnectionV2, CreateConnectionRequest, CreateDatasetConnectionRequest, CreateModelConnectionRequest, DatasetConnection, ModelConnection } from "./types";
 /**
  * Class representing the API for connections.
  *
  * @module ConnectionsApi
  * @extends BaseApi
- * @description This class provides methods for fetching and managing connection records.
+ * @description This class provides methods for fetching and managing connection records via the
+ * `/v2/connections` API.
  */
 declare class ConnectionsApi extends BaseApi {
     /**
@@ -14,59 +15,62 @@ declare class ConnectionsApi extends BaseApi {
      *
      * @public
      * @async
-     * @param {string} [connectionId] - The ID of the connection to retrieve.
-     * @returns {Promise<Connection>} A promise that resolves to the connection object.
+     * @param {string} connectionId - The ID of the connection to retrieve.
+     * @returns {Promise<ConnectionV2>} A promise that resolves to the connection object.
      * @throws Will throw an error if the API call fails.
      */
-    getConnection(connectionId?: string): Promise<Connection>;
+    getConnection(connectionId: string): Promise<ConnectionV2>;
     /**
-     * Retrieves all connections associated with a specific dataset.
+     * Lists the calling company's connections, optionally filtered by app, connection type, dataset, model, or
+     * profile.
      *
      * @public
      * @async
-     * @param {number} datasetId - The ID of the dataset to retrieve connections for.
-     * @returns {Promise<ApiRecords<Connection>>} A promise that resolves to an array of connection objects.
+     * @param {ConnectionFilters} [filters] - Optional filters to narrow the returned connections.
+     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
      * @throws Will throw an error if the API call fails.
      */
-    getDatasetConnections(datasetId: number): Promise<ApiRecords<Connection>>;
+    getConnections(filters?: ConnectionFilters): Promise<ApiRecords<ConnectionV2>>;
     /**
-     * Retrieves all connections associated with a specific profile.
+     * Retrieves all connections associated with a specific dataset.
      *
      * @public
      * @async
-     * @param {number} profileId - The ID of the profile to retrieve connections for.
-     * @returns {Promise<ApiRecords<Connection>>} A promise that resolves to an array of connection objects.
+     * @param {number} datasetId - The ID of the dataset to retrieve connections for.
+     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
      * @throws Will throw an error if the API call fails.
      */
-    getProfileConnections(profileId: string): Promise<ApiRecords<Connection>>;
+    getDatasetConnections(datasetId: number): Promise<ApiRecords<ConnectionV2>>;
     /**
-     * Creates a new connection.
+     * Retrieves all connections associated with a specific profile.
      *
      * @public
      * @async
-     * @param {Omit<Connection, "id">} newConnection - The connection data to create, excluding the ID.
-     * @returns {Promise<Connection>} A promise that resolves to the newly created connection object.
+     * @param {string} profileId - The ID of the profile to retrieve connections for.
+     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
      * @throws Will throw an error if the API call fails.
      */
-    createConnection(newConnection: Omit<Connection, "id">): Promise<Connection>;
+    getProfileConnections(profileId: string): Promise<ApiRecords<ConnectionV2>>;
     /**
-     * Deletes a connection.
+     * Creates a new connection routing a dataset's or model's data to a connector app.
      *
      * @public
      * @async
-     * @param {string} connectionId - The ID of the connection to delete.
-     * @returns {Promise<void>} A promise that resolves when the connection is deleted.
+     * @param {CreateConnectionRequest} newConnection - The connection data to create; a discriminated union keyed
+     * on `type` (`connections_dataset` | `connections_model`).
+     * @returns {Promise<ConnectionV2>} A promise that resolves to the newly created connection object.
      * @throws Will throw an error if the API call fails.
      */
-    deleteConnection(connectionId: string): Promise<void>;
+    createConnection(newConnection: CreateConnectionRequest): Promise<ConnectionV2>;
     /**
-     * Retrieves all connections for a given account.
+     * Archives a connection. The connection is not deleted; its status becomes `archived`.
      *
      * @public
      * @async
-     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
+     * @param {string} connectionId - The ID of the connection to archive.
+     * @returns {Promise<void>} A promise that resolves when the connection is archived.
      * @throws Will throw an error if the API call fails.
      */
-    getConnections(): Promise<ApiRecords<ConnectionV2>>;
+    deleteConnection(connectionId: string): Promise<void>;
 }
-export { type Connection, type ConnectionStatus, ConnectionsApi, type ConnectionV2, };
+export { type ConnectionAppRef, type ConnectionFilters, type ConnectionProfileRef, type ConnectionQueryType, type ConnectionStatus, ConnectionsApi, type ConnectionType, type ConnectionV2, type CreateConnectionRequest, type CreateDatasetConnectionRequest, type CreateModelConnectionRequest, type DatasetConnection, type ModelConnection, };

package/build/connections/index.js

@@ -5,13 +5,14 @@ import { BaseApi } from "../base-api";
  * @private
  * @type {string}
  */
-const resourceName = "connections";
+const resourceName = "v2/connections";
 /**
  * Class representing the API for connections.
  *
  * @module ConnectionsApi
  * @extends BaseApi
- * @description This class provides methods for fetching and managing connection records.
+ * @description This class provides methods for fetching and managing connection records via the
+ * `/v2/connections` API.
  */
 class ConnectionsApi extends BaseApi {
     /**
@@ -19,76 +20,94 @@ class ConnectionsApi extends BaseApi {
      *
      * @public
      * @async
-     * @param {string} [connectionId] - The ID of the connection to retrieve.
-     * @returns {Promise<Connection>} A promise that resolves to the connection object.
+     * @param {string} connectionId - The ID of the connection to retrieve.
+     * @returns {Promise<ConnectionV2>} A promise that resolves to the connection object.
      * @throws Will throw an error if the API call fails.
      */
     async getConnection(connectionId) {
         const url = `${resourceName}/${connectionId}`;
         return await this.get(url);
     }
+    /**
+     * Lists the calling company's connections, optionally filtered by app, connection type, dataset, model, or
+     * profile.
+     *
+     * @public
+     * @async
+     * @param {ConnectionFilters} [filters] - Optional filters to narrow the returned connections.
+     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
+     * @throws Will throw an error if the API call fails.
+     */
+    async getConnections(filters) {
+        const queryParams = new URLSearchParams();
+        if (filters?.app_id != null) {
+            queryParams.append("app_id", String(filters.app_id));
+        }
+        if (filters?.connection_type) {
+            queryParams.append("connection_type", filters.connection_type);
+        }
+        if (filters?.dataset_id != null) {
+            queryParams.append("dataset_id", String(filters.dataset_id));
+        }
+        if (filters?.model_id != null) {
+            queryParams.append("model_id", String(filters.model_id));
+        }
+        if (filters?.profile_id) {
+            queryParams.append("profile_id", filters.profile_id);
+        }
+        const queryString = queryParams.toString();
+        const url = queryString ? `${resourceName}?${queryString}` : resourceName;
+        return await this.get(url);
+    }
     /**
      * Retrieves all connections associated with a specific dataset.
      *
      * @public
      * @async
      * @param {number} datasetId - The ID of the dataset to retrieve connections for.
-     * @returns {Promise<ApiRecords<Connection>>} A promise that resolves to an array of connection objects.
+     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
      * @throws Will throw an error if the API call fails.
      */
     async getDatasetConnections(datasetId) {
-        const url = `${resourceName}?dataset_id=${datasetId}`;
-        return await this.get(url);
+        return await this.getConnections({ dataset_id: datasetId });
     }
     /**
      * Retrieves all connections associated with a specific profile.
      *
      * @public
      * @async
-     * @param {number} profileId - The ID of the profile to retrieve connections for.
-     * @returns {Promise<ApiRecords<Connection>>} A promise that resolves to an array of connection objects.
+     * @param {string} profileId - The ID of the profile to retrieve connections for.
+     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
      * @throws Will throw an error if the API call fails.
      */
     async getProfileConnections(profileId) {
-        const url = `${resourceName}?profile_id=${profileId}`;
-        return await this.get(url);
+        return await this.getConnections({ profile_id: profileId });
     }
     /**
-     * Creates a new connection.
+     * Creates a new connection routing a dataset's or model's data to a connector app.
      *
      * @public
      * @async
-     * @param {Omit<Connection, "id">} newConnection - The connection data to create, excluding the ID.
-     * @returns {Promise<Connection>} A promise that resolves to the newly created connection object.
+     * @param {CreateConnectionRequest} newConnection - The connection data to create; a discriminated union keyed
+     * on `type` (`connections_dataset` | `connections_model`).
+     * @returns {Promise<ConnectionV2>} A promise that resolves to the newly created connection object.
      * @throws Will throw an error if the API call fails.
      */
     async createConnection(newConnection) {
         return await this.post(resourceName, newConnection);
     }
     /**
-     * Deletes a connection.
+     * Archives a connection. The connection is not deleted; its status becomes `archived`.
      *
      * @public
      * @async
-     * @param {string} connectionId - The ID of the connection to delete.
-     * @returns {Promise<void>} A promise that resolves when the connection is deleted.
+     * @param {string} connectionId - The ID of the connection to archive.
+     * @returns {Promise<void>} A promise that resolves when the connection is archived.
      * @throws Will throw an error if the API call fails.
      */
     async deleteConnection(connectionId) {
         const url = `${resourceName}/${connectionId}`;
         return await this.delete(url);
     }
-    /**
-     * Retrieves all connections for a given account.
-     *
-     * @public
-     * @async
-     * @returns {Promise<ApiRecords<ConnectionV2>>} A promise that resolves to an array of connection objects.
-     * @throws Will throw an error if the API call fails.
-     */
-    async getConnections() {
-        const url = `v2/${resourceName}`;
-        return await this.get(url);
-    }
 }
 export { ConnectionsApi, };

package/build/connections/types.d.ts

@@ -1,21 +1,74 @@
 export type ConnectionStatus = "active" | "archived";
-export interface Connection {
+/** Discriminator values for a {@link ConnectionV2}. */
+export type ConnectionType = "connections_dataset" | "connections_model";
+/** Values accepted by the `connection_type` list filter (distinct from the {@link ConnectionType} discriminator). */
+export type ConnectionQueryType = "dataset" | "model";
+export interface ConnectionAppRef {
+    id: number;
+    name: string;
+}
+export interface ConnectionProfileRef {
     id: string;
-    dataset_id: number;
-    profile_id: string;
-    quick_settings: Record<string, unknown>;
-    status?: ConnectionStatus;
-}
-export interface ConnectionV2 extends Connection {
-    type: string;
-    app: {
-        id: number;
-        name: string;
-    };
+    name: string;
+}
+interface ConnectionV2Base {
+    id: string;
+    app: ConnectionAppRef;
     created_at: string;
     installation_id: number;
-    profile: {
-        id: string;
-        name: string;
-    };
+    /** Optional connector-specific settings, validated by the connector. */
+    quick_settings?: Record<string, unknown>;
+    /** @deprecated kept for backward compatibility, use {@link ConnectionV2Base.profile} instead. */
+    profile_id: string;
+    profile: ConnectionProfileRef;
+    status: ConnectionStatus;
+}
+export interface DatasetConnection extends ConnectionV2Base {
+    type: "connections_dataset";
+    dataset_id: number;
+}
+export interface ModelConnection extends ConnectionV2Base {
+    type: "connections_model";
+    model_id: number;
+}
+/**
+ * A connection routing a dataset's or model's data to a connector app.
+ *
+ * Discriminated on `type`.
+ */
+export type ConnectionV2 = DatasetConnection | ModelConnection;
+export interface CreateDatasetConnectionRequest {
+    type: "connections_dataset";
+    /** The dataset whose data is routed to the connector. */
+    dataset_id: number;
+    profile_id: string;
+    /** Optional connector-specific settings, validated by the connector. */
+    quick_settings?: Record<string, unknown>;
+}
+export interface CreateModelConnectionRequest {
+    type: "connections_model";
+    /** The model connected to the connector. */
+    model_id: number;
+    profile_id: string;
+    /** Optional connector-specific settings, validated by the connector. */
+    quick_settings?: Record<string, unknown>;
+}
+/**
+ * Request body for creating a connection.
+ *
+ * Discriminated on `type`.
+ */
+export type CreateConnectionRequest = CreateDatasetConnectionRequest | CreateModelConnectionRequest;
+export interface ConnectionFilters {
+    /** Only return connections to this app. */
+    app_id?: number;
+    /** Only return connections of this type. */
+    connection_type?: ConnectionQueryType;
+    /** Only return connections from this dataset. */
+    dataset_id?: number;
+    /** Only return connections from this model. */
+    model_id?: number;
+    /** Only return connections created against this app profile. */
+    profile_id?: string;
 }
+export {};

package/build/contracts/index.d.ts

@@ -1,33 +1,24 @@
 import { BaseApi } from "../base-api";
+import type { ApiRecords } from "../types";
 import type { ContractDetails, ContractRateView, CustomerContract, PaymentMethod } from "./types";
 /**
  * A class for accessing the Contracts API.
+ *
+ * Only the read routes `GET /contracts` and `GET /contracts/active` are part of
+ * the public surface. Fetching a specific contract revision and updating a
+ * contract exist server-side only as admin routes (`GET
+ * /admin/contracts/{id}/{revision}` and `PUT /admin/contracts/{company_id}`,
+ * both requiring `Permission.Admin`), so they are intentionally not exposed
+ * here.
  * @extends BaseApi
  */
 declare class ContractsApi extends BaseApi {
     /**
      * Gets a list of contracts from the API.
      *
-     * @returns {Promise<CustomerContract[]>} A promise that resolves with the list of contracts.
+     * @returns {Promise<ApiRecords<ContractDetails>>} A promise that resolves with the list of contracts.
      */
-    getContracts(): Promise<ContractDetails[]>;
-    /**
-     * Get a customer contract based on the contract ID
-     *
-     * @param contractId - ID of the customer contract
-     * @returns Promise that resolves to the customer contract
-     *
-     */
-    getContract(contractId: string): Promise<ContractDetails>;
-    /**
-     * Update a customer contract's payment method based on the contract ID
-     *
-     * @param contractId - ID of the customer contract
-     * @param paymentMethod - the updated payment method
-     * @returns Promise that resolves to the updated customer contract
-     *
-     */
-    updatePaymentMethod(contractId: string, paymentMethod: PaymentMethod): Promise<ContractDetails>;
+    getContracts(): Promise<ApiRecords<ContractDetails>>;
     /**
      * Get the active contract for a company
      *

package/build/contracts/index.js

@@ -8,38 +8,24 @@ import { BaseApi } from "../base-api";
 const resourceName = "contracts";
 /**
  * A class for accessing the Contracts API.
+ *
+ * Only the read routes `GET /contracts` and `GET /contracts/active` are part of
+ * the public surface. Fetching a specific contract revision and updating a
+ * contract exist server-side only as admin routes (`GET
+ * /admin/contracts/{id}/{revision}` and `PUT /admin/contracts/{company_id}`,
+ * both requiring `Permission.Admin`), so they are intentionally not exposed
+ * here.
  * @extends BaseApi
  */
 class ContractsApi extends BaseApi {
     /**
      * Gets a list of contracts from the API.
      *
-     * @returns {Promise<CustomerContract[]>} A promise that resolves with the list of contracts.
+     * @returns {Promise<ApiRecords<ContractDetails>>} A promise that resolves with the list of contracts.
      */
     async getContracts() {
         return await this.get(resourceName);
     }
-    /**
-     * Get a customer contract based on the contract ID
-     *
-     * @param contractId - ID of the customer contract
-     * @returns Promise that resolves to the customer contract
-     *
-     */
-    async getContract(contractId) {
-        return await this.get(`${resourceName}/${contractId}`);
-    }
-    /**
-     * Update a customer contract's payment method based on the contract ID
-     *
-     * @param contractId - ID of the customer contract
-     * @param paymentMethod - the updated payment method
-     * @returns Promise that resolves to the updated customer contract
-     *
-     */
-    async updatePaymentMethod(contractId, paymentMethod) {
-        return await this.put(`${resourceName}/${contractId}`, paymentMethod);
-    }
     /**
      * Get the active contract for a company
      *

package/build/contracts/types.d.ts

@@ -4,7 +4,7 @@ export interface ContractDetails {
 }
 export interface CustomerContract {
     id: string;
-    company_id: number;
+    payable_company_id: number;
     payment_method: PaymentMethod;
     internal_notes?: string;
     revision: number;
@@ -39,10 +39,14 @@ export interface UnitPrice {
 export interface ProductView {
     id?: string;
     sku?: string;
-    sku_type?: string;
+    sku_type?: SkuType;
     payable_company_id?: number;
     name?: string;
     unit?: string;
     status?: ProductStatus;
 }
+export type SkuTypeCategory = "processing" | "storage" | "transfer" | "marketplace-data-transaction";
+export interface SkuType {
+    category: SkuTypeCategory;
+}
 export type ProductStatus = "active" | "archived";

package/build/data-planes/index.d.ts

@@ -5,6 +5,10 @@ export declare class DataPlaneApi extends BaseApi {
     getDataPlanes(): Promise<ApiRecords<DataPlane>>;
     getDataPlane(dataPlaneId: string): Promise<DataPlane>;
     setDefaultComputePool(dataPlaneId: string, computePoolId: string): Promise<DataPlane>;
-    clearDefaultComputePool(dataPlaneId: string): Promise<void>;
+    /**
+     * Clears the default compute pool for a data plane.
+     * @returns {Promise<DataPlane>} - Promise resolving with the updated data plane.
+     */
+    clearDefaultComputePool(dataPlaneId: string): Promise<DataPlane>;
     runHealthCheck(dataPlaneId: string, computePoolId?: string): Promise<HealthCheckJobResponse>;
 }

package/build/data-planes/index.js

@@ -10,8 +10,14 @@ export class DataPlaneApi extends BaseApi {
     async setDefaultComputePool(dataPlaneId, computePoolId) {
         return await this.put(`${resourceName}/${dataPlaneId}/default-compute-pool/${computePoolId}`, undefined);
     }
+    /**
+     * Clears the default compute pool for a data plane.
+     * @returns {Promise<DataPlane>} - Promise resolving with the updated data plane.
+     */
     async clearDefaultComputePool(dataPlaneId) {
-        await this.delete(`${resourceName}/${dataPlaneId}/default-compute-pool`);
+        // BaseApi#delete discards the response body; the backend returns the updated
+        // data plane, so call the underlying client directly to surface it.
+        return await this.base_api.delete(`${resourceName}/${dataPlaneId}/default-compute-pool`);
     }
     async runHealthCheck(dataPlaneId, computePoolId) {
         const body = computePoolId != null ? { compute_pool_id: computePoolId } : {};

package/build/data-planes/types.d.ts

@@ -1,24 +1,80 @@
 import type { ComputePoolResponse, Participants } from "../compute-pools/types";
+import type { Job } from "../jobs/types";
+/** Discriminator distinguishing an owned data plane from one shared with you. */
 export type DataPlaneType = "owned" | "shared";
-export type DataPlaneStatus = "active" | "inactive" | "archived";
-export type DataPlanePlatformType = "platform_snowflake" | "platform_shared_snowflake" | "platform_aws" | "platform_shared_aws";
-export type DataPlaneRegionType = "region_aws";
-export interface DataPlanePlatformRegion {
-    type: DataPlaneRegionType;
+/**
+ * Lifecycle status of a data plane. The backend `DataPlane.Status` codec only
+ * emits `active` and `archived` (the previously-listed `inactive` could not be
+ * confirmed in the backend and was removed).
+ */
+export type DataPlaneStatus = "active" | "archived";
+/** An AWS region. `id` is the region code, e.g. `us-east-1`. */
+export interface AwsRegion {
+    type: "region_aws";
     id: string;
 }
-export interface DataPlanePlatform {
-    type: DataPlanePlatformType;
+export interface AzureRegion {
+    type: "region_azure";
+    id: string;
+}
+export interface GcpRegion {
+    type: "region_gcp";
+    id: string;
+}
+/**
+ * The region a data plane runs in. Encoded as a discriminated object, not a
+ * bare string — see `DataPlane.Region` in `datashops-protocol`.
+ */
+export type DataPlaneRegion = AwsRegion | AzureRegion | GcpRegion;
+export interface AwsPlatform {
+    type: "platform_aws";
+    /** 12-digit AWS account id. */
+    account_id: string;
+    region: AwsRegion;
+}
+export interface SnowflakePlatform {
+    type: "platform_snowflake";
     account_locator: string;
     account_name: string;
     organization_name: string;
-    region: DataPlanePlatformRegion;
+    /**
+     * Optional: the platform can fail to parse a region when provisioning the
+     * Snowflake Native App. Informational only.
+     */
+    region?: DataPlaneRegion;
 }
+/** Platform details returned for a data plane the calling company owns. */
+export type DataPlanePlatform = AwsPlatform | SnowflakePlatform;
+export interface AwsSharedPlatform {
+    type: "platform_shared_aws";
+    region: AwsRegion;
+}
+export interface SnowflakeSharedPlatform {
+    type: "platform_shared_snowflake";
+    region?: DataPlaneRegion;
+}
+/**
+ * Platform details returned for a data plane shared with you. Account
+ * identifiers are omitted for non-owned data planes.
+ */
+export type DataPlaneSharedPlatform = AwsSharedPlatform | SnowflakeSharedPlatform;
+/**
+ * The `platform.type` discriminator of any data plane, owned or shared. Owned and shared platforms
+ * are modelled as separate unions, so this is the flat set of wire literals across both.
+ */
+export type DataPlanePlatformType = DataPlanePlatform["type"] | DataPlaneSharedPlatform["type"];
 export interface DataPlaneCollaborators {
     participants: Participants;
+    /** Companies allowed to create/edit/archive compute pools on this data plane. */
+    manage_compute_pools: Participants;
 }
-export interface DataPlane {
-    type: DataPlaneType;
+/**
+ * A data plane owned by the calling company. Includes full details such as the
+ * external id and collaborators.
+ */
+export interface DataPlaneOwnedResponse {
+    type: "owned";
+    /** UUID. */
     id: string;
     company_id: number;
     created_at: string;
@@ -27,16 +83,40 @@ export interface DataPlane {
     platform: DataPlanePlatform;
     status: DataPlaneStatus;
     updated_at: string;
+    collaborators: DataPlaneCollaborators;
+    compute_pools: ComputePoolResponse[];
     description?: string;
     tags?: string[];
     last_heartbeat_at?: string;
     default_compute_pool_id?: string;
-    compute_pools?: ComputePoolResponse[];
-    collaborators?: DataPlaneCollaborators;
 }
+/**
+ * A data plane shared with the calling company. Omits details like the external
+ * id and collaborators that are only exposed to the owner.
+ */
+export interface DataPlaneSharedResponse {
+    type: "shared";
+    /** UUID. */
+    id: string;
+    company_id: number;
+    created_at: string;
+    display_name: string;
+    platform: DataPlaneSharedPlatform;
+    status: DataPlaneStatus;
+    updated_at: string;
+    compute_pools: ComputePoolResponse[];
+    description?: string;
+    tags?: string[];
+    last_heartbeat_at?: string;
+    default_compute_pool_id?: string;
+}
+/** Discriminated union of the owned/shared data plane response shapes. */
+export type DataPlane = DataPlaneOwnedResponse | DataPlaneSharedResponse;
 export interface HealthCheckRequest {
     compute_pool_id?: string;
 }
-export interface HealthCheckJobResponse {
-    job_id: string;
-}
+/**
+ * The backend enqueues a `health_check` job and returns the full job record (201 Created),
+ * not just its id — see `POST /data-planes/{id}/health-check`.
+ */
+export type HealthCheckJobResponse = Job;