@cedros/pay-react 1.0.5 → 1.1.2

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)
+
+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 + Go backend. Open API.
+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.
 
 ---
 
@@ -1148,6 +1178,23 @@ import { CryptoSubscribeButton } from "@cedros/pay-react";
 />;
 ```
 
+**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
@@ -1387,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
@@ -1427,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)
 
 ---
 
@@ -1678,8 +1830,8 @@ We follow [Semantic Versioning](https://semver.org/):
 
 **These exports are guaranteed stable** and follow semantic versioning:
 
-- ✅ **Components** - All exported React components (CedrosPay, StripeButton, CryptoButton, SubscribeButton, CryptoSubscribeButton, SubscriptionManagementPanel, etc.)
-- ✅ **Hooks** - useCedrosContext, useStripeCheckout, useX402Payment, useSubscription, useCryptoSubscription, useSubscriptionManagement, etc.
+- ✅ **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