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

package/build/base-api.d.ts

@@ -86,6 +86,17 @@ export declare abstract class BaseApi {
      * @returns A Promise that resolves to the data returned by the server.
      */
     protected put<I, T>(endpoint: string, data: I): Promise<T>;
+    /**
+     * Makes a PATCH request to the specified endpoint with the given data.
+     *
+     * Unlike {@link BaseApi.put}, a PATCH body carries only the fields being
+     * changed — the endpoints that accept one leave everything else as it is.
+     *
+     * @param endpoint - The endpoint to make the request to.
+     * @param data - The fields to change.
+     * @returns A Promise that resolves to the data returned by the server.
+     */
+    protected patch<I, T>(endpoint: string, data: I): Promise<T>;
     /**
      * Returns the base URL for the API based on the environment.
      *

package/build/base-api.js

@@ -137,6 +137,21 @@ export class BaseApi {
             console.log(`Making GET request to ${endpoint} with data: ${JSON.stringify(data)}...`);
         return await this.base_api.put(endpoint, data);
     }
+    /**
+     * Makes a PATCH request to the specified endpoint with the given data.
+     *
+     * Unlike {@link BaseApi.put}, a PATCH body carries only the fields being
+     * changed — the endpoints that accept one leave everything else as it is.
+     *
+     * @param endpoint - The endpoint to make the request to.
+     * @param data - The fields to change.
+     * @returns A Promise that resolves to the data returned by the server.
+     */
+    async patch(endpoint, data) {
+        if (this.verbose)
+            console.log(`Making PATCH request to ${endpoint} with data: ${JSON.stringify(data)}...`);
+        return await this.base_api.patch(endpoint, data);
+    }
     /**
      * Returns the base URL for the API based on the environment.
      *

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

@@ -1,136 +1,73 @@
-import type { ComputePoolResponse, Participants } from "../compute-pools/types";
+import type { components } from "../generated/api-types";
 import type { Job } from "../jobs/types";
-/** Discriminator distinguishing an owned data plane from one shared with you. */
-export type DataPlaneType = "owned" | "shared";
 /**
- * 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).
+ * Discriminator distinguishing a data plane the calling company owns from one
+ * shared with it.
  */
-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 AzureRegion {
-    type: "region_azure";
-    id: string;
-}
-export interface GcpRegion {
-    type: "region_gcp";
-    id: string;
-}
+export type DataPlaneType = DataPlane["type"];
+/** Lifecycle status of a data plane. */
+export type DataPlaneStatus = DataPlane["status"];
+export type AwsRegion = components["schemas"]["AwsRegion"];
+export type AzureRegion = components["schemas"]["AzureRegion"];
+export type GcpRegion = components["schemas"]["GcpRegion"];
 /**
- * The region a data plane runs in. Encoded as a discriminated object, not a
- * bare string — see `DataPlane.Region` in `datashops-protocol`.
+ * The region a data plane runs in. A discriminated object rather than the bare
+ * region code a caller might expect: `{ type: "region_aws", id: "us-east-1" }`.
  */
-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;
-    /**
-     * 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 | null;
-}
+export type DataPlaneRegion = components["schemas"]["Region"];
+export type AwsPlatform = components["schemas"]["AwsPlatform"];
+/**
+ * Snowflake platform details for a data plane the calling company owns.
+ *
+ * `region` is informational. Provisioning the Snowflake Native App can fail to
+ * parse a region, and the response then carries an explicit `null` rather than
+ * omitting the key.
+ */
+export type SnowflakePlatform = components["schemas"]["SnowflakePlatform"];
 /** 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";
-    /** Nullable for the same reason as {@link SnowflakePlatform.region}. */
-    region?: DataPlaneRegion | null;
-}
+export type DataPlanePlatform = components["schemas"]["Platform"];
+export type AwsSharedPlatform = components["schemas"]["AwsSharedResponse"];
+/** `region` is informational for the same reason as on {@link SnowflakePlatform}. */
+export type SnowflakeSharedPlatform = components["schemas"]["SnowflakeSharedResponse"];
 /**
- * Platform details returned for a data plane shared with you. Account
- * identifiers are omitted for non-owned data planes.
+ * Platform details returned for a data plane shared with the calling company.
+ * Account identifiers are omitted for planes the company does not own.
  */
-export type DataPlaneSharedPlatform = AwsSharedPlatform | SnowflakeSharedPlatform;
+export type DataPlaneSharedPlatform = components["schemas"]["PlatformSharedResponse"];
 /**
- * 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.
+ * 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 type DataPlaneCollaborators = components["schemas"]["DataPlaneCollaborators"];
 /**
- * A data plane owned by the calling company. Includes full details such as the
+ * A data plane the calling company owns. Includes full details such as the
  * external id and collaborators.
+ *
+ * `compute_pools` is always present, and empty when the plane has no pools.
+ * `description`, `tags`, `last_heartbeat_at` and `default_compute_pool_id` arrive
+ * as an explicit `null` when absent rather than being omitted, so a consumer that
+ * checks for `undefined` will not see one. A plane with no tags sends
+ * `tags: null` rather than `[]`.
  */
-export interface DataPlaneOwnedResponse {
-    type: "owned";
-    /** UUID. */
-    id: string;
-    company_id: number;
-    created_at: string;
-    display_name: string;
-    external_id: string;
-    platform: DataPlanePlatform;
-    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[];
-    /**
-     * 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;
-}
+export type DataPlaneOwnedResponse = components["schemas"]["DataPlaneOwnedResponse"];
 /**
  * A data plane shared with the calling company. Omits details like the external
- * id and collaborators that are only exposed to the owner.
+ * id and collaborators that are only exposed to the owner. `compute_pools` and
+ * the four nullable fields behave as they do on {@link DataPlaneOwnedResponse}.
  */
-export interface DataPlaneSharedResponse {
-    type: "shared";
-    /** UUID. */
-    id: string;
-    company_id: number;
-    created_at: string;
-    display_name: string;
-    platform: DataPlaneSharedPlatform;
-    status: DataPlaneStatus;
-    updated_at: string;
-    /** Required for the same reason as {@link DataPlaneOwnedResponse.compute_pools}. */
-    compute_pools: ComputePoolResponse[];
-    /** 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;
-}
+export type DataPlaneSharedResponse = components["schemas"]["DataPlaneSharedResponse"];
 /** Discriminated union of the owned/shared data plane response shapes. */
-export type DataPlane = DataPlaneOwnedResponse | DataPlaneSharedResponse;
-export interface HealthCheckRequest {
-    compute_pool_id?: string;
-}
+export type DataPlane = components["schemas"]["DataPlaneResponse"];
+export type HealthCheckRequest = components["schemas"]["EnqueueHealthCheckRequest"];
 /**
- * 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`.
+ * The backend enqueues a `health_check` job and returns the full job record (201
+ * Created), not just its id.
+ *
+ * This one name stays on the SDK's own {@link Job} rather than the spec's
+ * `JobResponse`. The spec types a job's `type` as an open string with opaque
+ * `input` and `result`, while `Job` is a discriminated union over the known job
+ * types that `isKnownJob` narrows.
  */
 export type HealthCheckJobResponse = Job;

package/build/derivations/index.d.ts

@@ -0,0 +1,84 @@
+import { BaseApi } from "../base-api";
+import type { Derivation, DerivationCollaborators, DerivationCost, DerivationCreateRequest, DerivationMapping, DerivationsResponse, DerivationUpdateRequest, DerivationWarning, ListDerivationsParams } from "./types";
+/**
+ * `DerivationsApi` wraps the derivation-rule endpoints. A derivation rule says
+ * how one attribute's value can be produced from another's — hashing a raw
+ * email, bucketing a birthdate into an age range — and the platform applies it
+ * when a query asks for the target attribute and only the source is available.
+ *
+ * Reads cover the rules the calling company can use: the ones it owns plus the
+ * ones shared with it through collaborators. Writes are narrower — they need an
+ * `admin` grant on `attribute_derivations`, and only the owning company can
+ * change or delete a rule.
+ */
+export declare class DerivationsApi extends BaseApi {
+    /**
+     * Lists the derivation rules the calling company can use, optionally
+     * filtered by source or target attribute.
+     *
+     * @param {ListDerivationsParams} [params] - Attribute-id filters. Each accepts
+     * several ids.
+     * @returns {Promise<DerivationsResponse>} The matching rules, with empty
+     * `warnings` — reads do not compute them.
+     * @see https://docs.narrative.io/api-reference/derivations/get-derivation-rules
+     */
+    listDerivations(params?: ListDerivationsParams): Promise<DerivationsResponse>;
+    /**
+     * Fetches a single rule.
+     *
+     * @param {number} derivationId - Id of the rule.
+     * @returns {Promise<Derivation>} The rule. Rejects with 404 if no rule with
+     * that id is usable by the calling company — rules belonging to someone else
+     * are not distinguished from rules that do not exist.
+     * @see https://docs.narrative.io/api-reference/derivations/get-a-derivation-rule
+     */
+    getDerivation(derivationId: number): Promise<Derivation>;
+    /**
+     * Creates a rule, owned by the calling company.
+     *
+     * The transformation is validated before the rule can exist: both attributes
+     * must be viewable, the target must grant the company `map` since the rule
+     * produces values for it, every expression must parse and type-check against
+     * the source attribute's shape, and the result must match the target's
+     * declared type.
+     *
+     * A rule that closes a cycle in the derivation graph is still created — the
+     * cycle comes back as a `cyclic_derivation` warning on the response rather
+     * than as an error.
+     *
+     * @param {DerivationCreateRequest} request - The rule to create.
+     * @returns {Promise<Derivation>} The created rule, with any warnings. Rejects
+     * with 400 if the transformation fails validation; 403 if the caller is not
+     * an admin, the rule's company or collaborators are not allowed, or the
+     * target attribute does not grant `map`; 409 if another of the company's
+     * rules already has the same name or already covers the same source and
+     * target pair.
+     * @see https://docs.narrative.io/api-reference/derivations/create-a-derivation-rule
+     */
+    createDerivation(request: DerivationCreateRequest): Promise<Derivation>;
+    /**
+     * Updates some fields of a rule. Only the keys present in `request` change,
+     * and a changed `mapping` runs the same validation as a creation.
+     *
+     * @param {number} derivationId - Id of the rule.
+     * @param {DerivationUpdateRequest} request - The fields to change.
+     * @returns {Promise<Derivation>} The updated rule, with any warnings. Rejects
+     * with 400 if the update fails validation; 403 if the caller is not an admin
+     * or does not own the rule; 404 if there is no rule with that id.
+     * @see https://docs.narrative.io/api-reference/derivations/update-a-derivation-rule
+     */
+    updateDerivation(derivationId: number, request: DerivationUpdateRequest): Promise<Derivation>;
+    /**
+     * Permanently removes a rule. To take a rule out of use while keeping it,
+     * pass `{ active: false }` to {@link DerivationsApi.updateDerivation}
+     * instead — deletions cannot be undone.
+     *
+     * @param {number} derivationId - Id of the rule.
+     * @returns {Promise<void>} Resolves when deleted. Rejects with 403 if the
+     * caller is not an admin or does not own the rule; 404 if there is no rule
+     * with that id.
+     * @see https://docs.narrative.io/api-reference/derivations/delete-a-derivation-rule
+     */
+    deleteDerivation(derivationId: number): Promise<void>;
+}
+export type { Derivation, DerivationCollaborators, DerivationCost, DerivationCreateRequest, DerivationMapping, DerivationsResponse, DerivationUpdateRequest, DerivationWarning, ListDerivationsParams, };

package/build/derivations/index.js

@@ -0,0 +1,93 @@
+import { BaseApi } from "../base-api";
+const resourceName = "derivations";
+/**
+ * `DerivationsApi` wraps the derivation-rule endpoints. A derivation rule says
+ * how one attribute's value can be produced from another's — hashing a raw
+ * email, bucketing a birthdate into an age range — and the platform applies it
+ * when a query asks for the target attribute and only the source is available.
+ *
+ * Reads cover the rules the calling company can use: the ones it owns plus the
+ * ones shared with it through collaborators. Writes are narrower — they need an
+ * `admin` grant on `attribute_derivations`, and only the owning company can
+ * change or delete a rule.
+ */
+export class DerivationsApi extends BaseApi {
+    /**
+     * Lists the derivation rules the calling company can use, optionally
+     * filtered by source or target attribute.
+     *
+     * @param {ListDerivationsParams} [params] - Attribute-id filters. Each accepts
+     * several ids.
+     * @returns {Promise<DerivationsResponse>} The matching rules, with empty
+     * `warnings` — reads do not compute them.
+     * @see https://docs.narrative.io/api-reference/derivations/get-derivation-rules
+     */
+    async listDerivations(params) {
+        return await this.get(resourceName, params);
+    }
+    /**
+     * Fetches a single rule.
+     *
+     * @param {number} derivationId - Id of the rule.
+     * @returns {Promise<Derivation>} The rule. Rejects with 404 if no rule with
+     * that id is usable by the calling company — rules belonging to someone else
+     * are not distinguished from rules that do not exist.
+     * @see https://docs.narrative.io/api-reference/derivations/get-a-derivation-rule
+     */
+    async getDerivation(derivationId) {
+        return await this.get(`${resourceName}/${derivationId}`);
+    }
+    /**
+     * Creates a rule, owned by the calling company.
+     *
+     * The transformation is validated before the rule can exist: both attributes
+     * must be viewable, the target must grant the company `map` since the rule
+     * produces values for it, every expression must parse and type-check against
+     * the source attribute's shape, and the result must match the target's
+     * declared type.
+     *
+     * A rule that closes a cycle in the derivation graph is still created — the
+     * cycle comes back as a `cyclic_derivation` warning on the response rather
+     * than as an error.
+     *
+     * @param {DerivationCreateRequest} request - The rule to create.
+     * @returns {Promise<Derivation>} The created rule, with any warnings. Rejects
+     * with 400 if the transformation fails validation; 403 if the caller is not
+     * an admin, the rule's company or collaborators are not allowed, or the
+     * target attribute does not grant `map`; 409 if another of the company's
+     * rules already has the same name or already covers the same source and
+     * target pair.
+     * @see https://docs.narrative.io/api-reference/derivations/create-a-derivation-rule
+     */
+    async createDerivation(request) {
+        return await this.post(resourceName, request);
+    }
+    /**
+     * Updates some fields of a rule. Only the keys present in `request` change,
+     * and a changed `mapping` runs the same validation as a creation.
+     *
+     * @param {number} derivationId - Id of the rule.
+     * @param {DerivationUpdateRequest} request - The fields to change.
+     * @returns {Promise<Derivation>} The updated rule, with any warnings. Rejects
+     * with 400 if the update fails validation; 403 if the caller is not an admin
+     * or does not own the rule; 404 if there is no rule with that id.
+     * @see https://docs.narrative.io/api-reference/derivations/update-a-derivation-rule
+     */
+    async updateDerivation(derivationId, request) {
+        return await this.patch(`${resourceName}/${derivationId}`, request);
+    }
+    /**
+     * Permanently removes a rule. To take a rule out of use while keeping it,
+     * pass `{ active: false }` to {@link DerivationsApi.updateDerivation}
+     * instead — deletions cannot be undone.
+     *
+     * @param {number} derivationId - Id of the rule.
+     * @returns {Promise<void>} Resolves when deleted. Rejects with 403 if the
+     * caller is not an admin or does not own the rule; 404 if there is no rule
+     * with that id.
+     * @see https://docs.narrative.io/api-reference/derivations/delete-a-derivation-rule
+     */
+    async deleteDerivation(derivationId) {
+        await this.delete(`${resourceName}/${derivationId}`);
+    }
+}

package/build/derivations/types.d.ts

@@ -0,0 +1,56 @@
+import type { components } from "../generated/api-types";
+/**
+ * A derivation rule: a transformation that produces one attribute's value from
+ * another's, applied when a query resolves the target attribute.
+ *
+ * `warnings` is populated on create and update responses and empty on reads —
+ * list and get do not compute them. `fidelity_note` arrives as an explicit
+ * `null` when the rule has no note rather than being omitted.
+ */
+export type Derivation = components["schemas"]["DerivationResponse"];
+/** The list endpoint's envelope. */
+export type DerivationsResponse = components["schemas"]["DerivationsResponse"];
+/**
+ * Which companies besides the owner may have a rule applied to their data. A
+ * rule grants a single thing, so there is one `use` dimension. Only Narrative
+ * can share a rule with `all` companies or with everyone outside an
+ * `exclusion` set.
+ */
+export type DerivationCollaborators = components["schemas"]["DerivationCollaborators"];
+/**
+ * The transformation itself. Expressions reach the source attribute's shape
+ * through `$source` — a rule from `raw_email` to `sha256_hashed_email` maps
+ * `value` to `SHA2(NORMALIZE_EMAIL($source.value), 256)`.
+ *
+ * Same shape as a dataset mapping except that `cached_mapping` is not allowed:
+ * a cached mapping reads out of a stored dataset, so there would be nothing to
+ * substitute `$source` into.
+ */
+export type DerivationMapping = components["schemas"]["DerivationMapping"];
+/**
+ * Something worth knowing that did not stop the rule from being written. The
+ * only kind today is `cyclic_derivation`, which lists the attribute ids on the
+ * cycle the rule closes.
+ */
+export type DerivationWarning = components["schemas"]["DerivationWarning"];
+/** Breaks ties when several rules reach the same target attribute — cheapest wins. */
+export type DerivationCost = components["schemas"]["DerivationCost"];
+/** Body of `POST /derivations`. */
+export type DerivationCreateRequest = components["schemas"]["DerivationCreateRequest"];
+/**
+ * Body of `PATCH /derivations/{id}`. Only the keys present change. Sending
+ * `fidelity_note: null` clears it; leaving the key out keeps it. A rule's
+ * source and target attributes are immutable — create a new rule instead.
+ */
+export type DerivationUpdateRequest = components["schemas"]["DerivationUpdateRequest"];
+/**
+ * Filters for the list endpoint. Both accept several ids, which the client
+ * repeats in the query string (`?source_attribute_id=1&source_attribute_id=2`)
+ * — the form the route's multi-value matcher reads.
+ */
+export interface ListDerivationsParams {
+    /** Only return rules reading from these attributes. */
+    source_attribute_id?: number[];
+    /** Only return rules producing these attributes. */
+    target_attribute_id?: number[];
+}

package/build/derivations/types.js

@@ -0,0 +1 @@
+export {};