@tiun/sdk/tiun.d.ts

tiun SDK for payments and subscriptions

/**
 * tiun SDK Type Definitions
 *
 * Install: npm install @tiun/types --save-dev
 *
 * These types are for the global `tiun` object exposed by the tiun script.
 * Load the script, then use tiun.* with full TypeScript support.
 *
 * @generated from packages/types/src/index.ts - Do not edit directly.
 * Run `npm run generate:types` to regenerate.
 */

// =============================================================================
// Core Types
// =============================================================================

export type ContentType = 'active' | 'inactive' | 'paused';
export type MediaType = 'text' | 'audio' | 'video';
export type SupportedLanguage = 'en' | 'de' | 'fr';
export type TiunEventType =
  | 'ready'
  | 'paywallShow'
  | 'paywallHide'
  | 'error'
  | 'userChange'
  | 'login'
  | 'logout';

// =============================================================================
// Configuration
// =============================================================================

export interface TiunConfig {
  /**
   * Your unique tiun snippet ID.
   * Required when using the NPM package (SDK loads the snippet from backend).
   * For legacy script tag usage, this is provided via the backend.
   */
  snippetId?: string;

  /**
   * Language for the snippet UI. Case-insensitive ('en', 'EN', 'De' all work).
   * Falls back to 'en' if an unsupported value is provided.
   * @default 'en'
   */
  language?: SupportedLanguage;

  /**
   * UI tone/style.
   * - 'formal': More professional tone
   * - 'informal': More casual/friendly tone
   * @default 'formal'
   */
  tone?: 'formal' | 'informal';

  /**
   * Enable debug logging to console.
   * @default false
   */
  debug?: boolean;

  /**
   * Use sandbox base URL instead of production.
   * @default false
   */
  sandbox?: boolean;

  /**
   * Called when the snippet has finished initializing and is ready
   */
  onReady?: () => void;

  /**
   * Called when paywall should be shown to the user
   */
  onPaywallShow?: (data: PaywallShowEvent) => void;

  /**
   * Called when paywall should be hidden (user has access)
   */
  onPaywallHide?: (data: PaywallHideEvent) => void;

  /**
   * Called on user state changes (init + every subsequent change)
   */
  onUserChange?: (data: UserChangeEvent) => void;

  /**
   * Called when user logs in
   */
  onLogin?: (data: LoginEvent) => void;

  /**
   * Called when user logs out
   */
  onLogout?: () => void;

  /**
   * Called on any error
   */
  onError?: (error: TiunError) => void;
}

// =============================================================================
// Event Payloads
// =============================================================================

export interface PaywallShowEvent {
  /**
   * Whether user has connected a payment method
   */
  isConnected: boolean;
}

export interface PaywallHideEvent {
  /**
   * Active session ID
   */
  sessionId: string;

  /**
   * Whether user is connected
   */
  isConnected: boolean;
}

export interface TiunError {
  code: string;
  message: string;
  details?: unknown;
}

export interface UserInfo {
  userId: string;
  email: string;
  productAccess: string[];
}

export interface UserChangeEvent {
  event: 'init' | 'login' | 'checkout' | 'logout' | 'update';
  isAuthenticated: boolean;
  user: UserInfo | null;
}

export interface LoginEvent {
  user: UserInfo;
}

export interface GetUserResponse {
  isAuthenticated: boolean;
  user: UserInfo | null;
}

// =============================================================================
// Checkout Options
// =============================================================================

export interface CheckoutOptions {
  /**
   * Specific product ID to checkout (optional, for future use)
   */
  productId?: string;
}

// =============================================================================
// Content Options
// =============================================================================

export interface ContentOptions {
  /**
   * Type of content (affects session state)
   */
  type: ContentType;

  /**
   * Unique identifier for this content/route
   */
  contentId?: string;

  /**
   * Media type being consumed
   * @default 'text'
   */
  mediaType?: MediaType;
}

// =============================================================================
// SDK Interface (for global tiun object)
// =============================================================================

export interface TiunSDK {
  /**
   * Initialize the SDK. Call once at app startup.
   *
   * ```typescript
   * tiun.init({ snippetId: 'your-snippet-id' });
   * ```
   */
  init(config?: TiunConfig): TiunSDK;

  /**
   * Open the time-based connect flow (no specific product).
   */
  start(): Promise<void>;

  /**
   * Open the checkout flow for a specific product.
   */
  checkout(options?: CheckoutOptions): Promise<void>;

  /**
   * Update the current content context.
   */
  setContent(options: ContentOptions): Promise<void>;

  /**
   * Open the OTP login modal for returning subscribers.
   */
  login(): Promise<void>;

  /**
   * Clear session and fire logout + userChange events.
   */
  logout(): void;

  /**
   * Returns the cached user state. Does not call the backend —
   * the snippet keeps user info in sync automatically.
   */
  getUser(): GetUserResponse;

  /**
   * Returns a signed JWT for server-to-server user verification.
   * Valid for 5 minutes. Returns null if the user is not authenticated.
   */
  getUserVerificationToken(): Promise<string | null>;

  /**
   * Subscribe to an event. Returns unsubscribe function.
   */
  on(event: 'ready', callback: () => void): () => void;
  on(
    event: 'paywallShow',
    callback: (data: PaywallShowEvent) => void
  ): () => void;
  on(
    event: 'paywallHide',
    callback: (data: PaywallHideEvent) => void
  ): () => void;
  on(event: 'error', callback: (error: TiunError) => void): () => void;
  on(
    event: 'userChange',
    callback: (data: UserChangeEvent) => void
  ): () => void;
  on(event: 'login', callback: (data: LoginEvent) => void): () => void;
  on(event: 'logout', callback: () => void): () => void;

  /**
   * Subscribe to an event once (auto-unsubscribes after first fire).
   */
  once(event: 'ready', callback: () => void): () => void;
  once(
    event: 'paywallShow',
    callback: (data: PaywallShowEvent) => void
  ): () => void;
  once(
    event: 'paywallHide',
    callback: (data: PaywallHideEvent) => void
  ): () => void;
  once(event: 'error', callback: (error: TiunError) => void): () => void;
  once(
    event: 'userChange',
    callback: (data: UserChangeEvent) => void
  ): () => void;
  once(event: 'login', callback: (data: LoginEvent) => void): () => void;
  once(event: 'logout', callback: () => void): () => void;

  /**
   * Destroy the SDK and cleanup all listeners.
   */
  destroy(): void;

  /**
   * Wait for the SDK to be ready.
   */
  waitForReady(): Promise<void>;

  /** SDK version */
  readonly version: string;

  /** Whether init() has been called */
  readonly isInitialized: boolean;

  /** Whether the snippet is ready */
  readonly isReady: boolean;

  /** Whether the user is identified (has valid session) */
  readonly isAuthenticated: boolean;

  /** Current user info or null */
  readonly user: UserInfo | null;
}


/** NPM: use import { tiun } from '@tiun/sdk' or import tiun from '@tiun/sdk' */
export const tiun: TiunSDK;
export default tiun;

// =============================================================================
// Global Declaration
// =============================================================================

declare global {
  /**
   * Global tiun SDK instance.
   * Available after loading the tiun script.
   */
  const tiun: TiunSDK;

  interface Window {
    tiun: TiunSDK;
  }
}

export {};