@0xkey-io/react-native-wallet-kit 0.1.0

package/dist/utils/oauth.mjs

@@ -0,0 +1,319 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { stringToBase64urlString } from '@0xkey-io/encoding';
+import { OAuthProviders } from '@0xkey-io/sdk-types';
+import AsyncStorageModule from '@react-native-async-storage/async-storage';
+
+// some bundlers wrap the module as { default: AsyncStorage } instead of
+// returning AsyncStorage directly. This handles both cases
+const AsyncStorage = AsyncStorageModule.default ?? AsyncStorageModule;
+const DISCORD_AUTH_URL = "https://discord.com/oauth2/authorize";
+const X_AUTH_URL = "https://x.com/i/oauth2/authorize";
+const GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const APPLE_AUTH_URL = "https://account.apple.com/auth/authorize";
+const FACEBOOK_AUTH_URL = "https://www.facebook.com/v23.0/dialog/oauth";
+const FACEBOOK_GRAPH_URL = "https://graph.facebook.com/v23.0/oauth/access_token";
+const ZEROXKEY_OAUTH_ORIGIN_URL = "https://oauth-origin.0xkey.com";
+const ZEROXKEY_OAUTH_REDIRECT_URL = "https://oauth-redirect.0xkey.com";
+// ============================================================================
+// OAuth State Building
+// ============================================================================
+/**
+ * Builds the OAuth state parameter string
+ */
+function buildOAuthState(params) {
+    const { provider, flow, publicKey, nonce, additionalState } = params;
+    let state = `provider=${provider}&flow=${flow}&publicKey=${encodeURIComponent(publicKey)}`;
+    if (nonce) {
+        state += `&nonce=${nonce}`;
+    }
+    if (additionalState) {
+        const extra = Object.entries(additionalState)
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+            .join("&");
+        if (extra) {
+            state += `&${extra}`;
+        }
+    }
+    return state;
+}
+/**
+ * Pre-configured OAuth provider settings
+ */
+const OAUTH_PROVIDER_CONFIGS = {
+    [OAuthProviders.GOOGLE]: {
+        provider: OAuthProviders.GOOGLE,
+        authUrl: GOOGLE_AUTH_URL,
+        scopes: "openid email profile",
+        usesPKCE: false,
+        responseType: "id_token",
+        nonceInParams: true,
+    },
+    [OAuthProviders.APPLE]: {
+        provider: OAuthProviders.APPLE,
+        authUrl: APPLE_AUTH_URL,
+        scopes: "",
+        usesPKCE: false,
+        responseType: "code id_token",
+        responseMode: "fragment",
+        nonceInParams: true,
+    },
+    [OAuthProviders.FACEBOOK]: {
+        provider: OAuthProviders.FACEBOOK,
+        authUrl: FACEBOOK_AUTH_URL,
+        scopes: "openid",
+        usesPKCE: true,
+        responseType: "code",
+        nonceInParams: true,
+    },
+    [OAuthProviders.DISCORD]: {
+        provider: OAuthProviders.DISCORD,
+        authUrl: DISCORD_AUTH_URL,
+        scopes: "identify email",
+        usesPKCE: true,
+        responseType: "code",
+        nonceInParams: false,
+    },
+    [OAuthProviders.X]: {
+        provider: OAuthProviders.X,
+        authUrl: X_AUTH_URL,
+        scopes: "tweet.read users.read",
+        usesPKCE: true,
+        responseType: "code",
+        nonceInParams: false,
+    },
+};
+// ============================================================================
+// OAuth State Parsing
+// ============================================================================
+/**
+ * Parses the OAuth state parameter string into an object
+ */
+function parseStateParam(stateParam) {
+    if (!stateParam)
+        return {};
+    const result = {};
+    const pairs = stateParam.split("&");
+    for (const pair of pairs) {
+        const [key, value] = pair.split("=");
+        if (key && value !== undefined) {
+            result[key] = decodeURIComponent(value);
+        }
+    }
+    return result;
+}
+// Function to generate PKCE challenge pair for Facebook OAuth
+async function generateChallengePair() {
+    // Generate verifier from 32 random bytes
+    const randomBytes = new Uint8Array(32);
+    // eslint-disable-next-line no-undef
+    crypto.getRandomValues(randomBytes);
+    const randomAsBinary = String.fromCharCode(...randomBytes);
+    const verifier = stringToBase64urlString(randomAsBinary);
+    // Compute SHA-256 over ASCII(verifier), then base64url encode
+    const ascii = new TextEncoder().encode(verifier);
+    const digest = sha256(ascii);
+    const digestAsBinary = String.fromCharCode(...digest);
+    const codeChallenge = stringToBase64urlString(digestAsBinary);
+    return { verifier, codeChallenge };
+}
+/**
+ * Gets the AsyncStorage key name for a PKCE provider's verifier
+ */
+function getPKCEVerifierKey(provider) {
+    return `${provider}_verifier`;
+}
+/**
+ * Stores the PKCE verifier in AsyncStorage
+ * @param provider - The OAuth provider
+ * @param verifier - The verifier string to store
+ */
+async function storePKCEVerifier(provider, verifier) {
+    const key = getPKCEVerifierKey(provider);
+    await AsyncStorage.setItem(key, verifier);
+}
+/**
+ * Retrieves and removes the PKCE verifier from AsyncStorage
+ * @param provider - The OAuth provider
+ * @returns The verifier string
+ * @throws Error if verifier is not found
+ */
+async function consumePKCEVerifier(provider) {
+    const key = getPKCEVerifierKey(provider);
+    const verifier = await AsyncStorage.getItem(key);
+    if (!verifier) {
+        throw new Error(`Missing PKCE verifier for ${provider}. OAuth flow may have been interrupted.`);
+    }
+    await AsyncStorage.removeItem(key);
+    return verifier;
+}
+/**
+ * Builds the complete OAuth authorization URL for a provider
+ * For react-native, can use either:
+ * - Direct provider URLs (Discord, X)
+ * - ZeroXKey OAuth proxy (Google, Apple, Facebook)
+ */
+function buildOAuthUrl(params) {
+    const { provider, clientId, redirectUri, publicKey, nonce, codeChallenge, additionalState, useOauthProxyOrigin = false, } = params;
+    const config = OAUTH_PROVIDER_CONFIGS[provider];
+    // Build state parameter
+    const stateParams = {
+        provider,
+        flow: "redirect",
+        publicKey,
+    };
+    if (!config.nonceInParams && nonce) {
+        stateParams.nonce = nonce;
+    }
+    if (additionalState) {
+        stateParams.additionalState = additionalState;
+    }
+    const state = buildOAuthState(stateParams);
+    // If using ZeroXKey Oauth proxy (for Google, Apple, Facebook)
+    if (useOauthProxyOrigin) {
+        const url = new URL(ZEROXKEY_OAUTH_ORIGIN_URL);
+        url.searchParams.set("provider", provider);
+        url.searchParams.set("clientId", clientId);
+        url.searchParams.set("redirectUri", redirectUri);
+        url.searchParams.set("nonce", nonce);
+        if (codeChallenge) {
+            url.searchParams.set("codeChallenge", codeChallenge);
+        }
+        url.searchParams.set("state", state);
+        return url.toString();
+    }
+    // Direct provider URLs (for Discord, X)
+    const authUrl = new URL(config.authUrl);
+    authUrl.searchParams.set("client_id", clientId);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("response_type", config.responseType);
+    if (config.scopes) {
+        authUrl.searchParams.set("scope", config.scopes);
+    }
+    if (config.usesPKCE && codeChallenge) {
+        authUrl.searchParams.set("code_challenge", codeChallenge);
+        authUrl.searchParams.set("code_challenge_method", "S256");
+    }
+    authUrl.searchParams.set("state", state);
+    return authUrl.toString();
+}
+/**
+ * Parses the deep link URL returned from InAppBrowser after OAuth redirect
+ * @param deepLinkUrl - The URL from InAppBrowser result (e.g., "myapp://?id_token=...&state=...")
+ * @returns Parsed OAuth response data
+ */
+function parseInAppBrowserResult(deepLinkUrl) {
+    const qsIndex = deepLinkUrl.indexOf("?");
+    const queryString = qsIndex >= 0 ? deepLinkUrl.substring(qsIndex + 1) : "";
+    const urlParams = new URLSearchParams(queryString);
+    const idToken = urlParams.get("id_token");
+    const authCode = urlParams.get("code");
+    const stateParam = urlParams.get("state");
+    // Parse state parameter
+    const stateData = parseStateParam(stateParam);
+    return {
+        idToken: idToken ?? null,
+        authCode: authCode ?? null,
+        sessionKey: stateData.sessionKey,
+        provider: stateData.provider ?? null,
+        publicKey: stateData.publicKey ?? null,
+        nonce: stateData.nonce ?? null,
+    };
+}
+/**
+ * Unified OAuth completion handler.
+ * Routes to the appropriate completion handler based on params:
+ * Priority: callbacks.onOauthSuccess > callbacks.onOauthRedirect > completeOauth
+ *
+ * This is the core completion logic used by InAppBrowser flows.
+ */
+async function completeOAuthFlow(params) {
+    const { provider, publicKey, oidcToken, sessionKey, callbacks, completeOauth, } = params;
+    const completionParams = {
+        oidcToken,
+        providerName: provider,
+        publicKey,
+        ...(sessionKey && { sessionKey }),
+    };
+    if (callbacks?.onOauthSuccess) {
+        callbacks.onOauthSuccess(completionParams);
+        return;
+    }
+    if (callbacks?.onOauthRedirect) {
+        callbacks.onOauthRedirect({
+            idToken: oidcToken,
+            publicKey,
+            ...(sessionKey && { sessionKey }),
+        });
+        return;
+    }
+    await completeOauth(completionParams);
+}
+/**
+ * Unified PKCE flow handler for all PKCE-based OAuth providers.
+ * Handles the complete PKCE flow: verifier retrieval, token exchange, and completion routing.
+ *
+ * @param params - The PKCE flow parameters
+ * @returns A promise that resolves when the flow is complete
+ */
+async function handlePKCEFlow(params) {
+    const { provider, publicKey, authCode, sessionKey, callbacks, completeOauth, exchangeCodeForToken, } = params;
+    if (!authCode) {
+        throw new Error(`Missing authorization code from ${provider} OAuth`);
+    }
+    // Get and consume the stored verifier
+    const verifier = await consumePKCEVerifier(provider);
+    try {
+        // Exchange code for token
+        const oidcToken = await exchangeCodeForToken(verifier);
+        if (!oidcToken) {
+            throw new Error(`Missing oidcToken from ${provider} OAuth exchange`);
+        }
+        // Complete the OAuth flow
+        const completionParams = {
+            provider,
+            publicKey,
+            oidcToken,
+            completeOauth,
+        };
+        if (sessionKey) {
+            completionParams.sessionKey = sessionKey;
+        }
+        if (callbacks) {
+            completionParams.callbacks = callbacks;
+        }
+        await completeOAuthFlow(completionParams);
+    }
+    catch (error) {
+        // Ensure cleanup even on error
+        const key = getPKCEVerifierKey(provider);
+        await AsyncStorage.removeItem(key).catch(() => {
+            /* ignore cleanup errors */
+        });
+        throw error;
+    }
+}
+// Function to exchange Facebook authorization code for token
+async function exchangeCodeForToken(clientId, redirectUri, code, codeVerifier) {
+    const params = new URLSearchParams({
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+        code: code,
+        grant_type: "authorization_code",
+    });
+    const response = await fetch(FACEBOOK_GRAPH_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        const errorData = await response.json();
+        throw new Error(`Facebook token exchange failed: ${JSON.stringify(errorData)}`);
+    }
+    return await response.json();
+}
+
+export { APPLE_AUTH_URL, DISCORD_AUTH_URL, FACEBOOK_AUTH_URL, FACEBOOK_GRAPH_URL, GOOGLE_AUTH_URL, OAUTH_PROVIDER_CONFIGS, X_AUTH_URL, ZEROXKEY_OAUTH_ORIGIN_URL, ZEROXKEY_OAUTH_REDIRECT_URL, buildOAuthState, buildOAuthUrl, completeOAuthFlow, consumePKCEVerifier, exchangeCodeForToken, generateChallengePair, getPKCEVerifierKey, handlePKCEFlow, parseInAppBrowserResult, parseStateParam, storePKCEVerifier };
+//# sourceMappingURL=oauth.mjs.map

package/dist/utils/oauth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.mjs","sources":["../../src/utils/oauth.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/utils/timers.d.ts

@@ -0,0 +1,73 @@
+export type TimerController = {
+    clear: () => void;
+};
+export type TimerMap = Record<string, TimerController>;
+export declare const MAX_DELAY_MS = 2147483647;
+/**
+ * @internal A drop-in replacement for `setTimeout` that supports arbitrarily long delays.
+ *
+ * ### Why?
+ * Browsers clamp `setTimeout` delays to a 32-bit signed integer,
+ * i.e. a maximum of ~24.8 days (`2_147_483_647ms`). Any larger value
+ * will fire almost immediately. This helper safely schedules timeouts
+ * that can be months or years into the future.
+ *
+ * ### How it works
+ * - On call, we record a fixed **target timestamp** (`now + delayMs`).
+ * - We schedule a single "leg" of at most ~24.8 days into the future,
+ *   with an internal `tick` function as the callback.
+ * - When a leg expires, `tick` checks how much time is left:
+ *   - If `remaining > 0`, it schedules the next leg (`min(MAX_DELAY_MS, remaining)`).
+ *   - If `remaining <= 0`, the full delay has passed and we finally call your `cb()`.
+ * - At any time, only **one** leg is active. Calling `.clear()` cancels
+ *   the current leg and prevents further hops.
+ *
+ * ### Benefits
+ * - Works seamlessly for both short and very long delays.
+ * - Survives tab sleep / system suspend: when the tab wakes,
+ *   `tick` re-checks the target timestamp and fires immediately if overdue.
+ * - No drift accumulation: each hop recalculates based on the fixed target,
+ *   so you always land as close as possible to the intended deadline.
+ *
+ * ### Example
+ * ```ts
+ * const controller = setCappedTimeout(() => {
+ *   console.log("A whole year later!");
+ * }, 1000 * 60 * 60 * 24 * 365);
+ *
+ * // Cancel if needed
+ * controller.clear();
+ * ```
+ *
+ * @param cb - Function to run once the full delay has elapsed.
+ * @param delayMs - Delay in milliseconds (can exceed 2_147_483_647).
+ * @returns A controller with a `.clear()` method to cancel the timeout.
+ */
+export declare function setCappedTimeout(cb: () => void, delayMs: number): TimerController;
+/** @internal Simple one-shot timeout that still returns a controller for uniformity. */
+export declare function setTimeoutController(cb: () => void, delayMs: number): TimerController;
+/** @internal Replace any existing timer for `key` with `controller`. */
+export declare function putTimer(map: TimerMap, key: string, controller: TimerController): void;
+/** @internal Clear a specific key (noop if missing). */
+export declare function clearKey(map: TimerMap, key: string): void;
+/** @internal Clear several keys at once (noop on missing). */
+export declare function clearKeys(map: TimerMap, keys: string[]): void;
+/** @internal Clear all timers in the map. */
+export declare function clearAll(map: TimerMap): void;
+/**
+ * @internal Convenience: set a capped timeout directly into the map for `key`.
+ * @param map The map to store the timer in (pass in the ref to the timer map)
+ * @param key The key to associate with the timer
+ * @param cb The callback to invoke when the timer expires
+ * @param delayMs The delay in milliseconds before the timer expires
+ * */
+export declare function setCappedTimeoutInMap(map: TimerMap, key: string, cb: () => void, delayMs: number): void;
+/**
+ * @internal Convenience: set a regular (short) timeout into the map for `key`.
+ * @param map The map to store the timer in (pass in the ref to the timer map)
+ * @param key The key to associate with the timer
+ * @param cb The callback to invoke when the timer expires
+ * @param delayMs The delay in milliseconds before the timer expires
+ */
+export declare function setTimeoutInMap(map: TimerMap, key: string, cb: () => void, delayMs: number): void;
+//# sourceMappingURL=timers.d.ts.map

package/dist/utils/timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../../src/utils/timers.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEvD,eAAO,MAAM,YAAY,aAAgB,CAAC;AAO1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,IAAI,EACd,OAAO,EAAE,MAAM,GACd,eAAe,CAuBjB;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,MAAM,IAAI,EACd,OAAO,EAAE,MAAM,GACd,eAAe,CAIjB;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CACtB,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,eAAe,QAI5B;AAED,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,QAGlD;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,QAEtD;AAED,6CAA6C;AAC7C,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,QAKrC;AAED;;;;;;KAMK;AACL,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,IAAI,EACd,OAAO,EAAE,MAAM,QAGhB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,IAAI,EACd,OAAO,EAAE,MAAM,QAGhB"}

package/dist/utils/timers.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// This file contains utility functions for managing timers and timeouts for session management.
+// Unfortunately, the delay param in Node Timeouts is a 32-bit signed integer, meaning it can only represent delays up to ~24.8 days.
+// This file provides functions to handle long delays by breaking them into smaller chunks.
+// These functions are separate from the normal utils function to reduce clutter and improve visibility.
+// Use `setTimeoutInMap` for short, frequent nudges (10s), and `setCappedTimeoutInMap` for anything that could exceed ~24.8 days.
+const MAX_DELAY_MS = 2_147_483_647; // ~24.8 days
+/** @internal */
+function toIntMs(x) {
+    return Math.max(0, Math.floor(Number.isFinite(x) ? x : 0));
+}
+/**
+ * @internal A drop-in replacement for `setTimeout` that supports arbitrarily long delays.
+ *
+ * ### Why?
+ * Browsers clamp `setTimeout` delays to a 32-bit signed integer,
+ * i.e. a maximum of ~24.8 days (`2_147_483_647ms`). Any larger value
+ * will fire almost immediately. This helper safely schedules timeouts
+ * that can be months or years into the future.
+ *
+ * ### How it works
+ * - On call, we record a fixed **target timestamp** (`now + delayMs`).
+ * - We schedule a single "leg" of at most ~24.8 days into the future,
+ *   with an internal `tick` function as the callback.
+ * - When a leg expires, `tick` checks how much time is left:
+ *   - If `remaining > 0`, it schedules the next leg (`min(MAX_DELAY_MS, remaining)`).
+ *   - If `remaining <= 0`, the full delay has passed and we finally call your `cb()`.
+ * - At any time, only **one** leg is active. Calling `.clear()` cancels
+ *   the current leg and prevents further hops.
+ *
+ * ### Benefits
+ * - Works seamlessly for both short and very long delays.
+ * - Survives tab sleep / system suspend: when the tab wakes,
+ *   `tick` re-checks the target timestamp and fires immediately if overdue.
+ * - No drift accumulation: each hop recalculates based on the fixed target,
+ *   so you always land as close as possible to the intended deadline.
+ *
+ * ### Example
+ * ```ts
+ * const controller = setCappedTimeout(() => {
+ *   console.log("A whole year later!");
+ * }, 1000 * 60 * 60 * 24 * 365);
+ *
+ * // Cancel if needed
+ * controller.clear();
+ * ```
+ *
+ * @param cb - Function to run once the full delay has elapsed.
+ * @param delayMs - Delay in milliseconds (can exceed 2_147_483_647).
+ * @returns A controller with a `.clear()` method to cancel the timeout.
+ */
+function setCappedTimeout(cb, delayMs) {
+    const target = Date.now() + toIntMs(delayMs);
+    let handle;
+    const tick = () => {
+        const remaining = target - Date.now();
+        if (remaining <= 0) {
+            cb();
+            return;
+        }
+        handle = setTimeout(tick, Math.min(MAX_DELAY_MS, remaining));
+    };
+    tick();
+    return {
+        clear() {
+            if (handle !== undefined) {
+                clearTimeout(handle);
+                handle = undefined;
+            }
+        },
+    };
+}
+/** @internal Simple one-shot timeout that still returns a controller for uniformity. */
+function setTimeoutController(cb, delayMs) {
+    const ms = toIntMs(delayMs);
+    const id = setTimeout(cb, ms);
+    return { clear: () => clearTimeout(id) };
+}
+/** @internal Replace any existing timer for `key` with `controller`. */
+function putTimer(map, key, controller) {
+    map[key]?.clear?.();
+    map[key] = controller;
+}
+/** @internal Clear a specific key (noop if missing). */
+function clearKey(map, key) {
+    map[key]?.clear?.();
+    delete map[key];
+}
+/** @internal Clear several keys at once (noop on missing). */
+function clearKeys(map, keys) {
+    for (const k of keys)
+        clearKey(map, k);
+}
+/** @internal Clear all timers in the map. */
+function clearAll(map) {
+    for (const k of Object.keys(map)) {
+        map[k]?.clear?.();
+        delete map[k];
+    }
+}
+/**
+ * @internal Convenience: set a capped timeout directly into the map for `key`.
+ * @param map The map to store the timer in (pass in the ref to the timer map)
+ * @param key The key to associate with the timer
+ * @param cb The callback to invoke when the timer expires
+ * @param delayMs The delay in milliseconds before the timer expires
+ * */
+function setCappedTimeoutInMap(map, key, cb, delayMs) {
+    putTimer(map, key, setCappedTimeout(cb, delayMs));
+}
+/**
+ * @internal Convenience: set a regular (short) timeout into the map for `key`.
+ * @param map The map to store the timer in (pass in the ref to the timer map)
+ * @param key The key to associate with the timer
+ * @param cb The callback to invoke when the timer expires
+ * @param delayMs The delay in milliseconds before the timer expires
+ */
+function setTimeoutInMap(map, key, cb, delayMs) {
+    putTimer(map, key, setTimeoutController(cb, delayMs));
+}
+
+exports.MAX_DELAY_MS = MAX_DELAY_MS;
+exports.clearAll = clearAll;
+exports.clearKey = clearKey;
+exports.clearKeys = clearKeys;
+exports.putTimer = putTimer;
+exports.setCappedTimeout = setCappedTimeout;
+exports.setCappedTimeoutInMap = setCappedTimeoutInMap;
+exports.setTimeoutController = setTimeoutController;
+exports.setTimeoutInMap = setTimeoutInMap;
+//# sourceMappingURL=timers.js.map

package/dist/utils/timers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.js","sources":["../../src/utils/timers.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AAMO,MAAM,YAAY,GAAG,cAAc;AAE1C;AACA,SAAS,OAAO,CAAC,CAAS,EAAA;IACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC5D;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCG;AACG,SAAU,gBAAgB,CAC9B,EAAc,EACd,OAAe,EAAA;IAEf,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;AAC5C,IAAA,IAAI,MAAiD;IAErD,MAAM,IAAI,GAAG,MAAK;QAChB,MAAM,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE;AACrC,QAAA,IAAI,SAAS,IAAI,CAAC,EAAE;AAClB,YAAA,EAAE,EAAE;YACJ;QACF;AACA,QAAA,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAC9D,IAAA,CAAC;AAED,IAAA,IAAI,EAAE;IAEN,OAAO;QACL,KAAK,GAAA;AACH,YAAA,IAAI,MAAM,KAAK,SAAS,EAAE;gBACxB,YAAY,CAAC,MAAM,CAAC;gBACpB,MAAM,GAAG,SAAS;YACpB;QACF,CAAC;KACF;AACH;AAEA;AACM,SAAU,oBAAoB,CAClC,EAAc,EACd,OAAe,EAAA;AAEf,IAAA,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAC3B,MAAM,EAAE,GAAG,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC;IAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC,EAAE,CAAC,EAAE;AAC1C;AAEA;SACgB,QAAQ,CACtB,GAAa,EACb,GAAW,EACX,UAA2B,EAAA;AAE3B,IAAA,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,IAAI;AACnB,IAAA,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU;AACvB;AAEA;AACM,SAAU,QAAQ,CAAC,GAAa,EAAE,GAAW,EAAA;AACjD,IAAA,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,IAAI;AACnB,IAAA,OAAO,GAAG,CAAC,GAAG,CAAC;AACjB;AAEA;AACM,SAAU,SAAS,CAAC,GAAa,EAAE,IAAc,EAAA;IACrD,KAAK,MAAM,CAAC,IAAI,IAAI;AAAE,QAAA,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;AACxC;AAEA;AACM,SAAU,QAAQ,CAAC,GAAa,EAAA;IACpC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;AAChC,QAAA,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI;AACjB,QAAA,OAAO,GAAG,CAAC,CAAC,CAAC;IACf;AACF;AAEA;;;;;;AAMK;AACC,SAAU,qBAAqB,CACnC,GAAa,EACb,GAAW,EACX,EAAc,EACd,OAAe,EAAA;AAEf,IAAA,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,gBAAgB,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;AACnD;AAEA;;;;;;AAMG;AACG,SAAU,eAAe,CAC7B,GAAa,EACb,GAAW,EACX,EAAc,EACd,OAAe,EAAA;AAEf,IAAA,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,oBAAoB,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;AACvD;;;;;;;;;;;;"}

package/dist/utils/timers.mjs

@@ -0,0 +1,122 @@
+// This file contains utility functions for managing timers and timeouts for session management.
+// Unfortunately, the delay param in Node Timeouts is a 32-bit signed integer, meaning it can only represent delays up to ~24.8 days.
+// This file provides functions to handle long delays by breaking them into smaller chunks.
+// These functions are separate from the normal utils function to reduce clutter and improve visibility.
+// Use `setTimeoutInMap` for short, frequent nudges (10s), and `setCappedTimeoutInMap` for anything that could exceed ~24.8 days.
+const MAX_DELAY_MS = 2_147_483_647; // ~24.8 days
+/** @internal */
+function toIntMs(x) {
+    return Math.max(0, Math.floor(Number.isFinite(x) ? x : 0));
+}
+/**
+ * @internal A drop-in replacement for `setTimeout` that supports arbitrarily long delays.
+ *
+ * ### Why?
+ * Browsers clamp `setTimeout` delays to a 32-bit signed integer,
+ * i.e. a maximum of ~24.8 days (`2_147_483_647ms`). Any larger value
+ * will fire almost immediately. This helper safely schedules timeouts
+ * that can be months or years into the future.
+ *
+ * ### How it works
+ * - On call, we record a fixed **target timestamp** (`now + delayMs`).
+ * - We schedule a single "leg" of at most ~24.8 days into the future,
+ *   with an internal `tick` function as the callback.
+ * - When a leg expires, `tick` checks how much time is left:
+ *   - If `remaining > 0`, it schedules the next leg (`min(MAX_DELAY_MS, remaining)`).
+ *   - If `remaining <= 0`, the full delay has passed and we finally call your `cb()`.
+ * - At any time, only **one** leg is active. Calling `.clear()` cancels
+ *   the current leg and prevents further hops.
+ *
+ * ### Benefits
+ * - Works seamlessly for both short and very long delays.
+ * - Survives tab sleep / system suspend: when the tab wakes,
+ *   `tick` re-checks the target timestamp and fires immediately if overdue.
+ * - No drift accumulation: each hop recalculates based on the fixed target,
+ *   so you always land as close as possible to the intended deadline.
+ *
+ * ### Example
+ * ```ts
+ * const controller = setCappedTimeout(() => {
+ *   console.log("A whole year later!");
+ * }, 1000 * 60 * 60 * 24 * 365);
+ *
+ * // Cancel if needed
+ * controller.clear();
+ * ```
+ *
+ * @param cb - Function to run once the full delay has elapsed.
+ * @param delayMs - Delay in milliseconds (can exceed 2_147_483_647).
+ * @returns A controller with a `.clear()` method to cancel the timeout.
+ */
+function setCappedTimeout(cb, delayMs) {
+    const target = Date.now() + toIntMs(delayMs);
+    let handle;
+    const tick = () => {
+        const remaining = target - Date.now();
+        if (remaining <= 0) {
+            cb();
+            return;
+        }
+        handle = setTimeout(tick, Math.min(MAX_DELAY_MS, remaining));
+    };
+    tick();
+    return {
+        clear() {
+            if (handle !== undefined) {
+                clearTimeout(handle);
+                handle = undefined;
+            }
+        },
+    };
+}
+/** @internal Simple one-shot timeout that still returns a controller for uniformity. */
+function setTimeoutController(cb, delayMs) {
+    const ms = toIntMs(delayMs);
+    const id = setTimeout(cb, ms);
+    return { clear: () => clearTimeout(id) };
+}
+/** @internal Replace any existing timer for `key` with `controller`. */
+function putTimer(map, key, controller) {
+    map[key]?.clear?.();
+    map[key] = controller;
+}
+/** @internal Clear a specific key (noop if missing). */
+function clearKey(map, key) {
+    map[key]?.clear?.();
+    delete map[key];
+}
+/** @internal Clear several keys at once (noop on missing). */
+function clearKeys(map, keys) {
+    for (const k of keys)
+        clearKey(map, k);
+}
+/** @internal Clear all timers in the map. */
+function clearAll(map) {
+    for (const k of Object.keys(map)) {
+        map[k]?.clear?.();
+        delete map[k];
+    }
+}
+/**
+ * @internal Convenience: set a capped timeout directly into the map for `key`.
+ * @param map The map to store the timer in (pass in the ref to the timer map)
+ * @param key The key to associate with the timer
+ * @param cb The callback to invoke when the timer expires
+ * @param delayMs The delay in milliseconds before the timer expires
+ * */
+function setCappedTimeoutInMap(map, key, cb, delayMs) {
+    putTimer(map, key, setCappedTimeout(cb, delayMs));
+}
+/**
+ * @internal Convenience: set a regular (short) timeout into the map for `key`.
+ * @param map The map to store the timer in (pass in the ref to the timer map)
+ * @param key The key to associate with the timer
+ * @param cb The callback to invoke when the timer expires
+ * @param delayMs The delay in milliseconds before the timer expires
+ */
+function setTimeoutInMap(map, key, cb, delayMs) {
+    putTimer(map, key, setTimeoutController(cb, delayMs));
+}
+
+export { MAX_DELAY_MS, clearAll, clearKey, clearKeys, putTimer, setCappedTimeout, setCappedTimeoutInMap, setTimeoutController, setTimeoutInMap };
+//# sourceMappingURL=timers.mjs.map