@zencemarketing/spin-scratch-sdk 0.1.0-alpha.1

package/dist/spin-wheel-sdk.d.ts

@@ -0,0 +1,513 @@
+/**
+ * SpinWheel SDK v0.1.0-alpha.1
+ * TypeScript declarations
+ */
+
+// ── SpinWheel Types ──
+
+export interface SegmentConfig {
+  /** Text displayed on the wheel segment */
+  label: string;
+  /** Segment background color (hex) */
+  color: string;
+  /** Emoji/icon displayed on the segment */
+  icon?: string;
+  /** Title shown on the win card (falls back to label) */
+  title?: string;
+  /** "WORTH ₹xxx" text on the win card */
+  worth?: string;
+  /** Fixed coupon code – overrides auto-generate */
+  code?: string;
+}
+
+export interface SpinWheelTheme {
+  gold?: string;
+  goldLight?: string;
+  goldDark?: string;
+  bgDark?: string;
+  textMuted?: string;
+}
+
+/** @deprecated Use SpinWheelTheme instead */
+export type ThemeConfig = SpinWheelTheme;
+
+export interface SpinWheelOptions {
+  /** CSS selector or DOM element to mount into */
+  container: string | HTMLElement;
+  /** Array of prize segments (min 2) */
+  segments: SegmentConfig[];
+  /**
+   * Pre-determined winning segment index (0-based).
+   * If set, spin() will always land on this segment unless overridden by forceIndex.
+   * Must be within bounds (0 <= index < segments.length), otherwise ignored.
+   * Default: null (random selection)
+   */
+  winningIndex?: number | null;
+
+  // ── Spin Behavior ──
+  /** Total spin animation duration in ms (default: 5000) */
+  spinDuration?: number;
+  /** Minimum full rotations (default: 5) */
+  minSpins?: number;
+  /** Maximum full rotations (default: 8) */
+  maxSpins?: number;
+  /** Max number of spins allowed. null = unlimited (default: null) */
+  spinLimit?: number | null;
+
+  // ── Header UI ──
+  /** If set, renders a header above the wheel */
+  headerTitle?: string | null;
+  /** Subtitle below the header */
+  headerSubtitle?: string | null;
+  /** Custom title color (uses theme.goldLight if null) */
+  titleColor?: string | null;
+  /** Custom subtitle color (uses theme.textMuted if null) */
+  subtitleColor?: string | null;
+
+  // ── Hub ──
+  /** Text inside the center hub (default: 'Spin & win') */
+  hubLabel?: string;
+  /** Icon inside the center hub (default: '▲') */
+  hubIcon?: string;
+
+  // ── Spin Button ──
+  /** Render the external SPIN! button (default: true) */
+  showButton?: boolean;
+  /** Button label text (default: 'SPIN!') */
+  buttonText?: string;
+
+  // ── Wheel Appearance ──
+  /** Container background color (uses theme.bgDark if null) */
+  backgroundColor?: string | null;
+  /** Background image URL */
+  backgroundImage?: string | null;
+  /** Wheel ring color (uses theme gradient if null) */
+  ringColor?: string | null;
+  /** Enable ring shadow/glow effect (default: true) */
+  ringShadow?: boolean;
+  /** Enable pulsing ring animation (default: true) */
+  ringAnimation?: boolean;
+  /** Pointer/arrow color (uses theme.gold if null) */
+  pointerColor?: string | null;
+  /** Spin button gradient color (uses theme gradient if null) */
+  buttonColor?: string | null;
+  /** Enable button shadow effect (default: true) */
+  buttonShadow?: boolean;
+  /** Enable button hover/active animations (default: true) */
+  buttonAnimation?: boolean;
+
+  // ── Win Card ──
+  /** Show the built-in win card overlay (default: true) */
+  showWinCard?: boolean;
+  /** Auto-generate a random coupon code (default: true) */
+  generateCode?: boolean;
+  /** Length of auto-generated codes (default: 9) */
+  codeLength?: number;
+  /** If set, "Redeem Now" opens this URL */
+  redeemUrl?: string | null;
+  /** Brand label on win card (uses hubLabel if null) */
+  winCardBrandLabel?: string | null;
+  /** Label before worth value (default: 'WORTH') */
+  winCardWorthLabel?: string;
+  /** Redeem button text (default: 'Redeem Now') */
+  winCardRedeemButtonText?: string;
+  /** Redeem button gradient top color (default: '#15803d') */
+  winCardRedeemButtonColorTop?: string;
+  /** Redeem button gradient bottom color (default: '#166534') */
+  winCardRedeemButtonColorBottom?: string;
+  /** Redeem button text color (default: '#ffffff') */
+  winCardRedeemButtonTextColor?: string;
+
+  // ── Confetti ──
+  /** Show confetti on win (default: true) */
+  confettiOnWin?: boolean;
+  /** Array of confetti colors (uses defaults if null) */
+  confettiColors?: string[] | null;
+  /** Number of confetti pieces (default: 40) */
+  confettiCount?: number;
+
+  // ── Theme ──
+  /** Color theme overrides */
+  theme?: SpinWheelTheme;
+
+  // ── Callbacks ──
+  /** Called when spin starts */
+  onSpinStart?: (winIndex: number) => void;
+  /** Called when spin ends */
+  onSpinEnd?: (prize: SegmentConfig, winIndex: number) => void;
+  /** Called when redeem is clicked */
+  onRedeem?: (prize: SegmentConfig) => void;
+  /** Called when spin limit is reached */
+  onSpinLimitReached?: (count: number) => void;
+}
+
+/**
+ * Options passed to {@link SpinWheel.init}.
+ *
+ * VS Code hover on `SpinWheel.init` typically shows only the parameter type name.
+ * To see all available option fields, go to the type definition of `SpinWheelInitOptions`
+ * (or `SpinWheelOptions`) and/or use IntelliSense inside the object literal:
+ *
+ * @example
+ * SpinWheel.init({
+ *   container: '#spin-wheel-container',
+ *   segments: [{ label: 'Prize', color: '#55efc4' }],
+ *   spinDuration: 5000,
+ *   onSpinEnd: (prize) => console.log(prize)
+ * })
+ */
+export type SpinWheelInitOptions = SpinWheelOptions;
+
+export declare class SpinWheelInstance {
+  constructor(opts: SpinWheelOptions);
+
+  /** Current cumulative rotation in degrees */
+  currentRotation: number;
+  /** Whether the wheel is currently animating */
+  isSpinning: boolean;
+
+  /**
+   * Spin the wheel.
+   * @param forceIndex – optional index to force the result
+   */
+  spin(forceIndex?: number): void;
+
+  /**
+   * Replace all segments at runtime and re-render the wheel.
+   * @param newSegments – array of new segments (min 2)
+   */
+  updateSegments(newSegments: SegmentConfig[]): void;
+
+  /** Programmatically close the win card overlay */
+  hideWinCard(): void;
+
+  /**
+   * Update configuration options at runtime.
+   * @param newOptions – partial options to merge
+   */
+  updateOptions(newOptions: Partial<SpinWheelOptions>): void;
+
+  /**
+   * Reset the spin count to allow more spins.
+   * @param count – new spin count to set (default: 0)
+   */
+  resetSpinCount(count?: number): void;
+
+  /** Remove all SDK-created DOM and clean up */
+  destroy(): void;
+
+  /** The last prize that was won */
+  readonly lastWonPrize: SegmentConfig | null;
+
+  /** The last won segment index */
+  readonly lastWonIndex: number;
+
+  /** The current spin count */
+  readonly spinCount: number;
+
+  /** The remaining spins (null if unlimited) */
+  readonly remainingSpins: number | null;
+}
+
+export declare class SpinWheel {
+  /**
+   * Initialise and mount a new Spin Wheel.
+   *
+   * Required: `container`, `segments`.
+   */
+  static init(options: SpinWheelInitOptions): SpinWheelInstance;
+  /** The underlying class */
+  static Instance: typeof SpinWheelInstance;
+  /** Current SDK version */
+  static VERSION: string;
+  /** Default configuration */
+  static DEFAULTS: Readonly<SpinWheelOptions>;
+}
+
+// ── ScratchCard Types ──
+
+export interface ScratchPrize {
+  /** Prize name (displayed in modal) */
+  name: string;
+  /** Emoji/icon */
+  icon?: string;
+  /** Label above prize name */
+  label?: string;
+}
+
+export interface ScratchCardTheme {
+  purpleDark?: string;
+  purpleMid?: string;
+  purpleLight?: string;
+  gold?: string;
+  goldLight?: string;
+  goldDark?: string;
+  white?: string;
+  textDark?: string;
+  textMuted?: string;
+}
+
+export interface ScratchCardOptions {
+  /** CSS selector or DOM element to mount into */
+  container: string | HTMLElement;
+  /** Prize object */
+  prize: ScratchPrize;
+
+  // ── Header UI ──
+  /** Header text (default: 'Scratch the Card to Win Exciting Prizes!') */
+  headerTitle?: string;
+  /** Header title color (uses theme.textDark if null) */
+  headerTitleColor?: string | null;
+
+  // ── Instruction ──
+  /** Instruction text */
+  instruction?: string;
+  /** Instruction text color (uses theme.textMuted if null) */
+  instructionColor?: string | null;
+
+  // ── Scratch Behavior ──
+  /** % scratched to auto-reveal, 10-90 (default: 55) */
+  revealThreshold?: number;
+  /** Scratch brush radius in px (default: 28) */
+  brushSize?: number;
+
+  // ── Coin (Eraser Tool) ──
+  /** Draggable eraser size in px (default: 56) */
+  coinSize?: number;
+  /** Show the draggable coin eraser (default: true) */
+  showCoin?: boolean;
+  /** Icon/text inside the coin (default: '$') */
+  coinIcon?: string;
+  /** Coin gradient start color (uses theme.goldLight if null) */
+  coinGradientStart?: string | null;
+  /** Coin gradient end color (uses theme.goldDark if null) */
+  coinGradientEnd?: string | null;
+
+  // ── Card Appearance ──
+  /** Card background CSS (uses default gradient if null) */
+  cardBackground?: string | null;
+  /** Enable card shadow (default: true) */
+  cardShadow?: boolean;
+  /** Card border radius in px (default: 24) */
+  cardBorderRadius?: number;
+
+  // ── Scratch Zone ──
+  /** Scratch zone background (uses theme gradient if null) */
+  scratchZoneBackground?: string | null;
+  /** Enable scratch zone shadow (default: true) */
+  scratchZoneShadow?: boolean;
+  /** Scratch zone border radius in px (default: 20) */
+  scratchZoneBorderRadius?: number;
+
+  // ── Scratch Layer ──
+  /** Scratch layer color (default: 'rgb(150, 130, 180)') */
+  scratchLayerColor?: string;
+  /** Show sparkle effects on scratch layer (default: true) */
+  scratchLayerSparkles?: boolean;
+  /** Number of sparkles (default: 40) */
+  scratchLayerSparkleCount?: number;
+
+  // ── Prize Display ──
+  /** Prize label color (uses white if null) */
+  prizeTextColor?: string | null;
+  /** Prize name color (uses theme.goldLight if null) */
+  prizeNameColor?: string | null;
+  /** Prize icon background (uses white opacity if null) */
+  prizeIconBackground?: string | null;
+
+  // ── Gift Icon (Hint) ──
+  /** Show gift icon hint on scratch layer (default: true) */
+  showGiftIcon?: boolean;
+  /** Gift icon emoji (default: '🎁') */
+  giftIcon?: string;
+  /** Gift icon background (uses white opacity if null) */
+  giftIconBackground?: string | null;
+
+  // ── Modal ──
+  /** Show the win modal on reveal (default: true) */
+  showModal?: boolean;
+  /** Modal title text (default: 'Congratulations!') */
+  modalTitle?: string;
+  /** Modal title color (uses theme.textDark if null) */
+  modalTitleColor?: string | null;
+  /** Modal button text prefix (default: 'Claim your') */
+  modalButtonText?: string;
+  /** Modal button background (uses theme gradient if null) */
+  modalButtonColor?: string | null;
+  /** Modal button text color (uses theme.white if null) */
+  modalButtonTextColor?: string | null;
+  /** Enable backdrop blur effect (default: true) */
+  modalBackdropBlur?: boolean;
+
+  // ── Confetti ──
+  /** Enable confetti on reveal (default: true) */
+  confettiEnabled?: boolean;
+  /** Array of confetti colors (uses defaults if null) */
+  confettiColors?: string[] | null;
+  /** Number of confetti pieces (default: 100) */
+  confettiCount?: number;
+  /** Confetti animation duration in ms (default: 5500) */
+  confettiDuration?: number;
+
+  // ── Animation ──
+  /** Animation type: 'default' | 'bounce' | 'none' (default: 'default') */
+  animationType?: 'default' | 'bounce' | 'none';
+  /** Animation duration in ms (default: 600) */
+  animationDuration?: number;
+
+  // ── Theme ──
+  /** Color theme overrides */
+  theme?: ScratchCardTheme;
+
+  // ── Callbacks ──
+  /** Called when scratching begins */
+  onScratchStart?: () => void;
+  /** Called with scratch percentage */
+  onScratchProgress?: (percent: number) => void;
+  /** Called when prize is revealed */
+  onReveal?: (prize: ScratchPrize) => void;
+  /** Called when claim is clicked */
+  onClaim?: (prize: ScratchPrize) => void;
+}
+
+export declare class ScratchCardInstance {
+  constructor(opts: ScratchCardOptions);
+
+  /** Current scratch percentage (0-100) */
+  scratchPercent: number;
+  /** Whether user is currently scratching */
+  isScratching: boolean;
+  /** Whether prize has been revealed */
+  hasRevealed: boolean;
+
+  /** Programmatically reveal the prize */
+  reveal(): void;
+  /** Reset the card for replay */
+  reset(): void;
+  /** Hide the win modal */
+  hideModal(): void;
+  /** Show the win modal */
+  showModal(): void;
+  /** Update prize at runtime and reset card */
+  updatePrize(prize: Partial<ScratchPrize>): void;
+  /**
+   * Update configuration options at runtime.
+   * @param newOptions – partial options to merge
+   */
+  updateOptions(newOptions: Partial<ScratchCardOptions>): void;
+  /** Remove all SDK-created DOM and clean up */
+  destroy(): void;
+
+  /** Get the current prize object */
+  readonly prize: ScratchPrize | null;
+}
+
+export declare const ScratchCard: {
+  /** Create and return a new ScratchCardInstance */
+  init(opts: ScratchCardOptions): ScratchCardInstance;
+  /** The underlying class */
+  Instance: typeof ScratchCardInstance;
+  /** Current SDK version */
+  VERSION: string;
+  /** Default configuration */
+  DEFAULTS: Readonly<ScratchCardOptions>;
+};
+
+// ── React Wrappers ──
+// These types are self-contained — vanilla TS users do NOT need @types/react.
+
+export interface SpinWheelReactProps extends Omit<SpinWheelOptions, 'container'> {
+  className?: string;
+  style?: Record<string, any>;
+}
+
+export interface SpinWheelReactHandle {
+  spin(forceIndex?: number): void;
+  updateSegments(segments: SegmentConfig[]): void;
+  hideWinCard(): void;
+  updateOptions(opts: Partial<SpinWheelOptions>): void;
+  resetSpinCount(count?: number): void;
+  readonly spinCount: number;
+  readonly remainingSpins: number | null;
+  readonly lastWonPrize: SegmentConfig | null;
+  readonly lastWonIndex: number;
+  readonly instance: SpinWheelInstance | null;
+}
+
+export interface ScratchCardReactProps extends Omit<ScratchCardOptions, 'container'> {
+  className?: string;
+  style?: Record<string, any>;
+}
+
+export interface ScratchCardReactHandle {
+  reveal(): void;
+  reset(): void;
+  hideModal(): void;
+  showModal(): void;
+  updatePrize(prize: Partial<ScratchPrize>): void;
+  updateOptions(opts: Partial<ScratchCardOptions>): void;
+  readonly scratchPercent: number;
+  readonly hasRevealed: boolean;
+  readonly prize: ScratchPrize | null;
+  readonly instance: ScratchCardInstance | null;
+}
+
+/**
+ * Creates a SpinWheelReact component using the provided React instance.
+ * Factory pattern avoids bundling React into the SDK.
+ *
+ * @param React – your app's React module
+ * @returns A ForwardRef component accepting {@link SpinWheelReactProps}.
+ *
+ * @example
+ * ```tsx
+ * import React, { useRef } from 'react';
+ * import { createSpinWheelReact, type SpinWheelReactHandle } from '@zencemarketing/spin-scratch-sdk';
+ *
+ * const SpinWheelReact = createSpinWheelReact(React);
+ * const ref = useRef<SpinWheelReactHandle>(null);
+ *
+ * <SpinWheelReact ref={ref} segments={[...]} onSpinEnd={(prize) => {}} />
+ * ```
+ */
+export declare function createSpinWheelReact(React: any): import('react').ForwardRefExoticComponent<
+  SpinWheelReactProps & import('react').RefAttributes<SpinWheelReactHandle>
+>;
+
+/**
+ * Creates a ScratchCardReact component using the provided React instance.
+ * Factory pattern avoids bundling React into the SDK.
+ *
+ * @param React – your app's React module
+ * @returns A ForwardRef component accepting {@link ScratchCardReactProps}.
+ *
+ * @example
+ * ```tsx
+ * import React, { useRef } from 'react';
+ * import { createScratchCardReact, type ScratchCardReactHandle } from '@zencemarketing/spin-scratch-sdk';
+ *
+ * const ScratchCardReact = createScratchCardReact(React);
+ * const ref = useRef<ScratchCardReactHandle>(null);
+ *
+ * <ScratchCardReact ref={ref} prize={{ name: 'Gift' }} onReveal={(p) => {}} />
+ * ```
+ */
+export declare function createScratchCardReact(React: any): import('react').ForwardRefExoticComponent<
+  ScratchCardReactProps & import('react').RefAttributes<ScratchCardReactHandle>
+>;
+
+/**
+ * Auto-detected SpinWheelReact (only available when `window.React` exists, e.g. UMD/CDN).
+ * In ESM/CJS bundler apps, import from `'@zencemarketing/spin-scratch-sdk/react'` instead.
+ */
+export declare const SpinWheelReact: import('react').ForwardRefExoticComponent<
+  SpinWheelReactProps & import('react').RefAttributes<SpinWheelReactHandle>
+> | undefined;
+
+/**
+ * Auto-detected ScratchCardReact (only available when `window.React` exists, e.g. UMD/CDN).
+ * In ESM/CJS bundler apps, import from `'@zencemarketing/spin-scratch-sdk/react'` instead.
+ */
+export declare const ScratchCardReact: import('react').ForwardRefExoticComponent<
+  ScratchCardReactProps & import('react').RefAttributes<ScratchCardReactHandle>
+> | undefined;