@everfur/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,156 @@
+import { U as UserRef, P as PetRef } from './ids-CJ1S6adf.cjs';
+export { B as Brand, C as ClientId, a as ConversationId, D as DocumentId, J as JobId, R as RecordsRequestId, b as ResponseId, _ as __brand, c as conversationId, p as petRef, k as userRef } from './ids-CJ1S6adf.cjs';
+export { e as EverfurConfigError, f as EverfurError, g as EverfurErrorCategory, a as EverfurErrorCode, E as EverfurResult, h as EverfurThrownError, l as categoryFor, q as isErr, r as isOk, s as isRetryableCode, w as unwrap, x as userFacingError } from './EverfurResult-D92-uL82.cjs';
+import { T as TransportPort } from './config-BSjBdxrZ.cjs';
+export { A as AcceptedFrame, b as AnalysisCompleteFrame, c as AnalysisStartedFrame, f as DeltaFrame, g as DoneFrame, j as ErrorFrame, E as EverfurRequest, p as EverfurRequestBase, F as Frame, s as FrameBase, t as FrameKind, H as HeartbeatFrame, u as HttpMethod, M as MultipartBody, U as UnknownFrame, G as UrgencyLevel } from './config-BSjBdxrZ.cjs';
+export { T as TokenProvider } from './identity-Brl-lDd6.cjs';
+import { b as CapabilityName, C as CapabilityDecision } from './resolve-Dq_4_agU.cjs';
+export { a as CapabilityDisabled, c as DisabledLevel } from './resolve-Dq_4_agU.cjs';
+import { K as KvPort, I as ImageCachePort } from './cacheEpoch-DknKn3S0.cjs';
+import { S as SecureStorePort, m as LogSink, U as UploadPort, q as UploadTransport, j as EverfurRuntime } from './runtime-BgQnA594.cjs';
+export { L as LogLevel, l as LogRecord, r as PresignedPolicy, s as UploadPolicyWire } from './runtime-BgQnA594.cjs';
+import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.cjs';
+import { C as CameraPort } from './CameraPort-Cv31Pz7g.cjs';
+export { a as CaptureOptions, M as MediaSource } from './CameraPort-Cv31Pz7g.cjs';
+export { F as FileHandle, a as FilePort } from './FilePort-BabWrv7I.cjs';
+import { E as ErrorPolicyPort } from './ChatController-CpUMvvZf.cjs';
+export { c as ChatMessage, e as ChatStatus, f as Citation, g as SendOptions } from './ChatController-CpUMvvZf.cjs';
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export { EverfurChat, EverfurChatProps, UseEverfurChatState, useEverfurChat } from './chat/index.cjs';
+import { n as EverfurTheme } from './petsRepository-BEGb97M9.cjs';
+export { d as EverfurColorTokens, e as EverfurFontWeight, f as EverfurLetterSpacingTokens, g as EverfurLineHeightTokens, h as EverfurMotionDurationTokens, i as EverfurMotionTokens, j as EverfurRadiusTokens, k as EverfurSpaceTokens, l as EverfurSpringToken, m as EverfurTextColorTokens, o as EverfurThemeMeta, p as EverfurTypeSizeTokens, q as EverfurTypeTokens, r as EverfurWeightTokens } from './petsRepository-BEGb97M9.cjs';
+import './requestFunnel-DuUH-kAe.cjs';
+
+interface EverfurConfig {
+    /** pk_live_... ; tenant-resolved server-side (the keyless-fallback / anonymous-mode credential). */
+    readonly publishableKey: string;
+    /** REQUIRED via config or the EVERFUR_API_BASE_URL env var; the SDK ships no hardcoded host (INV-ORG-AGNOSTIC). */
+    readonly apiBaseUrl?: string;
+    /** Sent as X-Everfur-Contract; server additive-only. */
+    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 =>
+     * capture-unavailable state, never a crash.
+     */
+    readonly camera?: CameraPort;
+    /** Native presigned-PUT seam for video / photo uploads. Absent => submits settle to a handled failure. */
+    readonly upload?: UploadPort;
+    /** Native S3-multipart seam for records document upload. Absent => records reads work, upload settles to a handled failure. */
+    readonly uploadTransport?: UploadTransport;
+    /** Platform image-cache seam for the animations fleet-wide epoch purge. Absent => the cosmetic purge no-ops. */
+    readonly imageCache?: ImageCachePort;
+    /** Structured, redacted LogPort events when true. */
+    readonly debug?: boolean;
+}
+/** Identity handed to the provider: the partner's opaque user id + a lazy token minter (SPEC-00 §4.3). */
+interface EverfurUser {
+    readonly userRef: UserRef;
+    readonly getToken: () => Promise<string>;
+}
+/** Opaque, permissive theme input; server branding merges ON TOP. Hostile values are sanitized downstream. */
+type EverfurThemeInput = Readonly<Record<string, string | number | boolean>>;
+interface EverfurProviderProps {
+    readonly config: EverfurConfig;
+    /** Omit => general (anonymous) mode: pk alone on the wire. */
+    readonly user?: EverfurUser;
+    /** Optional default pet scope for capability hooks. */
+    readonly activePet?: PetRef;
+    readonly theme?: EverfurThemeInput;
+    readonly children: ReactNode;
+}
+/**
+ * Imperative handle for non-hook callers (parity with the Flutter facade). Obtained via `useEverfur()`.
+ * Each verb re-scopes every open capability in ONE commit through the core runtime (SPEC-10 §3).
+ */
+interface EverfurHandle {
+    /** null => logout: drops the cached bearer and re-scopes every open capability. */
+    setUser(user: EverfurUser | null): void;
+    /** Re-scopes pet-bound controllers in the same commit. */
+    setActivePet(pet: PetRef | null): void;
+    /**
+     * Register (or update) the widget pet profile that records and consent assume exists. Without it, consent
+     * 404s for any pet the partner has not upserted out of band, so records is unreachable. Idempotent.
+     */
+    registerPet: EverfurRuntime['registerPet'];
+    /** Navigate / mount a prebuilt capability screen (host-routed via the runtime). */
+    open(capability: CapabilityName): void;
+    /**
+     * == setUser(null); additionally sweeps the SDK's genuinely per-user durable KV keys (the explicit
+     * PER_USER_KV_KEYS allowlist, EMPTY today; device-global keys are NOT swept). Returns a promise so a host
+     * can `await handle.logout()` before `setUser(nextUser)`.
+     */
+    logout(): Promise<void>;
+}
+/**
+ * Wrap the tree ONCE, high. Mounting constructs the runtime (transport, identity, registry,
+ * entitlement repository, pollers) exactly once and starts fail-closed: a bad manifest/entitlement
+ * fetch falls to the compiled default and children render immediately, never a blank screen.
+ * A config that cannot be resolved yields a DISABLED runtime (children still render, every capability
+ * off at `sdk_config`), never a throw: see `createEverfurRuntime`.
+ */
+declare function EverfurProvider(props: EverfurProviderProps): ReactNode;
+/**
+ * The imperative facade handle for non-hook callers.
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ */
+declare function useEverfur(): EverfurHandle;
+
+/**
+ * Read the resolved verdict for a coarse capability.
+ *
+ * During the first resolve (or while a stale value is being revalidated) the store reports
+ * `isPending`, and this returns `{ enabled:false, isPending:true }` so a gated surface shows a
+ * skeleton, never a flash of enabled UI it must retract. A kill-switch flip propagates through the
+ * store's revision poller and re-renders every subscriber in <2s. Never throws for a resolution
+ * failure (fail-closed: an absent verdict reads as denied).
+ */
+declare function useCapability(name: CapabilityName): CapabilityDecision;
+
+interface CapabilityGateProps {
+    readonly capability: CapabilityName;
+    readonly children: ReactNode;
+    /** Override the default OffState. Receives the resolved decision (carries SAFE `disabled` copy). */
+    readonly renderDisabled?: (decision: CapabilityDecision) => ReactNode;
+    /** Override the default pending skeleton. */
+    readonly renderPending?: () => ReactNode;
+    readonly style?: StyleProp<ViewStyle>;
+}
+declare function CapabilityGate(props: CapabilityGateProps): ReactNode;
+
+/**
+ * Read the resolved Everfur theme. Returns a COMPLETE, legible, deeply-frozen theme in every case - inside a
+ * provider it is the server-resolved theme; outside one it is the compiled Everfur default (never null, never
+ * blank). Read a token as `theme.color.brand`, `theme.space.md`, `theme.type.size.body`, `theme.radius.lg`.
+ */
+declare function useEverfurTheme(): EverfurTheme;
+
+interface EverfurThemeProviderProps {
+    /**
+     * The clamped client `theme` prop, a first-paint/offline fallback merged UNDER the server branding. Any
+     * shape is tolerated (parsed defensively); unknown keys are ignored. Omit for the compiled default.
+     */
+    readonly clientTheme?: EverfurThemeInput | null;
+    readonly children: ReactNode;
+}
+/**
+ * Compute + publish the resolved theme. Reads server branding off the runtime entitlement store (the same
+ * useSyncExternalStore path `useCapability` uses), the device color scheme, and reduced-motion, then merges
+ * the clamped client prop UNDER the server via the pure `resolveTheme`. Recomputes only when one of those
+ * inputs changes; a plain re-render reuses the frozen theme.
+ */
+declare function EverfurThemeProvider(props: EverfurThemeProviderProps): ReactNode;
+
+export { CameraPort, CapabilityDecision, CapabilityGate, type CapabilityGateProps, CapabilityName, ErrorPolicyPort, type EverfurConfig, type EverfurHandle, EverfurProvider, type EverfurProviderProps, EverfurTheme, type EverfurThemeInput, EverfurThemeProvider, type EverfurThemeProviderProps, type EverfurUser, ImageCachePort, KvPort, LogSink, PetRef, SecureStorePort, TelemetryPort, TransportPort, UploadPort, UploadTransport, UserRef, useCapability, useEverfur, useEverfurTheme };

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import { U as UserRef, P as PetRef } from './ids-CJ1S6adf.js';
+export { B as Brand, C as ClientId, a as ConversationId, D as DocumentId, J as JobId, R as RecordsRequestId, b as ResponseId, _ as __brand, c as conversationId, p as petRef, k as userRef } from './ids-CJ1S6adf.js';
+export { e as EverfurConfigError, f as EverfurError, g as EverfurErrorCategory, a as EverfurErrorCode, E as EverfurResult, h as EverfurThrownError, l as categoryFor, q as isErr, r as isOk, s as isRetryableCode, w as unwrap, x as userFacingError } from './EverfurResult-D92-uL82.js';
+import { T as TransportPort } from './config-CiJ0PVBB.js';
+export { A as AcceptedFrame, b as AnalysisCompleteFrame, c as AnalysisStartedFrame, f as DeltaFrame, g as DoneFrame, j as ErrorFrame, E as EverfurRequest, p as EverfurRequestBase, F as Frame, s as FrameBase, t as FrameKind, H as HeartbeatFrame, u as HttpMethod, M as MultipartBody, U as UnknownFrame, G as UrgencyLevel } from './config-CiJ0PVBB.js';
+export { T as TokenProvider } from './identity-DK9zORrG.js';
+import { b as CapabilityName, C as CapabilityDecision } from './resolve-Dq_4_agU.js';
+export { a as CapabilityDisabled, c as DisabledLevel } from './resolve-Dq_4_agU.js';
+import { K as KvPort, I as ImageCachePort } from './cacheEpoch-DknKn3S0.js';
+import { S as SecureStorePort, m as LogSink, U as UploadPort, q as UploadTransport, j as EverfurRuntime } from './runtime-CBA-LvdM.js';
+export { L as LogLevel, l as LogRecord, r as PresignedPolicy, s as UploadPolicyWire } from './runtime-CBA-LvdM.js';
+import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.js';
+import { C as CameraPort } from './CameraPort-Cv31Pz7g.js';
+export { a as CaptureOptions, M as MediaSource } from './CameraPort-Cv31Pz7g.js';
+export { F as FileHandle, a as FilePort } from './FilePort-BabWrv7I.js';
+import { E as ErrorPolicyPort } from './ChatController-CKdBvPj2.js';
+export { c as ChatMessage, e as ChatStatus, f as Citation, g as SendOptions } from './ChatController-CKdBvPj2.js';
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export { EverfurChat, EverfurChatProps, UseEverfurChatState, useEverfurChat } from './chat/index.js';
+import { n as EverfurTheme } from './petsRepository-Bu18r2kK.js';
+export { d as EverfurColorTokens, e as EverfurFontWeight, f as EverfurLetterSpacingTokens, g as EverfurLineHeightTokens, h as EverfurMotionDurationTokens, i as EverfurMotionTokens, j as EverfurRadiusTokens, k as EverfurSpaceTokens, l as EverfurSpringToken, m as EverfurTextColorTokens, o as EverfurThemeMeta, p as EverfurTypeSizeTokens, q as EverfurTypeTokens, r as EverfurWeightTokens } from './petsRepository-Bu18r2kK.js';
+import './requestFunnel-dio5OmR9.js';
+
+interface EverfurConfig {
+    /** pk_live_... ; tenant-resolved server-side (the keyless-fallback / anonymous-mode credential). */
+    readonly publishableKey: string;
+    /** REQUIRED via config or the EVERFUR_API_BASE_URL env var; the SDK ships no hardcoded host (INV-ORG-AGNOSTIC). */
+    readonly apiBaseUrl?: string;
+    /** Sent as X-Everfur-Contract; server additive-only. */
+    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 =>
+     * capture-unavailable state, never a crash.
+     */
+    readonly camera?: CameraPort;
+    /** Native presigned-PUT seam for video / photo uploads. Absent => submits settle to a handled failure. */
+    readonly upload?: UploadPort;
+    /** Native S3-multipart seam for records document upload. Absent => records reads work, upload settles to a handled failure. */
+    readonly uploadTransport?: UploadTransport;
+    /** Platform image-cache seam for the animations fleet-wide epoch purge. Absent => the cosmetic purge no-ops. */
+    readonly imageCache?: ImageCachePort;
+    /** Structured, redacted LogPort events when true. */
+    readonly debug?: boolean;
+}
+/** Identity handed to the provider: the partner's opaque user id + a lazy token minter (SPEC-00 §4.3). */
+interface EverfurUser {
+    readonly userRef: UserRef;
+    readonly getToken: () => Promise<string>;
+}
+/** Opaque, permissive theme input; server branding merges ON TOP. Hostile values are sanitized downstream. */
+type EverfurThemeInput = Readonly<Record<string, string | number | boolean>>;
+interface EverfurProviderProps {
+    readonly config: EverfurConfig;
+    /** Omit => general (anonymous) mode: pk alone on the wire. */
+    readonly user?: EverfurUser;
+    /** Optional default pet scope for capability hooks. */
+    readonly activePet?: PetRef;
+    readonly theme?: EverfurThemeInput;
+    readonly children: ReactNode;
+}
+/**
+ * Imperative handle for non-hook callers (parity with the Flutter facade). Obtained via `useEverfur()`.
+ * Each verb re-scopes every open capability in ONE commit through the core runtime (SPEC-10 §3).
+ */
+interface EverfurHandle {
+    /** null => logout: drops the cached bearer and re-scopes every open capability. */
+    setUser(user: EverfurUser | null): void;
+    /** Re-scopes pet-bound controllers in the same commit. */
+    setActivePet(pet: PetRef | null): void;
+    /**
+     * Register (or update) the widget pet profile that records and consent assume exists. Without it, consent
+     * 404s for any pet the partner has not upserted out of band, so records is unreachable. Idempotent.
+     */
+    registerPet: EverfurRuntime['registerPet'];
+    /** Navigate / mount a prebuilt capability screen (host-routed via the runtime). */
+    open(capability: CapabilityName): void;
+    /**
+     * == setUser(null); additionally sweeps the SDK's genuinely per-user durable KV keys (the explicit
+     * PER_USER_KV_KEYS allowlist, EMPTY today; device-global keys are NOT swept). Returns a promise so a host
+     * can `await handle.logout()` before `setUser(nextUser)`.
+     */
+    logout(): Promise<void>;
+}
+/**
+ * Wrap the tree ONCE, high. Mounting constructs the runtime (transport, identity, registry,
+ * entitlement repository, pollers) exactly once and starts fail-closed: a bad manifest/entitlement
+ * fetch falls to the compiled default and children render immediately, never a blank screen.
+ * A config that cannot be resolved yields a DISABLED runtime (children still render, every capability
+ * off at `sdk_config`), never a throw: see `createEverfurRuntime`.
+ */
+declare function EverfurProvider(props: EverfurProviderProps): ReactNode;
+/**
+ * The imperative facade handle for non-hook callers.
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ */
+declare function useEverfur(): EverfurHandle;
+
+/**
+ * Read the resolved verdict for a coarse capability.
+ *
+ * During the first resolve (or while a stale value is being revalidated) the store reports
+ * `isPending`, and this returns `{ enabled:false, isPending:true }` so a gated surface shows a
+ * skeleton, never a flash of enabled UI it must retract. A kill-switch flip propagates through the
+ * store's revision poller and re-renders every subscriber in <2s. Never throws for a resolution
+ * failure (fail-closed: an absent verdict reads as denied).
+ */
+declare function useCapability(name: CapabilityName): CapabilityDecision;
+
+interface CapabilityGateProps {
+    readonly capability: CapabilityName;
+    readonly children: ReactNode;
+    /** Override the default OffState. Receives the resolved decision (carries SAFE `disabled` copy). */
+    readonly renderDisabled?: (decision: CapabilityDecision) => ReactNode;
+    /** Override the default pending skeleton. */
+    readonly renderPending?: () => ReactNode;
+    readonly style?: StyleProp<ViewStyle>;
+}
+declare function CapabilityGate(props: CapabilityGateProps): ReactNode;
+
+/**
+ * Read the resolved Everfur theme. Returns a COMPLETE, legible, deeply-frozen theme in every case - inside a
+ * provider it is the server-resolved theme; outside one it is the compiled Everfur default (never null, never
+ * blank). Read a token as `theme.color.brand`, `theme.space.md`, `theme.type.size.body`, `theme.radius.lg`.
+ */
+declare function useEverfurTheme(): EverfurTheme;
+
+interface EverfurThemeProviderProps {
+    /**
+     * The clamped client `theme` prop, a first-paint/offline fallback merged UNDER the server branding. Any
+     * shape is tolerated (parsed defensively); unknown keys are ignored. Omit for the compiled default.
+     */
+    readonly clientTheme?: EverfurThemeInput | null;
+    readonly children: ReactNode;
+}
+/**
+ * Compute + publish the resolved theme. Reads server branding off the runtime entitlement store (the same
+ * useSyncExternalStore path `useCapability` uses), the device color scheme, and reduced-motion, then merges
+ * the clamped client prop UNDER the server via the pure `resolveTheme`. Recomputes only when one of those
+ * inputs changes; a plain re-render reuses the frozen theme.
+ */
+declare function EverfurThemeProvider(props: EverfurThemeProviderProps): ReactNode;
+
+export { CameraPort, CapabilityDecision, CapabilityGate, type CapabilityGateProps, CapabilityName, ErrorPolicyPort, type EverfurConfig, type EverfurHandle, EverfurProvider, type EverfurProviderProps, EverfurTheme, type EverfurThemeInput, EverfurThemeProvider, type EverfurThemeProviderProps, type EverfurUser, ImageCachePort, KvPort, LogSink, PetRef, SecureStorePort, TelemetryPort, TransportPort, UploadPort, UploadTransport, UserRef, useCapability, useEverfur, useEverfurTheme };