claudient 0.1.0

package/skills/finance-payments/de/stripe.md

@@ -0,0 +1,187 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../stripe.md).
+
+# Stripe Integration Skill
+
+## Wann aktivieren
+- Stripe Checkout oder Payment Intents für Einmalzahlungen implementieren
+- Stripe-Abonnements und Abrechnungszyklen einrichten
+- Stripe-Webhooks für Zahlungsereignisse verarbeiten
+- Rückerstattungen, Streitigkeiten oder Zahlungsabbrüche implementieren
+- Stripe Connect für Marktplatz-/Plattformzahlungen einrichten
+- Fehlgeschlagene Zahlungen, abgelehnte Karten oder Webhook-Zustellprobleme debuggen
+- SCA (Starke Kundenauthentifizierung) Compliance implementieren
+
+## Wann NICHT verwenden
+- PayPal, Braintree, Adyen, Mollie — andere Zahlungsanbieter mit anderen SDKs
+- Krypto-Zahlungen
+- Interne Buchhaltungs- oder Rechnungssysteme ohne Zahlungs-Gateway
+- Banküberweisung / nur ACH-Flows (anderes Stripe-Produkt — Payment Elements gelten noch, aber Flow unterscheidet sich)
+
+## Anweisungen
+
+### Niemals Zahlungsdaten hardcoden oder protokollieren
+```typescript
+// NIEMALS Kartendetails, vollständige Payment-Intent-Objekte oder Kunden-PII protokollieren
+// SCHLECHT:
+console.log('Payment intent:', paymentIntent); // Kann sensible Daten enthalten
+
+// GUT:
+console.log('Payment intent created:', paymentIntent.id, paymentIntent.status);
+```
+
+### Payment Intents — serverseitige Erstellung
+```typescript
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2024-12-18.acacia',  // API-Version immer pinnen
+});
+
+// Payment Intent serverseitig erstellen — niemals clientseitig
+export async function createPaymentIntent(
+  amount: number,   // Immer in kleinster Währungseinheit (Cents für USD)
+  currency: string,
+  customerId: string,
+  metadata: Record<string, string>
+): Promise<{ clientSecret: string; paymentIntentId: string }> {
+  const paymentIntent = await stripe.paymentIntents.create({
+    amount,                    // z.B. 2999 = $29.99
+    currency,                  // z.B. 'usd', 'eur'
+    customer: customerId,
+    automatic_payment_methods: { enabled: true },
+    metadata,                  // Interne IDs hier speichern
+    idempotency_key: `pi_${customerId}_${Date.now()}`,  // Doppelte Abbuchungen verhindern
+  });
+
+  return {
+    clientSecret: paymentIntent.client_secret!,
+    paymentIntentId: paymentIntent.id,
+  };
+}
+```
+
+### Webhook-Verarbeitung — immer Signatur verifizieren
+```typescript
+import { headers } from 'next/headers';
+
+export async function POST(request: Request) {
+  const body = await request.text();  // Roher Body — kein geparsten JSON
+  const signature = headers().get('stripe-signature')!;
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      body,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    );
+  } catch (err) {
+    // Ungültige Signatur — sofort ablehnen
+    return new Response('Invalid signature', { status: 400 });
+  }
+
+  // Idempotent verarbeiten — Webhooks können mehr als einmal zugestellt werden
+  switch (event.type) {
+    case 'payment_intent.succeeded':
+      await handlePaymentSucceeded(event.data.object as Stripe.PaymentIntent);
+      break;
+    case 'payment_intent.payment_failed':
+      await handlePaymentFailed(event.data.object as Stripe.PaymentIntent);
+      break;
+    case 'customer.subscription.deleted':
+      await handleSubscriptionCancelled(event.data.object as Stripe.Subscription);
+      break;
+    default:
+      // Protokollieren, aber kein Fehler bei unbekannten Ereignissen — Stripe fügt neue Ereignisse im Laufe der Zeit hinzu
+      console.log(`Unhandled event type: ${event.type}`);
+  }
+
+  return new Response(null, { status: 200 });
+}
+
+// Immer prüfen, ob bereits verarbeitet, bevor DB-Änderungen vorgenommen werden
+async function handlePaymentSucceeded(paymentIntent: Stripe.PaymentIntent) {
+  const orderId = paymentIntent.metadata.order_id;
+
+  // Idempotenzprüfung
+  const existing = await db.order.findUnique({ where: { id: orderId } });
+  if (existing?.status === 'paid') return;  // Bereits verarbeitet
+
+  await db.order.update({
+    where: { id: orderId },
+    data: { status: 'paid', stripePaymentIntentId: paymentIntent.id }
+  });
+}
+```
+
+### Abonnements
+```typescript
+// Abonnement erstellen
+const subscription = await stripe.subscriptions.create({
+  customer: customerId,
+  items: [{ price: priceId }],
+  payment_behavior: 'default_incomplete',  // Nicht aktivieren bis Zahlung bestätigt
+  expand: ['latest_invoice.payment_intent'],
+});
+
+// Wichtige Webhook-Ereignisse für Abonnements:
+// customer.subscription.created → Zugang bereitstellen
+// customer.subscription.updated → Planänderungen verarbeiten
+// customer.subscription.deleted → Zugang widerrufen
+// invoice.payment_succeeded → Zugangsperiode verlängern
+// invoice.payment_failed → Mahnung senden, dann nach Nachfrist sperren
+```
+
+### Testmodus-Disziplin
+```typescript
+// Testkartennummern in der Entwicklung verwenden:
+// Erfolg: 4242 4242 4242 4242
+// Ablehnung: 4000 0000 0000 0002
+// Auth erforderlich: 4000 0025 0000 3155
+// Test-Webhook-CLI verwenden: stripe listen --forward-to localhost:3000/api/webhooks/stripe
+
+// Niemals Testschlüssel in der Produktion, niemals Live-Schlüssel in der Entwicklung verwenden
+const isLiveMode = process.env.STRIPE_SECRET_KEY!.startsWith('sk_live_');
+if (isLiveMode && process.env.NODE_ENV !== 'production') {
+  throw new Error('Live Stripe keys must not be used outside production');
+}
+```
+
+### Fehlerbehandlung
+```typescript
+try {
+  const charge = await stripe.charges.create({ ... });
+} catch (err) {
+  if (err instanceof Stripe.errors.StripeCardError) {
+    // Karte abgelehnt — benutzerfreundliche Meldung anzeigen
+    return { error: err.message, code: err.code };
+  }
+  if (err instanceof Stripe.errors.StripeRateLimitError) {
+    // Mit exponentiellem Backoff wiederholen
+    throw err;
+  }
+  if (err instanceof Stripe.errors.StripeInvalidRequestError) {
+    // Fehlerhafter API-Aufruf — protokollieren und Code korrigieren
+    console.error('Invalid Stripe request:', err.message);
+    throw err;
+  }
+  // Andere Fehler: StripeAPIError, StripeConnectionError, StripeAuthenticationError
+  throw err;
+}
+```
+
+## Beispiel
+
+**Benutzer:** Einen Checkout-Flow für ein SaaS-Produkt implementieren: serverseitig einen Payment Intent erstellen, beim Erfolg den Webhook verarbeiten, um das Abonnement zu aktivieren, und fehlgeschlagene Zahlungen behandeln.
+
+**Erwartete Ausgabe:**
+- `POST /api/checkout` — erstellt PaymentIntent, gibt `clientSecret` zurück
+- `POST /api/webhooks/stripe` — verifiziert Signatur, verarbeitet `payment_intent.succeeded` (idempotentes DB-Update), `payment_intent.payment_failed` (protokollieren + benachrichtigen)
+- Metadaten auf PaymentIntent: `user_id`, `plan_id`, `order_id`
+- Alle Beträge in Cents, Währung explizit
+- API-Version gepinnt
+- Keine Protokollierung sensibler Daten
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. Zahlungsflows aufbauen oder KI-Produkte monetarisieren? [uitbreiden.com](https://uitbreiden.com/)

package/skills/finance-payments/es/stripe.md

@@ -0,0 +1,187 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../stripe.md).
+
+# Skill de Integración con Stripe
+
+## Cuándo activar
+- Implementar Stripe Checkout o Payment Intents para pagos únicos
+- Configurar suscripciones y ciclos de facturación en Stripe
+- Manejar webhooks de Stripe para eventos de pago
+- Implementar reembolsos, disputas o cancelaciones de pagos
+- Configurar Stripe Connect para pagos en marketplace/plataforma
+- Depurar pagos fallidos, tarjetas rechazadas o problemas de entrega de webhooks
+- Implementar cumplimiento de SCA (Strong Customer Authentication)
+
+## Cuándo NO usar
+- PayPal, Braintree, Adyen, Mollie — proveedores de pago diferentes con SDKs diferentes
+- Pagos con criptomonedas
+- Sistemas internos de contabilidad o facturación sin pasarela de pago
+- Flujos solo de transferencia bancaria/ACH (producto diferente de Stripe — Payment Elements aún aplica, pero el flujo difiere)
+
+## Instrucciones
+
+### Nunca hardcodees ni registres datos de pago
+```typescript
+// NUNCA registres detalles de tarjeta, objetos completos de payment intent o PII del cliente
+// MALO:
+console.log('Payment intent:', paymentIntent); // Puede contener datos sensibles
+
+// BUENO:
+console.log('Payment intent created:', paymentIntent.id, paymentIntent.status);
+```
+
+### Payment Intents — creación en el servidor
+```typescript
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2024-12-18.acacia',  // Siempre fija la versión de la API
+});
+
+// Crear payment intent en el servidor — nunca en el cliente
+export async function createPaymentIntent(
+  amount: number,   // Siempre en la unidad de moneda más pequeña (centavos para USD)
+  currency: string,
+  customerId: string,
+  metadata: Record<string, string>
+): Promise<{ clientSecret: string; paymentIntentId: string }> {
+  const paymentIntent = await stripe.paymentIntents.create({
+    amount,                    // p.ej., 2999 = $29.99
+    currency,                  // p.ej., 'usd', 'eur'
+    customer: customerId,
+    automatic_payment_methods: { enabled: true },
+    metadata,                  // Almacena tus IDs internos aquí
+    idempotency_key: `pi_${customerId}_${Date.now()}`,  // Prevenir cargos duplicados
+  });
+
+  return {
+    clientSecret: paymentIntent.client_secret!,
+    paymentIntentId: paymentIntent.id,
+  };
+}
+```
+
+### Manejo de webhooks — siempre verifica la firma
+```typescript
+import { headers } from 'next/headers';
+
+export async function POST(request: Request) {
+  const body = await request.text();  // Cuerpo sin procesar — no JSON parseado
+  const signature = headers().get('stripe-signature')!;
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      body,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    );
+  } catch (err) {
+    // Firma inválida — rechazar inmediatamente
+    return new Response('Invalid signature', { status: 400 });
+  }
+
+  // Procesar idempotentemente — los webhooks pueden entregarse más de una vez
+  switch (event.type) {
+    case 'payment_intent.succeeded':
+      await handlePaymentSucceeded(event.data.object as Stripe.PaymentIntent);
+      break;
+    case 'payment_intent.payment_failed':
+      await handlePaymentFailed(event.data.object as Stripe.PaymentIntent);
+      break;
+    case 'customer.subscription.deleted':
+      await handleSubscriptionCancelled(event.data.object as Stripe.Subscription);
+      break;
+    default:
+      // Registrar pero no dar error en eventos desconocidos — Stripe agrega nuevos eventos con el tiempo
+      console.log(`Unhandled event type: ${event.type}`);
+  }
+
+  return new Response(null, { status: 200 });
+}
+
+// Siempre verifica si ya fue procesado antes de hacer cambios en la BD
+async function handlePaymentSucceeded(paymentIntent: Stripe.PaymentIntent) {
+  const orderId = paymentIntent.metadata.order_id;
+
+  // Verificación de idempotencia
+  const existing = await db.order.findUnique({ where: { id: orderId } });
+  if (existing?.status === 'paid') return;  // Ya procesado
+
+  await db.order.update({
+    where: { id: orderId },
+    data: { status: 'paid', stripePaymentIntentId: paymentIntent.id }
+  });
+}
+```
+
+### Suscripciones
+```typescript
+// Crear suscripción
+const subscription = await stripe.subscriptions.create({
+  customer: customerId,
+  items: [{ price: priceId }],
+  payment_behavior: 'default_incomplete',  // No activar hasta que se confirme el pago
+  expand: ['latest_invoice.payment_intent'],
+});
+
+// Eventos webhook clave para suscripciones:
+// customer.subscription.created → aprovisionar acceso
+// customer.subscription.updated → manejar cambios de plan
+// customer.subscription.deleted → revocar acceso
+// invoice.payment_succeeded → extender período de acceso
+// invoice.payment_failed → enviar correo de dunning, luego suspender después del período de gracia
+```
+
+### Disciplina en modo de prueba
+```typescript
+// Usar números de tarjeta de prueba en desarrollo:
+// Éxito: 4242 4242 4242 4242
+// Rechazada: 4000 0000 0000 0002
+// Requiere autenticación: 4000 0025 0000 3155
+// Usar webhook CLI de prueba: stripe listen --forward-to localhost:3000/api/webhooks/stripe
+
+// Nunca usar claves de prueba en producción, nunca usar claves en vivo en desarrollo
+const isLiveMode = process.env.STRIPE_SECRET_KEY!.startsWith('sk_live_');
+if (isLiveMode && process.env.NODE_ENV !== 'production') {
+  throw new Error('Live Stripe keys must not be used outside production');
+}
+```
+
+### Manejo de errores
+```typescript
+try {
+  const charge = await stripe.charges.create({ ... });
+} catch (err) {
+  if (err instanceof Stripe.errors.StripeCardError) {
+    // Tarjeta rechazada — mostrar mensaje amigable al usuario
+    return { error: err.message, code: err.code };
+  }
+  if (err instanceof Stripe.errors.StripeRateLimitError) {
+    // Reintentar con backoff exponencial
+    throw err;
+  }
+  if (err instanceof Stripe.errors.StripeInvalidRequestError) {
+    // Llamada a la API incorrecta — registrar y corregir el código
+    console.error('Invalid Stripe request:', err.message);
+    throw err;
+  }
+  // Otros errores: StripeAPIError, StripeConnectionError, StripeAuthenticationError
+  throw err;
+}
+```
+
+## Ejemplo
+
+**Usuario:** Implementar un flujo de checkout para un producto SaaS: crear un payment intent en el servidor, manejar el webhook al tener éxito para activar la suscripción y manejar pagos fallidos.
+
+**Salida esperada:**
+- `POST /api/checkout` — crea PaymentIntent, devuelve `clientSecret`
+- `POST /api/webhooks/stripe` — verifica firma, maneja `payment_intent.succeeded` (actualización idempotente en BD), `payment_intent.payment_failed` (registrar + notificar)
+- Metadata en PaymentIntent: `user_id`, `plan_id`, `order_id`
+- Todos los importes en centavos, moneda explícita
+- Versión de la API fijada
+- Sin registro de datos sensibles
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. ¿Construyendo flujos de pago o monetizando productos de IA? [uitbreiden.com](https://uitbreiden.com/)

package/skills/finance-payments/fr/stripe.md

@@ -0,0 +1,187 @@
+> 🇫🇷 This is the French translation. [English version](../stripe.md).
+
+# Compétence Intégration Stripe
+
+## Quand activer
+- Implémenter Stripe Checkout ou Payment Intents pour les paiements uniques
+- Configurer les abonnements Stripe et les cycles de facturation
+- Gérer les webhooks Stripe pour les événements de paiement
+- Implémenter des remboursements, litiges ou annulations de paiement
+- Configurer Stripe Connect pour les paiements marketplace/plateforme
+- Déboguer des paiements échoués, des cartes refusées ou des problèmes de livraison de webhooks
+- Implémenter la conformité SCA (Strong Customer Authentication)
+
+## Quand NE PAS utiliser
+- PayPal, Braintree, Adyen, Mollie — fournisseurs de paiement différents avec des SDKs différents
+- Paiements crypto
+- Systèmes comptables internes ou de facturation sans passerelle de paiement
+- Flux uniquement par virement bancaire / ACH (produit Stripe différent — Payment Elements s'applique toujours, mais le flux diffère)
+
+## Instructions
+
+### Ne jamais coder en dur ou logger des données de paiement
+```typescript
+// NE JAMAIS logger les détails de carte, les objets payment intent complets, ou les PII clients
+// MAUVAIS :
+console.log('Payment intent:', paymentIntent); // Peut contenir des données sensibles
+
+// BON :
+console.log('Payment intent created:', paymentIntent.id, paymentIntent.status);
+```
+
+### Payment Intents — création côté serveur
+```typescript
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2024-12-18.acacia',  // Toujours épingler la version de l'API
+});
+
+// Créer le payment intent côté serveur — jamais côté client
+export async function createPaymentIntent(
+  amount: number,   // Toujours dans la plus petite unité monétaire (centimes pour USD)
+  currency: string,
+  customerId: string,
+  metadata: Record<string, string>
+): Promise<{ clientSecret: string; paymentIntentId: string }> {
+  const paymentIntent = await stripe.paymentIntents.create({
+    amount,                    // ex: 2999 = 29,99€
+    currency,                  // ex: 'usd', 'eur'
+    customer: customerId,
+    automatic_payment_methods: { enabled: true },
+    metadata,                  // Stocker vos IDs internes ici
+    idempotency_key: `pi_${customerId}_${Date.now()}`,  // Prévenir les charges en doublon
+  });
+
+  return {
+    clientSecret: paymentIntent.client_secret!,
+    paymentIntentId: paymentIntent.id,
+  };
+}
+```
+
+### Gestion des webhooks — toujours vérifier la signature
+```typescript
+import { headers } from 'next/headers';
+
+export async function POST(request: Request) {
+  const body = await request.text();  // Corps brut — pas de JSON parsé
+  const signature = headers().get('stripe-signature')!;
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      body,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    );
+  } catch (err) {
+    // Signature invalide — rejeter immédiatement
+    return new Response('Invalid signature', { status: 400 });
+  }
+
+  // Traiter de manière idempotente — les webhooks peuvent être livrés plus d'une fois
+  switch (event.type) {
+    case 'payment_intent.succeeded':
+      await handlePaymentSucceeded(event.data.object as Stripe.PaymentIntent);
+      break;
+    case 'payment_intent.payment_failed':
+      await handlePaymentFailed(event.data.object as Stripe.PaymentIntent);
+      break;
+    case 'customer.subscription.deleted':
+      await handleSubscriptionCancelled(event.data.object as Stripe.Subscription);
+      break;
+    default:
+      // Logger mais ne pas lever d'erreur sur les événements inconnus — Stripe en ajoute de nouveaux au fil du temps
+      console.log(`Unhandled event type: ${event.type}`);
+  }
+
+  return new Response(null, { status: 200 });
+}
+
+// Toujours vérifier si déjà traité avant de modifier la DB
+async function handlePaymentSucceeded(paymentIntent: Stripe.PaymentIntent) {
+  const orderId = paymentIntent.metadata.order_id;
+
+  // Vérification d'idempotence
+  const existing = await db.order.findUnique({ where: { id: orderId } });
+  if (existing?.status === 'paid') return;  // Déjà traité
+
+  await db.order.update({
+    where: { id: orderId },
+    data: { status: 'paid', stripePaymentIntentId: paymentIntent.id }
+  });
+}
+```
+
+### Abonnements
+```typescript
+// Créer un abonnement
+const subscription = await stripe.subscriptions.create({
+  customer: customerId,
+  items: [{ price: priceId }],
+  payment_behavior: 'default_incomplete',  // Ne pas activer avant confirmation du paiement
+  expand: ['latest_invoice.payment_intent'],
+});
+
+// Événements webhook clés pour les abonnements :
+// customer.subscription.created → provisionner l'accès
+// customer.subscription.updated → gérer les changements de plan
+// customer.subscription.deleted → révoquer l'accès
+// invoice.payment_succeeded → étendre la période d'accès
+// invoice.payment_failed → envoyer un email de relance, puis suspendre après la période de grâce
+```
+
+### Discipline du mode test
+```typescript
+// Utiliser des numéros de carte de test en développement :
+// Succès : 4242 4242 4242 4242
+// Refus : 4000 0000 0000 0002
+// Auth requise : 4000 0025 0000 3155
+// Utiliser la CLI webhook de test : stripe listen --forward-to localhost:3000/api/webhooks/stripe
+
+// Ne jamais utiliser des clés de test en production, ne jamais utiliser des clés live en développement
+const isLiveMode = process.env.STRIPE_SECRET_KEY!.startsWith('sk_live_');
+if (isLiveMode && process.env.NODE_ENV !== 'production') {
+  throw new Error('Live Stripe keys must not be used outside production');
+}
+```
+
+### Gestion des erreurs
+```typescript
+try {
+  const charge = await stripe.charges.create({ ... });
+} catch (err) {
+  if (err instanceof Stripe.errors.StripeCardError) {
+    // Carte refusée — afficher un message convivial
+    return { error: err.message, code: err.code };
+  }
+  if (err instanceof Stripe.errors.StripeRateLimitError) {
+    // Réessayer avec backoff exponentiel
+    throw err;
+  }
+  if (err instanceof Stripe.errors.StripeInvalidRequestError) {
+    // Mauvais appel API — logger et corriger le code
+    console.error('Invalid Stripe request:', err.message);
+    throw err;
+  }
+  // Autres erreurs : StripeAPIError, StripeConnectionError, StripeAuthenticationError
+  throw err;
+}
+```
+
+## Exemple
+
+**Utilisateur :** Implémenter un flux de checkout pour un produit SaaS : créer un payment intent côté serveur, gérer le webhook au succès pour activer l'abonnement et gérer les paiements échoués.
+
+**Sortie attendue :**
+- `POST /api/checkout` — crée le PaymentIntent, retourne `clientSecret`
+- `POST /api/webhooks/stripe` — vérifie la signature, gère `payment_intent.succeeded` (mise à jour DB idempotente), `payment_intent.payment_failed` (log + notification)
+- Métadonnées sur le PaymentIntent : `user_id`, `plan_id`, `order_id`
+- Tous les montants en centimes, devise explicite
+- Version de l'API épinglée
+- Pas de logging de données sensibles
+
+---
+
+> **Travaillez avec nous :** Claudient est soutenu par [Uitbreiden](https://uitbreiden.com/) — nous construisons des produits IA et des solutions B2B avec des communautés de développeurs. Vous construisez des flux de paiement ou monétisez des produits IA ? [uitbreiden.com](https://uitbreiden.com/)