@loxtep/sdk 0.7.21 → 0.7.24

package/dist/lib/workspace-lint.js

@@ -0,0 +1,199 @@
+/**
+ * Offline lint of a local Loxtep project package (entity schemas + relationships).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { EntityType, validateEntity } from './entity-json-schemas/index.js';
+function readJsonObject(filePath) {
+    try {
+        const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+            return raw;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function listJsonFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const full = join(dir, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            out.push(...listJsonFiles(full));
+        }
+        else if (name.endsWith('.json')) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function classifyEntity(projectDir, filePath) {
+    const rel = relative(projectDir, filePath).replace(/\\/g, '/');
+    if (rel.startsWith('connectors/') && rel.endsWith('.json')) {
+        return EntityType.CONNECTOR;
+    }
+    if (rel.match(/^workflows\/[^/]+\/workflow\.json$/)) {
+        return EntityType.WORKFLOW;
+    }
+    if (rel.match(/^workflows\/[^/]+\/connections\/[^/]+\.json$/)) {
+        return EntityType.CONNECTION;
+    }
+    if (rel.match(/^workflows\/[^/]+\/data-products\/[^/]+\.json$/)) {
+        return EntityType.DATA_PRODUCT;
+    }
+    if (rel.match(/^workflows\/[^/]+\/transformations\/[^/]+\.json$/)) {
+        return EntityType.TRANSFORMATION;
+    }
+    if (rel.match(/^workflows\/[^/]+\/validations\/[^/]+\.json$/)) {
+        return EntityType.VALIDATION;
+    }
+    if (rel.startsWith('domains/') && rel.endsWith('.json')) {
+        return EntityType.DOMAIN;
+    }
+    return null;
+}
+function discoverEntities(projectDir, workflowId) {
+    const entities = [];
+    const roots = [join(projectDir, 'connectors'), join(projectDir, 'domains')];
+    if (workflowId) {
+        roots.push(join(projectDir, 'workflows', workflowId));
+    }
+    else {
+        roots.push(join(projectDir, 'workflows'));
+    }
+    for (const root of roots) {
+        for (const filePath of listJsonFiles(root)) {
+            const entityType = classifyEntity(projectDir, filePath);
+            if (!entityType)
+                continue;
+            const data = readJsonObject(filePath);
+            const rel = relative(projectDir, filePath).replace(/\\/g, '/');
+            if (!data) {
+                entities.push({
+                    path: rel,
+                    entityType,
+                    data: {},
+                });
+                // mark unreadable via empty + special handling below
+                continue;
+            }
+            entities.push({ path: rel, entityType, data });
+        }
+    }
+    return entities;
+}
+/**
+ * Lint local entity JSON against shipped schemas and basic relationship checks.
+ */
+export function lintLocalPackage(options) {
+    const { projectDir, workflow_id } = options;
+    const issues = [];
+    if (!existsSync(projectDir)) {
+        return {
+            ok: false,
+            files_checked: 0,
+            issues: [{ path: projectDir, severity: 'error', message: 'Project directory not found' }],
+        };
+    }
+    const entities = discoverEntities(projectDir, workflow_id);
+    const byId = new Map();
+    for (const entity of entities) {
+        if (Object.keys(entity.data).length === 0) {
+            issues.push({
+                path: entity.path,
+                severity: 'error',
+                message: 'Invalid or unreadable JSON object',
+            });
+            continue;
+        }
+        const result = validateEntity(entity.entityType, entity.data);
+        if (!result.valid && result.errors) {
+            for (const err of result.errors) {
+                issues.push({
+                    path: `${entity.path}${err.path}`,
+                    severity: 'error',
+                    message: err.message,
+                });
+            }
+        }
+        const idKey = entity.data.connector_id ||
+            entity.data.connection_id ||
+            entity.data.workflow_id ||
+            entity.data.data_product_id ||
+            entity.data.domain_id;
+        if (idKey) {
+            byId.set(idKey, entity);
+        }
+    }
+    // Relationship checks
+    for (const entity of entities) {
+        if (entity.entityType === EntityType.CONNECTION) {
+            const connectorId = entity.data.connector_id;
+            if (typeof connectorId === 'string' && connectorId.length > 0) {
+                // connector may exist only remotely; warn only if local connectors/ is present
+                // and does not contain this id — keep as error when local connector file expected.
+                const localConnectors = entities.filter(e => e.entityType === EntityType.CONNECTOR);
+                if (localConnectors.length > 0 &&
+                    !localConnectors.some(c => c.data.connector_id === connectorId)) {
+                    issues.push({
+                        path: entity.path,
+                        severity: 'error',
+                        message: `connector_id "${connectorId}" not found under connectors/`,
+                    });
+                }
+            }
+            else {
+                issues.push({
+                    path: entity.path,
+                    severity: 'error',
+                    message: 'connection is missing connector_id',
+                });
+            }
+        }
+        if (entity.entityType === EntityType.DATA_PRODUCT) {
+            const upstream = entity.data.upstream_entity_id;
+            if (typeof upstream === 'string' && upstream.length > 0 && !byId.has(upstream)) {
+                // Upstream may be a connection in the same workflow — check connection ids
+                const conn = entities.find(e => e.entityType === EntityType.CONNECTION && e.data.connection_id === upstream);
+                if (!conn) {
+                    issues.push({
+                        path: entity.path,
+                        severity: 'error',
+                        message: `upstream_entity_id "${upstream}" not found in local package`,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        issues,
+        files_checked: entities.length,
+    };
+}
+/**
+ * True when the project has at least one entity JSON package file to lint.
+ */
+export function hasLocalEntityPackage(projectDir) {
+    const workflowsDir = join(projectDir, 'workflows');
+    if (!existsSync(workflowsDir))
+        return false;
+    for (const name of readdirSync(workflowsDir)) {
+        const wfJson = join(workflowsDir, name, 'workflow.json');
+        if (existsSync(wfJson))
+            return true;
+    }
+    return existsSync(join(projectDir, 'connectors')) && listJsonFiles(join(projectDir, 'connectors')).length > 0;
+}
+//# sourceMappingURL=workspace-lint.js.map

package/dist/lib/workspace-lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-lint.js","sourceRoot":"","sources":["../../src/lib/workspace-lint.ts"],"names":[],"mappings":"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"}

package/docs/getting-started.md

@@ -163,29 +163,19 @@ products, connectors, domains, queues, workflows). Re-run after platform changes
 
 ---
 
-## Step 6: Your first data product (SDK ingest)
+## Step 6: Create a data product and write from your app
 
-After `attach`, the usual greenfield goal is: **provision a source data product
-on your instance, then call `get_writer` from your app.**
-
-`get_writer` needs **deployment metadata** (queues and bots created at deploy
-time). Creating a catalog row alone is not enough.
-
-**Recommended:** follow **[SDK-first ingest](./sdk-first-ingest.md)** end to end.
-Short version:
+After `attach`, create a data product on that instance, then call `get_writer`
+from your application:
 
 ```bash
-pnpm exec loxtep domains list
-
-# One command: SDK connector + workflow bundle + deploy (no MCP)
 pnpm exec loxtep ingest provision --name app-events
-
+pnpm exec loxtep lint
+pnpm exec loxtep deploy
 pnpm exec loxtep data-products list
-node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
 ```
 
-Do **not** expect `pnpm exec loxtep data-products create` alone to enable
-streaming — it registers catalog metadata without runtime bindings.
+See **[Write to a data product](./sdk-first-ingest.md)** for the full flow and code sample.
 
 ---
 

package/docs/quick-reference.md

@@ -54,8 +54,8 @@ bus config from deployment metadata.
 ```typescript
 const writer = await client.get_writer('orders'); // deployed data product name
 
-writer.write({ id: 'evt-1', payload: { key: 'value' } });
-writer.write({ id: 'evt-2', payload: { key: 'value' } });
+writer.write({ order_id: 'ord-1', status: 'placed' });
+writer.write({ order_id: 'ord-2', status: 'shipped' });
 
 await writer.close(); // flushes all buffered events
 ```
@@ -65,8 +65,8 @@ await writer.close(); // flushes all buffered events
 ```python
 writer = await client.get_writer("my-data-product")
 
-writer.write({"id": "evt-1", "payload": {"key": "value"}})
-writer.write({"id": "evt-2", "payload": {"key": "value"}})
+writer.write({"order_id": "ord-1", "status": "placed"})
+writer.write({"order_id": "ord-2", "status": "shipped"})
 
 await writer.close()  # flushes all buffered events
 ```
@@ -189,15 +189,15 @@ pnpm exec loxtep attach --instance <instance-id>
 pnpm exec loxtep generate
 ```
 
-**SDK-first ingest** (after attach — see [SDK-first ingest](./sdk-first-ingest.md)):
+**Create a data product and write from your app** (after attach):
 
 ```bash
-pnpm exec loxtep domains list
-node node_modules/@loxtep/sdk/docs/examples/generate-ingest-bundle.mjs
-pnpm exec loxtep workflows deploy --project-id <id> --instance-id <id>
-node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
+pnpm exec loxtep ingest provision --name app-events
+pnpm exec loxtep lint && pnpm exec loxtep deploy
 ```
 
+See [Write to a data product](./sdk-first-ingest.md).
+
 Code-first workflow modules:
 
 ```bash

package/docs/sdk-first-ingest.md

@@ -1,263 +1,94 @@
-# SDK-first ingest — your first data product and `get_writer`
+# Write to a data product from your app
 
-You logged in, ran `init`, and `attach`. This guide takes you from there to
-**writing events from application code** with `client.get_writer(name)`.
+You installed the SDK, initialized a workspace, and attached an instance. Next:
+**create a data product**, open a writer, and send events from your code.
 
-That is the primary greenfield path when you are **not** wiring a SaaS connector
-first — you want your app (or ETL job) to push events into a **source** data
-product on your attached instance.
-
-> **Full CLI workspace setup:** [Getting Started](./getting-started.md) steps 1–4.
-> **Code-first workflow modules:** [Code-first CLI](./code-first-cli.md).
+> Already set up login, init, and attach? [Getting started](./getting-started.md).
 
 ---
 
-## What you are building
-
-```text
-Your app  ──get_writer──▶  rstreams queue  ──▶  source data product (catalog)
-     ▲                           ▲
-     │                           │
-  @loxtep/sdk              provisioned at deploy time
-  fromWorkspace()
-```
+## Phase 1 — Workspace ready
 
-`get_writer` resolves **queue**, **bot**, and **stream bus** config from
-**deployment metadata** (`deployment_bindings` on the data product). A catalog
-row alone is not enough — the ingestion workflow must be **saved and deployed**
-on your attached instance first.
-
----
-
-## Prerequisites
-
-Run from your scaffolded workspace (directory with `.loxtep/project.json`):
+Run commands from your project directory (the folder with `.loxtep/project.json`).
 
 ```bash
-pnpm exec loxtep config list   # project_id + instance_id should be set
-pnpm exec loxtep domains list  # you need a domain_id for the data product
+pnpm exec loxtep login
+pnpm exec loxtep init
+pnpm exec loxtep attach --instance <instance-id>
+pnpm exec loxtep config list
 ```
 
-Every org has at least one domain. Copy a `domain_id` from the list.
-
----
-
-## Overview (four phases)
-
-| Phase | What | How |
-| ----- | ---- | --- |
-| 1 | Workspace ready | `login` → `init` → `attach` (done) |
-| 2 | Provision runtime | SDK connector + workflow bundle + deploy |
-| 3 | Verify | `data-products list` / `data-products get` |
-| 4 | Write events | `LoxtepClient.fromWorkspace()` + `get_writer` |
-
-Phases 2–4 below.
+You should see `project_id` and `instance_id` from `attach`.
 
 ---
 
-## Phase 2 — Provision runtime (required before `get_writer`)
-
-Runtime provisioning creates the workflow graph (SDK connection node → source
-data product node), saves it to your project workspace, and **deploys** it to your
-instance so queues and bots exist.
-
-### Option A — CLI one-shot (recommended, no MCP)
+## Phase 2 — Create your data product (local package)
 
-From your workspace root (after `login`, `init`, `attach`):
+Pick a name your app will use (example: `app-events`):
 
 ```bash
+pnpm exec loxtep connectors list --type sdk   # optional: see existing SDK connectors
 pnpm exec loxtep ingest provision --name app-events
+pnpm exec loxtep lint
 ```
 
-This command:
-
-1. Creates an org-level **SDK connector** (`connector_type: "sdk"`).
-2. Builds and saves the workflow bundle (`workflow.json` + connection + source data product).
-3. **Deploys** to your attached instance (unless you pass `--no-deploy` or `--dry-run`).
-
-Validate first without writing:
-
-```bash
-pnpm exec loxtep ingest provision --name app-events --dry-run
-```
-
-### Option B — Helper script + bundle save
-
-Generate bundle JSON only:
-
-```bash
-node node_modules/@loxtep/sdk/docs/examples/generate-ingest-bundle.mjs
-```
-
-Then persist and deploy via CLI:
+`ingest provision` reuses an existing SDK connector when one exists (or creates one),
+then writes a **local** workflow package under `connectors/` and `workflows/<id>/`.
+It does **not** deploy by default. Validate with `loxtep lint`, then publish:
 
 ```bash
-pnpm exec loxtep bundle save --dry-run --file .loxtep/sdk-ingest-bundle.json
-pnpm exec loxtep bundle save --file .loxtep/sdk-ingest-bundle.json
-pnpm exec loxtep workflows deploy \
-  --project-id <project-id-from-config-list> \
-  --instance-id <instance-id-from-config-list>
+pnpm exec loxtep deploy --dry-run   # lint only
+pnpm exec loxtep deploy             # lint + compile/deploy modules
+# or: pnpm exec loxtep ingest provision --name app-events --deploy
 ```
 
-Or set `LOXTEP_AUTO_SAVE=1` on the helper script to save + deploy in one step.
-
-Poll until deployment completes (Web UI **Observe**, or `loxtep observe status`).
-
-### Option C — Loxtep MCP (Cursor / agent)
-
-Use **`loxtep_build`** → `save_workflow_bundle` if you prefer MCP authoring.
-Same bundle shape as below; deploy with `loxtep workflows deploy` or MCP
-`deploy_project`.
-
-### Option D — Web UI (Studio)
-
-Create an **ingestion** workflow with an **SDK** connection node and a **source**
-data product node, then deploy to your attached instance from the Studio deploy
-flow.
+That local package is what you iterate on; deploy pushes it to your instance.
 
 ---
 
-### Workflow bundle shape
-
-Minimal ingestion bundle (SDK connection → source data product). Replace UUIDs
-and names; `connector_id` must be the SDK connector from step 2A or 2B.
-
-```json
-{
-  "workflow.json": {
-    "workflow_id": "<workflow-uuid>",
-    "organization_id": "<org-uuid>",
-    "project_id": "<project-uuid>",
-    "name": "SDK App Events Ingest",
-    "workflow_type": "ingestion",
-    "domain_id": "<domain-uuid>",
-    "status": "active",
-    "configuration": {},
-    "metadata": {},
-    "created_at": "2026-07-23T00:00:00.000Z",
-    "updated_at": "2026-07-23T00:00:00.000Z"
-  },
-  "connections/<connection-uuid>.json": {
-    "connection_id": "<connection-uuid>",
-    "organization_id": "<org-uuid>",
-    "project_id": "<project-uuid>",
-    "workflow_id": "<workflow-uuid>",
-    "connector_id": "<sdk-connector-uuid>",
-    "key": "sdk-input",
-    "name": "SDK Input",
-    "type": "sdk",
-    "status": "active",
-    "configuration": {
-      "sdk_type": "nodejs",
-      "event_type": "app-events"
-    },
-    "created_at": "2026-07-23T00:00:00.000Z",
-    "updated_at": "2026-07-23T00:00:00.000Z"
-  },
-  "data-products/<data-product-uuid>.json": {
-    "data_product_id": "<data-product-uuid>",
-    "organization_id": "<org-uuid>",
-    "project_id": "<project-uuid>",
-    "workflow_id": "<workflow-uuid>",
-    "upstream_entity_id": "<connection-uuid>",
-    "upstream_entity_type": "connections",
-    "domain_id": "<domain-uuid>",
-    "name": "app-events",
-    "kind": "source",
-    "status": "draft",
-    "owner": {},
-    "governance": {
-      "classification": "internal",
-      "pii_fields": [],
-      "compliance_requirements": [],
-      "tags": []
-    },
-    "metadata": {},
-    "created_at": "2026-07-23T00:00:00.000Z",
-    "updated_at": "2026-07-23T00:00:00.000Z"
-  }
-}
-```
-
-The **`name`** on the data product node (`app-events` above) is what you pass
-to `get_writer('app-events')`.
-
----
-
-### Do not stop at `data-products create`
-
-```bash
-# Creates a catalog row only — get_writer will fail with "not deployed"
-pnpm exec loxtep data-products create --name app-events --domain-id <uuid> --kind source
-```
-
-Use **`data-products create`** only when you already have (or will immediately
-add) a deployed workflow that sets `deployment_bindings`. For greenfield SDK
-ingest, prefer the bundle + deploy path above.
-
----
+## Phase 3 — Confirm it exists
 
-## Phase 3 — Verify deployment
+After deploy:
 
 ```bash
 pnpm exec loxtep data-products list
-pnpm exec loxtep data-products get <data-product-id>
 ```
 
-A deployable source data product includes **`deployment_bindings`** with
-`queue_name`, `bot_id`, and `instance_id`. If those are missing, finish Phase 2
-before writing.
-
-Re-run code generation after platform changes:
-
-```bash
-pnpm exec loxtep generate
-```
+You should see `app-events` (or whatever name you chose).
 
 ---
 
-## Phase 4 — Write events from your app
+## Phase 4 — Write from your application
 
-Copy or run the example:
-
-```bash
-node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
-```
-
-Or embed in your service:
+The SDK reads your workspace (`.loxtep/project.json` + credentials). No manual
+URL or token wiring.
 
 ```typescript
 import { LoxtepClient } from '@loxtep/sdk';
 
 const client = await LoxtepClient.fromWorkspace();
 
-// Name from Phase 2 bundle / data-products list (case-sensitive)
 const writer = await client.get_writer('app-events');
 
 writer.write({
-  event_id: 'evt_001',
-  occurred_at: new Date().toISOString(),
-  payload: { user_id: 'u_1', action: 'signup' },
+  user_id: 'u_1',
+  action: 'signup',
 });
 
-await writer.close(); // flush buffered events
+await writer.close();
 ```
 
-Optional writer tuning:
+Pass your **business fields** to `write()`. The SDK wraps them for transport —
+you do not build an envelope or use a `payload` property yourself.
 
-```typescript
-await client.get_writer('app-events', {
-  batch_size: 500,
-  max_retries: 5,
-});
-```
+Use the same name you passed to `ingest provision`.
 
-Read back (after data has landed):
+### Read back (optional)
 
 ```typescript
-const reader = await client.get_reader('app-events', {
-  bot_id: 'my-app-reader',
-});
+const client = await LoxtepClient.fromWorkspace();
+const reader = await client.get_reader('app-events');
+
 for await (const event of reader) {
   console.log(event);
   break;
@@ -266,39 +97,45 @@ for await (const event of reader) {
 
 ---
 
-## End-to-end checklist
+## Quick checklist
 
 ```bash
 pnpm exec loxtep login
 pnpm exec loxtep init
 pnpm exec loxtep attach --instance <instance-id>
-pnpm exec loxtep domains list
-
 pnpm exec loxtep ingest provision --name app-events
-# or: generate-ingest-bundle.mjs + loxtep bundle save
-
+pnpm exec loxtep lint
+pnpm exec loxtep deploy
 pnpm exec loxtep data-products list
-node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
 ```
 
+Then `get_writer('app-events')` in your app.
+
 ---
 
-## Troubleshooting
+## If something goes wrong
 
-| Symptom | Cause | Fix |
-| ------- | ----- | --- |
-| `StreamingError: … is not deployed` | No `deployment_bindings` | Complete Phase 2 (bundle + deploy) |
-| `NotFoundError: Data product '…' not found` | Wrong name or wrong instance | `data-products list`; check `attach` / `instance_id` |
-| `AmbiguityError: Multiple data products match` | Same name on multiple instances | Use UUID or set `instance_id` in project.json |
-| Empty `domains list` | New org / permissions | Create a domain in the Web UI (Governance) |
+| What you see | What to do |
+| ------------ | ---------- |
+| Data product not found | Run `data-products list`. Check the name matches `get_writer('…')` exactly. |
+| Not ready to accept writes | Run `ingest provision`, then `deploy` (or `ingest provision --deploy`). Make sure you ran `attach` first. |
+| Multiple products with the same name | Pass the data product id to `get_writer`, or ensure `attach` points at the right instance. |
+| No domain available | Create a domain in the Loxtep UI, or pass `--domain-id` to `ingest provision`. |
 
 ---
 
-## Next steps
+## Other ways to create a data product
+
+**Loxtep MCP (AI assistant)** — If you use the Loxtep MCP in Cursor, Claude Code,
+or another client, describe what you want in plain language, for example:
+
+> Create a data product named `app-events` on my current Loxtep project and
+> deploy it to the instance I already attached. I want to write events from my
+> app with the SDK.
+
+The assistant provisions the same end state as `ingest provision`. After that,
+Phase 4 above is unchanged: `get_writer('app-events')` and `write()`.
 
-| Resource | Description |
-| -------- | ----------- |
-| [Getting Started](./getting-started.md) | Login, init, attach, generate |
-| [Quick Reference](./quick-reference.md) | CLI + SDK cheat sheet |
-| [Code-first CLI](./code-first-cli.md) | TypeScript workflow modules + `loxtep deploy` |
-| [Event Replay Cookbook](./event-replay-cookbook.md) | Replay and reprocess |
+**Loxtep Studio (web app)** — *Beta.* You can also design and publish a data
+product in the Loxtep UI. Once it exists on your instance, the SDK code in
+Phase 4 is the same.