x402 Giftcard Purchase

# 0. Discover available regions (e.g. US, CA, ...) and their brand counts
npx -p @goatnetwork/agentkit agentkit-giftcard regions

# 1. List brands in your chosen region (--country is required outside a TTY;
#    in an interactive terminal the CLI prompts you with a region picker)
npx -p @goatnetwork/agentkit agentkit-giftcard list-brands --country US

# 2. Pick a brand UUID and discover its products + face values
#    (get-brand is region-agnostic — brand UUIDs are global)
npx -p @goatnetwork/agentkit agentkit-giftcard get-brand <brand-id>

# 3. Buy (creates order, broadcasts source-chain transfer, polls until FULFILLED)
GOAT_PRIVATE_KEY=0x... \
PAYMENT_CHAIN_RPC_URL=https://bsc-dataseed.bnbchain.org \
PAYMENT_CHAIN_ID=56 \
  npx -p @goatnetwork/agentkit agentkit-giftcard buy \
    --product <product-id> --face-value 25 \
    --pay-chain 56 --pay-token USDT

# 4. (Later) re-check status or list past orders
npx -p @goatnetwork/agentkit agentkit-giftcard status <order-id>
npx -p @goatnetwork/agentkit agentkit-giftcard list-orders

CREATED              ← order accepted by backend, awaiting agent payment
        ↓ (backend transitions on payment readiness)
PAYMENT_PENDING      ← ready to receive the source-chain ERC-20 transfer
        ↓ (agent calls payOrder)
PAYMENT_CONFIRMED    ← chain watcher saw the transfer
        ↓
FULFILLING           ← brand integration in flight
        ↓
FULFILLMENT_POLLING  ← intermediate fulfillment poll (some brands)
        ↓
FULFILLED            ← giftcard delivered (card_code / card_pin / card_link available)

Terminal failure / refund branch:
    FAILED, EXPIRED, CANCELLED       — paid-or-unpaid order ended without delivery
    REFUNDING → REFUNDED             — backend issued a refund to the source-chain payer
    REFUND_FAILED                    — refund attempt failed; contact support

plugins/giftcard/
├── actions/                       # 8 actions above
└── adapters/
    ├── http-giftcard-api.ts       # HttpGiftcardGatewayAdapter — the HTTP client
    ├── eip712-auth-signer.ts      # Backend session auth (Redis-backed single-flight)
    └── types.ts                   # GiftcardOrderStatus, GiftcardBrand, ...

import { randomUUID } from 'node:crypto';
import { JsonRpcProvider, Wallet } from 'ethers';
import { ActionProvider, ExecutionRuntime, PolicyEngine } from '@goatnetwork/agentkit';
import { EvmWalletProvider } from '@goatnetwork/agentkit/core';
import {
  HttpGiftcardGatewayAdapter,
  Eip712AuthSigner,
  listBrandsAction,
  getBrandAction,
  createOrderAction,
  payOrderAction,
  getOrderAction,
} from '@goatnetwork/agentkit/plugins';

// Wire up the source-chain wallet (the one that broadcasts the ERC-20 transfer).
const rpc = process.env.PAYMENT_CHAIN_RPC_URL!;
const signer = new Wallet(process.env.GOAT_PRIVATE_KEY!, new JsonRpcProvider(rpc));
const wallet = new EvmWalletProvider(signer, new JsonRpcProvider(rpc), 'source');

// Auth signer for the giftcard backend (EIP-712). Pass a WalletProvider.
const authSigner = new Eip712AuthSigner(wallet);
const gateway = new HttpGiftcardGatewayAdapter({
  baseUrl: process.env.GIFTCARD_API_BASE_URL ?? 'https://giftcard-api.goat.network',
  authSigner,
});

const provider = new ActionProvider();
provider.register(listBrandsAction(gateway));
provider.register(getBrandAction(gateway));
provider.register(createOrderAction(gateway));
provider.register(payOrderAction(gateway, wallet));
provider.register(getOrderAction(gateway));

const policy = new PolicyEngine({
  allowedNetworks: ['source'],
  maxRiskWithoutConfirm: 'low',
  writeEnabled: true,
});
const runtime = new ExecutionRuntime(policy, { maxRetries: 0, retryDelayMs: 200 });
const ctx = { traceId: 'gift-1', network: 'source', now: Date.now() };

// 1. Discover brands → pick a product UUID from getBrand.products[]
const brands = await runtime.run(provider.get('goat.giftcard.listBrands'), ctx, {});
const brand = await runtime.run(provider.get('goat.giftcard.getBrand'), ctx, {
  brand_id: '<brand-id>',
});
const product = brand.output!.products[0]; // pick one

// 2. Create an order. idempotency_key MUST match ExecutionOptions.idempotencyKey.
const idemKey = randomUUID();
const order = await runtime.run(
  provider.get('goat.giftcard.createOrder'),
  ctx,
  {
    product_id: product.id,
    face_value: 25,
    pay_chain_id: 56,            // BSC
    pay_token_symbol: 'USDT',
    idempotency_key: idemKey,
  },
  { confirmed: true, idempotencyKey: idemKey },
);

// 3. Pay (broadcast the source-chain transfer).
//    NOTE the input field is `orderId` (camelCase) — payOrder + getOrder
//    both take camelCase input keys even though createOrder + the output
//    OrderRecord shape use snake_case (`order_id`). This mismatch is real;
//    don't pass `order_id` to payOrder/getOrder or Zod will reject with
//    INVALID_INPUT before any HTTP traffic.
const paid = await runtime.run(
  provider.get('goat.giftcard.payOrder'),
  ctx,
  { orderId: order.output!.order_id },
  { confirmed: true },
);

// 4. Poll status until FULFILLED (or a terminal failure / refund state)
const TERMINAL = new Set(['FULFILLED', 'FAILED', 'CANCELLED', 'EXPIRED', 'REFUNDED', 'REFUND_FAILED']);
const deadline = Date.now() + 5 * 60_000;
while (Date.now() < deadline) {
  const snap = await runtime.run(provider.get('goat.giftcard.getOrder'), ctx, {
    orderId: order.output!.order_id,
  });
  const status = (snap.output as { status: string }).status;
  console.log('status:', status);
  if (TERMINAL.has(status)) break;
  await new Promise((r) => setTimeout(r, 5_000));
}