@everfur/sdk 0.1.0

package/dist/server/index.js

@@ -0,0 +1,530 @@
+// src/client/errors/EverfurResult.ts
+function ok(value, warning) {
+  return Object.freeze(
+    { ok: true, value } 
+  );
+}
+function err(error) {
+  return Object.freeze({ ok: false, error });
+}
+var EverfurConfigError = class _EverfurConfigError extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.name = "EverfurConfigError";
+    this.kind = kind;
+    Object.setPrototypeOf(this, _EverfurConfigError.prototype);
+  }
+};
+
+// src/client/config.ts
+var SDK_VERSION = "0.1.0";
+var SDK_PLATFORM = "react-native";
+var DEFAULT_CONTRACT_VERSION = "2026-08-01";
+var ENV_API_BASE_URL = "EVERFUR_API_BASE_URL";
+function configFailure(reason, message) {
+  return Object.freeze({ ok: false, failure: Object.freeze({ reason, message }) });
+}
+function tryResolveApiBaseUrl(apiBaseUrl) {
+  const explicit = apiBaseUrl?.trim();
+  const candidate = explicit && explicit.length > 0 ? explicit : readEnv(ENV_API_BASE_URL);
+  if (!candidate) {
+    return configFailure(
+      "missing-api-base-url",
+      `apiBaseUrl is required: pass config.apiBaseUrl or set ${ENV_API_BASE_URL}. The SDK never ships a hardcoded host.`
+    );
+  }
+  return normalizeBaseUrl(candidate);
+}
+function resolveApiBaseUrl(apiBaseUrl) {
+  const outcome = tryResolveApiBaseUrl(apiBaseUrl);
+  if (!outcome.ok) {
+    throw new EverfurConfigError("invalid-argument", outcome.failure.message);
+  }
+  return outcome.value;
+}
+function buildBaseHeaders(cfg) {
+  return {
+    "X-Everfur-SDK-Version": cfg.sdkVersion,
+    "X-Everfur-SDK-Platform": cfg.platform,
+    "X-Everfur-Contract": cfg.contractVersion
+  };
+}
+var ABSOLUTE_URL = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)/;
+function hostOf(authority) {
+  const afterUserinfo = authority.slice(authority.lastIndexOf("@") + 1);
+  return afterUserinfo.replace(/:\d+$/, "").toLowerCase();
+}
+function isPrintableHost(host) {
+  if (host.length === 0) return false;
+  if (host.includes("@")) return false;
+  if (host.startsWith("[") && host.endsWith("]")) return true;
+  return !host.includes(":");
+}
+function canEchoOrigin(rawTrimmed, host) {
+  const schemeEnd = rawTrimmed.indexOf("://");
+  if (schemeEnd < 0) return false;
+  if (rawTrimmed.slice(schemeEnd + 3).includes("@")) return false;
+  return isPrintableHost(host);
+}
+function safeOrigin(scheme, host) {
+  return `${scheme}://${host}`;
+}
+function normalizeBaseUrl(raw) {
+  const trimmed = raw.trim();
+  const match = ABSOLUTE_URL.exec(trimmed);
+  if (match === null || match[2] === void 0 || match[2].length === 0) {
+    return configFailure("malformed-api-base-url", "apiBaseUrl is not a valid absolute URL");
+  }
+  const scheme = (match[1] ?? "").toLowerCase();
+  const host = hostOf(match[2]);
+  if (host.length === 0) {
+    return configFailure("malformed-api-base-url", "apiBaseUrl is not a valid absolute URL");
+  }
+  const shown = canEchoOrigin(trimmed, host) ? `: ${safeOrigin(scheme, host)}` : "";
+  if (scheme === "https") ; else if (scheme === "http" && isLoopbackHost(host)) ; else if (scheme === "http") {
+    return configFailure(
+      "insecure-api-base-url",
+      `apiBaseUrl must use https (cleartext http is only allowed for localhost)${shown}`
+    );
+  } else {
+    return configFailure("unsupported-api-base-url-scheme", `apiBaseUrl must be http(s)${shown}`);
+  }
+  const value = trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+  return Object.freeze({ ok: true, value });
+}
+function isLoopbackHost(hostname) {
+  const host = hostname.toLowerCase();
+  return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
+}
+function readEnv(name) {
+  const g = globalThis;
+  const value = g.process?.env?.[name];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+var CONTRACT_RETRYABILITY = Object.freeze([
+  Object.freeze({ wireCode: "AccessDeniedException", envelope: "http_envelope", httpStatus: 403, retryable: false }),
+  Object.freeze({ wireCode: "AuthorizationException", envelope: "http_envelope", httpStatus: 401, retryable: false }),
+  Object.freeze({ wireCode: "ConflictException", envelope: "http_envelope", httpStatus: 409, retryable: true }),
+  Object.freeze({ wireCode: "DAILY_QUOTA_EXCEEDED", envelope: "http_envelope", httpStatus: 429, retryable: true }),
+  Object.freeze({ wireCode: "IDEMPOTENCY_KEY_IN_FLIGHT", envelope: "http_envelope", httpStatus: 409, retryable: true }),
+  Object.freeze({ wireCode: "IDEMPOTENCY_KEY_REUSED_DIFFERENT_REQUEST", envelope: "http_envelope", httpStatus: 409, retryable: false }),
+  Object.freeze({ wireCode: "InternalFailureException", envelope: "http_envelope", httpStatus: 500, retryable: true }),
+  Object.freeze({ wireCode: "NotImplementedException", envelope: "http_envelope", httpStatus: 501, retryable: false }),
+  Object.freeze({ wireCode: "PaymentRequiredException", envelope: "http_envelope", httpStatus: 402, retryable: false }),
+  Object.freeze({ wireCode: "ResourceNotFoundException", envelope: "http_envelope", httpStatus: 404, retryable: false }),
+  Object.freeze({ wireCode: "ServiceUnavailableException", envelope: "http_envelope", httpStatus: 503, retryable: true }),
+  Object.freeze({ wireCode: "TIER_UPGRADE_REQUIRED", envelope: "http_envelope", httpStatus: 402, retryable: false }),
+  Object.freeze({ wireCode: "ThrottlingException", envelope: "http_envelope", httpStatus: 429, retryable: true }),
+  Object.freeze({ wireCode: "ValidationException", envelope: "http_envelope", httpStatus: 400, retryable: false }),
+  Object.freeze({ wireCode: "accessDenied", envelope: "http_envelope", httpStatus: 403, retryable: false }),
+  Object.freeze({ wireCode: "authExpired", envelope: "http_envelope", httpStatus: 401, retryable: true }),
+  Object.freeze({ wireCode: "internal_error", envelope: "sse_frame", httpStatus: 200, retryable: false }),
+  Object.freeze({ wireCode: "invalidRequest", envelope: "http_envelope", httpStatus: 400, retryable: false }),
+  Object.freeze({ wireCode: "not_found", envelope: "sse_frame", httpStatus: 200, retryable: false }),
+  Object.freeze({ wireCode: "session_required", envelope: "http_envelope", httpStatus: 403, retryable: false }),
+  Object.freeze({ wireCode: "timeout", envelope: "sse_frame", httpStatus: 200, retryable: true }),
+  Object.freeze({ wireCode: "unavailable", envelope: "http_envelope", httpStatus: 503, retryable: true })
+]);
+Object.freeze(
+  CONTRACT_RETRYABILITY.map((row) => row.wireCode)
+);
+
+// src/client/errors/contract.ts
+var NORMALIZED_FOLD = Object.freeze({
+  // the default status-mapped envelope
+  ValidationException: "validationFailed",
+  AuthorizationException: "authRejected",
+  PaymentRequiredException: "paymentRequired",
+  AccessDeniedException: "accessDenied",
+  ResourceNotFoundException: "resourceNotFound",
+  ConflictException: "conflict",
+  ThrottlingException: "rateLimited",
+  InternalFailureException: "internalError",
+  NotImplementedException: "notImplemented",
+  ServiceUnavailableException: "serviceUnavailable",
+  // dict-detail codes on the widget surface
+  authExpired: "authExpired",
+  unavailable: "serviceUnavailable",
+  session_required: "sessionRequired",
+  accessDenied: "accessDenied",
+  invalidRequest: "sdkUpdateRequired",
+  // typed codes
+  IDEMPOTENCY_KEY_IN_FLIGHT: "idempotencyInFlight",
+  IDEMPOTENCY_KEY_REUSED_DIFFERENT_REQUEST: "idempotencyConflict",
+  DAILY_QUOTA_EXCEEDED: "quotaExceeded",
+  TIER_UPGRADE_REQUIRED: "paymentRequired",
+  // SSE error frames
+  not_found: "conversationNotFound",
+  timeout: "streamTimeout",
+  internal_error: "internalError"
+});
+var CONTRACT_ERROR_ROWS = Object.freeze(
+  CONTRACT_RETRYABILITY.map(
+    (generated) => Object.freeze({
+      wireCode: generated.wireCode,
+      envelope: generated.envelope,
+      retryable: generated.retryable,
+      normalized: NORMALIZED_FOLD[generated.wireCode]
+    })
+  )
+);
+var BY_UPPER = new Map(
+  CONTRACT_ERROR_ROWS.map((r) => [r.wireCode.toUpperCase(), r])
+);
+function contractErrorFor(wireCode) {
+  if (typeof wireCode !== "string") return void 0;
+  const key = wireCode.trim().toUpperCase();
+  return key.length > 0 ? BY_UPPER.get(key) : void 0;
+}
+var CATEGORY_OF = Object.freeze({
+  // the caller's sign-in state is wrong and a credential change is the remedy
+  authExpired: "authentication",
+  authRejected: "authentication",
+  sessionRequired: "authentication",
+  // signed in, correctly identified, and still not allowed
+  accessDenied: "authorization",
+  // a plan gate, not a permission failure: the remedy is commercial
+  paymentRequired: "entitlement",
+  // slow down / come back later
+  quotaExceeded: "rateLimit",
+  rateLimited: "rateLimit",
+  // the request itself was wrong; retrying it unchanged can never succeed
+  validationFailed: "invalidRequest",
+  sdkUpdateRequired: "invalidRequest",
+  // the target is gone, hidden, or was never visible to this caller
+  conversationNotFound: "notFound",
+  petNotFound: "notFound",
+  resourceNotFound: "notFound",
+  // something else already holds the thing
+  conflict: "conflict",
+  idempotencyConflict: "conflict",
+  idempotencyInFlight: "conflict",
+  // the pipe, not the request: timeouts, drops, a briefly unreachable dependency
+  streamTimeout: "connection",
+  streamIncomplete: "connection",
+  upstreamLlmTimeout: "connection",
+  serviceUnavailable: "connection",
+  // the server admits fault
+  internalError: "server",
+  notImplemented: "server",
+  mediaUploadFailed: "media",
+  moderationBlocked: "policy",
+  unknown: "unknown"
+});
+function categoryFor(code) {
+  return CATEGORY_OF[code];
+}
+function fromWire(wire) {
+  const contractRow = contractErrorFor(wire);
+  if (contractRow) return contractRow.normalized;
+  const upper = (wire ?? "").trim().toUpperCase();
+  const canonical = upper.replace(/[^A-Z0-9]/g, "");
+  if (canonical === "AUTHREJECTED") return "authRejected";
+  if (upper.startsWith("AUTH")) return "authExpired";
+  switch (canonical) {
+    case "DAILYQUOTAEXCEEDED":
+    case "QUOTAEXCEEDED":
+      return "quotaExceeded";
+    case "RATELIMITED":
+    case "TOOMANYREQUESTS":
+      return "rateLimited";
+    case "IDEMPOTENCYKEYCONFLICT":
+    case "IDEMPOTENCYCONFLICT":
+      return "idempotencyConflict";
+    case "ACCESSDENIED":
+    case "FORBIDDEN":
+      return "accessDenied";
+    case "NOTFOUND":
+    case "CONVERSATIONNOTFOUND":
+      return "conversationNotFound";
+    case "PETNOTFOUND":
+      return "petNotFound";
+    case "TIMEOUT":
+    case "STREAMTIMEOUT":
+      return "streamTimeout";
+    // Analysis-domain deterministic 400s (NON-retryable). Additive per SPEC-00 §3.1 / SPEC-11b §2.6:
+    // fold to a NON-retried target so the SDK never retries a permanently-failing bad-input request.
+    // (Comment above the group so the empty fall-through cases stay lint-clean under no-fallthrough.)
+    case "MEDIAUPLOADFAILED":
+    case "UNRECOGNIZEDVIDEOFORMAT":
+    case "FILETOOSMALL":
+      return "mediaUploadFailed";
+    case "MODERATIONBLOCKED":
+      return "moderationBlocked";
+    case "UPSTREAMLLMTIMEOUT":
+      return "upstreamLlmTimeout";
+    case "INTERNALERROR":
+    case "INTERNALSERVERERROR":
+      return "internalError";
+    case "STREAMINCOMPLETE":
+    case "CHATSTREAMINCOMPLETE":
+      return "streamIncomplete";
+    // Deterministic 400s that can only come from an SDK bug -> unknown (NON-retryable). NEVER internalError
+    // (which IS auto-retried): mapping a bad-input 400 to a retryable code retries a request that never succeeds.
+    case "INVALIDANALYSISTYPE":
+    case "INVALIDUPLOADPURPOSE":
+      return "unknown";
+    default:
+      return "unknown";
+  }
+}
+function fromHttpStatus(status) {
+  if (status === 401) return "authExpired";
+  if (status === 403) return "accessDenied";
+  if (status === 404) return "conversationNotFound";
+  if (status === 409) return "idempotencyConflict";
+  if (status === 421) return "unknown";
+  if (status === 429) return "rateLimited";
+  if (status === 400 || status === 422) return "unknown";
+  if (status >= 500) return "internalError";
+  return "unknown";
+}
+var AUTO_RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  "streamTimeout",
+  "rateLimited",
+  "internalError",
+  "upstreamLlmTimeout",
+  "streamIncomplete"
+]);
+function isAutoRetryable(code) {
+  return AUTO_RETRYABLE_CODES.has(code);
+}
+var RETRYABLE_CONTRACT_CODES = /* @__PURE__ */ new Set([
+  "serviceUnavailable",
+  "conflict",
+  "idempotencyInFlight"
+]);
+function isRetryableCode(code) {
+  return isAutoRetryable(code) || RETRYABLE_CONTRACT_CODES.has(code);
+}
+
+// src/client/errors/EverfurError.ts
+var USER_FACING_COPY = Object.freeze({
+  authExpired: "Please sign in again to continue.",
+  authRejected: "Please sign in again to continue.",
+  sessionRequired: "This app needs to be updated to keep using Everfur.",
+  accessDenied: "This feature isn't available on your account right now.",
+  paymentRequired: "This is part of a paid plan.",
+  quotaExceeded: "You have used today's messages. This resets tomorrow.",
+  rateLimited: "You are sending messages quickly. Try again in a few seconds.",
+  validationFailed: "Something in that request was not right. Check the details and try again.",
+  sdkUpdateRequired: "This app needs to be updated to keep using Everfur.",
+  conflict: "That is already running. Wait for it to finish, then try again.",
+  idempotencyConflict: "That message was already delivered.",
+  idempotencyInFlight: "That is still processing. Give it a moment.",
+  conversationNotFound: "This conversation is no longer available.",
+  petNotFound: "We could not find that pet. Please pick a pet and try again.",
+  resourceNotFound: "We could not find that.",
+  streamTimeout: "The response timed out. Tap retry to try again.",
+  mediaUploadFailed: "We could not upload that photo. Please attach it again.",
+  moderationBlocked: "This request cannot be answered here.",
+  upstreamLlmTimeout: "The response timed out. Tap retry to try again.",
+  internalError: "We hit a snag on our end. Please try again.",
+  notImplemented: "That is not available yet.",
+  serviceUnavailable: "That service is briefly unavailable. Try again shortly.",
+  streamIncomplete: "The connection dropped mid-answer. Tap retry to continue.",
+  unknown: "Something went wrong. Please try again."
+});
+function userFacingError(code) {
+  return USER_FACING_COPY[code];
+}
+function defineHidden(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+}
+function makeEverfurError(code, opts) {
+  contractErrorFor(opts?.wireCode);
+  const error = {
+    code,
+    category: categoryFor(code),
+    retryable: opts?.retryable ?? isRetryableCode(code),
+    displayMessage: userFacingError(code)
+  };
+  if (opts?.httpStatus !== void 0) error.httpStatus = opts.httpStatus;
+  if (opts?.requestId) error.requestId = opts.requestId;
+  if (opts?.wireMessage) defineHidden(error, "wireMessage", opts.wireMessage);
+  if (opts?.raw !== void 0 && opts.raw !== null) defineHidden(error, "raw", opts.raw);
+  return Object.freeze(error);
+}
+
+// src/client/transport.ts
+var REQUEST_ID_HEADER = "x-request-id";
+function errorFromResponse(status, body, requestId) {
+  const wireCode = extractWireCode(body);
+  const code = wireCode ? fromWire(wireCode) : fromHttpStatus(status);
+  const wireMessage = extractWireMessage(body);
+  return makeEverfurError(code, {
+    httpStatus: status,
+    ...extractRetryable(body) ? { retryable: true } : {},
+    ...requestId ? { requestId } : {},
+    ...wireCode ? { wireCode } : {},
+    ...wireMessage ? { wireMessage } : {},
+    ...body !== null && body !== void 0 ? { raw: body } : {}
+  });
+}
+function networkError(cause) {
+  return makeEverfurError("internalError", { retryable: true, wireMessage: describeCause(cause) });
+}
+function requestIdOf(res) {
+  const value = res.headers.get(REQUEST_ID_HEADER);
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function getGlobalFetch() {
+  const candidate = globalThis.fetch;
+  if (typeof candidate !== "function") {
+    throw new EverfurConfigError(
+      "missing-peer-dependency",
+      "global fetch is unavailable; provide config.transport or an injected fetch implementation"
+    );
+  }
+  return candidate;
+}
+function extractWireCode(body) {
+  const b = body;
+  const code = b?.error?.code ?? b?.code;
+  return typeof code === "string" && code.length > 0 ? code : null;
+}
+function extractWireMessage(body) {
+  const b = body;
+  const message = b?.error?.message ?? b?.message;
+  return typeof message === "string" && message.length > 0 ? message : null;
+}
+function extractRetryable(body) {
+  const b = body;
+  return b?.error?.retryable === true || b?.retryable === true;
+}
+function describeCause(cause) {
+  if (cause instanceof Error) return cause.message;
+  return typeof cause === "string" ? cause : "network request failed";
+}
+
+// src/server/index.ts
+var USER_REF_MAX = 128;
+var TTL_MIN_SECONDS = 60;
+var TTL_MAX_SECONDS = 3600;
+var MINT_TIMEOUT_MS = 3e4;
+async function mintPartnerSession(params) {
+  const partnerUserRef = assertValidUserRef(params.userRef);
+  const ttlSeconds = clampTtl(params.ttlSeconds);
+  const fetchImpl = params.fetchImpl ?? getGlobalFetch();
+  const url = `${resolveApiBaseUrl(params.apiBaseUrl)}/widget/v1/sessions`;
+  const headers = {
+    ...buildBaseHeaders({
+      sdkVersion: SDK_VERSION,
+      platform: SDK_PLATFORM,
+      contractVersion: params.contractVersion ?? DEFAULT_CONTRACT_VERSION
+    }),
+    accept: "application/json",
+    "content-type": "application/json",
+    // The ONE legitimate two-credential request (SPEC-00 4.2 carve-out).
+    "x-everfur-partner-secret-key": params.partnerSecretKey,
+    "x-everfur-partner-key": params.publishableKey
+  };
+  const body = { user_ref: partnerUserRef };
+  if (ttlSeconds !== void 0) body.ttl_seconds = ttlSeconds;
+  const deadline = mintTimeoutSignal(MINT_TIMEOUT_MS);
+  const signal = mergeMintSignals(deadline.signal, params.signal);
+  const init = {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal
+  };
+  let res;
+  try {
+    res = await fetchImpl(url, init);
+  } catch (cause) {
+    return err(networkError(cause));
+  } finally {
+    deadline.cancel();
+  }
+  const json = await readJsonSafe(res);
+  const requestId = requestIdOf(res);
+  if (!res.ok) return err(errorFromResponse(res.status, json, requestId));
+  const mint = parseMint(json);
+  if (!mint) {
+    return err(errorFromResponse(502, { error: { code: "INTERNAL_ERROR" } }, requestId));
+  }
+  return ok(mint);
+}
+function assertValidUserRef(raw) {
+  const length = typeof raw === "string" ? [...raw].length : 0;
+  if (typeof raw !== "string" || length < 1 || length > USER_REF_MAX) {
+    throw new EverfurConfigError("invalid-argument", `user_ref must be 1..${USER_REF_MAX} characters`);
+  }
+  if (raw.trim().length === 0) {
+    throw new EverfurConfigError(
+      "invalid-argument",
+      "user_ref must not be blank: the server strips surrounding whitespace before validating, so a whitespace-only value arrives empty and is rejected as required."
+    );
+  }
+  if (raw !== raw.trim()) {
+    throw new EverfurConfigError(
+      "invalid-argument",
+      "user_ref must not have leading or trailing whitespace: the server strips it, so padded and unpadded forms of the same id resolve to ONE user. Pass the exact id you want to key on."
+    );
+  }
+  if (raw.includes("@")) {
+    throw new EverfurConfigError("invalid-argument", "user_ref must not contain '@'");
+  }
+  if (!isPrintable(raw)) {
+    throw new EverfurConfigError("invalid-argument", "user_ref must be printable (no control characters)");
+  }
+  return raw;
+}
+function clampTtl(ttl) {
+  if (ttl === void 0 || ttl === null) return void 0;
+  if (!Number.isInteger(ttl)) {
+    throw new EverfurConfigError("invalid-argument", "ttl_seconds must be an integer");
+  }
+  return Math.min(TTL_MAX_SECONDS, Math.max(TTL_MIN_SECONDS, ttl));
+}
+function isPrintable(value) {
+  return !NON_PRINTABLE.test(value);
+}
+var NON_PRINTABLE = /[\p{Cc}\p{Cf}\p{Cs}\p{Co}\p{Cn}\p{Zl}\p{Zp}]|(?!\u0020)[\p{Zs}]/u;
+function parseMint(json) {
+  if (typeof json !== "object" || json === null) return null;
+  const obj = json;
+  if (typeof obj.session_token !== "string" || obj.session_token.length === 0) return null;
+  if (typeof obj.expires_at !== "number") return null;
+  const capabilities = Array.isArray(obj.capabilities) ? obj.capabilities.filter((c) => typeof c === "string") : [];
+  return Object.freeze({
+    sessionToken: obj.session_token,
+    expiresAt: obj.expires_at,
+    capabilities: Object.freeze(capabilities)
+  });
+}
+async function readJsonSafe(res) {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+function mintTimeoutSignal(ms) {
+  const ctrl = new AbortController();
+  const handle = setTimeout(() => ctrl.abort(), ms);
+  return {
+    signal: ctrl.signal,
+    cancel: () => clearTimeout(handle)
+  };
+}
+function mergeMintSignals(deadline, caller) {
+  if (!caller) return deadline;
+  const ctrl = new AbortController();
+  if (deadline.aborted || caller.aborted) {
+    ctrl.abort();
+    return ctrl.signal;
+  }
+  const onAbort = () => ctrl.abort();
+  deadline.addEventListener("abort", onAbort, { once: true });
+  caller.addEventListener("abort", onAbort, { once: true });
+  return ctrl.signal;
+}
+
+export { assertValidUserRef, mintPartnerSession };