API Reference

⚡ 10 min read

Complete API documentation for the Transcodes WebWorker.

API Sections

Token API User API Events API Modal API

Token API

Authentication tokens and session management. Check auth status, get tokens, sign out.

User API

User information retrieval. Fetch user data by ID or email.

Events API

Event subscription and callbacks. Listen to auth state changes, token refresh, errors.

Authentication modal methods. Login, passkey management, MFA modals.

SDK Structure


interface TranscodesAPI {
  // Token Management
  token: {
    getCurrentUser(): Promise<User | null>;
    getAccessToken(): Promise<string | null>;
    hasToken(): boolean;
    hasPrivateKey(): Promise<boolean>;
    validateToken(): boolean;
    isAuthenticated(): Promise<boolean>;
    signOut(): Promise<void>;
  };
 
  // User Information
  user: {
    get(params: {
      projectId?: string;
      userId?: string;
      email?: string;
      fields?: string;
    }): Promise<ApiResponse<User[]>>;
  };
 
  // Event Subscription
  on(event: TranscodesEventName, callback: (payload: any) => void): () => void;
  off(event: TranscodesEventName, callback: (payload: any) => void): void;
 
  // Authentication Modals
  openAuthLoginModal(params: {
    projectId?: string;
    userId?: string;
  }): Promise<ApiResponse<AuthResult[]>>;
 
  openAuthModal(params: {
    userId: string;
    projectId?: string;
  }): Promise<ApiResponse<null>>;
 
  openAuthMfaModal(params: {
    userId: string;
    projectId?: string;
  }): Promise<ApiResponse<AuthResult[]>>;
}

Core Types

ApiResponse<T>


interface ApiResponse<T> {
  success: boolean;
  payload: T;
  error?: string;
  message?: string;
}

User


interface User {
  id?: string;
  projectId?: string;
  name?: string;
  email?: string;
  roles?: string;
  metadata?: Record<string, string | number | boolean | null | undefined>;
  createdAt?: Date | string;
  updatedAt?: Date | string;
}

AuthResult


interface AuthResult {
  token: string;
  user: User;
}

TranscodesEventName


type TranscodesEventName =
  | 'AUTH_STATE_CHANGED'
  | 'TOKEN_REFRESHED'
  | 'TOKEN_EXPIRED'
  | 'ERROR';

Complete TypeScript Definitions

Download the complete type definitions file for your project:

types/transcodes.d.ts


/**
 * Transcodes SDK Type Definitions
 */
 
declare global {
  interface Window {
    transcodes: TranscodesAPI;
  }
 
  var transcodes: Window['transcodes'];
}
 
export declare const TranscodesEventNames = {
  AUTH_STATE_CHANGED: 'AUTH_STATE_CHANGED',
  TOKEN_REFRESHED: 'TOKEN_REFRESHED',
  TOKEN_EXPIRED: 'TOKEN_EXPIRED',
  ERROR: 'ERROR',
} as const;
 
/**
 * Union type for window.transcodes
 * Can be either Static or Dynamic API depending on the entry point
 */
export type TranscodesAPI = TranscodesStaticAPI | TranscodesDynamicAPI;
 
/**
 * Static SDK API (PWA mode)
 * Build-time injected configuration
 */
export interface TranscodesStaticAPI extends TranscodesBaseAPI {
  showMessage: (message: string) => void;
}
 
/**
 * Dynamic SDK API (CDN mode)
 * Runtime configuration via init()
 */
export interface TranscodesDynamicAPI extends TranscodesBaseAPI {
  /**
   * Initialize the WebWorker with configuration
   * Fetches project config (branding, rpId) from API
   * Must be called before using any other WebWorker methods
   */
  init: (options: TranscodesInitOptions) => Promise<void>;
 
  /**
   * Update WebWorker configuration at runtime
   * Only customUserId can be changed. To change projectId, call init() again.
   */
  setConfig: (options: { customUserId?: string }) => void;
 
  /**
   * Check if WebWorker is initialized
   */
  isInitialized: () => boolean;
}
 
/**
 * Common base API interface shared by Static and Dynamic WebWorker
 */
export interface TranscodesBaseAPI {
  token: TokenAPI;
  user: PublicUserAPI;
 
  on: PublicEventAPI['on'];
  off: PublicEventAPI['off'];
 
  openAuthLoginModal: (params: {
    projectId?: string;
    userId?: string;
  }) => Promise<ApiResponse<AuthResult[]>>;
 
  openAuthModal: (params: {
    userId: string;
    projectId?: string;
  }) => Promise<ApiResponse<null>>;
 
  openAuthMfaModal: (params: {
    userId: string;
    projectId?: string;
  }) => Promise<ApiResponse<AuthResult[]>>;
}
 
/**
 * SDK Initialization Options (Dynamic SDK only)
 */
export interface TranscodesInitOptions {
  /** Project ID from Transcodes dashboard */
  projectId: string;
  /** Relying Party ID - the domain where the SDK is running (e.g., 'example.com') */
  rpId: string;
  /**
   * Custom user ID for SDK integration with external auth systems
   * (e.g., Firebase UID, Auth0 user_id)
   */
  customUserId?: string;
  /** Enable debug logging */
  debug?: boolean;
}
 
export interface TokenAPI {
  getCurrentUser(): Promise<User | null>;
  getAccessToken(): Promise<string | null>;
  hasToken(): boolean;
  hasPrivateKey(): Promise<boolean>;
  validateToken(): boolean;
  isAuthenticated(): Promise<boolean>;
  signOut(): Promise<void>;
}
 
export interface PublicUserAPI {
  get(params: {
    projectId?: string;
    userId?: string;
    email?: string;
    fields?: string;
  }): Promise<ApiResponse<User[]>>;
}
 
export interface PublicEventAPI {
  on<T extends TranscodesEventName>(
    event: T,
    callback: EventCallback<T>
  ): () => void;
  off<T extends TranscodesEventName>(
    event: T,
    callback: EventCallback<T>
  ): void;
}
 
export interface ApiResponse<T> {
  success: boolean;
  payload: T;
  error?: string;
  message?: string;
}
 
export interface AuthResult {
  token: string;
  user: User;
}
 
export interface User {
  id?: string;
  projectId?: string;
  name?: string;
  email?: string;
  roles?: string;
  metadata?: Record<string, string | number | boolean | null | undefined>;
  createdAt?: Date | string;
  updatedAt?: Date | string;
}
 
export type TranscodesEventName =
  (typeof TranscodesEventNames)[keyof typeof TranscodesEventNames];
 
export type EventCallback<T extends TranscodesEventName> = (
  payload: TranscodesEventMap[T]
) => void;
 
export interface TranscodesEventMap {
  AUTH_STATE_CHANGED: AuthStateChangedPayload;
  TOKEN_REFRESHED: TokenRefreshedPayload;
  TOKEN_EXPIRED: TokenExpiredPayload;
  ERROR: ErrorPayload;
}
 
export interface AuthStateChangedPayload {
  isAuthenticated: boolean;
  accessToken: string | null;
  expiresAt: number | null;
  user: User | null;
}
 
export interface TokenRefreshedPayload {
  accessToken: string;
  expiresAt: number;
}
 
export interface TokenExpiredPayload {
  expiredAt: number;
}
 
export interface ErrorPayload {
  code: string;
  message: string;
  context?: string;
}

Usage

Create the file types/transcodes.d.ts in your project root
Update your tsconfig.json:

tsconfig.json


{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"]
  },
  "include": ["src", "types"]
}