@aexhq/sdk 0.46.5-canary → 0.50.0

package/dist/_contracts/error-codes.js

@@ -1,116 +0,0 @@
-/**
- * SSoT for the platform's STABLE API error codes.
- *
- * The server (platform `api.ts`) imports this table instead of keeping its
- * own private copy, so a route emitting a code absent from the union fails to
- * compile and adding a code without a message is caught. The SDK error factory
- * ({@link import("./error-factory.js").apiErrorFromResponse}) dispatches on the
- * code to a typed subclass; the CLI maps it to a human remedy.
- *
- * The code is the stable, machine-branchable identity of a failure — distinct
- * from the human `message`. `idempotency_conflict` and `insufficient_scope`
- * (previously message-less bare 409/403 bodies) are first-class here.
- */
-export const AEX_API_ERROR_CODES = [
-    "unauthorized",
-    "forbidden",
-    "insufficient_scope",
-    "token_invalid",
-    "token_revoked",
-    "token_expired",
-    "malformed_token",
-    "not_found",
-    "idempotency_conflict",
-    "session_busy",
-    "checkpoint_not_available",
-    "session_not_terminal",
-    "session_terminal",
-    "event_archive_too_large",
-    "event_archive_deadline_exceeded",
-    "unknown_workspace",
-    "workspace_inactive",
-    "workspace_concurrency_exceeded",
-    "workspace_submit_rate_exceeded",
-    "workspace_spend_cap_exceeded",
-    "workspace_cap_exceeded",
-    "insufficient_credits",
-    "account_blocked",
-    "quota_exhausted",
-    "depth_exceeded",
-    "rate_limited",
-    "out_of_memory",
-    "disk_full",
-    "content_deleted",
-    "upstream_error",
-    "internal_error"
-];
-/**
- * Human message per stable code. A `Record` (not `Partial`) so a code added to
- * {@link AEX_API_ERROR_CODES} without a message is a COMPILE error. These are
- * the fallback messages the factory uses when the server sends a BARE code with
- * no `message` detail.
- */
-export const AEX_API_ERROR_MESSAGES = {
-    unauthorized: "The request was not authenticated.",
-    forbidden: "The API key is not permitted to perform this action.",
-    insufficient_scope: "The API key is missing a scope this endpoint requires.",
-    token_invalid: "The API key is not valid.",
-    token_revoked: "The API key has been revoked.",
-    token_expired: "The API key has expired.",
-    malformed_token: "The API key is malformed.",
-    not_found: "The requested resource was not found.",
-    idempotency_conflict: "This idempotency key was already used with a different request body.",
-    session_busy: "The session is busy handling another turn.",
-    checkpoint_not_available: "The session does not have a committed checkpoint available yet.",
-    session_not_terminal: "The session has not reached a terminal state yet.",
-    session_terminal: "The session has ended and cannot perform this action.",
-    event_archive_too_large: "The session event history is too large for synchronous bulk export.",
-    event_archive_deadline_exceeded: "The synchronous session event export exceeded its deadline.",
-    unknown_workspace: "The workspace could not be resolved from the API key.",
-    workspace_inactive: "The workspace no longer accepts new session work.",
-    workspace_concurrency_exceeded: "The workspace has reached its concurrent-run limit.",
-    workspace_submit_rate_exceeded: "The workspace submit-rate limit was exceeded.",
-    workspace_spend_cap_exceeded: "The workspace monthly spend cap was reached.",
-    workspace_cap_exceeded: "The organization has reached its workspace limit.",
-    insufficient_credits: "The free monthly allowance and the prepaid credit balance are both exhausted.",
-    account_blocked: "The organization is blocked and cannot start new work.",
-    quota_exhausted: "The request exceeds the workspace's remaining usage grant and there is no billable path for the overage.",
-    depth_exceeded: "The request would create a subagent deeper than the lineage depth ceiling.",
-    rate_limited: "Too many requests — retry after a short backoff.",
-    out_of_memory: "The runtime was killed for exceeding its memory allocation.",
-    disk_full: "A write failed because the runtime's filesystem was full.",
-    content_deleted: "The session's content was deleted after its retention window; only metadata remains.",
-    upstream_error: "An upstream provider returned an error.",
-    internal_error: "The aex API encountered an internal error."
-};
-/** Optional per-code fix hint the CLI surfaces alongside the error message. */
-export const AEX_API_ERROR_REMEDIES = {
-    insufficient_scope: "Mint an API key that includes the scope this endpoint requires.",
-    idempotency_conflict: "Use a fresh idempotency key, or resubmit the byte-identical request body to replay the original result.",
-    token_invalid: "Check the API key value and that its plane matches your baseUrl.",
-    token_expired: "Mint a new API key.",
-    token_revoked: "Mint a new API key.",
-    session_terminal: "Create or open an active session before retrying this action.",
-    checkpoint_not_available: "Wait for the current run to finish before reading checkpoint-backed session files.",
-    event_archive_too_large: "Traverse the event history with session.events.iterate().",
-    event_archive_deadline_exceeded: "Traverse the event history with session.events.iterate().",
-    workspace_inactive: "Use an active workspace; a workspace being deleted cannot accept new session work.",
-    workspace_spend_cap_exceeded: "Raise the workspace spend cap or wait for the next billing cycle.",
-    insufficient_credits: "Top up the prepaid balance, or add a payment method if the organization has none saved.",
-    // Deliberately NOT a top-up prompt: credit does not lift a block, so sending a
-    // blocked customer to the payment form takes their money and changes nothing.
-    account_blocked: "Adding credit does not lift the block — contact support to resolve it.",
-    workspace_concurrency_exceeded: "Wait for in-flight sessions to finish or raise the concurrency limit.",
-    workspace_submit_rate_exceeded: "Slow the submit rate or raise the workspace submit-rate limit.",
-    workspace_cap_exceeded: "Delete an unused workspace, or contact support to raise the organization's workspace limit.",
-    quota_exhausted: "Top up the prepaid balance so usage beyond the free monthly allowance has somewhere to bill.",
-    depth_exceeded: "Spawn the subagent from a shallower session, or flatten the lineage.",
-    out_of_memory: "Re-run on a larger runtimeSize, or reduce the memory the session holds at once.",
-    disk_full: "Re-run on a larger runtimeSize, or write fewer/smaller files inside the session.",
-    content_deleted: "The session content is gone after its retention window; read the session record's metadata, or start a new session."
-};
-const API_ERROR_CODE_SET = new Set(AEX_API_ERROR_CODES);
-/** Narrow an arbitrary value to a known {@link AexApiErrorCode}. */
-export function isAexApiErrorCode(value) {
-    return typeof value === "string" && API_ERROR_CODE_SET.has(value);
-}

package/dist/_contracts/error-factory.d.ts

@@ -1,32 +0,0 @@
-/**
- * The SINGLE wire→exception mapping. `apiErrorFromResponse` reads a non-2xx
- * body's stable `error` code, attaches it (typed) as `apiCode` plus the
- * `requestId`, and dispatches to the right {@link AexApiError} subclass. Both
- * `HttpClient.request` and `HttpClient.download` construct errors ONLY through
- * here, so the wire→exception mapping lives in one place — no inline
- * `new AexApiError(...)` with a hardcoded coarse code.
- */
-import { AexApiError } from "./sdk-errors.js";
-import { type AexApiErrorCode } from "./error-codes.js";
-export interface ApiErrorFromResponseInput {
-    readonly status: number;
-    readonly body: unknown;
-    /**
-     * Precomputed human message (e.g. `HttpClient`'s `extractErrorMessage`). When
-     * absent the factory derives one from the stable code table.
-     */
-    readonly message?: string;
-    readonly requestId?: string;
-    readonly cause?: unknown;
-}
-type ApiErrorKind = "auth" | "idempotency" | "not_found" | "rate_limit" | "content_deleted" | "generic";
-/**
- * EXHAUSTIVE stable-code → subclass-kind map. There is NO `default`: adding a
- * code to {@link AEX_API_ERROR_CODES} without a case here fails to compile
- * (the function would fall through and return `undefined`, which the
- * `ApiErrorKind` return type forbids). This is the whole-class guard that a new
- * server code can never silently collapse to the base error.
- */
-export declare function apiErrorKindForCode(code: AexApiErrorCode): ApiErrorKind;
-export declare function apiErrorFromResponse(input: ApiErrorFromResponseInput): AexApiError;
-export {};

package/dist/_contracts/error-factory.js

@@ -1,174 +0,0 @@
-/**
- * The SINGLE wire→exception mapping. `apiErrorFromResponse` reads a non-2xx
- * body's stable `error` code, attaches it (typed) as `apiCode` plus the
- * `requestId`, and dispatches to the right {@link AexApiError} subclass. Both
- * `HttpClient.request` and `HttpClient.download` construct errors ONLY through
- * here, so the wire→exception mapping lives in one place — no inline
- * `new AexApiError(...)` with a hardcoded coarse code.
- */
-import { AexApiError, AexAuthError, AexIdempotencyConflictError, AexNotFoundError, AexRateLimitError, ContentDeletedError } from "./sdk-errors.js";
-import { AEX_API_ERROR_MESSAGES, isAexApiErrorCode } from "./error-codes.js";
-/**
- * EXHAUSTIVE stable-code → subclass-kind map. There is NO `default`: adding a
- * code to {@link AEX_API_ERROR_CODES} without a case here fails to compile
- * (the function would fall through and return `undefined`, which the
- * `ApiErrorKind` return type forbids). This is the whole-class guard that a new
- * server code can never silently collapse to the base error.
- */
-export function apiErrorKindForCode(code) {
-    switch (code) {
-        case "unauthorized":
-        case "forbidden":
-        case "insufficient_scope":
-        case "token_invalid":
-        case "token_revoked":
-        case "token_expired":
-        case "malformed_token":
-            return "auth";
-        case "idempotency_conflict":
-            return "idempotency";
-        case "not_found":
-            return "not_found";
-        case "rate_limited":
-        case "workspace_concurrency_exceeded":
-        case "workspace_submit_rate_exceeded":
-            return "rate_limit";
-        case "content_deleted":
-            return "content_deleted";
-        case "session_busy":
-        case "checkpoint_not_available":
-        case "session_not_terminal":
-        case "session_terminal":
-        case "event_archive_too_large":
-        case "event_archive_deadline_exceeded":
-        case "unknown_workspace":
-        case "workspace_inactive":
-        case "workspace_spend_cap_exceeded":
-        case "workspace_cap_exceeded":
-        // Both 402s stay on the base class. They carry OPPOSITE remedies (buy credit
-        // / do not buy credit), so a shared subclass would invite exactly the
-        // conflation the two codes exist to prevent — branch on `apiCode`.
-        case "insufficient_credits":
-        case "account_blocked":
-        case "quota_exhausted":
-        case "depth_exceeded":
-        case "out_of_memory":
-        case "disk_full":
-        case "upstream_error":
-        case "internal_error":
-            return "generic";
-    }
-}
-function kindForStatus(status) {
-    if (status === 401 || status === 403)
-        return "auth";
-    if (status === 404)
-        return "not_found";
-    if (status === 429)
-        return "rate_limit";
-    return "generic";
-}
-export function apiErrorFromResponse(input) {
-    const apiCode = apiCodeFromBody(input.body);
-    const requestId = input.requestId ?? requestIdFromBody(input.body);
-    const message = input.message ?? fallbackMessage(apiCode, input.body);
-    const kind = apiCode !== undefined ? apiErrorKindForCode(apiCode) : kindForStatus(input.status);
-    const init = {
-        status: input.status,
-        message,
-        body: input.body,
-        apiCode,
-        requestId,
-        cause: input.cause
-    };
-    switch (kind) {
-        case "auth":
-            return new AexAuthError({ ...init, requiredScope: requiredScopeFromBody(input.body) });
-        case "idempotency":
-            return new AexIdempotencyConflictError(init);
-        case "not_found":
-            return new AexNotFoundError(init);
-        case "rate_limit":
-            return new AexRateLimitError({ ...init, retryAfterMs: retryAfterMsFromBody(input.body) });
-        case "content_deleted":
-            return new ContentDeletedError({
-                ...init,
-                sessionId: sessionIdFromBody(input.body),
-                purgedAt: purgedAtFromBody(input.body),
-                deletedBy: deletedByFromBody(input.body)
-            });
-        case "generic":
-            return new AexApiError(input.status, message, input.body, {
-                apiCode,
-                requestId,
-                ...(input.cause !== undefined ? { cause: input.cause } : {})
-            });
-    }
-}
-function asRecord(body) {
-    return body !== null && typeof body === "object" && !Array.isArray(body)
-        ? body
-        : undefined;
-}
-function apiCodeFromBody(body) {
-    const record = asRecord(body);
-    if (!record)
-        return undefined;
-    if (isAexApiErrorCode(record.error))
-        return record.error;
-    if (isAexApiErrorCode(record.code))
-        return record.code;
-    return undefined;
-}
-function requestIdFromBody(body) {
-    const record = asRecord(body);
-    const value = record?.requestId;
-    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
-}
-function requiredScopeFromBody(body) {
-    const record = asRecord(body);
-    if (!record)
-        return undefined;
-    for (const key of ["requiredScope", "required_scope", "scope"]) {
-        const value = record[key];
-        if (typeof value === "string" && value.length > 0)
-            return value;
-    }
-    return undefined;
-}
-function sessionIdFromBody(body) {
-    const value = asRecord(body)?.sessionId;
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-function purgedAtFromBody(body) {
-    const value = asRecord(body)?.purgedAt;
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-function deletedByFromBody(body) {
-    const value = asRecord(body)?.deletedBy;
-    return value === "retention" || value === "user" ? value : undefined;
-}
-function retryAfterMsFromBody(body) {
-    const record = asRecord(body);
-    if (!record)
-        return undefined;
-    if (typeof record.retryAfterMs === "number" && Number.isFinite(record.retryAfterMs)) {
-        return record.retryAfterMs;
-    }
-    if (typeof record.retryAfter === "number" && Number.isFinite(record.retryAfter)) {
-        return record.retryAfter * 1000;
-    }
-    return undefined;
-}
-function fallbackMessage(apiCode, body) {
-    if (apiCode !== undefined)
-        return AEX_API_ERROR_MESSAGES[apiCode];
-    const record = asRecord(body);
-    const message = record?.message;
-    if (typeof message === "string" && message.length > 0)
-        return message;
-    const error = record?.error;
-    if (typeof error === "string" && error.length > 0)
-        return error;
-    return "aex API request failed";
-}