@trustware/sdk-staging 1.0.17-staging.14 → 1.0.17-staging.17

package/README.md

@@ -1,8 +1,16 @@
 # Trustware SDK
 
-The Trustware SDK provides a React provider, prebuilt UI widget, and typed core API for bridging and top-up routes. It powers seamless fund transfers across chains, reusing resolved configurations for quoting, route selection, and transaction execution. Whether you embed the widget for a quick integration or use the imperative core for custom UIs, the SDK handles wallet detection, approvals, submission, and asset settlement under the hood.
+Trustware SDK gives you three integration styles on top of the same routing and wallet infrastructure:
 
-This guide covers installation, configuration, integration patterns (widget-based and headless), and advanced usage.
+- a prebuilt React widget for the full deposit flow
+- a provider + host wallet bridge for apps that already manage wallet state
+- a headless core API for custom UIs
+
+The current widget flow is:
+
+`Home -> Select Token -> Confirm Deposit -> Processing -> Success/Error`
+
+The refactored widget keeps the same behavior, but the configuration surface is now documented around the actual `TrustwareConfigOptions` shape and the current widget step model.
 
 ## Installation
 
@@ -12,79 +20,117 @@ npm install @trustware/sdk
 pnpm add @trustware/sdk
 ```
 
-The package exposes ESM modules and ships full TypeScript types.
-
-## Core Concepts
+## Main Exports
 
-- **`TrustwareProvider`** – Wraps your app to provide configuration (API key, routes, theme) via React context, making it available to the widget and core API.
-- **`TrustwareWidget`** – A prebuilt React component that renders a UI for quoting, wallet selection, top-up submission, and asset settlement.
-- **`Trustware core`** – An imperative singleton with helpers like `Trustware.runTopUp`, `Trustware.buildRoute`, and wallet utilities. Import once the provider is mounted.
-- **Config** – `TrustwareConfigOptions` defines your API key, default routes (e.g., toChain, toToken), slippage, theme, messages, and wallet detection behavior.
+- `TrustwareProvider`
+- `TrustwareWidget`
+- `Trustware`
+- `useTrustware`
 
-## Configuration
+## Quick Start
 
-Create a config object at the root of your app. It merges defaults for routes, slippage, and fallbacks (e.g., `toAddress` defaults to `fromAddress` if unset). By default the widget will route funds to original address that initiated the transaction, if that address can support the new funds.
+```tsx
+import {
+  TrustwareProvider,
+  TrustwareWidget,
+  type TrustwareConfigOptions,
+} from "@trustware/sdk";
 
-```ts
 const trustwareConfig = {
   apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
   routes: {
-    toChain: "8453", // Base chain ID
-    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // Native ETH on Base
+    toChain: "8453",
+    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
     defaultSlippage: 1,
-    // Optional defaults:
-    // fromAddress: "0x...", // User's wallet address
-    // toAddress: "0x...", // Destination; can be set later via Trustware.setDestinationAddress
     options: {
-      // fixedFromAmount: "5.00", // USD amount (locks input)
-      // minAmountOut: "1.00", // USD minimum
-      // maxAmountOut: "100.00", // USD maximum
-      // routeRefreshMs: 15000, // auto-refresh route quotes
+      routeRefreshMs: 15000,
     },
   },
-  autoDetectProvider: true, // Enable EIP-6963/EIP-1193 wallet discovery
-  theme: {
-    primaryColor: "#FCB514",
-    secondaryColor: "#FFFFFF",
-    backgroundColor: "#000000",
-    borderColor: "#FCB514",
-    textColor: "#FFFFFF",
-    radius: 16,
-  },
+  autoDetectProvider: true,
   messages: {
-    title: "Top up BasePass",
-    description: "Bridge and add funds directly to your BasePass wallet.",
-  },
-  onError: (error) => {
-    console.error("Trustware error:", error);
-  },
-  onSuccess: (tx) => {
-    console.log("Trustware success:", tx);
-  },
-  onEvent: (event) => {
-    // Optional: listen to all SDK events
-    console.log("Trustware event:", event);
+    title: "Deposit",
+    description: "Move funds into the destination asset and chain.",
   },
 } satisfies TrustwareConfigOptions;
+
+export function App() {
+  return (
+    <TrustwareProvider config={trustwareConfig}>
+      <TrustwareWidget />
+    </TrustwareProvider>
+  );
+}
 ```
 
-Retrieve the resolved config anytime via `Trustware.getConfig()` (after provider mount).
+## Config Reference
+
+`TrustwareConfigOptions` is the single source of truth. The current supported shape is:
 
 ```ts
-const cfg = Trustware.getConfig();
-console.log(cfg.routes.toChain); // "8453"
+type TrustwareConfigOptions = {
+  apiKey: string;
+  routes: {
+    toChain: string;
+    toToken: string;
+    fromToken?: string;
+    fromAddress?: string;
+    toAddress?: string;
+    defaultSlippage?: number;
+    routeType?: string;
+    options?: {
+      routeRefreshMs?: number;
+      fixedFromAmount?: string | number;
+      minAmountOut?: string | number;
+      maxAmountOut?: string | number;
+    };
+  };
+  autoDetectProvider?: boolean;
+  theme?: TrustwareWidgetTheme;
+  messages?: Partial<TrustwareWidgetMessages>;
+  retry?: RetryConfig;
+  walletConnect?: WalletConnectConfig;
+  onError?: (error: TrustwareError) => void;
+  onSuccess?: (transaction: Transaction) => void;
+  onEvent?: (event: TrustwareEvent) => void;
+};
 ```
 
-## Integration Modes
+### Route Fields
+
+- `routes.toChain`: destination chain key or chain id string.
+- `routes.toToken`: destination token address or registry token identifier.
+- `routes.fromToken`: optional source token preference.
+- `routes.fromAddress`: optional source wallet override.
+- `routes.toAddress`: optional destination address override.
+- `routes.defaultSlippage`: optional slippage percentage. Defaults to `1`.
+- `routes.routeType`: optional route flavor. Defaults to `"swap"`.
+
+### Route Options
+
+- `routes.options.routeRefreshMs`: auto-refresh cadence for route previews.
+- `routes.options.fixedFromAmount`: locks the widget amount input to a fixed USD amount.
+- `routes.options.minAmountOut`: minimum allowed USD amount.
+- `routes.options.maxAmountOut`: maximum allowed USD amount.
+
+### Other Config Groups
+
+- `autoDetectProvider`: enables Trustware-managed wallet discovery.
+- `theme`: widget color and radius customization.
+- `messages`: top-level copy overrides.
+- `retry`: API retry and rate-limit behavior.
+- `walletConnect`: WalletConnect overrides.
+- `onError`, `onSuccess`, `onEvent`: lifecycle callbacks.
 
-### 1. Widget with Trustware-managed Wallet Detection
+## Widget Usage Patterns
 
-Ideal for apps without existing wallet connections. The SDK auto-discovers wallets (if `autoDetectProvider: true`) and prompts during the flow.
+### 1. Drop-In Widget With Trustware-Managed Wallet Detection
+
+Use this when your app does not already manage a connected wallet.
 
 ```tsx
 import { TrustwareProvider, TrustwareWidget } from "@trustware/sdk";
 
-export function App() {
+export function DepositPanel() {
   return (
     <TrustwareProvider config={trustwareConfig}>
       <TrustwareWidget />
@@ -93,272 +139,175 @@ export function App() {
 }
 ```
 
-- No external wallet libs (e.g., Wagmi) needed.
-- Call `Trustware.setDestinationAddress(address)` dynamically if the `toAddress` is determined at runtime (e.g., after smart wallet generation).
+Use this mode when:
 
-### 2. Widget or Headless with Host-managed Wallet
+- you want the built-in wallet selection flow
+- you want the full hosted deposit UX
+- `autoDetectProvider` should stay enabled
 
-Reuse your app's wallet (e.g., via Wagmi/RainbowKit). Adapt clients to the `WalletInterfaceAPI` and inject via prop or `Trustware.useWallet`.
+### 2. Widget With a Host-Managed Wallet
+
+Use this when your app already controls wallet connection through Wagmi, Viem, or another adapter.
 
 ```tsx
-import { useEffect, useMemo } from "react";
+import { useMemo } from "react";
 import { useWalletClient } from "wagmi";
-import { TrustwareProvider, TrustwareWidget, Trustware } from "@trustware/sdk";
-import { useWagmi } from "@trustware/sdk/wallet"; // Adapter helper
+import { TrustwareProvider, TrustwareWidget } from "@trustware/sdk";
+import { useWagmi } from "@trustware/sdk/wallet";
 
-export function App() {
-  const { data: wagmiClient } = useWalletClient();
+export function DepositPanel() {
+  const { data: walletClient } = useWalletClient();
   const wallet = useMemo(
-    () => (wagmiClient ? useWagmi(wagmiClient) : undefined),
-    [wagmiClient],
+    () => (walletClient ? useWagmi(walletClient) : undefined),
+    [walletClient]
   );
 
-  useEffect(() => {
-    if (!wallet) return;
-    Trustware.setDestinationAddress("0xDestination...");
-  }, [wallet]);
-
   return (
     <TrustwareProvider
       config={trustwareConfig}
       wallet={wallet}
-      autoDetect={false} // Skip detection; use injected wallet
+      autoDetect={false}
     >
-      <TrustwareWidget /> {/* Or omit for headless */}
+      <TrustwareWidget />
     </TrustwareProvider>
   );
 }
 ```
 
-- Adapters: `useWagmi(client)` for Viem/Wagmi, `useEIP1193(provider)` for raw EIP-1193.
-- Attach imperatively post-mount: `Trustware.useWallet(wallet)`.
-- Bridge example for Wagmi:
-
-```ts
-import { useEffect } from "react";
-import { useWalletClient } from "wagmi";
-import { useWagmi } from "@trustware/sdk/wallet";
-import { Trustware } from "@trustware/sdk";
-
-export function useTrustwareWalletBridge() {
-  const { data } = useWalletClient();
-
-  useEffect(() => {
-    if (!data) return;
-    const wallet = useWagmi(data);
-    Trustware.useWallet(wallet);
-  }, [data]);
-}
-```
+Use this mode when:
 
-## Using the Widget
+- your app already owns wallet state
+- you do not want the SDK to pick another provider
+- you want the widget UX but not the widget’s wallet discovery responsibilities
 
-The `<TrustwareWidget />` handles the full flow: quoting, wallet prompts, approvals, submission, and final asset settlement. It mirrors the core's lifecycle and uses the provider's config/wallet, without disrupting user flows in your application.
+### 3. Controlled Widget Shell
 
-- Customize via `theme` and `messages` in config.
-- For dynamic `toAddress`: Call `Trustware.setDestinationAddress` before render.
+`TrustwareWidget` also supports basic shell control through props and a ref.
 
-## Imperative API (Headless / Without Widget)
+```tsx
+import { useRef } from "react";
+import {
+  TrustwareProvider,
+  TrustwareWidget,
+  type TrustwareWidgetRef,
+} from "@trustware/sdk";
 
-Import the core after mounting `TrustwareProvider`:
+export function ControlledWidget() {
+  const widgetRef = useRef<TrustwareWidgetRef>(null);
 
-```ts
-import { Trustware } from "@trustware/sdk";
+  return (
+    <TrustwareProvider config={trustwareConfig}>
+      <button onClick={() => widgetRef.current?.open()}>Open</button>
+      <TrustwareWidget
+        ref={widgetRef}
+        defaultOpen={false}
+        initialStep="home"
+        showThemeToggle={false}
+        onOpen={() => console.log("opened")}
+        onClose={() => console.log("closed")}
+      />
+    </TrustwareProvider>
+  );
+}
 ```
 
-Build custom UIs with these helpers, reusing the provider's config and wallet.
-
-### Wallet Detection and Management
+Current widget props:
 
-- `Trustware.autoDetect()` – Starts provider discovery (if enabled); returns unsubscribe.
-- `Trustware.useWallet(wallet)` – Inject a connected wallet.
-- `Trustware.getWallet()` / `Trustware.getAddress()` – Get active wallet/address.
+- `theme?: "light" | "dark" | "system"`
+- `initialStep?: "home" | "select-token" | "crypto-pay" | "processing" | "success" | "error"`
+- `defaultOpen?: boolean`
+- `onOpen?: () => void`
+- `onClose?: () => void`
+- `showThemeToggle?: boolean`
 
-### Building and Quoting Routes
+### 4. Headless Core API
 
-Create routes and fetch quotes before user interaction.
+Use this when you want Trustware’s routing and wallet plumbing without the widget UI.
 
 ```ts
-const cfg = Trustware.getConfig();
-const fromAddress = await Trustware.getAddress();
+import { Trustware } from "@trustware/sdk";
 
 const route = await Trustware.buildRoute({
-  amount: "0.1", // In fromToken currency (e.g., ETH)
-  fromAddress,
-  toAddress: cfg.routes.toAddress ?? fromAddress, // Fallbacks applied
+  amount: "0.1",
+  fromAddress: await Trustware.getAddress(),
 });
 
 const quote = await Trustware.getQuote(route);
-console.log(quote.expectedAmountOut);
-```
-
-- `amount`: Denominated in `fromToken` (defaults to native).
-- Fallbacks: `fromAddress` → connected wallet; `toAddress` → config → `fromAddress`.
-
-### Running a Top-up
 
-Orchestrates quoting, approvals, and submission. Wrap with your UI (e.g., loading states).
-
-```ts
-try {
-  const result = await Trustware.runTopUp({
-    amount: "0.25",
-    fromAddress: await Trustware.getAddress(),
-    toAddress: "0xDestination...", // Optional; uses config fallbacks
-  });
-
-  console.log("Top-up confirmed", result.txHash);
-} catch (err) {
-  console.error("Top-up failed", err);
-}
+const result = await Trustware.runTopUp({
+  amount: "0.1",
+  fromAddress: await Trustware.getAddress(),
+});
 ```
 
-Returns: `{ txHash, receipt?, approvals? }`.
-
-### Lifecycle Events
+## Common Config Examples
 
-Listen for updates mirroring the widget:
+### Fixed Amount Deposit
 
 ```ts
-const unsub = Trustware.on("status", (status) => {
-  console.log("Status:", status); // e.g., "idle", "quoting", "submitting"
-});
-
-// Later:
-unsub();
+const fixedAmountConfig = {
+  ...trustwareConfig,
+  routes: {
+    ...trustwareConfig.routes,
+    options: {
+      fixedFromAmount: "25",
+    },
+  },
+} satisfies TrustwareConfigOptions;
 ```
 
-Events:
-- `status`: High-level updates.
-- `quote`: Latest quote.
-- `error`: Thrown errors (e.g., approval/bridge failures).
-
-## Additional Utilities
-
-- `Trustware.setDestinationAddress(address)`: Updates runtime `toAddress`.
-- `Trustware.getConfig()`: Resolved config.
-- Hooks: `useTrustware()`, `useTrustwareRoute()` for advanced React flows.
-- Explore `src/core` for types on balances, tokens, chain metadata.
-
-## Error Handling Tips
-
-- Surface actionable errors from `runTopUp` or `error` events (e.g., network/approval issues).
-- Add retry logic for transients.
-- Guard calls: Ensure provider mounted and wallet connected.
-
-## Rate Limiting
-
-The SDK automatically handles API rate limits with retry logic. The backend enforces per-API-key limits and returns standard rate limit headers.
-
-### Default Behavior
-
-Rate limiting is **enabled by default**. When a 429 (Too Many Requests) response is received:
-1. The SDK waits for the time specified in the `Retry-After` header
-2. Automatically retries the request (up to 3 times by default)
-3. Uses exponential backoff if `Retry-After` is not provided
-
-### Configuration
-
-Customize rate limit handling in your config:
+### Min / Max Guardrails
 
 ```ts
-const config = {
-  apiKey: "...",
-  routes: { toChain: "8453", toToken: "0x..." },
-  retry: {
-    autoRetry: true,         // Enable/disable auto-retry on 429 (default: true)
-                             // Note: This does NOT disable backend rate limits,
-                             // only client-side retry behavior
-    maxRetries: 3,           // Max retry attempts (default: 3)
-    baseDelayMs: 1000,       // Base delay for exponential backoff (default: 1000)
-    approachingThreshold: 5, // Trigger warning when remaining < threshold (default: 5)
-
-    // Callbacks for monitoring
-    onRateLimitInfo: (info) => {
-      console.log(`${info.remaining}/${info.limit} requests remaining`);
-    },
-    onRateLimited: (info, retryCount) => {
-      console.warn(`Rate limited! Retry ${retryCount}, waiting ${info.retryAfter}s`);
-    },
-    onRateLimitApproaching: (info, threshold) => {
-      console.warn(`Approaching limit: ${info.remaining} remaining`);
+const guardedConfig = {
+  ...trustwareConfig,
+  routes: {
+    ...trustwareConfig.routes,
+    options: {
+      minAmountOut: "10",
+      maxAmountOut: "250",
+      routeRefreshMs: 10000,
     },
   },
-};
+} satisfies TrustwareConfigOptions;
 ```
 
-### Rate Limit Info
-
-The `RateLimitInfo` object contains:
+### Runtime Destination Address
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `limit` | number | Maximum requests allowed in the window |
-| `remaining` | number | Requests remaining in current window |
-| `reset` | number | Unix timestamp when window resets |
-| `retryAfter` | number? | Seconds to wait (only on 429) |
+```ts
+import { Trustware } from "@trustware/sdk";
 
-### Handling RateLimitError
+Trustware.setDestinationAddress("0xDestination...");
+```
 
-If retries are exhausted, a `RateLimitError` is thrown:
+## Headless / Core Notes
 
-```ts
-import { Trustware, RateLimitError } from "@trustware/sdk";
-
-try {
-  await Trustware.buildRoute({ ... });
-} catch (err) {
-  if (err instanceof RateLimitError) {
-    console.error(`Rate limited: ${err.message}`);
-    console.log(`Try again in ${err.rateLimitInfo.retryAfter}s`);
-  }
-}
-```
+- `Trustware.getConfig()` returns the resolved config.
+- `Trustware.getWallet()` and `Trustware.getAddress()` expose the active wallet.
+- `Trustware.useWallet(wallet)` attaches a wallet imperatively.
+- `Trustware.autoDetect()` can still be used if you want SDK-managed discovery outside the widget.
 
-### Disabling Auto-Retry
+## Rate Limiting
 
-To handle rate limits manually (disable client-side retry):
+Client retry behavior is configured through `retry`.
 
 ```ts
 const config = {
-  // ...
+  ...trustwareConfig,
   retry: {
-    autoRetry: false, // Disable auto-retry; 429s will throw immediately
-                      // Note: Backend rate limits still apply
+    autoRetry: true,
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    approachingThreshold: 5,
   },
-};
+} satisfies TrustwareConfigOptions;
 ```
 
-## Bundle Size
-
-The SDK is optimized for minimal bundle impact:
-
-| Bundle | Gzipped Size |
-|--------|--------------|
-| Full SDK (ESM) | ~49 KB |
-| CSS Styles | ~5 KB |
-| **Total** | **~54 KB** |
-
-*Sizes exclude React peer dependency*
-
-Key optimizations:
-- Tree-shaking enabled via ES modules
-- ConfettiEffect lazy-loaded (only imported on success page)
-- Minimal Radix UI usage (only react-dialog)
-- CSS scoped with `tw-` prefix to avoid conflicts
-
-Run `npm run size` to check current bundle sizes.
-
-## Troubleshooting
-
-- Mount `TrustwareProvider` once at app root.
-- For host wallets: Inject only after connection.
-- SSR/Next.js: Use `"use client";` for SDK-touching components.
-- No wallet? Enable `autoDetectProvider` or inject manually.
+If retries are exhausted, the SDK throws `RateLimitError`.
 
-## Further Reading
+## Docs
 
-- TypeScript defs in `src/core` for full API.
-- Source: Explore `sdk/src` for implementation details.
+- [Integration Guide](docs/intergrationGuide.md)
 - [Core Guide](docs/coreGuide.md)
-- [Integrations](docs/integrationGuide.md)
+- [Widget Architecture Boundaries](docs/widget-architecture-boundaries.md)
+- [Widget Refactor Baseline](docs/widget-refactor-baseline.md)

package/dist/constants.cjs

@@ -29,7 +29,7 @@ __export(constants_exports, {
 });
 module.exports = __toCommonJS(constants_exports);
 var SDK_NAME = "@trustware/sdk";
-var SDK_VERSION = "1.0.17-staging.14";
+var SDK_VERSION = "1.0.17-staging.17";
 var API_ROOT = "https://bv-staging-api.trustware.io";
 var API_PREFIX = "/api";
 var ASSETS_BASE_URL = "https://app.trustware.io";

package/dist/constants.mjs

@@ -1,6 +1,6 @@
 // src/constants.ts
 var SDK_NAME = "@trustware/sdk";
-var SDK_VERSION = "1.0.17-staging.14";
+var SDK_VERSION = "1.0.17-staging.17";
 var API_ROOT = "https://bv-staging-api.trustware.io";
 var API_PREFIX = "/api";
 var ASSETS_BASE_URL = "https://app.trustware.io";