@frak-labs/nexus-sdk 0.0.1-alpha

package/README.md

@@ -0,0 +1,70 @@
+# Nexus Wallet SDK
+
+This SDK help any dApps, or gated content provider, use the [Nexus Wallet](https://poc-wallet.frak.id/) as a regular wallet, with smoother UX for your end-users (pay for his gas fees, check the paywall options, track his consumption etc.)
+
+Checkout our documentation for more informations about the usage:
+ - [React client usage](https://docs.frak.id/wallet-sdk/how-to/client-react)
+ - [Core client usage](https://docs.frak.id/wallet-sdk/how-to/client-core)
+
+To have more info about how does it works under the hood, you can check [this](https://docs.frak.id/wallet-sdk/under-the-hood)
+
+## Installation
+
+```bash
+bun add viem @frak-labs/nexus-sdk
+```
+
+## Setup
+
+```ts
+import {
+    createIframe,
+    createIFrameNexusClient,
+} from "@frak-labs/nexus-sdk/core";
+import type { NexusClient, NexusWalletSdkConfig } from "@frak-labs/nexus-sdk/core";
+
+// Create the config for the Nexus Wallet SDK
+export const nexusConfig: NexusWalletSdkConfig = {
+    // The current url for the wallet sdk
+    walletUrl: "https://poc-wallet.frak.id",
+    // The content id on which this sdk will be used
+    contentId: "0xdeadbeef",
+    // The content title, this will be displayed to the user during a few registration steps
+    contentTitle: "My dApp content title"
+}
+
+// Create the iFrame and the associated NexusClient
+async function createClient(): Promise<NexusClient> {
+    // Create the iFrame that will be used for the communication with the nexus wallet
+    const iframe = await createIframe(nexusConfig);
+
+    // Build the client
+    const client = createIFrameNexusClient(nexusConfig, iframe);
+
+    // Wait for it to be ready
+    await client.waitForConnection();
+
+    // And then return it
+    return client;
+}
+
+// Create the client and use it
+export const nexusClient = await createClient();
+```
+
+## Sample usage
+
+Sample code to watch the current user wallet status:
+
+```ts
+import { nexusClient } from "./client";
+import { watchWalletStatus } from "@frak-labs/nexus-sdk/actions";
+import type { WalletStatusReturnType } from "@frak-labs/nexus-sdk/core";
+
+// Watch the wallet status
+watchWalletStatus(nexusClient, (walletStatus: WalletStatusReturnType) => {
+    console.log("Wallet status changed", { walletStatus });
+    // You can now use the status to update your UI
+});
+```
+

package/dist/chunk-4X75PGSK.cjs

@@ -0,0 +1,160 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+
+// src/core/utils/compression/compress.ts
+var _asynclzstring = require('async-lz-string');
+var _jssha256 = require('js-sha256');
+async function hashAndCompressData(data, keyProvider) {
+  const keys = keyProvider(data);
+  const validationHash = _jssha256.sha256.call(void 0, keys.join("_"));
+  const hashProtectedData = {
+    ...data,
+    validationHash
+  };
+  const compressed = await compressJson(hashProtectedData);
+  const compressedHash = _jssha256.sha256.call(void 0, compressed);
+  return {
+    compressed,
+    compressedHash
+  };
+}
+async function compressJson(data) {
+  return _asynclzstring.compressToBase64.call(void 0, JSON.stringify(data));
+}
+
+// src/core/utils/compression/decompress.ts
+
+
+async function decompressDataAndCheckHash(compressedData, keyAccessor) {
+  if (!(_optionalChain([compressedData, 'optionalAccess', _ => _.compressed]) && _optionalChain([compressedData, 'optionalAccess', _2 => _2.compressedHash]))) {
+    throw new Error("Missing compressed data");
+  }
+  const parsedData = await decompressJson(
+    compressedData.compressed
+  );
+  if (!parsedData) {
+    throw new Error(`Invalid compressed data: ${parsedData}`);
+  }
+  if (!_optionalChain([parsedData, 'optionalAccess', _3 => _3.validationHash])) {
+    throw new Error("Missing validation hash");
+  }
+  const expectedCompressedHash = _jssha256.sha256.call(void 0, compressedData.compressed);
+  if (expectedCompressedHash !== compressedData.compressedHash) {
+    throw new Error("Invalid compressed hash");
+  }
+  const keys = keyAccessor(parsedData);
+  const expectedValidationHash = _jssha256.sha256.call(void 0, keys.join("_"));
+  if (expectedValidationHash !== parsedData.validationHash) {
+    throw new Error("Invalid data validation hash");
+  }
+  return parsedData;
+}
+async function decompressJson(data) {
+  const decompressed = await _asynclzstring.decompressFromBase64.call(void 0, data);
+  try {
+    return JSON.parse(decompressed);
+  } catch (e) {
+    console.error("Invalid compressed data", e);
+    return null;
+  }
+}
+
+// src/core/utils/compression/iframeRpcKeyProvider.ts
+var iFrameRequestKeyProvider = (args) => {
+  if (args.method === "frak_getArticleUnlockOptions") {
+    return ["get-price", args.params[0], args.params[1]];
+  }
+  if (args.method === "frak_listenToWalletStatus") {
+    return ["wallet-status"];
+  }
+  if (args.method === "frak_listenToArticleUnlockStatus") {
+    return ["article-unlock-status", args.params[0], args.params[1]];
+  }
+  throw new Error(`No key provider found for the arguments ${args}`);
+};
+function getIFrameResponseKeyProvider(param) {
+  if (param.method === "frak_getArticleUnlockOptions") {
+    return (response) => [
+      "get-price-response",
+      response.prices.length
+    ];
+  }
+  if (param.method === "frak_listenToWalletStatus") {
+    return (response) => [
+      "wallet-status",
+      response.key,
+      response.key === "connected" ? response.wallet : "0xdeadbeef"
+    ];
+  }
+  if (param.method === "frak_listenToArticleUnlockStatus") {
+    return (response) => [
+      "article-unlock-status",
+      response.key,
+      response.key === "valid" ? response.allowedUntil.toString(16) : "deadbeef"
+    ];
+  }
+  throw new Error(`No key provider found for the request ${param}`);
+}
+
+// src/core/utils/iframeHelper.ts
+function createIframe({
+  walletBaseUrl
+}) {
+  const isAlreadyCreated = document.querySelector("#frak-wallet");
+  if (isAlreadyCreated) {
+    return Promise.resolve(void 0);
+  }
+  const iframe = document.createElement("iframe");
+  iframe.name = "frak-wallet";
+  iframe.id = "frak-wallet";
+  iframe.style.width = "0";
+  iframe.style.height = "0";
+  iframe.style.border = "0";
+  iframe.style.position = "absolute";
+  iframe.style.top = "-1000px";
+  iframe.style.left = "-1000px";
+  document.body.appendChild(iframe);
+  return new Promise((resolve) => {
+    _optionalChain([iframe, 'optionalAccess', _4 => _4.addEventListener, 'call', _5 => _5("load", () => resolve(iframe))]);
+    iframe.src = `${walletBaseUrl}/listener`;
+  });
+}
+
+// src/core/utils/compression/redirectKeyProvider.ts
+var redirectRequestKeyProvider = (args) => {
+  if (args.method === "frak_startArticleUnlock") {
+    return [
+      "start-unlock",
+      args.params.contentId,
+      args.params.articleId,
+      args.params.price.index.toString()
+    ];
+  }
+  throw new Error(`No key provider found for the arguments ${args}`);
+};
+function getRedirectResponseResponseKeyProvider(method) {
+  if (method === "frak_startArticleUnlock") {
+    return (response) => [
+      "start-unlock",
+      response.key,
+      response.status,
+      _nullishCoalesce(response.user, () => ( "0xdeadbeef"))
+    ];
+  }
+  throw new Error(`No key provider found for the method ${method}`);
+}
+
+
+
+
+
+
+
+
+
+
+exports.__publicField = __publicField; exports.hashAndCompressData = hashAndCompressData; exports.decompressDataAndCheckHash = decompressDataAndCheckHash; exports.iFrameRequestKeyProvider = iFrameRequestKeyProvider; exports.getIFrameResponseKeyProvider = getIFrameResponseKeyProvider; exports.createIframe = createIframe; exports.redirectRequestKeyProvider = redirectRequestKeyProvider; exports.getRedirectResponseResponseKeyProvider = getRedirectResponseResponseKeyProvider;

package/dist/chunk-JE64MPH2.js

@@ -0,0 +1,160 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+
+// src/core/utils/compression/compress.ts
+import { compressToBase64 } from "async-lz-string";
+import { sha256 } from "js-sha256";
+async function hashAndCompressData(data, keyProvider) {
+  const keys = keyProvider(data);
+  const validationHash = sha256(keys.join("_"));
+  const hashProtectedData = {
+    ...data,
+    validationHash
+  };
+  const compressed = await compressJson(hashProtectedData);
+  const compressedHash = sha256(compressed);
+  return {
+    compressed,
+    compressedHash
+  };
+}
+async function compressJson(data) {
+  return compressToBase64(JSON.stringify(data));
+}
+
+// src/core/utils/compression/decompress.ts
+import { decompressFromBase64 } from "async-lz-string";
+import { sha256 as sha2562 } from "js-sha256";
+async function decompressDataAndCheckHash(compressedData, keyAccessor) {
+  if (!(compressedData?.compressed && compressedData?.compressedHash)) {
+    throw new Error("Missing compressed data");
+  }
+  const parsedData = await decompressJson(
+    compressedData.compressed
+  );
+  if (!parsedData) {
+    throw new Error(`Invalid compressed data: ${parsedData}`);
+  }
+  if (!parsedData?.validationHash) {
+    throw new Error("Missing validation hash");
+  }
+  const expectedCompressedHash = sha2562(compressedData.compressed);
+  if (expectedCompressedHash !== compressedData.compressedHash) {
+    throw new Error("Invalid compressed hash");
+  }
+  const keys = keyAccessor(parsedData);
+  const expectedValidationHash = sha2562(keys.join("_"));
+  if (expectedValidationHash !== parsedData.validationHash) {
+    throw new Error("Invalid data validation hash");
+  }
+  return parsedData;
+}
+async function decompressJson(data) {
+  const decompressed = await decompressFromBase64(data);
+  try {
+    return JSON.parse(decompressed);
+  } catch (e) {
+    console.error("Invalid compressed data", e);
+    return null;
+  }
+}
+
+// src/core/utils/compression/iframeRpcKeyProvider.ts
+var iFrameRequestKeyProvider = (args) => {
+  if (args.method === "frak_getArticleUnlockOptions") {
+    return ["get-price", args.params[0], args.params[1]];
+  }
+  if (args.method === "frak_listenToWalletStatus") {
+    return ["wallet-status"];
+  }
+  if (args.method === "frak_listenToArticleUnlockStatus") {
+    return ["article-unlock-status", args.params[0], args.params[1]];
+  }
+  throw new Error(`No key provider found for the arguments ${args}`);
+};
+function getIFrameResponseKeyProvider(param) {
+  if (param.method === "frak_getArticleUnlockOptions") {
+    return (response) => [
+      "get-price-response",
+      response.prices.length
+    ];
+  }
+  if (param.method === "frak_listenToWalletStatus") {
+    return (response) => [
+      "wallet-status",
+      response.key,
+      response.key === "connected" ? response.wallet : "0xdeadbeef"
+    ];
+  }
+  if (param.method === "frak_listenToArticleUnlockStatus") {
+    return (response) => [
+      "article-unlock-status",
+      response.key,
+      response.key === "valid" ? response.allowedUntil.toString(16) : "deadbeef"
+    ];
+  }
+  throw new Error(`No key provider found for the request ${param}`);
+}
+
+// src/core/utils/iframeHelper.ts
+function createIframe({
+  walletBaseUrl
+}) {
+  const isAlreadyCreated = document.querySelector("#frak-wallet");
+  if (isAlreadyCreated) {
+    return Promise.resolve(void 0);
+  }
+  const iframe = document.createElement("iframe");
+  iframe.name = "frak-wallet";
+  iframe.id = "frak-wallet";
+  iframe.style.width = "0";
+  iframe.style.height = "0";
+  iframe.style.border = "0";
+  iframe.style.position = "absolute";
+  iframe.style.top = "-1000px";
+  iframe.style.left = "-1000px";
+  document.body.appendChild(iframe);
+  return new Promise((resolve) => {
+    iframe?.addEventListener("load", () => resolve(iframe));
+    iframe.src = `${walletBaseUrl}/listener`;
+  });
+}
+
+// src/core/utils/compression/redirectKeyProvider.ts
+var redirectRequestKeyProvider = (args) => {
+  if (args.method === "frak_startArticleUnlock") {
+    return [
+      "start-unlock",
+      args.params.contentId,
+      args.params.articleId,
+      args.params.price.index.toString()
+    ];
+  }
+  throw new Error(`No key provider found for the arguments ${args}`);
+};
+function getRedirectResponseResponseKeyProvider(method) {
+  if (method === "frak_startArticleUnlock") {
+    return (response) => [
+      "start-unlock",
+      response.key,
+      response.status,
+      response.user ?? "0xdeadbeef"
+    ];
+  }
+  throw new Error(`No key provider found for the method ${method}`);
+}
+
+export {
+  __publicField,
+  hashAndCompressData,
+  decompressDataAndCheckHash,
+  iFrameRequestKeyProvider,
+  getIFrameResponseKeyProvider,
+  createIframe,
+  redirectRequestKeyProvider,
+  getRedirectResponseResponseKeyProvider
+};

package/dist/client-SCwoh_kP.d.cts

@@ -0,0 +1,246 @@
+import { Hex, Address, RpcSchema } from 'viem';
+import { Prettify } from 'viem/chains';
+
+/**
+ * Configuration for the Frak Wallet SDK
+ */
+type FrakWalletSdkConfig = Readonly<{
+    walletUrl: string;
+    contentId: Hex;
+    contentTitle: string;
+}>;
+
+type PaidArticleUnlockPrice = Readonly<{
+    index: number;
+    unlockDurationInSec: number;
+    frkAmount: Hex;
+}>;
+
+/**
+ * Request to unlock a paid article
+ */
+type StartArticleUnlockParams = Readonly<{
+    articleId: Hex;
+    contentId: Hex;
+    imageUrl: string;
+    articleTitle: string;
+    contentTitle: string;
+    price: PaidArticleUnlockPrice;
+    articleUrl: string;
+    redirectUrl: string;
+    previewUrl?: string;
+}>;
+/**
+ * Return type of the unlock request
+ */
+type StartArticleUnlockReturnType = UnlockSuccess | AlreadyUnlocked | UnlockError;
+type UnlockSuccess = {
+    key: "success";
+    status: "in-progress";
+    user: Address;
+    userOpHash: Hex;
+};
+type AlreadyUnlocked = {
+    key: "already-unlocked";
+    status: "unlocked";
+    user: Address;
+};
+type UnlockError = {
+    key: "error" | "cancelled";
+    status: "locked";
+    user?: Address;
+    reason?: string;
+};
+
+/**
+ * The response to the get unlock options response
+ */
+type UnlockOptionsReturnType = Readonly<{
+    prices: {
+        index: number;
+        unlockDurationInSec: number;
+        frkAmount: Hex;
+        isUserAccessible: boolean | null;
+    }[];
+}>;
+
+/**
+ * The different types of response for the current unlock status
+ */
+type ArticleUnlockStatusReturnType = Readonly<UnlockStatusLocked | UnlockStatusProcessing | UnlockStatusValid | UnlockStatusError>;
+/**
+ * When the content unlocked was expired a few time ago
+ */
+type UnlockStatusLocked = {
+    key: "expired";
+    status: "locked";
+    expiredAt: number;
+} | {
+    key: "not-unlocked";
+    status: "locked";
+};
+/**
+ * When the content unlocked was expired a few time ago
+ */
+type UnlockStatusProcessing = {
+    key: "preparing" | "waiting-user-validation";
+} | {
+    key: "waiting-transaction-bundling";
+    userOpHash: Hex;
+} | {
+    key: "waiting-transaction-confirmation";
+    userOpHash: Hex;
+    txHash: Hex;
+};
+/**
+ * When the content unlocked was expired a few time ago
+ */
+type UnlockStatusValid = {
+    key: "valid";
+    status: "unlocked";
+    allowedUntil: number;
+};
+/**
+ * When the content unlocked was expired a few time ago
+ */
+type UnlockStatusError = {
+    key: "error";
+    status: "locked";
+    reason: string;
+};
+
+type WalletStatusReturnType = Readonly<WalletConnected | WalletNotConnected>;
+type WalletConnected = {
+    key: "connected";
+    wallet: Address;
+    frkBalanceAsHex: Hex;
+};
+type WalletNotConnected = {
+    key: "not-connected";
+};
+
+/**
+ * RPC interface that's used for the iframe communication
+ */
+type IFrameRpcSchema = [
+    /**
+     * Method used to fetch an article unlock options
+     */
+    {
+        Method: "frak_getArticleUnlockOptions";
+        Parameters: [contentId: Hex, articleId: Hex];
+        ReturnType: UnlockOptionsReturnType;
+    },
+    /**
+     * Method used to listen to the wallet status
+     */
+    {
+        Method: "frak_listenToWalletStatus";
+        Parameters?: undefined;
+        ReturnType: WalletStatusReturnType;
+    },
+    /**
+     * Method used to listen to an article unlock status
+     */
+    {
+        Method: "frak_listenToArticleUnlockStatus";
+        Parameters: [contentId: Hex, articleId: Hex];
+        ReturnType: ArticleUnlockStatusReturnType;
+    }
+];
+/**
+ * RPC interface that's used for the redirection communication
+ */
+type RedirectRpcSchema = [
+    /**
+     * Method used to start the unlock of an article
+     */
+    {
+        Method: "frak_startArticleUnlock";
+        Path: "/paywall";
+        Parameters: StartArticleUnlockParams;
+        ReturnType: StartArticleUnlockReturnType;
+    }
+];
+
+/**
+ * Type that extract the possible parameters from a RPC Schema
+ */
+type ExtractedParametersFromRpc<TRpcSchema extends RpcSchema | undefined = undefined> = TRpcSchema extends RpcSchema ? {
+    [K in keyof TRpcSchema]: Prettify<{
+        method: TRpcSchema[K] extends TRpcSchema[number] ? TRpcSchema[K]["Method"] : string;
+    } & (TRpcSchema[K] extends TRpcSchema[number] ? TRpcSchema[K]["Parameters"] extends undefined ? {
+        params?: never;
+    } : {
+        params: TRpcSchema[K]["Parameters"];
+    } : never)>;
+}[number] : {
+    method: string;
+    params?: unknown;
+};
+/**
+ * Type that extract the possible return type from a RPC Schema
+ */
+type ExtractedReturnTypeFromRpc<TRpcSchema extends RpcSchema | undefined = undefined, TParameters extends ExtractedParametersFromRpc<TRpcSchema> = ExtractedParametersFromRpc<TRpcSchema>> = TRpcSchema extends RpcSchema ? ExtractedMethodFromRpc<TRpcSchema, TParameters["method"]>["ReturnType"] : unknown;
+/**
+ * Type that extract the possible return type from a RPC Schema
+ */
+type ExtractedMethodFromRpc<TRpcSchema extends RpcSchema | undefined = undefined, TMethod extends ExtractedParametersFromRpc<TRpcSchema>["method"] = ExtractedParametersFromRpc<TRpcSchema>["method"]> = TRpcSchema extends RpcSchema ? Extract<TRpcSchema[number], {
+    Method: TMethod;
+}> : unknown;
+/**
+ * Type used for a one shot request function
+ */
+type RequestFn<TRpcSchema extends RpcSchema | undefined = undefined> = <TParameters extends ExtractedParametersFromRpc<TRpcSchema> = ExtractedParametersFromRpc<TRpcSchema>, _ReturnType = ExtractedReturnTypeFromRpc<TRpcSchema, TParameters>>(args: TParameters) => Promise<_ReturnType>;
+/**
+ * Type used for a one shot request function
+ */
+type ListenerRequestFn<TRpcSchema extends RpcSchema | undefined = undefined> = <TParameters extends ExtractedParametersFromRpc<TRpcSchema> = ExtractedParametersFromRpc<TRpcSchema>>(args: TParameters, callback: (result: ExtractedReturnTypeFromRpc<TRpcSchema, TParameters>) => void) => Promise<void>;
+/**
+ * IFrame transport interface
+ */
+type IFrameTransport = {
+    /**
+     * Wait for the connection to be established
+     */
+    waitForConnection: Promise<boolean>;
+    /**
+     * Function used to perform a single request via the iframe transport
+     */
+    request: RequestFn<IFrameRpcSchema>;
+    /**
+     * Function used to listen to a request response via the iframe transport
+     */
+    listenerRequest: ListenerRequestFn<IFrameRpcSchema>;
+    /**
+     * Function used to destroy the iframe transport
+     */
+    destroy: () => Promise<void>;
+};
+/**
+ * Represent an iframe event
+ */
+type IFrameEvent = IFrameRpcEvent | IFrameLifecycleEvent;
+/**
+ * Represent an iframe rpc event
+ */
+type IFrameRpcEvent = {
+    id: string;
+    topic: ExtractedParametersFromRpc<IFrameRpcSchema>["method"];
+    data: {
+        compressed: string;
+        compressedHash: string;
+    };
+};
+type IFrameLifecycleEvent = {
+    lifecycle: "connected";
+};
+
+/**
+ * Representing a Frak client
+ */
+type FrakClient = {
+    config: FrakWalletSdkConfig;
+} & IFrameTransport;
+
+export type { ArticleUnlockStatusReturnType as A, ExtractedParametersFromRpc as E, FrakClient as F, IFrameRpcSchema as I, PaidArticleUnlockPrice as P, RedirectRpcSchema as R, StartArticleUnlockReturnType as S, UnlockOptionsReturnType as U, WalletStatusReturnType as W, FrakWalletSdkConfig as a, StartArticleUnlockParams as b, ExtractedReturnTypeFromRpc as c, IFrameTransport as d, IFrameRpcEvent as e, IFrameEvent as f };