@avsbhq/vue 1.0.2 → 1.1.1

package/dist/index.d.cts

@@ -1,95 +1,89 @@
 import * as vue from 'vue';
 import { PropType, Plugin, InjectionKey, Ref, ComputedRef } from 'vue';
-import { InitResult, EvalContext, Flag, TrackPayload, ClientEventName, ClientEventMap } from '@avsbhq/core';
-export { ClientEventMap, ClientEventName, DecideOption, EvalContext, EvaluationSource, Flag, FlagDatafile, FlagDatafileAudience, FlagDatafileEntry, FlagDatafileOverride, FlagDatafileRule, FlagDatafileVariation, InitResult, Logger, MultiContext, SingleContext, TrackPayload } from '@avsbhq/core';
+import { EvalContext, FlagDatafile, AvsbFlagKey, Flag, TrackPayload } from '@avsbhq/core';
+export { ClientEventMap, ClientEventName, DecideOption, EvalContext, EvaluationSource, Flag, FlagDatafile, FlagDatafileAudience, FlagDatafileEntry, FlagDatafileOverride, FlagDatafileRule, FlagDatafileVariation, InitResult, Logger, MultiContext, RuleType, SingleContext, TrackPayload } from '@avsbhq/core';
+import { V as VueAvsbClient } from './clientInterface-BMlQ7Uhe.cjs';
+import { b as AvsbProviderOptions, d as AvsbStatus } from './types-DECMgjjk.cjs';
+export { A as AvsbProviderModeAProps, a as AvsbProviderModeBProps, c as AvsbProviderProps } from './types-DECMgjjk.cjs';
 import { AvsbClientOptions } from '@avsbhq/browser';
-export { AvsbClientOptions } from '@avsbhq/browser';
-import * as pinia from 'pinia';
-
-/**
- * The surface of AvsbClient that @avsbhq/vue depends on.
- *
- * This interface describes the new browser SDK surface being added in
- * CoW 3 (sdk-launch-readiness). Until @avsbhq/browser ships the full
- * implementation, the Vue package compiles against this interface rather
- * than the concrete class, avoiding cross-package coupling during the
- * in-progress reshape.
- *
- * When the browser SDK reshape lands, AvsbClient will satisfy this
- * interface structurally — no cast required. Until then, any runtime
- * use of these methods is guarded with `typeof client.method === 'function'`
- * checks in each composable.
- */
-
-interface VueAvsbClient {
-    onReady(): Promise<InitResult>;
-    close(): Promise<void>;
-    flush(): Promise<void>;
-    identify(ctx: EvalContext): void;
-    updateAttributes(partial: Record<string, unknown>, kind?: string): void;
-    alias(prev: EvalContext, next: EvalContext): Promise<void>;
-    getContext(): EvalContext;
-    reset(): void;
-    getFlag<T>(key: string, defaultValue: T): Flag<T>;
-    getBoolFlag(key: string, defaultValue: boolean): Flag<boolean>;
-    getStringFlag(key: string, defaultValue: string): Flag<string>;
-    getNumberFlag(key: string, defaultValue: number): Flag<number>;
-    getJsonFlag<T>(key: string, defaultValue: T): Flag<T>;
-    getAllFlags(options?: {
-        fireExposures?: boolean;
-    }): Record<string, Flag>;
-    /** Subscribe to changes for a specific flagKey; returns unsubscribe. */
-    subscribe(flagKey: string, listener: () => void): () => void;
-    /** Return a stable Flag<T> snapshot without firing an exposure event. */
-    getSnapshot<T>(flagKey: string, defaultValue: T): Flag<T>;
-    track(eventKey: string, payload?: TrackPayload): void;
-    on<E extends ClientEventName>(event: E, cb: ClientEventMap[E]): () => void;
-    setOverrideForUser(flagKey: string, contextKey: string, variationKey: string, contextKind?: string): void;
-    setGlobalOverride(flagKey: string, variationKey: string): void;
-    clearOverrideForUser(flagKey: string, contextKey: string, contextKind?: string): void;
-    clearGlobalOverride(flagKey: string): void;
-    clearAllOverrides(): void;
-}
+export { AvsbClientOptions, GetAllFlagsOptions, GetFlagOptions } from '@avsbhq/browser';
 
 declare const AvsbProvider: vue.DefineComponent<vue.ExtractPropTypes<{
+    /** Mode B: a client you built and own. */
     client: {
         type: PropType<VueAvsbClient>;
         default: undefined;
     };
+    /** Mode A: the environment's SDK key. */
     sdkKey: {
         type: StringConstructor;
         default: undefined;
     };
+    /** Mode A: evaluation context. Omit for an anonymous visitor. */
+    context: {
+        type: PropType<EvalContext>;
+        default: undefined;
+    };
+    /** Mode A: a datafile fetched on the server, for a real first paint. */
+    bootstrap: {
+        type: PropType<FlagDatafile>;
+        default: undefined;
+    };
+    /** Mode A: everything else AvsbClient accepts. */
+    options: {
+        type: PropType<AvsbProviderOptions>;
+        default: undefined;
+    };
 }>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>[] | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    /** Mode B: a client you built and own. */
     client: {
         type: PropType<VueAvsbClient>;
         default: undefined;
     };
+    /** Mode A: the environment's SDK key. */
     sdkKey: {
         type: StringConstructor;
         default: undefined;
     };
+    /** Mode A: evaluation context. Omit for an anonymous visitor. */
+    context: {
+        type: PropType<EvalContext>;
+        default: undefined;
+    };
+    /** Mode A: a datafile fetched on the server, for a real first paint. */
+    bootstrap: {
+        type: PropType<FlagDatafile>;
+        default: undefined;
+    };
+    /** Mode A: everything else AvsbClient accepts. */
+    options: {
+        type: PropType<AvsbProviderOptions>;
+        default: undefined;
+    };
 }>> & Readonly<{}>, {
-    client: VueAvsbClient;
     sdkKey: string;
+    context: EvalContext;
+    bootstrap: FlagDatafile;
+    options: AvsbProviderOptions;
+    client: VueAvsbClient;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
 /**
- * AvsbPlugin: Vue plugin alternative to mounting <AvsbProvider>.
+ * AvsbPlugin: the `app.use()` form of <AvsbProvider>.
  *
- * Usage:
- *   // Mode A: SDK creates and owns the client
- *   app.use(AvsbPlugin, { sdkKey: 'sdk-xxx', attributes: { userId: 'u_1' } })
+ *   // Mode A: the plugin builds and owns the client
+ *   app.use(AvsbPlugin, {
+ *     sdkKey: 'sdk_production_...',
+ *     context: { kind: 'user', key: userId },
+ *   })
  *
- *   // Mode B: pass a pre-built client
- *   app.use(AvsbPlugin, { client: myClient })
+ *   // Mode B: you built the client, you own it
+ *   app.use(AvsbPlugin, { client })
  *
- * The plugin installs AvsbProvider semantics at the app level via
- * app.provide(). It is equivalent to wrapping the root component in
- * <AvsbProvider>, but works better with apps that prefer the plugin
- * pattern over SFC wrapper components.
+ * Identical semantics to the component, provided at app level instead of at
+ * a subtree, which is what you want when the whole app reads flags.
  */
 
 type AvsbPluginOptions = (AvsbClientOptions & {
@@ -100,180 +94,216 @@ type AvsbPluginOptions = (AvsbClientOptions & {
 declare const AvsbPlugin: Plugin<AvsbPluginOptions>;
 
 interface AvsbContextValue {
-    client: VueAvsbClient | null;
-    status: 'loading' | 'ready' | 'error';
-    error?: Error;
+    client: VueAvsbClient;
+    status: AvsbStatus;
+    /**
+     * The last error the SDK reported. Present while `status` is `'error'`,
+     * and also present with `status: 'ready'` when a refresh failed while
+     * cached flags are still being served (`degraded`).
+     */
+    error: Error | undefined;
+    /** Serving a stale bootstrap or cached datafile after a failed refresh. */
+    degraded: boolean;
 }
 declare const AvsbInjectionKey: InjectionKey<AvsbContextValue>;
 
+/** A flag key, or a ref holding one. */
+type FlagKeyInput = AvsbFlagKey | Ref<AvsbFlagKey> | ComputedRef<AvsbFlagKey>;
+
 /**
- * §5.13 + §5.14: Subscribe to a single flag.
+ * Read one flag and re-render when it changes.
  *
- * Returns `ComputedRef<Flag<T>>` (not raw `T`). The computed re-evaluates
- * only when the value of `flagKey` changes via the subscribe callback.
+ * Returns `ComputedRef<Flag<T>>`, so in `<script setup>` the value is
+ * `flag.value.value`: the outer `.value` unwraps Vue's ref, the inner one is
+ * the flag's value. Templates unwrap the ref for you, so there it is
+ * `flag.value`. See the README section "Why .value.value".
  *
- * When flagKey is a Ref or ComputedRef, the subscription updates reactively
- * when the key changes (watchEffect re-subscribes).
+ * `flagKey` may be a string or a ref; a ref re-subscribes when it changes.
  *
- * For a plain `T` shortcut, use `useFlagValue()`.
+ * The read is render-safe: the same frozen object comes back until the value
+ * actually changes, and no exposure is recorded. Use `useExposure` where the
+ * decision is really shown to the visitor.
  */
-declare function useFlag<T>(flagKey: string | Ref<string> | ComputedRef<string>, defaultValue: T): ComputedRef<Flag<T>>;
+declare function useFlag<T>(flagKey: FlagKeyInput, defaultValue: T): ComputedRef<Flag<T>>;
 
 /**
- * §5.16: Convenience shortcut that returns the flag's raw value `T`
- * instead of the full `Flag<T>` object.
+ * The flag's value on its own, with no `Flag<T>` wrapper: one `.value` in
+ * script, and none in a template.
  *
- * Use `useFlag()` when you need `variationKey`, `source`, `reasons`, or
- * other evaluation metadata. Use this composable when you only care about
- * the value itself.
+ * Use `useFlag` when you also want `variationKey`, `source`, or `reasons`.
  */
-declare function useFlagValue<T>(flagKey: string | Ref<string> | ComputedRef<string>, defaultValue: T): ComputedRef<T>;
+declare function useFlagValue<T>(flagKey: FlagKeyInput, defaultValue: T): ComputedRef<T>;
 
 /**
- * §5.16: Typed boolean flag composable.
+ * Read a boolean flag, type-checked against the type the platform declared
+ * for it.
  *
- * Calls `client.getBoolFlag` under the hood, which performs a runtime
- * type check against the datafile's declared flag type and logs a warning
- * on mismatch before returning the default.
+ * On a mismatch nothing throws: the SDK logs one warning naming the flag and
+ * the getter, and you get your `defaultValue` back with
+ * `source: 'not_found'`.
  *
- * Returns `ComputedRef<Flag<boolean>>`.
+ * Render-safe: no exposure is recorded (see `useExposure`).
  */
-declare function useBoolFlag(flagKey: string, defaultValue: boolean): ComputedRef<Flag<boolean>>;
+declare function useBoolFlag(flagKey: FlagKeyInput, defaultValue: boolean): ComputedRef<Flag<boolean>>;
 
 /**
- * §5.16: Typed string flag composable.
- *
- * Calls `client.getStringFlag` under the hood, which performs a runtime
- * type check against the datafile's declared flag type and logs a warning
- * on mismatch before returning the default.
+ * Read a string flag, type-checked against the type the platform declared
+ * for it. A mismatch logs one warning and returns your `defaultValue`.
  *
- * Returns `ComputedRef<Flag<string>>`.
+ * Render-safe: no exposure is recorded (see `useExposure`).
  */
-declare function useStringFlag(flagKey: string, defaultValue: string): ComputedRef<Flag<string>>;
+declare function useStringFlag(flagKey: FlagKeyInput, defaultValue: string): ComputedRef<Flag<string>>;
 
 /**
- * §5.16: Typed number flag composable.
+ * Read a number flag, type-checked against the type the platform declared
+ * for it. A mismatch logs one warning and returns your `defaultValue`.
  *
- * Calls `client.getNumberFlag` under the hood, which performs a runtime
- * type check against the datafile's declared flag type and logs a warning
- * on mismatch before returning the default.
- *
- * Returns `ComputedRef<Flag<number>>`.
+ * Render-safe: no exposure is recorded (see `useExposure`).
  */
-declare function useNumberFlag(flagKey: string, defaultValue: number): ComputedRef<Flag<number>>;
+declare function useNumberFlag(flagKey: FlagKeyInput, defaultValue: number): ComputedRef<Flag<number>>;
 
 /**
- * §5.16: Typed JSON flag composable.
+ * Read a JSON flag as `Flag<T>`.
  *
- * Calls `client.getJsonFlag` under the hood, which performs a runtime
- * type check against the datafile's declared flag type and logs a warning
- * on mismatch before returning the default.
+ * The runtime check is that the platform declared this flag as JSON; the
+ * shape of `T` is not validated. Validate the payload yourself (zod, a type
+ * guard) if it crosses a trust boundary.
  *
- * Returns `ComputedRef<Flag<T>>` where `T` is your expected JSON shape.
+ * Render-safe: no exposure is recorded (see `useExposure`).
  */
-declare function useJsonFlag<T>(flagKey: string, defaultValue: T): ComputedRef<Flag<T>>;
+declare function useJsonFlag<T>(flagKey: FlagKeyInput, defaultValue: T): ComputedRef<Flag<T>>;
 
 /**
- * §5.16: Returns `ComputedRef<Record<string, Flag>>` containing all
- * evaluated flags.
+ * Every flag in the environment, keyed by flag key.
  *
- * Subscribes to the global `'flagChange'` event bus rather than per-flag
- * subscriptions. Any flag change causes re-evaluation of all flags.
+ * Re-computes on any flag change, so prefer `useFlag` in components that
+ * read one flag. This is for debug panels and admin views.
  *
- * Use this composable for dashboards or debug panels that display the full
- * flag state. For individual flag reads, prefer `useFlag()` which only
- * re-renders on changes to that specific flag.
+ * Exposures are suppressed, and the SDK returns the same object between
+ * changes, so this is safe to read on every render. Before the SDK is ready
+ * it is `{}` and the SDK logs one line saying why, rather than looking like
+ * a project with no flags.
  */
 declare function useAllFlags(): ComputedRef<Record<string, Flag>>;
 
 /**
- * §5.15: Returns `ComputedRef<boolean>` that is `true` once the
- * Provider's client is ready.
+ * `true` once flags are readable.
  *
- * Simple boolean alternative to reading status directly for components
- * that only need to gate rendering on readiness.
+ * A degraded client (serving a cached datafile after a failed refresh) is
+ * ready: flags answer, they may be stale. Use `useAvsbStatus` when you need
+ * to tell those two apart, or to show the error.
  */
 declare function useFlagReady(): ComputedRef<boolean>;
 
+interface UseAvsbStatusResult {
+    /** `'loading'` | `'ready'` | `'error'`. */
+    status: ComputedRef<AvsbStatus>;
+    /**
+     * The last error the SDK reported, if any. Present with `status: 'error'`,
+     * and also with `status: 'ready'` when `degraded` is true.
+     */
+    error: ComputedRef<Error | undefined>;
+    /**
+     * `true` when flags are being served from a bootstrap or the cache after a
+     * refresh failed. Values still answer; they may be stale.
+     */
+    degraded: ComputedRef<boolean>;
+}
+/**
+ * The provider's status, error, and staleness, as refs.
+ *
+ *   const { status, error, degraded } = useAvsbStatus()
+ *
+ * `status.value === 'error'` means nothing loaded and every flag is
+ * returning the default you passed; `error.value.message` names the HTTP
+ * status, the URL tried, and the fix.
+ */
+declare function useAvsbStatus(): UseAvsbStatusResult;
+
 /**
- * Returns the underlying `AvsbClient` instance (or `null` while loading).
+ * The underlying client, for the things composables do not cover: runtime
+ * overrides, `flush()`, `refresh()`, `updateAttributes()`.
  *
- * The type is `VueAvsbClient`, the interface declaring the surface this
- * package uses. Once @avsbhq/browser ships the full reshape, `AvsbClient`
- * satisfies this interface structurally.
+ * Never null: a provider either has a client or throws at setup.
  *
- * Prefer typed flag composables (`useFlag`, `useBoolFlag`, etc.) for feature
- * flag reads. Use this composable when you need low-level SDK access (e.g.
- * manual `flush()`, direct `track()`).
+ * Prefer `useFlag` and friends for reading flags; a direct `client.getFlag`
+ * in a component body fires an exposure on every render.
  */
-declare function useAvsbClient(): VueAvsbClient | null;
+declare function useAvsbClient(): VueAvsbClient;
 
 /**
- * §5.16: Returns a stable `identify` function.
+ * Replace the evaluation context, typically after sign-in.
+ *
+ * Every flag is re-evaluated, changed flags notify their subscribers, and
+ * bucketing rehashes immediately.
  *
- * Calling `identify(ctx)` replaces the client's current evaluation context.
- * All subsequent flag evaluations and exposure events use the new context.
- * Triggers re-evaluation for any `useFlag` subscribers whose values changed.
+ * The returned function is created once per component, so it is safe to pass
+ * straight to an event handler.
+ */
+declare function useIdentify(): (context: EvalContext) => void;
+
+/**
+ * Record that an anonymous visitor and a signed-in user are the same person,
+ * so results can stitch the two sessions together.
  *
- * @returns `(ctx: EvalContext) => void`
+ * Synchronous: it queues one `avsb_alias` event and returns. There is
+ * nothing to await, and it does not rewrite assignments already made. To
+ * carry bucketing across a login, evaluate with the same context key on both
+ * sides.
  */
-declare function useIdentify(): (ctx: EvalContext) => void;
+declare function useAlias(): (previousContext: EvalContext, newContext: EvalContext) => void;
 
 /**
- * §5.16: Returns a stable `alias` function.
+ * Return to a new anonymous identity and clear runtime overrides. Call this
+ * on sign-out.
  *
- * Calling `alias(prev, next)` records that two contexts represent the
- * same user identity (e.g. anonymous visitor → identified user after
- * sign-in). Used by the analytics backend to stitch sessions.
+ * The persisted visitor id is rotated, so the next anonymous session is
+ * genuinely a different visitor rather than the person who just signed out.
  *
- * @returns `(prev: EvalContext, next: EvalContext) => Promise<void>`
+ * One caveat when the A vs B web snippet is on the same page: the snippet
+ * owns the visitor cookie and this SDK only reads it, so the next page load
+ * adopts the snippet's id again unless the client was built with
+ * `adoptSnippetVisitorId: false`.
  */
-declare function useAlias(): (prev: EvalContext, next: EvalContext) => Promise<void>;
+declare function useReset(): () => void;
 
 /**
- * §5.16: Returns a stable `track` function that survives the
- * loading → ready transition without changing its reference.
+ * Send a conversion or metric event.
  *
- * The function delegates to `client.track()` via a ref so that callers
- * do not need to call `useTrack` again when the client becomes ready.
+ *   const track = useTrack()
+ *   track('checkout_started', { value: 99, properties: { step: 'cart' } })
  *
- * @returns `(eventKey: string, payload?: TrackPayload) => void`
+ * Events tracked before the SDK is ready are held (bounded) and flushed as
+ * soon as it is. The returned function is created once per component, so it
+ * is safe to use directly as an event handler.
  */
 declare function useTrack(): (eventKey: string, payload?: TrackPayload) => void;
 
-declare const useAvsbStore: pinia.StoreDefinition<"avsb", Pick<{
-    client: vue.ComputedRef<VueAvsbClient | null>;
-    status: vue.ComputedRef<"ready" | "error" | "loading">;
-    error: vue.ComputedRef<Error | undefined>;
-    setClient: (c: VueAvsbClient | null) => void;
-    identify: (ctx: EvalContext) => void;
-    track: (eventKey: string, payload?: TrackPayload) => void;
-    alias: (prev: EvalContext, next: EvalContext) => Promise<void>;
-    reset: () => void;
-}, never>, Pick<{
-    client: vue.ComputedRef<VueAvsbClient | null>;
-    status: vue.ComputedRef<"ready" | "error" | "loading">;
-    error: vue.ComputedRef<Error | undefined>;
-    setClient: (c: VueAvsbClient | null) => void;
-    identify: (ctx: EvalContext) => void;
-    track: (eventKey: string, payload?: TrackPayload) => void;
-    alias: (prev: EvalContext, next: EvalContext) => Promise<void>;
-    reset: () => void;
-}, "error" | "client" | "status">, Pick<{
-    client: vue.ComputedRef<VueAvsbClient | null>;
-    status: vue.ComputedRef<"ready" | "error" | "loading">;
-    error: vue.ComputedRef<Error | undefined>;
-    setClient: (c: VueAvsbClient | null) => void;
-    identify: (ctx: EvalContext) => void;
-    track: (eventKey: string, payload?: TrackPayload) => void;
-    alias: (prev: EvalContext, next: EvalContext) => Promise<void>;
-    reset: () => void;
-}, "track" | "identify" | "alias" | "reset" | "setClient">>;
+/**
+ * Record that this visitor has been shown a flag's decision.
+ *
+ * Reading a flag during render never records an exposure, which is what
+ * keeps a re-render from inflating your results. Call this once, in the
+ * component that actually shows the variation, or when the value came from
+ * the server as a prop.
+ *
+ * It fires on mount (never during render or during SSR), or as soon as the
+ * SDK becomes ready if it is not yet. A reactive key exposes the new flag
+ * when the key changes.
+ */
+declare function useExposure(flagKey: FlagKeyInput): void;
 
-type AvsbProviderProps = (AvsbClientOptions & {
-    client?: never;
-}) | {
-    client: VueAvsbClient;
-};
+/**
+ * Run a side effect when one flag changes, without re-rendering.
+ *
+ * The callback also runs once when the first datafile lands, so a component
+ * mounted before the SDK was ready still hears about the real value. Use
+ * `useFlag` when the value drives what you render; use this for analytics,
+ * logging, or imperative work.
+ *
+ * The flag handed to the callback is a render-safe read: it records no
+ * exposure.
+ */
+declare function useFlagSubscription(flagKey: FlagKeyInput, callback: (flag: Flag) => void): void;
 
-export { type AvsbContextValue, AvsbInjectionKey, AvsbPlugin, type AvsbPluginOptions, AvsbProvider, type AvsbProviderProps, type VueAvsbClient, useAlias, useAllFlags, useAvsbClient, useAvsbStore, useBoolFlag, useFlag, useFlagReady, useFlagValue, useIdentify, useJsonFlag, useNumberFlag, useStringFlag, useTrack };
+export { type AvsbContextValue, AvsbInjectionKey, AvsbPlugin, type AvsbPluginOptions, AvsbProvider, AvsbProviderOptions, AvsbStatus, type FlagKeyInput, type UseAvsbStatusResult, VueAvsbClient, useAlias, useAllFlags, useAvsbClient, useAvsbStatus, useBoolFlag, useExposure, useFlag, useFlagReady, useFlagSubscription, useFlagValue, useIdentify, useJsonFlag, useNumberFlag, useReset, useStringFlag, useTrack };