@narrative.io/data-collaboration-sdk-ts 2.64.0 → 2.65.0

package/build/collaboration-policy/types/collaboration-policy.js

@@ -0,0 +1,262 @@
+import * as z from "zod/v4";
+/** Branded types */
+const CollaborationPolicyIdentifier = z
+    .string()
+    .regex(/^[a-zA-Z0-9_-]+$/)
+    .brand("CollaborationPolicyId")
+    .meta({
+    id: "collaboration_policy_identifier",
+});
+/** Refresh Schedule Schema */
+const RefreshScheduleSchema = z
+    .object({
+    max: z.union([
+        z.enum(["@hourly", "@daily", "@weekly", "@monthly", "@once"]),
+        z
+            .string()
+            .regex(/^([0-5]?[0-9]|\*) ([01]?[0-9]|2[0-3]|\*) ([0-2]?[0-9]|3[01]|\*) ([0]?[1-9]|1[0-2]|\*) ([0-6]|\*)$/, "Invalid cron expression"),
+    ]),
+})
+    .strict()
+    .meta({
+    id: "refresh_schedule",
+});
+const CollaborationPolicyDefinitionMetadataSchema = z
+    .object({
+    tags: z.array(z.string().regex(/^[a-zA-Z0-9_-]+$/)).optional(),
+    refresh_schedule: RefreshScheduleSchema.optional(),
+})
+    .meta({ id: "metadata" });
+const JsonPointerSchema = z
+    .string()
+    .regex(/^(#\/|\/).+/, 'JSON Pointer must start with "/" or "#/".')
+    .meta({ id: "json-pointer" });
+/** Path can be dot-style or JSON Pointer */
+const PathSchema = z
+    .union([
+    z
+        .object({
+        dot: z.string().min(1, "Dot path cannot be empty"),
+    })
+        .strict(),
+    z
+        .object({
+        pointer: JsonPointerSchema,
+    })
+        .strict(),
+])
+    .meta({ id: "path" });
+/** ---------------------------
+ *  Base + contextual variants
+ *  --------------------------*/
+/**
+ * BaseAttributeRef:
+ * - supports either `attribute_name` (by name) OR `attribute` (by pointer), not both
+ * - includes both `additional_required_properties` and `path` (context will prune)
+ */
+const BaseAttributeRef = z
+    .object({
+    type: z.literal("attribute").meta({ id: "field_type" }),
+    // Choose ONE of these identifiers:
+    attribute_name: z.string().meta({ id: "attribute_name" }),
+    // Context-specific fields (trim in the derived schemas):
+    additional_required_properties: z
+        .array(PathSchema)
+        .optional()
+        .meta({ id: "additional_required_properties" }),
+    path: PathSchema.optional(),
+})
+    .strict()
+    .meta({ id: "attribute_reference" });
+/**
+ * StructureAttributeRef:
+ * - used in your “structure” (the logical tree)
+ * - allows: attribute_name + additional_required_properties
+ * - forbids: path, attribute (pointer)
+ * Example target:
+ * field: {
+ *   type: "attribute",
+ *   attribute_name: "sha256_hashed_email",
+ *   additional_required_properties: [{ dot: "type" }],
+ * }
+ */
+const StructureAttributeRef = BaseAttributeRef.omit({
+    path: true,
+}).meta({ id: "structure_attribute_reference" });
+/**
+ * FilterAttributeRef:
+ * - used inside filters
+ * - allows: attribute (pointer) + optional path
+ * - forbids: additional_required_properties, attribute_name
+ * Example target:
+ * left: {
+ *   type: "attribute",
+ *   attribute: "https://api.narrative.io/attributes/iso_3166_1_country",
+ *   path: { dot: "value" },
+ * }
+ */
+const FilterAttributeRef = BaseAttributeRef.omit({
+    additional_required_properties: true,
+}).meta({ id: "filter_attribute_reference" });
+// Now Expression can reference Filter without a lazy;
+// the recursive bits inside Filter are handled by getters.
+const Expression = z
+    .union([
+    z
+        .string()
+        .refine((s) => !s.startsWith("https://api.narrative.io/attributes/"), "String expression cannot be a JSON pointer; use { type:'attribute', attribute: ... }"),
+    z.number(),
+    z.boolean(),
+    FilterAttributeRef,
+])
+    .meta({ id: "expression" });
+const FilterAndOr = z
+    .object({
+    op: z.enum(["and", "or"]),
+    stage: z.literal("generation").default("generation"),
+    name: z.string().optional(),
+    required: z.boolean().default(true),
+    get args() {
+        return z.array(Expression).min(2);
+    },
+})
+    .strict();
+const FilterNot = z
+    .object({
+    op: z.literal("not"),
+    stage: z.literal("generation").default("generation"),
+    name: z.string().optional(),
+    required: z.boolean().default(true),
+    get args() {
+        return z.array(Expression).length(1);
+    },
+})
+    .strict();
+const FilterIsNull = z
+    .object({
+    op: z.enum(["is_null", "is_not_null"]),
+    stage: z.literal("generation").default("generation"),
+    name: z.string().optional(),
+    required: z.boolean().default(true),
+    get left() {
+        return Expression;
+    },
+})
+    .strict();
+const FilterIn = z
+    .object({
+    op: z.enum(["in", "not in"]),
+    stage: z.literal("generation").default("generation"),
+    name: z.string().optional(),
+    required: z.boolean().default(true),
+    get left() {
+        return Expression;
+    },
+    get right() {
+        return z.array(Expression).min(1);
+    },
+})
+    .strict();
+const FilterCompare = z
+    .object({
+    op: z.enum(["=", "<>", ">", ">=", "<", "<=", "like", "not like"]),
+    stage: z.literal("generation").default("generation"),
+    name: z.string().optional(),
+    required: z.boolean().default(true),
+    get left() {
+        return Expression;
+    },
+    get right() {
+        return Expression;
+    },
+})
+    .strict();
+const FilterBetween = z
+    .object({
+    op: z.literal("between"),
+    stage: z.literal("generation").default("generation"),
+    name: z.string().optional(),
+    required: z.boolean().default(true),
+    get operand() {
+        return Expression;
+    },
+    get lower() {
+        return Expression;
+    },
+    get upper() {
+        return Expression;
+    },
+})
+    .strict();
+const Filter = z
+    .union([
+    FilterAndOr,
+    FilterNot,
+    FilterIsNull,
+    FilterIn,
+    FilterCompare,
+    FilterBetween,
+])
+    .meta({ id: "filter" });
+const logicalTree = (leaf) => {
+    const NodeSchema = z.lazy(() => z
+        .union([
+        z
+            .object({
+            anyOf: z
+                .array(z.union([leaf, NodeSchema]))
+                .min(1)
+                .meta({ id: "any_of" }),
+        })
+            .strict()
+            .meta({ id: "any_of_object" }),
+        z
+            .object({
+            allOf: z
+                .array(z.union([leaf, NodeSchema]))
+                .min(1)
+                .meta({ id: "all_of" }),
+        })
+            .strict()
+            .meta({ id: "all_of_object" }),
+    ])
+        .meta({ id: "logical_node" }));
+    // Top-level can be a leaf T or a logical node.
+    return z.union([leaf, NodeSchema]).meta({ id: "logical_tree" });
+};
+const ExtendedAttribute = z
+    .object({
+    field: StructureAttributeRef,
+    filters: z.array(Filter).optional(),
+})
+    .meta({ id: "extended_attribute" });
+const CollaborationPolicyDefinitionShape = z
+    .object({
+    id: CollaborationPolicyIdentifier,
+    structure: logicalTree(ExtendedAttribute).meta({ id: "structure" }),
+    filters: z.array(Filter).optional(),
+})
+    .meta({ id: "shape" });
+const CollaborationPolicyDefinition = z
+    .object({
+    metadata: CollaborationPolicyDefinitionMetadataSchema,
+    definition: CollaborationPolicyDefinitionShape,
+})
+    .meta({ id: "policy_definition" });
+const CollaborationPolicy = z
+    .object({
+    name: CollaborationPolicyIdentifier,
+    description: z.string().max(2000).optional(),
+    display_name: z.string().max(255),
+    policy: CollaborationPolicyDefinition,
+})
+    .meta({ id: "policy" });
+// Export the schema for validation
+export { CollaborationPolicy };
+export function buildCollaborationPolicyJsonSchema(options = {}) {
+    const override = (options ?? {});
+    return z.toJSONSchema(CollaborationPolicy, {
+        reused: "ref",
+        ...override,
+    });
+}

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

@@ -0,0 +1,2 @@
+export type { CollaborationPolicyInput, CollaborationPolicyType, } from "./collaboration-policy";
+export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./collaboration-policy";

package/build/collaboration-policy/types/index.js

@@ -0,0 +1 @@
+export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./collaboration-policy";

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

@@ -0,0 +1,8 @@
+import type { Attribute } from "../attributes/types";
+import type { Dataset } from "../datasets/types";
+import type { PolicySqlFragments } from "./core/types";
+import type { CollaborationPolicyType } from "./types";
+export default function useCollaborationPolicy(): {
+    getEligibleConnectorsPolicies: (dataset: Dataset, policies: CollaborationPolicyType[], attributes: Attribute[]) => CollaborationPolicyType[];
+    buildPolicySqlFragments: (dataset: Dataset, policies: CollaborationPolicyType[], attributes: Attribute[]) => PolicySqlFragments;
+};

package/build/collaboration-policy/useCollaborationPolicy.js

@@ -0,0 +1,14 @@
+import { buildPolicySql, categorizePolicies } from "./core/sql-builder";
+export default function useCollaborationPolicy() {
+    const getEligibleConnectorsPolicies = (dataset, policies, attributes) => {
+        const { matching } = categorizePolicies(policies, dataset, attributes);
+        return matching;
+    };
+    const buildPolicySqlFragments = (dataset, policies, attributes) => {
+        return buildPolicySql(dataset, policies, attributes);
+    };
+    return {
+        getEligibleConnectorsPolicies,
+        buildPolicySqlFragments,
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { Attribute } from "../../attributes/types";
+import type { AttributePathIndex, PathValue } from "../core/types";
+export declare function markAttributePath(index: AttributePathIndex, attribute: Attribute, path: string): void;
+export declare function normalizePathValue(path?: PathValue): string;

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

@@ -0,0 +1,36 @@
+export function markAttributePath(index, attribute, path) {
+    const attributePaths = index.get(attribute.name) ?? new Set();
+    const normalized = 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 "";
+}
+export function normalizePathValue(path) {
+    if (!path) {
+        return "";
+    }
+    if ("dot" in path) {
+        return path.dot;
+    }
+    const pointer = path.pointer;
+    let trimmed = pointer.startsWith("#/") ? pointer.slice(2) : pointer;
+    if (trimmed.startsWith("/")) {
+        trimmed = trimmed.slice(1);
+    }
+    const parts = trimmed
+        .split("/")
+        .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+    return parts.join(".");
+}

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

@@ -0,0 +1,5 @@
+import type { Attribute } from "../../attributes/types";
+export declare function resolveAttributeExpression(attribute: Attribute, path: string, datasetName: string): string;
+export declare function buildSelectAlias(attributeName: string, path: string): string;
+export declare function buildPolicyWhereGroups(policyWhereClauses: string[][]): string[];
+export declare function formatWhereClause(policyWhereClauses: string[][]): string;

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

@@ -0,0 +1,65 @@
+export function resolveAttributeExpression(attribute, path, datasetName) {
+    // Use standardized company_data format with proper SQL identifier quoting
+    const quotedDatasetName = quoteIdentifier(datasetName);
+    const quotedRosettaStone = quoteIdentifier("_rosetta_stone");
+    const quotedAttributeName = quoteIdentifier(attribute.name);
+    const basePath = `company_data.${quotedDatasetName}.${quotedRosettaStone}.${quotedAttributeName}`;
+    if (!path) {
+        return basePath;
+    }
+    // Handle different path formats and quote each path segment
+    let pathSegments;
+    if (path.includes(".")) {
+        // Already dot notation (e.g., "some.nested.path")
+        pathSegments = path.split(".");
+    }
+    else if (path.includes("/")) {
+        // JSON pointer format was normalized but still has slashes
+        // This shouldn't happen after normalizePathValue, but handle it just in case
+        pathSegments = path.split("/");
+    }
+    else {
+        // Simple property name (e.g., "value", "type")
+        pathSegments = [path];
+    }
+    // Quote each path segment and join with dots
+    const quotedPathSegments = pathSegments
+        .filter((segment) => segment.length > 0)
+        .map((segment) => quoteIdentifier(segment));
+    return `${basePath}.${quotedPathSegments.join(".")}`;
+}
+export function buildSelectAlias(attributeName, path) {
+    if (!path) {
+        return quoteIdentifier(attributeName);
+    }
+    const suffix = path.replace(/[^a-zA-Z0-9]+/g, "_");
+    return quoteIdentifier(`${attributeName}_${suffix}`);
+}
+export function buildPolicyWhereGroups(policyWhereClauses) {
+    const groups = [];
+    for (const clauses of policyWhereClauses) {
+        if (clauses.length === 0) {
+            continue;
+        }
+        const firstClause = clauses[0];
+        if (firstClause === undefined) {
+            continue;
+        }
+        groups.push(clauses.length === 1 ? firstClause : `(${clauses.join(" AND ")})`);
+    }
+    return groups;
+}
+export function formatWhereClause(policyWhereClauses) {
+    const groups = buildPolicyWhereGroups(policyWhereClauses);
+    if (groups.length === 0) {
+        return "";
+    }
+    if (groups.length === 1) {
+        return `\nWHERE\n  ${groups[0]}`;
+    }
+    return `\nWHERE\n  ${groups.join(" OR\n  ")}`;
+}
+function quoteIdentifier(identifier) {
+    const safe = identifier.replace(/"/g, "");
+    return `"${safe}"`;
+}

package/build/datasets/index.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -178,15 +179,15 @@ export declare class DatasetApi extends BaseApi {
      */
     deleteDatasetSample(datasetId: number): Promise<void>;
     /**
-     * Refreshes the materlized view for the given dataset id.
+     * Refreshes the materialized view for the given dataset id.
      *
      * @param {number} datasetId - The ID of the dataset for which to refresh the materialized view.
-     * @returns {Promise<AdvancedStatistics>} A Promise that resolves on success.
+     * @returns {Promise<UnknownJob>} A Promise that resolves with a job object to track the refresh operation.
      * @throws {Error} If there is an issue with the request or the response.
      * @memberof DatasetApi
      * @public
      */
-    refreshMaterializedView(datasetId: number): Promise<void>;
+    refreshMaterializedView(datasetId: number): Promise<UnknownJob>;
     createDatasetRefreshSchedule(datasetId: number, refreshSchedule: CreateDatasetRefreshScheduleRequest): Promise<void>;
     updateDatasetRefreshSchedule(datasetId: number, refreshSchedule: UpdateDatasetRefreshScheduleRequest): Promise<void>;
     deleteDatasetRefreshSchedule(datasetId: number): Promise<void>;

package/build/datasets/index.js

@@ -217,10 +217,10 @@ export class DatasetApi extends BaseApi {
         await this.delete(`${resourceName}/${datasetId}/sample`);
     }
     /**
-     * Refreshes the materlized view for the given dataset id.
+     * Refreshes the materialized view for the given dataset id.
      *
      * @param {number} datasetId - The ID of the dataset for which to refresh the materialized view.
-     * @returns {Promise<AdvancedStatistics>} A Promise that resolves on success.
+     * @returns {Promise<UnknownJob>} A Promise that resolves with a job object to track the refresh operation.
      * @throws {Error} If there is an issue with the request or the response.
      * @memberof DatasetApi
      * @public

package/build/index.d.ts

@@ -5,6 +5,7 @@ export type { App } from "./apps";
 export * from "./attributes";
 export * from "./authentication";
 export * from "./base-api";
+export * from "./collaboration-policy";
 export * from "./company-info";
 export * from "./connections";
 export * from "./contracts";

package/build/index.js

@@ -5,6 +5,7 @@ export { resources } from "./access-tokens/types";
 export * from "./attributes";
 export * from "./authentication";
 export * from "./base-api";
+export * from "./collaboration-policy";
 export * from "./company-info";
 export * from "./connections";
 export * from "./contracts";

package/build/jobs/index.d.ts

@@ -5,6 +5,9 @@ interface GetJobsParameters extends Record<string, string | number | boolean | u
     dataset_id?: number;
     per_page?: number;
     offset?: number;
+    order_by?: "created_at_asc" | "created_at_desc";
+    state?: "cancelled" | "completed" | "failed" | "pending" | "pending_cancellation" | "running";
+    type?: string;
 }
 /**
  * @module JobsApi

package/build/jobs/types.d.ts

@@ -58,6 +58,13 @@ export interface MaterializedViewInput {
     budget: NqlBudget;
     dataset_id: number;
     stats_enabled: boolean;
+    chunk_metadata?: {
+        batch_id: string;
+        chunk_sequence: {
+            number: number;
+            of: number;
+        };
+    };
 }
 export interface MaterializedViewOutput {
     success: {

package/build/nql/AstParser.js

@@ -196,8 +196,8 @@ function parseColumnRef(n) {
                 return attrRef;
             }
             if (n.schema === "company_data" &&
-                !Number.isNaN(Number.parseInt(n.table))) {
-                const datasetId = Number.parseInt(n.table);
+                !Number.isNaN(Number.parseInt(n.table, 10))) {
+                const datasetId = Number.parseInt(n.table, 10);
                 const datasetColumnRef = {
                     type: "dataset_column_ref",
                     as: n.as,
@@ -442,8 +442,9 @@ function parseTable(n) {
         };
         return table;
     }
-    if (n.schema === "company_data" && !Number.isNaN(Number.parseInt(n.table))) {
-        const datasetId = Number.parseInt(n.table);
+    if (n.schema === "company_data" &&
+        !Number.isNaN(Number.parseInt(n.table, 10))) {
+        const datasetId = Number.parseInt(n.table, 10);
         const table = {
             type: "dataset",
             as: n.as,

package/build/nql/NqlBuilder.js

@@ -331,7 +331,7 @@ function compileLit(value, valueType, as, aliasParens) {
                 break;
             }
             case "long":
-                valueNql = `${Number.parseInt(value)}`;
+                valueNql = `${Number.parseInt(value, 10)}`;
                 break;
             case "double":
                 valueNql = `${Number.parseFloat(value)}`;

package/build/nql/types.d.ts

@@ -293,6 +293,18 @@ export declare const NqlObj: z.ZodObject<{
     join: z.ZodUndefined;
 }, z.core.$strip>;
 export type Nql = z.infer<typeof NqlObj>;
+export interface RelatedJob {
+    id: string;
+    number: number;
+    idempotency_key: string;
+    state: string;
+    compiled_select: string;
+}
+export interface BatchInfo {
+    batch_id: string;
+    batch_size: number;
+    related_jobs: RelatedJob[];
+}
 export interface NqlResult {
     id: string;
     company_id: number;
@@ -318,6 +330,7 @@ export interface NqlResult {
     };
     state: string;
     updated_at: string;
+    chunking_context?: BatchInfo;
 }
 export type NqlMappingErrors = Record<number, string>;
 export interface NqlCompileResult {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "2.64.0",
+	"version": "2.65.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -20,21 +20,21 @@
 	"author": "",
 	"license": "ISC",
 	"devDependencies": {
-		"@babel/core": "7.28.0",
-		"@babel/preset-env": "7.28.0",
+		"@babel/core": "7.28.3",
+		"@babel/preset-env": "7.28.3",
 		"@babel/preset-typescript": "7.27.1",
-		"@biomejs/biome": "2.1.3",
-		"@commitlint/cli": "19.8.1",
-		"@commitlint/config-conventional": "19.8.1",
+		"@biomejs/biome": "2.2.2",
+		"@commitlint/cli": "20.0.0",
+		"@commitlint/config-conventional": "20.0.0",
 		"@types/jest": "30.0.0",
-		"babel-jest": "30.0.5",
-		"jest": "30.0.5",
-		"lefthook": "1.12.2",
-		"ts-jest": "29.4.0"
+		"babel-jest": "30.1.0",
+		"jest": "30.1.0",
+		"lefthook": "1.12.3",
+		"ts-jest": "29.4.1"
 	},
 	"dependencies": {
 		"mande": "2.0.9",
-		"zod": "4.0.14",
+		"zod": "4.1.3",
 		"bignumber.js": "9.3.1"
 	},
 	"overrides": {