@cedros/pay-react 0.1.0 → 1.0.0

package/README.md

@@ -5,65 +5,150 @@
 [![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/cedros-tech/pay-react)
+[![Tests](https://img.shields.io/badge/tests-55%20passed-brightgreen)](https://github.com/CedrosPay/react)
 
-> **Unified payments for humans and agents — from Solana Beach to the web.**
+> **Add crypto to your store without building crypto.**
 
-## ⚠️ BREAKING CHANGES (v2.0.0+)
+One React component for Stripe and Solana USDC. Uses your existing products. No deposit wallets. No monitoring. No custom crypto backend.
 
-**Version 2.0.0 introduces security improvements that require backend updates.**
+---
 
-### What Changed
+## 🎯 What is Cedros Pay?
 
-- **NEW:** API v1 versioning (`/paywall/v1/*` endpoints) for stable API contracts
-- **NEW:** Generic endpoints (`/paywall/v1/quote`, `/paywall/v1/verify`) prevent resource ID leakage
-- **REMOVED:** Resource-specific endpoints (`/paywall/{resource}`, `/paywall/cart/{id}`)
-- **SECURITY:** Resource IDs now sent in request bodies and X-PAYMENT headers (not URLs)
+**One component, two payment rails.** Stripe for cards, Solana USDC for wallets. No second checkout.
 
-## 🌅 Why Cedros Pay?
+Built as a nod to **Solana Beach's Cedros Avenue**, 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.
 
-Built as a nod to **Solana Beach’s Cedros Avenue**, Cedros Pay embodies the connection between **old-world payments and new-world rails** — Stripe’s fiat system and Solana’s instant, decentralized network.
+### The Problem with Traditional Crypto Payments
 
-Whether you're building a paywalled blog, an agentic API, or a marketplace, Cedros Pay handles both sides:
+Adding crypto to your store traditionally requires:
 
-- Stripe-hosted checkout for credit/debit cards.
-- x402-verified USDC payments for instant crypto settlement.
+- Creating deposit wallets per user
+- Monitoring deposits 24/7
+- Sweeping funds to your merchant wallet
+- Storing wallet state in your database
+- Building Stripe separately
+- Maintaining two systems
 
----
+**Time:** 3-8 weeks | **Risk:** Custody risk | **Cost:** More DevOps
 
-## 🧩 Architecture
+### The Cedros Pay Solution
 
+```tsx
+<CedrosPay
+  resource="your-product-id" // from your DB
+  onPaymentSuccess={(txId) => unlockContent(txId)}
+/>
 ```
-Frontend (React)  →  Cedros Server  →  Stripe & Solana RPC
-  |                        |
-  |---- x402 headers ----> |---- Stripe webhooks ----> DB
-```
 
-**Frontend**
+**Time:** ~15 minutes | **Risk:** No custody | **Cost:** Less DevOps
+
+---
+
+## 🧩 How It Works (x402)
 
-- React SDK (`@cedros/pay-react`) for drop-in payment buttons.
-- Uses wallet adapters for Solana and Stripe JS SDK for fiat.
+x402 makes Solana payments stateless. The client includes a signed transaction with the request. Your backend verifies it on-chain and unlocks the resource.
 
-**Backend**
+**Flow:**
 
-- Go service handling session creation, webhooks, x402 verification, and route protection.
-- Deploy standalone or embed into existing backend.
+```
+Traditional:
+User → Deposit Wallet (you manage) → Monitor → Sweep → Merchant
+         ↓
+  Store state in DB
+         ↓
+  Custody risk
+
+x402:
+User → Sign Transaction → Your Backend → Verify On-Chain → Merchant (Direct)
+```
+
+**Three key benefits:**
+
+- No deposit wallets
+- No sweeping funds
+- No payment state in your DB
 
 ---
 
 ## 💳 Key Features
 
-- 🪙 **Dual payment support** — Card + Crypto
-- ⚡ **Instant agentic payments** — Pay per request via x402
-- 🔐 **Stateless & secure** — No need for user accounts or deposit addresses
+### 1. One Component, Two Rails
+
+Stripe for cards, Solana USDC for wallets. No second checkout.
+
+```tsx
+<CedrosPay resource="product-1" />
+// Both payment methods work
+```
+
+### 2. Works With Your Products
+
+Pass your DB ID. No new schema.
+
+```tsx
+<CedrosPay resource="existing-product-123" />
+// resource = your database primary key
+```
+
+### 3. Real Ecommerce, Not Just a Button
+
+Carts, coupons, refunds, metadata.
+
+```tsx
+<CedrosPay
+  items={[{ resource: "item-1", quantity: 2 }]}
+  couponCode="LAUNCH50"
+/>
+```
+
+### 4. Auto-Detects Wallet
+
+No wallet: card only. Wallet: card and crypto.
+
+```tsx
+// User without wallet sees:
+[Pay with Card] button
+
+// User with Phantom sees:
+[Pay with Card] [Pay with Crypto]
+```
+
+### 5. Agent-Ready
+
+x402 over HTTP; agents pay per request.
+
+```bash
+GET /api/premium-data
+X-PAYMENT: <signed-transaction>
+# Agent gets data instantly
+```
+
+### 6. Self-Host or Roll Your Own
+
+React UI + Go backend. Open API.
+
+```tsx
+<CedrosPay
+  resource="item"
+  wallets={customWallets}
+  renderModal={CustomModal}
+/>
+```
+
+**Additional Features:**
+
 - 🌍 **Open source** — MIT-licensed and extensible
+- 🔐 **Stateless & secure** — No user accounts or deposit addresses required
 - 🧱 **Minimal integration** — Middleware or proxy for Go APIs
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Quick Start (3 Steps in ~3 Minutes)
 
-### Installation
+If you can wrap a provider, you can ship dual payments.
+
+### Step 1: Install
 
 **Option 1: Stripe + Crypto (Full Features)**
 
@@ -185,10 +270,12 @@ function App() {
 <CedrosPay resource="item-id" display={{ showCrypto: false }} />
 ```
 
-### Basic Usage
+### Step 2: Configure Provider
+
+Wrap your app with credentials + cluster:
 
 ```tsx
-import { CedrosPay, CedrosProvider } from "@cedros/pay-react";
+import { CedrosProvider } from "@cedros/pay-react";
 import "@cedros/pay-react/style.css";
 
 function App() {
@@ -196,26 +283,49 @@ function App() {
     <CedrosProvider
       config={{
         stripePublicKey: "pk_test_...",
-        serverUrl: window.location.origin,
+        serverUrl: "https://your-api.com",
         solanaCluster: "mainnet-beta",
-        // serverUrl defaults to window.location.origin
-        // Only needed if your backend is on a different domain
       }}
     >
-      <CedrosPay
-        resource="demo-item-id-1"
-        callbacks={{
-          onPaymentSuccess: (result) =>
-            console.log("Payment successful!", result.transactionId),
-          onPaymentError: (error) =>
-            console.error("Payment failed:", error.message),
-        }}
-      />
+      <YourApp />
     </CedrosProvider>
   );
 }
 ```
 
+### Step 3: Drop in the Component
+
+On success → fulfill order:
+
+```tsx
+import { CedrosPay } from "@cedros/pay-react";
+
+function Checkout() {
+  return (
+    <CedrosPay
+      resource="your-product-id"
+      callbacks={{
+        onPaymentSuccess: (result) => {
+          // Unlock content / fulfill order
+          unlockContent(result.transactionId);
+        },
+      }}
+    />
+  );
+}
+```
+
+**Total time:** ~3 minutes
+
+**Backend options:** Use the Go server, or implement the open API.
+
+**Links:**
+
+- [Backend setup →](https://github.com/CedrosPay/server)
+- [Full docs →](https://github.com/CedrosPay/react)
+- [Example apps →](https://github.com/CedrosPay/react/tree/main/stories)
+- [Storybook →](https://github.com/CedrosPay/react#-storybook-development)
+
 **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`:
 
@@ -1679,6 +1789,7 @@ function PaymentButton() {
 This means `VITE_SOLANA_RPC_URL` or `VITE_STORYBOOK_SOLANA_ENDPOINT` is missing or empty in your `.env` file.
 
 **Fix:**
+
 ```bash
 # Add to .env
 VITE_SOLANA_RPC_URL=https://api.devnet.solana.com
@@ -1691,6 +1802,7 @@ VITE_STORYBOOK_SOLANA_ENDPOINT=https://api.devnet.solana.com
 The `VITE_SERVER_URL` or `VITE_STORYBOOK_SERVER_URL` is missing.
 
 **Fix:**
+
 ```bash
 # Add to .env
 VITE_SERVER_URL=http://localhost:8080

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedros/pay-react",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "React frontend library for Cedros Pay - unified Stripe and Solana x402 payments",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",