@loxtep/sdk 0.7.21 → 0.7.22
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 +12 -0
- package/README.md +12 -13
- package/dist/cli/commands/config-cmd.js +1 -1
- package/dist/cli/commands/ingest-cmd.d.ts.map +1 -1
- package/dist/cli/commands/ingest-cmd.js +1 -2
- package/dist/cli/commands/ingest-cmd.js.map +1 -1
- package/dist/cli/help.d.ts.map +1 -1
- package/dist/cli/help.js +0 -3
- package/dist/cli/help.js.map +1 -1
- package/docs/getting-started.md +4 -16
- package/docs/quick-reference.md +8 -9
- package/docs/sdk-first-ingest.md +53 -232
- package/package.json +1 -1
- package/docs/examples/generate-ingest-bundle.mjs +0 -133
- package/docs/examples/write-events.mjs +0 -54
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
6
6
|
and this project adheres to
|
|
7
7
|
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
8
8
|
|
|
9
|
+
## [0.7.22] - 2026-07-24
|
|
10
|
+
|
|
11
|
+
### Changed
|
|
12
|
+
|
|
13
|
+
- **`sdk-first-ingest.md`** — rewritten for the developer mental model (workspace
|
|
14
|
+
→ attach → create data product → `get_writer`); removed internal platform jargon.
|
|
15
|
+
- **Docs / READMEs** — removed `node_modules/@loxtep/sdk/docs/examples/*.mjs` run
|
|
16
|
+
instructions and deleted the example scripts; write path is inline `get_writer` +
|
|
17
|
+
`write()` in application code only.
|
|
18
|
+
- **CLI help** — `loxtep --help`, `ingest provision`, and `config init` no longer
|
|
19
|
+
point readers at `node_modules/.../docs` or example scripts.
|
|
20
|
+
|
|
9
21
|
## [0.7.21] - 2026-07-23
|
|
10
22
|
|
|
11
23
|
### Fixed
|
package/README.md
CHANGED
|
@@ -101,18 +101,16 @@ Run these in an **empty directory** you want to turn into a Loxtep workspace.
|
|
|
101
101
|
Not in a scaffolded folder? Run `pnpm exec loxtep projects list` first, then
|
|
102
102
|
`workflows list --project-id <uuid>`.
|
|
103
103
|
|
|
104
|
-
6. **
|
|
105
|
-
|
|
106
|
-
See **[SDK-first ingest](./docs/sdk-first-ingest.md)** — generate bundle,
|
|
107
|
-
save via MCP, deploy, then write:
|
|
104
|
+
6. **Create a data product and write from your app**
|
|
108
105
|
|
|
109
106
|
```bash
|
|
110
|
-
pnpm exec loxtep
|
|
111
|
-
|
|
112
|
-
# … save_workflow_bundle (MCP) + workflows deploy …
|
|
113
|
-
node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
107
|
+
pnpm exec loxtep ingest provision --name app-events
|
|
108
|
+
pnpm exec loxtep data-products list
|
|
114
109
|
```
|
|
115
110
|
|
|
111
|
+
Then use `get_writer` in your application — see
|
|
112
|
+
**[Write to a data product](./docs/sdk-first-ingest.md)**.
|
|
113
|
+
|
|
116
114
|
7. **Author code-first workflow modules** (optional, different path)
|
|
117
115
|
|
|
118
116
|
```bash
|
|
@@ -135,17 +133,15 @@ const { user, organization } = await client.session.get_current_user();
|
|
|
135
133
|
console.log(user.email, organization?.name);
|
|
136
134
|
```
|
|
137
135
|
|
|
138
|
-
### Write and read events
|
|
136
|
+
### Write and read events
|
|
139
137
|
|
|
140
|
-
|
|
141
|
-
**deployment metadata**. Complete [SDK-first ingest](./docs/sdk-first-ingest.md)
|
|
142
|
-
before streaming:
|
|
138
|
+
After you create a data product on your attached instance:
|
|
143
139
|
|
|
144
140
|
```ts
|
|
145
141
|
const client = await LoxtepClient.fromWorkspace();
|
|
146
142
|
|
|
147
143
|
const writer = await client.get_writer('app-events');
|
|
148
|
-
writer.write({
|
|
144
|
+
writer.write({ hello: 'world' });
|
|
149
145
|
await writer.close();
|
|
150
146
|
|
|
151
147
|
const reader = await client.get_reader('app-events');
|
|
@@ -155,6 +151,8 @@ for await (const event of reader) {
|
|
|
155
151
|
}
|
|
156
152
|
```
|
|
157
153
|
|
|
154
|
+
See [Write to a data product](./docs/sdk-first-ingest.md).
|
|
155
|
+
|
|
158
156
|
---
|
|
159
157
|
|
|
160
158
|
## Quick start — Code-first workflow module
|
|
@@ -337,6 +335,7 @@ await client.build.targets.delete('dp_abc123', webhook.consumption_id);
|
|
|
337
335
|
| `init --create-repo [name]` | Scaffold + create a new GitHub repo (private default) |
|
|
338
336
|
| `init --from-repo <url>` | Scaffold + import from an existing repo |
|
|
339
337
|
| `attach --instance <name-or-id>` | Bind project to a runtime instance |
|
|
338
|
+
| `ingest provision [--name]` | Create a data product on your instance (ready for `get_writer`) |
|
|
340
339
|
| `generate` | Codegen typed workspace constants to `.loxtep/generated/index.ts` |
|
|
341
340
|
| `test <module> --event <file>` | Run a workflow module locally with sample event(s) |
|
|
342
341
|
| `deploy` | Compile modules, validate resources, deploy to workflow engine |
|
|
@@ -346,7 +346,7 @@ export async function runInit() {
|
|
|
346
346
|
From a data product: loxtep config export --from-data-product <uuid>
|
|
347
347
|
|
|
348
348
|
Auth precedence: LOXTEP_AUTH_TOKEN env var → ./.loxtep/credentials.json (walk up from cwd) → ~/.loxtep/credentials.json.
|
|
349
|
-
Docs:
|
|
349
|
+
Docs: github.com/LoxtepInc/loxtep-sdk/tree/main/nodejs/docs (sdk-pairing.md, getting-started.md, sdk-first-ingest.md).
|
|
350
350
|
`);
|
|
351
351
|
}
|
|
352
352
|
//# sourceMappingURL=config-cmd.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ingest-cmd.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ingest-cmd.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IACN,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,EACD,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,
|
|
1
|
+
{"version":3,"file":"ingest-cmd.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ingest-cmd.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE;IACN,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,EACD,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA+Gf"}
|
|
@@ -87,8 +87,7 @@ export async function runIngestProvision(params, options = {}) {
|
|
|
87
87
|
}, null, 2));
|
|
88
88
|
if (!params.no_deploy && instanceId) {
|
|
89
89
|
console.error(`
|
|
90
|
-
|
|
91
|
-
LOXTEP_DATA_PRODUCT_NAME=${dataProductName} node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
90
|
+
Provisioned "${dataProductName}". Use get_writer('${dataProductName}') in your app (see docs/sdk-first-ingest.md).
|
|
92
91
|
`);
|
|
93
92
|
}
|
|
94
93
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ingest-cmd.js","sourceRoot":"","sources":["../../../src/cli/commands/ingest-cmd.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"ingest-cmd.js","sourceRoot":"","sources":["../../../src/cli/commands/ingest-cmd.ts"],"names":[],"mappings":"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"}
|
package/dist/cli/help.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,QAAQ,
|
|
1
|
+
{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,QAAQ,QAkFV,CAAC;AAEZ,wBAAgB,YAAY,IAAI,IAAI,CAEnC"}
|
package/dist/cli/help.js
CHANGED
|
@@ -70,9 +70,6 @@ Examples:
|
|
|
70
70
|
pnpm exec loxtep login
|
|
71
71
|
pnpm exec loxtep init && pnpm exec loxtep attach --instance <id>
|
|
72
72
|
pnpm exec loxtep ingest provision --name app-events
|
|
73
|
-
pnpm exec loxtep bundle save --dry-run
|
|
74
|
-
pnpm exec loxtep workflows deploy --project-id <id> --instance-id <id>
|
|
75
|
-
node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
76
73
|
pnpm exec loxtep init --template shopify-orders
|
|
77
74
|
pnpm exec loxtep attach --instance prod && pnpm exec loxtep generate
|
|
78
75
|
pnpm exec loxtep projects list
|
package/dist/cli/help.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG
|
|
1
|
+
{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkFvB,CAAC,OAAO,EAAE,CAAC;AAEZ,MAAM,UAAU,YAAY;IAC1B,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACxB,CAAC"}
|
package/docs/getting-started.md
CHANGED
|
@@ -163,29 +163,17 @@ products, connectors, domains, queues, workflows). Re-run after platform changes
|
|
|
163
163
|
|
|
164
164
|
---
|
|
165
165
|
|
|
166
|
-
## Step 6:
|
|
166
|
+
## Step 6: Create a data product and write from your app
|
|
167
167
|
|
|
168
|
-
After `attach`,
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
`get_writer` needs **deployment metadata** (queues and bots created at deploy
|
|
172
|
-
time). Creating a catalog row alone is not enough.
|
|
173
|
-
|
|
174
|
-
**Recommended:** follow **[SDK-first ingest](./sdk-first-ingest.md)** end to end.
|
|
175
|
-
Short version:
|
|
168
|
+
After `attach`, create a data product on that instance, then call `get_writer`
|
|
169
|
+
from your application:
|
|
176
170
|
|
|
177
171
|
```bash
|
|
178
|
-
pnpm exec loxtep domains list
|
|
179
|
-
|
|
180
|
-
# One command: SDK connector + workflow bundle + deploy (no MCP)
|
|
181
172
|
pnpm exec loxtep ingest provision --name app-events
|
|
182
|
-
|
|
183
173
|
pnpm exec loxtep data-products list
|
|
184
|
-
node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
185
174
|
```
|
|
186
175
|
|
|
187
|
-
|
|
188
|
-
streaming — it registers catalog metadata without runtime bindings.
|
|
176
|
+
See **[Write to a data product](./sdk-first-ingest.md)** for the full flow and code sample.
|
|
189
177
|
|
|
190
178
|
---
|
|
191
179
|
|
package/docs/quick-reference.md
CHANGED
|
@@ -54,8 +54,8 @@ bus config from deployment metadata.
|
|
|
54
54
|
```typescript
|
|
55
55
|
const writer = await client.get_writer('orders'); // deployed data product name
|
|
56
56
|
|
|
57
|
-
writer.write({
|
|
58
|
-
writer.write({
|
|
57
|
+
writer.write({ order_id: 'ord-1', status: 'placed' });
|
|
58
|
+
writer.write({ order_id: 'ord-2', status: 'shipped' });
|
|
59
59
|
|
|
60
60
|
await writer.close(); // flushes all buffered events
|
|
61
61
|
```
|
|
@@ -65,8 +65,8 @@ await writer.close(); // flushes all buffered events
|
|
|
65
65
|
```python
|
|
66
66
|
writer = await client.get_writer("my-data-product")
|
|
67
67
|
|
|
68
|
-
writer.write({"
|
|
69
|
-
writer.write({"
|
|
68
|
+
writer.write({"order_id": "ord-1", "status": "placed"})
|
|
69
|
+
writer.write({"order_id": "ord-2", "status": "shipped"})
|
|
70
70
|
|
|
71
71
|
await writer.close() # flushes all buffered events
|
|
72
72
|
```
|
|
@@ -189,15 +189,14 @@ pnpm exec loxtep attach --instance <instance-id>
|
|
|
189
189
|
pnpm exec loxtep generate
|
|
190
190
|
```
|
|
191
191
|
|
|
192
|
-
**
|
|
192
|
+
**Create a data product and write from your app** (after attach):
|
|
193
193
|
|
|
194
194
|
```bash
|
|
195
|
-
pnpm exec loxtep
|
|
196
|
-
node node_modules/@loxtep/sdk/docs/examples/generate-ingest-bundle.mjs
|
|
197
|
-
pnpm exec loxtep workflows deploy --project-id <id> --instance-id <id>
|
|
198
|
-
node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
195
|
+
pnpm exec loxtep ingest provision --name app-events
|
|
199
196
|
```
|
|
200
197
|
|
|
198
|
+
See [Write to a data product](./sdk-first-ingest.md).
|
|
199
|
+
|
|
201
200
|
Code-first workflow modules:
|
|
202
201
|
|
|
203
202
|
```bash
|
package/docs/sdk-first-ingest.md
CHANGED
|
@@ -1,263 +1,80 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Write to a data product from your app
|
|
2
2
|
|
|
3
|
-
You
|
|
4
|
-
**
|
|
3
|
+
You installed the SDK, initialized a workspace, and attached an instance. Next:
|
|
4
|
+
**create a data product**, open a writer, and send events from your code.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
first — you want your app (or ETL job) to push events into a **source** data
|
|
8
|
-
product on your attached instance.
|
|
9
|
-
|
|
10
|
-
> **Full CLI workspace setup:** [Getting Started](./getting-started.md) steps 1–4.
|
|
11
|
-
> **Code-first workflow modules:** [Code-first CLI](./code-first-cli.md).
|
|
6
|
+
> Already set up login, init, and attach? [Getting started](./getting-started.md).
|
|
12
7
|
|
|
13
8
|
---
|
|
14
9
|
|
|
15
|
-
##
|
|
16
|
-
|
|
17
|
-
```text
|
|
18
|
-
Your app ──get_writer──▶ rstreams queue ──▶ source data product (catalog)
|
|
19
|
-
▲ ▲
|
|
20
|
-
│ │
|
|
21
|
-
@loxtep/sdk provisioned at deploy time
|
|
22
|
-
fromWorkspace()
|
|
23
|
-
```
|
|
10
|
+
## Phase 1 — Workspace ready
|
|
24
11
|
|
|
25
|
-
|
|
26
|
-
**deployment metadata** (`deployment_bindings` on the data product). A catalog
|
|
27
|
-
row alone is not enough — the ingestion workflow must be **saved and deployed**
|
|
28
|
-
on your attached instance first.
|
|
29
|
-
|
|
30
|
-
---
|
|
31
|
-
|
|
32
|
-
## Prerequisites
|
|
33
|
-
|
|
34
|
-
Run from your scaffolded workspace (directory with `.loxtep/project.json`):
|
|
12
|
+
Run commands from your project directory (the folder with `.loxtep/project.json`).
|
|
35
13
|
|
|
36
14
|
```bash
|
|
37
|
-
pnpm exec loxtep
|
|
38
|
-
pnpm exec loxtep
|
|
15
|
+
pnpm exec loxtep login
|
|
16
|
+
pnpm exec loxtep init
|
|
17
|
+
pnpm exec loxtep attach --instance <instance-id>
|
|
18
|
+
pnpm exec loxtep config list
|
|
39
19
|
```
|
|
40
20
|
|
|
41
|
-
|
|
21
|
+
You should see `project_id` and `instance_id` from `attach`.
|
|
42
22
|
|
|
43
23
|
---
|
|
44
24
|
|
|
45
|
-
##
|
|
46
|
-
|
|
47
|
-
| Phase | What | How |
|
|
48
|
-
| ----- | ---- | --- |
|
|
49
|
-
| 1 | Workspace ready | `login` → `init` → `attach` (done) |
|
|
50
|
-
| 2 | Provision runtime | SDK connector + workflow bundle + deploy |
|
|
51
|
-
| 3 | Verify | `data-products list` / `data-products get` |
|
|
52
|
-
| 4 | Write events | `LoxtepClient.fromWorkspace()` + `get_writer` |
|
|
53
|
-
|
|
54
|
-
Phases 2–4 below.
|
|
55
|
-
|
|
56
|
-
---
|
|
25
|
+
## Phase 2 — Create your data product
|
|
57
26
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
Runtime provisioning creates the workflow graph (SDK connection node → source
|
|
61
|
-
data product node), saves it to your project workspace, and **deploys** it to your
|
|
62
|
-
instance so queues and bots exist.
|
|
63
|
-
|
|
64
|
-
### Option A — CLI one-shot (recommended, no MCP)
|
|
65
|
-
|
|
66
|
-
From your workspace root (after `login`, `init`, `attach`):
|
|
27
|
+
Pick a name your app will use (example: `app-events`):
|
|
67
28
|
|
|
68
29
|
```bash
|
|
69
30
|
pnpm exec loxtep ingest provision --name app-events
|
|
70
31
|
```
|
|
71
32
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
1. Creates an org-level **SDK connector** (`connector_type: "sdk"`).
|
|
75
|
-
2. Builds and saves the workflow bundle (`workflow.json` + connection + source data product).
|
|
76
|
-
3. **Deploys** to your attached instance (unless you pass `--no-deploy` or `--dry-run`).
|
|
77
|
-
|
|
78
|
-
Validate first without writing:
|
|
79
|
-
|
|
80
|
-
```bash
|
|
81
|
-
pnpm exec loxtep ingest provision --name app-events --dry-run
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
### Option B — Helper script + bundle save
|
|
85
|
-
|
|
86
|
-
Generate bundle JSON only:
|
|
87
|
-
|
|
88
|
-
```bash
|
|
89
|
-
node node_modules/@loxtep/sdk/docs/examples/generate-ingest-bundle.mjs
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Then persist and deploy via CLI:
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
pnpm exec loxtep bundle save --dry-run --file .loxtep/sdk-ingest-bundle.json
|
|
96
|
-
pnpm exec loxtep bundle save --file .loxtep/sdk-ingest-bundle.json
|
|
97
|
-
pnpm exec loxtep workflows deploy \
|
|
98
|
-
--project-id <project-id-from-config-list> \
|
|
99
|
-
--instance-id <instance-id-from-config-list>
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
Or set `LOXTEP_AUTO_SAVE=1` on the helper script to save + deploy in one step.
|
|
103
|
-
|
|
104
|
-
Poll until deployment completes (Web UI **Observe**, or `loxtep observe status`).
|
|
105
|
-
|
|
106
|
-
### Option C — Loxtep MCP (Cursor / agent)
|
|
107
|
-
|
|
108
|
-
Use **`loxtep_build`** → `save_workflow_bundle` if you prefer MCP authoring.
|
|
109
|
-
Same bundle shape as below; deploy with `loxtep workflows deploy` or MCP
|
|
110
|
-
`deploy_project`.
|
|
111
|
-
|
|
112
|
-
### Option D — Web UI (Studio)
|
|
113
|
-
|
|
114
|
-
Create an **ingestion** workflow with an **SDK** connection node and a **source**
|
|
115
|
-
data product node, then deploy to your attached instance from the Studio deploy
|
|
116
|
-
flow.
|
|
117
|
-
|
|
118
|
-
---
|
|
119
|
-
|
|
120
|
-
### Workflow bundle shape
|
|
121
|
-
|
|
122
|
-
Minimal ingestion bundle (SDK connection → source data product). Replace UUIDs
|
|
123
|
-
and names; `connector_id` must be the SDK connector from step 2A or 2B.
|
|
124
|
-
|
|
125
|
-
```json
|
|
126
|
-
{
|
|
127
|
-
"workflow.json": {
|
|
128
|
-
"workflow_id": "<workflow-uuid>",
|
|
129
|
-
"organization_id": "<org-uuid>",
|
|
130
|
-
"project_id": "<project-uuid>",
|
|
131
|
-
"name": "SDK App Events Ingest",
|
|
132
|
-
"workflow_type": "ingestion",
|
|
133
|
-
"domain_id": "<domain-uuid>",
|
|
134
|
-
"status": "active",
|
|
135
|
-
"configuration": {},
|
|
136
|
-
"metadata": {},
|
|
137
|
-
"created_at": "2026-07-23T00:00:00.000Z",
|
|
138
|
-
"updated_at": "2026-07-23T00:00:00.000Z"
|
|
139
|
-
},
|
|
140
|
-
"connections/<connection-uuid>.json": {
|
|
141
|
-
"connection_id": "<connection-uuid>",
|
|
142
|
-
"organization_id": "<org-uuid>",
|
|
143
|
-
"project_id": "<project-uuid>",
|
|
144
|
-
"workflow_id": "<workflow-uuid>",
|
|
145
|
-
"connector_id": "<sdk-connector-uuid>",
|
|
146
|
-
"key": "sdk-input",
|
|
147
|
-
"name": "SDK Input",
|
|
148
|
-
"type": "sdk",
|
|
149
|
-
"status": "active",
|
|
150
|
-
"configuration": {
|
|
151
|
-
"sdk_type": "nodejs",
|
|
152
|
-
"event_type": "app-events"
|
|
153
|
-
},
|
|
154
|
-
"created_at": "2026-07-23T00:00:00.000Z",
|
|
155
|
-
"updated_at": "2026-07-23T00:00:00.000Z"
|
|
156
|
-
},
|
|
157
|
-
"data-products/<data-product-uuid>.json": {
|
|
158
|
-
"data_product_id": "<data-product-uuid>",
|
|
159
|
-
"organization_id": "<org-uuid>",
|
|
160
|
-
"project_id": "<project-uuid>",
|
|
161
|
-
"workflow_id": "<workflow-uuid>",
|
|
162
|
-
"upstream_entity_id": "<connection-uuid>",
|
|
163
|
-
"upstream_entity_type": "connections",
|
|
164
|
-
"domain_id": "<domain-uuid>",
|
|
165
|
-
"name": "app-events",
|
|
166
|
-
"kind": "source",
|
|
167
|
-
"status": "draft",
|
|
168
|
-
"owner": {},
|
|
169
|
-
"governance": {
|
|
170
|
-
"classification": "internal",
|
|
171
|
-
"pii_fields": [],
|
|
172
|
-
"compliance_requirements": [],
|
|
173
|
-
"tags": []
|
|
174
|
-
},
|
|
175
|
-
"metadata": {},
|
|
176
|
-
"created_at": "2026-07-23T00:00:00.000Z",
|
|
177
|
-
"updated_at": "2026-07-23T00:00:00.000Z"
|
|
178
|
-
}
|
|
179
|
-
}
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
The **`name`** on the data product node (`app-events` above) is what you pass
|
|
183
|
-
to `get_writer('app-events')`.
|
|
184
|
-
|
|
185
|
-
---
|
|
186
|
-
|
|
187
|
-
### Do not stop at `data-products create`
|
|
188
|
-
|
|
189
|
-
```bash
|
|
190
|
-
# Creates a catalog row only — get_writer will fail with "not deployed"
|
|
191
|
-
pnpm exec loxtep data-products create --name app-events --domain-id <uuid> --kind source
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
Use **`data-products create`** only when you already have (or will immediately
|
|
195
|
-
add) a deployed workflow that sets `deployment_bindings`. For greenfield SDK
|
|
196
|
-
ingest, prefer the bundle + deploy path above.
|
|
33
|
+
That is all you need for SDK writes — one command, one name.
|
|
197
34
|
|
|
198
35
|
---
|
|
199
36
|
|
|
200
|
-
## Phase 3 —
|
|
37
|
+
## Phase 3 — Confirm it exists
|
|
201
38
|
|
|
202
39
|
```bash
|
|
203
40
|
pnpm exec loxtep data-products list
|
|
204
|
-
pnpm exec loxtep data-products get <data-product-id>
|
|
205
41
|
```
|
|
206
42
|
|
|
207
|
-
|
|
208
|
-
`queue_name`, `bot_id`, and `instance_id`. If those are missing, finish Phase 2
|
|
209
|
-
before writing.
|
|
210
|
-
|
|
211
|
-
Re-run code generation after platform changes:
|
|
212
|
-
|
|
213
|
-
```bash
|
|
214
|
-
pnpm exec loxtep generate
|
|
215
|
-
```
|
|
43
|
+
You should see `app-events` (or whatever name you chose).
|
|
216
44
|
|
|
217
45
|
---
|
|
218
46
|
|
|
219
|
-
## Phase 4 — Write
|
|
220
|
-
|
|
221
|
-
Copy or run the example:
|
|
222
|
-
|
|
223
|
-
```bash
|
|
224
|
-
node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
225
|
-
```
|
|
47
|
+
## Phase 4 — Write from your application
|
|
226
48
|
|
|
227
|
-
|
|
49
|
+
The SDK reads your workspace (`.loxtep/project.json` + credentials). No manual
|
|
50
|
+
URL or token wiring.
|
|
228
51
|
|
|
229
52
|
```typescript
|
|
230
53
|
import { LoxtepClient } from '@loxtep/sdk';
|
|
231
54
|
|
|
232
55
|
const client = await LoxtepClient.fromWorkspace();
|
|
233
56
|
|
|
234
|
-
// Name from Phase 2 bundle / data-products list (case-sensitive)
|
|
235
57
|
const writer = await client.get_writer('app-events');
|
|
236
58
|
|
|
237
59
|
writer.write({
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
payload: { user_id: 'u_1', action: 'signup' },
|
|
60
|
+
user_id: 'u_1',
|
|
61
|
+
action: 'signup',
|
|
241
62
|
});
|
|
242
63
|
|
|
243
|
-
await writer.close();
|
|
64
|
+
await writer.close();
|
|
244
65
|
```
|
|
245
66
|
|
|
246
|
-
|
|
67
|
+
Pass your **business fields** to `write()`. The SDK wraps them for transport —
|
|
68
|
+
you do not build an envelope or use a `payload` property yourself.
|
|
247
69
|
|
|
248
|
-
|
|
249
|
-
await client.get_writer('app-events', {
|
|
250
|
-
batch_size: 500,
|
|
251
|
-
max_retries: 5,
|
|
252
|
-
});
|
|
253
|
-
```
|
|
70
|
+
Use the same name you passed to `ingest provision`.
|
|
254
71
|
|
|
255
|
-
Read back (
|
|
72
|
+
### Read back (optional)
|
|
256
73
|
|
|
257
74
|
```typescript
|
|
258
|
-
const
|
|
259
|
-
|
|
260
|
-
|
|
75
|
+
const client = await LoxtepClient.fromWorkspace();
|
|
76
|
+
const reader = await client.get_reader('app-events');
|
|
77
|
+
|
|
261
78
|
for await (const event of reader) {
|
|
262
79
|
console.log(event);
|
|
263
80
|
break;
|
|
@@ -266,39 +83,43 @@ for await (const event of reader) {
|
|
|
266
83
|
|
|
267
84
|
---
|
|
268
85
|
|
|
269
|
-
##
|
|
86
|
+
## Quick checklist
|
|
270
87
|
|
|
271
88
|
```bash
|
|
272
89
|
pnpm exec loxtep login
|
|
273
90
|
pnpm exec loxtep init
|
|
274
91
|
pnpm exec loxtep attach --instance <instance-id>
|
|
275
|
-
pnpm exec loxtep domains list
|
|
276
|
-
|
|
277
92
|
pnpm exec loxtep ingest provision --name app-events
|
|
278
|
-
# or: generate-ingest-bundle.mjs + loxtep bundle save
|
|
279
|
-
|
|
280
93
|
pnpm exec loxtep data-products list
|
|
281
|
-
node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
282
94
|
```
|
|
283
95
|
|
|
96
|
+
Then `get_writer('app-events')` in your app.
|
|
97
|
+
|
|
284
98
|
---
|
|
285
99
|
|
|
286
|
-
##
|
|
100
|
+
## If something goes wrong
|
|
287
101
|
|
|
288
|
-
|
|
|
289
|
-
|
|
|
290
|
-
|
|
|
291
|
-
|
|
|
292
|
-
|
|
|
293
|
-
|
|
|
102
|
+
| What you see | What to do |
|
|
103
|
+
| ------------ | ---------- |
|
|
104
|
+
| Data product not found | Run `data-products list`. Check the name matches `get_writer('…')` exactly. |
|
|
105
|
+
| Not ready to accept writes | Run `ingest provision` again for that name. Make sure you ran `attach` first. |
|
|
106
|
+
| Multiple products with the same name | Pass the data product id to `get_writer`, or ensure `attach` points at the right instance. |
|
|
107
|
+
| No domain available | Create a domain in the Loxtep UI, or pass `--domain-id` to `ingest provision`. |
|
|
294
108
|
|
|
295
109
|
---
|
|
296
110
|
|
|
297
|
-
##
|
|
111
|
+
## Other ways to create a data product
|
|
112
|
+
|
|
113
|
+
**Loxtep MCP (AI assistant)** — If you use the Loxtep MCP in Cursor, Claude Code,
|
|
114
|
+
or another client, describe what you want in plain language, for example:
|
|
115
|
+
|
|
116
|
+
> Create a data product named `app-events` on my current Loxtep project and
|
|
117
|
+
> deploy it to the instance I already attached. I want to write events from my
|
|
118
|
+
> app with the SDK.
|
|
119
|
+
|
|
120
|
+
The assistant provisions the same end state as `ingest provision`. After that,
|
|
121
|
+
Phase 4 above is unchanged: `get_writer('app-events')` and `write()`.
|
|
298
122
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
| [Quick Reference](./quick-reference.md) | CLI + SDK cheat sheet |
|
|
303
|
-
| [Code-first CLI](./code-first-cli.md) | TypeScript workflow modules + `loxtep deploy` |
|
|
304
|
-
| [Event Replay Cookbook](./event-replay-cookbook.md) | Replay and reprocess |
|
|
123
|
+
**Loxtep Studio (web app)** — *Beta.* You can also design and publish a data
|
|
124
|
+
product in the Loxtep UI. Once it exists on your instance, the SDK code in
|
|
125
|
+
Phase 4 is the same.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@loxtep/sdk",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.22",
|
|
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,133 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* Greenfield SDK ingest — one-shot provision via CLI (preferred) or bundle JSON for manual save.
|
|
4
|
-
*
|
|
5
|
-
* Run from your Loxtep workspace root (after login, init, attach):
|
|
6
|
-
*
|
|
7
|
-
* pnpm exec loxtep ingest provision --name app-events
|
|
8
|
-
*
|
|
9
|
-
* Or generate bundle JSON only:
|
|
10
|
-
*
|
|
11
|
-
* node node_modules/@loxtep/sdk/docs/examples/generate-ingest-bundle.mjs
|
|
12
|
-
* pnpm exec loxtep bundle save --dry-run
|
|
13
|
-
* pnpm exec loxtep bundle save
|
|
14
|
-
*/
|
|
15
|
-
|
|
16
|
-
import { LoxtepClient, buildSdkIngestBundle } from '@loxtep/sdk';
|
|
17
|
-
import { randomUUID } from 'node:crypto';
|
|
18
|
-
import { writeFileSync, mkdirSync } from 'node:fs';
|
|
19
|
-
import { join } from 'node:path';
|
|
20
|
-
|
|
21
|
-
const DATA_PRODUCT_NAME = process.env.LOXTEP_DATA_PRODUCT_NAME ?? 'app-events';
|
|
22
|
-
const WORKFLOW_NAME = process.env.LOXTEP_WORKFLOW_NAME ?? 'SDK App Events Ingest';
|
|
23
|
-
const AUTO_SAVE = process.env.LOXTEP_AUTO_SAVE === '1';
|
|
24
|
-
|
|
25
|
-
async function main() {
|
|
26
|
-
const client = await LoxtepClient.fromWorkspace();
|
|
27
|
-
|
|
28
|
-
const user = await client.session.get_current_user();
|
|
29
|
-
const organizationId = user.organization_id ?? client.organization_id;
|
|
30
|
-
const projectId = client.project_id;
|
|
31
|
-
const instanceId = client.instance_id;
|
|
32
|
-
|
|
33
|
-
if (!organizationId || !projectId) {
|
|
34
|
-
console.error(
|
|
35
|
-
'Missing organization_id or project_id. Run from a workspace after `loxtep init`.'
|
|
36
|
-
);
|
|
37
|
-
process.exit(1);
|
|
38
|
-
}
|
|
39
|
-
if (!instanceId) {
|
|
40
|
-
console.error('Missing instance_id. Run `loxtep attach --instance <id>` first.');
|
|
41
|
-
process.exit(1);
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
let domainId = process.env.LOXTEP_DOMAIN_ID;
|
|
45
|
-
if (!domainId) {
|
|
46
|
-
const domains = await client.define.domains.list({ page_size: 20 });
|
|
47
|
-
const items = domains.items ?? [];
|
|
48
|
-
if (items.length === 0) {
|
|
49
|
-
console.error(
|
|
50
|
-
'No domains found. Create one in the Web UI (Governance → Domains) or set LOXTEP_DOMAIN_ID.'
|
|
51
|
-
);
|
|
52
|
-
process.exit(1);
|
|
53
|
-
}
|
|
54
|
-
domainId = items[0].domain_id;
|
|
55
|
-
console.error(`Using domain: ${items[0].name} (${domainId})`);
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
console.error('Creating SDK connector…');
|
|
59
|
-
const connector = await client.connect.connectors.create({
|
|
60
|
-
connector_type: 'sdk',
|
|
61
|
-
metadata: { name: 'SDK Connector', created_by: 'generate-ingest-bundle' },
|
|
62
|
-
});
|
|
63
|
-
|
|
64
|
-
const bundle = buildSdkIngestBundle({
|
|
65
|
-
organization_id: organizationId,
|
|
66
|
-
project_id: projectId,
|
|
67
|
-
domain_id: domainId,
|
|
68
|
-
connector_id: connector.connector_id,
|
|
69
|
-
data_product_name: DATA_PRODUCT_NAME,
|
|
70
|
-
workflow_name: WORKFLOW_NAME,
|
|
71
|
-
user_id: user.user_id,
|
|
72
|
-
workflow_id: randomUUID(),
|
|
73
|
-
connection_id: randomUUID(),
|
|
74
|
-
data_product_id: randomUUID(),
|
|
75
|
-
});
|
|
76
|
-
|
|
77
|
-
mkdirSync('.loxtep', { recursive: true });
|
|
78
|
-
const outPath = join('.loxtep', 'sdk-ingest-bundle.json');
|
|
79
|
-
writeFileSync(outPath, JSON.stringify({ project_id: projectId, files: bundle.files }, null, 2));
|
|
80
|
-
|
|
81
|
-
console.log(
|
|
82
|
-
JSON.stringify(
|
|
83
|
-
{
|
|
84
|
-
connector_id: connector.connector_id,
|
|
85
|
-
workflow_id: bundle.workflow_id,
|
|
86
|
-
data_product_id: bundle.data_product_id,
|
|
87
|
-
data_product_name: bundle.data_product_name,
|
|
88
|
-
bundle_path: outPath,
|
|
89
|
-
},
|
|
90
|
-
null,
|
|
91
|
-
2
|
|
92
|
-
)
|
|
93
|
-
);
|
|
94
|
-
|
|
95
|
-
if (AUTO_SAVE) {
|
|
96
|
-
console.error('Saving workflow bundle (LOXTEP_AUTO_SAVE=1)…');
|
|
97
|
-
const saveResult = await client.build.workflows.save_workflow_bundle(projectId, {
|
|
98
|
-
files: bundle.files,
|
|
99
|
-
dry_run: false,
|
|
100
|
-
});
|
|
101
|
-
console.error('Deploying…');
|
|
102
|
-
const deployResult = await client.build.workflows.deploy({
|
|
103
|
-
project_id: projectId,
|
|
104
|
-
instance_id: instanceId,
|
|
105
|
-
});
|
|
106
|
-
console.log(JSON.stringify({ save: saveResult, deploy: deployResult }, null, 2));
|
|
107
|
-
console.error(`
|
|
108
|
-
Provisioned. Write events:
|
|
109
|
-
LOXTEP_DATA_PRODUCT_NAME=${DATA_PRODUCT_NAME} node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
110
|
-
`);
|
|
111
|
-
return;
|
|
112
|
-
}
|
|
113
|
-
|
|
114
|
-
console.error(`
|
|
115
|
-
Next steps (no MCP required)
|
|
116
|
-
────────────────────────────
|
|
117
|
-
Preferred — one command:
|
|
118
|
-
pnpm exec loxtep ingest provision --name ${DATA_PRODUCT_NAME}
|
|
119
|
-
|
|
120
|
-
Or save the generated bundle:
|
|
121
|
-
pnpm exec loxtep bundle save --dry-run --file ${outPath}
|
|
122
|
-
pnpm exec loxtep bundle save --file ${outPath}
|
|
123
|
-
pnpm exec loxtep workflows deploy --project-id ${projectId} --instance-id ${instanceId}
|
|
124
|
-
|
|
125
|
-
Write events:
|
|
126
|
-
LOXTEP_DATA_PRODUCT_NAME=${DATA_PRODUCT_NAME} node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
127
|
-
`);
|
|
128
|
-
}
|
|
129
|
-
|
|
130
|
-
main().catch(err => {
|
|
131
|
-
console.error(err instanceof Error ? err.message : err);
|
|
132
|
-
process.exit(1);
|
|
133
|
-
});
|
|
@@ -1,54 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* Write sample events to a deployed source data product via get_writer.
|
|
4
|
-
*
|
|
5
|
-
* Prerequisites: login, init, attach, SDK ingest workflow deployed (see sdk-first-ingest.md).
|
|
6
|
-
*
|
|
7
|
-
* node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
|
|
8
|
-
*
|
|
9
|
-
* Env:
|
|
10
|
-
* LOXTEP_DATA_PRODUCT_NAME default: app-events
|
|
11
|
-
*/
|
|
12
|
-
|
|
13
|
-
import { LoxtepClient } from '@loxtep/sdk';
|
|
14
|
-
|
|
15
|
-
const DATA_PRODUCT_NAME = process.env.LOXTEP_DATA_PRODUCT_NAME ?? 'app-events';
|
|
16
|
-
|
|
17
|
-
async function main() {
|
|
18
|
-
const client = await LoxtepClient.fromWorkspace();
|
|
19
|
-
|
|
20
|
-
console.error(`Opening writer for data product "${DATA_PRODUCT_NAME}"…`);
|
|
21
|
-
const writer = await client.get_writer(DATA_PRODUCT_NAME);
|
|
22
|
-
|
|
23
|
-
const events = [
|
|
24
|
-
{
|
|
25
|
-
event_id: `evt_${Date.now()}_1`,
|
|
26
|
-
occurred_at: new Date().toISOString(),
|
|
27
|
-
payload: { source: 'write-events.mjs', action: 'example_write', index: 1 },
|
|
28
|
-
},
|
|
29
|
-
{
|
|
30
|
-
event_id: `evt_${Date.now()}_2`,
|
|
31
|
-
occurred_at: new Date().toISOString(),
|
|
32
|
-
payload: { source: 'write-events.mjs', action: 'example_write', index: 2 },
|
|
33
|
-
},
|
|
34
|
-
];
|
|
35
|
-
|
|
36
|
-
for (const event of events) {
|
|
37
|
-
writer.write(event);
|
|
38
|
-
console.log(JSON.stringify({ written: event.event_id }));
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
await writer.close();
|
|
42
|
-
console.error('Writer closed — events flushed.');
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
main().catch(err => {
|
|
46
|
-
const message = err instanceof Error ? err.message : String(err);
|
|
47
|
-
console.error(message);
|
|
48
|
-
if (/not deployed/i.test(message)) {
|
|
49
|
-
console.error(
|
|
50
|
-
'\nDeploy an SDK ingestion workflow first. See nodejs/docs/sdk-first-ingest.md'
|
|
51
|
-
);
|
|
52
|
-
}
|
|
53
|
-
process.exit(1);
|
|
54
|
-
});
|