@narrative.io/data-collaboration-sdk-ts 4.3.0 → 4.4.0

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

@@ -38,10 +38,11 @@ export interface SnowflakePlatform {
     account_name: string;
     organization_name: string;
     /**
-     * Optional: the platform can fail to parse a region when provisioning the
-     * Snowflake Native App. Informational only.
+     * The platform can fail to parse a region when provisioning the Snowflake
+     * Native App, so this is informational only. Responses always carry the key,
+     * with an explicit `null` when there is no region.
      */
-    region?: DataPlaneRegion;
+    region?: DataPlaneRegion | null;
 }
 /** Platform details returned for a data plane the calling company owns. */
 export type DataPlanePlatform = AwsPlatform | SnowflakePlatform;
@@ -51,7 +52,8 @@ export interface AwsSharedPlatform {
 }
 export interface SnowflakeSharedPlatform {
     type: "platform_shared_snowflake";
-    region?: DataPlaneRegion;
+    /** Nullable for the same reason as {@link SnowflakePlatform.region}. */
+    region?: DataPlaneRegion | null;
 }
 /**
  * Platform details returned for a data plane shared with you. Account
@@ -84,11 +86,21 @@ export interface DataPlaneOwnedResponse {
     status: DataPlaneStatus;
     updated_at: string;
     collaborators: DataPlaneCollaborators;
+    /**
+     * Always present, empty when the plane has no pools: the backend field is a
+     * plain `List`, never an `Option`.
+     */
     compute_pools: ComputePoolResponse[];
-    description?: string;
-    tags?: string[];
-    last_heartbeat_at?: string;
-    default_compute_pool_id?: string;
+    /**
+     * The response encoder does not drop nulls, so each of these four arrives as
+     * an explicit `null` when absent rather than being left out. `tags` is `null`
+     * for a plane with no tags too — `DataPlaneResponse.apply` maps an empty list
+     * to `None` — though a directly constructed response can still send `[]`.
+     */
+    description?: string | null;
+    tags?: string[] | null;
+    last_heartbeat_at?: string | null;
+    default_compute_pool_id?: string | null;
 }
 /**
  * A data plane shared with the calling company. Omits details like the external
@@ -104,11 +116,13 @@ export interface DataPlaneSharedResponse {
     platform: DataPlaneSharedPlatform;
     status: DataPlaneStatus;
     updated_at: string;
+    /** Required for the same reason as {@link DataPlaneOwnedResponse.compute_pools}. */
     compute_pools: ComputePoolResponse[];
-    description?: string;
-    tags?: string[];
-    last_heartbeat_at?: string;
-    default_compute_pool_id?: string;
+    /** Nullable for the same reason as on {@link DataPlaneOwnedResponse}. */
+    description?: string | null;
+    tags?: string[] | null;
+    last_heartbeat_at?: string | null;
+    default_compute_pool_id?: string | null;
 }
 /** Discriminated union of the owned/shared data plane response shapes. */
 export type DataPlane = DataPlaneOwnedResponse | DataPlaneSharedResponse;

package/build/generated/api-types.d.ts

@@ -2,7 +2,7 @@
  * GENERATED FILE — DO NOT EDIT.
  *
  * Source: https://docs-cdn.narrative.io/api-reference/main/openapi.json
- * Spec etag: W/"2579229b75ddefef951659560f71d465"
+ * Spec etag: W/"1b05b0fe6188a5d59c67bbde3678af08"
  *
  * Regenerate with: bun run generate:api-types
  */
@@ -24249,15 +24249,54 @@ export interface components {
             provider?: components["schemas"]["Provider"];
             collaborators?: components["schemas"]["ComputePoolCollaborators"];
         };
+        AwsRegion: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "region_aws";
+            /** @description AWS region identifier, e.g. `us-east-1`. */
+            id: string;
+        };
         AwsPlatform: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "platform_aws";
-            region: string;
+            /** @description The 12-digit AWS account ID of the account hosting the data plane. */
+            account_id: string;
+            region: components["schemas"]["AwsRegion"];
         };
+        AzureRegion: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "region_azure";
+            /** @description Azure region identifier, e.g. `uaenorth`. */
+            id: string;
+        };
+        GcpRegion: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "region_gcp";
+            /** @description GCP region identifier, e.g. `us-east4`. */
+            id: string;
+        };
+        Region: components["schemas"]["AwsRegion"] | components["schemas"]["AzureRegion"] | components["schemas"]["GcpRegion"];
         SnowflakePlatform: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "platform_snowflake";
-            region?: string;
+            account_locator: string;
+            account_name: string;
+            organization_name: string;
+            region?: components["schemas"]["Region"] | null;
         };
         Platform: components["schemas"]["AwsPlatform"] | components["schemas"]["SnowflakePlatform"];
         "data-plane-collaborators_ParticipantsAll": {
@@ -24274,7 +24313,7 @@ export interface components {
              */
             type: "none";
         };
-        "data-plane-collaborators_CompanyId": string;
+        "data-plane-collaborators_CompanyId": number;
         "data-plane-collaborators_ParticipantsInclusion": {
             /**
              * @description discriminator enum property added by openapi-typescript
@@ -24297,60 +24336,73 @@ export interface components {
             manage_compute_pools: components["schemas"]["DataPlaneParticipants"];
         };
         DataPlaneOwnedResponse: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "owned";
             /** Format: uuid */
             id: string;
             company_id: number;
             /** Format: date-time */
             created_at: string;
-            description?: string;
+            description?: string | null;
             display_name: string;
             external_id: string;
             platform: components["schemas"]["Platform"];
             /** @enum {string} */
             status: "active" | "archived";
             /** Format: date-time */
-            last_heartbeat_at?: string;
-            tags?: string[];
+            last_heartbeat_at?: string | null;
+            tags?: string[] | null;
             /** Format: date-time */
             updated_at: string;
             collaborators: components["schemas"]["DataPlaneCollaborators"];
             /** Format: uuid */
-            default_compute_pool_id?: string;
-            compute_pools?: components["schemas"]["ComputePoolResponse"][];
+            default_compute_pool_id?: string | null;
+            compute_pools: components["schemas"]["ComputePoolResponse"][];
         };
         AwsSharedResponse: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "platform_shared_aws";
-            region: string;
+            region: components["schemas"]["AwsRegion"];
         };
         SnowflakeSharedResponse: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "platform_shared_snowflake";
-            region?: string;
+            region?: components["schemas"]["Region"] | null;
         };
         PlatformSharedResponse: components["schemas"]["AwsSharedResponse"] | components["schemas"]["SnowflakeSharedResponse"];
         DataPlaneSharedResponse: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "shared";
+            /** Format: uuid */
             id: string;
-            company_id: string;
+            company_id: number;
             /** Format: date-time */
             created_at: string;
-            description?: string;
+            description?: string | null;
             display_name: string;
             platform: components["schemas"]["PlatformSharedResponse"];
             /** @enum {string} */
             status: "active" | "archived";
             /** Format: date-time */
-            last_heartbeat_at?: string;
-            tags?: string[];
+            last_heartbeat_at?: string | null;
+            tags?: string[] | null;
             /** Format: date-time */
             updated_at: string;
             /** Format: uuid */
-            default_compute_pool_id?: string;
-            compute_pools?: components["schemas"]["ComputePoolResponse"][];
+            default_compute_pool_id?: string | null;
+            compute_pools: components["schemas"]["ComputePoolResponse"][];
         };
         DataPlaneResponse: components["schemas"]["DataPlaneOwnedResponse"] | components["schemas"]["DataPlaneSharedResponse"];
         GetDataPlanesResponse: {

package/build/generated/api-types.js

@@ -2,7 +2,7 @@
  * GENERATED FILE — DO NOT EDIT.
  *
  * Source: https://docs-cdn.narrative.io/api-reference/main/openapi.json
- * Spec etag: W/"2579229b75ddefef951659560f71d465"
+ * Spec etag: W/"1b05b0fe6188a5d59c67bbde3678af08"
  *
  * Regenerate with: bun run generate:api-types
  */

package/build/testing/fixtures/data-planes.d.ts

@@ -1,8 +1,25 @@
-import type { DataPlaneOwnedResponse, JobResponse } from "../types";
+import type { DataPlaneOwnedResponse, DataPlaneSharedResponse, JobResponse } from "../types";
 /**
  * An owned, active data plane. Every field the spec requires is filled in, so a
- * caller only overrides what its assertion is about.
+ * caller only overrides what its assertion is about. The optional fields are
+ * present and `null`, which is what the API sends for an absent value — a mock
+ * that omitted them would let a consumer assert `undefined` and still pass.
  */
-export declare function createDataPlane(overrides?: Partial<DataPlaneOwnedResponse>): DataPlaneOwnedResponse;
+export declare function createOwnedDataPlane(overrides?: Partial<DataPlaneOwnedResponse>): DataPlaneOwnedResponse;
+/**
+ * A data plane shared with the calling company, active, on AWS. Shared planes
+ * belong to someone else, so this one carries a different `company_id` and id
+ * than {@link createOwnedDataPlane} — seeding both gives you two records.
+ *
+ * Optional fields are present and `null` for the same reason as on the owned
+ * factory. For the other platform the API serves, override it:
+ *
+ * ```ts
+ * createSharedDataPlane({
+ *   platform: { type: "platform_shared_snowflake", region: null },
+ * });
+ * ```
+ */
+export declare function createSharedDataPlane(overrides?: Partial<DataPlaneSharedResponse>): DataPlaneSharedResponse;
 /** The job a health check enqueues, pending and not yet attempted. */
 export declare function createHealthCheckJob(overrides?: Partial<JobResponse>): JobResponse;

package/build/testing/fixtures/data-planes.js

@@ -1,9 +1,11 @@
 const TIMESTAMP = "2026-01-01T00:00:00Z";
 /**
  * An owned, active data plane. Every field the spec requires is filled in, so a
- * caller only overrides what its assertion is about.
+ * caller only overrides what its assertion is about. The optional fields are
+ * present and `null`, which is what the API sends for an absent value — a mock
+ * that omitted them would let a consumer assert `undefined` and still pass.
  */
-export function createDataPlane(overrides = {}) {
+export function createOwnedDataPlane(overrides = {}) {
     return {
         type: "owned",
         id: "5f9d1a4e-0000-4000-8000-000000000001",
@@ -11,13 +13,57 @@ export function createDataPlane(overrides = {}) {
         created_at: TIMESTAMP,
         display_name: "Test Data Plane",
         external_id: "test-data-plane",
-        platform: { type: "platform_aws", region: "us-east-1" },
+        platform: {
+            type: "platform_aws",
+            account_id: "123456789000",
+            region: { type: "region_aws", id: "us-east-1" },
+        },
         status: "active",
         updated_at: TIMESTAMP,
         collaborators: {
             participants: { type: "none" },
             manage_compute_pools: { type: "none" },
         },
+        compute_pools: [],
+        description: null,
+        tags: null,
+        last_heartbeat_at: null,
+        default_compute_pool_id: null,
+        ...overrides,
+    };
+}
+/**
+ * A data plane shared with the calling company, active, on AWS. Shared planes
+ * belong to someone else, so this one carries a different `company_id` and id
+ * than {@link createOwnedDataPlane} — seeding both gives you two records.
+ *
+ * Optional fields are present and `null` for the same reason as on the owned
+ * factory. For the other platform the API serves, override it:
+ *
+ * ```ts
+ * createSharedDataPlane({
+ *   platform: { type: "platform_shared_snowflake", region: null },
+ * });
+ * ```
+ */
+export function createSharedDataPlane(overrides = {}) {
+    return {
+        type: "shared",
+        id: "5f9d1a4e-0000-4000-8000-000000000002",
+        company_id: 2,
+        created_at: TIMESTAMP,
+        display_name: "Test Shared Data Plane",
+        platform: {
+            type: "platform_shared_aws",
+            region: { type: "region_aws", id: "us-east-1" },
+        },
+        status: "active",
+        updated_at: TIMESTAMP,
+        compute_pools: [],
+        description: null,
+        tags: null,
+        last_heartbeat_at: null,
+        default_compute_pool_id: null,
         ...overrides,
     };
 }

package/build/testing/fixtures/index.d.ts

@@ -1 +1 @@
-export { createDataPlane, createHealthCheckJob } from "./data-planes";
+export { createHealthCheckJob, createOwnedDataPlane, createSharedDataPlane, } from "./data-planes";

package/build/testing/fixtures/index.js

@@ -1 +1 @@
-export { createDataPlane, createHealthCheckJob } from "./data-planes";
+export { createHealthCheckJob, createOwnedDataPlane, createSharedDataPlane, } from "./data-planes";

package/build/testing/handlers/data-planes.js

@@ -1,5 +1,5 @@
 import { rejectUnauthenticated } from "../auth";
-import { createDataPlane, createHealthCheckJob } from "../fixtures/data-planes";
+import { createHealthCheckJob, createOwnedDataPlane, } from "../fixtures/data-planes";
 /**
  * Records live for the lifetime of one `createHandlers()` call, so each test
  * suite gets its own copy and writes from one test can't leak into another.
@@ -16,7 +16,7 @@ function findOwned(store, id) {
     const record = store.find(id);
     return record?.type === "owned" ? record : undefined;
 }
-export function createDataPlaneHandlers(http, auth, seed = [createDataPlane()]) {
+export function createDataPlaneHandlers(http, auth, seed = [createOwnedDataPlane()]) {
     const store = createStore(seed);
     return [
         http.get("/data-planes", ({ request, cookies, response }) => {
@@ -49,7 +49,9 @@ export function createDataPlaneHandlers(http, auth, seed = [createDataPlane()])
             const record = findOwned(store, params.data_plane_id);
             if (!record)
                 return response(404).empty();
-            record.default_compute_pool_id = undefined;
+            // null, not undefined: the encoder emits the key with an explicit
+            // null, and JSON.stringify would drop an undefined one entirely.
+            record.default_compute_pool_id = null;
             return response(200).json(record);
         }),
         http.post("/data-planes/{data_plane_id}/health-check", async ({ params, request, cookies, response }) => {

package/build/testing/index.d.ts

@@ -7,12 +7,20 @@
  *
  * ```ts
  * import { setupServer } from "msw/node";
- * import { createHandlers, createDataPlane } from "@narrative.io/data-collaboration-sdk-ts/testing";
+ * import {
+ * 	createHandlers,
+ * 	createOwnedDataPlane,
+ * 	createSharedDataPlane,
+ * } from "@narrative.io/data-collaboration-sdk-ts/testing";
  *
- * const server = setupServer(...createHandlers({ dataPlanes: [createDataPlane()] }));
+ * const server = setupServer(
+ * 	...createHandlers({
+ * 		dataPlanes: [createOwnedDataPlane(), createSharedDataPlane()],
+ * 	}),
+ * );
  * ```
  */
-export { createDataPlane, createHealthCheckJob } from "./fixtures";
+export { createHealthCheckJob, createOwnedDataPlane, createSharedDataPlane, } from "./fixtures";
 export { createHandlers } from "./handlers";
 export { createDataPlaneHandlers } from "./handlers/data-planes";
-export type { AuthGuard, AuthGuardContext, CreateHandlersOptions, DataPlaneOwnedResponse, DataPlaneResponse, JobResponse, } from "./types";
+export type { AuthGuard, AuthGuardContext, CreateHandlersOptions, DataPlaneOwnedResponse, DataPlanePlatform, DataPlaneResponse, DataPlaneSharedPlatform, DataPlaneSharedResponse, JobResponse, } from "./types";

package/build/testing/index.js

@@ -7,11 +7,19 @@
  *
  * ```ts
  * import { setupServer } from "msw/node";
- * import { createHandlers, createDataPlane } from "@narrative.io/data-collaboration-sdk-ts/testing";
+ * import {
+ * 	createHandlers,
+ * 	createOwnedDataPlane,
+ * 	createSharedDataPlane,
+ * } from "@narrative.io/data-collaboration-sdk-ts/testing";
  *
- * const server = setupServer(...createHandlers({ dataPlanes: [createDataPlane()] }));
+ * const server = setupServer(
+ * 	...createHandlers({
+ * 		dataPlanes: [createOwnedDataPlane(), createSharedDataPlane()],
+ * 	}),
+ * );
  * ```
  */
-export { createDataPlane, createHealthCheckJob } from "./fixtures";
+export { createHealthCheckJob, createOwnedDataPlane, createSharedDataPlane, } from "./fixtures";
 export { createHandlers } from "./handlers";
 export { createDataPlaneHandlers } from "./handlers/data-planes";

package/build/testing/types.d.ts

@@ -1,8 +1,34 @@
 import type { components } from "../generated/api-types";
 /** A data plane as the API returns it, owned or shared. */
 export type DataPlaneResponse = components["schemas"]["DataPlaneResponse"];
-/** A data plane this company owns. Only owned planes have a default compute pool. */
+/**
+ * A data plane this company owns. Only owned planes carry an external id and
+ * collaborators, and only they accept the default-compute-pool endpoints.
+ */
 export type DataPlaneOwnedResponse = components["schemas"]["DataPlaneOwnedResponse"];
+/**
+ * A data plane shared with this company. Same shape as the owned variant minus
+ * `external_id` and `collaborators`, and its platform is one of the
+ * `platform_shared_*` types rather than the owned ones.
+ */
+export type DataPlaneSharedResponse = components["schemas"]["DataPlaneSharedResponse"];
+/**
+ * The platform an owned data plane runs on — AWS or Snowflake.
+ *
+ * Both factories default to AWS, so a test that needs another variant passes
+ * this as a `platform` override. Named after the root entry point's
+ * `DataPlanePlatform` rather than the generated schema's bare `Platform`, so
+ * the two entry points read the same way — the two are assignable in both
+ * directions.
+ */
+export type DataPlanePlatform = components["schemas"]["Platform"];
+/**
+ * The platform a shared data plane runs on. Distinct from
+ * {@link DataPlanePlatform}: the discriminators are the `platform_shared_*`
+ * ones, and `region` is required on the AWS variant but optional and nullable
+ * on the Snowflake one.
+ */
+export type DataPlaneSharedPlatform = components["schemas"]["PlatformSharedResponse"];
 /** A job as the API returns it, including the one a health check enqueues. */
 export type JobResponse = components["schemas"]["JobResponse"];
 export interface AuthGuardContext {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "4.3.0",
+	"version": "4.4.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",