@everfur/sdk 0.1.0

package/dist/EverfurResult-D92-uL82.d.cts

@@ -0,0 +1,240 @@
+/** The frozen error taxonomy. Additive-only under the dated-contract policy. */
+type EverfurErrorCode = 'authExpired' | 'authRejected' | 'sessionRequired' | 'accessDenied' | 'paymentRequired' | 'quotaExceeded' | 'rateLimited' | 'validationFailed' | 'sdkUpdateRequired' | 'conflict' | 'idempotencyConflict' | 'idempotencyInFlight' | 'conversationNotFound' | 'petNotFound' | 'resourceNotFound' | 'streamTimeout' | 'mediaUploadFailed' | 'moderationBlocked' | 'upstreamLlmTimeout' | 'internalError' | 'notImplemented' | 'serviceUnavailable' | 'streamIncomplete' | 'unknown';
+/** Every code, frozen, for iteration in conformance / property tests. */
+declare const EVERFUR_ERROR_CODES: readonly EverfurErrorCode[];
+/**
+ * The coarse failure axis. Adopted from Stripe's error CONTENT (a stable, documented type alongside a
+ * fine-grained code) while REFUSING its control flow: an Everfur failure is still a returned
+ * `EverfurResult`, never a throw, so a domain failure can never trip a partner's error boundary.
+ *
+ * Branch on `category` for the shape of the response (re-auth? show a paywall? offer retry?) and on
+ * `code` only when the exact case matters. `category` is total over the taxonomy, so a code added in a
+ * later SDK still lands in a bucket an already-shipped consumer handles.
+ */
+type EverfurErrorCategory = 'authentication' | 'authorization' | 'entitlement' | 'rateLimit' | 'invalidRequest' | 'notFound' | 'conflict' | 'connection' | 'server' | 'media' | 'policy' | 'unknown';
+/** Every category, frozen, for iteration in conformance / property tests. */
+declare const EVERFUR_ERROR_CATEGORIES: readonly EverfurErrorCategory[];
+/** The coarse category for a normalized code. Total: every member has exactly one category. */
+declare function categoryFor(code: EverfurErrorCode): EverfurErrorCategory;
+/**
+ * Map a raw wire `code` (any casing, any channel) to the normalized enum.
+ *
+ * Order, and why:
+ *  1. The CONTRACT REGISTRY first (./contract). Every code `contract/errors.yaml` declares folds to the
+ *     member that row names. It has to PRECEDE the legacy rules for one code and it CHANGES the answer
+ *     for sixteen, and those are different statements:
+ *
+ *     - ORDERING. `AuthorizationException` is the only registry code with a non-`unknown` legacy fold.
+ *       It is the generic, NON-retryable 401 and must fold to `authRejected`, where the blanket `AUTH*`
+ *       prefix rule below would have folded it to `authExpired` and spun a token refresh against a 401
+ *       no fresh token can fix. That is the fold the ORDER decides.
+ *     - COVERAGE. Sixteen codes that previously fell through to `unknown` now resolve to a named
+ *       member. They are enumerated in `tests/contract/errorRegistry.test.ts` ("every code that used
+ *       to fall through to `unknown` now has a name"), which is the list to read before assuming this
+ *       change is cosmetic.
+ *
+ *     TWO OF THOSE SIXTEEN REACH THE AUTOMATIC RETRY LOOP, not just the affordance. `ThrottlingException`
+ *     now folds to `rateLimited` and `InternalFailureException` to `internalError`, both members of
+ *     AUTO_RETRYABLE_CODES below. `transport.ts` computes `isAutoRetryable(fromWire(wireCode))` into the
+ *     synthetic error frame's `retryable`, which `ChatController` reads as `framedRetry` and turns into
+ *     up to `maxAttempts` retried stream attempts. So a 500 `InternalFailureException` that used to be
+ *     terminal is now retried with backoff. That widening is DELIBERATE (the registry marks both
+ *     retryable and the historical failure was a retryable 503 arriving at the UI as a dead end) and it
+ *     is pinned by a test, so it cannot be walked back by accident.
+ *  2. The `AUTH*` prefix fold, kept verbatim for Dart parity (everfur_error_code.dart:43-65).
+ *  3. The exact-match switch: wire codes that are live but not (yet) in the registry.
+ *  4. Anything else -> `unknown`, which is NON-retryable. A new backend code is absorbed, never fatal.
+ */
+declare function fromWire(wire: string | null): EverfurErrorCode;
+/**
+ * HTTP-status fallback (SPEC-00 §3.1), used ONLY when there is no wire `code`.
+ * 403 is DISTINCT from auth (accessDenied); it must never sign the user out or nuke a valid session.
+ * 421 folds to `unknown` (a misdirected request, the deprecated storefront proxy rejecting a
+ * partner key). 400/422 have no dedicated enum member; they surface as `unknown` (NON-retryable).
+ *
+ * DELIBERATELY unchanged by the registry reconciliation. This is the no-wire-code path, so there is no
+ * registry row to consult: a bare 400 could be `ValidationException` or `invalidRequest`, and a bare 503
+ * could be `ServiceUnavailableException` or `unavailable`. Guessing one would hand a caller a specific
+ * remedy for a failure the server never identified, so the status fallback stays as coarse as the
+ * evidence. When a wire code IS present, `fromWire` wins and the specific member is used.
+ */
+declare function fromHttpStatus(status: number): EverfurErrorCode;
+/** The retryable-with-backoff set (SPEC-00 §3.2). Frozen for property tests. */
+declare const AUTO_RETRYABLE_CODES: ReadonlySet<EverfurErrorCode>;
+/**
+ * True for the retryable-with-backoff set. `authExpired` is NOT here: it is not a backoff retry, it
+ * triggers one token refresh + single replay (§4.3), then fails as `authRejected`.
+ */
+declare function isAutoRetryable(code: EverfurErrorCode): boolean;
+/**
+ * Codes the CONTRACT REGISTRY marks retryable that the SDK's backoff set does not contain.
+ *
+ * Two different questions, deliberately kept apart:
+ *  - `isAutoRetryable` answers "will the SDK silently retry this with backoff?" It is the input to the
+ *    controller's retry loop and to `defaultErrorPolicy`, and it is FROZEN at its five members.
+ *  - `isRetryableCode` answers "could retrying this ever succeed?" It is what a surface reads to decide
+ *    whether to offer a Retry affordance, and it is the union of the backoff set with the registry's own
+ *    `retryable: true` rows.
+ *
+ * The split is ADDITIVE-ONLY by construction: this set names only members introduced by the registry
+ * reconciliation, so importing the registry's retry semantics cannot re-litigate the policy of a code
+ * that already shipped. (`DAILY_QUOTA_EXCEEDED` is the sharp example: the registry marks it retryable,
+ * but `quotaExceeded` has shipped as terminal-for-today and keeps that behaviour.)
+ */
+declare const RETRYABLE_CONTRACT_CODES: ReadonlySet<EverfurErrorCode>;
+/**
+ * True when retrying could plausibly succeed: the backoff set, plus the registry-declared retryable
+ * codes. Drives the retry AFFORDANCE (`EverfurError.retryable`), not the automatic retry loop.
+ */
+declare function isRetryableCode(code: EverfurErrorCode): boolean;
+/**
+ * The full retry decision: a frame's explicit `retryable:true` ALSO forces a retry
+ * (`shouldRetry = frameRetryable || isAutoRetryable(code)`), parity with EverfurChatException.shouldRetry.
+ */
+declare function shouldRetry(code: EverfurErrorCode, frameRetryable?: boolean): boolean;
+/** Exponential-with-full-jitter base. */
+declare const BACKOFF_BASE_MS = 500;
+/** Exponential-with-full-jitter cap. */
+declare const BACKOFF_CAP_MS = 8000;
+/** Max attempts before surfacing the terminal error. */
+declare const MAX_RETRY_ATTEMPTS = 4;
+/**
+ * Full-jitter backoff: `delay = random(0, min(BASE * 2^attempt, CAP))`. `attempt` is 0-based.
+ * `rng` is injectable so tests are deterministic.
+ */
+declare function backoffDelayMs(attempt: number, rng?: () => number): number;
+/**
+ * 403-excluded-from-recreate (SPEC-00 §3 / §4.3). A 404 `conversationNotFound` recreates the
+ * conversation and resends ONCE; a 403 `accessDenied` is TERMINAL, it never recreates a conversation
+ * and never invalidates the session (the REACT-NATIVE-12 storm). This predicate is the single source
+ * of that rule for the recovery policy: ONLY `conversationNotFound` may trigger a recreate.
+ */
+declare function canRecreateOnNotFound(code: EverfurErrorCode): boolean;
+
+/**
+ * The one normalized error object. Expected domain failures settle as this (inside an EverfurResult or a
+ * terminal frame), never a throw. `wireMessage` is telemetry/logs only and is never surfaced to a user.
+ */
+interface EverfurError {
+    readonly code: EverfurErrorCode;
+    /** Coarse branching axis (auth vs entitlement vs connection ...). Total over the taxonomy. */
+    readonly category: EverfurErrorCategory;
+    /** `isRetryableCode(code)` OR an explicit `retryable:true` from the frame / body. */
+    readonly retryable: boolean;
+    readonly httpStatus?: number;
+    /**
+     * The `X-Request-ID` of the response that produced this failure, when the server sent one. The one
+     * string a partner can quote in a support ticket, and the join key back to the server-side trace.
+     * Absent on failures with no HTTP response (an offline fetch rejection) and on the SSE frames, which
+     * the contract records as carrying no request id at all.
+     */
+    readonly requestId?: string;
+    /** Site-relative documentation path for the wire code, from the contract registry. No host is implied. */
+    readonly docUrl?: string;
+    /** raw wire text; telemetry / logs only, NEVER rendered. NON-ENUMERABLE. */
+    readonly wireMessage?: string;
+    /** Opaque parsed wire payload for debugging (untrusted, unvalidated). NON-ENUMERABLE. */
+    readonly raw?: unknown;
+    /** SAFE localizable copy resolved from `code` via `userFacingError` (never the raw wireMessage). */
+    readonly displayMessage: string;
+}
+/**
+ * The ONLY function the UI may call to render an error. Returns SAFE, code-derived copy; it never returns
+ * the untrusted `wireMessage`. Total over the taxonomy (an unmapped code cannot occur at the type level).
+ */
+declare function userFacingError(code: EverfurErrorCode): string;
+/** Options accepted by `makeEverfurError`. Every field is optional; the code alone is a valid error. */
+interface MakeEverfurErrorOptions {
+    /** Forces the retry affordance. Omit to derive it from the code (`isRetryableCode`). */
+    readonly retryable?: boolean;
+    readonly httpStatus?: number;
+    /** `X-Request-ID` from the response, when the server sent one. */
+    readonly requestId?: string | null;
+    /**
+     * The RAW wire code string, used to resolve the contract registry row (and from it, `docUrl`). Pass
+     * the code exactly as the server sent it; a code that is not in the registry simply yields no docUrl.
+     */
+    readonly wireCode?: string | null;
+    /** Untrusted wire text. Carried NON-ENUMERABLY for telemetry; never rendered. */
+    readonly wireMessage?: string | null;
+    /** Opaque parsed wire payload. Carried NON-ENUMERABLY for debugging; never rendered. */
+    readonly raw?: unknown;
+}
+/**
+ * Build a normalized, frozen `EverfurError` from a normalized code plus optional wire/HTTP context.
+ *
+ * `displayMessage` is always the SAFE code-derived string. `retryable` defaults to the code's policy
+ * (`isRetryableCode`) unless the caller overrides it, e.g. a frame carrying explicit `retryable:true`.
+ * `requestId` and `docUrl` are the two support-facing additions: the id a partner quotes, and the
+ * site-relative registry path for the wire code. `wireMessage` and `raw` are carried NON-ENUMERABLY and
+ * are dropped when empty.
+ */
+declare function makeEverfurError(code: EverfurErrorCode, opts?: MakeEverfurErrorOptions): EverfurError;
+
+/**
+ * The settle type. An async public operation returns this instead of throwing for an EXPECTED failure.
+ * A successful result may carry a non-fatal `warning` (e.g. served-stale, degraded path).
+ */
+type EverfurResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly warning?: EverfurError;
+} | {
+    readonly ok: false;
+    readonly error: EverfurError;
+};
+/** Construct a success result. Frozen, public state is immutable end to end. */
+declare function ok<T>(value: T, warning?: EverfurError): EverfurResult<T>;
+/** Construct a failure result. Frozen. */
+declare function err<T = never>(error: EverfurError): EverfurResult<T>;
+/** Narrowing guard: true iff the result is a success. */
+declare function isOk<T>(r: EverfurResult<T>): r is {
+    readonly ok: true;
+    readonly value: T;
+    readonly warning?: EverfurError;
+};
+/** Narrowing guard: true iff the result is a failure. */
+declare function isErr<T>(r: EverfurResult<T>): r is {
+    readonly ok: false;
+    readonly error: EverfurError;
+};
+/**
+ * The real `Error` subclass `unwrap` throws, so an imperative call site that lets the throw escape
+ * produces a proper Error rather than a bare object (which a crash reporter files as
+ * "Non-Error exception captured", with no stack and no grouping).
+ *
+ * `message` is built from the normalized `code` and the frozen, product-owned `displayMessage` ONLY.
+ * The untrusted `wireMessage` is deliberately NOT in it: `message` is the one field every telemetry
+ * vendor captures and indexes by default, so putting wire text there would make an untrusted,
+ * healthcare-adjacent string flow automatically into a partner's third-party tooling. The full
+ * `EverfurError` hangs off `.error`, where `wireMessage` and `raw` remain non-enumerable.
+ */
+declare class EverfurThrownError extends Error {
+    /** The settled error this was thrown from. Its `wireMessage` / `raw` stay non-enumerable. */
+    readonly error: EverfurError;
+    /** Mirror of `error.code`, so a catch block can branch without reaching through `.error`. */
+    readonly code: EverfurError['code'];
+    /** Mirror of `error.category`, the coarse branching axis. */
+    readonly category: EverfurError['category'];
+    constructor(error: EverfurError);
+}
+/**
+ * Escape hatch for imperative callers: return the value or throw. The throw is an `EverfurThrownError`
+ * (a real `Error`, safe message); the settled `EverfurError` is on its `.error`.
+ * Prefer pattern-matching on `ok`; `unwrap` exists for call sites that want the throw.
+ */
+declare function unwrap<T>(r: EverfurResult<T>): T;
+/**
+ * Thrown SYNCHRONOUSLY for programmer error ONLY, never for a network or domain failure.
+ * Mirrors Flutter `_requireInitialized` (a real guard, not an assert).
+ *
+ *  - `not-initialized`    , a capability used before EverfurProvider mounted / init ran.
+ *  - `invalid-argument`   , a malformed id or option shape (e.g. a non-UUID conversation id).
+ *  - `missing-peer-dependency`, a capability subpath used without its required native peer dep.
+ */
+declare class EverfurConfigError extends Error {
+    readonly kind: 'not-initialized' | 'invalid-argument' | 'missing-peer-dependency';
+    constructor(kind: 'not-initialized' | 'invalid-argument' | 'missing-peer-dependency', message: string);
+}
+
+export { AUTO_RETRYABLE_CODES as A, BACKOFF_BASE_MS as B, type EverfurResult as E, MAX_RETRY_ATTEMPTS as M, RETRYABLE_CONTRACT_CODES as R, type EverfurErrorCode as a, BACKOFF_CAP_MS as b, EVERFUR_ERROR_CATEGORIES as c, EVERFUR_ERROR_CODES as d, EverfurConfigError as e, type EverfurError as f, type EverfurErrorCategory as g, EverfurThrownError as h, type MakeEverfurErrorOptions as i, backoffDelayMs as j, canRecreateOnNotFound as k, categoryFor as l, err as m, fromHttpStatus as n, fromWire as o, isAutoRetryable as p, isErr as q, isOk as r, isRetryableCode as s, makeEverfurError as t, ok as u, shouldRetry as v, unwrap as w, userFacingError as x };

package/dist/EverfurResult-D92-uL82.d.ts

@@ -0,0 +1,240 @@
+/** The frozen error taxonomy. Additive-only under the dated-contract policy. */
+type EverfurErrorCode = 'authExpired' | 'authRejected' | 'sessionRequired' | 'accessDenied' | 'paymentRequired' | 'quotaExceeded' | 'rateLimited' | 'validationFailed' | 'sdkUpdateRequired' | 'conflict' | 'idempotencyConflict' | 'idempotencyInFlight' | 'conversationNotFound' | 'petNotFound' | 'resourceNotFound' | 'streamTimeout' | 'mediaUploadFailed' | 'moderationBlocked' | 'upstreamLlmTimeout' | 'internalError' | 'notImplemented' | 'serviceUnavailable' | 'streamIncomplete' | 'unknown';
+/** Every code, frozen, for iteration in conformance / property tests. */
+declare const EVERFUR_ERROR_CODES: readonly EverfurErrorCode[];
+/**
+ * The coarse failure axis. Adopted from Stripe's error CONTENT (a stable, documented type alongside a
+ * fine-grained code) while REFUSING its control flow: an Everfur failure is still a returned
+ * `EverfurResult`, never a throw, so a domain failure can never trip a partner's error boundary.
+ *
+ * Branch on `category` for the shape of the response (re-auth? show a paywall? offer retry?) and on
+ * `code` only when the exact case matters. `category` is total over the taxonomy, so a code added in a
+ * later SDK still lands in a bucket an already-shipped consumer handles.
+ */
+type EverfurErrorCategory = 'authentication' | 'authorization' | 'entitlement' | 'rateLimit' | 'invalidRequest' | 'notFound' | 'conflict' | 'connection' | 'server' | 'media' | 'policy' | 'unknown';
+/** Every category, frozen, for iteration in conformance / property tests. */
+declare const EVERFUR_ERROR_CATEGORIES: readonly EverfurErrorCategory[];
+/** The coarse category for a normalized code. Total: every member has exactly one category. */
+declare function categoryFor(code: EverfurErrorCode): EverfurErrorCategory;
+/**
+ * Map a raw wire `code` (any casing, any channel) to the normalized enum.
+ *
+ * Order, and why:
+ *  1. The CONTRACT REGISTRY first (./contract). Every code `contract/errors.yaml` declares folds to the
+ *     member that row names. It has to PRECEDE the legacy rules for one code and it CHANGES the answer
+ *     for sixteen, and those are different statements:
+ *
+ *     - ORDERING. `AuthorizationException` is the only registry code with a non-`unknown` legacy fold.
+ *       It is the generic, NON-retryable 401 and must fold to `authRejected`, where the blanket `AUTH*`
+ *       prefix rule below would have folded it to `authExpired` and spun a token refresh against a 401
+ *       no fresh token can fix. That is the fold the ORDER decides.
+ *     - COVERAGE. Sixteen codes that previously fell through to `unknown` now resolve to a named
+ *       member. They are enumerated in `tests/contract/errorRegistry.test.ts` ("every code that used
+ *       to fall through to `unknown` now has a name"), which is the list to read before assuming this
+ *       change is cosmetic.
+ *
+ *     TWO OF THOSE SIXTEEN REACH THE AUTOMATIC RETRY LOOP, not just the affordance. `ThrottlingException`
+ *     now folds to `rateLimited` and `InternalFailureException` to `internalError`, both members of
+ *     AUTO_RETRYABLE_CODES below. `transport.ts` computes `isAutoRetryable(fromWire(wireCode))` into the
+ *     synthetic error frame's `retryable`, which `ChatController` reads as `framedRetry` and turns into
+ *     up to `maxAttempts` retried stream attempts. So a 500 `InternalFailureException` that used to be
+ *     terminal is now retried with backoff. That widening is DELIBERATE (the registry marks both
+ *     retryable and the historical failure was a retryable 503 arriving at the UI as a dead end) and it
+ *     is pinned by a test, so it cannot be walked back by accident.
+ *  2. The `AUTH*` prefix fold, kept verbatim for Dart parity (everfur_error_code.dart:43-65).
+ *  3. The exact-match switch: wire codes that are live but not (yet) in the registry.
+ *  4. Anything else -> `unknown`, which is NON-retryable. A new backend code is absorbed, never fatal.
+ */
+declare function fromWire(wire: string | null): EverfurErrorCode;
+/**
+ * HTTP-status fallback (SPEC-00 §3.1), used ONLY when there is no wire `code`.
+ * 403 is DISTINCT from auth (accessDenied); it must never sign the user out or nuke a valid session.
+ * 421 folds to `unknown` (a misdirected request, the deprecated storefront proxy rejecting a
+ * partner key). 400/422 have no dedicated enum member; they surface as `unknown` (NON-retryable).
+ *
+ * DELIBERATELY unchanged by the registry reconciliation. This is the no-wire-code path, so there is no
+ * registry row to consult: a bare 400 could be `ValidationException` or `invalidRequest`, and a bare 503
+ * could be `ServiceUnavailableException` or `unavailable`. Guessing one would hand a caller a specific
+ * remedy for a failure the server never identified, so the status fallback stays as coarse as the
+ * evidence. When a wire code IS present, `fromWire` wins and the specific member is used.
+ */
+declare function fromHttpStatus(status: number): EverfurErrorCode;
+/** The retryable-with-backoff set (SPEC-00 §3.2). Frozen for property tests. */
+declare const AUTO_RETRYABLE_CODES: ReadonlySet<EverfurErrorCode>;
+/**
+ * True for the retryable-with-backoff set. `authExpired` is NOT here: it is not a backoff retry, it
+ * triggers one token refresh + single replay (§4.3), then fails as `authRejected`.
+ */
+declare function isAutoRetryable(code: EverfurErrorCode): boolean;
+/**
+ * Codes the CONTRACT REGISTRY marks retryable that the SDK's backoff set does not contain.
+ *
+ * Two different questions, deliberately kept apart:
+ *  - `isAutoRetryable` answers "will the SDK silently retry this with backoff?" It is the input to the
+ *    controller's retry loop and to `defaultErrorPolicy`, and it is FROZEN at its five members.
+ *  - `isRetryableCode` answers "could retrying this ever succeed?" It is what a surface reads to decide
+ *    whether to offer a Retry affordance, and it is the union of the backoff set with the registry's own
+ *    `retryable: true` rows.
+ *
+ * The split is ADDITIVE-ONLY by construction: this set names only members introduced by the registry
+ * reconciliation, so importing the registry's retry semantics cannot re-litigate the policy of a code
+ * that already shipped. (`DAILY_QUOTA_EXCEEDED` is the sharp example: the registry marks it retryable,
+ * but `quotaExceeded` has shipped as terminal-for-today and keeps that behaviour.)
+ */
+declare const RETRYABLE_CONTRACT_CODES: ReadonlySet<EverfurErrorCode>;
+/**
+ * True when retrying could plausibly succeed: the backoff set, plus the registry-declared retryable
+ * codes. Drives the retry AFFORDANCE (`EverfurError.retryable`), not the automatic retry loop.
+ */
+declare function isRetryableCode(code: EverfurErrorCode): boolean;
+/**
+ * The full retry decision: a frame's explicit `retryable:true` ALSO forces a retry
+ * (`shouldRetry = frameRetryable || isAutoRetryable(code)`), parity with EverfurChatException.shouldRetry.
+ */
+declare function shouldRetry(code: EverfurErrorCode, frameRetryable?: boolean): boolean;
+/** Exponential-with-full-jitter base. */
+declare const BACKOFF_BASE_MS = 500;
+/** Exponential-with-full-jitter cap. */
+declare const BACKOFF_CAP_MS = 8000;
+/** Max attempts before surfacing the terminal error. */
+declare const MAX_RETRY_ATTEMPTS = 4;
+/**
+ * Full-jitter backoff: `delay = random(0, min(BASE * 2^attempt, CAP))`. `attempt` is 0-based.
+ * `rng` is injectable so tests are deterministic.
+ */
+declare function backoffDelayMs(attempt: number, rng?: () => number): number;
+/**
+ * 403-excluded-from-recreate (SPEC-00 §3 / §4.3). A 404 `conversationNotFound` recreates the
+ * conversation and resends ONCE; a 403 `accessDenied` is TERMINAL, it never recreates a conversation
+ * and never invalidates the session (the REACT-NATIVE-12 storm). This predicate is the single source
+ * of that rule for the recovery policy: ONLY `conversationNotFound` may trigger a recreate.
+ */
+declare function canRecreateOnNotFound(code: EverfurErrorCode): boolean;
+
+/**
+ * The one normalized error object. Expected domain failures settle as this (inside an EverfurResult or a
+ * terminal frame), never a throw. `wireMessage` is telemetry/logs only and is never surfaced to a user.
+ */
+interface EverfurError {
+    readonly code: EverfurErrorCode;
+    /** Coarse branching axis (auth vs entitlement vs connection ...). Total over the taxonomy. */
+    readonly category: EverfurErrorCategory;
+    /** `isRetryableCode(code)` OR an explicit `retryable:true` from the frame / body. */
+    readonly retryable: boolean;
+    readonly httpStatus?: number;
+    /**
+     * The `X-Request-ID` of the response that produced this failure, when the server sent one. The one
+     * string a partner can quote in a support ticket, and the join key back to the server-side trace.
+     * Absent on failures with no HTTP response (an offline fetch rejection) and on the SSE frames, which
+     * the contract records as carrying no request id at all.
+     */
+    readonly requestId?: string;
+    /** Site-relative documentation path for the wire code, from the contract registry. No host is implied. */
+    readonly docUrl?: string;
+    /** raw wire text; telemetry / logs only, NEVER rendered. NON-ENUMERABLE. */
+    readonly wireMessage?: string;
+    /** Opaque parsed wire payload for debugging (untrusted, unvalidated). NON-ENUMERABLE. */
+    readonly raw?: unknown;
+    /** SAFE localizable copy resolved from `code` via `userFacingError` (never the raw wireMessage). */
+    readonly displayMessage: string;
+}
+/**
+ * The ONLY function the UI may call to render an error. Returns SAFE, code-derived copy; it never returns
+ * the untrusted `wireMessage`. Total over the taxonomy (an unmapped code cannot occur at the type level).
+ */
+declare function userFacingError(code: EverfurErrorCode): string;
+/** Options accepted by `makeEverfurError`. Every field is optional; the code alone is a valid error. */
+interface MakeEverfurErrorOptions {
+    /** Forces the retry affordance. Omit to derive it from the code (`isRetryableCode`). */
+    readonly retryable?: boolean;
+    readonly httpStatus?: number;
+    /** `X-Request-ID` from the response, when the server sent one. */
+    readonly requestId?: string | null;
+    /**
+     * The RAW wire code string, used to resolve the contract registry row (and from it, `docUrl`). Pass
+     * the code exactly as the server sent it; a code that is not in the registry simply yields no docUrl.
+     */
+    readonly wireCode?: string | null;
+    /** Untrusted wire text. Carried NON-ENUMERABLY for telemetry; never rendered. */
+    readonly wireMessage?: string | null;
+    /** Opaque parsed wire payload. Carried NON-ENUMERABLY for debugging; never rendered. */
+    readonly raw?: unknown;
+}
+/**
+ * Build a normalized, frozen `EverfurError` from a normalized code plus optional wire/HTTP context.
+ *
+ * `displayMessage` is always the SAFE code-derived string. `retryable` defaults to the code's policy
+ * (`isRetryableCode`) unless the caller overrides it, e.g. a frame carrying explicit `retryable:true`.
+ * `requestId` and `docUrl` are the two support-facing additions: the id a partner quotes, and the
+ * site-relative registry path for the wire code. `wireMessage` and `raw` are carried NON-ENUMERABLY and
+ * are dropped when empty.
+ */
+declare function makeEverfurError(code: EverfurErrorCode, opts?: MakeEverfurErrorOptions): EverfurError;
+
+/**
+ * The settle type. An async public operation returns this instead of throwing for an EXPECTED failure.
+ * A successful result may carry a non-fatal `warning` (e.g. served-stale, degraded path).
+ */
+type EverfurResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly warning?: EverfurError;
+} | {
+    readonly ok: false;
+    readonly error: EverfurError;
+};
+/** Construct a success result. Frozen, public state is immutable end to end. */
+declare function ok<T>(value: T, warning?: EverfurError): EverfurResult<T>;
+/** Construct a failure result. Frozen. */
+declare function err<T = never>(error: EverfurError): EverfurResult<T>;
+/** Narrowing guard: true iff the result is a success. */
+declare function isOk<T>(r: EverfurResult<T>): r is {
+    readonly ok: true;
+    readonly value: T;
+    readonly warning?: EverfurError;
+};
+/** Narrowing guard: true iff the result is a failure. */
+declare function isErr<T>(r: EverfurResult<T>): r is {
+    readonly ok: false;
+    readonly error: EverfurError;
+};
+/**
+ * The real `Error` subclass `unwrap` throws, so an imperative call site that lets the throw escape
+ * produces a proper Error rather than a bare object (which a crash reporter files as
+ * "Non-Error exception captured", with no stack and no grouping).
+ *
+ * `message` is built from the normalized `code` and the frozen, product-owned `displayMessage` ONLY.
+ * The untrusted `wireMessage` is deliberately NOT in it: `message` is the one field every telemetry
+ * vendor captures and indexes by default, so putting wire text there would make an untrusted,
+ * healthcare-adjacent string flow automatically into a partner's third-party tooling. The full
+ * `EverfurError` hangs off `.error`, where `wireMessage` and `raw` remain non-enumerable.
+ */
+declare class EverfurThrownError extends Error {
+    /** The settled error this was thrown from. Its `wireMessage` / `raw` stay non-enumerable. */
+    readonly error: EverfurError;
+    /** Mirror of `error.code`, so a catch block can branch without reaching through `.error`. */
+    readonly code: EverfurError['code'];
+    /** Mirror of `error.category`, the coarse branching axis. */
+    readonly category: EverfurError['category'];
+    constructor(error: EverfurError);
+}
+/**
+ * Escape hatch for imperative callers: return the value or throw. The throw is an `EverfurThrownError`
+ * (a real `Error`, safe message); the settled `EverfurError` is on its `.error`.
+ * Prefer pattern-matching on `ok`; `unwrap` exists for call sites that want the throw.
+ */
+declare function unwrap<T>(r: EverfurResult<T>): T;
+/**
+ * Thrown SYNCHRONOUSLY for programmer error ONLY, never for a network or domain failure.
+ * Mirrors Flutter `_requireInitialized` (a real guard, not an assert).
+ *
+ *  - `not-initialized`    , a capability used before EverfurProvider mounted / init ran.
+ *  - `invalid-argument`   , a malformed id or option shape (e.g. a non-UUID conversation id).
+ *  - `missing-peer-dependency`, a capability subpath used without its required native peer dep.
+ */
+declare class EverfurConfigError extends Error {
+    readonly kind: 'not-initialized' | 'invalid-argument' | 'missing-peer-dependency';
+    constructor(kind: 'not-initialized' | 'invalid-argument' | 'missing-peer-dependency', message: string);
+}
+
+export { AUTO_RETRYABLE_CODES as A, BACKOFF_BASE_MS as B, type EverfurResult as E, MAX_RETRY_ATTEMPTS as M, RETRYABLE_CONTRACT_CODES as R, type EverfurErrorCode as a, BACKOFF_CAP_MS as b, EVERFUR_ERROR_CATEGORIES as c, EVERFUR_ERROR_CODES as d, EverfurConfigError as e, type EverfurError as f, type EverfurErrorCategory as g, EverfurThrownError as h, type MakeEverfurErrorOptions as i, backoffDelayMs as j, canRecreateOnNotFound as k, categoryFor as l, err as m, fromHttpStatus as n, fromWire as o, isAutoRetryable as p, isErr as q, isOk as r, isRetryableCode as s, makeEverfurError as t, ok as u, shouldRetry as v, unwrap as w, userFacingError as x };

package/dist/FilePort-BabWrv7I.d.cts

@@ -0,0 +1,22 @@
+/** Opaque handle to a local file to upload. Server-owned upload target is defined by records/video specs. */
+interface FileHandle {
+    /** Local file URI. */
+    readonly uri: string;
+    readonly mimeType: string;
+    readonly sizeBytes?: number;
+    /** Original file name, when the host has one. */
+    readonly name?: string;
+}
+/**
+ * Presigned PUT upload. `idempotencyKey` is reused on every retry (a re-uploaded identical file dedupes
+ * server-side). `signal` cancels an in-flight upload. Settles at the controller; this port itself may reject,
+ * which the controller normalizes to a typed EverfurError.
+ */
+interface FilePort {
+    presignedPut(file: FileHandle, opts: {
+        readonly idempotencyKey: string;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+export type { FileHandle as F, FilePort as a };

package/dist/FilePort-BabWrv7I.d.ts

@@ -0,0 +1,22 @@
+/** Opaque handle to a local file to upload. Server-owned upload target is defined by records/video specs. */
+interface FileHandle {
+    /** Local file URI. */
+    readonly uri: string;
+    readonly mimeType: string;
+    readonly sizeBytes?: number;
+    /** Original file name, when the host has one. */
+    readonly name?: string;
+}
+/**
+ * Presigned PUT upload. `idempotencyKey` is reused on every retry (a re-uploaded identical file dedupes
+ * server-side). `signal` cancels an in-flight upload. Settles at the controller; this port itself may reject,
+ * which the controller normalizes to a typed EverfurError.
+ */
+interface FilePort {
+    presignedPut(file: FileHandle, opts: {
+        readonly idempotencyKey: string;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+export type { FileHandle as F, FilePort as a };

package/dist/PhotoController-BItt5M7u.d.cts

@@ -0,0 +1,43 @@
+import { J as JobId } from './ids-CJ1S6adf.cjs';
+import { I as Interpretation } from './projection-CeIUsbSk.cjs';
+
+/** Deterministic + semantic precheck reason codes (ground truth `everfur_common/schemas/analysis.py`). */
+type PrecheckReasonCode = 'blurry' | 'too_dark' | 'too_bright' | 'too_far' | 'too_close' | 'bad_framing' | 'low_quality' | 'wrong_modality' | 'wrong_species' | 'not_an_animal' | string;
+
+/** v1 server models are skin + eye only; ear/teeth resolve to OffState('version') until their models ship. */
+type PhotoRegion = 'skin' | 'eye';
+type RiskTier = 'low_risk' | 'concern' | 'uncertain';
+type ConfidenceTier = 'possible' | 'probable';
+/** Projector-safe only (§7). Mirrors the 14-key allowlist; NO operator internals. */
+interface PhotoAnalysisResult {
+    readonly jobId: JobId | null;
+    readonly analysisType: PhotoRegion;
+    readonly primaryLabel: string;
+    readonly riskTier: RiskTier | null;
+    readonly confidence: number | null;
+    /** Consumer-friendly; render VERBATIM (never subtype_label). */
+    readonly subtypeDisplay: string | null;
+    /** BE-owned hedge; render verbatim. */
+    readonly confidenceTier: ConfidenceTier | null;
+    readonly diseaseName: string | null;
+    /** Self-contained sentence; the FE owns the hedge prefix. */
+    readonly diseaseFraming: string | null;
+    readonly copyShort: string | null;
+    readonly interpretation: Interpretation | null;
+    readonly modelVersion: string | null;
+}
+/** The honest, non-error outcomes of the species/quality gates (§6, §9). NOT an EverfurError. */
+type PhotoGateOutcome = {
+    readonly kind: 'accepted';
+} | {
+    readonly kind: 'pet_context_required';
+} | {
+    readonly kind: 'species_unsupported';
+    readonly species: 'cat';
+} | {
+    readonly kind: 'retake';
+    readonly reasons: readonly PrecheckReasonCode[];
+};
+type PhotoStatus = 'idle' | 'capturing' | 'analyzing' | 'complete' | 'error';
+
+export type { ConfidenceTier as C, PhotoStatus as P, RiskTier as R, PhotoRegion as a, PhotoAnalysisResult as b, PhotoGateOutcome as c, PrecheckReasonCode as d };

package/dist/PhotoController-D8zMTdcW.d.ts

@@ -0,0 +1,43 @@
+import { J as JobId } from './ids-CJ1S6adf.js';
+import { I as Interpretation } from './projection-CeIUsbSk.js';
+
+/** Deterministic + semantic precheck reason codes (ground truth `everfur_common/schemas/analysis.py`). */
+type PrecheckReasonCode = 'blurry' | 'too_dark' | 'too_bright' | 'too_far' | 'too_close' | 'bad_framing' | 'low_quality' | 'wrong_modality' | 'wrong_species' | 'not_an_animal' | string;
+
+/** v1 server models are skin + eye only; ear/teeth resolve to OffState('version') until their models ship. */
+type PhotoRegion = 'skin' | 'eye';
+type RiskTier = 'low_risk' | 'concern' | 'uncertain';
+type ConfidenceTier = 'possible' | 'probable';
+/** Projector-safe only (§7). Mirrors the 14-key allowlist; NO operator internals. */
+interface PhotoAnalysisResult {
+    readonly jobId: JobId | null;
+    readonly analysisType: PhotoRegion;
+    readonly primaryLabel: string;
+    readonly riskTier: RiskTier | null;
+    readonly confidence: number | null;
+    /** Consumer-friendly; render VERBATIM (never subtype_label). */
+    readonly subtypeDisplay: string | null;
+    /** BE-owned hedge; render verbatim. */
+    readonly confidenceTier: ConfidenceTier | null;
+    readonly diseaseName: string | null;
+    /** Self-contained sentence; the FE owns the hedge prefix. */
+    readonly diseaseFraming: string | null;
+    readonly copyShort: string | null;
+    readonly interpretation: Interpretation | null;
+    readonly modelVersion: string | null;
+}
+/** The honest, non-error outcomes of the species/quality gates (§6, §9). NOT an EverfurError. */
+type PhotoGateOutcome = {
+    readonly kind: 'accepted';
+} | {
+    readonly kind: 'pet_context_required';
+} | {
+    readonly kind: 'species_unsupported';
+    readonly species: 'cat';
+} | {
+    readonly kind: 'retake';
+    readonly reasons: readonly PrecheckReasonCode[];
+};
+type PhotoStatus = 'idle' | 'capturing' | 'analyzing' | 'complete' | 'error';
+
+export type { ConfidenceTier as C, PhotoStatus as P, RiskTier as R, PhotoRegion as a, PhotoAnalysisResult as b, PhotoGateOutcome as c, PrecheckReasonCode as d };

package/dist/TelemetryPort-BDNr00hu.d.cts

@@ -0,0 +1,12 @@
+/**
+ * Analytics sink. `track` records an event; `trackExpectedFailure` records a handled, product-expected
+ * failure (a settled `EverfurError`, never a crash) so expected failures stay off the crash channel.
+ */
+interface TelemetryPort {
+    track(event: string, props?: Record<string, unknown>): void;
+    trackExpectedFailure(code: string, props?: Record<string, unknown>): void;
+}
+/** The safe default: a telemetry port that discards everything. Used when the host injects none. */
+declare const noopTelemetry: TelemetryPort;
+
+export { type TelemetryPort as T, noopTelemetry as n };

package/dist/TelemetryPort-BDNr00hu.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Analytics sink. `track` records an event; `trackExpectedFailure` records a handled, product-expected
+ * failure (a settled `EverfurError`, never a crash) so expected failures stay off the crash channel.
+ */
+interface TelemetryPort {
+    track(event: string, props?: Record<string, unknown>): void;
+    trackExpectedFailure(code: string, props?: Record<string, unknown>): void;
+}
+/** The safe default: a telemetry port that discards everything. Used when the host injects none. */
+declare const noopTelemetry: TelemetryPort;
+
+export { type TelemetryPort as T, noopTelemetry as n };