@b3dotfun/sdk 0.1.65 → 0.1.66-alpha.0

package/dist/types/anyspend/react/components/common/OrderTokenAmount.d.ts

@@ -1,5 +1,5 @@
 import { components } from "@b3dotfun/sdk/anyspend/types/api";
-export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect, canEditAmount, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, walletAddress, skipAutoMaxOnTokenChange, }: {
+export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect, canEditAmount, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, }: {
     disabled?: boolean;
     inputValue: string;
     onChangeInput: (value: string) => void;
@@ -18,7 +18,4 @@ export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput,
     onTokenSelect?: (token: components["schemas"]["Token"], event: {
         preventDefault: () => void;
     }) => void;
-    walletAddress?: string | undefined;
-    /** When true, skip auto-setting max balance when token changes (used for fixed destination amount mode) */
-    skipAutoMaxOnTokenChange?: boolean;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/types/anyspend/react/components/index.d.ts

@@ -8,6 +8,8 @@ export { AnySpendDeposit } from "./AnySpendDeposit";
 export type { AnySpendDepositProps, ChainConfig, DepositContractConfig } from "./AnySpendDeposit";
 export type { AnySpendAllClasses, AnySpendClasses, AnySpendCustomExactInClasses, AnySpendDepositClasses, CryptoPaymentMethodClasses, CryptoPaySectionClasses, CryptoReceiveSectionClasses, FiatPaymentMethodClasses, OrderDetailsClasses, PanelOnrampClasses, QRDepositClasses, RecipientSelectionClasses, } from "./types/classes";
 export { AnySpendDepositHype, HYPE_TOKEN_DETAILS } from "./AnyspendDepositHype";
+export { AnySpendWorkflowTrigger } from "./AnySpendWorkflowTrigger";
+export type { AnySpendWorkflowTriggerProps } from "./AnySpendWorkflowTrigger";
 export * from "./AnySpendFingerprintWrapper";
 export { AnySpendNFT } from "./AnySpendNFT";
 export { AnyspendSignatureMint } from "./AnyspendSignatureMint";

package/dist/types/anyspend/react/hooks/index.d.ts

@@ -12,6 +12,7 @@ export * from "./useGasPrice";
 export * from "./useGeoOnrampOptions";
 export * from "./useGetGeo";
 export * from "./useHyperliquidTransfer";
+export * from "./useOnOrderSuccess";
 export * from "./useRecipientAddressState";
 export * from "./useSigMint";
 export * from "./useStripeClientSecret";

package/dist/types/anyspend/react/hooks/useAnyspendCreateOrder.d.ts

@@ -18,6 +18,7 @@ export type CreateOrderParams = {
     creatorAddress?: string;
     payload?: any;
     metadata?: Record<string, any>;
+    callbackMetadata?: Record<string, unknown>;
 };
 export type UseAnyspendCreateOrderProps = {
     onSuccess?: (data: any) => void;

package/dist/types/anyspend/react/hooks/useOnOrderSuccess.d.ts

@@ -0,0 +1,10 @@
+import { GetOrderAndTxsResponse } from "../../types/api_req_res";
+/**
+ * Hook to call onSuccess callback when an order is executed.
+ * Handles fallback to relayTxs when executeTx is null.
+ */
+export declare function useOnOrderSuccess({ orderData, orderId, onSuccess, }: {
+    orderData: GetOrderAndTxsResponse | undefined;
+    orderId: string | undefined;
+    onSuccess?: (txHash?: string) => void;
+}): void;

package/dist/types/anyspend/services/anyspend.d.ts

@@ -6,7 +6,7 @@ export declare const anyspendService: {
     getTokenList: (chainId: number, query: string) => Promise<components["schemas"]["Token"][]>;
     getToken: (chainId: number, tokenAddress: string) => Promise<components["schemas"]["Token"]>;
     getQuote: (req: GetQuoteRequest, partnerId?: string) => Promise<GetQuoteResponse>;
-    createOrder: ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, }: {
+    createOrder: ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, callbackMetadata, }: {
         recipientAddress: string;
         type: string;
         srcChain: number;
@@ -21,6 +21,7 @@ export declare const anyspendService: {
         partnerId?: string;
         clientReferenceId?: string;
         visitorData?: VisitorData;
+        callbackMetadata?: Record<string, unknown>;
     }) => Promise<{
         success: boolean;
         message: string;

package/dist/types/anyspend/utils/chain.d.ts

@@ -82,7 +82,7 @@ export declare function isTestnet(chainId: number): boolean;
 export declare function getDefaultToken(chainId: number): components["schemas"]["Token"];
 export declare function getChainName(chainId: number): string;
 export declare function getCoingeckoName(chainId: number): string | null;
-export declare function getPaymentUrl(address: string, amount: bigint, currency: string, chainId: number, decimals?: number): string;
+export declare function getPaymentUrl(address: string, amount: bigint | undefined, currency: string, chainId: number, decimals?: number): string;
 export declare function getExplorerTxUrl(chainId: number, txHash: string): string;
 export declare function getExplorerAddressUrl(chainId: number, address: string): string;
 export declare function getMulticall3Address(chainId: number): string;

package/dist/types/global-account/react/stores/useModalStore.d.ts

@@ -470,11 +470,45 @@ export interface AnySpendCollectorClubPurchaseProps extends BaseModalProps {
     forceFiatPayment?: boolean;
     /** Staging environment support */
     isStaging?: boolean;
+    /** Optional discount code to apply to the purchase */
+    discountCode?: string;
 }
 /**
  * Props for the AnySpend Deposit modal
  * Flexible deposit component with optional chain selection
  */
+/**
+ * Props for the AnySpend Workflow Trigger modal
+ * Handles payments that trigger b3os-workflow runs
+ */
+export interface AnySpendWorkflowTriggerModalProps extends BaseModalProps {
+    /** Modal type identifier */
+    type: "anySpendWorkflowTrigger";
+    /** Payment recipient address (hex) */
+    recipientAddress: string;
+    /** Destination chain ID */
+    chainId: number;
+    /** Destination token address */
+    tokenAddress: string;
+    /** Required payment amount in token base units (wei) */
+    amount: string;
+    /** Workflow ID to trigger */
+    workflowId: string;
+    /** Organization ID that owns the workflow */
+    orgId: string;
+    /** Optional callback metadata */
+    callbackMetadata?: {
+        inputs?: Record<string, unknown>;
+    } & Record<string, unknown>;
+    /** Callback when payment succeeds */
+    onSuccess?: (amount: string) => void;
+    /** Callback when modal is closed */
+    onClose?: () => void;
+    /** Custom action label */
+    actionLabel?: string;
+    /** Custom class names */
+    classes?: AnySpendAllClasses;
+}
 export interface AnySpendDepositModalProps extends BaseModalProps {
     /** Modal type identifier */
     type: "anySpendDeposit";
@@ -534,11 +568,13 @@ export interface AnySpendDepositModalProps extends BaseModalProps {
     classes?: AnySpendAllClasses;
     /** Whether to allow direct transfer without swap */
     allowDirectTransfer?: boolean;
+    /** Opaque metadata passed to the order for callbacks (e.g., workflow form data) */
+    callbackMetadata?: Record<string, unknown>;
 }
 /**
  * Union type of all possible modal content types
  */
-export type ModalContentType = SignInWithB3ModalProps | RequestPermissionsModalProps | ManageAccountModalProps | AnySpendModalProps | AnyspendOrderDetailsProps | AnySpendNftProps | AnySpendJoinTournamentProps | AnySpendFundTournamentProps | AnySpendOrderHistoryProps | AnySpendStakeB3Props | AnySpendStakeB3ExactInProps | AnySpendStakeUpsideProps | AnySpendStakeUpsideExactInProps | AnySpendDepositUpsideProps | AnySpendBuySpinProps | AnySpendSignatureMintProps | AnySpendBondKitProps | LinkAccountModalProps | LinkNewAccountModalProps | AnySpendDepositHypeProps | AvatarEditorModalProps | DepositModalProps | SendModalProps | NotificationsModalProps | AnySpendCollectorClubPurchaseProps | AnySpendDepositModalProps;
+export type ModalContentType = SignInWithB3ModalProps | RequestPermissionsModalProps | ManageAccountModalProps | AnySpendModalProps | AnyspendOrderDetailsProps | AnySpendNftProps | AnySpendJoinTournamentProps | AnySpendFundTournamentProps | AnySpendOrderHistoryProps | AnySpendStakeB3Props | AnySpendStakeB3ExactInProps | AnySpendStakeUpsideProps | AnySpendStakeUpsideExactInProps | AnySpendDepositUpsideProps | AnySpendBuySpinProps | AnySpendSignatureMintProps | AnySpendBondKitProps | LinkAccountModalProps | LinkNewAccountModalProps | AnySpendDepositHypeProps | AvatarEditorModalProps | DepositModalProps | SendModalProps | NotificationsModalProps | AnySpendCollectorClubPurchaseProps | AnySpendDepositModalProps | AnySpendWorkflowTriggerModalProps;
 /**
  * State interface for the modal store
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b3dotfun/sdk",
-  "version": "0.1.65",
+  "version": "0.1.66-alpha.0",
   "source": "src/index.ts",
   "main": "./dist/cjs/index.js",
   "react-native": "./dist/cjs/index.native.js",

package/src/anyspend/README.md

@@ -81,6 +81,7 @@ That's it! Your users can now purchase NFTs with any token from any supported ch
 | [🧩 Components API](./docs/components.md) | Pre-built React components for common use cases |
 | [🪝 Hooks API](./docs/hooks.md) | React hooks for custom implementations |
 | [💡 Examples & Use Cases](./docs/examples.md) | Real-world integration examples |
+| [🛒 Checkout Sessions](./docs/checkout-sessions.md) | Stripe-like checkout sessions for merchant integrations |
 | [⚠️ Error Handling](./docs/error-handling.md) | Error handling patterns and troubleshooting |
 | [🤝 Contributing](./docs/contributing.md) | How to contribute to AnySpend |
 
@@ -123,6 +124,19 @@ That's it! Your users can now purchase NFTs with any token from any supported ch
 />
 ```
 
+### Merchant Checkout Sessions
+```tsx
+<AnySpend
+  defaultActiveTab="fiat"
+  destinationTokenAddress="0x..." // USDC
+  recipientAddress={userAddress}
+  checkoutSession={{
+    success_url: "https://myshop.com/success?session={SESSION_ID}",
+    metadata: { sku: "widget-1" },
+  }}
+/>
+```
+
 ## 🌐 Supported Networks
 
 - **Ethereum** (Mainnet & Sepolia)

package/src/anyspend/docs/checkout-sessions.md

@@ -0,0 +1,228 @@
+# Checkout Sessions
+
+Stripe-like checkout sessions for AnySpend. Sessions are decoupled from orders — create a session first, then create an order when the user is ready to pay.
+
+## Flow
+
+```
+1. Merchant creates session        POST /checkout-sessions
+                                   <- { id, status: "open" }
+
+2. User picks payment method       POST /orders { checkoutSessionId }
+                                   <- { id, globalAddress, oneClickBuyUrl }
+
+3. User pays                       Crypto: send to globalAddress
+                                   Onramp: redirect to oneClickBuyUrl
+
+4. Merchant polls for completion   GET /checkout-sessions/:id
+                                   <- { status: "complete", order_id }
+```
+
+### Why Decoupled?
+
+Session creation is instant (DB-only, no external calls). The order is created separately when the user commits to a payment method. This means:
+
+- Payment method doesn't need to be known at session creation
+- A hosted checkout page can let users choose how to pay
+- Session creation never fails due to external API errors
+
+## Session Status Lifecycle
+
+```
+open --> processing --> complete
+  |
+  └--> expired
+```
+
+| Status | When |
+|--------|------|
+| `open` | Created, waiting for order/payment |
+| `processing` | Payment received, order executing |
+| `complete` | Order executed successfully |
+| `expired` | TTL expired, payment failed, or manually expired |
+
+## API
+
+### `POST /checkout-sessions` — Create Session
+
+Creates a lightweight session. No order, no external API calls.
+
+```json
+{
+  "success_url": "https://merchant.com/success?session_id={SESSION_ID}",
+  "cancel_url": "https://merchant.com/cancel",
+  "metadata": { "sku": "widget-1" },
+  "client_reference_id": "merchant-order-456",
+  "expires_in": 1800
+}
+```
+
+All fields are optional. Payment config (amount, tokens, chains) lives on the order, not the session.
+
+### `POST /orders` — Create Order with Session Linking
+
+Pass `checkoutSessionId` in the standard order creation request to link the order to a session.
+
+```json
+{
+  "recipientAddress": "0x...",
+  "srcChain": 8453,
+  "dstChain": 8453,
+  "srcTokenAddress": "0x...",
+  "dstTokenAddress": "0x...",
+  "srcAmount": "1000000",
+  "type": "swap",
+  "payload": { "expectedDstAmount": "1000000" },
+  "checkoutSessionId": "550e8400-..."
+}
+```
+
+**Validation:**
+- Session must exist (`400` if not found)
+- Session must be `open` (`400` if expired/processing/complete)
+- Session must not already have an order (`409 Conflict`)
+
+### `GET /checkout-sessions/:id` — Retrieve Session
+
+Returns current session state. Status is synced from the underlying order on each retrieval.
+
+| Query Param | Description |
+|-------------|-------------|
+| `include=order` | Embed the full order object with transactions |
+
+### `POST /checkout-sessions/:id/expire` — Manually Expire
+
+Only works on sessions with status `open`.
+
+## Redirect URL Templates
+
+Use template variables in `success_url` and `cancel_url`:
+
+| Variable | Replaced with |
+|----------|--------------|
+| `{SESSION_ID}` | The checkout session UUID |
+| `{ORDER_ID}` | Same value (alias) |
+
+If no template variable is present, `?sessionId=<uuid>` is appended automatically.
+
+## SDK Integration
+
+### Service Methods
+
+```typescript
+// Create a checkout session
+const session = await anyspend.createCheckoutSession({
+  success_url: "https://mysite.com/success/{SESSION_ID}",
+  metadata: { sku: "widget-1" },
+});
+
+// Retrieve session status
+const session = await anyspend.getCheckoutSession(sessionId);
+```
+
+### React Hooks
+
+#### `useCreateCheckoutSession`
+
+Mutation hook for creating sessions.
+
+```tsx
+import { useCreateCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { mutate: createSession, data, isPending } = useCreateCheckoutSession();
+```
+
+#### `useCheckoutSession`
+
+Query hook with auto-polling. Stops polling when status reaches `complete` or `expired`.
+
+```tsx
+import { useCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { data: session, isLoading } = useCheckoutSession(sessionId);
+```
+
+### Component `checkoutSession` Prop
+
+The `<AnySpend>`, `<AnySpendCustom>`, and `<AnySpendCustomExactIn>` components accept an optional `checkoutSession` prop:
+
+```tsx
+<AnySpend
+  defaultActiveTab="fiat"
+  destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  destinationTokenChainId={8453}
+  recipientAddress="0x..."
+  checkoutSession={{
+    success_url: "https://myshop.com/success?session={SESSION_ID}",
+    cancel_url: "https://myshop.com/cancel",
+    metadata: { sku: "widget-1" },
+  }}
+/>
+```
+
+When the `checkoutSession` prop is set, the component automatically creates a session before creating the order, and uses the session's `success_url` for redirects. Without the prop, existing flows are unchanged.
+
+## Examples
+
+### Crypto Payment
+
+```typescript
+// 1. Create session
+const session = await fetch("/checkout-sessions", {
+  method: "POST",
+  body: JSON.stringify({
+    success_url: "https://mysite.com/success/{SESSION_ID}",
+    metadata: { sku: "widget-1" },
+  }),
+}).then(r => r.json());
+
+// 2. Create order linked to session
+const order = await fetch("/orders", {
+  method: "POST",
+  body: JSON.stringify({
+    recipientAddress: "0x...",
+    srcChain: 8453,
+    dstChain: 8453,
+    srcTokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    dstTokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    srcAmount: "1000000",
+    type: "swap",
+    payload: { expectedDstAmount: "1000000" },
+    checkoutSessionId: session.data.id,
+  }),
+}).then(r => r.json());
+
+// 3. User sends crypto to order.data.globalAddress
+
+// 4. Poll session until complete
+const poll = setInterval(async () => {
+  const s = await fetch(`/checkout-sessions/${session.data.id}`).then(r => r.json());
+  if (s.data.status === "complete") {
+    clearInterval(poll);
+    // redirect to success_url or show confirmation
+  }
+}, 3000);
+```
+
+### Onramp Payment (Coinbase/Stripe)
+
+```typescript
+// Steps 1-2 same as above, but include onramp config in order creation:
+const order = await fetch("/orders", {
+  method: "POST",
+  body: JSON.stringify({
+    // ... same order fields ...
+    checkoutSessionId: session.data.id,
+    onramp: {
+      vendor: "coinbase",
+      payment_method: "card",
+      country: "US",
+    },
+  }),
+}).then(r => r.json());
+
+// Redirect user to vendor checkout page
+window.location.href = order.data.oneClickBuyUrl;
+
+// After vendor redirects back, poll GET /checkout-sessions/:id for completion
+```

package/src/anyspend/docs/components.md

@@ -207,6 +207,32 @@ const stakingCalldata = encodeFunctionData({
 />
 ```
 
+### Checkout Session Prop
+
+The `<AnySpend>`, `<AnySpendCustom>`, and `<AnySpendCustomExactIn>` components accept an optional `checkoutSession` prop for merchant checkout flows. When set, the component creates a session before the order and uses the session's redirect URLs. See [Checkout Sessions](./checkout-sessions.md) for the full guide.
+
+```tsx
+<AnySpend
+  defaultActiveTab="fiat"
+  destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  destinationTokenChainId={8453}
+  recipientAddress="0x..."
+  checkoutSession={{
+    success_url: "https://myshop.com/success?session={SESSION_ID}",
+    cancel_url: "https://myshop.com/cancel",
+    metadata: { sku: "widget-1" },
+  }}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `checkoutSession.success_url` | `string` | Redirect URL on completion. Supports `{SESSION_ID}` template. |
+| `checkoutSession.cancel_url` | `string` | Redirect URL on cancellation |
+| `checkoutSession.metadata` | `Record<string, string>` | Custom metadata attached to the session |
+
+---
+
 ## Specialized Components
 
 ### `<AnySpendNFT>`

package/src/anyspend/docs/examples.md

@@ -720,8 +720,66 @@ function PortfolioRebalancer() {
 }
 ```
 
+## 🛒 Checkout Sessions (Merchant Integration)
+
+### Hosted Checkout with Payment Choice
+
+Let users choose their payment method (crypto or fiat) after session creation.
+
+```tsx
+import { AnySpend } from "@b3dotfun/sdk/anyspend/react";
+
+function MerchantCheckout({ sku, price }: { sku: string; price: string }) {
+  const [userAddress] = useWallet();
+
+  return (
+    <AnySpend
+      defaultActiveTab="fiat"
+      destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+      destinationTokenChainId={8453}
+      recipientAddress={userAddress}
+      checkoutSession={{
+        success_url: "https://myshop.com/success?session={SESSION_ID}",
+        cancel_url: "https://myshop.com/cancel",
+        metadata: { sku, price },
+      }}
+    />
+  );
+}
+```
+
+### Server-Side Session with Custom Polling
+
+```tsx
+import {
+  useCreateCheckoutSession,
+  useCheckoutSession,
+} from "@b3dotfun/sdk/anyspend";
+
+function ServerCheckout() {
+  const { mutate: createSession, data: session } = useCreateCheckoutSession();
+  const { data: sessionStatus } = useCheckoutSession(session?.data?.id);
+
+  useEffect(() => {
+    createSession({
+      success_url: "https://mysite.com/success/{SESSION_ID}",
+      metadata: { sku: "widget-1" },
+    });
+  }, []);
+
+  if (sessionStatus?.data?.status === "complete") {
+    return <div>Payment complete!</div>;
+  }
+
+  // Render order creation UI...
+}
+```
+
+See [Checkout Sessions](./checkout-sessions.md) for the full guide including API details and the session lifecycle.
+
 ## Next Steps
 
+- [Checkout Sessions →](./checkout-sessions.md)
 - [Error Handling Guide →](./error-handling.md)
 - [Components Reference →](./components.md)
 - [Hooks Reference →](./hooks.md)

package/src/anyspend/docs/hooks.md

@@ -385,6 +385,38 @@ Get Stripe payment intent for credit card payments.
 const { clientSecret, isLoadingClientSecret } = useStripeClientSecret(orderData);
 ```
 
+### `useCreateCheckoutSession`
+
+Create checkout sessions for merchant integrations. See [Checkout Sessions](./checkout-sessions.md) for the full guide.
+
+```tsx
+import { useCreateCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { mutate: createSession, data, isPending } = useCreateCheckoutSession();
+
+createSession({
+  success_url: "https://mysite.com/success/{SESSION_ID}",
+  cancel_url: "https://mysite.com/cancel",
+  metadata: { sku: "widget-1" },
+});
+```
+
+---
+
+### `useCheckoutSession`
+
+Poll a checkout session's status. Auto-polls while the session is `open` or `processing`, and stops when `complete` or `expired`.
+
+```tsx
+import { useCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { data: session, isLoading } = useCheckoutSession(sessionId);
+
+// session.data.status: "open" | "processing" | "complete" | "expired"
+```
+
+---
+
 ## Hook Patterns
 
 ### Error Handling Pattern