@runbandit/sdk 1.0.0 → 2.0.1

package/dist/index.d.ts

@@ -50,10 +50,12 @@ interface Experiment {
     name: string;
     description?: string;
     algorithm: BanditAlgorithm;
+    forgetting?: ForgettingConfig;
     status: ExperimentStatus;
     contentType: ContentType;
     treatments: Treatment[];
     context?: Record<string, any>;
+    bundleId?: string;
     image?: string;
     emoji?: string;
     assignmentTtl: number;
@@ -61,7 +63,18 @@ interface Experiment {
     createdAt: Date;
     updatedAt: Date;
     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 {
     id: string;
     experimentId: string;
@@ -74,12 +87,47 @@ 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>;
 }
 interface ContextualFeatures {
@@ -106,13 +154,88 @@ 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 {
-    EPSILON_GREEDY = "epsilon_greedy",
-    UCB1 = "ucb1",
     THOMPSON_SAMPLING = "thompson_sampling",
-    CONTEXTUAL_LINEAR = "contextual_linear",
-    CONTEXTUAL_NEURAL = "contextual_neural"
+    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",
+    SLIDING_WINDOW = "sliding_window"
+}
+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",
     MARKDOWN = "markdown",
@@ -162,6 +285,8 @@ interface AssignmentRequest {
     userId: string;
     context?: ContextualFeatures;
     sessionId?: string;
+    /** Browser page the assignment was requested from (origin + pathname). */
+    pageUrl?: string;
 }
 interface TrackNamedEventRequest {
     name: string;
@@ -226,6 +351,72 @@ interface ResolvedIdentity {
     anonymousIds: string[];
     isIdentified: boolean;
 }
+type BundleMode = 'factored' | 'joint';
+interface Bundle {
+    id: string;
+    name: string;
+    description?: string;
+    status: ExperimentStatus;
+    mode: BundleMode;
+    funnelId?: string;
+    assignmentTtl: number;
+    conversionWindowMs: number;
+    companyId: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface BundleAssignmentRequest {
+    bundleId: string;
+    userId: string;
+    context?: ContextualFeatures;
+    sessionId?: string;
+    pageUrl?: string;
+}
+interface BundleSlotAssignment {
+    assignmentId: string;
+    experimentId: string;
+    treatmentId: string;
+    config: VariantConfig | Record<string, unknown>;
+}
+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[];
+}
+interface CompanySnapshot {
+    ttl: number;
+    generatedAt: number;
+    experiments: Record<string, SnapshotExperiment>;
+}
 
 declare function generateId(): string;
 declare function validateTreatmentWeights(treatments: Treatment[]): boolean;
@@ -265,6 +456,369 @@ declare function extractSubdomain(hostname: string, baseDomain: string): string
  */
 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 = {
+    valid: true;
+    payload: Required<EmailTokenPayload>;
+} | {
+    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;
+}
+type Bound<T> = T | SlotBinding;
+declare function isSlotBinding(value: unknown): value is SlotBinding;
+interface HeadingBlock {
+    type: 'heading';
+    text: Bound<string>;
+    level?: 1 | 2 | 3;
+    align?: 'left' | 'center' | 'right';
+    color?: Bound<string>;
+}
+interface TextBlock {
+    type: 'text';
+    text: Bound<string>;
+    align?: 'left' | 'center' | 'right';
+    color?: Bound<string>;
+}
+interface ButtonBlock {
+    type: 'button';
+    text: Bound<string>;
+    href: Bound<string>;
+    backgroundColor?: Bound<string>;
+    textColor?: Bound<string>;
+    align?: 'left' | 'center' | 'right';
+}
+interface ImageBlock {
+    type: 'image';
+    src: Bound<string>;
+    alt: Bound<string>;
+    href?: Bound<string>;
+    width?: number;
+}
+interface DividerBlock {
+    type: 'divider';
+    color?: string;
+}
+interface SpacerBlock {
+    type: 'spacer';
+    height?: number;
+}
+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 {
     apiUrl: string;
     apiKey: string;
@@ -326,11 +880,266 @@ declare class BanditsClient {
      * @param value - The payout value (e.g., purchase amount in dollars)
      */
     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;
     private startBatchFlush;
     destroy(): void;
 }
 
-export { type APIResponse, type Account, type AlgorithmResult, type ApiKey, type Assignment, type AssignmentRequest, BanditAlgorithm, BanditsClient as BanditClient, type BanditConfig, type BanditResult, BanditsClient, type BanditsClientConfig, type Company, ContentType, type ContextualFeatures, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateExperimentRequest, type Experiment, type ExperimentStats, ExperimentStatus, type Funnel, type FunnelRewardRequest, FunnelStatus, type IdentifyMergeReason, type IdentifyUserRequest, type IdentifyUserResponse, type ResolvedIdentity, type Session, type TrackNamedEventRequest, type Treatment, type TreatmentMetadata, type TreatmentStats, type User, type VariantConfig, buildSubdomainUrl, calculateConfidenceInterval, extractSubdomain, generateId, generateSubdomain, getContentTypeCategory, isValidEmail, isValidSubdomain, normalizeTreatmentWeights, sanitizeMetadata, validateTreatmentWeights };
+interface SyncAssignment {
+    clientAssignmentId: string;
+    experimentId: string;
+    treatmentId: string;
+    config: unknown;
+}
+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;
+    private storage;
+    private now;
+    private fetchImpl;
+    private snapshot;
+    private queue;
+    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;
+    batchKey?: string;
+}): Promise<{
+    recorded: boolean;
+    alreadyRecorded: boolean;
+}>;
+
+export { type APIResponse, type Account, type AlgorithmResult, type ApiKey, type Assignment, type AssignmentRequest, BanditAlgorithm, BanditsClient as BanditClient, type BanditConfig, type BanditResult, BanditsClient, type BanditsClientConfig, type Bound, type Bundle, type BundleAssignmentRequest, type BundleAssignmentResponse, type BundleMode, type BundleSlotAssignment, type ButtonBlock, type Company, type CompanySnapshot, ContentType, type ContextualFeatures, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateExperimentRequest, DEFAULT_HALF_LIFE_MS, DEFAULT_SESSION_TTL_MS, DEFAULT_WINDOW_MS, type DividerBlock, EMAIL_TOKEN_PARAM, type EmailBlock, type EmailDocument, type EmailPlan, type EmailTokenPayload, type Experiment, type ExperimentStats, ExperimentStatus, type ForgettingConfig, ForgettingMode, type Funnel, type FunnelRewardRequest, FunnelStatus, type HeadingBlock, type IdentifyMergeReason, type IdentifyUserRequest, type IdentifyUserResponse, type ImageBlock, PLACEMENTS, type Placement, type PlanArm, type PlanRenderResult, type PlanSlot, Posterior, type RenderEmailOptions, type RenderedDocument, type RenderedEmail, type ResolvedIdentity, type RewriteOptions, type RewriteResult, SESSION_CREATED_AT_KEY, SESSION_ID_KEY, STATIONARY, type Session, type SessionOptions, type SigningKey, type SlotBinding, SnapshotClient, type SnapshotClientConfig, type SnapshotExperiment, type SnapshotTreatment, type SpacerBlock, type SyncAssignment, type TextBlock, type TrackNamedEventRequest, type Treatment, type TreatmentMetadata, type TreatmentStats, type User, type VariantConfig, type VerifiedToken, appendEmailToken, buildSubdomainUrl, calculateConfidenceInterval, extractDocumentSlots, extractEmailLinks, extractSlotNames, extractSubdomain, generateId, generateSubdomain, getContentTypeCategory, getOrCreateSessionId, hashRecipient, impressionManifest, isSlotBinding, isValidEmail, isValidSubdomain, mintEmailToken, normalizeAlgorithm, normalizePosterior, normalizeTreatmentWeights, pickArm, pickTreatment, renderEmail, renderEmailDocument, renderFromPlan, reportPlanImpressions, resolveForgetting, rewriteEmailLinks, sampleCombination, sanitizeMetadata, shouldRefreshPlan, uniformFor, validateTreatmentWeights, verifyEmailToken };