@orkid-labs/widget 0.1.0

package/README.md

@@ -0,0 +1,212 @@
+# @orkid/widget
+
+White-label React swap widget for the Orkid gasless swap API. Supports Base, Ethereum, Arbitrum, and Polygon.
+
+## Features
+
+- Drop-in React component (`<OrkidSwapWidget />`).
+- Iframe embed (`<OrkidSwapIframe />`) and script embed (`mountOrkidSwap`).
+- Built-in wallet (MetaMask / injected) with optional WalletConnect.
+- External `wagmi` config mode for host apps already using wagmi.
+- Configurable API endpoint — direct Orkid, sandbox, or partner proxy.
+- Full theming via CSS custom properties and a `theme` prop.
+- All four chains live: Base, Ethereum, Arbitrum, Polygon.
+- Gasless execution with user-pays-gas fallback.
+- Sandbox support via `SANDBOX_BASE_URL`.
+
+## Install
+
+```bash
+npm install @orkid/widget @orkid/sdk wagmi viem @tanstack/react-query
+```
+
+`wagmi`, `viem`, `@tanstack/react-query`, and `@orkid/sdk` are peer dependencies.
+
+## Quick start
+
+```tsx
+import { OrkidSwapProvider, OrkidSwapWidget } from '@orkid/widget'
+
+function App() {
+  return (
+    <OrkidSwapProvider
+      apiKey={process.env.NEXT_PUBLIC_ORKID_API_KEY}
+      partnerId="alternate-futures"
+      brandName="Alternate Futures"
+      showPoweredBy={false}
+      walletMode="built-in"
+      defaultFromToken={{
+        address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+        symbol: 'USDC',
+        decimals: 6,
+        chain: 'base',
+      }}
+      defaultToToken={{
+        address: '0x4200000000000000000000000000000000000006',
+        symbol: 'WETH',
+        decimals: 18,
+        chain: 'base',
+      }}
+    >
+      <OrkidSwapWidget />
+    </OrkidSwapProvider>
+  )
+}
+```
+
+## Sandbox mode
+
+To point the widget at the sandbox (dry-run only, never submits):
+
+```tsx
+import { OrkidSwapProvider, OrkidSwapWidget } from '@orkid/widget'
+import { SANDBOX_BASE_URL } from '@orkid/sdk'
+
+function App() {
+  return (
+    <OrkidSwapProvider
+      apiKey={process.env.ORKID_SANDBOX_KEY}
+      apiBaseUrl={SANDBOX_BASE_URL}
+    >
+      <OrkidSwapWidget />
+    </OrkidSwapProvider>
+  )
+}
+```
+
+## Iframe embed
+
+```tsx
+import { OrkidSwapIframe } from '@orkid/widget'
+
+<OrkidSwapIframe
+  src="https://widget.orkidlabs.xyz"
+  partner="alternate-futures"
+  brandName="Alternate Futures"
+  theme={{ primary: '#0052FF' }}
+  fromToken="0x833589fcd6edb6e08f4c7c32d4f71b54bda02913:USDC:6"
+  toToken="0x4200000000000000000000000000000000000006:WETH:18"
+  amount="25"
+  showPoweredBy={false}
+/>
+```
+
+The hosted page reads the query parameters and forwards them to `OrkidSwapProvider`.
+
+## Script embed
+
+```html
+<script type="module">
+  import { mountOrkidSwap } from 'https://cdn.orkidlabs.xyz/widget.js'
+  mountOrkidSwap({
+    target: '#swap-widget',
+    partnerId: 'alternate-futures',
+    apiBaseUrl: 'https://partner.com',
+  })
+</script>
+```
+
+## External wagmi config
+
+If your app already sets up `wagmi`, pass the `wagmiConfig` and set `walletMode="external"`:
+
+```tsx
+import { OrkidSwapProvider, OrkidSwapWidget } from '@orkid/widget'
+import { wagmiConfig } from './wagmi'
+
+function App() {
+  return (
+    <WagmiProvider config={wagmiConfig}>
+      <QueryClientProvider client={queryClient}>
+        <OrkidSwapProvider walletMode="external" wagmiConfig={wagmiConfig} apiKey="...">
+          <OrkidSwapWidget />
+        </OrkidSwapProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  )
+}
+```
+
+## Proxy mode
+
+To avoid exposing an Orkid API key in the browser, set `apiBaseUrl` to your own backend and omit `apiKey`. Your backend must forward the request with the `X-ORKID-API-Key` header.
+
+```tsx
+<OrkidSwapProvider apiBaseUrl="https://partner.com" apiKey={undefined}>
+  <OrkidSwapWidget />
+</OrkidSwapProvider>
+```
+
+## Theming
+
+Pass a `theme` object or override CSS variables:
+
+```tsx
+<OrkidSwapProvider
+  theme={{
+    primary: '#0052FF',
+    background: '#ffffff',
+    card: '#f8fafc',
+    radius: '0.75rem',
+  }}
+>
+  <OrkidSwapWidget />
+</OrkidSwapProvider>
+```
+
+Available CSS variables: `--orkid-widget-bg`, `--orkid-widget-card`, `--orkid-widget-primary`, `--orkid-widget-text`, etc. See `src/styles.css`.
+
+## Props
+
+### OrkidSwapProvider
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | `undefined` | Orkid API key. Optional in proxy mode. |
+| `apiBaseUrl` | `string` | `https://orkidlabs.xyz` | API base URL. Use `SANDBOX_BASE_URL` for sandbox. |
+| `partnerId` | `string` | `undefined` | Partner identifier. |
+| `walletMode` | `'built-in' \| 'external'` | `'built-in'` | Wallet connection mode. |
+| `walletConnectProjectId` | `string` | `undefined` | WalletConnect project ID. |
+| `wagmiConfig` | `Config` | `undefined` | External wagmi config. |
+| `theme` | `OrkidWidgetTheme` | `defaultLightTheme` | Theme overrides. |
+| `logoUrl` | `string` | `undefined` | Partner logo URL. |
+| `brandName` | `string` | `'Swap'` | Brand name. |
+| `showPoweredBy` | `boolean` | `true` | Show "Powered by Orkid" footer. |
+| `supportedChains` | `number[]` | `[8453, 1, 42161, 137]` | Chain IDs to show. |
+| `defaultFromToken` | `OrkidWidgetToken` | `undefined` | Default input token. |
+| `defaultToToken` | `OrkidWidgetToken` | `undefined` | Default output token. |
+| `defaultAmount` | `string` | `undefined` | Default input amount. |
+| `defaultSlippageBps` | `number` | `50` | Default slippage in basis points. |
+| `tokenList` | `OrkidWidgetToken[]` | `undefined` | Restrict token list. |
+| `gasless` | `boolean` | `true` | Try gasless solve first. |
+| `onQuote` | `(res) => void` | `undefined` | Quote callback. |
+| `onSolve` | `(res) => void` | `undefined` | Solve success callback. |
+| `onError` | `(err) => void` | `undefined` | Error callback. |
+
+### OrkidSwapWidget
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | `undefined` | Additional class on the widget root. |
+
+## Chain support
+
+| Chain | ID | Status |
+|---|---|---|
+| Base | 8453 | Live |
+| Ethereum | 1 | Live |
+| Arbitrum | 42161 | Live |
+| Polygon | 137 | Live |
+
+## Development
+
+```bash
+cd orkid-widget
+npm install
+npm run typecheck
+npm run build
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,155 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+import { Config } from 'wagmi';
+import { OrkidResponse, OrkidClient } from '@orkid/sdk';
+
+interface OrkidWidgetToken {
+    address: string;
+    symbol: string;
+    decimals: number;
+    chain: string;
+}
+interface OrkidWidgetTheme {
+    background?: string;
+    card?: string;
+    cardForeground?: string;
+    primary?: string;
+    primaryForeground?: string;
+    text?: string;
+    muted?: string;
+    mutedForeground?: string;
+    border?: string;
+    success?: string;
+    warning?: string;
+    danger?: string;
+    radius?: string;
+    fontFamily?: string;
+    accent?: string;
+    accentForeground?: string;
+    popover?: string;
+    popoverForeground?: string;
+    input?: string;
+    ring?: string;
+}
+type OrkidWalletMode = 'built-in' | 'external';
+interface OrkidSwapProviderProps {
+    /** Orkid API key. Required for direct Orkid API mode. */
+    apiKey?: string;
+    /** API base URL. Defaults to https://orkidlabs.xyz. Use a partner proxy in production. */
+    apiBaseUrl?: string;
+    /** Partner identifier. Used for analytics, config lookup, and iframe mode. */
+    partnerId?: string;
+    /** Wallet connection mode. */
+    walletMode?: OrkidWalletMode;
+    /** WalletConnect project ID for built-in wallet mode. */
+    walletConnectProjectId?: string;
+    /** External wagmi config. Required when walletMode is 'external'. */
+    wagmiConfig?: Config;
+    /** Theme overrides. */
+    theme?: OrkidWidgetTheme;
+    /** Partner logo URL. */
+    logoUrl?: string;
+    /** Partner brand name shown in the widget. */
+    brandName?: string;
+    /** Show "Powered by Orkid" footer. */
+    showPoweredBy?: boolean;
+    /** Chain IDs to show. Defaults to [8453, 1, 42161, 137]. Non-live chains are disabled. */
+    supportedChains?: number[];
+    /** Default token to sell. */
+    defaultFromToken?: OrkidWidgetToken;
+    /** Default token to buy. */
+    defaultToToken?: OrkidWidgetToken;
+    /** Default input amount. */
+    defaultAmount?: string;
+    /** Default slippage in basis points. */
+    defaultSlippageBps?: number;
+    /** Restrict token list. If omitted, tokens are fetched from the API. */
+    tokenList?: OrkidWidgetToken[];
+    /** Enable gasless solve. If false, the widget will always fall back to user-pays-gas. */
+    gasless?: boolean;
+    /** Called when a quote is returned. */
+    onQuote?: (res: OrkidResponse) => void;
+    /** Called when a solve succeeds (gasless or user-pays). */
+    onSolve?: (res: OrkidResponse) => void;
+    /** Called on errors. */
+    onError?: (error: string) => void;
+    children: React.ReactNode;
+}
+interface OrkidSwapWidgetProps {
+    /** Additional CSS class on the widget root. */
+    className?: string;
+}
+
+declare function OrkidSwapProvider({ apiKey, apiBaseUrl, partnerId, walletMode, walletConnectProjectId, wagmiConfig, theme, logoUrl, brandName, showPoweredBy, supportedChains, defaultFromToken, defaultToToken, defaultAmount, defaultSlippageBps, tokenList, gasless, onQuote, onSolve, onError, children, }: OrkidSwapProviderProps): react.JSX.Element;
+
+declare function OrkidSwapWidget({ className }: {
+    className?: string;
+}): react.JSX.Element;
+
+interface OrkidSwapIframeProps {
+    /** Base URL of the hosted widget page, e.g. https://widget.orkidlabs.xyz */
+    src?: string;
+    /** Partner identifier */
+    partner?: string;
+    /** Brand name to show */
+    brandName?: string;
+    /** Logo URL */
+    logoUrl?: string;
+    /** Theme overrides */
+    theme?: OrkidWidgetTheme;
+    /** Default input token */
+    fromToken?: string;
+    /** Default output token */
+    toToken?: string;
+    /** Default amount */
+    amount?: string;
+    /** Whether to show "Powered by Orkid" */
+    showPoweredBy?: boolean;
+    /** Allow iframe to go fullscreen */
+    allowFullScreen?: boolean;
+    /** Additional class name */
+    className?: string;
+    /** Additional style */
+    style?: CSSProperties;
+}
+declare function OrkidSwapIframe({ src, partner, brandName, logoUrl, theme, fromToken, toToken, amount, showPoweredBy, allowFullScreen, className, style, }: OrkidSwapIframeProps): react.JSX.Element;
+
+interface OrkidSwapEmbedOptions extends OrkidSwapProviderProps {
+    /** The DOM element or selector to mount the widget into. */
+    target: HTMLElement | string;
+}
+/**
+ * Mounts the Orkid swap widget into a DOM element.
+ * Useful for script embeds or non-React hosts.
+ */
+declare function mountOrkidSwap(options: OrkidSwapEmbedOptions): () => void;
+
+interface OrkidSwapContextValue {
+    client: OrkidClient;
+    wagmiConfig?: Config;
+    walletMode: OrkidWalletMode;
+    theme: Required<OrkidWidgetTheme>;
+    logoUrl?: string;
+    brandName?: string;
+    showPoweredBy: boolean;
+    supportedChains: number[];
+    defaultFromToken?: OrkidWidgetToken;
+    defaultToToken?: OrkidWidgetToken;
+    defaultAmount?: string;
+    defaultSlippageBps: number;
+    tokenList?: OrkidWidgetToken[];
+    gasless: boolean;
+    partnerId?: string;
+    onQuote?: (res: OrkidResponse) => void;
+    onSolve?: (res: OrkidResponse) => void;
+    onError?: (error: string) => void;
+}
+declare const OrkidSwapContext: react.Context<OrkidSwapContextValue | undefined>;
+declare function useOrkidSwapContext(): OrkidSwapContextValue;
+
+declare const defaultLightTheme: Required<OrkidWidgetTheme>;
+declare const defaultDarkTheme: Required<OrkidWidgetTheme>;
+declare function resolveTheme(partial?: OrkidWidgetTheme): Required<OrkidWidgetTheme>;
+declare function themeToCssVariables(theme: Required<OrkidWidgetTheme>): Record<string, string>;
+
+export { OrkidSwapContext, OrkidSwapIframe, OrkidSwapProvider, type OrkidSwapProviderProps, OrkidSwapWidget, type OrkidSwapWidgetProps, type OrkidWalletMode, type OrkidWidgetTheme, type OrkidWidgetToken, defaultDarkTheme, defaultLightTheme, mountOrkidSwap, resolveTheme, themeToCssVariables, useOrkidSwapContext };

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+import { Config } from 'wagmi';
+import { OrkidResponse, OrkidClient } from '@orkid/sdk';
+
+interface OrkidWidgetToken {
+    address: string;
+    symbol: string;
+    decimals: number;
+    chain: string;
+}
+interface OrkidWidgetTheme {
+    background?: string;
+    card?: string;
+    cardForeground?: string;
+    primary?: string;
+    primaryForeground?: string;
+    text?: string;
+    muted?: string;
+    mutedForeground?: string;
+    border?: string;
+    success?: string;
+    warning?: string;
+    danger?: string;
+    radius?: string;
+    fontFamily?: string;
+    accent?: string;
+    accentForeground?: string;
+    popover?: string;
+    popoverForeground?: string;
+    input?: string;
+    ring?: string;
+}
+type OrkidWalletMode = 'built-in' | 'external';
+interface OrkidSwapProviderProps {
+    /** Orkid API key. Required for direct Orkid API mode. */
+    apiKey?: string;
+    /** API base URL. Defaults to https://orkidlabs.xyz. Use a partner proxy in production. */
+    apiBaseUrl?: string;
+    /** Partner identifier. Used for analytics, config lookup, and iframe mode. */
+    partnerId?: string;
+    /** Wallet connection mode. */
+    walletMode?: OrkidWalletMode;
+    /** WalletConnect project ID for built-in wallet mode. */
+    walletConnectProjectId?: string;
+    /** External wagmi config. Required when walletMode is 'external'. */
+    wagmiConfig?: Config;
+    /** Theme overrides. */
+    theme?: OrkidWidgetTheme;
+    /** Partner logo URL. */
+    logoUrl?: string;
+    /** Partner brand name shown in the widget. */
+    brandName?: string;
+    /** Show "Powered by Orkid" footer. */
+    showPoweredBy?: boolean;
+    /** Chain IDs to show. Defaults to [8453, 1, 42161, 137]. Non-live chains are disabled. */
+    supportedChains?: number[];
+    /** Default token to sell. */
+    defaultFromToken?: OrkidWidgetToken;
+    /** Default token to buy. */
+    defaultToToken?: OrkidWidgetToken;
+    /** Default input amount. */
+    defaultAmount?: string;
+    /** Default slippage in basis points. */
+    defaultSlippageBps?: number;
+    /** Restrict token list. If omitted, tokens are fetched from the API. */
+    tokenList?: OrkidWidgetToken[];
+    /** Enable gasless solve. If false, the widget will always fall back to user-pays-gas. */
+    gasless?: boolean;
+    /** Called when a quote is returned. */
+    onQuote?: (res: OrkidResponse) => void;
+    /** Called when a solve succeeds (gasless or user-pays). */
+    onSolve?: (res: OrkidResponse) => void;
+    /** Called on errors. */
+    onError?: (error: string) => void;
+    children: React.ReactNode;
+}
+interface OrkidSwapWidgetProps {
+    /** Additional CSS class on the widget root. */
+    className?: string;
+}
+
+declare function OrkidSwapProvider({ apiKey, apiBaseUrl, partnerId, walletMode, walletConnectProjectId, wagmiConfig, theme, logoUrl, brandName, showPoweredBy, supportedChains, defaultFromToken, defaultToToken, defaultAmount, defaultSlippageBps, tokenList, gasless, onQuote, onSolve, onError, children, }: OrkidSwapProviderProps): react.JSX.Element;
+
+declare function OrkidSwapWidget({ className }: {
+    className?: string;
+}): react.JSX.Element;
+
+interface OrkidSwapIframeProps {
+    /** Base URL of the hosted widget page, e.g. https://widget.orkidlabs.xyz */
+    src?: string;
+    /** Partner identifier */
+    partner?: string;
+    /** Brand name to show */
+    brandName?: string;
+    /** Logo URL */
+    logoUrl?: string;
+    /** Theme overrides */
+    theme?: OrkidWidgetTheme;
+    /** Default input token */
+    fromToken?: string;
+    /** Default output token */
+    toToken?: string;
+    /** Default amount */
+    amount?: string;
+    /** Whether to show "Powered by Orkid" */
+    showPoweredBy?: boolean;
+    /** Allow iframe to go fullscreen */
+    allowFullScreen?: boolean;
+    /** Additional class name */
+    className?: string;
+    /** Additional style */
+    style?: CSSProperties;
+}
+declare function OrkidSwapIframe({ src, partner, brandName, logoUrl, theme, fromToken, toToken, amount, showPoweredBy, allowFullScreen, className, style, }: OrkidSwapIframeProps): react.JSX.Element;
+
+interface OrkidSwapEmbedOptions extends OrkidSwapProviderProps {
+    /** The DOM element or selector to mount the widget into. */
+    target: HTMLElement | string;
+}
+/**
+ * Mounts the Orkid swap widget into a DOM element.
+ * Useful for script embeds or non-React hosts.
+ */
+declare function mountOrkidSwap(options: OrkidSwapEmbedOptions): () => void;
+
+interface OrkidSwapContextValue {
+    client: OrkidClient;
+    wagmiConfig?: Config;
+    walletMode: OrkidWalletMode;
+    theme: Required<OrkidWidgetTheme>;
+    logoUrl?: string;
+    brandName?: string;
+    showPoweredBy: boolean;
+    supportedChains: number[];
+    defaultFromToken?: OrkidWidgetToken;
+    defaultToToken?: OrkidWidgetToken;
+    defaultAmount?: string;
+    defaultSlippageBps: number;
+    tokenList?: OrkidWidgetToken[];
+    gasless: boolean;
+    partnerId?: string;
+    onQuote?: (res: OrkidResponse) => void;
+    onSolve?: (res: OrkidResponse) => void;
+    onError?: (error: string) => void;
+}
+declare const OrkidSwapContext: react.Context<OrkidSwapContextValue | undefined>;
+declare function useOrkidSwapContext(): OrkidSwapContextValue;
+
+declare const defaultLightTheme: Required<OrkidWidgetTheme>;
+declare const defaultDarkTheme: Required<OrkidWidgetTheme>;
+declare function resolveTheme(partial?: OrkidWidgetTheme): Required<OrkidWidgetTheme>;
+declare function themeToCssVariables(theme: Required<OrkidWidgetTheme>): Record<string, string>;
+
+export { OrkidSwapContext, OrkidSwapIframe, OrkidSwapProvider, type OrkidSwapProviderProps, OrkidSwapWidget, type OrkidSwapWidgetProps, type OrkidWalletMode, type OrkidWidgetTheme, type OrkidWidgetToken, defaultDarkTheme, defaultLightTheme, mountOrkidSwap, resolveTheme, themeToCssVariables, useOrkidSwapContext };