@echoxyz/sonar-react 0.0.3 → 0.1.1

package/CHANGELOG.md

@@ -1,9 +1,28 @@
 # @echoxyz/sonar-react
 
+## 0.1.1
+
+### Patch Changes
+
+- 95d0235: Include dist in build output for publishing
+- Updated dependencies [95d0235]
+    - @echoxyz/sonar-core@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 41247e9: Initial implementation of core/react wrapper.
+
+### Patch Changes
+
+- Updated dependencies [41247e9]
+    - @echoxyz/sonar-core@0.1.0
+
 ## 0.0.3
 
 ### Patch Changes
 
 - 52ddd3f: Initial commit (empty)
 - Updated dependencies [52ddd3f]
-  - @echoxyz/sonar-core@0.0.3
+    - @echoxyz/sonar-core@0.0.3

package/README.md

@@ -0,0 +1,149 @@
+# @echoxyz/sonar-react
+
+React provider and hooks for Echo’s Sonar APIs, built on `@echoxyz/sonar-core`.
+
+- Framework/router agnostic (works with React Router, Next.js, etc.).
+- Handles PKCE OAuth redirect flow and token storage for the browser.
+- Exposes a ready-to-use API client bound to a single `saleUUID`.
+
+## Install
+
+```bash
+pnpm add @echoxyz/sonar-react @echoxyz/sonar-core
+```
+
+Peer dependency: `react@>=18`.
+
+## Quick start
+
+1. Wrap your app with `SonarProvider`:
+
+```tsx
+import { SonarProvider } from "@echoxyz/sonar-react";
+
+export function AppRoot({ children }: { children: React.ReactNode }) {
+    return (
+        <SonarProvider
+            config={{
+                saleUUID: "<your-sale-uuid>",
+                clientUUID: "<your-oauth-client-id>",
+                redirectURI: window.location.origin + "/oauth/callback",
+                // Optional:
+                // apiURL: "https://api.echo.xyz",
+                // tokenStorageKey: "sonar:auth-token",
+            }}
+        >
+            {children}
+        </SonarProvider>
+    );
+}
+```
+
+2. Trigger login with PKCE + redirect:
+
+```tsx
+import { useSonarAuth } from "@echoxyz/sonar-react";
+
+export function LoginButton() {
+    const { login, authenticated } = useSonarAuth();
+    if (authenticated()) {
+        return null;
+    }
+    return <button onClick={() => login()}>Sign in with Echo</button>;
+}
+```
+
+3. Complete OAuth on your callback route/page:
+
+```tsx
+import { useEffect } from "react";
+import { useSonarAuth } from "@echoxyz/sonar-react";
+
+export default function OAuthCallback() {
+    const { completeOAuth } = useSonarAuth();
+
+    useEffect(() => {
+        const params = new URLSearchParams(window.location.search);
+        const code = params.get("code");
+        const state = params.get("state");
+        if (!code || !state) {
+            return;
+        }
+        completeOAuth({ code, state }).catch((err) => {
+            console.error("OAuth completion failed", err);
+        });
+    }, [completeOAuth]);
+
+    return <p>Completing sign-in…</p>;
+}
+```
+
+4. Call APIs using the low-level client:
+
+```tsx
+import { useEffect } from "react";
+import { useSonarAuth, useSonarClient } from "@echoxyz/sonar-react";
+import { EntityType } from "@echoxyz/sonar-core";
+
+export function Example() {
+    const { authenticated } = useSonarAuth();
+    const client = useSonarClient();
+
+    useEffect(() => {
+        if (!authenticated()) {
+            return;
+        }
+
+        (async () => {
+            const { Entities } = await client.listAvailableEntities({ saleUUID: "<your-sale-uuid>" });
+            if (Entities.length === 0) return;
+
+            const entity = Entities[0];
+            const pre = await client.prePurchaseCheck({
+                saleUUID: "<your-sale-uuid>",
+                entityUUID: entity.EntityUUID,
+                entityType: EntityType.USER,
+                walletAddress: "0x1234...abcd" as `0x${string}`,
+            });
+
+            if (pre.ReadyToPurchase) {
+                const permit = await client.generatePurchasePermit({
+                    saleUUID: "<your-sale-uuid>",
+                    entityUUID: entity.EntityUUID,
+                    entityType: EntityType.USER,
+                    walletAddress: "0x1234...abcd" as `0x${string}`,
+                });
+                console.log(permit.Signature, permit.Permit);
+            }
+
+            const alloc = await client.fetchAllocation({
+                saleUUID: "<your-sale-uuid>",
+                walletAddress: "0x1234...abcd" as `0x${string}`,
+            });
+            console.log(alloc);
+        })();
+    }, [authenticated, client]);
+
+    return null;
+}
+```
+
+## API
+
+- `SonarProvider`
+    - Props `config`:
+        - `saleUUID: string` (required) – Sale to scope API calls against.
+        - `clientUUID: string` (required) – Echo OAuth Client ID.
+        - `redirectURI: string` (required) – Your OAuth callback URI.
+        - `apiURL?: string` (default: `https://api.echo.xyz`) – API base URL.
+        - `tokenStorageKey?: string` (default: `sonar:auth-token`) – Browser storage key for the access token.
+
+- `useSonarAuth()` → `{ authenticated, token?, login(), completeOAuth({ code, state }), logout() }`
+
+- `useSonarClient()` → low-level `SonarClient` instance.
+
+## Notes
+
+- Tokens are not auto-refreshed. On expiry, call `logout()` and re-run the OAuth flow.
+- This package doesn’t depend on a specific router. Use it in Next.js, React Router, or any custom setup.
+- Wallet addresses are typed as template literals `0x${string}`.

package/dist/index.cjs

@@ -0,0 +1,116 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  SonarProvider: () => SonarProvider,
+  useSonarAuth: () => useSonarAuth,
+  useSonarClient: () => useSonarClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/react.tsx
+var import_sonar_core = require("@echoxyz/sonar-core");
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var AuthContext = (0, import_react.createContext)(void 0);
+var ClientContext = (0, import_react.createContext)(void 0);
+function SonarProvider({ children, config }) {
+  const client = (0, import_react.useMemo)(() => {
+    return (0, import_sonar_core.createClient)({
+      saleUUID: config.saleUUID,
+      apiURL: config.apiURL,
+      tokenKey: config.tokenStorageKey
+    });
+  }, [config.apiURL, config.saleUUID, config.tokenStorageKey]);
+  const login = (0, import_react.useCallback)(async () => {
+    const { codeVerifier, codeChallenge, state } = await (0, import_sonar_core.generatePKCEParams)();
+    if (typeof window === "undefined") {
+      throw new Error("window is not available for OAuth flow");
+    }
+    window.sessionStorage.setItem("sonar:oauth:state", state);
+    window.sessionStorage.setItem("sonar:oauth:verifier", codeVerifier);
+    const url = (0, import_sonar_core.buildAuthorizationUrl)({
+      saleUUID: config.saleUUID,
+      clientUUID: config.clientUUID,
+      redirectURI: config.redirectURI,
+      state,
+      codeChallenge,
+      frontendURL: config.frontendURL
+    });
+    window.location.href = url.toString();
+  }, [config.saleUUID, config.clientUUID, config.redirectURI, config.frontendURL]);
+  const completeOAuth = (0, import_react.useCallback)(
+    async ({ code, state }) => {
+      if (typeof window === "undefined") {
+        throw new Error("window is not available for OAuth verification");
+      }
+      const expectedState = window.sessionStorage.getItem("sonar:oauth:state");
+      const codeVerifier = window.sessionStorage.getItem("sonar:oauth:verifier");
+      if (state !== expectedState || !codeVerifier) {
+        throw new Error("Invalid OAuth state or missing verifier");
+      }
+      const { token } = await client.exchangeAuthorizationCode({
+        code,
+        codeVerifier,
+        redirectURI: config.redirectURI
+      });
+      client.setToken(token);
+      window.sessionStorage.removeItem("sonar:oauth:state");
+      window.sessionStorage.removeItem("sonar:oauth:verifier");
+    },
+    [client, config.redirectURI]
+  );
+  const logout = (0, import_react.useCallback)(() => {
+    client.clear();
+  }, []);
+  const authValue = (0, import_react.useMemo)(
+    () => ({
+      login,
+      logout,
+      authenticated: () => Boolean(client.getToken()),
+      token: client.getToken() ?? void 0,
+      completeOAuth
+    }),
+    [client, login, completeOAuth, logout]
+  );
+  const clientValue = (0, import_react.useMemo)(() => ({ client }), [client]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AuthContext.Provider, { value: authValue, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ClientContext.Provider, { value: clientValue, children }) });
+}
+function useSonarAuth() {
+  const ctx = (0, import_react.useContext)(AuthContext);
+  if (!ctx) {
+    throw new Error("useSonarAuth must be used within a SonarProvider");
+  }
+  return ctx;
+}
+function useSonarClient() {
+  const ctx = (0, import_react.useContext)(ClientContext);
+  if (!ctx) {
+    throw new Error("useSonarClient must be used within a SonarProvider");
+  }
+  return ctx.client;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SonarProvider,
+  useSonarAuth,
+  useSonarClient
+});

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SonarClient } from '@echoxyz/sonar-core';
+import React from 'react';
+
+type SonarProviderProps = {
+    children: React.ReactNode;
+    config: {
+        saleUUID: string;
+        clientUUID: string;
+        redirectURI: string;
+        apiURL?: string;
+        frontendURL?: string;
+        tokenStorageKey?: string;
+    };
+};
+type AuthContextValue = {
+    authenticated: () => boolean;
+    token?: string;
+    login: () => Promise<void>;
+    completeOAuth: (args: {
+        code: string;
+        state: string;
+    }) => Promise<void>;
+    logout: () => void;
+};
+declare function SonarProvider({ children, config }: SonarProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSonarAuth(): AuthContextValue;
+declare function useSonarClient(): SonarClient;
+
+export { SonarProvider, useSonarAuth, useSonarClient };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SonarClient } from '@echoxyz/sonar-core';
+import React from 'react';
+
+type SonarProviderProps = {
+    children: React.ReactNode;
+    config: {
+        saleUUID: string;
+        clientUUID: string;
+        redirectURI: string;
+        apiURL?: string;
+        frontendURL?: string;
+        tokenStorageKey?: string;
+    };
+};
+type AuthContextValue = {
+    authenticated: () => boolean;
+    token?: string;
+    login: () => Promise<void>;
+    completeOAuth: (args: {
+        code: string;
+        state: string;
+    }) => Promise<void>;
+    logout: () => void;
+};
+declare function SonarProvider({ children, config }: SonarProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSonarAuth(): AuthContextValue;
+declare function useSonarClient(): SonarClient;
+
+export { SonarProvider, useSonarAuth, useSonarClient };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/react.tsx
+import { buildAuthorizationUrl, createClient, generatePKCEParams } from "@echoxyz/sonar-core";
+import { createContext, useCallback, useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+var AuthContext = createContext(void 0);
+var ClientContext = createContext(void 0);
+function SonarProvider({ children, config }) {
+  const client = useMemo(() => {
+    return createClient({
+      saleUUID: config.saleUUID,
+      apiURL: config.apiURL,
+      tokenKey: config.tokenStorageKey
+    });
+  }, [config.apiURL, config.saleUUID, config.tokenStorageKey]);
+  const login = useCallback(async () => {
+    const { codeVerifier, codeChallenge, state } = await generatePKCEParams();
+    if (typeof window === "undefined") {
+      throw new Error("window is not available for OAuth flow");
+    }
+    window.sessionStorage.setItem("sonar:oauth:state", state);
+    window.sessionStorage.setItem("sonar:oauth:verifier", codeVerifier);
+    const url = buildAuthorizationUrl({
+      saleUUID: config.saleUUID,
+      clientUUID: config.clientUUID,
+      redirectURI: config.redirectURI,
+      state,
+      codeChallenge,
+      frontendURL: config.frontendURL
+    });
+    window.location.href = url.toString();
+  }, [config.saleUUID, config.clientUUID, config.redirectURI, config.frontendURL]);
+  const completeOAuth = useCallback(
+    async ({ code, state }) => {
+      if (typeof window === "undefined") {
+        throw new Error("window is not available for OAuth verification");
+      }
+      const expectedState = window.sessionStorage.getItem("sonar:oauth:state");
+      const codeVerifier = window.sessionStorage.getItem("sonar:oauth:verifier");
+      if (state !== expectedState || !codeVerifier) {
+        throw new Error("Invalid OAuth state or missing verifier");
+      }
+      const { token } = await client.exchangeAuthorizationCode({
+        code,
+        codeVerifier,
+        redirectURI: config.redirectURI
+      });
+      client.setToken(token);
+      window.sessionStorage.removeItem("sonar:oauth:state");
+      window.sessionStorage.removeItem("sonar:oauth:verifier");
+    },
+    [client, config.redirectURI]
+  );
+  const logout = useCallback(() => {
+    client.clear();
+  }, []);
+  const authValue = useMemo(
+    () => ({
+      login,
+      logout,
+      authenticated: () => Boolean(client.getToken()),
+      token: client.getToken() ?? void 0,
+      completeOAuth
+    }),
+    [client, login, completeOAuth, logout]
+  );
+  const clientValue = useMemo(() => ({ client }), [client]);
+  return /* @__PURE__ */ jsx(AuthContext.Provider, { value: authValue, children: /* @__PURE__ */ jsx(ClientContext.Provider, { value: clientValue, children }) });
+}
+function useSonarAuth() {
+  const ctx = useContext(AuthContext);
+  if (!ctx) {
+    throw new Error("useSonarAuth must be used within a SonarProvider");
+  }
+  return ctx;
+}
+function useSonarClient() {
+  const ctx = useContext(ClientContext);
+  if (!ctx) {
+    throw new Error("useSonarClient must be used within a SonarProvider");
+  }
+  return ctx.client;
+}
+export {
+  SonarProvider,
+  useSonarAuth,
+  useSonarClient
+};

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@echoxyz/sonar-react",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "type": "module",
   "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "peerDependencies": {
     "react": ">=18"
   },
   "dependencies": {
-    "@echoxyz/sonar-core": "0.0.3"
+    "@echoxyz/sonar-core": "0.1.1"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^2.0.0",
+    "@types/react": "^18"
   },
   "repository": {
     "type": "git",
@@ -36,8 +37,8 @@
     "package.json"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "build": "tsup src/index.tsx --format esm,cjs --dts",
+    "dev": "tsup src/index.tsx --format esm,cjs --dts --watch",
     "test": "vitest run"
   }
 }