@narrative.io/data-collaboration-sdk-ts 2.64.1 → 2.66.0

package/README.md

@@ -313,4 +313,140 @@ try {
 
 ## API Reference
 
-For detailed API documentation, please visit the [Narrative.io API Documentation](https://api.narrative.dev).
+For detailed API documentation, please visit the [Narrative.io API Documentation](https://api.narrative.dev).
+
+## Local Development: Use This SDK Locally in a Consumer App (No Publish Needed)
+
+You can link this SDK into another repo (e.g., a Nuxt 3 app) and iterate without publishing to npm each time. Two supported flows:
+
+- **Linked mode (fastest)** — symlink your local SDK into the app
+- **Tarball mode (exact publish parity)** — install from a local `npm pack` tarball
+
+Both approaches use the SDK’s **built output** in `build/`, exactly like the published package.
+
+### Prerequisites
+
+- Node & npm
+- This repo builds TypeScript to `build/`
+- This repo includes `scripts/ensureBuild.js` to verify artifacts exist
+
+```bash
+# In the SDK repo (this one)
+npm i
+npm run build              # one-time; emits build/**
+node scripts/ensureBuild.js
+```
+
+---
+
+### Option A — Linked Mode (Fastest Dev Feedback)
+
+1. **Keep the SDK building on save**
+   In the SDK repo (leave this running):
+   ```bash
+   npm run dev             # tsc -w → continuously updates build/**
+   ```
+
+2. **Register the SDK globally**
+   In the SDK repo (new terminal):
+   ```bash
+   npm run link:global     # runs ensureBuild + npm link
+   ```
+
+3. **Link into your consumer app**
+   In your app repo (e.g., Nuxt project):
+   ```bash
+   # optional safety if a link exists
+   npm unlink @narrative.io/data-collaboration-sdk-ts --no-save || true
+
+   # link the globally-registered SDK into this app’s node_modules
+   npm link @narrative.io/data-collaboration-sdk-ts
+   ```
+
+4. **Verify the app resolves to your local SDK**
+   ```bash
+   node -e "console.log(require.resolve('@narrative.io/data-collaboration-sdk-ts/package.json'))"
+   ```
+   You should see a path inside your SDK repo (not a versioned folder under the app’s `node_modules`).
+
+5. **Run your app**
+   ```bash
+   npm run dev
+   ```
+   Edit files under `SDK/src/**` → the watcher writes to `build/**` → your app hot-reloads.
+
+**Revert to the registry version (in the app):**
+```bash
+npm unlink @narrative.io/data-collaboration-sdk-ts --no-save
+npm i
+```
+
+---
+
+### Option B — Tarball Mode (Exact Publish Parity)
+
+1. **Pack the SDK (same artifact you would publish)**
+   ```bash
+   # in the SDK repo
+   npm run build
+   npm pack                 # creates ./<name>-<version>.tgz
+   ```
+
+2. **Install the tarball in the app**
+   ```bash
+   # in the app repo
+   npm i /ABS/PATH/TO/<name>-<version>.tgz
+   npm run dev
+   ```
+
+**Revert to a registry version (in the app):**
+```bash
+npm i @narrative.io/data-collaboration-sdk-ts@<semver>
+```
+
+---
+
+### Troubleshooting (Nuxt 3 / Vite / SSR)
+
+- **“Cannot use import statement outside a module” (SSR):** Inline the SDK so Nitro bundles it.
+  ```ts
+  // nuxt.config.ts
+  export default defineNuxtConfig({
+    nitro: { externals: { inline: ['@narrative.io/data-collaboration-sdk-ts'] } }
+  })
+  ```
+
+- **Build artifacts not updating:** Ensure `npm run dev` is running in the SDK repo (TypeScript watch), and that the app is linked (or reinstalled from a fresh tarball).
+
+- **Accidental imports from `src/*`:** Consumers should import from the package root only. This SDK publishes `build/**` and defines `main`/`types` (and may include an `exports` map) to prevent `src/*` imports.
+
+- **Type/version drift (e.g., Zod):** If your app and the SDK use different major versions of a library whose types appear in public APIs, align versions or declare that library as a `peerDependency` in the SDK.
+
+---
+
+### Quick Reference
+
+```bash
+# SDK (this repo)
+npm i
+npm run build
+npm run dev
+npm run link:global
+
+# App (consumer repo)
+npm unlink @narrative.io/data-collaboration-sdk-ts --no-save || true
+npm link @narrative.io/data-collaboration-sdk-ts
+npm run dev
+```
+
+Alternative (publish-parity):
+
+```bash
+# SDK
+npm run build
+npm pack
+
+# App
+npm i /ABS/PATH/TO/*.tgz
+npm run dev
+```

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

@@ -0,0 +1,3 @@
+import type { Attribute } from "../../attributes/types";
+import type { PolicyFilter } from "./types";
+export declare function filterToSql(filter: PolicyFilter, attributeByName: Map<string, Attribute>, datasetName: string): string;

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

@@ -0,0 +1,90 @@
+import { normalizePathValue } from "../utils/path-helpers";
+import { resolveAttributeExpression } from "../utils/sql-helpers";
+import { isAttributeReference } from "./filter-utils";
+export function filterToSql(filter, attributeByName, datasetName) {
+    const op = filter.op.toLowerCase();
+    switch (op) {
+        case "and":
+        case "or": {
+            const args = filter.args;
+            if (!Array.isArray(args) || args.length === 0) {
+                throw new Error(`Logical filter "${filter.op}" requires at least one argument.`);
+            }
+            const pieces = args.map((arg) => expressionToSql(arg, attributeByName, datasetName));
+            const joiner = op === "and" ? " AND " : " OR ";
+            return `(${pieces.join(joiner)})`;
+        }
+        case "not": {
+            const args = filter.args;
+            if (!Array.isArray(args) || args.length !== 1) {
+                throw new Error("NOT filter must have exactly one argument.");
+            }
+            return `(NOT ${expressionToSql(args[0], attributeByName, datasetName)})`;
+        }
+        case "is_null":
+        case "is_not_null": {
+            const left = filter.left;
+            const leftSql = expressionToSql(left, attributeByName, datasetName);
+            return `(${leftSql} ${op === "is_null" ? "IS NULL" : "IS NOT NULL"})`;
+        }
+        case "in":
+        case "not in": {
+            const left = filter.left;
+            const right = filter.right;
+            if (!Array.isArray(right) || right.length === 0) {
+                throw new Error(`Filter "${filter.op}" requires a non-empty array of values.`);
+            }
+            const leftSql = expressionToSql(left, attributeByName, datasetName);
+            const rightSql = right
+                .map((value) => expressionToSql(value, attributeByName, datasetName))
+                .join(", ");
+            const operator = op === "in" ? "IN" : "NOT IN";
+            return `(${leftSql} ${operator} (${rightSql}))`;
+        }
+        case "between": {
+            const operand = filter.operand;
+            const lower = filter.lower;
+            const upper = filter.upper;
+            const operandSql = expressionToSql(operand, attributeByName, datasetName);
+            const lowerSql = expressionToSql(lower, attributeByName, datasetName);
+            const upperSql = expressionToSql(upper, attributeByName, datasetName);
+            return `(${operandSql} BETWEEN ${lowerSql} AND ${upperSql})`;
+        }
+        default: {
+            const left = filter.left;
+            const right = filter.right;
+            const leftSql = expressionToSql(left, attributeByName, datasetName);
+            const rightSql = expressionToSql(right, attributeByName, datasetName);
+            return `(${leftSql} ${filter.op} ${rightSql})`;
+        }
+    }
+}
+function expressionToSql(expression, attributeByName, datasetName) {
+    if (expression === null || expression === undefined) {
+        throw new Error("Filter expressions cannot be null or undefined.");
+    }
+    if (typeof expression === "number") {
+        return expression.toString();
+    }
+    if (typeof expression === "boolean") {
+        return expression ? "TRUE" : "FALSE";
+    }
+    if (typeof expression === "string") {
+        return `'${expression.replace(/'/g, "''")}'`;
+    }
+    if (typeof expression === "object") {
+        if (isAttributeReference(expression)) {
+            const attributeName = expression.attribute_name;
+            const attribute = attributeByName.get(attributeName);
+            if (!attribute) {
+                throw new Error(`Attribute "${attributeName}" referenced in filter but not provided.`);
+            }
+            const path = normalizePathValue(expression.path);
+            return resolveAttributeExpression(attribute, path, datasetName);
+        }
+        if ("op" in expression) {
+            return filterToSql(expression, attributeByName, datasetName);
+        }
+    }
+    throw new Error(`Unsupported filter expression: ${JSON.stringify(expression)}`);
+}

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

@@ -0,0 +1,6 @@
+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;
+};

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

@@ -0,0 +1,49 @@
+import { normalizePathValue } from "../utils/path-helpers";
+export function visitFilterAttributes(filter, visitor) {
+    traverseFilter(filter, visitor);
+}
+function traverseFilter(node, visitor) {
+    if (!node || typeof node !== "object") {
+        return;
+    }
+    if (isAttributeReference(node)) {
+        const normalizedPath = normalizePathValue(node.path);
+        visitor(node.attribute_name, normalizedPath);
+        return;
+    }
+    if ("left" in node) {
+        traverseFilter(node.left, visitor);
+    }
+    if ("right" in node) {
+        const right = node.right;
+        if (Array.isArray(right)) {
+            for (const item of right) {
+                traverseFilter(item, visitor);
+            }
+        }
+        else {
+            traverseFilter(right, visitor);
+        }
+    }
+    if ("args" in node && Array.isArray(node.args)) {
+        for (const arg of node.args) {
+            traverseFilter(arg, visitor);
+        }
+    }
+    if ("operand" in node) {
+        traverseFilter(node.operand, visitor);
+    }
+    if ("lower" in node) {
+        traverseFilter(node.lower, visitor);
+    }
+    if ("upper" in node) {
+        traverseFilter(node.upper, visitor);
+    }
+}
+export function isAttributeReference(node) {
+    return (!!node &&
+        typeof node === "object" &&
+        "type" in node &&
+        node.type === "attribute" &&
+        "attribute_name" in node);
+}

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

@@ -0,0 +1,4 @@
+import type { Attribute } from "../../attributes/types";
+import type { CollaborationPolicyType } from "../types";
+import type { AttributePathIndex } from "./types";
+export declare function traversePolicy(policy: CollaborationPolicyType, attributeByName: Map<string, Attribute>, requiredAttributePaths: AttributePathIndex, whereClauses: Set<string>, datasetName: string): void;

package/build/collaboration-policy/core/policy-traverser.js

@@ -0,0 +1,100 @@
+import { markAttributePath, normalizePathValue } from "../utils/path-helpers";
+import { filterToSql } from "./filter-builder";
+import { visitFilterAttributes } from "./filter-utils";
+export function traversePolicy(policy, attributeByName, requiredAttributePaths, whereClauses, datasetName) {
+    const definition = policy.policy.definition;
+    // Only traverse satisfied parts of the structure
+    traverseSatisfiedStructure(definition.structure, attributeByName, (node) => {
+        const field = node.field;
+        const attributeName = field.attribute_name;
+        const attribute = attributeByName.get(attributeName);
+        if (!attribute) {
+            throw new Error(`Attribute "${attributeName}" referenced in policy but not provided.`);
+        }
+        // Always mark the root attribute (without path) for SELECT clause
+        markAttributePath(requiredAttributePaths, attribute, normalizePathValue(undefined));
+        if (field.additional_required_properties) {
+            for (const path of field.additional_required_properties) {
+                // Add IS NOT NULL filter for each additional required property
+                const pathStr = normalizePathValue(path);
+                const expression = `company_data."${datasetName}"."_rosetta_stone"."${attribute.name}"."${pathStr}"`;
+                whereClauses.add(`(${expression} IS NOT NULL)`);
+            }
+        }
+        if (node.filters) {
+            for (const filter of node.filters) {
+                visitFilterAttributes(filter, (attributeName, path) => {
+                    const attribute = attributeByName.get(attributeName);
+                    if (!attribute) {
+                        throw new Error(`Attribute "${attributeName}" referenced in filter but not provided.`);
+                    }
+                    markAttributePath(requiredAttributePaths, attribute, path);
+                });
+                const sql = filterToSql(filter, attributeByName, datasetName);
+                whereClauses.add(sql);
+            }
+        }
+    });
+    if (definition.filters) {
+        for (const filter of definition.filters) {
+            visitFilterAttributes(filter, (attributeName, path) => {
+                const attribute = attributeByName.get(attributeName);
+                if (!attribute) {
+                    throw new Error(`Attribute "${attributeName}" referenced in filter but not provided.`);
+                }
+                markAttributePath(requiredAttributePaths, attribute, path);
+            });
+            const sql = filterToSql(filter, attributeByName, datasetName);
+            whereClauses.add(sql);
+        }
+    }
+}
+function traverseSatisfiedStructure(node, attributeByName, visitor) {
+    if (!node || typeof node !== "object") {
+        return;
+    }
+    if ("field" in node) {
+        visitor(node);
+        return;
+    }
+    if ("anyOf" in node && Array.isArray(node.anyOf)) {
+        // For anyOf, only traverse the FIRST satisfied branch
+        for (const child of node.anyOf) {
+            if (isBranchSatisfied(child, attributeByName)) {
+                traverseSatisfiedStructure(child, attributeByName, visitor);
+                return; // Only process the first satisfied branch
+            }
+        }
+        return;
+    }
+    if ("allOf" in node && Array.isArray(node.allOf)) {
+        // For allOf, traverse all branches (they must all be satisfied)
+        for (const child of node.allOf) {
+            traverseSatisfiedStructure(child, attributeByName, visitor);
+        }
+    }
+}
+function isBranchSatisfied(node, attributeByName) {
+    if (!node || typeof node !== "object") {
+        return true;
+    }
+    if ("field" in node) {
+        const field = node
+            .field;
+        if (field.type === "attribute") {
+            const attributeName = field.attribute_name;
+            // Only check if attribute exists, not mappings since we use company_data format
+            return attributeByName.has(attributeName);
+        }
+        return true;
+    }
+    if ("anyOf" in node && Array.isArray(node.anyOf)) {
+        // For anyOf, at least one child must be satisfied
+        return node.anyOf.some((child) => isBranchSatisfied(child, attributeByName));
+    }
+    if ("allOf" in node && Array.isArray(node.allOf)) {
+        // For allOf, all children must be satisfied
+        return node.allOf.every((child) => isBranchSatisfied(child, attributeByName));
+    }
+    return true;
+}

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

@@ -0,0 +1,11 @@
+import type { Attribute } from "../../attributes/types";
+import type { Dataset } from "../../datasets/types";
+import type { CollaborationPolicyType } from "../types";
+interface PolicyValidationResult {
+    isValid: boolean;
+    missingAttributes: string[];
+    missingMappings: string[];
+    errors: string[];
+}
+export declare function validatePolicyAgainstDataset(policy: CollaborationPolicyType, _dataset: Dataset, attributes: Attribute[]): PolicyValidationResult;
+export {};

package/build/collaboration-policy/core/policy-validator.js

@@ -0,0 +1,148 @@
+import { visitFilterAttributes } from "./filter-utils";
+export function validatePolicyAgainstDataset(policy, _dataset, attributes) {
+    const result = {
+        isValid: true,
+        missingAttributes: [],
+        missingMappings: [],
+        errors: [],
+    };
+    const attributeByName = new Map();
+    for (const attribute of attributes) {
+        attributeByName.set(attribute.name, attribute);
+    }
+    // Validate the policy structure considering logical operators
+    const validation = validatePolicyStructure(policy.policy.definition.structure, attributeByName);
+    if (!validation.isValid) {
+        result.isValid = false;
+        result.errors.push(...validation.errors);
+        // Extract unique missing attributes for backwards compatibility
+        const allMissingAttributes = new Set();
+        for (const error of validation.errors) {
+            if (error.includes("Missing attributes:")) {
+                const attrs = error
+                    .split("Missing attributes:")[1]
+                    ?.split(",")
+                    .map((s) => s.trim()) || [];
+                for (const attr of attrs) {
+                    allMissingAttributes.add(attr);
+                }
+            }
+        }
+        result.missingAttributes = Array.from(allMissingAttributes);
+    }
+    const missingFilterAttributes = new Set();
+    const filters = policy.policy.definition.filters ?? [];
+    for (const filter of filters) {
+        collectMissingAttributesFromFilter(filter, attributeByName, missingFilterAttributes);
+    }
+    visitStructureFilters(policy.policy.definition.structure, (filter) => collectMissingAttributesFromFilter(filter, attributeByName, missingFilterAttributes));
+    if (missingFilterAttributes.size > 0) {
+        result.isValid = false;
+        const missingList = Array.from(missingFilterAttributes).sort();
+        result.errors.push(`Filters reference missing attributes: ${missingList.join(", ")}`);
+        for (const attr of missingList) {
+            if (!result.missingAttributes.includes(attr)) {
+                result.missingAttributes.push(attr);
+            }
+        }
+    }
+    return result;
+}
+function validatePolicyStructure(structure, attributeByName) {
+    if (!structure || typeof structure !== "object") {
+        return { isValid: true, errors: [] };
+    }
+    const struct = structure;
+    // Handle anyOf - at least one must be valid
+    if (struct.anyOf && Array.isArray(struct.anyOf)) {
+        for (const option of struct.anyOf) {
+            const optionValidation = validatePolicyStructure(option, attributeByName);
+            if (optionValidation.isValid) {
+                // If any option is valid, the whole anyOf is valid
+                return { isValid: true, errors: [] };
+            }
+        }
+        // If no options are valid, collect all errors
+        const allErrors = [];
+        for (const option of struct.anyOf) {
+            const optionValidation = validatePolicyStructure(option, attributeByName);
+            allErrors.push(...optionValidation.errors);
+        }
+        return {
+            isValid: false,
+            errors: [
+                `None of the anyOf options are satisfied. Issues: ${allErrors.join("; ")}`,
+            ],
+        };
+    }
+    // Handle allOf - all must be valid
+    if (struct.allOf && Array.isArray(struct.allOf)) {
+        const allErrors = [];
+        for (const requirement of struct.allOf) {
+            const reqValidation = validatePolicyStructure(requirement, attributeByName);
+            if (!reqValidation.isValid) {
+                allErrors.push(...reqValidation.errors);
+            }
+        }
+        return allErrors.length > 0
+            ? { isValid: false, errors: allErrors }
+            : { isValid: true, errors: [] };
+    }
+    // Handle single field with attribute
+    if (struct.field &&
+        struct.field.type ===
+            "attribute") {
+        const attributeName = struct.field
+            .attribute_name;
+        const errors = [];
+        // Check if attribute exists - we don't need to check mappings anymore
+        // since we use company_data.<attribute_name> format
+        if (!attributeByName.has(attributeName)) {
+            errors.push(`Missing attributes: ${attributeName}`);
+        }
+        return errors.length > 0
+            ? { isValid: false, errors }
+            : { isValid: true, errors: [] };
+    }
+    // For other structures, recursively validate
+    for (const value of Object.values(struct)) {
+        if (typeof value === "object") {
+            const childValidation = validatePolicyStructure(value, attributeByName);
+            if (!childValidation.isValid) {
+                return childValidation;
+            }
+        }
+    }
+    return { isValid: true, errors: [] };
+}
+function visitStructureFilters(node, visitor) {
+    if (!node || typeof node !== "object") {
+        return;
+    }
+    if ("field" in node) {
+        const filters = node.filters;
+        if (filters) {
+            for (const filter of filters) {
+                visitor(filter);
+            }
+        }
+        return;
+    }
+    if ("anyOf" in node && Array.isArray(node.anyOf)) {
+        for (const child of node.anyOf) {
+            visitStructureFilters(child, visitor);
+        }
+    }
+    if ("allOf" in node && Array.isArray(node.allOf)) {
+        for (const child of node.allOf) {
+            visitStructureFilters(child, visitor);
+        }
+    }
+}
+function collectMissingAttributesFromFilter(filter, attributesByName, missingAttributes) {
+    visitFilterAttributes(filter, (attributeName) => {
+        if (!attributesByName.has(attributeName)) {
+            missingAttributes.add(attributeName);
+        }
+    });
+}

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

@@ -0,0 +1,37 @@
+import type { Attribute } from "../../attributes/types";
+import type { Dataset } from "../../datasets/types";
+import type { CollaborationPolicyType } from "../types";
+import type { PolicyMatchResult, PolicySqlFragments } from "./types";
+export declare function buildPolicySqlWithValidation(dataset: Dataset, policies: CollaborationPolicyType[], attributes: Attribute[]): PolicyMatchResult;
+/**
+ * Categorizes collaboration policies into matching and non-matching groups based on dataset compatibility.
+ *
+ * This function validates each policy against the provided dataset and attributes to determine
+ * whether the policy can be successfully applied. Policies are categorized as matching if they
+ * have all required attributes available, or non-matching if they're missing required attributes
+ * or mappings.
+ *
+ * @param policies - Array of collaboration policies to categorize
+ * @param dataset - The dataset to validate policies against
+ * @param attributes - Available attributes for validation
+ * @returns Object containing matching policies, non-matching policies, and detailed skip information
+ *
+ * @example
+ * ```typescript
+ * const { matching, nonMatching, skippedDetails } = categorizePolicies(
+ *   allPolicies,
+ *   myDataset,
+ *   availableAttributes
+ * );
+ *
+ * console.log(`${matching.length} policies can be applied`);
+ * console.log(`${nonMatching.length} policies were skipped`);
+ * skippedDetails.forEach(skip => console.log(`Skipped ${skip.name}: ${skip.reason}`));
+ * ```
+ */
+export declare function categorizePolicies(policies: CollaborationPolicyType[], dataset: Dataset, attributes: Attribute[]): {
+    matching: CollaborationPolicyType[];
+    nonMatching: CollaborationPolicyType[];
+    skippedDetails: PolicyMatchResult["skippedPolicies"];
+};
+export declare function buildPolicySql(dataset: Dataset, policies: CollaborationPolicyType[], attributes: Attribute[]): PolicySqlFragments;