@loxtep/sdk 0.7.1 → 0.7.7

package/docs/quick-reference.md

@@ -1,7 +1,8 @@
 # SDK Quick Reference Card
 
-Concise cheat sheet for common Loxtep SDK operations. For full walkthroughs,
-see the [Getting Started Guide](./getting-started.md).
+Concise cheat sheet for common Loxtep SDK operations (Node.js **v0.7+** MCP
+facades). For full walkthroughs, see the [Getting Started Guide](./getting-started.md)
+(programmatic) or [Code-first CLI guide](./code-first-cli.md) (`loxtep init`).
 
 ---
 
@@ -14,11 +15,15 @@ import { LoxtepClient } from '@loxtep/sdk';
 
 const client = new LoxtepClient({
   api_url: process.env.LOXTEP_API_URL,
+  auth: { type: 'jwt', token: process.env.LOXTEP_AUTH_TOKEN! },
   organization_id: process.env.LOXTEP_ORGANIZATION_ID,
   project_id: process.env.LOXTEP_PROJECT_ID,
   instance_id: process.env.LOXTEP_INSTANCE_ID,
   region: process.env.LOXTEP_REGION,
 });
+
+// Or from workspace files after `loxtep init` + `loxtep login`:
+const wsClient = LoxtepClient.fromWorkspace();
 ```
 
 ### Python
@@ -36,21 +41,17 @@ client = LoxtepClient(
 )
 ```
 
-> If you ran `loxtep init`, the SDK reads defaults from
-> `~/.loxtep/config.json` — you can use `new LoxtepClient()` with no args.
-
 ---
 
 ## Writing Events
 
-**Recommended: use `data_products.get_writer('name')`** — the SDK resolves
-queue, bot_id, and stream bus config automatically from deployment metadata.
+**Recommended: `client.get_writer('name')`** — resolves queue, bot_id, and stream
+bus config from deployment metadata.
 
 ### Node.js
 
 ```typescript
-// Resolve by name — no manual queue/bot/stream config needed
-const writer = await client.data_products.get_writer('my-data-product');
+const writer = await client.get_writer('my-data-product');
 
 writer.write({ id: 'evt-1', payload: { key: 'value' } });
 writer.write({ id: 'evt-2', payload: { key: 'value' } });
@@ -61,8 +62,7 @@ await writer.close(); // flushes all buffered events
 ### Python
 
 ```python
-# Resolve by name — no manual queue/bot/stream config needed
-writer = await client.data_products.get_writer("my-data-product")
+writer = await client.get_writer("my-data-product")
 
 writer.write({"id": "evt-1", "payload": {"key": "value"}})
 writer.write({"id": "evt-2", "payload": {"key": "value"}})
@@ -74,13 +74,12 @@ await writer.close()  # flushes all buffered events
 
 ## Reading Events
 
-**Recommended: use `data_products.get_reader('name')`** — resolves everything
-automatically.
+**Recommended: `client.get_reader('name')`**
 
 ### Node.js
 
 ```typescript
-const reader = await client.data_products.get_reader('my-data-product');
+const reader = await client.get_reader('my-data-product');
 
 for await (const event of reader) {
   console.log(event);
@@ -90,16 +89,16 @@ for await (const event of reader) {
 ### Python
 
 ```python
-reader = await client.data_products.get_reader("my-data-product")
+reader = await client.get_reader("my-data-product")
 
 for event in reader:
     print(event)
 ```
 
-### Advanced: manual queue reader (`queues` namespace)
+### Advanced: manual queue reader (`client.observe`)
 
 ```typescript
-const reader = await client.queues.open_reader({
+const reader = await client.observe.open_reader({
   bot_id: 'my-reader',
   queue_name: 'raw-events',
 });
@@ -111,14 +110,17 @@ reader.close();
 
 ---
 
-## Data Products
+## Data Products (CRUD / stream / replay)
+
+Under **`client.build.data_products`** for control-plane APIs; top-level
+`get_writer` / `get_reader` for live I/O.
 
 ### Stream Live Events
 
 #### Node.js
 
 ```typescript
-const stream = await client.data_products.stream('<data_product_id>', {
+const stream = await client.build.data_products.stream('<data_product_id>', {
   bot_id: 'my-stream-bot',
 });
 
@@ -127,128 +129,88 @@ for await (const event of stream) {
 }
 ```
 
-#### Python
-
-```python
-stream = client.data_products.stream("<data_product_id>", {
-    "bot_id": "my-stream-bot",
-})
-
-for event in stream:
-    print(event)
-```
-
 ### Replay Historical Events
 
-#### Node.js
-
 ```typescript
-const events = await client.data_products.replay('<data_product_id>', {
+for await (const event of client.build.data_products.replay('<data_product_id>', {
   start: '2024-01-01T00:00:00Z',
   end: '2024-01-02T00:00:00Z',
-});
-```
-
-#### Python
-
-```python
-events = client.data_products.replay("<data_product_id>", {
-    "start": "2024-01-01T00:00:00Z",
-    "end": "2024-01-02T00:00:00Z",
-})
+})) {
+  console.log(event);
+}
 ```
 
-### List and Get Data Products
-
-#### Node.js
+### List and Get
 
 ```typescript
-const products = await client.data_products.list();
-const product = await client.data_products.get('<data_product_id>');
-```
-
-#### Python
-
-```python
-products = client.data_products.list()
-product = client.data_products.get("<data_product_id>")
+const products = await client.build.data_products.list();
+const product = await client.build.data_products.get('<data_product_id>');
 ```
 
 ---
 
 ## Workflows and Connectors
 
-### List Workflows
-
-#### Node.js
-
-```typescript
-const workflows = await client.workflows.list({ project_id: '<project_id>' });
-```
-
-#### Python
-
-```python
-workflows = client.workflows.list(project_id="<project_id>")
-```
-
-### Get Connector
-
-#### Node.js
-
 ```typescript
-const connector = await client.connectors.get('<connector_id>');
-```
-
-#### Python
-
-```python
-connector = client.connectors.get("<connector_id>")
+const workflows = await client.build.workflows.list({ project_id: '<project_id>' });
+const connector = await client.connect.connectors.get('<connector_id>');
+const hits = await client.query.catalog.search({ query: 'orders' });
 ```
 
 ---
 
 ## Quick Reference Table
 
-| Task | Node.js | Python |
-|------|---------|--------|
-| **Init client** | `new LoxtepClient(options)` | `LoxtepClient(**options)` |
-| **Write events** | `await client.data_products.get_writer('name')` → `writer.write(evt)` → `writer.close()` | Same API |
-| **Read events** | `await client.data_products.get_reader('name')` → `for await (const e of reader)` | Same API |
-| **Read (low-level)** | `client.queues.open_reader({ bot_id, queue_name })` → `reader.read()` | Same API |
-| **Stream live** | `client.data_products.stream(id, opts)` | Same API |
-| **Replay history** | `client.data_products.replay(id, opts)` | Same API |
-| **List data products** | `client.data_products.list()` | Same API |
-| **Get data product** | `client.data_products.get(id)` | Same API |
-| **List workflows** | `client.workflows.list({ project_id })` | Same API |
-| **Get connector** | `client.connectors.get(id)` | Same API |
-| **Invalidate cache** | `client.data_products.invalidate_cache('name')` | Same API |
+| Task | Node.js (v0.7+) |
+|------|-----------------|
+| **Init client** | `new LoxtepClient(options)` or `LoxtepClient.fromWorkspace()` |
+| **Write events** | `await client.get_writer('name')` → `writer.write(evt)` → `writer.close()` |
+| **Read events** | `await client.get_reader('name')` → `for await (const e of reader)` |
+| **Read (low-level)** | `client.observe.open_reader({ bot_id, queue_name })` |
+| **Stream live** | `client.build.data_products.stream(id, opts)` |
+| **Replay history** | `client.build.data_products.replay(id, opts)` |
+| **List data products** | `client.build.data_products.list()` |
+| **List workflows** | `client.build.workflows.list({ project_id })` |
+| **Get connector** | `client.connect.connectors.get(id)` |
+| **Catalog search** | `client.query.catalog.search({ query })` |
+| **Invalidate cache** | `client.build.data_products.invalidate_cache('name')` |
+
+See [MCP → SDK mapping](./sdk-mcp-mapping.md) for all 10 facades.
 
 ---
 
 ## CLI Shortcuts
 
+Workspace lifecycle (requires `loxtep init` first — see [Code-first CLI guide](./code-first-cli.md)):
+
 ```bash
-# Log in
-npx loxtep login
+pnpm exec loxtep init [--template shopify-orders]
+pnpm exec loxtep login
+pnpm exec loxtep attach --instance prod
+pnpm exec loxtep generate
+pnpm exec loxtep test my-module --event ./events/sample.json
+pnpm exec loxtep deploy
+```
 
-# Initialize config
-npx loxtep init
+Other commands:
 
-# Export connector config (shell, json, or env format)
-npx loxtep config export --from-connector "<connector_id>" --format sh
-npx loxtep config export --from-connector "<connector_id>" --format json
-npx loxtep config export --from-connector "<connector_id>" --format env
+```bash
+pnpm exec loxtep login
+pnpm exec loxtep config export --from-connector "<connector_id>" --format json
 ```
 
 ---
 
 ## Auth Precedence
 
-The SDK resolves authentication in this order:
+CLI and `fromWorkspace()` resolve tokens in this order:
+
+1. `LOXTEP_AUTH_TOKEN` (CLI) / `LOXTEP_TOKEN` (auto-config env)
+2. Project-local `.loxtep/credentials.json`
+3. `~/.loxtep/credentials.json` (from `loxtep login`)
 
-1. `LOXTEP_AUTH_TOKEN` environment variable
-2. `~/.loxtep/credentials.json` (from `loxtep login`)
+Pass `auth: { type: 'jwt', token }` explicitly when constructing `LoxtepClient`
+in application code.
 
 ---
 
@@ -257,5 +219,5 @@ The SDK resolves authentication in this order:
 | Resource | Description |
 |----------|-------------|
 | [Getting Started Guide](./getting-started.md) | Zero-to-first-event walkthrough |
-| [Event Replay Cookbook](./event-replay-cookbook.md) | Patterns for replaying historical events |
+| [Event Replay Cookbook](./event-replay-cookbook.md) | Replay patterns (`build.data_products`, `observe`) |
 | [MCP → SDK Mapping](./sdk-mcp-mapping.md) | How MCP tools map to SDK methods |

package/docs/sdk-pairing.md

@@ -20,15 +20,15 @@ authenticates via its own OAuth flow in the MCP client, not this file.
 | Typed REST from Node services, scripts, CI | **`@loxtep/sdk`** (`LoxtepClient`) |
 | Quick operator commands, token bootstrap | **`loxtep` CLI** (ships with the SDK) |
 | **Live** queue produce/consume | **SDK** with stream config |
-| **Historical** replay / trace-style reads | **SDK** `data_products.replay()` (REST API) |
+| **Historical** replay / trace-style reads | **SDK** `client.build.data_products.replay()` (REST API) |
 
-There is **no** required joint npm install of MCP and SDK; pair them by
+There is **no** required joint package install of MCP and SDK; pair them by
 **config + docs**, not a metapackage.
 
 ## Install
 
 ```bash
-npm install @loxtep/sdk
+pnpm add @loxtep/sdk
 # Node.js 22+ recommended (see package engines).
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxtep/sdk",
-  "version": "0.7.1",
+  "version": "0.7.7",
   "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",