@narrative.io/data-collaboration-sdk-ts 2.65.0 → 2.67.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/policy-traverser.js

@@ -11,10 +11,14 @@ export function traversePolicy(policy, attributeByName, requiredAttributePaths,
         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) {
-                markAttributePath(requiredAttributePaths, attribute, normalizePathValue(path));
+                // 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) {
@@ -54,11 +58,10 @@ function traverseSatisfiedStructure(node, attributeByName, visitor) {
         return;
     }
     if ("anyOf" in node && Array.isArray(node.anyOf)) {
-        // For anyOf, only traverse the FIRST satisfied branch
+        // For anyOf, traverse ALL satisfied branches
         for (const child of node.anyOf) {
             if (isBranchSatisfied(child, attributeByName)) {
                 traverseSatisfiedStructure(child, attributeByName, visitor);
-                return; // Only process the first satisfied branch
             }
         }
         return;

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

@@ -58,16 +58,16 @@ function buildPolicySqlUsingIndexes(policies, attributeByName, datasetName) {
         }
     }
     const selectClauses = new Set();
-    for (const [attributeName, paths] of globalRequiredAttributePaths) {
+    for (const [attributeName, _paths] of globalRequiredAttributePaths) {
         const attribute = attributeByName.get(attributeName);
         if (!attribute) {
             continue;
         }
-        for (const path of paths) {
-            const expression = resolveAttributeExpression(attribute, path, datasetName);
-            const alias = buildSelectAlias(attributeName, path);
-            selectClauses.add(`${expression} AS ${alias}`);
-        }
+        // Always select the root attribute (without path)
+        const expression = resolveAttributeExpression(attribute, "", // Empty path for root attribute
+        datasetName);
+        const alias = buildSelectAlias(attributeName, "");
+        selectClauses.add(`${expression} AS ${alias}`);
     }
     return {
         select: Array.from(selectClauses),

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

@@ -1,6 +1,9 @@
 export function markAttributePath(index, attribute, path) {
     const attributePaths = index.get(attribute.name) ?? new Set();
-    const normalized = path || determineDefaultPath(attribute);
+    // 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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "2.65.0",
+	"version": "2.67.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -14,27 +14,31 @@
 		"preversion": "npm run lint",
 		"version": "npm run && git add -A src",
 		"postversion": "git push && git push --tags",
-		"test": "jest --coverage"
+		"test": "jest --coverage",
+		"dev": "tsc -w",
+		"check:built": "node scripts/ensureBuild.js",
+		"link:global": "npm run check:built && npm link",
+		"pack:dist": "npm run check:built && npm pack"
 	},
 	"keywords": [],
 	"author": "",
 	"license": "ISC",
 	"devDependencies": {
-		"@babel/core": "7.28.3",
+		"@babel/core": "7.28.4",
 		"@babel/preset-env": "7.28.3",
 		"@babel/preset-typescript": "7.27.1",
-		"@biomejs/biome": "2.2.2",
-		"@commitlint/cli": "20.0.0",
+		"@biomejs/biome": "2.2.5",
+		"@commitlint/cli": "20.1.0",
 		"@commitlint/config-conventional": "20.0.0",
 		"@types/jest": "30.0.0",
-		"babel-jest": "30.1.0",
-		"jest": "30.1.0",
-		"lefthook": "1.12.3",
-		"ts-jest": "29.4.1"
+		"babel-jest": "30.2.0",
+		"jest": "30.2.0",
+		"lefthook": "1.13.6",
+		"ts-jest": "29.4.4"
 	},
 	"dependencies": {
 		"mande": "2.0.9",
-		"zod": "4.1.3",
+		"zod": "4.1.11",
 		"bignumber.js": "9.3.1"
 	},
 	"overrides": {