@frak-labs/frame-connector 0.1.0-beta.afa252b0 → 0.1.0-beta.c7e026e5

package/dist/index-BSzskALu.d.cts

@@ -0,0 +1,402 @@
+import { Prettify } from "viem";
+
+//#region src/rpc-schema.d.ts
+
+/**
+ * Generic shape of a single RPC schema entry
+ *
+ * Each entry defines a method with its parameters, return type, and response kind
+ *
+ * @typeParam TMethod - The method name (string literal)
+ * @typeParam TParams - The parameters type (can be undefined for no parameters)
+ * @typeParam TReturn - The return type
+ * @typeParam TResponseKind - Either "promise" or "stream"
+ */
+type RpcSchemaEntry<TMethod extends string = string, TParams = unknown, TReturn = unknown> = {
+  /**
+   * The method name (e.g., "frak_sendInteraction")
+   */
+  Method: TMethod;
+  /**
+   * The parameters type (undefined if no parameters)
+   */
+  Parameters?: TParams;
+  /**
+   * The return type
+   */
+  ReturnType: TReturn;
+};
+/**
+ * An RPC schema is a readonly array of schema entries
+ *
+ * @example
+ * ```ts
+ * type MySchema = [
+ *   {
+ *     Method: "greet";
+ *     Parameters: [name: string];
+ *     ReturnType: string;
+ *     ResponseType: "promise";
+ *   },
+ *   {
+ *     Method: "watchTime";
+ *     Parameters?: undefined;
+ *     ReturnType: number;
+ *     ResponseType: "stream";
+ *   }
+ * ]
+ * ```
+ */
+type RpcSchema = readonly RpcSchemaEntry[];
+/**
+ * Extract method names from a schema
+ *
+ * @typeParam TSchema - The RPC schema type
+ *
+ * @example
+ * ```ts
+ * type Methods = ExtractMethod<MySchema>
+ * // "greet" | "watchTime"
+ * ```
+ */
+type ExtractMethod<TSchema extends RpcSchema> = TSchema[number]["Method"];
+/**
+ * Extract a specific schema entry by method name
+ *
+ * @typeParam TSchema - The RPC schema type
+ * @typeParam TMethod - The method name to extract
+ *
+ * @example
+ * ```ts
+ * type GreetEntry = ExtractSchemaEntry<MySchema, "greet">
+ * // { Method: "greet"; Parameters: [name: string]; ReturnType: string; ResponseType: "promise" }
+ * ```
+ */
+type ExtractSchemaEntry<TSchema extends RpcSchema, TMethod extends ExtractMethod<TSchema>> = Extract<TSchema[number], {
+  Method: TMethod;
+}>;
+/**
+ * Extract parameters type for a specific method
+ *
+ * @typeParam TSchema - The RPC schema type
+ * @typeParam TMethod - The method name
+ *
+ * @example
+ * ```ts
+ * type GreetParams = ExtractParams<MySchema, "greet">
+ * // [name: string]
+ * ```
+ */
+type ExtractParams<TSchema extends RpcSchema, TMethod extends ExtractMethod<TSchema>> = ExtractSchemaEntry<TSchema, TMethod>["Parameters"];
+/**
+ * Type that extract the possible parameters from a RPC Schema
+ * @ignore
+ */
+type ExtractedParametersFromRpc<TRpcSchema extends RpcSchema> = { [K in keyof TRpcSchema]: Prettify<{
+  method: TRpcSchema[K] extends TRpcSchema[number] ? TRpcSchema[K]["Method"] : string;
+} & (TRpcSchema[K] extends TRpcSchema[number] ? TRpcSchema[K]["Parameters"] extends undefined ? {
+  params?: never;
+} : {
+  params: TRpcSchema[K]["Parameters"];
+} : never)> }[number];
+/**
+ * Type that extract the possible parameters from a RPC Schema
+ * @ignore
+ */
+type ExtractedSpecificParametersFromRpc<TRpcSchema extends RpcSchema, TMethod extends ExtractMethod<TRpcSchema>> = Extract<ExtractedParametersFromRpc<TRpcSchema>, {
+  method: TMethod;
+}>;
+/**
+ * Extract return type for a specific method
+ *
+ * @typeParam TSchema - The RPC schema type
+ * @typeParam TMethod - The method name
+ *
+ * @example
+ * ```ts
+ * type GreetReturn = ExtractReturnType<MySchema, "greet">
+ * // string
+ * ```
+ */
+type ExtractReturnType<TSchema extends RpcSchema, TMethod extends ExtractMethod<TSchema>> = ExtractSchemaEntry<TSchema, TMethod>["ReturnType"];
+//#endregion
+//#region src/types.d.ts
+/**
+ * Transport interface for RPC communication
+ * Abstracts the underlying message passing mechanism (postMessage, etc)
+ */
+type RpcTransport = {
+  /**
+   * Send a message through the transport
+   */
+  postMessage: (message: RpcMessage, targetOrigin: string) => void;
+  /**
+   * Listen for messages
+   */
+  addEventListener: (type: "message", listener: (event: MessageEvent<RpcMessage>) => void) => void;
+  /**
+   * Remove message listener
+   */
+  removeEventListener: (type: "message", listener: (event: MessageEvent<RpcMessage>) => void) => void;
+};
+/**
+ * RPC message format (maintains backward compatibility)
+ * This is the exact format sent over the wire
+ *
+ * @typeParam TMethod - The method name type (defaults to string for flexibility)
+ */
+type RpcMessage<TMethod extends string = string> = {
+  /**
+   * Unique message identifier for correlating requests and responses
+   */
+  id: string;
+  /**
+   * The RPC method name (topic for backward compatibility)
+   */
+  topic: TMethod;
+  /**
+   * The message payload (compressed data) or raw params
+   */
+  data: unknown;
+};
+/**
+ * Lifecycle message format for client-to-iframe communication
+ * These messages handle connection lifecycle events (handshake, heartbeat, etc.)
+ */
+type ClientLifecycleMessage = {
+  clientLifecycle: string;
+  data?: unknown;
+};
+/**
+ * Lifecycle message format for iframe-to-client communication
+ */
+type IFrameLifecycleMessage = {
+  iframeLifecycle: string;
+  data?: unknown;
+};
+/**
+ * Union of all lifecycle message types
+ */
+type LifecycleMessage = ClientLifecycleMessage | IFrameLifecycleMessage;
+/**
+ * Union of all message types that can be received
+ */
+type AnyMessage = RpcMessage | LifecycleMessage;
+/**
+ * RPC response wrapper
+ * Contains either a successful result or an error
+ */
+type RpcResponse<TResult = unknown> = {
+  result: TResult;
+  error?: never;
+} | {
+  result?: never;
+  error: RpcError;
+};
+/**
+ * RPC error object
+ */
+type RpcError = {
+  code: number;
+  message: string;
+  data?: unknown;
+};
+/**
+ * Request context for handlers
+ * Contains information about the origin and source of the request
+ */
+type RpcRequestContext = {
+  /**
+   * Origin of the request
+   */
+  origin: string;
+  /**
+   * Message source (for responding)
+   */
+  source: MessageEventSource | null;
+};
+/**
+ * Middleware context that can be augmented with custom fields
+ * Generic type parameter allows domain-specific context augmentation
+ *
+ * @typeParam TCustomContext - Custom context fields to merge with base context
+ *
+ * @example
+ * ```ts
+ * type WalletContext = RpcMiddlewareContext<{
+ *   productId: string
+ *   sourceUrl: string
+ *   isAutoContext: boolean
+ * }>
+ * // { origin: string, source: MessageEventSource | null, productId: string, sourceUrl: string, isAutoContext: boolean }
+ * ```
+ */
+type RpcMiddlewareContext<TCustomContext = Record<string, never>> = RpcRequestContext & TCustomContext;
+/**
+ * Type-safe request parameters
+ *
+ * @typeParam TSchema - The RPC schema type
+ * @typeParam TMethod - The method name from the schema
+ */
+type TypedRpcRequest<TSchema extends RpcSchema, TMethod extends ExtractMethod<TSchema>> = {
+  method: TMethod;
+  params: ExtractParams<TSchema, TMethod>;
+};
+/**
+ * Stream emitter function
+ * Used by stream handlers to emit multiple values
+ */
+type StreamEmitter<TResult> = (chunk: TResult) => void;
+/**
+ * Lifecycle handler function
+ * Handles lifecycle events using discriminated unions for automatic type narrowing
+ *
+ * @typeParam TLifecycleEvent - The lifecycle event union type (e.g., ClientLifecycleEvent | IFrameLifecycleEvent)
+ *
+ * @param event - The full lifecycle event object with discriminated union
+ * @param context - Request context with origin and source
+ *
+ * @example
+ * ```ts
+ * const handler: LifecycleHandler<ClientLifecycleEvent> = (event, context) => {
+ *   if (event.clientLifecycle === "modal-css") {
+ *     // event.data is automatically typed as { cssLink: string }
+ *     console.log(event.data.cssLink)
+ *   }
+ * }
+ * ```
+ */
+type LifecycleHandler<TLifecycleEvent = unknown> = (event: TLifecycleEvent, context: RpcRequestContext) => void | Promise<void>;
+/**
+ * Unified middleware function for RPC requests (both listener and client)
+ * Works on both listener-side (with context augmentation) and client-side (empty context)
+ *
+ * Key features:
+ * - Can mutate message.data directly for efficiency (compression, validation)
+ * - Can mutate response.result directly for transformation
+ * - Listener-side: Can augment context by returning modified context
+ * - Client-side: Uses TContext = {} (empty context), always returns unchanged
+ *
+ * @typeParam TSchema - The RPC schema type
+ * @typeParam TContext - Custom context type to augment base context (empty {} for client-side)
+ *
+ * @example Listener-side with context augmentation
+ * ```ts
+ * type WalletContext = { productId: string, sourceUrl: string }
+ * const contextMiddleware: RpcMiddleware<MySchema, WalletContext> = {
+ *   onRequest: async (message, context) => {
+ *     // Read from store and augment context
+ *     const productId = await getProductId(context.origin)
+ *     return { ...context, productId, sourceUrl: context.origin }
+ *   }
+ * }
+ * ```
+ *
+ * @example Client-side (empty context)
+ * ```ts
+ * const compressionMiddleware: RpcMiddleware<MySchema> = {
+ *   onRequest: async (message, context) => {
+ *     // Mutate message.data directly
+ *     message.data = compress(message.data)
+ *     return context  // Empty context, unchanged
+ *   },
+ *   onResponse: async (message, response, context) => {
+ *     // Mutate response.result directly
+ *     response.result = decompress(response.result)
+ *     return response
+ *   }
+ * }
+ * ```
+ *
+ * @example Shared middleware (works on both sides)
+ * ```ts
+ * const loggingMiddleware: RpcMiddleware<MySchema> = {
+ *   onRequest: async (message, context) => {
+ *     console.log(`[RPC] ${message.topic}`, context.origin || 'client')
+ *     return context
+ *   },
+ *   onResponse: async (message, response, context) => {
+ *     console.log(`[RPC] ${message.topic} completed`)
+ *     return response
+ *   }
+ * }
+ * ```
+ */
+type RpcMiddleware<TSchema extends RpcSchema, TContext = Record<string, never>> = {
+  /**
+   * Called before handler execution (listener) or before sending (client)
+   *
+   * For listener: Can augment context and mutate message
+   * For client: Can mutate message, context is empty {}
+   *
+   * @param message - The RPC message (can be mutated)
+   * @param context - Request context (listener-side) or empty (client-side)
+   * @returns Updated context (listener mutates this, client returns unchanged)
+   * @throws FrakRpcError to reject the request with a specific error code
+   */
+  onRequest?: (message: RpcMessage<ExtractMethod<TSchema>>, context: RpcMiddlewareContext<TContext>) => Promise<RpcMiddlewareContext<TContext>> | RpcMiddlewareContext<TContext>;
+  /**
+   * Called after handler execution (listener) or after receiving (client)
+   *
+   * @param message - The original RPC message
+   * @param response - The response (can be mutated)
+   * @param context - Request context (listener-side) or empty (client-side)
+   * @returns Transformed response
+   * @throws Error to send an error response instead
+   */
+  onResponse?: (message: RpcMessage<ExtractMethod<TSchema>>, response: RpcResponse, context: RpcMiddlewareContext<TContext>) => Promise<RpcResponse> | RpcResponse;
+};
+/**
+ * Promise handler function type
+ * Handles one-shot requests that return a single promise
+ *
+ * @typeParam TSchema - The RPC schema type
+ * @typeParam TMethod - The method name from the schema
+ * @typeParam TContext - Custom context type augmented by middleware
+ */
+type RpcPromiseHandler<TSchema extends RpcSchema, TMethod extends ExtractMethod<TSchema>, TContext = Record<string, never>> = (params: ExtractParams<TSchema, TMethod>, context: RpcMiddlewareContext<TContext>) => Promise<ExtractReturnType<TSchema, TMethod>>;
+/**
+ * Stream handler function type
+ * Handles streaming requests that can emit multiple values
+ *
+ * @typeParam TSchema - The RPC schema type
+ * @typeParam TMethod - The method name from the schema
+ * @typeParam TContext - Custom context type augmented by middleware
+ */
+type RpcStreamHandler<TSchema extends RpcSchema, TMethod extends ExtractMethod<TSchema>, TContext = Record<string, never>> = (params: ExtractParams<TSchema, TMethod>, emitter: StreamEmitter<ExtractReturnType<TSchema, TMethod>>, context: RpcMiddlewareContext<TContext>) => Promise<void> | void;
+//#endregion
+//#region src/middleware/compression.d.ts
+/**
+ * Client-side compression middleware
+ *
+ * Compresses outgoing requests and decompresses incoming responses.
+ * Always uses the format: {method: string, params: unknown}
+ *
+ * @example Client side
+ * ```ts
+ * const client = createRpcClient({
+ *   transport: iframe.contentWindow,
+ *   targetOrigin: 'https://wallet.frak.id',
+ *   middleware: [createClientCompressionMiddleware()]
+ * })
+ * ```
+ */
+declare const createClientCompressionMiddleware: <TSchema extends RpcSchema, TContext>() => RpcMiddleware<TSchema, TContext>;
+/**
+ * Listener-side compression middleware
+ *
+ * Decompresses incoming requests and compresses outgoing responses.
+ * Always uses the format: {method: string, params: unknown}
+ *
+ * @example Listener side
+ * ```ts
+ * const listener = createRpcListener({
+ *   transport: window,
+ *   allowedOrigins: ['https://example.com'],
+ *   middleware: [createListenerCompressionMiddleware()]
+ * })
+ * ```
+ */
+declare const createListenerCompressionMiddleware: <TSchema extends RpcSchema, TContext>() => RpcMiddleware<TSchema, TContext>;
+//#endregion
+export { ExtractedParametersFromRpc as C, RpcSchemaEntry as E, ExtractSchemaEntry as S, RpcSchema as T, StreamEmitter as _, IFrameLifecycleMessage as a, ExtractParams as b, RpcError as c, RpcMiddlewareContext as d, RpcPromiseHandler as f, RpcTransport as g, RpcStreamHandler as h, ClientLifecycleMessage as i, RpcMessage as l, RpcResponse as m, createListenerCompressionMiddleware as n, LifecycleHandler as o, RpcRequestContext as p, AnyMessage as r, LifecycleMessage as s, createClientCompressionMiddleware as t, RpcMiddleware as u, TypedRpcRequest as v, ExtractedSpecificParametersFromRpc as w, ExtractReturnType as x, ExtractMethod as y };