@runbandit/sdk 2.0.1 → 2.1.2

package/dist/index.d.ts

@@ -65,14 +65,6 @@ interface Experiment {
     endAt?: Date;
     placement?: Placement;
 }
-/**
- * Storefront slots a theme app extension block can occupy.
- *
- * Closed set: theme block settings are a static schema compiled into the
- * extension, so a placement cannot be added without shipping a new extension
- * version. Keep in sync with the `placement` select in
- * extensions/bandit-storefront/blocks/bandit_text.liquid.
- */
 declare const PLACEMENTS: readonly ["hero_headline", "hero_subhead", "cta_primary", "banner_text", "badge_text"];
 type Placement = (typeof PLACEMENTS)[number];
 interface Treatment {
@@ -87,46 +79,13 @@ interface Treatment {
 }
 interface AlgorithmResult {
     treatmentId: string;
-    /**
-     * @deprecated Per-algorithm, not comparable across algorithms, and about to
-     * be redefined in a future major version. Historically a single raw
-     * posterior draw for the selected arm (e.g. one Beta or LinUCB-squash
-     * sample) - in [0,1], but a *volatile* one: it is a single sample, not an
-     * estimate, so it swings arm-to-arm and request-to-request even when the
-     * underlying posteriors haven't moved. Kept for backward compatibility with
-     * documented example values (`api/assignments/route.doc.ts`,
-     * `src/lib/api-reference.ts`, `specs/assignments.md`). New consumers should
-     * use `probabilityBest` instead. See
-     * `docs/plans/2026-09-14-gaussian-thompson-migration-plan.md` task 4 for
-     * why this is an additive field rather than an in-place redefinition.
-     */
     confidence: number;
-    /**
-     * P(this arm is the best arm), estimated by Monte Carlo sampling of the
-     * arms' posteriors many times and tallying wins (see
-     * `MultiArmBandit.getSelectionProbabilities()`). In [0,1], sums to ~1
-     * across an experiment's arms, and is far less volatile than `confidence`
-     * since it averages over many draws instead of reporting one.
-     *
-     * Not every algorithm can produce this cheaply on the assignment hot path:
-     * - `ThompsonSampling` populates it (reduced sample count - see comment at
-     *   the call site for the cost tradeoff).
-     * - `ContinuousThompson` and `FunnelBandit` support Monte Carlo estimation
-     *   via their own `getSelectionProbabilities()` / repeated `selectArm()`
-     *   calls, but neither is wired into `probabilityBest` on the live
-     *   assignment path (todo - see migration plan task 7 rollout).
-     * - `LinearContextualBandit` does not populate this field at all: LinUCB is
-     *   not a posterior sampler, so there is nothing to Monte Carlo over. The
-     *   field is simply absent (`undefined`), not a stand-in zero.
-     */
     probabilityBest?: number;
 }
 interface BanditResult {
     assignmentId: string;
     treatmentId: string;
-    /** @deprecated see `AlgorithmResult.confidence`. */
     confidence: number;
-    /** See `AlgorithmResult.probabilityBest`. */
     probabilityBest?: number;
     metadata?: Record<string, any>;
 }
@@ -154,55 +113,15 @@ interface VariantConfig {
     content: string;
     metadata?: TreatmentMetadata & Record<string, any>;
 }
-/**
- * Bandit algorithm families.
- *
- * Every family is Thompson-style: a Bayesian posterior per arm, sampled at
- * selection time. How much of the past that posterior remembers is controlled
- * separately, by `ForgettingMode`.
- */
 declare enum BanditAlgorithm {
     THOMPSON_SAMPLING = "thompson_sampling",
     CONTEXTUAL_LINEAR = "contextual_linear"
 }
-/**
- * Which posterior a Thompson-family experiment samples from.
- *
- * See the migration plan (docs/plans/2026-09-14-gaussian-thompson-migration-plan.md,
- * task 7): this is a per-experiment rollout flag, not a replacement of
- * `BanditAlgorithm`. `BETA` is the existing Beta-Binomial posterior
- * (`ThompsonSampling`); `NORMAL_GAMMA` is the extracted Normal-Gamma one
- * (`ContinuousThompson`). Missing/undefined means `BETA` - every experiment
- * written before this field existed must keep selecting exactly as it does
- * today.
- */
 declare enum Posterior {
     BETA = "beta",
     NORMAL_GAMMA = "normal_gamma"
 }
-/**
- * Map a stored posterior string onto a supported one, defaulting missing or
- * unrecognised values to `BETA` - the behaviour every existing experiment
- * already has. Only `create` (new experiments) or an explicit switch should
- * ever produce `NORMAL_GAMMA`.
- */
 declare function normalizePosterior(posterior: string | null | undefined): Posterior;
-/**
- * How an algorithm forgets old observations.
- *
- * Standard bandits assume the arms are stationary: a conversion from six months
- * ago counts exactly as much as one from this morning. Real treatments are
- * restless - creative fatigues, seasons turn, traffic mix shifts - so the two
- * non-stationary modes below down-weight or drop stale evidence.
- *
- * - NONE           stationary; every observation counts forever
- * - DISCOUNTED     observation weight decays as 0.5^(age / halfLifeMs)
- * - SLIDING_WINDOW observations outside the last `windowMs` are dropped entirely
- *
- * Both non-stationary modes measure age in wall-clock time rather than in
- * observation count, so a quiet experiment forgets at the same rate as a busy
- * one.
- */
 declare enum ForgettingMode {
     NONE = "none",
     DISCOUNTED = "discounted",
@@ -210,31 +129,13 @@ declare enum ForgettingMode {
 }
 interface ForgettingConfig {
     mode: ForgettingMode;
-    /** Half-life in milliseconds. DISCOUNTED only. */
     halfLifeMs?: number;
-    /** Window length in milliseconds. SLIDING_WINDOW only. */
     windowMs?: number;
 }
-/** Default half-life for DISCOUNTED: one week. */
 declare const DEFAULT_HALF_LIFE_MS: number;
-/** Default window for SLIDING_WINDOW: two weeks. */
 declare const DEFAULT_WINDOW_MS: number;
-/** The stationary default applied when an experiment has no forgetting config. */
 declare const STATIONARY: ForgettingConfig;
-/**
- * Fill in the defaults for a partially-specified forgetting config.
- * An unrecognised or missing mode degrades to NONE rather than throwing, so a
- * stale row written by an older deploy still selects treatments.
- */
 declare function resolveForgetting(config?: Partial<ForgettingConfig> | null): ForgettingConfig;
-/**
- * Map a stored algorithm string onto a supported algorithm.
- *
- * Retired names (epsilon_greedy, ucb1) map onto standard Thompson Sampling,
- * which reads the same successes/trials counters they did, so a running
- * experiment keeps its learned history. contextual_neural maps onto
- * contextual_linear, which is what it already fell back to at runtime.
- */
 declare function normalizeAlgorithm(algorithm: string | null | undefined): BanditAlgorithm;
 declare enum ContentType {
     PLAIN_TEXT = "plain_text",
@@ -285,7 +186,6 @@ interface AssignmentRequest {
     userId: string;
     context?: ContextualFeatures;
     sessionId?: string;
-    /** Browser page the assignment was requested from (origin + pathname). */
     pageUrl?: string;
 }
 interface TrackNamedEventRequest {
@@ -306,7 +206,8 @@ interface Funnel {
     name: string;
     description?: string;
     status: FunnelStatus;
-    conversionWindowMs: number;
+    inactivityTimeoutMs?: number;
+    revisionWindowMs?: number;
     companyId: string;
     createdAt: Date;
     updatedAt: Date;
@@ -361,6 +262,8 @@ interface Bundle {
     funnelId?: string;
     assignmentTtl: number;
     conversionWindowMs: number;
+    inactivityTimeoutMs?: number;
+    revisionWindowMs?: number;
     companyId: string;
     createdAt: Date;
     updatedAt: Date;
@@ -382,33 +285,14 @@ interface BundleAssignmentResponse {
     bundleAssignmentId: string;
     slots: Record<string, BundleSlotAssignment>;
 }
-/**
- * One treatment's published allocation within a snapshot experiment.
- *
- * This is the wire contract between the snapshot publisher (dashboard API)
- * and its only consumer (the SDK). Declared once here so both sides share
- * the same shape instead of drifting apart.
- */
 interface SnapshotTreatment {
     id: string;
     name?: string;
     config: unknown;
-    /** Probability the next visitor is assigned this arm. Sums to ~1 per experiment. */
     pct: number;
 }
 interface SnapshotExperiment {
-    /**
-     * 'snapshot' means the client may decide locally from `pct`. 'network' means
-     * it must call /api/assignments, because the experiment's state cannot be
-     * reduced to a static distribution.
-     */
     mode: 'snapshot' | 'network';
-    /**
-     * Assignment lifetime in SECONDS (the unit `assignments.expiresAt` uses).
-     * The client holds a decision this long so that repeated pageviews in one
-     * session report one impression, matching the server path's one assignment
-     * per (experiment, user).
-     */
     assignmentTtl: number;
     treatments: SnapshotTreatment[];
 }
@@ -427,118 +311,21 @@ declare function calculateConfidenceInterval(successes: number, trials: number,
 };
 declare function isValidEmail(email: string): boolean;
 declare function sanitizeMetadata(metadata: Record<string, any>): Record<string, any>;
-/**
- * Generates a URL-safe subdomain from a company name
- * @param name Company name
- * @returns URL-safe subdomain
- */
 declare function generateSubdomain(name: string): string;
-/**
- * Validates if a subdomain is properly formatted
- * @param subdomain Subdomain to validate
- * @returns true if valid, false otherwise
- */
 declare function isValidSubdomain(subdomain: string): boolean;
-/**
- * Extracts subdomain from hostname
- * @param hostname Full hostname (e.g., 'acme.example.com')
- * @param baseDomain Base domain (e.g., 'example.com')
- * @returns Subdomain or null if not found
- */
 declare function extractSubdomain(hostname: string, baseDomain: string): string | null;
-/**
- * Builds full URL with subdomain
- * @param subdomain Subdomain
- * @param baseDomain Base domain
- * @param path Optional path
- * @param protocol Protocol (default: https)
- * @returns Full URL
- */
 declare function buildSubdomainUrl(subdomain: string, baseDomain: string, path?: string, protocol?: string): string;
 
-/**
- * The email tracking token.
- *
- * Every tracked link in an email carries one of these as a query parameter.
- * It is the impression record: which campaign, which recipient, which arm was
- * chosen in every slot, and which link was clicked - all of it self-contained
- * and signed, so no row has to be written at send time.
- *
- * Three constraints shape the format, and all three are unusual:
- *
- * 1. **It must be mintable offline.** In `plan` mode the customer's own SDK
- *    mints tokens for millions of recipients with no network calls, so the
- *    token cannot be a database id we hand out. Minting is a pure function of
- *    (payload, key).
- *
- * 2. **It must outlive everything else in the system.** A link minted today
- *    may be clicked in three years. That makes this format a public contract
- *    with no deprecation path: campaign link tables are never deleted, slot
- *    order is never changed, and several signing keys stay valid at once so a
- *    rotation cannot break links already sitting in inboxes.
- *
- * 3. **It travels somewhere hostile.** URLs get forwarded, logged by proxies
- *    and leaked through `Referer`. Nothing in here may be a secret, and
- *    nothing in here may be trusted before the signature is checked.
- *
- * See specs/email.md, "Tokens".
- */
-/**
- * The query parameter tracked links are tagged with.
- *
- * Kept distinct from the well-known ad-tech parameters (`fbclid`, `gclid`,
- * `utm_*`): Safari's Link Tracking Protection and Firefox's strict ETP strip
- * params from a curated list of known trackers, and sharing a name with one of
- * them would mean being stripped by association.
- */
 declare const EMAIL_TOKEN_PARAM = "bt";
-/**
- * One signing key. Several are valid concurrently - see `verifyEmailToken`.
- *
- * `version` is carried in the token so verification can select the right key
- * directly instead of trying each in turn, which would leak timing information
- * and get slower with every rotation.
- */
 interface SigningKey {
     version: number;
     secret: string;
 }
-/**
- * The signed body of a token. Field names are single characters because this
- * is base64'd into a URL that also has to survive an email client's line
- * wrapping - the verbosity is not worth the bytes.
- */
 interface EmailTokenPayload {
-    /** Campaign id. */
     c: string;
-    /** Pseudonymous recipient - see `hashRecipient`. Never a raw identifier. */
     r: string;
-    /**
-     * The arm chosen in each slot, POSITIONALLY: `k[i]` is the arm index chosen
-     * for the campaign's `slots[i]`.
-     *
-     * Positional rather than a `{ slotId: armId }` map because ids are ~32
-     * characters each and a six-slot email would spend over 200 characters
-     * restating what the campaign already knows. The cost is that a campaign's
-     * slot order becomes load-bearing forever, which is why reordering slots
-     * after a send is rejected at the campaign level.
-     *
-     * The whole combination is here, not just the clicked slot, because a click
-     * has to credit every slot the recipient saw - and because in `plan` mode
-     * this token IS the impression record, reconstructable from a first click
-     * even if the send-time manifest never arrived.
-     */
     k: number[];
-    /**
-     * Index into the campaign's link table - never a URL.
-     *
-     * A token carrying its own destination would be an open redirect the moment
-     * the signature check had a bug, and would make every token long enough to
-     * matter. An index can only ever address a link the campaign already
-     * declared.
-     */
     l: number;
-    /** Signing key version. Set by `mintEmailToken`; do not pass it in. */
     v?: number;
 }
 type VerifiedToken = {
@@ -548,210 +335,43 @@ type VerifiedToken = {
     valid: false;
     reason: 'malformed' | 'unknown_key' | 'bad_signature';
 };
-/**
- * Pseudonymise a recipient identifier.
- *
- * Deliberately a one-way HMAC rather than something we can reverse. We do not
- * need to: the destination page is the customer's own, and their SDK resolves
- * the real identity through `identify()` on arrival. What Bandit needs is a
- * stable key to attribute a click and to dedupe first-touch, and a hash serves
- * that without ever putting a customer's user ids in a URL that gets
- * forwarded, proxy-logged and leaked through `Referer`.
- *
- * Keyed on a company-level secret rather than a campaign one, so the same
- * recipient hashes identically across every campaign that company sends. That
- * is what makes cross-campaign frequency and fatigue analysis possible later -
- * an unsubscribe is usually the result of the fifth email, not the first.
- *
- * Truncated to 16 bytes: 128 bits is far beyond collision range for any real
- * list, and the 22 characters saved matter in a URL.
- */
 declare function hashRecipient(recipientId: string, companySecret: string): Promise<string>;
-/**
- * Mint a token. Pure function of (payload, key) - the same inputs always
- * produce the same token, which is what lets the SDK mint offline in `plan`
- * mode and the server arrive independently at the identical value.
- */
 declare function mintEmailToken(payload: EmailTokenPayload, key: SigningKey): Promise<string>;
-/**
- * Verify a token against every currently-held key.
- *
- * Never throws. This is called from a redirect endpoint and a click ingest
- * route, both of which take their input straight off a URL - a crash there is
- * a broken link in a real person's inbox, and the input is attacker-controlled
- * by definition.
- *
- * Pass every key still in rotation, oldest included. Dropping a key
- * permanently breaks every link ever minted under it, and those links live in
- * inboxes we cannot reach.
- */
 declare function verifyEmailToken(token: string, keys: SigningKey[]): Promise<VerifiedToken>;
-/**
- * Append a token to a destination URL.
- *
- * Appends rather than replaces, which is the whole reason the default tracking
- * mode needs no redirect service, no DNS setup and no custom certificate: the
- * link still points at the customer's own domain, and their existing Bandit
- * SDK reads the parameter on page load. Established practice - every ESP and
- * marketer already decorates outbound links this way.
- *
- * Existing query parameters and fragments are preserved; a fragment must stay
- * last or the browser will treat the token as part of it.
- */
 declare function appendEmailToken(url: string, token: string): string;
 
-/**
- * `plan` mode - assignment for bulk sends, with no per-recipient round trip.
- *
- * `resolve` and `batch` both make an HTTP call carrying recipients. That is
- * fine to ten thousand and untenable at two million: the customer's send
- * pipeline would spend its entire budget waiting on us.
- *
- * So instead of answering per recipient, we hand over the *policy*. The plan
- * carries each slot's arm set and the selection probabilities the bandit's
- * posterior currently implies, plus a salt and the campaign's signing key. The
- * SDK then derives each recipient's arm locally and mints their token offline -
- * no network, perfectly parallel, as fast as the customer's own loop.
- *
- * Two properties make this work, and both are load-bearing:
- *
- * **Determinism.** The sampler here is the single implementation. The server
- * and the customer's SDK must derive the identical arm for the identical
- * recipient, or the impression manifest reports one thing and the tokens say
- * another. It is pure, keyed only on (salt, recipientId, slot), and pinned by
- * test.
- *
- * **Staleness is bounded by chunking.** A plan is one snapshot of the
- * posterior, so a whole blast served from a single plan is one learning epoch.
- * `refreshEvery` lets the caller re-request every N recipients, turning a 2M
- * send into a few dozen epochs instead of one - the customer's own dial
- * between throughput and adaptivity.
- */
 interface PlanArm {
     treatmentId: string;
-    /**
-     * Position of this arm in its slot's treatment list.
-     *
-     * This is what a token carries, so it must be the same index the render and
-     * click paths resolve against - not this array's position, which is only
-     * incidentally the same.
-     */
     armIndex: number;
 }
 interface PlanSlot {
     experimentId: string;
-    /** Slot name, for substituting into the template. */
     name: string;
     arms: PlanArm[];
-    /**
-     * P(each arm is best), positionally aligned with `arms`, summing to ~1.
-     *
-     * Thompson sampling's allocation, computed once from the posterior rather
-     * than re-sampled per recipient. Sampling locally from these probabilities
-     * is distributionally identical to sampling the posterior directly, which is
-     * what makes the offline derivation legitimate rather than an approximation.
-     */
     probabilities: number[];
-    /** Arm content, positionally aligned with `arms`. */
     configs: unknown[];
 }
 interface EmailPlan {
     campaignId: string;
     slots: PlanSlot[];
     linkTable: string[];
-    /**
-     * Per-plan randomisation. Two campaigns must not assign the same recipient
-     * the same way merely because the probabilities happen to match, or the
-     * population splits into permanent cohorts and cross-campaign comparisons
-     * quietly stop being independent.
-     */
     salt: string;
-    /**
-     * The campaign's current signing key, so the SDK can mint offline.
-     *
-     * This is the customer's own campaign secret, sent to their server - not to
-     * a browser. It lets them mint tokens for their own campaign, which they
-     * could already do by calling the click endpoint directly; it does not let
-     * them touch anyone else's.
-     */
     signingKey: {
         version: number;
         secret: string;
     };
-    /** Re-request after this many recipients to pick up what the send has learned. */
     refreshEvery: number;
-    /** When this plan stops being usable. */
     expiresAt: number;
 }
-/**
- * A uniform draw in [0,1) for one recipient and slot.
- *
- * HMAC rather than a plain hash so the mapping cannot be reproduced by anyone
- * without the salt - otherwise a recipient could work out which arm they were
- * in, and more importantly a third party could reconstruct the whole
- * assignment for a campaign they observed one token from.
- *
- * Six bytes gives 2^48 distinct values, far finer than any arm allocation
- * needs, and avoids the precision loss of stuffing 64 bits into a double.
- */
 declare function uniformFor(salt: string, recipientId: string, slotIndex: number): Promise<number>;
-/**
- * Pick an arm index from a probability vector given a uniform draw.
- *
- * Separated from the draw so the selection itself is synchronous and trivially
- * testable against hand-written vectors.
- *
- * Degenerate vectors are handled rather than trusted: probabilities that do
- * not quite sum to 1 (Monte Carlo estimates never do) must not leave a
- * recipient unassigned, so the last arm absorbs the remainder.
- */
 declare function pickArm(probabilities: number[], uniform: number): number;
-/** The arm each slot assigns this recipient, positionally by slot. */
 declare function sampleCombination(plan: EmailPlan, recipientId: string): Promise<number[]>;
-/**
- * Tally a plan-mode send into per-arm impression counts.
- *
- * Aggregated because a send is a burst: the bandit needs a denominator, not a
- * row per recipient, and the per-recipient detail already lives in each token.
- */
 declare function impressionManifest(plan: EmailPlan, recipientIds: string[]): Promise<Array<{
     experimentId: string;
     treatmentId: string;
     count: number;
 }>>;
 
-/**
- * Email as a structured document.
- *
- * The other authoring mode takes the customer's own HTML template and
- * substitutes slots into it. This one inverts that: the email is authored in
- * Bandit as a block tree, and every block property is a candidate slot. Four
- * slots with four options each is sixteen authored pieces and 256 possible
- * emails, none of which anyone hand-writes.
- *
- * This is about AUTHORING, not learning - cross-campaign learning works
- * identically either way. What it buys is that a marketer can run a
- * multi-armed email without owning an HTML template at all.
- *
- * ## Why this renderer is hand-written
- *
- * MJML is the obvious choice and was the original plan. Two things rule it
- * out. The dashboard runs on Cloudflare Workers, where MJML's several
- * megabytes sit badly against the bundle limit; and the same rendering has to
- * be available in `@runbandit/sdk`, which ships with no runtime dependencies
- * because customers did not agree to a transitive tree in order to send an
- * email. One small renderer serving both beats two that can disagree.
- *
- * ## Why the output looks like 1999
- *
- * Because email clients do. Outlook renders through Word, which ignores
- * `div`-based layout, flexbox and grid entirely; Gmail strips `<style>` blocks
- * in several contexts. Tables with inline styles are not nostalgia, they are
- * the only layout primitive that survives everywhere - and a button that needs
- * a background colour in Outlook needs a VML rectangle, which is why the
- * button block emits a conditional comment.
- */
-/** A value that comes from a bandit slot rather than being authored directly. */
 interface SlotBinding {
     $slot: string;
 }
@@ -795,28 +415,18 @@ interface SpacerBlock {
 }
 type EmailBlock = HeadingBlock | TextBlock | ButtonBlock | ImageBlock | DividerBlock | SpacerBlock;
 interface EmailDocument {
-    /** Subject line - a slot like any other, and usually the highest-leverage one. */
     subject: Bound<string>;
     preheader?: Bound<string>;
     blocks: EmailBlock[];
     backgroundColor?: string;
     contentWidth?: number;
 }
-/** Every slot name the document refers to, in document order, de-duplicated. */
 declare function extractDocumentSlots(document: EmailDocument): string[];
 interface RenderedDocument {
     subject: string;
     html: string;
-    /** Slots the document referenced that no value was supplied for. */
     missingSlots: string[];
 }
-/**
- * Render a document to email-safe HTML.
- *
- * The output is deliberately a complete document with the table scaffolding
- * every client needs, not a fragment: there is no "outer template" the
- * customer supplies in this mode, which is the entire point of it.
- */
 declare function renderEmailDocument(document: EmailDocument, slots: Record<string, string>): RenderedDocument;
 
 interface BanditsClientConfig {
@@ -833,6 +443,7 @@ interface Assignment {
     experimentId: string;
     userId: string;
     config: any;
+    funnelId?: string;
 }
 declare class BanditsClient {
     private config;
@@ -841,11 +452,6 @@ declare class BanditsClient {
     private flushTimer?;
     constructor(config: BanditsClientConfig);
     getAssignment(experimentId: string, userId: string, context?: ContextualFeatures): Promise<Assignment>;
-    /**
-     * Track a named event for session-based attribution (recommended)
-     * Events are matched to bandits by sessionId — no assignmentId needed
-     * Set immediate: true to fire synchronously (survives navigation)
-     */
     trackNamedEvent(event: {
         name: string;
         category?: string;
@@ -855,38 +461,12 @@ declare class BanditsClient {
         immediate?: boolean;
     }): void;
     flush(): Promise<void>;
-    /**
-     * Link an anonymous user ID to a durable identity (e.g. email, account ID).
-     * All historical assignments and events for the anonymous ID are re-attributed
-     * to the identified user. Future calls to getAssignment() with either ID will
-     * resolve to the same assignment.
-     *
-     * Requires admin authentication — the client must be configured with a
-     * personal access token (PAT) instead of an API key, and companyId must
-     * be provided. This is a management operation, not an SDK client operation.
-     *
-     * @param anonymousId - The temporary/anonymous user ID (e.g. crypto.randomUUID())
-     * @param identifiedUserId - The permanent user ID (e.g. email, database ID)
-     * @param companyId - The company ID (required for PAT auth)
-     * @param mergeReason - Why the identification is happening
-     */
     identify(anonymousId: string, identifiedUserId: string, companyId: string, mergeReason?: 'user_signup' | 'email_verification' | 'social_login' | 'account_recovery' | 'manual'): Promise<void>;
-    /**
-     * Record a funnel payout event.
-     * Call this when the terminal conversion happens (e.g., purchase).
-     *
-     * @param funnelId - The funnel ID
-     * @param userId - The user who converted
-     * @param value - The payout value (e.g., purchase amount in dollars)
-     */
+    label(userId: string, labels: Record<string, string | boolean>): Promise<void>;
     trackFunnelReward(funnelId: string, userId: string, value: number): Promise<void>;
     getBundle(bundleId: string, userId: string, context?: ContextualFeatures): Promise<BundleAssignmentResponse>;
     trackBundleReward(bundleId: string, userId: string, value: number): Promise<void>;
     private generateId;
-    /**
-     * Normalize the apiUrl by adding /api prefix if not present.
-     * Supports both 'https://runbandit.com' and 'https://runbandit.com/api'.
-     */
     private normalizeApiUrl;
     private getOrCreateSessionId;
     private makeRequest;
@@ -903,28 +483,12 @@ interface SyncAssignment {
 interface SnapshotClientConfig {
     apiUrl: string;
     publishableKey: string;
-    /** Defaults to window.localStorage. Injectable for tests and SSR. */
     storage?: Storage;
-    /** Injectable clock. Defaults to Date.now. */
     now?: () => number;
-    /** Session lifetime in ms. Must match the BanditsClient using the same storage. */
     sessionTtl?: number;
-    /**
-     * A snapshot embedded in the page at render time. When present there is no
-     * cold start at all - the decision happens with zero network calls, which is
-     * the whole point of the design.
-     */
     inlineSnapshot?: CompanySnapshot;
     fetchImpl?: typeof fetch;
 }
-/**
- * Pick an arm from a published allocation.
- *
- * One uniform draw against the cumulative distribution. This is equivalent to
- * Thompson sampling because `pct` *is* the distribution Thompson sampling
- * draws from - the Monte Carlo ran server-side, once, instead of here on every
- * pageview.
- */
 declare function pickTreatment(treatments: SnapshotTreatment[], draw: number): SnapshotTreatment | null;
 declare class SnapshotClient {
     private config;
@@ -936,203 +500,63 @@ declare class SnapshotClient {
     private sessionId;
     private inFlight;
     constructor(config: SnapshotClientConfig);
-    /**
-     * Decide an arm with no network call, or return null.
-     *
-     * Null means "this caller must fall back" - a cold cache, an expired one, an
-     * unknown experiment, or one whose state cannot be served from a static
-     * document. Returning null rather than the control is deliberate: the caller
-     * renders control itself, and no impression is reported for it. Reporting a
-     * forced-control impression would inflate the control arm's trials with
-     * decisions the bandit never made.
-     */
     getAssignmentSync(experimentId: string, userId: string): SyncAssignment | null;
-    /** Fetch a fresh snapshot and cache it. Safe to call on every pageview. */
     refresh(): Promise<void>;
-    /**
-     * Post queued impressions.
-     *
-     * The queue is only cleared on success. A failed flush leaves the reports in
-     * storage, so a pageview that happened offline is still counted when the
-     * next one succeeds - the trial really did occur, and dropping it would bias
-     * the arm's denominator downward.
-     */
     flush(): Promise<void>;
     private doFlush;
-    /** The session id these reports are attributed under. */
     getSessionId(): string;
     pendingReportCount(): number;
-    /** The cached snapshot, or null when absent or past its ttl. */
     private freshSnapshot;
     private readSnapshot;
     private persistSnapshot;
     private readQueue;
-    /** Stored decisions, pruned of expired entries. */
     private readDecisions;
     private writeDecisions;
     private persistQueue;
 }
 
-/**
- * Session identity, shared by every client in this package.
- *
- * Reward attribution joins `assignments` by `sessionId`, so a decision made by
- * `SnapshotClient` and an event tracked by `BanditsClient` must agree on the
- * id or the conversion never lands on the impression. One implementation,
- * used by both, is the only way that rule stays true.
- */
 declare const SESSION_ID_KEY = "bandits_session_id";
 declare const SESSION_CREATED_AT_KEY = "bandits_session_created_at";
-/** 24 hours, in milliseconds. */
 declare const DEFAULT_SESSION_TTL_MS = 86400000;
 interface SessionOptions {
-    /** Where the session lives. Null (no browser storage) means ephemeral. */
     storage?: Storage | null;
-    /** Injectable clock, in milliseconds. */
     now?: () => number;
     ttlMs?: number;
 }
-/**
- * Return the current session id, minting and persisting a new one when there
- * is none or the stored one has aged past `ttlMs`.
- */
 declare function getOrCreateSessionId(options?: SessionOptions): string;
 
 interface RewriteOptions {
-    /**
-     * The campaign's ordered destination URLs. A token carries an index into
-     * THIS array, not into the order links happen to appear in the document -
-     * otherwise moving a paragraph would repoint every token already sent.
-     */
     linkTable: string[];
-    /** One token per link table entry, positionally aligned. */
     tokens: string[];
 }
 interface RewriteResult {
     html: string;
-    /** How many hrefs were tokenised. */
     rewritten: number;
-    /**
-     * Trackable links found in the document but absent from the link table.
-     *
-     * Reported rather than guessed at: a link we cannot attribute is left
-     * exactly as authored, because a dead link is far worse than an untracked
-     * one. Surfacing them is what lets the campaign append the missing entries
-     * (appending is always allowed; reordering is not).
-     */
     untracked: string[];
 }
-/**
- * Every trackable destination in the document, in order, de-duplicated.
- *
- * Used at campaign creation to build the link table that tokens index into.
- */
 declare function extractEmailLinks(html: string): string[];
-/**
- * Tokenise every trackable link in the document.
- *
- * Tokens are appended, not substituted, so the link still points at the
- * customer's own domain: no redirect service, no DNS record, no certificate,
- * and no shared link-domain reputation to poison. Their landing page's
- * existing Bandit SDK reads the parameter on load.
- *
- * Synchronous and pure: minting is asynchronous (WebCrypto), so the caller
- * mints one token per link table entry first and passes them in. That keeps
- * this function trivially testable and lets a batch send mint once per
- * recipient rather than once per link per parse.
- */
 declare function rewriteEmailLinks(html: string, options: RewriteOptions): RewriteResult;
 
 interface RenderEmailOptions {
-    /** Chosen content per slot, keyed by slot name, from /api/email/render. */
     slots: Record<string, string>;
-    /** The campaign's ordered destination URLs. */
     linkTable: string[];
-    /** One token per link table entry, minted for this recipient. */
     tokens: string[];
 }
 interface RenderedEmail {
     html: string;
-    /** How many links were tokenised. */
     rewritten: number;
-    /** Trackable links not present in the campaign's link table. */
     untracked: string[];
-    /**
-     * Placeholders the template asked for that no slot supplied.
-     *
-     * Reported rather than left in place as literal `{{bandit.x}}`, which is
-     * what a recipient would otherwise read in their inbox.
-     */
     missingSlots: string[];
 }
-/**
- * Substitute slot values, then tokenise every trackable link.
- *
- * Order matters: substitution happens first, so a slot whose value contains a
- * link gets that link tokenised too. Doing it the other way round would leave
- * links from bandit-selected content untracked - exactly the content whose
- * performance we are trying to measure.
- */
 declare function renderEmail(templateHtml: string, options: RenderEmailOptions): RenderedEmail;
-/**
- * The slot names a template refers to.
- *
- * Used at authoring time to check a template against a campaign's slots before
- * anything is sent, rather than discovering the mismatch in an inbox.
- */
 declare function extractSlotNames(templateHtml: string): string[];
 
-/**
- * Offline rendering from a campaign plan.
- *
- * This is what makes a two-million-recipient send possible. The plan is
- * fetched once; every recipient after that is derived locally - arm selection,
- * token minting, slot substitution and link rewriting - with no network call
- * at all. The customer's send loop runs at whatever speed their own ESP client
- * manages, and we are not in it.
- *
- * Nothing here needs to reach us, which is also why the customer's template
- * and merge data never leave their infrastructure.
- */
 interface PlanRenderResult extends RenderedEmail {
-    /** Arm chosen per slot, positionally against the plan's slots. */
     combination: number[];
-    /** The token minted for each link, positionally against the link table. */
     tokens: string[];
 }
-/**
- * Render one recipient's email from a plan.
- *
- * Derivation is deterministic in (salt, recipientId, slot), so re-rendering the
- * same recipient - a retry, a resumed batch, a preview - produces byte-identical
- * output and the same tokens. A send that crashes halfway can simply be run
- * again without double-counting anyone or issuing a second set of links.
- */
 declare function renderFromPlan(plan: EmailPlan, recipientId: string, templateHtml: string, companySecret: string): Promise<PlanRenderResult>;
-/**
- * Whether a plan should be refreshed before continuing a send.
- *
- * A plan is one snapshot of the posterior, so serving a whole blast from it
- * makes the entire send a single learning epoch - the bandit cannot react to
- * anything it learns partway through. Refreshing every `refreshEvery`
- * recipients turns a 2M send into a few dozen epochs for a few dozen API
- * calls, which is the trade the customer gets to make rather than us.
- */
 declare function shouldRefreshPlan(plan: EmailPlan, recipientsRenderedSincePlan: number, now?: number): boolean;
-/**
- * Post a plan-mode send's impressions so the bandit has a denominator.
- *
- * This is not optional bookkeeping. `plan` mode makes no per-recipient call,
- * so without this the only observations that ever reach the posterior are
- * clicks - every one of them a success - and every arm converges on
- * "everything works" while the dashboard shows excellent numbers measuring
- * nothing. The same omission was caught once already in the `batch` render
- * path; it is easier to make here precisely because nothing else round-trips.
- *
- * Aggregated per arm, so ten thousand recipients across a handful of arms is
- * one small request. `batchKey` makes it idempotent: a retried post must not
- * double the denominator and quietly halve every arm's apparent rate.
- */
 declare function reportPlanImpressions(plan: EmailPlan, recipientIds: string[], options: {
     apiUrl: string;
     apiKey: string;