@loxtep/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `@loxtep/sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Initial SDK release
+- `LoxtepClient` with JWT and SigV4 authentication
+- Data products API (list, get, search, query, stream, replay)
+- Flows API (list, get, create, get_writer)
+- Connections API (list, get, create, test)
+- Queues API (metadata, checkpoints, open_reader, open_writer)
+- Quality API (list, get)
+- Catalog and Discovery APIs
+- Schemas, Projects, Domains, Standards, Data Contracts APIs
+- Process Intelligence API (entity context, decision traces)
+- Observe API (status, stream_config)
+- FlowWriter with transparent batching
+- QueueReader with async iteration
+- Stream helpers (`mapStream`, `filterStream`)
+- CLI (`loxtep`) with login, config, data-products, flows, connections, queues
+  commands
+- Typed errors (`@loxtep/sdk/errors`)
+- Generated API types from Zod schemas

package/README.md

@@ -0,0 +1,274 @@
+# Loxtep Node.js SDK
+
+Client for the Loxtep API. Customer-facing surface: **data_products**,
+**flows**, **connections**, **queues**, **quality**, **catalog**, **discovery**,
+**schemas**, **projects**, **domains**, **standards**, **data_contracts**.
+
+**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.
+
+## Quick start (< 5 min to first stream)
+
+1. **Install**
+
+   ```bash
+   npm install @loxtep/sdk
+   ```
+
+2. **Configure and log in**
+
+   ```bash
+   npx loxtep config set api_url https://api.loxtep.com
+   npx loxtep login
+   ```
+
+   Tokens resolve in this order: **`LOXTEP_AUTH_TOKEN`** →
+   **`~/.loxtep/credentials.json`** (shared with
+   `npx @loxtep/customer-mcp-server login`).
+
+3. **Create a client, write and read events**
+
+   ```ts
+   import { LoxtepClient } from '@loxtep/sdk';
+
+   const client = new LoxtepClient({
+     api_url: 'https://api.loxtep.com',
+     auth: { type: 'jwt', token: process.env.LOXTEP_TOKEN },
+   });
+
+   // Write events to a data product
+   const writer = await client.data_products.get_writer('shopify_gql_customer');
+   writer.write({
+     customer_id: '123',
+     name: 'Alice',
+     email: 'alice@example.com',
+   });
+   await writer.close();
+
+   // Read events from a data product
+   const reader = await client.data_products.get_reader('shopify_gql_customer');
+   for await (const event of reader) {
+     console.log(event);
+   }
+   ```
+
+   That's it. The SDK resolves the data product's queue, bot identity, and
+   stream bus configuration automatically from the deployment metadata. No
+   manual queue names, no stream config, no bot IDs.
+
+4. **Lower-level escape hatch** — if you need explicit control over bot_id,
+   queue name, or stream bus resources, use `flows.get_writer` directly:
+
+   ```ts
+   const writer = client.flows.get_writer('your-flow-id', {
+     bot_id: 'your-bot-id',
+     output_queue_name: 'your-ingest-queue',
+   });
+   writer.write({ id: 'e1', payload: { name: 'Alice' } });
+   await writer.close();
+   ```
+
+5. **Stream config from the platform (optional)** — after login,
+   `await client.observe.stream_config()` returns Leo/RStreams resource names
+   via **`GET /observe/stream-config`** (Observe proxy + `instances:read`).
+   Merge into `new LoxtepClient({ ...opts, streams: { ...partial } })` with your
+   JWT-backed client. Note: `data_products.get_writer` and `get_reader` resolve
+   stream config automatically — this is only needed for manual bus access.
+
+## Quick start: "Tell me everything about this order"
+
+Process Intelligence returns unified context from all connected systems
+(Shopify, Stripe, Gorgias, etc.) for a given entity:
+
+```ts
+import { LoxtepClient } from '@loxtep/sdk';
+
+const client = new LoxtepClient({
+  api_url: 'https://api.loxtep.com',
+  auth: { type: 'jwt', token: process.env.LOXTEP_AUTH_TOKEN! },
+  organization_id: process.env.LOXTEP_ORGANIZATION_ID,
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? 'cli',
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? 'cli',
+  },
+});
+
+// Tell me everything about order #4821
+const context = await client.process_intelligence.getEntityContext(
+  client.organization_id!,
+  { entity_type: 'order', entity_id: '4821' }
+);
+console.log(context); // Shopify order + Stripe payments + support tickets, etc.
+```
+
+See
+[Process Intelligence API Guide](../../docs/api/process-intelligence-guide.md)
+for full API and MCP tool reference.
+
+## API surface
+
+- **data_products** – get, list, search, query, list_tables, create, stream,
+  replay, **get_writer**, **get_reader**, invalidate_cache
+- **flows** – list, get, create, get_writer
+- **connections** – list, get, create, test
+- **queues** – get_queue_metadata, get_reader_checkpoint, open_reader,
+  open_writer
+- **quality** – list, get
+- **catalog** – search
+- **discovery** – search (access-filtered catalog search with optional
+  evidence/lineage), getEvidence, getLineageImpact, getGovernanceFlags,
+  runDiscovery (all call `POST /ai/mcp/tools/call`; results are access-filtered
+  when user context is present)
+- **schemas** – get (data product schema)
+- **observe** – `status`, **`stream_config`** (proxied bus resource names for
+  SDK `streams`)
+- **projects**, **domains**, **standards**, **data_contracts** – list, get (full
+  CRUD where applicable)
+
+## Data product writer and reader
+
+`await client.data_products.get_writer('name')` resolves the data product's
+queue, bot identity, and stream bus config automatically, then returns a
+**FlowWriter**:
+
+```ts
+const writer = await client.data_products.get_writer('shopify_gql_customer');
+writer.write({ customer_id: '123', name: 'Alice', email: 'alice@example.com' });
+await writer.close();
+```
+
+`await client.data_products.get_reader('name')` returns an async iterable over
+the data product's queue:
+
+```ts
+const reader = await client.data_products.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.data_products.invalidate_cache('name')` to force
+re-resolution on the next call.
+
+## Flow writer (lower-level escape hatch)
+
+`client.flows.get_writer(flow_id)` returns a **FlowWriter** with:
+
+- **`write(event)`** – enqueues an event. Batching is transparent: you do not
+  control batch size or flush timing.
+- **`close()`** – flushes any buffered events and guarantees delivery (or
+  attempts to). Always call `close()` when done writing.
+
+Example:
+
+```ts
+const writer = client.flows.get_writer(flowId, { bot_id: 'your-bot-id' });
+writer.write({ id: 'e1', payload: { name: 'Alice' } });
+writer.write({ id: 'e2', payload: { name: 'Bob' } });
+await writer.close();
+```
+
+Buffered events flush on `close()` via stream **`putEvents`** to the resolved
+output queue (see `docs/sdk-control-vs-data-plane.md`).
+
+## Stream helpers
+
+Use `mapStream` and `filterStream` with `data_products.stream()`,
+`data_products.replay()`, or `queues.open_reader().read()`:
+
+```ts
+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);
+}
+```
+
+## Generated API types
+
+Types for API request/response shapes (data_product, workflow, connection, etc.)
+are generated from Zod schemas and exported from `@loxtep/sdk`:
+
+```ts
+import type { DataProductApi, FlowApi, ConnectionApi } from '@loxtep/sdk';
+```
+
+Regenerate after changing `scripts/api-schemas.ts`:
+
+```bash
+pnpm run generate:api-types
+```
+
+## Documentation
+
+- **[Event replay cookbook](docs/event-replay-cookbook.md)** – Replay events
+  from a data product or queue (key differentiator).
+- **[MCP + SDK pairing](docs/sdk-pairing.md)** – one auth story, when MCP vs
+  SDK.
+- **[Control vs data plane](docs/sdk-control-vs-data-plane.md)** – REST vs
+  Loxtep streams.
+- **[REST SigV4 vs bus](docs/sdk-rest-vs-bus.md)** – never mix secrets.
+- **[MCP → SDK mapping](docs/sdk-mcp-mapping.md)** – agent-oriented table.
+- **[Bus RBAC threat model](docs/sdk-bus-rbac-threat-model.md)** – issuance
+  direction.
+- **Typed errors** – `import { … } from '@loxtep/sdk/errors'`.
+- **API reference** – `npm run docs` (Typedoc).
+
+## CLI reference
+
+| Command                                              | Description                                                 |
+| ---------------------------------------------------- | ----------------------------------------------------------- |
+| `login`                                              | Log in with email/password (prompts if not provided)        |
+| `logout`                                             | Remove stored credentials                                   |
+| `whoami`                                             | Print current user and organization                         |
+| `init`                                               | Setup checklist + doc pointers                              |
+| `config list`                                        | Show api_url, organization_id, project_id, instance_id      |
+| `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                |
+| `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                                |
+| `flows list [--project-id <id>]`                     | List flows (project_id required or from config)             |
+| `flows get <id>`                                     | Get flow by id (with nodes)                                 |
+| `flows create --name <n> --project-id <id>`          | Create flow (optional: `--template-id`, `--description`)    |
+| `connections list`                                   | List connections                                            |
+| `connections get <id>`                               | Get connection by id                                        |
+| `connections create --name <n> --type <t> --key <k>` | Create connection                                           |
+| `connections test <id>`                              | Test connection                                             |
+| `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:
+
+```bash
+loxtep login
+loxtep whoami
+loxtep data-products list
+loxtep flows list --project-id <project-id>
+loxtep flows get <flow-id>
+loxtep queue info <data-product-id>
+loxtep data-products query <data-product-id> "SELECT * FROM t LIMIT 10"
+loxtep metrics rate-limits
+```

package/dist/auth/index.d.ts

@@ -0,0 +1,6 @@
+export { decodeJwtPayload, DEFAULT_REFRESH_THRESHOLD_SECONDS } from './jwt.js';
+export { TokenManager } from './token-manager.js';
+export type { TokenState } from './token-manager.js';
+export { login, refresh, LoginMfaRequiredError } from './login.js';
+export type { AwsCredentialsSnake, LoginResponse, RefreshResponse } from './login.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,iCAAiC,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,4 @@
+export { decodeJwtPayload, DEFAULT_REFRESH_THRESHOLD_SECONDS } from './jwt.js';
+export { TokenManager } from './token-manager.js';
+export { login, refresh, LoginMfaRequiredError } from './login.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,iCAAiC,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Decode JWT payload to read exp (expiry) without verification.
+ * Used client-side only for refresh threshold; do not use for security decisions.
+ */
+export declare function decodeJwtPayload(token: string): {
+    exp?: number;
+};
+/** Default refresh threshold: refresh when less than 5 minutes until expiry. */
+export declare const DEFAULT_REFRESH_THRESHOLD_SECONDS = 300;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAehE;AAED,gFAAgF;AAChF,eAAO,MAAM,iCAAiC,MAAM,CAAC"}

package/dist/auth/jwt.js

@@ -0,0 +1,24 @@
+/**
+ * Decode JWT payload to read exp (expiry) without verification.
+ * Used client-side only for refresh threshold; do not use for security decisions.
+ */
+export function decodeJwtPayload(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return {};
+        const payload = parts[1];
+        if (!payload)
+            return {};
+        const decoded = Buffer.from(payload.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8');
+        const parsed = JSON.parse(decoded);
+        const exp = typeof parsed.exp === 'number' ? parsed.exp : undefined;
+        return { exp };
+    }
+    catch {
+        return {};
+    }
+}
+/** Default refresh threshold: refresh when less than 5 minutes until expiry. */
+export const DEFAULT_REFRESH_THRESHOLD_SECONDS = 300;
+//# sourceMappingURL=jwt.js.map

package/dist/auth/jwt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAC3F,OAAO,CACR,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;QAC9D,MAAM,GAAG,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACpE,OAAO,EAAE,GAAG,EAAE,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,iCAAiC,GAAG,GAAG,CAAC"}

package/dist/auth/login.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Login and refresh using platform auth endpoints.
+ * POST .../{app}/auth/login and POST .../{app}/auth/refresh (first segment = app microservice by default). No token on disk.
+ */
+/** Thrown when POST /auth/login returns 403 and the user must supply TOTP (same as the web app for MFA). */
+export declare class LoginMfaRequiredError extends Error {
+    readonly name = "LoginMfaRequiredError";
+    constructor();
+}
+/** Same snake_case shape as platform login/refresh JSON. */
+export type AwsCredentialsSnake = {
+    access_key_id: string;
+    secret_access_key: string;
+    session_token: string;
+    expiration: string;
+};
+export interface LoginResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    expires_at: string;
+    aws_credentials?: AwsCredentialsSnake;
+}
+export interface RefreshResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    expires_at: string;
+    aws_credentials?: AwsCredentialsSnake;
+}
+/**
+ * Login with email/password. POST `{apiUrl}/{auth_path}/auth/login` (default `auth_path` = `app`).
+ * Returns tokens; caller should set them in TokenManager (no disk).
+ */
+export declare function login(apiUrl: string, email: string, password: string, options?: {
+    organization_id?: string;
+    mfa_code?: string;
+    /** Omitted: default `app`. Set to `""` to omit (if `api_url` already includes `/app`). */
+    auth_path_prefix?: string;
+    fetchFn?: typeof fetch;
+}): Promise<LoginResponse>;
+/**
+ * Refresh access token. POST `{apiUrl}/{auth_path}/auth/refresh` (default path segment: `app`).
+ */
+export declare function refresh(apiUrl: string, refreshToken: string, options?: {
+    auth_path_prefix?: string;
+    fetchFn?: typeof fetch;
+}): Promise<RefreshResponse>;
+//# sourceMappingURL=login.d.ts.map

package/dist/auth/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/auth/login.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,4GAA4G;AAC5G,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAkB,IAAI,2BAA2B;;CAIlD;AAED,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAiED;;;GAGG;AACH,wBAAsB,KAAK,CACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,GACA,OAAO,CAAC,aAAa,CAAC,CAgDxB;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GAC9D,OAAO,CAAC,eAAe,CAAC,CA4C1B"}

package/dist/auth/login.js

@@ -0,0 +1,131 @@
+import { buildAuthServiceUrl } from '../config/api-path.js';
+/**
+ * Login and refresh using platform auth endpoints.
+ * POST .../{app}/auth/login and POST .../{app}/auth/refresh (first segment = app microservice by default). No token on disk.
+ */
+/** Thrown when POST /auth/login returns 403 and the user must supply TOTP (same as the web app for MFA). */
+export class LoginMfaRequiredError extends Error {
+    name = 'LoginMfaRequiredError';
+    constructor() {
+        super('MFA code required');
+    }
+}
+const DEFAULT_FETCH = typeof fetch !== 'undefined' ? fetch : undefined;
+/** Undici/Node `fetch` throws `TypeError: fetch failed` with no URL; rethrow with `POST {url}` and `error.cause`. */
+function rethrowNetworkError(method, url, err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    const cause = e.cause;
+    const causeMsg = cause instanceof Error
+        ? cause.message
+        : cause !== undefined && cause !== null
+            ? String(cause)
+            : '';
+    const tail = [e.message, causeMsg].filter(s => s.length > 0).join(' — ');
+    throw new Error(`${method} ${url} failed${tail ? `: ${tail}` : ''}`);
+}
+async function doFetch(method, url, init, fetchFn) {
+    try {
+        return await fetchFn(url, init);
+    }
+    catch (e) {
+        rethrowNetworkError(method, url, e);
+    }
+}
+function isMfaRequiredResponse(status, json) {
+    if (status !== 403)
+        return false;
+    if (json.mfaRequired === true)
+        return true;
+    const e = json.error;
+    if (e && typeof e === 'object') {
+        if (e.details?.mfaRequired === true)
+            return true;
+        if (e.context?.mfaRequired === true)
+            return true;
+        if (typeof e.message === 'string' && /\bmfa\b/i.test(e.message))
+            return true;
+    }
+    if (typeof e === 'string' && /\bmfa\b/i.test(e))
+        return true;
+    return false;
+}
+function getLoginErrorMessage(json, res) {
+    const e = json.error;
+    if (typeof e === 'string' && e.trim())
+        return e;
+    if (e && typeof e === 'object' && typeof e.message === 'string' && e.message.trim()) {
+        return e.message;
+    }
+    return res.statusText;
+}
+/**
+ * Login with email/password. POST `{apiUrl}/{auth_path}/auth/login` (default `auth_path` = `app`).
+ * Returns tokens; caller should set them in TokenManager (no disk).
+ */
+export async function login(apiUrl, email, password, options) {
+    const base = apiUrl.replace(/\/$/, '');
+    const url = buildAuthServiceUrl(base, options?.auth_path_prefix, '/auth/login');
+    const body = {
+        email,
+        password,
+        ...(options?.organization_id && { organization_id: options.organization_id }),
+        ...(options?.mfa_code && { mfa_code: options.mfa_code }),
+    };
+    const fetchFn = options?.fetchFn ?? DEFAULT_FETCH;
+    if (!fetchFn)
+        throw new Error('fetch not available');
+    const res = await doFetch('POST', url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    }, fetchFn);
+    const json = (await res.json());
+    if (!res.ok) {
+        if (isMfaRequiredResponse(res.status, json)) {
+            throw new LoginMfaRequiredError();
+        }
+        const msg = getLoginErrorMessage(json, res);
+        throw new Error(String(msg));
+    }
+    const payload = json?.data;
+    if (!payload?.access_token)
+        throw new Error('Invalid login response');
+    return {
+        access_token: payload.access_token,
+        refresh_token: payload.refresh_token,
+        expires_in: payload.expires_in ?? 3600,
+        expires_at: payload.expires_at ?? '',
+        ...(payload.aws_credentials ? { aws_credentials: payload.aws_credentials } : {}),
+    };
+}
+/**
+ * Refresh access token. POST `{apiUrl}/{auth_path}/auth/refresh` (default path segment: `app`).
+ */
+export async function refresh(apiUrl, refreshToken, options) {
+    const base = apiUrl.replace(/\/$/, '');
+    const url = buildAuthServiceUrl(base, options?.auth_path_prefix, '/auth/refresh');
+    const fetchFn = options?.fetchFn ?? DEFAULT_FETCH;
+    if (!fetchFn)
+        throw new Error('fetch not available');
+    const res = await doFetch('POST', url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refresh_token: refreshToken }),
+    }, fetchFn);
+    const json = (await res.json());
+    if (!res.ok) {
+        const msg = json?.error ?? res.statusText;
+        throw new Error(String(msg));
+    }
+    const payload = json.success && json.data && typeof json.data === 'object' ? json.data : json;
+    if (!payload?.access_token)
+        throw new Error('Invalid refresh response');
+    return {
+        access_token: payload.access_token,
+        refresh_token: payload.refresh_token ?? refreshToken,
+        expires_in: payload.expires_in ?? 3600,
+        expires_at: payload.expires_at ?? '',
+        ...(payload.aws_credentials ? { aws_credentials: payload.aws_credentials } : {}),
+    };
+}
+//# sourceMappingURL=login.js.map

package/dist/auth/login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/auth/login.ts"],"names":[],"mappings":"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"}

package/dist/auth/token-manager.d.ts

@@ -0,0 +1,30 @@
+export interface TokenState {
+    access_token: string;
+    refresh_token?: string;
+    expires_at?: number;
+}
+/**
+ * In-memory token manager. No token persisted to disk.
+ * setToken, getToken, shouldRefresh, getTokenOrRefresh (with optional refresh fetcher).
+ */
+export declare class TokenManager {
+    private state;
+    setToken(access_token: string, refresh_token?: string, expires_at?: number): void;
+    getToken(): string | null;
+    getRefreshToken(): string | null;
+    clear(): void;
+    /**
+     * True if access token is missing or expires within thresholdSeconds.
+     */
+    shouldRefresh(thresholdSeconds?: number): boolean;
+    /**
+     * Return access token, or refresh if shouldRefresh(thresholdSeconds) and refresh_token exists.
+     * refreshFn(apiUrl, refresh_token) must return { access_token, refresh_token?, expires_in }.
+     */
+    getTokenOrRefresh(apiUrl: string, thresholdSeconds: number | undefined, refreshFn: (apiUrl: string, refreshToken: string) => Promise<{
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+    }>): Promise<string | null>;
+}
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/auth/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/auth/token-manager.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA2B;IAExC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAQjF,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,aAAa,CAAC,gBAAgB,GAAE,MAA0C,GAAG,OAAO;IASpF;;;OAGG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,YAAoC,EAC5D,SAAS,EAAE,CACT,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,KACjB,OAAO,CAAC;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,GACD,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAgB1B"}

package/dist/auth/token-manager.js

@@ -0,0 +1,61 @@
+import { decodeJwtPayload, DEFAULT_REFRESH_THRESHOLD_SECONDS } from './jwt.js';
+/**
+ * In-memory token manager. No token persisted to disk.
+ * setToken, getToken, shouldRefresh, getTokenOrRefresh (with optional refresh fetcher).
+ */
+export class TokenManager {
+    state = null;
+    setToken(access_token, refresh_token, expires_at) {
+        this.state = {
+            access_token,
+            refresh_token,
+            expires_at,
+        };
+    }
+    getToken() {
+        return this.state?.access_token ?? null;
+    }
+    getRefreshToken() {
+        return this.state?.refresh_token ?? null;
+    }
+    clear() {
+        this.state = null;
+    }
+    /**
+     * True if access token is missing or expires within thresholdSeconds.
+     */
+    shouldRefresh(thresholdSeconds = DEFAULT_REFRESH_THRESHOLD_SECONDS) {
+        const token = this.state?.access_token;
+        if (!token)
+            return true;
+        const { exp } = decodeJwtPayload(token);
+        if (exp == null)
+            return false; // No exp claim → don't refresh
+        const now = Math.floor(Date.now() / 1000);
+        return exp - now < thresholdSeconds;
+    }
+    /**
+     * Return access token, or refresh if shouldRefresh(thresholdSeconds) and refresh_token exists.
+     * refreshFn(apiUrl, refresh_token) must return { access_token, refresh_token?, expires_in }.
+     */
+    async getTokenOrRefresh(apiUrl, thresholdSeconds = DEFAULT_REFRESH_THRESHOLD_SECONDS, refreshFn) {
+        const token = this.getToken();
+        if (!token)
+            return null;
+        if (!this.shouldRefresh(thresholdSeconds))
+            return token;
+        const refreshToken = this.getRefreshToken();
+        if (!refreshToken)
+            return token; // No refresh token, return current
+        try {
+            const result = await refreshFn(apiUrl.replace(/\/$/, ''), refreshToken);
+            const expiresAt = result.expires_in != null ? Math.floor(Date.now() / 1000) + result.expires_in : undefined;
+            this.setToken(result.access_token, result.refresh_token ?? refreshToken, expiresAt);
+            return this.state?.access_token ?? null;
+        }
+        catch {
+            return token; // On refresh failure, return current token
+        }
+    }
+}
+//# sourceMappingURL=token-manager.js.map