@cedros/pay-react 1.0.4 → 1.1.0

package/README.md

@@ -5,19 +5,26 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue.svg)](https://www.typescriptlang.org/)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@cedros/pay-react)](https://bundlephobia.com/package/@cedros/pay-react)
 [![Stripe-only: <100KB](https://img.shields.io/badge/stripe--only-%3C100KB-success)]()
-[![Tests](https://img.shields.io/badge/tests-55%20passed-brightgreen)](https://github.com/CedrosPay/react)
+[![Tests](https://img.shields.io/badge/tests-55%20passed-brightgreen)](https://github.com/conorholds/cedros-pay/tree/main/ui)
 
-> **Add crypto to your store without building crypto.**
+> **Three payment rails. One React component.**
 
-One React component for Stripe and Solana USDC. Uses your existing products. No deposit wallets. No monitoring. No custom crypto backend.
+Stripe for cards. Solana USDC for wallets. Credits for cedros-login users. Uses your existing products. No deposit wallets. No monitoring. No custom crypto backend.
 
 ---
 
+## Ecommerce UI (Cedros Shop)
+
+This repo now includes a provider-agnostic storefront UI layer (catalog + cart + checkout orchestration) built in a shadcn-inspired style.
+
+- Docs: `docs/ecommerce/README.md`
+- Import: `import { ecommerce } from '@cedros/pay-react'`
+
 ## What is Cedros Pay?
 
-**One component, two payment rails.** Stripe for cards, Solana USDC for wallets. No second checkout.
+**One component, three payment rails.** Stripe for cards, Solana USDC for wallets, Credits for account balances. No second checkout.
 
-Cedros Pay connects traditional payments (Stripe) with crypto (Solana x402) using the product IDs you already have. No deposit wallets to manage. No wallet infrastructure to secure. No custody risk.
+Cedros Pay connects traditional payments (Stripe) with crypto (Solana x402) and account credits (cedros-login) using the product IDs you already have. No deposit wallets to manage. No wallet infrastructure to secure. No custody risk.
 
 ### The Problem with Traditional Crypto Payments
 
@@ -69,13 +76,13 @@ User → Sign Transaction → Your Backend → Verify On-Chain → Merchant (Dir
 
 ## Key Features
 
-### 1. One Component, Two Rails
+### 1. One Component, Three Rails
 
-Stripe for cards, Solana USDC for wallets. No second checkout.
+Stripe for cards, Solana USDC for wallets, Credits for account balances. No second checkout.
 
 ```tsx
 <CedrosPay resource="product-1" />
-// Both payment methods work
+// All three payment methods work
 ```
 
 ### 2. Works With Your Products
@@ -98,16 +105,19 @@ Carts, coupons, refunds, metadata.
 />
 ```
 
-### 4. Auto-Detects Wallet
+### 4. Auto-Detects Payment Options
 
-No wallet: card only. Wallet: card and crypto.
+Shows available payment methods based on user context.
 
 ```tsx
-// User without wallet sees:
-[Pay with Card] button
+// User without wallet, not logged in:
+[Pay with Card]
 
-// User with Phantom sees:
+// User with Phantom wallet:
 [Pay with Card] [Pay with Crypto]
+
+// User logged into cedros-login:
+[Pay with Card] [Pay with Crypto] [Pay with Credits]
 ```
 
 ### 5. Agent-Ready
@@ -120,9 +130,29 @@ X-PAYMENT: <signed-transaction>
 # Agent gets data instantly
 ```
 
-### 6. Self-Host or Roll Your Own
+### 6. Credits Payment (cedros-login)
 
-React UI + Go backend. Open API.
+Let users pay with account credits. Instant, zero-fee payments.
+
+```tsx
+import { useCedrosLogin } from '@cedros/login-react';
+
+function Checkout() {
+  const { authToken } = useCedrosLogin();
+
+  return (
+    <CedrosPay
+      resource="product-1"
+      display={{ showCredits: !!authToken }}
+      checkout={{ authToken }}
+    />
+  );
+}
+```
+
+### 7. Self-Host or Roll Your Own
+
+React UI + Rust backend. Open API.
 
 ```tsx
 <CedrosPay resource="item" wallets={customWallets} renderModal={CustomModal} />
@@ -132,13 +162,13 @@ React UI + Go backend. Open API.
 
 - 🌍 **Open source** — MIT-licensed and extensible
 - 🔐 **Stateless & secure** — No user accounts or deposit addresses required
-- 🧱 **Minimal integration** — Middleware or proxy for Go APIs
+- 🧱 **Minimal integration** — Middleware or proxy for Rust APIs
 
 ---
 
 ## Quick Start (3 Steps in ~3 Minutes)
 
-If you can wrap a provider, you can ship dual payments.
+If you can wrap a provider, you can ship triple-rail payments.
 
 ### Step 1: Install
 
@@ -301,13 +331,13 @@ function Checkout() {
 }
 ```
 
-**Backend options:** Use the Go server, or implement the open API.
+**Backend options:** Use the Rust server, or implement the open API.
 
 **Links:**
 
-- [Backend setup →](https://github.com/CedrosPay/server)
+- [Backend setup →](https://github.com/conorholds/cedros-pay/tree/main/server)
 - [Full docs →](https://docs.cedrospay.com)
-- [Example apps →](https://github.com/CedrosPay/react/tree/main/examples)
+- [Example apps →](https://github.com/conorholds/cedros-pay/tree/main/ui/tree/main/examples)
 
 **Cross-Domain Backend (Optional):**
 If your backend is on a different domain (e.g., `api.example.com` while your frontend is on `example.com`), explicitly set `serverUrl`:
@@ -329,7 +359,7 @@ If your backend is on a different domain (e.g., `api.example.com` while your fro
 Your backend must implement the Cedros Pay API endpoints:
 
 ```bash
-go get github.com/cedros-pay/server
+cargo install cedros-pay-server
 ```
 
 **Required Endpoints (v2.0.0+):**
@@ -417,7 +447,7 @@ X-Signer: <admin-wallet-address>
 # Response: [{ refundId, originalPurchaseId, recipientWallet, amount, token, reason, ... }]
 ```
 
-See [Backend Integration](https://github.com/CedrosPay/server) and `@backend-migration-resource-leakage.md` for complete API reference and migration guide.
+See [Backend Integration](https://github.com/conorholds/cedros-pay/tree/main/server) and `@backend-migration-resource-leakage.md` for complete API reference and migration guide.
 
 ---
 
@@ -1115,6 +1145,129 @@ const newReq: v2.X402Requirement = { maxAmountRequired: 1000000n };
 />
 ```
 
+### Subscriptions
+
+Cedros Pay supports recurring subscriptions with both Stripe and crypto (x402) payments.
+
+**Stripe Subscription Checkout:**
+
+```tsx
+import { SubscribeButton } from "@cedros/pay-react";
+
+<SubscribeButton
+  resource="plan-pro"
+  interval="monthly"
+  trialDays={14}
+  onSubscriptionSuccess={(result) => {
+    console.log("Subscribed:", result.subscriptionStatus);
+  }}
+/>;
+```
+
+**Crypto Subscription (x402):**
+
+```tsx
+import { CryptoSubscribeButton } from "@cedros/pay-react";
+
+<CryptoSubscribeButton
+  resource="plan-pro"
+  interval="monthly"
+  onSubscriptionSuccess={(result) => {
+    console.log("Subscription active until:", result.expiresAt);
+  }}
+/>;
+```
+
+**Credits Subscription (cedros-login):**
+
+```tsx
+import { CreditsSubscribeButton } from "@cedros/pay-react";
+
+<CreditsSubscribeButton
+  resource="plan-pro"
+  interval="monthly"
+  authToken={user.cedrosToken}
+  userId={user.id}
+  autoCheckStatus
+  onSubscriptionSuccess={(result) => {
+    console.log("Subscription active until:", result.expiresAt);
+  }}
+/>;
+```
+
+**Subscription Management (Upgrade/Downgrade/Cancel):**
+
+```tsx
+import { SubscriptionManagementPanel } from "@cedros/pay-react";
+
+<SubscriptionManagementPanel
+  resource="plan-pro"
+  userId="user@example.com"
+  availablePlans={[
+    { resource: "plan-basic", name: "Basic", price: 999, currency: "USD", interval: "monthly" },
+    { resource: "plan-pro", name: "Pro", price: 1999, currency: "USD", interval: "monthly" },
+    { resource: "plan-enterprise", name: "Enterprise", price: 4999, currency: "USD", interval: "monthly" },
+  ]}
+  onSubscriptionChanged={(newResource) => console.log("Changed to:", newResource)}
+  onSubscriptionCanceled={() => console.log("Subscription canceled")}
+  showBillingPortal
+/>;
+```
+
+**Programmatic Subscription Management:**
+
+```tsx
+import { useSubscriptionManagement } from "@cedros/pay-react";
+
+function SubscriptionSettings({ userId }: { userId: string }) {
+  const {
+    subscription,
+    status,
+    loadSubscription,
+    previewChange,
+    changeSubscription,
+    cancelSubscription,
+    openBillingPortal,
+  } = useSubscriptionManagement();
+
+  useEffect(() => {
+    loadSubscription("plan-pro", userId);
+  }, [userId]);
+
+  const handleUpgrade = async () => {
+    // Preview proration before confirming
+    const preview = await previewChange("plan-pro", "plan-enterprise", userId);
+    if (preview && confirm(`Upgrade for $${preview.immediateAmount / 100}?`)) {
+      await changeSubscription({ newResource: "plan-enterprise" });
+    }
+  };
+
+  return (
+    <div>
+      {subscription && (
+        <>
+          <p>Plan: {subscription.resource}</p>
+          <p>Status: {subscription.status}</p>
+          <button onClick={handleUpgrade}>Upgrade to Enterprise</button>
+          <button onClick={() => cancelSubscription(false)}>Cancel at Period End</button>
+          <button onClick={() => openBillingPortal(userId)}>Manage Billing</button>
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+**Billing Intervals:** `weekly`, `monthly`, `yearly`, `custom`
+
+**Subscription Features:**
+
+- Trial periods (Stripe)
+- Proration on plan changes
+- Immediate or period-end cancellation
+- Stripe billing portal integration
+- Backend-verified subscription status for x402 gating
+
 ### Coupon Codes
 
 ```tsx
@@ -1281,6 +1434,109 @@ For complete control over styling, use the `unstyled` prop to disable all defaul
 
 ---
 
+## Admin Dashboard
+
+Cedros Pay includes a complete admin dashboard for managing your store. Use it standalone or combine it with cedros-login for a unified admin experience.
+
+### Standalone Dashboard
+
+Drop in `<CedrosPayAdminDashboard />` for a complete payment admin interface:
+
+```tsx
+import { CedrosPayAdminDashboard } from "@cedros/pay-react";
+
+function AdminPage() {
+  return (
+    <CedrosPayAdminDashboard
+      serverUrl="https://api.example.com"
+      title="My Store"
+      defaultSection="transactions"
+    />
+  );
+}
+```
+
+**Available Sections:**
+
+| Section | Description |
+|---------|-------------|
+| `transactions` | Payment history with filtering by method |
+| `products` | Manage products, pricing, and variations |
+| `subscriptions` | Configure subscription plans |
+| `coupons` | Create and manage discount codes |
+| `refunds` | Process refund requests |
+| `storefront` | Customize shop layout and appearance |
+| `ai-settings` | Configure AI-powered features |
+| `payment-settings` | Payment method configuration |
+| `messaging` | Email and notification templates |
+| `settings` | Server and integration settings |
+
+### Unified Dashboard with Plugin System
+
+For apps using both **cedros-login** and **cedros-pay**, use cedros-login's `AdminShell` component with the `cedrosPayPlugin` to create a combined admin interface:
+
+```tsx
+import { AdminShell, cedrosLoginPlugin, useCedrosLogin } from "@cedros/login-react";
+import { cedrosPayPlugin } from "@cedros/pay-react";
+
+function UnifiedAdmin() {
+  const { user, getAccessToken, serverUrl } = useCedrosLogin();
+
+  // Build host context from your auth providers
+  const hostContext = {
+    cedrosLogin: {
+      user,
+      getAccessToken,
+      serverUrl,
+    },
+    cedrosPay: {
+      serverUrl: "https://api.example.com",
+    },
+  };
+
+  return (
+    <AdminShell
+      title="Admin Dashboard"
+      plugins={[cedrosLoginPlugin, cedrosPayPlugin]}
+      hostContext={hostContext}
+      defaultSection="cedros-pay:transactions"
+    />
+  );
+}
+```
+
+> **Note:** The `AdminShell` component is provided by `@cedros/login-react`. This package only exports the `cedrosPayPlugin` for use with their shell.
+
+### cedrosPayPlugin Sections
+
+The plugin registers these sections for the unified dashboard:
+
+| Section ID | Group | Description |
+|------------|-------|-------------|
+| `transactions` | Store | Payment transactions |
+| `products` | Store | Product management |
+| `subscriptions` | Store | Subscription plans |
+| `coupons` | Store | Coupon management |
+| `refunds` | Store | Refund requests |
+| `storefront` | Configuration | Storefront settings |
+| `ai-settings` | Configuration | AI assistant settings |
+| `payment-settings` | Configuration | Payment method toggles |
+| `messaging` | Configuration | Email/webhook settings |
+| `settings` | Configuration | Server configuration |
+
+### Section Addressing
+
+Sections are addressed using the format `pluginId:sectionId`:
+
+- `cedros-pay:transactions` - Cedros Pay transactions
+- `cedros-pay:products` - Cedros Pay products
+- `cedros-login:users` - Cedros Login user management
+- `cedros-login:orgs` - Cedros Login organizations
+
+See the [cedros-login documentation](https://github.com/cedros-dev/cedros-login) for full `AdminShell` API reference and custom plugin creation.
+
+---
+
 ## Props Reference
 
 ### CedrosProvider Configuration
@@ -1321,24 +1577,26 @@ For complete control over styling, use the `unstyled` prop to disable all defaul
 
 #### Display Options
 
-| Field         | Type                         | Description                         |
-| ------------- | ---------------------------- | ----------------------------------- |
-| `cardLabel`   | `string`                     | Stripe button label                 |
-| `cryptoLabel` | `string`                     | Crypto button label                 |
-| `showCard`    | `boolean`                    | Show Stripe button (default: true)  |
-| `showCrypto`  | `boolean`                    | Show crypto button (default: true)  |
-| `layout`      | `'vertical' \| 'horizontal'` | Button layout (default: 'vertical') |
-| `className`   | `string`                     | Custom CSS class                    |
+| Field          | Type                         | Description                          |
+| -------------- | ---------------------------- | ------------------------------------ |
+| `cardLabel`    | `string`                     | Stripe button label                  |
+| `cryptoLabel`  | `string`                     | Crypto button label                  |
+| `creditsLabel` | `string`                     | Credits button label                 |
+| `showCard`     | `boolean`                    | Show Stripe button (default: true)   |
+| `showCrypto`   | `boolean`                    | Show crypto button (default: true)   |
+| `showCredits`  | `boolean`                    | Show credits button (default: false) |
+| `layout`       | `'vertical' \| 'horizontal'` | Button layout (default: 'vertical')  |
+| `className`    | `string`                     | Custom CSS class                     |
 
 #### Callback Options
 
-| Field              | Type                                     | Description                  |
-| ------------------ | ---------------------------------------- | ---------------------------- |
-| `onPaymentSuccess` | `(result: PaymentSuccessResult) => void` | Called on successful payment |
-| `onPaymentError`   | `(error: PaymentErrorDetail) => void`    | Called on payment error      |
-| `onPaymentAttempt` | `(method: 'stripe' \| 'crypto') => void` | Called when payment starts   |
+| Field              | Type                                                  | Description                  |
+| ------------------ | ----------------------------------------------------- | ---------------------------- |
+| `onPaymentSuccess` | `(result: PaymentSuccessResult) => void`              | Called on successful payment |
+| `onPaymentError`   | `(error: PaymentErrorDetail) => void`                 | Called on payment error      |
+| `onPaymentAttempt` | `(method: 'stripe' \| 'crypto' \| 'credits') => void` | Called when payment starts   |
 
-[Full API Reference →](https://github.com/CedrosPay/react/tree/main/stories)
+[Full API Reference →](https://github.com/conorholds/cedros-pay/tree/main/ui/tree/main/stories)
 
 ---
 
@@ -1572,9 +1830,9 @@ We follow [Semantic Versioning](https://semver.org/):
 
 **These exports are guaranteed stable** and follow semantic versioning:
 
-- ✅ **Components** - All exported React components (CedrosPay, StripeButton, CryptoButton, etc.)
-- ✅ **Hooks** - useCedrosContext, useStripeCheckout, useX402Payment, etc.
-- ✅ **Manager Interfaces** - IStripeManager, IX402Manager, IWalletManager, IRouteDiscoveryManager
+- ✅ **Components** - All exported React components (CedrosPay, StripeButton, CryptoButton, CreditsButton, SubscribeButton, CryptoSubscribeButton, CreditsSubscribeButton, SubscriptionManagementPanel, etc.)
+- ✅ **Hooks** - useCedrosContext, useStripeCheckout, useX402Payment, useCreditsPayment, useSubscription, useCryptoSubscription, useCreditsSubscription, useSubscriptionManagement, etc.
+- ✅ **Manager Interfaces** - IStripeManager, IX402Manager, IWalletManager, ISubscriptionManager, ISubscriptionChangeManager, IRouteDiscoveryManager
 - ✅ **Types** - All types exported via versioned namespaces (v1, v2, etc.)
 - ✅ **Utilities** - validateConfig, parseCouponCodes, rate limiters, logging, events