@narrative.io/data-collaboration-sdk-ts 3.0.1 → 3.1.1

package/README.md

@@ -317,91 +317,67 @@ For detailed API documentation, please visit the [Narrative.io API Documentation
 
 ## 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:
+Link this SDK into another local app (e.g. a Nuxt 3 project) and iterate without publishing to npm. Both modes consume the SDK's built output in `build/**`, exactly like the published package — the only difference is how the bytes reach the app's `node_modules`:
 
-- **Linked mode (fastest)** — symlink your local SDK into the app
-- **Tarball mode (exact publish parity)** — install from a local `npm pack` tarball
+- **Linked mode (default)** — `bun link` symlinks this repo into the app; with `tsc -w` running, `src/**` edits flow live.
+- **Tarball mode** — `bun pm pack` → the app installs the `.tgz` (exact publish parity, a snapshot).
 
-Both approaches use the SDK’s **built output** in `build/`, exactly like the published package.
+The full flow (build → link/pack → install → verify resolution) is automated by two `bun run` scripts (backed by `scripts/link-local.sh` and `scripts/unlink-local.sh`). Both default the consumer app to `~/narrative/narrative-platform-ui` (override with `--app PATH` or `$NARRATIVE_UI_DIR`). Pass flags after a `--` so `bun` forwards them to the script.
 
-### Prerequisites
+### `bun run` scripts
 
-- Bun (this project uses bun as its package manager)
-- This repo builds TypeScript to `build/`
-- This repo includes `scripts/ensureBuild.js` to verify artifacts exist
+**Set up — `bun run link:local`** (build → register/pack → install into the app → verify it resolves into this repo):
 
 ```bash
-# In the SDK repo (this one)
-bun install
-bun run build              # one-time; emits build/**
-node scripts/ensureBuild.js
+# Linked mode into the default app, then verify resolution
+bun run link:local
+
+# A different consumer app
+bun run link:local -- --app /abs/path/to/app
+
+# Tarball mode (exact publish parity)
+bun run link:local -- --mode tarball
+
+# SDK side only (build + register/pack); prints the app-side command to run by hand
+bun run link:local -- --sdk-only
 ```
 
----
-
-### Option A — Linked Mode (Fastest Dev Feedback)
-
-1. **Keep the SDK building on save**
-   In the SDK repo (leave this running):
-   ```bash
-   bun run dev             # tsc -w → continuously updates build/**
-   ```
-
-2. **Register the SDK globally**
-   In the SDK repo (new terminal):
-   ```bash
-   bun run link:global     # runs ensureBuild + bun link
-   ```
-
-3. **Link into your consumer app**
-   In your app repo (e.g., Nuxt project):
-   ```bash
-   # link the globally-registered SDK into this app's node_modules
-   bun 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
-   bun run dev
-   ```
-   Edit files under `SDK/src/**` → the watcher writes to `build/**` → your app hot-reloads.
-
-**Revert to the registry version (in the app):**
+For live edits in linked mode, keep the watcher running in this repo so `src/**` edits rebuild `build/**`:
+
 ```bash
-bun remove @narrative.io/data-collaboration-sdk-ts
-bun add @narrative.io/data-collaboration-sdk-ts
+bun run dev      # tsc -w → continuously rewrites build/**
 ```
 
----
+**Tear down — `bun run unlink:local`** (stop the watcher → unlink from the app and reinstall the published package → deregister the global link):
 
-### Option B — Tarball Mode (Exact Publish Parity)
+```bash
+# Undo everything for the default app
+bun run unlink:local
+
+# Preview without changing anything
+bun run unlink:local -- --dry-run
+```
 
-1. **Pack the SDK (same artifact you would publish)**
-   ```bash
-   # in the SDK repo
-   bun run build
-   bun run pack:dist        # creates ./<name>-<version>.tgz
-   ```
+Flags: `--app PATH`, `--no-reinstall` (leave the SDK uninstalled), `--keep-global-link`, `--no-kill-watcher`, `--dry-run`.
 
-2. **Install the tarball in the app**
-   ```bash
-   # in the app repo
-   bun add /ABS/PATH/TO/<name>-<version>.tgz
-   bun run dev
-   ```
+### Lowest level (plain bun, no scripts)
 
-**Revert to a registry version (in the app):**
 ```bash
-bun add @narrative.io/data-collaboration-sdk-ts@<semver>
-```
+# Linked mode — SDK repo, then the app
+bun install && bun run build && bun run link:global
+bun link @narrative.io/data-collaboration-sdk-ts            # in the app
+
+# Tarball mode — SDK repo, then the app
+bun run build && bun run pack:dist                          # → ./<name>-<version>.tgz
+bun add /ABS/PATH/TO/<name>-<version>.tgz                   # in the app
 
----
+# Verify from the app — must resolve into this SDK repo (linked) or the tarball
+node -e "console.log(require.resolve('@narrative.io/data-collaboration-sdk-ts/package.json'))"
+
+# Revert (in the app)
+bun remove @narrative.io/data-collaboration-sdk-ts
+bun add @narrative.io/data-collaboration-sdk-ts             # or @<semver>
+```
 
 ### Troubleshooting (Nuxt 3 / Vite / SSR)
 
@@ -413,36 +389,8 @@ bun add @narrative.io/data-collaboration-sdk-ts@<semver>
   })
   ```
 
-- **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).
+- **Build artifacts not updating:** Ensure `bun 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)
-bun install
-bun run build
-bun run dev
-bun run link:global
-
-# App (consumer repo)
-bun link @narrative.io/data-collaboration-sdk-ts
-bun run dev
-```
-
-Alternative (publish-parity):
-
-```bash
-# SDK
-bun run build
-bun run pack:dist
-
-# App
-bun add /ABS/PATH/TO/*.tgz
-bun run dev
-```
+- **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.

package/build/compute-pools/index.d.ts

@@ -1,10 +1,43 @@
 import { BaseApi } from "../base-api";
 import type { ComputePoolResponse, CreateComputePoolRequest, ListComputePoolsParams, ListComputePoolsResponse, UpdateComputePoolRequest } from "./types";
+/**
+ * A class for accessing the Compute Pools API.
+ *
+ * @extends BaseApi
+ */
 export declare class ComputePoolsApi extends BaseApi {
     private computePoolsResourcePath;
+    /**
+     * List compute pools for a data plane.
+     *
+     * Note: the public API documents a `status` query parameter, but the
+     * backend currently returns active compute pools regardless of that value.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/list-compute-pools}
+     */
     listComputePools(dataPlaneId: string, params?: ListComputePoolsParams): Promise<ListComputePoolsResponse>;
+    /**
+     * Create a compute pool for a data plane.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/create-a-compute-pool}
+     */
     createComputePool(dataPlaneId: string, request: CreateComputePoolRequest): Promise<ComputePoolResponse>;
+    /**
+     * Get a compute pool by ID.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/get-a-compute-pool-by-id}
+     */
     getComputePool(dataPlaneId: string, computePoolId: string): Promise<ComputePoolResponse>;
+    /**
+     * Update a compute pool.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/update-a-compute-pool}
+     */
     updateComputePool(dataPlaneId: string, computePoolId: string, request: UpdateComputePoolRequest): Promise<ComputePoolResponse>;
+    /**
+     * Archive a compute pool.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/archive-a-compute-pool}
+     */
     archiveComputePool(dataPlaneId: string, computePoolId: string): Promise<void>;
 }

package/build/compute-pools/index.js

@@ -1,20 +1,53 @@
 import { BaseApi } from "../base-api";
+/**
+ * A class for accessing the Compute Pools API.
+ *
+ * @extends BaseApi
+ */
 export class ComputePoolsApi extends BaseApi {
     computePoolsResourcePath(dataPlaneId) {
         return `data-planes/${dataPlaneId}/compute-pools`;
     }
+    /**
+     * List compute pools for a data plane.
+     *
+     * Note: the public API documents a `status` query parameter, but the
+     * backend currently returns active compute pools regardless of that value.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/list-compute-pools}
+     */
     async listComputePools(dataPlaneId, params) {
         return await this.get(this.computePoolsResourcePath(dataPlaneId), params);
     }
+    /**
+     * Create a compute pool for a data plane.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/create-a-compute-pool}
+     */
     async createComputePool(dataPlaneId, request) {
         return await this.post(this.computePoolsResourcePath(dataPlaneId), request);
     }
+    /**
+     * Get a compute pool by ID.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/get-a-compute-pool-by-id}
+     */
     async getComputePool(dataPlaneId, computePoolId) {
         return await this.get(`${this.computePoolsResourcePath(dataPlaneId)}/${computePoolId}`);
     }
+    /**
+     * Update a compute pool.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/update-a-compute-pool}
+     */
     async updateComputePool(dataPlaneId, computePoolId, request) {
         return await this.put(`${this.computePoolsResourcePath(dataPlaneId)}/${computePoolId}`, request);
     }
+    /**
+     * Archive a compute pool.
+     *
+     * @see {@link https://docs.narrative.io/api-reference/compute-pools/archive-a-compute-pool}
+     */
     async archiveComputePool(dataPlaneId, computePoolId) {
         await this.delete(`${this.computePoolsResourcePath(dataPlaneId)}/${computePoolId}`);
     }

package/build/compute-pools/types.d.ts

@@ -1,6 +1,8 @@
 export type ComputePoolType = "owned" | "shared";
 export type ComputePoolStatus = "active" | "archived";
-export type SnowflakeWarehouseSize = "x-small" | "small" | "medium" | "large" | "x-large" | "2x-large" | "3x-large" | "4x-large" | "5x-large" | "6x-large";
+export type ComputePoolSize = "x_small" | "small" | "medium" | "large" | "x_large" | "2x_large" | "3x_large" | "4x_large" | "5x_large" | "6x_large";
+export type SnowflakeWarehouseSize = ComputePoolSize;
+export type AwsEmrSize = ComputePoolSize;
 export type SnowflakeWarehouseType = "standard" | "snowpark_optimized";
 export type ScalingPolicy = "standard" | "economy";
 export interface SnowflakeWarehouseExternalId {
@@ -8,9 +10,13 @@ export interface SnowflakeWarehouseExternalId {
     name: string;
     alias: string;
 }
-export type ComputePoolExternalId = SnowflakeWarehouseExternalId;
+export interface AwsEmrExternalId {
+    type: "aws_emr";
+}
+export type ComputePoolExternalId = SnowflakeWarehouseExternalId | AwsEmrExternalId;
 export interface SnowflakeWarehouseProvider {
     type: "snowflake_warehouse";
+    warehouse_name?: string;
     size?: SnowflakeWarehouseSize;
     warehouse_type?: SnowflakeWarehouseType;
     auto_suspend?: number;
@@ -26,7 +32,13 @@ export interface SnowflakeWarehouseProvider {
     resource_constraint?: string;
     comment?: string;
 }
-export type ComputePoolProvider = SnowflakeWarehouseProvider;
+export interface AwsEmrProvider {
+    type: "aws_emr";
+    size: AwsEmrSize;
+    idle_timeout_seconds?: number;
+    job_execution_timeout_seconds?: number;
+}
+export type ComputePoolProvider = SnowflakeWarehouseProvider | AwsEmrProvider;
 export interface ParticipantsAll {
     type: "all";
 }
@@ -73,15 +85,22 @@ export interface ComputePoolSharedResponse {
     provider: ComputePoolProvider;
 }
 export type ComputePoolResponse = ComputePoolOwnedResponse | ComputePoolSharedResponse;
-export interface CreateComputePoolRequest {
-    external_id: ComputePoolExternalId;
+export interface CreateComputePoolRequestCommon {
     name: string;
     display_name: string;
     description?: string;
     tags?: string[];
     collaborators?: ComputePoolCollaborators;
-    provider: ComputePoolProvider;
 }
+export type CreateSnowflakeWarehouseComputePoolRequest = CreateComputePoolRequestCommon & {
+    external_id: SnowflakeWarehouseExternalId;
+    provider: SnowflakeWarehouseProvider;
+};
+export type CreateAwsEmrComputePoolRequest = CreateComputePoolRequestCommon & {
+    external_id?: AwsEmrExternalId;
+    provider: AwsEmrProvider;
+};
+export type CreateComputePoolRequest = CreateSnowflakeWarehouseComputePoolRequest | CreateAwsEmrComputePoolRequest;
 export interface UpdateComputePoolRequest {
     display_name?: string;
     description?: string;

package/build/compute-pools/types.test-d.d.ts

@@ -0,0 +1,75 @@
+import type { AwsEmrExternalId, AwsEmrProvider, ComputePoolResponse, CreateComputePoolRequest, SnowflakeWarehouseExternalId, SnowflakeWarehouseProvider } from "./types";
+type IsAssignable<T, U> = T extends U ? true : false;
+type AssertTrue<T extends true> = T;
+type AssertFalse<T extends false> = T;
+export type AwsCreateWithoutExternalId = AssertTrue<IsAssignable<{
+    name: "aws_pool";
+    display_name: "AWS pool";
+    provider: {
+        type: "aws_emr";
+        size: "x_small";
+    };
+}, CreateComputePoolRequest>>;
+export type AwsCreateWithExternalId = AssertTrue<IsAssignable<{
+    name: "aws_pool";
+    display_name: "AWS pool";
+    external_id: {
+        type: "aws_emr";
+    };
+    provider: {
+        type: "aws_emr";
+        size: "x_small";
+    };
+}, CreateComputePoolRequest>>;
+export type SnowflakeCreateWithoutExternalId = AssertFalse<IsAssignable<{
+    name: "snowflake_pool";
+    display_name: "Snowflake pool";
+    provider: {
+        type: "snowflake_warehouse";
+    };
+}, CreateComputePoolRequest>>;
+export type SnowflakeCreateWithExternalId = AssertTrue<IsAssignable<{
+    name: "snowflake_pool";
+    display_name: "Snowflake pool";
+    external_id: {
+        type: "snowflake_warehouse";
+        name: "WAREHOUSE_NAME";
+        alias: "3c90c3cc-0d44-4b50-8888-8dd25736052a";
+    };
+    provider: {
+        type: "snowflake_warehouse";
+        warehouse_name: "WAREHOUSE_NAME";
+    };
+}, CreateComputePoolRequest>>;
+export type AwsResponse = AssertTrue<IsAssignable<{
+    type: "owned";
+    id: string;
+    company_id: number;
+    data_plane_id: string;
+    external_id: AwsEmrExternalId;
+    name: string;
+    display_name: string;
+    status: "active";
+    created_at: string;
+    tags: string[];
+    provider: AwsEmrProvider;
+    collaborators: {
+        use: {
+            type: "none";
+        };
+    };
+}, ComputePoolResponse>>;
+export type SnowflakeResponse = AssertTrue<IsAssignable<{
+    type: "shared";
+    id: string;
+    company_id: number;
+    data_plane_id: string;
+    external_id: SnowflakeWarehouseExternalId;
+    name: string;
+    display_name: string;
+    status: "active";
+    created_at: string;
+    tags: string[];
+    provider: SnowflakeWarehouseProvider;
+}, ComputePoolResponse>>;
+export {};

package/build/compute-pools/types.test-d.js

@@ -0,0 +1 @@
+export {};

package/build/nql/AstParser.js

@@ -32,14 +32,86 @@ export function parseExplain(n) {
             return nqlOrFail(n);
     }
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function walkNodes(value, visit) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walkNodes(item, visit);
+        return;
+    }
+    if (isRecord(value)) {
+        visit(value);
+        for (const key of Object.keys(value))
+            walkNodes(value[key], visit);
+    }
+}
+// The server qualifies first-party (`company_data`) refs by dataset NAME when a
+// query was written by name (e.g. `company_data.my_dataset`), echoing the name in
+// the `table` field and carrying the numeric dataset id only in a table node's
+// `metadata.id`. `parseTable`/`parseColumnRef` bind a dataset node only when
+// `table` is the numeric id, so we first rewrite name-qualified first-party refs
+// back to their id: build a name/alias -> id map from the FROM tables' metadata,
+// then rewrite both the table refs and the column refs that point at them. Id-form
+// queries are unaffected, and non-`company_data` schemas (e.g. third-party access
+// rules `<slug>.<name>`) are left untouched.
+function resolveFirstPartyDatasetId(node) {
+    const table = node.table;
+    if (typeof table === "string" && /^\d+$/.test(table)) {
+        return Number.parseInt(table, 10);
+    }
+    const metadata = node.metadata;
+    if (isRecord(metadata)) {
+        const id = metadata.id;
+        if (typeof id === "number")
+            return id;
+        if (typeof id === "string" && /^\d+$/.test(id)) {
+            return Number.parseInt(id, 10);
+        }
+    }
+    return undefined;
+}
+function normalizeFirstPartyRefs(n) {
+    const clone = JSON.parse(JSON.stringify(n));
+    const idByRef = new Map();
+    // Pass 1: first-party FROM tables — record name/alias -> id, rewrite to id.
+    walkNodes(clone, (node) => {
+        if (node.type !== "table" || node.schema !== "company_data")
+            return;
+        const id = resolveFirstPartyDatasetId(node);
+        if (id === undefined)
+            return;
+        if (typeof node.table === "string")
+            idByRef.set(node.table, id);
+        if (typeof node.as === "string")
+            idByRef.set(node.as, id);
+        idByRef.set(String(id), id);
+        node.table = String(id);
+    });
+    if (idByRef.size === 0)
+        return clone;
+    // Pass 2: first-party column refs still qualified by name -> rewrite to id.
+    walkNodes(clone, (node) => {
+        if (node.type !== "column" || node.schema !== "company_data")
+            return;
+        if (typeof node.table !== "string" || /^\d+$/.test(node.table))
+            return;
+        const id = idByRef.get(node.table);
+        if (id !== undefined)
+            node.table = String(id);
+    });
+    return clone;
+}
 export function parseSelect(n) {
+    const normalized = normalizeFirstPartyRefs(n);
     const select = {
         type: "select",
-        budget: n.budget,
-        columns: n.columns.map((col) => parseOutput(col)),
-        deduplication: parseDeduplication(n),
-        from: n.from !== null ? parseFrom(n.from) : [],
-        where: n.where !== null ? parseWhere(n.where) : null,
+        budget: normalized.budget,
+        columns: normalized.columns.map((col) => parseOutput(col)),
+        deduplication: parseDeduplication(normalized),
+        from: normalized.from !== null ? parseFrom(normalized.from) : [],
+        where: normalized.where !== null ? parseWhere(normalized.where) : null,
     };
     return select;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "3.0.1",
+	"version": "3.1.1",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -19,7 +19,9 @@
 		"dev": "tsc -w",
 		"check:built": "node scripts/ensureBuild.js",
 		"link:global": "bun run check:built && bun link",
-		"pack:dist": "bun run check:built && bun pm pack"
+		"pack:dist": "bun run check:built && bun pm pack",
+		"link:local": "bash scripts/link-local.sh",
+		"unlink:local": "bash scripts/unlink-local.sh"
 	},
 	"keywords": [],
 	"author": "",
@@ -41,7 +43,7 @@
 	},
 	"dependencies": {
 		"zod": "4.4.3",
-		"bignumber.js": "11.1.2"
+		"bignumber.js": "11.1.3"
 	},
 	"overrides": {
 		"semver@<7.5.2": "7.5.2"