feat: AI Credits Widget — buy AI coding credits with G$ on Celo

.gitignore

@@ -18,3 +18,7 @@ playwright-report/
 local-reference-assets
 .vercel
 .env*
+
+
+.agents
+skills-lock.json

examples/storybook/package.json

@@ -14,6 +14,7 @@
     "@goodwidget/claim-widget-theme-demo": "workspace:*",
     "@goodwidget/citizen-claim-widget": "workspace:*",
     "@goodwidget/staking-migration-widget": "workspace:*",
+    "@goodwidget/ai-credits-widget": "workspace:*",
     "react": "^18.3.0",
     "react-dom": "^18.3.0",
     "react-native-web": "^0.19.13",

examples/storybook/src/stories/ai-credits-widget/AiCreditsWidget.mdx

@@ -0,0 +1,106 @@
+import { Canvas, Meta } from '@storybook/blocks';
+import * as ShowcaseStories from './AiCreditsWidgetShowcase.stories';
+import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/DocsLayout';
+
+<Meta of={ShowcaseStories} />
+
+<DocsPage
+  eyebrow="Widget Guide"
+  title="AiCreditsWidget"
+  lead="Buy AI coding credits with G$ on Celo. Credits settle on Base and are redeemable with AntSeed-compatible AI coding tools like Cursor and Cline."
+>
+  <DocsSection
+    title="Interactive showcase (mock backend)"
+    description="Uses your browser wallet (`window.ethereum`, e.g. Rabby) with the in-memory mock backend — no local antseed worker required."
+  >
+    <Canvas of={ShowcaseStories.MockBackend} />
+  </DocsSection>
+
+  <DocsSection
+    title="Injected wallet"
+    description="Uses your browser wallet (`window.ethereum`, e.g. Rabby), `VITE_AI_CREDITS_BACKEND_URL`, `VITE_AI_CREDITS_BASE_RPC_URL`, `VITE_AI_CREDITS_FUNDING_VAULT_ADDRESS`, and `VITE_AI_CREDITS_VAULT_ADDRESS` from `examples/storybook/.env.local`."
+  >
+    <Canvas of={ShowcaseStories.InjectedWallet} />
+  </DocsSection>
+
+  <DocsSection
+    title="QA coverage"
+    description="Use the QA demo when you need reproducible fixture states, Playwright screenshots, or fixture-driven debugging."
+  >
+    <DocsCard
+      title="Open the QA fixture demo"
+      href="?path=/story/qa-aicreditswidget-runtime-fixtures--disconnected"
+    >
+      All 10 widget states as deterministic mock fixtures — ideal for automation and debugging.
+    </DocsCard>
+  </DocsSection>
+
+  <DocsSection
+    title="Widget states"
+    description="The widget uses a flat 10-state status union, consistent with other GoodWidget packages."
+  >
+    <DocsGrid>
+      <DocsCard title="S1 – Disconnected">No wallet connected.</DocsCard>
+      <DocsCard title="S2 – Purchase Setup">Wallet connected; buyer key / consent / amounts in progress.</DocsCard>
+      <DocsCard title="S3 – Quote Ready">Setup complete; on-chain quote built; ready to pay.</DocsCard>
+      <DocsCard title="S4 – Payment Pending">Celo tx submitted.</DocsCard>
+      <DocsCard title="S5 – Payment Confirmed">Settling on Base.</DocsCard>
+      <DocsCard title="S6 – Credits Management">AI credits balance &gt; 0; management dashboard with stream, history, and API setup.</DocsCard>
+      <DocsCard title="S7 – Insufficient G$">G$ below minimum purchase threshold.</DocsCard>
+      <DocsCard title="S8 – Payment Failed">Transaction or settlement error.</DocsCard>
+      <DocsCard title="S9 – Backend Unavailable">Backend unreachable.</DocsCard>
+      <DocsCard title="S10 – Unsupported Chain">Wrong network (Celo required).</DocsCard>
+    </DocsGrid>
+  </DocsSection>
+
+  <DocsSection
+    title="Backend API usage"
+    description="Production stories call the antseed-integration worker for reads, settlement, and management actions."
+  >
+    <DocsGrid>
+      <DocsCard title="GET …/credit">Credits profile and funding history for the payer wallet.</DocsCard>
+      <DocsCard title="GET …/outstanding">Pending or failed Base funding entries.</DocsCard>
+      <DocsCard title="POST …/celo/events/record">Notify `{ txHash }` after a successful Celo payment.</DocsCard>
+      <DocsCard title="POST …/accounts/:buyer/operator-consent">
+        Buyer-signed SetOperator relay — backend submits `acceptBuyerOperator` on Base (no buyer gas).
+      </DocsCard>
+      <DocsCard title="POST …/channels/:channelId/close">Buyer-signed channel close from credits management.</DocsCard>
+      <DocsCard title="POST …/accounts/:buyer/withdraw">Buyer-signed principal withdraw to the payer wallet.</DocsCard>
+    </DocsGrid>
+    <DocsCallout title="On-chain (not backend)" tone="info">
+      Vault minimum reads, quotes, withdrawable principal, and Celo deposit/stream transactions are
+      handled on-chain via RPC. Buyer EIP-712 signing for operator consent, close, and withdraw
+      happens in the widget; only the Base submission is relayed by the worker. There is no
+      channel-list API — paste the channel ID manually.
+    </DocsCallout>
+  </DocsSection>
+
+  <DocsSection
+    title="Known limitations"
+    description="Features that still need operator care in production."
+  >
+    <DocsCallout title="Buyer private key session" tone="warning">
+      Close channel and withdraw require the buyer private key in the current browser session. Use
+      Sign &amp; Generate in Buyer &amp; Operator on the credits management screen if the key was
+      lost after refresh.
+    </DocsCallout>
+    <DocsCallout title="Vault minimums" tone="info">
+      First-deposit USD minimum applies only when `totalDepositedGd(payer)` is zero. Monthly stream
+      USD minimum applies on every stream create/update.
+    </DocsCallout>
+    <DocsCallout title="Base bridge" tone="info">
+      Operator consent, close, withdraw, and credit funding require the worker&apos;s Base operator
+      bridge to be configured (`bridge.enabled: true` in API responses).
+    </DocsCallout>
+  </DocsSection>
+
+  <DocsSection
+    title="Workflow guidance"
+    description="Choose the story type based on the job you are trying to do."
+  >
+    <DocsCallout title="Rule of use" tone="info">
+      Use the showcase story when validating the product-facing integration flow. Use the QA fixture
+      stories when you need state-flow coverage, screenshots, or reproducible runtime conditions.
+    </DocsCallout>
+  </DocsSection>
+</DocsPage>

examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetQA.stories.tsx

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { AiCreditsWidget } from '@goodwidget/ai-credits-widget'
+import {
+  DisconnectedStory,
+  PurchaseSetupStory,
+  QuoteReadyStory,
+  QuoteReadyGoodIdStory,
+  PaymentPendingStory,
+  PaymentConfirmedStory,
+  CreditsManagementStory,
+  InsufficientGBalanceStory,
+  PaymentFailedStory,
+  BackendUnavailableStory,
+  UnsupportedChainStory,
+} from '../helpers/aiCreditsWidgetStories'
+
+const meta: Meta<typeof AiCreditsWidget> = {
+  title: 'QA/AiCreditsWidget/Runtime Fixtures',
+  component: AiCreditsWidget,
+  tags: ['autodocs', 'qa'],
+  parameters: { layout: 'padded' },
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Disconnected: Story = {
+  render: () => <DisconnectedStory />,
+}
+
+export const PurchaseSetup: Story = {
+  render: () => <PurchaseSetupStory />,
+}
+
+export const QuoteReady: Story = {
+  render: () => <QuoteReadyStory />,
+}
+
+export const QuoteReadyGoodId: Story = {
+  render: () => <QuoteReadyGoodIdStory />,
+}
+
+export const PaymentPending: Story = {
+  render: () => <PaymentPendingStory />,
+}
+
+export const PaymentConfirmed: Story = {
+  render: () => <PaymentConfirmedStory />,
+}
+
+export const CreditsManagement: Story = {
+  render: () => <CreditsManagementStory />,
+}
+
+export const InsufficientGBalance: Story = {
+  render: () => <InsufficientGBalanceStory />,
+}
+
+export const PaymentFailed: Story = {
+  render: () => <PaymentFailedStory />,
+}
+
+export const BackendUnavailable: Story = {
+  render: () => <BackendUnavailableStory />,
+}
+
+export const UnsupportedChain: Story = {
+  render: () => <UnsupportedChainStory />,
+}

examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetShowcase.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { AiCreditsWidget } from '@goodwidget/ai-credits-widget'
+import { InjectedWalletStory, MockBackendStory } from '../helpers/aiCreditsWidgetStories'
+
+const meta: Meta<typeof AiCreditsWidget> = {
+  title: 'Widgets/AiCreditsWidget/Showcase',
+  component: AiCreditsWidget,
+  tags: ['integrator', 'manual', 'showcase'],
+  parameters: { layout: 'padded' },
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const MockBackend: Story = {
+  name: 'Mock Backend (browser wallet)',
+  render: () => <MockBackendStory />,
+}
+
+export const InjectedWallet: Story = {
+  name: 'Injected Wallet',
+  render: () => <InjectedWalletStory />,
+}