@stripe-sdk/core 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,8 @@
 # @stripe-sdk/core
 
-SDK Stripe **cle en main** pour vos applications. Integrez les paiements, abonnements, factures, webhooks, marketplace et plus en quelques lignes. Compatible React, Next.js, Vue, Angular et tout framework JavaScript.
+A **turnkey** Stripe SDK for your applications. Integrate payments, subscriptions, invoices, webhooks, marketplace and more in just a few lines. Compatible with React, Next.js, Vue, Angular and any JavaScript framework.
+
+**[Documentation: English](docs/en/) | [Documentation: Francais](docs/fr/)**
 
 ## Installation
 
@@ -8,9 +10,11 @@ SDK Stripe **cle en main** pour vos applications. Integrez les paiements, abonne
 npm install @stripe-sdk/core stripe @stripe/stripe-js @stripe/react-stripe-js
 ```
 
-## Configuration
+> For server-only usage (no React), you only need: `npm install @stripe-sdk/core stripe`
+
+## Quick Start
 
-### 1. Variables d'environnement
+### 1. Environment Variables
 
 ```env
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
@@ -18,7 +22,7 @@ STRIPE_SECRET_KEY=sk_test_...
 STRIPE_WEBHOOK_SECRET=whsec_...
 ```
 
-### 2. Initialisation (serveur)
+### 2. Server Initialization
 
 ```ts
 // lib/stripe.ts
@@ -33,22 +37,22 @@ export const stripe = initStripe({
 
 ---
 
-## Paiements
+## Payments
 
-### Paiement simple avec formulaire integre
+### Simple Payment with Built-in Form
 
-**Serveur** - Creer un PaymentIntent :
+**Server** - Create a PaymentIntent:
 
 ```ts
 // app/api/create-payment/route.ts
-import '@/lib/stripe'; // initialise Stripe
+import '@/lib/stripe';
 import { createPaymentIntent } from '@stripe-sdk/core/server';
 
 export async function POST(req: Request) {
   const { amount } = await req.json();
 
   const result = await createPaymentIntent({
-    amount,      // en centimes (1000 = 10.00 EUR)
+    amount,      // in cents (1000 = 10.00 EUR)
     currency: 'eur',
   });
 
@@ -60,7 +64,7 @@ export async function POST(req: Request) {
 }
 ```
 
-**Client** - Formulaire de paiement :
+**Client** - Payment form:
 
 ```tsx
 // app/checkout/page.tsx
@@ -89,7 +93,7 @@ export default function CheckoutPage() {
       <CheckoutForm
         onSuccess={(id) => console.log('Paid!', id)}
         onError={(err) => console.error(err)}
-        submitLabel="Payer 20 EUR"
+        submitLabel="Pay 20 EUR"
         showEmail
       />
     </StripeElementsProvider>
@@ -97,26 +101,25 @@ export default function CheckoutPage() {
 }
 ```
 
-### Checkout Session (page Stripe hebergee)
+### Checkout Session (Stripe-hosted page)
 
 ```ts
-// Server
 import { createCheckoutSession } from '@stripe-sdk/core/server';
 
 const result = await createCheckoutSession({
   mode: 'payment',
   lineItems: [{ priceId: 'price_xxx', quantity: 1 }],
-  successUrl: 'https://monsite.com/success?session_id={CHECKOUT_SESSION_ID}',
-  cancelUrl: 'https://monsite.com/cancel',
+  successUrl: 'https://mysite.com/success?session_id={CHECKOUT_SESSION_ID}',
+  cancelUrl: 'https://mysite.com/cancel',
   automaticTax: true,
   allowPromotionCodes: true,
 });
 
-// Redirect le client vers result.data.url
+// Redirect the user to result.data.url
 ```
 
 ```tsx
-// Client - redirect vers Checkout
+// Client - redirect to Checkout
 import { useCheckout } from '@stripe-sdk/core/client';
 
 function BuyButton() {
@@ -130,11 +133,11 @@ function BuyButton() {
     await redirectToCheckout(sessionId);
   };
 
-  return <button onClick={handleClick} disabled={isLoading}>Acheter</button>;
+  return <button onClick={handleClick} disabled={isLoading}>Buy Now</button>;
 }
 ```
 
-### Payment Link (sans code)
+### Payment Link (no-code)
 
 ```ts
 import { createPaymentLink } from '@stripe-sdk/core/server';
@@ -144,22 +147,21 @@ const result = await createPaymentLink({
   allowPromotionCodes: true,
   afterCompletion: {
     type: 'redirect',
-    redirectUrl: 'https://monsite.com/merci',
+    redirectUrl: 'https://mysite.com/thank-you',
   },
 });
 
-console.log(result.data.url); // Lien partageable
+console.log(result.data.url); // Shareable link
 ```
 
 ---
 
-## Abonnements
-
-### Creer un abonnement
+## Subscriptions
 
 ```ts
-import { createSubscription } from '@stripe-sdk/core/server';
+import { createSubscription, updateSubscription, cancelSubscription, resumeSubscription } from '@stripe-sdk/core/server';
 
+// Create
 const result = await createSubscription({
   customerId: 'cus_xxx',
   priceId: 'price_monthly_xxx',
@@ -167,39 +169,24 @@ const result = await createSubscription({
   paymentBehavior: 'default_incomplete',
 });
 
-// result.data.latest_invoice.payment_intent.client_secret
-// -> utiliser avec StripeElementsProvider pour confirmer le paiement
-```
-
-### Changer de plan
-
-```ts
-import { updateSubscription } from '@stripe-sdk/core/server';
-
+// Change plan
 await updateSubscription({
   subscriptionId: 'sub_xxx',
   items: [{ id: 'si_xxx', priceId: 'price_annual_xxx' }],
   prorationBehavior: 'create_prorations',
 });
-```
-
-### Annuler / Reprendre
-
-```ts
-import { cancelSubscription, resumeSubscription } from '@stripe-sdk/core/server';
 
-// Annuler a la fin de la periode
+// Cancel at period end
 await cancelSubscription({
   subscriptionId: 'sub_xxx',
   cancelAtPeriodEnd: true,
-  cancellationDetails: { feedback: 'too_expensive' },
 });
 
-// Reprendre
+// Resume
 await resumeSubscription('sub_xxx');
 ```
 
-### Composant PricingTable
+### PricingTable Component
 
 ```tsx
 import { PricingTable, type PricingPlan } from '@stripe-sdk/core/client';
@@ -212,7 +199,7 @@ const plans: PricingPlan[] = [
     amount: 900,
     currency: 'eur',
     interval: 'month',
-    features: ['5 projets', '1 Go stockage', 'Support email'],
+    features: ['5 projects', '1 GB storage', 'Email support'],
   },
   {
     id: 'pro',
@@ -221,9 +208,9 @@ const plans: PricingPlan[] = [
     amount: 2900,
     currency: 'eur',
     interval: 'month',
-    features: ['Projets illimites', '100 Go stockage', 'Support prioritaire', 'API access'],
+    features: ['Unlimited projects', '100 GB storage', 'Priority support', 'API access'],
     highlighted: true,
-    badge: 'Populaire',
+    badge: 'Popular',
   },
 ];
 
@@ -234,101 +221,53 @@ const plans: PricingPlan[] = [
 />
 ```
 
-### Composant SubscriptionManager
-
-```tsx
-import { SubscriptionManager } from '@stripe-sdk/core/client';
-
-<SubscriptionManager
-  subscription={{
-    id: 'sub_xxx',
-    status: 'active',
-    planName: 'Pro',
-    amount: 2900,
-    currency: 'eur',
-    interval: 'month',
-    currentPeriodEnd: '2025-03-01',
-    cancelAtPeriodEnd: false,
-  }}
-  onCancel={async (id) => {
-    await fetch(`/api/subscriptions/${id}/cancel`, { method: 'POST' });
-  }}
-  onResume={async (id) => {
-    await fetch(`/api/subscriptions/${id}/resume`, { method: 'POST' });
-  }}
-  onManageBilling={() => window.location.href = '/api/portal'}
-/>
-```
-
 ---
 
-## Clients
+## Customers
 
 ```ts
 import {
-  createCustomer,
-  retrieveCustomer,
-  updateCustomer,
-  deleteCustomer,
-  listCustomers,
-  searchCustomers,
+  createCustomer, retrieveCustomer, updateCustomer,
+  deleteCustomer, listCustomers, searchCustomers,
 } from '@stripe-sdk/core/server';
 
-// Creer
 const { data: customer } = await createCustomer({
   email: 'user@example.com',
   name: 'John Doe',
   metadata: { userId: 'usr_123' },
 });
 
-// Rechercher
 const { data: results } = await searchCustomers("email:'user@example.com'");
-
-// Mettre a jour
-await updateCustomer({
-  customerId: 'cus_xxx',
-  name: 'Jane Doe',
-  defaultPaymentMethodId: 'pm_xxx',
-});
 ```
 
 ---
 
-## Portail Client
+## Customer Portal
 
 ```ts
 import { createPortalSession } from '@stripe-sdk/core/server';
 
-// API route
-export async function POST(req: Request) {
-  const { customerId } = await req.json();
-  const result = await createPortalSession({
-    customerId,
-    returnUrl: 'https://monsite.com/account',
-  });
-  return Response.json({ url: result.data.url });
-}
-
-// Le client est redirige vers le portail Stripe pour gerer
-// ses abonnements, moyens de paiement et factures.
+const result = await createPortalSession({
+  customerId: 'cus_xxx',
+  returnUrl: 'https://mysite.com/account',
+});
+// Redirect user to result.data.url
 ```
 
 ---
 
-## Sauvegarder un moyen de paiement (SetupIntent)
+## Save a Payment Method (SetupIntent)
 
 ```ts
-// Serveur
 import { createSetupIntent } from '@stripe-sdk/core/server';
 
 const result = await createSetupIntent({
   customerId: 'cus_xxx',
-  usage: 'off_session', // pour les paiements futurs sans le client
+  usage: 'off_session',
 });
 ```
 
 ```tsx
-// Client
 import { StripeElementsProvider, SetupForm } from '@stripe-sdk/core/client';
 
 <StripeElementsProvider
@@ -336,65 +275,44 @@ import { StripeElementsProvider, SetupForm } from '@stripe-sdk/core/client';
   clientSecret={setupClientSecret}
 >
   <SetupForm
-    onSuccess={(setupId, pmId) => {
-      console.log('Saved!', pmId);
-    }}
-    submitLabel="Sauvegarder la carte"
+    onSuccess={(setupId, pmId) => console.log('Saved!', pmId)}
+    submitLabel="Save Card"
   />
 </StripeElementsProvider>
 ```
 
 ---
 
-## Produits & Prix
+## Products & Prices
 
 ```ts
-import {
-  createProduct,
-  createPrice,
-  listProducts,
-  listPrices,
-} from '@stripe-sdk/core/server';
+import { createProduct, createPrice, listProducts, listPrices } from '@stripe-sdk/core/server';
 
-// Creer un produit avec prix par defaut
 const { data: product } = await createProduct({
-  name: 'Plan Pro',
-  description: 'Acces complet a la plateforme',
+  name: 'Pro Plan',
   defaultPriceData: {
-    unitAmount: 2900, // 29.00 EUR
+    unitAmount: 2900,
     currency: 'eur',
     recurring: { interval: 'month' },
   },
 });
 
-// Ajouter un prix annuel
 await createPrice({
   productId: product.id,
-  unitAmount: 29000, // 290.00 EUR
+  unitAmount: 29000,
   currency: 'eur',
   recurring: { interval: 'year' },
   lookupKey: 'pro_annual',
 });
-
-// Lister les produits actifs
-const { data: products } = await listProducts({ active: true, limit: 20 });
 ```
 
 ---
 
-## Factures
+## Invoices
 
 ```ts
-import {
-  createInvoice,
-  createInvoiceItem,
-  finalizeInvoice,
-  sendInvoice,
-  listInvoices,
-  getUpcomingInvoice,
-} from '@stripe-sdk/core/server';
+import { createInvoice, createInvoiceItem, finalizeInvoice, sendInvoice } from '@stripe-sdk/core/server';
 
-// Creer et envoyer une facture
 const { data: invoice } = await createInvoice({
   customerId: 'cus_xxx',
   collectionMethod: 'send_invoice',
@@ -404,79 +322,55 @@ const { data: invoice } = await createInvoice({
 await createInvoiceItem({
   customerId: 'cus_xxx',
   invoiceId: invoice.id,
-  amount: 5000, // 50.00 EUR
+  amount: 5000,
   currency: 'eur',
-  description: 'Consulting - Janvier 2025',
+  description: 'Consulting - January 2025',
 });
 
 await finalizeInvoice(invoice.id);
 await sendInvoice(invoice.id);
-
-// Prochaine facture d'un abonnement
-const { data: upcoming } = await getUpcomingInvoice('cus_xxx', 'sub_xxx');
 ```
 
 ---
 
-## Remboursements & Litiges
+## Refunds & Disputes
 
 ```ts
-import {
-  createRefund,
-  listRefunds,
-  retrieveDispute,
-  updateDispute,
-} from '@stripe-sdk/core/server';
+import { createRefund, updateDispute } from '@stripe-sdk/core/server';
 
-// Remboursement total
+// Full refund
 await createRefund({ paymentIntentId: 'pi_xxx' });
 
-// Remboursement partiel
-await createRefund({
-  paymentIntentId: 'pi_xxx',
-  amount: 500, // 5.00 EUR
-  reason: 'requested_by_customer',
-});
+// Partial refund
+await createRefund({ paymentIntentId: 'pi_xxx', amount: 500, reason: 'requested_by_customer' });
 
-// Repondre a un litige
+// Respond to dispute
 await updateDispute({
   disputeId: 'dp_xxx',
-  evidence: {
-    customerName: 'John Doe',
-    productDescription: 'Abonnement SaaS mensuel',
-    serviceDocumentation: 'file_xxx',
-  },
+  evidence: { customerName: 'John Doe', productDescription: 'Monthly SaaS subscription' },
   submit: true,
 });
 ```
 
 ---
 
-## Coupons & Codes Promo
+## Coupons & Promotion Codes
 
 ```ts
-import {
-  createCoupon,
-  createPromotionCode,
-  listPromotionCodes,
-} from '@stripe-sdk/core/server';
+import { createCoupon, createPromotionCode } from '@stripe-sdk/core/server';
 
-// Coupon -20%
 const { data: coupon } = await createCoupon({
   percentOff: 20,
   duration: 'repeating',
   durationInMonths: 3,
-  name: 'Lancement 2025',
+  name: 'Launch 2025',
 });
 
-// Code promo public
 await createPromotionCode({
   couponId: coupon.id,
   code: 'LAUNCH20',
   maxRedemptions: 100,
-  restrictions: {
-    firstTimeTransaction: true,
-  },
+  restrictions: { firstTimeTransaction: true },
 });
 ```
 
@@ -485,41 +379,22 @@ await createPromotionCode({
 ## Stripe Connect (Marketplace)
 
 ```ts
-import {
-  createConnectAccount,
-  createAccountLink,
-  createTransfer,
-  getBalance,
-} from '@stripe-sdk/core/server';
+import { createConnectAccount, createAccountLink, createTransfer, getBalance } from '@stripe-sdk/core/server';
 
-// Creer un compte vendeur
 const { data: account } = await createConnectAccount({
   type: 'express',
   email: 'seller@example.com',
-  capabilities: {
-    cardPayments: { requested: true },
-    transfers: { requested: true },
-  },
+  capabilities: { cardPayments: { requested: true }, transfers: { requested: true } },
 });
 
-// Lien d'onboarding
 const { data: link } = await createAccountLink({
   accountId: account.id,
-  refreshUrl: 'https://monsite.com/onboarding/refresh',
-  returnUrl: 'https://monsite.com/onboarding/complete',
+  refreshUrl: 'https://mysite.com/onboarding/refresh',
+  returnUrl: 'https://mysite.com/onboarding/complete',
   type: 'account_onboarding',
 });
-// Rediriger le vendeur vers link.url
-
-// Transferer des fonds
-await createTransfer({
-  amount: 8000, // 80 EUR au vendeur
-  currency: 'eur',
-  destinationAccountId: account.id,
-});
 
-// Voir le solde
-const { data: balance } = await getBalance();
+await createTransfer({ amount: 8000, currency: 'eur', destinationAccountId: account.id });
 ```
 
 ---
@@ -538,29 +413,11 @@ export const POST = createNextWebhookHandler({
     'payment_intent.succeeded': async (event) => {
       const pi = event.data.object;
       console.log('Payment succeeded:', pi.id);
-      // Mettre a jour votre base de donnees
-    },
-
-    'customer.subscription.created': async (event) => {
-      const sub = event.data.object;
-      console.log('New subscription:', sub.id);
-    },
-
-    'customer.subscription.deleted': async (event) => {
-      const sub = event.data.object;
-      console.log('Subscription cancelled:', sub.id);
-    },
-
-    'invoice.payment_failed': async (event) => {
-      const invoice = event.data.object;
-      console.log('Payment failed for:', invoice.customer);
-      // Envoyer un email au client
-    },
-
-    'checkout.session.completed': async (event) => {
-      const session = event.data.object;
-      console.log('Checkout completed:', session.id);
     },
+    'customer.subscription.created': async (event) => { /* ... */ },
+    'customer.subscription.deleted': async (event) => { /* ... */ },
+    'invoice.payment_failed': async (event) => { /* ... */ },
+    'checkout.session.completed': async (event) => { /* ... */ },
   },
   onError: (error, event) => {
     console.error('Webhook error:', error.message, event?.type);
@@ -586,7 +443,7 @@ export default createPagesWebhookHandler({
 
 ---
 
-## Next.js - Routes API pre-construites
+## Next.js Pre-built API Routes
 
 ```ts
 // app/api/create-payment-intent/route.ts
@@ -594,9 +451,7 @@ import '@/lib/stripe';
 import { createPaymentIntentRoute } from '@stripe-sdk/core/next';
 
 export const POST = createPaymentIntentRoute({
-  // Optionnel : modifier l'input avant creation
   beforeCreate: async (input, request) => {
-    // Verifier l'authentification, forcer un montant, etc.
     return { ...input, currency: 'eur' };
   },
 });
@@ -606,7 +461,6 @@ export const POST = createPaymentIntentRoute({
 // app/api/create-checkout-session/route.ts
 import '@/lib/stripe';
 import { createCheckoutSessionRoute } from '@stripe-sdk/core/next';
-
 export const POST = createCheckoutSessionRoute();
 ```
 
@@ -614,20 +468,19 @@ export const POST = createCheckoutSessionRoute();
 // app/api/create-portal-session/route.ts
 import '@/lib/stripe';
 import { createPortalSessionRoute } from '@stripe-sdk/core/next';
-
 export const POST = createPortalSessionRoute();
 ```
 
 ---
 
-## Gestion des erreurs
+## Error Handling
 
-Toutes les fonctions serveur retournent un `SDKResult<T>` :
+All server functions return an `SDKResult<T>`:
 
 ```ts
 type SDKResult<T> =
-  | { data: T; error: null }        // Succes
-  | { data: null; error: SDKError } // Erreur
+  | { data: T; error: null }        // Success
+  | { data: null; error: SDKError } // Error
 
 type SDKError = {
   message: string;
@@ -641,60 +494,34 @@ type SDKError = {
 const result = await createPaymentIntent({ amount: 2000, currency: 'eur' });
 
 if (result.error) {
-  console.error(result.error.message);
-  // "Your card was declined"
+  console.error(result.error.message); // "Your card was declined"
   return;
 }
 
-console.log(result.data.id); // pi_xxx - TypeScript infere le type correct
+console.log(result.data.id); // pi_xxx - TypeScript infers the correct type
 ```
 
 ---
 
-## Architecture
-
-```
-src/
-  server/            # Code serveur uniquement
-    stripe-client.ts   # Init & singleton Stripe
-    payments/          # PaymentIntent, Checkout, PaymentLink, SetupIntent
-    customers/         # CRUD clients + Portail
-    subscriptions/     # CRUD abonnements
-    products/          # Produits & Prix
-    invoices/          # Facturation
-    refunds/           # Remboursements & Litiges
-    connect/           # Marketplace, Transfers, Payouts, Balance
-    coupons/           # Coupons & Codes promo
-    webhooks/          # Handler avec verification de signature
-  client/            # Code client (React)
-    providers/         # StripeProvider, StripeElementsProvider
-    hooks/             # usePayment, useSetupIntent, useCheckout
-    components/        # CheckoutForm, SetupForm, PricingTable, SubscriptionManager
-  next/              # Utilitaires specifiques Next.js
-    index.ts           # Server Actions, API route helpers
-  types/             # Types TypeScript complets
-  utils/             # Gestion d'erreurs
-```
-
 ## Imports
 
 ```ts
-// Serveur uniquement
+// Server only
 import { ... } from '@stripe-sdk/core/server';
 
-// Client uniquement (React)
+// Client only (React)
 import { ... } from '@stripe-sdk/core/client';
 
 // Webhooks
 import { ... } from '@stripe-sdk/core/webhooks';
 
-// Helpers Next.js
+// Next.js helpers
 import { ... } from '@stripe-sdk/core/next';
 
-// Tout (attention au tree-shaking)
+// Everything (watch out for tree-shaking)
 import { ... } from '@stripe-sdk/core';
 ```
 
-## Licence
+## License
 
 MIT