@zorveus/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1205 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIConnectionError: () => APIConnectionError,
+  APIStatusError: () => APIStatusError,
+  AuthenticationError: () => AuthenticationError,
+  CapExceededError: () => CapExceededError,
+  CreditGrantExpiredError: () => CreditGrantExpiredError,
+  InsufficientFundsError: () => InsufficientFundsError,
+  InternalServerError: () => InternalServerError,
+  NotFoundError: () => NotFoundError,
+  PermissionDeniedError: () => PermissionDeniedError,
+  RateLimitError: () => RateLimitError,
+  UnprocessableEntityError: () => UnprocessableEntityError,
+  Zorveus: () => Zorveus,
+  ZorveusBusinessError: () => ZorveusBusinessError,
+  ZorveusError: () => ZorveusError,
+  ZorveusInferenceClient: () => ZorveusInferenceClient,
+  ZorveusOAuth: () => ZorveusOAuth,
+  ZorveusServiceClient: () => ZorveusServiceClient,
+  assertDecimalString: () => assertDecimalString,
+  createAPIError: () => createAPIError,
+  formatGatewayMetadata: () => formatGatewayMetadata,
+  isValidDecimalString: () => isValidDecimalString
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/http/headers.ts
+function buildHeaders(options) {
+  const headers = {
+    Accept: "application/json"
+  };
+  if (typeof window === "undefined") {
+    headers["User-Agent"] = "@zorveus/sdk/0.1.0";
+  }
+  if (options.contentType) {
+    headers["Content-Type"] = options.contentType;
+  }
+  if (options.apiKey) {
+    headers["Authorization"] = `Bearer ${options.apiKey}`;
+  }
+  if (options.defaultHeaders) {
+    Object.assign(headers, options.defaultHeaders);
+  }
+  if (options.customHeaders) {
+    Object.assign(headers, options.customHeaders);
+  }
+  return headers;
+}
+
+// src/errors/zorveus-error.ts
+var ZorveusError = class extends Error {
+  status;
+  code;
+  param;
+  type;
+  headers;
+  rawBody;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ZorveusError";
+    this.status = options.status;
+    this.code = options.code;
+    this.param = options.param;
+    this.type = options.type;
+    this.headers = options.headers;
+    this.rawBody = options.rawBody;
+    if (options.cause) {
+      this.cause = options.cause;
+    }
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var APIConnectionError = class extends ZorveusError {
+  constructor(message = "Connection to Zorveus API failed", options = {}) {
+    super(message, options);
+    this.name = "APIConnectionError";
+    if (options.cause) {
+      this.cause = options.cause;
+    }
+  }
+};
+var APIStatusError = class extends ZorveusError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "APIStatusError";
+  }
+};
+var AuthenticationError = class extends APIStatusError {
+  constructor(message = "Invalid or expired Zorveus credentials", options = {}) {
+    super(message, { ...options, status: options.status ?? 401 });
+    this.name = "AuthenticationError";
+  }
+};
+var PermissionDeniedError = class extends APIStatusError {
+  constructor(message = "Permission denied for this operation or model", options = {}) {
+    super(message, { ...options, status: options.status ?? 403 });
+    this.name = "PermissionDeniedError";
+  }
+};
+var NotFoundError = class extends APIStatusError {
+  constructor(message = "Resource not found", options = {}) {
+    super(message, { ...options, status: options.status ?? 404 });
+    this.name = "NotFoundError";
+  }
+};
+var UnprocessableEntityError = class extends APIStatusError {
+  constructor(message = "Request validation failed", options = {}) {
+    super(message, { ...options, status: options.status ?? 422 });
+    this.name = "UnprocessableEntityError";
+  }
+};
+var RateLimitError = class extends APIStatusError {
+  constructor(message = "Rate limit exceeded. Please retry after some time.", options = {}) {
+    super(message, { ...options, status: options.status ?? 429 });
+    this.name = "RateLimitError";
+  }
+};
+var InternalServerError = class extends APIStatusError {
+  constructor(message = "Zorveus internal server error", options = {}) {
+    super(message, { ...options, status: options.status ?? 500 });
+    this.name = "InternalServerError";
+  }
+};
+var ZorveusBusinessError = class extends APIStatusError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ZorveusBusinessError";
+  }
+};
+var InsufficientFundsError = class extends ZorveusBusinessError {
+  constructor(message = "Wallet balance exhausted. Top up required.", options = {}) {
+    super(message, { ...options, status: options.status ?? 402, code: options.code ?? "insufficient_funds" });
+    this.name = "InsufficientFundsError";
+  }
+};
+var CapExceededError = class extends ZorveusBusinessError {
+  constructor(message = "Spending cap limit reached", options = {}) {
+    super(message, { ...options, status: options.status ?? 402, code: options.code ?? "cap_exceeded" });
+    this.name = "CapExceededError";
+  }
+};
+var CreditGrantExpiredError = class extends ZorveusBusinessError {
+  constructor(message = "Product user credit grant has expired", options = {}) {
+    super(message, { ...options, status: options.status ?? 403, code: options.code ?? "credit_grant_expired" });
+    this.name = "CreditGrantExpiredError";
+  }
+};
+function createAPIError(status, body, headers) {
+  let message = `Request failed with status ${status}`;
+  let code;
+  let param;
+  let type;
+  let parsedBody = body;
+  if (typeof body === "string") {
+    try {
+      parsedBody = JSON.parse(body);
+    } catch {
+      try {
+        parsedBody = JSON.parse(body.replace(/'/g, '"'));
+      } catch {
+        const codeMatch = body.match(/['"]code['"]\s*:\s*['"]([^'"]+)['"]/);
+        const msgMatch = body.match(/['"]message['"]\s*:\s*['"]([^'"]+)['"]/);
+        if (msgMatch?.[1]) message = msgMatch[1];
+        if (codeMatch?.[1]) code = codeMatch[1];
+      }
+    }
+  }
+  if (parsedBody && typeof parsedBody === "object") {
+    const obj = parsedBody;
+    if (obj.error && typeof obj.error === "object") {
+      const err = obj.error;
+      if (typeof err.message === "string") message = err.message;
+      if (typeof err.code === "string") code = err.code;
+      if (typeof err.param === "string") param = err.param;
+      if (typeof err.type === "string") type = err.type;
+    } else if (typeof obj.detail === "string") {
+      message = obj.detail;
+    } else if (Array.isArray(obj.detail) && obj.detail.length > 0) {
+      const first = obj.detail[0];
+      if (first && typeof first.msg === "string") {
+        message = first.msg;
+      }
+    } else if (typeof obj.message === "string") {
+      message = obj.message;
+    }
+  }
+  const options = { status, code, param, type, headers, rawBody: body };
+  const normalizedCode = (code || "").toLowerCase();
+  if (normalizedCode.includes("cap_exceed") || normalizedCode.includes("spend_cap") || message.toLowerCase().includes("spending cap")) {
+    return new CapExceededError(message, options);
+  }
+  if (normalizedCode.includes("insufficient_funds") || normalizedCode.includes("balance_exhausted") || normalizedCode.includes("insufficient_balance") || normalizedCode.includes("wallet_empty") || message.toLowerCase().includes("insufficient funds") || message.toLowerCase().includes("balance exhausted") || message.toLowerCase().includes("wallet is empty")) {
+    return new InsufficientFundsError(message, options);
+  }
+  if (normalizedCode.includes("grant_expired")) {
+    return new CreditGrantExpiredError(message, options);
+  }
+  if (status === 401) {
+    return new AuthenticationError(message, options);
+  }
+  if (status === 402) {
+    return new InsufficientFundsError(message, options);
+  }
+  if (status === 403) {
+    return new PermissionDeniedError(message, options);
+  }
+  if (status === 404) {
+    return new NotFoundError(message, options);
+  }
+  if (status === 422) {
+    return new UnprocessableEntityError(message, options);
+  }
+  if (status === 429) {
+    return new RateLimitError(message, options);
+  }
+  if (status >= 500) {
+    return new InternalServerError(message, options);
+  }
+  return new APIStatusError(message, options);
+}
+
+// src/http/transport.ts
+var HTTPTransport = class {
+  apiKey;
+  baseURL;
+  gatewayBaseURL;
+  timeout;
+  maxRetries;
+  defaultHeaders;
+  fetchFn;
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new Error("HTTPTransport initialized without an apiKey.");
+    }
+    this.apiKey = options.apiKey;
+    this.baseURL = (options.baseURL || "https://api.zorveus.com").replace(/\/+$/, "");
+    this.gatewayBaseURL = (options.gatewayBaseURL || `${this.baseURL}/v1`).replace(/\/+$/, "");
+    this.timeout = options.timeout ?? 6e4;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.defaultHeaders = options.defaultHeaders || {};
+    this.fetchFn = options.fetch || globalThis.fetch.bind(globalThis);
+  }
+  /**
+   * Executes an HTTP request with timeout, strict idempotency-aware retries, and error mapping.
+   */
+  async request(path, options = {}) {
+    const method = options.method || "GET";
+    const isGateway = options.isGateway ?? false;
+    const rootUrl = isGateway ? this.gatewayBaseURL : this.baseURL;
+    const url = this.buildUrl(rootUrl, path, options.query);
+    const isJsonBody = options.body !== void 0 && !(options.body instanceof FormData);
+    const contentType = isJsonBody ? "application/json" : void 0;
+    const customHeaders = { ...options.headers };
+    if (options.idempotencyKey) {
+      customHeaders["X-Idempotency-Key"] = options.idempotencyKey;
+    }
+    const headers = buildHeaders({
+      apiKey: this.apiKey,
+      defaultHeaders: this.defaultHeaders,
+      customHeaders,
+      contentType
+    });
+    const isSafeMethod = method === "GET" || method === "HEAD" || method === "OPTIONS";
+    const isIdempotent = isSafeMethod || Boolean(options.isIdempotent || options.idempotencyKey);
+    const maxRetries = isIdempotent ? options.maxRetries ?? this.maxRetries : 0;
+    const timeoutMs = options.timeout ?? this.timeout;
+    if (options.signal?.aborted) {
+      throw new APIConnectionError("Request was cancelled by user");
+    }
+    let attempt = 0;
+    while (true) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+      const onAbort = () => controller.abort();
+      if (options.signal) {
+        options.signal.addEventListener("abort", onAbort, { once: true });
+      }
+      try {
+        const bodyContent = isJsonBody ? JSON.stringify(options.body) : options.body;
+        const response = await this.fetchFn(url.toString(), {
+          method,
+          headers,
+          body: bodyContent,
+          signal: controller.signal
+        });
+        if (options.stream) {
+          if (!response.ok) {
+            const errorBody = await this.parseResponseBody(response);
+            throw createAPIError(response.status, errorBody, this.extractHeaders(response.headers));
+          }
+          if (!response.body) {
+            throw new APIConnectionError("Streaming response body is null");
+          }
+          return response.body;
+        }
+        if (!response.ok) {
+          const errorBody = await this.parseResponseBody(response);
+          const shouldRetry = isIdempotent && this.shouldRetryStatus(response.status) && attempt < maxRetries;
+          if (shouldRetry) {
+            attempt++;
+            const delay = this.calculateRetryDelay(attempt, response.headers.get("retry-after"));
+            await this.sleep(delay);
+            continue;
+          }
+          throw createAPIError(response.status, errorBody, this.extractHeaders(response.headers));
+        }
+        if (response.status === 204) {
+          return void 0;
+        }
+        const data = await this.parseResponseBody(response);
+        return data;
+      } catch (error) {
+        if (error && typeof error === "object" && "status" in error) {
+          throw error;
+        }
+        const isAbortError = error instanceof Error && error.name === "AbortError";
+        const wasUserAborted = options.signal?.aborted;
+        if (isAbortError && wasUserAborted) {
+          throw new APIConnectionError("Request was cancelled by user", { cause: error });
+        }
+        const isTimeout = isAbortError && !wasUserAborted;
+        const errorMessage = isTimeout ? `Request timed out after ${timeoutMs}ms` : "Network request failed";
+        if (isIdempotent && attempt < maxRetries) {
+          attempt++;
+          const delay = this.calculateRetryDelay(attempt);
+          await this.sleep(delay);
+          continue;
+        }
+        throw new APIConnectionError(errorMessage, { cause: error });
+      } finally {
+        clearTimeout(timeoutId);
+        if (options.signal) {
+          options.signal.removeEventListener("abort", onAbort);
+        }
+      }
+    }
+  }
+  buildUrl(base, path, query) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const url = new URL(`${base}${normalizedPath}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0 || value === null) {
+          continue;
+        }
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            if (item !== void 0 && item !== null) {
+              url.searchParams.append(key, String(item));
+            }
+          }
+        } else {
+          url.searchParams.append(key, String(value));
+        }
+      }
+    }
+    return url;
+  }
+  async parseResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+      return null;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  extractHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+      result[key] = value;
+    });
+    return result;
+  }
+  shouldRetryStatus(status) {
+    return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+  }
+  calculateRetryDelay(attempt, retryAfterHeader) {
+    if (retryAfterHeader) {
+      const parsedSeconds = parseInt(retryAfterHeader, 10);
+      if (!isNaN(parsedSeconds) && parsedSeconds > 0) {
+        return parsedSeconds * 1e3;
+      }
+      const parsedDate = Date.parse(retryAfterHeader);
+      if (!isNaN(parsedDate)) {
+        const diff = parsedDate - Date.now();
+        if (diff > 0) {
+          return diff;
+        }
+      }
+    }
+    const baseDelay = 500;
+    const maxBackoff = Math.min(1e4, baseDelay * Math.pow(2, Math.max(0, attempt - 1)));
+    const jitter = Math.floor(Math.random() * maxBackoff);
+    return Math.max(baseDelay, jitter);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/http/sse.ts
+async function* parseSSEStream(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith(":")) {
+          continue;
+        }
+        if (trimmed.startsWith("data:")) {
+          const dataContent = trimmed.slice(5).trim();
+          if (dataContent === "[DONE]") {
+            return;
+          }
+          try {
+            const parsed = JSON.parse(dataContent);
+            yield parsed;
+          } catch {
+          }
+        }
+      }
+    }
+    if (buffer.trim()) {
+      const trimmed = buffer.trim();
+      if (trimmed.startsWith("data:")) {
+        const dataContent = trimmed.slice(5).trim();
+        if (dataContent !== "[DONE]") {
+          try {
+            const parsed = JSON.parse(dataContent);
+            yield parsed;
+          } catch {
+          }
+        }
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+    }
+    reader.releaseLock();
+  }
+}
+
+// src/types/chat.ts
+function formatGatewayMetadata(meta) {
+  if (!meta) return void 0;
+  const result = {};
+  if (meta.externalUserId) {
+    result.external_user_id = meta.externalUserId;
+  }
+  if (meta.displayName !== void 0 || meta.userEmail !== void 0 || meta.metadata !== void 0) {
+    result.product_user = {
+      display_name: meta.displayName ?? null,
+      email: meta.userEmail ?? null,
+      metadata: meta.metadata ?? null
+    };
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+
+// src/resources/chat/completions.ts
+var Completions = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async create(params, options = {}) {
+    const isStreaming = Boolean(params.stream);
+    const { zorveusMetadata, metadata: explicitMetadata, ...requestBody } = params;
+    const gatewayMetadata = formatGatewayMetadata(zorveusMetadata);
+    const combinedMetadata = explicitMetadata ? { ...gatewayMetadata, ...explicitMetadata } : gatewayMetadata;
+    const payload = {
+      ...requestBody,
+      ...combinedMetadata ? { metadata: combinedMetadata } : {}
+    };
+    if (isStreaming) {
+      const responseStream = await this.transport.request(
+        "/chat/completions",
+        {
+          method: "POST",
+          body: { ...payload, stream: true },
+          isGateway: true,
+          stream: true,
+          ...options
+        }
+      );
+      return parseSSEStream(responseStream);
+    }
+    return this.transport.request("/chat/completions", {
+      method: "POST",
+      body: payload,
+      isGateway: true,
+      stream: false,
+      ...options
+    });
+  }
+};
+
+// src/resources/chat/index.ts
+var Chat = class {
+  completions;
+  constructor(transport) {
+    this.completions = new Completions(transport);
+  }
+};
+
+// src/resources/embeddings.ts
+var Embeddings = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Creates an embedding vector representing the input text.
+   */
+  async create(params, options = {}) {
+    const { zorveusMetadata, ...requestBody } = params;
+    const gatewayMetadata = formatGatewayMetadata(zorveusMetadata);
+    const payload = {
+      ...requestBody,
+      ...gatewayMetadata ? { metadata: gatewayMetadata } : {}
+    };
+    return this.transport.request("/embeddings", {
+      method: "POST",
+      body: payload,
+      isGateway: true,
+      ...options
+    });
+  }
+};
+
+// src/resources/models.ts
+var Models = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Lists available models on the Zorveus gateway.
+   */
+  async list(params = {}, options = {}) {
+    const query = {};
+    if (params.routeStatus) {
+      query.route_status = params.routeStatus;
+    }
+    return this.transport.request("/models", {
+      method: "GET",
+      query,
+      isGateway: true,
+      ...options
+    });
+  }
+  /**
+   * Retrieves information about a specific model.
+   */
+  async retrieve(modelId, options = {}) {
+    return this.transport.request(`/models/${encodeURIComponent(modelId)}`, {
+      method: "GET",
+      isGateway: true,
+      ...options
+    });
+  }
+};
+
+// src/client.ts
+var ZorveusInferenceClient = class {
+  chat;
+  embeddings;
+  models;
+  transport;
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new Error(
+        "ZorveusInferenceClient requires an 'apiKey' (Inference Key or OAuth Access Token)."
+      );
+    }
+    const baseURL = options.baseURL ? options.baseURL.replace(/\/+$/, "") : options.gatewayBaseURL ? options.gatewayBaseURL.replace(/\/v1\/?$/, "").replace(/\/+$/, "") : "https://api.zorveus.com";
+    const gatewayBaseURL = (options.gatewayBaseURL || `${baseURL}/v1`).replace(/\/+$/, "");
+    this.transport = new HTTPTransport({
+      apiKey: options.apiKey,
+      baseURL,
+      gatewayBaseURL,
+      timeout: options.timeout,
+      maxRetries: options.maxRetries,
+      defaultHeaders: options.defaultHeaders,
+      fetch: options.fetch
+    });
+    this.chat = new Chat(this.transport);
+    this.embeddings = new Embeddings(this.transport);
+    this.models = new Models(this.transport);
+  }
+  /**
+   * Retrieves live spend, budget cap, and balance for the active inference key (`GET /inference-keys/usage`).
+   */
+  async getUsage(options = {}) {
+    return this.transport.request("/inference-keys/usage", {
+      method: "GET",
+      ...options
+    });
+  }
+};
+var Zorveus = class extends ZorveusInferenceClient {
+};
+
+// src/utils/decimal.ts
+function isValidDecimalString(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return false;
+  }
+  const decimalRegex = /^-?\d+(\.\d+)?$/;
+  return decimalRegex.test(trimmed);
+}
+function assertDecimalString(value, fieldName) {
+  if (typeof value === "number") {
+    return value.toFixed(4);
+  }
+  if (isValidDecimalString(value)) {
+    return value.trim();
+  }
+  throw new TypeError(
+    `Field '${fieldName}' must be a valid decimal string (e.g. "15.0000"), received: ${JSON.stringify(value)}`
+  );
+}
+
+// src/resources/product-users.ts
+var ProductUsers = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Upserts a product user by external user ID (`PUT /product-users/by-external-id`).
+   * Creates the user if they do not exist, or updates their profile if they do.
+   */
+  async createOrUpdate(params, options = {}) {
+    const payload = {
+      ...params.appId ? { app_id: params.appId } : {},
+      external_user_id: params.externalUserId,
+      display_name: params.displayName ?? null,
+      email: params.email ?? null,
+      metadata: params.metadata ?? null
+    };
+    const query = params.orgId ? { org_id: params.orgId } : void 0;
+    return this.transport.request("/product-users/by-external-id", {
+      method: "PUT",
+      body: payload,
+      query,
+      ...options
+    });
+  }
+  /**
+   * Alias for `createOrUpdate` (`PUT /product-users/by-external-id`).
+   */
+  async upsert(params, options = {}) {
+    return this.createOrUpdate(params, options);
+  }
+  /**
+   * Retrieves a single product end-user by ID (`GET /product-users/{product_end_user_id}`).
+   */
+  async get(productEndUserId, options = {}) {
+    return this.transport.request(
+      `/product-users/${encodeURIComponent(productEndUserId)}`,
+      {
+        method: "GET",
+        ...options
+      }
+    );
+  }
+  /**
+   * Retrieves a product user profile by external ID (`GET /product-users/by-external-id`).
+   * Returns complete profile with usage, active cap, and live credits.
+   */
+  async getByExternalId(params, options = {}) {
+    const query = {
+      app_id: params.appId,
+      external_user_id: params.externalUserId
+    };
+    if (params.orgId) {
+      query.org_id = params.orgId;
+    }
+    return this.transport.request("/product-users/by-external-id", {
+      method: "GET",
+      query,
+      ...options
+    });
+  }
+  /**
+   * Retrieves a product user's live credit summary by external ID (`GET /product-users/by-external-id/credit-summary`).
+   */
+  async getCreditSummaryByExternalId(params, options = {}) {
+    const query = {
+      app_id: params.appId,
+      external_user_id: params.externalUserId
+    };
+    if (params.currency) {
+      query.currency = params.currency;
+    }
+    if (params.orgId) {
+      query.org_id = params.orgId;
+    }
+    return this.transport.request(
+      "/product-users/by-external-id/credit-summary",
+      {
+        method: "GET",
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Lists product end-users for an organization (`GET /product-users`).
+   */
+  async list(params = {}, options = {}) {
+    const query = {};
+    if (params.orgId) query.org_id = params.orgId;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.offset !== void 0) query.offset = params.offset;
+    return this.transport.request("/product-users", {
+      method: "GET",
+      query,
+      ...options
+    });
+  }
+  /**
+   * Grants startup-funded AI credits to a product user (`POST /product-users/{id}/credit-grants`).
+   * Validates amount as a strict financial decimal string.
+   */
+  async grantCredit(productEndUserId, params, options = {}) {
+    const amount = assertDecimalString(params.amount, "grantCredit.amount");
+    const payload = {
+      app_id: params.appId,
+      amount,
+      currency: params.currency || "USD",
+      reason: params.reason ?? null,
+      expires_at: params.expiresAt ?? null,
+      metadata: params.metadata ?? null
+    };
+    const query = params.orgId ? { org_id: params.orgId } : void 0;
+    return this.transport.request(
+      `/product-users/${encodeURIComponent(productEndUserId)}/credit-grants`,
+      {
+        method: "POST",
+        body: payload,
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Grants credits to an end user by external ID (`POST /product-users/by-external-id/credit-grants`).
+   * Automatically provisions the product user if they do not exist yet.
+   */
+  async grantCreditByExternalId(params, options = {}) {
+    const amount = assertDecimalString(params.amount, "grantCreditByExternalId.amount");
+    const payload = {
+      app_id: params.appId,
+      external_user_id: params.externalUserId,
+      display_name: params.displayName ?? null,
+      email: params.email ?? null,
+      amount,
+      currency: params.currency || "USD",
+      source: params.source ?? null,
+      reason: params.reason ?? null,
+      expires_at: params.expiresAt ?? null,
+      metadata: params.metadata ?? null
+    };
+    const query = params.orgId ? { org_id: params.orgId } : void 0;
+    return this.transport.request(
+      "/product-users/by-external-id/credit-grants",
+      {
+        method: "POST",
+        body: payload,
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Lists credit grants for a product user (`GET /product-users/{id}/credit-grants`).
+   * Accepts either an external user ID or a Zorveus product user ID.
+   */
+  async listCreditGrants(userIdentifier, params = {}, options = {}) {
+    const query = {};
+    if (params.appId) query.app_id = params.appId;
+    if (params.orgId) query.org_id = params.orgId;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.offset !== void 0) query.offset = params.offset;
+    return this.transport.request(
+      `/product-users/${encodeURIComponent(userIdentifier)}/credit-grants`,
+      {
+        method: "GET",
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Lists credit grants for a product user by external ID (`GET /product-users/by-external-id/credit-grants`).
+   */
+  async listCreditGrantsByExternalId(params, options = {}) {
+    const query = {
+      app_id: params.appId,
+      external_user_id: params.externalUserId
+    };
+    if (params.status) query.status = params.status;
+    if (params.source) query.source = params.source;
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.orgId) query.org_id = params.orgId;
+    return this.transport.request(
+      "/product-users/by-external-id/credit-grants",
+      {
+        method: "GET",
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Revokes an active credit grant (`POST /product-users/{id}/credit-grants/{grantId}/revoke`).
+   */
+  async revokeCredit(productEndUserId, creditGrantId, options = {}) {
+    return this.transport.request(
+      `/product-users/${encodeURIComponent(productEndUserId)}/credit-grants/${encodeURIComponent(creditGrantId)}/revoke`,
+      {
+        method: "POST",
+        ...options
+      }
+    );
+  }
+};
+
+// src/resources/provider-credentials.ts
+var ProviderCredentials = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Registers an organization BYOK provider credential via Service Key (`POST /provider-credentials/org-programmatic`).
+   */
+  async create(params, options = {}) {
+    const payload = {
+      provider: params.provider,
+      credential_name: params.credentialName,
+      api_key: params.apiKey,
+      secret_kind: params.secretKind || "api_key",
+      model_policies: params.modelPolicies || [],
+      provider_config: params.providerConfig ?? null,
+      routing_mode: params.routingMode || "auto_resolve",
+      routing_priority: params.routingPriority ?? 100
+    };
+    const query = params.orgId ? { org_id: params.orgId } : void 0;
+    return this.transport.request(
+      "/provider-credentials/org-programmatic",
+      {
+        method: "POST",
+        body: payload,
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Lists BYOK provider credentials for an organization (`GET /provider-credentials/org-programmatic`).
+   */
+  async list(params = {}, options = {}) {
+    const query = {};
+    if (params.orgId) query.org_id = params.orgId;
+    if (params.status) query.status = params.status;
+    return this.transport.request(
+      "/provider-credentials/org-programmatic",
+      {
+        method: "GET",
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Rotates a provider credential secret (`POST /provider-credentials/org-programmatic/{id}/rotate`).
+   */
+  async rotate(providerCredentialId, params, options = {}) {
+    const payload = {
+      api_key: params.apiKey,
+      secret_kind: params.secretKind || "api_key"
+    };
+    const query = params.orgId ? { org_id: params.orgId } : void 0;
+    return this.transport.request(
+      `/provider-credentials/org-programmatic/${encodeURIComponent(providerCredentialId)}/rotate`,
+      {
+        method: "POST",
+        body: payload,
+        query,
+        ...options
+      }
+    );
+  }
+  /**
+   * Deletes a provider credential (`DELETE /provider-credentials/org-programmatic/{id}`).
+   */
+  async delete(providerCredentialId, options = {}) {
+    return this.transport.request(
+      `/provider-credentials/org-programmatic/${encodeURIComponent(providerCredentialId)}`,
+      {
+        method: "DELETE",
+        ...options
+      }
+    );
+  }
+  /**
+   * Lists supported AI provider catalog (`GET /provider-credentials/providers`).
+   */
+  async listProviders(options = {}) {
+    return this.transport.request(
+      "/provider-credentials/providers",
+      {
+        method: "GET",
+        ...options
+      }
+    );
+  }
+};
+
+// src/service-client.ts
+var ZorveusServiceClient = class {
+  productUsers;
+  providerCredentials;
+  transport;
+  constructor(options) {
+    if (!options || !options.apiKey) {
+      throw new Error(
+        "ZorveusServiceClient requires an 'apiKey' (Organization Service Key 'zrv_service_...')."
+      );
+    }
+    const baseURL = (options.baseURL || "https://api.zorveus.com").replace(/\/+$/, "");
+    this.transport = new HTTPTransport({
+      apiKey: options.apiKey,
+      baseURL,
+      timeout: options.timeout,
+      maxRetries: options.maxRetries,
+      defaultHeaders: options.defaultHeaders,
+      fetch: options.fetch
+    });
+    this.productUsers = new ProductUsers(this.transport);
+    this.providerCredentials = new ProviderCredentials(this.transport);
+  }
+};
+
+// src/utils/crypto.ts
+function getCrypto() {
+  if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.subtle) {
+    return globalThis.crypto;
+  }
+  throw new Error("Web Crypto API (crypto.subtle) is not available in the current environment.");
+}
+function base64UrlEncode(buffer) {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  const base64 = typeof btoa === "function" ? btoa(binary) : Buffer.from(bytes).toString("base64");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateRandomString(byteLength = 32) {
+  const crypto = getCrypto();
+  const randomBytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(randomBytes);
+  return base64UrlEncode(randomBytes);
+}
+async function sha256Base64Url(plainText) {
+  const crypto = getCrypto();
+  const encoder = new TextEncoder();
+  const data = encoder.encode(plainText);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(hashBuffer);
+}
+
+// src/oauth.ts
+var ZorveusOAuth = class {
+  /**
+   * Generates an RFC 7636 PKCE code_verifier, code_challenge (S256), and CSRF state parameter.
+   */
+  static async generatePKCE(byteLength = 32) {
+    const codeVerifier = generateRandomString(byteLength);
+    const codeChallenge = await sha256Base64Url(codeVerifier);
+    const state = generateRandomString(32);
+    return {
+      codeVerifier,
+      codeChallenge,
+      state
+    };
+  }
+  /**
+   * Constructs the Zorveus OAuth PKCE consent URL.
+   */
+  static getAuthorizationUrl(params) {
+    const baseUrl = (params.baseURL || "https://api.zorveus.com").replace(/\/+$/, "");
+    const url = new URL(`${baseUrl}/oauth/authorize`);
+    url.searchParams.set("client_id", params.clientId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("state", params.state);
+    url.searchParams.set("code_challenge", params.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("response_type", "code");
+    const scopes = params.scopes ? Array.isArray(params.scopes) ? params.scopes.join(" ") : params.scopes : "inference:write models:*";
+    url.searchParams.set("scope", scopes);
+    return url.toString();
+  }
+  /**
+   * Validates OAuth redirect parameters against expected CSRF state.
+   */
+  static validateCallback(options) {
+    let params;
+    if (typeof options.urlOrParams === "string") {
+      const urlStr = options.urlOrParams;
+      const queryIdx = urlStr.indexOf("?");
+      const search = queryIdx !== -1 ? urlStr.slice(queryIdx) : urlStr;
+      params = new URLSearchParams(search);
+    } else if (options.urlOrParams instanceof URLSearchParams) {
+      params = options.urlOrParams;
+    } else if (options.urlOrParams && typeof options.urlOrParams === "object") {
+      params = new URLSearchParams();
+      for (const [key, value] of Object.entries(options.urlOrParams)) {
+        if (value !== void 0 && value !== null && value !== "undefined" && value !== "null") {
+          params.set(key, String(value));
+        }
+      }
+    } else {
+      params = new URLSearchParams();
+    }
+    const rawError = params.get("error");
+    const isRealError = rawError && rawError !== "undefined" && rawError !== "null";
+    if (isRealError) {
+      const rawDesc = params.get("error_description");
+      const errorDescription = rawDesc && rawDesc !== "undefined" && rawDesc !== "null" ? rawDesc : void 0;
+      return {
+        valid: false,
+        error: rawError,
+        errorDescription
+      };
+    }
+    const rawCode = params.get("code");
+    const code = rawCode && rawCode !== "undefined" && rawCode !== "null" ? rawCode : void 0;
+    if (!code) {
+      return {
+        valid: false,
+        error: "invalid_response",
+        errorDescription: "Missing authorization code in redirect params"
+      };
+    }
+    const rawState = params.get("state");
+    const state = rawState && rawState !== "undefined" && rawState !== "null" ? rawState : void 0;
+    if (options.expectedState && state !== options.expectedState) {
+      return {
+        valid: false,
+        error: "state_mismatch",
+        errorDescription: "State parameter does not match expected CSRF token"
+      };
+    }
+    return {
+      valid: true,
+      code,
+      state
+    };
+  }
+  /**
+   * Exchanges an OAuth authorization code for a Zorveus inference key using application/x-www-form-urlencoded.
+   */
+  static async exchangeToken(params) {
+    const baseUrl = (params.baseURL || "https://api.zorveus.com").replace(/\/+$/, "");
+    const url = `${baseUrl}/oauth/token`;
+    const bodyParams = new URLSearchParams();
+    bodyParams.append("grant_type", "authorization_code");
+    bodyParams.append("client_id", params.clientId);
+    bodyParams.append("code", params.code);
+    bodyParams.append("code_verifier", params.codeVerifier);
+    bodyParams.append("redirect_uri", params.redirectUri);
+    if (params.clientSecret) {
+      bodyParams.append("client_secret", params.clientSecret);
+    }
+    const headers = {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    };
+    if (typeof window === "undefined") {
+      headers["User-Agent"] = "@zorveus/sdk/0.1.0";
+    }
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: bodyParams.toString()
+    });
+    if (!response.ok) {
+      let errorBody;
+      try {
+        errorBody = await response.json();
+      } catch {
+        errorBody = await response.text();
+      }
+      throw createAPIError(response.status, errorBody);
+    }
+    const tokenData = await response.json();
+    return tokenData;
+  }
+  /**
+   * Revokes an existing OAuth token or app connection using application/x-www-form-urlencoded.
+   */
+  static async revokeToken(params) {
+    const baseUrl = (params.baseURL || "https://api.zorveus.com").replace(/\/+$/, "");
+    const url = `${baseUrl}/oauth/revoke`;
+    const bodyParams = new URLSearchParams();
+    bodyParams.append("token", params.token);
+    if (params.clientId) {
+      bodyParams.append("client_id", params.clientId);
+    }
+    if (params.clientSecret) {
+      bodyParams.append("client_secret", params.clientSecret);
+    }
+    const headers = {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    };
+    if (typeof window === "undefined") {
+      headers["User-Agent"] = "@zorveus/sdk/0.1.0";
+    }
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: bodyParams.toString()
+    });
+    if (!response.ok) {
+      let errorBody;
+      try {
+        errorBody = await response.json();
+      } catch {
+        errorBody = await response.text();
+      }
+      throw createAPIError(response.status, errorBody);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIConnectionError,
+  APIStatusError,
+  AuthenticationError,
+  CapExceededError,
+  CreditGrantExpiredError,
+  InsufficientFundsError,
+  InternalServerError,
+  NotFoundError,
+  PermissionDeniedError,
+  RateLimitError,
+  UnprocessableEntityError,
+  Zorveus,
+  ZorveusBusinessError,
+  ZorveusError,
+  ZorveusInferenceClient,
+  ZorveusOAuth,
+  ZorveusServiceClient,
+  assertDecimalString,
+  createAPIError,
+  formatGatewayMetadata,
+  isValidDecimalString
+});
+//# sourceMappingURL=index.js.map