@stripe-sdk/core 1.0.0

package/README.md

@@ -0,0 +1,700 @@
+# @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.
+
+## Installation
+
+```bash
+npm install @stripe-sdk/core stripe @stripe/stripe-js @stripe/react-stripe-js
+```
+
+## Configuration
+
+### 1. Variables d'environnement
+
+```env
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+### 2. Initialisation (serveur)
+
+```ts
+// lib/stripe.ts
+import { initStripe } from '@stripe-sdk/core/server';
+
+export const stripe = initStripe({
+  secretKey: process.env.STRIPE_SECRET_KEY!,
+  publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+});
+```
+
+---
+
+## Paiements
+
+### Paiement simple avec formulaire integre
+
+**Serveur** - Creer un PaymentIntent :
+
+```ts
+// app/api/create-payment/route.ts
+import '@/lib/stripe'; // initialise 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)
+    currency: 'eur',
+  });
+
+  if (result.error) {
+    return Response.json(result.error, { status: 400 });
+  }
+
+  return Response.json({ clientSecret: result.data.client_secret });
+}
+```
+
+**Client** - Formulaire de paiement :
+
+```tsx
+// app/checkout/page.tsx
+'use client';
+import { StripeElementsProvider, CheckoutForm } from '@stripe-sdk/core/client';
+
+export default function CheckoutPage() {
+  const [clientSecret, setClientSecret] = useState('');
+
+  useEffect(() => {
+    fetch('/api/create-payment', {
+      method: 'POST',
+      body: JSON.stringify({ amount: 2000 }), // 20 EUR
+    })
+      .then(r => r.json())
+      .then(data => setClientSecret(data.clientSecret));
+  }, []);
+
+  if (!clientSecret) return <p>Loading...</p>;
+
+  return (
+    <StripeElementsProvider
+      publishableKey={process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!}
+      clientSecret={clientSecret}
+    >
+      <CheckoutForm
+        onSuccess={(id) => console.log('Paid!', id)}
+        onError={(err) => console.error(err)}
+        submitLabel="Payer 20 EUR"
+        showEmail
+      />
+    </StripeElementsProvider>
+  );
+}
+```
+
+### Checkout Session (page Stripe hebergee)
+
+```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',
+  automaticTax: true,
+  allowPromotionCodes: true,
+});
+
+// Redirect le client vers result.data.url
+```
+
+```tsx
+// Client - redirect vers Checkout
+import { useCheckout } from '@stripe-sdk/core/client';
+
+function BuyButton() {
+  const { redirectToCheckout, isLoading } = useCheckout({
+    publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
+  });
+
+  const handleClick = async () => {
+    const res = await fetch('/api/create-checkout-session', { method: 'POST' });
+    const { sessionId } = await res.json();
+    await redirectToCheckout(sessionId);
+  };
+
+  return <button onClick={handleClick} disabled={isLoading}>Acheter</button>;
+}
+```
+
+### Payment Link (sans code)
+
+```ts
+import { createPaymentLink } from '@stripe-sdk/core/server';
+
+const result = await createPaymentLink({
+  lineItems: [{ priceId: 'price_xxx', quantity: 1 }],
+  allowPromotionCodes: true,
+  afterCompletion: {
+    type: 'redirect',
+    redirectUrl: 'https://monsite.com/merci',
+  },
+});
+
+console.log(result.data.url); // Lien partageable
+```
+
+---
+
+## Abonnements
+
+### Creer un abonnement
+
+```ts
+import { createSubscription } from '@stripe-sdk/core/server';
+
+const result = await createSubscription({
+  customerId: 'cus_xxx',
+  priceId: 'price_monthly_xxx',
+  trialPeriodDays: 14,
+  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';
+
+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
+await cancelSubscription({
+  subscriptionId: 'sub_xxx',
+  cancelAtPeriodEnd: true,
+  cancellationDetails: { feedback: 'too_expensive' },
+});
+
+// Reprendre
+await resumeSubscription('sub_xxx');
+```
+
+### Composant PricingTable
+
+```tsx
+import { PricingTable, type PricingPlan } from '@stripe-sdk/core/client';
+
+const plans: PricingPlan[] = [
+  {
+    id: 'starter',
+    name: 'Starter',
+    priceId: 'price_starter',
+    amount: 900,
+    currency: 'eur',
+    interval: 'month',
+    features: ['5 projets', '1 Go stockage', 'Support email'],
+  },
+  {
+    id: 'pro',
+    name: 'Pro',
+    priceId: 'price_pro',
+    amount: 2900,
+    currency: 'eur',
+    interval: 'month',
+    features: ['Projets illimites', '100 Go stockage', 'Support prioritaire', 'API access'],
+    highlighted: true,
+    badge: 'Populaire',
+  },
+];
+
+<PricingTable
+  plans={plans}
+  onSelectPlan={(plan) => handleSubscribe(plan.priceId)}
+  currentPlanId="starter"
+/>
+```
+
+### 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
+
+```ts
+import {
+  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
+
+```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.
+```
+
+---
+
+## Sauvegarder un moyen de paiement (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
+});
+```
+
+```tsx
+// Client
+import { StripeElementsProvider, SetupForm } from '@stripe-sdk/core/client';
+
+<StripeElementsProvider
+  publishableKey={process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!}
+  clientSecret={setupClientSecret}
+>
+  <SetupForm
+    onSuccess={(setupId, pmId) => {
+      console.log('Saved!', pmId);
+    }}
+    submitLabel="Sauvegarder la carte"
+  />
+</StripeElementsProvider>
+```
+
+---
+
+## Produits & Prix
+
+```ts
+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',
+  defaultPriceData: {
+    unitAmount: 2900, // 29.00 EUR
+    currency: 'eur',
+    recurring: { interval: 'month' },
+  },
+});
+
+// Ajouter un prix annuel
+await createPrice({
+  productId: product.id,
+  unitAmount: 29000, // 290.00 EUR
+  currency: 'eur',
+  recurring: { interval: 'year' },
+  lookupKey: 'pro_annual',
+});
+
+// Lister les produits actifs
+const { data: products } = await listProducts({ active: true, limit: 20 });
+```
+
+---
+
+## Factures
+
+```ts
+import {
+  createInvoice,
+  createInvoiceItem,
+  finalizeInvoice,
+  sendInvoice,
+  listInvoices,
+  getUpcomingInvoice,
+} from '@stripe-sdk/core/server';
+
+// Creer et envoyer une facture
+const { data: invoice } = await createInvoice({
+  customerId: 'cus_xxx',
+  collectionMethod: 'send_invoice',
+  daysUntilDue: 30,
+});
+
+await createInvoiceItem({
+  customerId: 'cus_xxx',
+  invoiceId: invoice.id,
+  amount: 5000, // 50.00 EUR
+  currency: 'eur',
+  description: 'Consulting - Janvier 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
+
+```ts
+import {
+  createRefund,
+  listRefunds,
+  retrieveDispute,
+  updateDispute,
+} from '@stripe-sdk/core/server';
+
+// Remboursement total
+await createRefund({ paymentIntentId: 'pi_xxx' });
+
+// Remboursement partiel
+await createRefund({
+  paymentIntentId: 'pi_xxx',
+  amount: 500, // 5.00 EUR
+  reason: 'requested_by_customer',
+});
+
+// Repondre a un litige
+await updateDispute({
+  disputeId: 'dp_xxx',
+  evidence: {
+    customerName: 'John Doe',
+    productDescription: 'Abonnement SaaS mensuel',
+    serviceDocumentation: 'file_xxx',
+  },
+  submit: true,
+});
+```
+
+---
+
+## Coupons & Codes Promo
+
+```ts
+import {
+  createCoupon,
+  createPromotionCode,
+  listPromotionCodes,
+} from '@stripe-sdk/core/server';
+
+// Coupon -20%
+const { data: coupon } = await createCoupon({
+  percentOff: 20,
+  duration: 'repeating',
+  durationInMonths: 3,
+  name: 'Lancement 2025',
+});
+
+// Code promo public
+await createPromotionCode({
+  couponId: coupon.id,
+  code: 'LAUNCH20',
+  maxRedemptions: 100,
+  restrictions: {
+    firstTimeTransaction: true,
+  },
+});
+```
+
+---
+
+## Stripe Connect (Marketplace)
+
+```ts
+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 },
+  },
+});
+
+// Lien d'onboarding
+const { data: link } = await createAccountLink({
+  accountId: account.id,
+  refreshUrl: 'https://monsite.com/onboarding/refresh',
+  returnUrl: 'https://monsite.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();
+```
+
+---
+
+## Webhooks
+
+### Next.js App Router
+
+```ts
+// app/api/webhooks/stripe/route.ts
+import '@/lib/stripe';
+import { createNextWebhookHandler } from '@stripe-sdk/core/webhooks';
+
+export const POST = createNextWebhookHandler({
+  handlers: {
+    '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);
+    },
+  },
+  onError: (error, event) => {
+    console.error('Webhook error:', error.message, event?.type);
+  },
+});
+```
+
+### Next.js Pages Router
+
+```ts
+// pages/api/webhooks/stripe.ts
+import '@/lib/stripe';
+import { createPagesWebhookHandler } from '@stripe-sdk/core/webhooks';
+
+export const config = { api: { bodyParser: false } };
+
+export default createPagesWebhookHandler({
+  handlers: {
+    'payment_intent.succeeded': async (event) => { /* ... */ },
+  },
+});
+```
+
+---
+
+## Next.js - Routes API pre-construites
+
+```ts
+// app/api/create-payment-intent/route.ts
+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' };
+  },
+});
+```
+
+```ts
+// app/api/create-checkout-session/route.ts
+import '@/lib/stripe';
+import { createCheckoutSessionRoute } from '@stripe-sdk/core/next';
+
+export const POST = createCheckoutSessionRoute();
+```
+
+```ts
+// app/api/create-portal-session/route.ts
+import '@/lib/stripe';
+import { createPortalSessionRoute } from '@stripe-sdk/core/next';
+
+export const POST = createPortalSessionRoute();
+```
+
+---
+
+## Gestion des erreurs
+
+Toutes les fonctions serveur retournent un `SDKResult<T>` :
+
+```ts
+type SDKResult<T> =
+  | { data: T; error: null }        // Succes
+  | { data: null; error: SDKError } // Erreur
+
+type SDKError = {
+  message: string;
+  type: string;
+  code?: string;
+  statusCode?: number;
+};
+```
+
+```ts
+const result = await createPaymentIntent({ amount: 2000, currency: 'eur' });
+
+if (result.error) {
+  console.error(result.error.message);
+  // "Your card was declined"
+  return;
+}
+
+console.log(result.data.id); // pi_xxx - TypeScript infere le type correct
+```
+
+---
+
+## 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
+import { ... } from '@stripe-sdk/core/server';
+
+// Client uniquement (React)
+import { ... } from '@stripe-sdk/core/client';
+
+// Webhooks
+import { ... } from '@stripe-sdk/core/webhooks';
+
+// Helpers Next.js
+import { ... } from '@stripe-sdk/core/next';
+
+// Tout (attention au tree-shaking)
+import { ... } from '@stripe-sdk/core';
+```
+
+## Licence
+
+MIT