qati-sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,996 @@
+import { config } from 'dotenv';
+import { z } from 'zod';
+import axios, { AxiosError } from 'axios';
+
+// src/config.ts
+
+// src/shared/common/exceptions.ts
+var QatiSDKError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "QatiSDKError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QatiAPIError = class extends QatiSDKError {
+  detail;
+  constructor(detail) {
+    super(
+      `HTTP ${detail.status_code}: ${detail.message} (request_id=${detail.request_id})`
+    );
+    this.name = "QatiAPIError";
+    this.detail = detail;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /**
+   * @returns Same as `detail.status_code`.
+   */
+  get status_code() {
+    return this.detail.status_code;
+  }
+  /**
+   * @returns Same as `detail.request_id`.
+   */
+  get request_id() {
+    return this.detail.request_id;
+  }
+};
+var QatiAuthError = class extends QatiAPIError {
+  constructor(detail) {
+    super(detail);
+    this.name = "QatiAuthError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QatiNotFoundError = class extends QatiAPIError {
+  constructor(detail) {
+    super(detail);
+    this.name = "QatiNotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QatiRateLimitError = class extends QatiAPIError {
+  constructor(detail) {
+    super(detail);
+    this.name = "QatiRateLimitError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QatiServerError = class extends QatiAPIError {
+  constructor(detail) {
+    super(detail);
+    this.name = "QatiServerError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var QatiConfigError = class extends QatiSDKError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "QatiConfigError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/config.ts
+var EV_VARIABLES_NAMES = [
+  "QATI_TENANT_API_KEY",
+  "QATI_QUERY_API_BASE_URL",
+  "QATI_INGESTION_API_BASE_URL",
+  "QATI_TIMEOUT",
+  "QATI_MAX_RETRIES",
+  "QATI_INGESTION_BATCH_SIZE",
+  "QATI_INGESTION_FLUSH_INTERVAL_SECONDS",
+  "QATI_RETRY_BACKOFF_INITIAL_SECONDS",
+  "QATI_RETRY_BACKOFF_MAX_SECONDS",
+  "QATI_RETRY_JITTER_FRACTION",
+  "QATI_MAX_RETRIES"
+];
+var API_REGISTRY = {
+  query_api: "queryApiBaseUrl",
+  ingestion_api: "ingestionApiBaseUrl"
+};
+var QatiConfigBase = z.object({
+  tenantApiKey: z.string().min(1),
+  queryApiBaseUrl: z.string().url(),
+  ingestionApiBaseUrl: z.string().url(),
+  timeout: z.number().min(1).optional().default(30),
+  ingestionBatchSize: z.number().int().min(1).optional().default(100),
+  ingestionFlushIntervalSeconds: z.number().positive().optional().default(5),
+  // Retry fields
+  retryBackoffInitialSeconds: z.number().nonnegative().optional().default(1),
+  retryBackoffMaxSeconds: z.number().nonnegative().optional().default(30),
+  retryJitterFraction: z.number().min(0).max(1).optional().default(0.1),
+  maxRetries: z.number().int().min(1).max(10).optional().default(3)
+});
+var stripUndefined = (obj) => {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([_, v]) => v !== void 0)
+  );
+};
+var readEnvOverrides = () => {
+  const e = process.env;
+  const sanitizedEnvs = EV_VARIABLES_NAMES.reduce(
+    (acc, ev) => {
+      acc[ev] = e[ev];
+      return acc;
+    },
+    {}
+  );
+  return sanitizedEnvs;
+};
+var resolveQatiConfig = (input) => {
+  config({ path: ".env" });
+  const merged = {
+    ...readEnvOverrides(),
+    ...stripUndefined(input ?? {})
+  };
+  const parsed = QatiConfigBase.safeParse(merged);
+  if (!parsed.success) {
+    const msg = parsed.error.flatten().fieldErrors;
+    throw new QatiConfigError(
+      `Invalid QATI SDK configuration: ${JSON.stringify(msg)}`
+    );
+  }
+  return parsed.data;
+};
+var parseQatiConfig = (input) => {
+  const parsed = QatiConfigBase.safeParse(input);
+  if (!parsed.success) {
+    throw new QatiConfigError(
+      `Invalid QATI SDK configuration: ${JSON.stringify(parsed.error.flatten().fieldErrors)}`
+    );
+  }
+  return parsed.data;
+};
+var baseUrlFor = (config, apiName) => {
+  if (!(apiName in API_REGISTRY))
+    throw new QatiConfigError(
+      `Unknown API "${apiName}". Registered APIs: ${Object.keys(API_REGISTRY).map((k) => `"${k}"`).join(", ")}.`
+    );
+  const field = API_REGISTRY[apiName];
+  const url = config[field];
+  if (typeof url !== "string")
+    throw new QatiConfigError(`Missing base URL field for API "${apiName}"`);
+  return url.replace(/\/$/, "");
+};
+var isRetryableStatusCode = (statusCode) => statusCode === 429 || statusCode >= 500;
+var defaultHeaders = (config) => ({
+  "x-tenant-api-key": config.tenantApiKey,
+  "Content-Type": "application/json"
+});
+var resolveRequestHeaders = (config, headers = {}, extraHeaders = {}) => {
+  return { ...headers, ...defaultHeaders(config), ...extraHeaders };
+};
+var computeBackoffMs = (attemptNumber, config) => {
+  const {
+    retryBackoffInitialSeconds,
+    retryBackoffMaxSeconds,
+    retryJitterFraction
+  } = config;
+  const expBase = 2;
+  const rawDelay = retryBackoffInitialSeconds * expBase ** (attemptNumber - 1);
+  const base = Math.min(rawDelay, retryBackoffMaxSeconds);
+  const jitterFactor = 1 + (Math.random() * 2 * retryJitterFraction - retryJitterFraction);
+  const delayMs = Math.max(
+    0,
+    Math.min(base * jitterFactor, retryBackoffMaxSeconds)
+  );
+  return delayMs * 1e3;
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var isRetryableAxiosFailure = (err) => {
+  if (!axios.isAxiosError(err)) return false;
+  if (!err.response) return true;
+  return isRetryableStatusCode(err.response.status);
+};
+var validateInjectedApiNames = (instances) => {
+  if (!instances) return;
+  const unknownApiNames = Object.keys(instances).filter(
+    (name) => !(name in API_REGISTRY)
+  );
+  if (unknownApiNames?.length) {
+    const badApiNames = unknownApiNames.map((name) => `"${name}"`).join(", ");
+    throw new QatiConfigError(`Unknown API name(s): ${badApiNames}`);
+  }
+};
+var STATUS_ERROR_MAP = {
+  401: QatiAuthError,
+  403: QatiAuthError,
+  404: QatiNotFoundError,
+  429: QatiRateLimitError,
+  500: QatiServerError
+};
+var parseDetail = (response) => {
+  const { headers, status, statusText, data } = response;
+  const requestId = headers["x-request-id"] ?? headers["X-Request-Id"];
+  let message = statusText ?? "";
+  try {
+    const body = data;
+    if (typeof body === "object") {
+      const msg = body.detail || body.message;
+      message = typeof msg === "string" ? msg : JSON.stringify(msg);
+    }
+  } catch {
+    message = statusText;
+  }
+  return {
+    status_code: status,
+    message,
+    request_id: requestId
+  };
+};
+var qatiApiErrorFromRequestFailure = (err) => {
+  if (axios.isAxiosError(err)) {
+    const ax = err;
+    if (ax.response) {
+      const resp = ax.response;
+      const ErrorCls = STATUS_ERROR_MAP[resp.status] ?? (resp.status >= 500 ? QatiServerError : QatiAPIError);
+      return new ErrorCls(parseDetail(resp));
+    }
+    return new QatiAPIError({
+      status_code: 0,
+      message: ax.message || String(ax.code ?? "Axios request error"),
+      request_id: null
+    });
+  }
+  throw new TypeError(`Expected Axios error, got ${typeof err}`);
+};
+
+// src/http/http-client.ts
+var HttpClient = class {
+  _config;
+  _httpClients;
+  constructor(config, axiosInstances = {}) {
+    validateInjectedApiNames(axiosInstances);
+    this._config = config;
+    this._httpClients = /* @__PURE__ */ new Map();
+    for (const apiName of Object.keys(API_REGISTRY)) {
+      const existingApiInstance = axiosInstances[apiName];
+      if (existingApiInstance) {
+        this._httpClients.set(apiName, existingApiInstance);
+        continue;
+      }
+      const apiInstance = this.createClient(apiName);
+      this._httpClients.set(apiName, apiInstance);
+    }
+  }
+  createClient(apiName) {
+    const baseURL = baseUrlFor(this._config, apiName);
+    return axios.create({
+      baseURL,
+      timeout: this._config.timeout * 1e3,
+      headers: defaultHeaders(this._config)
+    });
+  }
+  /**
+   * @returns The same configuration used to build base URLs, timeouts, and default headers.
+   */
+  get config() {
+    return this._config;
+  }
+  /**
+   * Returns the underlying `axios` instance for a logical API.
+   *
+   * @param apiName - `query_api` or `ingestion_api`.
+   * @returns Configured `AxiosInstance` for that API.
+   * @throws {@link QatiConfigError} If the internal client map has no entry for `apiName`.
+   */
+  getClient(apiName) {
+    const instance = this._httpClients.get(apiName);
+    if (!instance)
+      throw new QatiConfigError(`Unknown HTTP client for API "${apiName}"`);
+    return instance;
+  }
+  /**
+   * Performs one HTTP request and returns the **unwrapped** `data` field from the QATI `{ data: T }` envelope.
+   *
+   * @typeParam T - Response payload type inside the API envelope.
+   * @param method - HTTP verb (e.g. `GET`, `POST`).
+   * @param url - Path relative to the API base URL (may include query string; prefer `options.params` for queries).
+   * @param options - `api_name` selects which base URL and client to use. Set `retry: true` to retry transient failures.
+   * @returns Parsed `T` from `response.data.data` (not the full `ApiResponse` wrapper).
+   * @throws `QatiAPIError` or subclasses (`QatiAuthError`, `QatiNotFoundError`, …) on HTTP failures; on transport exhaustion when `retry` is `true`, after optional dead-letter callback.
+   *
+   * When `options.retry` is `true`, retries `429`, `5xx`, and transport errors up to `maxRetries` from config;
+   * other `4xx` are not retried. When `retry` is `false` or omitted, a single attempt is made.
+   */
+  async request(method, url, options) {
+    const instance = this.getClient(options.api_name);
+    const resolvedHeaders = resolveRequestHeaders(
+      this._config,
+      options.headers,
+      options.extraHeaders
+    );
+    const req = {
+      method,
+      url,
+      params: options.params ?? void 0,
+      headers: resolvedHeaders,
+      data: options.data
+    };
+    if (!options.retry) {
+      const { data } = await instance.request(req);
+      return data.data;
+    }
+    const response = await this.retryRequest(
+      () => instance.request(req),
+      options
+    );
+    return response.data.data;
+  }
+  async retryRequest(requestFn, options) {
+    for (let attempt = 0; attempt <= this._config.maxRetries; attempt++) {
+      try {
+        const response = await requestFn();
+        if (!isRetryableStatusCode(response.status)) return response;
+        if (attempt >= this._config.maxRetries) {
+          throw new AxiosError(
+            `Retryable HTTP ${response.status}`,
+            String(response.status),
+            response.config,
+            void 0,
+            response
+          );
+        }
+        await sleep(computeBackoffMs(attempt + 1, this._config));
+      } catch (err) {
+        const shouldRetry = isRetryableAxiosFailure(err) && attempt < this._config.maxRetries;
+        if (shouldRetry) {
+          await sleep(computeBackoffMs(attempt + 1, this._config));
+          continue;
+        }
+        const error = qatiApiErrorFromRequestFailure(err);
+        options.deadLetterCallback?.(options.data, error);
+        throw error;
+      }
+    }
+    throw new QatiConfigError("Unreachable retry exhaustion");
+  }
+};
+
+// src/shared/utils/date.utils.ts
+function dateToIso8601(value) {
+  if (!value) return;
+  if (value instanceof Date) return value.toISOString();
+  return value;
+}
+
+// src/resources/advisory-resource.ts
+var AdvisoryResource = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  _http;
+  apiName = "query_api";
+  /**
+   * Lists persisted advisories for the tenant (`GET /v1/advisories`).
+   *
+   * @param entityKey - Scoped entity key: uppercase type, colon, opaque id (e.g. `USER:20`). Must match server expectations for entity keys.
+   * @param advisoryType - Filter by advisory `type` (see {@link AdvisoryType}).
+   * @param severity - Filter by `severity` tier (see {@link AdvisorySeverity}).
+   * @param options - Optional time range and pagination ({@link ListAdvisoriesOptions}).
+   * @returns: {@link AdvisoryListResponse} including `total_count`, `limit`, and `offset` echo from the API.
+   * ```
+   */
+  async listAdvisories(entityKey, advisoryType, severity, options) {
+    return this._http.request("GET", "/v1/advisories", {
+      api_name: this.apiName,
+      params: {
+        severity,
+        entity_key: entityKey,
+        advisory_type: advisoryType,
+        since: options?.since ? dateToIso8601(options.since) : void 0,
+        until: options?.until ? dateToIso8601(options.until) : void 0,
+        limit: options?.limit,
+        offset: options?.offset
+      }
+    });
+  }
+};
+
+// src/shared/utils/mutext.utils.ts
+var createMutex = () => {
+  let tail = Promise.resolve();
+  return async (fn) => {
+    const result = tail.then(() => fn());
+    tail = result.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return result;
+  };
+};
+var BatchBufferOptionsSchema = z.object({
+  batchSize: z.number().int().min(1).default(100),
+  flushIntervalSeconds: z.number().min(0).default(5)
+});
+
+// src/shared/buffering/auto-flush-batch-buffer.ts
+var AutoFlushBatchBuffer = class {
+  /**
+   * Serializes buffer/timer mutations so enqueue, flush, and timer fire never overlap.
+   */
+  runExclusive = createMutex();
+  queue = [];
+  flushBatch;
+  batchSize;
+  flushIntervalMs;
+  pendingTimer = null;
+  timerSequence = 0;
+  constructor(flushBatch, options) {
+    this.flushBatch = flushBatch;
+    const validatedOptions = BatchBufferOptionsSchema.parse(options);
+    this.batchSize = validatedOptions.batchSize;
+    this.flushIntervalMs = validatedOptions.flushIntervalSeconds * 1e3;
+  }
+  async enqueue(item) {
+    let batchToFlush = [];
+    await this.runExclusive(async () => {
+      this.queue.push(item);
+      if (this.queue.length >= this.batchSize) {
+        this.cancelTimer();
+        batchToFlush = this.getItemsToSend();
+      }
+      if (this.queue.length === 1) this.scheduleTimer();
+    });
+    if (batchToFlush.length)
+      await this.executeFlush(batchToFlush).catch(() => {
+      });
+    return "queued";
+  }
+  /**
+   * Flush all buffered items immediately.
+   * @returns The return value of {@link flushBatch}, or `{}` if the buffer was empty.
+   */
+  async flush() {
+    let batch = [];
+    await this.runExclusive(async () => {
+      this.cancelTimer();
+      batch = this.getItemsToSend();
+    });
+    if (!batch.length) return {};
+    return this.executeFlush(batch);
+  }
+  /**
+   * Best-effort flush for shutdown; logs and drops items on failure.
+   */
+  async shutdown() {
+    let batch = [];
+    await this.runExclusive(async () => {
+      this.cancelTimer();
+      batch = this.getItemsToSend();
+    });
+    if (!batch.length) return;
+    await this.executeFlush(batch).catch(() => {
+    });
+  }
+  /**
+   * The number of items currently in the buffer.
+   */
+  get pendingCount() {
+    return this.queue.length;
+  }
+  getItemsToSend() {
+    if (!this.queue.length) return [];
+    return this.queue.splice(0, this.queue.length);
+  }
+  cancelTimer() {
+    if (!this.pendingTimer) return;
+    clearTimeout(this.pendingTimer.handleTimer);
+    this.pendingTimer = null;
+  }
+  scheduleTimer() {
+    this.cancelTimer();
+    const seq = ++this.timerSequence;
+    const handleTimer = setTimeout(
+      () => this.timerFire(seq),
+      this.flushIntervalMs
+    );
+    this.pendingTimer = { sequence: seq, handleTimer };
+  }
+  async timerFire(seq) {
+    let batch = [];
+    await this.runExclusive(async () => {
+      if (this.pendingTimer?.sequence !== seq) return;
+      this.pendingTimer = null;
+      batch = this.getItemsToSend();
+    });
+    if (!batch.length) return;
+    await this.executeFlush(batch).catch(() => {
+    });
+  }
+  async executeFlush(batch) {
+    const result = await this.flushBatch(batch);
+    return result ?? {};
+  }
+};
+
+// src/resources/event-resource.ts
+var EventResource = class {
+  _http;
+  _buffer;
+  apiName = "ingestion_api";
+  _deadLetterCallback;
+  /**
+   * @param http - Shared HTTP client (supplies config defaults and axios instance for `ingestion_api`).
+   * @param options - Optional buffer sizing overrides ({@link EventResourceOptions}).
+   */
+  constructor(http, options = {}) {
+    this._http = http;
+    this._buffer = new AutoFlushBatchBuffer((batch) => this.postBatch(batch), {
+      batchSize: options.batchSize ?? http.config.ingestionBatchSize,
+      flushIntervalSeconds: options.flushIntervalSeconds ?? http.config.ingestionFlushIntervalSeconds
+    });
+  }
+  /**
+   * Registers a hook invoked after retries are exhausted for a failed batch POST so you can land failures on a DLQ or metric pipeline. Must stay non-throwing — swallow errors inside your handler.
+   */
+  onIngestionFailure(callback) {
+    this._deadLetterCallback = callback;
+    return this;
+  }
+  /**
+   * Accepts one normalized event into the in-memory buffer and returns immediately with **`queued`** — HTTP happens on flush timers or explicit `flush`, not inline with `enqueue`.
+   */
+  async enqueue(event) {
+    return await this._buffer.enqueue(event);
+  }
+  /**
+   * Sends whatever is buffered **now** as one ingestion batch (or resolves immediately with an empty-shaped result when nothing was pending).
+   */
+  async flush() {
+    return this._buffer.flush();
+  }
+  /**
+   * Best-effort final flush then tears down timers — typically reached via `Client.close()` during graceful shutdown so late telemetry is not dropped on SIGTERM.
+   */
+  async shutdown() {
+    await this._buffer.shutdown();
+  }
+  /**
+   * Live count of rows waiting in the in-memory buffer (not yet acknowledged by the ingestion API).
+   */
+  get pendingCount() {
+    return this._buffer.pendingCount;
+  }
+  async postBatch(batch) {
+    return this._http.request("POST", "/v1/events:batch", {
+      api_name: this.apiName,
+      data: { events: batch },
+      retry: true,
+      deadLetterCallback: this._deadLetterCallback
+    });
+  }
+};
+
+// src/resources/explain-resource.ts
+var ExplainResource = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  _http;
+  apiName = "query_api";
+  /**
+   * Fetches composite explain for one entity (`GET /v1/explain/{entity_key}`).
+   *
+   * @param entityKey - URL-encoded path segment: uppercase entity type, colon, id (e.g. `USER:user-123`). Must not contain raw `/` (caller passes logical key; SDK encodes for HTTP).
+   * @param atTimestamp - Optional “as of” time (`Date` or ISO-8601 string). Omitted means server default (typically “now”).
+   * @param topDominantNeighbors - Optional cap on dominant neighbor rows returned.
+   * @param topEvents - Optional cap on top contributing events returned.
+   * @returns {@link ExplainResponse} (closure score, risk tier, top events, neighbours, active advisories).
+   * @example
+   * ```ts
+   * const x = await client.explain.get('USER:alice', new Date(), 5, 10);
+   * ```
+   */
+  async get(entityKey, atTimestamp, topDominantNeighbors, topEvents) {
+    return await this._http.request(
+      "GET",
+      `/v1/explain/${encodeURIComponent(entityKey)}`,
+      {
+        api_name: this.apiName,
+        params: {
+          at_timestamp: dateToIso8601(atTimestamp),
+          top_dominant_neighbors: topDominantNeighbors,
+          top_events: topEvents
+        }
+      }
+    );
+  }
+};
+
+// src/resources/tenant-resource.ts
+var TenantResource = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  _http;
+  apiName = "query_api";
+  /**
+   * Confirms whether the **`x-tenant-api-key`** presented by this client is accepted by the platform and returns the opaqu
+   * e **tenant partition id** bound to that key.
+   * Use at process startup so misconfigured keys fail fast before trust-state or explain traffic.
+   *
+   * @returns: {@link VerifyCredentialsResponse}
+   */
+  async verifyCredentials() {
+    return this._http.request(
+      "GET",
+      "/v1/tenants/verify-credentials",
+      { api_name: this.apiName }
+    );
+  }
+};
+
+// src/resources/trust-state-resource.ts
+var TrustStateResource = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  _http;
+  apiName = "query_api";
+  /**
+   * Fetches the latest trust state for one entity.
+   *
+   * @param entityType - Lowercase entity class: `user`, `device`, `account`, `model`, `session`, or `service` (see {@link EntityTypeLowerCase}).
+   * @param entityId - Id for the entity(Required)
+   * @param options - Optional contributor limits/window.
+   * @returns {@link TrustState} including `current_closure_score`, `risk_tier`, and `top_contributors`.
+   */
+  async getTrustState(entityType, entityId, options = {}) {
+    return await this._http.request(
+      "GET",
+      `/v1/entities/${entityType}/${encodeURIComponent(entityId)}/trust-state`,
+      {
+        api_name: this.apiName,
+        params: {
+          top_contributors_limit: options.topContributorsLimit ?? 5,
+          top_contributors_window_minutes: options.topContributorsWindowMinutes
+        }
+      }
+    );
+  }
+  /**
+   * Fetches trust states for many entities in one request.
+   *
+   * @param entityType - Lowercase entity class: `user`, `device`, `account`, `model`, `session`, or `service` (see {@link EntityTypeLowerCase}).
+   * @param entityIds - Distinct ids to query. Prefer length ≤ 100 or the server may reject the request.
+   * @param options - Optional contributor limits/window.
+   * @returns Array of {@link TrustState} in server-defined order; empty array when `entityIds` is empty.
+   */
+  async getTrustStates(entityType, entityIds, options = {}) {
+    if (!entityIds.length) return [];
+    return await this._http.request("GET", "/v1/trust-states", {
+      api_name: this.apiName,
+      params: {
+        entity_type: entityType,
+        entity_ids: entityIds.join(","),
+        top_contributors_limit: options.topContributorsLimit ?? 5,
+        top_contributors_window_minutes: options.topContributorsWindowMinutes
+      }
+    });
+  }
+};
+
+// src/client/client.ts
+var Client = class extends HttpClient {
+  _tenant;
+  _trustState;
+  _advisory;
+  _explain;
+  _events;
+  /**
+   * @param config - Resolved SDK configuration (typically `session.config`).
+   * @param axiosInstances - Optional per-API `axios` instances; see {@link Session#createClient}.
+   * @param eventResourceOptions - Optional overrides for buffered ingestion (`onDeadLetter`, batch sizing).
+   */
+  constructor(config, axiosInstances) {
+    super(config, axiosInstances);
+    this._tenant = new TenantResource(this);
+    this._trustState = new TrustStateResource(this);
+    this._advisory = new AdvisoryResource(this);
+    this._explain = new ExplainResource(this);
+    this._events = new EventResource(this);
+  }
+  /**
+   * Tenant API surface (credentials verification).
+   *
+   * @returns {@link TenantResource} bound to this client’s Query API base URL and tenant key.
+   */
+  get tenant() {
+    return this._tenant;
+  }
+  /**
+   * Trust scores and contributors for entities.
+   *
+   * @returns {@link TrustStateResource} for the Query API.
+   */
+  get trustState() {
+    return this._trustState;
+  }
+  /**
+   * List persisted advisories for an entity.
+   *
+   * @returns {@link AdvisoryResource} for the Query API.
+   */
+  get advisory() {
+    return this._advisory;
+  }
+  /**
+   * Composite explain / attribution for an entity key.
+   *
+   * @returns {@link ExplainResource} for the Query API.
+   */
+  get explain() {
+    return this._explain;
+  }
+  /**
+   * Buffered ingestion of `RawEventRequest` payloads to the ingestion API (`POST /v1/events:batch`).
+   *
+   * @returns {@link EventResource} for the Query API.
+   */
+  get events() {
+    return this._events;
+  }
+  /**
+   * Flushes the event ingestion buffer (best-effort), then shuts down the batch scheduler.
+   * Call this on process shutdown so queued events are not lost.
+   *
+   * @returns Resolves when {@link EventResource#shutdown} completes.
+   */
+  async close() {
+    await this._events.shutdown();
+  }
+};
+
+// src/session.ts
+var Session = class {
+  _config;
+  constructor(config) {
+    this._config = resolveQatiConfig(config);
+  }
+  /**
+   * Resolved, validated configuration.
+   */
+  get config() {
+    return this._config;
+  }
+  /**
+   * Creates an API {@link Client} using this session’s resolved config.
+   *
+   * @param httpClients - Optional injected `axios` instances keyed by `query_api` / `ingestion_api` (testing, proxies, interceptors).
+   * @returns A new {@link Client} (not a singleton).
+   * @example
+   * ```typescript
+   * const session = new Session();
+   * const client = session.createClient();
+   * const explained = await client.explain.get('USER:user-123');
+   * console.log(explained.closure_score);
+   * ```
+   */
+  createClient(httpClients) {
+    return new Client(this._config, httpClients ?? {});
+  }
+};
+
+// src/shared/types/signal-type.ts
+var SIGNAL_TYPES = [
+  "TRANSACTION",
+  "AUTH",
+  "BEHAVIOR",
+  "SYSTEM_TELEMETRY",
+  "MODEL_OUTPUT",
+  "ANOMALY_FLAG",
+  "NETWORK_EVENT"
+];
+
+// src/shared/types/provenance-mode.ts
+var PROVENANCE_MODES = [
+  "DETERMINISTIC",
+  "EXTERNAL_RNG",
+  "ATTESTED"
+];
+
+// src/v1/schemas/provenance.ts
+var ProvenanceSchema = z.object({
+  mode: z.enum(PROVENANCE_MODES).optional(),
+  source_id: z.string().optional(),
+  epoch_counter: z.number().int().nonnegative().optional(),
+  health_summary: z.union([z.string(), z.record(z.unknown())]).optional()
+});
+var IntegritySchema = z.object({
+  hash: z.string().optional(),
+  signature: z.string().optional()
+});
+var EventPrincipalSchema = z.object({
+  user_id: z.string().min(1).optional(),
+  account_id: z.string().min(1).optional(),
+  device_id: z.string().min(1).optional(),
+  session_id: z.string().min(1).optional(),
+  model_id: z.string().min(1).optional(),
+  service_id: z.string().min(1).optional()
+});
+
+// src/v1/schemas/raw-event.ts
+var BaseEventSchema = z.object({
+  tenant_id: z.string().describe("Tenant partition key (required)."),
+  signal_version: z.string().describe("Schema version (e.g. v1)."),
+  signal_type: z.enum(SIGNAL_TYPES).describe("Type of signal."),
+  signal_payload: z.record(z.any()).describe("Payload validated per signal_type."),
+  principal: EventPrincipalSchema,
+  timestamp: z.string().datetime().default((/* @__PURE__ */ new Date()).toISOString()).optional().describe("Event / provenance record time when provided by the client."),
+  confidence_hint: z.number().max(1).min(0).optional().describe("Scalar in [0,1]; how trustworthy this event is."),
+  provenance: ProvenanceSchema.optional().describe(
+    "Optional provenance (mode, source_id, epoch_counter, health_summary)."
+  ),
+  integrity: IntegritySchema.optional()
+});
+var RawEventRequestSchema = z.object({
+  tenant_id: z.string().describe("Tenant partition key (required)."),
+  payload: z.record(z.any()).describe("JSON payload (stored as JSONB in DB).")
+});
+
+// src/v1/schemas/signal-payload.ts
+var TransactionSignalPayloadSchema = z.object({
+  amount: z.number().nonnegative().default(0),
+  amount_minor: z.number().int().nonnegative().nullable().optional(),
+  amount_usd: z.number().nonnegative().nullable().optional(),
+  currency: z.string().nullable().optional(),
+  merchant_category: z.string().nullable().optional(),
+  merchant_id: z.string().nullable().optional(),
+  channel: z.string().nullable().optional(),
+  country: z.string().nullable().optional(),
+  velocity: z.number().nonnegative().nullable().optional(),
+  external_anomaly_score: z.number().nullable().optional(),
+  geo_distance: z.number().nonnegative().nullable().optional(),
+  geo_distance_km: z.number().nonnegative().nullable().optional(),
+  records_accessed: z.number().int().nonnegative().nullable().optional(),
+  baseline_records_accessed: z.number().int().nonnegative().nullable().optional(),
+  sensitivity_level: z.string().nullable().optional(),
+  export_count: z.number().int().nonnegative().nullable().optional(),
+  bulk_export: z.boolean().optional().default(false),
+  contains_phi: z.boolean().optional().default(false),
+  control_command: z.string().nullable().optional(),
+  authorized: z.boolean().nullable().optional(),
+  safety_critical: z.boolean().optional().default(false)
+});
+var AuthSignalPayloadSchema = z.object({
+  result: z.string().nullable().optional(),
+  auth_method: z.string().nullable().optional(),
+  mfa_used: z.boolean().nullable().optional(),
+  mfa_bypassed: z.boolean().optional().default(false),
+  failed_attempts: z.number().int().nonnegative().optional().default(0),
+  ip: z.string().nullable().optional(),
+  country: z.string().nullable().optional(),
+  user_agent: z.string().nullable().optional(),
+  unusual_location: z.boolean().optional().default(false),
+  after_hours_login: z.boolean().optional().default(false)
+});
+var ModelOutputSignalPayloadSchema = z.object({
+  missing_citations_rate: z.number().min(0).max(1).nullable().optional(),
+  citation_rate: z.number().min(0).max(1).nullable().optional(),
+  expected_citation_rate: z.number().min(0).max(1).nullable().optional(),
+  policy_violations: z.number().int().nonnegative().optional().default(0),
+  policy_violation_rate: z.number().min(0).max(1).nullable().optional(),
+  tool_call_inconsistency: z.number().min(0).max(1).optional().default(0),
+  tool_inconsistency_rate: z.number().min(0).max(1).nullable().optional(),
+  tool_miss_rate: z.number().min(0).max(1).nullable().optional(),
+  eval_window_n: z.number().int().min(1).nullable().optional()
+});
+var SystemTelemetrySignalPayloadSchema = z.object({
+  metric_name: z.string().nullable().optional(),
+  value: z.number().nullable().optional(),
+  baseline: z.number().nullable().optional(),
+  window_seconds: z.number().int().min(1).nullable().optional(),
+  error_rate: z.number().min(0).max(1).optional().default(0),
+  baseline_error_rate: z.number().min(0).max(1).nullable().optional(),
+  unusual_auth_rate: z.number().min(0).max(1).optional().default(0),
+  firmware_hash_changed: z.boolean().optional().default(false),
+  expected_hash_match: z.boolean().nullable().optional(),
+  sensor_deviation_score: z.number().min(0).max(1).nullable().optional()
+});
+var AnomalyFlagSignalPayloadSchema = z.object({
+  severity: z.number().min(0).max(1)
+});
+var BehaviorSignalPayloadSchema = z.object({
+  deviation_score: z.number().min(0).max(1)
+});
+var NetworkSignalPayloadSchema = z.object({
+  ip: z.string().nullable().optional(),
+  asn: z.string().nullable().optional(),
+  reputation_score: z.number().min(0).max(1).nullable().optional(),
+  threat_score: z.number().min(0).max(1).nullable().optional(),
+  is_datacenter: z.boolean().nullable().optional(),
+  is_untrusted_segment: z.boolean().optional().default(false),
+  asn_reputation: z.number().min(0).max(1).nullable().optional()
+});
+BaseEventSchema.extend({
+  signal_payload: TransactionSignalPayloadSchema
+});
+BaseEventSchema.extend({
+  signal_payload: AnomalyFlagSignalPayloadSchema
+});
+BaseEventSchema.extend({
+  signal_payload: AuthSignalPayloadSchema
+});
+BaseEventSchema.extend({
+  signal_payload: BehaviorSignalPayloadSchema
+});
+BaseEventSchema.extend({
+  signal_payload: NetworkSignalPayloadSchema
+});
+BaseEventSchema.extend({
+  signal_payload: ModelOutputSignalPayloadSchema
+});
+BaseEventSchema.extend({
+  signal_payload: SystemTelemetrySignalPayloadSchema
+});
+
+// src/v1/builders/event-builder.ts
+var buildRawEventPayload = (event, signalPayload, signalType) => {
+  const rawEventPayload = {
+    timestamp: event.timestamp,
+    provenance: event.provenance,
+    principal: event.principal,
+    confidence_hint: event.confidence_hint,
+    tenant_id: event.tenant_id,
+    signal_version: "v1",
+    signal_type: signalType,
+    signal_payload: signalPayload,
+    integrity: event.integrity
+  };
+  return BaseEventSchema.parse(rawEventPayload);
+};
+var buildRawEventRequest = (event, signalPayload, signalType) => {
+  const rawEventPayload = buildRawEventPayload(
+    event,
+    signalPayload,
+    signalType
+  );
+  return {
+    tenant_id: event.tenant_id,
+    payload: rawEventPayload
+  };
+};
+var createAuthEvent = (event) => {
+  const signalPayload = AuthSignalPayloadSchema.parse(event.signal_payload);
+  return buildRawEventRequest(event, signalPayload, "AUTH");
+};
+function createTransactionEvent(event) {
+  const signalPayload = TransactionSignalPayloadSchema.parse(
+    event.signal_payload
+  );
+  return buildRawEventRequest(event, signalPayload, "TRANSACTION");
+}
+var createAnomalyFlagEvent = (event) => {
+  const signalPayload = AnomalyFlagSignalPayloadSchema.parse(
+    event.signal_payload
+  );
+  return buildRawEventRequest(event, signalPayload, "ANOMALY_FLAG");
+};
+var createBehaviorEvent = (event) => {
+  const signalPayload = BehaviorSignalPayloadSchema.parse(event.signal_payload);
+  return buildRawEventRequest(event, signalPayload, "BEHAVIOR");
+};
+var createNetworkEvent = (event) => {
+  const signalPayload = NetworkSignalPayloadSchema.parse(event.signal_payload);
+  return buildRawEventRequest(event, signalPayload, "NETWORK_EVENT");
+};
+var createModelOutputEvent = (event) => {
+  const signalPayload = ModelOutputSignalPayloadSchema.parse(
+    event.signal_payload
+  );
+  return buildRawEventRequest(event, signalPayload, "MODEL_OUTPUT");
+};
+var createSystemTelemetryEvent = (event) => {
+  const signalPayload = SystemTelemetrySignalPayloadSchema.parse(
+    event.signal_payload
+  );
+  return buildRawEventRequest(event, signalPayload, "SYSTEM_TELEMETRY");
+};
+
+export { API_REGISTRY, QatiAPIError, QatiAuthError, QatiConfigError, QatiNotFoundError, QatiRateLimitError, QatiSDKError, QatiServerError, RawEventRequestSchema, Session, baseUrlFor, createAnomalyFlagEvent, createAuthEvent, createBehaviorEvent, createModelOutputEvent, createNetworkEvent, createSystemTelemetryEvent, createTransactionEvent, parseQatiConfig, resolveQatiConfig };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map