@loxtep/sdk 0.7.9 → 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.
- package/CHANGELOG.md +22 -0
- package/README.md +94 -87
- package/dist/cli/commands/deploy-cmd.d.ts +2 -0
- package/dist/cli/commands/deploy-cmd.d.ts.map +1 -1
- package/dist/cli/commands/deploy-cmd.js +1 -1
- package/dist/cli/commands/deploy-cmd.js.map +1 -1
- package/dist/cli/commands/generate-cmd.d.ts +7 -1
- package/dist/cli/commands/generate-cmd.d.ts.map +1 -1
- package/dist/cli/commands/generate-cmd.js +4 -3
- package/dist/cli/commands/generate-cmd.js.map +1 -1
- package/dist/cli/commands/test-cmd.d.ts +2 -0
- package/dist/cli/commands/test-cmd.d.ts.map +1 -1
- package/dist/cli/commands/test-cmd.js +1 -1
- package/dist/cli/commands/test-cmd.js.map +1 -1
- package/dist/cli/commands/whoami.d.ts +10 -12
- package/dist/cli/commands/whoami.d.ts.map +1 -1
- package/dist/cli/commands/whoami.js +6 -2
- package/dist/cli/commands/whoami.js.map +1 -1
- package/dist/cli/create-cli-client.d.ts +2 -0
- package/dist/cli/create-cli-client.d.ts.map +1 -1
- package/dist/cli/create-cli-client.js +5 -1
- package/dist/cli/create-cli-client.js.map +1 -1
- package/dist/cli/index.js +0 -0
- package/dist/client/current-user-response.d.ts +18 -0
- package/dist/client/current-user-response.d.ts.map +1 -0
- package/dist/client/current-user-response.js +50 -0
- package/dist/client/current-user-response.js.map +1 -0
- package/dist/client/session.d.ts.map +1 -1
- package/dist/client/session.js +4 -2
- package/dist/client/session.js.map +1 -1
- package/docs/code-first-cli.md +10 -8
- package/docs/event-replay-cookbook.md +3 -4
- package/docs/getting-started.md +152 -200
- package/docs/quick-reference.md +8 -7
- package/package.json +1 -1
- package/dist/cli/commands/connections-cmd.d.ts +0 -19
- package/dist/cli/commands/connections-cmd.d.ts.map +0 -1
- package/dist/cli/commands/connections-cmd.js +0 -39
- package/dist/cli/commands/connections-cmd.js.map +0 -1
- package/dist/cli/commands/data-assets-cmd.d.ts +0 -12
- package/dist/cli/commands/data-assets-cmd.d.ts.map +0 -1
- package/dist/cli/commands/data-assets-cmd.js +0 -75
- package/dist/cli/commands/data-assets-cmd.js.map +0 -1
- package/dist/cli/commands/flows-cmd.d.ts +0 -19
- package/dist/cli/commands/flows-cmd.d.ts.map +0 -1
- package/dist/cli/commands/flows-cmd.js +0 -37
- package/dist/cli/commands/flows-cmd.js.map +0 -1
- package/dist/cli/commands/pipelines-cmd.d.ts +0 -17
- package/dist/cli/commands/pipelines-cmd.d.ts.map +0 -1
- package/dist/cli/commands/pipelines-cmd.js +0 -52
- package/dist/cli/commands/pipelines-cmd.js.map +0 -1
- package/dist/cli/commands/promises-cmd.d.ts +0 -11
- package/dist/cli/commands/promises-cmd.d.ts.map +0 -1
- package/dist/cli/commands/promises-cmd.js +0 -53
- package/dist/cli/commands/promises-cmd.js.map +0 -1
- package/dist/client/connection-types.d.ts +0 -98
- package/dist/client/connection-types.d.ts.map +0 -1
- package/dist/client/connection-types.js +0 -18
- package/dist/client/connection-types.js.map +0 -1
- package/dist/client/connections.d.ts +0 -18
- package/dist/client/connections.d.ts.map +0 -1
- package/dist/client/connections.js +0 -66
- package/dist/client/connections.js.map +0 -1
- package/dist/client/consumptions-types.d.ts +0 -80
- package/dist/client/consumptions-types.d.ts.map +0 -1
- package/dist/client/consumptions-types.js +0 -5
- package/dist/client/consumptions-types.js.map +0 -1
- package/dist/client/consumptions.d.ts +0 -14
- package/dist/client/consumptions.d.ts.map +0 -1
- package/dist/client/consumptions.js +0 -47
- package/dist/client/consumptions.js.map +0 -1
- package/dist/client/data-assets-types.d.ts +0 -150
- package/dist/client/data-assets-types.d.ts.map +0 -1
- package/dist/client/data-assets-types.js +0 -5
- package/dist/client/data-assets-types.js.map +0 -1
- package/dist/client/data-assets.d.ts +0 -31
- package/dist/client/data-assets.d.ts.map +0 -1
- package/dist/client/data-assets.js +0 -182
- package/dist/client/data-assets.js.map +0 -1
- package/dist/client/delivery-types.d.ts +0 -97
- package/dist/client/delivery-types.d.ts.map +0 -1
- package/dist/client/delivery-types.js +0 -10
- package/dist/client/delivery-types.js.map +0 -1
- package/dist/client/delivery.d.ts +0 -23
- package/dist/client/delivery.d.ts.map +0 -1
- package/dist/client/delivery.js +0 -105
- package/dist/client/delivery.js.map +0 -1
- package/dist/client/flows.d.ts +0 -33
- package/dist/client/flows.d.ts.map +0 -1
- package/dist/client/flows.js +0 -218
- package/dist/client/flows.js.map +0 -1
package/docs/getting-started.md
CHANGED
|
@@ -1,24 +1,25 @@
|
|
|
1
1
|
# SDK Getting Started Guide
|
|
2
2
|
|
|
3
|
-
Get from zero to
|
|
4
|
-
|
|
5
|
-
|
|
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:**
|
|
8
|
-
>
|
|
9
|
-
>
|
|
10
|
-
>
|
|
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:
|
|
20
|
-
- [Step 4:
|
|
21
|
-
- [
|
|
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
|
|
34
|
-
| **Loxtep account** |
|
|
35
|
-
| **
|
|
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
|
-
|
|
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
|
-
|
|
49
|
-
|
|
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
|
|
50
|
+
Verify the CLI:
|
|
54
51
|
|
|
55
52
|
```bash
|
|
56
53
|
pnpm exec loxtep --version
|
|
@@ -60,269 +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
|
-
|
|
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
|
-
**
|
|
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:
|
|
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
|
-
```
|
|
95
|
-
|
|
80
|
+
```bash
|
|
81
|
+
pnpm exec loxtep init
|
|
82
|
+
```
|
|
96
83
|
|
|
97
|
-
|
|
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
|
-
|
|
103
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
115
|
-
|
|
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
|
-
|
|
101
|
+
---
|
|
119
102
|
|
|
120
|
-
|
|
103
|
+
## Step 4: Attach to an Instance
|
|
121
104
|
|
|
122
|
-
|
|
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
|
-
|
|
112
|
+
`attach` writes `instance_id` and `api_url` into `.loxtep/project.json`.
|
|
113
|
+
Required before `generate`, `test`, and `deploy`.
|
|
133
114
|
|
|
134
|
-
|
|
115
|
+
---
|
|
135
116
|
|
|
136
|
-
|
|
137
|
-
const reader = await client.get_reader('my-data-product');
|
|
117
|
+
## Step 5: Generate Typed Constants
|
|
138
118
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
}
|
|
119
|
+
```bash
|
|
120
|
+
pnpm exec loxtep generate
|
|
142
121
|
```
|
|
143
122
|
|
|
144
|
-
|
|
145
|
-
|
|
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
|
-
|
|
126
|
+
---
|
|
148
127
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
##
|
|
141
|
+
## Step 7: Use the SDK in Application Code
|
|
160
142
|
|
|
161
|
-
|
|
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
|
-
|
|
168
|
-
|
|
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
|
-
|
|
174
|
-
|
|
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
|
-
|
|
191
|
-
|
|
192
|
-
|
|
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
|
-
|
|
196
|
-
}
|
|
158
|
+
List or manage resources via namespaced APIs:
|
|
197
159
|
|
|
198
|
-
|
|
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
|
-
##
|
|
204
|
-
|
|
205
|
-
### Data product not found
|
|
167
|
+
## Step 8: Write and Read Events (after deploy)
|
|
206
168
|
|
|
207
|
-
|
|
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
|
-
|
|
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
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
227
|
-
|
|
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
|
-
|
|
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
|
-
|
|
204
|
+
### Writer / reader options
|
|
234
205
|
|
|
235
|
-
|
|
206
|
+
```typescript
|
|
207
|
+
await client.get_writer('orders', {
|
|
208
|
+
batch_size: 500,
|
|
209
|
+
max_retries: 5,
|
|
210
|
+
});
|
|
236
211
|
|
|
237
|
-
|
|
238
|
-
|
|
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
|
-
|
|
248
|
-
|
|
249
|
-
**Symptom:** `StreamingError: Failed to resolve stream config for instance
|
|
250
|
-
<instance-id>`
|
|
221
|
+
## Troubleshooting
|
|
251
222
|
|
|
252
|
-
|
|
253
|
-
retrieve the stream configuration from the instance record.
|
|
223
|
+
### Run `loxtep init` first / not attached
|
|
254
224
|
|
|
255
|
-
**
|
|
225
|
+
**Symptom:** `Run loxtep init first` or `Run loxtep attach`
|
|
256
226
|
|
|
257
|
-
|
|
258
|
-
|
|
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
|
-
###
|
|
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
|
-
**
|
|
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
|
-
|
|
277
|
-
instance:
|
|
239
|
+
---
|
|
278
240
|
|
|
279
|
-
|
|
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
|
-
|
|
243
|
+
**Symptom:** `StreamingError: … is not deployed`
|
|
288
244
|
|
|
289
|
-
|
|
290
|
-
|
|
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
|
|
296
|
-
|
|
297
|
-
**Symptom:** `AuthenticationError: No authentication token found`
|
|
250
|
+
### Missing auth token
|
|
298
251
|
|
|
299
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
270
|
+
---
|
|
271
|
+
|
|
272
|
+
## Next Steps
|
|
321
273
|
|
|
322
274
|
| Resource | Description |
|
|
323
275
|
|----------|-------------|
|
|
324
|
-
| [Code-first CLI guide](./code-first-cli.md) |
|
|
325
|
-
| [Quick Reference Card](./quick-reference.md) |
|
|
326
|
-
| [Event Replay Cookbook](./event-replay-cookbook.md) |
|
|
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 |
|
|
327
279
|
|
|
328
|
-
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.
|
package/docs/quick-reference.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# SDK Quick Reference Card
|
|
2
2
|
|
|
3
|
-
Concise cheat sheet for common Loxtep SDK operations (Node.js
|
|
3
|
+
Concise cheat sheet for common Loxtep SDK operations (Node.js).
|
|
4
4
|
For full walkthroughs, see the [Getting Started Guide](./getting-started.md)
|
|
5
|
-
|
|
5
|
+
or [Code-first CLI guide](./code-first-cli.md).
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -13,7 +13,11 @@ For full walkthroughs, see the [Getting Started Guide](./getting-started.md)
|
|
|
13
13
|
```typescript
|
|
14
14
|
import { LoxtepClient } from '@loxtep/sdk';
|
|
15
15
|
|
|
16
|
-
|
|
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('
|
|
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' } });
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@loxtep/sdk",
|
|
3
|
-
"version": "0.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"}
|