@frak-labs/core-sdk 0.0.19-beta.f259d7fc → 0.1.0-beta.afa252b0

package/dist/bundle.d.cts

@@ -7,6 +7,11 @@ 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
@@ -62,6 +67,23 @@ declare function compress(context?: Partial<FrakContext>): string | undefined;
  */
 export declare type CompressedData = Uint8Array;
 
+/**
+ * Type of compressed the sso data
+ */
+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
  * @param data
@@ -431,6 +453,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;
 
 /**
@@ -539,6 +582,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
@@ -777,11 +852,27 @@ export declare type IFrameRpcSchema = [
     ReturnType: SendInteractionReturnType;
 },
 /**
-* Method to start a SSO
-* This is a one-shot request
+* 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,
@@ -1173,7 +1264,16 @@ export declare type OpenInteractionSessionReturnType = {
  * @param client - The current Frak Client
  * @param args - The SSO parameters
  *
- * @description This function will open the SSO with the provided parameters.
+ * @description Two SSO flow modes:
+ *
+ * **Redirect Mode** (openInSameWindow: true):
+ * - Wallet generates URL and triggers redirect
+ * - Used when redirectUrl is provided
+ *
+ * **Popup Mode** (openInSameWindow: false/omitted):
+ * - SDK generates URL client-side (or uses provided ssoPopupUrl)
+ * - Opens popup synchronously (prevents popup blockers)
+ * - Waits for SSO completion via postMessage
  *
  * @example
  * First we build the sso metadata
@@ -1187,28 +1287,28 @@ export declare type OpenInteractionSessionReturnType = {
  *
  * Then, either use it with direct exit (and so user is directly redirected to your website), or a custom redirect URL
  * :::code-group
- * ```ts [Direct exit]
- * // Trigger an sso opening with redirection
+ * ```ts [Popup (default)]
+ * // Opens in popup, SDK generates URL automatically
  * await openSso(frakConfig, {
  *     directExit: true,
  *     metadata,
  * });
  * ```
- * ```ts [Redirection]
- * // Trigger an sso opening within a popup with direct exit
+ * ```ts [Redirect]
+ * // Opens in same window with redirect
  * await openSso(frakConfig, {
  *     redirectUrl: "https://my-app.com/frak-sso",
  *     metadata,
+ *     openInSameWindow: true,
  * });
  * ```
- * ```ts [With tracking]
- * // Trigger an sso with consumeKey for tracking
- * const result = await openSso(frakConfig, {
- *     directExit: true,
- *     generateConsumeKey: true,
+ * ```ts [Custom popup URL]
+ * // Advanced: provide custom SSO URL
+ * const { ssoUrl } = await prepareSso(frakConfig, { metadata });
+ * await openSso(frakConfig, {
  *     metadata,
+ *     ssoPopupUrl: `${ssoUrl}&custom=param`,
  * });
- * console.log(result.consumeKey); // Use this to track SSO status
  * ```
  * :::
  */
@@ -1218,30 +1318,16 @@ export declare function openSso(client: FrakClient, args: OpenSsoParamsType): Pr
  * Params to start a SSO
  * @group RPC Schema
  */
-export declare type OpenSsoParamsType = {
+export declare type OpenSsoParamsType = PrepareSsoParamsType & {
     /**
-     * Redirect URL after the SSO (optional)
-     */
-    redirectUrl?: string;
-    /**
-     * If the SSO should directly exit after completion
-     * @defaultValue true
-     */
-    directExit?: boolean;
-    /**
-     * If true, opens SSO in same window instead of popup
-     * Defaults to true when redirectUrl is provided, false otherwise
+     * 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
      */
     openInSameWindow?: boolean;
     /**
-     * Language of the SSO page (optional)
-     * It will default to the current user language (or "en" if unsupported language)
+     * Custom SSO popup url if user want additionnal customisation
      */
-    lang?: "en" | "fr";
-    /**
-     * Custom SSO metadata
-     */
-    metadata: SsoMetadata;
+    ssoPopupUrl?: string;
 };
 
 /**
@@ -1273,6 +1359,76 @@ export declare type PreparedInteraction = {
     interactionData: Hex;
 };
 
+/**
+ * Generate SSO URL without opening popup
+ *
+ * This is a **synchronous**, client-side function that generates the SSO URL
+ * without any RPC calls to the wallet iframe. Use this when you need:
+ * - Custom URL modifications before opening popup
+ * - Pre-generation for advanced popup strategies
+ * - URL inspection/logging before SSO flow
+ *
+ * @param client - The current Frak Client
+ * @param args - The SSO parameters
+ * @returns Object containing the generated ssoUrl
+ *
+ * @example
+ * ```ts
+ * // Generate URL for inspection
+ * const { ssoUrl } = prepareSso(client, {
+ *   metadata: { logoUrl: "..." },
+ *   directExit: true
+ * });
+ * console.log("Opening SSO:", ssoUrl);
+ *
+ * // Add custom params
+ * const customUrl = `${ssoUrl}&tracking=abc123`;
+ * await openSso(client, { metadata, ssoPopupUrl: customUrl });
+ * ```
+ *
+ * @remarks
+ * For most use cases, just use `openSso()` which handles URL generation automatically.
+ * Only use `prepareSso()` when you need explicit control over the URL.
+ */
+export declare function prepareSso(client: FrakClient, args: PrepareSsoParamsType): Promise<PrepareSsoReturnType>;
+
+/**
+ * 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;
+};
+
 /**
  * Press interactions allow you to track user engagement with articles or other press content on your platform.
  * After setting up these interactions, you can create acquisition campaign based on the user engagement with your press content.
@@ -1790,6 +1946,10 @@ 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: {

package/dist/bundle.d.ts

@@ -7,6 +7,11 @@ 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
@@ -62,6 +67,23 @@ declare function compress(context?: Partial<FrakContext>): string | undefined;
  */
 export declare type CompressedData = Uint8Array;
 
+/**
+ * Type of compressed the sso data
+ */
+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
  * @param data
@@ -431,6 +453,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;
 
 /**
@@ -539,6 +582,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
@@ -777,11 +852,27 @@ export declare type IFrameRpcSchema = [
     ReturnType: SendInteractionReturnType;
 },
 /**
-* Method to start a SSO
-* This is a one-shot request
+* 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,
@@ -1173,7 +1264,16 @@ export declare type OpenInteractionSessionReturnType = {
  * @param client - The current Frak Client
  * @param args - The SSO parameters
  *
- * @description This function will open the SSO with the provided parameters.
+ * @description Two SSO flow modes:
+ *
+ * **Redirect Mode** (openInSameWindow: true):
+ * - Wallet generates URL and triggers redirect
+ * - Used when redirectUrl is provided
+ *
+ * **Popup Mode** (openInSameWindow: false/omitted):
+ * - SDK generates URL client-side (or uses provided ssoPopupUrl)
+ * - Opens popup synchronously (prevents popup blockers)
+ * - Waits for SSO completion via postMessage
  *
  * @example
  * First we build the sso metadata
@@ -1187,28 +1287,28 @@ export declare type OpenInteractionSessionReturnType = {
  *
  * Then, either use it with direct exit (and so user is directly redirected to your website), or a custom redirect URL
  * :::code-group
- * ```ts [Direct exit]
- * // Trigger an sso opening with redirection
+ * ```ts [Popup (default)]
+ * // Opens in popup, SDK generates URL automatically
  * await openSso(frakConfig, {
  *     directExit: true,
  *     metadata,
  * });
  * ```
- * ```ts [Redirection]
- * // Trigger an sso opening within a popup with direct exit
+ * ```ts [Redirect]
+ * // Opens in same window with redirect
  * await openSso(frakConfig, {
  *     redirectUrl: "https://my-app.com/frak-sso",
  *     metadata,
+ *     openInSameWindow: true,
  * });
  * ```
- * ```ts [With tracking]
- * // Trigger an sso with consumeKey for tracking
- * const result = await openSso(frakConfig, {
- *     directExit: true,
- *     generateConsumeKey: true,
+ * ```ts [Custom popup URL]
+ * // Advanced: provide custom SSO URL
+ * const { ssoUrl } = await prepareSso(frakConfig, { metadata });
+ * await openSso(frakConfig, {
  *     metadata,
+ *     ssoPopupUrl: `${ssoUrl}&custom=param`,
  * });
- * console.log(result.consumeKey); // Use this to track SSO status
  * ```
  * :::
  */
@@ -1218,30 +1318,16 @@ export declare function openSso(client: FrakClient, args: OpenSsoParamsType): Pr
  * Params to start a SSO
  * @group RPC Schema
  */
-export declare type OpenSsoParamsType = {
+export declare type OpenSsoParamsType = PrepareSsoParamsType & {
     /**
-     * Redirect URL after the SSO (optional)
-     */
-    redirectUrl?: string;
-    /**
-     * If the SSO should directly exit after completion
-     * @defaultValue true
-     */
-    directExit?: boolean;
-    /**
-     * If true, opens SSO in same window instead of popup
-     * Defaults to true when redirectUrl is provided, false otherwise
+     * 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
      */
     openInSameWindow?: boolean;
     /**
-     * Language of the SSO page (optional)
-     * It will default to the current user language (or "en" if unsupported language)
+     * Custom SSO popup url if user want additionnal customisation
      */
-    lang?: "en" | "fr";
-    /**
-     * Custom SSO metadata
-     */
-    metadata: SsoMetadata;
+    ssoPopupUrl?: string;
 };
 
 /**
@@ -1273,6 +1359,76 @@ export declare type PreparedInteraction = {
     interactionData: Hex;
 };
 
+/**
+ * Generate SSO URL without opening popup
+ *
+ * This is a **synchronous**, client-side function that generates the SSO URL
+ * without any RPC calls to the wallet iframe. Use this when you need:
+ * - Custom URL modifications before opening popup
+ * - Pre-generation for advanced popup strategies
+ * - URL inspection/logging before SSO flow
+ *
+ * @param client - The current Frak Client
+ * @param args - The SSO parameters
+ * @returns Object containing the generated ssoUrl
+ *
+ * @example
+ * ```ts
+ * // Generate URL for inspection
+ * const { ssoUrl } = prepareSso(client, {
+ *   metadata: { logoUrl: "..." },
+ *   directExit: true
+ * });
+ * console.log("Opening SSO:", ssoUrl);
+ *
+ * // Add custom params
+ * const customUrl = `${ssoUrl}&tracking=abc123`;
+ * await openSso(client, { metadata, ssoPopupUrl: customUrl });
+ * ```
+ *
+ * @remarks
+ * For most use cases, just use `openSso()` which handles URL generation automatically.
+ * Only use `prepareSso()` when you need explicit control over the URL.
+ */
+export declare function prepareSso(client: FrakClient, args: PrepareSsoParamsType): Promise<PrepareSsoReturnType>;
+
+/**
+ * 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;
+};
+
 /**
  * Press interactions allow you to track user engagement with articles or other press content on your platform.
  * After setting up these interactions, you can create acquisition campaign based on the user engagement with your press content.
@@ -1790,6 +1946,10 @@ 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: {