@echoxyz/sonar-core 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @echoxyz/sonar-core
 
+## 0.1.0
+
+### Minor Changes
+
+- 41247e9: Initial implementation of core/react wrapper.
+
 ## 0.0.3
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,139 @@
+# @echoxyz/sonar-core
+
+Headless core client for interacting with Echo’s Sonar APIs. Router-agnostic, framework-agnostic.
+
+## Install
+
+```bash
+pnpm add @echoxyz/sonar-core
+```
+
+## Quick start (default settings)
+
+The default client targets Echo’s hosted API and reads the auth token from `localStorage` under the `sonar:auth-token` key.
+
+```ts
+import { createClient, buildAuthorizationUrl, generatePKCEParams, EntityType } from "@echoxyz/sonar-core";
+
+// Configure once at app startup
+const saleUUID = "<your-sale-uuid>";
+const clientUUID = "<your-oauth-client-id>";
+const redirectURI = window.location.origin + "/oauth/callback";
+
+const client = createClient({ saleUUID });
+
+// Start OAuth login (e.g. on a button click)
+export async function login() {
+    const { codeVerifier, codeChallenge, state } = await generatePKCEParams();
+
+    sessionStorage.setItem("sonar:oauth:state", state);
+    sessionStorage.setItem("sonar:oauth:verifier", codeVerifier);
+
+    const url = buildAuthorizationUrl({
+        saleUUID,
+        clientUUID,
+        redirectURI,
+        state,
+        codeChallenge,
+    });
+
+    window.location.href = url.toString();
+}
+
+// Complete OAuth on your callback route/page
+export async function completeOAuthFromCallback() {
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    const state = params.get("state");
+    if (!code || !state) {
+        throw new Error("Missing OAuth params");
+    }
+
+    const expectedState = sessionStorage.getItem("sonar:oauth:state");
+    const codeVerifier = 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,
+    });
+
+    // Persist through the client (wired to default storage)
+    client.setToken(token);
+
+    // Clean up temp params
+    sessionStorage.removeItem("sonar:oauth:state");
+    sessionStorage.removeItem("sonar:oauth:verifier");
+}
+
+// Call APIs (after token is set)
+export async function exampleCalls() {
+    // List entities available to this user for the configured sale
+    const { Entities } = await client.listAvailableEntities({ saleUUID });
+
+    // Run a pre-purchase check
+    const pre = await client.prePurchaseCheck({
+        saleUUID,
+        entityUUID: Entities[0].EntityUUID,
+        entityType: EntityType.USER, // or EntityType.ORGANIZATION
+        walletAddress: "0x1234...abcd" as `0x${string}`,
+    });
+
+    if (pre.ReadyToPurchase) {
+        // Generate a purchase permit
+        const permit = await client.generatePurchasePermit({
+            saleUUID,
+            entityUUID: Entities[0].EntityUUID,
+            entityType: EntityType.USER,
+            walletAddress: "0x1234...abcd" as `0x${string}`,
+        });
+        console.log(permit.Signature, permit.Permit);
+    }
+
+    // Fetch allocation
+    const alloc = await client.fetchAllocation({ saleUUID, walletAddress: "0x1234...abcd" as `0x${string}` });
+    console.log(alloc);
+}
+```
+
+## Customizing the client
+
+`createClient` accepts options so you can swap out pieces as needed:
+
+```ts
+import { AuthSession, buildAuthorizationUrl, createClient, createMemoryStorage } from "@echoxyz/sonar-core";
+
+const client = createClient({
+    saleUUID: "<sale-uuid>",
+    apiURL: "https://api.echo.xyz",
+    fetch: customFetchImplementation,
+    auth: new AuthSession({
+        storage: createMemoryStorage(),
+        tokenKey: "custom-token-key",
+    }),
+});
+
+// or let the factory create the session but tweak defaults
+const clientWithCallbacks = createClient({
+    saleUUID: "<sale-uuid>",
+    onTokenChange: (token) => console.log("token updated", token),
+    onExpire: () => console.log("session expired"),
+});
+
+const oauthURL = buildAuthorizationUrl({
+    saleUUID: "<sale-uuid>",
+    clientUUID: "<client-id>",
+    redirectURI: "https://example.com/oauth/callback",
+    state: "opaque-state",
+    codeChallenge: "pkce-challenge",
+    frontendURL: "https://custom.echo.xyz", // optional override
+});
+```
+
+## Notes
+
+- Tokens are not auto-refreshed. When they expire, clear `sonar:auth-token` and re-run the OAuth flow.
+- This package is headless and router-agnostic. You can integrate with any router or framework.

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@echoxyz/sonar-core",
-  "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"
     }
   },
   "devDependencies": {
@@ -29,6 +29,9 @@
     "README.md",
     "package.json"
   ],
+  "dependencies": {
+    "jose": "^6.1.0"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch",