@runbandit/sdk 2.0.0 → 2.1.0

package/README.md

@@ -14,7 +14,7 @@ npm install @runbandit/sdk
 import { BanditsClient } from '@runbandit/sdk'
 
 const client = new BanditsClient({
-  apiUrl: 'https://app.runbandit.com',
+  apiUrl: 'https://runbandit.com',
   apiKey: 'your-api-key',
 })
 
@@ -29,4 +29,6 @@ client.trackNamedEvent({
 })
 ```
 
+**Note:** The SDK automatically adds `/api` to your `apiUrl`, so use the base domain (e.g., `https://runbandit.com`) without the `/api` path. If your `apiUrl` already ends with `/api`, the SDK won't double-prefix it.
+
 See the [SDK docs](https://runbandit.com/docs/sdk) for the full API.

package/dist/index.d.ts

@@ -63,7 +63,10 @@ interface Experiment {
     createdAt: Date;
     updatedAt: Date;
     endAt?: Date;
+    placement?: Placement;
 }
+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;
@@ -77,11 +80,13 @@ interface Treatment {
 interface AlgorithmResult {
     treatmentId: string;
     confidence: number;
+    probabilityBest?: number;
 }
 interface BanditResult {
     assignmentId: string;
     treatmentId: string;
     confidence: number;
+    probabilityBest?: number;
     metadata?: Record<string, any>;
 }
 interface ContextualFeatures {
@@ -108,33 +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"
 }
-/**
- * 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 Posterior {
+    BETA = "beta",
+    NORMAL_GAMMA = "normal_gamma"
+}
+declare function normalizePosterior(posterior: string | null | undefined): Posterior;
 declare enum ForgettingMode {
     NONE = "none",
     DISCOUNTED = "discounted",
@@ -142,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",
@@ -217,6 +186,7 @@ interface AssignmentRequest {
     userId: string;
     context?: ContextualFeatures;
     sessionId?: string;
+    pageUrl?: string;
 }
 interface TrackNamedEventRequest {
     name: string;
@@ -300,6 +270,7 @@ interface BundleAssignmentRequest {
     userId: string;
     context?: ContextualFeatures;
     sessionId?: string;
+    pageUrl?: string;
 }
 interface BundleSlotAssignment {
     assignmentId: string;
@@ -311,33 +282,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[];
 }
@@ -356,35 +308,124 @@ 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;
 
+declare const EMAIL_TOKEN_PARAM = "bt";
+interface SigningKey {
+    version: number;
+    secret: string;
+}
+interface EmailTokenPayload {
+    c: string;
+    r: string;
+    k: number[];
+    l: number;
+    v?: number;
+}
+type VerifiedToken = {
+    valid: true;
+    payload: Required<EmailTokenPayload>;
+} | {
+    valid: false;
+    reason: 'malformed' | 'unknown_key' | 'bad_signature';
+};
+declare function hashRecipient(recipientId: string, companySecret: string): Promise<string>;
+declare function mintEmailToken(payload: EmailTokenPayload, key: SigningKey): Promise<string>;
+declare function verifyEmailToken(token: string, keys: SigningKey[]): Promise<VerifiedToken>;
+declare function appendEmailToken(url: string, token: string): string;
+
+interface PlanArm {
+    treatmentId: string;
+    armIndex: number;
+}
+interface PlanSlot {
+    experimentId: string;
+    name: string;
+    arms: PlanArm[];
+    probabilities: number[];
+    configs: unknown[];
+}
+interface EmailPlan {
+    campaignId: string;
+    slots: PlanSlot[];
+    linkTable: string[];
+    salt: string;
+    signingKey: {
+        version: number;
+        secret: string;
+    };
+    refreshEvery: number;
+    expiresAt: number;
+}
+declare function uniformFor(salt: string, recipientId: string, slotIndex: number): Promise<number>;
+declare function pickArm(probabilities: number[], uniform: number): number;
+declare function sampleCombination(plan: EmailPlan, recipientId: string): Promise<number[]>;
+declare function impressionManifest(plan: EmailPlan, recipientIds: string[]): Promise<Array<{
+    experimentId: string;
+    treatmentId: string;
+    count: number;
+}>>;
+
+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: Bound<string>;
+    preheader?: Bound<string>;
+    blocks: EmailBlock[];
+    backgroundColor?: string;
+    contentWidth?: number;
+}
+declare function extractDocumentSlots(document: EmailDocument): string[];
+interface RenderedDocument {
+    subject: string;
+    html: string;
+    missingSlots: string[];
+}
+declare function renderEmailDocument(document: EmailDocument, slots: Record<string, string>): RenderedDocument;
+
 interface BanditsClientConfig {
     apiUrl: string;
     apiKey: string;
@@ -407,11 +448,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;
@@ -421,34 +457,13 @@ 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;
+    private normalizeApiUrl;
     private getOrCreateSessionId;
     private makeRequest;
     private startBatchFlush;
@@ -464,28 +479,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;
@@ -497,66 +496,70 @@ 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;
 
-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 Bundle, type BundleAssignmentRequest, type BundleAssignmentResponse, type BundleMode, type BundleSlotAssignment, 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 Experiment, type ExperimentStats, ExperimentStatus, type ForgettingConfig, ForgettingMode, type Funnel, type FunnelRewardRequest, FunnelStatus, type IdentifyMergeReason, type IdentifyUserRequest, type IdentifyUserResponse, type ResolvedIdentity, SESSION_CREATED_AT_KEY, SESSION_ID_KEY, STATIONARY, type Session, type SessionOptions, SnapshotClient, type SnapshotClientConfig, type SnapshotExperiment, type SnapshotTreatment, type SyncAssignment, type TrackNamedEventRequest, type Treatment, type TreatmentMetadata, type TreatmentStats, type User, type VariantConfig, buildSubdomainUrl, calculateConfidenceInterval, extractSubdomain, generateId, generateSubdomain, getContentTypeCategory, getOrCreateSessionId, isValidEmail, isValidSubdomain, normalizeAlgorithm, normalizeTreatmentWeights, pickTreatment, resolveForgetting, sanitizeMetadata, validateTreatmentWeights };
+interface RewriteOptions {
+    linkTable: string[];
+    tokens: string[];
+}
+interface RewriteResult {
+    html: string;
+    rewritten: number;
+    untracked: string[];
+}
+declare function extractEmailLinks(html: string): string[];
+declare function rewriteEmailLinks(html: string, options: RewriteOptions): RewriteResult;
+
+interface RenderEmailOptions {
+    slots: Record<string, string>;
+    linkTable: string[];
+    tokens: string[];
+}
+interface RenderedEmail {
+    html: string;
+    rewritten: number;
+    untracked: string[];
+    missingSlots: string[];
+}
+declare function renderEmail(templateHtml: string, options: RenderEmailOptions): RenderedEmail;
+declare function extractSlotNames(templateHtml: string): string[];
+
+interface PlanRenderResult extends RenderedEmail {
+    combination: number[];
+    tokens: string[];
+}
+declare function renderFromPlan(plan: EmailPlan, recipientId: string, templateHtml: string, companySecret: string): Promise<PlanRenderResult>;
+declare function shouldRefreshPlan(plan: EmailPlan, recipientsRenderedSincePlan: number, now?: number): boolean;
+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 };