@everfur/sdk 0.1.1 → 0.4.0

package/dist/requestFunnel-BjDpqqvm.d.cts

@@ -0,0 +1,110 @@
+import { c as EverfurResult, b as EverfurErrorCode } from './EverfurResult-DN9pL2Ab.cjs';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CNf4uQZP.cjs';
+import { d as EverfurRequest, F as Frame } from './config--Wu1Umhd.cjs';
+import { A as AuthContext } from './identity-C2-08BZW.cjs';
+
+/** Why the funnel stopped, or kept going. Every settle and every retry names one. */
+type FunnelRetryReason = 'ok' | 'aborted' | 'terminal-code' | 'attempts-exhausted' | 'daily-quota-exhausted' | 'burst-throttle' | 'retryable-code' | 'server-reset-beyond-budget';
+/**
+ * One funnel observation. Codes, statuses and ids ONLY: `wireMessage` is untrusted, healthcare-adjacent
+ * free text and must never leave the SDK through a telemetry sink, so it is structurally absent here.
+ */
+interface FunnelEvent {
+    /** Stable call-site name, e.g. `records.createRequest`. */
+    readonly call: string;
+    readonly phase: 'attempt' | 'retry' | 'settled' | 'stream.open';
+    readonly method: string;
+    readonly path: string;
+    /** 0-based attempt index. */
+    readonly attempt: number;
+    readonly ok?: boolean;
+    readonly code?: EverfurErrorCode;
+    readonly httpStatus?: number;
+    /** `X-Request-ID` of the failing response, when the server sent one. The support-ticket join key. */
+    readonly requestId?: string;
+    /** The client-minted key, when this request carried one. Never a caller-supplied value. */
+    readonly idempotencyKey?: string;
+    readonly reason?: FunnelRetryReason;
+    readonly delayMs?: number;
+}
+interface FunnelObserver {
+    onEvent(event: FunnelEvent): void;
+}
+/** The timer seam, mirroring the shape core already uses, so a test drives the deadline deterministically. */
+interface FunnelTimers {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+interface RequestFunnelDeps {
+    readonly auth: AuthContext;
+    readonly observer?: FunnelObserver;
+    readonly timers?: FunnelTimers;
+    /** Injected for deterministic jitter in tests. */
+    readonly rng?: () => number;
+    /** Injected so a test asserts the backoff schedule without burning wall-clock time. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Total attempts (initial try plus retries) before a retryable failure surfaces. */
+    readonly maxAttempts?: number;
+    /**
+     * The partner's `EverfurConfig.errorPolicy`. Consulted per FAILURE, because both of its knobs are keyed
+     * on the error code, which is not known until one arrives. It can only NARROW what the funnel would do
+     * on its own: see `decideRetry`.
+     */
+    readonly errorPolicy?: ErrorPolicyPort;
+    readonly unaryTimeoutMs?: number;
+    /**
+     * Idempotency-key minter. Injected ONLY for deterministic tests. It is never reachable from partner
+     * code and never fed a caller-supplied value: the whole point is that the SDK owns the key.
+     */
+    readonly newIdempotencyKey?: () => string;
+}
+interface FunnelSendOptions {
+    /**
+     * Force the idempotency decision. Omit to derive it from the method (mutating -> minted). Pass `false`
+     * for a mutating request the server does not dedup and that must not claim to be idempotent.
+     */
+    readonly idempotent?: boolean;
+    /** Per-call attempt ceiling override (a poll loop that owns its own budget passes 1). */
+    readonly maxAttempts?: number;
+    /**
+     * The STABLE IDENTITY of this logical call, seeding the key the funnel mints for it.
+     *
+     * WHY A SEED AND NOT A HEADER. The funnel is the sole authority for `Idempotency-Key` because a caller
+     * that writes the header directly gets the guarantee backwards in both directions (see
+     * `assembleHeaders`). But the funnel only knows where one logical call starts and ends when the call is
+     * ONE `send`. Televet booking is not: the owner composes a draft across several screens, the key is
+     * derived from the held slot so a resubmit after a timeout is the SAME booking, and a screen re-mount
+     * mid-flow must not turn one booking into two. The caller is the only party that can say "this is still
+     * that booking", and it is the only thing it is allowed to say.
+     *
+     * SO THE SPLIT IS: the caller supplies the IDENTITY, the funnel still owns the HEADER. The seed is
+     * namespaced and length-bounded here rather than forwarded verbatim, so a caller cannot smuggle a key
+     * that collides with a minted one, exceed the server's 8..128 bound, or reuse a value from another
+     * surface. Everything `assembleHeaders` strips, it still strips: a caller-supplied header is never
+     * honoured, seed or no seed.
+     *
+     * IGNORED when the call is not idempotent (`idempotent: false` or a GET), because there is no key to
+     * seed. A blank or whitespace-only seed falls back to a minted key rather than sending nothing: an
+     * empty identity is a caller bug, and dropping a REQUIRED header over it would turn it into a 422 the
+     * owner reads as "booking failed".
+     */
+    readonly idempotencyKey?: string;
+}
+interface RequestFunnel {
+    /** The ONE unary path: headers, auth, deadline, retry, idempotency, request-id, telemetry. */
+    send<T>(call: string, req: EverfurRequest, opts?: FunnelSendOptions): Promise<EverfurResult<T>>;
+    /**
+     * Resolve device auth onto a request (bearer XOR publishable key, caller auth headers stripped).
+     * Rejects only when the TokenProvider fails; the caller settles that into its own terminal outcome.
+     */
+    authorize(req: EverfurRequest): Promise<EverfurRequest>;
+    /**
+     * Open an SSE stream. NOT idempotency-wrapped and NOT buffered: frames are yielded as they arrive.
+     * `req` is expected to have been through `authorize`.
+     */
+    stream(call: string, req: EverfurRequest, signal: AbortSignal): AsyncIterable<Frame>;
+}
+declare function createRequestFunnel(deps: RequestFunnelDeps): RequestFunnel;
+
+export { type FunnelSendOptions as F, type RequestFunnel as R, type RequestFunnelDeps as a, createRequestFunnel as c };

package/dist/requestFunnel-DFMGcluw.d.ts

@@ -0,0 +1,110 @@
+import { c as EverfurResult, b as EverfurErrorCode } from './EverfurResult-DN9pL2Ab.js';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CwbfmxzJ.js';
+import { d as EverfurRequest, F as Frame } from './config-C7eb_IMD.js';
+import { A as AuthContext } from './identity-CEi9GRFZ.js';
+
+/** Why the funnel stopped, or kept going. Every settle and every retry names one. */
+type FunnelRetryReason = 'ok' | 'aborted' | 'terminal-code' | 'attempts-exhausted' | 'daily-quota-exhausted' | 'burst-throttle' | 'retryable-code' | 'server-reset-beyond-budget';
+/**
+ * One funnel observation. Codes, statuses and ids ONLY: `wireMessage` is untrusted, healthcare-adjacent
+ * free text and must never leave the SDK through a telemetry sink, so it is structurally absent here.
+ */
+interface FunnelEvent {
+    /** Stable call-site name, e.g. `records.createRequest`. */
+    readonly call: string;
+    readonly phase: 'attempt' | 'retry' | 'settled' | 'stream.open';
+    readonly method: string;
+    readonly path: string;
+    /** 0-based attempt index. */
+    readonly attempt: number;
+    readonly ok?: boolean;
+    readonly code?: EverfurErrorCode;
+    readonly httpStatus?: number;
+    /** `X-Request-ID` of the failing response, when the server sent one. The support-ticket join key. */
+    readonly requestId?: string;
+    /** The client-minted key, when this request carried one. Never a caller-supplied value. */
+    readonly idempotencyKey?: string;
+    readonly reason?: FunnelRetryReason;
+    readonly delayMs?: number;
+}
+interface FunnelObserver {
+    onEvent(event: FunnelEvent): void;
+}
+/** The timer seam, mirroring the shape core already uses, so a test drives the deadline deterministically. */
+interface FunnelTimers {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+interface RequestFunnelDeps {
+    readonly auth: AuthContext;
+    readonly observer?: FunnelObserver;
+    readonly timers?: FunnelTimers;
+    /** Injected for deterministic jitter in tests. */
+    readonly rng?: () => number;
+    /** Injected so a test asserts the backoff schedule without burning wall-clock time. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Total attempts (initial try plus retries) before a retryable failure surfaces. */
+    readonly maxAttempts?: number;
+    /**
+     * The partner's `EverfurConfig.errorPolicy`. Consulted per FAILURE, because both of its knobs are keyed
+     * on the error code, which is not known until one arrives. It can only NARROW what the funnel would do
+     * on its own: see `decideRetry`.
+     */
+    readonly errorPolicy?: ErrorPolicyPort;
+    readonly unaryTimeoutMs?: number;
+    /**
+     * Idempotency-key minter. Injected ONLY for deterministic tests. It is never reachable from partner
+     * code and never fed a caller-supplied value: the whole point is that the SDK owns the key.
+     */
+    readonly newIdempotencyKey?: () => string;
+}
+interface FunnelSendOptions {
+    /**
+     * Force the idempotency decision. Omit to derive it from the method (mutating -> minted). Pass `false`
+     * for a mutating request the server does not dedup and that must not claim to be idempotent.
+     */
+    readonly idempotent?: boolean;
+    /** Per-call attempt ceiling override (a poll loop that owns its own budget passes 1). */
+    readonly maxAttempts?: number;
+    /**
+     * The STABLE IDENTITY of this logical call, seeding the key the funnel mints for it.
+     *
+     * WHY A SEED AND NOT A HEADER. The funnel is the sole authority for `Idempotency-Key` because a caller
+     * that writes the header directly gets the guarantee backwards in both directions (see
+     * `assembleHeaders`). But the funnel only knows where one logical call starts and ends when the call is
+     * ONE `send`. Televet booking is not: the owner composes a draft across several screens, the key is
+     * derived from the held slot so a resubmit after a timeout is the SAME booking, and a screen re-mount
+     * mid-flow must not turn one booking into two. The caller is the only party that can say "this is still
+     * that booking", and it is the only thing it is allowed to say.
+     *
+     * SO THE SPLIT IS: the caller supplies the IDENTITY, the funnel still owns the HEADER. The seed is
+     * namespaced and length-bounded here rather than forwarded verbatim, so a caller cannot smuggle a key
+     * that collides with a minted one, exceed the server's 8..128 bound, or reuse a value from another
+     * surface. Everything `assembleHeaders` strips, it still strips: a caller-supplied header is never
+     * honoured, seed or no seed.
+     *
+     * IGNORED when the call is not idempotent (`idempotent: false` or a GET), because there is no key to
+     * seed. A blank or whitespace-only seed falls back to a minted key rather than sending nothing: an
+     * empty identity is a caller bug, and dropping a REQUIRED header over it would turn it into a 422 the
+     * owner reads as "booking failed".
+     */
+    readonly idempotencyKey?: string;
+}
+interface RequestFunnel {
+    /** The ONE unary path: headers, auth, deadline, retry, idempotency, request-id, telemetry. */
+    send<T>(call: string, req: EverfurRequest, opts?: FunnelSendOptions): Promise<EverfurResult<T>>;
+    /**
+     * Resolve device auth onto a request (bearer XOR publishable key, caller auth headers stripped).
+     * Rejects only when the TokenProvider fails; the caller settles that into its own terminal outcome.
+     */
+    authorize(req: EverfurRequest): Promise<EverfurRequest>;
+    /**
+     * Open an SSE stream. NOT idempotency-wrapped and NOT buffered: frames are yielded as they arrive.
+     * `req` is expected to have been through `authorize`.
+     */
+    stream(call: string, req: EverfurRequest, signal: AbortSignal): AsyncIterable<Frame>;
+}
+declare function createRequestFunnel(deps: RequestFunnelDeps): RequestFunnel;
+
+export { type FunnelSendOptions as F, type RequestFunnel as R, type RequestFunnelDeps as a, createRequestFunnel as c };

package/dist/{resolve-Dq_4_agU.d.ts → resolve-D4Ywz5OS.d.cts}

@@ -2,7 +2,7 @@
  * Every entitlement key the PUBLIC contract declares. Internal packs are absent by construction (the
  * projection redacts them), so this union is exactly what a partner surface may require.
  */
-type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "photo.checkup.execute" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "video.gait.execute";
+type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "partner_events.event.read" | "partner_events.inbound.create" | "pets.health.update" | "pets.profile.delete" | "pets.profile.update" | "photo.checkup.execute" | "records.clinic.create" | "records.record.create" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "televet.visit.create" | "video.gait.execute";
 
 interface LevelGrant {
     /** capability keys this level permits */
@@ -24,7 +24,7 @@ interface ResolvedEntitlements {
  */
 declare function resolveEntitlements(levels: readonly LevelGrant[]): ResolvedEntitlements;
 /** Coarse UI capability ids. NOT valid entitlement keys; bridged to resource keys by `requires`. */
-type CapabilityName = 'chat' | 'records' | 'video' | 'photo' | 'animations';
+type CapabilityName = 'chat' | 'records' | 'recordsClinic' | 'video' | 'photo' | 'animations' | 'televet';
 type DisabledLevel = 'contract' | 'partner_config' | 'user_entitlement' | 'version_floor' | 'kill_switch'
 /**
  * The SDK itself is not configured (no publishableKey, or no resolvable apiBaseUrl), so NOTHING can be
@@ -72,7 +72,13 @@ declare function requires(name: CapabilityName): readonly EverfurCapabilityKey[]
  */
 declare function deniedDecisionsFor(level: DisabledLevel, reason: string): readonly EntitlementDecision[];
 interface DecideOptions {
-    /** true during first resolve or while serving a stale value -> skeleton, never a flash of enabled UI. */
+    /**
+     * The first verdict of the scope is still being fetched. It pends ONLY a capability the decision set leaves
+     * undecided (a required key absent from it): a gate then shows its skeleton rather than the fail-closed
+     * off-state it would have to retract when the verdict lands. A capability every key of which the set already
+     * decides renders that decision at once, granted (chat, on the compiled floor) or denied (every key of a
+     * disabled runtime), so a verdict in flight never adds a loading step to what the floor has settled.
+     */
     readonly isPending?: boolean;
 }
 /**
@@ -83,4 +89,4 @@ interface DecideOptions {
  */
 declare function decideCapability(name: CapabilityName, decisions: readonly EntitlementDecision[], opts?: DecideOptions): CapabilityDecision;
 
-export { type CapabilityDecision as C, type DecideOptions as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDisabled as a, type CapabilityName as b, type DisabledLevel as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };
+export { type CapabilityName as C, type DisabledLevel as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDecision as a, type CapabilityDisabled as b, type DecideOptions as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };

package/dist/{resolve-Dq_4_agU.d.cts → resolve-D4Ywz5OS.d.ts}

@@ -2,7 +2,7 @@
  * Every entitlement key the PUBLIC contract declares. Internal packs are absent by construction (the
  * projection redacts them), so this union is exactly what a partner surface may require.
  */
-type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "photo.checkup.execute" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "video.gait.execute";
+type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "partner_events.event.read" | "partner_events.inbound.create" | "pets.health.update" | "pets.profile.delete" | "pets.profile.update" | "photo.checkup.execute" | "records.clinic.create" | "records.record.create" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "televet.visit.create" | "video.gait.execute";
 
 interface LevelGrant {
     /** capability keys this level permits */
@@ -24,7 +24,7 @@ interface ResolvedEntitlements {
  */
 declare function resolveEntitlements(levels: readonly LevelGrant[]): ResolvedEntitlements;
 /** Coarse UI capability ids. NOT valid entitlement keys; bridged to resource keys by `requires`. */
-type CapabilityName = 'chat' | 'records' | 'video' | 'photo' | 'animations';
+type CapabilityName = 'chat' | 'records' | 'recordsClinic' | 'video' | 'photo' | 'animations' | 'televet';
 type DisabledLevel = 'contract' | 'partner_config' | 'user_entitlement' | 'version_floor' | 'kill_switch'
 /**
  * The SDK itself is not configured (no publishableKey, or no resolvable apiBaseUrl), so NOTHING can be
@@ -72,7 +72,13 @@ declare function requires(name: CapabilityName): readonly EverfurCapabilityKey[]
  */
 declare function deniedDecisionsFor(level: DisabledLevel, reason: string): readonly EntitlementDecision[];
 interface DecideOptions {
-    /** true during first resolve or while serving a stale value -> skeleton, never a flash of enabled UI. */
+    /**
+     * The first verdict of the scope is still being fetched. It pends ONLY a capability the decision set leaves
+     * undecided (a required key absent from it): a gate then shows its skeleton rather than the fail-closed
+     * off-state it would have to retract when the verdict lands. A capability every key of which the set already
+     * decides renders that decision at once, granted (chat, on the compiled floor) or denied (every key of a
+     * disabled runtime), so a verdict in flight never adds a loading step to what the floor has settled.
+     */
     readonly isPending?: boolean;
 }
 /**
@@ -83,4 +89,4 @@ interface DecideOptions {
  */
 declare function decideCapability(name: CapabilityName, decisions: readonly EntitlementDecision[], opts?: DecideOptions): CapabilityDecision;
 
-export { type CapabilityDecision as C, type DecideOptions as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDisabled as a, type CapabilityName as b, type DisabledLevel as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };
+export { type CapabilityName as C, type DisabledLevel as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDecision as a, type CapabilityDisabled as b, type DecideOptions as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };

package/dist/{runtime-Bvr8yqXm.d.cts → runtimeTypes-gZEJu-da.d.cts}

@@ -1,14 +1,16 @@
-import { E as EntitlementDecision, b as CapabilityName } from './resolve-Dq_4_agU.cjs';
-import { C as ClientBranding, F as FetchEntitlementsArgs, c as EntitlementResolution, w as PetProfileInput, R as RegisteredPet } from './petsRepository-BEGb97M9.cjs';
-import { E as EverfurResult } from './EverfurResult-D92-uL82.cjs';
-import { A as AuthContext, T as TokenProvider } from './identity-Brl-lDd6.cjs';
-import { U as UserRef, P as PetRef, a as ConversationId } from './ids-CJ1S6adf.cjs';
-import { T as TransportPort, k as EventSourceFactory } from './config-BSjBdxrZ.cjs';
+import { E as EntitlementDecision, C as CapabilityName } from './resolve-D4Ywz5OS.cjs';
+import { P as PetProfileInput, R as RegisteredPet, a as PetProfilePatch } from './petsRepository-B_gKbAzJ.cjs';
+import { c as EverfurResult } from './EverfurResult-DN9pL2Ab.cjs';
+import { E as EverfurThemeInput, C as ClientBranding } from './branding-CsRdeNwK.cjs';
+import { A as AuthContext, T as TokenProvider } from './identity-C2-08BZW.cjs';
+import { U as UserRef, P as PetRef, C as ConversationId } from './ids-B2GAAifq.cjs';
+import { T as TransportPort } from './config--Wu1Umhd.cjs';
 import { I as ImageCachePort, K as KvPort } from './cacheEpoch-DknKn3S0.cjs';
-import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.cjs';
-import { E as ErrorPolicyPort, C as ChatController } from './ChatController-CpUMvvZf.cjs';
-import { F as FileHandle } from './FilePort-BabWrv7I.cjs';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CNf4uQZP.cjs';
+import { U as UploadPort, l as ChatController } from './ports-BY2ph0_y.cjs';
 import { C as CameraPort } from './CameraPort-Cv31Pz7g.cjs';
+import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.cjs';
+import { U as UploadTransport } from './ports-BN6RHF9W.cjs';
 
 /**
  * Opt-in encrypted secret storage. Backed by a Keychain / Keystore native peer through an rn-layer adapter.
@@ -50,95 +52,6 @@ interface LogSink {
     emit(record: Readonly<LogRecord>): void;
 }
 
-/** Minimum re-poll interval; a server ttl below this is clamped so we never hot-loop the endpoint. */
-declare const MIN_POLL_INTERVAL_SECONDS = 30;
-/** Injectable timer seam so a suite drives the re-poll clock deterministically (default: global timers). */
-type TimerHandle = ReturnType<typeof setTimeout>;
-interface PollScheduler {
-    set(callback: () => void, ms: number): TimerHandle;
-    clear(handle: TimerHandle): void;
-}
-interface EntitlementPollerDeps {
-    /** Re-derived every poll so a token refresh / user re-scope is reflected on the next hop. */
-    readonly authFor: () => AuthContext;
-    /**
-     * Push a fresh verdict into the runtime store. Called ONLY on a 200 'updated'. Carries the server-driven
-     * branding parsed from the SAME body (null when absent/unparseable -> the compiled default theme); branding
-     * is additive and orthogonal to the decisions.
-     */
-    readonly update: (decisions: readonly EntitlementDecision[], branding: ClientBranding | null) => void;
-    /** Optional region hint forwarded to the endpoint. */
-    readonly region?: string;
-    readonly telemetry?: TelemetryPort;
-    /** Test seam; defaults to global timers (unref'd so a live poll never pins a Node event loop). */
-    readonly scheduler?: PollScheduler;
-    /** Test seam; defaults to the real repository call. */
-    readonly resolve?: (auth: AuthContext, args: FetchEntitlementsArgs) => Promise<EntitlementResolution>;
-    /** Floor override for tests; defaults to MIN_POLL_INTERVAL_SECONDS. */
-    readonly floorSeconds?: number;
-    /** Test seam for deterministic failure-retry jitter; defaults to Math.random. */
-    readonly rng?: () => number;
-}
-interface EntitlementPoller {
-    /** Idempotent. Kicks an immediate first poll, then self-schedules on the returned cadence. */
-    start(): void;
-    /** Idempotent. Clears the pending timer and prevents any post-stop update (dispose calls this). */
-    stop(): void;
-    /**
-     * Drop the cached revision and re-poll immediately. A user / pet re-scope invalidates the cached verdict, so
-     * the next request must be UNCONDITIONAL (no If-None-Match) to force a fresh 200 for the new scope.
-     */
-    refresh(): void;
-}
-declare function createEntitlementPoller(deps: EntitlementPollerDeps): EntitlementPoller;
-
-/** The presigned POST/PUT policy returned by `/uploads/initiate` (SPEC-11b §2.1). */
-interface PresignedPolicy {
-    /** Absolute S3 endpoint URL to POST/PUT the bytes at. */
-    readonly url: string;
-    /** POST-policy form fields to include with the upload (empty for a plain PUT). */
-    readonly fields: Readonly<Record<string, string>>;
-    /** The owned-uploads-prefixed key the analyze call then references. */
-    readonly s3Key: string;
-    /** epoch seconds the policy expires; telemetry only. */
-    readonly expiresAt: number | null;
-}
-/**
- * The native upload seam. It PUTs `file` at the presigned `target` (SPEC-11b §2.1). `idempotencyKey` is reused
- * on every retry so a re-uploaded identical file dedupes server-side. A network failure REJECTS; the controller
- * normalizes that to a `mediaUploadFailed` and exposes a retake affordance (never auto-retried, SPEC-00 §3.2).
- *
- * NOTE: the spine `FilePort.presignedPut(file, { idempotencyKey, signal })` has no slot for the presigned
- * target; this richer port is the shape it must grow to. See the manifest gap note.
- */
-interface UploadPort {
-    presignedPut(file: FileHandle, opts: {
-        readonly target: PresignedPolicy;
-        readonly idempotencyKey: string;
-        readonly signal?: AbortSignal;
-    }): Promise<void>;
-}
-
-interface UploadPolicyWire {
-    readonly upload_id: string;
-    readonly upload_url: string;
-    readonly upload_fields: Readonly<Record<string, string>>;
-    readonly expires_in_seconds: number;
-    readonly max_content_length: number;
-}
-/**
- * Platform-specific: the rn adapter binds `expo-file-system` (uploadAsync) behind `optionalModule`; the
- * controller stays platform-neutral and never sees a native module. Resolves on S3's 204; rejects on a
- * policy 403 / stream failure, which the controller normalizes to a typed `mediaUploadFailed` (never a throw
- * that escapes the controller).
- */
-interface UploadTransport {
-    postMultipart(policy: UploadPolicyWire, file: FileHandle, opts: {
-        readonly onProgress?: (fraction: number) => void;
-        readonly signal?: AbortSignal;
-    }): Promise<void>;
-}
-
 /**
  * The public init config the host passes at EverfurProvider mount: the lean client subset
  * (publishableKey / apiBaseUrl / contractVersion / transport / debug) PLUS the host-seam ports. The client
@@ -189,8 +102,8 @@ interface RuntimeUser {
     readonly userRef: UserRef;
     readonly getToken: TokenProvider;
 }
-/** Opaque, permissive theme input; server branding merges ON TOP. Sanitized downstream. */
-type RuntimeTheme = Readonly<Record<string, string | number | boolean>>;
+/** The client `theme` prop as the provider hands it over (tolerant shape; sanitized by the theme provider). */
+type RuntimeTheme = EverfurThemeInput;
 interface CreateEverfurRuntimeInput {
     readonly config: EverfurRuntimeConfig;
     /** null => general (anonymous) mode: pk alone on the wire. */
@@ -221,6 +134,12 @@ interface CapabilityServices {
     readonly uploadTransport: UploadTransport;
     readonly imageCache: ImageCachePort;
     readonly kv: KvPort;
+    /**
+     * The API base URL the transport was built for (the config's, or the environment's), or null with an
+     * injected transport and no base URL. A relative link the server returns (a share link's path) is
+     * resolved against this origin, never opened raw.
+     */
+    readonly apiBaseUrl: string | null;
 }
 /**
  * The ONE ref-counted capability registry (SPEC-10 §7.4). Chat (the spine) is acquired by its typed method;
@@ -236,6 +155,12 @@ interface CapabilityRegistry {
     /** Chat is the spine capability; the registry constructs + ref-counts it directly. */
     acquireChat(scope: ChatScope): ChatController;
     releaseChat(controller: ChatController): void;
+    /**
+     * The live controller for a scope WITHOUT taking a hold, or null. A mount reads it synchronously on its
+     * first render so a scope `prepare()` primed renders its settled snapshot at once (no bootstrapping frame),
+     * then takes its hold through `acquireChat` in the commit effect as before.
+     */
+    peekChat(scope: ChatScope): ChatController | null;
     /**
      * Ref-counted acquire for the tree-shakeable capabilities. Two calls with the same (kind, scopeKey) under
      * the current epoch share ONE controller; the last release disposes it via `destroy`.
@@ -249,7 +174,12 @@ type ChatControllerRegistry = CapabilityRegistry;
 /** The already-resolved server verdict the capability hooks render (never re-folded here). */
 interface EntitlementSnapshot {
     readonly decisions: readonly EntitlementDecision[];
-    /** true during the first resolve or while serving a stale value -> skeleton, never a flash of UI. */
+    /**
+     * The first verdict of the current scope is still being fetched. `decideCapability` pends only what the
+     * decisions leave undecided: a key absent from the compiled floor (records) shows its skeleton, a key the
+     * floor grants (chat) renders at once. false once that fetch settles, whatever it settled to (a failure keeps
+     * the floor: fail-closed, never a skeleton left up), and always on a runtime that never fetched.
+     */
     readonly isPending: boolean;
     /**
      * Server-driven theme branding from the SAME entitlements body (orthogonal to decisions). null/absent =>
@@ -267,6 +197,48 @@ interface EntitlementStore {
     subscribe(listener: () => void): () => void;
     getSnapshot(): EntitlementSnapshot;
 }
+interface PrepareOptions {
+    /**
+     * The pet the first chat mount will be scoped to. Names it and the warm-up ALSO primes that scope's chat
+     * bootstrap (conversation + suggested prompts), held for the first mount. It registers nothing: a pet the
+     * partner has not upserted is registered with `registerPet`, not here.
+     */
+    readonly petRef?: PetRef;
+}
+/**
+ * `ready`: token minted (when a user is set), verdict resolved, chat primed (when a pet was named).
+ * `partial`: the token is ready but the verdict fetch or the chat prime settled to an error; surfaces still
+ * mount and self-heal (the poller re-polls, the first send recreates the conversation).
+ * `failed`: nothing authenticated can proceed: the mint failed, or the runtime is disposed / not configured.
+ */
+type PrepareStatus = 'ready' | 'partial' | 'failed';
+/** The settled warm-up. Each step carries the same `EverfurError` the surfaces settle to; nothing throws. */
+interface PrepareResult {
+    readonly status: PrepareStatus;
+    /** Milliseconds from the `prepare()` call to settlement: the login-to-ready number, also on telemetry. */
+    readonly durationMs: number;
+    /** The session-token mint. `ok` without a user (anonymous mode mints nothing). */
+    readonly session: EverfurResult<void>;
+    /** The entitlement verdict fetch into the store every gate reads. */
+    readonly entitlements: EverfurResult<void>;
+    /** The chat prime for `petRef`; absent when no pet was named. */
+    readonly chat?: EverfurResult<void>;
+}
+/**
+ * What a before-logout hook receives: who is leaving, and an auth context that keeps signing requests for the
+ * length of the hook budget even though the runtime drops the live identity synchronously right after the hooks
+ * start. The bearer is read from the identity's cache at that instant (or minted then, if none was cached), so a
+ * request the hook issues after an `await` still goes out under the signed-out user, never re-minted afterwards.
+ */
+interface BeforeLogoutContext {
+    readonly userRef: UserRef;
+    readonly auth: AuthContext;
+}
+/**
+ * A hook that runs when a signed-in user is about to leave (`logout()`, `setUser(null)`, a switch to another
+ * user). It may return a promise; `logout()` waits for it up to `LOGOUT_HOOK_BUDGET_MS` and never fails on it.
+ */
+type BeforeLogoutHook = (context: BeforeLogoutContext) => unknown;
 interface EverfurRuntime {
     readonly registry: CapabilityRegistry;
     /**
@@ -303,18 +275,39 @@ interface EverfurRuntime {
      * calling `setUser(nextUser)`.
      */
     logout(): Promise<void>;
+    /**
+     * Run `hook` BEFORE a signed-in user leaves: on `logout()`, on `setUser(null)` and on a switch to another user,
+     * with the leaving user's `userRef` and a grace auth that still signs requests. Started synchronously, before
+     * the bearer drops and the capabilities re-scope; `logout()` additionally awaits it, bounded by
+     * `LOGOUT_HOOK_BUDGET_MS`, and a hook that throws, rejects or hangs never fails or delays sign-out beyond that.
+     * The per-user KV sweep runs after the hooks. Returns the unsubscribe. Nothing runs for an anonymous runtime.
+     */
+    onBeforeLogout(hook: BeforeLogoutHook): () => void;
     /** Re-scopes pet-bound controllers in the same commit. */
     setActivePet(pet: PetRef | null): void;
     /**
      * Register (or update) the widget pet profile the records and consent routes assume already exists.
      *
      * All three consent routes resolve `pet_ref` through the server's `_resolve_pet_id`, which 404s when no
-     * widget pet exists — so consent, and therefore records, is UNREACHABLE for any pet the partner has not
+     * widget pet exists, so consent, and therefore records, is UNREACHABLE for any pet the partner has not
      * upserted out of band. `createPetsRepository` exists on the `@everfur/sdk/client` subpath, but that is
      * the advanced-integrator surface and it takes a raw `AuthContext`; a partner using the provider had no
      * way to call it. This is that way. Idempotent: the route is an upsert keyed on `pet_ref`.
      */
     registerPet(pet: PetRef, profile?: PetProfileInput): Promise<EverfurResult<RegisteredPet>>;
+    /**
+     * Change part of a registered pet's profile (`PATCH /widget/v1/pets/{pet_ref}`). An omitted field is unchanged,
+     * `null` clears it. An unknown pet settles to the not-found error.
+     */
+    updatePet(pet: PetRef, patch: PetProfilePatch): Promise<EverfurResult<RegisteredPet>>;
+    /** Delete a pet profile (`DELETE /widget/v1/pets/{pet_ref}`); the server also retires its Records data. */
+    deletePet(pet: PetRef): Promise<EverfurResult<void>>;
+    /**
+     * Permanently erase everything Everfur holds for the current user (`DELETE /widget/v1/me`). A failure is
+     * retryable and a repeat call resumes the erasure. It does not sign the user out: call `logout()` or
+     * `setUser(null)` afterwards so mounted surfaces stop showing the erased data.
+     */
+    eraseUserData(): Promise<EverfurResult<void>>;
     /**
      * Replace the rendered entitlement verdict (a future poller / a manifest refresh). The SERVER stays
      * authoritative: this only feeds the render store, so the pending/enabled paths become reachable while a
@@ -323,40 +316,19 @@ interface EverfurRuntime {
     updateEntitlements(next: EntitlementSnapshot): void;
     /** Navigate / mount a prebuilt capability screen (host-routed). No-op at the spine. */
     open(capability: CapabilityName): void;
+    /**
+     * Warm up during the partner's OWN login so no Everfur surface adds a loading step of its own: mint the
+     * session token, resolve the entitlement verdict into the gate store and, when a pet is named, prime its
+     * chat bootstrap. Concurrent calls coalesce onto one run; a settled `ready` is returned again without I/O
+     * until the identity or pet re-scopes; a `partial` / `failed` run is retried on the next call. Never
+     * throws. Emits `sdk.prepare.timing` (`durationMs`, `status`) on the host telemetry sink once per run.
+     */
+    prepare(opts?: PrepareOptions): Promise<PrepareResult>;
     /**
      * Idempotent teardown: aborts in-flight capability requests, tears down every open SSE stream, and stops
      * the entitlement poller (an in-flight entitlement poll's result is DROPPED, not aborted mid-flight).
      */
     dispose(): void;
 }
-/** Runtime-construction options, distinct from the partner-facing config (host wiring / test seams). */
-interface CreateRuntimeOptions {
-    /**
-     * Whether to start the entitlement poller. Default: start ONLY when the transport was NOT injected (a real,
-     * base-URL runtime). An injected transport is the test seam, so auto-start stays OFF to keep MockTransport
-     * suites network-free; pass `true` to exercise the wired poller against a MockTransport.
-     */
-    readonly startEntitlementPolling?: boolean;
-    /** Test seam: an injected scheduler so a suite can drive the entitlement re-poll timer deterministically. */
-    readonly pollScheduler?: PollScheduler;
-    /**
-     * Host-wiring seam: the EventSource factory the built HTTP transport falls back to when a streaming
-     * `res.body` is unavailable (stock RN fetch). The rn facade injects react-native-sse here so streaming works
-     * on stock React Native; core NEVER imports react-native-sse (it stays framework-free and only threads this
-     * through). Absent (web/expo, or an injected transport) => the fetch-body streaming path is used.
-     */
-    readonly eventSourceFactory?: EventSourceFactory;
-}
-/**
- * Construct the runtime once (EverfurProvider mount). Builds the transport (injected test seam, else the
- * real HTTP transport from the resolved client config), the IdentityProvider when a user is set, the
- * capability registry, the entitlement store, and (for a real runtime) the entitlement poller.
- * A config that cannot be resolved (missing publishableKey, or an unresolvable / non-https base URL when
- * no transport is injected) does NOT throw: it yields a DISABLED runtime whose transport refuses and
- * whose every capability settles to the deliberate off-state at `disabled.level === 'sdk_config'`.
- * @throws {EverfurConfigError} only for a supplied ACTIVE secureStore, which expresses a security
- * intent the SDK cannot yet honour and must not silently discard.
- */
-declare function createEverfurRuntime(input: CreateEverfurRuntimeInput, opts?: CreateRuntimeOptions): EverfurRuntime;
 
-export { type CapabilityKind as C, type EntitlementPoller as E, type LogLevel as L, MIN_POLL_INTERVAL_SECONDS as M, NULL_SECURE_STORE as N, type PollScheduler as P, type RuntimeTheme as R, type SecureStorePort as S, type TimerHandle as T, type UploadPort as U, type CapabilityRegistry as a, type CapabilityServices as b, type ChatControllerRegistry as c, type ChatScope as d, type CreateEverfurRuntimeInput as e, type CreateRuntimeOptions as f, type EntitlementPollerDeps as g, type EntitlementSnapshot as h, type EntitlementStore as i, type EverfurRuntime as j, type EverfurRuntimeConfig as k, type LogRecord as l, type LogSink as m, type RuntimeUser as n, createEntitlementPoller as o, createEverfurRuntime as p, type UploadTransport as q, type PresignedPolicy as r, type UploadPolicyWire as s };
+export { type BeforeLogoutContext as B, type CreateEverfurRuntimeInput as C, type EntitlementSnapshot as E, type LogLevel as L, NULL_SECURE_STORE as N, type PrepareOptions as P, type RuntimeTheme as R, type SecureStorePort as S, type LogRecord as a, type LogSink as b, type PrepareResult as c, type PrepareStatus as d, type EverfurRuntime as e, type BeforeLogoutHook as f, type CapabilityKind as g, type CapabilityRegistry as h, type CapabilityServices as i, type ChatControllerRegistry as j, type ChatScope as k, type EntitlementStore as l, type EverfurRuntimeConfig as m, type RuntimeUser as n };