claudient 0.1.0

package/skills/database/de/graphql.md

@@ -0,0 +1,181 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../graphql.md).
+
+# GraphQL Skill
+
+## Wann aktivieren
+- Ein GraphQL-Schema entwerfen (Types, Queries, Mutations, Subscriptions)
+- Resolver in Node.js implementieren (Apollo Server, Pothos, GraphQL Yoga)
+- Prisma mit einer GraphQL API einrichten
+- GraphQL-Abfragen und Fragments für einen Frontend-Client schreiben
+- Cursor-basierte oder Offset-Paginierung in GraphQL implementieren
+- DataLoader zur N+1-Abfragevermeidung einrichten
+- Authentifizierung und Autorisierung zu einer GraphQL API hinzufügen
+- GraphQL-Performance oder N+1-Probleme debuggen
+
+## Wann NICHT verwenden
+- REST APIs, bei denen GraphQL Komplexität ohne Vorteil hinzufügt (einfaches CRUD, Webhooks, Datei-Uploads)
+- gRPC oder ereignisgesteuerte Systeme
+- Fälle, in denen der Client immer die vollständige Antwort benötigt (GraphQL's Feldauswahl fügt keinen Wert hinzu)
+
+## Anweisungen
+
+### Schema-Designprinzipien
+```graphql
+# Typnamen: PascalCase Substantive im Singular
+# Feldnamen: camelCase
+# Enums: SCREAMING_SNAKE_CASE-Werte
+
+type Order {
+  id: ID!
+  status: OrderStatus!
+  customer: Customer!       # Verschachtelter Typ — immer das Objekt zurückgeben, nicht nur die ID
+  items: [OrderItem!]!     # Nicht-null-Liste von nicht-null-Elementen
+  totalAmount: Float!
+  createdAt: DateTime!
+}
+
+enum OrderStatus {
+  PENDING
+  COMPLETED
+  CANCELLED
+}
+
+# Queries: nullable für einzelnes Element zurückgeben (nicht gefunden = null), nicht-null für Listen
+type Query {
+  order(id: ID!): Order       # Nullable — null wenn nicht gefunden
+  orders(filter: OrderFilter): [Order!]!  # Nicht-null-Liste
+  me: User                    # Nullable — null wenn nicht authentifiziert
+}
+
+# Mutations: immer das mutierte Objekt plus ein Fehler-Array zurückgeben
+type Mutation {
+  createOrder(input: CreateOrderInput!): CreateOrderPayload!
+}
+
+type CreateOrderPayload {
+  order: Order          # Null wenn Mutation fehlgeschlagen
+  errors: [UserError!]! # Leer wenn erfolgreich
+}
+
+type UserError {
+  field: String
+  message: String!
+}
+```
+
+### N+1-Vermeidung mit DataLoader
+```typescript
+import DataLoader from 'dataloader';
+
+// Pro Request erstellen — niemals Singleton (Anfragedaten-Isolation)
+export function createLoaders() {
+  return {
+    customerLoader: new DataLoader<string, Customer>(async (ids) => {
+      const customers = await db.customer.findMany({
+        where: { id: { in: [...ids] } }
+      });
+      // Muss in gleicher Reihenfolge wie ids zurückgeben
+      const customerMap = new Map(customers.map(c => [c.id, c]));
+      return ids.map(id => customerMap.get(id) ?? new Error(`Customer ${id} not found`));
+    }),
+  };
+}
+
+// Resolver — verwendet Loader, nicht direkten DB-Aufruf
+const resolvers = {
+  Order: {
+    customer: (order, _, { loaders }) => loaders.customerLoader.load(order.customerId),
+  }
+};
+```
+
+### Cursor-basierte Paginierung (gegenüber Offset bevorzugen)
+```graphql
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  node: Order!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type Query {
+  orders(first: Int, after: String, last: Int, before: String): OrderConnection!
+}
+```
+
+### Autorisierungsmuster
+```typescript
+// Feldebenen-Autorisierung im Resolver
+const resolvers = {
+  Query: {
+    adminStats: (_, __, { user }) => {
+      if (!user || user.role !== 'ADMIN') {
+        throw new GraphQLError('Unauthorized', {
+          extensions: { code: 'UNAUTHORIZED' }
+        });
+      }
+      return getAdminStats();
+    }
+  },
+  Order: {
+    // Objektebene: sensible Felder nur dem Besitzer der Bestellung zurückgeben
+    internalNotes: (order, _, { user }) => {
+      if (user?.id !== order.customerId && user?.role !== 'ADMIN') return null;
+      return order.internalNotes;
+    }
+  }
+};
+```
+
+### Prisma + GraphQL-Muster
+```typescript
+// Resolver mit Prisma — Über-Fetching vermeiden
+const resolvers = {
+  Query: {
+    order: async (_, { id }, { prisma, user }) => {
+      const order = await prisma.order.findUnique({
+        where: { id },
+        select: {
+          id: true,
+          status: true,
+          customerId: true,
+          totalAmount: true,
+          createdAt: true,
+          // items NICHT hier auswählen — den items-Resolver damit umgehen
+          // mit DataLoader, um N+1 zu vermeiden
+        }
+      });
+      if (!order) return null;
+      if (order.customerId !== user?.id) throw new GraphQLError('Forbidden');
+      return order;
+    }
+  }
+};
+```
+
+## Beispiel
+
+**Benutzer:** Ein GraphQL-Schema und Resolver für eine einfache E-Commerce-API entwerfen — Produkte, Bestellungen und Kunden. Paginierung, DataLoader für Kunden und Mutation-Fehlerbehandlung einschließen.
+
+**Erwartete Ausgabe:**
+- Schema: `Product`, `Order`, `Customer`, `OrderConnection`, `UserError`-Typen
+- `Query.orders` mit Cursor-Paginierung, die `OrderConnection` zurückgibt
+- `Mutation.createOrder` gibt `CreateOrderPayload` mit Fehler-Array zurück
+- `Order.customer`-Resolver verwendet DataLoader (keine direkte DB-Abfrage)
+- `createLoaders()`-Funktion pro Request, batcht Kunden-Lookups nach ID
+- Auth-Prüfung: nur authentifizierte Benutzer können ihre eigenen Bestellungen sehen
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. GraphQL APIs oder KI-gestützte Datenschichten aufbauen? [uitbreiden.com](https://uitbreiden.com/)

package/skills/database/es/graphql.md

@@ -0,0 +1,181 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../graphql.md).
+
+# Skill de GraphQL
+
+## Cuándo activar
+- Diseñar un esquema de GraphQL (tipos, queries, mutations, subscriptions)
+- Implementar resolvers en Node.js (Apollo Server, Pothos, GraphQL Yoga)
+- Configurar Prisma con una API de GraphQL
+- Escribir queries y fragments de GraphQL para un cliente frontend
+- Implementar paginación basada en cursor o por offset en GraphQL
+- Configurar DataLoader para prevención de consultas N+1
+- Agregar autenticación y autorización a una API de GraphQL
+- Depurar rendimiento de GraphQL o problemas N+1
+
+## Cuándo NO usar
+- APIs REST donde GraphQL añade complejidad sin beneficio (CRUD simple, webhooks, cargas de archivos)
+- gRPC o sistemas orientados a eventos
+- Casos donde el cliente siempre necesita la respuesta completa (la selección de campos de GraphQL no aporta valor)
+
+## Instrucciones
+
+### Principios de diseño de esquemas
+```graphql
+# Nombres de tipos: PascalCase con sustantivos singulares
+# Nombres de campos: camelCase
+# Enums: valores SCREAMING_SNAKE_CASE
+
+type Order {
+  id: ID!
+  status: OrderStatus!
+  customer: Customer!       # Tipo anidado — siempre devolver el objeto, no solo el ID
+  items: [OrderItem!]!     # Lista no nula de elementos no nulos
+  totalAmount: Float!
+  createdAt: DateTime!
+}
+
+enum OrderStatus {
+  PENDING
+  COMPLETED
+  CANCELLED
+}
+
+# Queries: devolver nullable para elemento individual (no encontrado = null), no nulo para listas
+type Query {
+  order(id: ID!): Order       # Nullable — null si no se encuentra
+  orders(filter: OrderFilter): [Order!]!  # Lista no nula
+  me: User                    # Nullable — null si no está autenticado
+}
+
+# Mutations: siempre devolver el objeto mutado más un array de errores
+type Mutation {
+  createOrder(input: CreateOrderInput!): CreateOrderPayload!
+}
+
+type CreateOrderPayload {
+  order: Order          # Null si la mutation falló
+  errors: [UserError!]! # Vacío si fue exitoso
+}
+
+type UserError {
+  field: String
+  message: String!
+}
+```
+
+### Prevención de N+1 con DataLoader
+```typescript
+import DataLoader from 'dataloader';
+
+// Crear por solicitud — nunca singleton (aislamiento de datos de solicitud)
+export function createLoaders() {
+  return {
+    customerLoader: new DataLoader<string, Customer>(async (ids) => {
+      const customers = await db.customer.findMany({
+        where: { id: { in: [...ids] } }
+      });
+      // Debe devolver en el mismo orden que ids
+      const customerMap = new Map(customers.map(c => [c.id, c]));
+      return ids.map(id => customerMap.get(id) ?? new Error(`Customer ${id} not found`));
+    }),
+  };
+}
+
+// Resolver — usa el loader, no llamada directa a la BD
+const resolvers = {
+  Order: {
+    customer: (order, _, { loaders }) => loaders.customerLoader.load(order.customerId),
+  }
+};
+```
+
+### Paginación basada en cursor (preferida sobre offset)
+```graphql
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  node: Order!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type Query {
+  orders(first: Int, after: String, last: Int, before: String): OrderConnection!
+}
+```
+
+### Patrón de autorización
+```typescript
+// Autorización a nivel de campo en el resolver
+const resolvers = {
+  Query: {
+    adminStats: (_, __, { user }) => {
+      if (!user || user.role !== 'ADMIN') {
+        throw new GraphQLError('Unauthorized', {
+          extensions: { code: 'UNAUTHORIZED' }
+        });
+      }
+      return getAdminStats();
+    }
+  },
+  Order: {
+    // A nivel de objeto: solo devolver campos sensibles al propietario del pedido
+    internalNotes: (order, _, { user }) => {
+      if (user?.id !== order.customerId && user?.role !== 'ADMIN') return null;
+      return order.internalNotes;
+    }
+  }
+};
+```
+
+### Patrón de Prisma + GraphQL
+```typescript
+// Resolver usando Prisma — evitar over-fetching
+const resolvers = {
+  Query: {
+    order: async (_, { id }, { prisma, user }) => {
+      const order = await prisma.order.findUnique({
+        where: { id },
+        select: {
+          id: true,
+          status: true,
+          customerId: true,
+          totalAmount: true,
+          createdAt: true,
+          // NO seleccionar items aquí — dejar que el resolver de items lo maneje
+          // con DataLoader para evitar N+1
+        }
+      });
+      if (!order) return null;
+      if (order.customerId !== user?.id) throw new GraphQLError('Forbidden');
+      return order;
+    }
+  }
+};
+```
+
+## Ejemplo
+
+**Usuario:** Diseñar un esquema de GraphQL y resolvers para una API de comercio electrónico simple — productos, pedidos y clientes. Incluir paginación, DataLoader para clientes y manejo de errores en mutations.
+
+**Salida esperada:**
+- Esquema: tipos `Product`, `Order`, `Customer`, `OrderConnection`, `UserError`
+- `Query.orders` con paginación de cursor devolviendo `OrderConnection`
+- `Mutation.createOrder` devolviendo `CreateOrderPayload` con array de errores
+- Resolver `Order.customer` usando DataLoader (no consulta directa a la BD)
+- Función `createLoaders()` por solicitud, agrupando búsquedas de clientes por ID
+- Verificación de autenticación: solo los usuarios autenticados pueden ver sus propios pedidos
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. ¿Construyendo APIs GraphQL o capas de datos impulsadas por IA? [uitbreiden.com](https://uitbreiden.com/)

package/skills/database/fr/graphql.md

@@ -0,0 +1,181 @@
+> 🇫🇷 This is the French translation. [English version](../graphql.md).
+
+# Compétence GraphQL
+
+## Quand activer
+- Concevoir un schéma GraphQL (types, queries, mutations, subscriptions)
+- Implémenter des resolvers en Node.js (Apollo Server, Pothos, GraphQL Yoga)
+- Configurer Prisma avec une API GraphQL
+- Rédiger des queries et fragments GraphQL pour un client frontend
+- Implémenter une pagination cursor-based ou offset-based dans GraphQL
+- Configurer DataLoader pour la prévention des requêtes N+1
+- Ajouter l'authentification et l'autorisation à une API GraphQL
+- Déboguer les performances GraphQL ou les problèmes N+1
+
+## Quand NE PAS utiliser
+- APIs REST où GraphQL ajoute de la complexité sans bénéfice (CRUD simple, webhooks, upload de fichiers)
+- gRPC ou systèmes event-driven
+- Cas où le client a toujours besoin de la réponse complète (la sélection de champs de GraphQL n'apporte aucune valeur)
+
+## Instructions
+
+### Principes de conception du schéma
+```graphql
+# Noms de types : noms singuliers en PascalCase
+# Noms de champs : camelCase
+# Valeurs d'enum : SCREAMING_SNAKE_CASE
+
+type Order {
+  id: ID!
+  status: OrderStatus!
+  customer: Customer!       # Type imbriqué — toujours retourner l'objet, pas juste l'ID
+  items: [OrderItem!]!     # Liste non-null d'éléments non-null
+  totalAmount: Float!
+  createdAt: DateTime!
+}
+
+enum OrderStatus {
+  PENDING
+  COMPLETED
+  CANCELLED
+}
+
+# Queries : retourner nullable pour un seul élément (non trouvé = null), non-null pour les listes
+type Query {
+  order(id: ID!): Order       # Nullable — null si non trouvé
+  orders(filter: OrderFilter): [Order!]!  # Liste non-null
+  me: User                    # Nullable — null si non authentifié
+}
+
+# Mutations : toujours retourner l'objet muté plus un tableau d'erreurs
+type Mutation {
+  createOrder(input: CreateOrderInput!): CreateOrderPayload!
+}
+
+type CreateOrderPayload {
+  order: Order          # Null si la mutation a échoué
+  errors: [UserError!]! # Vide si succès
+}
+
+type UserError {
+  field: String
+  message: String!
+}
+```
+
+### Prévention N+1 avec DataLoader
+```typescript
+import DataLoader from 'dataloader';
+
+// Créer par requête — jamais singleton (isolation des données de requête)
+export function createLoaders() {
+  return {
+    customerLoader: new DataLoader<string, Customer>(async (ids) => {
+      const customers = await db.customer.findMany({
+        where: { id: { in: [...ids] } }
+      });
+      // Doit retourner dans le même ordre que ids
+      const customerMap = new Map(customers.map(c => [c.id, c]));
+      return ids.map(id => customerMap.get(id) ?? new Error(`Customer ${id} not found`));
+    }),
+  };
+}
+
+// Resolver — utilise le loader, pas un appel DB direct
+const resolvers = {
+  Order: {
+    customer: (order, _, { loaders }) => loaders.customerLoader.load(order.customerId),
+  }
+};
+```
+
+### Pagination cursor-based (préférée à l'offset)
+```graphql
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  node: Order!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+type Query {
+  orders(first: Int, after: String, last: Int, before: String): OrderConnection!
+}
+```
+
+### Pattern d'autorisation
+```typescript
+// Autorisation au niveau du champ dans le resolver
+const resolvers = {
+  Query: {
+    adminStats: (_, __, { user }) => {
+      if (!user || user.role !== 'ADMIN') {
+        throw new GraphQLError('Unauthorized', {
+          extensions: { code: 'UNAUTHORIZED' }
+        });
+      }
+      return getAdminStats();
+    }
+  },
+  Order: {
+    // Au niveau de l'objet : retourner les champs sensibles uniquement au propriétaire de la commande
+    internalNotes: (order, _, { user }) => {
+      if (user?.id !== order.customerId && user?.role !== 'ADMIN') return null;
+      return order.internalNotes;
+    }
+  }
+};
+```
+
+### Pattern Prisma + GraphQL
+```typescript
+// Resolver utilisant Prisma — éviter le sur-fetch
+const resolvers = {
+  Query: {
+    order: async (_, { id }, { prisma, user }) => {
+      const order = await prisma.order.findUnique({
+        where: { id },
+        select: {
+          id: true,
+          status: true,
+          customerId: true,
+          totalAmount: true,
+          createdAt: true,
+          // Ne PAS sélectionner items ici — laisser le resolver items le gérer
+          // avec DataLoader pour éviter N+1
+        }
+      });
+      if (!order) return null;
+      if (order.customerId !== user?.id) throw new GraphQLError('Forbidden');
+      return order;
+    }
+  }
+};
+```
+
+## Exemple
+
+**Utilisateur :** Concevoir un schéma GraphQL et des resolvers pour une API e-commerce simple — produits, commandes et clients. Inclure la pagination, DataLoader pour les clients et la gestion des erreurs de mutation.
+
+**Sortie attendue :**
+- Schéma : types `Product`, `Order`, `Customer`, `OrderConnection`, `UserError`
+- `Query.orders` avec pagination cursor retournant `OrderConnection`
+- `Mutation.createOrder` retournant `CreateOrderPayload` avec tableau d'erreurs
+- Resolver `Order.customer` utilisant DataLoader (pas de requête DB directe)
+- Fonction `createLoaders()` par requête, regroupant les recherches de clients par ID
+- Vérification d'auth : seuls les utilisateurs authentifiés peuvent voir leurs propres commandes
+
+---
+
+> **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 APIs GraphQL ou des couches de données alimentées par l'IA ? [uitbreiden.com](https://uitbreiden.com/)