@pymthouse/builder-sdk 0.0.8 → 0.3.0

package/dist/env.js

@@ -1,6 +1,15 @@
 import { genericTokenEndpointRequest, processGenericTokenEndpointResponse, clientCredentialsGrantRequest, processClientCredentialsResponse, customFetch, allowInsecureRequests, discoveryRequest, processDiscoveryResponse, ResponseBodyError, OperationProcessingError } from 'oauth4webapi';
+import 'crypto';
 
-// src/client.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/encoding.ts
 function encodeClientSecretBasic(clientId, clientSecret) {
@@ -8,35 +17,69 @@ function encodeClientSecretBasic(clientId, clientSecret) {
   const b64 = typeof Buffer !== "undefined" ? Buffer.from(raw, "utf8").toString("base64") : btoa(Array.from(new TextEncoder().encode(raw), (c) => String.fromCharCode(c)).join(""));
   return `Basic ${b64}`;
 }
+var init_encoding = __esm({
+  "src/encoding.ts"() {
+  }
+});
 
 // src/errors.ts
-var PmtHouseError = class extends Error {
-  status;
-  code;
-  details;
-  constructor(message, {
-    status = 500,
-    code = "pymthouse_error",
-    details
-  } = {}) {
-    super(message);
-    this.name = "PmtHouseError";
-    this.status = status;
-    this.code = code;
-    this.details = details;
+var PmtHouseError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    PmtHouseError = class extends Error {
+      status;
+      code;
+      details;
+      constructor(message, {
+        status = 500,
+        code = "pymthouse_error",
+        details
+      } = {}) {
+        super(message);
+        this.name = "PmtHouseError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+      }
+    };
   }
-};
+});
 
 // src/string-utils.ts
 function stripTrailingSlashes(value) {
   let end = value.length;
-  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+  while (end > 0 && (value.codePointAt(end - 1) ?? 0) === 47) {
     end--;
   }
   return value.slice(0, end);
 }
-
-// src/discovery.ts
+function endsWithIgnoreCase(value, suffix) {
+  if (suffix.length > value.length) {
+    return false;
+  }
+  const start = value.length - suffix.length;
+  for (let i = 0; i < suffix.length; i++) {
+    const a = value.codePointAt(start + i) ?? 0;
+    const b = suffix.codePointAt(i) ?? 0;
+    if (a !== b && (a | 32) !== (b | 32)) {
+      return false;
+    }
+  }
+  return true;
+}
+function stripSuffixIgnoreCase(value, suffix) {
+  return endsWithIgnoreCase(value, suffix) ? value.slice(0, value.length - suffix.length) : value;
+}
+function stripIssuerOriginFromOidcUrl(issuerUrl) {
+  let base = stripTrailingSlashes(issuerUrl.trim());
+  base = stripSuffixIgnoreCase(base, "/api/v1/oidc");
+  base = stripSuffixIgnoreCase(base, "/oidc");
+  return stripTrailingSlashes(base);
+}
+var init_string_utils = __esm({
+  "src/string-utils.ts"() {
+  }
+});
 function authorizationServerToOidcDocument(as) {
   const tokenEndpoint = as.token_endpoint;
   const jwksUri = as.jwks_uri;
@@ -55,8 +98,6 @@ function authorizationServerToOidcDocument(as) {
     device_authorization_endpoint: as.device_authorization_endpoint
   };
 }
-var CACHE_TTL_MS = 5 * 60 * 1e3;
-var discoveryCache = /* @__PURE__ */ new Map();
 function normalizedIssuerKey(issuerUrl) {
   return stripTrailingSlashes(issuerUrl);
 }
@@ -121,6 +162,612 @@ function mapDiscoveryNetworkError(error) {
     code: "oidc_discovery_failed"
   });
 }
+var CACHE_TTL_MS, discoveryCache;
+var init_discovery = __esm({
+  "src/discovery.ts"() {
+    init_errors();
+    init_string_utils();
+    CACHE_TTL_MS = 5 * 60 * 1e3;
+    discoveryCache = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/signer/fetch-json.ts
+function oauthFailureDescription(parsed, failureLabel, status) {
+  if (typeof parsed.error_description === "string") {
+    return parsed.error_description;
+  }
+  if (typeof parsed.error === "string") {
+    return parsed.error;
+  }
+  return `${failureLabel} (${status})`;
+}
+async function readJsonObjectFromResponse(response, options) {
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = text ? JSON.parse(text) : {};
+  } catch {
+    throw new PmtHouseError(options.invalidJsonMessage, {
+      status: 502,
+      code: options.invalidJsonCode,
+      details: { status: response.status }
+    });
+  }
+  if (!response.ok) {
+    const description = oauthFailureDescription(parsed, options.failureLabel, response.status);
+    throw new PmtHouseError(description, {
+      status: response.status,
+      code: typeof parsed.error === "string" ? parsed.error : options.defaultErrorCode,
+      details: parsed
+    });
+  }
+  return parsed;
+}
+var init_fetch_json = __esm({
+  "src/signer/fetch-json.ts"() {
+    init_errors();
+  }
+});
+
+// src/signer/handler-errors.ts
+function signerHandlerErrorResponse(error) {
+  if (error instanceof PmtHouseError) {
+    return new Response(
+      JSON.stringify({
+        error: error.code,
+        error_description: error.message,
+        details: error.details
+      }),
+      {
+        status: error.status,
+        headers: { "Content-Type": "application/json" }
+      }
+    );
+  }
+  const message = error instanceof Error ? error.message : "Internal error";
+  return new Response(JSON.stringify({ error: "internal_error", error_description: message }), {
+    status: 500,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+var init_handler_errors = __esm({
+  "src/signer/handler-errors.ts"() {
+    init_errors();
+  }
+});
+
+// src/signer/json-fields.ts
+function readStringField(body, key, errorCode, messagePrefix = "Response") {
+  const value = body[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new PmtHouseError(`${messagePrefix} missing ${key}`, {
+      status: 502,
+      code: errorCode
+    });
+  }
+  return value.trim();
+}
+function readExpiresIn(body, errorCode) {
+  const expiresIn = body.expires_in;
+  if (typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+    throw new PmtHouseError("Response missing expires_in", {
+      status: 502,
+      code: errorCode
+    });
+  }
+  return Math.floor(expiresIn);
+}
+var init_json_fields = __esm({
+  "src/signer/json-fields.ts"() {
+    init_errors();
+  }
+});
+
+// src/signer/mint-token.ts
+function parseMintUserSignerTokenResponse(body, ttlRefreshRatio = DEFAULT_TTL_REFRESH_RATIO) {
+  const accessToken = readStringField(body, "access_token", TOKEN_RESPONSE_ERROR, "Token response");
+  const expiresIn = readExpiresIn(body, TOKEN_RESPONSE_ERROR);
+  const balanceUsdMicros = readStringField(
+    body,
+    "balanceUsdMicros",
+    TOKEN_RESPONSE_ERROR,
+    "Token response"
+  );
+  const lifetimeGrantedUsdMicros = readStringField(
+    body,
+    "lifetimeGrantedUsdMicros",
+    TOKEN_RESPONSE_ERROR,
+    "Token response"
+  );
+  const now = Date.now();
+  const expiresAt = now + expiresIn * 1e3;
+  const refreshAt = now + Math.floor(expiresIn * 1e3 * ttlRefreshRatio);
+  return {
+    jwt: accessToken,
+    expiresAt,
+    refreshAt,
+    balanceUsdMicros,
+    lifetimeGrantedUsdMicros
+  };
+}
+var LIVEPEER_REMOTE_SIGNER_AUDIENCE, DEFAULT_TTL_REFRESH_RATIO, TOKEN_RESPONSE_ERROR;
+var init_mint_token = __esm({
+  "src/signer/mint-token.ts"() {
+    init_json_fields();
+    LIVEPEER_REMOTE_SIGNER_AUDIENCE = "livepeer-remote-signer";
+    DEFAULT_TTL_REFRESH_RATIO = 0.8;
+    TOKEN_RESPONSE_ERROR = "invalid_token_response";
+  }
+});
+
+// src/signer/device-exchange.ts
+function extractSignerAccessTokenFromExchangeBody(body) {
+  const tokenObj = body.token;
+  if (tokenObj !== null && typeof tokenObj === "object" && !Array.isArray(tokenObj)) {
+    const nested = tokenObj;
+    for (const key of ["accessToken", "access_token"]) {
+      const value = nested[key];
+      if (typeof value === "string" && value.trim()) {
+        return value.trim();
+      }
+    }
+  }
+  for (const key of ["accessToken", "access_token"]) {
+    const value = body[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  throw new PmtHouseError("Device exchange response missing signer access token", {
+    status: 502,
+    code: "invalid_exchange_response"
+  });
+}
+function normalizeDeviceExchangeResponse(minted, options) {
+  const scope = minted.scope.trim() || "sign:job";
+  const body = {
+    access_token: minted.access_token,
+    token_type: "Bearer",
+    expires_in: minted.expires_in,
+    scope,
+    balanceUsdMicros: minted.balanceUsdMicros,
+    lifetimeGrantedUsdMicros: minted.lifetimeGrantedUsdMicros,
+    token: {
+      accessToken: minted.access_token,
+      access_token: minted.access_token,
+      expiresIn: minted.expires_in,
+      expires_in: minted.expires_in,
+      scope,
+      balanceUsdMicros: minted.balanceUsdMicros,
+      lifetimeGrantedUsdMicros: minted.lifetimeGrantedUsdMicros
+    }
+  };
+  const signerUrl = options?.signerUrl?.trim();
+  if (signerUrl) {
+    body.signerUrl = signerUrl;
+  }
+  return body;
+}
+async function mintSignerTokenFromDeviceToken(options) {
+  const fetchImpl = options.fetch ?? fetch;
+  const issuerUrl = stripTrailingSlashes(options.issuerUrl);
+  const as = await loadAuthorizationServer(issuerUrl, fetchImpl, {
+    allowInsecureHttp: options.allowInsecureHttp
+  });
+  const tokenEndpoint = as.token_endpoint;
+  if (!tokenEndpoint) {
+    throw new PmtHouseError("OIDC discovery document is missing token_endpoint", {
+      status: 500,
+      code: "oidc_discovery_invalid"
+    });
+  }
+  const audience = options.audience?.trim() || LIVEPEER_REMOTE_SIGNER_AUDIENCE;
+  const params = new URLSearchParams({
+    grant_type: TOKEN_EXCHANGE_GRANT,
+    subject_token: options.deviceToken,
+    subject_token_type: SUBJECT_ACCESS_TOKEN_TYPE,
+    audience,
+    resource: audience
+  });
+  if (options.scope?.trim()) {
+    params.set("scope", options.scope.trim());
+  }
+  const response = await fetchImpl(tokenEndpoint, {
+    method: "POST",
+    headers: {
+      Authorization: encodeClientSecretBasic(options.m2mClientId, options.m2mClientSecret),
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    body: params.toString(),
+    cache: "no-store"
+  });
+  const parsed = await readJsonObjectFromResponse(response, {
+    invalidJsonMessage: "Token endpoint returned invalid JSON",
+    invalidJsonCode: "invalid_token_response",
+    failureLabel: "Signer JWT exchange failed",
+    defaultErrorCode: "token_exchange_failed"
+  });
+  const cached = parseMintUserSignerTokenResponse(parsed);
+  return {
+    access_token: cached.jwt,
+    expires_in: readExpiresIn(parsed, EXCHANGE_RESPONSE_ERROR),
+    scope: readStringField(parsed, "scope", EXCHANGE_RESPONSE_ERROR),
+    balanceUsdMicros: cached.balanceUsdMicros,
+    lifetimeGrantedUsdMicros: cached.lifetimeGrantedUsdMicros
+  };
+}
+var TOKEN_EXCHANGE_GRANT, SUBJECT_ACCESS_TOKEN_TYPE, EXCHANGE_RESPONSE_ERROR;
+var init_device_exchange = __esm({
+  "src/signer/device-exchange.ts"() {
+    init_discovery();
+    init_encoding();
+    init_errors();
+    init_string_utils();
+    init_fetch_json();
+    init_json_fields();
+    init_mint_token();
+    TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
+    SUBJECT_ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+    EXCHANGE_RESPONSE_ERROR = "invalid_exchange_response";
+  }
+});
+
+// src/signer/api-key-exchange.ts
+var api_key_exchange_exports = {};
+__export(api_key_exchange_exports, {
+  createApiKeyExchangeHandler: () => createApiKeyExchangeHandler,
+  exchangeApiKeyForSigner: () => exchangeApiKeyForSigner,
+  mintSignerSessionFromApiKey: () => mintSignerSessionFromApiKey,
+  mintUserAccessTokenFromApiKey: () => mintUserAccessTokenFromApiKey,
+  parseApiKeyExchangeRequestBody: () => parseApiKeyExchangeRequestBody
+});
+async function parseApiKeyExchangeRequestBody(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    throw new PmtHouseError("Request body must be JSON", {
+      status: 400,
+      code: "invalid_request"
+    });
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    throw new PmtHouseError("Request body must be a JSON object", {
+      status: 400,
+      code: "invalid_request"
+    });
+  }
+  const record = body;
+  const apiKeyRaw = record.apiKey;
+  if (typeof apiKeyRaw !== "string" || !apiKeyRaw.trim()) {
+    throw new PmtHouseError("Request body must include apiKey", {
+      status: 400,
+      code: "invalid_request"
+    });
+  }
+  const scope = typeof record.scope === "string" && record.scope.trim() ? record.scope.trim() : void 0;
+  const clientId = typeof record.clientId === "string" && record.clientId.trim() ? record.clientId.trim() : void 0;
+  return { apiKey: apiKeyRaw.trim(), scope, clientId };
+}
+async function mintUserAccessTokenFromApiKey(input) {
+  const fetchImpl = input.fetch ?? fetch;
+  const issuerOrigin = stripIssuerOriginFromOidcUrl(input.issuerUrl);
+  const url = `${issuerOrigin}/api/v1/apps/${encodeURIComponent(input.publicClientId)}/auth/api-key/token`;
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${input.apiKey}`,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(input.scope ? { scope: input.scope } : {}),
+    cache: "no-store"
+  });
+  const parsed = await readJsonObjectFromResponse(response, {
+    invalidJsonMessage: "API key token exchange returned invalid JSON",
+    invalidJsonCode: "invalid_token_response",
+    failureLabel: "API key token exchange failed",
+    defaultErrorCode: "api_key_token_exchange_failed"
+  });
+  const accessToken = parsed.access_token;
+  if (typeof accessToken !== "string" || !accessToken.trim()) {
+    throw new PmtHouseError("API key token exchange missing access_token", {
+      status: 502,
+      code: EXCHANGE_RESPONSE_ERROR2
+    });
+  }
+  const expiresIn = typeof parsed.expires_in === "number" && Number.isFinite(parsed.expires_in) ? parsed.expires_in : 900;
+  const scope = typeof parsed.scope === "string" && parsed.scope.trim() ? parsed.scope.trim() : input.scope?.trim() || "sign:job";
+  return {
+    access_token: accessToken.trim(),
+    expires_in: expiresIn,
+    scope
+  };
+}
+async function mintSignerSessionFromApiKey(input) {
+  const userToken = await mintUserAccessTokenFromApiKey({
+    issuerUrl: input.issuerUrl,
+    publicClientId: input.publicClientId,
+    apiKey: input.apiKey,
+    scope: input.scope,
+    fetch: input.fetch
+  });
+  return mintSignerTokenFromDeviceToken({
+    issuerUrl: input.issuerUrl,
+    m2mClientId: input.m2mClientId,
+    m2mClientSecret: input.m2mClientSecret,
+    deviceToken: userToken.access_token,
+    scope: userToken.scope,
+    audience: input.audience,
+    fetch: input.fetch,
+    allowInsecureHttp: input.allowInsecureHttp
+  });
+}
+async function exchangeApiKeyForSigner(options) {
+  const fetchImpl = options.fetch ?? fetch;
+  const url = `${stripTrailingSlashes(options.facadeUrl)}/api/pymthouse/keys/exchange`;
+  const body = { apiKey: options.apiKey };
+  if (options.scope?.trim()) {
+    body.scope = options.scope.trim();
+  }
+  if (options.clientId?.trim()) {
+    body.clientId = options.clientId.trim();
+  }
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(body),
+    cache: "no-store"
+  });
+  const parsed = await readJsonObjectFromResponse(response, {
+    invalidJsonMessage: "API key exchange returned invalid JSON",
+    invalidJsonCode: EXCHANGE_RESPONSE_ERROR2,
+    failureLabel: "API key exchange failed",
+    defaultErrorCode: "api_key_exchange_failed"
+  });
+  const accessToken = extractSignerAccessTokenFromExchangeBody(parsed);
+  const signerUrlRaw = parsed.signerUrl ?? parsed.signer_url;
+  const signerUrl = typeof signerUrlRaw === "string" && signerUrlRaw.trim() ? signerUrlRaw.trim() : void 0;
+  return normalizeDeviceExchangeResponse(
+    {
+      access_token: accessToken,
+      expires_in: typeof parsed.expires_in === "number" && Number.isFinite(parsed.expires_in) ? parsed.expires_in : 3600,
+      scope: typeof parsed.scope === "string" && parsed.scope.trim() ? parsed.scope.trim() : "sign:job",
+      balanceUsdMicros: typeof parsed.balanceUsdMicros === "string" ? parsed.balanceUsdMicros : "0",
+      lifetimeGrantedUsdMicros: typeof parsed.lifetimeGrantedUsdMicros === "string" ? parsed.lifetimeGrantedUsdMicros : "0"
+    },
+    { signerUrl }
+  );
+}
+function createApiKeyExchangeHandler(config) {
+  const publicClientId = config.publicClientId.trim();
+  return async function apiKeyExchangeHandler(request) {
+    try {
+      if (request.method !== "POST") {
+        return new Response(JSON.stringify({ error: "method_not_allowed" }), {
+          status: 405,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      const parsed = await parseApiKeyExchangeRequestBody(request);
+      const effectiveClientId = parsed.clientId?.trim() || publicClientId;
+      if (effectiveClientId !== publicClientId) {
+        throw new PmtHouseError("clientId does not match configured public client", {
+          status: 400,
+          code: "invalid_request"
+        });
+      }
+      const minted = await mintSignerSessionFromApiKey({
+        issuerUrl: config.issuerUrl,
+        publicClientId,
+        m2mClientId: config.m2mClientId,
+        m2mClientSecret: config.m2mClientSecret,
+        apiKey: parsed.apiKey,
+        scope: parsed.scope,
+        audience: config.audience,
+        fetch: config.fetch,
+        allowInsecureHttp: config.allowInsecureHttp
+      });
+      const signerUrlValue = typeof config.signerUrl === "string" && config.signerUrl.trim() ? config.signerUrl.trim() : void 0;
+      const body = normalizeDeviceExchangeResponse(minted, { signerUrl: signerUrlValue });
+      return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: {
+          "Content-Type": "application/json",
+          "Cache-Control": "no-store"
+        }
+      });
+    } catch (error) {
+      return signerHandlerErrorResponse(error);
+    }
+  };
+}
+var EXCHANGE_RESPONSE_ERROR2;
+var init_api_key_exchange = __esm({
+  "src/signer/api-key-exchange.ts"() {
+    init_string_utils();
+    init_errors();
+    init_fetch_json();
+    init_handler_errors();
+    init_device_exchange();
+    EXCHANGE_RESPONSE_ERROR2 = "invalid_exchange_response";
+  }
+});
+
+// src/client.ts
+init_encoding();
+init_discovery();
+init_errors();
+function parseAppManifestResponse(json) {
+  if (!json || typeof json !== "object" || Array.isArray(json)) {
+    return { capabilities: [], excludedCapabilities: [] };
+  }
+  const record = json;
+  const capabilities = parseCapabilityArray(record.capabilities);
+  const excludedCapabilities = parseCapabilityArray(record.excludedCapabilities);
+  const manifestVersion = typeof record.manifestVersion === "string" && record.manifestVersion.trim() ? record.manifestVersion.trim() : void 0;
+  return { capabilities, excludedCapabilities, manifestVersion };
+}
+function parseCapabilityArray(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (c) => !!c && typeof c === "object" && typeof c.pipeline === "string" && typeof c.modelId === "string"
+  );
+}
+
+// src/client.ts
+init_string_utils();
+
+// src/tokens.ts
+var SIGNER_SESSION_TTL_MS = 90 * 24 * 60 * 60 * 1e3;
+var SIGNER_SESSION_EXPIRES_IN_SEC = Math.floor(SIGNER_SESSION_TTL_MS / 1e3);
+var SIGN_JOB_SCOPE = "sign:job";
+function isLikelyOidcJwt(rawToken) {
+  const t = rawToken.trim();
+  return t.startsWith("eyJ") && t.split(".").length >= 3;
+}
+function parseSignerSessionExchange(res) {
+  const accessToken = typeof res.access_token === "string" ? res.access_token.trim() : "";
+  if (!accessToken) {
+    throw new Error("PymtHouse signer session exchange returned no access_token");
+  }
+  if (isLikelyOidcJwt(accessToken)) {
+    throw new Error(
+      "PymtHouse signer session exchange returned a JWT; expected opaque signer session token"
+    );
+  }
+  const tokenType = typeof res.token_type === "string" && res.token_type.trim() ? res.token_type.trim() : "Bearer";
+  const expiresIn = typeof res.expires_in === "number" && Number.isFinite(res.expires_in) && res.expires_in > 0 ? Math.floor(res.expires_in) : SIGNER_SESSION_EXPIRES_IN_SEC;
+  const scope = typeof res.scope === "string" && res.scope.trim() ? res.scope.trim() : SIGN_JOB_SCOPE;
+  return {
+    accessToken,
+    tokenType,
+    expiresIn,
+    scope
+  };
+}
+
+// src/usage.ts
+function parseSafeBigInt(value, fallback = 0n) {
+  try {
+    return BigInt(value);
+  } catch {
+    return fallback;
+  }
+}
+function getEndUserIdsForExternalUser(usage, externalUserId) {
+  const userIds = /* @__PURE__ */ new Set();
+  for (const row of usage.byUser ?? []) {
+    if (row.externalUserId === externalUserId && row.endUserId !== "unknown") {
+      userIds.add(row.endUserId);
+    }
+  }
+  return [...userIds];
+}
+function summarizeUsageFiatForExternalUser(usageByUser, externalUserId) {
+  const rows = usageByUser.byUser ?? [];
+  let requestCount = 0;
+  let networkFeeUsdMicros = 0n;
+  let ownerChargeUsdMicros = 0n;
+  let endUserBillableUsdMicros = 0n;
+  let currency = "USD";
+  for (const row of rows) {
+    if (row.externalUserId !== externalUserId) continue;
+    requestCount += row.requestCount;
+    if (row.currency) currency = row.currency;
+    if (row.networkFeeUsdMicros) {
+      networkFeeUsdMicros += BigInt(row.networkFeeUsdMicros);
+    }
+    if (row.ownerChargeUsdMicros) {
+      ownerChargeUsdMicros += BigInt(row.ownerChargeUsdMicros);
+    }
+    if (row.endUserBillableUsdMicros) {
+      endUserBillableUsdMicros += BigInt(row.endUserBillableUsdMicros);
+    }
+  }
+  return {
+    externalUserId,
+    requestCount,
+    currency,
+    networkFeeUsdMicros: networkFeeUsdMicros.toString(),
+    ownerChargeUsdMicros: ownerChargeUsdMicros.toString(),
+    endUserBillableUsdMicros: endUserBillableUsdMicros.toString()
+  };
+}
+function mergeUsageByPipelineModel(usagePipelineModels) {
+  let responses;
+  if (Array.isArray(usagePipelineModels)) {
+    responses = usagePipelineModels;
+  } else if (usagePipelineModels) {
+    responses = [usagePipelineModels];
+  } else {
+    responses = [];
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const response of responses) {
+    for (const row of response.byPipelineModel ?? []) {
+      const { pipeline, modelId } = row;
+      if (!pipeline || !modelId) continue;
+      const key = JSON.stringify([pipeline, modelId]);
+      const existing = byKey.get(key);
+      const rowCurrency = row.currency ?? "USD";
+      const networkFee = row.networkFeeUsdMicros ?? "0";
+      const ownerCharge = row.ownerChargeUsdMicros ?? "0";
+      const endUserBillable = row.endUserBillableUsdMicros ?? "0";
+      if (!existing) {
+        byKey.set(key, {
+          pipeline,
+          modelId,
+          requestCount: row.requestCount,
+          currency: rowCurrency,
+          networkFeeUsdMicros: networkFee,
+          ownerChargeUsdMicros: ownerCharge,
+          endUserBillableUsdMicros: endUserBillable
+        });
+        continue;
+      }
+      byKey.set(key, {
+        ...existing,
+        requestCount: existing.requestCount + row.requestCount,
+        networkFeeUsdMicros: (parseSafeBigInt(existing.networkFeeUsdMicros) + parseSafeBigInt(networkFee)).toString(),
+        ownerChargeUsdMicros: (parseSafeBigInt(existing.ownerChargeUsdMicros) + parseSafeBigInt(ownerCharge)).toString(),
+        endUserBillableUsdMicros: (parseSafeBigInt(existing.endUserBillableUsdMicros) + parseSafeBigInt(endUserBillable)).toString()
+      });
+    }
+  }
+  return [...byKey.values()].sort((a, b) => {
+    if (a.pipeline === b.pipeline) return a.modelId.localeCompare(b.modelId);
+    return a.pipeline.localeCompare(b.pipeline);
+  });
+}
+function buildMeScopeUsagePayload(usageByUser, externalUserId, usagePipelineModel, usageDaily) {
+  const summary = summarizeUsageFiatForExternalUser(usageByUser, externalUserId);
+  const pipelineModels = mergeUsageByPipelineModel(usagePipelineModel);
+  const dailyByPipeline = usageDaily?.byDailyPipeline ?? [];
+  return {
+    clientId: usageByUser.clientId,
+    period: usageByUser.period,
+    currentUser: {
+      externalUserId: summary.externalUserId,
+      requestCount: summary.requestCount,
+      currency: summary.currency,
+      networkFeeUsdMicros: summary.networkFeeUsdMicros,
+      ownerChargeUsdMicros: summary.ownerChargeUsdMicros,
+      endUserBillableUsdMicros: summary.endUserBillableUsdMicros,
+      pipelineModels,
+      dailyByPipeline
+    }
+  };
+}
+var DEFAULT_MAX_END_USER_IDS = 25;
+
+// src/oauth-map.ts
+init_errors();
 var ACCEPTED_ISSUED_TOKEN_TYPES = /* @__PURE__ */ new Set([
   "urn:ietf:params:oauth:token-type:access_token",
   "urn:pmth:token-type:remote-signer-session"
@@ -213,9 +860,94 @@ function m2mClient(clientId) {
   return { client_id: clientId };
 }
 
+// src/ingest.ts
+init_encoding();
+init_errors();
+init_string_utils();
+function ingestUrl(issuerUrl, publicClientId) {
+  const origin = new URL(stripTrailingSlashes(issuerUrl)).origin;
+  return `${origin}/api/v1/apps/${encodeURIComponent(publicClientId)}/usage/signed-tickets`;
+}
+async function readJsonResponse(response) {
+  const text = await response.text();
+  if (!text.trim()) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(text);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function ingestSignedTicket(options) {
+  const fetchImpl = options.fetch ?? fetch;
+  const url = ingestUrl(options.issuerUrl, options.publicClientId);
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      Authorization: encodeClientSecretBasic(options.m2mClientId, options.m2mClientSecret),
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify(options.ticket),
+    cache: "no-store"
+  });
+  const body = await readJsonResponse(response);
+  if (!response.ok) {
+    const message = typeof body.error === "string" ? body.error : `Signed-ticket ingest failed (${response.status})`;
+    throw new PmtHouseError(message, {
+      status: response.status,
+      code: "ingest_failed",
+      details: body
+    });
+  }
+  return {
+    ingested: Boolean(body.ingested),
+    duplicate: Boolean(body.duplicate),
+    source: body.source === "openmeter" ? "openmeter" : "disabled"
+  };
+}
+async function ingestSignedTicketsBatch(options) {
+  const fetchImpl = options.fetch ?? fetch;
+  const url = ingestUrl(options.issuerUrl, options.publicClientId);
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      Authorization: encodeClientSecretBasic(options.m2mClientId, options.m2mClientSecret),
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    },
+    body: JSON.stringify({ tickets: options.tickets }),
+    cache: "no-store"
+  });
+  const body = await readJsonResponse(response);
+  if (!response.ok) {
+    const message = typeof body.error === "string" ? body.error : `Signed-ticket batch ingest failed (${response.status})`;
+    throw new PmtHouseError(message, {
+      status: response.status,
+      code: "ingest_failed",
+      details: body
+    });
+  }
+  const rawResults = Array.isArray(body.results) ? body.results : [];
+  return {
+    results: rawResults.map((entry) => {
+      const row = entry ?? {};
+      return {
+        requestId: typeof row.requestId === "string" ? row.requestId : void 0,
+        ok: row.ok === true,
+        ingested: Boolean(row.ingested),
+        duplicate: Boolean(row.duplicate),
+        source: row.source === "openmeter" ? "openmeter" : "disabled"
+      };
+    })
+  };
+}
+
 // src/client.ts
-var TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
-var SUBJECT_ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+var TOKEN_EXCHANGE_GRANT2 = "urn:ietf:params:oauth:grant-type:token-exchange";
+var SUBJECT_ACCESS_TOKEN_TYPE2 = "urn:ietf:params:oauth:token-type:access_token";
 var REQUESTED_ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
 var DEVICE_RESOURCE_PREFIX = "urn:pmth:device_code:";
 function normalizeUserCode(value) {
@@ -342,6 +1074,50 @@ var PmtHouseClient = class {
       cache: "no-store"
     });
   }
+  /**
+   * Exchange a long-lived dashboard API key (`pmth_*`) for a short-lived user JWT.
+   */
+  async exchangeApiKeyForUserAccessToken(input) {
+    const url = `${this.getAppsBaseUrl()}/auth/api-key/token`;
+    return this.requestJson(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${input.apiKey.trim()}`,
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      },
+      body: JSON.stringify(input.scope ? { scope: input.scope } : {}),
+      cache: "no-store"
+    });
+  }
+  /**
+   * Exchange a dashboard API key for a signer session via a trusted facade (recommended)
+   * or directly when M2M credentials are available on this client.
+   */
+  async exchangeApiKeyForSignerSession(input) {
+    if (input.facadeUrl?.trim()) {
+      const { exchangeApiKeyForSigner: exchangeApiKeyForSigner2 } = await Promise.resolve().then(() => (init_api_key_exchange(), api_key_exchange_exports));
+      const exchanged = await exchangeApiKeyForSigner2({
+        facadeUrl: input.facadeUrl.trim(),
+        apiKey: input.apiKey,
+        scope: input.scope,
+        clientId: this.publicClientId,
+        fetch: this.fetchImpl
+      });
+      return {
+        access_token: exchanged.access_token,
+        token_type: exchanged.token_type,
+        expires_in: exchanged.expires_in,
+        scope: exchanged.scope,
+        issued_token_type: "urn:ietf:params:oauth:token-type:access_token"
+      };
+    }
+    const userToken = await this.exchangeApiKeyForUserAccessToken({
+      apiKey: input.apiKey,
+      scope: input.scope
+    });
+    return this.exchangeForSignerSession({ userJwt: userToken.access_token });
+  }
   async completeDeviceApproval(input) {
     const as = await loadAuthorizationServer(this.issuerUrl, this.fetchImpl, {
       allowInsecureHttp: this.allowInsecureHttp
@@ -350,14 +1126,14 @@ var PmtHouseClient = class {
     const clientAuth = this.m2mClientAuth();
     const params = new URLSearchParams();
     params.set("subject_token", input.userJwt);
-    params.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE);
+    params.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE2);
     params.set("resource", buildDeviceCodeResource(input.userCode));
     try {
       const response = await genericTokenEndpointRequest(
         as,
         client,
         clientAuth,
-        TOKEN_EXCHANGE_GRANT,
+        TOKEN_EXCHANGE_GRANT2,
         params,
         this.tokenEndpointFetchOptions()
       );
@@ -405,7 +1181,7 @@ var PmtHouseClient = class {
     const clientAuth = this.m2mClientAuth();
     const params = new URLSearchParams();
     params.set("subject_token", input.userJwt);
-    params.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE);
+    params.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE2);
     params.set("requested_token_type", REQUESTED_ACCESS_TOKEN_TYPE);
     const resourceCandidate = typeof input.resource === "string" && input.resource.trim() !== "" ? input.resource.trim() : this.issuerUrl;
     params.set("resource", stripTrailingSlashes(resourceCandidate));
@@ -414,7 +1190,7 @@ var PmtHouseClient = class {
         as,
         client,
         clientAuth,
-        TOKEN_EXCHANGE_GRANT,
+        TOKEN_EXCHANGE_GRANT2,
         params,
         this.tokenEndpointFetchOptions()
       );
@@ -470,12 +1246,267 @@ var PmtHouseClient = class {
     if (input.groupBy) url.searchParams.set("groupBy", input.groupBy);
     if (input.userId) url.searchParams.set("userId", input.userId);
     if (input.gatewayRequestId) url.searchParams.set("gatewayRequestId", input.gatewayRequestId);
+    if (input.includeRetail) url.searchParams.set("include", "retail");
+    return this.requestJson(url.toString(), {
+      method: "GET",
+      headers: this.builderHeaders(),
+      cache: "no-store"
+    });
+  }
+  /**
+   * Session-scoped usage for one `externalUserId`: user rollup plus merged pipeline/model breakdown.
+   */
+  async ingestSignedTicket(ticket) {
+    return ingestSignedTicket({
+      issuerUrl: this.issuerUrl,
+      publicClientId: this.publicClientId,
+      m2mClientId: this.m2mClientId,
+      m2mClientSecret: this.m2mClientSecret,
+      ticket,
+      fetch: this.fetchImpl
+    });
+  }
+  async ingestSignedTickets(tickets) {
+    return ingestSignedTicketsBatch({
+      issuerUrl: this.issuerUrl,
+      publicClientId: this.publicClientId,
+      m2mClientId: this.m2mClientId,
+      m2mClientSecret: this.m2mClientSecret,
+      tickets,
+      fetch: this.fetchImpl
+    });
+  }
+  async getSignerRouting() {
+    return this.requestJson(
+      `${this.getAppsBaseUrl()}/signer/routing`,
+      {
+        method: "GET",
+        headers: this.builderHeaders(),
+        cache: "no-store"
+      }
+    );
+  }
+  async listBillingProducts() {
+    const url = `${this.getAppsBaseUrl()}/plans?apiVersion=2`;
+    const body = await this.requestJson(
+      url,
+      {
+        method: "GET",
+        headers: this.builderHeaders(),
+        cache: "no-store"
+      }
+    );
+    return {
+      apiVersion: body.apiVersion ?? 2,
+      products: body.products ?? body.plans ?? []
+    };
+  }
+  async syncBillingProduct(planId) {
+    return this.requestJson(
+      `${this.getAppsBaseUrl()}/plans/${encodeURIComponent(planId)}/sync`,
+      {
+        method: "POST",
+        headers: this.builderHeaders(),
+        cache: "no-store"
+      }
+    );
+  }
+  async getUsageBalance(externalUserId) {
+    const url = new URL(`${this.getAppsBaseUrl()}/usage/balance`);
+    url.searchParams.set("externalUserId", externalUserId);
     return this.requestJson(url.toString(), {
       method: "GET",
       headers: this.builderHeaders(),
       cache: "no-store"
     });
   }
+  async getUserAllowances(externalUserId) {
+    return this.requestJson(
+      `${this.getAppsBaseUrl()}/users/${encodeURIComponent(externalUserId)}/allowances`,
+      {
+        method: "GET",
+        headers: this.builderHeaders(),
+        cache: "no-store"
+      }
+    );
+  }
+  async grantUserAllowance(externalUserId, input) {
+    return this.requestJson(
+      `${this.getAppsBaseUrl()}/users/${encodeURIComponent(externalUserId)}/allowances`,
+      {
+        method: "POST",
+        headers: this.builderHeaders(),
+        body: JSON.stringify(input),
+        cache: "no-store"
+      }
+    );
+  }
+  /**
+   * @deprecated Removed from PymtHouse — use {@link getUsageBalance} or {@link getUserAllowances}.
+   */
+  async getUserCredits(externalUserId) {
+    return this.getUsageBalance(externalUserId);
+  }
+  /**
+   * @deprecated Removed from PymtHouse — use {@link grantUserAllowance} (`POST .../allowances`).
+   */
+  async grantUserCredits(externalUserId, input) {
+    const result = await this.grantUserAllowance(externalUserId, {
+      amountUsdMicros: input.amountUsdMicros,
+      source: input.source ?? "manual",
+      featureKey: input.featureKey
+    });
+    const flat = result;
+    const nested = result.allowances;
+    return {
+      externalUserId: result.externalUserId,
+      balanceUsdMicros: flat.balanceUsdMicros ?? nested?.balanceUsdMicros ?? "0",
+      consumedUsdMicros: flat.consumedUsdMicros ?? nested?.consumedUsdMicros ?? "0",
+      lifetimeGrantedUsdMicros: flat.lifetimeGrantedUsdMicros ?? nested?.lifetimeGrantedUsdMicros ?? "0",
+      hasAccess: flat.hasAccess ?? nested?.hasAccess ?? false,
+      remainingUsdMicros: flat.balanceUsdMicros ?? nested?.balanceUsdMicros,
+      grantedUsdMicros: flat.grantedUsdMicros,
+      featureKey: flat.featureKey
+    };
+  }
+  async getUserSubscription(externalUserId) {
+    return this.requestJson(
+      `${this.getAppsBaseUrl()}/users/${encodeURIComponent(externalUserId)}/subscription`,
+      {
+        method: "GET",
+        headers: this.builderHeaders(),
+        cache: "no-store"
+      }
+    );
+  }
+  async fetchUsageForExternalUser(input) {
+    const usageByUser = await this.getUsage({
+      startDate: input.startDate,
+      endDate: input.endDate,
+      groupBy: "user"
+    });
+    const userIds = getEndUserIdsForExternalUser(usageByUser, input.externalUserId);
+    const cap = input.maxEndUserIds ?? DEFAULT_MAX_END_USER_IDS;
+    const cappedUserIds = userIds.slice(0, cap);
+    const usagePipelineModels = await Promise.all(
+      cappedUserIds.map(
+        (userId) => this.getUsage({
+          startDate: input.startDate,
+          endDate: input.endDate,
+          groupBy: "pipeline_model",
+          userId
+        })
+      )
+    );
+    const usageDaily = await this.getUsage({
+      startDate: input.startDate,
+      endDate: input.endDate,
+      groupBy: "daily_pipeline",
+      userId: input.externalUserId
+    });
+    return buildMeScopeUsagePayload(
+      usageByUser,
+      input.externalUserId,
+      usagePipelineModels,
+      usageDaily
+    );
+  }
+  async getAppManifest(opts) {
+    const url = `${this.getAppsBaseUrl()}/manifest`;
+    const headers = {
+      ...this.builderHeadersRecord()
+    };
+    if (opts?.ifNoneMatch) {
+      headers["If-None-Match"] = opts.ifNoneMatch;
+    }
+    this.logger?.debug?.("PmtHouse request", { method: "GET", url });
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers,
+      signal: opts?.signal,
+      cache: "no-store"
+    });
+    const etag = response.headers.get("etag")?.trim() ?? null;
+    if (response.status === 304) {
+      return {
+        manifest: null,
+        etag: etag ?? opts?.ifNoneMatch ?? null,
+        notModified: true
+      };
+    }
+    const raw = await response.text();
+    const ct = response.headers.get("content-type") ?? "";
+    const looksJson = ct.includes("application/json") || ct.includes("json");
+    const parsed = raw && looksJson ? this.safeParseJson(raw) : null;
+    if (!response.ok) {
+      const details = parsed ?? {};
+      let description;
+      if (typeof details.error_description === "string") {
+        description = details.error_description;
+      } else if (typeof details.error === "string") {
+        description = details.error;
+      } else {
+        description = `Request failed (${response.status})`;
+      }
+      throw new PmtHouseError(description, {
+        status: response.status,
+        code: typeof details.error === "string" ? details.error : "pymthouse_http_error",
+        details
+      });
+    }
+    if (!looksJson || parsed === null) {
+      throw new PmtHouseError("Expected JSON response from Builder manifest endpoint", {
+        status: 502,
+        code: "invalid_response",
+        details: { contentType: ct, preview: raw.slice(0, 200) }
+      });
+    }
+    return {
+      manifest: parseAppManifestResponse(parsed),
+      etag,
+      notModified: false
+    };
+  }
+  /**
+   * Upsert an external user, mint a short-lived JWT, and exchange for an opaque signer session.
+   */
+  async mintSignerSessionForExternalUser(input) {
+    await this.upsertAppUser({
+      externalUserId: input.externalUserId,
+      email: input.email,
+      status: "active"
+    });
+    const exchange = await this.mintUserSignerSessionToken({
+      externalUserId: input.externalUserId,
+      scope: input.scope ?? SIGN_JOB_SCOPE,
+      resource: this.issuerUrl
+    });
+    return parseSignerSessionExchange(exchange);
+  }
+  /**
+   * Approve a pending RFC 8628 device code for an external user (Option B).
+   */
+  async approveDeviceLogin(input) {
+    if (input.publicClientId && input.publicClientId !== this.publicClientId) {
+      throw new PmtHouseError(
+        "publicClientId does not match configured public client id",
+        { status: 400, code: "invalid_client" }
+      );
+    }
+    await this.upsertAppUser({
+      externalUserId: input.externalUserId,
+      email: input.email,
+      status: "active"
+    });
+    const userToken = await this.mintUserAccessToken({
+      externalUserId: input.externalUserId,
+      scope: SIGN_JOB_SCOPE
+    });
+    await this.completeDeviceApproval({
+      userJwt: userToken.access_token,
+      userCode: input.userCode
+    });
+  }
   tokenEndpointFetchOptions() {
     const o = {
       [customFetch]: this.fetchImpl
@@ -492,6 +1523,9 @@ var PmtHouseClient = class {
     return new URL(this.issuerUrl).origin;
   }
   builderHeaders() {
+    return this.builderHeadersRecord();
+  }
+  builderHeadersRecord() {
     return {
       Authorization: encodeClientSecretBasic(this.m2mClientId, this.m2mClientSecret),
       "Content-Type": "application/json",
@@ -515,7 +1549,14 @@ var PmtHouseClient = class {
     const parsed = raw && looksJson ? this.safeParseJson(raw) : raw ? null : null;
     if (!response.ok) {
       const details = parsed ?? {};
-      const description = typeof details.error_description === "string" ? details.error_description : typeof details.error === "string" ? details.error : `Request failed (${response.status})`;
+      let description;
+      if (typeof details.error_description === "string") {
+        description = details.error_description;
+      } else if (typeof details.error === "string") {
+        description = details.error;
+      } else {
+        description = `Request failed (${response.status})`;
+      }
       throw new PmtHouseError(description, {
         status: response.status,
         code: typeof details.error === "string" ? details.error : "pymthouse_http_error",
@@ -559,6 +1600,8 @@ var PmtHouseClient = class {
 };
 
 // src/env.ts
+init_errors();
+init_string_utils();
 function assertEnvModuleServerOnly() {
   if (typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined") {
     throw new Error(