@everfur/sdk 0.1.0

package/dist/runtime-CBA-LvdM.d.ts

@@ -0,0 +1,349 @@
+import { E as EntitlementDecision, b as CapabilityName } from './resolve-Dq_4_agU.js';
+import { C as ClientBranding, F as FetchEntitlementsArgs, c as EntitlementResolution, w as PetProfileInput, R as RegisteredPet } from './petsRepository-Bu18r2kK.js';
+import { E as EverfurResult } from './EverfurResult-D92-uL82.js';
+import { A as AuthContext, T as TokenProvider } from './identity-DK9zORrG.js';
+import { U as UserRef, P as PetRef, a as ConversationId } from './ids-CJ1S6adf.js';
+import { T as TransportPort, k as EventSourceFactory } from './config-CiJ0PVBB.js';
+import { I as ImageCachePort, K as KvPort } from './cacheEpoch-DknKn3S0.js';
+import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.js';
+import { E as ErrorPolicyPort, C as ChatController } from './ChatController-CKdBvPj2.js';
+import { F as FileHandle } from './FilePort-BabWrv7I.js';
+import { C as CameraPort } from './CameraPort-Cv31Pz7g.js';
+
+/**
+ * Opt-in encrypted secret storage. Backed by a Keychain / Keystore native peer through an rn-layer adapter.
+ * Absent by default; the SDK never persists a credential unless the host supplies this port.
+ */
+interface SecureStorePort {
+    readonly isAvailable: boolean;
+    getSecret(key: string): Promise<string | null>;
+    setSecret(key: string, value: string): Promise<void>;
+    deleteSecret(key: string): Promise<void>;
+}
+/**
+ * The safe default: NO persistence. `currentToken()` lives only in IdentityProvider memory (cleared on
+ * setUser / clear). Attempting to persist without an explicit port fails loud so a partner opts in on
+ * purpose rather than silently leaking a token to disk.
+ */
+declare const NULL_SECURE_STORE: SecureStorePort;
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * One structured, correlated log record. `context` is key-allowlisted and value-scrubbed by createLogPort
+ * BEFORE it reaches any sink; the raw untrusted `wireMessage` never flows into a rendered node.
+ */
+interface LogRecord {
+    readonly level: LogLevel;
+    /** Stable machine id, e.g. 'chat.stream.error' | 'transport.retry'. */
+    readonly event: string;
+    /** One id per request; also sent as X-Everfur-Correlation-Id in debug mode. */
+    readonly correlationId?: string;
+    readonly code?: string;
+    readonly httpStatus?: number;
+    readonly attempt?: number;
+    readonly latencyMs?: number;
+    /** Key-allowlisted + value-scrubbed before ANY sink. */
+    readonly context?: Record<string, unknown>;
+}
+/** The sink partners inject. It only ever receives already-redacted records. */
+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
+ * layer validates only its own subset; the ports below are consumed here in the core runtime. The rn
+ * facade declares a structurally identical `EverfurConfig`, which is assignable to this type.
+ */
+interface EverfurRuntimeConfig {
+    readonly publishableKey: string;
+    readonly apiBaseUrl?: string;
+    readonly contractVersion?: string;
+    /** Non-secret durable KV; a token is NEVER written through it. In-memory fallback when absent. */
+    readonly storage?: KvPort;
+    /** Opt-in encrypted storage, the ONLY port a token may cross to disk. Omit for memory-only tokens. */
+    readonly secureStore?: SecureStorePort;
+    /** Analytics sink; the SDK never imports PostHog / Sentry. No-op default. */
+    readonly telemetry?: TelemetryPort;
+    /** Receives ALREADY-redacted structured log records. */
+    readonly logSink?: LogSink;
+    /** Recovery decisions the host can override; a default policy is applied when absent. */
+    readonly errorPolicy?: ErrorPolicyPort;
+    /** Test seam; production builds the real transport from apiBaseUrl. */
+    readonly transport?: TransportPort;
+    /**
+     * Native capture seam for video / photo (an rn adapter over the camera peer). Absent =>
+     * `unavailableCamera`, so those surfaces render the deliberate capture-unavailable state, never a crash.
+     */
+    readonly camera?: CameraPort;
+    /**
+     * Native presigned-PUT seam for video / photo uploads. Absent => `unavailableUpload` (rejects), so a
+     * submit settles to a handled `mediaUploadFailed` rather than silently succeeding.
+     */
+    readonly upload?: UploadPort;
+    /**
+     * Native S3-multipart seam for records document upload. Absent => an unavailable transport (rejects), so
+     * records READS still work and only the upload action settles to a handled failure.
+     */
+    readonly uploadTransport?: UploadTransport;
+    /**
+     * Platform image-cache seam for the animations fleet-wide epoch purge (rn: expo-image clear*). Absent =>
+     * a no-op cache (the cosmetic purge never fires); every other animations path is unaffected.
+     */
+    readonly imageCache?: ImageCachePort;
+    /** Structured, redacted LogPort events when true. */
+    readonly debug?: boolean;
+}
+/** Identity handed to the runtime: the partner's opaque user id + a lazy token minter (SPEC-00 §4.3). */
+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>>;
+interface CreateEverfurRuntimeInput {
+    readonly config: EverfurRuntimeConfig;
+    /** null => general (anonymous) mode: pk alone on the wire. */
+    readonly user: RuntimeUser | null;
+    readonly activePet: PetRef | null;
+    readonly theme: RuntimeTheme | null;
+}
+/** Scope key for a chat controller: two hooks with the same scope share ONE ref-counted controller. */
+interface ChatScope {
+    readonly userRef: UserRef | null;
+    readonly petRef: PetRef | null;
+    readonly conversationId: ConversationId | null;
+}
+/** The four optional (tree-shakeable) capabilities that self-register a controller through the registry. */
+type CapabilityKind = 'records' | 'video' | 'photo' | 'animations';
+/**
+ * The shared services a capability hook builds its controller from: the device AuthContext, the analytics
+ * sink, and the injected native seams. Handing these out (rather than importing every controller here) is what
+ * lets the runtime stay tree-shake-clean while every capability is still genuinely wired.
+ */
+interface CapabilityServices {
+    /** Build a device AuthContext for a scope (personalized bearer XOR anonymous pk). */
+    authFor(userRef: UserRef | null): AuthContext;
+    readonly telemetry: TelemetryPort;
+    readonly errorPolicy: ErrorPolicyPort | undefined;
+    readonly camera: CameraPort;
+    readonly upload: UploadPort;
+    readonly uploadTransport: UploadTransport;
+    readonly imageCache: ImageCachePort;
+    readonly kv: KvPort;
+}
+/**
+ * The ONE ref-counted capability registry (SPEC-10 §7.4). Chat (the spine) is acquired by its typed method;
+ * every optional capability is acquired through the generic `acquire`, keyed by (kind, scopeKey) under the
+ * current epoch, so two hooks with the same scope share ONE controller and the last release disposes it. A
+ * user / pet re-scope bumps the epoch, disposing every open controller so a fresh one is keyed to the new
+ * scope. The controller type is inferred from `create`, so a capability hook binds BY NAME (its kind + its own
+ * factory) with NO cast, while this module never statically names a media capability controller.
+ */
+interface CapabilityRegistry {
+    /** The shared services each capability hook builds its controller from (native seams + auth + telemetry). */
+    readonly services: CapabilityServices;
+    /** Chat is the spine capability; the registry constructs + ref-counts it directly. */
+    acquireChat(scope: ChatScope): ChatController;
+    releaseChat(controller: ChatController): void;
+    /**
+     * 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`.
+     */
+    acquire<C extends object>(kind: CapabilityKind, scopeKey: string, create: () => C, destroy: (controller: C) => void): C;
+    /** Release a controller acquired via `acquire`; the last release disposes it. */
+    release(controller: object): void;
+}
+/** @deprecated Pre-capability alias retained for back-compat; the registry is a full CapabilityRegistry. */
+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. */
+    readonly isPending: boolean;
+    /**
+     * Server-driven theme branding from the SAME entitlements body (orthogonal to decisions). null/absent =>
+     * the compiled Everfur default theme. The rn EverfurThemeProvider reads this off the store snapshot and
+     * feeds it to resolveTheme; the SERVER stays authoritative for capabilities regardless of branding.
+     */
+    readonly branding?: ClientBranding | null;
+}
+/**
+ * Framework-free entitlement store bound by `useCapability` through useSyncExternalStore. `getSnapshot`
+ * returns a STABLE reference until a real change (tearing-safe). `subscribe`/`getSnapshot` are closures,
+ * safe to pass as bare references.
+ */
+interface EntitlementStore {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): EntitlementSnapshot;
+}
+interface EverfurRuntime {
+    readonly registry: CapabilityRegistry;
+    /**
+     * True once `dispose()` has run. Every verb early-returns after that, so a host holding a disposed
+     * runtime silently gets nothing: the entitlement store never advances and every gate renders its
+     * off-state forever. React StrictMode's dev double-mount runs the unmount cleanup once, which makes this
+     * reachable in ordinary development, so the provider checks it and rebuilds rather than republishing a
+     * dead runtime.
+     */
+    readonly isDisposed: boolean;
+    readonly entitlements: EntitlementStore;
+    /** null => logout: drops the cached bearer and re-scopes every open capability. */
+    setUser(user: RuntimeUser | null): void;
+    /**
+     * Full sign-out: setUser(null) (drop the bearer + re-scope every open capability), and ADDITIONALLY sweep
+     * the SDK's genuinely PER-USER non-secret durable KV keys so the next user does not inherit the previous
+     * user's cached state. The per-user set is the explicit allowlist `PER_USER_KV_KEYS`, which is EMPTY today:
+     * no SDK state persisted through KvPort is per-user yet. Device-global keys (manifest last-known-good,
+     * petState cacheEpoch) are deliberately NOT swept. The bearer never enters KV (KvPort privacy invariant),
+     * so this touches only non-secret durable state. Returns a promise so a host can await the sweep before
+     * calling `setUser(nextUser)`.
+     */
+    logout(): Promise<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
+     * 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>>;
+    /**
+     * 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
+     * 403 on any request still settles the controller to its denied state.
+     */
+    updateEntitlements(next: EntitlementSnapshot): void;
+    /** Navigate / mount a prebuilt capability screen (host-routed). No-op at the spine. */
+    open(capability: CapabilityName): void;
+    /**
+     * 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 };