@loxtep/sdk 0.9.14 → 0.9.16

package/dist/rstreams/leo-runtime.js

@@ -7,7 +7,7 @@
  */
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
-export function createRStreamsSdk(config) {
+export function createRStreamsSdk(config, options) {
     // Lazy CJS require — only when a stream reader/writer is actually constructed.
     const StreamRuntime = require('leo-sdk');
     const defaultExport = StreamRuntime.default;
@@ -15,6 +15,19 @@ export function createRStreamsSdk(config) {
     if (!SDK || typeof SDK !== 'function') {
         throw new Error('Failed to resolve RStreamsSdk constructor from leo-sdk');
     }
-    return new SDK(config);
+    const credentials = options?.credentials;
+    if (!credentials) {
+        return new SDK(config);
+    }
+    // Pin STS onto every AWS client the bus uses — default credential chain is the
+    // operator profile, which cannot write org/shared bus Kinesis streams.
+    const region = config.Region;
+    const clientCreds = { credentials, region };
+    return new SDK(config, {
+        kinesisConfig: clientCreds,
+        dynamodbConfig: clientCreds,
+        s3Config: clientCreds,
+        firehoseConfig: clientCreds,
+    });
 }
 //# sourceMappingURL=leo-runtime.js.map

package/dist/rstreams/leo-runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"leo-runtime.js","sourceRoot":"","sources":["../../src/rstreams/leo-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,UAAU,iBAAiB,CAAC,MAA8B;IAC9D,+EAA+E;IAC/E,MAAM,aAAa,GAAG,OAAO,CAAC,SAAS,CAGtC,CAAC;IACF,MAAM,aAAa,GAAG,aAAa,CAAC,OAAO,CAAC;IAC5C,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,WAAW,IAAI,aAAa,EAAE,WAAW,CAEvD,CAAC;IACd,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"leo-runtime.js","sourceRoot":"","sources":["../../src/rstreams/leo-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAO/C,MAAM,UAAU,iBAAiB,CAC/B,MAA8B,EAC9B,OAAkC;IAElC,+EAA+E;IAC/E,MAAM,aAAa,GAAG,OAAO,CAAC,SAAS,CAMtC,CAAC;IACF,MAAM,aAAa,GAAG,aAAa,CAAC,OAAO,CAAC;IAC5C,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,WAAW,IAAI,aAAa,EAAE,WAAW,CAKvD,CAAC;IACd,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,CAAC;IACzC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IAED,+EAA+E;IAC/E,uEAAuE;IACvE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,MAAM,WAAW,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAC5C,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE;QACrB,aAAa,EAAE,WAAW;QAC1B,cAAc,EAAE,WAAW;QAC3B,QAAQ,EAAE,WAAW;QACrB,cAAc,EAAE,WAAW;KAC5B,CAAC,CAAC;AACL,CAAC"}

package/docs/code-first-cli.md

@@ -86,9 +86,10 @@ Scaffolds a **Loxtep workspace** in the current directory.
 | `workflows/` | Workflow modules you author and deploy |
 | `data-products/` | Data product definitions |
 
-With **`--template <slug>`**, init also materializes template content from the
-platform catalog, including **`AGENTS.md`** and a default skill at
-**`.loxtep/skills/<slug>.yaml`**.
+With **`--template shopify-orders`**, init materializes the **bundled runnable
+sample** (workflow, event fixture, AGENTS.md, skill, package/tsconfig). Other
+slugs still write AGENTS.md + a default skill from catalog metadata when
+available.
 
 ### Common flags
 
@@ -141,17 +142,18 @@ Import in workflow modules:
 
 ```typescript
 import { defineDataWorkflow, on } from '@loxtep/sdk';
-import { workspace } from './.loxtep/generated';
+import { workspace } from '../.loxtep/generated/index.js';
 
 export default defineDataWorkflow({
   name: 'orders-enricher',
-  triggers: [on.queueEvent(workspace.queues.orders_raw)],
+  triggers: [on.webhook('/shopify/orders')],
+  requireApproval: ['dataProducts.write'],
   async handler(ctx, event) {
-    await ctx.toolbox.dataProducts.upsert({
-      dataProduct: workspace.dataProducts.orders_enriched,
-      domain: workspace.domains.commerce,
-      record: event,
-    });
+    const order = (event ?? {}) as Record<string, unknown>;
+    await ctx.toolbox!.dataProducts.write(
+      workspace.dataProducts.orders_enriched,
+      { ...order, enriched_at: new Date().toISOString(), source: 'orders-enricher' }
+    );
   },
 });
 ```
@@ -161,6 +163,19 @@ credentials without hand-wiring env vars.
 
 ---
 
+## `loxtep setup` (shopify-orders)
+
+After attach, provision the sample data products (idempotent):
+
+```bash
+pnpm exec loxtep setup
+```
+
+Creates `orders_raw` and `orders_enriched` via `ingest create --deploy` when
+missing. Requires an org domain.
+
+---
+
 ## `loxtep test` and `loxtep deploy`
 
 ```bash
@@ -168,8 +183,9 @@ pnpm exec loxtep test orders-enricher --event ./events/order-created.json
 pnpm exec loxtep deploy
 ```
 
-- **`test`** — runs one workflow module locally against the attached instance and
-  prints an action trace.
+- **`test`** — runs one workflow module **locally with live instance I/O** and
+  prints an action trace. Guarded ops (`requireApproval`) prompt; reject/timeout
+  and handler errors exit **nonzero**.
 - **`deploy`** — compiles modules into the platform workflow graph and deploys to
   the attached instance.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxtep/sdk",
-  "version": "0.9.14",
+  "version": "0.9.16",
   "description": "Loxtep SDK for Node.js — the Enterprise Context Layer: data products, workflows, projects, queues, and machine-usable context for AI",
   "author": "Loxtep <engineering@loxtep.io>",
   "homepage": "https://loxtep.io",
@@ -34,17 +34,19 @@
     "dist",
     "docs",
     "schemas",
+    "templates",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc && mkdir -p dist/lib/entity-json-schemas && cp src/lib/entity-json-schemas/ajv-loader.cjs dist/lib/entity-json-schemas/ajv-loader.cjs",
+    "build": "tsc && mkdir -p dist/lib/entity-json-schemas && cp src/lib/entity-json-schemas/ajv-loader.cjs dist/lib/entity-json-schemas/ajv-loader.cjs && cp src/cli/resolve-package-root.cjs dist/cli/resolve-package-root.cjs",
     "prepublishOnly": "npm run build",
     "test": "jest --config jest.config.cjs",
     "lint": "eslint src --ext .ts",
     "sync:entity-schemas": "node scripts/sync-entity-schemas.mjs",
     "generate:api-types": "tsx scripts/generate-api-types.ts",
     "docs": "typedoc",
-    "test:e2e:cli": "bash scripts/cli-e2e.sh"
+    "test:e2e:cli": "bash scripts/cli-e2e.sh",
+    "test:e2e:try-it": "bash scripts/try-it-onboarding-e2e.sh"
   },
   "publishConfig": {
     "access": "public",
@@ -89,6 +91,7 @@
     "ajv-formats": "^3.0.1",
     "js-yaml": "^4.3.0",
     "leo-sdk": "7.1.21",
+    "tsx": "^4.22.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -97,7 +100,6 @@
     "fast-check": "^4.8.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.9",
-    "tsx": "^4.22.0",
     "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
     "zod-to-ts": "^2.0.0"

package/templates/shopify-orders/AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md — shopify-orders
+
+This project was scaffolded from the `shopify-orders` template (Try it sample).
+
+## MCP tools
+
+```json
+{ "mcpServers": { "loxtep": { "url": "https://mcp.loxtep.io/ai/mcp/stream" } } }
+```
+
+Dev MCP host: `https://mcpdev.loxtep.io/ai/mcp/stream`.
+
+## Lifecycle
+
+```bash
+loxtep login
+loxtep attach --instance <non-prod-instance-id>
+loxtep setup
+loxtep generate
+loxtep test orders-enricher --event ./events/order-created.json
+loxtep deploy
+```
+
+`loxtep test` runs the handler locally with **live** instance I/O. Approve
+`dataProducts.write` when prompted.
+
+## SDK methods
+
+- `LoxtepClient.fromWorkspace()` — configure from `.loxtep/project.json`
+- `defineDataWorkflow({ name, triggers, handler, requireApproval })`
+- `workspace.dataProducts.*` — typed constants after `loxtep generate`
+
+## Skill scope
+
+Default skill: `.loxtep/skills/shopify-orders.yaml`

package/templates/shopify-orders/README.md

@@ -0,0 +1,50 @@
+# Shopify orders sample (`shopify-orders`)
+
+Minimal code-first Loxtep workspace used by [Try it](https://loxtep.io/try-it).
+
+## Prerequisites
+
+| Requirement | Notes |
+| --- | --- |
+| **Node.js 22+** | `node --version` |
+| **Loxtep account** | [app.loxtep.io](https://app.loxtep.io) |
+| **Auth** | `loxtep login` (writes `./.loxtep/credentials.json`) |
+| **Instance** | Non-production preferred — `loxtep instances list` then `loxtep attach` |
+| **Domain** | Org must have at least one domain (create in UI if none) |
+
+`loxtep test` executes your handler **locally with live instance I/O** (stream writes).
+It is not an offline simulator. Sample writes require terminal approval
+(`requireApproval: ['dataProducts.write']`).
+
+## Lifecycle (empty directory → deploy)
+
+```bash
+mkdir shopify-orders-demo && cd shopify-orders-demo
+npm init -y
+npm install @loxtep/sdk@^0.9.16
+npx loxtep login
+npx loxtep init --template shopify-orders
+npx loxtep attach --instance <non-prod-instance-id>
+npx loxtep setup                 # provisions orders_raw + orders_enriched (idempotent)
+npx loxtep generate
+npx loxtep test orders-enricher --event ./events/order-created.json
+# Approve dataProducts.write when prompted (y)
+npx loxtep deploy
+```
+
+Re-running `setup` is safe: existing data products are reused.
+
+## What this template scaffolds
+
+| Path | Purpose |
+| --- | --- |
+| `workflows/orders-enricher.ts` | Sample module (webhook → enrich → write) |
+| `events/order-created.json` | Fixture for `loxtep test` |
+| `AGENTS.md` / `.loxtep/skills/` | Agent + skill scope |
+| `package.json` / `tsconfig.json` | Node 22 + typed workflows |
+
+## Approval / failure behavior
+
+- Reject or timeout on a guarded write → operation skipped, **nonzero exit**
+- Handler or toolbox errors → recorded in the action trace, **nonzero exit**
+- Success → exit 0 and a trace with `handler.start` → `dataProducts.write` → `handler.complete`

package/templates/shopify-orders/events/order-created.json

@@ -0,0 +1,17 @@
+{
+  "id": "gid://shopify/Order/5678901234",
+  "name": "#1001",
+  "email": "customer@example.com",
+  "created_at": "2026-09-22T12:00:00Z",
+  "currency": "USD",
+  "total_price": "129.99",
+  "financial_status": "paid",
+  "line_items": [
+    {
+      "id": 1,
+      "title": "Sample Widget",
+      "quantity": 1,
+      "price": "129.99"
+    }
+  ]
+}

package/templates/shopify-orders/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "loxtep-shopify-orders-sample",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@loxtep/sdk": "^0.9.16"
+  }
+}

package/templates/shopify-orders/skills/shopify-orders.yaml

@@ -0,0 +1,29 @@
+# Default skill for the shopify-orders template.
+# Scoped to the sample resources provisioned by `loxtep setup`.
+name: shopify-orders
+description: Shopify orders enricher sample — orders_raw ingest and orders_enriched write target
+scope:
+  # workflows left empty until after first `loxtep deploy` of orders-enricher
+  # (generate validates skill refs against the live workspace).
+  data_products:
+    - orders_raw
+    - orders_enriched
+  connectors: []
+  workflows: []
+  domains: []
+  queues: []
+permissions:
+  data_products:
+    - read
+    - write
+  connectors:
+    - read
+  workflows:
+    - read
+    - write
+    - create
+  domains:
+    - read
+  queues:
+    - read
+    - write

package/templates/shopify-orders/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["workflows/**/*.ts", ".loxtep/generated/**/*.ts"]
+}

package/templates/shopify-orders/workflows/orders-enricher.ts

@@ -0,0 +1,31 @@
+/**
+ * Sample: enrich an inbound Shopify order and write it to `orders_enriched`.
+ *
+ * Prerequisites (see README / `loxtep setup`):
+ *   - attached non-production instance
+ *   - `orders_enriched` data product provisioned and deployed
+ *   - `loxtep generate` so `.loxtep/generated` exists
+ *
+ * `loxtep test` runs this handler locally against the attached instance
+ * (live stream I/O — not an offline simulation). `dataProducts.write` is
+ * gated by `requireApproval` so sample writes cannot silently hit the bus.
+ */
+import { defineDataWorkflow, on } from '@loxtep/sdk';
+import { workspace } from '../.loxtep/generated/index.js';
+
+export default defineDataWorkflow({
+  name: 'orders-enricher',
+  // Webhook trigger avoids depending on a friendly observe queue name.
+  // After `loxtep setup`, you can switch to on.queueEvent(workspace.queues.*)
+  // once a matching queue appears in `loxtep generate` output.
+  triggers: [on.webhook('/shopify/orders')],
+  requireApproval: ['dataProducts.write'],
+  async handler(ctx, event) {
+    const order = (event ?? {}) as Record<string, unknown>;
+    await ctx.toolbox.dataProducts.write(workspace.dataProducts.orders_enriched, {
+      ...order,
+      enriched_at: new Date().toISOString(),
+      source: 'orders-enricher',
+    });
+  },
+});