@narrative.io/data-collaboration-sdk-ts 2.100.0 → 2.101.1-beta.0

package/build/apps/index.d.ts

@@ -1,4 +1,5 @@
 import { BaseApi } from "../base-api";
+import type { JsonSchemaConnectorPolicy } from "../collaboration-policy/core/jsonschema/json-schema-types";
 import type { ApiRecords } from "../types";
 import type { App, Installation } from "./types";
 /**
@@ -14,5 +15,11 @@ declare class AppsApi extends BaseApi {
      */
     getApps(appCategory?: string): Promise<ApiRecords<App>>;
     getInstalledApps(appCategory?: string): Promise<ApiRecords<Installation>>;
+    /**
+     * Get all interfaces for the current user's installed connectors.
+     * @param {string[]} [tags] - Optional tags to filter interfaces (e.g. ["audience_delivery"]).
+     * @returns {Promise<ApiRecords<JsonSchemaConnectorPolicy>>} - Promise resolving with the list of interfaces.
+     */
+    getInstalledInterfaces(tags?: string[]): Promise<ApiRecords<JsonSchemaConnectorPolicy>>;
 }
 export { type App, AppsApi, type Installation };

package/build/apps/index.js

@@ -21,5 +21,14 @@ class AppsApi extends BaseApi {
         const url = `installations${appCategoryQuery}`;
         return await this.get(url);
     }
+    /**
+     * Get all interfaces for the current user's installed connectors.
+     * @param {string[]} [tags] - Optional tags to filter interfaces (e.g. ["audience_delivery"]).
+     * @returns {Promise<ApiRecords<JsonSchemaConnectorPolicy>>} - Promise resolving with the list of interfaces.
+     */
+    async getInstalledInterfaces(tags) {
+        const queryString = this.constructQueryString(tags != null ? { tags } : undefined);
+        return await this.get(`${resourceName}/installed/interfaces${queryString}`);
+    }
 }
 export { AppsApi };

package/build/collaboration-policy/core/filter-builder.js

@@ -1,6 +1,12 @@
 import { normalizePathValue } from "../utils/path-helpers";
 import { resolveAttributeExpression } from "../utils/sql-helpers";
-import { isAttributeReference } from "./filter-utils";
+function isAttributeReference(node) {
+    return (!!node &&
+        typeof node === "object" &&
+        "type" in node &&
+        node.type === "attribute" &&
+        "attribute_name" in node);
+}
 export function filterToSql(filter, attributeByName, datasetName) {
     const op = filter.op.toLowerCase();
     switch (op) {

package/build/collaboration-policy/core/jsonschema/json-schema-types.d.ts

@@ -0,0 +1,45 @@
+import type { JSONSchema7 } from "json-schema";
+/**
+ * Base JSON Schema type used for connector policies.
+ *
+ * Uses JSONSchema7 as a structural base. The real API schemas declare
+ * `$schema: "https://json-schema.org/draft/2020-12/schema"` and are
+ * validated with AJV 2020-12.
+ */
+export type JsonSchema = JSONSchema7;
+/**
+ * Shape of a JSON-Schema-based connector policy as returned by the backend API.
+ *
+ * The `policy` field is a JSON Schema document that must be satisfied
+ * by `dataset.schema`. Refresh schedule lives in `metadata.refresh_schedule.max`.
+ *
+ * Filters live on property definitions inside the schema (as `filters` arrays
+ * on individual attribute entries), not on anyOf branches.
+ */
+export interface JsonSchemaConnectorPolicy {
+    /** Stable identifier (e.g., "audience_first_party_new"). */
+    name: string;
+    /** Policy ID, typically matches name. */
+    id: string;
+    /** The app this policy belongs to. */
+    app_id: number;
+    /** Metadata including tags and refresh schedule. */
+    metadata: {
+        tags?: string[];
+        refresh_schedule?: {
+            min: string | null;
+            max: string;
+        };
+    };
+    /**
+     * The JSON Schema that must be satisfied by dataset.schema.
+     * Contains `properties`, `required`, `anyOf`/`allOf` for branch structure.
+     * Filters are on property definitions (sibling `properties` next to `anyOf`).
+     * May declare `$schema: "https://json-schema.org/draft/2020-12/schema"`.
+     */
+    policy: JsonSchema;
+    /** UI form schema — not used by the SDK. */
+    schema?: unknown;
+    /** UI schema — not used by the SDK. */
+    uischema?: unknown;
+}

package/build/collaboration-policy/core/jsonschema/json-schema-types.js

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

package/build/collaboration-policy/core/jsonschema/policy-branches.d.ts

@@ -0,0 +1,49 @@
+import type { PolicyFilter } from "../types";
+import type { JsonSchemaConnectorPolicy } from "./json-schema-types";
+/**
+ * A single logical branch within a JSON-Schema policy that matched the dataset.
+ * Typically corresponds to one entry in schema.properties.properties.anyOf[*],
+ * or an allOf group inside one of those entries.
+ */
+export interface PolicyBranchMatch {
+    /**
+     * Index into the top-level anyOf array under the policy's
+     * `policy.properties.properties.anyOf`.
+     */
+    branchIndex: number;
+    /**
+     * Required attribute names for this branch. These correspond to Schema.properties keys
+     * like "sha256_hashed_email", "postal_code", etc.
+     */
+    requiredAttributes: string[];
+    /**
+     * Filters collected from the property definitions for this branch's required attributes.
+     * Filters live on the property definitions (sibling `properties` to `anyOf`), not on branches.
+     * These follow the existing PolicyFilter structure and can be fed directly into filterToSql.
+     */
+    filters: PolicyFilter[];
+    /**
+     * Additional required subfield paths per attribute, used to generate IS NOT NULL WHERE clauses.
+     * Derived from `$ref` resolution against `$defs` in the JSON Schema.
+     *
+     * Example: for `sha256_hashed_phone_number` referencing an object-type `$def`,
+     * this produces `(company_data."ds"."_rosetta_stone"."sha256_hashed_phone_number"."type" IS NOT NULL)`.
+     */
+    additionalRequiredProperties: Array<{
+        attributeName: string;
+        paths: string[];
+    }>;
+}
+/**
+ * Evaluation result for a single JSON-Schema-based policy.
+ */
+export interface PolicyEvaluation {
+    /** The policy that was evaluated. */
+    policy: JsonSchemaConnectorPolicy;
+    /** Whether dataset.schema is compatible with the policy's JSON Schema. */
+    isValid: boolean;
+    /** Branches within the policy that are satisfied for this dataset. */
+    matches: PolicyBranchMatch[];
+    /** Human-readable validation issues if isValid === false. */
+    errors: string[];
+}

package/build/collaboration-policy/core/jsonschema/policy-branches.js

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

package/build/collaboration-policy/core/jsonschema/policy-evaluator.d.ts

@@ -0,0 +1,22 @@
+import type { Attribute } from "../../../attributes/types";
+import type { Dataset } from "../../../datasets/types";
+import type { JsonSchemaConnectorPolicy } from "./json-schema-types";
+import type { PolicyEvaluation } from "./policy-branches";
+/**
+ * Evaluate an array of JSON-Schema-based connector policies against a dataset.
+ *
+ * Eligibility is determined by checking whether the dataset's Rosetta Stone
+ * attributes satisfy at least one anyOf branch in the policy schema. This uses
+ * the `attributes` array (resolved from dataset mappings) as the source of truth,
+ * NOT the raw dataset.schema — the raw schema contains storage-level column names
+ * and flat types that don't match the policy's Rosetta Stone attribute names.
+ *
+ * A policy is considered valid (compatible) if `findMatchingBranches` finds at
+ * least one satisfied branch.
+ *
+ * @param _dataset - The dataset (currently unused; attributes carry the relevant info).
+ * @param attributes - Rosetta Stone attributes associated with the dataset.
+ * @param policies - JSON-Schema-based connector policies to evaluate.
+ * @returns An array of PolicyEvaluation results, one per policy.
+ */
+export declare function evaluateJsonSchemaPolicies(_dataset: Dataset, attributes: Attribute[], policies: JsonSchemaConnectorPolicy[]): PolicyEvaluation[];

package/build/collaboration-policy/core/jsonschema/policy-evaluator.js

@@ -0,0 +1,250 @@
+/**
+ * Collect filters for a list of required attribute names by looking them up
+ * in the property definitions object (sibling to anyOf).
+ *
+ * In the real API shape, filters live on individual property definitions:
+ *
+ *   schema.properties.properties.properties = {
+ *     "sha256_hashed_email": {
+ *       "$ref": "#/$defs/object_value",
+ *       "attribute": "https://api.narrative.io/attributes/sha256_hashed_email",
+ *       "filters": [ ... ]
+ *     }
+ *   }
+ *
+ * @param requiredAttrs - Attribute names whose filters should be collected.
+ * @param propertyDefs - The property definitions object from the schema.
+ * @returns Collected filters from all matching property definitions.
+ */
+function collectFiltersForAttributes(requiredAttrs, propertyDefs) {
+    if (!propertyDefs)
+        return [];
+    const filters = [];
+    for (const attrName of requiredAttrs) {
+        const propDef = propertyDefs[attrName];
+        if (propDef?.filters && Array.isArray(propDef.filters)) {
+            filters.push(...propDef.filters);
+        }
+    }
+    return filters;
+}
+/**
+ * Resolve a `$ref` on a property definition to its `$defs` entry and extract
+ * the required data subfields that should generate IS NOT NULL WHERE clauses.
+ *
+ * Only object-type `$defs` (where `properties.type.const === "object"`) have
+ * data subfields. The data subfields are listed in
+ * `properties.properties.required`.
+ *
+ * Note: the top-level `required` array on an object-type $def (typically
+ * `["type", "properties"]`) describes the schema's structural envelope —
+ * `"type"` there is the meta-schema discriminator (`{const: "object"}`),
+ * not a Rosetta Stone data column — so it must not be emitted as a subfield.
+ *
+ * Primitive types (like `string_value_type`) return no subfields.
+ *
+ * @param propDef - The property definition that may have a `$ref`.
+ * @param defs - The `$defs` object from the schema root.
+ * @returns Array of subfield names that require IS NOT NULL checks.
+ */
+function resolveRefRequiredSubfields(propDef, defs) {
+    if (!propDef.$ref || !defs)
+        return [];
+    const defName = propDef.$ref.replace(/^#\/\$defs\//, "");
+    const def = defs[defName];
+    if (!def)
+        return [];
+    const defProperties = def.properties;
+    if (!defProperties)
+        return [];
+    // Only object-type $defs have data subfields
+    const typeProperty = defProperties.type;
+    if (typeProperty?.const !== "object")
+        return [];
+    const innerProps = defProperties.properties;
+    const innerRequired = innerProps?.required;
+    if (!innerRequired)
+        return [];
+    return [...innerRequired];
+}
+/**
+ * Collect required data subfields for a list of attribute names by resolving
+ * their `$ref` entries against the schema's `$defs`.
+ *
+ * These generate IS NOT NULL WHERE clauses in the SQL builder.
+ *
+ * @param requiredAttrs - Attribute names whose required subfields should be collected.
+ * @param propertyDefs - The property definitions object from the schema.
+ * @param defs - The `$defs` object from the schema root.
+ * @returns Per-attribute list of subfield paths that require IS NOT NULL checks.
+ */
+function collectRequiredSubfieldsFromRefs(requiredAttrs, propertyDefs, defs) {
+    if (!propertyDefs)
+        return [];
+    const result = [];
+    for (const attrName of requiredAttrs) {
+        const propDef = propertyDefs[attrName];
+        if (!propDef)
+            continue;
+        const paths = resolveRefRequiredSubfields(propDef, defs);
+        if (paths.length > 0) {
+            result.push({ attributeName: attrName, paths });
+        }
+    }
+    return result;
+}
+/**
+ * Determine which branches in a JSON-Schema policy are satisfied for the given attributes.
+ *
+ * Expects the real API structure:
+ *
+ *   schema.properties.properties = {
+ *     anyOf: [
+ *       { required: ["sha256_hashed_email"] },
+ *       { allOf: [
+ *           { required: ["person_name"] },
+ *           { required: ["iso_3166_1_country"] },
+ *           { required: ["postal_address"] }
+ *         ]
+ *       }
+ *     ],
+ *     properties: {
+ *       "sha256_hashed_email": {
+ *         "$ref": "#/$defs/attribute_value",
+ *         "attribute": "https://api.narrative.io/attributes/sha256_hashed_email",
+ *         "filters": [ ... ],
+ *         "$ref": "#/$defs/object_value"
+ *       },
+ *       ...
+ *     }
+ *   }
+ *
+ * Branches only contain `required` arrays. Filters are defined on the property
+ * definitions (sibling `properties` object next to `anyOf`). Required subfields
+ * for IS NOT NULL clauses are derived by resolving `$ref` entries against `$defs`.
+ *
+ * A branch is considered satisfied if:
+ *   - For a simple branch: all required property names exist as Attributes by name.
+ *   - For an allOf group: all sub-branches' required property names exist as Attributes.
+ *
+ * @param policy - The JSON-Schema connector policy to inspect.
+ * @param attributes - Attributes available on the dataset.
+ * @returns A list of matching branches with their required attributes, filters, and additional requirements.
+ */
+function findMatchingBranches(policy, attributes) {
+    const attributeByName = new Map();
+    for (const attr of attributes) {
+        attributeByName.set(attr.name, attr);
+    }
+    const schema = policy.policy;
+    const schemaProps = schema.properties;
+    // Extract $defs from the schema root for $ref resolution
+    const defs = schema.$defs;
+    // Expect something like: schema.properties.properties.anyOf
+    const propertiesObj = schemaProps &&
+        schemaProps.properties;
+    const anyOfBranches = propertiesObj?.anyOf;
+    if (!Array.isArray(anyOfBranches)) {
+        return [];
+    }
+    // Property definitions live as a sibling to anyOf — this is where filters are.
+    const propertyDefs = propertiesObj?.properties;
+    const matches = [];
+    anyOfBranches.forEach((branch, index) => {
+        if (!branch || typeof branch !== "object")
+            return;
+        const branchObj = branch;
+        // Case 1: "allOf" group branch (bundle of multiple fields)
+        if (Array.isArray(branchObj.allOf)) {
+            const groupRequiredAttrs = [];
+            let allSubBranchesSatisfied = true;
+            for (const sub of branchObj.allOf) {
+                if (!sub || typeof sub !== "object") {
+                    allSubBranchesSatisfied = false;
+                    break;
+                }
+                const subObj = sub;
+                const subRequired = Array.isArray(subObj.required)
+                    ? subObj.required
+                    : [];
+                // Sub-branch is satisfied if all required keys exist as attributes.
+                const missingSub = subRequired.filter((key) => !attributeByName.has(key));
+                if (missingSub.length > 0) {
+                    allSubBranchesSatisfied = false;
+                    break;
+                }
+                groupRequiredAttrs.push(...subRequired);
+            }
+            if (!allSubBranchesSatisfied) {
+                return; // this outer anyOf branch is not satisfied
+            }
+            const deduped = Array.from(new Set(groupRequiredAttrs));
+            matches.push({
+                branchIndex: index,
+                requiredAttributes: deduped,
+                filters: collectFiltersForAttributes(deduped, propertyDefs),
+                additionalRequiredProperties: collectRequiredSubfieldsFromRefs(deduped, propertyDefs, defs),
+            });
+            return;
+        }
+        // Case 2: simple single-field branch
+        const branchRequired = Array.isArray(branchObj.required)
+            ? branchObj.required
+            : [];
+        const missing = branchRequired.filter((key) => !attributeByName.has(key));
+        if (missing.length > 0) {
+            return; // this branch is not satisfied
+        }
+        matches.push({
+            branchIndex: index,
+            requiredAttributes: branchRequired,
+            filters: collectFiltersForAttributes(branchRequired, propertyDefs),
+            additionalRequiredProperties: collectRequiredSubfieldsFromRefs(branchRequired, propertyDefs, defs),
+        });
+    });
+    return matches;
+}
+/**
+ * Evaluate an array of JSON-Schema-based connector policies against a dataset.
+ *
+ * Eligibility is determined by checking whether the dataset's Rosetta Stone
+ * attributes satisfy at least one anyOf branch in the policy schema. This uses
+ * the `attributes` array (resolved from dataset mappings) as the source of truth,
+ * NOT the raw dataset.schema — the raw schema contains storage-level column names
+ * and flat types that don't match the policy's Rosetta Stone attribute names.
+ *
+ * A policy is considered valid (compatible) if `findMatchingBranches` finds at
+ * least one satisfied branch.
+ *
+ * @param _dataset - The dataset (currently unused; attributes carry the relevant info).
+ * @param attributes - Rosetta Stone attributes associated with the dataset.
+ * @param policies - JSON-Schema-based connector policies to evaluate.
+ * @returns An array of PolicyEvaluation results, one per policy.
+ */
+export function evaluateJsonSchemaPolicies(_dataset, attributes, policies) {
+    const evaluations = [];
+    for (const policy of policies) {
+        // Determine which branches within the policy are satisfied by the
+        // dataset's Rosetta Stone attributes.
+        const matches = findMatchingBranches(policy, attributes);
+        if (matches.length > 0) {
+            evaluations.push({
+                policy,
+                isValid: true,
+                matches,
+                errors: [],
+            });
+        }
+        else {
+            evaluations.push({
+                policy,
+                isValid: false,
+                matches: [],
+                errors: [
+                    `No anyOf branches are satisfied by the available attributes for policy "${policy.name}"`,
+                ],
+            });
+        }
+    }
+    return evaluations;
+}

package/build/collaboration-policy/core/jsonschema/sql-builder.d.ts

@@ -0,0 +1,79 @@
+import type { Attribute } from "../../../attributes/types";
+import type { Dataset } from "../../../datasets/types";
+import type { PolicyMatchResult, PolicySqlFragments } from "../types";
+import type { JsonSchemaConnectorPolicy } from "./json-schema-types";
+import type { PolicyBranchMatch } from "./policy-branches";
+/**
+ * JSON-Schema-based equivalent of PolicyMatchResult, but instead of fully-built SQL,
+ * it carries branch-level matches that your existing SQL builder can consume.
+ */
+export interface JsonSchemaPolicyMatchResult {
+    /** Names of policies whose JSON Schemas were compatible with the dataset. */
+    appliedPolicies: string[];
+    /** Policies that were skipped because validation failed. */
+    skippedPolicies: PolicyMatchResult["skippedPolicies"];
+    /** Non-fatal warnings (e.g. some policies were skipped). */
+    warnings: string[];
+    /**
+     * The minimum refresh schedule (most frequent) across all applied policies,
+     * expressed as an ISO 8601 duration string.
+     */
+    refresh_schedule: string;
+    /**
+     * For each applied policy, which branches matched and what filters/attributes
+     * they require. This is what your SQL builder layer should consume.
+     */
+    branchMatches: Array<{
+        policyName: string;
+        branches: PolicyBranchMatch[];
+    }>;
+}
+/**
+ * Categorize JSON-Schema-based connector policies into matching and non-matching
+ * groups based on dataset compatibility.
+ *
+ * @param policies - JSON-Schema-based connector policies.
+ * @param dataset - Dataset whose schema is used for validation.
+ * @param attributes - Attributes associated with the dataset.
+ * @returns Object with matching policies, nonMatching policies, and skip details.
+ */
+export declare function categorizePolicies(policies: JsonSchemaConnectorPolicy[], dataset: Dataset, attributes: Attribute[]): {
+    matching: JsonSchemaConnectorPolicy[];
+    nonMatching: JsonSchemaConnectorPolicy[];
+    skippedDetails: PolicyMatchResult["skippedPolicies"];
+};
+/**
+ * Helper that evaluates JSON-Schema-based policies and returns branch-level
+ * matches plus scheduling information.
+ *
+ * This is intended to be consumed by a separate SQL builder layer or for
+ * inspection of branch-level match details.
+ *
+ * @param dataset - The dataset against which policies should be evaluated.
+ * @param policies - JSON-Schema-based connector policies.
+ * @param attributes - Attributes associated with the dataset.
+ * @returns JsonSchemaPolicyMatchResult with applied/skipped policies and branch matches.
+ * @throws If no policies are compatible with the dataset.
+ */
+export declare function buildPolicySqlWithJsonSchema(dataset: Dataset, policies: JsonSchemaConnectorPolicy[], attributes: Attribute[]): JsonSchemaPolicyMatchResult;
+/**
+ * Uses JSON Schema branch matching to determine valid policies, then builds
+ * SELECT and WHERE SQL fragments.
+ *
+ * @param dataset - Dataset for which to evaluate policies and produce SQL.
+ * @param policies - JSON-Schema-based connector policies.
+ * @param attributes - Attributes associated with the dataset.
+ * @returns PolicyMatchResult with select, where, applied/skipped policies, warnings, and refresh schedule.
+ */
+export declare function buildPolicySqlWithValidation(dataset: Dataset, policies: JsonSchemaConnectorPolicy[], attributes: Attribute[]): PolicyMatchResult;
+/**
+ * Build SQL fragments without validation. Assumes you already filtered the policies
+ * however you want (e.g. via categorizePolicies). Builds SELECT and WHERE SQL
+ * fragments from all provided policies.
+ *
+ * @param dataset - Dataset for which to build SQL fragments.
+ * @param policies - JSON-Schema-based connector policies.
+ * @param attributes - Attributes associated with the dataset.
+ * @returns PolicySqlFragments with select and where arrays.
+ */
+export declare function buildPolicySql(dataset: Dataset, policies: JsonSchemaConnectorPolicy[], attributes: Attribute[]): PolicySqlFragments;