@mezo-org/passport 0.4.0-dev.1 → 0.4.0-dev.11

package/dist/src/utils/numbers.js

@@ -0,0 +1,40 @@
+/**
+ * Formats a number or bigint into a human-readable string with K, M, B, or T suffix.
+ * @param value The number or bigint to format.
+ * @param decimals Number of decimal places to include (ignored for bigint to avoid floating point issues).
+ * @returns The formatted number as a string.
+ */
+export function formatHumanReadableNumber(value, decimals = 4) {
+    return value.toLocaleString("en-US", {
+        notation: "compact",
+        compactDisplay: "short",
+        maximumFractionDigits: decimals,
+    });
+}
+/**
+ * Returns a number rounded up to the desired number of decimals.
+ * @param amount The number to round up.
+ * @param desiredDecimals The number of decimals to round up to.
+ * @returns The rounded up number.
+ * @see https://github.com/thesis/acre/blob/2078d339f4ddce79e69c78529c9d72910dd2640a/dapp/src/utils/numbersUtils.ts#L1-L3
+ */
+export function roundUpNumber(amount, desiredDecimals = 2) {
+    return Math.ceil(amount * 10 ** desiredDecimals) / 10 ** desiredDecimals;
+}
+/**
+ * Convert a fixed point bigint with precision `fixedPointDecimals` to a
+ * floating point number truncated to `desiredDecimals`.
+ * @param fixedPoint The fixed point bigint to convert.
+ * @param fixedPointDecimals The number of decimals in the fixed point bigint.
+ * @param desiredDecimals The number of decimals in the output number.
+ * @returns The floating point number truncated to `desiredDecimals`.
+ * @see https://github.com/tahowallet/extension/blob/f6b26b7cb4a0a0278b1fccc6319626638f1a6dfa/background/lib/fixed-point.ts#L216-L239
+ */
+export function fromFixedPoint(fixedPoint, fixedPointDecimals, desiredDecimals = 2) {
+    const fixedPointDesiredDecimalsAmount = fixedPoint /
+        10n ** BigInt(Math.max(1, fixedPointDecimals - desiredDecimals));
+    const formattedAmount = Number(fixedPointDesiredDecimalsAmount) /
+        10 ** Math.min(desiredDecimals, fixedPointDecimals);
+    return formattedAmount;
+}
+//# sourceMappingURL=numbers.js.map

package/dist/src/utils/numbers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.js","sourceRoot":"","sources":["../../../src/utils/numbers.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAsB,EACtB,QAAQ,GAAG,CAAC;IAEZ,OAAO,KAAK,CAAC,cAAc,CAAC,OAAO,EAAE;QACnC,QAAQ,EAAE,SAAS;QACnB,cAAc,EAAE,OAAO;QACvB,qBAAqB,EAAE,QAA2B;KACnD,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,eAAe,GAAG,CAAC;IAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,IAAI,eAAe,CAAC,GAAG,EAAE,IAAI,eAAe,CAAA;AAC1E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAkB,EAClB,kBAA0B,EAC1B,eAAe,GAAG,CAAC;IAEnB,MAAM,+BAA+B,GACnC,UAAU;QACV,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,kBAAkB,GAAG,eAAe,CAAC,CAAC,CAAA;IAElE,MAAM,eAAe,GACnB,MAAM,CAAC,+BAA+B,CAAC;QACvC,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAA;IAErD,OAAO,eAAe,CAAA;AACxB,CAAC"}

package/dist/src/utils/numbers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=numbers.test.d.ts.map

package/dist/src/utils/numbers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.test.d.ts","sourceRoot":"","sources":["../../../src/utils/numbers.test.ts"],"names":[],"mappings":""}

package/dist/src/utils/numbers.test.js

@@ -0,0 +1,54 @@
+import { formatHumanReadableNumber, fromFixedPoint, roundUpNumber, } from "./numbers";
+describe("formatHumanReadableNumber", () => {
+    it("formats number less than 1000 with decimals", () => {
+        expect(formatHumanReadableNumber(123.456789, 2)).toBe("123.46");
+    });
+    it("formats thousands with K", () => {
+        expect(formatHumanReadableNumber(12_345, 2)).toBe("12.35K");
+    });
+    it("formats millions with M", () => {
+        expect(formatHumanReadableNumber(12_345_678, 2)).toBe("12.35M");
+    });
+    it("formats billions with B", () => {
+        expect(formatHumanReadableNumber(12_345_678_901, 2)).toBe("12.35B");
+    });
+    it("formats trillions with T", () => {
+        expect(formatHumanReadableNumber(12_345_678_901_234, 2)).toBe("12.35T");
+    });
+    it("formats bigint as readable number", () => {
+        expect(formatHumanReadableNumber(1234567890123456789n, 2)).toBe("1,234,567.89T");
+    });
+    it("caps at > 1000T for huge numbers", () => {
+        const hugeNumber = 10 ** 18; // 1e18
+        expect(formatHumanReadableNumber(hugeNumber, 2)).toBe("1,000,000T");
+    });
+    it("formats numbers with trailing zeros correctly", () => {
+        expect(formatHumanReadableNumber(1_000, 2)).toBe("1K");
+    });
+});
+describe("roundUpNumber", () => {
+    it("rounds up to 2 decimals", () => {
+        expect(roundUpNumber(1.234)).toBe(1.24);
+    });
+    it("rounds up to 3 decimals", () => {
+        expect(roundUpNumber(9.87654, 3)).toBe(9.877);
+    });
+    it("rounds up exact decimal", () => {
+        expect(roundUpNumber(2.5, 1)).toBe(2.5);
+    });
+});
+describe("fromFixedPoint", () => {
+    it("converts fixed point with 18 decimals to float", () => {
+        const raw = 1234567890000000000n; // 1.23456789 ETH in 18 decimals
+        expect(fromFixedPoint(raw, 18, 4)).toBe(1.2345);
+    });
+    it("converts with truncation to 2 decimals", () => {
+        const raw = 987654321000000000n; // ~0.987654321 ETH
+        expect(fromFixedPoint(raw, 18, 2)).toBe(0.98);
+    });
+    it("handles large fixedPoint decimals", () => {
+        const raw = 1000000000000000000000000n; // 1M with 6 decimals
+        expect(fromFixedPoint(raw, 6, 2)).toBe(1000000000000000000);
+    });
+});
+//# sourceMappingURL=numbers.test.js.map

package/dist/src/utils/numbers.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.test.js","sourceRoot":"","sources":["../../../src/utils/numbers.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@mezo-org/passport",
-  "version": "0.4.0-dev.1",
+  "version": "0.4.0-dev.11",
   "main": "dist/src/index.js",
   "license": "GPL-3.0-only",
   "scripts": {
     "build": "tsc",
+    "dev": "tsc --watch",
     "format": "npm run lint:js && npm run lint:config",
     "format:fix": "npm run lint:js:fix && npm run lint:config:fix",
     "lint:js": "eslint .",
@@ -23,24 +24,29 @@
     "directory": "typescript/passport"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.23.7",
     "@thesis-co/eslint-config": "github:thesis/eslint-config#7b9bc8c",
     "@types/jest": "^29.5.12",
     "@types/node": "^20.11.30",
     "@types/react": "^18.2.64",
     "eslint": "^8.57.1",
     "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "prettier": "^3.2.5",
     "ts-jest": "^29.1.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.3"
   },
   "dependencies": {
-    "@mezo-org/orangekit": "1.0.0-beta.40-dev.0",
+    "@mezo-org/mezo-clay": "0.1.0-dev.18",
+    "@mezo-org/orangekit": "1.0.0-beta.40-dev.1",
+    "@mezo-org/sign-in-with-wallet": "1.0.0-beta.8"
+  },
+  "peerDependencies": {
     "@rainbow-me/rainbowkit": "2.0.2",
     "@tanstack/react-query": "^5.28.4",
-    "@mezo-org/sign-in-with-wallet": "1.0.0-beta.8",
     "react": "^18.2.0",
+    "styletron-engine-monolithic": "^1.0.0",
+    "usehooks-ts": "^3.1.1",
     "viem": "2.22.8",
     "wagmi": "2.5.12"
   }

package/src/api/auth.ts

@@ -1,152 +1,110 @@
-type RequestHandlerOptions = Omit<RequestInit, "credentials" | "body"> & {
-  body?: Record<string, unknown>
-  queryParams?: Record<string, string | undefined>
-}
-type PassportIdentityProvider = "wallet" | "discord" | "email"
+import { ApiClient } from "./client"
+import { FetchError } from "./fetch-error"
 
-type AccountPublicData = {
-  mezoId?: string
-  btcAddress: string
+type AuthProvider = "discord"
+
+export type LinkedWalletAccount = {
+  type: "wallet"
+  btcAddress?: string
   evmAddress: string
 }
 
+export type LinkedProviderAccount = {
+  type: AuthProvider
+  name: string
+  id: string
+  avatarUrl: string
+}
+
+export type LinkedAccount = LinkedWalletAccount | LinkedProviderAccount
+
 type Account = {
-  app_metadata: {
-    provider: PassportIdentityProvider
-    providers: PassportIdentityProvider[]
-  }
-  user_metadata: AccountPublicData
+  mezoId: string
+  hasModifiedMezoId: boolean
+  linkedAccounts: LinkedAccount[]
 }
 
-type Session = {
-  access_token: string
-  token_type: string
-  expires_in: number
-  expires_at: number
-  refresh_token: string
-  user: Account
+export type Session = {
+  expiresIn: number
+  expiresAt: number
+  sessionLinks: {
+    _links: {
+      account: string
+    }
+  }
 }
 
-type AuthenticationProviderRedirectResponse = {
+export type AuthenticationProviderRedirectResponse = {
   redirectTo: string
 }
 
-type WalletAccountCredentials = {
-  type: "wallet"
+type SignatureData = {
   message: string
   signature: string
 }
 
+// Request and Response types
+export type GetSessionResponse = Session | { nonce: string }
+
 export type CreateSessionRequest =
-  | WalletAccountCredentials
+  | ({ type: "wallet" } & SignatureData)
   | { type: "discord" }
+export type CreateSessionResponse =
+  | Session
+  | AuthenticationProviderRedirectResponse
 
-export type LinkAccountRequest = CreateSessionRequest
+export type DeleteSessionResponse = { message: string }
 
-export type CreateAccountRequest = WalletAccountCredentials
+export type GetCurrentAccountResponse = Partial<Account> | null
 
-export const API_ENDPOINTS_BY_ENV = {
-  mainnet: "https://api.mezo.org",
-  testnet: "https://api.test.mezo.org",
+export type GetAccountByMezoIdOrAddressResponse = {
+  mezoId?: string
+  linkedAccounts?: Extract<LinkedAccount, { type: "wallet" }>[]
 }
 
-const DEFAULT_API_ENDPOINT = API_ENDPOINTS_BY_ENV.mainnet
-
-export class AuthApiClient {
-  private apiUrl: string
-
-  constructor(apiUrl?: string) {
-    this.apiUrl = apiUrl ?? DEFAULT_API_ENDPOINT
-  }
-
-  /**
-   * The request handler for the Passport API. It accepts an API endpoint and
-   * request options.
-   * @dev Generic type `D` is a type of returned object from the function
-   * @param endpoint - The API endpoint to request. Should start with
-   * forward slash ("/")
-   * @param {RequestHandlerOptions<B>} options - The request options, the
-   * `RequestInit` type with additional type-safe properties
-   * @returns The promise of the API response
-   */
-  protected async handleRequest<D>(
-    endpoint: `/${string}`,
-    options: RequestHandlerOptions,
-  ): Promise<D> {
-    const {
-      method,
-      headers,
-      body,
-      queryParams = {},
-      ...restOptions
-    } = options || {}
-
-    // If last character in apiUrl is forward slash we are removing it
-    const authApiUrlRoute = this.apiUrl.replace(/\/$/, "")
-    const url = new URL(`${authApiUrlRoute}${endpoint}`)
-
-    // Removes falsy values (e.g. null, undefined etc.) from query params and
-    // appends remaining ones to the URL
-    Object.entries(queryParams)
-      .filter(([, value]) => value) // Remove falsy values
-      .forEach(([key, value]) => url.searchParams.append(key, value!))
-
-    try {
-      const response = await fetch(url, {
-        method,
-        credentials: "include",
-        headers: {
-          "Content-Type": "application/json",
-          ...headers,
-        },
-        body: body ? JSON.stringify(body) : undefined,
-        ...restOptions,
-      })
+export type LinkAccountRequest = CreateSessionRequest
+export type LinkAccountResponse =
+  | Account
+  | AuthenticationProviderRedirectResponse
 
-      const data = await response.json()
+export type CreateAccountRequest = { type: "wallet" } & SignatureData
+export type CreateAccountResponse = Account
 
-      if (!response.ok || data?.error) {
-        const error = data?.error || "An error occurred"
-        throw new Error(error)
-      }
+export type UpdateMezoIdResponse = Account
 
-      return data as D
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : "An error occurred"
+export const AUTH_API_ENDPOINTS_BY_ENV = {
+  mainnet: "https://api.mezo.org",
+  testnet: "https://api.test.mezo.org",
+}
 
-      throw new Error(errorMessage)
-    }
+export class AuthApiClient extends ApiClient {
+  constructor(
+    environment: keyof typeof AUTH_API_ENDPOINTS_BY_ENV = "mainnet",
+    apiUrl?: string,
+  ) {
+    super(apiUrl ?? AUTH_API_ENDPOINTS_BY_ENV[environment])
   }
 
   async getSession(code?: string) {
-    const data = await this.handleRequest<Session | { nonce: string }>(
-      "/session",
-      {
-        method: "GET",
-        queryParams: { code },
-      },
-    )
+    const data = await this.handleRequest<GetSessionResponse>("/session", {
+      method: "GET",
+      queryParams: { code },
+    })
 
     return data
   }
 
   async createSession(createSessionRequest: CreateSessionRequest) {
-    const data = await this.handleRequest<Session | { redirectTo: string }>(
-      "/session",
-      {
-        method: "POST",
-        body: createSessionRequest,
-      },
-    )
+    const data = await this.handleRequest<CreateSessionResponse>("/session", {
+      method: "POST",
+      body: createSessionRequest,
+    })
 
     return data
   }
 
   async deleteSession() {
-    const data = await this.handleRequest<{
-      message: string
-    }>("/session", {
+    const data = await this.handleRequest<DeleteSessionResponse>("/session", {
       method: "DELETE",
     })
 
@@ -154,37 +112,51 @@ export class AuthApiClient {
   }
 
   async getCurrentAccount() {
-    const data = await this.handleRequest<Account>("/session/account", {
-      method: "GET",
-    })
+    const data = await this.handleRequest<GetCurrentAccountResponse>(
+      "/session/account",
+      {
+        method: "GET",
+      },
+    )
 
     return data
   }
 
   async getAccountByMezoIdOrAddress(mezoIdOrAddress: string) {
-    const data = await this.handleRequest<AccountPublicData>(
-      `/accounts/${mezoIdOrAddress}`,
-      {
-        method: "GET",
-      },
-    )
+    let data
+    try {
+      data = await this.handleRequest<GetAccountByMezoIdOrAddressResponse>(
+        `/accounts/${mezoIdOrAddress}`,
+        {
+          method: "GET",
+        },
+      )
+    } catch (error) {
+      // Return null if account is not found instead of throwing an error
+      if (error instanceof FetchError && error.status === 404) {
+        data = null
+      } else {
+        throw error
+      }
+    }
 
     return data
   }
 
   async linkAccount(linkAccountRequest: LinkAccountRequest) {
-    const data = await this.handleRequest<
-      Account | AuthenticationProviderRedirectResponse
-    >("/session/account/linked-accounts", {
-      method: "POST",
-      body: linkAccountRequest,
-    })
+    const data = await this.handleRequest<LinkAccountResponse>(
+      "/session/account/linked-accounts",
+      {
+        method: "POST",
+        body: linkAccountRequest,
+      },
+    )
 
     return data
   }
 
   async createAccount(createAccountRequest: CreateAccountRequest) {
-    const data = await this.handleRequest<Account>("/accounts", {
+    const data = await this.handleRequest<CreateAccountResponse>("/accounts", {
       method: "POST",
       body: createAccountRequest,
     })
@@ -193,10 +165,13 @@ export class AuthApiClient {
   }
 
   async updateMezoId(newMezoId: string) {
-    const data = await this.handleRequest<Account>("/session/account", {
-      method: "PATCH",
-      body: { newMezoId },
-    })
+    const data = await this.handleRequest<UpdateMezoIdResponse>(
+      "/session/account",
+      {
+        method: "PATCH",
+        body: { mezoId: newMezoId },
+      },
+    )
 
     return data
   }

package/src/api/client.ts

@@ -0,0 +1,78 @@
+import { FetchError } from "./fetch-error"
+
+type RequestHandlerOptions = Omit<RequestInit, "credentials" | "body"> & {
+  body?: Record<string, unknown>
+  queryParams?: Record<string, string | undefined>
+}
+
+export abstract class ApiClient {
+  private apiUrl: string
+
+  constructor(apiUrl: string) {
+    this.apiUrl = apiUrl
+  }
+
+  /**
+   * The request handler for the Passport API. It accepts an API endpoint and
+   * request options.
+   * @dev Generic type `D` is a type of returned object from the function
+   * @dev WARNING: This function hardcodes `credentials: "include"`, meaning
+   * cookies and authentication headers will be sent with every request. Ensure
+   * this is safe if you plan to use it in other contexts than auth api worker.
+   * @param endpoint - The API endpoint to request. Should start with
+   * forward slash ("/")
+   * @param options - The request options, the `RequestInit` type with
+   * additional type-safe properties
+   * @returns The promise of the API response
+   */
+  protected async handleRequest<D>(
+    endpoint: `/${string}`,
+    options: RequestHandlerOptions = {},
+  ): Promise<D> {
+    try {
+      const { method, body, queryParams = {}, ...restOptions } = options
+
+      // If last character in apiUrl is forward slash we are removing it
+      const authApiUrlRoute = this.apiUrl.replace(/\/$/, "")
+      const url = new URL(`${authApiUrlRoute}${endpoint}`)
+
+      // Removes falsy values (e.g. null, undefined etc.) from query params and
+      // appends remaining ones to the URL
+      Object.entries(queryParams)
+        .filter(([, value]) => value) // Remove falsy values
+        .forEach(([key, value]) => url.searchParams.append(key, value!))
+
+      const response = await fetch(url, {
+        method,
+        credentials: "include",
+        body: body ? JSON.stringify(body) : undefined,
+        ...restOptions,
+      })
+
+      const data = await response.json()
+
+      if (!response.ok || data?.error) {
+        const error =
+          data?.error ||
+          `An error occurred when handling API request: ${JSON.stringify(data)}`
+        throw new FetchError(
+          response.status,
+          `Error [${response.status}]: ${error}`,
+        )
+      }
+
+      return data as D
+    } catch (error) {
+      if (error instanceof FetchError) {
+        throw error
+      }
+
+      const errorMessage =
+        error instanceof Error ? error.message : JSON.stringify(error)
+      throw new FetchError(
+        500,
+        `Error [500]: An error occurred when handling API request: ${errorMessage}`,
+      )
+    }
+  }
+}

package/src/api/fetch-error.ts

@@ -0,0 +1,8 @@
+export class FetchError extends Error {
+  constructor(
+    public status: number,
+    message?: string,
+  ) {
+    super(message)
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,2 @@
+export * from "./auth"
+export * from "./portal"

package/src/api/portal.ts

@@ -0,0 +1,56 @@
+import { ApiClient } from "./client"
+
+type PortalStatistics = {
+  hodlers: number
+  depositedBitcoin: string
+  tvl: number
+  currentUsdPerBtc: string
+  currentUsdPerEth: string
+  usdPerBtc24hChange: string
+}
+
+type PortalMats = {
+  address: string
+  totalMats: number
+  matsFromDeposits: number
+  matsFromReferrals: number
+  matsFromSecondaryReferrals: number
+  netMatsTransferred: number
+  dailyMats: number
+  dailyMatsFromDeposits: number
+  dailyMatsFromReferrals: number
+  dailyMatsFromSecondaryReferrals: number
+}
+
+export const PORTAL_API_ENDPOINTS_BY_ENV = {
+  mainnet: "https://api.mezo.org/api/v1",
+  testnet: "https://api.test.mezo.org/api/v1",
+}
+
+export class PortalApiClient extends ApiClient {
+  constructor(
+    environment: keyof typeof PORTAL_API_ENDPOINTS_BY_ENV = "mainnet",
+    apiUrl?: string,
+  ) {
+    super(apiUrl ?? PORTAL_API_ENDPOINTS_BY_ENV[environment])
+  }
+
+  async getPortalStatistics() {
+    const data = await this.handleRequest<PortalStatistics>("/statistics", {
+      method: "GET",
+    })
+
+    return data
+  }
+
+  async getPortalMats(address: string) {
+    const data = await this.handleRequest<PortalMats>(
+      `/accounts/${address}/mats`,
+      {
+        method: "GET",
+      },
+    )
+
+    return data
+  }
+}