@pkme/widget-bridge/dist/index.d.ts

TypeScript React bridge client for Secret City Games widget integration across Framer, Figma, and web platforms

/**
 * @pkme/widget-bridge - TypeScript Definitions
 */

export interface BridgeContext {
  viewId: string;
  sessionId: string;
  gameId: string;
}

export interface BridgeMessage {
  type: string;
  payload?: any;
  scope?: 'global' | 'item' | 'screen';
  key?: string;
  _t?: number;
  _changeId?: string;
}

export type MessageHandler = (message: BridgeMessage) => void;

export interface BridgeInstance {
  setGlobal(data: Record<string, any>): Promise<void>;
  setItem(data: Record<string, any>): Promise<void>;
  setItemById(itemId: string, data: Record<string, any>): Promise<void>;
  subscribeGlobal(handler: (data: Record<string, any>) => void): () => void;
  subscribeItem(handler: (data: Record<string, any>) => void): () => void;
  subscribeItemById(itemId: string, handler: (data: Record<string, any>) => void): () => void;
  navigate(to: string, params?: Record<string, any>, method?: 'push' | 'replace'): Promise<void>;
  back(steps?: number): Promise<void>;
  complete(data?: Record<string, any>): Promise<void>;
  send(type: string, payload?: any, extra?: any): Promise<void>;
  on(type: string, handler: MessageHandler): () => void;
  onAny(handler: MessageHandler): () => void;
  readonly isReady: boolean;
  readonly environment: 'expo' | 'iframe' | 'standalone';
  readonly context: BridgeContext | null;
  ready(): Promise<void>;
}

export declare const bridge: BridgeInstance;

export class BridgeError extends Error {
  constructor(message: string, code?: string);
  code?: string;
}

export declare const MESSAGE_TYPES: {
  readonly SAVE_GLOBAL: 'data/saveGlobal';
  readonly SAVE_ITEM: 'data/saveItem';
  readonly SUBSCRIBE: 'data/subscribe';
  readonly UNSUBSCRIBE: 'data/unsubscribe';
  readonly GLOBAL_UPDATED: 'data/globalUpdated';
  readonly ITEM_UPDATED: 'data/itemUpdated';
  readonly ITEM_DELETED: 'data/itemDeleted';
  readonly NAVIGATE: 'navigation/navigate';
  readonly BACK: 'navigation/back';
  readonly GET_CURRENT: 'navigation/getCurrent';
  readonly READY: 'app/ready';
  readonly CARD_COMPLETED: 'app/cardCompleted';
  readonly NAVIGATE_TO_NEXT_CARD: 'app/navigateToNextCard';
};

export declare function navigateToNextCard(params?: Record<string, any>): Promise<void>;
export declare function completeCard(completionData?: Record<string, any>): Promise<void>;
export declare function navigateToCard(cardId: string, cardData?: Record<string, any>): Promise<void>;
export declare function savePuzzleProgress(progress: number, additionalData?: Record<string, any>): Promise<void>;
export declare function updateGlobalGameState(updates: Record<string, any>): Promise<void>;

// Re-export React hooks for Framer compatibility
export interface UseBridgeReturn {
  bridge: BridgeInstance | null;
  isReady: boolean;
  context: BridgeContext | null;
  environment: 'expo' | 'iframe' | 'standalone';
}

export interface UseBridgeDataReturn<TGlobal = any, TItem = any> {
  globalData: TGlobal | null;
  itemData: TItem | null;
  setGlobal: (data: TGlobal) => Promise<void>;
  setItem: (data: TItem) => Promise<void>;
  navigate: (to: string, params?: Record<string, any>, method?: 'push' | 'replace') => Promise<void>;
  back: (steps?: number) => Promise<void>;
  complete: (data?: Record<string, any>) => Promise<void>;
  isReady: boolean;
  context: BridgeContext | null;
  environment: 'expo' | 'iframe' | 'standalone';
}

export type UseGlobalDataReturn<T = any> = [T | null, (data: T) => Promise<void>];
export type UseItemDataReturn<T = any> = [T | null, (data: T) => Promise<void>];

export declare function useBridge(): UseBridgeReturn;
export declare function useBridgeData<TGlobal = any, TItem = any>(): UseBridgeDataReturn<TGlobal, TItem>;
export declare function useGlobalData<T = any>(initialData?: T): UseGlobalDataReturn<T>;
export declare function useItemData<T = any>(initialData?: T): UseItemDataReturn<T>;
export declare function useNavigation(): {
  navigate: (to: string, params?: Record<string, any>, method?: 'push' | 'replace') => Promise<void>;
  back: (steps?: number) => Promise<void>;
  complete: (data?: Record<string, any>) => Promise<void>;
  isReady: boolean;
};