@loxtep/sdk 0.7.7 → 0.7.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +119 -116
  3. package/dist/auth/browser-login.d.ts +6 -0
  4. package/dist/auth/browser-login.d.ts.map +1 -1
  5. package/dist/auth/browser-login.js +54 -26
  6. package/dist/auth/browser-login.js.map +1 -1
  7. package/dist/cli/commands/deploy-cmd.d.ts +2 -0
  8. package/dist/cli/commands/deploy-cmd.d.ts.map +1 -1
  9. package/dist/cli/commands/deploy-cmd.js +1 -1
  10. package/dist/cli/commands/deploy-cmd.js.map +1 -1
  11. package/dist/cli/commands/generate-cmd.d.ts +7 -1
  12. package/dist/cli/commands/generate-cmd.d.ts.map +1 -1
  13. package/dist/cli/commands/generate-cmd.js +4 -3
  14. package/dist/cli/commands/generate-cmd.js.map +1 -1
  15. package/dist/cli/commands/test-cmd.d.ts +2 -0
  16. package/dist/cli/commands/test-cmd.d.ts.map +1 -1
  17. package/dist/cli/commands/test-cmd.js +1 -1
  18. package/dist/cli/commands/test-cmd.js.map +1 -1
  19. package/dist/cli/commands/whoami.d.ts +10 -12
  20. package/dist/cli/commands/whoami.d.ts.map +1 -1
  21. package/dist/cli/commands/whoami.js +6 -2
  22. package/dist/cli/commands/whoami.js.map +1 -1
  23. package/dist/cli/create-cli-client.d.ts +2 -0
  24. package/dist/cli/create-cli-client.d.ts.map +1 -1
  25. package/dist/cli/create-cli-client.js +5 -1
  26. package/dist/cli/create-cli-client.js.map +1 -1
  27. package/dist/cli/index.js +0 -0
  28. package/dist/cli/version.d.ts.map +1 -1
  29. package/dist/cli/version.js +1 -6
  30. package/dist/cli/version.js.map +1 -1
  31. package/dist/client/current-user-response.d.ts +18 -0
  32. package/dist/client/current-user-response.d.ts.map +1 -0
  33. package/dist/client/current-user-response.js +50 -0
  34. package/dist/client/current-user-response.js.map +1 -0
  35. package/dist/client/session.d.ts.map +1 -1
  36. package/dist/client/session.js +4 -2
  37. package/dist/client/session.js.map +1 -1
  38. package/docs/code-first-cli.md +10 -8
  39. package/docs/event-replay-cookbook.md +3 -4
  40. package/docs/getting-started.md +152 -201
  41. package/docs/quick-reference.md +10 -11
  42. package/package.json +1 -1
  43. package/dist/cli/commands/connections-cmd.d.ts +0 -19
  44. package/dist/cli/commands/connections-cmd.d.ts.map +0 -1
  45. package/dist/cli/commands/connections-cmd.js +0 -39
  46. package/dist/cli/commands/connections-cmd.js.map +0 -1
  47. package/dist/cli/commands/data-assets-cmd.d.ts +0 -12
  48. package/dist/cli/commands/data-assets-cmd.d.ts.map +0 -1
  49. package/dist/cli/commands/data-assets-cmd.js +0 -75
  50. package/dist/cli/commands/data-assets-cmd.js.map +0 -1
  51. package/dist/cli/commands/flows-cmd.d.ts +0 -19
  52. package/dist/cli/commands/flows-cmd.d.ts.map +0 -1
  53. package/dist/cli/commands/flows-cmd.js +0 -37
  54. package/dist/cli/commands/flows-cmd.js.map +0 -1
  55. package/dist/cli/commands/pipelines-cmd.d.ts +0 -17
  56. package/dist/cli/commands/pipelines-cmd.d.ts.map +0 -1
  57. package/dist/cli/commands/pipelines-cmd.js +0 -52
  58. package/dist/cli/commands/pipelines-cmd.js.map +0 -1
  59. package/dist/cli/commands/promises-cmd.d.ts +0 -11
  60. package/dist/cli/commands/promises-cmd.d.ts.map +0 -1
  61. package/dist/cli/commands/promises-cmd.js +0 -53
  62. package/dist/cli/commands/promises-cmd.js.map +0 -1
  63. package/dist/client/connection-types.d.ts +0 -98
  64. package/dist/client/connection-types.d.ts.map +0 -1
  65. package/dist/client/connection-types.js +0 -18
  66. package/dist/client/connection-types.js.map +0 -1
  67. package/dist/client/connections.d.ts +0 -18
  68. package/dist/client/connections.d.ts.map +0 -1
  69. package/dist/client/connections.js +0 -66
  70. package/dist/client/connections.js.map +0 -1
  71. package/dist/client/consumptions-types.d.ts +0 -80
  72. package/dist/client/consumptions-types.d.ts.map +0 -1
  73. package/dist/client/consumptions-types.js +0 -5
  74. package/dist/client/consumptions-types.js.map +0 -1
  75. package/dist/client/consumptions.d.ts +0 -14
  76. package/dist/client/consumptions.d.ts.map +0 -1
  77. package/dist/client/consumptions.js +0 -47
  78. package/dist/client/consumptions.js.map +0 -1
  79. package/dist/client/data-assets-types.d.ts +0 -150
  80. package/dist/client/data-assets-types.d.ts.map +0 -1
  81. package/dist/client/data-assets-types.js +0 -5
  82. package/dist/client/data-assets-types.js.map +0 -1
  83. package/dist/client/data-assets.d.ts +0 -31
  84. package/dist/client/data-assets.d.ts.map +0 -1
  85. package/dist/client/data-assets.js +0 -182
  86. package/dist/client/data-assets.js.map +0 -1
  87. package/dist/client/delivery-types.d.ts +0 -97
  88. package/dist/client/delivery-types.d.ts.map +0 -1
  89. package/dist/client/delivery-types.js +0 -10
  90. package/dist/client/delivery-types.js.map +0 -1
  91. package/dist/client/delivery.d.ts +0 -23
  92. package/dist/client/delivery.d.ts.map +0 -1
  93. package/dist/client/delivery.js +0 -105
  94. package/dist/client/delivery.js.map +0 -1
  95. package/dist/client/flows.d.ts +0 -33
  96. package/dist/client/flows.d.ts.map +0 -1
  97. package/dist/client/flows.js +0 -218
  98. package/dist/client/flows.js.map +0 -1
@@ -1,24 +1,25 @@
1
1
  # SDK Getting Started Guide
2
2
 
3
- Get from zero to your first event in under 5 minutes. This guide walks you
4
- through installing the Loxtep SDK, authenticating, and writing your first event
5
- to a data product all with a single method call.
3
+ Get from zero to a working Loxtep workspace: authenticate, scaffold a project,
4
+ attach to a runtime instance, and generate typed constants. Stream read/write
5
+ comes **after** you deploy a workflow that publishes a data product.
6
6
 
7
- > **Other paths:** This guide covers the **programmatic SDK** path (no
8
- > `loxtep init` required). For **code-first workflow authoring**, see the
9
- > [Code-first CLI guide](./code-first-cli.md) (`init → attach → generate → test → deploy`).
10
- > Loxtep also supports an [Agent-first (MCP)](https://github.com/LoxtepInc/loxtep-plugins-skills)
11
- > path and a **Web UI** at [app.loxtep.io](https://app.loxtep.io). See the
12
- > [Loxtep Quickstart](https://docs.loxtep.io/quickstart) for all paths.
7
+ > **Other paths:** [Code-first CLI](./code-first-cli.md) (`init attach
8
+ > generate → test → deploy`), [Agent-first MCP](https://github.com/LoxtepInc/loxtep-plugins-skills),
9
+ > or the **Web UI** at [app.loxtep.io](https://app.loxtep.io).
10
+ > Overview: [Loxtep Quickstart](https://docs.loxtep.io/quickstart).
13
11
 
14
12
  ## Table of Contents
15
13
 
16
14
  - [Prerequisites](#prerequisites)
17
15
  - [Step 1: Install the SDK](#step-1-install-the-sdk)
18
16
  - [Step 2: Log In](#step-2-log-in)
19
- - [Step 3: Write Your First Event](#step-3-write-your-first-event)
20
- - [Step 4: Read Events Back](#step-4-read-events-back)
21
- - [Complete Example](#complete-example)
17
+ - [Step 3: Scaffold a Workspace](#step-3-scaffold-a-workspace)
18
+ - [Step 4: Attach to an Instance](#step-4-attach-to-an-instance)
19
+ - [Step 5: Generate Typed Constants](#step-5-generate-typed-constants)
20
+ - [Step 6: Explore the Platform](#step-6-explore-the-platform)
21
+ - [Step 7: Use the SDK in Application Code](#step-7-use-the-sdk-in-application-code)
22
+ - [Step 8: Write and Read Events (after deploy)](#step-8-write-and-read-events-after-deploy)
22
23
  - [Troubleshooting](#troubleshooting)
23
24
  - [Next Steps](#next-steps)
24
25
 
@@ -26,31 +27,27 @@ to a data product — all with a single method call.
26
27
 
27
28
  ## Prerequisites
28
29
 
29
- Before you begin, make sure you have:
30
-
31
30
  | Requirement | Details |
32
31
  |-------------|---------|
33
- | **Node.js 22+** | Required for the Node.js SDK (`@loxtep/sdk`). Check with `node --version`. |
34
- | **Loxtep account** | You need an account with the **developer** role. Ask your org admin if you don't have one. |
35
- | **A deployed data product** | Your organization must have at least one data product deployed to an instance. |
32
+ | **Node.js 22+** | Required for `@loxtep/sdk`. Check with `node --version`. |
33
+ | **Loxtep account** | Sign up at [app.loxtep.io](https://app.loxtep.io). |
34
+ | **Runtime instance** | Your org needs at least one instance (`loxtep instances list`). New trials usually include a shared dev instance. |
35
+
36
+ You do **not** need an existing data product on day one. Empty lists after
37
+ attach are normal until you deploy workflows.
36
38
 
37
39
  ---
38
40
 
39
41
  ## Step 1: Install the SDK
40
42
 
41
- ```bash
42
- pnpm add @loxtep/sdk
43
- ```
44
-
45
- Or with your preferred package manager:
43
+ Create a directory for your project, then install:
46
44
 
47
45
  ```bash
48
- npm install @loxtep/sdk
49
- # or
50
- yarn add @loxtep/sdk
46
+ mkdir my-loxtep-app && cd my-loxtep-app
47
+ pnpm add @loxtep/sdk
51
48
  ```
52
49
 
53
- Verify the installation:
50
+ Verify the CLI:
54
51
 
55
52
  ```bash
56
53
  pnpm exec loxtep --version
@@ -60,270 +57,224 @@ pnpm exec loxtep --version
60
57
 
61
58
  ## Step 2: Log In
62
59
 
63
- Authenticate with your Loxtep account. This stores credentials locally so the
64
- SDK can make API calls on your behalf.
65
-
66
60
  ```bash
67
61
  pnpm exec loxtep login
62
+ pnpm exec loxtep whoami
68
63
  ```
69
64
 
70
- Follow the prompts to enter your email and password. On success you'll see:
71
-
72
- ```
73
- ✓ Logged in successfully. Credentials saved to ./.loxtep/credentials.json
74
- ```
65
+ On success, credentials are stored in `./.loxtep/credentials.json` (project-local
66
+ by default). `whoami` should print your email and organization — not placeholders.
75
67
 
76
- **Alternative: use an environment variable.** If you're running in CI/CD or a
77
- container, set the token directly instead of using `loxtep login`:
68
+ **CI / headless:**
78
69
 
79
70
  ```bash
71
+ pnpm exec loxtep login --email you@company.com --password '…'
72
+ # or
80
73
  export LOXTEP_AUTH_TOKEN="your-jwt-token"
81
74
  ```
82
75
 
83
- The SDK checks `LOXTEP_AUTH_TOKEN` first, then `./.loxtep/credentials.json`
84
- (walking up from cwd), then `~/.loxtep/credentials.json`.
85
-
86
76
  ---
87
77
 
88
- ## Step 3: Write Your First Event
89
-
90
- With the new data-product-centric API, you write events by referencing a data
91
- product by name. The SDK resolves all the plumbing (queue names, bot IDs, stream
92
- bus configuration) automatically.
78
+ ## Step 3: Scaffold a Workspace
93
79
 
94
- ```typescript
95
- import { LoxtepClient } from '@loxtep/sdk';
80
+ ```bash
81
+ pnpm exec loxtep init
82
+ ```
96
83
 
97
- const client = new LoxtepClient({
98
- api_url: process.env.LOXTEP_API_URL,
99
- auth: { type: 'jwt', token: process.env.LOXTEP_TOKEN },
100
- });
84
+ Optional starter template:
101
85
 
102
- // Write events to a data product by name (top-level — preferred since v0.7.0)
103
- const writer = await client.get_writer('my-data-product');
104
- writer.write({ id: '123', name: 'Alice' });
105
- await writer.close();
86
+ ```bash
87
+ pnpm exec loxtep init --template shopify-orders
106
88
  ```
107
89
 
108
- That's it. No workflow IDs, no deployment lookups, no queue name conventions.
109
- The SDK resolves the data product's runtime bindings, connects to the correct
110
- stream bus, and writes directly to the data product queue.
90
+ This creates:
111
91
 
112
- ### What happens under the hood
92
+ | Path | Purpose |
93
+ | --- | --- |
94
+ | `.loxtep/project.json` | Project identity; updated by `attach` |
95
+ | `workflows/` | Workflow modules you author and deploy |
96
+ | `connectors/`, `domains/`, `data-products/` | Code-first resource folders |
113
97
 
114
- 1. The SDK looks up the data product by name via the platform API
115
- 2. It resolves the runtime configuration (queue, bot identity, stream config)
116
- 3. It connects to the stream data plane and returns a writer pointed at the correct queue
98
+ `init` can run before or after `login`. Platform project registration happens
99
+ when you're authenticated; local scaffolding always succeeds.
117
100
 
118
- ### Writer options
101
+ ---
119
102
 
120
- You can customize the writer behavior with an options object:
103
+ ## Step 4: Attach to an Instance
121
104
 
122
- ```typescript
123
- const writer = await client.get_writer('my-data-product', {
124
- bot_id: 'custom-bot-id', // Override the resolved bot identity
125
- batch_size: 500, // Events per batch (default: 100)
126
- max_retries: 5, // Retry attempts on failure (default: 3)
127
- });
128
- ```
105
+ List instances, then bind your workspace to one:
129
106
 
130
- ---
107
+ ```bash
108
+ pnpm exec loxtep instances list
109
+ pnpm exec loxtep attach --instance <instance-id>
110
+ ```
131
111
 
132
- ## Step 4: Read Events Back
112
+ `attach` writes `instance_id` and `api_url` into `.loxtep/project.json`.
113
+ Required before `generate`, `test`, and `deploy`.
133
114
 
134
- Reading from a data product is just as simple:
115
+ ---
135
116
 
136
- ```typescript
137
- const reader = await client.get_reader('my-data-product');
117
+ ## Step 5: Generate Typed Constants
138
118
 
139
- for await (const event of reader) {
140
- console.log('Received:', event);
141
- }
119
+ ```bash
120
+ pnpm exec loxtep generate
142
121
  ```
143
122
 
144
- The reader yields events as an async iterable. By default it generates a
145
- reader bot ID of `sdk-reader-{data-product-name}` for checkpoint tracking.
123
+ Pulls live metadata from the platform into `.loxtep/generated/index.ts` (data
124
+ products, connectors, domains, queues, workflows). Re-run after platform changes.
146
125
 
147
- ### Reader options
126
+ ---
148
127
 
149
- ```typescript
150
- const reader = await client.get_reader('my-data-product', {
151
- bot_id: 'my-consumer', // Custom reader identity for checkpointing
152
- from: 'z/2024/01/01', // Start position (default: latest checkpoint)
153
- batch_size: 200, // Events per batch (default: 100)
154
- });
128
+ ## Step 6: Explore the Platform
129
+
130
+ ```bash
131
+ pnpm exec loxtep data-products list
132
+ pnpm exec loxtep workflows list --project-id <project-id>
133
+ pnpm exec loxtep domains list
155
134
  ```
156
135
 
136
+ On a new account, **data products may be empty** until you create and deploy
137
+ workflows (CLI, MCP, or Web UI). That's expected — don't call `get_writer` yet.
138
+
157
139
  ---
158
140
 
159
- ## Complete Example
141
+ ## Step 7: Use the SDK in Application Code
160
142
 
161
- ```typescript
162
- // first-event.ts
163
- // Run: pnpm exec tsx first-event.ts
143
+ Prefer workspace auto-config instead of hand-building `api_url` and tokens:
164
144
 
145
+ ```typescript
165
146
  import { LoxtepClient } from '@loxtep/sdk';
166
147
 
167
- async function main() {
168
- const client = new LoxtepClient({
169
- api_url: process.env.LOXTEP_API_URL,
170
- auth: { type: 'jwt', token: process.env.LOXTEP_TOKEN },
171
- });
148
+ const client = await LoxtepClient.fromWorkspace();
149
+ const { user, organization } = await client.session.get_current_user();
172
150
 
173
- // Write an event to a data product
174
- const writer = await client.get_writer('my-data-product');
175
-
176
- writer.write({
177
- id: `event-${Date.now()}`,
178
- timestamp: new Date().toISOString(),
179
- payload: { message: 'Hello from the Loxtep SDK!' },
180
- });
181
-
182
- await writer.close();
183
- console.log('✓ Event written');
184
-
185
- // Read it back
186
- const reader = await client.get_reader('my-data-product', {
187
- bot_id: 'quickstart-reader',
188
- });
151
+ console.log(user.email, organization?.name);
152
+ ```
189
153
 
190
- for await (const event of reader) {
191
- console.log('✓ Event received:', JSON.stringify(event, null, 2));
192
- break; // Just read the first one to verify
193
- }
154
+ `fromWorkspace()` reads `.loxtep/project.json` and `./.loxtep/credentials.json`
155
+ (walking up from `cwd`). Env overrides: `LOXTEP_API_URL`, `LOXTEP_TOKEN`,
156
+ `LOXTEP_ORGANIZATION_ID`, `LOXTEP_PROJECT_ID`, `LOXTEP_INSTANCE_ID`.
194
157
 
195
- console.log('Done!');
196
- }
158
+ List or manage resources via namespaced APIs:
197
159
 
198
- main().catch(console.error);
160
+ ```typescript
161
+ const { items } = await client.build.data_products.list();
162
+ const instances = await client.workspace.instances.list();
199
163
  ```
200
164
 
201
165
  ---
202
166
 
203
- ## Troubleshooting
204
-
205
- ### Data product not found
167
+ ## Step 8: Write and Read Events (after deploy)
206
168
 
207
- **Symptom:** `NotFoundError: Data product 'my-data-product' not found`
169
+ `get_writer` and `get_reader` resolve queue, bot, and stream configuration from
170
+ **deployment metadata**. They only work for data products that exist **and** are
171
+ deployed on your attached instance.
208
172
 
209
- **Cause:** The SDK could not find a data product matching the name you provided.
173
+ 1. Author a workflow under `workflows/` (see [Code-first CLI](./code-first-cli.md)).
174
+ 2. `pnpm exec loxtep deploy`
175
+ 3. Confirm the data product name:
210
176
 
211
- **Fix:**
212
-
213
- 1. Verify the data product name is spelled correctly (names are case-sensitive).
214
- 2. Check that the data product's workflow has been deployed to an instance.
215
- 3. If you're using a UUID, confirm it matches an existing data product ID.
177
+ ```bash
178
+ pnpm exec loxtep data-products list
179
+ ```
216
180
 
217
- ```bash
218
- # List data products in your organization
219
- pnpm exec loxtep data-products list
220
- ```
181
+ 4. Stream from application code:
221
182
 
222
- ---
183
+ ```typescript
184
+ const client = await LoxtepClient.fromWorkspace();
223
185
 
224
- ### Data product not deployed
186
+ const writer = await client.get_writer('orders'); // use your deployed name
187
+ writer.write({
188
+ order_id: 'ord_1',
189
+ total: 99.5,
190
+ });
191
+ await writer.close();
225
192
 
226
- **Symptom:** `StreamingError: Data product 'my-data-product' is not deployed.
227
- Deploy the workflow first.`
193
+ const reader = await client.get_reader('orders', {
194
+ bot_id: 'my-app-reader',
195
+ });
196
+ for await (const event of reader) {
197
+ console.log(event);
198
+ break;
199
+ }
200
+ ```
228
201
 
229
- **Cause:** The data product exists in the workflow graph but has not been
230
- deployed to an instance. Runtime bindings (queue name, bot ID) are only
231
- available after deployment.
202
+ The SDK resolves runtime bindings automatically no manual queue names or bot IDs.
232
203
 
233
- **Fix:**
204
+ ### Writer / reader options
234
205
 
235
- 1. Deploy the workflow containing the data product:
206
+ ```typescript
207
+ await client.get_writer('orders', {
208
+ batch_size: 500,
209
+ max_retries: 5,
210
+ });
236
211
 
237
- ```bash
238
- pnpm exec loxtep deploy <workflow-id>
212
+ await client.get_reader('orders', {
213
+ bot_id: 'my-consumer',
214
+ from: undefined, // latest checkpoint
215
+ batch_size: 200,
216
+ });
239
217
  ```
240
218
 
241
- 2. Or deploy via the Loxtep UI: **Workflows** → select your workflow → **Deploy**.
242
-
243
- 3. If using an AI assistant with MCP, use the `deploy_workflow` tool.
244
-
245
219
  ---
246
220
 
247
- ### Unable to resolve stream configuration
248
-
249
- **Symptom:** `StreamingError: Failed to resolve stream config for instance
250
- <instance-id>`
221
+ ## Troubleshooting
251
222
 
252
- **Cause:** The SDK resolved the data product and its instance, but could not
253
- retrieve the stream configuration from the instance record.
223
+ ### Run `loxtep init` first / not attached
254
224
 
255
- **Fix:**
225
+ **Symptom:** `Run loxtep init first` or `Run loxtep attach`
256
226
 
257
- 1. Verify the instance is fully provisioned and running in the Loxtep UI.
258
- 2. Check that your account has `instances:read` permission on the target instance.
259
- 3. If the instance was recently created, wait a few minutes for provisioning to
260
- complete.
261
- 4. Contact your platform admin if the instance shows as provisioned but
262
- resolution still fails.
227
+ **Fix:** Complete [Step 3](#step-3-scaffold-a-workspace) and
228
+ [Step 4](#step-4-attach-to-an-instance).
263
229
 
264
230
  ---
265
231
 
266
- ### Multiple data products match
267
-
268
- **Symptom:** `AmbiguityError: Multiple data products match 'my-data-product'.
269
- Found matches on instances: [instance-a, instance-b]`
232
+ ### Data product not found
270
233
 
271
- **Cause:** The same data product name exists on multiple instances and the SDK
272
- cannot determine which one you mean.
234
+ **Symptom:** `NotFoundError: Data product 'orders' not found`
273
235
 
274
- **Fix:**
236
+ **Fix:** Deploy a workflow that publishes the data product, then verify with
237
+ `pnpm exec loxtep data-products list`. Names are case-sensitive.
275
238
 
276
- 1. Set `instance_id` in the client options to scope resolution to a specific
277
- instance:
239
+ ---
278
240
 
279
- ```typescript
280
- const client = new LoxtepClient({
281
- api_url: process.env.LOXTEP_API_URL,
282
- auth: { type: 'jwt', token: process.env.LOXTEP_TOKEN },
283
- instance_id: process.env.LOXTEP_INSTANCE_ID,
284
- });
285
- ```
241
+ ### Data product not deployed
286
242
 
287
- 2. Or use the data product's UUID instead of its name:
243
+ **Symptom:** `StreamingError: is not deployed`
288
244
 
289
- ```typescript
290
- const writer = await client.get_writer('09fa202b-...');
291
- ```
245
+ **Fix:** The catalog entry exists but has no runtime bindings yet. Run
246
+ `pnpm exec loxtep deploy` or deploy via MCP/UI, then retry.
292
247
 
293
248
  ---
294
249
 
295
- ### Missing Auth Token
296
-
297
- **Symptom:** `AuthenticationError: No authentication token found`
250
+ ### Missing auth token
298
251
 
299
- **Cause:** The SDK cannot find a JWT token. Set `LOXTEP_AUTH_TOKEN` (CLI) or
300
- `LOXTEP_TOKEN` (programmatic auto-config), or run `pnpm exec loxtep login` so
301
- `./.loxtep/credentials.json` exists (or `~/.loxtep/credentials.json` with
302
- `--global`).
252
+ **Symptom:** `Missing api_url or access token` / authentication errors
303
253
 
304
254
  **Fix:**
305
255
 
306
256
  ```bash
307
- # Option 1: Log in interactively
308
257
  pnpm exec loxtep login
309
-
310
- # Option 2: Set the token directly (CLI / manual client bootstrap)
311
- export LOXTEP_AUTH_TOKEN="your-jwt-token"
312
- # Auto-config via LoxtepClient.fromWorkspace() also reads LOXTEP_TOKEN
313
- export LOXTEP_TOKEN="your-jwt-token"
258
+ pnpm exec loxtep whoami
314
259
  ```
315
260
 
316
261
  ---
317
262
 
318
- ## Next Steps
263
+ ### Multiple data products match
264
+
265
+ **Symptom:** `AmbiguityError: Multiple data products match …`
266
+
267
+ **Fix:** Set `instance_id` in `.loxtep/project.json` via `attach`, or pass a
268
+ data product UUID instead of a name.
319
269
 
320
- Now that you've written and read your first event, explore these resources:
270
+ ---
271
+
272
+ ## Next Steps
321
273
 
322
274
  | Resource | Description |
323
275
  |----------|-------------|
324
- | [Code-first CLI guide](./code-first-cli.md) | `loxtep init`, attach, generate, test, deploy |
325
- | [Quick Reference Card](./quick-reference.md) | Single-page cheat sheet for common SDK operations |
326
- | [Event Replay Cookbook](./event-replay-cookbook.md) | Patterns for replaying and reprocessing historical events |
327
- | [MCP → SDK Mapping](./sdk-mcp-mapping.md) | How MCP tools map to SDK methods |
276
+ | [Code-first CLI guide](./code-first-cli.md) | Workflow modules, `test`, `deploy` |
277
+ | [Quick Reference Card](./quick-reference.md) | Cheat sheet for common operations |
278
+ | [Event Replay Cookbook](./event-replay-cookbook.md) | Replay and reprocess historical events |
328
279
 
329
- See the [SDK README](../README.md) for the full API surface.
280
+ See the [SDK README](../README.md) for the full API surface and CLI reference.
@@ -1,8 +1,8 @@
1
1
  # SDK Quick Reference Card
2
2
 
3
- Concise cheat sheet for common Loxtep SDK operations (Node.js **v0.7+** MCP
4
- facades). For full walkthroughs, see the [Getting Started Guide](./getting-started.md)
5
- (programmatic) or [Code-first CLI guide](./code-first-cli.md) (`loxtep init`).
3
+ Concise cheat sheet for common Loxtep SDK operations (Node.js).
4
+ For full walkthroughs, see the [Getting Started Guide](./getting-started.md)
5
+ or [Code-first CLI guide](./code-first-cli.md).
6
6
 
7
7
  ---
8
8
 
@@ -13,7 +13,11 @@ facades). For full walkthroughs, see the [Getting Started Guide](./getting-start
13
13
  ```typescript
14
14
  import { LoxtepClient } from '@loxtep/sdk';
15
15
 
16
- const client = new LoxtepClient({
16
+ // Recommended after `login` + `init` + `attach`:
17
+ const client = await LoxtepClient.fromWorkspace();
18
+
19
+ // Explicit config (CI, multi-tenant scripts):
20
+ const explicit = new LoxtepClient({
17
21
  api_url: process.env.LOXTEP_API_URL,
18
22
  auth: { type: 'jwt', token: process.env.LOXTEP_AUTH_TOKEN! },
19
23
  organization_id: process.env.LOXTEP_ORGANIZATION_ID,
@@ -21,9 +25,6 @@ const client = new LoxtepClient({
21
25
  instance_id: process.env.LOXTEP_INSTANCE_ID,
22
26
  region: process.env.LOXTEP_REGION,
23
27
  });
24
-
25
- // Or from workspace files after `loxtep init` + `loxtep login`:
26
- const wsClient = LoxtepClient.fromWorkspace();
27
28
  ```
28
29
 
29
30
  ### Python
@@ -51,7 +52,7 @@ bus config from deployment metadata.
51
52
  ### Node.js
52
53
 
53
54
  ```typescript
54
- const writer = await client.get_writer('my-data-product');
55
+ const writer = await client.get_writer('orders'); // deployed data product name
55
56
 
56
57
  writer.write({ id: 'evt-1', payload: { key: 'value' } });
57
58
  writer.write({ id: 'evt-2', payload: { key: 'value' } });
@@ -175,8 +176,6 @@ const hits = await client.query.catalog.search({ query: 'orders' });
175
176
  | **Catalog search** | `client.query.catalog.search({ query })` |
176
177
  | **Invalidate cache** | `client.build.data_products.invalidate_cache('name')` |
177
178
 
178
- See [MCP → SDK mapping](./sdk-mcp-mapping.md) for all 10 facades.
179
-
180
179
  ---
181
180
 
182
181
  ## CLI Shortcuts
@@ -220,4 +219,4 @@ in application code.
220
219
  |----------|-------------|
221
220
  | [Getting Started Guide](./getting-started.md) | Zero-to-first-event walkthrough |
222
221
  | [Event Replay Cookbook](./event-replay-cookbook.md) | Replay patterns (`build.data_products`, `observe`) |
223
- | [MCP SDK Mapping](./sdk-mcp-mapping.md) | How MCP tools map to SDK methods |
222
+ | [Code-first CLI guide](./code-first-cli.md) | `loxtep init` through deploy |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loxtep/sdk",
3
- "version": "0.7.7",
3
+ "version": "0.7.10",
4
4
  "description": "Loxtep SDK for Node.js — the Enterprise Context Layer: data products, workflows, projects, queues, and machine-usable context for AI",
5
5
  "author": "Loxtep <engineering@loxtep.io>",
6
6
  "homepage": "https://loxtep.io",
@@ -1,19 +0,0 @@
1
- /**
2
- * CLI: loxtep connections list | connections get <id> | connections create ... | connections test <id>
3
- */
4
- export interface ConnectionsCmdOptions {
5
- configFilePath?: string;
6
- credentialsPath?: string;
7
- customerMcpPath?: string;
8
- }
9
- export declare function runConnectionsList(options?: ConnectionsCmdOptions): Promise<void>;
10
- export declare function runConnectionsGet(connectionId: string, options?: ConnectionsCmdOptions): Promise<void>;
11
- export declare function runConnectionsCreate(params: {
12
- name?: string;
13
- type?: string;
14
- key?: string;
15
- data?: string;
16
- configuration?: Record<string, unknown>;
17
- }, options?: ConnectionsCmdOptions): Promise<void>;
18
- export declare function runConnectionsTest(connectionId: string, options?: ConnectionsCmdOptions): Promise<void>;
19
- //# sourceMappingURL=connections-cmd.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"connections-cmd.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/connections-cmd.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,qBAAqB;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3F;AAED,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE;IACN,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC,EACD,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAIf"}
@@ -1,39 +0,0 @@
1
- /**
2
- * CLI: loxtep connections list | connections get <id> | connections create ... | connections test <id>
3
- */
4
- import { requireCliClient } from '../create-cli-client.js';
5
- export async function runConnectionsList(options = {}) {
6
- const { client } = await requireCliClient(options);
7
- const result = await client.connections.list({ page_size: 50 });
8
- console.log(JSON.stringify(result, null, 2));
9
- }
10
- export async function runConnectionsGet(connectionId, options = {}) {
11
- const { client } = await requireCliClient(options);
12
- const conn = await client.connections.get(connectionId);
13
- console.log(JSON.stringify(conn, null, 2));
14
- }
15
- export async function runConnectionsCreate(params, options = {}) {
16
- const { client } = await requireCliClient(options);
17
- const name = params.name ?? '';
18
- const type = params.type ?? 'api';
19
- const key = params.key ?? params.name ?? '';
20
- if (!name || !key) {
21
- console.error('Missing required: --name, --type, --key');
22
- process.exitCode = 1;
23
- return;
24
- }
25
- const conn = await client.connections.create({
26
- name,
27
- type: type,
28
- key,
29
- data: params.data ?? '{}',
30
- configuration: params.configuration,
31
- });
32
- console.log(JSON.stringify(conn, null, 2));
33
- }
34
- export async function runConnectionsTest(connectionId, options = {}) {
35
- const { client } = await requireCliClient(options);
36
- const result = await client.connections.test(connectionId);
37
- console.log(JSON.stringify(result, null, 2));
38
- }
39
- //# sourceMappingURL=connections-cmd.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"connections-cmd.js","sourceRoot":"","sources":["../../../src/cli/commands/connections-cmd.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAQ3D,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,UAAiC,EAAE;IAC1E,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,YAAoB,EACpB,UAAiC,EAAE;IAEnC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACxD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAMC,EACD,UAAiC,EAAE;IAEnC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC;IAClC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;IAC5C,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACzD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;QAC3C,IAAI;QACJ,IAAI,EAAE,IAA+C;QACrD,GAAG;QACH,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;QACzB,aAAa,EAAE,MAAM,CAAC,aAAa;KACpC,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,YAAoB,EACpB,UAAiC,EAAE;IAEnC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3D,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC"}
@@ -1,12 +0,0 @@
1
- /**
2
- * CLI: loxtep data-assets list | data-assets get <id>
3
- */
4
- export interface DataAssetsCmdOptions {
5
- configFilePath?: string;
6
- credentialsPath?: string;
7
- }
8
- export declare function runDataAssetsList(options?: DataAssetsCmdOptions): Promise<void>;
9
- export declare function runDataAssetsGet(dataAssetId: string, options?: DataAssetsCmdOptions): Promise<void>;
10
- export declare function runDataAssetsQuery(dataAssetId: string, sql: string, options?: DataAssetsCmdOptions): Promise<void>;
11
- export declare function runDataAssetsTables(dataAssetId: string, options?: DataAssetsCmdOptions): Promise<void>;
12
- //# sourceMappingURL=data-assets-cmd.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"data-assets-cmd.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/data-assets-cmd.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBzF;AAED,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf"}