@frak-labs/core-sdk 1.0.0-beta.a7645eaa → 1.0.0-beta.b917e199

package/dist/src-C4ZNZbhF.cjs

@@ -0,0 +1,13 @@
+const e=require(`./sdkConfigStore-DDL_fjYX.cjs`);let t=require(`@frak-labs/frame-connector`),n=require(`@openpanel/web`);function r(n){return(0,t.jsonDecode)(e.h(n))}const i=`nexus-wallet-backup`,a=`frakwallet://`;function o(){let e=navigator.userAgent;return/Android/i.test(e)&&/Chrome\/\d+/i.test(e)}function s(e){return`intent://${e.slice(13)}#Intent;scheme=frakwallet;end`}function c(e,t){let n=t?.timeout??2500,r=!1,i=()=>{document.hidden&&(r=!0)};document.addEventListener(`visibilitychange`,i);let a=o()&&l(e)?s(e):e;window.location.href=a,setTimeout(()=>{document.removeEventListener(`visibilitychange`,i),r||t?.onFallback?.()},n)}function l(e){return e.startsWith(a)}const u={eur:`fr-FR`,usd:`en-US`,gbp:`en-GB`};function d(e){return e&&e in u?e:`eur`}function f(e){return e?u[e]??u.eur:u.eur}function p(e,t){let n=f(t),r=d(t);return e.toLocaleString(n,{style:`currency`,currency:r,minimumFractionDigits:0,maximumFractionDigits:2})}function m(e){return e?`${e}Amount`:`eurAmount`}const h={id:`frak-wallet`,name:`frak-wallet`,title:`Frak Wallet`,allow:`publickey-credentials-get *; clipboard-write; web-share *`,style:{width:`0`,height:`0`,border:`0`,position:`absolute`,zIndex:2000001,top:`-1000px`,left:`-1000px`,colorScheme:`auto`}};function g({walletBaseUrl:t,config:n}){let r=document.querySelector(`#frak-wallet`);r&&r.remove();let i=document.createElement(`iframe`);i.id=h.id,i.name=h.name,i.allow=h.allow,i.style.zIndex=h.style.zIndex.toString(),_({iframe:i,isVisible:!1});let a=n?.walletUrl??t??`https://wallet.frak.id`,o=e.v();return i.src=`${a}/listener?clientId=${encodeURIComponent(o)}`,new Promise(e=>{i.addEventListener(`load`,()=>e(i)),document.body.appendChild(i)})}function _({iframe:e,isVisible:t}){if(!t){e.style.width=`0`,e.style.height=`0`,e.style.border=`0`,e.style.position=`fixed`,e.style.top=`-1000px`,e.style.left=`-1000px`;return}e.style.position=`fixed`,e.style.top=`0`,e.style.left=`0`,e.style.width=`100%`,e.style.height=`100%`,e.style.pointerEvents=`auto`}function v(e=`/listener`){if(!window.opener)return null;let t=t=>{try{return t.location.origin===window.location.origin&&t.location.pathname===e}catch{return!1}};if(t(window.opener))return window.opener;try{let e=window.opener.frames;for(let n=0;n<e.length;n++)if(t(e[n]))return e[n];return null}catch(t){return console.error(`[findIframeInOpener] Error finding iframe with pathname ${e}:`,t),null}}function y(){if(typeof navigator>`u`)return!1;let e=navigator.userAgent;return!!(/iPhone|iPad|iPod/i.test(e)||/Macintosh/i.test(e)&&navigator.maxTouchPoints>1)}const b=y();function x(){if(typeof navigator>`u`)return!1;let e=navigator.userAgent.toLowerCase();return e.includes(`instagram`)||e.includes(`fban`)||e.includes(`fbav`)||e.includes(`facebook`)}const S=x();function C(e){b&&e.startsWith(`https://`)?window.location.href=`x-safari-https://${e.slice(8)}`:b&&e.startsWith(`http://`)?window.location.href=`x-safari-http://${e.slice(7)}`:window.location.href=`https://backend.frak.id/common/social?u=${encodeURIComponent(e)}`}function w({perCall:e,defaults:t,productUtmContent:n}){if(e===null)return;let r=e!==void 0,i=t!==void 0&&Object.keys(t).length>0;if(!r&&!i&&!(n!==void 0&&n!==``))return;let a={...t,...e??{}},o=n??e?.utmContent;return o!==void 0&&o!==``?a.utmContent=o:delete a.utmContent,a}function T(e,t){if(typeof window>`u`)return;let n=new URL(window.location.href),r=n.searchParams.get(`sso`);r&&(t.then(()=>{e.sendLifecycle({clientLifecycle:`sso-redirect-complete`,data:{compressed:r}}),console.log(`[SSO URL Listener] Forwarded compressed SSO data to iframe`)}).catch(e=>{console.error(`[SSO URL Listener] Failed to forward SSO data:`,e)}),n.searchParams.delete(`sso`),window.history.replaceState({},``,n.toString()),console.log(`[SSO URL Listener] SSO parameter detected and URL cleaned`))}var E=class e{config;iframe;isSetupDone=!1;lastResponse=null;lastRequest=null;constructor(e,t){this.config=e,this.iframe=t,this.lastRequest=null,this.lastResponse=null}setLastResponse(e,t){this.lastResponse={message:e,response:t,timestamp:Date.now()}}setLastRequest(e){this.lastRequest={event:e,timestamp:Date.now()}}updateSetupStatus(e){this.isSetupDone=e}base64Encode(e){try{return btoa(JSON.stringify(e))}catch(e){return console.warn(`Failed to encode debug data`,e),btoa(`Failed to encode data`)}}getIframeStatus(){return this.iframe?{loading:this.iframe.hasAttribute(`loading`),url:this.iframe.src,readyState:this.iframe.contentDocument?.readyState?+(this.iframe.contentDocument.readyState===`complete`):-1,contentWindow:!!this.iframe.contentWindow,isConnected:this.iframe.isConnected}:null}getNavigatorInfo(){return navigator?{userAgent:navigator.userAgent,language:navigator.language,onLine:navigator.onLine,screenWidth:window.screen.width,screenHeight:window.screen.height,pixelRatio:window.devicePixelRatio}:null}gatherDebugInfo(e){let n=this.getIframeStatus(),r=this.getNavigatorInfo(),i=`Unknown`;return e instanceof t.FrakRpcError?i=`FrakRpcError: ${e.code} '${e.message}'`:e instanceof Error?i=e.message:typeof e==`string`&&(i=e),{timestamp:new Date().toISOString(),encodedUrl:btoa(window.location.href),encodedConfig:this.config?this.base64Encode(this.config):`no-config`,navigatorInfo:r?this.base64Encode(r):`no-navigator`,iframeStatus:n?this.base64Encode(n):`not-iframe`,lastRequest:this.lastRequest?this.base64Encode(this.lastRequest):`No Frak request logged`,lastResponse:this.lastResponse?this.base64Encode(this.lastResponse):`No Frak response logged`,clientStatus:this.isSetupDone?`setup`:`not-setup`,error:i}}static empty(){return new e}formatDebugInfo(e){let t=this.gatherDebugInfo(e);return`
+  Debug Information:
+  -----------------
+  Timestamp: ${t.timestamp}
+  URL: ${t.encodedUrl}
+  Config: ${t.encodedConfig}
+  Navigator Info: ${t.navigatorInfo}
+  IFrame Status: ${t.iframeStatus}
+  Last Request: ${t.lastRequest}
+  Last Response: ${t.lastResponse}
+  Client Status: ${t.clientStatus}
+  Error: ${t.error}
+  `.trim()}};const D=(()=>{if(typeof navigator>`u`)return!1;let e=navigator.userAgent;if(!(/iPhone|iPad|iPod/i.test(e)||/Macintosh/i.test(e)&&navigator.maxTouchPoints>1))return!1;let t=e.toLowerCase();return t.includes(`instagram`)||t.includes(`fban`)||t.includes(`fbav`)||t.includes(`facebook`)})();function O(e){e?localStorage.setItem(i,e):localStorage.removeItem(i)}function k(e,t){try{let n=new URL(e);if(!n.searchParams.has(`u`))return e;let r=M(window.location.href,t);return n.searchParams.delete(`u`),n.searchParams.append(`u`,r),n.toString()}catch{return e}}function A(e){let t=new URL(window.location.href);e&&t.searchParams.set(`fmt`,e);let n=t.protocol===`http:`?`x-safari-http`:`x-safari-https`;window.location.href=`${n}://${t.host}${t.pathname}${t.search}${t.hash}`}function j(e){return e.includes(`/common/social`)}function M(e,t){if(!t)return e;try{let n=new URL(e);return n.searchParams.set(`fmt`,t),n.toString()}catch{return`${e}${e.includes(`?`)?`&`:`?`}fmt=${encodeURIComponent(t)}`}}function N(e,t,n,r,i){if(i){let e=k(t,r);window.open(e,`_blank`);return}if(l(t)){let i=k(t,r);c(i,{onFallback:()=>{e.contentWindow?.postMessage({clientLifecycle:`deep-link-failed`,data:{originalUrl:i}},n)}})}else if(D&&j(t))A(r);else{let e=k(t,r);window.location.href=e}}function P({iframe:e,targetOrigin:n}){let r=new t.Deferred;return{handleEvent:t=>{if(!(`iframeLifecycle`in t))return;let{iframeLifecycle:a,data:o}=t;switch(a){case`connected`:r.resolve(!0);break;case`do-backup`:O(o.backup);break;case`remove-backup`:localStorage.removeItem(i);break;case`show`:case`hide`:_({iframe:e,isVisible:a===`show`});break;case`redirect`:N(e,o.baseRedirectUrl,n,o.mergeToken,o.openInNewTab);break}},isConnected:r.promise}}function F({config:r,iframe:i}){let a=r?.walletUrl??`https://wallet.frak.id`,o=typeof navigator<`u`?navigator.language?.split(`-`)[0]:void 0,s=r.metadata.lang??(o===`en`||o===`fr`?o:void 0),c=r.domain??(typeof window<`u`?window.location.hostname:``);e.t.setCacheScope(c,s),e.t.reset();let l=e.t.isCacheFresh?void 0:e.t.resolve(r.domain,r.walletUrl,s),u=P({iframe:i,targetOrigin:a}),d=new t.Deferred,f=Date.now(),p=new E(r,i);if(!i.contentWindow)throw new t.FrakRpcError(t.RpcErrorCodes.configError,`The iframe does not have a content window`);let m=(0,t.createRpcClient)({emittingTransport:i.contentWindow,listeningTransport:window,targetOrigin:a,middleware:[{async onRequest(e,n){if(!await u.isConnected)throw new t.FrakRpcError(t.RpcErrorCodes.clientNotConnected,`The iframe provider isn't connected yet`);return await d.promise,n}},{onRequest(e,t){return p.setLastRequest(e),t},onResponse(e,t){return p.setLastResponse(e,t),t}}],lifecycleHandlers:{iframeLifecycle:(e,t)=>{u.handleEvent(e)}}}),h=I(m,u),g=async()=>{h(),m.cleanup(),i.remove(),e.a(),e.t.clearCache(),e.t.reset()},_;{console.log(`[Frak SDK] Initializing OpenPanel`),_=new n.OpenPanel({apiUrl:`https://op-api.gcp.frak.id`,clientId:`6eacc8d7-49ac-4936-95e9-81ef29449570`,trackScreenViews:!0,trackOutgoingLinks:!0,trackAttributes:!1,filter:({type:t,payload:n})=>(t!==`track`||!n?.properties||`sdkVersion`in n.properties||(n.properties={...n.properties,sdkVersion:`1.0.0`,userAnonymousClientId:e.v()}),!0)}),_.setGlobalProperties({sdkVersion:`1.0.0`,userAnonymousClientId:e.v()}),_.init(),_.track(`sdk_initialized`,{sdkVersion:`1.0.0`});let t=!1,r=setTimeout(()=>{t||(t=!0,_?.track(`sdk_iframe_handshake_failed`,{reason:`timeout`}))},3e4);u.isConnected.then(()=>{t||(t=!0,clearTimeout(r),_?.track(`sdk_iframe_connected`,{handshake_duration_ms:Date.now()-f}))}).catch(()=>{t||(t=!0,clearTimeout(r),_?.track(`sdk_iframe_handshake_failed`,{reason:`unknown`}))})}let v=L({config:r,rpcClient:m,lifecycleManager:u,configPromise:l,contextSent:d,openPanel:_}).then(()=>p.updateSetupStatus(!0)).catch(e=>{throw d.reject(e),e});return{config:r,debugInfo:p,waitForConnection:u.isConnected,waitForSetup:v,request:m.request,listenerRequest:m.listen,destroy:g,openPanel:_}}function I(e,t){let n,r,i=()=>e.sendLifecycle({clientLifecycle:`heartbeat`});async function a(){i(),n=setInterval(i,1e3),r=setTimeout(()=>{o(),console.log(`Heartbeat timeout: connection failed`)},3e4),await t.isConnected,o()}function o(){n&&clearInterval(n),r&&clearTimeout(r)}return a(),o}async function L({config:t,rpcClient:n,lifecycleManager:r,configPromise:a,contextSent:o,openPanel:s}){await r.isConnected,T(n,r.isConnected);let c=new URL(window.location.href),l=c.searchParams.get(`fmt`)??void 0;l&&(c.searchParams.delete(`fmt`),window.history.replaceState({},``,c.toString()));let u=n=>{let r=n?.merchantId??t.metadata.merchantId??``,i=n?.domain??``,a=n?.allowedDomains??[],o=n?.sdkConfig,s=o?.attribution||t.attribution?{...t.attribution,...o?.attribution}:void 0;e.t.setConfig(o?{isResolved:!0,merchantId:r,domain:i,allowedDomains:a,hasRawSdkConfig:!0,name:o.name??t.metadata.name,logoUrl:o.logoUrl??t.metadata.logoUrl,homepageLink:o.homepageLink??t.metadata.homepageLink,lang:o.lang??t.metadata.lang,currency:o.currency??t.metadata.currency,hidden:o.hidden,css:o.css,translations:o.translations,placements:o.placements,components:o.components,attribution:s}:{isResolved:!0,merchantId:r,domain:i,allowedDomains:a,name:t.metadata.name,logoUrl:t.metadata.logoUrl,homepageLink:t.metadata.homepageLink,lang:t.metadata.lang,currency:t.metadata.currency,attribution:s})},d=!1,f=t=>{let r=d?void 0:l;d=!0;let i=t.hasRawSdkConfig?{name:t.name,logoUrl:t.logoUrl,homepageLink:t.homepageLink,lang:t.lang,currency:t.currency,hidden:t.hidden,css:t.css,translations:t.translations,placements:t.placements,attribution:t.attribution}:t.attribution?{attribution:t.attribution}:void 0,a=e.v();if(s){let e=s.global??{};s.setGlobalProperties({...e,merchantId:t.merchantId,domain:t.domain??``})}n.sendLifecycle({clientLifecycle:`resolved-config`,data:{merchantId:t.merchantId,domain:t.domain??``,allowedDomains:t.allowedDomains??[],sourceUrl:window.location.href,...a&&{sdkAnonymousId:a},...r&&{pendingMergeToken:r},...i&&{sdkConfig:i}}})};e.t.isResolved&&(f(e.t.getConfig()),o.resolve()),a&&(u(await a),f(e.t.getConfig()),o.resolve());async function p(){let e=t.customizations?.css;e&&n.sendLifecycle({clientLifecycle:`modal-css`,data:{cssLink:e}})}async function m(){let e=t.customizations?.i18n;e&&n.sendLifecycle({clientLifecycle:`modal-i18n`,data:{i18n:e}})}async function h(){if(typeof window>`u`)return;let e=window.localStorage.getItem(i);e&&n.sendLifecycle({clientLifecycle:`restore-backup`,data:{backup:e}})}(await Promise.allSettled([p(),m(),h()])).some(e=>e.status===`rejected`)&&s?.track(`sdk_iframe_handshake_failed`,{reason:`asset_push`})}async function R({config:e}){let t=z(e),n=await g({config:t});if(!n){console.error(`Failed to create iframe`);return}let r=F({config:t,iframe:n});if(await r.waitForSetup,!await r.waitForConnection){console.error(`Failed to connect to client`);return}return r}function z(e){let t=d(e.metadata?.currency);return{...e,metadata:{...e.metadata,currency:t}}}Object.defineProperty(exports,`_`,{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,`a`,{enumerable:!0,get:function(){return b}}),Object.defineProperty(exports,`b`,{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,`c`,{enumerable:!0,get:function(){return h}}),Object.defineProperty(exports,`d`,{enumerable:!0,get:function(){return m}}),Object.defineProperty(exports,`f`,{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,`g`,{enumerable:!0,get:function(){return o}}),Object.defineProperty(exports,`h`,{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,`i`,{enumerable:!0,get:function(){return w}}),Object.defineProperty(exports,`l`,{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,`m`,{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return F}}),Object.defineProperty(exports,`o`,{enumerable:!0,get:function(){return S}}),Object.defineProperty(exports,`p`,{enumerable:!0,get:function(){return f}}),Object.defineProperty(exports,`r`,{enumerable:!0,get:function(){return E}}),Object.defineProperty(exports,`s`,{enumerable:!0,get:function(){return C}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return R}}),Object.defineProperty(exports,`u`,{enumerable:!0,get:function(){return v}}),Object.defineProperty(exports,`v`,{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,`x`,{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,`y`,{enumerable:!0,get:function(){return c}});

package/dist/src-D_QRg85U.js

@@ -0,0 +1,13 @@
+import{a as e,h as t,t as n,v as r}from"./sdkConfigStore-BXzz5PlK.js";import{Deferred as i,FrakRpcError as a,RpcErrorCodes as o,createRpcClient as s,jsonDecode as c}from"@frak-labs/frame-connector";import{OpenPanel as l}from"@openpanel/web";function u(e){return c(t(e))}const d=`nexus-wallet-backup`,f=`frakwallet://`;function p(){let e=navigator.userAgent;return/Android/i.test(e)&&/Chrome\/\d+/i.test(e)}function m(e){return`intent://${e.slice(13)}#Intent;scheme=frakwallet;end`}function h(e,t){let n=t?.timeout??2500,r=!1,i=()=>{document.hidden&&(r=!0)};document.addEventListener(`visibilitychange`,i);let a=p()&&g(e)?m(e):e;window.location.href=a,setTimeout(()=>{document.removeEventListener(`visibilitychange`,i),r||t?.onFallback?.()},n)}function g(e){return e.startsWith(f)}const _={eur:`fr-FR`,usd:`en-US`,gbp:`en-GB`};function v(e){return e&&e in _?e:`eur`}function y(e){return e?_[e]??_.eur:_.eur}function b(e,t){let n=y(t),r=v(t);return e.toLocaleString(n,{style:`currency`,currency:r,minimumFractionDigits:0,maximumFractionDigits:2})}function x(e){return e?`${e}Amount`:`eurAmount`}const S={id:`frak-wallet`,name:`frak-wallet`,title:`Frak Wallet`,allow:`publickey-credentials-get *; clipboard-write; web-share *`,style:{width:`0`,height:`0`,border:`0`,position:`absolute`,zIndex:2000001,top:`-1000px`,left:`-1000px`,colorScheme:`auto`}};function C({walletBaseUrl:e,config:t}){let n=document.querySelector(`#frak-wallet`);n&&n.remove();let i=document.createElement(`iframe`);i.id=S.id,i.name=S.name,i.allow=S.allow,i.style.zIndex=S.style.zIndex.toString(),w({iframe:i,isVisible:!1});let a=t?.walletUrl??e??`https://wallet.frak.id`,o=r();return i.src=`${a}/listener?clientId=${encodeURIComponent(o)}`,new Promise(e=>{i.addEventListener(`load`,()=>e(i)),document.body.appendChild(i)})}function w({iframe:e,isVisible:t}){if(!t){e.style.width=`0`,e.style.height=`0`,e.style.border=`0`,e.style.position=`fixed`,e.style.top=`-1000px`,e.style.left=`-1000px`;return}e.style.position=`fixed`,e.style.top=`0`,e.style.left=`0`,e.style.width=`100%`,e.style.height=`100%`,e.style.pointerEvents=`auto`}function T(e=`/listener`){if(!window.opener)return null;let t=t=>{try{return t.location.origin===window.location.origin&&t.location.pathname===e}catch{return!1}};if(t(window.opener))return window.opener;try{let e=window.opener.frames;for(let n=0;n<e.length;n++)if(t(e[n]))return e[n];return null}catch(t){return console.error(`[findIframeInOpener] Error finding iframe with pathname ${e}:`,t),null}}function E(){if(typeof navigator>`u`)return!1;let e=navigator.userAgent;return!!(/iPhone|iPad|iPod/i.test(e)||/Macintosh/i.test(e)&&navigator.maxTouchPoints>1)}const D=E();function O(){if(typeof navigator>`u`)return!1;let e=navigator.userAgent.toLowerCase();return e.includes(`instagram`)||e.includes(`fban`)||e.includes(`fbav`)||e.includes(`facebook`)}const k=O();function A(e){D&&e.startsWith(`https://`)?window.location.href=`x-safari-https://${e.slice(8)}`:D&&e.startsWith(`http://`)?window.location.href=`x-safari-http://${e.slice(7)}`:window.location.href=`https://backend.frak.id/common/social?u=${encodeURIComponent(e)}`}function j({perCall:e,defaults:t,productUtmContent:n}){if(e===null)return;let r=e!==void 0,i=t!==void 0&&Object.keys(t).length>0;if(!r&&!i&&!(n!==void 0&&n!==``))return;let a={...t,...e??{}},o=n??e?.utmContent;return o!==void 0&&o!==``?a.utmContent=o:delete a.utmContent,a}function M(e,t){if(typeof window>`u`)return;let n=new URL(window.location.href),r=n.searchParams.get(`sso`);r&&(t.then(()=>{e.sendLifecycle({clientLifecycle:`sso-redirect-complete`,data:{compressed:r}}),console.log(`[SSO URL Listener] Forwarded compressed SSO data to iframe`)}).catch(e=>{console.error(`[SSO URL Listener] Failed to forward SSO data:`,e)}),n.searchParams.delete(`sso`),window.history.replaceState({},``,n.toString()),console.log(`[SSO URL Listener] SSO parameter detected and URL cleaned`))}var N=class e{config;iframe;isSetupDone=!1;lastResponse=null;lastRequest=null;constructor(e,t){this.config=e,this.iframe=t,this.lastRequest=null,this.lastResponse=null}setLastResponse(e,t){this.lastResponse={message:e,response:t,timestamp:Date.now()}}setLastRequest(e){this.lastRequest={event:e,timestamp:Date.now()}}updateSetupStatus(e){this.isSetupDone=e}base64Encode(e){try{return btoa(JSON.stringify(e))}catch(e){return console.warn(`Failed to encode debug data`,e),btoa(`Failed to encode data`)}}getIframeStatus(){return this.iframe?{loading:this.iframe.hasAttribute(`loading`),url:this.iframe.src,readyState:this.iframe.contentDocument?.readyState?+(this.iframe.contentDocument.readyState===`complete`):-1,contentWindow:!!this.iframe.contentWindow,isConnected:this.iframe.isConnected}:null}getNavigatorInfo(){return navigator?{userAgent:navigator.userAgent,language:navigator.language,onLine:navigator.onLine,screenWidth:window.screen.width,screenHeight:window.screen.height,pixelRatio:window.devicePixelRatio}:null}gatherDebugInfo(e){let t=this.getIframeStatus(),n=this.getNavigatorInfo(),r=`Unknown`;return e instanceof a?r=`FrakRpcError: ${e.code} '${e.message}'`:e instanceof Error?r=e.message:typeof e==`string`&&(r=e),{timestamp:new Date().toISOString(),encodedUrl:btoa(window.location.href),encodedConfig:this.config?this.base64Encode(this.config):`no-config`,navigatorInfo:n?this.base64Encode(n):`no-navigator`,iframeStatus:t?this.base64Encode(t):`not-iframe`,lastRequest:this.lastRequest?this.base64Encode(this.lastRequest):`No Frak request logged`,lastResponse:this.lastResponse?this.base64Encode(this.lastResponse):`No Frak response logged`,clientStatus:this.isSetupDone?`setup`:`not-setup`,error:r}}static empty(){return new e}formatDebugInfo(e){let t=this.gatherDebugInfo(e);return`
+  Debug Information:
+  -----------------
+  Timestamp: ${t.timestamp}
+  URL: ${t.encodedUrl}
+  Config: ${t.encodedConfig}
+  Navigator Info: ${t.navigatorInfo}
+  IFrame Status: ${t.iframeStatus}
+  Last Request: ${t.lastRequest}
+  Last Response: ${t.lastResponse}
+  Client Status: ${t.clientStatus}
+  Error: ${t.error}
+  `.trim()}};const P=(()=>{if(typeof navigator>`u`)return!1;let e=navigator.userAgent;if(!(/iPhone|iPad|iPod/i.test(e)||/Macintosh/i.test(e)&&navigator.maxTouchPoints>1))return!1;let t=e.toLowerCase();return t.includes(`instagram`)||t.includes(`fban`)||t.includes(`fbav`)||t.includes(`facebook`)})();function F(e){e?localStorage.setItem(d,e):localStorage.removeItem(d)}function I(e,t){try{let n=new URL(e);if(!n.searchParams.has(`u`))return e;let r=z(window.location.href,t);return n.searchParams.delete(`u`),n.searchParams.append(`u`,r),n.toString()}catch{return e}}function L(e){let t=new URL(window.location.href);e&&t.searchParams.set(`fmt`,e);let n=t.protocol===`http:`?`x-safari-http`:`x-safari-https`;window.location.href=`${n}://${t.host}${t.pathname}${t.search}${t.hash}`}function R(e){return e.includes(`/common/social`)}function z(e,t){if(!t)return e;try{let n=new URL(e);return n.searchParams.set(`fmt`,t),n.toString()}catch{return`${e}${e.includes(`?`)?`&`:`?`}fmt=${encodeURIComponent(t)}`}}function B(e,t,n,r,i){if(i){let e=I(t,r);window.open(e,`_blank`);return}if(g(t)){let i=I(t,r);h(i,{onFallback:()=>{e.contentWindow?.postMessage({clientLifecycle:`deep-link-failed`,data:{originalUrl:i}},n)}})}else if(P&&R(t))L(r);else{let e=I(t,r);window.location.href=e}}function V({iframe:e,targetOrigin:t}){let n=new i;return{handleEvent:r=>{if(!(`iframeLifecycle`in r))return;let{iframeLifecycle:i,data:a}=r;switch(i){case`connected`:n.resolve(!0);break;case`do-backup`:F(a.backup);break;case`remove-backup`:localStorage.removeItem(d);break;case`show`:case`hide`:w({iframe:e,isVisible:i===`show`});break;case`redirect`:B(e,a.baseRedirectUrl,t,a.mergeToken,a.openInNewTab);break}},isConnected:n.promise}}function H({config:t,iframe:c}){let u=t?.walletUrl??`https://wallet.frak.id`,d=typeof navigator<`u`?navigator.language?.split(`-`)[0]:void 0,f=t.metadata.lang??(d===`en`||d===`fr`?d:void 0),p=t.domain??(typeof window<`u`?window.location.hostname:``);n.setCacheScope(p,f),n.reset();let m=n.isCacheFresh?void 0:n.resolve(t.domain,t.walletUrl,f),h=V({iframe:c,targetOrigin:u}),g=new i,_=Date.now(),v=new N(t,c);if(!c.contentWindow)throw new a(o.configError,`The iframe does not have a content window`);let y=s({emittingTransport:c.contentWindow,listeningTransport:window,targetOrigin:u,middleware:[{async onRequest(e,t){if(!await h.isConnected)throw new a(o.clientNotConnected,`The iframe provider isn't connected yet`);return await g.promise,t}},{onRequest(e,t){return v.setLastRequest(e),t},onResponse(e,t){return v.setLastResponse(e,t),t}}],lifecycleHandlers:{iframeLifecycle:(e,t)=>{h.handleEvent(e)}}}),b=U(y,h),x=async()=>{b(),y.cleanup(),c.remove(),e(),n.clearCache(),n.reset()},S;{console.log(`[Frak SDK] Initializing OpenPanel`),S=new l({apiUrl:`https://op-api.gcp.frak.id`,clientId:`6eacc8d7-49ac-4936-95e9-81ef29449570`,trackScreenViews:!0,trackOutgoingLinks:!0,trackAttributes:!1,filter:({type:e,payload:t})=>(e!==`track`||!t?.properties||`sdkVersion`in t.properties||(t.properties={...t.properties,sdkVersion:`1.0.0`,userAnonymousClientId:r()}),!0)}),S.setGlobalProperties({sdkVersion:`1.0.0`,userAnonymousClientId:r()}),S.init(),S.track(`sdk_initialized`,{sdkVersion:`1.0.0`});let e=!1,t=setTimeout(()=>{e||(e=!0,S?.track(`sdk_iframe_handshake_failed`,{reason:`timeout`}))},3e4);h.isConnected.then(()=>{e||(e=!0,clearTimeout(t),S?.track(`sdk_iframe_connected`,{handshake_duration_ms:Date.now()-_}))}).catch(()=>{e||(e=!0,clearTimeout(t),S?.track(`sdk_iframe_handshake_failed`,{reason:`unknown`}))})}let C=W({config:t,rpcClient:y,lifecycleManager:h,configPromise:m,contextSent:g,openPanel:S}).then(()=>v.updateSetupStatus(!0)).catch(e=>{throw g.reject(e),e});return{config:t,debugInfo:v,waitForConnection:h.isConnected,waitForSetup:C,request:y.request,listenerRequest:y.listen,destroy:x,openPanel:S}}function U(e,t){let n,r,i=()=>e.sendLifecycle({clientLifecycle:`heartbeat`});async function a(){i(),n=setInterval(i,1e3),r=setTimeout(()=>{o(),console.log(`Heartbeat timeout: connection failed`)},3e4),await t.isConnected,o()}function o(){n&&clearInterval(n),r&&clearTimeout(r)}return a(),o}async function W({config:e,rpcClient:t,lifecycleManager:i,configPromise:a,contextSent:o,openPanel:s}){await i.isConnected,M(t,i.isConnected);let c=new URL(window.location.href),l=c.searchParams.get(`fmt`)??void 0;l&&(c.searchParams.delete(`fmt`),window.history.replaceState({},``,c.toString()));let u=t=>{let r=t?.merchantId??e.metadata.merchantId??``,i=t?.domain??``,a=t?.allowedDomains??[],o=t?.sdkConfig,s=o?.attribution||e.attribution?{...e.attribution,...o?.attribution}:void 0;n.setConfig(o?{isResolved:!0,merchantId:r,domain:i,allowedDomains:a,hasRawSdkConfig:!0,name:o.name??e.metadata.name,logoUrl:o.logoUrl??e.metadata.logoUrl,homepageLink:o.homepageLink??e.metadata.homepageLink,lang:o.lang??e.metadata.lang,currency:o.currency??e.metadata.currency,hidden:o.hidden,css:o.css,translations:o.translations,placements:o.placements,components:o.components,attribution:s}:{isResolved:!0,merchantId:r,domain:i,allowedDomains:a,name:e.metadata.name,logoUrl:e.metadata.logoUrl,homepageLink:e.metadata.homepageLink,lang:e.metadata.lang,currency:e.metadata.currency,attribution:s})},f=!1,p=e=>{let n=f?void 0:l;f=!0;let i=e.hasRawSdkConfig?{name:e.name,logoUrl:e.logoUrl,homepageLink:e.homepageLink,lang:e.lang,currency:e.currency,hidden:e.hidden,css:e.css,translations:e.translations,placements:e.placements,attribution:e.attribution}:e.attribution?{attribution:e.attribution}:void 0,a=r();if(s){let t=s.global??{};s.setGlobalProperties({...t,merchantId:e.merchantId,domain:e.domain??``})}t.sendLifecycle({clientLifecycle:`resolved-config`,data:{merchantId:e.merchantId,domain:e.domain??``,allowedDomains:e.allowedDomains??[],sourceUrl:window.location.href,...a&&{sdkAnonymousId:a},...n&&{pendingMergeToken:n},...i&&{sdkConfig:i}}})};n.isResolved&&(p(n.getConfig()),o.resolve()),a&&(u(await a),p(n.getConfig()),o.resolve());async function m(){let n=e.customizations?.css;n&&t.sendLifecycle({clientLifecycle:`modal-css`,data:{cssLink:n}})}async function h(){let n=e.customizations?.i18n;n&&t.sendLifecycle({clientLifecycle:`modal-i18n`,data:{i18n:n}})}async function g(){if(typeof window>`u`)return;let e=window.localStorage.getItem(d);e&&t.sendLifecycle({clientLifecycle:`restore-backup`,data:{backup:e}})}(await Promise.allSettled([m(),h(),g()])).some(e=>e.status===`rejected`)&&s?.track(`sdk_iframe_handshake_failed`,{reason:`asset_push`})}async function G({config:e}){let t=K(e),n=await C({config:t});if(!n){console.error(`Failed to create iframe`);return}let r=H({config:t,iframe:n});if(await r.waitForSetup,!await r.waitForConnection){console.error(`Failed to connect to client`);return}return r}function K(e){let t=v(e.metadata?.currency);return{...e,metadata:{...e.metadata,currency:t}}}export{g as _,D as a,f as b,S as c,x as d,b as f,p as g,_ as h,j as i,C as l,v as m,H as n,k as o,y as p,N as r,A as s,G as t,T as u,m as v,u as x,h as y};

package/package.json

@@ -11,7 +11,7 @@
       "url": "https://twitter.com/QNivelais"
     }
   ],
-  "version": "1.0.0-beta.a7645eaa",
+  "version": "1.0.0-beta.b917e199",
   "description": "Core SDK of the Frak wallet, low level library to interact directly with the frak ecosystem.",
   "repository": {
     "url": "https://github.com/frak-id/wallet",
@@ -91,7 +91,7 @@
     "viem": "^2.x"
   },
   "dependencies": {
-    "@frak-labs/frame-connector": "0.2.0-beta.a7645eaa",
+    "@frak-labs/frame-connector": "0.2.0-beta.b917e199",
     "@openpanel/web": "^1.2.0"
   },
   "devDependencies": {

package/src/utils/FrakContext.test.ts

@@ -25,10 +25,12 @@ describe("FrakContextManager", () => {
     });
 
     describe("V2 context", () => {
+        const MERCHANT_ID = "550e8400-e29b-41d4-a716-446655440000";
+        const CLIENT_ID = "550e8400-e29b-41d4-a716-446655440001";
         const v2Context: FrakContextV2 = {
             v: 2,
-            c: "test-client-id-uuid",
-            m: "merchant-uuid-1234",
+            c: CLIENT_ID,
+            m: MERCHANT_ID,
             t: 1709654400,
         };
 
@@ -53,7 +55,7 @@ describe("FrakContextManager", () => {
             it("should compress v2 context with wallet only (no clientId)", () => {
                 const v2WithWalletOnly: FrakContextV2 = {
                     v: 2,
-                    m: "merchant-uuid-1234",
+                    m: MERCHANT_ID,
                     t: 1709654400,
                     w: "0x1234567890123456789012345678901234567890" as Address,
                 };
@@ -66,8 +68,8 @@ describe("FrakContextManager", () => {
             it("should compress v2 context with both clientId and wallet", () => {
                 const v2Hybrid: FrakContextV2 = {
                     v: 2,
-                    c: "test-client-id-uuid",
-                    m: "merchant-uuid-1234",
+                    c: CLIENT_ID,
+                    m: MERCHANT_ID,
                     t: 1709654400,
                     w: "0x1234567890123456789012345678901234567890" as Address,
                 };
@@ -78,7 +80,7 @@ describe("FrakContextManager", () => {
             });
 
             it("should return undefined when v2 context is missing merchantId", () => {
-                const partial = { v: 2 as const, c: "c", t: 123 };
+                const partial = { v: 2 as const, c: CLIENT_ID, t: 123 };
                 const result = FrakContextManager.compress(
                     partial as FrakContextV2
                 );
@@ -86,7 +88,7 @@ describe("FrakContextManager", () => {
             });
 
             it("should return undefined when v2 context is missing timestamp", () => {
-                const partial = { v: 2 as const, c: "c", m: "m" };
+                const partial = { v: 2 as const, c: CLIENT_ID, m: MERCHANT_ID };
                 const result = FrakContextManager.compress(
                     partial as FrakContextV2
                 );
@@ -96,7 +98,7 @@ describe("FrakContextManager", () => {
             it("should reject v2 context with a malformed wallet address", () => {
                 const partial = {
                     v: 2 as const,
-                    m: "merchant-uuid",
+                    m: MERCHANT_ID,
                     t: 1709654400,
                     w: "0xnot-a-valid-address" as Address,
                 };
@@ -110,8 +112,8 @@ describe("FrakContextManager", () => {
             it("should drop a malformed wallet but keep a valid clientId", () => {
                 const hybrid = {
                     v: 2 as const,
-                    c: "valid-client-id",
-                    m: "merchant-uuid",
+                    c: CLIENT_ID,
+                    m: MERCHANT_ID,
                     t: 1709654400,
                     w: "0xnot-a-valid-address" as Address,
                 };
@@ -121,8 +123,8 @@ describe("FrakContextManager", () => {
                 const decompressed = FrakContextManager.decompress(compressed);
                 expect(decompressed).toEqual({
                     v: 2,
-                    c: "valid-client-id",
-                    m: "merchant-uuid",
+                    c: CLIENT_ID,
+                    m: MERCHANT_ID,
                     t: 1709654400,
                 });
             });
@@ -136,26 +138,20 @@ describe("FrakContextManager", () => {
                 expect(decompressed).toEqual(v2Context);
             });
 
-            it("should drop malformed `w` field on decompress (defense against crafted URLs)", async () => {
-                // Manually compress a payload bypassing client-side validation
-                // by reaching into the underlying compressJsonToB64.
-                const { compressJsonToB64 } = await import(
-                    "./compression/compress"
+            it("should reject payloads whose header reserved bits are set", async () => {
+                // Craft a valid V2 binary payload then flip a reserved bit
+                // in the header — decompress must refuse to parse it (forward-compat guard).
+                const { encodeFrakContextV2 } = await import(
+                    "./frakContextV2Codec"
                 );
-                const malformed = compressJsonToB64({
-                    v: 2,
-                    c: "valid-client-id",
-                    m: "merchant-uuid",
-                    t: 1709654400,
-                    w: "0xnot-a-real-address",
-                });
-                const result = FrakContextManager.decompress(malformed);
-                expect(result).toEqual({
-                    v: 2,
-                    c: "valid-client-id",
-                    m: "merchant-uuid",
-                    t: 1709654400,
-                });
+                const { base64urlEncode } = await import("./compression/b64");
+                const encoded = encodeFrakContextV2(v2Context);
+                expect(encoded).toBeDefined();
+                const tampered = new Uint8Array(encoded as Uint8Array);
+                tampered[0] |= 0x40; // set a reserved bit
+                const payload = base64urlEncode(tampered);
+                const result = FrakContextManager.decompress(payload);
+                expect(result).toBeUndefined();
             });
         });
 
@@ -169,8 +165,8 @@ describe("FrakContextManager", () => {
                 expect(result).toBeDefined();
                 expect(result).toHaveProperty("v", 2);
                 const v2 = result as FrakContextV2;
-                expect(v2.c).toBe("test-client-id-uuid");
-                expect(v2.m).toBe("merchant-uuid-1234");
+                expect(v2.c).toBe(CLIENT_ID);
+                expect(v2.m).toBe(MERCHANT_ID);
                 expect(v2.t).toBe(1709654400);
             });
         });
@@ -650,8 +646,8 @@ describe("FrakContextManager", () => {
             const url = "https://example.com/test";
             const context: FrakContextV2 = {
                 v: 2,
-                c: "client-id",
-                m: "merchant-id",
+                c: "550e8400-e29b-41d4-a716-446655440001",
+                m: "550e8400-e29b-41d4-a716-446655440000",
                 t: 1709654400,
             };
 

package/src/utils/FrakContext.ts

@@ -7,8 +7,7 @@ import type {
 } from "../types";
 import { isV2Context } from "../types";
 import { base64urlDecode, base64urlEncode } from "./compression/b64";
-import { compressJsonToB64 } from "./compression/compress";
-import { decompressJsonFromB64 } from "./compression/decompress";
+import { decodeFrakContextV2, encodeFrakContextV2 } from "./frakContextV2Codec";
 
 /**
  * URL parameter key for the Frak referral context
@@ -18,7 +17,8 @@ const contextKey = "fCtx";
 /**
  * Compress a Frak context into a URL-safe string.
  *
- * - V2 contexts are serialized as compressed JSON (base64url).
+ * - V2 contexts are encoded using a compact binary layout (see
+ *   {@link encodeFrakContextV2}) then base64url-encoded.
  * - V1 contexts encode the wallet address as raw bytes (base64url).
  *
  * @param context - The context to compress (V1 or V2)
@@ -28,18 +28,9 @@ function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
     if (!context) return;
     try {
         if (isV2Context(context)) {
-            // Runtime validation: m + t are always required, and at least one of
-            // c (anonymous fingerprint) or w (valid wallet) must be present.
-            if (!context.m || !context.t) return undefined;
-            const hasValidWallet = context.w && isAddress(context.w);
-            if (!context.c && !hasValidWallet) return undefined;
-            return compressJsonToB64({
-                v: 2,
-                m: context.m,
-                t: context.t,
-                ...(context.c ? { c: context.c } : {}),
-                ...(hasValidWallet ? { w: context.w } : {}),
-            });
+            const encoded = encodeFrakContextV2(context);
+            if (!encoded) return undefined;
+            return base64urlEncode(encoded);
         }
 
         // V1 legacy: compress wallet address as raw bytes
@@ -54,7 +45,8 @@ function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
 /**
  * Decompress a base64url string back into a Frak context.
  *
- * Attempts V2 JSON decompression first, then falls back to V1 raw bytes.
+ * V1 (exactly 20 bytes) and V2 (37, 41, or 57 bytes) are distinguished by
+ * their decoded byte length, so there is no ambiguity.
  *
  * @param context - The compressed context string
  * @returns The decompressed FrakContext, or undefined on failure
@@ -62,25 +54,16 @@ function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
 function decompress(context?: string): FrakContext | undefined {
     if (!context || context.length === 0) return;
     try {
-        // Try V2 JSON first — V2 payloads are longer than V1's 20-byte address
-        const json = decompressJsonFromB64<FrakContextV2>(context);
-        if (json && typeof json === "object" && json.v === 2) {
-            if (!json.m || !json.t) return undefined;
-            // Validate `w` with isAddress() — protects self-referral checks and
-            // URL replacement from crafted payloads carrying a malformed wallet.
-            const hasValidWallet = json.w && isAddress(json.w);
-            if (!json.c && !hasValidWallet) return undefined;
-            return {
-                v: 2,
-                m: json.m,
-                t: json.t,
-                ...(json.c ? { c: json.c } : {}),
-                ...(hasValidWallet ? { w: json.w } : {}),
-            };
+        const bytes = base64urlDecode(context);
+
+        // V1 is a raw 20-byte wallet address; V2 binary is always longer
+        // and starts with a header byte whose low nibble is the version.
+        if (bytes.length !== 20) {
+            const v2 = decodeFrakContextV2(bytes);
+            if (v2) return v2;
+            return undefined;
         }
 
-        // Fall back to V1: raw 20-byte address
-        const bytes = base64urlDecode(context);
         const hex = bytesToHex(bytes, { size: 20 }) as Address;
         if (isAddress(hex)) {
             return { r: hex };

package/src/utils/frakContextV2Codec.test.ts

@@ -0,0 +1,241 @@
+import type { Address } from "viem";
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import type { FrakContextV2 } from "../types";
+import { base64urlEncode } from "./compression/b64";
+import {
+    decodeFrakContextV2,
+    encodeFrakContextV2,
+    isV2BinaryLength,
+} from "./frakContextV2Codec";
+
+const MERCHANT = "550e8400-e29b-41d4-a716-446655440000";
+const CLIENT = "550e8400-e29b-41d4-a716-446655440001";
+const WALLET = "0x1234567890123456789012345678901234567890" as Address;
+
+describe("frakContextV2Codec", () => {
+    describe("encodeFrakContextV2 / decodeFrakContextV2 round-trip", () => {
+        it("round-trips a context with clientId only (37 bytes)", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                c: CLIENT,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            expect(encoded).toBeInstanceOf(Uint8Array);
+            expect(encoded?.length).toBe(37);
+            expect(decodeFrakContextV2(encoded as Uint8Array)).toEqual(ctx);
+        });
+
+        it("round-trips a context with wallet only (41 bytes)", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                w: WALLET,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            expect(encoded?.length).toBe(41);
+            expect(decodeFrakContextV2(encoded as Uint8Array)).toEqual(ctx);
+        });
+
+        it("round-trips a context with clientId + wallet (57 bytes)", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                c: CLIENT,
+                w: WALLET,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            expect(encoded?.length).toBe(57);
+            expect(decodeFrakContextV2(encoded as Uint8Array)).toEqual(ctx);
+        });
+
+        it("produces a base64url string shorter than the legacy JSON format", () => {
+            // Legacy reference: a typical anonymous context is ~115 JSON bytes
+            // \u2192 ~154 base64url chars. Wallet variant is ~165 \u2192 ~220 chars.
+            const ctxBoth: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 1709654400,
+                c: CLIENT,
+                w: WALLET,
+            };
+            const encoded = base64urlEncode(
+                encodeFrakContextV2(ctxBoth) as Uint8Array
+            );
+            // 57 bytes encodes to 76 chars (no padding).
+            expect(encoded.length).toBe(76);
+            // Sanity: far below the legacy ~220-char payload.
+            expect(encoded.length).toBeLessThan(100);
+        });
+
+        it("preserves UUID case insensitivity on decode", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT.toUpperCase(),
+                t: 1,
+                c: CLIENT,
+            };
+            const encoded = encodeFrakContextV2(ctx);
+            const decoded = decodeFrakContextV2(encoded as Uint8Array);
+            // Decoded UUIDs are lower-case canonical.
+            expect(decoded?.m).toBe(MERCHANT);
+        });
+
+        it("preserves timestamp at the uint32 boundary", () => {
+            const ctx: FrakContextV2 = {
+                v: 2,
+                m: MERCHANT,
+                t: 0xff_ff_ff_ff,
+                c: CLIENT,
+            };
+            const decoded = decodeFrakContextV2(
+                encodeFrakContextV2(ctx) as Uint8Array
+            );
+            expect(decoded?.t).toBe(0xff_ff_ff_ff);
+        });
+    });
+
+    describe("encodeFrakContextV2 validation", () => {
+        it("rejects non-UUID merchant id", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: "not-a-uuid",
+                    t: 1,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+        });
+
+        it("rejects non-UUID client id", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1,
+                    c: "not-a-uuid",
+                })
+            ).toBeNull();
+        });
+
+        it("rejects malformed wallet address", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1,
+                    w: "0xnot-a-wallet" as Address,
+                })
+            ).toBeNull();
+        });
+
+        it("rejects contexts missing both c and w", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1,
+                } as FrakContextV2)
+            ).toBeNull();
+        });
+
+        it("rejects timestamps outside uint32 range", () => {
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: -1,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 0x1_00_00_00_00,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+            expect(
+                encodeFrakContextV2({
+                    v: 2,
+                    m: MERCHANT,
+                    t: 1.5,
+                    c: CLIENT,
+                })
+            ).toBeNull();
+        });
+    });
+
+    describe("decodeFrakContextV2 validation", () => {
+        it("returns null on wrong version nibble", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            const tampered = new Uint8Array(encoded);
+            tampered[0] = (tampered[0] & 0xf0) | 0x03; // flip version to 3
+            expect(decodeFrakContextV2(tampered)).toBeNull();
+        });
+
+        it("returns null when reserved header bits are set", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            const tampered = new Uint8Array(encoded);
+            tampered[0] |= 0x80;
+            expect(decodeFrakContextV2(tampered)).toBeNull();
+        });
+
+        it("returns null when neither flag is set", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            const tampered = new Uint8Array(encoded);
+            tampered[0] &= 0x0f; // clear flags, keep version
+            expect(decodeFrakContextV2(tampered)).toBeNull();
+        });
+
+        it("returns null when byte length disagrees with flags", () => {
+            const encoded = encodeFrakContextV2({
+                v: 2,
+                m: MERCHANT,
+                t: 1,
+                c: CLIENT,
+            }) as Uint8Array;
+            // Drop the trailing byte to break the expected length.
+            const truncated = encoded.subarray(0, encoded.length - 1);
+            expect(decodeFrakContextV2(truncated)).toBeNull();
+        });
+
+        it("returns null on an empty buffer", () => {
+            expect(decodeFrakContextV2(new Uint8Array(0))).toBeNull();
+        });
+    });
+
+    describe("isV2BinaryLength", () => {
+        it("matches exactly the three valid V2 sizes", () => {
+            expect(isV2BinaryLength(37)).toBe(true);
+            expect(isV2BinaryLength(41)).toBe(true);
+            expect(isV2BinaryLength(57)).toBe(true);
+        });
+
+        it("rejects V1 size and everything else", () => {
+            expect(isV2BinaryLength(20)).toBe(false);
+            expect(isV2BinaryLength(0)).toBe(false);
+            expect(isV2BinaryLength(36)).toBe(false);
+            expect(isV2BinaryLength(58)).toBe(false);
+        });
+    });
+});