@runbandit/sdk 3.1.3 → 3.4.0

package/dist/decision-cookie-CNIp56yQ.d.ts

@@ -0,0 +1,503 @@
+declare const STOREFRONT_KINDS: readonly ["text", "image", "ordering", "offer"];
+type StorefrontKind = (typeof STOREFRONT_KINDS)[number];
+declare const PLACEMENTS_BY_KIND: {
+    readonly text: readonly ["hero_headline", "hero_subhead", "cta_primary", "banner_text", "badge_text"];
+    readonly image: readonly ["hero_image", "banner_image", "feature_image"];
+    readonly ordering: readonly ["product_list_primary", "product_list_secondary"];
+    readonly offer: readonly ["offer_banner"];
+};
+type Placement = (typeof PLACEMENTS_BY_KIND)[StorefrontKind][number];
+declare const PLACEMENTS: readonly Placement[];
+declare function isPlacement(value: unknown): value is Placement;
+declare function kindOfPlacement(placement: Placement): StorefrontKind;
+declare const CONTENT_TYPE_BY_KIND: {
+    readonly text: {
+        readonly contentType: "TEXT";
+        readonly contentSubtype: "plain_text";
+    };
+    readonly image: {
+        readonly contentType: "FILE";
+        readonly contentSubtype: "image";
+    };
+    readonly ordering: {
+        readonly contentType: "CODE";
+        readonly contentSubtype: "json";
+    };
+    readonly offer: {
+        readonly contentType: "CODE";
+        readonly contentSubtype: "json";
+    };
+};
+declare const MIN_ORDERING_ITEMS = 2;
+declare const MAX_ORDERING_ITEMS = 12;
+interface ImageContent {
+    url: string;
+    alt: string;
+    width: number;
+    height: number;
+    sourceId: string;
+}
+interface OfferContent {
+    discountId: string;
+    code: string;
+    headline: string;
+    subtext: string;
+}
+type TreatmentContent = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'image';
+    image: ImageContent;
+} | {
+    kind: 'ordering';
+    productIds: string[];
+} | {
+    kind: 'offer';
+    offer: OfferContent | null;
+};
+declare function isShopifyCdnUrl(value: string): boolean;
+declare function parseTreatmentContent(kind: StorefrontKind, config: unknown): TreatmentContent | null;
+declare function serializeTreatmentConfig(content: TreatmentContent): {
+    content: unknown;
+};
+
+declare const SITE_TARGET_KINDS: readonly ["text", "image"];
+type SiteTargetKind = (typeof SITE_TARGET_KINDS)[number];
+interface SiteTarget {
+    page: string;
+    selector: string;
+    tag: string;
+    kind: SiteTargetKind;
+    original: string;
+}
+type FunnelGoal = {
+    kind: 'page';
+    page: string;
+} | {
+    kind: 'click';
+    page: string;
+    selector: string;
+    tag: string;
+    label: string;
+};
+declare function parseSiteContent(config: unknown): string | null;
+declare function normalizeSiteTarget(target: SiteTarget): SiteTarget;
+declare function normalizeFunnelGoal(goal: FunnelGoal): FunnelGoal;
+declare function targetMatchesPage(target: Pick<SiteTarget, 'page'>, pathname: string): boolean;
+declare function goalMatchesPage(goal: Pick<FunnelGoal, 'page'>, pathname: string): boolean;
+declare const MAX_ALTERNATIVES = 5;
+declare const MAX_TEXT_ALTERNATIVE_LENGTH = 300;
+declare const MAX_IMAGE_URL_LENGTH = 2048;
+interface PickDraft {
+    target?: SiteTarget;
+    alternatives: string[];
+    goal?: FunnelGoal;
+}
+interface PickState {
+    funnelId: string;
+    siteHost: string;
+    expiresAt: number;
+    draft: PickDraft;
+    funnelGoal: FunnelGoal | null;
+    experimentId: string | null;
+    runningExperiments: number;
+}
+declare const SUGGESTED_SITE_EXPERIMENTS = 3;
+declare function moreExperimentsSentence(running: number, suggested: number): string;
+type PickStep = 'pick' | 'alternatives' | 'goal' | 'ready' | 'live';
+declare function pickStep(state: Pick<PickState, 'draft' | 'funnelGoal' | 'experimentId'>): PickStep;
+declare function parseAlternative(kind: SiteTargetKind, raw: string): string;
+declare const PICK_CHANNEL = "bandit-pick";
+declare const PICK_PROTOCOL_VERSION = 1;
+declare const PICK_MODES: readonly ["idle", "target", "goal-click"];
+type PickMode = (typeof PICK_MODES)[number];
+declare const PICK_REJECTIONS: readonly ["not-text-or-image", "has-markup", "not-clickable", "no-selector"];
+type PickRejection = (typeof PICK_REJECTIONS)[number];
+type ClickFunnelGoal = Extract<FunnelGoal, {
+    kind: 'click';
+}>;
+type PickerToPanel = {
+    type: 'navigated';
+    page: string;
+} | {
+    type: 'target-picked';
+    target: SiteTarget;
+} | {
+    type: 'goal-picked';
+    goal: ClickFunnelGoal;
+} | {
+    type: 'rejected';
+    reason: PickRejection;
+} | {
+    type: 'cancelled';
+};
+type PanelToPicker = {
+    type: 'hello';
+} | {
+    type: 'mode';
+    mode: PickMode;
+} | {
+    type: 'preview';
+    target: SiteTarget;
+    content: string;
+} | {
+    type: 'clear-preview';
+} | {
+    type: 'finish';
+} | {
+    type: 'renew';
+    token: string;
+};
+declare const PICK_TOKEN_PREFIX = "bpick_";
+interface PickEnvelope<M> {
+    channel: typeof PICK_CHANNEL;
+    v: typeof PICK_PROTOCOL_VERSION;
+    msg: M;
+}
+declare function pickEnvelope<M extends PickerToPanel | PanelToPicker>(msg: M): PickEnvelope<M>;
+declare function parsePickerMessage(data: unknown): PickerToPanel | null;
+declare function parsePanelMessage(data: unknown): PanelToPicker | null;
+
+interface OrderLineItem {
+    id?: string;
+    quantity?: number;
+    price: number;
+    discount?: number;
+    unitCost?: number;
+}
+type OrderAmounts = {
+    lines: OrderLineItem[];
+    shipping?: number;
+    shippingCost?: number;
+} | {
+    revenue: number;
+    cost?: number;
+    shipping?: number;
+    shippingCost?: number;
+};
+
+interface Company {
+    id: string;
+    name: string;
+    subdomain?: string;
+    domain?: string;
+    plan: string;
+    apiKey: string;
+    status: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface User {
+    id: string;
+    email: string;
+    name: string;
+    image?: string;
+    role: string;
+    companyId: string | null;
+    emailVerified?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface Session {
+    id: string;
+    userId: string;
+    token: string;
+    expiresAt: Date;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface Account {
+    id: string;
+    userId: string;
+    provider: string;
+    providerAccountId: string;
+    accessToken?: string;
+    refreshToken?: string;
+    accessTokenExpiresAt?: Date;
+    refreshTokenExpiresAt?: Date;
+    scope?: string;
+    idToken?: string;
+    sessionState?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface Experiment {
+    id: string;
+    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;
+    companyId: string;
+    createdAt: Date;
+    updatedAt: Date;
+    endAt?: Date;
+    placement?: Placement;
+}
+interface Treatment {
+    id: string;
+    experimentId: string;
+    name: string;
+    description?: string;
+    config: VariantConfig;
+    weight?: number;
+    companyId: string;
+    createdAt: Date;
+}
+interface AlgorithmResult {
+    treatmentId: string;
+    confidence: number;
+    probabilityBest?: number;
+}
+interface BanditResult {
+    assignmentId: string;
+    treatmentId: string;
+    confidence: number;
+    probabilityBest?: number;
+    metadata?: Record<string, any>;
+}
+interface ContextualFeatures {
+    [key: string]: string | number | boolean;
+}
+declare enum ExperimentStatus {
+    DRAFT = "draft",
+    ACTIVE = "active",
+    PAUSED = "paused",
+    COMPLETED = "completed",
+    ARCHIVED = "archived"
+}
+interface TreatmentMetadata {
+    strategy?: string;
+    tone?: string;
+    ctaStyle?: string;
+    emotionalHook?: string;
+    reasoning?: string;
+    tags?: string[];
+    generated?: boolean;
+    generatedAt?: string;
+}
+interface VariantConfig {
+    content: string;
+    metadata?: TreatmentMetadata & Record<string, any>;
+}
+declare enum BanditAlgorithm {
+    THOMPSON_SAMPLING = "thompson_sampling",
+    CONTEXTUAL_LINEAR = "contextual_linear"
+}
+declare enum Posterior {
+    BETA = "beta",
+    NORMAL_GAMMA = "normal_gamma"
+}
+declare function normalizePosterior(posterior: string | null | undefined): Posterior;
+declare enum ForgettingMode {
+    NONE = "none",
+    DISCOUNTED = "discounted",
+    SLIDING_WINDOW = "sliding_window"
+}
+interface ForgettingConfig {
+    mode: ForgettingMode;
+    halfLifeMs?: number;
+    windowMs?: number;
+}
+declare const DEFAULT_HALF_LIFE_MS: number;
+declare const DEFAULT_WINDOW_MS: number;
+declare const STATIONARY: ForgettingConfig;
+declare function resolveForgetting(config?: Partial<ForgettingConfig> | null): ForgettingConfig;
+declare function normalizeAlgorithm(algorithm: string | null | undefined): BanditAlgorithm;
+declare enum ContentType {
+    PLAIN_TEXT = "plain_text",
+    MARKDOWN = "markdown",
+    HTML = "html",
+    CSS = "css",
+    JAVASCRIPT = "javascript",
+    JSON = "json",
+    IMAGE = "image",
+    VIDEO = "video",
+    AUDIO = "audio",
+    DOCUMENT = "document"
+}
+declare function getContentTypeCategory(contentType: ContentType): 'text' | 'code' | 'file';
+interface BanditConfig {
+    algorithm: BanditAlgorithm;
+    parameters: Record<string, any>;
+}
+interface ExperimentStats {
+    totalAssignments: number;
+    totalConversions: number;
+    conversionRate: number;
+    treatmentStats: Record<string, TreatmentStats>;
+}
+interface TreatmentStats {
+    assignments: number;
+    conversions: number;
+    conversionRate: number;
+    confidence: number;
+    lift?: number;
+}
+interface APIResponse<T = any> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    timestamp: Date;
+}
+interface CreateExperimentRequest {
+    name: string;
+    description?: string;
+    algorithm: BanditAlgorithm;
+    contentType: ContentType;
+    algorithmConfig?: Record<string, any>;
+    treatments?: Omit<Treatment, 'id' | 'experimentId' | 'createdAt'>[];
+}
+interface AssignmentRequest {
+    experimentId: string;
+    userId: string;
+    context?: ContextualFeatures;
+    sessionId?: string;
+    pageUrl?: string;
+}
+interface TrackNamedEventRequest {
+    name: string;
+    category?: string;
+    value?: number;
+    cost?: number;
+    lineItems?: OrderLineItem[];
+    metadata?: Record<string, any>;
+    sessionId: string;
+    userId?: string;
+    assignmentId?: string;
+}
+declare enum FunnelStatus {
+    DRAFT = "draft",
+    ACTIVE = "active",
+    PAUSED = "paused",
+    COMPLETED = "completed"
+}
+interface Funnel {
+    id: string;
+    name: string;
+    description?: string;
+    status: FunnelStatus;
+    inactivityTimeoutMs?: number;
+    revisionWindowMs?: number;
+    companyId: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface FunnelRewardRequest {
+    funnelId: string;
+    userId: string;
+    value: number;
+}
+interface ApiKey {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    status: 'active' | 'revoked';
+    createdBy: string;
+    createdAt: Date;
+    lastUsedAt?: Date;
+    revokedAt?: Date;
+    revokedBy?: string;
+}
+interface CreateApiKeyRequest {
+    name: string;
+}
+interface CreateApiKeyResponse {
+    id: string;
+    key: string;
+    name: string;
+}
+type IdentifyMergeReason = 'user_signup' | 'email_verification' | 'social_login' | 'account_recovery' | 'manual';
+interface IdentifyUserRequest {
+    anonymousId: string;
+    identifiedUserId: string;
+    mergeReason?: IdentifyMergeReason;
+}
+interface IdentifyUserResponse {
+    anonymousId: string;
+    identifiedUserId: string;
+    alreadyMapped: boolean;
+}
+interface ResolvedIdentity {
+    canonicalId: string;
+    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;
+    inactivityTimeoutMs?: number;
+    revisionWindowMs?: 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>;
+}
+interface SnapshotTreatment {
+    id: string;
+    name?: string;
+    config: unknown;
+    pct: number;
+}
+interface SnapshotExperiment {
+    name?: string;
+    mode: 'snapshot' | 'network';
+    assignmentTtl: number;
+    treatments: SnapshotTreatment[];
+    target?: SiteTarget;
+    funnelId?: string;
+}
+interface CompanySnapshot {
+    ttl: number;
+    generatedAt: number;
+    experiments: Record<string, SnapshotExperiment>;
+    goals?: Record<string, FunnelGoal>;
+}
+
+declare const VISITOR_COOKIE = "bandit_v";
+declare const DECISIONS_COOKIE = "bandit_d";
+interface CookieDecision {
+    experimentId: string;
+    treatmentId: string;
+    clientAssignmentId: string;
+    expiresAt: number;
+}
+type CookieDecisions = Record<string, CookieDecision>;
+declare function readCookie(header: string | null | undefined, name: string): string | null;
+declare function parseDecisions(value: string | null | undefined, now: number): CookieDecisions;
+declare function serializeDecisions(decisions: CookieDecisions): string;
+
+export { type BundleMode as $, type Account as A, type BundleAssignmentResponse as B, type ContextualFeatures as C, DECISIONS_COOKIE as D, type Experiment as E, ForgettingMode as F, type TreatmentStats as G, type APIResponse as H, type CreateExperimentRequest as I, type AssignmentRequest as J, type TrackNamedEventRequest as K, FunnelStatus as L, type Funnel as M, type FunnelRewardRequest as N, type OrderLineItem as O, Posterior as P, type ApiKey as Q, type CreateApiKeyRequest as R, type SnapshotTreatment as S, type Treatment as T, type User as U, VISITOR_COOKIE as V, type CreateApiKeyResponse as W, type IdentifyMergeReason as X, type IdentifyUserRequest as Y, type IdentifyUserResponse as Z, type ResolvedIdentity as _, type CompanySnapshot as a, type Bundle as a0, type BundleAssignmentRequest as a1, type BundleSlotAssignment as a2, STOREFRONT_KINDS as a3, type StorefrontKind as a4, PLACEMENTS_BY_KIND as a5, type Placement as a6, PLACEMENTS as a7, isPlacement as a8, kindOfPlacement as a9, pickStep as aA, parseAlternative as aB, PICK_CHANNEL as aC, PICK_PROTOCOL_VERSION as aD, PICK_MODES as aE, type PickMode as aF, PICK_REJECTIONS as aG, type PickRejection as aH, type ClickFunnelGoal as aI, type PickerToPanel as aJ, type PanelToPicker as aK, PICK_TOKEN_PREFIX as aL, type PickEnvelope as aM, pickEnvelope as aN, parsePickerMessage as aO, parsePanelMessage as aP, type OrderAmounts as aQ, CONTENT_TYPE_BY_KIND as aa, MIN_ORDERING_ITEMS as ab, MAX_ORDERING_ITEMS as ac, type ImageContent as ad, type OfferContent as ae, type TreatmentContent as af, isShopifyCdnUrl as ag, parseTreatmentContent as ah, serializeTreatmentConfig as ai, SITE_TARGET_KINDS as aj, type SiteTargetKind as ak, type SiteTarget as al, type FunnelGoal as am, parseSiteContent as an, normalizeSiteTarget as ao, normalizeFunnelGoal as ap, targetMatchesPage as aq, goalMatchesPage as ar, MAX_ALTERNATIVES as as, MAX_TEXT_ALTERNATIVE_LENGTH as at, MAX_IMAGE_URL_LENGTH as au, type PickDraft as av, type PickState as aw, SUGGESTED_SITE_EXPERIMENTS as ax, moreExperimentsSentence as ay, type PickStep as az, type SnapshotExperiment as b, type CookieDecision as c, type CookieDecisions as d, type Company as e, type Session as f, type AlgorithmResult as g, type BanditResult as h, ExperimentStatus as i, type TreatmentMetadata as j, type VariantConfig as k, BanditAlgorithm as l, type ForgettingConfig as m, normalizePosterior as n, DEFAULT_HALF_LIFE_MS as o, parseDecisions as p, DEFAULT_WINDOW_MS as q, readCookie as r, serializeDecisions as s, STATIONARY as t, resolveForgetting as u, normalizeAlgorithm as v, ContentType as w, getContentTypeCategory as x, type BanditConfig as y, type ExperimentStats as z };