@echoxyz/sonar-core 0.0.3 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @echoxyz/sonar-core
 
+## 0.1.1
+
+### Patch Changes
+
+- 95d0235: Include dist in build output for publishing
+
+## 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/dist/index.cjs

@@ -0,0 +1,430 @@
+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.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  EntitySetupState: () => EntitySetupState,
+  EntityType: () => EntityType,
+  PrePurchaseFailureReason: () => PrePurchaseFailureReason,
+  PurchasePermitType: () => PurchasePermitType,
+  SaleEligibility: () => SaleEligibility,
+  SonarClient: () => SonarClient,
+  buildAuthorizationUrl: () => buildAuthorizationUrl,
+  createClient: () => createClient,
+  createMemoryStorage: () => createMemoryStorage,
+  createWebStorage: () => createWebStorage,
+  generatePKCEParams: () => generatePKCEParams
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/auth.ts
+function safeDecodeExp(token) {
+  if (typeof token !== "string") {
+    return void 0;
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return void 0;
+  }
+  try {
+    let base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const payload = JSON.parse(atob(base64));
+    const exp = payload == null ? void 0 : payload.exp;
+    if (typeof exp === "number" && isFinite(exp)) {
+      return exp * 1e3;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function decodeJwtExp(token) {
+  const ms = safeDecodeExp(token);
+  return ms ? new Date(ms) : void 0;
+}
+var AuthSession = class {
+  storage;
+  tokenKey;
+  onExpire;
+  listeners = /* @__PURE__ */ new Set();
+  expiryTimer;
+  constructor(opts) {
+    this.storage = opts.storage;
+    this.tokenKey = opts.tokenKey ?? "sonar:auth-token";
+    this.onExpire = opts.onExpire;
+    const token = this.getToken();
+    if (token) {
+      this.scheduleExpiry(token);
+    }
+  }
+  setToken(token) {
+    this.storage.setItem(this.tokenKey, token);
+    this.clearTimer();
+    this.scheduleExpiry(token);
+    this.emit(token);
+  }
+  getToken() {
+    const v = this.storage.getItem(this.tokenKey);
+    return v ?? void 0;
+  }
+  clear() {
+    this.storage.removeItem(this.tokenKey);
+    this.clearTimer();
+    this.emit(void 0);
+    if (this.onExpire) {
+      this.onExpire();
+    }
+  }
+  onTokenChange(cb) {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+  emit(token) {
+    for (const cb of this.listeners) {
+      try {
+        cb(token);
+      } catch {
+      }
+    }
+  }
+  clearTimer() {
+    if (this.expiryTimer !== void 0) {
+      clearTimeout(this.expiryTimer);
+      this.expiryTimer = void 0;
+    }
+  }
+  scheduleExpiry(token) {
+    const exp = decodeJwtExp(token);
+    if (!exp) {
+      this.clear();
+      return;
+    }
+    const delay = Math.max(0, exp.getTime() - Date.now() - 5e3);
+    if (typeof window !== "undefined") {
+      this.expiryTimer = window.setTimeout(() => this.clear(), delay);
+    }
+  }
+};
+
+// src/storage.ts
+function createMemoryStorage() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    getItem(key) {
+      return map.has(key) ? map.get(key) : null;
+    },
+    setItem(key, value) {
+      map.set(key, value);
+    },
+    removeItem(key) {
+      map.delete(key);
+    }
+  };
+}
+function createWebStorage() {
+  if (typeof window === "undefined") {
+    return createMemoryStorage();
+  }
+  const ls = window.localStorage;
+  return {
+    getItem(key) {
+      try {
+        return ls.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    setItem(key, value) {
+      try {
+        ls.setItem(key, value);
+      } catch {
+      }
+    },
+    removeItem(key) {
+      try {
+        ls.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/client.ts
+var SonarClient = class {
+  apiURL;
+  auth;
+  fetchFn;
+  onUnauthorized;
+  constructor(args) {
+    var _a, _b, _c;
+    this.apiURL = args.apiURL;
+    this.auth = ((_a = args.opts) == null ? void 0 : _a.auth) ?? new AuthSession({ storage: createWebStorage() });
+    const fetchImpl = ((_b = args.opts) == null ? void 0 : _b.fetch) ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new Error("A fetch implementation must be provided");
+    }
+    this.fetchFn = fetchImpl;
+    this.onUnauthorized = (_c = args.opts) == null ? void 0 : _c.onUnauthorized;
+  }
+  // Expose token management methods from the underlying AuthSession for convenience
+  setToken(token) {
+    this.auth.setToken(token);
+  }
+  getToken() {
+    return this.auth.getToken();
+  }
+  clear() {
+    this.auth.clear();
+  }
+  headers({ includeAuth = true } = {}) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (includeAuth) {
+      const token = this.auth.getToken();
+      if (token) {
+        headers["authorization"] = `api:Bearer ${token}`;
+      }
+    }
+    return headers;
+  }
+  async postJSON(path, body, { includeAuth = true } = {}) {
+    const resp = await this.fetchFn(new URL(path, this.apiURL), {
+      method: "POST",
+      headers: this.headers({ includeAuth }),
+      body: JSON.stringify(body)
+    });
+    return this.parseJsonResponse(resp);
+  }
+  async parseJsonResponse(resp) {
+    const bodyText = await resp.text();
+    if (resp.status === 401 && this.onUnauthorized) {
+      try {
+        this.onUnauthorized();
+      } catch {
+      }
+    }
+    if (!resp.ok) {
+      let message = `Request failed with status ${resp.status}`;
+      let code;
+      let details = bodyText || void 0;
+      if (bodyText) {
+        try {
+          const parsed = JSON.parse(bodyText);
+          details = parsed;
+          if (typeof parsed === "object" && parsed !== null) {
+            const parsedRecord = parsed;
+            const parsedMessage = parsedRecord.message ?? parsedRecord.Message ?? parsedRecord.error ?? parsedRecord.Error;
+            if (typeof parsedMessage === "string" && parsedMessage.trim()) {
+              message = parsedMessage;
+            }
+            const parsedCode = parsedRecord.code ?? parsedRecord.Code;
+            if (typeof parsedCode === "string" && parsedCode.trim()) {
+              code = parsedCode;
+            }
+          }
+        } catch {
+        }
+      }
+      throw new APIError(resp.status, message, code, details);
+    }
+    try {
+      return JSON.parse(bodyText);
+    } catch {
+      throw new APIError(
+        resp.status,
+        `Failed to parse JSON response (status ${resp.status})`,
+        void 0,
+        bodyText || void 0
+      );
+    }
+  }
+  async exchangeAuthorizationCode(args) {
+    return this.postJSON(
+      "/oauth.ExchangeAuthorizationCode",
+      {
+        Code: args.code,
+        CodeVerifier: args.codeVerifier,
+        RedirectURI: args.redirectURI
+      },
+      { includeAuth: false }
+    );
+  }
+  async prePurchaseCheck(args) {
+    return this.postJSON("/externalapi.PrePurchaseCheck", {
+      SaleUUID: args.saleUUID,
+      EntityUUID: args.entityUUID,
+      EntityType: args.entityType,
+      PurchasingWalletAddress: args.walletAddress
+    });
+  }
+  async generatePurchasePermit(args) {
+    return this.postJSON("/externalapi.GenerateSalePurchasePermit", {
+      SaleUUID: args.saleUUID,
+      EntityUUID: args.entityUUID,
+      EntityType: args.entityType,
+      PurchasingWalletAddress: args.walletAddress
+    });
+  }
+  async fetchAllocation(args) {
+    return this.postJSON("/externalapi.Allocation", {
+      SaleUUID: args.saleUUID,
+      WalletAddress: args.walletAddress
+    });
+  }
+  async listAvailableEntities(args) {
+    const data = await this.postJSON("/externalapi.ListAvailableEntities", {
+      SaleUUID: args.saleUUID
+    });
+    return data;
+  }
+};
+var APIError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(status, message, code, details) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "APIError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/oauth.ts
+var DEFAULT_FRONTEND_URL = "https://app.echo.xyz";
+function buildAuthorizationUrl({
+  saleUUID,
+  clientUUID,
+  redirectURI,
+  state,
+  codeChallenge,
+  frontendURL = DEFAULT_FRONTEND_URL
+}) {
+  const url = new URL("/oauth/authorize", frontendURL);
+  url.searchParams.set("client_id", clientUUID);
+  url.searchParams.set("redirect_uri", redirectURI);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("saleUUID", saleUUID);
+  return url;
+}
+
+// src/pkce.ts
+function base64UrlEncode(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier() {
+  const bytes = new Uint8Array(32);
+  if (typeof crypto === "undefined" || typeof crypto.getRandomValues !== "function") {
+    throw new Error("crypto.getRandomValues is not available");
+  }
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function generateCodeChallenge(codeVerifier) {
+  if (typeof crypto !== "undefined" && crypto.subtle && typeof TextEncoder !== "undefined") {
+    const data = new TextEncoder().encode(codeVerifier);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return base64UrlEncode(new Uint8Array(hash));
+  }
+  throw new Error("SubtleCrypto not available to compute code challenge");
+}
+async function generatePKCEParams() {
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = await generateCodeChallenge(codeVerifier);
+  const state = crypto.randomUUID();
+  return { codeVerifier, codeChallenge, state };
+}
+
+// src/types.ts
+var EntityType = /* @__PURE__ */ ((EntityType2) => {
+  EntityType2["USER"] = "user";
+  EntityType2["ORGANIZATION"] = "organization";
+  return EntityType2;
+})(EntityType || {});
+var EntitySetupState = /* @__PURE__ */ ((EntitySetupState2) => {
+  EntitySetupState2["NOT_STARTED"] = "not-started";
+  EntitySetupState2["IN_PROGRESS"] = "in-progress";
+  EntitySetupState2["IN_REVIEW"] = "in-review";
+  EntitySetupState2["FAILURE"] = "failure";
+  EntitySetupState2["FAILURE_FINAL"] = "failure-final";
+  EntitySetupState2["COMPLETE"] = "complete";
+  return EntitySetupState2;
+})(EntitySetupState || {});
+var SaleEligibility = /* @__PURE__ */ ((SaleEligibility2) => {
+  SaleEligibility2["ELIGIBLE"] = "eligible";
+  SaleEligibility2["NOT_ELIGIBLE"] = "not-eligible";
+  SaleEligibility2["UNKNOWN_INCOMPLETE_SETUP"] = "unknown-incomplete-setup";
+  return SaleEligibility2;
+})(SaleEligibility || {});
+var PurchasePermitType = /* @__PURE__ */ ((PurchasePermitType2) => {
+  PurchasePermitType2["BASIC"] = "basic";
+  PurchasePermitType2["ALLOCATION"] = "allocation";
+  return PurchasePermitType2;
+})(PurchasePermitType || {});
+var PrePurchaseFailureReason = /* @__PURE__ */ ((PrePurchaseFailureReason2) => {
+  PrePurchaseFailureReason2["UNKNOWN"] = "unknown";
+  PrePurchaseFailureReason2["WALLET_RISK"] = "wallet-risk";
+  PrePurchaseFailureReason2["MAX_WALLETS_USED"] = "max-wallets-used";
+  PrePurchaseFailureReason2["REQUIRES_LIVENESS"] = "requires-liveness";
+  PrePurchaseFailureReason2["NO_RESERVED_ALLOCATION"] = "no-reserved-allocation";
+  return PrePurchaseFailureReason2;
+})(PrePurchaseFailureReason || {});
+
+// src/index.ts
+var DEFAULT_API_URL = "https://api.echo.xyz";
+function createClient(options) {
+  const { saleUUID, apiURL = DEFAULT_API_URL, auth, fetch, tokenKey, onExpire, onTokenChange } = options;
+  const authSession = auth ?? new AuthSession({
+    storage: createWebStorage(),
+    tokenKey,
+    onExpire
+  });
+  if (onTokenChange) {
+    authSession.onTokenChange(onTokenChange);
+  }
+  return new SonarClient({
+    apiURL,
+    opts: { auth: authSession, fetch, onUnauthorized: () => authSession.clear() }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  EntitySetupState,
+  EntityType,
+  PrePurchaseFailureReason,
+  PurchasePermitType,
+  SaleEligibility,
+  SonarClient,
+  buildAuthorizationUrl,
+  createClient,
+  createMemoryStorage,
+  createWebStorage,
+  generatePKCEParams
+});

package/dist/index.d.cts

@@ -0,0 +1,182 @@
+interface StorageLike {
+    getItem(key: string): string | null | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare function createMemoryStorage(): StorageLike;
+declare function createWebStorage(): StorageLike;
+
+type Listener = (token?: string) => void;
+declare class AuthSession {
+    private storage;
+    private readonly tokenKey;
+    private onExpire?;
+    private listeners;
+    private expiryTimer?;
+    constructor(opts: {
+        storage: StorageLike;
+        tokenKey?: string;
+        onExpire?: () => void;
+    });
+    setToken(token: string): void;
+    getToken(): string | undefined;
+    clear(): void;
+    onTokenChange(cb: Listener): () => void;
+    private emit;
+    private clearTimer;
+    private scheduleExpiry;
+}
+
+type Hex = `0x${string}`;
+declare enum EntityType {
+    USER = "user",
+    ORGANIZATION = "organization"
+}
+declare enum EntitySetupState {
+    NOT_STARTED = "not-started",
+    IN_PROGRESS = "in-progress",
+    IN_REVIEW = "in-review",
+    FAILURE = "failure",
+    FAILURE_FINAL = "failure-final",
+    COMPLETE = "complete"
+}
+declare enum SaleEligibility {
+    ELIGIBLE = "eligible",
+    NOT_ELIGIBLE = "not-eligible",
+    UNKNOWN_INCOMPLETE_SETUP = "unknown-incomplete-setup"
+}
+type BasicPermit = {
+    EntityID: Uint8Array;
+    SaleUUID: Uint8Array;
+    Wallet: string;
+    ExpiresAt: string;
+    Payload: Uint8Array;
+};
+type AllocationPermit = {
+    Permit: BasicPermit;
+    ReservedAmount: string;
+    MaxAmount: string;
+};
+declare enum PurchasePermitType {
+    BASIC = "basic",
+    ALLOCATION = "allocation"
+}
+type PurchasePermit<T extends PurchasePermitType> = T extends PurchasePermitType.BASIC ? BasicPermit : T extends PurchasePermitType.ALLOCATION ? AllocationPermit : never;
+declare enum PrePurchaseFailureReason {
+    UNKNOWN = "unknown",
+    WALLET_RISK = "wallet-risk",
+    MAX_WALLETS_USED = "max-wallets-used",
+    REQUIRES_LIVENESS = "requires-liveness",
+    NO_RESERVED_ALLOCATION = "no-reserved-allocation"
+}
+type EntityDetails = {
+    Label: string;
+    EntityUUID: string;
+    EntityType: EntityType;
+    EntitySetupState: string;
+    SaleEligibility: string;
+    InvestingRegion: string;
+    ObfuscatedEntityID: `0x${string}`;
+};
+
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type PrePurchaseCheckResponse = {
+    ReadyToPurchase: boolean;
+    FailureReason: string;
+    LivenessCheckURL: string;
+};
+type GeneratePurchasePermitResponse = {
+    Permit: BasicPermit | AllocationPermit;
+    Signature: string;
+};
+type AllocationResponse = {
+    HasReservedAllocation: boolean;
+    ReservedAmountUSD: string;
+    MaxAmountUSD: string;
+};
+type ListAvailableEntitiesResponse = {
+    Entities: EntityDetails[];
+};
+type ClientOptions = {
+    auth?: AuthSession;
+    fetch?: FetchLike;
+    onUnauthorized?: () => void;
+};
+declare class SonarClient {
+    private readonly apiURL;
+    private readonly auth;
+    private readonly fetchFn;
+    private readonly onUnauthorized?;
+    constructor(args: {
+        apiURL: string;
+        opts?: ClientOptions;
+    });
+    setToken(token: string): void;
+    getToken(): string | undefined;
+    clear(): void;
+    private headers;
+    private postJSON;
+    private parseJsonResponse;
+    exchangeAuthorizationCode(args: {
+        code: string;
+        codeVerifier: string;
+        redirectURI: string;
+    }): Promise<{
+        token: string;
+    }>;
+    prePurchaseCheck(args: {
+        saleUUID: string;
+        entityUUID: string;
+        entityType: EntityType;
+        walletAddress: string;
+    }): Promise<PrePurchaseCheckResponse>;
+    generatePurchasePermit(args: {
+        saleUUID: string;
+        entityUUID: string;
+        entityType: EntityType;
+        walletAddress: string;
+    }): Promise<GeneratePurchasePermitResponse>;
+    fetchAllocation(args: {
+        saleUUID: string;
+        walletAddress: string;
+    }): Promise<AllocationResponse>;
+    listAvailableEntities(args: {
+        saleUUID: string;
+    }): Promise<ListAvailableEntitiesResponse>;
+}
+declare class APIError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(status: number, message: string, code?: string, details?: unknown);
+}
+
+type BuildAuthorizationUrlArgs = {
+    saleUUID: string;
+    clientUUID: string;
+    redirectURI: string;
+    state: string;
+    codeChallenge: string;
+    frontendURL?: string;
+};
+declare function buildAuthorizationUrl({ saleUUID, clientUUID, redirectURI, state, codeChallenge, frontendURL, }: BuildAuthorizationUrlArgs): URL;
+
+type PKCEParams = {
+    codeVerifier: string;
+    codeChallenge: string;
+    state: string;
+};
+declare function generatePKCEParams(): Promise<PKCEParams>;
+
+type CreateClientOptions = {
+    saleUUID: string;
+    apiURL?: string;
+    auth?: AuthSession;
+    fetch?: FetchLike;
+    tokenKey?: string;
+    onExpire?: () => void;
+    onTokenChange?: (token?: string) => void;
+};
+declare function createClient(options: CreateClientOptions): SonarClient;
+
+export { APIError, type AllocationPermit, type AllocationResponse, type BasicPermit, type BuildAuthorizationUrlArgs, type ClientOptions, type CreateClientOptions, type EntityDetails, EntitySetupState, EntityType, type FetchLike, type GeneratePurchasePermitResponse, type Hex, type ListAvailableEntitiesResponse, type PrePurchaseCheckResponse, PrePurchaseFailureReason, type PurchasePermit, PurchasePermitType, SaleEligibility, SonarClient, type StorageLike, buildAuthorizationUrl, createClient, createMemoryStorage, createWebStorage, generatePKCEParams };

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+interface StorageLike {
+    getItem(key: string): string | null | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare function createMemoryStorage(): StorageLike;
+declare function createWebStorage(): StorageLike;
+
+type Listener = (token?: string) => void;
+declare class AuthSession {
+    private storage;
+    private readonly tokenKey;
+    private onExpire?;
+    private listeners;
+    private expiryTimer?;
+    constructor(opts: {
+        storage: StorageLike;
+        tokenKey?: string;
+        onExpire?: () => void;
+    });
+    setToken(token: string): void;
+    getToken(): string | undefined;
+    clear(): void;
+    onTokenChange(cb: Listener): () => void;
+    private emit;
+    private clearTimer;
+    private scheduleExpiry;
+}
+
+type Hex = `0x${string}`;
+declare enum EntityType {
+    USER = "user",
+    ORGANIZATION = "organization"
+}
+declare enum EntitySetupState {
+    NOT_STARTED = "not-started",
+    IN_PROGRESS = "in-progress",
+    IN_REVIEW = "in-review",
+    FAILURE = "failure",
+    FAILURE_FINAL = "failure-final",
+    COMPLETE = "complete"
+}
+declare enum SaleEligibility {
+    ELIGIBLE = "eligible",
+    NOT_ELIGIBLE = "not-eligible",
+    UNKNOWN_INCOMPLETE_SETUP = "unknown-incomplete-setup"
+}
+type BasicPermit = {
+    EntityID: Uint8Array;
+    SaleUUID: Uint8Array;
+    Wallet: string;
+    ExpiresAt: string;
+    Payload: Uint8Array;
+};
+type AllocationPermit = {
+    Permit: BasicPermit;
+    ReservedAmount: string;
+    MaxAmount: string;
+};
+declare enum PurchasePermitType {
+    BASIC = "basic",
+    ALLOCATION = "allocation"
+}
+type PurchasePermit<T extends PurchasePermitType> = T extends PurchasePermitType.BASIC ? BasicPermit : T extends PurchasePermitType.ALLOCATION ? AllocationPermit : never;
+declare enum PrePurchaseFailureReason {
+    UNKNOWN = "unknown",
+    WALLET_RISK = "wallet-risk",
+    MAX_WALLETS_USED = "max-wallets-used",
+    REQUIRES_LIVENESS = "requires-liveness",
+    NO_RESERVED_ALLOCATION = "no-reserved-allocation"
+}
+type EntityDetails = {
+    Label: string;
+    EntityUUID: string;
+    EntityType: EntityType;
+    EntitySetupState: string;
+    SaleEligibility: string;
+    InvestingRegion: string;
+    ObfuscatedEntityID: `0x${string}`;
+};
+
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type PrePurchaseCheckResponse = {
+    ReadyToPurchase: boolean;
+    FailureReason: string;
+    LivenessCheckURL: string;
+};
+type GeneratePurchasePermitResponse = {
+    Permit: BasicPermit | AllocationPermit;
+    Signature: string;
+};
+type AllocationResponse = {
+    HasReservedAllocation: boolean;
+    ReservedAmountUSD: string;
+    MaxAmountUSD: string;
+};
+type ListAvailableEntitiesResponse = {
+    Entities: EntityDetails[];
+};
+type ClientOptions = {
+    auth?: AuthSession;
+    fetch?: FetchLike;
+    onUnauthorized?: () => void;
+};
+declare class SonarClient {
+    private readonly apiURL;
+    private readonly auth;
+    private readonly fetchFn;
+    private readonly onUnauthorized?;
+    constructor(args: {
+        apiURL: string;
+        opts?: ClientOptions;
+    });
+    setToken(token: string): void;
+    getToken(): string | undefined;
+    clear(): void;
+    private headers;
+    private postJSON;
+    private parseJsonResponse;
+    exchangeAuthorizationCode(args: {
+        code: string;
+        codeVerifier: string;
+        redirectURI: string;
+    }): Promise<{
+        token: string;
+    }>;
+    prePurchaseCheck(args: {
+        saleUUID: string;
+        entityUUID: string;
+        entityType: EntityType;
+        walletAddress: string;
+    }): Promise<PrePurchaseCheckResponse>;
+    generatePurchasePermit(args: {
+        saleUUID: string;
+        entityUUID: string;
+        entityType: EntityType;
+        walletAddress: string;
+    }): Promise<GeneratePurchasePermitResponse>;
+    fetchAllocation(args: {
+        saleUUID: string;
+        walletAddress: string;
+    }): Promise<AllocationResponse>;
+    listAvailableEntities(args: {
+        saleUUID: string;
+    }): Promise<ListAvailableEntitiesResponse>;
+}
+declare class APIError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(status: number, message: string, code?: string, details?: unknown);
+}
+
+type BuildAuthorizationUrlArgs = {
+    saleUUID: string;
+    clientUUID: string;
+    redirectURI: string;
+    state: string;
+    codeChallenge: string;
+    frontendURL?: string;
+};
+declare function buildAuthorizationUrl({ saleUUID, clientUUID, redirectURI, state, codeChallenge, frontendURL, }: BuildAuthorizationUrlArgs): URL;
+
+type PKCEParams = {
+    codeVerifier: string;
+    codeChallenge: string;
+    state: string;
+};
+declare function generatePKCEParams(): Promise<PKCEParams>;
+
+type CreateClientOptions = {
+    saleUUID: string;
+    apiURL?: string;
+    auth?: AuthSession;
+    fetch?: FetchLike;
+    tokenKey?: string;
+    onExpire?: () => void;
+    onTokenChange?: (token?: string) => void;
+};
+declare function createClient(options: CreateClientOptions): SonarClient;
+
+export { APIError, type AllocationPermit, type AllocationResponse, type BasicPermit, type BuildAuthorizationUrlArgs, type ClientOptions, type CreateClientOptions, type EntityDetails, EntitySetupState, EntityType, type FetchLike, type GeneratePurchasePermitResponse, type Hex, type ListAvailableEntitiesResponse, type PrePurchaseCheckResponse, PrePurchaseFailureReason, type PurchasePermit, PurchasePermitType, SaleEligibility, SonarClient, type StorageLike, buildAuthorizationUrl, createClient, createMemoryStorage, createWebStorage, generatePKCEParams };

package/dist/index.js

@@ -0,0 +1,393 @@
+// src/auth.ts
+function safeDecodeExp(token) {
+  if (typeof token !== "string") {
+    return void 0;
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return void 0;
+  }
+  try {
+    let base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const payload = JSON.parse(atob(base64));
+    const exp = payload == null ? void 0 : payload.exp;
+    if (typeof exp === "number" && isFinite(exp)) {
+      return exp * 1e3;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function decodeJwtExp(token) {
+  const ms = safeDecodeExp(token);
+  return ms ? new Date(ms) : void 0;
+}
+var AuthSession = class {
+  storage;
+  tokenKey;
+  onExpire;
+  listeners = /* @__PURE__ */ new Set();
+  expiryTimer;
+  constructor(opts) {
+    this.storage = opts.storage;
+    this.tokenKey = opts.tokenKey ?? "sonar:auth-token";
+    this.onExpire = opts.onExpire;
+    const token = this.getToken();
+    if (token) {
+      this.scheduleExpiry(token);
+    }
+  }
+  setToken(token) {
+    this.storage.setItem(this.tokenKey, token);
+    this.clearTimer();
+    this.scheduleExpiry(token);
+    this.emit(token);
+  }
+  getToken() {
+    const v = this.storage.getItem(this.tokenKey);
+    return v ?? void 0;
+  }
+  clear() {
+    this.storage.removeItem(this.tokenKey);
+    this.clearTimer();
+    this.emit(void 0);
+    if (this.onExpire) {
+      this.onExpire();
+    }
+  }
+  onTokenChange(cb) {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+  emit(token) {
+    for (const cb of this.listeners) {
+      try {
+        cb(token);
+      } catch {
+      }
+    }
+  }
+  clearTimer() {
+    if (this.expiryTimer !== void 0) {
+      clearTimeout(this.expiryTimer);
+      this.expiryTimer = void 0;
+    }
+  }
+  scheduleExpiry(token) {
+    const exp = decodeJwtExp(token);
+    if (!exp) {
+      this.clear();
+      return;
+    }
+    const delay = Math.max(0, exp.getTime() - Date.now() - 5e3);
+    if (typeof window !== "undefined") {
+      this.expiryTimer = window.setTimeout(() => this.clear(), delay);
+    }
+  }
+};
+
+// src/storage.ts
+function createMemoryStorage() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    getItem(key) {
+      return map.has(key) ? map.get(key) : null;
+    },
+    setItem(key, value) {
+      map.set(key, value);
+    },
+    removeItem(key) {
+      map.delete(key);
+    }
+  };
+}
+function createWebStorage() {
+  if (typeof window === "undefined") {
+    return createMemoryStorage();
+  }
+  const ls = window.localStorage;
+  return {
+    getItem(key) {
+      try {
+        return ls.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    setItem(key, value) {
+      try {
+        ls.setItem(key, value);
+      } catch {
+      }
+    },
+    removeItem(key) {
+      try {
+        ls.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/client.ts
+var SonarClient = class {
+  apiURL;
+  auth;
+  fetchFn;
+  onUnauthorized;
+  constructor(args) {
+    var _a, _b, _c;
+    this.apiURL = args.apiURL;
+    this.auth = ((_a = args.opts) == null ? void 0 : _a.auth) ?? new AuthSession({ storage: createWebStorage() });
+    const fetchImpl = ((_b = args.opts) == null ? void 0 : _b.fetch) ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new Error("A fetch implementation must be provided");
+    }
+    this.fetchFn = fetchImpl;
+    this.onUnauthorized = (_c = args.opts) == null ? void 0 : _c.onUnauthorized;
+  }
+  // Expose token management methods from the underlying AuthSession for convenience
+  setToken(token) {
+    this.auth.setToken(token);
+  }
+  getToken() {
+    return this.auth.getToken();
+  }
+  clear() {
+    this.auth.clear();
+  }
+  headers({ includeAuth = true } = {}) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (includeAuth) {
+      const token = this.auth.getToken();
+      if (token) {
+        headers["authorization"] = `api:Bearer ${token}`;
+      }
+    }
+    return headers;
+  }
+  async postJSON(path, body, { includeAuth = true } = {}) {
+    const resp = await this.fetchFn(new URL(path, this.apiURL), {
+      method: "POST",
+      headers: this.headers({ includeAuth }),
+      body: JSON.stringify(body)
+    });
+    return this.parseJsonResponse(resp);
+  }
+  async parseJsonResponse(resp) {
+    const bodyText = await resp.text();
+    if (resp.status === 401 && this.onUnauthorized) {
+      try {
+        this.onUnauthorized();
+      } catch {
+      }
+    }
+    if (!resp.ok) {
+      let message = `Request failed with status ${resp.status}`;
+      let code;
+      let details = bodyText || void 0;
+      if (bodyText) {
+        try {
+          const parsed = JSON.parse(bodyText);
+          details = parsed;
+          if (typeof parsed === "object" && parsed !== null) {
+            const parsedRecord = parsed;
+            const parsedMessage = parsedRecord.message ?? parsedRecord.Message ?? parsedRecord.error ?? parsedRecord.Error;
+            if (typeof parsedMessage === "string" && parsedMessage.trim()) {
+              message = parsedMessage;
+            }
+            const parsedCode = parsedRecord.code ?? parsedRecord.Code;
+            if (typeof parsedCode === "string" && parsedCode.trim()) {
+              code = parsedCode;
+            }
+          }
+        } catch {
+        }
+      }
+      throw new APIError(resp.status, message, code, details);
+    }
+    try {
+      return JSON.parse(bodyText);
+    } catch {
+      throw new APIError(
+        resp.status,
+        `Failed to parse JSON response (status ${resp.status})`,
+        void 0,
+        bodyText || void 0
+      );
+    }
+  }
+  async exchangeAuthorizationCode(args) {
+    return this.postJSON(
+      "/oauth.ExchangeAuthorizationCode",
+      {
+        Code: args.code,
+        CodeVerifier: args.codeVerifier,
+        RedirectURI: args.redirectURI
+      },
+      { includeAuth: false }
+    );
+  }
+  async prePurchaseCheck(args) {
+    return this.postJSON("/externalapi.PrePurchaseCheck", {
+      SaleUUID: args.saleUUID,
+      EntityUUID: args.entityUUID,
+      EntityType: args.entityType,
+      PurchasingWalletAddress: args.walletAddress
+    });
+  }
+  async generatePurchasePermit(args) {
+    return this.postJSON("/externalapi.GenerateSalePurchasePermit", {
+      SaleUUID: args.saleUUID,
+      EntityUUID: args.entityUUID,
+      EntityType: args.entityType,
+      PurchasingWalletAddress: args.walletAddress
+    });
+  }
+  async fetchAllocation(args) {
+    return this.postJSON("/externalapi.Allocation", {
+      SaleUUID: args.saleUUID,
+      WalletAddress: args.walletAddress
+    });
+  }
+  async listAvailableEntities(args) {
+    const data = await this.postJSON("/externalapi.ListAvailableEntities", {
+      SaleUUID: args.saleUUID
+    });
+    return data;
+  }
+};
+var APIError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(status, message, code, details) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "APIError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/oauth.ts
+var DEFAULT_FRONTEND_URL = "https://app.echo.xyz";
+function buildAuthorizationUrl({
+  saleUUID,
+  clientUUID,
+  redirectURI,
+  state,
+  codeChallenge,
+  frontendURL = DEFAULT_FRONTEND_URL
+}) {
+  const url = new URL("/oauth/authorize", frontendURL);
+  url.searchParams.set("client_id", clientUUID);
+  url.searchParams.set("redirect_uri", redirectURI);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("saleUUID", saleUUID);
+  return url;
+}
+
+// src/pkce.ts
+function base64UrlEncode(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier() {
+  const bytes = new Uint8Array(32);
+  if (typeof crypto === "undefined" || typeof crypto.getRandomValues !== "function") {
+    throw new Error("crypto.getRandomValues is not available");
+  }
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+async function generateCodeChallenge(codeVerifier) {
+  if (typeof crypto !== "undefined" && crypto.subtle && typeof TextEncoder !== "undefined") {
+    const data = new TextEncoder().encode(codeVerifier);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return base64UrlEncode(new Uint8Array(hash));
+  }
+  throw new Error("SubtleCrypto not available to compute code challenge");
+}
+async function generatePKCEParams() {
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = await generateCodeChallenge(codeVerifier);
+  const state = crypto.randomUUID();
+  return { codeVerifier, codeChallenge, state };
+}
+
+// src/types.ts
+var EntityType = /* @__PURE__ */ ((EntityType2) => {
+  EntityType2["USER"] = "user";
+  EntityType2["ORGANIZATION"] = "organization";
+  return EntityType2;
+})(EntityType || {});
+var EntitySetupState = /* @__PURE__ */ ((EntitySetupState2) => {
+  EntitySetupState2["NOT_STARTED"] = "not-started";
+  EntitySetupState2["IN_PROGRESS"] = "in-progress";
+  EntitySetupState2["IN_REVIEW"] = "in-review";
+  EntitySetupState2["FAILURE"] = "failure";
+  EntitySetupState2["FAILURE_FINAL"] = "failure-final";
+  EntitySetupState2["COMPLETE"] = "complete";
+  return EntitySetupState2;
+})(EntitySetupState || {});
+var SaleEligibility = /* @__PURE__ */ ((SaleEligibility2) => {
+  SaleEligibility2["ELIGIBLE"] = "eligible";
+  SaleEligibility2["NOT_ELIGIBLE"] = "not-eligible";
+  SaleEligibility2["UNKNOWN_INCOMPLETE_SETUP"] = "unknown-incomplete-setup";
+  return SaleEligibility2;
+})(SaleEligibility || {});
+var PurchasePermitType = /* @__PURE__ */ ((PurchasePermitType2) => {
+  PurchasePermitType2["BASIC"] = "basic";
+  PurchasePermitType2["ALLOCATION"] = "allocation";
+  return PurchasePermitType2;
+})(PurchasePermitType || {});
+var PrePurchaseFailureReason = /* @__PURE__ */ ((PrePurchaseFailureReason2) => {
+  PrePurchaseFailureReason2["UNKNOWN"] = "unknown";
+  PrePurchaseFailureReason2["WALLET_RISK"] = "wallet-risk";
+  PrePurchaseFailureReason2["MAX_WALLETS_USED"] = "max-wallets-used";
+  PrePurchaseFailureReason2["REQUIRES_LIVENESS"] = "requires-liveness";
+  PrePurchaseFailureReason2["NO_RESERVED_ALLOCATION"] = "no-reserved-allocation";
+  return PrePurchaseFailureReason2;
+})(PrePurchaseFailureReason || {});
+
+// src/index.ts
+var DEFAULT_API_URL = "https://api.echo.xyz";
+function createClient(options) {
+  const { saleUUID, apiURL = DEFAULT_API_URL, auth, fetch, tokenKey, onExpire, onTokenChange } = options;
+  const authSession = auth ?? new AuthSession({
+    storage: createWebStorage(),
+    tokenKey,
+    onExpire
+  });
+  if (onTokenChange) {
+    authSession.onTokenChange(onTokenChange);
+  }
+  return new SonarClient({
+    apiURL,
+    opts: { auth: authSession, fetch, onUnauthorized: () => authSession.clear() }
+  });
+}
+export {
+  APIError,
+  EntitySetupState,
+  EntityType,
+  PrePurchaseFailureReason,
+  PurchasePermitType,
+  SaleEligibility,
+  SonarClient,
+  buildAuthorizationUrl,
+  createClient,
+  createMemoryStorage,
+  createWebStorage,
+  generatePKCEParams
+};

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@echoxyz/sonar-core",
-  "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"
     }
   },
   "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",