@echoxyz/sonar-react 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,9 +1,20 @@
 # @echoxyz/sonar-react
 
+## 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/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@echoxyz/sonar-react",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "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.0"
   },
   "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"
   }
 }