@narrative.io/data-collaboration-sdk-ts 2.102.0 → 2.105.0

package/build/collaboration-policy/core/jsonschema/sql-builder.js

@@ -0,0 +1,306 @@
+import { buildSelectAlias, resolveAttributeExpression, } from "../../utils/sql-helpers";
+import { filterToSql } from "../filter-builder";
+import { evaluateJsonSchemaPolicies } from "./policy-evaluator";
+/**
+ * Convert an ISO 8601 duration string (e.g. "P1D", "PT1H") into milliseconds.
+ * This is an approximation (months and years are treated as 30 and 365 days respectively).
+ *
+ * @param duration - The ISO 8601 duration string.
+ * @returns The approximate duration in milliseconds.
+ * @throws If the duration string does not match the ISO 8601 duration format.
+ */
+function parseDurationToMilliseconds(duration) {
+    const regex = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+    const matches = duration.match(regex);
+    if (!matches) {
+        throw new Error(`Invalid ISO 8601 duration format: ${duration}`);
+    }
+    const [, years, months, weeks, days, hours, minutes, seconds] = matches.map((m) => Number.parseInt(m || "0", 10));
+    const milliseconds = years * 365 * 24 * 60 * 60 * 1000 +
+        months * 30 * 24 * 60 * 60 * 1000 +
+        weeks * 7 * 24 * 60 * 60 * 1000 +
+        days * 24 * 60 * 60 * 1000 +
+        hours * 60 * 60 * 1000 +
+        minutes * 60 * 1000 +
+        seconds * 1000;
+    return milliseconds;
+}
+/**
+ * Find the "smallest" (most frequent) ISO 8601 duration within a list.
+ *
+ * @param schedules - Array of ISO 8601 duration strings.
+ * @returns The smallest duration as an ISO 8601 string, or "P1M" if none are valid.
+ */
+function getSmallestRefreshSchedule(schedules) {
+    const defaultMonthly = "P1M";
+    if (schedules.length === 0)
+        return defaultMonthly;
+    if (schedules.length === 1) {
+        try {
+            parseDurationToMilliseconds(schedules[0]);
+            return schedules[0];
+        }
+        catch {
+            return defaultMonthly;
+        }
+    }
+    let smallestValue = Number.MAX_SAFE_INTEGER;
+    let smallestSchedule = null;
+    for (const schedule of schedules) {
+        try {
+            const value = parseDurationToMilliseconds(schedule);
+            if (value < smallestValue) {
+                smallestValue = value;
+                smallestSchedule = schedule;
+            }
+        }
+        catch {
+            // skip invalid schedule
+        }
+    }
+    return smallestSchedule ?? defaultMonthly;
+}
+/**
+ * Build SQL fragments (SELECT + WHERE) from branch matches across all applied policies.
+ *
+ * SELECT: one entry per unique required attribute (root level, no subfield paths):
+ *   company_data."<dataset>"."_rosetta_stone"."<attr>" AS "<attr>"
+ *
+ * WHERE: structured as root AND → per-policy structure → OR of branches.
+ *   Each branch contains IS NOT NULL clauses (from additionalRequiredProperties)
+ *   and filter SQL (from filters), ANDed together.
+ *
+ * @param branchMatches - Per-policy branch match results from evaluateJsonSchemaPolicies.
+ * @param attributeByName - Map of attribute name → Attribute for SQL expression building.
+ * @param datasetName - Dataset name used in SQL column paths.
+ * @returns PolicySqlFragments with select and where arrays.
+ */
+function buildSqlFromBranchMatches(branchMatches, attributeByName, datasetName) {
+    // --- SELECT ---
+    // Collect all unique required attributes across all policies and branches
+    const globalRequiredAttributes = new Set();
+    for (const policyMatch of branchMatches) {
+        for (const branch of policyMatch.branches) {
+            for (const attrName of branch.requiredAttributes) {
+                globalRequiredAttributes.add(attrName);
+            }
+        }
+    }
+    const selectClauses = new Set();
+    for (const attrName of globalRequiredAttributes) {
+        const attribute = attributeByName.get(attrName);
+        if (!attribute)
+            continue;
+        const expression = resolveAttributeExpression(attribute, "", datasetName);
+        const alias = buildSelectAlias(attrName, "");
+        selectClauses.add(`${expression} AS ${alias}`);
+    }
+    // --- WHERE ---
+    const policyWhereGroups = [];
+    for (const policyMatch of branchMatches) {
+        const branchWheres = [];
+        for (const branch of policyMatch.branches) {
+            const branchClauses = [];
+            // 1. IS NOT NULL clauses derived from $ref/$defs resolution
+            for (const req of branch.additionalRequiredProperties) {
+                const attribute = attributeByName.get(req.attributeName);
+                if (!attribute)
+                    continue;
+                for (const path of req.paths) {
+                    const expression = resolveAttributeExpression(attribute, path, datasetName);
+                    branchClauses.push(`(${expression} IS NOT NULL)`);
+                }
+            }
+            // 2. Filter SQL
+            for (const filter of branch.filters) {
+                const sql = filterToSql(filter, attributeByName, datasetName);
+                branchClauses.push(sql);
+            }
+            if (branchClauses.length === 0) {
+                continue; // branch has no WHERE contribution
+            }
+            if (branchClauses.length === 1) {
+                branchWheres.push(branchClauses[0]);
+            }
+            else {
+                branchWheres.push({
+                    operation: "AND",
+                    fragments: branchClauses,
+                });
+            }
+        }
+        if (branchWheres.length === 0) {
+            continue; // policy has no WHERE contribution
+        }
+        if (branchWheres.length === 1) {
+            policyWhereGroups.push(branchWheres[0]);
+        }
+        else {
+            // Multiple branches → OR them (anyOf semantics)
+            policyWhereGroups.push({
+                operation: "OR",
+                fragments: branchWheres,
+            });
+        }
+    }
+    let where;
+    if (policyWhereGroups.length === 0) {
+        where = [];
+    }
+    else {
+        // Root AND wrapping all policies
+        where = [
+            {
+                fragments: policyWhereGroups,
+                operation: "AND",
+            },
+        ];
+    }
+    return {
+        select: Array.from(selectClauses),
+        where,
+    };
+}
+/**
+ * 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 function categorizePolicies(policies, dataset, attributes) {
+    const evaluations = evaluateJsonSchemaPolicies(dataset, attributes, policies);
+    const matching = [];
+    const nonMatching = [];
+    const skippedDetails = [];
+    for (const evalResult of evaluations) {
+        const { policy, isValid, errors } = evalResult;
+        if (isValid) {
+            matching.push(policy);
+        }
+        else {
+            nonMatching.push(policy);
+            skippedDetails.push({
+                name: policy.name,
+                reason: "Dataset schema not compatible with policy JSON Schema",
+                details: errors,
+            });
+        }
+    }
+    return { matching, nonMatching, skippedDetails };
+}
+/**
+ * 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 function buildPolicySqlWithJsonSchema(dataset, policies, attributes) {
+    const evaluations = evaluateJsonSchemaPolicies(dataset, attributes, policies);
+    const appliedPolicies = [];
+    const skippedPolicies = [];
+    const warnings = [];
+    const branchMatches = [];
+    for (const evalResult of evaluations) {
+        const { policy, isValid, matches, errors } = evalResult;
+        if (!isValid) {
+            skippedPolicies.push({
+                name: policy.name,
+                reason: "Dataset schema not compatible with policy JSON Schema",
+                details: errors,
+            });
+            continue;
+        }
+        appliedPolicies.push(policy.name);
+        branchMatches.push({
+            policyName: policy.name,
+            branches: matches,
+        });
+    }
+    if (appliedPolicies.length === 0) {
+        const errorMessage = policies.length === 0
+            ? "No policies provided"
+            : `No policies are compatible with dataset "${dataset.display_name || dataset.name}".`;
+        const details = skippedPolicies.length > 0
+            ? [`Skipped policies: ${skippedPolicies.map((p) => p.name).join(", ")}`]
+            : [];
+        throw new Error(`${errorMessage}\n${details.join("\n")}`);
+    }
+    if (skippedPolicies.length > 0) {
+        warnings.push(`Skipped ${skippedPolicies.length} incompatible policies: ${skippedPolicies
+            .map((p) => p.name)
+            .join(", ")}`);
+    }
+    const refreshSchedules = evaluations
+        .filter((e) => e.isValid && e.policy.metadata.refresh_schedule?.max)
+        .map((e) => e.policy.metadata.refresh_schedule?.max)
+        .filter((max) => max != null);
+    const refresh_schedule = getSmallestRefreshSchedule(refreshSchedules);
+    return {
+        appliedPolicies,
+        skippedPolicies,
+        warnings,
+        refresh_schedule,
+        branchMatches,
+    };
+}
+/**
+ * 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 function buildPolicySqlWithValidation(dataset, policies, attributes) {
+    const matchResult = buildPolicySqlWithJsonSchema(dataset, policies, attributes);
+    const attributeByName = new Map();
+    for (const attr of attributes) {
+        attributeByName.set(attr.name, attr);
+    }
+    const sqlFragments = buildSqlFromBranchMatches(matchResult.branchMatches, attributeByName, dataset.name);
+    return {
+        ...sqlFragments,
+        appliedPolicies: matchResult.appliedPolicies,
+        skippedPolicies: matchResult.skippedPolicies,
+        warnings: matchResult.warnings,
+        refresh_schedule: matchResult.refresh_schedule,
+    };
+}
+/**
+ * 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 function buildPolicySql(dataset, policies, attributes) {
+    const evaluations = evaluateJsonSchemaPolicies(dataset, attributes, policies);
+    const attributeByName = new Map();
+    for (const attr of attributes) {
+        attributeByName.set(attr.name, attr);
+    }
+    const branchMatches = [];
+    for (const evalResult of evaluations) {
+        if (evalResult.isValid) {
+            branchMatches.push({
+                policyName: evalResult.policy.name,
+                branches: evalResult.matches,
+            });
+        }
+    }
+    return buildSqlFromBranchMatches(branchMatches, attributeByName, dataset.name);
+}

package/build/collaboration-policy/core/types.d.ts

@@ -1,20 +1,91 @@
-import type { CollaborationPolicyType } from "../types";
-type PolicyDefinition = CollaborationPolicyType["policy"]["definition"];
-export type StructureNode = PolicyDefinition["structure"];
-export type ExtendedAttributeNode = Extract<StructureNode, {
-    field: unknown;
-}>;
-export type PolicyFilter = NonNullable<PolicyDefinition["filters"]>[number];
-export type PathValue = NonNullable<ExtendedAttributeNode["field"]["additional_required_properties"]>[number];
+/**
+ * PathValue describes a path to a subfield, expressed as either dot notation
+ * or a JSON Pointer. Used in filter attribute references to specify which
+ * subfield of an attribute to operate on.
+ */
+export type PathValue = {
+    dot: string;
+} | {
+    pointer: string;
+};
+/**
+ * An attribute reference within a filter expression.
+ */
+export interface FilterAttributeRef {
+    type: "attribute";
+    attribute_name: string;
+    path?: PathValue;
+}
+/**
+ * A filter expression: a literal value or an attribute reference.
+ */
+export type FilterExpression = string | number | boolean | FilterAttributeRef;
+/**
+ * PolicyFilter is a single filter entry in a policy definition.
+ *
+ * This is the canonical filter type used across the codebase (JSON-Schema
+ * filters, SQL builder, etc.).
+ */
+export type PolicyFilter = PolicyFilterAndOr | PolicyFilterNot | PolicyFilterIsNull | PolicyFilterIn | PolicyFilterCompare | PolicyFilterBetween;
+interface PolicyFilterBase {
+    stage?: "generation";
+    name?: string;
+    required?: boolean;
+}
+interface PolicyFilterAndOr extends PolicyFilterBase {
+    op: "and" | "or";
+    args: FilterExpression[];
+}
+interface PolicyFilterNot extends PolicyFilterBase {
+    op: "not";
+    args: FilterExpression[];
+}
+interface PolicyFilterIsNull extends PolicyFilterBase {
+    op: "is_null" | "is_not_null";
+    left: FilterExpression;
+}
+interface PolicyFilterIn extends PolicyFilterBase {
+    op: "in" | "not in";
+    left: FilterExpression;
+    right: FilterExpression[];
+}
+interface PolicyFilterCompare extends PolicyFilterBase {
+    op: "=" | "<>" | ">" | ">=" | "<" | "<=" | "like" | "not like";
+    left: FilterExpression;
+    right: FilterExpression;
+}
+interface PolicyFilterBetween extends PolicyFilterBase {
+    op: "between";
+    operand: FilterExpression;
+    lower: FilterExpression;
+    upper: FilterExpression;
+}
+/**
+ * Map from attribute name -> set of normalized paths that must be selected
+ * for SQL generation.
+ */
 export type AttributePathIndex = Map<string, Set<string>>;
+/**
+ * A logical group of SQL fragments combined by an operation.
+ */
 export interface PolicySqlGroup {
     fragments: Array<string | PolicySqlGroup>;
     operation: "AND" | "OR";
 }
+/**
+ * Core SQL fragments required to represent a set of collaboration policies.
+ */
 export interface PolicySqlFragments {
     select: string[];
     where: Array<PolicySqlGroup | string>;
 }
+/**
+ * Full result of applying collaboration policies to a dataset, including:
+ * - which policies were applied
+ * - which were skipped and why
+ * - warnings
+ * - the minimum refresh schedule across applied policies
+ */
 export interface PolicyMatchResult extends PolicySqlFragments {
     appliedPolicies: string[];
     skippedPolicies: Array<{
@@ -23,7 +94,7 @@ export interface PolicyMatchResult extends PolicySqlFragments {
         details: string[];
     }>;
     warnings: string[];
-    /** The minimum refresh schedule in milliseconds across all evaluated policies */
-    refresh_schedule: number;
+    /** The minimum refresh schedule as an ISO 8601 duration string across all evaluated policies */
+    refresh_schedule: string;
 }
 export {};

package/build/collaboration-policy/index.d.ts

@@ -1,4 +1,5 @@
-export { buildPolicySql, buildPolicySqlWithValidation, categorizePolicies, } from "./core/sql-builder";
-export type { AttributePathIndex, ExtendedAttributeNode, PathValue, PolicyFilter, PolicyMatchResult, PolicySqlFragments, PolicySqlGroup, StructureNode, } from "./core/types";
-export type { CollaborationPolicyInput, CollaborationPolicyType, } from "./types";
-export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./types";
+export type { JsonSchemaConnectorPolicy } from "./core/jsonschema/json-schema-types";
+export { evaluateJsonSchemaPolicies } from "./core/jsonschema/policy-evaluator";
+export { buildPolicySql, buildPolicySqlWithJsonSchema, buildPolicySqlWithValidation, categorizePolicies, type JsonSchemaPolicyMatchResult, } from "./core/jsonschema/sql-builder";
+export type { AttributePathIndex, FilterAttributeRef, FilterExpression, PathValue, PolicyFilter, PolicyMatchResult, PolicySqlFragments, PolicySqlGroup, } from "./core/types";
+export { default as useCollaborationPolicy } from "./useCollaborationPolicy";

package/build/collaboration-policy/index.js

@@ -1,3 +1,4 @@
-// Export the main functions
-export { buildPolicySql, buildPolicySqlWithValidation, categorizePolicies, } from "./core/sql-builder";
-export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./types";
+export { evaluateJsonSchemaPolicies } from "./core/jsonschema/policy-evaluator";
+export { buildPolicySql, buildPolicySqlWithJsonSchema, buildPolicySqlWithValidation, categorizePolicies, } from "./core/jsonschema/sql-builder";
+// Hook-style entrypoint
+export { default as useCollaborationPolicy } from "./useCollaborationPolicy";

package/build/collaboration-policy/useCollaborationPolicy.d.ts

@@ -1,8 +1,17 @@
 import type { Attribute } from "../attributes/types";
 import type { Dataset } from "../datasets/types";
-import type { PolicySqlFragments } from "./core/types";
-import type { CollaborationPolicyType } from "./types";
+import type { JsonSchemaConnectorPolicy } from "./core/jsonschema/json-schema-types";
+import type { PolicyMatchResult, PolicySqlFragments } from "./core/types";
+/**
+ * Hook-style wrapper that exposes collaboration policy helpers.
+ *
+ * Public API surface:
+ * - categorizePolicies
+ * - buildPolicySql
+ * - buildPolicySqlWithValidation
+ */
 export default function useCollaborationPolicy(): {
-    getEligibleConnectorsPolicies: (dataset: Dataset, policies: CollaborationPolicyType[], attributes: Attribute[]) => CollaborationPolicyType[];
-    buildPolicySqlFragments: (dataset: Dataset, policies: CollaborationPolicyType[], attributes: Attribute[]) => PolicySqlFragments;
+    getEligibleConnectorsPolicies: (dataset: Dataset, policies: JsonSchemaConnectorPolicy[], attributes: Attribute[]) => JsonSchemaConnectorPolicy[];
+    buildPolicySqlFragments: (dataset: Dataset, policies: JsonSchemaConnectorPolicy[], attributes: Attribute[]) => PolicySqlFragments;
+    buildPolicySqlWithValidationJsonSchema: (dataset: Dataset, policies: JsonSchemaConnectorPolicy[], attributes: Attribute[]) => PolicyMatchResult;
 };

package/build/collaboration-policy/useCollaborationPolicy.js

@@ -1,14 +1,36 @@
-import { buildPolicySql, categorizePolicies } from "./core/sql-builder";
+import { buildPolicySql, buildPolicySqlWithValidation, categorizePolicies, } from "./core/jsonschema/sql-builder";
+/**
+ * Hook-style wrapper that exposes collaboration policy helpers.
+ *
+ * Public API surface:
+ * - categorizePolicies
+ * - buildPolicySql
+ * - buildPolicySqlWithValidation
+ */
 export default function useCollaborationPolicy() {
+    /**
+     * Get policies that are compatible with a dataset using the JSON-Schema policy system.
+     */
     const getEligibleConnectorsPolicies = (dataset, policies, attributes) => {
         const { matching } = categorizePolicies(policies, dataset, attributes);
         return matching;
     };
+    /**
+     * Build SQL fragments using JSON-Schema policies, without per-policy validation.
+     */
     const buildPolicySqlFragments = (dataset, policies, attributes) => {
         return buildPolicySql(dataset, policies, attributes);
     };
+    /**
+     * Validate each JSON-Schema policy against the dataset and build SQL
+     * plus metadata (appliedPolicies, skippedPolicies, etc.).
+     */
+    const buildPolicySqlWithValidationJsonSchema = (dataset, policies, attributes) => {
+        return buildPolicySqlWithValidation(dataset, policies, attributes);
+    };
     return {
         getEligibleConnectorsPolicies,
         buildPolicySqlFragments,
+        buildPolicySqlWithValidationJsonSchema,
     };
 }

package/build/collaboration-policy/utils/path-helpers.d.ts

@@ -1,4 +1,8 @@
-import type { Attribute } from "../../attributes/types";
-import type { AttributePathIndex, PathValue } from "../core/types";
-export declare function markAttributePath(index: AttributePathIndex, attribute: Attribute, path: string): void;
+import type { PathValue } from "../core/types";
+/**
+ * Normalizes a PathValue (dot notation or JSON pointer) into a simple dot-notation string.
+ *
+ * @param path - A PathValue with either `{ dot: "..." }` or `{ pointer: "..." }` format.
+ * @returns Normalized dot-notation string, or empty string for undefined/null.
+ */
 export declare function normalizePathValue(path?: PathValue): string;

package/build/collaboration-policy/utils/path-helpers.js

@@ -1,25 +1,9 @@
-export function markAttributePath(index, attribute, path) {
-    const attributePaths = index.get(attribute.name) ?? new Set();
-    // Use the provided path, even if it's an empty string (which represents the root attribute)
-    const normalized = path !== undefined && path !== null
-        ? path
-        : determineDefaultPath(attribute);
-    attributePaths.add(normalized);
-    index.set(attribute.name, attributePaths);
-}
-function determineDefaultPath(attribute) {
-    if (attribute.type === "object" && "properties" in attribute) {
-        const properties = attribute.properties ?? {};
-        if ("value" in properties) {
-            return "value";
-        }
-        const [firstKey] = Object.keys(properties);
-        if (firstKey) {
-            return firstKey;
-        }
-    }
-    return "";
-}
+/**
+ * Normalizes a PathValue (dot notation or JSON pointer) into a simple dot-notation string.
+ *
+ * @param path - A PathValue with either `{ dot: "..." }` or `{ pointer: "..." }` format.
+ * @returns Normalized dot-notation string, or empty string for undefined/null.
+ */
 export function normalizePathValue(path) {
     if (!path) {
         return "";

package/build/datasets/index.d.ts

@@ -2,9 +2,9 @@ import type { UnknownJob } from "src/jobs/types";
 import { BaseApi } from "../base-api";
 import type { ApiRecords } from "../types";
 import type { DatasetStatisticsConfiguration, StatisticsConfigurationResponse } from "./statistics-types";
-import type { AdvancedStatistics, AdvancedStatisticsMetadata, BasicStatistics, ColumnStatistics, ColumnSummary, Columns, Configuration, CreateDatasetRefreshScheduleRequest, CreateDatasetRequest, Dataset, DatasetStatus, DatasetTableSummary, DatasetTableSummaryAPIResponse, DatasetWriteMode, FilePerSnapshotResponse, Histogram, IngestDatasetFileRequest, RecalculationInfo, RetentionPolicy, RetentionScheduleConfig, RowClock, RowTTLPolicy, Schema, SchemaArrayItems, SchemaArrayItemsArray, SchemaArrayItemsObject, SchemaArrayItemsPrimitive, SchemaArrayProperty, SchemaFileConfig, SchemaFileConfigType, SchemaObjectProperty, SchemaPrimitiveProperty, SchemaProperties, SchemaPropertiesType, SchemaProperty, SnapshotAgeExpression, SnapshotRange, SnapshotTTLPolicy, TableClock, TableClockKind, TableTTLPolicy, TTLPolicy, TTLPolicyKind, UpdateDatasetRefreshScheduleRequest, UpdateDatasetRequest, UpsertRetentionPoliciesRequest, Value } from "./types";
+import type { AdvancedStatistics, AdvancedStatisticsMetadata, BasicStatistics, ColumnStatistics, ColumnSummary, Columns, Configuration, CreateDatasetRefreshScheduleRequest, CreateDatasetRequest, Dataset, DatasetInterfaceError, DatasetInterfaceRef, DatasetInterfaceValidation, DatasetStatus, DatasetTableSummary, DatasetTableSummaryAPIResponse, DatasetWriteMode, FilePerSnapshotResponse, Histogram, IngestDatasetFileRequest, JsonSchemaValidationNode, RecalculationInfo, RetentionPolicy, RetentionScheduleConfig, RowClock, RowTTLPolicy, Schema, SchemaArrayItems, SchemaArrayItemsArray, SchemaArrayItemsObject, SchemaArrayItemsPrimitive, SchemaArrayProperty, SchemaFileConfig, SchemaFileConfigType, SchemaObjectProperty, SchemaPrimitiveProperty, SchemaProperties, SchemaPropertiesType, SchemaProperty, SnapshotAgeExpression, SnapshotRange, SnapshotTTLPolicy, TableClock, TableClockKind, TableTTLPolicy, TTLPolicy, TTLPolicyKind, UpdateDatasetRefreshScheduleRequest, UpdateDatasetRequest, UpsertRetentionPoliciesRequest, Value } from "./types";
 export type { CronRefresh, DatasetFieldConfig, DatasetFieldNamespace, DatasetStatisticsConfiguration, HistogramOptions, HistogramOverflow, ManualRefresh, NestedNodeConfig, NestedPropertyConfig, NonPrimitiveNodeConfig, OnUpdateRefresh, PrimitiveNodeConfig, RefreshTrigger, RosettaStoneFieldConfig, RosettaStoneFieldNamespace, StatConfig, StatisticsConfigurationResponse, StatName, StatOptions, } from "./statistics-types";
-export type { AdvancedStatistics, AdvancedStatisticsMetadata, BasicStatistics, ColumnStatistics, ColumnSummary, Columns, Configuration, CreateDatasetRefreshScheduleRequest, CreateDatasetRequest, Dataset, DatasetStatus, DatasetTableSummaryAPIResponse, DatasetWriteMode, FilePerSnapshotResponse, Histogram, RetentionPolicy, RetentionScheduleConfig, RowClock, RowTTLPolicy, Schema, SchemaArrayItems, SchemaArrayItemsArray, SchemaArrayItemsObject, SchemaArrayItemsPrimitive, SchemaArrayProperty, SchemaFileConfig, SchemaFileConfigType, SchemaObjectProperty, SchemaPrimitiveProperty, SchemaProperties, SchemaPropertiesType, SchemaProperty, SnapshotAgeExpression, SnapshotRange, SnapshotTTLPolicy, TableClock, TableClockKind, TableTTLPolicy, TTLPolicy, TTLPolicyKind, UpdateDatasetRefreshScheduleRequest, UpdateDatasetRequest, UpsertRetentionPoliciesRequest, Value, };
+export type { AdvancedStatistics, AdvancedStatisticsMetadata, BasicStatistics, ColumnStatistics, ColumnSummary, Columns, Configuration, CreateDatasetRefreshScheduleRequest, CreateDatasetRequest, Dataset, DatasetInterfaceError, DatasetInterfaceRef, DatasetInterfaceValidation, DatasetStatus, DatasetTableSummaryAPIResponse, DatasetWriteMode, FilePerSnapshotResponse, Histogram, JsonSchemaValidationNode, RetentionPolicy, RetentionScheduleConfig, RowClock, RowTTLPolicy, Schema, SchemaArrayItems, SchemaArrayItemsArray, SchemaArrayItemsObject, SchemaArrayItemsPrimitive, SchemaArrayProperty, SchemaFileConfig, SchemaFileConfigType, SchemaObjectProperty, SchemaPrimitiveProperty, SchemaProperties, SchemaPropertiesType, SchemaProperty, SnapshotAgeExpression, SnapshotRange, SnapshotTTLPolicy, TableClock, TableClockKind, TableTTLPolicy, TTLPolicy, TTLPolicyKind, UpdateDatasetRefreshScheduleRequest, UpdateDatasetRequest, UpsertRetentionPoliciesRequest, Value, };
 /**
  * @module DatasetApi
  * @description This module provides methods for fetching datasets.
@@ -221,6 +221,15 @@ export declare class DatasetApi extends BaseApi {
     createDatasetRefreshSchedule(datasetId: number, refreshSchedule: CreateDatasetRefreshScheduleRequest): Promise<void>;
     updateDatasetRefreshSchedule(datasetId: number, refreshSchedule: UpdateDatasetRefreshScheduleRequest): Promise<void>;
     deleteDatasetRefreshSchedule(datasetId: number): Promise<void>;
+    /**
+     * Validate which connector interfaces are compatible with a dataset.
+     * Filtered by the user's installed apps and optionally by tags.
+     *
+     * @param {number} datasetId - The ID of the dataset to validate interfaces against.
+     * @param {string[]} [tags] - Optional tags to filter interfaces (e.g. ["audience_delivery"]).
+     * @returns {Promise<DatasetInterfaceValidation>} - Accepted interface IDs and per-interface validation errors.
+     */
+    getDatasetInterfaces(datasetId: number, tags?: string[]): Promise<DatasetInterfaceValidation>;
     putStatisticsConfiguration(datasetId: number, configuration: DatasetStatisticsConfiguration): Promise<StatisticsConfigurationResponse>;
     getStatisticsConfiguration(datasetId: number): Promise<StatisticsConfigurationResponse>;
     deleteStatisticsConfiguration(datasetId: number): Promise<StatisticsConfigurationResponse>;

package/build/datasets/index.js

@@ -295,6 +295,18 @@ export class DatasetApi extends BaseApi {
     async deleteDatasetRefreshSchedule(datasetId) {
         await this.delete(`${resourceName}/${datasetId}/refresh-schedule`);
     }
+    /**
+     * Validate which connector interfaces are compatible with a dataset.
+     * Filtered by the user's installed apps and optionally by tags.
+     *
+     * @param {number} datasetId - The ID of the dataset to validate interfaces against.
+     * @param {string[]} [tags] - Optional tags to filter interfaces (e.g. ["audience_delivery"]).
+     * @returns {Promise<DatasetInterfaceValidation>} - Accepted interface IDs and per-interface validation errors.
+     */
+    async getDatasetInterfaces(datasetId, tags) {
+        const queryString = this.constructQueryString(tags != null ? { tags } : undefined);
+        return await this.get(`${resourceName}/${datasetId}/interfaces${queryString}`);
+    }
     async putStatisticsConfiguration(datasetId, configuration) {
         return await this.put(`${resourceName}/${datasetId}/statistics-configuration`, configuration);
     }

package/build/datasets/types.d.ts

@@ -294,6 +294,31 @@ export interface CreateDatasetRequest {
 export interface IngestDatasetFileRequest {
     source_file: string;
 }
+export interface DatasetInterfaceRef {
+    app_id: number;
+    interface_id: string;
+}
+/**
+ * A JSON-Schema 2020-12 "Basic" output node, used recursively in validation errors.
+ * `errors` is keyed by JSON-Schema keyword (`"required"`, `"type"`, etc.); values
+ * are human-readable strings.
+ */
+export interface JsonSchemaValidationNode {
+    valid: boolean;
+    evaluationPath: string;
+    schemaLocation: string;
+    instanceLocation: string;
+    errors?: Record<string, string>;
+    details?: JsonSchemaValidationNode[];
+}
+export interface DatasetInterfaceError extends DatasetInterfaceRef {
+    details: JsonSchemaValidationNode;
+}
+export interface DatasetInterfaceValidation {
+    dataset_id: number;
+    accepted: DatasetInterfaceRef[];
+    errors: DatasetInterfaceError[];
+}
 export interface UpdateDatasetRefreshScheduleRequest {
     cron?: string;
     cron_zone_id?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "2.102.0",
+	"version": "2.105.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -32,6 +32,7 @@
 		"@commitlint/cli": "21.0.1",
 		"@commitlint/config-conventional": "21.0.1",
 		"@types/jest": "30.0.0",
+		"@types/json-schema": "^7.0.15",
 		"babel-jest": "30.4.1",
 		"jest": "30.4.2",
 		"lefthook": "2.1.6",

package/build/collaboration-policy/core/filter-utils.d.ts

@@ -1,6 +0,0 @@
-import type { PathValue, PolicyFilter } from "./types";
-export declare function visitFilterAttributes(filter: PolicyFilter, visitor: (attributeName: string, normalizedPath: string) => void): void;
-export declare function isAttributeReference(node: unknown): node is {
-    attribute_name: string;
-    path?: PathValue;
-};