@loxtep/sdk 0.7.22 → 0.7.24

package/dist/lib/workspace-lint.js

@@ -0,0 +1,199 @@
+/**
+ * Offline lint of a local Loxtep project package (entity schemas + relationships).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { EntityType, validateEntity } from './entity-json-schemas/index.js';
+function readJsonObject(filePath) {
+    try {
+        const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+            return raw;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function listJsonFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const full = join(dir, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            out.push(...listJsonFiles(full));
+        }
+        else if (name.endsWith('.json')) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+function classifyEntity(projectDir, filePath) {
+    const rel = relative(projectDir, filePath).replace(/\\/g, '/');
+    if (rel.startsWith('connectors/') && rel.endsWith('.json')) {
+        return EntityType.CONNECTOR;
+    }
+    if (rel.match(/^workflows\/[^/]+\/workflow\.json$/)) {
+        return EntityType.WORKFLOW;
+    }
+    if (rel.match(/^workflows\/[^/]+\/connections\/[^/]+\.json$/)) {
+        return EntityType.CONNECTION;
+    }
+    if (rel.match(/^workflows\/[^/]+\/data-products\/[^/]+\.json$/)) {
+        return EntityType.DATA_PRODUCT;
+    }
+    if (rel.match(/^workflows\/[^/]+\/transformations\/[^/]+\.json$/)) {
+        return EntityType.TRANSFORMATION;
+    }
+    if (rel.match(/^workflows\/[^/]+\/validations\/[^/]+\.json$/)) {
+        return EntityType.VALIDATION;
+    }
+    if (rel.startsWith('domains/') && rel.endsWith('.json')) {
+        return EntityType.DOMAIN;
+    }
+    return null;
+}
+function discoverEntities(projectDir, workflowId) {
+    const entities = [];
+    const roots = [join(projectDir, 'connectors'), join(projectDir, 'domains')];
+    if (workflowId) {
+        roots.push(join(projectDir, 'workflows', workflowId));
+    }
+    else {
+        roots.push(join(projectDir, 'workflows'));
+    }
+    for (const root of roots) {
+        for (const filePath of listJsonFiles(root)) {
+            const entityType = classifyEntity(projectDir, filePath);
+            if (!entityType)
+                continue;
+            const data = readJsonObject(filePath);
+            const rel = relative(projectDir, filePath).replace(/\\/g, '/');
+            if (!data) {
+                entities.push({
+                    path: rel,
+                    entityType,
+                    data: {},
+                });
+                // mark unreadable via empty + special handling below
+                continue;
+            }
+            entities.push({ path: rel, entityType, data });
+        }
+    }
+    return entities;
+}
+/**
+ * Lint local entity JSON against shipped schemas and basic relationship checks.
+ */
+export function lintLocalPackage(options) {
+    const { projectDir, workflow_id } = options;
+    const issues = [];
+    if (!existsSync(projectDir)) {
+        return {
+            ok: false,
+            files_checked: 0,
+            issues: [{ path: projectDir, severity: 'error', message: 'Project directory not found' }],
+        };
+    }
+    const entities = discoverEntities(projectDir, workflow_id);
+    const byId = new Map();
+    for (const entity of entities) {
+        if (Object.keys(entity.data).length === 0) {
+            issues.push({
+                path: entity.path,
+                severity: 'error',
+                message: 'Invalid or unreadable JSON object',
+            });
+            continue;
+        }
+        const result = validateEntity(entity.entityType, entity.data);
+        if (!result.valid && result.errors) {
+            for (const err of result.errors) {
+                issues.push({
+                    path: `${entity.path}${err.path}`,
+                    severity: 'error',
+                    message: err.message,
+                });
+            }
+        }
+        const idKey = entity.data.connector_id ||
+            entity.data.connection_id ||
+            entity.data.workflow_id ||
+            entity.data.data_product_id ||
+            entity.data.domain_id;
+        if (idKey) {
+            byId.set(idKey, entity);
+        }
+    }
+    // Relationship checks
+    for (const entity of entities) {
+        if (entity.entityType === EntityType.CONNECTION) {
+            const connectorId = entity.data.connector_id;
+            if (typeof connectorId === 'string' && connectorId.length > 0) {
+                // connector may exist only remotely; warn only if local connectors/ is present
+                // and does not contain this id — keep as error when local connector file expected.
+                const localConnectors = entities.filter(e => e.entityType === EntityType.CONNECTOR);
+                if (localConnectors.length > 0 &&
+                    !localConnectors.some(c => c.data.connector_id === connectorId)) {
+                    issues.push({
+                        path: entity.path,
+                        severity: 'error',
+                        message: `connector_id "${connectorId}" not found under connectors/`,
+                    });
+                }
+            }
+            else {
+                issues.push({
+                    path: entity.path,
+                    severity: 'error',
+                    message: 'connection is missing connector_id',
+                });
+            }
+        }
+        if (entity.entityType === EntityType.DATA_PRODUCT) {
+            const upstream = entity.data.upstream_entity_id;
+            if (typeof upstream === 'string' && upstream.length > 0 && !byId.has(upstream)) {
+                // Upstream may be a connection in the same workflow — check connection ids
+                const conn = entities.find(e => e.entityType === EntityType.CONNECTION && e.data.connection_id === upstream);
+                if (!conn) {
+                    issues.push({
+                        path: entity.path,
+                        severity: 'error',
+                        message: `upstream_entity_id "${upstream}" not found in local package`,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        issues,
+        files_checked: entities.length,
+    };
+}
+/**
+ * True when the project has at least one entity JSON package file to lint.
+ */
+export function hasLocalEntityPackage(projectDir) {
+    const workflowsDir = join(projectDir, 'workflows');
+    if (!existsSync(workflowsDir))
+        return false;
+    for (const name of readdirSync(workflowsDir)) {
+        const wfJson = join(workflowsDir, name, 'workflow.json');
+        if (existsSync(wfJson))
+            return true;
+    }
+    return existsSync(join(projectDir, 'connectors')) && listJsonFiles(join(projectDir, 'connectors')).length > 0;
+}
+//# sourceMappingURL=workspace-lint.js.map

package/dist/lib/workspace-lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-lint.js","sourceRoot":"","sources":["../../src/lib/workspace-lint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AA2B5E,SAAS,cAAc,CAAC,QAAgB;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAY,CAAC;QAClE,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1D,OAAO,GAA8B,CAAC;QACxC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,EAAE,CAAC;QACP,IAAI,CAAC;YACH,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;YACrB,GAAG,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CACrB,UAAkB,EAClB,QAAgB;IAEhB,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/D,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3D,OAAO,UAAU,CAAC,SAAS,CAAC;IAC9B,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,oCAAoC,CAAC,EAAE,CAAC;QACpD,OAAO,UAAU,CAAC,QAAQ,CAAC;IAC7B,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,8CAA8C,CAAC,EAAE,CAAC;QAC9D,OAAO,UAAU,CAAC,UAAU,CAAC;IAC/B,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,gDAAgD,CAAC,EAAE,CAAC;QAChE,OAAO,UAAU,CAAC,YAAY,CAAC;IACjC,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,kDAAkD,CAAC,EAAE,CAAC;QAClE,OAAO,UAAU,CAAC,cAAc,CAAC;IACnC,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,8CAA8C,CAAC,EAAE,CAAC;QAC9D,OAAO,UAAU,CAAC,UAAU,CAAC;IAC/B,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACxD,OAAO,UAAU,CAAC,MAAM,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,UAAkB,EAAE,UAAmB;IAC/D,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,MAAM,KAAK,GAAa,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;IAEtF,IAAI,UAAU,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;IACxD,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,UAAU,GAAG,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YACxD,IAAI,CAAC,UAAU;gBAAE,SAAS;YAC1B,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;YACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC/D,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,GAAG;oBACT,UAAU;oBACV,IAAI,EAAE,EAAE;iBACT,CAAC,CAAC;gBACH,qDAAqD;gBACrD,SAAS;YACX,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACnD,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAC5C,MAAM,MAAM,GAAgB,EAAE,CAAC;IAE/B,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,aAAa,EAAE,CAAC;YAChB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAC;SAC1F,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEjD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,mCAAmC;aAC7C,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YACnC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAChC,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,GAAG,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE;oBACjC,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,GAAG,CAAC,OAAO;iBACrB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GACR,MAAM,CAAC,IAAI,CAAC,YAAmC;YAC/C,MAAM,CAAC,IAAI,CAAC,aAAoC;YAChD,MAAM,CAAC,IAAI,CAAC,WAAkC;YAC9C,MAAM,CAAC,IAAI,CAAC,eAAsC;YAClD,MAAM,CAAC,IAAI,CAAC,SAAgC,CAAC;QAChD,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,IAAI,MAAM,CAAC,UAAU,KAAK,UAAU,CAAC,UAAU,EAAE,CAAC;YAChD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;YAC7C,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9D,+EAA+E;gBAC/E,mFAAmF;gBACnF,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,SAAS,CAAC,CAAC;gBACpF,IACE,eAAe,CAAC,MAAM,GAAG,CAAC;oBAC1B,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,KAAK,WAAW,CAAC,EAC/D,CAAC;oBACD,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,MAAM,CAAC,IAAI;wBACjB,QAAQ,EAAE,OAAO;wBACjB,OAAO,EAAE,iBAAiB,WAAW,+BAA+B;qBACrE,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,oCAAoC;iBAC9C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,KAAK,UAAU,CAAC,YAAY,EAAE,CAAC;YAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC;YAChD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC/E,2EAA2E;gBAC3E,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,CACF,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,UAAU,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,KAAK,QAAQ,CAC9E,CAAC;gBACF,IAAI,CAAC,IAAI,EAAE,CAAC;oBACV,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,MAAM,CAAC,IAAI;wBACjB,QAAQ,EAAE,OAAO;wBACjB,OAAO,EAAE,uBAAuB,QAAQ,8BAA8B;qBACvE,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QACvB,MAAM;QACN,aAAa,EAAE,QAAQ,CAAC,MAAM;KAC/B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkB;IACtD,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;QACzD,IAAI,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;IACtC,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAChH,CAAC"}

package/docs/getting-started.md

@@ -170,6 +170,8 @@ from your application:
 
 ```bash
 pnpm exec loxtep ingest provision --name app-events
+pnpm exec loxtep lint
+pnpm exec loxtep deploy
 pnpm exec loxtep data-products list
 ```
 

package/docs/quick-reference.md

@@ -193,6 +193,7 @@ pnpm exec loxtep generate
 
 ```bash
 pnpm exec loxtep ingest provision --name app-events
+pnpm exec loxtep lint && pnpm exec loxtep deploy
 ```
 
 See [Write to a data product](./sdk-first-ingest.md).

package/docs/sdk-first-ingest.md

@@ -22,20 +22,34 @@ You should see `project_id` and `instance_id` from `attach`.
 
 ---
 
-## Phase 2 — Create your data product
+## Phase 2 — Create your data product (local package)
 
 Pick a name your app will use (example: `app-events`):
 
 ```bash
+pnpm exec loxtep connectors list --type sdk   # optional: see existing SDK connectors
 pnpm exec loxtep ingest provision --name app-events
+pnpm exec loxtep lint
 ```
 
-That is all you need for SDK writes — one command, one name.
+`ingest provision` reuses an existing SDK connector when one exists (or creates one),
+then writes a **local** workflow package under `connectors/` and `workflows/<id>/`.
+It does **not** deploy by default. Validate with `loxtep lint`, then publish:
+
+```bash
+pnpm exec loxtep deploy --dry-run   # lint only
+pnpm exec loxtep deploy             # lint + compile/deploy modules
+# or: pnpm exec loxtep ingest provision --name app-events --deploy
+```
+
+That local package is what you iterate on; deploy pushes it to your instance.
 
 ---
 
 ## Phase 3 — Confirm it exists
 
+After deploy:
+
 ```bash
 pnpm exec loxtep data-products list
 ```
@@ -90,6 +104,8 @@ pnpm exec loxtep login
 pnpm exec loxtep init
 pnpm exec loxtep attach --instance <instance-id>
 pnpm exec loxtep ingest provision --name app-events
+pnpm exec loxtep lint
+pnpm exec loxtep deploy
 pnpm exec loxtep data-products list
 ```
 
@@ -102,7 +118,7 @@ Then `get_writer('app-events')` in your app.
 | What you see | What to do |
 | ------------ | ---------- |
 | Data product not found | Run `data-products list`. Check the name matches `get_writer('…')` exactly. |
-| Not ready to accept writes | Run `ingest provision` again for that name. Make sure you ran `attach` first. |
+| Not ready to accept writes | Run `ingest provision`, then `deploy` (or `ingest provision --deploy`). Make sure you ran `attach` first. |
 | Multiple products with the same name | Pass the data product id to `get_writer`, or ensure `attach` points at the right instance. |
 | No domain available | Create a domain in the Loxtep UI, or pass `--domain-id` to `ingest provision`. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxtep/sdk",
-  "version": "0.7.22",
+  "version": "0.7.24",
   "description": "Loxtep SDK for Node.js — the Enterprise Context Layer: data products, workflows, projects, queues, and machine-usable context for AI",
   "author": "Loxtep <engineering@loxtep.io>",
   "homepage": "https://loxtep.io",
@@ -33,13 +33,15 @@
   "files": [
     "dist",
     "docs",
+    "schemas",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && mkdir -p dist/lib/entity-json-schemas && cp src/lib/entity-json-schemas/ajv-loader.cjs dist/lib/entity-json-schemas/ajv-loader.cjs",
     "prepublishOnly": "npm run build",
     "test": "jest --config jest.config.cjs",
     "lint": "eslint src --ext .ts",
+    "sync:entity-schemas": "node scripts/sync-entity-schemas.mjs",
     "generate:api-types": "tsx scripts/generate-api-types.ts",
     "docs": "typedoc"
   },
@@ -82,6 +84,8 @@
     "@smithy/protocol-http": "^5.4.3",
     "@smithy/signature-v4": "^5.4.3",
     "@smithy/types": "^4.14.2",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "js-yaml": "^4.3.0",
     "leo-sdk": "7.1.21",
     "zod": "^4.4.3"

package/schemas/entity-json-schemas/SCHEMA_SYNC.md

@@ -0,0 +1,18 @@
+# Entity JSON schemas (vendored)
+
+These JSON Schema draft-07 files are a copy of the Loxtep platform schemas used
+for customer workspace entity validation.
+
+**Source (canonical):**
+`loxtep/platform-backend/_core/src/customer-workspace/entity-json-schemas/`
+
+**Sync command** (from `nodejs/`):
+
+```bash
+node scripts/sync-entity-schemas.mjs /path/to/loxtep
+```
+
+When platform schemas change, re-run the sync script and note the date/source
+commit in the SDK CHANGELOG.
+
+**Last synced:** 2026-07-24 (from local loxtep checkout)

package/schemas/entity-json-schemas/connection.json

@@ -0,0 +1,310 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://loxtep.io/schemas/entity/connection.json",
+  "title": "Connection Entity",
+  "description": "JSON Schema for Connection entity in customer workspace. Connections are configured instances of connectors with credentials and settings.",
+  "type": "object",
+  "required": [
+    "connection_id",
+    "organization_id",
+    "project_id",
+    "key",
+    "name",
+    "type",
+    "status"
+  ],
+  "properties": {
+    "connection_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the connection"
+    },
+    "organization_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Organization that owns this connection"
+    },
+    "project_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Project that contains this connection"
+    },
+    "workflow_id": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "Workflow this connection belongs to; null for project-level/draft connections"
+    },
+    "connector_id": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "Reference to the connector definition this connection uses; null for project-level/draft connections"
+    },
+    "sync_entity": {
+      "type": ["string", "null"],
+      "pattern": "^[a-z0-9-_]+$",
+      "description": "For API poll connectors: which entity (e.g. orders, customers) this connection syncs. Must match connector supported_entities when present."
+    },
+    "key": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "pattern": "^[a-z0-9-_]+$",
+      "description": "Unique key for the connection within the organization"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255,
+      "description": "Display name for the connection"
+    },
+    "description": {
+      "type": ["string", "null"],
+      "maxLength": 1000,
+      "description": "Connection description"
+    },
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Connection type: database, api, webhook, file, or connector type (e.g. spotify, shopify)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "inactive", "error"],
+      "description": "Connection status"
+    },
+    "credential_fields": {
+      "type": "object",
+      "description": "Encrypted credential fields for the connection (structure depends on connector auth_type)",
+      "properties": {
+        "api_key": {
+          "type": ["string", "null"],
+          "description": "API key (encrypted)"
+        },
+        "api_secret": {
+          "type": ["string", "null"],
+          "description": "API secret (encrypted)"
+        },
+        "oauth_access_token": {
+          "type": ["string", "null"],
+          "description": "OAuth access token (encrypted)"
+        },
+        "oauth_refresh_token": {
+          "type": ["string", "null"],
+          "description": "OAuth refresh token (encrypted)"
+        },
+        "oauth_expires_at": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "OAuth token expiration time"
+        },
+        "username": {
+          "type": ["string", "null"],
+          "description": "Username for basic auth (encrypted)"
+        },
+        "password": {
+          "type": ["string", "null"],
+          "description": "Password for basic auth (encrypted)"
+        },
+        "bearer_token": {
+          "type": ["string", "null"],
+          "description": "Bearer token (encrypted)"
+        },
+        "custom_credentials": {
+          "type": ["object", "null"],
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Custom credential fields (encrypted)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "credential_parameter_store_refs": {
+      "type": "object",
+      "description": "SSM Parameter Store paths for OAuth/credentials (keyed by credential name)",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "configuration": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Connection configuration (non-sensitive settings)"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Additional metadata for the connection"
+    },
+    "verified": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the connection has been verified/tested"
+    },
+    "draft": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether this connection is still in draft state"
+    },
+    "last_tested": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when connection was last tested"
+    },
+    "created_by": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "User ID who created the connection"
+    },
+    "updated_by": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "User ID who last updated the connection"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when connection was created"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when connection was last updated"
+    },
+    "deleted_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when connection was deleted (soft delete)"
+    },
+    "ingestion_config": {
+      "type": ["object", "null"],
+      "description": "Structured ingestion settings (schedule, batch, polling). Extensible per connection type.",
+      "properties": {
+        "schedule": {
+          "type": ["string", "null"],
+          "description": "Cron expression (LeoCron `time`) or platform-supported schedule string for this connection's registered bot. Distinct from `polling_interval_ms`, which is a millisecond gap for application-level throttling between requests—not the Leo schedule field."
+        },
+        "runtime_memory_mb": {
+          "description": "Shared runtimes tier for trigger registration (256–2048). Defaults to 256 when unset. LeoCron `lambdaName`: `w-{org4}-{inst4}-bot-connectors-{mb}-rtime`; bot id: `w-{org4}-{inst4}-{workflow4}-bot-connectors-{mb}-{container_id}`. Instance `connection_details.runtimes_stack_identifier` may override the org/instance middle segment (CDK `microserviceIdentifier` = `w-{that middle}`).",
+          "oneOf": [
+            { "type": "null" },
+            { "type": "integer", "enum": [256, 512, 1024, 2048] }
+          ]
+        },
+        "fetch_action_key": {
+          "type": ["string", "null"],
+          "description": "Declarative connector package action key used for polling fetches (e.g. shopify_get_orders). Often matches sync_plan entity fetch_action_key."
+        },
+        "batch_size": {
+          "type": ["integer", "null"],
+          "description": "Batch size for polling (default 100)"
+        },
+        "polling_interval_ms": {
+          "type": ["integer", "null"],
+          "description": "Polling interval in milliseconds"
+        },
+        "max_retries": {
+          "type": ["integer", "null"],
+          "description": "Max retries on failure"
+        },
+        "timeout_ms": {
+          "type": ["integer", "null"],
+          "description": "Request/timeout in milliseconds"
+        }
+      },
+      "additionalProperties": true
+    },
+    "runtime_status": {
+      "type": ["string", "null"],
+      "enum": ["not_deployed", "deploying", "running", "paused", "error", null],
+      "description": "Deployment state of the connection's bot (written at deploy time)"
+    },
+    "auth_type": {
+      "type": ["string", "null"],
+      "enum": [
+        "oauth2",
+        "api_key",
+        "webhook",
+        "data_product_rbac",
+        "none",
+        null
+      ],
+      "description": "Authentication type for the connection (optional, backwards compat)."
+    },
+    "ingestion_type": {
+      "type": ["string", "null"],
+      "enum": [
+        "polling",
+        "webhook",
+        "data_product",
+        "database_cdc",
+        "file",
+        "api_sdk",
+        "stream",
+        "other",
+        null
+      ],
+      "description": "How data is ingested (optional)."
+    },
+    "export_type": {
+      "type": ["string", "null"],
+      "enum": ["file", "database", "stream", "api_sdk", "other", null],
+      "description": "How data is exported (optional)."
+    },
+    "source_schema": {
+      "type": ["object", "null"],
+      "description": "Source schema reference (optional)."
+    },
+    "destination_schema": {
+      "type": ["object", "null"],
+      "description": "Destination schema reference (optional)."
+    },
+    "retry_policy": {
+      "type": ["object", "null"],
+      "description": "Retry policy (max_retries, backoff, etc.).",
+      "properties": {
+        "max_retries": { "type": ["integer", "null"] },
+        "backoff_ms": { "type": ["integer", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "timeout": {
+      "type": ["integer", "null"],
+      "description": "Timeout in milliseconds (optional)."
+    },
+    "concurrency": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "Concurrency limit (optional)."
+    },
+    "batch_size": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "Batch size for sync (optional)."
+    },
+    "connector_mode": {
+      "type": ["string", "null"],
+      "enum": ["inbound", "outbound", "bidirectional", null],
+      "description": "For enrichment workflows: mid-flow connection must be 'bidirectional'. For ingestion head use 'inbound'; for consumption tail use 'outbound'. Must match connector supported_directions."
+    }
+  },
+  "upstream_entity_id": {
+    "type": ["string", "null"],
+    "format": "uuid",
+    "description": "Upstream entity in the flow graph (e.g. data-product in consumption flows). Null for source connections."
+  },
+  "upstream_entity_type": {
+    "type": ["string", "null"],
+    "enum": [
+      "connections",
+      "transformations",
+      "validations",
+      "data-products",
+      null
+    ],
+    "description": "Entity type of the upstream entity."
+  },
+  "additionalProperties": false
+}