qati-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,78 @@
+QATI SDK PROPRIETARY LICENSE
+
+Copyright (c) 2024–2026 Qlok Tech. All rights reserved.
+
+IMPORTANT — READ CAREFULLY BEFORE USING THIS SOFTWARE.
+
+By downloading, installing, copying, or otherwise using the QATI SDK
+("Software"), you agree to be bound by the terms of this license
+("License"). If you do not agree to these terms, do not use the Software.
+
+1. GRANT OF LICENSE
+
+   Subject to the terms and conditions of this License and your compliance
+   with the QATI Terms of Service (https://qlokinc.com/terms-of-use), Qlok Tech
+   grants you a limited, non-exclusive, non-transferable, non-sublicensable
+   license to use the Software solely to interact with the QATI platform
+   APIs using a valid API key issued by Qlok Tech.
+
+2. RESTRICTIONS
+
+   You may NOT, without prior written permission from Qlok Tech:
+
+   a. Copy, modify, adapt, translate, or create derivative works of the
+      Software or any portion thereof;
+   b. Distribute, sublicense, sell, resell, transfer, assign, or otherwise
+      make the Software available to any third party;
+   c. Reverse-engineer, decompile, disassemble, or attempt to derive the
+      source code of any compiled component of the Software;
+   d. Remove, alter, or obscure any proprietary notices, labels, or marks
+      on the Software;
+   e. Use the Software to build a competing product or service;
+   f. Use the Software without a valid QATI API key or in violation of the
+      QATI Terms of Service.
+
+3. API KEY REQUIREMENT
+
+   Use of the Software requires a valid API key issued by Qlok Tech. API
+   keys are subject to the QATI Terms of Service and may be revoked at any
+   time for violation of those terms.
+
+4. OWNERSHIP
+
+   Qlok Tech retains all right, title, and interest in and to the Software,
+   including all intellectual property rights. This License does not grant
+   you any rights to trademarks, service marks, or trade names of Qlok Tech.
+
+5. DISCLAIMER OF WARRANTIES
+
+   THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. QLOK TECH DOES
+   NOT WARRANT THAT THE SOFTWARE WILL BE ERROR-FREE OR UNINTERRUPTED.
+
+6. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   QLOK TECH BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+   CONSEQUENTIAL DAMAGES (INCLUDING LOSS OF PROFITS, DATA, OR BUSINESS
+   INTERRUPTION) ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF
+   THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. TERMINATION
+
+   This License is effective until terminated. It will terminate automatically
+   if you fail to comply with any term herein. Upon termination, you must
+   immediately cease all use of the Software and destroy all copies in your
+   possession.
+
+8. GOVERNING LAW
+
+   This License shall be governed by and construed in accordance with the
+   laws of the State of Delaware, United States, without regard to its
+   conflict-of-law provisions.
+
+9. CONTACT
+
+   For licensing inquiries or permissions beyond the scope of this License,
+   contact: tim@qlok.net

package/README.md

@@ -0,0 +1,564 @@
+# QATI TypeScript SDK (`qati-sdk`)
+
+Developer Reference · v1
+
+## Overview
+
+The Qati SDK is the official TypeScript client for the Qati platform. It gives you a clean, type-safe interface to two backend services — the Query API and the Ingestion API — without having to craft raw HTTP requests yourself.
+Everything starts from a `Session` object, which holds your credentials and connection settings. From that session you open a **client** and call methods grouped by feature area.
+The main feature groups on the client are:
+
+- `client.tenant` — verify that your API key is accepted.
+- `client.trustState` — read risk and trust scores for users or other entities.
+- `client.advisory` — list persisted advisories for the tenant (with filters and pagination).
+- `client.explain` — fetch a composite explain / attribution payload for a single entity (by entity key).
+- `client.events` — send telemetry events to the ingestion pipeline.
+
+No network traffic occurs until you call a method. Opening a client only prepares HTTP connections and resolves configuration.
+
+**Positioning:** QATI v1 is an **append-only, non-blocking observability and threat-intelligence layer**. It does **not** perform automated enforcement, blocking, or policy execution — your application owns those decisions.
+
+## Requirements
+
+- **Node.js** 24 or newer (`engines` in [`package.json`](package.json)).
+- **TypeScript** 5.x or newer recommended (matches this package’s dev toolchain).
+- A tenant API key. Set `QATI_TENANT_API_KEY`, pass `tenantApiKey` into `new Session({ ... })`, or build a resolved config with `parseQatiConfig` / `resolveQatiConfig`.
+- **Query API base URL** — mandatory; there is **no** built-in default. Set `QATI_QUERY_API_BASE_URL` or pass `queryApiBaseUrl` in the session config (for example `http://localhost:8001` when developing locally).
+- **Ingestion API base URL** — mandatory; there is **no** built-in default. Set `QATI_INGESTION_API_BASE_URL` or pass `ingestionApiBaseUrl` in the session config (for example `http://localhost:8000` when developing locally).
+
+## Installation
+
+Install from npm (distribution name `qati-sdk`):
+
+```bash
+npm install qati-sdk
+```
+
+Or with Yarn:
+
+```bash
+yarn add qati-sdk
+```
+
+Or with pnpm:
+
+```bash
+pnpm add qati-sdk
+```
+
+The package ships **ESM** and **CJS** via `package.json` `exports`. Types live in `./dist/index.d.ts`.
+
+## Client
+
+Open a client with `session.createClient()`, `await` the methods you need, and always **`await client.close()`** in a `finally` block (or on shutdown) so buffered ingestion flushes and timers stop.
+
+```ts
+const session = new Session();
+const client = session.createClient();
+try {
+  await client.trustState.getTrustState(...)
+} finally {
+  await client.close();
+}
+```
+
+## Step 1 Verify your credentials
+
+Before doing anything else, confirm that your API key is accepted. This prevents hard-to-debug errors later.
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const result = await client.tenant.verifyCredentials();
+  console.log(result.is_valid, result.tenant_id);
+} finally {
+  await client.close();
+}
+```
+
+Tip: If `is_valid` is `false`, check that `QATI_TENANT_API_KEY` is set correctly before continuing.
+
+## Step 2 Read trust state
+
+Trust state tells you the risk tier and closure score for an entity — typically a user — as computed by the Qati platform. Entities are identified by a **lowercase** entity type string and an opaque id (see `EntityTypeLowerCase` in the SDK: `user`, `device`, `account`, `model`, `session`, `service`).
+
+### Single entity
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const data = await client.trustState.getTrustState('user', 'user-123', {
+    topContributorsLimit: 5,
+  });
+  console.log(data.risk_tier, data.current_closure_score);
+} finally {
+  await client.close();
+}
+```
+
+The response is the requested trust-state data.
+
+### Multiple entities in one round trip
+
+Pass an array of ids to `getTrustStates`. If the array is **empty**, the SDK returns `[]` immediately without hitting the network.
+
+```ts
+const batch = await client.trustState.getTrustStates(
+  'user',
+  ['user-1', 'user-2'],
+  { topContributorsLimit: 3 },
+);
+for (const row of batch) {
+  console.log(row.entity_key, row.risk_tier);
+}
+```
+
+## Query API: advisories and explain
+
+### List advisories
+
+Use `client.advisory.listAdvisories()`. `GET /v1/advisories` returns a paginated list of advisories.
+
+In TypeScript, **`advisoryType`** and **`severity`** are **required** positional arguments (they map to `advisory_type` and `severity` query params). Pass a `Date` or an ISO-8601 string for `since` / `until`; the SDK serializes dates to ISO-8601 for the query string.
+
+```ts
+import type { AdvisorySeverity, AdvisoryType } from 'qati-sdk';
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const page = await client.advisory.listAdvisories(
+    'USER:user-123',
+    'ANOMALY_CLUSTER' as AdvisoryType,
+    'HIGH' as AdvisorySeverity,
+    { limit: 20, offset: 0 },
+  );
+  console.log(page.total_count, page.advisories.length);
+} finally {
+  await client.close();
+}
+```
+
+### Composite explain for one entity
+
+`GET /v1/explain/{entity_key}` returns an `ExplainResponse`. The SDK URL-encodes `entity_key` for the path segment (for example scoped keys that contain `:`). Optional `at_timestamp` accepts a `Date` or ISO-8601 string for historical snapshots.
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const out = await client.explain.get(
+    'USER:user-123',
+    new Date(Date.UTC(2026, 3, 1, 12, 0, 0)),
+  );
+  console.log(out.closure_score, out.risk_tier);
+} finally {
+  await client.close();
+}
+```
+
+## Step 3 Configure the session
+
+For most teams, environment variables are the simplest approach — set them once and the SDK picks them up automatically (via `dotenv` loading `.env` from the working directory when using `new Session()` / `resolveQatiConfig()`). If you need finer control (custom URLs, timeouts, or multiple tenants), pass a config object into `Session`.
+
+### Environment variables
+
+Configuration precedence (highest first): explicit fields on `new Session({ ... })` → `QATI_*` environment variables (merged from `process.env` into camelCase) → Zod defaults **only for optional fields** (timeouts, retries, batch sizing). **`QATI_QUERY_API_BASE_URL` and `QATI_INGESTION_API_BASE_URL` have no defaults** — you must supply them via env or constructor config.
+
+| Variable                                | Required | Default | Purpose                                    |
+| --------------------------------------- | -------- | ------- | ------------------------------------------ |
+| `QATI_TENANT_API_KEY`                   | Yes      | —       | Your tenant API key                        |
+| `QATI_QUERY_API_BASE_URL`               | Yes      | —       | Query API base URL (no default)            |
+| `QATI_INGESTION_API_BASE_URL`           | Yes      | —       | Ingestion API base URL (no default)        |
+| `QATI_TIMEOUT`                          | No       | 30      | Seconds to wait per HTTP request           |
+| `QATI_MAX_RETRIES`                      | No       | 3       | Retry attempts on transient failure (1–10) |
+| `QATI_RETRY_BACKOFF_INITIAL_SECONDS`    | No       | 1       | First backoff delay in seconds             |
+| `QATI_RETRY_BACKOFF_MAX_SECONDS`        | No       | 30      | Maximum backoff delay cap                  |
+| `QATI_RETRY_JITTER_FRACTION`            | No       | 0.1     | Random jitter to spread out retries        |
+| `QATI_INGESTION_BATCH_SIZE`             | No       | 100     | Max events buffered before auto-flush      |
+| `QATI_INGESTION_FLUSH_INTERVAL_SECONDS` | No       | 5       | Max wait before flushing a partial batch   |
+
+### Configuration in code
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session({
+  tenantApiKey: 'qati-...',
+  queryApiBaseUrl: 'https://query.example.com',
+  ingestionApiBaseUrl: 'https://ingest.example.com',
+  timeout: 15,
+  ingestionBatchSize: 50,
+});
+```
+
+Advanced: inject custom `axios` instances per logical API with `session.createClient({ query_api: customAxios, ingestion_api: customAxios })` if your platform requires special TLS settings or proxy configuration.
+
+## Step 4 Build an event payload
+
+Sending an event is a deliberate two-step process: first build a valid payload, then hand it to the client. Separating construction from delivery means you can validate your data before any network call is made, and catch mistakes early.
+
+The `create*` functions exported from `qati-sdk` accept a typed envelope and return a `RawEventRequest`. If your payload is malformed, **Zod** throws while building — no partial HTTP requests to untangle.
+
+Builders set `payload.signal_version` to `'v1'` and `payload.signal_type` for you. The ingestion API assigns the persisted raw-event id (**UUID v7**); responses include `event_id`. You do **not** send a top-level `id` on ingest or set `signal_version` manually on the wire object.
+
+Most events share the same outer envelope fields. In strict TypeScript codebases, prefer **inlined literals** per builder so `signal_payload` inference stays narrow; here we use a widened helper plus `as` for readability:
+
+```ts
+const TENANT_ID = '550e8400-e29b-41d4-a716-446655440000';
+
+const v1Event = (signalPayload: object, extra: object = {}) => {
+  return {
+    tenant_id: TENANT_ID,
+    timestamp: new Date().toISOString(),
+    provenance: {
+      mode: 'DETERMINISTIC' as const,
+      source_id: 'my-service',
+      epoch_counter: 0,
+      health_summary: {},
+    },
+    principal: { user_id: 'user-123' },
+    signal_payload: signalPayload,
+    ...extra,
+  };
+};
+```
+
+### Available signal types
+
+#### Transaction
+
+```ts
+import { createTransactionEvent, type TransactionSignalEvent } from 'qati-sdk';
+
+const raw = createTransactionEvent(
+  v1Event({ amount: 99.99 }) as TransactionSignalEvent,
+);
+```
+
+#### Auth
+
+```ts
+import { createAuthEvent, type AuthSignalEvent } from 'qati-sdk';
+
+const raw = createAuthEvent(
+  v1Event({
+    result: 'success',
+    auth_method: 'password',
+    mfa_used: true,
+  }) as AuthSignalEvent,
+);
+```
+
+#### Model output
+
+```ts
+import { createModelOutputEvent, type ModelOutputSignalEvent } from 'qati-sdk';
+
+const raw = createModelOutputEvent(
+  v1Event({
+    citation_rate: 0.95,
+    eval_window_n: 1000,
+  }) as ModelOutputSignalEvent,
+);
+```
+
+#### System telemetry
+
+```ts
+import {
+  createSystemTelemetryEvent,
+  type SystemTelemetrySignalEvent,
+} from 'qati-sdk';
+
+const raw = createSystemTelemetryEvent(
+  v1Event({
+    metric_name: 'p99_latency_ms',
+    value: 120.0,
+    baseline: 80.0,
+  }) as SystemTelemetrySignalEvent,
+);
+```
+
+#### Anomaly flag
+
+`severity` must be between 0 and 1.
+
+```ts
+import { createAnomalyFlagEvent, type AnomalyFlagSignalEvent } from 'qati-sdk';
+
+const raw = createAnomalyFlagEvent(
+  v1Event({ severity: 0.85 }) as AnomalyFlagSignalEvent,
+);
+```
+
+#### Behavior
+
+`deviation_score` must be between 0 and 1.
+
+```ts
+import { createBehaviorEvent, type BehaviorSignalEvent } from 'qati-sdk';
+
+const raw = createBehaviorEvent(
+  v1Event({ deviation_score: 0.4 }) as BehaviorSignalEvent,
+);
+```
+
+#### Network
+
+```ts
+import { createNetworkEvent, type NetworkSignalEvent } from 'qati-sdk';
+
+const raw = createNetworkEvent(
+  v1Event({
+    ip: '198.51.100.10',
+    reputation_score: 0.2,
+    threat_score: 0.7,
+  }) as NetworkSignalEvent,
+);
+```
+
+Note: At this point `raw` is an in-memory object. Nothing has been sent over the network yet. Proceed to Step 5 to deliver it.
+
+### Canonical wire shape (`RawEventRequest` / `BaseEvent`)
+
+HTTP ingestion bodies use **`RawEventRequest`**: `{ tenant_id, payload }` (no client-supplied top-level `id`). The typed **`BaseEvent`** lives inside `payload` (`signal_version`, `signal_type`, `signal_payload`, `principal`, optional `timestamp`, `confidence_hint`, `provenance`, `integrity`). After acceptance, the API returns **`event_id`** in the response body.
+
+The product spec’s `source: { system, component, region? }` field is **not** modeled as a first-class Zod field in this SDK; use **`provenance`** and **`principal`** for origin context.
+
+## Step 5 Send events
+
+`enqueue` adds one event to an in-memory queue inside your process. It does **not** trigger an immediate HTTP call. The SDK groups queued events and posts them in batches to `POST /v1/events:batch`, making the per-event cost very low.
+
+Call `flush` when you need delivery to happen right now — for example, at the end of a script or at a processing checkpoint.
+
+### One event, forced delivery
+
+The most explicit pattern: build → enqueue → flush.
+
+```ts
+import { Session, createTransactionEvent } from 'qati-sdk';
+
+const TENANT_ID = '550e8400-e29b-41d4-a716-446655440000';
+
+const main = async () => {
+  const session = new Session();
+  const client = session.createClient();
+  try {
+    const raw = createTransactionEvent({
+      tenant_id: TENANT_ID,
+      signal_version: 'v1',
+      signal_type: 'TRANSACTION',
+      timestamp: new Date().toISOString(),
+      provenance: {
+        mode: 'DETERMINISTIC',
+        source_id: 'example',
+        epoch_counter: 0,
+        health_summary: {},
+      },
+      principal: { user_id: 'user-123' },
+      signal_payload: {
+        amount: 42.0,
+        bulk_export: false,
+        contains_phi: false,
+        safety_critical: false,
+      },
+    });
+    await client.events.enqueue(raw);
+    await client.events.flush();
+  } finally {
+    await client.close();
+  }
+};
+
+void main();
+```
+
+### Multiple enqueues, single flush
+
+Enqueue as many events as you like, then flush once to send them all in a single batch.
+
+```ts
+import {
+  Session,
+  createTransactionEvent,
+  type TransactionSignalEvent,
+} from 'qati-sdk';
+
+const TENANT_ID = '550e8400-e29b-41d4-a716-446655440000';
+
+const v1Event = (signalPayload: object, extra: object = {}) => {
+  return {
+    tenant_id: TENANT_ID,
+    timestamp: new Date().toISOString(),
+    provenance: {
+      mode: 'DETERMINISTIC' as const,
+      source_id: 'batch-example',
+      epoch_counter: 0,
+      health_summary: {},
+    },
+    principal: { user_id: 'user-123' },
+    signal_payload: signalPayload,
+    ...extra,
+  };
+};
+
+const main = async () => {
+  const session = new Session();
+  const client = session.createClient();
+  try {
+    await client.events.enqueue(
+      createTransactionEvent(
+        v1Event({ amount: 10.0 }) as TransactionSignalEvent,
+      ),
+    );
+    await client.events.enqueue(
+      createTransactionEvent(
+        v1Event({ amount: 20.0 }) as TransactionSignalEvent,
+      ),
+    );
+    await client.events.flush();
+  } finally {
+    await client.close();
+  }
+};
+
+void main();
+```
+
+### Automatic batching (no manual flush)
+
+If you never call `flush`, the SDK still sends data when either condition is met:
+
+- The queue reaches `ingestionBatchSize` events (default **100**), or
+- `ingestionFlushIntervalSeconds` have elapsed since the first buffered event (default **5**).
+
+High-throughput traffic fills batches quickly; quieter traffic drains on the timer. Adjust both thresholds with `QATI_INGESTION_BATCH_SIZE` and `QATI_INGESTION_FLUSH_INTERVAL_SECONDS`.
+
+Important: The queue lives only in memory. If the process exits or crashes before a batch is sent, those events are lost. For high-stakes pipelines, call `flush()` at processing checkpoints rather than relying solely on the automatic timer.
+
+### Dead-letter hook (TypeScript)
+
+Buffered ingestion uses `retry: true` on the batch HTTP call. After retries are exhausted, you can register **`client.events.onIngestionFailure((payload, error) => { ... })`** once to log, metrics, or persist failed batches (do not throw from the callback).
+
+## Step 6 Handle errors
+
+All SDK errors inherit from `QatiSDKError`. HTTP failures come back as `QatiAPIError` or a narrower subclass.
+
+| Exception            | When it fires                                                      |
+| -------------------- | ------------------------------------------------------------------ |
+| `QatiAuthError`      | 401 or 403 — key missing, expired, or lacking permission.          |
+| `QatiNotFoundError`  | 404 — the requested resource does not exist.                       |
+| `QatiRateLimitError` | 429 — too many requests; the built-in retry policy may recover it. |
+| `QatiServerError`    | 5xx — server-side fault; the built-in retry policy may recover it. |
+| `QatiAPIError`       | Any other HTTP error response.                                     |
+| `QatiConfigError`    | Session / config is incomplete or invalid.                         |
+
+On `QatiAPIError` you can inspect `e.detail.status_code`, `e.detail.message`, and `e.detail.request_id` (useful when filing a support ticket).
+
+### Example error handler
+
+```ts
+import {
+  Session,
+  QatiAPIError,
+  QatiAuthError,
+  QatiNotFoundError,
+  QatiRateLimitError,
+} from 'qati-sdk';
+
+type QatiClient = ReturnType<Session['createClient']>;
+
+const safeCall = async (client: QatiClient) => {
+  try {
+    return await client.trustState.getTrustState('user', 'id');
+  } catch (e) {
+    if (e instanceof QatiAuthError) throw e;
+    if (e instanceof QatiNotFoundError) return null;
+    if (e instanceof QatiRateLimitError) throw e;
+    if (e instanceof QatiAPIError) {
+      const log = `${e.detail.status_code} ${e.detail.message} request_id=${e.detail.request_id}`;
+      throw new Error(log, { cause: e });
+    }
+    throw e;
+  }
+};
+```
+
+### Validation errors when building events
+
+If you pass an invalid payload to a `create*` function, **Zod** throws before any HTTP call is made. Inspect `error.issues` for a structured description of what is wrong.
+
+```ts
+import { ZodError } from 'zod';
+import { createAnomalyFlagEvent, type AnomalyFlagSignalEvent } from 'qati-sdk';
+
+const v1Event = (signalPayload: object, extra: object = {}) => {
+  return {
+    tenant_id: '550e8400-e29b-41d4-a716-446655440000',
+    timestamp: new Date().toISOString(),
+    provenance: {
+      mode: 'DETERMINISTIC' as const,
+      source_id: 'validation-example',
+      epoch_counter: 0,
+      health_summary: {},
+    },
+    principal: { user_id: 'user-123' },
+    signal_payload: signalPayload,
+    ...extra,
+  };
+};
+
+try {
+  createAnomalyFlagEvent(v1Event({ severity: 2.0 }) as AnomalyFlagSignalEvent);
+} catch (e) {
+  if (e instanceof ZodError) console.log(e.issues);
+}
+```
+
+### Retries
+
+Transient failures are retried automatically for **`POST /v1/events:batch`** according to `QATI_MAX_RETRIES` and the backoff settings in your session config. Retries cover **429**, **5xx**, and transport errors without a response, using exponential backoff with jitter (see `computeBackoffMs` in the SDK source). Once retries are exhausted you still get a `QatiAPIError`. For other endpoints, the SDK typically performs a single attempt unless you use the low-level HTTP layer with `retry: true`.
+
+## Further reading
+
+- HTTP paths, headers, and error shapes: [docs/API.md](../../docs/API.md) (repo root).
+- Live OpenAPI UI (when running the Query API locally): `/v1/docs`.
+- TypeScript source: [`sdks/typescript/src/`](src/).
+- Python SDK (sync/async patterns and feature parity notes): [`sdks/python/README.md`](../python/README.md).
+
+---
+
+## Appendix: API surface (compact)
+
+| Symbol          | Role                                                                                                                                                                                                       |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Session`       | `new Session(config?)`, `session.config`, `session.createClient(httpClients?)`.                                                                                                                            |
+| `Client`        | Namespaces: `tenant`, `trustState`, `advisory`, `explain`, `events`; `await client.close()`.                                                                                                               |
+| `client.events` | `enqueue`, `flush`, `shutdown`, `pendingCount`, `onIngestionFailure`.                                                                                                                                      |
+| `create*Event`  | `createTransactionEvent`, `createAuthEvent`, `createModelOutputEvent`, `createSystemTelemetryEvent`, `createAnomalyFlagEvent`, `createBehaviorEvent`, `createNetworkEvent` — all exported from `qati-sdk`. |
+| Config          | `resolveQatiConfig`, `parseQatiConfig`, `baseUrlFor`, types `QatiConfigInput` / `QatiConfigOutput`.                                                                                                        |
+| Errors          | `QatiSDKError`, `QatiAPIError`, `QatiAuthError`, `QatiNotFoundError`, `QatiRateLimitError`, `QatiServerError`, `QatiConfigError`.                                                                          |
+
+`HttpClient.request(...)` exists for advanced use; prefer resource methods for application code.
+
+## Build (maintainers)
+
+From `sdks/typescript/`:
+
+```bash
+npm ci
+npm test
+npm run build
+```
+
+Outputs land in `dist/` (ESM + CJS + declarations).