@frak-labs/core-sdk 0.0.19 → 0.1.0-beta.8d103039

package/dist/index.d.ts

@@ -1,10 +1,17 @@
 import type { Address } from 'viem';
 import type { Hex } from 'viem';
+import type { LifecycleMessage } from '@frak-labs/frame-connector';
 import type { OpenPanel } from '@openpanel/web';
-import type { Prettify } from 'viem/chains';
-import type { RpcSchema } from 'viem';
+import type { RpcClient } from '@frak-labs/frame-connector';
+import { RpcMessage } from '@frak-labs/frame-connector';
+import { RpcResponse } from '@frak-labs/frame-connector';
 import type { SiweMessage } from 'viem/siwe';
 
+export declare type AppSpecificSsoMetadata = SsoMetadata & {
+    name: string;
+    css?: string;
+};
+
 /**
  * Decode a base64url encoded string
  * @param value The value to decode
@@ -44,12 +51,7 @@ export declare const baseIframeProps: {
  * Event related to the iframe lifecycle
  * @ignore
  */
-export declare type ClientLifecycleEvent = CustomCssEvent | CustomI18nEvent | RestoreBackupEvent | HearbeatEvent | HandshakeResponse;
-
-/** @ignore */
-export declare class ClientNotFound extends FrakRpcError {
-    constructor();
-}
+export declare type ClientLifecycleEvent = CustomCssEvent | CustomI18nEvent | RestoreBackupEvent | HearbeatEvent | HandshakeResponse | SsoRedirectCompleteEvent;
 
 /**
  * Compress the current Frak context
@@ -66,11 +68,21 @@ declare function compress(context?: Partial<FrakContext>): string | undefined;
 export declare type CompressedData = Uint8Array;
 
 /**
- * Compress json data
- * @param data
- * @ignore
+ * Type of compressed the sso data
  */
-export declare function compressJson(data: unknown): Uint8Array;
+export declare type CompressedSsoData = {
+    id?: Hex;
+    r?: string;
+    d?: boolean;
+    l?: "en" | "fr";
+    p: Hex;
+    m: {
+        n: string;
+        css?: string;
+        l?: string;
+        h?: string;
+    };
+};
 
 /**
  * Compress json data
@@ -139,8 +151,8 @@ export declare class DebugInfoGatherer {
     private lastResponse;
     private lastRequest;
     constructor(config?: FrakWalletSdkConfig, iframe?: HTMLIFrameElement);
-    setLastResponse(event: MessageEvent<IFrameEvent>): void;
-    setLastRequest(event: IFrameEvent, target: string): void;
+    setLastResponse(message: RpcMessage, response: RpcResponse): void;
+    setLastRequest(event: RpcMessage): void;
     updateSetupStatus(status: boolean): void;
     private base64Encode;
     /**
@@ -163,20 +175,6 @@ export declare class DebugInfoGatherer {
  */
 declare function decompress(context?: string): FrakContext | undefined;
 
-/**
- * Decompress the given string
- * @param compressedData The params to encode
- * @ignore
- */
-export declare function decompressDataAndCheckHash<T>(compressedData: CompressedData): HashProtectedData<T>;
-
-/**
- * Decompress json data
- * @param data
- * @ignore
- */
-export declare function decompressJson<T>(data: Uint8Array): T | null;
-
 /**
  * Decompress json data
  * @param data
@@ -184,20 +182,6 @@ export declare function decompressJson<T>(data: Uint8Array): T | null;
  */
 export declare function decompressJsonFromB64<T>(data: string): T | null;
 
-/**
- * Simple deferred promise wrapper
- * @ignore
- */
-export declare class Deferred<T> {
-    private readonly _promise;
-    private _resolve;
-    private _reject;
-    constructor();
-    get promise(): Promise<T>;
-    resolve: (value: T | PromiseLike<T>) => void;
-    reject: (reason?: unknown) => void;
-}
-
 /**
  * The params used to display the embedded wallet
  *
@@ -311,34 +295,6 @@ export declare type EmbeddedViewActionSharing = {
 
 declare type EventProps = Record<string, unknown>;
 
-/**
- * Type that extract the possible return type from a RPC Schema
- * @ignore
- */
-declare type ExtractedMethodFromRpc<TRpcSchema extends RpcSchema, TMethod extends ExtractedParametersFromRpc<TRpcSchema>["method"] = ExtractedParametersFromRpc<TRpcSchema>["method"]> = Extract<TRpcSchema[number], {
-    Method: TMethod;
-}>;
-
-/**
- * Type that extract the possible parameters from a RPC Schema
- * @ignore
- */
-export declare 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 return type from a RPC Schema
- * @ignore
- */
-export declare type ExtractedReturnTypeFromRpc<TRpcSchema extends RpcSchema, TParameters extends ExtractedParametersFromRpc<TRpcSchema> = ExtractedParametersFromRpc<TRpcSchema>> = ExtractedMethodFromRpc<TRpcSchema, TParameters["method"]>["ReturnType"];
-
 /**
  * The different types of final actions we can display in the final step
  * @group Modal Display
@@ -375,6 +331,27 @@ export declare type FinalModalStepType = GenericModalStepType<"final", {
     autoSkip?: boolean;
 }, object>;
 
+/**
+ * Find an iframe within window.opener by pathname
+ *
+ * When a popup is opened via window.open from an iframe, window.opener points to
+ * the parent window, not the iframe itself. This utility searches through all frames
+ * in window.opener to find an iframe matching the specified pathname.
+ *
+ * @param pathname - The pathname to search for (default: "/listener")
+ * @returns The matching iframe window, or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Find the default /listener iframe
+ * const listenerIframe = findIframeInOpener();
+ *
+ * // Find a custom iframe
+ * const customIframe = findIframeInOpener("/my-custom-iframe");
+ * ```
+ */
+export declare function findIframeInOpener(pathname?: string): Window | null;
+
 export declare function formatAmount(amount: number, currency?: Currency): string;
 
 /**
@@ -400,7 +377,7 @@ export declare type FrakContext = {
 };
 
 /**
- * Export our frak context "class"
+ * Export our frak context
  */
 export declare const FrakContextManager: {
     compress: typeof compress;
@@ -414,14 +391,9 @@ export declare const FrakContextManager: {
 declare type FrakEvent = "share_button_clicked" | "wallet_button_clicked" | "share_modal_error" | "user_referred";
 
 /**
- * Generic Frak RPC error
- * @ignore
+ * Represent an iframe event
  */
-export declare class FrakRpcError<T = undefined> extends Error {
-    code: number;
-    data?: T | undefined;
-    constructor(code: number, message: string, data?: T | undefined);
-}
+export declare type FrakLifecycleEvent = IFrameLifecycleEvent | ClientLifecycleEvent;
 
 /**
  * Configuration for the Frak Wallet SDK
@@ -488,6 +460,38 @@ export declare type FullInteractionTypesKey = {
     [Category in keyof typeof interactionTypes]: `${Category & string}.${keyof (typeof interactionTypes)[Category] & string}`;
 }[keyof typeof interactionTypes];
 
+/**
+ * The full SSO params that will be used for compression
+ */
+export declare type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
+    metadata: AppSpecificSsoMetadata;
+    productId: Hex;
+};
+
+/**
+ * Generate SSO URL with compressed parameters
+ * This mirrors the wallet's getOpenSsoLink() function
+ *
+ * @param walletUrl - Base wallet URL (e.g., "https://wallet.frak.id")
+ * @param params - SSO parameters
+ * @param productId - Product identifier
+ * @param name - Application name
+ * @param css - Optional custom CSS
+ * @returns Complete SSO URL ready to open in popup or redirect
+ *
+ * @example
+ * ```ts
+ * const ssoUrl = generateSsoUrl(
+ *   "https://wallet.frak.id",
+ *   { metadata: { logoUrl: "..." }, directExit: true },
+ *   "0x123...",
+ *   "My App"
+ * );
+ * // Returns: https://wallet.frak.id/sso?p=<compressed_base64>
+ * ```
+ */
+export declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, productId: Hex, name: string, css?: string): string;
+
 /**
  * Represent a generic modal step type
  * @ignore
@@ -581,13 +585,6 @@ declare type HandshakeResponse = {
     };
 };
 
-/**
- * Compress the given params, and add hash protection to (rapidly) prevent interception modification
- * @param data The params to encode
- * @ignore
- */
-export declare function hashAndCompressData<T>(data: T): CompressedData;
-
 /**
  * The encoded data to send to a client / received by a client
  *  @ignore
@@ -598,6 +595,7 @@ export declare type HashProtectedData<DataType> = Readonly<DataType & {
 
 declare type HearbeatEvent = {
     clientLifecycle: "heartbeat";
+    data?: never;
 };
 
 /**
@@ -635,66 +633,63 @@ declare type HearbeatEvent = {
  */
 export declare type I18nConfig = Record<Language, LocalizedI18nConfig> | LocalizedI18nConfig;
 
-/**
- * Represent an iframe event
- */
-export declare type IFrameEvent = IFrameRpcEvent | IFrameLifecycleEvent | ClientLifecycleEvent;
-
 /**
  * Event related to the iframe lifecycle
  * @ignore
  */
 export declare type IFrameLifecycleEvent = {
-    iframeLifecycle: "connected" | "show" | "hide";
+    iframeLifecycle: "connected" | "show" | "hide" | "remove-backup";
     data?: never;
-} | DoBackupEvent | RemoveBackupEvent | HandshakeRequestEvent | RedirectRequestEvent;
-
-/**
- * Represent an iframe rpc event
- */
-export declare type IFrameRpcEvent = {
-    id: string;
-    topic: ExtractedParametersFromRpc<IFrameRpcSchema>["method"];
-    data: CompressedData;
-};
+} | DoBackupEvent | HandshakeRequestEvent | RedirectRequestEvent;
 
 /**
  * RPC interface that's used for the iframe communication
  *
- * Define all the methods available within the iFrame RPC client
+ * Define all the methods available within the iFrame RPC client with response type annotations
  *
  * @group RPC Schema
  *
  * @remarks
- * Here is the list of methods available:
+ * Each method in the schema now includes a ResponseType field that indicates:
+ * - "promise": One-shot request that resolves once
+ * - "stream": Streaming request that can emit multiple values
+ *
+ * ### Methods:
  *
- * ### frak_listenToWalletStatus
+ * #### frak_listenToWalletStatus
  *  - Params: None
  *  - Returns: {@link WalletStatusReturnType}
+ *  - Response Type: stream (emits updates when wallet status changes)
  *
- * ### frak_displayModal
- * - Params: [{@link ModalRpcStepsInput}, name: string, metadata?: {@link ModalRpcMetadata}]
+ * #### frak_displayModal
+ * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"]]
  * - Returns: {@link ModalRpcStepsResultType}
+ * - Response Type: promise (one-shot)
  *
- * ### frak_sendInteraction
+ * #### frak_sendInteraction
  *  - Params: [productId: Hex, interaction: {@link PreparedInteraction}, signature?: Hex]
  *  - Returns: {@link SendInteractionReturnType}
+ *  - Response Type: promise (one-shot)
  *
- * ### frak_sso
- *  - Params [params: {@link OpenSsoParamsType}, name: string, customCss?: string]
- *  - Returns: undefined
+ * #### frak_sso
+ *  - Params: [params: {@link OpenSsoParamsType}, name: string, customCss?: string]
+ *  - Returns: {@link OpenSsoReturnType}
+ *  - Response Type: promise (one-shot)
  *
- *  ### frak_getProductInformation
+ * #### frak_getProductInformation
  *  - Params: None
  *  - Returns: {@link GetProductInformationReturnType}
+ *  - Response Type: promise (one-shot)
  *
- * ### frak_displayEmbeddedWallet
- * - Params: [{@link DisplayEmbeddedWalletParamsType}]
+ * #### frak_displayEmbeddedWallet
+ * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"]]
  * - Returns: {@link DisplayEmbeddedWalletResultType}
+ * - Response Type: promise (one-shot)
  */
 export declare type IFrameRpcSchema = [
 /**
 * Method used to listen to the wallet status
+* This is a streaming method that emits updates when wallet status changes
 */
     {
     Method: "frak_listenToWalletStatus";
@@ -703,6 +698,7 @@ export declare type IFrameRpcSchema = [
 },
 /**
 * Method to display a modal with the provided steps
+* This is a one-shot request
 */
     {
     Method: "frak_displayModal";
@@ -715,6 +711,7 @@ export declare type IFrameRpcSchema = [
 },
 /**
 * Method to transmit a user interaction
+* This is a one-shot request
 */
     {
     Method: "frak_sendInteraction";
@@ -726,23 +723,40 @@ export declare type IFrameRpcSchema = [
     ReturnType: SendInteractionReturnType;
 },
 /**
-* Method to start a SSO
-*  todo: Should also support direct tracking via a consumeKey
+* Method to prepare SSO (generate URL for popup)
+* Returns the SSO URL that should be opened in a popup
+* Only used for popup flows (not redirect flows)
 */
     {
-    Method: "frak_sso";
+    Method: "frak_prepareSso";
+    Parameters: [
+    params: PrepareSsoParamsType,
+    name: string,
+    customCss?: string
+    ];
+    ReturnType: PrepareSsoReturnType;
+},
+/**
+* Method to open/trigger SSO
+* Either triggers redirect (if openInSameWindow/redirectUrl)
+* Or waits for popup completion (if popup mode)
+* This method handles BOTH redirect and popup flows
+*/
+    {
+    Method: "frak_openSso";
     Parameters: [
     params: OpenSsoParamsType,
     name: string,
     customCss?: string
     ];
-    ReturnType: undefined;
+    ReturnType: OpenSsoReturnType;
 },
 /**
 * Method to get current product information's
 *  - Is product minted?
 *  - Does it have running campaign?
 *  - Estimated reward on actions
+* This is a one-shot request
 */
     {
     Method: "frak_getProductInformation";
@@ -751,6 +765,7 @@ export declare type IFrameRpcSchema = [
 },
 /**
 * Method to show the embedded wallet, with potential customization
+* This is a one-shot request
 */
     {
     Method: "frak_displayEmbeddedWallet";
@@ -777,11 +792,11 @@ export declare type IFrameTransport = {
     /**
      * Function used to perform a single request via the iframe transport
      */
-    request: RequestFn<IFrameRpcSchema>;
+    request: RpcClient<IFrameRpcSchema, LifecycleMessage>["request"];
     /**
      * Function used to listen to a request response via the iframe transport
      */
-    listenerRequest: ListenerRequestFn<IFrameRpcSchema>;
+    listenerRequest: RpcClient<IFrameRpcSchema, LifecycleMessage>["listen"];
     /**
      * Function used to destroy the iframe transport
      */
@@ -837,12 +852,6 @@ export declare type KeyProvider<DataType> = (value: DataType) => string[];
  */
 export declare type Language = "fr" | "en";
 
-/**
- * Type used for a listening request
- * @inline
- */
-declare type ListenerRequestFn<TRpcSchema extends RpcSchema> = <TParameters extends ExtractedParametersFromRpc<TRpcSchema> = ExtractedParametersFromRpc<TRpcSchema>, _ReturnType = ExtractedReturnTypeFromRpc<TRpcSchema, TParameters>>(args: TParameters, callback: (result: _ReturnType) => void) => Promise<void>;
-
 /**
  * Map the currency to the locale
  */
@@ -1047,25 +1056,27 @@ export declare type OpenInteractionSessionReturnType = {
  * Params to start a SSO
  * @group RPC Schema
  */
-export declare type OpenSsoParamsType = {
+export declare type OpenSsoParamsType = PrepareSsoParamsType & {
     /**
-     * Redirect URL after the SSO (optional)
+     * Indicate whether we want todo the flow within the same window context, or if we want to do it with an external popup window openned
+     * Note: Default true if redirectUrl is present, otherwise, false
      */
-    redirectUrl?: string;
+    openInSameWindow?: boolean;
     /**
-     * If the SSO should directly exit after completion
-     * @defaultValue true
+     * Custom SSO popup url if user want additionnal customisation
      */
-    directExit?: boolean;
-    /**
-     * Language of the SSO page (optional)
-     * It will default to the current user language (or "en" if unsupported language)
-     */
-    lang?: "en" | "fr";
+    ssoPopupUrl?: string;
+};
+
+/**
+ * Response after an SSO has been openned
+ */
+export declare type OpenSsoReturnType = {
     /**
-     * Custom SSO metadata
+     * Optional wallet address, returned when SSO completes via postMessage
+     * Note: Only present when SSO flow completes (not immediately on open)
      */
-    metadata: SsoMetadata;
+    wallet?: Hex;
 };
 
 /**
@@ -1086,6 +1097,43 @@ export declare type PreparedInteraction = {
     interactionData: Hex;
 };
 
+/**
+ * Params for preparing SSO (generating URL)
+ * Same as OpenSsoParamsType but without openInSameWindow (popup-only operation)
+ * @group RPC Schema
+ */
+export declare type PrepareSsoParamsType = {
+    /**
+     * Redirect URL after the SSO (optional)
+     */
+    redirectUrl?: string;
+    /**
+     * If the SSO should directly exit after completion
+     * @defaultValue true
+     */
+    directExit?: boolean;
+    /**
+     * Language of the SSO page (optional)
+     * It will default to the current user language (or "en" if unsupported language)
+     */
+    lang?: "en" | "fr";
+    /**
+     * Custom SSO metadata
+     */
+    metadata?: SsoMetadata;
+};
+
+/**
+ * Response after preparing SSO
+ * @group RPC Schema
+ */
+export declare type PrepareSsoReturnType = {
+    /**
+     * The SSO URL that should be opened in a popup
+     */
+    ssoUrl: string;
+};
+
 /**
  * List of the product types per denominator
  */
@@ -1113,7 +1161,8 @@ declare type RedirectRequestEvent = {
     iframeLifecycle: "redirect";
     data: {
         /**
-         * The base url to redirect to (contain a query param `u`, the client need to suffix the current url to the base url)
+         * The base url to redirect to
+         *  If it contain a query param `u`, the client need will suffix the current url to the base url
          */
         baseRedirectUrl: string;
     };
@@ -1126,10 +1175,6 @@ declare type RedirectRequestEvent = {
  */
 declare function remove(url: string): string;
 
-declare type RemoveBackupEvent = {
-    iframeLifecycle: "remove-backup";
-};
-
 /**
  * Replace the current url with the given Frak context
  * @param args
@@ -1141,12 +1186,6 @@ declare function replaceUrl({ url: baseUrl, context, }: {
     context: Partial<FrakContext> | null;
 }): void;
 
-/**
- * Type used for a one shot request function
- * @inline
- */
-declare type RequestFn<TRpcSchema extends RpcSchema> = <TParameters extends ExtractedParametersFromRpc<TRpcSchema> = ExtractedParametersFromRpc<TRpcSchema>, _ReturnType = ExtractedReturnTypeFromRpc<TRpcSchema, TParameters>>(args: TParameters) => Promise<_ReturnType>;
-
 declare type RestoreBackupEvent = {
     clientLifecycle: "restore-backup";
     data: {
@@ -1154,42 +1193,6 @@ declare type RestoreBackupEvent = {
     };
 };
 
-/**
- * The different Frak RPC error codes
- */
-export declare const RpcErrorCodes: {
-    readonly parseError: -32700;
-    readonly invalidRequest: -32600;
-    readonly methodNotFound: -32601;
-    readonly invalidParams: -32602;
-    readonly internalError: -32603;
-    readonly serverError: -32000;
-    readonly clientNotConnected: -32001;
-    readonly configError: -32002;
-    readonly corruptedResponse: -32003;
-    readonly clientAborted: -32004;
-    readonly walletNotConnected: -32005;
-    readonly serverErrorForInteractionDelegation: -32006;
-};
-
-/**
- * Raw response that we will receive after an rpc request
- * @ignore
- */
-export declare type RpcResponse<TRpcSchema extends RpcSchema, TMethod extends TRpcSchema[number]["Method"] = TRpcSchema[number]["Method"]> = {
-    result: Extract<TRpcSchema[number], {
-        Method: TMethod;
-    }>["ReturnType"];
-    error?: never;
-} | {
-    result?: never;
-    error: {
-        code: number;
-        message: string;
-        data?: unknown;
-    };
-};
-
 /**
  * Parameters that will be used to send an interaction to the blockchain
  * @inline
@@ -1315,6 +1318,17 @@ export declare type SsoMetadata = {
     homepageLink?: string;
 };
 
+export declare const ssoPopupFeatures = "menubar=no,status=no,scrollbars=no,fullscreen=no,width=500, height=800";
+
+export declare const ssoPopupName = "frak-sso";
+
+declare type SsoRedirectCompleteEvent = {
+    clientLifecycle: "sso-redirect-complete";
+    data: {
+        compressed: string;
+    };
+};
+
 /**
  * The type for the amount of tokens
  */