@aori/mega-swap-widget 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aori
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,404 @@
+# @aori/mega-swap-widget
+
+Embeddable cross-chain swap widget powered by [Aori](https://aori.io).
+
+## Install
+
+```bash
+npm install @aori/mega-swap-widget
+# or
+yarn add @aori/mega-swap-widget
+# or
+bun add @aori/mega-swap-widget
+```
+
+## Peer Dependencies
+
+| Package                         | Version  | Required |
+| ------------------------------- | -------- | -------- |
+| `wagmi`                         | ^2       | Yes      |
+| `@wagmi/core`                   | ^2       | Yes      |
+| `viem`                          | ^2       | Yes      |
+| `@tanstack/react-query`         | ≥5       | Yes      |
+| `zustand`                       | ^4 / ^5  | Yes      |
+| `abitype`                       | ≥1       | Optional |
+
+## Quick Start
+
+### 1. Configure the widget
+
+```ts
+import type { AoriSwapWidgetConfig } from '@aori/mega-swap-widget';
+
+const config: AoriSwapWidgetConfig = {
+  vtApiBaseUrl: '/api/vt',
+  walletConnectProjectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
+  rpcOverrides: {
+    1: '/api/rpc/1',
+    10: '/api/rpc/10',
+    8453: '/api/rpc/8453',
+    42161: '/api/rpc/42161',
+    // ...
+  },
+  theme: {
+    mode: 'dark',
+    dark: { /* color overrides */ },
+    light: { /* color overrides */ },
+  },
+  // All token/chain fields are optional — omit to allow all supported tokens and chains.
+  tokens: {
+    defaultBase: { chainId: 1, address: '0x...' },
+    defaultQuote: { chainId: 4326, address: '0x...' },
+    supportedInputTokens: [
+      { chainId: 1, address: '0x...' },
+      // ...
+    ],
+    supportedOutputTokens: [
+      { chainId: 4326, address: '0x...' },
+      // ...
+    ],
+    supportedInputChains: [1, 10, 8453, 42161],
+    supportedOutputChains: [4326],
+    enabledChains: [1, 10, 56, 143, 4326, 8453, 42161],
+    lockBase: false,
+    lockQuote: false,
+    disableInverting: true,
+  },
+  appearance: {
+    widgetType: 'default',
+    tokenDisplay: 'default',
+    fillContainer: false,
+    hideBorder: true,
+    walletButtonEnabled: false,
+  },
+  settings: {
+    defaultSlippage: 0.01,
+  },
+};
+```
+
+### 2. Render
+
+```tsx
+import { SwapWidget } from '@aori/mega-swap-widget';
+import { ConnectButton, useConnectModal, useAccountModal } from '@rainbow-me/rainbowkit';
+
+export default function App() {
+  const { openConnectModal } = useConnectModal();
+  const { openAccountModal } = useAccountModal();
+
+  return (
+    <div>
+      <ConnectButton />
+      <SwapWidget
+        config={config}
+        customWalletUI="provider"
+        onRequestConnect={() => openConnectModal?.()}
+        onRequestAccount={() => openAccountModal?.()}
+      />
+    </div>
+  );
+}
+```
+
+## Wallet Connection
+
+The widget expects your app to provide the wallet context (wagmi, RainbowKit, AppKit, etc.). A typical integration uses `customWalletUI="provider"` with `onRequestConnect` and `onRequestAccount` to wire the widget's connect/account buttons into your existing wallet modals — this is the recommended approach for most integrators.
+
+### Provider (recommended)
+
+Wrap the widget inside your existing wallet provider. Pass `onRequestConnect` and `onRequestAccount` so the widget's built-in buttons open your modals. The widget inherits the wagmi context automatically.
+
+```tsx
+import { useConnectModal, useAccountModal } from '@rainbow-me/rainbowkit';
+
+function SwapPage() {
+  const { openConnectModal } = useConnectModal();
+  const { openAccountModal } = useAccountModal();
+
+  return (
+    <SwapWidget
+      config={config}
+      customWalletUI="provider"
+      onRequestConnect={() => openConnectModal?.()}
+      onRequestAccount={() => openAccountModal?.()}
+    />
+  );
+}
+```
+
+This works the same way with AppKit or any other wagmi-compatible wallet kit — just swap the modal hooks.
+
+
+
+## Chain & RPC Configuration
+
+Your wagmi config **must include all Aori-supported chains** or approvals, wrapping/unwrapping, and chain switching will fail silently.
+
+Import `wagmiChains` and `buildTransports` from the widget package — these provide every supported chain with built-in RPC fallback (multiple public RPCs per chain, tried in order on error or rate-limit).
+
+```ts
+import { wagmiChains, buildTransports } from '@aori/mega-swap-widget';
+import { getDefaultConfig } from '@rainbow-me/rainbowkit';
+import { aoriConfig } from './aori.config';
+
+const wagmiConfig = getDefaultConfig({
+  appName: 'My App',
+  projectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
+  chains: wagmiChains,
+  transports: buildTransports(aoriConfig.rpcOverrides),
+  ssr: false,
+});
+```
+
+There are two separate RPC paths in the widget:
+
+| Path | Source | Used for |
+| --- | --- | --- |
+| **Widget internal** | `rpcOverrides` in `AoriSwapWidgetConfig` | Balance fetching, quote pricing |
+| **Wagmi** | `buildTransports()` in your wagmi config | Signing, sending txs, chain switching |
+
+`rpcOverrides` in your `aori.config` only affects the widget's internal viem clients. Wagmi transports are configured separately via `buildTransports()` — any URLs passed there are **client-side JavaScript** and will be visible in the browser. Never pass private RPC URLs directly to `buildTransports`.
+
+To keep private RPCs server-side for both paths, use the same relative proxy paths (e.g. `/api/rpc/1`) in your `rpcOverrides` and pass them to `buildTransports` as shown above. The browser hits your API route, which forwards to the real RPC with credentials from environment variables. See [Server-Side Proxying](#server-side-proxying) for how to set up the proxy routes.
+
+## Server-Side Proxying
+
+In production you almost certainly want to keep your API key **and** private RPC URLs off the client. The widget supports this via two config fields: `vtApiBaseUrl` and `rpcOverrides`. Both accept relative paths that hit your own backend routes, which then forward requests upstream with the real credentials attached.
+
+### API Key Proxy (`vtApiBaseUrl`)
+
+Instead of passing `apiKey` in the client config, point `vtApiBaseUrl` at your own API route. The widget will send all transfer/quote requests there instead of directly to the Aori API.
+
+**Widget config:**
+
+```ts
+const config: AoriSwapWidgetConfig = {
+  vtApiBaseUrl: '/api/vt',
+  // no apiKey needed — the server injects it
+  // ...
+};
+```
+
+**Next.js API route** (`pages/api/vt/[...path].ts`):
+
+```ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+const VT_UPSTREAM = 'https://transfer.layerzero-api.com/v1';
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const { path } = req.query;
+  const segments = Array.isArray(path) ? path.join('/') : path ?? '';
+  const queryString = new URL(req.url!, `http://${req.headers.host}`).search;
+  const upstreamUrl = `${VT_UPSTREAM}/${segments}${queryString}`;
+
+  const apiKey = process.env.VT_API_KEY;
+  if (!apiKey) {
+    return res.status(500).json({ error: 'VT_API_KEY not configured' });
+  }
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'x-api-key': apiKey,
+  };
+
+  const upstream = await fetch(upstreamUrl, {
+    method: req.method,
+    headers,
+    body: req.method !== 'GET' && req.method !== 'HEAD' ? JSON.stringify(req.body) : undefined,
+  });
+
+  const contentType = upstream.headers.get('content-type') ?? 'application/json';
+  res.setHeader('Content-Type', contentType);
+  res.status(upstream.status);
+
+  const body = await upstream.text();
+  res.send(body);
+}
+```
+
+Then set `VT_API_KEY` in your `.env` (or hosting provider's environment variables):
+
+```
+VT_API_KEY=your_aori_api_key
+```
+
+### Private RPC Proxy (`rpcOverrides`)
+
+The same pattern works for RPC endpoints. Point each chain's override at a local route that forwards JSON-RPC requests to your private RPC, keeping the URL and any auth tokens server-side.
+
+**Widget config:**
+
+```ts
+const config: AoriSwapWidgetConfig = {
+  vtApiBaseUrl: '/api/vt',
+  rpcOverrides: {
+    1: '/api/rpc/1',
+    10: '/api/rpc/10',
+    56: '/api/rpc/56',
+    8453: '/api/rpc/8453',
+    42161: '/api/rpc/42161',
+    143: '/api/rpc/143',
+    4326: '/api/rpc/4326',
+  },
+  // ...
+};
+```
+
+**Next.js API route** (`pages/api/rpc/[chainId].ts`):
+
+```ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+const RPC_URLS: Record<string, string | undefined> = {
+  '1': process.env.ETHEREUM_RPC_URL,
+  '10': process.env.OPTIMISM_RPC_URL,
+  '56': process.env.BSC_RPC_URL,
+  '8453': process.env.BASE_RPC_URL,
+  '42161': process.env.ARBITRUM_RPC_URL,
+  '143': process.env.MONAD_RPC_URL,
+  '4326': process.env.MEGAETH_RPC_URL,
+};
+
+function jsonRpcError(res: NextApiResponse, id: unknown, code: number, message: string) {
+  return res.status(200).json({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+}
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  const chainId = req.query.chainId as string;
+  const rpcUrl = RPC_URLS[chainId];
+
+  if (!rpcUrl) {
+    return jsonRpcError(res, null, -32603, `RPC not configured for chain ${chainId}`);
+  }
+
+  try {
+    const response = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(req.body),
+    });
+
+    res.setHeader('Cache-Control', 'no-store');
+    return res.status(200).json(await response.json());
+  } catch (error) {
+    return jsonRpcError(res, null, -32603, error instanceof Error ? error.message : 'RPC request failed');
+  }
+}
+```
+
+**.env:**
+
+```
+ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
+OPTIMISM_RPC_URL=https://opt-mainnet.g.alchemy.com/v2/YOUR_KEY
+BSC_RPC_URL=https://bsc-mainnet.g.alchemy.com/v2/YOUR_KEY
+BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
+ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
+MONAD_RPC_URL=https://your-monad-rpc.example.com
+MEGAETH_RPC_URL=https://your-megaeth-rpc.example.com
+```
+
+> **Not using Next.js?** The same approach works with any backend — Express, Fastify, Cloudflare Workers, etc. The proxy just needs to forward the request body upstream and return the response. The widget doesn't care what's behind the route as long as it speaks the same protocol (REST for VT, JSON-RPC for RPCs).
+
+## Props
+
+| Prop                 | Type                                     | Default        | Description                                      |
+| -------------------- | ---------------------------------------- | -------------- | ------------------------------------------------ |
+| `config`             | `AoriSwapWidgetConfig`                   | —              | Widget configuration (required)                  |
+| `customWalletUI`     | `'none' \| 'provider'`                  | `'provider'`   | `'provider'` wires into your wallet modals via callbacks; `'none'` hides all wallet UI |
+| `onRequestConnect`   | `() => void`                             | —              | Open the host app's connect modal                |
+| `onRequestAccount`   | `() => void`                             | —              | Open the host app's account modal                |
+| `onSwapComplete`     | `(orderHash: string) => void`            | —              | Callback after a successful swap                 |
+| `onBaseTokenChange`  | `(token: Asset) => void`                 | —              | Callback when the base token changes             |
+| `onQuoteTokenChange` | `(token: Asset) => void`                 | —              | Callback when the quote token changes            |
+| `className`          | `string`                                 | —              | Additional CSS class on the root element         |
+
+## Configuration
+
+See [`AoriSwapWidgetConfig`](./src/config/types.ts) for the full type. Only non-default values need to be specified.
+
+| Section | Type | Description |
+| --- | --- | --- |
+| `theme` | `{ mode, light?, dark? }` | Active color mode and optional light/dark theme overrides. Each theme controls colors, border radius, fonts, and shadows. |
+| `tokens` | `{ defaultBase?, defaultQuote?, lockBase?, lockQuote?, enabledChains?, disableInverting?, supportedInputTokens?, supportedOutputTokens? }` | Default token pair, enabled chains, lock/invert settings, and per-side token whitelists. All fields are optional — when omitted, all supported tokens and chains are available. |
+| `appearance` | `{ widgetType?, tokenDisplay?, assetMenuVariant?, swapButtonVariant?, ... }` | Layout variant (`default`, `compact`, `horizontal`, `split`), token display style, asset menu variant, quote loader, and other UI options. |
+| `settings` | `{ defaultSlippage? }` | Default slippage tolerance. |
+| `integrator` | `{ id?, feeRecipient?, feeAmount? }` | Integrator ID, fee recipient address, and fee amount for revenue attribution. |
+| `vtApiBaseUrl` | `string` | Base URL for the Aori transfer API. Use a relative path (e.g. `'/api/vt'`) to proxy through your server and keep the API key off the client. |
+| `rpcOverrides` | `Record<number, string \| string[]>` | Override RPCs for the widget's internal viem clients. Accepts direct URLs or relative paths to your own proxy routes. |
+
+## Display Patterns
+
+The widget is a standard React component — place it anywhere in your layout.
+
+### Inline (default)
+
+```tsx
+<SwapWidget config={config} />
+```
+
+### Modal / Dialog
+
+```tsx
+const [open, setOpen] = useState(false);
+
+return (
+  <>
+    <button onClick={() => setOpen(true)}>Swap</button>
+    {open && (
+      <div
+        className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
+        onClick={() => setOpen(false)}
+      >
+        <div onClick={(e) => e.stopPropagation()}>
+          <SwapWidget config={config} />
+        </div>
+      </div>
+    )}
+  </>
+);
+```
+
+### Drawer / Slide-in
+
+```tsx
+const [open, setOpen] = useState(false);
+
+return (
+  <>
+    <button onClick={() => setOpen(true)}>Swap</button>
+    <div
+      className={`fixed top-0 right-0 z-50 h-full w-[420px] bg-background shadow-xl
+        transition-transform duration-300
+        ${open ? 'translate-x-0' : 'translate-x-full'}`}
+    >
+      <button onClick={() => setOpen(false)}>Close</button>
+      <SwapWidget config={config} />
+    </div>
+    {open && (
+      <div
+        className="fixed inset-0 z-40 bg-black/30"
+        onClick={() => setOpen(false)}
+      />
+    )}
+  </>
+);
+```
+
+These are minimal examples. In production, use your app's existing modal/drawer components (Radix, shadcn, Headless UI, etc.) for accessibility and consistent behavior.
+
+## Resources
+
+- [Full Documentation](https://docs.aori.io)
+- [Widget API Reference](https://docs.aori.io/swap-widget)
+- [GitHub](https://github.com/aori-io)
+
+## License
+
+[MIT](./LICENSE)

package/dist/AssetSelectionMenu-Y3EB32BT.cjs

@@ -0,0 +1,13 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
+"use client";
+
+
+var _chunk3E6RNP2Dcjs = require('./chunk-3E6RNP2D.cjs');
+require('./chunk-6XB5R4GF.cjs');
+require('./chunk-GZUTUD5O.cjs');
+require('./chunk-PGYOJ5RB.cjs');
+require('./chunk-NBJPKJBC.cjs');
+
+
+exports.default = _chunk3E6RNP2Dcjs.AssetSelectionMenu_default;
+//# sourceMappingURL=AssetSelectionMenu-Y3EB32BT.cjs.map

package/dist/AssetSelectionMenu-Y3EB32BT.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/flooreyes/mega-swap-widget/dist/AssetSelectionMenu-Y3EB32BT.cjs"],"names":[],"mappings":"AAAA,qFAAY;AACZ,YAAY;AACZ;AACE;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B,gCAA6B;AAC7B,gCAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACF,+DAAC","file":"/Users/flooreyes/mega-swap-widget/dist/AssetSelectionMenu-Y3EB32BT.cjs"}

package/dist/AssetSelectionMenu-ZRG42UCZ.js

@@ -0,0 +1,13 @@
+"use client";
+"use client";
+import {
+  AssetSelectionMenu_default
+} from "./chunk-6YLNOZ7P.js";
+import "./chunk-TMC4SUEV.js";
+import "./chunk-6Q7MSCKS.js";
+import "./chunk-7AWG6OWF.js";
+import "./chunk-GGM3MDFM.js";
+export {
+  AssetSelectionMenu_default as default
+};
+//# sourceMappingURL=AssetSelectionMenu-ZRG42UCZ.js.map

package/dist/AssetSelectionMenu-ZRG42UCZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/ChainSelectionMenu-FBAPPFKI.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
+"use client";
+
+
+var _chunkB3ILUJ7Gcjs = require('./chunk-B3ILUJ7G.cjs');
+require('./chunk-GZUTUD5O.cjs');
+require('./chunk-NBJPKJBC.cjs');
+
+
+exports.default = _chunkB3ILUJ7Gcjs.ChainSelectionMenu_default;
+//# sourceMappingURL=ChainSelectionMenu-FBAPPFKI.cjs.map

package/dist/ChainSelectionMenu-FBAPPFKI.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/flooreyes/mega-swap-widget/dist/ChainSelectionMenu-FBAPPFKI.cjs"],"names":[],"mappings":"AAAA,qFAAY;AACZ,YAAY;AACZ;AACE;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACF,+DAAC","file":"/Users/flooreyes/mega-swap-widget/dist/ChainSelectionMenu-FBAPPFKI.cjs"}

package/dist/ChainSelectionMenu-QO3H4TNR.js

@@ -0,0 +1,11 @@
+"use client";
+"use client";
+import {
+  ChainSelectionMenu_default
+} from "./chunk-5XSCUUOW.js";
+import "./chunk-6Q7MSCKS.js";
+import "./chunk-GGM3MDFM.js";
+export {
+  ChainSelectionMenu_default as default
+};
+//# sourceMappingURL=ChainSelectionMenu-QO3H4TNR.js.map

package/dist/ChainSelectionMenu-QO3H4TNR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}