Loxtep Node.js SDK

Client for the Loxtep API. LoxtepClient groups platform APIs under namespaced areas on the client:

| Area | SDK namespace | Examples | | --- | --- | --- | | Authentication | client.session | get_current_user() | | Connect | client.connect | .connectors.*, .templates.* | | Workspace | client.workspace | .projects.*, .instances.* | | Build & deploy | client.build | .workflows.*, .triggers.*, .data_products.*, .targets.* | | Governance | client.define | .schemas.*, .shapes.*, .quality.*, .domains.*, … | | Semantics | client.meaning | .thesaurus.*, .ontology.*, .packs.*, .semantic.*, .proposals.*, .bundles.* | | Review | client.review | .approvals.*, .improvements.* | | Analytics | client.query | .catalog.*, .discovery.*, .query() | | Observe | client.observe | .stream_config(), .open_reader() | | Context | client.context | .procedures.*, .issues.*, .goals.*, .workstreams.*, … |

Stream I/O uses top-level helpers on the client: await client.get_writer('data-product-name') and await client.get_reader('data-product-name') — but only after that data product is deployed on your attached instance.

Node.js 22+ is the supported runtime (engines in package.json). Live queue/flow writes use the Loxtep stream data plane; configure stream bus resources (streams on LoxtepClient and instance env from your stack) and AWS credentials for SigV4 on both REST and the bus.

Ways to get started

| Path | Use case | Entry point | |------|----------|-------------| | Code-first CLI | New project on Loxtep — scaffold, attach, author, deploy | loxtep init → attach → generate → test → deploy | | Programmatic | App code that reads/writes events or calls APIs | LoxtepClient.fromWorkspace() after login + attach | | Agent-first (MCP) | Conversational setup from your IDE | loxtep-plugins-skills | | Web UI | Visual project and workflow management | app.loxtep.io |

All paths: Loxtep Quickstart.

Quick start — First run (recommended)

Run these in an empty directory you want to turn into a Loxtep workspace.

1. Install

   pnpm add @loxtep/sdk

2. Log in and confirm identity

   pnpm exec loxtep login
   pnpm exec loxtep whoami

   Tokens are saved to ./.loxtep/credentials.json by default (use --global for ~/.loxtep/credentials.json).

   CI/headless: pnpm exec loxtep login --email [email protected] --password … or set LOXTEP_AUTH_TOKEN.

Login from code (library)

Use these when your app mints tokens itself (not the CLI). Library login uses the sdk_node session channel — separate from CLI, web, Python SDK, and MCP.

import { login, browserLogin, LoxtepClient } from '@loxtep/sdk';

const apiUrl = 'https://api.loxtep.io'; // or apidev.loxtep.io

// Email / password (optional mfa_code). Defaults to client_channel: 'sdk_node'.
const tokens = await login(apiUrl, '[email protected]', 'secret', {
  // mfa_code: '123456',
});

// Or browser handoff → /auth/sdk?runtime=node (also sdk_node).
// const tokens = await browserLogin({ app_url: 'https://app.loxtep.io' });

const client = new LoxtepClient({
  api_url: apiUrl,
  auth: { type: 'jwt', token: tokens.access_token },
});

Refresh with refresh(apiUrl, tokens.refresh_token). Prefer loxtep login + LoxtepClient.fromWorkspace() when you want credentials on disk for the CLI.

3. Scaffold the workspace

   pnpm exec loxtep init
   # optional: pnpm exec loxtep init --template shopify-orders

   Creates .loxtep/project.json, workflows/, connectors/, domains/, and data-products/.

4. Attach to a runtime instance

   pnpm exec loxtep instances list
   pnpm exec loxtep attach --instance <instance-id>
   pnpm exec loxtep instances stream-config   # optional: Leo/S3/Kinesis names

   Writes instance_id and api_url into .loxtep/project.json. Required before generate, test, and deploy. Bus physical names are CLI/REST (instances stream-config or client.workspace.instances.get_stream_config); MCP list_instances / get_sdk_config do not return them.

5. Generate typed workspace constants

   pnpm exec loxtep generate

   Emits .loxtep/generated/index.ts from live platform metadata.

6. See what's on the instance

   pnpm exec loxtep config list           # project_id from init
   pnpm exec loxtep data-products list
   pnpm exec loxtep workflows list        # uses project_id from .loxtep/project.json

   Not in a scaffolded folder? Run pnpm exec loxtep projects list first, then workflows list --project-id <uuid>.

7. Create a data product and write from your app

   pnpm exec loxtep ingest provision --name app-events
   pnpm exec loxtep lint
   pnpm exec loxtep deploy
   pnpm exec loxtep data-products list

   Then use get_writer in your application — see Write to a data product.

8. Author code-first workflow modules (optional, different path)

   pnpm exec loxtep test <module> --event ./events/sample.json
   pnpm exec loxtep deploy

   See Code-first CLI guide.

Bootstrap the SDK from your workspace

After steps 1–4 above, application code can use auto-config — no hand-built client options:

import { LoxtepClient } from '@loxtep/sdk';

const client = await LoxtepClient.fromWorkspace();
const { user, organization } = await client.session.get_current_user();
console.log(user.email, organization?.name);

Write and read events

After you create a data product on your attached instance:

const client = await LoxtepClient.fromWorkspace();

const writer = await client.get_writer('app-events');
writer.write({ hello: 'world' });
await writer.close();

const reader = await client.get_reader('app-events');
for await (const event of reader) {
  console.log(event);
  break;
}

See Write to a data product.

Quick start — Code-first workflow module

After init, attach, and generate, import typed constants in workflow modules:

import { defineDataWorkflow, on } from '@loxtep/sdk';
import { workspace } from './.loxtep/generated';

export default defineDataWorkflow({
  name: 'orders-enricher',
  triggers: [on.webhook('/orders')],
  async handler(_ctx, event) {
    console.log('received', event);
  },
});

See loxtep init --help, loxtep attach --help, etc. CLI reference below.

API surface

Every method is snake_case. APIs live on namespaced areas of LoxtepClient (see table at the top). Nested APIs use descriptive names (workflows, data_products, connectors, …) under each area.

Top-level stream I/O (preferred)

• get_writer(name_or_id) — write path; resolves queue, bot, stream config
• get_reader(name_or_id) — async iterable read path
• LoxtepClient.fromWorkspace() — construct from .loxtep/project.json + ./.loxtep/credentials.json (env overrides: LOXTEP_API_URL, LOXTEP_TOKEN, …)

Build & deploy (client.build)

• .workflows — list, get, create, get_graph, deploy; low-level .get_writer(workflow_id, { bot_id, … }) escape hatch
• .triggers — get, list, create, update, delete, test, reset_backfill
  • Naming note: an SDK Trigger (dist/client/trigger-types.d.ts) is the platform connection entity (connection_id, workflows/<id>/connections/*.json), validated by schemas/entity-json-schemas/connection.json. It is not the workflow's trigger property (event / schedule / connector / query_trigger), which is part of workflow.json. There is no separate trigger entity schema.
• .data_products — CRUD, stream, replay, get_queue_info, invalidate_cache, … (for writes/reads by name, prefer top-level client.get_writer / get_reader)
• .targets — delivery sink bindings (list, get, create, update, delete)

Connect (client.connect)

• .connectors — org-level connector credentials
• .templates — starter templates (list, get, apply_template on projects)

Workspace (client.workspace)

• .projects — list, get, create, update, delete, apply_template
• .instances — list, get, stream config helpers

Governance (client.define)

• .schemas (data-product), .shapes (domain canonical), .quality, .standards, .data_contracts, .domains

Analytics (client.query)

• .catalog, .discovery, .query(), .list_tables(), .search()

Observe (client.observe)

• status(), stream_config(), open_reader(), open_writer(), get_queue_metadata(), get_reader_checkpoint()

Authentication, semantics, review, and context

• client.session — get_current_user, get_current_organization, logout
• client.meaning — .thesaurus.*, .ontology.*, .packs.*, .semantic.*, .proposals.*, .bundles.import
• client.review — .approvals.*, .improvements.*
• client.context — .procedures.*, .activity.*, .process_intelligence.*, .issues.*, .goals.*, .workstreams.*
• client.metrics — log, get_reporter (stub until metrics wiring lands)

Data product writer and reader

await client.get_writer('name') resolves the data product's queue, bot identity, and stream bus config automatically, then returns a FlowWriter:

const writer = await client.get_writer('shopify_gql_customer');
writer.write({ customer_id: '123', name: 'Alice', email: '[email protected]' });
await writer.close();

await client.get_reader('name') returns an async iterable over the data product's queue:

const reader = await client.get_reader('shopify_gql_customer');
for await (const event of reader) {
  console.log(event);
}

Options:

• Writer: { bot_id?, batch_size?, max_retries? }
• Reader: { bot_id?, from?, batch_size? }

Cache: call client.build.data_products.invalidate_cache('name') to force re-resolution on the next call.

Stream helpers

Use mapStream and filterStream with client.build.data_products.stream(), client.build.data_products.replay(), or client.observe.open_reader().read():

import { mapStream, filterStream } from '@loxtep/sdk';

for await (const event of mapStream(reader.read(), e => e.payload)) {
  console.log(event);
}
for await (const event of filterStream(
  reader.read(),
  e => e.event_id !== 'skip'
)) {
  console.log(event);
}

Targets (delivery)

Configure how a data product delivers data to external systems.

import { LoxtepClient } from '@loxtep/sdk';
import type { Target, TargetCreateInput } from '@loxtep/sdk';

const client = new LoxtepClient({
  api_url: 'https://api.loxtep.com',
  auth: { type: 'jwt', token: process.env.LOXTEP_AUTH_TOKEN! },
});

// List targets for a data product
const { items, pagination } = await client.build.targets.list('dp_abc123');

// Create a webhook target
const webhook = await client.build.targets.create('dp_abc123', {
  targetType: 'webhook',
  name: 'Order notifications',
  endpoint_url: 'https://example.com/webhooks/orders',
  method: 'POST',
});

// Update a target
await client.build.targets.update('dp_abc123', webhook.consumption_id, {
  is_active: false,
});

// Delete a target
await client.build.targets.delete('dp_abc123', webhook.consumption_id);

Documentation

• Getting started – Login, init, attach, generate — then stream I/O after deploy.
• Code-first CLI – loxtep init, attach, generate, test, deploy.
• Quick reference – Single-page cheat sheet.
• Event replay cookbook – Replay events from a data product or queue.
• Data plane CLI – Iceberg rebuild and inspection, SQL receipts, read-only export.
• SDK + agent pairing – When to use the SDK vs IDE agent integrations.
• Typed errors – import { … } from '@loxtep/sdk/errors'.
• API reference – pnpm run docs (Typedoc).

CLI reference

| Command | Description | | ---------------------------------------------------- | ------------------------------------------------------------------ | | login | Log in via browser OAuth (default) or email/password | | login --browser | Explicitly use browser OAuth flow | | login --email <e> --password <p> | Headless login for CI (optional --mfa-code) | | logout | Remove stored credentials | | whoami | Print current user and organization | | init [--template <slug>] | Scaffold project structure, AGENTS.md, and default skill | | init --create-repo [name] | Scaffold + create a new GitHub repo (private default) | | init --from-repo <url> | Scaffold + import from an existing repo | | attach --instance <name-or-id> | Bind project to a runtime instance | | status [--json] | Cwd-first workspace status (local/cloud/deployed; not observe) | | connectors list [--type] | List org connectors (filter e.g. --type sdk) | | ingest provision [--name] | Write local SDK ingest package (reuse/create connector; no deploy) | | lint [--workflow] | Validate local entity JSON (schemas + relationships) | | deploy [--dry-run] | Lint preflight, then compile/deploy (or lint-only with --dry-run)| | generate | Codegen typed workspace constants to .loxtep/generated/index.ts | | test <module> --event <file> | Run a workflow module locally with sample event(s) | | deploy | Compile modules, validate resources, deploy to workflow engine | | config list | Show api_url, organization_id, project_id, instance_id | | projects list | projects get <id> | projects link | projects clone [dir] | projects pull | projects push | List/get/link/clone; GH sync when bound; unbound Local→Cloud remains loxtep push | | config paths | Show resolved URLs for auth and SDK path matrix | | config set <key> <value> | Set api_url | organization_id | project_id | instance_id | | config export --from-data-product <id> | Print shell exports / JSON for SDK bootstrap | | config export --from-connector <id> | Print env exports from SDK connector | | bus login | Explain bus vs JWT (placeholder for future session API) | | data-products list | List data products | | data-products get <id> | Get data product by id | | data-products create --name … --domain-id … | Create data product | | data-products query <id> <SQL> | Run SQL in data product context (or --file query.sql) | | data-products tables <id> | List tables for data product | | workflows list [--project-id <id>] | List workflows (project_id required or from config) | | workflows get <id> | Get workflow by id (with nodes) | | workflows create --name <n> --project-id <id> | Create workflow (optional: --template-id, --description) | | workflows deploy --project-id <id> | Deploy workflow (optional: --instance-id, --version-id) | | triggers list | List triggers (ingest source bindings) | | triggers get <id> | Get trigger by id | | triggers create --name <n> --type <t> --key <k> | Create trigger | | triggers test <id> | Test trigger | | triggers reset-backfill <connection_id> | Clear one paused MongoDB backfill checkpoint | | observe status | Show observability status (bots) | | queue info <data-product-id> | Queue info by data product id | | queue info --queue <name> | Queue info by queue name | | queue checkpoint <id> --bot <bot-id> | Reader checkpoint for data product and bot | | domains list | domains get <id> | List or get domain | | standards list | standards get <id> | List or get standard (policy) | | data-contracts list | data-contracts get <id> | List or get data contract | | metrics rate-limits | Show rate limit info | | metrics log --id <id> --value <n> | Log metric (optional --tags k=v,...) |

Examples:

loxtep login
loxtep whoami
loxtep data-products list
loxtep projects list
loxtep workflows list
loxtep workflows get <workflow-id>
loxtep workflows deploy --project-id <id> --instance-id <id>
loxtep config export --from-connector <connector-id> --format json
loxtep queue info <data-product-id>
loxtep data-products query <data-product-id> "SELECT * FROM t LIMIT 10"
loxtep metrics rate-limits

Module exports

The SDK re-exports configuration, authentication, codegen, skill scoping, workflow authoring, HTTP, checkpoint, and streaming helpers from the main entry point. @loxtep/sdk/errors is the only additional published subpath (see package.json exports).

import {
  LoxtepClient,
  loadConfig,
  login,
  defineDataWorkflow,
  on,
  checkScope,
  signRequest,
  createMemoryCheckpointStore,
  DataProductResolver,
} from '@loxtep/sdk';

import { ValidationError, parseHttpError } from '@loxtep/sdk/errors';

Selected exports (import from @loxtep/sdk unless noted)

Config: loadConfig, loadConfigSync, saveConfig, parseStreamsPartial, getConfigDir, getDefaultConfigPath, buildAuthServiceUrl, buildPlatformRequestUrl, resolveAutoConfig

Auth: decodeJwtPayload, login, refresh, browserLogin, TokenManager, LoginMfaRequiredError

Codegen: loadWorkspaceContext, deriveKey, normalizeContext, emitArtifact, writeArtifact, computeCounts

Skills: checkScope, checkScopeByName, parseSkillYaml, loadSkillFromFile, loadSkillsFromDirectory, validateSkillReferences, formatSkillValidationErrors, SkillDefinitionSchema

Authoring: defineDataWorkflow, on, createToolbox, agent, validateAgentOptions, compileModule, ActionTrace, AgentScopeError, ToolboxOperationError

HTTP: signRequest, LoxtepHttpClient

Checkpoint: createMemoryCheckpointStore

Streaming: mapStream, filterStream

Errors (from @loxtep/sdk/errors): AuthorizationError, ConflictError, ValidationError, DefinitionValidationError, SchemaValidationError, CheckpointError, parseHttpError

Resolver: DataProductResolver, AmbiguityError — used internally by get_writer / get_reader; import when building custom resolution logic.