@loxtep/sdk 0.2.3 → 0.4.0

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 (239) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +255 -4
  3. package/dist/authoring/agent.d.ts +164 -0
  4. package/dist/authoring/agent.d.ts.map +1 -0
  5. package/dist/authoring/agent.js +376 -0
  6. package/dist/authoring/agent.js.map +1 -0
  7. package/dist/authoring/compiler.d.ts +103 -0
  8. package/dist/authoring/compiler.d.ts.map +1 -0
  9. package/dist/authoring/compiler.js +305 -0
  10. package/dist/authoring/compiler.js.map +1 -0
  11. package/dist/authoring/define-data-workflow.d.ts +24 -0
  12. package/dist/authoring/define-data-workflow.d.ts.map +1 -0
  13. package/dist/authoring/define-data-workflow.js +93 -0
  14. package/dist/authoring/define-data-workflow.js.map +1 -0
  15. package/dist/authoring/index.d.ts +19 -0
  16. package/dist/authoring/index.d.ts.map +1 -0
  17. package/dist/authoring/index.js +15 -0
  18. package/dist/authoring/index.js.map +1 -0
  19. package/dist/authoring/toolbox.d.ts +133 -0
  20. package/dist/authoring/toolbox.d.ts.map +1 -0
  21. package/dist/authoring/toolbox.js +166 -0
  22. package/dist/authoring/toolbox.js.map +1 -0
  23. package/dist/authoring/triggers.d.ts +41 -0
  24. package/dist/authoring/triggers.d.ts.map +1 -0
  25. package/dist/authoring/triggers.js +60 -0
  26. package/dist/authoring/triggers.js.map +1 -0
  27. package/dist/authoring/types.d.ts +111 -0
  28. package/dist/authoring/types.d.ts.map +1 -0
  29. package/dist/authoring/types.js +9 -0
  30. package/dist/authoring/types.js.map +1 -0
  31. package/dist/cli/commands/activity-cmd.d.ts +28 -0
  32. package/dist/cli/commands/activity-cmd.d.ts.map +1 -0
  33. package/dist/cli/commands/activity-cmd.js +78 -0
  34. package/dist/cli/commands/activity-cmd.js.map +1 -0
  35. package/dist/cli/commands/attach-cmd.d.ts +38 -0
  36. package/dist/cli/commands/attach-cmd.d.ts.map +1 -0
  37. package/dist/cli/commands/attach-cmd.js +141 -0
  38. package/dist/cli/commands/attach-cmd.js.map +1 -0
  39. package/dist/cli/commands/data-contracts-cmd.d.ts +8 -0
  40. package/dist/cli/commands/data-contracts-cmd.d.ts.map +1 -1
  41. package/dist/cli/commands/data-contracts-cmd.js +11 -0
  42. package/dist/cli/commands/data-contracts-cmd.js.map +1 -1
  43. package/dist/cli/commands/data-products-cmd.d.ts +2 -0
  44. package/dist/cli/commands/data-products-cmd.d.ts.map +1 -1
  45. package/dist/cli/commands/data-products-cmd.js +35 -0
  46. package/dist/cli/commands/data-products-cmd.js.map +1 -1
  47. package/dist/cli/commands/deploy-cmd.d.ts +101 -0
  48. package/dist/cli/commands/deploy-cmd.d.ts.map +1 -0
  49. package/dist/cli/commands/deploy-cmd.js +461 -0
  50. package/dist/cli/commands/deploy-cmd.js.map +1 -0
  51. package/dist/cli/commands/generate-cmd.d.ts +35 -0
  52. package/dist/cli/commands/generate-cmd.d.ts.map +1 -0
  53. package/dist/cli/commands/generate-cmd.js +134 -0
  54. package/dist/cli/commands/generate-cmd.js.map +1 -0
  55. package/dist/cli/commands/improvements-cmd.d.ts +44 -0
  56. package/dist/cli/commands/improvements-cmd.d.ts.map +1 -0
  57. package/dist/cli/commands/improvements-cmd.js +215 -0
  58. package/dist/cli/commands/improvements-cmd.js.map +1 -0
  59. package/dist/cli/commands/init-cmd.d.ts +78 -0
  60. package/dist/cli/commands/init-cmd.d.ts.map +1 -0
  61. package/dist/cli/commands/init-cmd.js +250 -0
  62. package/dist/cli/commands/init-cmd.js.map +1 -0
  63. package/dist/cli/commands/instances-cmd.d.ts +37 -0
  64. package/dist/cli/commands/instances-cmd.d.ts.map +1 -0
  65. package/dist/cli/commands/instances-cmd.js +150 -0
  66. package/dist/cli/commands/instances-cmd.js.map +1 -0
  67. package/dist/cli/commands/test-cmd.d.ts +89 -0
  68. package/dist/cli/commands/test-cmd.d.ts.map +1 -0
  69. package/dist/cli/commands/test-cmd.js +378 -0
  70. package/dist/cli/commands/test-cmd.js.map +1 -0
  71. package/dist/cli/index.d.ts +5 -2
  72. package/dist/cli/index.d.ts.map +1 -1
  73. package/dist/cli/index.js +240 -8
  74. package/dist/cli/index.js.map +1 -1
  75. package/dist/cli/project-context.d.ts +153 -0
  76. package/dist/cli/project-context.d.ts.map +1 -0
  77. package/dist/cli/project-context.js +190 -0
  78. package/dist/cli/project-context.js.map +1 -0
  79. package/dist/client/activity-types.d.ts +66 -0
  80. package/dist/client/activity-types.d.ts.map +1 -0
  81. package/dist/client/activity-types.js +9 -0
  82. package/dist/client/activity-types.js.map +1 -0
  83. package/dist/client/activity.d.ts +22 -0
  84. package/dist/client/activity.d.ts.map +1 -0
  85. package/dist/client/activity.js +43 -0
  86. package/dist/client/activity.js.map +1 -0
  87. package/dist/client/data-products-types.d.ts +23 -0
  88. package/dist/client/data-products-types.d.ts.map +1 -1
  89. package/dist/client/data-products.d.ts +3 -1
  90. package/dist/client/data-products.d.ts.map +1 -1
  91. package/dist/client/data-products.js +20 -98
  92. package/dist/client/data-products.js.map +1 -1
  93. package/dist/client/{consumptions-types.d.ts → delivery-types.d.ts} +25 -8
  94. package/dist/client/delivery-types.d.ts.map +1 -0
  95. package/dist/client/delivery-types.js +10 -0
  96. package/dist/client/delivery-types.js.map +1 -0
  97. package/dist/client/delivery.d.ts +23 -0
  98. package/dist/client/delivery.d.ts.map +1 -0
  99. package/dist/client/delivery.js +105 -0
  100. package/dist/client/delivery.js.map +1 -0
  101. package/dist/client/flow-types.d.ts +4 -2
  102. package/dist/client/flow-types.d.ts.map +1 -1
  103. package/dist/client/flows.d.ts +1 -1
  104. package/dist/client/flows.d.ts.map +1 -1
  105. package/dist/client/flows.js +49 -124
  106. package/dist/client/flows.js.map +1 -1
  107. package/dist/client/improvements-types.d.ts +55 -0
  108. package/dist/client/improvements-types.d.ts.map +1 -0
  109. package/dist/client/improvements-types.js +9 -0
  110. package/dist/client/improvements-types.js.map +1 -0
  111. package/dist/client/improvements.d.ts +29 -0
  112. package/dist/client/improvements.d.ts.map +1 -0
  113. package/dist/client/improvements.js +50 -0
  114. package/dist/client/improvements.js.map +1 -0
  115. package/dist/client/index.d.ts +8 -3
  116. package/dist/client/index.d.ts.map +1 -1
  117. package/dist/client/index.js.map +1 -1
  118. package/dist/client/instances-types.d.ts +92 -0
  119. package/dist/client/instances-types.d.ts.map +1 -1
  120. package/dist/client/instances.d.ts +26 -4
  121. package/dist/client/instances.d.ts.map +1 -1
  122. package/dist/client/instances.js +94 -3
  123. package/dist/client/instances.js.map +1 -1
  124. package/dist/client/loxtep-client.d.ts +48 -3
  125. package/dist/client/loxtep-client.d.ts.map +1 -1
  126. package/dist/client/loxtep-client.js +73 -5
  127. package/dist/client/loxtep-client.js.map +1 -1
  128. package/dist/client/projects-types.d.ts +25 -0
  129. package/dist/client/projects-types.d.ts.map +1 -1
  130. package/dist/client/projects.d.ts +2 -1
  131. package/dist/client/projects.d.ts.map +1 -1
  132. package/dist/client/projects.js +17 -0
  133. package/dist/client/projects.js.map +1 -1
  134. package/dist/client/promises.d.ts +11 -0
  135. package/dist/client/promises.d.ts.map +1 -1
  136. package/dist/client/promises.js +11 -0
  137. package/dist/client/promises.js.map +1 -1
  138. package/dist/client/queue-types.d.ts +15 -2
  139. package/dist/client/queue-types.d.ts.map +1 -1
  140. package/dist/client/queues.d.ts.map +1 -1
  141. package/dist/client/queues.js +3 -14
  142. package/dist/client/queues.js.map +1 -1
  143. package/dist/client/schemas.d.ts +1 -0
  144. package/dist/client/schemas.d.ts.map +1 -1
  145. package/dist/client/schemas.js +4 -0
  146. package/dist/client/schemas.js.map +1 -1
  147. package/dist/client/thesaurus.d.ts +5 -0
  148. package/dist/client/thesaurus.d.ts.map +1 -1
  149. package/dist/client/thesaurus.js +12 -0
  150. package/dist/client/thesaurus.js.map +1 -1
  151. package/dist/codegen/emit.d.ts +25 -0
  152. package/dist/codegen/emit.d.ts.map +1 -0
  153. package/dist/codegen/emit.js +158 -0
  154. package/dist/codegen/emit.js.map +1 -0
  155. package/dist/codegen/index.d.ts +17 -0
  156. package/dist/codegen/index.d.ts.map +1 -0
  157. package/dist/codegen/index.js +16 -0
  158. package/dist/codegen/index.js.map +1 -0
  159. package/dist/codegen/load-workspace-context.d.ts +30 -0
  160. package/dist/codegen/load-workspace-context.d.ts.map +1 -0
  161. package/dist/codegen/load-workspace-context.js +127 -0
  162. package/dist/codegen/load-workspace-context.js.map +1 -0
  163. package/dist/codegen/normalize.d.ts +35 -0
  164. package/dist/codegen/normalize.d.ts.map +1 -0
  165. package/dist/codegen/normalize.js +77 -0
  166. package/dist/codegen/normalize.js.map +1 -0
  167. package/dist/codegen/types.d.ts +89 -0
  168. package/dist/codegen/types.d.ts.map +1 -0
  169. package/dist/codegen/types.js +9 -0
  170. package/dist/codegen/types.js.map +1 -0
  171. package/dist/codegen/write-artifact.d.ts +40 -0
  172. package/dist/codegen/write-artifact.d.ts.map +1 -0
  173. package/dist/codegen/write-artifact.js +74 -0
  174. package/dist/codegen/write-artifact.js.map +1 -0
  175. package/dist/config/index.d.ts +1 -0
  176. package/dist/config/index.d.ts.map +1 -1
  177. package/dist/config/index.js +1 -0
  178. package/dist/config/index.js.map +1 -1
  179. package/dist/config/workspace-config.d.ts +76 -0
  180. package/dist/config/workspace-config.d.ts.map +1 -0
  181. package/dist/config/workspace-config.js +129 -0
  182. package/dist/config/workspace-config.js.map +1 -0
  183. package/dist/index.d.ts +3 -0
  184. package/dist/index.d.ts.map +1 -1
  185. package/dist/index.js +3 -0
  186. package/dist/index.js.map +1 -1
  187. package/dist/rstreams/event-bridge.d.ts +16 -2
  188. package/dist/rstreams/event-bridge.d.ts.map +1 -1
  189. package/dist/rstreams/event-bridge.js +38 -5
  190. package/dist/rstreams/event-bridge.js.map +1 -1
  191. package/dist/skills/check-scope.d.ts +42 -0
  192. package/dist/skills/check-scope.d.ts.map +1 -0
  193. package/dist/skills/check-scope.js +84 -0
  194. package/dist/skills/check-scope.js.map +1 -0
  195. package/dist/skills/index.d.ts +14 -0
  196. package/dist/skills/index.d.ts.map +1 -0
  197. package/dist/skills/index.js +12 -0
  198. package/dist/skills/index.js.map +1 -0
  199. package/dist/skills/loader.d.ts +79 -0
  200. package/dist/skills/loader.d.ts.map +1 -0
  201. package/dist/skills/loader.js +102 -0
  202. package/dist/skills/loader.js.map +1 -0
  203. package/dist/skills/types.d.ts +55 -0
  204. package/dist/skills/types.d.ts.map +1 -0
  205. package/dist/skills/types.js +9 -0
  206. package/dist/skills/types.js.map +1 -0
  207. package/dist/skills/validate-references.d.ts +54 -0
  208. package/dist/skills/validate-references.d.ts.map +1 -0
  209. package/dist/skills/validate-references.js +80 -0
  210. package/dist/skills/validate-references.js.map +1 -0
  211. package/docs/getting-started.md +7 -0
  212. package/package.json +7 -5
  213. package/dist/cli/commands/data-assets-cmd.d.ts +0 -12
  214. package/dist/cli/commands/data-assets-cmd.d.ts.map +0 -1
  215. package/dist/cli/commands/data-assets-cmd.js +0 -75
  216. package/dist/cli/commands/data-assets-cmd.js.map +0 -1
  217. package/dist/cli/commands/pipelines-cmd.d.ts +0 -17
  218. package/dist/cli/commands/pipelines-cmd.d.ts.map +0 -1
  219. package/dist/cli/commands/pipelines-cmd.js +0 -52
  220. package/dist/cli/commands/pipelines-cmd.js.map +0 -1
  221. package/dist/cli/commands/promises-cmd.d.ts +0 -11
  222. package/dist/cli/commands/promises-cmd.d.ts.map +0 -1
  223. package/dist/cli/commands/promises-cmd.js +0 -53
  224. package/dist/cli/commands/promises-cmd.js.map +0 -1
  225. package/dist/client/consumptions-types.d.ts.map +0 -1
  226. package/dist/client/consumptions-types.js +0 -5
  227. package/dist/client/consumptions-types.js.map +0 -1
  228. package/dist/client/consumptions.d.ts +0 -14
  229. package/dist/client/consumptions.d.ts.map +0 -1
  230. package/dist/client/consumptions.js +0 -47
  231. package/dist/client/consumptions.js.map +0 -1
  232. package/dist/client/data-assets-types.d.ts +0 -150
  233. package/dist/client/data-assets-types.d.ts.map +0 -1
  234. package/dist/client/data-assets-types.js +0 -5
  235. package/dist/client/data-assets-types.js.map +0 -1
  236. package/dist/client/data-assets.d.ts +0 -31
  237. package/dist/client/data-assets.d.ts.map +0 -1
  238. package/dist/client/data-assets.js +0 -182
  239. package/dist/client/data-assets.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,74 @@ 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.4.0] - 2026-07-13
10
+
11
+ ### Breaking changes
12
+
13
+ - **`consumptions` namespace removed** — use `data_products.delivery` and `DeliveryInterface` instead.
14
+
15
+ ### Added
16
+
17
+ - **`data_products.delivery` namespace** — `list`, `create`, `update`, and `delete` for delivery interfaces.
18
+ - **`data_products.readiness` / `data_products.promote`** — medallion tier promotion APIs.
19
+ - **`instances` client namespace** and **`loxtep instances` CLI** — list, get, create, and update runtime instances.
20
+ - **Data product promotion CLI** — `loxtep data-products readiness` and `loxtep data-products promote`.
21
+ - **Data contracts CLI** — `loxtep data-contracts create`.
22
+
23
+ ### Changed
24
+
25
+ - Flow and data-product writers now delegate buffering/batching to the rstreams `load` stream via `createQueueWriter`.
26
+
27
+ ---
28
+
29
+ ## [0.3.0] - 2026-06-08
30
+
31
+ ### Terminology Migration
32
+
33
+ The SDK now uses "delivery" terminology as the primary interface, replacing the
34
+ overloaded "consumption" vocabulary. This aligns the SDK with the platform UI,
35
+ documentation, and MCP tool names.
36
+
37
+ **Namespace rename:** `consumptions` → `delivery`
38
+
39
+ ```ts
40
+ const interfaces = await client.dataProducts.delivery.list(dpId);
41
+ ```
42
+
43
+ **Type:** `DeliveryInterface`
44
+
45
+ ```ts
46
+ import type { DeliveryInterface } from '@loxtep/sdk';
47
+ ```
48
+
49
+ **`deliveryType` field on `DeliveryInterface`:**
50
+
51
+ ```ts
52
+ const webhook: DeliveryInterface = {
53
+ id: 'di_...',
54
+ deliveryType: 'webhook',
55
+ endpointUrl: 'https://example.com/hook',
56
+ method: 'POST',
57
+ // ...
58
+ };
59
+ ```
60
+
61
+ The old `consumptions` namespace and `Consumption` type have been removed.
62
+
63
+ ### New features
64
+
65
+ - **`dataProducts.delivery` namespace** — Primary namespace for managing delivery
66
+ interfaces with `list()`, `create()`, `update()`, and `delete()` methods.
67
+ - **`DeliveryInterface` type** — Includes a `deliveryType` discriminator field
68
+ (`'webhook' | 'api_endpoint' | 'export' | 'database_sync' | 'bi_connect' | 'event_stream'`).
69
+
70
+ ### Removed
71
+
72
+ - `dataProducts.consumptions` namespace — removed. Use `dataProducts.delivery`.
73
+ - `Consumption` type — removed. Use `DeliveryInterface`.
74
+
75
+ ---
76
+
9
77
  ## [0.2.0] - Unreleased
10
78
 
11
79
  ### Breaking changes
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Client for the Loxtep API. Customer-facing surface: **data_products**,
4
4
  **flows**, **connections**, **queues**, **quality**, **catalog**, **discovery**,
5
5
  **schemas**, **projects**, **domains**, **standards**, **data_contracts**,
6
- **workflows**, **templates**, **connectors**, **instances**, **consumptions**,
6
+ **workflows**, **templates**, **connectors**, **instances**, **delivery**,
7
7
  **thesaurus**, **procedures**, **metrics**.
8
8
 
9
9
  **Node.js 22+** is the supported runtime (`engines` in `package.json`). **Live**
@@ -11,7 +11,24 @@ queue/flow writes use the **Loxtep stream** data plane; configure stream bus
11
11
  resources (`streams` on `LoxtepClient` and instance env from your stack) and AWS
12
12
  credentials for SigV4 on both REST and the bus.
13
13
 
14
- ## Quick start (< 5 min to first stream)
14
+ ## Ways to get started
15
+
16
+ This SDK supports two developer workflows:
17
+
18
+ | Path | Use case | Entry point |
19
+ |------|----------|-------------|
20
+ | **Programmatic** | Write/read events from application code (microservices, lambdas, scripts) | `LoxtepClient` → `data_products.get_writer` / `get_reader` |
21
+ | **Code-first CLI** | Author workflows as TypeScript, test locally, deploy via CI | `loxtep init → attach → generate → test → deploy` |
22
+
23
+ There are also two additional paths that don't require this SDK:
24
+ - **Agent-first (MCP)** — drive Loxtep conversationally from Cursor, Kiro, Claude, etc. See [loxtep-plugins-skills](https://github.com/LoxtepInc/loxtep-plugins-skills).
25
+ - **Web UI** — visual project setup and management at [app.loxtep.io](https://app.loxtep.io).
26
+
27
+ All paths are documented in the [Loxtep Quickstart](https://docs.loxtep.io/quickstart).
28
+
29
+ ---
30
+
31
+ ## Quick start — Programmatic (< 5 min to first stream)
15
32
 
16
33
  1. **Install**
17
34
 
@@ -85,6 +102,60 @@ credentials for SigV4 on both REST and the bus.
85
102
  JWT-backed client. Note: `data_products.get_writer` and `get_reader` resolve
86
103
  stream config automatically — this is only needed for manual bus access.
87
104
 
105
+ ---
106
+
107
+ ## Quick start — Code-first CLI (init → deploy)
108
+
109
+ For developers who author workflows as TypeScript and want the full local-dev-to-production lifecycle:
110
+
111
+ ```bash
112
+ # 1. Install
113
+ npm install @loxtep/sdk
114
+
115
+ # 2. Authenticate
116
+ npx loxtep login
117
+
118
+ # 3. Scaffold a project from a template
119
+ npx loxtep init --template shopify-orders
120
+
121
+ # 4. Bind to a runtime instance
122
+ npx loxtep attach --instance prod
123
+
124
+ # 5. Generate typed workspace constants
125
+ npx loxtep generate
126
+
127
+ # 6. Author a workflow (see authoring module docs below)
128
+
129
+ # 7. Test locally with a sample event
130
+ npx loxtep test orders-enricher --event ./events/order-created.json
131
+
132
+ # 8. Deploy to the workflow engine
133
+ npx loxtep deploy
134
+ ```
135
+
136
+ The `generate` step produces `.loxtep/generated/index.ts` with typed constants for every data product, connector, domain, and queue in your workspace. Import them in your workflow modules for compile-time safety:
137
+
138
+ ```ts
139
+ import { defineDataWorkflow, on } from '@loxtep/sdk/authoring'
140
+ import { workspace } from './.loxtep/generated'
141
+
142
+ export default defineDataWorkflow({
143
+ name: 'orders-enricher',
144
+ triggers: [on.queueEvent(workspace.queues.orders_raw)],
145
+ async handler(ctx, event) {
146
+ await ctx.toolbox.dataProducts.upsert({
147
+ dataProduct: workspace.dataProducts.orders_enriched,
148
+ domain: workspace.domains.commerce,
149
+ record: event,
150
+ })
151
+ },
152
+ })
153
+ ```
154
+
155
+ See `loxtep init --help`, `loxtep attach --help`, etc. for all flags. The full CLI reference is in the [CLI reference](#cli-reference) section below.
156
+
157
+ ---
158
+
88
159
  ## API surface
89
160
 
90
161
  - **data_products** – get, get_lexicon, list, search, query, list_tables,
@@ -108,7 +179,7 @@ credentials for SigV4 on both REST and the bus.
108
179
  - **standards** – list, get
109
180
  - **data_contracts** – list, get
110
181
  - **thesaurus** – listTerms, resolveCanonicalKey
111
- - **consumptions** – list, get, create, update, delete
182
+ - **delivery** – list, get, create, update, delete
112
183
  - **instances** – list, get, get_stream_config
113
184
  - **procedures** – list
114
185
  - **metrics** – log, get_reporter
@@ -184,6 +255,39 @@ for await (const event of filterStream(
184
255
  }
185
256
  ```
186
257
 
258
+ ## Delivery interfaces
259
+
260
+ Configure how a data product delivers data to external systems.
261
+
262
+ ```ts
263
+ import { LoxtepClient } from '@loxtep/sdk';
264
+ import type { DeliveryInterface, DeliveryCreateInput } from '@loxtep/sdk';
265
+
266
+ const client = new LoxtepClient({
267
+ api_url: 'https://api.loxtep.com',
268
+ auth: { type: 'jwt', token: process.env.LOXTEP_AUTH_TOKEN! },
269
+ });
270
+
271
+ // List delivery interfaces for a data product
272
+ const { items, pagination } = await client.delivery.list('dp_abc123');
273
+
274
+ // Create a webhook delivery interface
275
+ const webhook = await client.delivery.create('dp_abc123', {
276
+ deliveryType: 'webhook',
277
+ name: 'Order notifications',
278
+ endpoint_url: 'https://example.com/webhooks/orders',
279
+ method: 'POST',
280
+ });
281
+
282
+ // Update a delivery interface
283
+ await client.delivery.update('dp_abc123', webhook.consumption_id, {
284
+ is_active: false,
285
+ });
286
+
287
+ // Delete a delivery interface
288
+ await client.delivery.delete('dp_abc123', webhook.consumption_id);
289
+ ```
290
+
187
291
  ## Documentation
188
292
 
189
293
  - **Getting started** – Zero to first event in under 5 minutes.
@@ -203,7 +307,13 @@ for await (const event of filterStream(
203
307
  | `login --email <e> --password <p>` | Headless login for CI (optional `--mfa-code`) |
204
308
  | `logout` | Remove stored credentials |
205
309
  | `whoami` | Print current user and organization |
206
- | `init` | Setup checklist + doc pointers |
310
+ | `init [--template <slug>]` | Scaffold project structure, AGENTS.md, and default skill |
311
+ | `init --create-repo [name]` | Scaffold + create a new GitHub repo (private default) |
312
+ | `init --from-repo <url>` | Scaffold + import from an existing repo |
313
+ | `attach --instance <name-or-id>` | Bind project to a runtime instance |
314
+ | `generate` | Codegen typed workspace constants to `.loxtep/generated/index.ts` |
315
+ | `test <module> --event <file>` | Run a workflow module locally with sample event(s) |
316
+ | `deploy` | Compile modules, validate resources, deploy to workflow engine |
207
317
  | `config list` | Show api_url, organization_id, project_id, instance_id |
208
318
  | `config paths` | Show resolved URLs for auth and SDK path matrix |
209
319
  | `config set <key> <value>` | Set api_url \| organization_id \| project_id \| instance_id |
@@ -249,3 +359,144 @@ loxtep queue info <data-product-id>
249
359
  loxtep data-products query <data-product-id> "SELECT * FROM t LIMIT 10"
250
360
  loxtep metrics rate-limits
251
361
  ```
362
+
363
+ ## Module exports
364
+
365
+ The SDK also ships standalone modules for configuration, authentication,
366
+ code generation, skill scoping, and workflow authoring. Import them directly
367
+ from the relevant subpath.
368
+
369
+ ### `config` module
370
+
371
+ ```typescript
372
+ import { loadConfig, loadConfigSync, saveConfig } from '@loxtep/sdk/config';
373
+ ```
374
+
375
+ | Export | Type | Description |
376
+ | --- | --- | --- |
377
+ | `loadConfig` | function | Load config from env vars and optional file (async). Precedence: env > file > defaults |
378
+ | `loadConfigSync` | function | Synchronous variant of `loadConfig` using `readFileSync` |
379
+ | `saveConfig` | function | Persist config (api_url, org/project/instance IDs) to file. No secrets written to disk |
380
+ | `parseStreamsPartial` | function | Extract a partial bus config from unknown JSON, keeping only valid stream resource keys |
381
+ | `getConfigDir` | function | Return the default config directory path (`~/.loxtep`) |
382
+ | `getDefaultConfigPath` | function | Return the default config file path (`~/.loxtep/config.json`) |
383
+ | `buildAuthServiceUrl` | function | Build the full URL for auth endpoints (`/auth/login`, `/auth/refresh`) with path prefix |
384
+ | `extendClientBaseUrl` | function | Extend `api_url` with a microservice path segment, avoiding duplication |
385
+ | `buildPlatformRequestUrl` | function | Build a full request URL for the shared control-plane host, handling microservice routing |
386
+ | `resolveAutoConfig` | function | Resolve configuration with full precedence: env > explicit > workspace files |
387
+
388
+ ### `auth` module
389
+
390
+ ```typescript
391
+ import { login, refresh, browserLogin, TokenManager } from '@loxtep/sdk/auth';
392
+ ```
393
+
394
+ | Export | Type | Description |
395
+ | --- | --- | --- |
396
+ | `decodeJwtPayload` | function | Decode JWT payload to read `exp` (expiry) without verification. Client-side only |
397
+ | `login` | function | Authenticate with email/password via `POST /auth/login`. Returns access + refresh tokens |
398
+ | `refresh` | function | Refresh an access token via `POST /auth/refresh` |
399
+ | `browserLogin` | function | Run OAuth 2.1 browser-based login flow with a localhost callback server |
400
+ | `TokenManager` | class | In-memory token manager with auto-refresh support. No tokens persisted to disk |
401
+ | `LoginMfaRequiredError` | class | Error thrown when login returns 403 and the user must supply a TOTP code |
402
+
403
+ ### `codegen` module
404
+
405
+ ```typescript
406
+ import { loadWorkspaceContext, deriveKey, normalizeContext, emitArtifact, writeArtifact, computeCounts } from '@loxtep/sdk/codegen';
407
+ ```
408
+
409
+ | Export | Type | Description |
410
+ | --- | --- | --- |
411
+ | `loadWorkspaceContext` | function | Fetch all workspace resources from the control plane and assemble a `WorkspaceContext` |
412
+ | `deriveKey` | function | Derive a deterministic, valid TypeScript identifier key from a resource name |
413
+ | `normalizeContext` | function | Transform raw `WorkspaceContext` into canonical `NormalizedContext` with stable keys and id-sorted ordering |
414
+ | `emitArtifact` | function | Render a `NormalizedContext` into a complete TypeScript source string with `as const` exports |
415
+ | `writeArtifact` | function | Atomic file write of the generated artifact; returns per-resource-type counts |
416
+ | `computeCounts` | function | Compute per-resource-type counts from a `NormalizedContext` |
417
+
418
+ ### `skills` module
419
+
420
+ ```typescript
421
+ import { checkScope, parseSkillYaml, loadSkillsFromDirectory } from '@loxtep/sdk/skills';
422
+ ```
423
+
424
+ | Export | Type | Description |
425
+ | --- | --- | --- |
426
+ | `checkScope` | function | Fail-closed scope decision: check whether an operation on a resource is permitted by a skill |
427
+ | `checkScopeByName` | function | Resolve a skill by name from a map and check scope in one step |
428
+ | `parseSkillYaml` | function | Parse a YAML string into a validated `SkillDefinition` |
429
+ | `loadSkillFromFile` | function | Load a single skill definition from a `.yaml` file path |
430
+ | `loadSkillsFromDirectory` | function | Load all skill definitions from a `.loxtep/skills/` directory |
431
+ | `validateSkillReferences` | function | Validate all skill resource references against the loaded `WorkspaceContext` |
432
+ | `formatSkillValidationErrors` | function | Format skill validation errors into human-readable messages |
433
+ | `SkillDefinitionSchema` | object | Zod schema for validating skill definition YAML structure |
434
+
435
+ ### `authoring` module
436
+
437
+ ```typescript
438
+ import { defineDataWorkflow, on, createToolbox, agent } from '@loxtep/sdk/authoring';
439
+ ```
440
+
441
+ | Export | Type | Description |
442
+ | --- | --- | --- |
443
+ | `defineDataWorkflow` | function | Validate and return a `DataWorkflowModule` spec. Throws `ValidationError` on invalid input |
444
+ | `on` | object | Trigger builders: `queueEvent`, `connectorEvent`, `schedule`, `webhook` |
445
+ | `createToolbox` | function | Create a deterministic typed platform-call toolbox (no model in the loop) |
446
+ | `agent` | function | Agentic operation entry point with scope enforcement and action trace |
447
+ | `validateAgentOptions` | function | Validate agent options (prompt length, skills references) against available skills |
448
+ | `computeReachableScope` | function | Compute the union of all resource scopes from supplied skill definitions |
449
+ | `enforceAgentScope` | function | Check whether a resource access is within the merged scope of the agent's skills |
450
+ | `createScopeGuardedToolbox` | function | Create a scope-guarded proxy that enforces scope and records traces before every call |
451
+ | `compileModule` | function | Pure compiler: lower a `DataWorkflowModule` into `GraphPatchOp[]` for deployment |
452
+ | `computeRemovalSet` | function | Compute workflows present on instance but absent from project modules (for cleanup) |
453
+ | `ActionTrace` | class | Mutable action trace recorder with monotonically increasing sequence numbers |
454
+ | `AgentScopeError` | class | Error thrown when an agentic operation is blocked due to a scope violation |
455
+ | `ToolboxOperationError` | class | Error thrown when a toolbox operation fails (network, validation, or platform error) |
456
+
457
+ ### `http` module
458
+
459
+ ```typescript
460
+ import { signRequest, LoxtepHttpClient } from '@loxtep/sdk/http';
461
+ ```
462
+
463
+ | Export | Type | Description |
464
+ | --- | --- | --- |
465
+ | `signRequest` | function | Sign an HTTP request with AWS SigV4 for API Gateway (`execute-api`). Returns headers including `Authorization` and `x-amz-*` |
466
+ | `LoxtepHttpClient` | class | HTTP client that signs requests with AWS SigV4 and attaches JWT. Provides `get`, `post`, `put`, `delete` helpers with retry on 5xx/network errors and typed Loxtep errors on 4xx |
467
+
468
+ ### `checkpoint` module
469
+
470
+ ```typescript
471
+ import { createMemoryCheckpointStore } from '@loxtep/sdk/checkpoint';
472
+ ```
473
+
474
+ | Export | Type | Description |
475
+ | --- | --- | --- |
476
+ | `createMemoryCheckpointStore` | function | Create an in-memory checkpoint store for stream/replay resume. Suitable for tests or single-process use |
477
+
478
+ ### Error classes
479
+
480
+ ```typescript
481
+ import { AuthorizationError, ConflictError, ValidationError, DefinitionValidationError, SchemaValidationError, CheckpointError, parseHttpError } from '@loxtep/sdk/errors';
482
+ ```
483
+
484
+ | Export | Type | Description |
485
+ | --- | --- | --- |
486
+ | `AuthorizationError` | class | 403 — Insufficient permissions |
487
+ | `ConflictError` | class | 409 — Resource already exists or version conflict |
488
+ | `ValidationError` | class | 400 — Invalid input with optional `field_errors` array |
489
+ | `DefinitionValidationError` | class | 400 — Payload doesn't match data product definition (schema validation failures) |
490
+ | `SchemaValidationError` | class | Alias for `DefinitionValidationError` (backend terminology) |
491
+ | `CheckpointError` | class | 500 — Failed to save or load a stream checkpoint |
492
+ | `parseHttpError` | function | Map an HTTP status code and response body to the appropriate typed Loxtep error class |
493
+
494
+ ### `DataProductResolver` class
495
+
496
+ ```typescript
497
+ import { DataProductResolver } from '@loxtep/sdk/client';
498
+ ```
499
+
500
+ | Export | Type | Description |
501
+ | --- | --- | --- |
502
+ | `DataProductResolver` | class | Resolves a data product name or UUID into full runtime configuration (queue name, bot_id, stream bus resources). Caches results in memory. Used internally by `client.data_products.get_writer`/`get_reader` |
@@ -0,0 +1,164 @@
1
+ /**
2
+ * `agent()` entry point — agentic operations with input validation,
3
+ * client-side scope enforcement, and action trace recording.
4
+ *
5
+ * The agentic path accepts a prompt and a skills allowlist, validates inputs,
6
+ * enforces scope boundaries before any platform call, and records every
7
+ * operation as an ordered ActionTraceEntry.
8
+ *
9
+ * Requirements: 4.2, 4.3, 4.4, 4.5, 4.6, 7.1
10
+ */
11
+ import { LoxtepError } from '../errors/base.js';
12
+ import type { SkillDefinition, SkillScope, Operation, ScopeDecision } from '../skills/types.js';
13
+ import type { HandlerContext } from './types.js';
14
+ import type { Toolbox } from './toolbox.js';
15
+ /**
16
+ * A reference to a skill from the Generated_SDK_Artifact.
17
+ * Must contain at minimum a `name` field that matches a loaded skill definition.
18
+ */
19
+ export interface SkillRef {
20
+ name: string;
21
+ }
22
+ /**
23
+ * Options for the `agent()` entry point.
24
+ */
25
+ export interface AgentOptions {
26
+ /** The prompt for the agentic operation. 1–10,000 characters, non-empty (R4.2, R4.6). */
27
+ prompt: string;
28
+ /** Skills allowlist. 1–50 refs, each present in the generated artifact (R4.2, R4.6). */
29
+ skills: SkillRef[];
30
+ }
31
+ /**
32
+ * Outcome of an action trace entry.
33
+ */
34
+ export type ActionOutcome = 'succeeded' | 'failed' | 'blocked';
35
+ /**
36
+ * A single entry in the action trace recording an operation's execution.
37
+ * Ordered by execution start time (monotonic sequence, R4.5, R7.1).
38
+ */
39
+ export interface ActionTraceEntry {
40
+ /** Monotonically increasing sequence number (1-based). */
41
+ seq: number;
42
+ /** The type of operation: deterministic toolbox call or agentic step. */
43
+ kind: 'toolbox' | 'agentic' | 'scope_check';
44
+ /** The operation name (e.g. 'dataProducts.write', 'scope_enforcement'). */
45
+ operationName: string;
46
+ /** The target resource identifier, if applicable. */
47
+ targetResource?: string;
48
+ /** Execution start time (ISO 8601 UTC). */
49
+ startedAt: string;
50
+ /** Execution completion time (ISO 8601 UTC). */
51
+ completedAt: string;
52
+ /** Outcome of the operation. */
53
+ outcome: ActionOutcome;
54
+ /** Error message if the operation failed or was blocked. */
55
+ error?: string;
56
+ }
57
+ /**
58
+ * The result of an `agent()` invocation.
59
+ */
60
+ export interface AgentResult {
61
+ /** Whether the overall agentic operation succeeded. */
62
+ success: boolean;
63
+ /** The action trace recording every operation executed. */
64
+ trace: ActionTraceEntry[];
65
+ /** Error if the operation terminated due to a scope violation or failure. */
66
+ error?: {
67
+ code: string;
68
+ message: string;
69
+ deniedResource?: string;
70
+ };
71
+ }
72
+ /**
73
+ * Internal context for the agent execution environment.
74
+ */
75
+ export interface AgentExecutionContext {
76
+ /** The handler context (workflow name, instance, project). */
77
+ handlerContext: HandlerContext;
78
+ /** The resolved skill definitions for the supplied skills. */
79
+ skillDefinitions: SkillDefinition[];
80
+ /** The available toolbox for making platform calls. */
81
+ toolbox: Toolbox;
82
+ /** The set of valid skill names from the generated artifact. */
83
+ availableSkillNames: Set<string>;
84
+ }
85
+ /**
86
+ * Validate the agent options (prompt + skills).
87
+ * Throws ValidationError on invalid input (R4.6).
88
+ *
89
+ * @param options - The agent options to validate.
90
+ * @param availableSkillNames - Set of skill names present in the generated artifact.
91
+ */
92
+ export declare function validateAgentOptions(options: AgentOptions, availableSkillNames: Set<string>): void;
93
+ /**
94
+ * Compute the union of all resource scopes from the supplied skill definitions.
95
+ * The reachable set is the union of all skills' scopes (R4.3).
96
+ *
97
+ * @param skills - The skill definitions to union.
98
+ * @returns A merged SkillScope representing all reachable resources.
99
+ */
100
+ export declare function computeReachableScope(skills: SkillDefinition[]): SkillDefinition;
101
+ /**
102
+ * Check whether a resource access is within the merged scope of the agent's skills.
103
+ * Blocks out-of-scope reaches before any platform call (R4.4).
104
+ *
105
+ * @param mergedSkill - The merged skill scope (union of all supplied skills).
106
+ * @param resourceType - The resource type being accessed.
107
+ * @param resourceId - The resource identifier being accessed.
108
+ * @param operation - The operation being attempted.
109
+ * @returns The scope decision.
110
+ */
111
+ export declare function enforceAgentScope(mergedSkill: SkillDefinition, resourceType: keyof SkillScope, resourceId: string, operation: Operation): ScopeDecision;
112
+ /**
113
+ * Mutable action trace recorder. Assigns monotonically increasing sequence
114
+ * numbers to each entry (R4.5, R7.1).
115
+ */
116
+ export declare class ActionTrace {
117
+ private readonly entries;
118
+ private seq;
119
+ /**
120
+ * Record a completed operation in the trace.
121
+ */
122
+ record(entry: Omit<ActionTraceEntry, 'seq'>): ActionTraceEntry;
123
+ /**
124
+ * Get all recorded entries in order.
125
+ */
126
+ getEntries(): ActionTraceEntry[];
127
+ /**
128
+ * Get the current sequence number (number of recorded entries).
129
+ */
130
+ getSeq(): number;
131
+ }
132
+ /**
133
+ * Error thrown when an agentic operation is blocked due to a scope violation.
134
+ */
135
+ export declare class AgentScopeError extends LoxtepError {
136
+ readonly deniedResource: string;
137
+ constructor(deniedResource: string, code: string, message: string);
138
+ }
139
+ /**
140
+ * The `agent()` entry point for agentic operations within a data workflow handler.
141
+ *
142
+ * Validates inputs (R4.6), restricts the model to the supplied skills (R4.3),
143
+ * blocks out-of-scope reaches before any platform call (R4.4), and records
144
+ * every operation in an ordered action trace (R4.5, R7.1).
145
+ *
146
+ * @param ctx - Handler context (workflow name, instance, project).
147
+ * @param options - Agent options (prompt + skills allowlist).
148
+ * @param execContext - Execution context with resolved skills + toolbox.
149
+ * @returns The agent result including the action trace.
150
+ * @throws {ValidationError} If prompt or skills are invalid (R4.6).
151
+ */
152
+ export declare function agent(ctx: HandlerContext, options: AgentOptions, execContext: AgentExecutionContext): Promise<AgentResult>;
153
+ /**
154
+ * Create a scope-guarded proxy around the toolbox. Every method call goes through
155
+ * scope enforcement first; if denied, the call is blocked, a trace entry is recorded,
156
+ * and an AgentScopeError is thrown terminating the operation (R4.4).
157
+ *
158
+ * @param toolbox - The underlying toolbox.
159
+ * @param mergedSkill - The merged skill scope for enforcement.
160
+ * @param trace - The action trace to record operations.
161
+ * @returns A guarded toolbox that enforces scope and records traces.
162
+ */
163
+ export declare function createScopeGuardedToolbox(toolbox: Toolbox, mergedSkill: SkillDefinition, trace: ActionTrace): Toolbox;
164
+ //# sourceMappingURL=agent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/authoring/agent.ts"],"names":[],"mappings":"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"}