@everfur/sdk 0.1.0

package/dist/petsRepository-BEGb97M9.d.cts

@@ -0,0 +1,326 @@
+import { f as EverfurError, E as EverfurResult } from './EverfurResult-D92-uL82.cjs';
+import { R as RequestFunnel } from './requestFunnel-DuUH-kAe.cjs';
+import { A as AuthContext } from './identity-Brl-lDd6.cjs';
+import { E as EntitlementDecision } from './resolve-Dq_4_agU.cjs';
+import { P as PetRef } from './ids-CJ1S6adf.cjs';
+
+/** Recursively freeze a plain object/array tree in place and return it (typed as the input). */
+declare function deepFreeze<T>(value: T): T;
+/** Foreground text tokens; the semantic text ramp over surfaces. */
+interface EverfurTextColorTokens {
+    readonly primary: string;
+    readonly secondary: string;
+    readonly muted: string;
+    readonly placeholder: string;
+    /** Text drawn on the brand fill (a compiled default; resolve recomputes onPrimary/onAccent via WCAG). */
+    readonly onBrand: string;
+    readonly metaCool: string;
+}
+/** The Everfur color system: brand + surfaces + text ramp + semantic palette + component washes. */
+interface EverfurColorTokens {
+    readonly brand: string;
+    readonly brandSoft: string;
+    readonly brandSofter: string;
+    readonly brandBorder: string;
+    readonly borderHairlineGreen: string;
+    readonly surface: string;
+    readonly surfaceCream: string;
+    readonly surfaceSubtle: string;
+    readonly background: string;
+    readonly borderRingCream: string;
+    readonly text: EverfurTextColorTokens;
+    /** The primary CTA fill (server-overridable via primary_color). Foreground is `onPrimary`. */
+    readonly primary: string;
+    /** WCAG-legible foreground for `primary` (computed by resolveTheme, never passed through). */
+    readonly onPrimary: string;
+    /** The user/CTA accent fill (server-overridable via accent_color). Foreground is `onAccent`. */
+    readonly accent: string;
+    /** WCAG-legible foreground for `accent` (computed by resolveTheme). */
+    readonly onAccent: string;
+    /** The 0.5px bubble edge (a lightened brand / success green for the default). */
+    readonly accentEdge: string;
+    readonly success: string;
+    readonly danger: string;
+    readonly errorRed: string;
+    readonly warningStrong: string;
+    readonly cautionAccent: string;
+    readonly riskConcern: string;
+    readonly badgeBgPositive: string;
+    readonly badgeBgCaution: string;
+    readonly badgeBgCritical: string;
+    readonly badgeBgNeutral: string;
+    /** user bubble = accent fill; assistant bubble = bare surface (the mobile/Flutter asymmetry). */
+    readonly bubbleUser: string;
+    readonly bubbleAssistant: string;
+    readonly skeleton: string;
+    readonly scanButtonPink: string;
+    readonly checkupCardLowRiskBg: string;
+    readonly checkupCardConcernBg: string;
+}
+/** Spacing scale (dp). */
+interface EverfurSpaceTokens {
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly xxl: number;
+}
+/** Corner-radius scale (dp); `pill` is an effectively-infinite radius. */
+interface EverfurRadiusTokens {
+    readonly tile: number;
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly pill: number;
+}
+interface EverfurTypeSizeTokens {
+    readonly nano: number;
+    readonly small: number;
+    readonly micro: number;
+    readonly tiny: number;
+    readonly caption: number;
+    readonly bodyTight: number;
+    readonly body: number;
+    readonly subtitle: number;
+    readonly heading: number;
+    readonly verdict: number;
+}
+/** Line-height multipliers (applied to a size to derive an absolute lineHeight). */
+interface EverfurLineHeightTokens {
+    readonly tight: number;
+    readonly snug: number;
+    readonly normal: number;
+    readonly relaxed: number;
+}
+/**
+ * RN-assignable font-weight literals. Typed as the exact string literals we ship (not bare `string`) so a
+ * consumer can spread a weight token straight into a `Text` style: React Native's `TextStyle['fontWeight']`
+ * accepts these, but rejects `string`. Kept framework-free (no react-native import) to hold the client layer's
+ * no-framework boundary - these three literals are a subset of RN's fontWeight union.
+ */
+type EverfurFontWeight = '400' | '500' | '700';
+/** RN fontWeight tokens. */
+interface EverfurWeightTokens {
+    readonly regular: EverfurFontWeight;
+    readonly medium: EverfurFontWeight;
+    readonly bold: EverfurFontWeight;
+}
+interface EverfurLetterSpacingTokens {
+    readonly eyebrow: number;
+    readonly monoWide: number;
+    readonly headerBrand: number;
+    readonly tight: number;
+}
+/** Typography tokens. `family`/`mono` default to the platform font; server font_family/font_url may override. */
+interface EverfurTypeTokens {
+    readonly family: string;
+    readonly mono: string;
+    /** Optional remote font (server font_url); null unless a server override supplies an https URL. */
+    readonly fontUrl: string | null;
+    readonly size: EverfurTypeSizeTokens;
+    readonly lineHeight: EverfurLineHeightTokens;
+    readonly weight: EverfurWeightTokens;
+    readonly letterSpacing: EverfurLetterSpacingTokens;
+}
+interface EverfurSpringToken {
+    readonly damping: number;
+    readonly stiffness: number;
+}
+interface EverfurMotionDurationTokens {
+    readonly instant: number;
+    readonly fast: number;
+    readonly normal: number;
+    readonly slow: number;
+}
+/** Motion tokens. Under reduced-motion, resolveTheme collapses durations to 0 and stiffens the spring. */
+interface EverfurMotionTokens {
+    readonly duration: EverfurMotionDurationTokens;
+    readonly spring: {
+        readonly gentle: EverfurSpringToken;
+    };
+    readonly easing: {
+        readonly standard: string;
+    };
+    /** true when the resolved theme has collapsed motion (AccessibilityInfo reduced-motion). */
+    readonly reducedMotion: boolean;
+}
+/** Non-visual identity + partner copy carried on the theme (server display_name/logo_url/placeholder overlay). */
+interface EverfurThemeMeta {
+    readonly displayName: string;
+    readonly logoUrl: string | null;
+    /** Server-overridable composer placeholder (chat_placeholder/placeholder); null keeps Everfur's neutral default. */
+    readonly placeholder: string | null;
+    /** White-label switch (hide_powered_by): drop the "powered by everfur" attribution. Default false (shown). */
+    readonly hidePoweredBy: boolean;
+}
+/**
+ * The frozen, never-null theme the rn layer renders. Read a token as `theme.color.brand`,
+ * `theme.space.md`, `theme.type.size.body`, `theme.radius.lg`, `theme.motion.duration.fast`.
+ */
+interface EverfurTheme {
+    readonly brightness: 'light' | 'dark';
+    readonly meta: EverfurThemeMeta;
+    readonly color: EverfurColorTokens;
+    readonly space: EverfurSpaceTokens;
+    readonly radius: EverfurRadiusTokens;
+    readonly type: EverfurTypeTokens;
+    readonly motion: EverfurMotionTokens;
+}
+/** The compiled LIGHT default (deeply frozen). */
+declare const EVERFUR_LIGHT: EverfurTheme;
+/** The compiled DARK default (deeply frozen). */
+declare const EVERFUR_DARK: EverfurTheme;
+
+interface ClientBranding {
+    readonly displayName: string | null;
+    /** normalized (https-hardened downstream) logo URL */
+    readonly logoUrl: string | null;
+    /** normalized color string (#RRGGBB or rgba(...)) or null */
+    readonly primaryColor: string | null;
+    readonly accentColor: string | null;
+    readonly brightness: 'light' | 'dark' | null;
+    readonly fontFamily: string | null;
+    readonly fontUrl: string | null;
+    /** composer placeholder override (chat_placeholder/placeholder); null keeps the base. */
+    readonly placeholder: string | null;
+    /** white-label switch (hide_powered_by): hide the powered-by attribution. null = unset (keep the base). */
+    readonly hidePoweredBy: boolean | null;
+}
+/** true when every field is null (no config) - treated by callers as "absent". */
+declare function isEmptyBranding(b: ClientBranding): boolean;
+/**
+ * Parse an untrusted branding blob (from the entitlements render_hints, or the client `theme` prop) into a
+ * normalized `ClientBranding`. Accepts BOTH snake_case and camelCase keys. Returns null when the input is not
+ * an object OR when the result is empty (all fields null) - callers read null as "no config" (fail-closed to
+ * the compiled default). Never throws.
+ */
+declare function parseClientBranding(json: unknown): ClientBranding | null;
+/**
+ * Parse a permissive color into a normalized string (`#RRGGBB` when opaque, else `rgba(r,g,b,a)`), or null.
+ * Accepts `#RGB`, `#RRGGBB`, `#AARRGGBB`, `0xAARRGGBB` (string), a 32-bit ARGB `int`, and `rgb()/rgba()`.
+ * An empty string, whitespace, or an unrecognized value yields null.
+ */
+declare function parseColor(value: unknown): string | null;
+/**
+ * Return the more legible of near-black / white for `background` (WCAG 2.x contrast). Ported from Flutter
+ * `_readableOn`. Falls back to white for an unparseable background (never throws).
+ */
+declare function readableOn(background: string): string;
+/**
+ * Return the URL only if it is an https URL with no embedded whitespace, else null (security invariant:
+ * https-only; rejects http:, javascript:, data:, etc.). Uses a protocol-locked regex rather than the URL
+ * constructor so it is portable + total on React Native (whose URL global is incomplete) and never throws.
+ */
+declare function hardenHttpsUrl(url: string | null): string | null;
+/**
+ * Overlay `b` onto `base`, field by field: a non-null branding field WINS; a null field KEEPS the base. A
+ * valid brightness re-selects the matching compiled palette (light/dark); an invalid/absent brightness leaves
+ * the base palette untouched. Returns a NEW deeply-frozen theme; `base` and `b` are never mutated.
+ *
+ * NOTE: foreground legibility (onPrimary/onAccent) and URL hardening are applied by `resolveTheme`, the total
+ * entry point. Call this directly only when you will finalize the result yourself.
+ */
+declare function withServerBranding(base: EverfurTheme, b: ClientBranding | null): EverfurTheme;
+/**
+ * Inputs to the total theme resolve. All optional; `resolveTheme(undefined)` yields the compiled Everfur
+ * default. Merge order (server wins): compiled default <- clientOverride (first-paint/offline fallback) <-
+ * branding (server render_hints).
+ */
+interface ResolveThemeInput {
+    /** Server-driven branding from the live entitlements render_hints (authoritative overlay). */
+    readonly branding?: ClientBranding | null;
+    /** The clamped client `theme` prop - a first-paint/offline fallback merged UNDER the server. */
+    readonly clientOverride?: ClientBranding | null;
+    /** The device color scheme (useColorScheme); selects the base palette when branding sets no brightness. */
+    readonly colorScheme?: 'light' | 'dark' | null;
+    /** AccessibilityInfo reduced-motion: collapses the motion tokens. */
+    readonly reducedMotion?: boolean;
+}
+/**
+ * Resolve the final, legible, deeply-frozen theme. Never throws, never returns null/transparent. Applies the
+ * client fallback UNDER the server overlay, recomputes onPrimary/onAccent via WCAG, hardens logo/font URLs to
+ * https-only, guarantees a non-empty displayName, and collapses motion under reduced-motion.
+ */
+declare function resolveTheme(input?: ResolveThemeInput): EverfurTheme;
+
+/** The conditional-GET endpoint (SPEC-00 §5.3). Relative; the transport prefixes the resolved base URL. */
+declare const ENTITLEMENTS_PATH = "/widget/v1/entitlements";
+/**
+ * The settled outcome of one entitlement fetch. `updated` carries a fresh verdict + the cadence to re-poll on;
+ * `notModified` means the cached verdict still holds; `failed` carries a normalized error and means keep-last.
+ */
+type EntitlementResolution = {
+    readonly kind: 'updated';
+    readonly revision: number;
+    readonly region: string;
+    readonly ttlSeconds: number;
+    readonly decisions: readonly EntitlementDecision[];
+    /**
+     * Server-driven branding parsed from the SAME 200 body's render_hints (orthogonal to capabilities).
+     * null when absent or unparseable (fail-closed -> the compiled Everfur default theme). OPTIONAL so a
+     * hand-built resolution (tests / injected resolve) need not supply it.
+     */
+    readonly branding?: ClientBranding | null;
+} | {
+    readonly kind: 'notModified';
+} | {
+    readonly kind: 'failed';
+    readonly error: EverfurError;
+};
+interface FetchEntitlementsArgs {
+    /** The revision we last stored; echoed as If-None-Match so an unchanged verdict returns 304. */
+    readonly cachedRevision?: number | null;
+    /** Optional region hint; forwarded as ?region. */
+    readonly region?: string;
+}
+/**
+ * Fetch the server-resolved entitlement verdict once. Never throws: a 304, a domain error, a network reject,
+ * and a malformed body all SETTLE to an EntitlementResolution. Fail-closed on every non-`updated` path.
+ */
+declare function fetchEntitlements(auth: AuthContext, args?: FetchEntitlementsArgs, funnel?: RequestFunnel): Promise<EntitlementResolution>;
+
+/**
+ * Server-declared bounds on `WidgetPetInput`, mirrored so a violation is refused before the wire rather
+ * than returning a 422 after the caller has already driven a registration flow. Every field is optional
+ * server-side: `POST` with an empty body registers a bare pet, which is all consent needs.
+ */
+declare const PET_NAME_MAX = 100;
+declare const PET_SPECIES_MAX = 50;
+declare const PET_BREED_MAX = 100;
+declare const PET_AGE_YEARS_MAX = 50;
+declare const PET_WEIGHT_KG_MAX = 500;
+/** The optional profile fields. Omit all of them to register the pet without describing it. */
+interface PetProfileInput {
+    readonly name?: string;
+    readonly species?: string;
+    readonly breed?: string;
+    readonly ageYears?: number;
+    readonly weightKg?: number;
+}
+/** The registered profile, as the server echoes it back. */
+interface RegisteredPet {
+    readonly petRef: string;
+    readonly name: string | null;
+    readonly species: string | null;
+    readonly breed: string | null;
+    readonly ageYears: number | null;
+    readonly weightKg: number | null;
+}
+interface PetsRepository {
+    /**
+     * `POST /widget/v1/pets/{pet_ref}` - create or update the widget pet profile. Idempotent by construction:
+     * the route is an upsert, so calling it for an already-registered pet updates rather than duplicates.
+     *
+     * Settles: `ok(RegisteredPet)` on 201, `err(EverfurError)` otherwise. Never throws.
+     */
+    registerPet(petRef: PetRef, profile?: PetProfileInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<EverfurResult<RegisteredPet>>;
+}
+/** Build the repository over a device AuthContext (personalized bearer XOR anonymous pk). */
+declare function createPetsRepository(auth: AuthContext): PetsRepository;
+
+export { deepFreeze as A, fetchEntitlements as B, type ClientBranding as C, hardenHttpsUrl as D, ENTITLEMENTS_PATH as E, type FetchEntitlementsArgs as F, isEmptyBranding as G, parseClientBranding as H, parseColor as I, readableOn as J, resolveTheme as K, withServerBranding as L, PET_AGE_YEARS_MAX as P, type RegisteredPet as R, EVERFUR_DARK as a, EVERFUR_LIGHT as b, type EntitlementResolution as c, type EverfurColorTokens as d, type EverfurFontWeight as e, type EverfurLetterSpacingTokens as f, type EverfurLineHeightTokens as g, type EverfurMotionDurationTokens as h, type EverfurMotionTokens as i, type EverfurRadiusTokens as j, type EverfurSpaceTokens as k, type EverfurSpringToken as l, type EverfurTextColorTokens as m, type EverfurTheme as n, type EverfurThemeMeta as o, type EverfurTypeSizeTokens as p, type EverfurTypeTokens as q, type EverfurWeightTokens as r, PET_BREED_MAX as s, PET_NAME_MAX as t, PET_SPECIES_MAX as u, PET_WEIGHT_KG_MAX as v, type PetProfileInput as w, type PetsRepository as x, type ResolveThemeInput as y, createPetsRepository as z };

package/dist/petsRepository-Bu18r2kK.d.ts

@@ -0,0 +1,326 @@
+import { f as EverfurError, E as EverfurResult } from './EverfurResult-D92-uL82.js';
+import { R as RequestFunnel } from './requestFunnel-dio5OmR9.js';
+import { A as AuthContext } from './identity-DK9zORrG.js';
+import { E as EntitlementDecision } from './resolve-Dq_4_agU.js';
+import { P as PetRef } from './ids-CJ1S6adf.js';
+
+/** Recursively freeze a plain object/array tree in place and return it (typed as the input). */
+declare function deepFreeze<T>(value: T): T;
+/** Foreground text tokens; the semantic text ramp over surfaces. */
+interface EverfurTextColorTokens {
+    readonly primary: string;
+    readonly secondary: string;
+    readonly muted: string;
+    readonly placeholder: string;
+    /** Text drawn on the brand fill (a compiled default; resolve recomputes onPrimary/onAccent via WCAG). */
+    readonly onBrand: string;
+    readonly metaCool: string;
+}
+/** The Everfur color system: brand + surfaces + text ramp + semantic palette + component washes. */
+interface EverfurColorTokens {
+    readonly brand: string;
+    readonly brandSoft: string;
+    readonly brandSofter: string;
+    readonly brandBorder: string;
+    readonly borderHairlineGreen: string;
+    readonly surface: string;
+    readonly surfaceCream: string;
+    readonly surfaceSubtle: string;
+    readonly background: string;
+    readonly borderRingCream: string;
+    readonly text: EverfurTextColorTokens;
+    /** The primary CTA fill (server-overridable via primary_color). Foreground is `onPrimary`. */
+    readonly primary: string;
+    /** WCAG-legible foreground for `primary` (computed by resolveTheme, never passed through). */
+    readonly onPrimary: string;
+    /** The user/CTA accent fill (server-overridable via accent_color). Foreground is `onAccent`. */
+    readonly accent: string;
+    /** WCAG-legible foreground for `accent` (computed by resolveTheme). */
+    readonly onAccent: string;
+    /** The 0.5px bubble edge (a lightened brand / success green for the default). */
+    readonly accentEdge: string;
+    readonly success: string;
+    readonly danger: string;
+    readonly errorRed: string;
+    readonly warningStrong: string;
+    readonly cautionAccent: string;
+    readonly riskConcern: string;
+    readonly badgeBgPositive: string;
+    readonly badgeBgCaution: string;
+    readonly badgeBgCritical: string;
+    readonly badgeBgNeutral: string;
+    /** user bubble = accent fill; assistant bubble = bare surface (the mobile/Flutter asymmetry). */
+    readonly bubbleUser: string;
+    readonly bubbleAssistant: string;
+    readonly skeleton: string;
+    readonly scanButtonPink: string;
+    readonly checkupCardLowRiskBg: string;
+    readonly checkupCardConcernBg: string;
+}
+/** Spacing scale (dp). */
+interface EverfurSpaceTokens {
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly xxl: number;
+}
+/** Corner-radius scale (dp); `pill` is an effectively-infinite radius. */
+interface EverfurRadiusTokens {
+    readonly tile: number;
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly pill: number;
+}
+interface EverfurTypeSizeTokens {
+    readonly nano: number;
+    readonly small: number;
+    readonly micro: number;
+    readonly tiny: number;
+    readonly caption: number;
+    readonly bodyTight: number;
+    readonly body: number;
+    readonly subtitle: number;
+    readonly heading: number;
+    readonly verdict: number;
+}
+/** Line-height multipliers (applied to a size to derive an absolute lineHeight). */
+interface EverfurLineHeightTokens {
+    readonly tight: number;
+    readonly snug: number;
+    readonly normal: number;
+    readonly relaxed: number;
+}
+/**
+ * RN-assignable font-weight literals. Typed as the exact string literals we ship (not bare `string`) so a
+ * consumer can spread a weight token straight into a `Text` style: React Native's `TextStyle['fontWeight']`
+ * accepts these, but rejects `string`. Kept framework-free (no react-native import) to hold the client layer's
+ * no-framework boundary - these three literals are a subset of RN's fontWeight union.
+ */
+type EverfurFontWeight = '400' | '500' | '700';
+/** RN fontWeight tokens. */
+interface EverfurWeightTokens {
+    readonly regular: EverfurFontWeight;
+    readonly medium: EverfurFontWeight;
+    readonly bold: EverfurFontWeight;
+}
+interface EverfurLetterSpacingTokens {
+    readonly eyebrow: number;
+    readonly monoWide: number;
+    readonly headerBrand: number;
+    readonly tight: number;
+}
+/** Typography tokens. `family`/`mono` default to the platform font; server font_family/font_url may override. */
+interface EverfurTypeTokens {
+    readonly family: string;
+    readonly mono: string;
+    /** Optional remote font (server font_url); null unless a server override supplies an https URL. */
+    readonly fontUrl: string | null;
+    readonly size: EverfurTypeSizeTokens;
+    readonly lineHeight: EverfurLineHeightTokens;
+    readonly weight: EverfurWeightTokens;
+    readonly letterSpacing: EverfurLetterSpacingTokens;
+}
+interface EverfurSpringToken {
+    readonly damping: number;
+    readonly stiffness: number;
+}
+interface EverfurMotionDurationTokens {
+    readonly instant: number;
+    readonly fast: number;
+    readonly normal: number;
+    readonly slow: number;
+}
+/** Motion tokens. Under reduced-motion, resolveTheme collapses durations to 0 and stiffens the spring. */
+interface EverfurMotionTokens {
+    readonly duration: EverfurMotionDurationTokens;
+    readonly spring: {
+        readonly gentle: EverfurSpringToken;
+    };
+    readonly easing: {
+        readonly standard: string;
+    };
+    /** true when the resolved theme has collapsed motion (AccessibilityInfo reduced-motion). */
+    readonly reducedMotion: boolean;
+}
+/** Non-visual identity + partner copy carried on the theme (server display_name/logo_url/placeholder overlay). */
+interface EverfurThemeMeta {
+    readonly displayName: string;
+    readonly logoUrl: string | null;
+    /** Server-overridable composer placeholder (chat_placeholder/placeholder); null keeps Everfur's neutral default. */
+    readonly placeholder: string | null;
+    /** White-label switch (hide_powered_by): drop the "powered by everfur" attribution. Default false (shown). */
+    readonly hidePoweredBy: boolean;
+}
+/**
+ * The frozen, never-null theme the rn layer renders. Read a token as `theme.color.brand`,
+ * `theme.space.md`, `theme.type.size.body`, `theme.radius.lg`, `theme.motion.duration.fast`.
+ */
+interface EverfurTheme {
+    readonly brightness: 'light' | 'dark';
+    readonly meta: EverfurThemeMeta;
+    readonly color: EverfurColorTokens;
+    readonly space: EverfurSpaceTokens;
+    readonly radius: EverfurRadiusTokens;
+    readonly type: EverfurTypeTokens;
+    readonly motion: EverfurMotionTokens;
+}
+/** The compiled LIGHT default (deeply frozen). */
+declare const EVERFUR_LIGHT: EverfurTheme;
+/** The compiled DARK default (deeply frozen). */
+declare const EVERFUR_DARK: EverfurTheme;
+
+interface ClientBranding {
+    readonly displayName: string | null;
+    /** normalized (https-hardened downstream) logo URL */
+    readonly logoUrl: string | null;
+    /** normalized color string (#RRGGBB or rgba(...)) or null */
+    readonly primaryColor: string | null;
+    readonly accentColor: string | null;
+    readonly brightness: 'light' | 'dark' | null;
+    readonly fontFamily: string | null;
+    readonly fontUrl: string | null;
+    /** composer placeholder override (chat_placeholder/placeholder); null keeps the base. */
+    readonly placeholder: string | null;
+    /** white-label switch (hide_powered_by): hide the powered-by attribution. null = unset (keep the base). */
+    readonly hidePoweredBy: boolean | null;
+}
+/** true when every field is null (no config) - treated by callers as "absent". */
+declare function isEmptyBranding(b: ClientBranding): boolean;
+/**
+ * Parse an untrusted branding blob (from the entitlements render_hints, or the client `theme` prop) into a
+ * normalized `ClientBranding`. Accepts BOTH snake_case and camelCase keys. Returns null when the input is not
+ * an object OR when the result is empty (all fields null) - callers read null as "no config" (fail-closed to
+ * the compiled default). Never throws.
+ */
+declare function parseClientBranding(json: unknown): ClientBranding | null;
+/**
+ * Parse a permissive color into a normalized string (`#RRGGBB` when opaque, else `rgba(r,g,b,a)`), or null.
+ * Accepts `#RGB`, `#RRGGBB`, `#AARRGGBB`, `0xAARRGGBB` (string), a 32-bit ARGB `int`, and `rgb()/rgba()`.
+ * An empty string, whitespace, or an unrecognized value yields null.
+ */
+declare function parseColor(value: unknown): string | null;
+/**
+ * Return the more legible of near-black / white for `background` (WCAG 2.x contrast). Ported from Flutter
+ * `_readableOn`. Falls back to white for an unparseable background (never throws).
+ */
+declare function readableOn(background: string): string;
+/**
+ * Return the URL only if it is an https URL with no embedded whitespace, else null (security invariant:
+ * https-only; rejects http:, javascript:, data:, etc.). Uses a protocol-locked regex rather than the URL
+ * constructor so it is portable + total on React Native (whose URL global is incomplete) and never throws.
+ */
+declare function hardenHttpsUrl(url: string | null): string | null;
+/**
+ * Overlay `b` onto `base`, field by field: a non-null branding field WINS; a null field KEEPS the base. A
+ * valid brightness re-selects the matching compiled palette (light/dark); an invalid/absent brightness leaves
+ * the base palette untouched. Returns a NEW deeply-frozen theme; `base` and `b` are never mutated.
+ *
+ * NOTE: foreground legibility (onPrimary/onAccent) and URL hardening are applied by `resolveTheme`, the total
+ * entry point. Call this directly only when you will finalize the result yourself.
+ */
+declare function withServerBranding(base: EverfurTheme, b: ClientBranding | null): EverfurTheme;
+/**
+ * Inputs to the total theme resolve. All optional; `resolveTheme(undefined)` yields the compiled Everfur
+ * default. Merge order (server wins): compiled default <- clientOverride (first-paint/offline fallback) <-
+ * branding (server render_hints).
+ */
+interface ResolveThemeInput {
+    /** Server-driven branding from the live entitlements render_hints (authoritative overlay). */
+    readonly branding?: ClientBranding | null;
+    /** The clamped client `theme` prop - a first-paint/offline fallback merged UNDER the server. */
+    readonly clientOverride?: ClientBranding | null;
+    /** The device color scheme (useColorScheme); selects the base palette when branding sets no brightness. */
+    readonly colorScheme?: 'light' | 'dark' | null;
+    /** AccessibilityInfo reduced-motion: collapses the motion tokens. */
+    readonly reducedMotion?: boolean;
+}
+/**
+ * Resolve the final, legible, deeply-frozen theme. Never throws, never returns null/transparent. Applies the
+ * client fallback UNDER the server overlay, recomputes onPrimary/onAccent via WCAG, hardens logo/font URLs to
+ * https-only, guarantees a non-empty displayName, and collapses motion under reduced-motion.
+ */
+declare function resolveTheme(input?: ResolveThemeInput): EverfurTheme;
+
+/** The conditional-GET endpoint (SPEC-00 §5.3). Relative; the transport prefixes the resolved base URL. */
+declare const ENTITLEMENTS_PATH = "/widget/v1/entitlements";
+/**
+ * The settled outcome of one entitlement fetch. `updated` carries a fresh verdict + the cadence to re-poll on;
+ * `notModified` means the cached verdict still holds; `failed` carries a normalized error and means keep-last.
+ */
+type EntitlementResolution = {
+    readonly kind: 'updated';
+    readonly revision: number;
+    readonly region: string;
+    readonly ttlSeconds: number;
+    readonly decisions: readonly EntitlementDecision[];
+    /**
+     * Server-driven branding parsed from the SAME 200 body's render_hints (orthogonal to capabilities).
+     * null when absent or unparseable (fail-closed -> the compiled Everfur default theme). OPTIONAL so a
+     * hand-built resolution (tests / injected resolve) need not supply it.
+     */
+    readonly branding?: ClientBranding | null;
+} | {
+    readonly kind: 'notModified';
+} | {
+    readonly kind: 'failed';
+    readonly error: EverfurError;
+};
+interface FetchEntitlementsArgs {
+    /** The revision we last stored; echoed as If-None-Match so an unchanged verdict returns 304. */
+    readonly cachedRevision?: number | null;
+    /** Optional region hint; forwarded as ?region. */
+    readonly region?: string;
+}
+/**
+ * Fetch the server-resolved entitlement verdict once. Never throws: a 304, a domain error, a network reject,
+ * and a malformed body all SETTLE to an EntitlementResolution. Fail-closed on every non-`updated` path.
+ */
+declare function fetchEntitlements(auth: AuthContext, args?: FetchEntitlementsArgs, funnel?: RequestFunnel): Promise<EntitlementResolution>;
+
+/**
+ * Server-declared bounds on `WidgetPetInput`, mirrored so a violation is refused before the wire rather
+ * than returning a 422 after the caller has already driven a registration flow. Every field is optional
+ * server-side: `POST` with an empty body registers a bare pet, which is all consent needs.
+ */
+declare const PET_NAME_MAX = 100;
+declare const PET_SPECIES_MAX = 50;
+declare const PET_BREED_MAX = 100;
+declare const PET_AGE_YEARS_MAX = 50;
+declare const PET_WEIGHT_KG_MAX = 500;
+/** The optional profile fields. Omit all of them to register the pet without describing it. */
+interface PetProfileInput {
+    readonly name?: string;
+    readonly species?: string;
+    readonly breed?: string;
+    readonly ageYears?: number;
+    readonly weightKg?: number;
+}
+/** The registered profile, as the server echoes it back. */
+interface RegisteredPet {
+    readonly petRef: string;
+    readonly name: string | null;
+    readonly species: string | null;
+    readonly breed: string | null;
+    readonly ageYears: number | null;
+    readonly weightKg: number | null;
+}
+interface PetsRepository {
+    /**
+     * `POST /widget/v1/pets/{pet_ref}` - create or update the widget pet profile. Idempotent by construction:
+     * the route is an upsert, so calling it for an already-registered pet updates rather than duplicates.
+     *
+     * Settles: `ok(RegisteredPet)` on 201, `err(EverfurError)` otherwise. Never throws.
+     */
+    registerPet(petRef: PetRef, profile?: PetProfileInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<EverfurResult<RegisteredPet>>;
+}
+/** Build the repository over a device AuthContext (personalized bearer XOR anonymous pk). */
+declare function createPetsRepository(auth: AuthContext): PetsRepository;
+
+export { deepFreeze as A, fetchEntitlements as B, type ClientBranding as C, hardenHttpsUrl as D, ENTITLEMENTS_PATH as E, type FetchEntitlementsArgs as F, isEmptyBranding as G, parseClientBranding as H, parseColor as I, readableOn as J, resolveTheme as K, withServerBranding as L, PET_AGE_YEARS_MAX as P, type RegisteredPet as R, EVERFUR_DARK as a, EVERFUR_LIGHT as b, type EntitlementResolution as c, type EverfurColorTokens as d, type EverfurFontWeight as e, type EverfurLetterSpacingTokens as f, type EverfurLineHeightTokens as g, type EverfurMotionDurationTokens as h, type EverfurMotionTokens as i, type EverfurRadiusTokens as j, type EverfurSpaceTokens as k, type EverfurSpringToken as l, type EverfurTextColorTokens as m, type EverfurTheme as n, type EverfurThemeMeta as o, type EverfurTypeSizeTokens as p, type EverfurTypeTokens as q, type EverfurWeightTokens as r, PET_BREED_MAX as s, PET_NAME_MAX as t, PET_SPECIES_MAX as u, PET_WEIGHT_KG_MAX as v, type PetProfileInput as w, type PetsRepository as x, type ResolveThemeInput as y, createPetsRepository as z };