@vinaverse/server 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# @vinaverse/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vinaverse for Node backends: call the Vinaverse API typed with a service key, verify webhooks into typed events,
+and serve the tools the agent calls with the contract enforced, with adapters for AWS Lambda, Express, Fastify, Hono
+and any Fetch API runtime. Runs on Node 18+, AWS Lambda and edge runtimes: it uses Web APIs only (Web Crypto, never a
+Node-only API).
+
+Pre-release (`0.x`): it targets the contract named in `CONTRACT`. Its types need TypeScript 5.0 or newer (the gate
+compiles a consumer against the published declarations with 5.0). Errors it throws carry a `name`
+(`WebCryptoUnavailableError`, `RawBodyRequiredError`): check `error.name`, since each entry point and module format
+has its own copy of the class.
+
+## Verify a delivery
+
+```ts
+import { verifyWebhook } from '@vinaverse/server';
+
+const result = await verifyWebhook({
+  rawBody, // the body exactly as received: string, Uint8Array/Buffer or ArrayBuffer
+  header: request.headers['vinaverse-signature'],
+  secret: process.env.VINAVERSE_WEBHOOK_SECRET, // the whole vv_whsec_… value; two while rotating
+});
+
+if (!result.ok) return reply(400); // result.error.code says why
+if (result.kind === 'event') {
+  switch (result.event.type) {
+    case 'conversation.completed':
+      result.event.data.answers; // typed ConversationState
+      break;
+  }
+}
+return reply(200); // also for 'test' (a Studio test delivery) and 'unrecognized' (a newer event type)
+```
+
+Deliveries are at least once: deduplicate on `event.id`. Answer within 5 seconds and do the work afterwards.
+
+## Adapters
+
+Each answers 200 when handled, 400 when refused, 413 over `maxBodyBytes` (default 1 MiB), and lets your handler's
+error through so Vinaverse retries.
+
+```ts
+// AWS Lambda: API Gateway REST (v1), HTTP API (v2) or a function URL; base64 bodies handled
+import { createLambdaWebhookHandler } from '@vinaverse/server/lambda';
+export const handler = createLambdaWebhookHandler({ secret, onEvent: async (event) => { /* … */ } });
+
+// Express: mount before express.json() (or behind express.raw({ type: 'application/json' }))
+import { vinaverseWebhook } from '@vinaverse/server/express';
+app.post('/webhooks/vinaverse', vinaverseWebhook({ secret, onEvent }));
+
+// Fastify: the plugin reads its route's body raw; the rest of the app keeps its JSON parser
+import { vinaverseWebhookPlugin } from '@vinaverse/server/fastify';
+await app.register(vinaverseWebhookPlugin({ path: '/webhooks/vinaverse', secret, onEvent }));
+
+// Hono
+import { vinaverseWebhook } from '@vinaverse/server/hono';
+app.post('/webhooks/vinaverse', vinaverseWebhook({ secret, onEvent }));
+
+// Next.js route handlers, Cloudflare Workers, Deno, Bun: any Request → Response runtime
+import { createFetchWebhookHandler } from '@vinaverse/server';
+export const POST = createFetchWebhookHandler({ secret, onEvent });
+```
+
+`onTest`, `onUnrecognized` and `onRejected` are optional.
+
+## Order a conversation's states
+
+```ts
+import { applyConversationState, missingSequences } from '@vinaverse/server';
+
+const { record, action } = applyConversationState(stored, event.data);
+// action: 'apply' or 'stale' (an equal or lower sequence, even under a new envelope id)
+// record: what to store: { state, seen, fullReadNeeded }. fullReadNeeded: the webhook left out the answers
+// (over 64 KB); read GET /v1/conversations/{id}. missingSequences(record): the states still to come.
+// Deduplicate deliveries on event.id first; ConversationReceiver does all of it in memory, for one process.
+```
+
+## Serve your tools
+
+```ts
+import { createToolProvider, MemoryNonceStore, MemoryIdempotencyStore, ToolRefusal } from '@vinaverse/server';
+import { redisNonceStore, redisIdempotencyStore } from '@vinaverse/server/stores'; // shared, for several instances
+
+const tools = createToolProvider({
+  secret: process.env.VINAVERSE_TOOL_SECRET, // the whole tool signing secret; two while rotating
+  nonces: new MemoryNonceStore(),            // or redisNonceStore({ command: (args) => redis.sendCommand(args) })
+  idempotency: new MemoryIdempotencyStore(), // or the matching shared store
+  basePath: '/api/v2/ai',                    // the path of the tool base URL registered in Studio
+  authenticate: async (token) => (await verifyMyToken(token)) ?? throwExpired(), // your principal
+  handlers: {
+    get_flow_definition: ({ params, query }) => myFlows.definition(params.flow, query.version),
+    submit_flow: async ({ params, body, principal }) => {
+      const problem = await myFlows.check(params.flow, body);
+      if (problem) throw ToolRefusal.flowRefused(problem.code, problem.questionId);
+      await myFlows.store(principal, body); // returning nothing accepts it
+    },
+    create_handoff: ({ body, principal }) => mySupport.openTicket(principal, body),
+  },
+  leaseSeconds: 60,                          // above the longest a handler can run
+  onRefused: (reason) => log.warn({ reason }, 'tool call signature refused'),
+  onError: (error, operation) => log.error({ error, operation }),
+});
+```
+
+A `submit_flow` handler refuses only with `ToolRefusal.flowRefused` (any other 422 is answered as a 500), and every
+handler validates what it acts on. Idempotent answers are kept under a SHA-256 fingerprint of the request, never the
+request itself; `scope(principal)` keeps them apart per tenant or environment.
+
+Then mount it: `createLambdaToolHandler(tools)` (`/lambda`), `app.use('/api/v2/ai', vinaverseTools(tools))`
+(`/express`), `vinaverseToolsPlugin({ provider: tools, basePath })` (`/fastify`), `vinaverseTools(tools)` (`/hono`)
+or `createFetchToolHandler(tools)`. Signatures, nonces, token presence, sizes, refusals and idempotent submissions,
+proposals and handoffs are handled; your handlers decide what an answer or a ticket means. Details:
+[docs/architecture/tools.md](../../docs/architecture/tools.md).
+
+## Test your route
+
+```ts
+import { signToolCall, signWebhook } from '@vinaverse/server/testing';
+const header = await signWebhook({ body, secret }); // the Vinaverse-Signature value Vinaverse would send
+const toolHeader = await signToolCall({ secret, method: 'POST', target, token, body }); // a tool call's
+```
+
+## The Vinaverse API (`@vinaverse/server/api`)
+
+Typed calls to the Vinaverse API with a service key, generated from the pinned public contract.
+
+```ts
+import { createApiClient, VinaverseApiError } from '@vinaverse/server/api';
+
+const vinaverse = createApiClient({ apiKey: process.env.VINAVERSE_API_KEY }); // vv_sk_<mock|dev|live>_…
+
+// Your app asks your backend for a session; give it the session's id, URLs and client_secret only.
+const session = await vinaverse.sessions.create({ agent: 'intake', subject, tool_access }); // your agent's id
+
+try {
+  await vinaverse.moderation.createJob({ policy: 'default', items });
+} catch (error) {
+  if (error instanceof VinaverseApiError && error.code === 'invalid_request') console.log(error.errors);
+}
+```
+
+- **Idempotency keys** are added to the calls that take one (`sessions.create`, `moderation.createJob`,
+  `media.createJob`, `documentChecks.create`, `subjects.erase`); pass `{ idempotencyKey }` to use your own.
+- **Retries are safe:** a `429` is retried after its `Retry-After`; a `5xx`, a retryable problem, a timeout or a
+  network error is retried only for a read or a call with an idempotency key. Default 2 retries, 30 s timeout per try
+  (reading the body included), and a `Retry-After` over 30 s is not waited for (`maxRetries`, `timeout`,
+  `maxRetryDelay`, checked when the client is made).
+- **Trying again yourself:** when a keyed call still fails (`VinaverseTimeoutError`, `VinaverseNetworkError`, or a
+  retryable `VinaverseApiError`), its error carries `idempotencyKey`. Send the call again later with
+  `{ idempotencyKey: error.idempotencyKey }`: the API does it once, however many times it was sent.
+- **Aborts:** pass `{ signal }`; aborting stops the call at once, during a try, a body read or a wait between tries,
+  and an already aborted signal sends nothing.
+- **Refusals throw `VinaverseApiError`**, with the problem's `status`, `code`, `retryable`, `requestId`, `retryAfter`
+  and, for `invalid_request`, the field `errors`.
+- **Every operation** is also on `vinaverse.api`, the typed openapi-fetch client (`api.GET('/v1/usage')`).
+- **Backend only.** The client refuses a client secret, and refuses to start in a browser or in React Native: a
+  service key there ships to everyone who loads the app. Apps use `@vinaverse/client` with the session's client secret.
+- The base URL follows the key: `https://api.vinaverse.com` for a live key, `https://api-dev.vinaverse.com` for mock
+  and dev keys. A `baseUrl` of your own must be `https:` (or `http:` on `localhost` for tests), and redirects are
+  refused: a service key never travels in clear or follows a redirect. Every request, the raw `api` client's included,
+  goes to that origin only. In the mock environment, the `Vinaverse-Mock-Scenario` header (`headers`
+  option) provokes a `429` or a `503` to test your handling.
+
+Details: [docs/architecture/webhooks.md](../../docs/architecture/webhooks.md),
+[docs/architecture/tools.md](../../docs/architecture/tools.md) and
+[docs/architecture/api-client.md](../../docs/architecture/api-client.md). Licence: Apache-2.0.

package/dist/api.cjs

@@ -0,0 +1,528 @@
+'use strict';
+
+var createClient = require('openapi-fetch');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var createClient__default = /*#__PURE__*/_interopDefault(createClient);
+
+// src/api/client.ts
+
+// src/api/errors.ts
+var VinaverseApiError = class extends Error {
+  name = "VinaverseApiError";
+  status;
+  /** The problem's code (`invalid_request`, `rate_limited`, …), or `http_<status>` when the body was not a problem. */
+  code;
+  /** Whether the same call may succeed later: the problem's `retryable`, else true for 429 and 5xx. */
+  retryable;
+  /** `Vinaverse-Request-Id`, or the problem's `request_id`. */
+  requestId;
+  /** `Retry-After`, in seconds, when the API sent one. */
+  retryAfter;
+  /** For `invalid_request`: the fields refused, as JSON Pointers into the request. */
+  errors;
+  /** The problem as sent, or undefined when the body was not one. */
+  problem;
+  /** The `Idempotency-Key` the call carried: send the same call again with it to have it done once. */
+  idempotencyKey;
+  constructor(init) {
+    const { status, problem } = init;
+    super(
+      problem ? `${problem.title} (${problem.code})${problem.detail ? `: ${problem.detail}` : ""}` : `The Vinaverse API answered HTTP ${status}.`
+    );
+    this.idempotencyKey = init.idempotencyKey;
+    this.status = status;
+    this.problem = problem;
+    this.code = problem?.code ?? `http_${status}`;
+    this.retryable = problem?.retryable ?? (status === 429 || status >= 500);
+    this.requestId = init.requestId ?? problem?.request_id;
+    this.retryAfter = init.retryAfter;
+    this.errors = problem?.errors ?? [];
+  }
+};
+function apiError(response, body, idempotencyKey) {
+  return new VinaverseApiError({
+    status: response.status,
+    problem: isProblem(body) ? body : void 0,
+    requestId: response.headers.get("vinaverse-request-id") ?? void 0,
+    retryAfter: retryAfterSeconds(response),
+    idempotencyKey
+  });
+}
+function retryAfterSeconds(response, now = Date.now) {
+  const value = response.headers.get("retry-after");
+  if (value === null || value.trim() === "") return void 0;
+  if (/^\d+$/.test(value.trim())) return Number(value.trim());
+  const at = Date.parse(value);
+  return Number.isNaN(at) ? void 0 : Math.max(0, Math.ceil((at - now()) / 1e3));
+}
+function isProblem(body) {
+  if (typeof body !== "object" || body === null) return false;
+  const b = body;
+  return typeof b.code === "string" && typeof b.status === "number";
+}
+
+// src/api/random.ts
+var fromNode;
+async function randomUUID() {
+  const global = globalThis.crypto;
+  if (global?.randomUUID) return global.randomUUID();
+  const specifier = ["node", "crypto"].join(":");
+  fromNode ??= import(
+    /* webpackIgnore: true */
+    /* @vite-ignore */
+    specifier
+  ).then((mod) => mod.randomUUID);
+  return (await fromNode)();
+}
+
+// src/api/retry.ts
+var IDEMPOTENT = /* @__PURE__ */ new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+var NULL_BODY = /* @__PURE__ */ new Set([101, 204, 205, 304]);
+var MAX_REFUSAL_BYTES = 64 * 1024;
+var VinaverseTimeoutError = class extends Error {
+  name = "VinaverseTimeoutError";
+  idempotencyKey;
+  constructor(ms, idempotencyKey) {
+    super(`The Vinaverse API did not answer within ${ms} ms.`);
+    this.idempotencyKey = idempotencyKey;
+  }
+};
+var VinaverseNetworkError = class extends Error {
+  name = "VinaverseNetworkError";
+  idempotencyKey;
+  constructor(cause, idempotencyKey) {
+    super(
+      `The Vinaverse API could not be reached: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+    this.idempotencyKey = idempotencyKey;
+  }
+};
+var MAX_TIMER_MS = 2147483647;
+function retryingFetch(fetchFn, options = {}, guard = () => {
+}) {
+  const maxRetries = check(
+    "maxRetries",
+    options.maxRetries ?? 2,
+    (n) => Number.isSafeInteger(n) && n >= 0
+  );
+  const maxDelay = check(
+    "maxRetryDelay",
+    options.maxRetryDelay ?? 30,
+    (n) => Number.isFinite(n) && n >= 0 && n * 1e3 <= MAX_TIMER_MS
+  ) * 1e3;
+  const timeout = check(
+    "timeout",
+    options.timeout ?? 3e4,
+    (n) => Number.isFinite(n) && n > 0 && n <= MAX_TIMER_MS
+  );
+  const sleep = options.sleep;
+  const random = options.random ?? Math.random;
+  return async (request) => {
+    guard(request.url);
+    const signal = request.signal;
+    const key = request.headers.get("idempotency-key") ?? void 0;
+    const replayable = IDEMPOTENT.has(request.method.toUpperCase()) || key !== void 0;
+    for (let attempt = 0; ; attempt++) {
+      if (signal.aborted) throw aborted(signal);
+      const last = attempt >= maxRetries;
+      let response;
+      try {
+        response = await once(fetchFn, request.clone(), signal, timeout);
+      } catch (error) {
+        if (signal.aborted) throw aborted(signal);
+        if (last || !replayable) {
+          throw error instanceof VinaverseTimeoutError ? new VinaverseTimeoutError(timeout, key) : new VinaverseNetworkError(error, key);
+        }
+        await wait(sleep, Math.min(backoff(attempt, random), maxDelay), signal);
+        continue;
+      }
+      const retry = response.status === 429 || replayable && retryable(response, await problemOf(response));
+      if (!retry || last) return response;
+      const delay = retryAfter(response) ?? backoff(attempt, random);
+      if (delay > maxDelay) return response;
+      await wait(sleep, delay, signal);
+    }
+  };
+}
+async function once(fetchFn, request, signal, timeout) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  const stop = () => controller.abort();
+  signal.addEventListener("abort", stop, { once: true });
+  if (signal.aborted) controller.abort();
+  try {
+    const pending = fetchFn(
+      new Request(request, { signal: controller.signal, redirect: "error" })
+    );
+    pending.catch(() => {
+    });
+    const response = await until(pending, controller.signal);
+    const empty = NULL_BODY.has(response.status);
+    const body = empty ? null : await readBody(
+      response,
+      response.ok ? Number.POSITIVE_INFINITY : MAX_REFUSAL_BYTES,
+      controller.signal
+    );
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+  } catch (error) {
+    if (controller.signal.aborted && !signal.aborted)
+      throw new VinaverseTimeoutError(timeout);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", stop);
+  }
+}
+async function readBody(response, limit, signal) {
+  if (!response.body) return null;
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (; ; ) {
+    const read = reader.read();
+    read.catch(() => {
+    });
+    const { done, value } = await until(read, signal).catch(
+      async (error) => {
+        void reader.cancel().catch(() => {
+        });
+        throw error;
+      }
+    );
+    if (done) break;
+    chunks.push(value);
+    size += value.length;
+    if (size >= limit) {
+      void reader.cancel().catch(() => {
+      });
+      break;
+    }
+  }
+  const body = new Uint8Array(new ArrayBuffer(Math.min(size, limit)));
+  let at = 0;
+  for (const chunk of chunks) {
+    const part = chunk.subarray(0, body.length - at);
+    body.set(part, at);
+    at += part.length;
+    if (at >= body.length) break;
+  }
+  return body;
+}
+async function problemOf(response) {
+  if (response.ok) return void 0;
+  try {
+    return await response.clone().json();
+  } catch {
+    return void 0;
+  }
+}
+function retryable(response, problem) {
+  if (response.status >= 500) return true;
+  return response.status >= 400 && problem?.retryable === true;
+}
+async function until(promise, signal) {
+  if (signal.aborted) throw aborted(signal);
+  let stop = () => {
+  };
+  const abort = new Promise((_, reject) => {
+    stop = () => reject(aborted(signal));
+    signal.addEventListener("abort", stop, { once: true });
+  });
+  try {
+    return await Promise.race([promise, abort]);
+  } finally {
+    signal.removeEventListener("abort", stop);
+  }
+}
+function wait(sleep, ms, signal) {
+  if (sleep) return until(sleep(ms), signal);
+  if (signal.aborted) return Promise.reject(aborted(signal));
+  return new Promise((resolve, reject) => {
+    const stop = () => {
+      clearTimeout(timer);
+      reject(aborted(signal));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", stop);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", stop, { once: true });
+  });
+}
+function aborted(signal) {
+  return signal.reason ?? new DOMException("The call was aborted.", "AbortError");
+}
+function retryAfter(response) {
+  const seconds = retryAfterSeconds(response);
+  return seconds === void 0 ? void 0 : seconds * 1e3;
+}
+function backoff(attempt, random) {
+  const base = 500 * 2 ** attempt;
+  return Math.round(base / 2 + random() * (base / 2));
+}
+function check(name, value, valid) {
+  if (typeof value !== "number" || !valid(value)) {
+    throw new TypeError(`${name} is not valid: ${String(value)}`);
+  }
+  return value;
+}
+
+// src/api/client.ts
+var SERVICE_KEY = /^vv_sk_(mock|dev|live)_[A-Za-z0-9_-]{8,}$/;
+var ServiceKeyExposureError = class extends Error {
+  name = "ServiceKeyExposureError";
+};
+function createApiClient(options) {
+  refuseClientRuntime();
+  const key = options.apiKey;
+  if (typeof key !== "string" || !SERVICE_KEY.test(key)) {
+    throw new TypeError(
+      key?.startsWith?.("vv_cs_") ? "createApiClient takes a service key (vv_sk_\u2026); a client secret (vv_cs_\u2026) is for the app" : "createApiClient needs a service key: vv_sk_<mock|dev|live>_\u2026"
+    );
+  }
+  const live = key.startsWith("vv_sk_live_");
+  const baseUrl = safeBaseUrl(
+    options.baseUrl ?? (live ? "https://api.vinaverse.com" : "https://api-dev.vinaverse.com")
+  );
+  const transport = options.fetch ?? ((request) => globalThis.fetch(request));
+  const api = createClient__default.default({
+    baseUrl,
+    redirect: "error",
+    // the API never redirects; a service key never follows one
+    // Every request, from a helper or from `api` with a per-call baseUrl, goes to this origin only.
+    fetch: retryingFetch(transport, options, sameOrigin(baseUrl)),
+    headers: {
+      ...options.headers,
+      authorization: `Bearer ${key}`,
+      accept: "application/json"
+    }
+  });
+  async function run(call, idempotencyKey) {
+    const { data, error, response } = await call;
+    if (!response.ok) throw apiError(response, error, idempotencyKey);
+    return data;
+  }
+  async function keyed(o, call) {
+    const key2 = o?.idempotencyKey ?? await newKey();
+    if (typeof key2 !== "string" || key2.length < 1 || key2.length > 255) {
+      throw new TypeError("idempotencyKey must be 1 to 255 characters");
+    }
+    return run(call({ "Idempotency-Key": key2 }), key2);
+  }
+  const init = (o) => o?.signal ? { signal: o.signal } : {};
+  return {
+    /** Every operation of the contract, typed, for what the helpers below do not cover (openapi-fetch). */
+    api,
+    sessions: {
+      /** Mint a session for the person in your app; give the app its `id`, URLs and `client_secret` only. */
+      create: (body, o) => keyed(
+        o,
+        (header) => api.POST("/v1/sessions", {
+          body,
+          params: { header },
+          ...init(o)
+        })
+      ),
+      get: (sessionId, o) => run(
+        api.GET("/v1/sessions/{session_id}", {
+          params: { path: { session_id: sessionId } },
+          ...init(o)
+        })
+      ),
+      revoke: (sessionId, o) => run(
+        api.POST("/v1/sessions/{session_id}/revoke", {
+          params: { path: { session_id: sessionId } },
+          ...init(o)
+        })
+      ),
+      /** A fresh client secret for an open session: what an app's `refreshSecret(sessionId)` asks your backend for. */
+      refreshClientSecret: (sessionId, o) => run(
+        api.POST("/v1/sessions/{session_id}/client_secret", {
+          params: { path: { session_id: sessionId } },
+          ...init(o)
+        })
+      )
+    },
+    conversations: {
+      get: (conversationId, o) => run(
+        api.GET("/v1/conversations/{conversation_id}", {
+          params: { path: { conversation_id: conversationId } },
+          ...init(o)
+        })
+      )
+    },
+    suggestions: {
+      create: (body, o) => run(
+        api.POST("/v1/suggestions", { body, ...init(o) })
+      )
+    },
+    moderation: {
+      createJob: (body, o) => keyed(
+        o,
+        (header) => api.POST("/v1/moderation/jobs", {
+          body,
+          params: { header },
+          ...init(o)
+        })
+      ),
+      getJob: (jobId, o) => run(
+        api.GET("/v1/moderation/jobs/{job_id}", {
+          params: { path: { job_id: jobId } },
+          ...init(o)
+        })
+      ),
+      getItem: (itemId, o) => run(
+        api.GET("/v1/moderation/items/{item_id}", {
+          params: { path: { item_id: itemId } },
+          ...init(o)
+        })
+      )
+    },
+    media: {
+      createJob: (body, o) => keyed(
+        o,
+        (header) => api.POST("/v1/media/jobs", {
+          body,
+          params: { header },
+          ...init(o)
+        })
+      ),
+      listJobs: (query = {}, o) => run(
+        api.GET("/v1/media/jobs", { params: { query }, ...init(o) })
+      ),
+      getJob: (jobId, o) => run(
+        api.GET("/v1/media/jobs/{job_id}", {
+          params: { path: { job_id: jobId } },
+          ...init(o)
+        })
+      ),
+      cancelJob: (jobId, o) => run(
+        api.POST("/v1/media/jobs/{job_id}/cancel", {
+          params: { path: { job_id: jobId } },
+          ...init(o)
+        })
+      ),
+      listProfiles: (o) => run(
+        api.GET("/v1/media/profiles", { ...init(o) })
+      )
+    },
+    screening: {
+      text: (body, o) => run(
+        api.POST("/v1/screening/text", { body, ...init(o) })
+      )
+    },
+    documentChecks: {
+      create: (body, o) => keyed(
+        o,
+        (header) => api.POST("/v1/document-checks", {
+          body,
+          params: { header },
+          ...init(o)
+        })
+      ),
+      get: (checkId, o) => run(
+        api.GET("/v1/document-checks/{check_id}", {
+          params: { path: { check_id: checkId } },
+          ...init(o)
+        })
+      )
+    },
+    subjects: {
+      erase: (subjectId, o) => keyed(
+        o,
+        (header) => api.POST("/v1/subjects/{subject_id}/erase", {
+          params: { path: { subject_id: subjectId }, header },
+          ...init(o)
+        })
+      )
+    },
+    feedback: {
+      send: (body, o) => run(
+        api.POST("/v1/feedback", { body, ...init(o) })
+      )
+    },
+    events: {
+      send: (body, o) => run(
+        api.POST("/v1/events", { body, ...init(o) })
+      )
+    },
+    knowledge: {
+      sendDocument: (body, o) => run(
+        api.POST("/v1/knowledge/documents", { body, ...init(o) })
+      )
+    },
+    catalog: {
+      put: (type, id, body, o) => run(
+        api.PUT("/v1/catalog/{type}/{id}", {
+          params: { path: { type, id } },
+          body,
+          ...init(o)
+        })
+      )
+    },
+    usage: {
+      get: (query = {}, o) => run(
+        api.GET("/v1/usage", { params: { query }, ...init(o) })
+      )
+    }
+  };
+}
+function refuseClientRuntime() {
+  const scope = globalThis;
+  if (scope.window !== void 0 && scope.document !== void 0) {
+    throw new ServiceKeyExposureError(
+      "The Vinaverse API client holds a service key and runs on your backend only, never in a browser. Give the app a session client secret (sessions.create)."
+    );
+  }
+  if (scope.navigator?.product === "ReactNative") {
+    throw new ServiceKeyExposureError(
+      "The Vinaverse API client holds a service key and runs on your backend only, never in an app. Use @vinaverse/client with a session client secret."
+    );
+  }
+}
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function safeBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError(`baseUrl is not a URL: ${value}`);
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+    throw new TypeError(
+      `baseUrl must be https: (or http: on localhost); a service key never travels in clear: ${url.origin}`
+    );
+  }
+  return value.replace(/\/+$/, "");
+}
+function sameOrigin(baseUrl) {
+  const origin = new URL(baseUrl).origin;
+  return (url) => {
+    const target = new URL(url);
+    if (target.origin !== origin) {
+      throw new TypeError(
+        `The Vinaverse API client sends its service key to ${origin} only, not to ${target.origin}`
+      );
+    }
+  };
+}
+function newKey() {
+  return randomUUID();
+}
+
+exports.ServiceKeyExposureError = ServiceKeyExposureError;
+exports.VinaverseApiError = VinaverseApiError;
+exports.VinaverseNetworkError = VinaverseNetworkError;
+exports.VinaverseTimeoutError = VinaverseTimeoutError;
+exports.apiError = apiError;
+exports.createApiClient = createApiClient;
+exports.retryAfterSeconds = retryAfterSeconds;
+//# sourceMappingURL=api.cjs.map
+//# sourceMappingURL=api.cjs.map