@narrative.io/data-collaboration-sdk-ts 2.94.1 → 2.95.0-beta.0

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

@@ -41,30 +41,34 @@ function parseDurationToMilliseconds(duration) {
  * The smallest duration means the most frequent refresh rate.
  *
  * @param schedules - Array of ISO 8601 duration strings
- * @returns The smallest duration in milliseconds, or 2592000000 (30 days/1 month) if no schedules provided
+ * @returns The smallest duration as an ISO 8601 string, or "P1M" (1 month) if no schedules provided
  */
 function getSmallestRefreshSchedule(schedules) {
-    // Default to monthly (30 days in milliseconds)
-    const defaultMonthlyMs = 30 * 24 * 60 * 60 * 1000;
+    // Default to monthly
+    const defaultMonthly = "P1M";
     if (schedules.length === 0) {
-        return defaultMonthlyMs;
+        return defaultMonthly;
     }
     if (schedules.length === 1) {
         try {
-            return parseDurationToMilliseconds(schedules[0]);
+            // Validate by parsing, but return the original string
+            parseDurationToMilliseconds(schedules[0]);
+            return schedules[0];
         }
         catch (error) {
             console.warn(`Invalid refresh schedule: ${schedules[0]}, using default`, error);
-            return defaultMonthlyMs;
+            return defaultMonthly;
         }
     }
     // Find the schedule with the smallest duration (most frequent refresh)
     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 (error) {
@@ -73,9 +77,7 @@ function getSmallestRefreshSchedule(schedules) {
         }
     }
     // If all schedules failed to parse, return default
-    return smallestValue === Number.MAX_SAFE_INTEGER
-        ? defaultMonthlyMs
-        : smallestValue;
+    return smallestSchedule ?? defaultMonthly;
 }
 /**
  * Builds structured WHERE clauses for a single branch node

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

@@ -1,8 +1,8 @@
 import type { UnknownJob } from "src/jobs/types";
 import { BaseApi } from "../base-api";
 import type { ApiRecords } from "../types";
-import type { AdvancedStatistics, AdvancedStatisticsMetadata, BasicStatistics, ColumnStatistics, ColumnSummary, Columns, Configuration, CreateDatasetRefreshScheduleRequest, CreateDatasetRequest, Dataset, DatasetStatus, DatasetTableSummary, DatasetTableSummaryAPIResponse, DatasetWriteMode, FilePerSnapshotResponse, Histogram, IngestDatasetFileRequest, RecalculationInfo, RetentionPolicy, Schema, SchemaArrayItems, SchemaArrayItemsArray, SchemaArrayItemsObject, SchemaArrayItemsPrimitive, SchemaArrayProperty, SchemaFileConfig, SchemaFileConfigType, SchemaObjectProperty, SchemaPrimitiveProperty, SchemaProperties, SchemaPropertiesType, SchemaProperty, SnapshotRange, UpdateDatasetRefreshScheduleRequest, UpdateDatasetRequest, Value } from "./types";
-export type { FilePerSnapshotResponse, Dataset, RetentionPolicy, DatasetTableSummaryAPIResponse, ColumnStatistics, UpdateDatasetRequest, SchemaFileConfigType, SchemaPropertiesType, DatasetStatus, DatasetWriteMode, SchemaFileConfig, SchemaProperties, SchemaProperty, SchemaPrimitiveProperty, SchemaObjectProperty, SchemaArrayProperty, SchemaArrayItems, SchemaArrayItemsPrimitive, SchemaArrayItemsObject, SchemaArrayItemsArray, Schema, AdvancedStatisticsMetadata, SnapshotRange, Configuration, Columns, ColumnSummary, BasicStatistics, AdvancedStatistics, Histogram, Value, CreateDatasetRequest, UpdateDatasetRefreshScheduleRequest, CreateDatasetRefreshScheduleRequest, };
+import type { AdvancedStatistics, AdvancedStatisticsMetadata, BasicStatistics, ColumnStatistics, ColumnSummary, Columns, Configuration, CreateDatasetRefreshScheduleRequest, CreateDatasetRequest, Dataset, DatasetInterfaceValidation, DatasetStatus, DatasetTableSummary, DatasetTableSummaryAPIResponse, DatasetWriteMode, FilePerSnapshotResponse, Histogram, IngestDatasetFileRequest, RecalculationInfo, RetentionPolicy, Schema, SchemaArrayItems, SchemaArrayItemsArray, SchemaArrayItemsObject, SchemaArrayItemsPrimitive, SchemaArrayProperty, SchemaFileConfig, SchemaFileConfigType, SchemaObjectProperty, SchemaPrimitiveProperty, SchemaProperties, SchemaPropertiesType, SchemaProperty, SnapshotRange, UpdateDatasetRefreshScheduleRequest, UpdateDatasetRequest, Value } from "./types";
+export type { FilePerSnapshotResponse, Dataset, RetentionPolicy, DatasetTableSummaryAPIResponse, ColumnStatistics, UpdateDatasetRequest, SchemaFileConfigType, SchemaPropertiesType, DatasetStatus, DatasetWriteMode, SchemaFileConfig, SchemaProperties, SchemaProperty, SchemaPrimitiveProperty, SchemaObjectProperty, SchemaArrayProperty, SchemaArrayItems, SchemaArrayItemsPrimitive, SchemaArrayItemsObject, SchemaArrayItemsArray, Schema, AdvancedStatisticsMetadata, SnapshotRange, Configuration, Columns, ColumnSummary, BasicStatistics, AdvancedStatistics, Histogram, Value, CreateDatasetRequest, UpdateDatasetRefreshScheduleRequest, CreateDatasetRefreshScheduleRequest, DatasetInterfaceValidation, };
 /**
  * @module DatasetApi
  * @description This module provides methods for fetching datasets.
@@ -215,4 +215,13 @@ 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>;
 }

package/build/datasets/index.js

@@ -287,4 +287,16 @@ 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}`);
+    }
 }

package/build/datasets/types.d.ts

@@ -244,6 +244,10 @@ export interface CreateDatasetRequest {
 export interface IngestDatasetFileRequest {
     source_file: string;
 }
+export interface DatasetInterfaceValidation {
+    accepted: string[];
+    errors: Record<string, string[]>;
+}
 export interface UpdateDatasetRefreshScheduleRequest {
     cron?: string;
     cron_zone_id?: string;