@enterstellar-ai/cloud 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1433 @@
+'use strict';
+
+var types = require('@enterstellar-ai/types');
+var eventsourceParser = require('eventsource-parser');
+
+// src/errors.ts
+var CloudError = class _CloudError extends types.EnterstellarError {
+  /**
+   * The Cloud-specific error code.
+   *
+   * For SDK-originated errors, this mirrors `EnterstellarError.code` (e.g., `'ENS-5001'`).
+   * For server-originated errors, this is the `ENS-C{NNNN}` code from the
+   * response body (e.g., `'ENS-C4290'`).
+   */
+  cloudCode;
+  /**
+   * URL for the billing upgrade page.
+   * Present only on `ENS-C4290` (IPU quota exceeded) errors.
+   *
+   * @see Design Choice SD3 — app decides how to surface the upgrade prompt.
+   */
+  upgradeUrl;
+  /**
+   * Milliseconds until the quota resets or rate limit expires.
+   * Present only on `ENS-C4290` errors.
+   *
+   * Use this to schedule a retry or display a countdown to the user.
+   */
+  retryAfterMs;
+  /**
+   * The `X-Request-Id` header value from the server response.
+   * A bare ULID (AG16) for support ticket correlation.
+   * `undefined` if the error occurred before a server response was received
+   * (e.g., network failure, config validation).
+   */
+  requestId;
+  /**
+   * @internal Use factory functions instead of constructing directly.
+   *
+   * @param code - The `EnterstellarErrorCode` for the base `EnterstellarError` class.
+   * @param cloudCode - The Cloud-specific error code (`ENS-5xxx` or `ENS-C{NNNN}`).
+   * @param message - Human-readable error description.
+   * @param recoverable - Whether the caller can meaningfully retry.
+   * @param options - Optional Cloud-specific metadata.
+   */
+  constructor(code, cloudCode, message, recoverable, options) {
+    super(code, "cloud", message, recoverable, options?.cause);
+    this.name = "CloudError";
+    this.cloudCode = cloudCode;
+    this.upgradeUrl = options?.upgradeUrl;
+    this.retryAfterMs = options?.retryAfterMs;
+    this.requestId = options?.requestId;
+    if ("captureStackTrace" in Error) {
+      Error.captureStackTrace(
+        this,
+        _CloudError
+      );
+    }
+  }
+  /**
+   * Serializes the error to a plain object for logging, telemetry, or DevTools.
+   *
+   * Extends `EnterstellarError.toJSON()` with Cloud-specific fields.
+   *
+   * @returns A plain object representation including all Cloud metadata.
+   */
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      name: this.name,
+      cloudCode: this.cloudCode,
+      module: "cloud",
+      upgradeUrl: this.upgradeUrl,
+      retryAfterMs: this.retryAfterMs,
+      requestId: this.requestId
+    };
+  }
+};
+function createConfigError(field) {
+  return new CloudError(
+    "ENS-5001",
+    "ENS-5001",
+    `@enterstellar-ai/cloud: Invalid config \u2014 "${field}" is required and must be a non-empty string.`,
+    false
+  );
+}
+function createDisposedError() {
+  return new CloudError(
+    "ENS-5002",
+    "ENS-5002",
+    "@enterstellar-ai/cloud: Client has been disposed. Create a new client with createEnterstellarCloudClient().",
+    false
+  );
+}
+function createAnonymousModeError(method) {
+  return new CloudError(
+    "ENS-5004",
+    "ENS-5004",
+    `@enterstellar-ai/cloud: ${method}() is not available in anonymous mode. Anonymous clients (pk_anon_*) can only call submitSignal(). Use a project API key (ak_*) for full access.`,
+    false
+  );
+}
+function createRetriesExhaustedError(attempts, lastStatusCode, requestId) {
+  const statusSuffix = lastStatusCode !== void 0 ? ` Last status: ${String(lastStatusCode)}.` : " Last error: network failure.";
+  return new CloudError(
+    "ENS-5005",
+    "ENS-5005",
+    `@enterstellar-ai/cloud: All ${String(attempts)} retry attempts failed.${statusSuffix}`,
+    true,
+    { requestId }
+  );
+}
+function createQuotaExceededError(body, requestId) {
+  return new CloudError(
+    "ENS-5003",
+    // Base EnterstellarErrorCode — server errors map to ENS-5003
+    body.code,
+    // Cloud code — 'ENS-C4290' (or 'ENS-C4291' if server sends it)
+    `@enterstellar-ai/cloud: ${body.message}`,
+    true,
+    // Recoverable — caller can upgrade tier or wait for reset
+    {
+      upgradeUrl: body.upgradeUrl,
+      retryAfterMs: body.retryAfterMs,
+      requestId
+    }
+  );
+}
+
+// src/version.ts
+var CLOUD_SDK_VERSION = "0.1.0";
+
+// src/transport/idempotency.ts
+var CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function encodeTimestamp(timeMs) {
+  let remaining = timeMs;
+  const chars = new Array(10);
+  for (let i = 9; i >= 0; i--) {
+    chars[i] = CROCKFORD_BASE32[remaining & 31];
+    remaining = Math.floor(remaining / 32);
+  }
+  return chars.join("");
+}
+function encodeRandomness() {
+  const bytes = new Uint8Array(10);
+  crypto.getRandomValues(bytes);
+  const chars = new Array(16);
+  let bitBuffer = 0;
+  let bitsInBuffer = 0;
+  let charIndex = 0;
+  for (let byteIndex = 0; byteIndex < 10; byteIndex++) {
+    bitBuffer = bitBuffer << 8 | bytes[byteIndex];
+    bitsInBuffer += 8;
+    while (bitsInBuffer >= 5) {
+      bitsInBuffer -= 5;
+      const fiveBitValue = bitBuffer >>> bitsInBuffer & 31;
+      chars[charIndex] = CROCKFORD_BASE32[fiveBitValue];
+      charIndex++;
+    }
+  }
+  return chars.join("");
+}
+function generateIdempotencyKey() {
+  return encodeTimestamp(Date.now()) + encodeRandomness();
+}
+
+// src/transport/cloud-http.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var MAX_ATTEMPTS = 3;
+var RETRY_BACKOFF_MS = [1e3, 2e3, 4e3];
+var OPERATION_TIMEOUTS = Object.freeze({
+  /** Forge P99 = 10s (§8.9), 3× safety margin. */
+  forge: 3e4,
+  /** CR5: max 60s runtime + network/queue overhead. */
+  certify: 9e4,
+  /** OLAP queries can be slow depending on data volume. */
+  analytics: 3e4,
+  /** Business analytics — same profile as trace analytics. */
+  businessAnalytics: 3e4,
+  /** Default for all other operations. */
+  default: 1e4
+});
+function parseNumericHeader(headers, name) {
+  const raw = headers.get(name);
+  if (raw === null || raw.trim().length === 0) {
+    return void 0;
+  }
+  const value = Number(raw);
+  if (Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+  return void 0;
+}
+async function safeParseJson(response) {
+  try {
+    const data = await response.json();
+    return data;
+  } catch {
+    return null;
+  }
+}
+async function parseErrorBody(response) {
+  try {
+    const raw = await response.json();
+    if (typeof raw === "object" && raw !== null && "error" in raw) {
+      const envelope = raw;
+      const errorObj = envelope.error;
+      if (typeof errorObj === "object" && errorObj !== null && "code" in errorObj && "message" in errorObj && typeof errorObj.code === "string" && typeof errorObj.message === "string") {
+        const typed = errorObj;
+        return {
+          code: typed.code,
+          message: typed.message,
+          retryAfterMs: typeof typed.retryAfterMs === "number" ? typed.retryAfterMs : void 0,
+          upgradeUrl: typeof typed.upgradeUrl === "string" ? typed.upgradeUrl : void 0
+        };
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function resolveTimeout(globalTimeout, operationTimeout) {
+  return globalTimeout ?? operationTimeout ?? DEFAULT_TIMEOUT_MS;
+}
+function createCloudHttpTransport(config) {
+  const { endpoint, apiKey, timeoutMs: globalTimeoutMs } = config;
+  return {
+    async request(reqConfig) {
+      const effectiveTimeout = resolveTimeout(
+        globalTimeoutMs,
+        reqConfig.operationTimeout
+      );
+      const url = `${endpoint}${reqConfig.path}`;
+      const idempotencyKey = reqConfig.ipuCost > 0 ? generateIdempotencyKey() : void 0;
+      const headers = {
+        "Authorization": `Bearer ${apiKey}`,
+        "User-Agent": `enterstellar-cloud-sdk/${CLOUD_SDK_VERSION}`,
+        "Accept": "application/json"
+      };
+      if (reqConfig.body !== void 0) {
+        headers["Content-Type"] = "application/json";
+      }
+      if (idempotencyKey !== void 0) {
+        headers["X-Idempotency-Key"] = idempotencyKey;
+      }
+      let lastStatusCode;
+      let lastRequestId;
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+          controller.abort();
+        }, effectiveTimeout);
+        try {
+          const response = await fetch(url, {
+            method: reqConfig.method,
+            headers,
+            ...reqConfig.body !== void 0 ? { body: JSON.stringify(reqConfig.body) } : {},
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
+          const ipuUsed = parseNumericHeader(response.headers, "X-IPU-Used");
+          const ipuRemaining = parseNumericHeader(response.headers, "X-IPU-Remaining");
+          const ipuCost = parseNumericHeader(response.headers, "X-IPU-Cost");
+          const requestId = response.headers.get("X-Request-Id") ?? void 0;
+          lastStatusCode = response.status;
+          lastRequestId = requestId;
+          if (response.ok) {
+            const data = await safeParseJson(response);
+            return {
+              ok: true,
+              statusCode: response.status,
+              data,
+              ipuUsed,
+              ipuRemaining,
+              ipuCost,
+              requestId,
+              error: null
+            };
+          }
+          if (response.status === 429) {
+            const errorBody2 = await parseErrorBody(response);
+            const body = errorBody2 ?? {
+              code: "ENS-C4290",
+              message: "IPU quota exceeded"
+            };
+            throw createQuotaExceededError(body, requestId);
+          }
+          if (response.status >= 500) {
+            await response.text().catch(() => void 0);
+            if (attempt < MAX_ATTEMPTS - 1) {
+              const backoffMs = RETRY_BACKOFF_MS[attempt];
+              await sleep(backoffMs);
+            }
+            continue;
+          }
+          const errorBody = await parseErrorBody(response);
+          throw new CloudError(
+            "ENS-5003",
+            errorBody?.code ?? `HTTP-${String(response.status)}`,
+            `@enterstellar-ai/cloud: Request failed \u2014 ${errorBody?.message ?? `HTTP ${String(response.status)}`}.`,
+            false,
+            { requestId }
+          );
+        } catch (error) {
+          clearTimeout(timeoutId);
+          if (error instanceof CloudError) {
+            throw error;
+          }
+          lastStatusCode = void 0;
+          lastRequestId = void 0;
+          if (attempt < MAX_ATTEMPTS - 1) {
+            const backoffMs = RETRY_BACKOFF_MS[attempt];
+            await sleep(backoffMs);
+          }
+        }
+      }
+      throw createRetriesExhaustedError(MAX_ATTEMPTS, lastStatusCode, lastRequestId);
+    }
+  };
+}
+function parseNumericHeader2(headers, name) {
+  const raw = headers.get(name);
+  if (raw === null || raw.trim().length === 0) {
+    return void 0;
+  }
+  const value = Number(raw);
+  if (Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+  return void 0;
+}
+function parseIPUHeaders(headers, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  const used = parseNumericHeader2(headers, "X-IPU-Used");
+  const remaining = parseNumericHeader2(headers, "X-IPU-Remaining");
+  const cost = parseNumericHeader2(headers, "X-IPU-Cost");
+  if (used !== void 0 && remaining !== void 0 && cost !== void 0) {
+    return { used, remaining, cost };
+  }
+  return null;
+}
+async function parseErrorBody2(response) {
+  try {
+    const raw = await response.json();
+    if (typeof raw === "object" && raw !== null && "error" in raw) {
+      const envelope = raw;
+      const errorObj = envelope.error;
+      if (typeof errorObj === "object" && errorObj !== null && "code" in errorObj && "message" in errorObj && typeof errorObj.code === "string" && typeof errorObj.message === "string") {
+        const typed = errorObj;
+        return {
+          code: typed.code,
+          message: typed.message,
+          retryAfterMs: typeof typed.retryAfterMs === "number" ? typed.retryAfterMs : void 0,
+          upgradeUrl: typeof typed.upgradeUrl === "string" ? typed.upgradeUrl : void 0
+        };
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function safeParseJsonString(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+function mapEventToFragment(event, ipu) {
+  const eventType = event.event ?? "message";
+  switch (eventType) {
+    case "meta": {
+      const data = safeParseJsonString(event.data);
+      if (data === null) {
+        return null;
+      }
+      const fragment = {
+        type: "meta",
+        data: { provider: data.provider, model: data.model },
+        ipu
+      };
+      return fragment;
+    }
+    case "node": {
+      const data = safeParseJsonString(event.data);
+      if (data === null) {
+        return null;
+      }
+      const fragment = {
+        type: "node",
+        data
+      };
+      return fragment;
+    }
+    case "property": {
+      const data = safeParseJsonString(event.data);
+      if (data === null) {
+        return null;
+      }
+      const fragment = {
+        type: "property",
+        data: { path: data.path, value: data.value }
+      };
+      return fragment;
+    }
+    case "complete": {
+      const data = safeParseJsonString(event.data);
+      if (data === null) {
+        return null;
+      }
+      const fragment = {
+        type: "complete",
+        data,
+        ipu
+      };
+      return fragment;
+    }
+    case "error": {
+      const data = safeParseJsonString(event.data);
+      if (data === null) {
+        return null;
+      }
+      const fragment = {
+        type: "error",
+        data: { code: data.code, message: data.message }
+      };
+      return fragment;
+    }
+    default:
+      return null;
+  }
+}
+function createCloudSSETransport(config) {
+  const { endpoint, apiKey, timeoutMs: globalTimeoutMs } = config;
+  return {
+    async *stream(sseConfig) {
+      const effectiveTimeout = globalTimeoutMs ?? OPERATION_TIMEOUTS.forge;
+      const url = `${endpoint}/v1/forge`;
+      const idempotencyKey = generateIdempotencyKey();
+      const headers = {
+        "Authorization": `Bearer ${apiKey}`,
+        "User-Agent": `enterstellar-cloud-sdk/${CLOUD_SDK_VERSION}`,
+        "Accept": "text/event-stream",
+        "Content-Type": "application/json",
+        "X-Idempotency-Key": idempotencyKey
+      };
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, effectiveTimeout);
+      let response;
+      try {
+        response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(sseConfig.body),
+          signal: controller.signal
+        });
+      } catch {
+        clearTimeout(timeoutId);
+        throw createRetriesExhaustedError(
+          1,
+          void 0,
+          void 0
+        );
+      }
+      if (!response.ok) {
+        clearTimeout(timeoutId);
+        if (response.status === 429) {
+          const errorBody2 = await parseErrorBody2(response);
+          const requestId2 = response.headers.get("X-Request-Id") ?? void 0;
+          const body2 = errorBody2 ?? {
+            code: "ENS-C4290",
+            message: "IPU quota exceeded"
+          };
+          throw createQuotaExceededError(body2, requestId2);
+        }
+        const errorBody = await parseErrorBody2(response);
+        const requestId = response.headers.get("X-Request-Id") ?? void 0;
+        throw new CloudError(
+          "ENS-5003",
+          errorBody?.code ?? `HTTP-${String(response.status)}`,
+          `@enterstellar-ai/cloud: Forge stream failed \u2014 ${errorBody?.message ?? `HTTP ${String(response.status)}`}.`,
+          false,
+          { requestId }
+        );
+      }
+      const ipu = parseIPUHeaders(response.headers, sseConfig.isAnonymous);
+      const body = response.body;
+      if (body === null) {
+        clearTimeout(timeoutId);
+        throw createRetriesExhaustedError(1, response.status);
+      }
+      const fragmentBuffer = [];
+      const streamState = { done: false };
+      const parser = eventsourceParser.createParser({
+        onEvent(event) {
+          const fragment = mapEventToFragment(event, ipu);
+          if (fragment !== null) {
+            fragmentBuffer.push(fragment);
+            if (fragment.type === "complete" || fragment.type === "error") {
+              streamState.done = true;
+            }
+          }
+        }
+      });
+      function drainBuffer() {
+        return fragmentBuffer.splice(0);
+      }
+      const reader = body.getReader();
+      const decoder = new TextDecoder();
+      try {
+        let readerDone = false;
+        while (!readerDone) {
+          const readResult = await reader.read();
+          readerDone = readResult.done;
+          if (readResult.value !== void 0) {
+            const text = decoder.decode(readResult.value, { stream: true });
+            parser.feed(text);
+          }
+          for (const fragment of drainBuffer()) {
+            yield fragment;
+          }
+          if (streamState.done) {
+            break;
+          }
+        }
+        for (const fragment of drainBuffer()) {
+          yield fragment;
+        }
+      } catch (error) {
+        if (error instanceof CloudError) {
+          throw error;
+        }
+        throw createRetriesExhaustedError(1, void 0, void 0);
+      } finally {
+        clearTimeout(timeoutId);
+        try {
+          reader.releaseLock();
+        } catch {
+        }
+      }
+    }
+  };
+}
+
+// src/metering/ipu-tracker.ts
+var DRIFT_THRESHOLD = 0.1;
+function createIPUTracker() {
+  let localUsed = 0;
+  let serverLimit = null;
+  let lastCorrected = false;
+  let lastIPUCost;
+  return {
+    record(cost) {
+      localUsed += cost;
+    },
+    reconcile(serverUsed, serverRemaining, ipuCost) {
+      lastIPUCost = ipuCost;
+      serverLimit = serverUsed + serverRemaining;
+      if (serverUsed === 0) {
+        if (localUsed > 0) {
+          localUsed = serverUsed;
+          lastCorrected = true;
+        } else {
+          lastCorrected = false;
+        }
+        return;
+      }
+      const drift = Math.abs(localUsed - serverUsed) / serverUsed;
+      if (drift > DRIFT_THRESHOLD) {
+        localUsed = serverUsed;
+        lastCorrected = true;
+      } else {
+        lastCorrected = false;
+      }
+    },
+    getEstimate() {
+      const remaining = serverLimit !== null ? Math.max(0, serverLimit - localUsed) : null;
+      return {
+        used: localUsed,
+        remaining,
+        limit: serverLimit,
+        lastReconciliationCorrected: lastCorrected
+      };
+    },
+    isOverQuota() {
+      if (serverLimit === null) {
+        return false;
+      }
+      return localUsed >= serverLimit;
+    },
+    getLastIPUCost() {
+      return lastIPUCost;
+    },
+    reset() {
+      localUsed = 0;
+      serverLimit = null;
+      lastCorrected = false;
+      lastIPUCost = void 0;
+    }
+  };
+}
+
+// src/metering/ipu-costs.ts
+var IPU_COSTS = Object.freeze({
+  /**
+   * CloudForge generation — LLM-based component contract generation.
+   * Premium feature, highest per-operation cost.
+   *
+   * @see Design Choice CL2 — "CloudForge generation = 10 IPU"
+   * @see Bible §9.1 — `POST /v1/forge`
+   */
+  FORGE: 10,
+  /**
+   * Cloud semantic search — vector similarity lookup via Vectorize.
+   * Lightweight operation, lowest per-operation cost.
+   *
+   * @see Design Choice CL2 — "cloud semantic search = 1 IPU"
+   * @see Bible §9.1 — `POST /v1/semantic-search`
+   */
+  SEMANTIC_SEARCH: 1,
+  /**
+   * Intent routing — frequency-based (Phase 2) or ML-based (Phase 3)
+   * component prediction for a single intent hash.
+   *
+   * @see Design Choice IR2 — router prediction response shape.
+   * @see Bible §9.1 — `POST /v1/route`
+   */
+  ROUTE: 1,
+  /**
+   * Batch intent routing — per-intent cost within a batch request.
+   * A batch of N intents costs `N × 1 IPU`.
+   *
+   * @see Design Choice IR5 — batch routing for pre-rendering.
+   * @see Bible §9.1 — `POST /v1/route/batch`
+   */
+  ROUTE_BATCH_PER_INTENT: 1,
+  /**
+   * ForgeSignal submission — telemetry data ingestion.
+   * Free — signal data is Enterstellar's #1 strategic asset (§9.1:
+   * "never charge for data collection").
+   *
+   * @see Design Choice SD4 — transparent `pk_anon` auth for signals.
+   * @see Bible §9.1 — `POST /v1/signals`
+   */
+  SIGNAL_SUBMIT: 0,
+  /**
+   * AgentTrace submission — trace data ingestion for aggregation.
+   * Free — trace data is the feedstock for analytics features.
+   *
+   * **CORRECTED:** Was 5 IPU in the OSS Bible (§4.13). Changed to 0
+   * in the Cloud Bible §9.1: "never charge for data collection."
+   *
+   * @see Bible §9.1 — `POST /v1/traces` (0 IPU)
+   */
+  TRACE_SUBMIT: 0,
+  /**
+   * Trace analytics query — server-side OLAP aggregation via ClickHouse.
+   * Moderate cost reflecting the compute intensity.
+   *
+   * @see Design Choice TA5 — fixed analytics query types.
+   * @see Bible §9.1 — `POST /v1/traces/analytics`
+   */
+  TRACE_ANALYTICS: 5,
+  /**
+   * Business analytics query — product intelligence via ClickHouse.
+   * Same cost profile as trace analytics.
+   *
+   * @see Design Choice TA10 — Enterstellar Analytics (business intelligence).
+   * @see Bible §9.1 — `POST /v1/analytics/*`
+   */
+  BUSINESS_ANALYTICS: 5,
+  /**
+   * Contract certification — "Enterstellar Certified" audit initiation.
+   * Highest cost — involves Fly.io microVM test execution (CR5).
+   *
+   * @see Design Choice GI5 — certification lifecycle.
+   * @see Design Choice CR6 — certification costs 20 IPU.
+   * @see Bible §9.1 — `POST /v1/contracts/:id/certify`
+   */
+  CERTIFY: 20,
+  /**
+   * Usage query — returns current IPU consumption and tier.
+   * Free — necessary for clients to monitor their own usage.
+   *
+   * @see Bible §9.1 — `GET /v1/usage`
+   */
+  USAGE_QUERY: 0,
+  /**
+   * IPU ledger query — per-operation charge audit trail.
+   * Free — billing transparency.
+   *
+   * @see Design Choice AM13 — IPU ledger exposure.
+   * @see Bible §9.1 — `GET /v1/usage/ledger`
+   */
+  LEDGER_QUERY: 0,
+  /**
+   * Trace listing query — paginated trace retrieval.
+   * Free — reading your own data is never charged.
+   *
+   * @see Bible §9.1 — `GET /v1/traces`
+   */
+  GET_TRACES: 0,
+  /**
+   * GDPR data deletion — initiate project data purge.
+   * Free — compliance operations are never charged.
+   *
+   * @see Design Choice AG9 — two-phase delete.
+   * @see Design Choice D110 — GDPR soft-delete.
+   * @see Bible §9.1 — `DELETE /v1/project/:id/data`
+   */
+  DELETE_PROJECT_DATA: 0
+});
+
+// src/inference/cloud-forge-proxy.ts
+function buildIPU(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createCloudForgeProxy(transport, sseTransport, tracker, isAnonymous, sessionType) {
+  return {
+    async forge(options) {
+      if (tracker.isOverQuota()) {
+        throw createQuotaExceededError({
+          code: "ENS-C4290",
+          message: "IPU quota exceeded (pre-flight check)"
+        });
+      }
+      const response = await transport.request({
+        method: "POST",
+        path: "/v1/forge",
+        body: {
+          intent: options.intent,
+          constraints: options.constraints,
+          sessionType
+        },
+        ipuCost: IPU_COSTS.FORGE,
+        operationTimeout: OPERATION_TIMEOUTS.forge
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      tracker.record(IPU_COSTS.FORGE);
+      const ipu = buildIPU(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data;
+      if (data === null) {
+        throw createQuotaExceededError({
+          code: "ENS-C5000",
+          message: "Forge response contained no data"
+        });
+      }
+      return { data, ipu };
+    },
+    async *stream(options) {
+      if (tracker.isOverQuota()) {
+        throw createQuotaExceededError({
+          code: "ENS-C4290",
+          message: "IPU quota exceeded (pre-flight check)"
+        });
+      }
+      const sseConfig = {
+        body: {
+          intent: options.intent,
+          constraints: options.constraints,
+          sessionType
+        },
+        isAnonymous
+      };
+      tracker.record(IPU_COSTS.FORGE);
+      yield* sseTransport.stream(sseConfig);
+    }
+  };
+}
+
+// src/inference/cloud-index-proxy.ts
+var DEFAULT_TOP_K = 5;
+function buildIPU2(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createCloudIndexProxy(transport, tracker, isAnonymous) {
+  return {
+    async search(query, topK = DEFAULT_TOP_K) {
+      if (tracker.isOverQuota()) {
+        throw createQuotaExceededError({
+          code: "ENS-C4290",
+          message: "IPU quota exceeded (pre-flight check)"
+        });
+      }
+      const response = await transport.request({
+        method: "POST",
+        path: "/v1/semantic-search",
+        body: { query, topK },
+        ipuCost: IPU_COSTS.SEMANTIC_SEARCH
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      tracker.record(IPU_COSTS.SEMANTIC_SEARCH);
+      const ipu = buildIPU2(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data;
+      const results = data?.results ?? [];
+      return { data: results, ipu };
+    }
+  };
+}
+
+// src/routing/cloud-router-proxy.ts
+function buildIPU3(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createCloudRouterProxy(transport, tracker, isAnonymous) {
+  return {
+    async route(intentHash) {
+      if (tracker.isOverQuota()) {
+        throw createQuotaExceededError({
+          code: "ENS-C4290",
+          message: "IPU quota exceeded (pre-flight check)"
+        });
+      }
+      const response = await transport.request({
+        method: "POST",
+        path: "/v1/route",
+        body: { intentHash },
+        ipuCost: IPU_COSTS.ROUTE
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      tracker.record(IPU_COSTS.ROUTE);
+      const ipu = buildIPU3(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data ?? {
+        predictions: [],
+        metadata: { modelVersion: "unknown", signalCount: 0 }
+      };
+      return { data, ipu };
+    },
+    async routeBatch(intentHashes) {
+      if (tracker.isOverQuota()) {
+        throw createQuotaExceededError({
+          code: "ENS-C4290",
+          message: "IPU quota exceeded (pre-flight check)"
+        });
+      }
+      const batchCost = intentHashes.length * IPU_COSTS.ROUTE_BATCH_PER_INTENT;
+      const response = await transport.request({
+        method: "POST",
+        path: "/v1/route/batch",
+        body: { intentHashes },
+        ipuCost: batchCost
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      tracker.record(batchCost);
+      const ipu = buildIPU3(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data ?? [];
+      return { data, ipu };
+    }
+  };
+}
+
+// src/analytics/cloud-analytics-proxy.ts
+function buildIPU4(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createCloudAnalyticsProxy(transport, tracker, isAnonymous) {
+  async function executeAnalyticsRequest(path, query, costConstant) {
+    if (tracker.isOverQuota()) {
+      throw createQuotaExceededError({
+        code: "ENS-C4290",
+        message: "IPU quota exceeded (pre-flight check)"
+      });
+    }
+    const response = await transport.request({
+      method: "POST",
+      path,
+      body: query,
+      ipuCost: costConstant,
+      operationTimeout: OPERATION_TIMEOUTS.analytics
+    });
+    if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+      tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+    }
+    tracker.record(costConstant);
+    const ipu = buildIPU4(
+      response.ipuUsed,
+      response.ipuRemaining,
+      response.ipuCost,
+      isAnonymous
+    );
+    const data = response.data ?? {
+      rows: [],
+      queryType: query.queryType
+    };
+    return { data, ipu };
+  }
+  return {
+    async analytics(query) {
+      return executeAnalyticsRequest(
+        "/v1/traces/analytics",
+        query,
+        IPU_COSTS.TRACE_ANALYTICS
+      );
+    },
+    async businessAnalytics(query) {
+      return executeAnalyticsRequest(
+        "/v1/analytics/query",
+        query,
+        IPU_COSTS.BUSINESS_ANALYTICS
+      );
+    }
+  };
+}
+
+// src/traces/trace-submitter.ts
+var CONSENT_DENIED_RESULT = Object.freeze({
+  data: Object.freeze({ accepted: false }),
+  ipu: null
+});
+function buildIPU5(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createTraceSubmitter(transport, tracker, isAnonymous, traceConsent, sessionType) {
+  return {
+    async submitTrace(trace) {
+      if (!traceConsent) {
+        return CONSENT_DENIED_RESULT;
+      }
+      if (!trace.consent.anonymizedAggregation) {
+        return CONSENT_DENIED_RESULT;
+      }
+      const response = await transport.request({
+        method: "POST",
+        path: "/v1/traces",
+        body: { trace, sessionType },
+        ipuCost: IPU_COSTS.TRACE_SUBMIT
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      const ipu = buildIPU5(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const accepted = response.data?.accepted ?? true;
+      return { data: { accepted }, ipu };
+    }
+  };
+}
+
+// src/signals/signal-submitter.ts
+function buildIPU6(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createSignalSubmitter(transport, tracker, isAnonymous, sessionType) {
+  return {
+    async submitSignal(signal) {
+      const response = await transport.request({
+        method: "POST",
+        path: "/v1/signals",
+        body: { ...signal, sessionType },
+        ipuCost: IPU_COSTS.SIGNAL_SUBMIT
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      const ipu = buildIPU6(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const accepted = response.data?.accepted ?? true;
+      return { data: { accepted }, ipu };
+    }
+  };
+}
+
+// src/operations/traces-query-proxy.ts
+function buildQueryString(params) {
+  const entries = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0 && value !== null) {
+      entries.push(
+        `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`
+      );
+    }
+  }
+  return entries.length > 0 ? `?${entries.join("&")}` : "";
+}
+function buildIPU7(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createTracesQueryProxy(transport, tracker, isAnonymous) {
+  return {
+    async getTraces(options) {
+      const queryString = buildQueryString({
+        cursor: options?.cursor,
+        limit: options?.limit,
+        correlation_id: options?.correlationId,
+        thread_id: options?.threadId
+      });
+      const response = await transport.request({
+        method: "GET",
+        path: `/v1/traces${queryString}`,
+        ipuCost: IPU_COSTS.GET_TRACES
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      const ipu = buildIPU7(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data ?? {
+        items: [],
+        cursor: null,
+        hasMore: false
+      };
+      return { data, ipu };
+    }
+  };
+}
+
+// src/operations/certify-proxy.ts
+function buildIPU8(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createCertifyProxy(transport, tracker, isAnonymous) {
+  return {
+    async certify(contractId) {
+      if (tracker.isOverQuota()) {
+        throw createQuotaExceededError({
+          code: "ENS-C4290",
+          message: "IPU quota exceeded (pre-flight check)"
+        });
+      }
+      const path = `/v1/contracts/${encodeURIComponent(contractId)}/certify`;
+      const response = await transport.request({
+        method: "POST",
+        path,
+        ipuCost: IPU_COSTS.CERTIFY,
+        operationTimeout: OPERATION_TIMEOUTS.certify
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      tracker.record(IPU_COSTS.CERTIFY);
+      const ipu = buildIPU8(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data ?? {
+        status: "pending",
+        pollUrl: `/v1/contracts/${encodeURIComponent(contractId)}`
+      };
+      return { data, ipu };
+    }
+  };
+}
+
+// src/operations/ledger-query-proxy.ts
+function buildQueryString2(params) {
+  const entries = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0 && value !== null) {
+      entries.push(
+        `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`
+      );
+    }
+  }
+  return entries.length > 0 ? `?${entries.join("&")}` : "";
+}
+function buildIPU9(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createLedgerQueryProxy(transport, tracker, isAnonymous) {
+  return {
+    async getLedger(options) {
+      const queryString = buildQueryString2({
+        cursor: options?.cursor,
+        limit: options?.limit
+      });
+      const response = await transport.request({
+        method: "GET",
+        path: `/v1/usage/ledger${queryString}`,
+        ipuCost: IPU_COSTS.LEDGER_QUERY
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      const ipu = buildIPU9(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data ?? {
+        items: [],
+        cursor: null,
+        hasMore: false
+      };
+      return { data, ipu };
+    }
+  };
+}
+
+// src/operations/data-deletion-proxy.ts
+function buildIPU10(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createDataDeletionProxy(transport, tracker, isAnonymous) {
+  return {
+    async deleteProjectData(projectId) {
+      const path = `/v1/project/${encodeURIComponent(projectId)}/data`;
+      const response = await transport.request({
+        method: "DELETE",
+        path,
+        ipuCost: IPU_COSTS.DELETE_PROJECT_DATA
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      const ipu = buildIPU10(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const accepted = response.data?.accepted ?? true;
+      return { data: { accepted }, ipu };
+    }
+  };
+}
+
+// src/create-cloud-client.ts
+var DEFAULT_BASE_URL = "https://api.enterstellar.dev";
+var ANONYMOUS_KEY_PREFIX = "pk_anon_";
+var DEFAULT_SESSION_TYPE = "app";
+function buildIPU11(ipuUsed, ipuRemaining, ipuCost, isAnonymous) {
+  if (isAnonymous) {
+    return null;
+  }
+  if (ipuUsed !== void 0 && ipuRemaining !== void 0 && ipuCost !== void 0) {
+    return { used: ipuUsed, remaining: ipuRemaining, cost: ipuCost };
+  }
+  return null;
+}
+function createEnterstellarCloudClient(config) {
+  if (!config.apiKey || config.apiKey.trim().length === 0) {
+    throw createConfigError("apiKey");
+  }
+  const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+  const sessionType = config.sessionType ?? DEFAULT_SESSION_TYPE;
+  const traceConsent = config.traceConsent ?? false;
+  const isAnonymous = config.apiKey.startsWith(ANONYMOUS_KEY_PREFIX);
+  const transport = createCloudHttpTransport({
+    endpoint: baseUrl,
+    apiKey: config.apiKey,
+    timeoutMs: config.timeoutMs
+  });
+  const sseTransport = createCloudSSETransport({
+    endpoint: baseUrl,
+    apiKey: config.apiKey,
+    timeoutMs: config.timeoutMs
+  });
+  const tracker = createIPUTracker();
+  const forgeProxy = createCloudForgeProxy(
+    transport,
+    sseTransport,
+    tracker,
+    isAnonymous,
+    sessionType
+  );
+  const indexProxy = createCloudIndexProxy(transport, tracker, isAnonymous);
+  const routerProxy = createCloudRouterProxy(transport, tracker, isAnonymous);
+  const analyticsProxy = createCloudAnalyticsProxy(transport, tracker, isAnonymous);
+  const traceSubmitter = createTraceSubmitter(
+    transport,
+    tracker,
+    isAnonymous,
+    traceConsent,
+    sessionType
+  );
+  const signalSubmitter = createSignalSubmitter(
+    transport,
+    tracker,
+    isAnonymous,
+    sessionType
+  );
+  const tracesQueryProxy = createTracesQueryProxy(transport, tracker, isAnonymous);
+  const certifyProxy = createCertifyProxy(transport, tracker, isAnonymous);
+  const ledgerQueryProxy = createLedgerQueryProxy(transport, tracker, isAnonymous);
+  const dataDeletionProxy = createDataDeletionProxy(transport, tracker, isAnonymous);
+  let disposed = false;
+  function assertNotDisposed() {
+    if (disposed) {
+      throw createDisposedError();
+    }
+  }
+  function assertNotAnonymous(method) {
+    if (isAnonymous) {
+      throw createAnonymousModeError(method);
+    }
+  }
+  const forge = Object.assign(
+    async (options) => {
+      assertNotDisposed();
+      assertNotAnonymous("forge");
+      return forgeProxy.forge(options);
+    },
+    {
+      stream(options) {
+        assertNotDisposed();
+        assertNotAnonymous("forge.stream");
+        return forgeProxy.stream(options);
+      }
+    }
+  );
+  return {
+    // -------------------------------------------------------------------
+    // Generation (SD6)
+    // -------------------------------------------------------------------
+    forge,
+    // -------------------------------------------------------------------
+    // Search
+    // -------------------------------------------------------------------
+    async search(query, topK) {
+      assertNotDisposed();
+      assertNotAnonymous("search");
+      return indexProxy.search(query, topK);
+    },
+    // -------------------------------------------------------------------
+    // Routing (IR2, IR5)
+    // -------------------------------------------------------------------
+    async route(intentHash) {
+      assertNotDisposed();
+      assertNotAnonymous("route");
+      return routerProxy.route(intentHash);
+    },
+    async routeBatch(intentHashes) {
+      assertNotDisposed();
+      assertNotAnonymous("routeBatch");
+      return routerProxy.routeBatch(intentHashes);
+    },
+    // -------------------------------------------------------------------
+    // Signals (SD1, SD4) — works in anonymous mode
+    // -------------------------------------------------------------------
+    async submitSignal(signal) {
+      assertNotDisposed();
+      return signalSubmitter.submitSignal(signal);
+    },
+    // -------------------------------------------------------------------
+    // Traces (TA2)
+    // -------------------------------------------------------------------
+    async submitTrace(trace) {
+      assertNotDisposed();
+      assertNotAnonymous("submitTrace");
+      return traceSubmitter.submitTrace(trace);
+    },
+    async getTraces(options) {
+      assertNotDisposed();
+      assertNotAnonymous("getTraces");
+      return tracesQueryProxy.getTraces(options);
+    },
+    // -------------------------------------------------------------------
+    // Analytics (TA3, TA5, TA10)
+    // -------------------------------------------------------------------
+    async analytics(query) {
+      assertNotDisposed();
+      assertNotAnonymous("analytics");
+      return analyticsProxy.analytics(query);
+    },
+    async businessAnalytics(query) {
+      assertNotDisposed();
+      assertNotAnonymous("businessAnalytics");
+      return analyticsProxy.businessAnalytics(query);
+    },
+    // -------------------------------------------------------------------
+    // Billing (CL1) — inline, no separate proxy
+    // -------------------------------------------------------------------
+    async getUsage() {
+      assertNotDisposed();
+      assertNotAnonymous("getUsage");
+      const response = await transport.request({
+        method: "GET",
+        path: "/v1/usage",
+        ipuCost: IPU_COSTS.USAGE_QUERY
+      });
+      if (response.ipuUsed !== void 0 && response.ipuRemaining !== void 0) {
+        tracker.reconcile(response.ipuUsed, response.ipuRemaining, response.ipuCost);
+      }
+      const ipu = buildIPU11(
+        response.ipuUsed,
+        response.ipuRemaining,
+        response.ipuCost,
+        isAnonymous
+      );
+      const data = response.data !== null ? {
+        used: response.data.used,
+        limit: response.data.limit,
+        tier: response.data.tier
+      } : { used: 0, limit: 0, tier: "unknown" };
+      return { data, ipu };
+    },
+    async getLedger(options) {
+      assertNotDisposed();
+      assertNotAnonymous("getLedger");
+      return ledgerQueryProxy.getLedger(options);
+    },
+    // -------------------------------------------------------------------
+    // Operations
+    // -------------------------------------------------------------------
+    async certify(contractId) {
+      assertNotDisposed();
+      assertNotAnonymous("certify");
+      return certifyProxy.certify(contractId);
+    },
+    async deleteProjectData(projectId) {
+      assertNotDisposed();
+      assertNotAnonymous("deleteProjectData");
+      return dataDeletionProxy.deleteProjectData(projectId);
+    },
+    // -------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------
+    dispose() {
+      disposed = true;
+    }
+  };
+}
+
+exports.CLOUD_SDK_VERSION = CLOUD_SDK_VERSION;
+exports.CloudError = CloudError;
+exports.IPU_COSTS = IPU_COSTS;
+exports.createEnterstellarCloudClient = createEnterstellarCloudClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map