@usewayn/widget/src/wayn.d.ts

Client side widget generator for Wayn PoW CAPTCHA.

/**
 * TypeScript declarations for wayn.js
 * Main Wayn widget implementation
 */

declare namespace Wayn {
  /**
   * Configuration options for Wayn widget
   */
  interface Config {
    /** API endpoint for challenge requests */
    apiEndpoint?: string;
    /** Number of web workers to use for solving */
    workerCount?: number;
    /** Custom fetch function */
    customFetch?: typeof fetch;
    /** Custom WASM URL */
    customWasmUrl?: string;
    /** Hidden field name for form integration */
    hiddenFieldName?: string;
    /** Internationalization text overrides */
    i18n?: {
      initialState?: string;
      verifyingLabel?: string;
      verifyingAriaLabel?: string;
      verifiedAriaLabel?: string;
      errorAriaLabel?: string;
      solvedLabel?: string;
      errorLabel?: string;
      verifyAriaLabel?: string;
    };
  }

  /**
   * Challenge data from server
   */
  interface Challenge {
    challenge: Array<[string, string]>; // [salt, target] tuples
    token?: string;
    expires: number;
  }

  /**
   * Solution format for redeeming challenges
   */
  interface Solution {
    token: string;
    solutions: Array<[string, string, number]>; // [salt, target, nonce] tuples
  }

  /**
   * Server response for challenge redemption
   */
  interface RedeemResponse {
    success: boolean;
    message?: string;
    token?: string;
    expires?: number;
  }

  /**
   * Event detail for progress events
   */
  interface ProgressDetail {
    progress: number; // 0-100
  }

  /**
   * Event detail for solve events
   */
  interface SolveDetail {
    token: string;
  }

  /**
   * Event detail for error events
   */
  interface ErrorDetail {
    isWayn: boolean;
    message: string;
  }

  /**
   * Event detail for reset events
   */
  interface ResetDetail {}

  /**
   * Custom events dispatched by Wayn widget
   */
  interface WaynEvents {
    progress: CustomEvent<ProgressDetail>;
    solve: CustomEvent<SolveDetail>;
    error: CustomEvent<ErrorDetail>;
    reset: CustomEvent<ResetDetail>;
  }
}

/**
 * Wayn Widget Custom Element
 */
declare class WaynWidget extends HTMLElement {
  /** Current token value */
  token: string | null;

  /**
   * Solve the proof-of-work challenge
   * @returns Promise resolving to success result with token
   */
  solve(): Promise<{ success: boolean; token: string }>;

  /**
   * Reset the widget to initial state
   */
  reset(): void;

  /**
   * Get the current token value
   */
  get tokenValue(): string | null;

  /**
   * Set number of workers for solving
   * @param workers Number of workers to use
   */
  setWorkersCount(workers: number): void;

  /**
   * Get internationalized text
   * @param key Text key
   * @param defaultValue Default value if key not found
   */
  getI18nText(key: string, defaultValue: string): string;

  /**
   * Dispatch a custom event with detail
   * @param eventName Name of the event
   * @param detail Event detail object
   */
  dispatchEvent<K extends keyof Wayn.WaynEvents>(
    eventName: K,
    detail?: Wayn.WaynEvents[K]['detail']
  ): void;

  /**
   * Handle error and dispatch error event
   * @param message Error message
   */
  error(message?: string): void;

  // Event handlers
  addEventListener<K extends keyof Wayn.WaynEvents>(
    type: K,
    listener: (this: WaynWidget, ev: Wayn.WaynEvents[K]) => any,
    options?: boolean | AddEventListenerOptions
  ): void;
  addEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions
  ): void;

  removeEventListener<K extends keyof Wayn.WaynEvents>(
    type: K,
    listener: (this: WaynWidget, ev: Wayn.WaynEvents[K]) => any,
    options?: boolean | EventListenerOptions
  ): void;
  removeEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | EventListenerOptions
  ): void;

  // HTML attributes
  static readonly observedAttributes: string[];

  // Lifecycle callbacks
  connectedCallback(): Promise<void>;
  disconnectedCallback(): void;
  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
}

/**
 * Wayn class for programmatic usage
 */
declare class Wayn {
  /** The underlying widget element */
  readonly widget: WaynWidget;
  
  /** Current token value */
  readonly token: string | null;

  /**
   * Create a new Wayn instance
   * @param config Configuration options
   * @param el Optional existing element to use
   */
  constructor(config?: Wayn.Config, el?: WaynWidget);

  /**
   * Solve the proof-of-work challenge
   */
  solve(): Promise<{ success: boolean; token: string }>;

  /**
   * Reset the widget to initial state
   */
  reset(): void;

  /**
   * Add event listener to the widget
   */
  addEventListener<K extends keyof Wayn.WaynEvents>(
    type: K,
    listener: (this: WaynWidget, ev: Wayn.WaynEvents[K]) => any,
    options?: boolean | AddEventListenerOptions
  ): void;
}

declare global {
  interface Window {
    /** Custom fetch function for Wayn */
    WAYN_CUSTOM_FETCH?: typeof fetch;
    /** Custom WASM URL for Wayn */
    WAYN_CUSTOM_WASM_URL?: string;
    /** Skip re-defining custom element */
    WAYN_DONT_SKIP_REDEFINE?: boolean;
    /** Wayn class constructor */
    Wayn: typeof Wayn;
  }

  interface HTMLElementTagNameMap {
    'wayn-widget': WaynWidget;
  }

  namespace JSX {
    interface IntrinsicElements {
      'wayn-widget': React.DetailedHTMLProps<React.HTMLAttributes<WaynWidget>, WaynWidget> & {
        'data-wayn-api-endpoint'?: string;
        'data-wayn-worker-count'?: string;
        'data-wayn-hidden-field-name'?: string;
        'data-wayn-i18n-initial-state'?: string;
        'data-wayn-i18n-verifying-label'?: string;
        'data-wayn-i18n-verifying-aria-label'?: string;
        'data-wayn-i18n-verified-aria-label'?: string;
        'data-wayn-i18n-error-aria-label'?: string;
        'data-wayn-i18n-solved-label'?: string;
        'data-wayn-i18n-error-label'?: string;
        'data-wayn-i18n-verify-aria-label'?: string;
        onsolve?: string;
        onprogress?: string;
        onreset?: string;
        onerror?: string;
      };
    }
  }
}

export = Wayn;
export as namespace Wayn;