@gamifyio/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,778 @@
+/**
+ * Configuration options for the Gamify SDK
+ */
+interface GamifyConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the API endpoint */
+    endpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Flush interval in milliseconds (default: 10000) */
+    flushInterval?: number;
+    /** Maximum events to batch before auto-flush (default: 10) */
+    maxBatchSize?: number;
+    /** Storage key prefix (default: 'gamify_') */
+    storagePrefix?: string;
+}
+/**
+ * Event payload structure
+ */
+interface GamifyEvent {
+    /** Event type (e.g., 'page_view', 'click', 'purchase') */
+    type: string;
+    /** Event properties */
+    properties?: Record<string, unknown>;
+    /** Timestamp when event occurred */
+    timestamp: string;
+    /** User ID if identified */
+    userId?: string;
+    /** Anonymous ID for unidentified users */
+    anonymousId: string;
+}
+/**
+ * User traits for identify calls
+ */
+interface UserTraits {
+    email?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Internal queued event with metadata
+ */
+interface QueuedEvent {
+    id: string;
+    event: GamifyEvent;
+    attempts: number;
+    createdAt: number;
+}
+/**
+ * API response structure
+ */
+interface ApiResponse {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Storage interface for persistence layer
+ */
+interface StorageAdapter {
+    get<T>(key: string): T | null;
+    set<T>(key: string, value: T): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/**
+ * Cart item structure for sessions
+ */
+interface CartItem {
+    sku: string;
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    category?: string;
+    brand?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Session request to create/update cart
+ */
+interface SessionRequest {
+    userId: string;
+    items: CartItem[];
+    coupons?: string[];
+    currency?: string;
+}
+/**
+ * Applied effect from rule engine
+ */
+interface AppliedEffect {
+    type: string;
+    ruleId?: string;
+    params: Record<string, unknown>;
+    discountAmount?: number;
+}
+/**
+ * Session response from API
+ */
+interface SessionResponse {
+    sessionToken: string;
+    items: CartItem[];
+    subtotal: number;
+    discount: number;
+    total: number;
+    coupons: string[];
+    appliedEffects: AppliedEffect[];
+    rejectedCoupons?: string[];
+    currency: string;
+    status: string;
+}
+/**
+ * Loyalty tier information
+ */
+interface LoyaltyTier {
+    id: string;
+    name: string;
+    level: number;
+    benefits: Record<string, unknown>;
+    color?: string | null;
+    iconUrl?: string | null;
+}
+/**
+ * Next tier information
+ */
+interface NextTierInfo {
+    id: string;
+    name: string;
+    minPoints: number;
+    pointsNeeded: number;
+}
+/**
+ * Loyalty summary statistics
+ */
+interface LoyaltySummary {
+    totalEarned: number;
+    totalRedeemed: number;
+    transactionCount: number;
+}
+/**
+ * Customer loyalty profile
+ */
+interface LoyaltyProfile {
+    userId: string;
+    points: number;
+    tier: LoyaltyTier | null;
+    nextTier: NextTierInfo | null;
+    summary: LoyaltySummary;
+}
+/**
+ * Loyalty transaction entry
+ */
+interface LoyaltyTransaction {
+    id: string;
+    amount: number;
+    balance: number;
+    type: 'earn' | 'redeem' | 'expire' | 'adjust' | 'bonus';
+    referenceId?: string;
+    referenceType?: string;
+    description?: string;
+    createdAt: string;
+}
+/**
+ * Loyalty history response
+ */
+interface LoyaltyHistoryResponse {
+    transactions: LoyaltyTransaction[];
+    total: number;
+}
+/**
+ * Affiliate tier/plan information
+ */
+interface AffiliateTier {
+    id: string;
+    name: string;
+    type: 'PERCENTAGE' | 'FIXED';
+    value: number;
+}
+/**
+ * Referral information
+ */
+interface ReferralInfo {
+    id: string;
+    referredExternalId: string;
+    referralCode: string;
+    createdAt: string;
+}
+/**
+ * Affiliate earnings summary
+ */
+interface AffiliateEarnings {
+    totalEarned: number;
+    totalPending: number;
+    totalPaid: number;
+    transactionCount: number;
+    currency: string;
+}
+/**
+ * Affiliate statistics profile
+ */
+interface AffiliateStats {
+    userId: string;
+    referralCode: string | null;
+    referralCount: number;
+    earnings: AffiliateEarnings;
+    tier: AffiliateTier | null;
+}
+/**
+ * Affiliate stats API response
+ */
+interface AffiliateStatsResponse {
+    stats: AffiliateStats;
+}
+/**
+ * Leaderboard entry
+ */
+interface LeaderboardEntry {
+    rank: number;
+    userId: string;
+    displayName?: string;
+    referralCount: number;
+    totalEarnings: number;
+    tier?: AffiliateTier | null;
+}
+/**
+ * Leaderboard response
+ */
+interface LeaderboardResponse {
+    entries: LeaderboardEntry[];
+    total: number;
+    currentUserRank?: number;
+}
+/**
+ * Quest step definition
+ */
+interface QuestStep {
+    id: string;
+    name: string;
+    description?: string;
+    eventName: string;
+    requiredCount: number;
+    order: number;
+    currentCount: number;
+    completed: boolean;
+}
+/**
+ * Quest with user progress
+ */
+interface QuestWithProgress {
+    id: string;
+    name: string;
+    description?: string;
+    xpReward: number;
+    badgeReward?: string;
+    status: 'not_started' | 'in_progress' | 'completed';
+    percentComplete: number;
+    steps: QuestStep[];
+    startedAt?: string;
+    completedAt?: string;
+}
+/**
+ * Quests response from API
+ */
+interface QuestsResponse {
+    quests: QuestWithProgress[];
+}
+/**
+ * Streak milestone definition
+ */
+interface StreakMilestone {
+    day: number;
+    rewardXp: number;
+    badgeId?: string;
+    reached: boolean;
+}
+/**
+ * User streak with progress
+ */
+interface StreakWithProgress {
+    id: string;
+    name: string;
+    description?: string;
+    eventType: string;
+    frequency: string;
+    currentCount: number;
+    maxStreak: number;
+    status: string;
+    lastActivityDate?: string;
+    freezeInventory: number;
+    freezeUsedToday: boolean;
+    nextMilestone?: {
+        day: number;
+        rewardXp: number;
+        badgeId?: string;
+    };
+    milestones: StreakMilestone[];
+}
+/**
+ * Streaks response from API
+ */
+interface StreaksResponse {
+    streaks: StreakWithProgress[];
+    stats: {
+        totalActive: number;
+        longestCurrent: number;
+        longestEver: number;
+    };
+}
+/**
+ * Freeze response
+ */
+interface FreezeResponse {
+    success: boolean;
+    remainingFreezes: number;
+    message: string;
+}
+/**
+ * Badge rarity levels
+ */
+type BadgeRarity = 'COMMON' | 'RARE' | 'EPIC' | 'LEGENDARY';
+/**
+ * Badge with unlock status
+ */
+interface BadgeWithStatus {
+    id: string;
+    name: string;
+    description?: string;
+    iconUrl?: string;
+    imageUrl?: string;
+    rarity: BadgeRarity;
+    visibility: 'PUBLIC' | 'HIDDEN';
+    category?: string;
+    isUnlocked: boolean;
+    unlockedAt?: string;
+}
+/**
+ * Badges response from API
+ */
+interface BadgesResponse {
+    badges: BadgeWithStatus[];
+    stats: {
+        total: number;
+        unlocked: number;
+        byRarity: Record<string, {
+            total: number;
+            unlocked: number;
+        }>;
+    };
+}
+/**
+ * Reward item from store
+ */
+interface RewardItem {
+    id: string;
+    name: string;
+    description?: string;
+    pointsCost: number;
+    imageUrl?: string;
+    category?: string;
+    stock?: number;
+    requiredBadgeId?: string;
+    requiredBadgeName?: string;
+    canAfford: boolean;
+    hasBadge: boolean;
+    isAvailable: boolean;
+}
+/**
+ * Rewards store response
+ */
+interface RewardsStoreResponse {
+    items: RewardItem[];
+    userPoints: number;
+}
+/**
+ * Redemption result
+ */
+interface RedemptionResult {
+    success: boolean;
+    transactionId?: string;
+    message: string;
+    remainingPoints?: number;
+}
+
+interface HttpResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * HTTP client for sending events to the API
+ * Uses fetch with keepalive for reliable delivery during page unload
+ */
+declare class HttpClient {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly debug;
+    constructor(endpoint: string, apiKey: string, debug?: boolean);
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Generic GET request
+     */
+    get<T>(path: string): Promise<HttpResponse<T>>;
+    /**
+     * Generic POST request
+     */
+    post<T>(path: string, body: unknown): Promise<HttpResponse<T>>;
+    /**
+     * Send a batch of events to the API
+     */
+    sendEvents(events: GamifyEvent[]): Promise<ApiResponse>;
+    /**
+     * Send a single event using beacon API (for page unload)
+     * Falls back to fetch if beacon is not available
+     */
+    sendBeacon(events: GamifyEvent[]): boolean;
+}
+
+/**
+ * SessionManager - Manages cart sessions with discount calculations
+ */
+declare class SessionManager {
+    private readonly client;
+    private readonly storage;
+    private readonly debug;
+    private sessionToken;
+    private cachedSession;
+    constructor(config: Required<GamifyConfig>, client: HttpClient, storage: StorageAdapter);
+    /**
+     * Create or update a session with cart items
+     */
+    updateCart(userId: string, items: CartItem[], coupons?: string[], currency?: string): Promise<SessionResponse>;
+    /**
+     * Get current session by token
+     */
+    getSession(): Promise<SessionResponse | null>;
+    /**
+     * Apply a coupon to the current session
+     */
+    applyCoupon(code: string): Promise<SessionResponse>;
+    /**
+     * Complete the session (checkout)
+     */
+    complete(): Promise<SessionResponse>;
+    /**
+     * Clear the current session
+     */
+    clearSession(): void;
+    /**
+     * Get cached session data
+     */
+    getCachedSession(): SessionResponse | null;
+    /**
+     * Get current session token
+     */
+    getSessionToken(): string | null;
+    /**
+     * Check if there's an active session
+     */
+    hasActiveSession(): boolean;
+    private log;
+}
+
+/**
+ * LoyaltyManager - Manages customer loyalty points and tiers
+ */
+declare class LoyaltyManager {
+    private readonly client;
+    private readonly storage;
+    private readonly debug;
+    private cachedProfile;
+    constructor(config: Required<GamifyConfig>, client: HttpClient, storage: StorageAdapter);
+    /**
+     * Get customer loyalty profile
+     */
+    getProfile(userId: string): Promise<LoyaltyProfile>;
+    /**
+     * Get customer transaction history
+     */
+    getHistory(userId: string, limit?: number, offset?: number): Promise<LoyaltyHistoryResponse>;
+    /**
+     * Get cached loyalty profile
+     */
+    getCachedProfile(): LoyaltyProfile | null;
+    /**
+     * Get current points balance from cache
+     */
+    getPoints(): number;
+    /**
+     * Get current tier from cache
+     */
+    getTier(): LoyaltyProfile['tier'];
+    /**
+     * Get next tier info from cache
+     */
+    getNextTier(): LoyaltyProfile['nextTier'];
+    /**
+     * Clear cached profile
+     */
+    clearCache(): void;
+    /**
+     * Refresh profile from server
+     */
+    refresh(userId: string): Promise<LoyaltyProfile>;
+    private log;
+}
+
+/**
+ * Referral Manager - Handles URL parameter detection and referrer storage
+ *
+ * Automatically detects `?ref=code` parameter from URLs and stores
+ * the referrer code in localStorage for attribution tracking.
+ */
+declare class ReferralManager {
+    private readonly config;
+    private readonly storage;
+    private referrerCode;
+    constructor(config: Required<GamifyConfig>, storage: StorageAdapter);
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Detect referrer code from current URL
+     * Looks for `?ref=` parameter
+     */
+    detectReferrerFromUrl(): string | null;
+    /**
+     * Manually set the referrer code
+     */
+    setReferrer(code: string): void;
+    /**
+     * Get the current referrer code
+     */
+    getReferrer(): string | null;
+    /**
+     * Check if a referrer code is present
+     */
+    hasReferrer(): boolean;
+    /**
+     * Clear the referrer code
+     */
+    clearReferrer(): void;
+    /**
+     * Get referrer data to include in event properties
+     */
+    getReferrerProperties(): Record<string, unknown>;
+}
+
+/**
+ * Affiliate Manager - Handles fetching affiliate stats and leaderboard
+ */
+declare class AffiliateManager {
+    private readonly config;
+    private readonly client;
+    private readonly storage;
+    private cachedStats;
+    private lastFetchTime;
+    constructor(config: Required<GamifyConfig>, client: HttpClient, storage: StorageAdapter);
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Get affiliate stats for the current user
+     * @param userId - User ID to fetch stats for
+     * @param forceRefresh - Force refresh from API
+     */
+    getStats(userId: string, forceRefresh?: boolean): Promise<AffiliateStats>;
+    /**
+     * Get cached affiliate stats (if available)
+     */
+    getCachedStats(): AffiliateStats | null;
+    /**
+     * Get leaderboard data
+     * @param limit - Number of entries to fetch (default: 10)
+     */
+    getLeaderboard(limit?: number): Promise<LeaderboardResponse>;
+    /**
+     * Clear cached affiliate stats
+     */
+    clearCache(): void;
+}
+
+/**
+ * Gamify SDK - Framework-agnostic event tracking
+ */
+declare class Gamify {
+    private readonly config;
+    private readonly storage;
+    private readonly queue;
+    private readonly client;
+    private readonly _session;
+    private readonly _loyalty;
+    private readonly _referral;
+    private readonly _affiliate;
+    private flushTimer;
+    private anonymousId;
+    private userId;
+    private userTraits;
+    private initialized;
+    constructor(config: GamifyConfig);
+    /**
+     * Initialize the SDK
+     */
+    private initialize;
+    /**
+     * Log debug messages
+     */
+    private log;
+    /**
+     * Start the automatic flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Handle page unload - send remaining events via beacon
+     */
+    private onBeforeUnload;
+    /**
+     * Identify a user with optional traits
+     * User ID persists across page reloads
+     */
+    identify(userId: string, traits?: UserTraits): void;
+    /**
+     * Track an event
+     */
+    track(eventType: string, properties?: Record<string, unknown>): void;
+    /**
+     * Flush pending events to the server
+     */
+    flush(): Promise<void>;
+    /**
+     * Reset the SDK state (logout user)
+     */
+    reset(): void;
+    /**
+     * Get current user ID (null if not identified)
+     */
+    getUserId(): string | null;
+    /**
+     * Get anonymous ID
+     */
+    getAnonymousId(): string;
+    /**
+     * Get pending event count
+     */
+    getPendingCount(): number;
+    /**
+     * Shutdown the SDK gracefully
+     */
+    shutdown(): void;
+    /**
+     * Get the session manager
+     */
+    get session(): SessionManager;
+    /**
+     * Convenience method: Update cart and get discounts
+     */
+    updateCart(items: CartItem[], coupons?: string[], currency?: string): Promise<SessionResponse>;
+    /**
+     * Get the loyalty manager
+     */
+    get loyalty(): LoyaltyManager;
+    /**
+     * Convenience method: Get loyalty profile for current user
+     */
+    getLoyaltyProfile(): Promise<LoyaltyProfile>;
+    /**
+     * Convenience method: Get loyalty history for current user
+     */
+    getLoyaltyHistory(limit?: number, offset?: number): Promise<LoyaltyHistoryResponse>;
+    /**
+     * Get the referral manager
+     */
+    get referral(): ReferralManager;
+    /**
+     * Convenience method: Get current referrer code
+     */
+    getReferrer(): string | null;
+    /**
+     * Convenience method: Set referrer code manually
+     */
+    setReferrer(code: string): void;
+    /**
+     * Get the affiliate manager
+     */
+    get affiliate(): AffiliateManager;
+    /**
+     * Convenience method: Get affiliate stats for current user
+     */
+    getAffiliateStats(forceRefresh?: boolean): Promise<AffiliateStats>;
+    /**
+     * Convenience method: Get leaderboard
+     */
+    getLeaderboard(limit?: number): Promise<LeaderboardResponse>;
+    /**
+     * Get user's quest progress
+     */
+    getQuests(): Promise<QuestsResponse>;
+    /**
+     * Get user's streaks with progress
+     */
+    getStreaks(): Promise<StreaksResponse>;
+    /**
+     * Use a freeze token for a streak
+     */
+    useStreakFreeze(ruleId: string): Promise<FreezeResponse>;
+    /**
+     * Get user's badge collection
+     */
+    getBadges(category?: string): Promise<BadgesResponse>;
+    /**
+     * Get available badge categories
+     */
+    getBadgeCategories(): Promise<string[]>;
+    /**
+     * Get rewards store items
+     */
+    getRewardsStore(): Promise<RewardsStoreResponse>;
+    /**
+     * Redeem a reward item
+     */
+    redeemReward(itemId: string): Promise<RedemptionResult>;
+}
+
+/**
+ * Create appropriate storage adapter based on environment
+ */
+declare function createStorage(prefix: string): StorageAdapter;
+
+/**
+ * Event queue for reliable event delivery with offline support
+ */
+declare class EventQueue {
+    private queue;
+    private readonly maxSize;
+    private readonly storage;
+    constructor(storage: StorageAdapter, maxSize?: number);
+    /**
+     * Load persisted queue from storage
+     */
+    private loadFromStorage;
+    /**
+     * Persist queue to storage
+     */
+    private saveToStorage;
+    /**
+     * Add an event to the queue
+     */
+    enqueue(event: GamifyEvent): string;
+    /**
+     * Get events ready for sending (batch)
+     */
+    peek(count: number): QueuedEvent[];
+    /**
+     * Mark events as successfully sent and remove from queue
+     */
+    acknowledge(ids: string[]): void;
+    /**
+     * Mark events as failed (increment retry count)
+     */
+    nack(ids: string[]): void;
+    /**
+     * Get current queue size
+     */
+    size(): number;
+    /**
+     * Check if queue has pending events
+     */
+    hasPending(): boolean;
+    /**
+     * Clear all events from queue
+     */
+    clear(): void;
+}
+
+export { type AffiliateEarnings, AffiliateManager, type AffiliateStats, type AffiliateStatsResponse, type AffiliateTier, type ApiResponse, type AppliedEffect, type BadgeRarity, type BadgeWithStatus, type BadgesResponse, type CartItem, EventQueue, type FreezeResponse, Gamify, type GamifyConfig, type GamifyEvent, HttpClient, type LeaderboardEntry, type LeaderboardResponse, type LoyaltyHistoryResponse, LoyaltyManager, type LoyaltyProfile, type LoyaltySummary, type LoyaltyTier, type LoyaltyTransaction, type NextTierInfo, type QuestStep, type QuestWithProgress, type QuestsResponse, type QueuedEvent, type RedemptionResult, type ReferralInfo, ReferralManager, type RewardItem, type RewardsStoreResponse, SessionManager, type SessionRequest, type SessionResponse, type StorageAdapter, type StreakMilestone, type StreakWithProgress, type StreaksResponse, type UserTraits, createStorage };