@fanfare-io/fanfare-sdk-core 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,178 @@
+import { CDPAdapter, CDPAdapterConfig } from '../adapters/types';
+import { AppointmentModule } from '../appointments/types';
+import { AuctionModule } from '../auctions/types';
+import { AuthModule } from '../auth/types';
+import { BeaconConfig, BeaconModule } from '../beacon';
+import { ChallengeModule } from '../challenges/types';
+import { DrawModule } from '../draws/types';
+import { DistributionMonitor } from '../experiences/distribution-monitor.types';
+import { JourneyHandle } from '../experiences/journey.types';
+import { ConsumerMe, ExperienceModule, ResumeJourneysResult } from '../experiences/types';
+import { QueueModule } from '../queues/types';
+import { SDKEvents } from '../state/events';
+import { TimedReleaseModule } from '../timed-releases/types';
+import { WaitlistModule } from '../waitlists/types';
+/**
+ * SDK configuration options
+ */
+export interface FanfareConfig {
+    /**
+     * Your Fanfare organization ID
+     */
+    organizationId: string;
+    /**
+     * Your publishable API key
+     */
+    publishableKey: string;
+    /**
+     * API environment
+     * @default "production"
+     */
+    environment?: "production" | "development";
+    /**
+     * Custom API URL (overrides environment)
+     */
+    apiUrl?: string;
+    /**
+     * Cookie behavior for SDK fetches.
+     *
+     * Defaults to `"include"` so the SDK can use HttpOnly refresh-token
+     * cookies for cross-origin consumer API calls.
+     *
+     * Set to `"same-origin"` when the SDK runs behind a same-origin proxy, or
+     * `"omit"` for a strictly token-based deployment that should never send
+     * cookies.
+     *
+     * @default "include"
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Enable debug mode
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Authentication configuration
+     */
+    auth?: {
+        /**
+         * Whether to persist sessions in storage
+         * @default true
+         */
+        persistSession?: boolean;
+        /**
+         * Session duration in seconds
+         * @default 3600 (1 hour)
+         */
+        sessionDuration?: number;
+    };
+    /**
+     * Logging configuration
+     */
+    logging?: {
+        /**
+         * Log level
+         * @default "error"
+         */
+        level?: "error" | "warn" | "info" | "debug" | "metrics";
+    };
+    /**
+     * Inter-tab synchronization configuration
+     */
+    sync?: boolean | {
+        /**
+         * Whether sync is enabled
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Custom channel name for BroadcastChannel
+         * @default "fanfare-sdk-sync"
+         */
+        channelName?: string;
+    };
+    /**
+     * Feature flags for optional functionality
+     */
+    features?: {
+        /**
+         * Enable browser fingerprinting for device identification
+         * Can be disabled for privacy compliance or troubleshooting
+         * @default true
+         */
+        fingerprinting?: boolean;
+    };
+    /**
+     * Beacon event tracking configuration
+     */
+    beacon?: BeaconConfig;
+}
+/**
+ * Journey registry and resurrection APIs.
+ */
+export interface JourneysModule {
+    /**
+     * Create (or retrieve) a journey handle for the given experience.
+     * Restores any locally persisted journey snapshot for that experience.
+     */
+    get(experienceId: string): JourneyHandle;
+    /**
+     * List experience IDs with known journey state or active handles.
+     */
+    list(): string[];
+    /**
+     * Reconcile journeys from local durable state and `/consumers/me`.
+     */
+    resumeAll(me?: ConsumerMe): Promise<ResumeJourneysResult>;
+}
+/**
+ * Main public SDK interface.
+ */
+export interface FanfareSDK {
+    /**
+     * Authentication module
+     */
+    readonly auth: AuthModule;
+    /**
+     * Challenge module - bot prevention / human verification
+     */
+    readonly challenges: ChallengeModule;
+    /**
+     * Journey registry and resurrection APIs
+     */
+    readonly journeys: JourneysModule;
+    /**
+     * Beacon event tracking module - client-side analytics
+     */
+    readonly beacon: BeaconModule;
+    readonly appointments: AppointmentModule;
+    /**
+     * Register a CDP adapter (e.g. Google Analytics)
+     */
+    use(adapter: CDPAdapter, config?: CDPAdapterConfig): void;
+    /**
+     * Subscribe to SDK events
+     */
+    on<K extends keyof SDKEvents>(event: K, handler: (data: SDKEvents[K]) => void): () => void;
+    /**
+     * Clean up and destroy SDK instance
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Internal browser runtime surface used by the journey state machine and first-party adapters.
+ * Not re-exported from the package root.
+ */
+export interface InternalFanfareSDK extends FanfareSDK {
+    readonly queues: QueueModule & DistributionMonitor;
+    readonly draws: DrawModule & DistributionMonitor;
+    readonly auctions: AuctionModule & DistributionMonitor;
+    readonly appointments: AppointmentModule & DistributionMonitor;
+    readonly waitlists: WaitlistModule;
+    readonly timedReleases: TimedReleaseModule & DistributionMonitor;
+    readonly experiences: ExperienceModule & {
+        get(experienceId: string): Promise<import('../experiences/types').ExperienceDetails>;
+        createJourney(experienceId: string): JourneyHandle;
+        resumeJourneysFromMe(me?: ConsumerMe): Promise<ResumeJourneysResult>;
+    };
+}

package/dist/utils/fingerprint.module.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser fingerprinting module for Fanfare SDK
+ * Generates a unique fingerprint based on various browser characteristics
+ */
+/**
+ * Browser fingerprint interface containing various identifying components
+ */
+export interface BrowserFingerprint {
+    canvas: string;
+    webgl: string;
+    timezone: string;
+    userAgent: string;
+    screenResolution: string;
+    language: string;
+    hash: string;
+}
+/**
+ * Generate a browser fingerprint with multiple identifying components
+ * @returns Promise resolving to BrowserFingerprint object
+ */
+export declare function generateFingerprint(): Promise<BrowserFingerprint>;
+/**
+ * Generate a synchronous browser fingerprint (without async hash)
+ * Uses simple hash instead of crypto.subtle
+ * @returns BrowserFingerprint object with simple hash
+ */
+export declare function generateFingerprintSync(): BrowserFingerprint;

package/dist/utils/fingerprint.module.js

@@ -0,0 +1 @@
+import{isBrowser as t}from"../core/utils.js";function e(){if(!t())return"";try{const t=document.createElement("canvas"),e=t.getContext("2d");return e?(t.width=200,t.height=50,e.font="14px Arial",e.textBaseline="top",e.fillText("Fanfare SDK 🎫",2,2),e.fillStyle="rgba(102, 204, 0, 0.7)",e.fillRect(100,5,50,20),t.toDataURL()):""}catch{return""}}function n(){if(!t())return"";try{const t=document.createElement("canvas"),e=t.getContext("webgl")||t.getContext("experimental-webgl");if(!e)return"";const n=e.getExtension("WEBGL_debug_renderer_info");if(!n)return"";const r=e.getParameter(n.UNMASKED_VENDOR_WEBGL);return`${r}~${e.getParameter(n.UNMASKED_RENDERER_WEBGL)}`}catch{return""}}function r(){if(!t())return"";try{return Intl.DateTimeFormat().resolvedOptions().timeZone||""}catch{return""}}function i(){if(!t())return"";try{return navigator.userAgent||""}catch{return""}}function o(){if(!t())return"";try{if(!window.screen)return"";const t=window.screen.width,e=window.screen.height,n=window.screen.colorDepth;return void 0===t||void 0===e||void 0===n?"":`${t}x${e}x${n}`}catch{return""}}function c(){if(!t())return"";try{return navigator.language||""}catch{return""}}async function u(e){if(!t()||!window.crypto?.subtle)return a(JSON.stringify(e));try{const t=JSON.stringify(e),n=(new TextEncoder).encode(t);return function(t){const e=new Uint8Array(t),n=[];for(let r=0;r<e.length;r++){const t=e[r].toString(16);n.push(1===t.length?"0"+t:t)}return n.join("")}(await crypto.subtle.digest("SHA-256",n))}catch{return a(JSON.stringify(e))}}function a(t){let e=0;for(let n=0;n<t.length;n++){e=(e<<5)-e+t.charCodeAt(n),e&=e}return Math.abs(e).toString(16)}async function s(){const t={canvas:e(),webgl:n(),timezone:r(),userAgent:i(),screenResolution:o(),language:c()},a=await u(t);return{...t,hash:a}}function g(){const t={canvas:e(),webgl:n(),timezone:r(),userAgent:i(),screenResolution:o(),language:c()},u=a(JSON.stringify(t));return{...t,hash:u}}export{s as generateFingerprint,g as generateFingerprintSync};

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Utils module exports
+ */
+export * from './fingerprint.module';

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SDK version
+ * This is automatically updated during the build process
+ */
+export declare const version = "0.1.0";

package/dist/version.js

@@ -0,0 +1 @@
+const o="0.1.0";export{o as version};

package/dist/waitlists/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export { WaitlistManagementModule } from './waitlist.module';

package/dist/waitlists/public.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Public waitlist surface. The runtime `WaitlistManagementModule` from `./types`
+ * is internal and not exported here.
+ */
+export { WaitlistClosedError } from './types';
+export type { WaitlistEntry, WaitlistStatus } from './types';

package/dist/waitlists/public.js

@@ -0,0 +1 @@
+import{WaitlistClosedError as o}from"./types.js";export{o as WaitlistClosedError};

package/dist/waitlists/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Waitlist Module Types
+ * Simple notification signup system - NOT flow control or position tracking
+ */
+/**
+ * API response when checking waitlist status
+ */
+export interface WaitlistStatus {
+    waitlistId: string;
+    sequenceId?: string;
+    isEntered: boolean;
+    enteredAt?: string;
+}
+/**
+ * API response when entering a waitlist
+ */
+export interface WaitlistEntry {
+    id: string;
+    waitlistId: string;
+    sequenceId: string;
+    consumerId: string;
+    enteredAt: string;
+}
+/**
+ * Error thrown when waitlist is closed
+ */
+export declare class WaitlistClosedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Waitlist module interface
+ */
+export interface WaitlistModule {
+    /**
+     * Enter a waitlist for notifications
+     */
+    enter(waitlistId: string, options?: import('../core/http').RequestOptions): Promise<WaitlistEntry>;
+    /**
+     * Leave a specific waitlist
+     */
+    leave(waitlistId: string, options?: import('../core/http').RequestOptions): Promise<void>;
+    /**
+     * Check if user is on a waitlist
+     */
+    getStatus(waitlistId: string): Promise<WaitlistStatus>;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}

package/dist/waitlists/types.js

@@ -0,0 +1 @@
+class r extends Error{constructor(r){super(r),this.name="WaitlistClosedError"}}export{r as WaitlistClosedError};

package/dist/waitlists/waitlist.module.d.ts

@@ -0,0 +1,17 @@
+import { HttpClient } from '../core/http';
+import { WaitlistEntry, WaitlistModule, WaitlistStatus } from './types';
+/**
+ * Waitlist Management Module
+ * Simple notification signup system - NOT flow control or position tracking
+ */
+export declare class WaitlistManagementModule implements WaitlistModule {
+    private readonly http;
+    private readonly logger;
+    private get store();
+    private readonly events;
+    constructor(http: HttpClient);
+    enter(waitlistId: string, options?: import('../core/http').RequestOptions): Promise<WaitlistEntry>;
+    leave(waitlistId: string, options?: import('../core/http').RequestOptions): Promise<void>;
+    getStatus(waitlistId: string): Promise<WaitlistStatus>;
+    destroy(): void;
+}

package/dist/waitlists/waitlist.module.js

@@ -0,0 +1 @@
+import{createError as t}from"../core/errors.js";import{getLogger as e}from"../core/logger.js";import{generateId as s}from"../core/utils.js";import{getEventBus as i}from"../state/events.js";import{getSDKStore as r}from"../state/store.js";import{WaitlistClosedError as o}from"./types.js";class a{constructor(t){this.logger=e(),this.events=i(),this.http=t}get store(){return r()}async enter(e,i){try{if(!this.store.session)throw t.unauthorized("Not authenticated. Call auth.guest() or auth.login() first");this.logger.info("Entering waitlist",{waitlistId:e});const s=await this.http.post(`/waitlists/${e}/enter`,void 0,i);return this.events.emit("waitlist:entered",{waitlistId:e,sequenceId:s.sequenceId,enteredAt:s.enteredAt}),s}catch(r){if(r&&"object"==typeof r&&"message"in r){const t=r.message.toLowerCase();if(t.includes("already on list")||t.includes("already entered")||t.includes("already joined")){this.logger.info("Waitlist entry already exists",{waitlistId:e});const t=await this.getStatus(e);return{id:s(),waitlistId:e,sequenceId:t.sequenceId??"",consumerId:this.store.session?.consumerId||"unknown",enteredAt:t.enteredAt||/* @__PURE__ */(new Date).toISOString()}}if(t.includes("waitlist closed")||t.includes("not accepting")){const t=new o("Waitlist is no longer accepting entries");throw this.logger.error("Waitlist closed",{waitlistId:e}),this.events.emit("waitlist:error",{waitlistId:e,error:t.message}),t}}throw this.logger.error("Failed to enter waitlist",{waitlistId:e,error:r}),this.events.emit("waitlist:error",{waitlistId:e,error:r instanceof Error?r.message:"Unknown error"}),r}}async leave(t,e){try{this.logger.info("Leaving waitlist",{waitlistId:t}),await this.http.delete(`/waitlists/${t}/leave`,e),this.events.emit("waitlist:left",{waitlistId:t})}catch(s){throw this.logger.error("Failed to leave waitlist",{waitlistId:t,error:s}),this.events.emit("waitlist:error",{waitlistId:t,error:s instanceof Error?s.message:"Unknown error"}),s}}async getStatus(t){try{return await this.http.get(`/waitlists/${t}/status`)}catch(e){if(e&&"object"==typeof e&&"status"in e&&404===e.status)return{waitlistId:t,isEntered:!1};throw this.logger.error("Failed to get waitlist status",{waitlistId:t,error:e}),this.events.emit("waitlist:error",{waitlistId:t,error:e instanceof Error?e.message:"Unknown error"}),e}}destroy(){this.logger.debug("WaitlistManagementModule destroyed")}}export{a as WaitlistManagementModule};

package/package.json

@@ -0,0 +1,205 @@
+{
+  "name": "@fanfare-io/fanfare-sdk-core",
+  "version": "0.1.0",
+  "description": "Official Fanfare Browser SDK for queue, draw, auction, and appointment experiences",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fanfare-io/fanfare-sdk.git"
+  },
+  "homepage": "https://docs.fanfare.io/sdk/core/quickstart",
+  "bugs": {
+    "url": "https://github.com/fanfare-io/fanfare-sdk/issues"
+  },
+  "type": "module",
+  "files": [
+    "dist/",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/stats.html",
+    "README.md",
+    "LICENSE"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./queues": {
+      "types": "./dist/queues/index.d.ts",
+      "import": "./dist/queues/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js"
+    },
+    "./experiences": {
+      "types": "./dist/experiences/public.d.ts",
+      "import": "./dist/experiences/public.js"
+    },
+    "./challenges": {
+      "types": "./dist/challenges/public.d.ts",
+      "import": "./dist/challenges/public.js"
+    },
+    "./appointments": {
+      "types": "./dist/appointments/public.d.ts",
+      "import": "./dist/appointments/public.js"
+    },
+    "./beacon": {
+      "types": "./dist/beacon/public.d.ts",
+      "import": "./dist/beacon/public.js"
+    },
+    "./theme": {
+      "types": "./dist/theme.d.ts",
+      "import": "./dist/theme.js"
+    },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js"
+    },
+    "./internals": {
+      "types": "./dist/internals.d.ts",
+      "import": "./dist/internals.js"
+    },
+    "./test-utils": {
+      "types": "./dist/test-utils/index.d.ts",
+      "import": "./dist/test-utils/index.js"
+    },
+    "./test-utils/vitest": {
+      "types": "./dist/test-utils/mock-sdk-vitest.d.ts",
+      "import": "./dist/test-utils/mock-sdk-vitest.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./handoff": {
+      "types": "./dist/handoff/index.d.ts",
+      "import": "./dist/handoff/index.js"
+    },
+    "./draws": {
+      "types": "./dist/draws/public.d.ts",
+      "import": "./dist/draws/public.js"
+    },
+    "./auctions": {
+      "types": "./dist/auctions/public.d.ts",
+      "import": "./dist/auctions/public.js"
+    },
+    "./waitlists": {
+      "types": "./dist/waitlists/public.d.ts",
+      "import": "./dist/waitlists/public.js"
+    },
+    "./timed-releases": {
+      "types": "./dist/timed-releases/public.d.ts",
+      "import": "./dist/timed-releases/public.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "big.js": "^7.0.1",
+    "nanostores": "^1.1.0",
+    "uuid": "^14.0.0",
+    "wretch": "^2.11.0",
+    "zustand": "^5.0.6",
+    "@fanfare-io/fanfare-sdk-contracts": "0.1.0"
+  },
+  "peerDependencies": {
+    "valibot": "^1.1.0",
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^5.0.1",
+    "@size-limit/preset-small-lib": "^11.1.8",
+    "@storybook/addon-docs": "^10.2.16",
+    "@storybook/addon-onboarding": "^10.2.16",
+    "@storybook/addon-vitest": "^10.2.16",
+    "@storybook/react-vite": "^10.2.16",
+    "@types/big.js": "^6.2.2",
+    "@types/node": "^24.1.0",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "@types/uuid": "^10.0.0",
+    "@vitest/browser": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "jsdom": "^26.1.0",
+    "playwright": "^1.51.1",
+    "prettier": "^3.5.3",
+    "prettier-plugin-organize-imports": "^4.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "rimraf": "^6.0.1",
+    "rollup-plugin-visualizer": "^5.14.0",
+    "size-limit": "^11.1.8",
+    "storybook": "^10.2.16",
+    "terser": "^5.46.1",
+    "typescript": "^5.9.2",
+    "valibot": "^1.1.0",
+    "vite": "^7.3.1",
+    "vite-bundle-visualizer": "^1.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4",
+    "@fanfare-io/shared-models": "0.1.0"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "fanfare",
+    "queue",
+    "waitlist",
+    "ecommerce",
+    "sdk",
+    "browser",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "size-limit": [
+    {
+      "name": "Core + Queues",
+      "path": "dist/index.js",
+      "limit": "42 KB"
+    }
+  ],
+  "scripts": {
+    "build": "vite build && pnpm size",
+    "build:deps": "vite build --emptyOutDir false",
+    "build:incremental": "vite build --emptyOutDir false",
+    "build:dist": "rimraf dist && vite build",
+    "build:strict": "pnpm typecheck && pnpm build",
+    "build-storybook": "storybook build",
+    "dev": "vite build --watch",
+    "fmt": "prettier src --write",
+    "lint": "oxlint src",
+    "lint:fix": "oxlint --fix src",
+    "prebuild": "rimraf dist",
+    "prebuild-storybook": "pnpm typecheck",
+    "size": "size-limit",
+    "storybook": "storybook dev -p 6007 --no-open",
+    "build:test-deps": "pnpm --filter @fanfare-io/fanfare-sdk-contracts run build:incremental",
+    "test": "pnpm build:test-deps && vitest run",
+    "test:debug": "NODE_OPTIONS='--expose-gc' vitest run --reporter=verbose",
+    "test:ci": "pnpm build:test-deps && vitest run --reporter=verbose --coverage",
+    "test:watch": "vitest",
+    "test:unit": "pnpm build:test-deps && vitest run .unit.test.ts --passWithNoTests",
+    "test:integration": "pnpm build:test-deps && vitest run .integration.test.ts --passWithNoTests",
+    "test:contract": "pnpm build:test-deps && vitest run .contract.test.ts --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}