whatsapp-cloud 0.0.4 → 0.0.5

package/cloud-api-docs/webhooks/overview.md

@@ -0,0 +1,154 @@
+Nav-Logo
+Build with us
+Docs
+Blog
+Resources
+Developer centers
+Meine Apps
+Dokumente
+Übersicht
+Webhooks
+Webhooks
+Aktualisiert: 07.11.2025
+In diesem Dokument werden Webhooks beschrieben und wie sie auf der WhatsApp Business-Plattform verwendet werden.
+Webhooks sind HTTP-Anfragen mit JSON-Payloads, die von Meta-Servern an einen von dir bestimmten Server gesendet werden. Die WhatsApp Business-Plattform verwendet Webhooks, um dich über eingehende Nachrichten, den Status ausgehender Nachrichten und andere wichtige Informationen zu informieren, wie z. B. Änderungen an deinem Kontostatus, Upgrades der Nachrichtenfunktion und Änderungen an der Qualitätsbewertungen deiner Vorlagen.
+Hier siehst du einen Webhook, der eine Nachricht beschreibt, die von einem*einer WhatsApp-Benutzer*in an ein Unternehmen gesendet wurde:
+{
+"object": "whatsapp_business_account",
+"entry": [
+{
+"id": "102290129340398",
+"changes": [
+{
+"value": {
+"messaging_product": "whatsapp",
+"metadata": {
+"display_phone_number": "15550783881",
+"phone_number_id": "106540352242922"
+},
+"contacts": [
+{
+"profile": {
+"name": "Sheena Nelson"
+},
+"wa_id": "16505551234"
+}
+],
+"messages": [
+{
+"from": "16505551234",
+"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
+"timestamp": "1749416383",
+"type": "text"
+"text": {
+"body": "Does it come in another color?"
+}
+}
+]
+},
+"field": "messages"
+}
+]
+}
+]
+}
+
+Einen Webhook-Endpunkt erstellen
+Um Webhooks zu empfangen, musst du einen Webhook-Endpunkt erstellen und konfigurieren. Im Dokument Webhook-Endpunkt erstellen erfährst du, wie du deinen eigenen Endpunkt erstellst.
+Wenn du noch nicht bereit bist, deinen eigenen Endpunkt zu erstellen, kannst du einen Test-Webhook-Endpunkt erstellen, der Webhook-Payloads an die Konsole exportiert. Beachte jedoch, dass du deinen eigenen Endpunkt erstellen musst, bevor du deine App in einer Produktionsumgebung verwenden kannst.
+Berechtigungen
+Du benötigst die folgenden Berechtigungen, um Webhooks zu erhalten:
+whatsapp_business_messaging – für messages-Webhooks
+whatsapp_business_management – für alle anderen Webhooks
+Wenn du ein*e direkte*r Entwickler*in bist, gewähre deiner App über deine*n Systemnutzer*in diese Berechtigungen, wenn du dein Systemtoken generierst.
+Wenn du als Lösungsanbieter*in diese Berechtigungen benötigst, um deinen Unternehmenskunden entsprechende Services zur Verfügung zu stellen, musst du vor der App-Review die Genehmigung für erweiterten Zugriff auf die Berechtigungen erhalten. Erst dann können deine Unternehmenskunden deiner App während des Onboardings diese Berechtigungen erteilen.
+Felder
+Sobald du deinen Webhook-Endpunkt erstellt und konfiguriert hast, kannst du die folgenden Webhook-Felder abonnieren.
+Name des Feldes Beschreibung
+account_alerts
+Der account_alerts-Webhook benachrichtigt dich über Änderungen des Messaging-Limits, des Unternehmensprofils und des Status als offizielles Unternehmenskonto einer Unternehmenstelefonnummer.
+account_review_update
+Der account_review_update-Webhook benachrichtigt dich, wenn ein WhatsApp-Unternehmenskonto hinsichtlich der Einhaltung unserer Richtlinien überprüft wurde.
+account_update
+Der account_update-Webhook benachrichtigt dich über Änderungen an der partnergeführten Unternehmensverifizierung eines WhatsApp-Unternehmenskontos, seiner Berechtigung für den Tarif für internationale Authentifizierung oder seinem Hauptgeschäftsstandort, wenn das Konto mit einem*einer Lösungsanbieter*in geteilt wird, bei Richtlinien- oder Nutzungsbedingungsverstößen oder wenn es gelöscht wird.
+automatic_events
+Der automatic_events-Webhook benachrichtigt dich, wenn wir ein Kauf- oder Lead-Event in einem Chat-Thread zwischen dir und einem*einer WhatsApp-Nutzer*in erkennen, der*die dir über deine Click-to-WhatsApp Ad eine Nachricht gesendet hat. Dazu musst du Berichte für automatische Events aktiviert haben.
+business_capability_update
+Der business_capability_update-Webhook informiert dich über Änderungen der Funktionen für WhatsApp-Unternehmenskonto oder Business-Portfolio (Messaging-Limits, Telefonnummer-Limits usw.).
+history
+Der history-Webhook wird verwendet, um den Chatverlauf in der WhatsApp Business-App eines Unternehmenskunden zu synchronisieren, der von einem*einer Lösungsanbieter*in freigeschaltet wurde.
+message_template_components_update
+Der message_template_components_update-Webhook benachrichtigt dich über Änderungen an den Komponenten einer Vorlage.
+message_template_quality_update
+Der message_template_quality_update-Webhook benachrichtigt dich über Änderungen an der Qualitätsbewertung einer Vorlage.
+message_template_status_update
+Der message_template_status_update-Webhook benachrichtigt dich über Änderungen am Status einer vorhandenen Vorlage.
+messages
+Der messages-Webhook beschreibt Nachrichten, die von einem*einer WhatsApp-Nutzer*in an ein Unternehmen gesendet werden, und den Status von Nachrichten, die von einem Unternehmen an eine*n WhatsApp-Nutzer*in gesendet werden.
+partner_solutions
+Der partner_solutions-Webhook beschreibt Änderungen am Status einer Multi-Partner-Lösung.
+payment_configuration_update
+Der payment_configuration_update-Webhook informiert dich über Änderungen an Zahlungskonfigurationen für die Payments API für Indien und die Payments API für Brasilien.
+phone_number_name_update
+Der phone_number_name_update-Webhook informiert dich über die Verifizierung des Display-Namens der Unternehmenstelefonnummer.
+phone_number_quality_update
+Der phone_number_quality_update-Webhook benachrichtigt dich über Änderungen an der Durchsatzrate einer Unternehmenstelefonnummer.
+security
+Der security-Webhook benachrichtigt dich über Änderungen an den Sicherheitseinstellungen einer Unternehmenstelefonnummer.
+smb_app_state_sync
+Der smb_app_state_sync-Webhook wird zum Synchronisieren von Kontakten von Nutzer*innen der WhatsApp Business-App verwendet, die über eine*n Lösungsanbieter*in freigeschaltet wurden.
+smb_message_echoes
+Der smb_message_echoes-Webhook benachrichtigt dich über Nachrichten, die über die WhatsApp Business-App oder ein begleitendes („verknüpftes“) Gerät von einem Unternehmenskunden gesendet wurden, der über eine*n Lösungsanbieter*in für die Cloud API freigeschaltet wurde.
+template_category_update
+Der template_category_update-Webhook benachrichtigt dich über Änderungen an der Kategorie einer Vorlage.
+user_preferences
+Der user_preferences-Webhook benachrichtigt dich über Änderungen an den Marketing-Nachrichten-Einstellungen eines*einer WhatsApp-Nutzer*in.
+Webhooks überschreiben
+Du kannst einen alternativen Webhook-Endpunkt für messages-Webhooks für dein WhatsApp-Unternehmenskonto (WABA) oder deine Unternehmenstelefonnummer verwenden. Dieser kann für Testzwecke nützlich sein oder wenn du als Lösungsanbieter eindeutige Webhook-Endpunkte für alle deine registrierten Kund\*innen verwenden möchtest.
+In unserem Dokument zu Webhook-Überschreibungen erfährst du, wie du Webhooks überschreiben kannst.
+Payload-Größe
+Payload-Webhooks können bis zu 3 MB groß sein.
+Fehler bei der Webhook-Auslieferung
+Wenn wir eine Webhook-Anfrage an deinen Endpunkt senden und dein Server mit einem anderen HTTP-Statuscode als 200 antwortet oder wenn wir den Webhook aus einem anderen Grund nicht zustellen können, versuchen wir es so lange mit abnehmender Häufigkeit, bis die Anfrage erfolgreich ist, und zwar bis zu 7 Tage lang.
+Beachte, dass Wiederholungsversuche an alle Apps gesendet werden, die Webhooks (und ihre entsprechenden Felder) für das WhatsApp Business-Konto abonniert haben. Dies kann zu doppelten Webhook-Benachrichtigungen führen.
+IP-Adressen
+Du kannst die IP-Adressen unserer Webhook-Server abrufen, indem du in deinem Terminal den folgenden Befehl ausführst:
+whois -h whois.radb.net — '-i origin AS32934' | grep '^route' | awk '{print $2}' | sort
+Wir ändern diese IP-Adressen in regelmäßigen Abständen. Wenn du also unsere Server auf der Positivliste hast, solltest du diese Liste gelegentlich neu erstellen und deine Positivliste entsprechend aktualisieren.
+Problembehandlung
+Wenn du keine Webhooks erhältst:
+Vergewissere dich, dass dein Endpunkt Anfragen akzeptiert.
+Sende eine Test-Payload an deinen Endpunkt über das Panel App-Dashboard > WhatsApp > Konfigurationen.
+Stelle sicher, dass der Live-Modus für deine App aktiviert ist. Wenn deine App im Entwicklungsmodus ist, werden einige Webhooks nicht gesendet.
+Mehr dazu
+Siehe unseren Blogeintrag Implementierung von Webhooks mit Node.js für WhatsApp Business.
+War diese Seite hilfreich?
+„Daumen hoch“-Symbol
+„Daumen runter“-Symbol
+Meta
+FacebookInstagramXLinkedInYouTube
+Build with Meta
+AI
+Meta Horizon
+Social technologies
+Wearables
+News
+Meta for Developers
+Blog
+Success stories
+Support
+Developer Support
+Bug tool
+Platform status
+Developer community forum
+Report an incident
+About us
+About
+Careers
+Terms and policies
+Responsible platform initiatives
+Platform terms
+Developer policies
+Privacy policy
+Cookies
+English (US)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-cloud",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Work in progress. A WhatsApp client tailored for LLMs—built to actually work.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,10 @@
   "license": "MIT",
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@types/node": "^25.0.3",
+    "dotenv": "^17.2.3",
     "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
@@ -19,6 +22,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
-    "lint": "tsc"
+    "lint": "tsc",
+    "example": "tsx src/examples/main.ts"
   }
 }

package/src/client/HttpClient.ts

@@ -1,5 +1,12 @@
 import type { ClientConfig } from "../types/client";
 
+interface APIErrorResponse {
+  error?: {
+    message?: string;
+    code?: number;
+  };
+}
+
 /**
  * HTTP client for making requests to the WhatsApp Cloud API
  */
@@ -42,12 +49,12 @@ export class HttpClient {
     });
 
     if (!response.ok) {
-      const error = await response.json().catch(() => ({
+      const error = (await response.json().catch(() => ({
         error: {
           message: response.statusText,
           code: response.status,
         },
-      }));
+      }))) as APIErrorResponse;
       throw new Error(
         `API Error: ${error.error?.message || response.statusText} (${
           error.error?.code || response.status
@@ -72,12 +79,12 @@ export class HttpClient {
     });
 
     if (!response.ok) {
-      const error = await response.json().catch(() => ({
+      const error = (await response.json().catch(() => ({
         error: {
           message: response.statusText,
           code: response.status,
         },
-      }));
+      }))) as APIErrorResponse;
       throw new Error(
         `API Error: ${error.error?.message || response.statusText} (${
           error.error?.code || response.status
@@ -104,12 +111,42 @@ export class HttpClient {
     });
 
     if (!response.ok) {
-      const error = await response.json().catch(() => ({
+      const error = (await response.json().catch(() => ({
+        error: {
+          message: response.statusText,
+          code: response.status,
+        },
+      }))) as APIErrorResponse;
+      throw new Error(
+        `API Error: ${error.error?.message || response.statusText} (${
+          error.error?.code || response.status
+        })`
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Make a DELETE request
+   */
+  async delete<T>(path: string): Promise<T> {
+    const url = `${this.baseURL}/${this.apiVersion}${path}`;
+
+    const response = await fetch(url, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const error = (await response.json().catch(() => ({
         error: {
           message: response.statusText,
           code: response.status,
         },
-      }));
+      }))) as APIErrorResponse;
       throw new Error(
         `API Error: ${error.error?.message || response.statusText} (${
           error.error?.code || response.status

package/src/client/WhatsAppClient.ts

@@ -4,6 +4,7 @@ import { HttpClient } from "./HttpClient";
 import { MessagesService } from "../services/messages/index";
 import { AccountsService } from "../services/accounts/index";
 import { BusinessService } from "../services/business/index";
+import { TemplatesService } from "../services/templates/index";
 import { ZodError } from "zod";
 import { transformZodError } from "../utils/zod-error";
 import type { DebugTokenResponse } from "../types/debug";
@@ -15,6 +16,7 @@ export class WhatsAppClient {
   public readonly messages: MessagesService;
   public readonly accounts: AccountsService;
   public readonly business: BusinessService;
+  public readonly templates: TemplatesService;
 
   private readonly httpClient: HttpClient;
 
@@ -37,6 +39,7 @@ export class WhatsAppClient {
     this.messages = new MessagesService(this.httpClient);
     this.accounts = new AccountsService(this.httpClient);
     this.business = new BusinessService(this.httpClient);
+    this.templates = new TemplatesService(this.httpClient);
   }
 
   /**

package/src/examples/main.ts

@@ -0,0 +1,9 @@
+import "dotenv/config";
+import { WhatsAppClient } from "../client";
+
+const client = new WhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+});
+
+const debugInfo = await client.debugToken();
+console.log(debugInfo);

package/src/examples/template.ts

@@ -0,0 +1,134 @@
+import "dotenv/config";
+import { WhatsAppClient } from "../client";
+
+const client = new WhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+  businessAccountId: process.env.WHATSAPP_BUSINESS_ACCOUNT_ID!,
+});
+
+async function testTemplates() {
+  try {
+    console.log("🧪 Testing Templates API...\n");
+
+    // Test 1: Create a template
+    console.log("1️⃣ Creating template...");
+    const createResponse = await client.templates.create({
+      name: `test_template_${Date.now()}`, // Unique name to avoid conflicts
+      language: "en",
+      category: "UTILITY",
+      components: [
+        {
+          type: "BODY",
+          text: "Hello! This is a test template. Thank you for testing our WhatsApp Cloud API SDK.",
+        },
+        {
+          type: "FOOTER",
+          text: "This is a test footer",
+        },
+        {
+          type: "BUTTONS",
+          buttons: [
+            {
+              type: "QUICK_REPLY",
+              text: "Get Started",
+            },
+            {
+              type: "QUICK_REPLY",
+              text: "Learn More",
+            },
+          ],
+        },
+      ],
+    });
+
+    console.log("✅ Template created successfully!");
+    console.log("Response:", JSON.stringify(createResponse, null, 2));
+    console.log("\n");
+
+    // Verify create response structure
+    if (!createResponse.id) {
+      throw new Error("Create response missing 'id' field");
+    }
+    if (!createResponse.status) {
+      throw new Error("Create response missing 'status' field");
+    }
+    if (!createResponse.category) {
+      throw new Error("Create response missing 'category' field");
+    }
+    console.log("✅ Create response structure verified\n");
+
+    // Test 2: Get template by ID
+    console.log("2️⃣ Getting template by ID...");
+    const templateId = createResponse.id;
+    const getResponse = await client.templates.get(templateId);
+
+    console.log("✅ Template retrieved successfully!");
+    console.log("Response:", JSON.stringify(getResponse, null, 2));
+    console.log("\n");
+
+    // Verify get response structure
+    if (!getResponse.id) {
+      throw new Error("Get response missing 'id' field");
+    }
+    if (!getResponse.name) {
+      throw new Error("Get response missing 'name' field");
+    }
+    if (!getResponse.language) {
+      throw new Error("Get response missing 'language' field");
+    }
+    if (!getResponse.status) {
+      throw new Error("Get response missing 'status' field");
+    }
+    if (!getResponse.category) {
+      throw new Error("Get response missing 'category' field");
+    }
+    if (!Array.isArray(getResponse.components)) {
+      throw new Error("Get response missing 'components' array");
+    }
+    console.log("✅ Get response structure verified\n");
+
+    // Verify components
+    const bodyComponent = getResponse.components.find((c) => c.type === "BODY");
+    if (!bodyComponent) {
+      throw new Error("BODY component not found in response");
+    }
+    if (bodyComponent.type !== "BODY") {
+      throw new Error("BODY component type mismatch");
+    }
+    console.log("✅ Components verified\n");
+
+    // Test 3: List templates
+    console.log("3️⃣ Listing templates...");
+    const listResponse = await client.templates.list();
+    console.log(`✅ Found ${listResponse.data.length} template(s)`);
+    console.log("Response:", JSON.stringify(listResponse, null, 2));
+    console.log("\n");
+
+    // Verify list response structure
+    if (!Array.isArray(listResponse.data)) {
+      throw new Error("List response missing 'data' array");
+    }
+    console.log("✅ List response structure verified\n");
+
+    // Verify our created template is in the list
+    const foundTemplate = listResponse.data.find((t) => t.id === templateId);
+    if (!foundTemplate) {
+      console.log(
+        "⚠️  Note: Created template may not appear in list immediately (async processing)"
+      );
+    } else {
+      console.log("✅ Created template found in list\n");
+    }
+
+    console.log("🎉 All tests passed!");
+  } catch (error) {
+    console.error("❌ Test failed:", error);
+    if (error instanceof Error) {
+      console.error("Error message:", error.message);
+      console.error("Error stack:", error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+testTemplates();

package/src/schemas/client.ts

@@ -44,7 +44,7 @@ export const clientConfigSchema = z.object({
     .refine((val) => val === undefined || val.trim().length > 0, {
       message: "businessId cannot be empty or whitespace only",
     }),
-  apiVersion: z.string().default("v18.0"),
-  baseURL: z.string().url().default("https://graph.facebook.com"),
+  apiVersion: z.string().default("v18.0").optional(),
+  baseURL: z.string().url().default("https://graph.facebook.com").optional(),
   timeout: z.number().positive().optional(),
 });

package/src/schemas/index.ts

@@ -2,4 +2,5 @@ export * from "./client";
 export * from "./messages/index";
 export * from "./accounts/index";
 export * from "./business/index";
+export * from "./templates/index";
 export * from "./debug";

package/src/schemas/templates/component.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+
+/**
+ * Button schemas for template components
+ * Simplified version without variables for now
+ */
+
+/**
+ * Quick reply button schema
+ */
+export const quickReplyButtonSchema = z.object({
+  type: z.literal("QUICK_REPLY"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+});
+
+/**
+ * URL button schema
+ * Note: example field will be added later when we support variables
+ */
+export const urlButtonSchema = z.object({
+  type: z.literal("URL"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+  url: z.string().url().max(2000, "URL must be 2000 characters or less"),
+  // example: z.array(z.string()).optional(), // For later: when URL contains variables
+});
+
+/**
+ * Phone number button schema
+ */
+export const phoneNumberButtonSchema = z.object({
+  type: z.literal("PHONE_NUMBER"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+  phone_number: z
+    .string()
+    .min(1)
+    .max(20, "Phone number must be 20 characters or less"),
+});
+
+/**
+ * Copy code button schema
+ * Note: example field will be added later
+ */
+export const copyCodeButtonSchema = z.object({
+  type: z.literal("COPY_CODE"),
+  // example: z.string().max(15).optional(), // For later: example value to copy
+});
+
+/**
+ * Flow button schema (for authentication templates)
+ * Note: Will be expanded later when we support flow templates
+ */
+export const flowButtonSchema = z.object({
+  type: z.literal("FLOW"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+  flow_action: z.string().optional(),
+  flow_id: z.string().optional(),
+  navigate_screen: z.string().optional(),
+});
+
+/**
+ * Union of all button types
+ */
+export const buttonSchema = z.discriminatedUnion("type", [
+  quickReplyButtonSchema,
+  urlButtonSchema,
+  phoneNumberButtonSchema,
+  copyCodeButtonSchema,
+  flowButtonSchema,
+]);
+
+/**
+ * Header component schema
+ * Simplified - no variables/examples for now
+ *
+ * Note:
+ * - TEXT format requires text field
+ * - IMAGE/VIDEO/DOCUMENT formats require example.header_handle (for later)
+ * - LOCATION format requires neither text nor example
+ */
+export const headerComponentSchema = z
+  .object({
+    type: z.literal("HEADER"),
+    format: z.enum(["TEXT", "IMAGE", "VIDEO", "DOCUMENT", "LOCATION"]),
+    text: z
+      .string()
+      .max(60, "Header text must be 60 characters or less")
+      .optional(),
+    // example: z.object({...}).optional(), // For later: when using variables or media
+  })
+  .refine(
+    (data) => {
+      // TEXT format requires text
+      if (data.format === "TEXT" && !data.text) {
+        return false;
+      }
+      // LOCATION format doesn't need text
+      if (data.format === "LOCATION") {
+        return true;
+      }
+      // IMAGE/VIDEO/DOCUMENT will need example.header_handle (for later)
+      return true;
+    },
+    {
+      message: "TEXT format header requires text field",
+    }
+  );
+
+/**
+ * Body component schema
+ * Required component - no variables for now
+ */
+export const bodyComponentSchema = z.object({
+  type: z.literal("BODY"),
+  text: z
+    .string()
+    .min(1)
+    .max(1024, "Body text must be 1024 characters or less"),
+  // example: z.object({...}).optional(), // For later: when using variables
+});
+
+/**
+ * Footer component schema
+ */
+export const footerComponentSchema = z.object({
+  type: z.literal("FOOTER"),
+  text: z.string().min(1).max(60, "Footer text must be 60 characters or less"),
+});
+
+/**
+ * Buttons component schema
+ */
+export const buttonsComponentSchema = z.object({
+  type: z.literal("BUTTONS"),
+  buttons: z.array(buttonSchema).min(1).max(10, "Maximum 10 buttons allowed"),
+});
+
+/**
+ * Union of all component types
+ */
+export const componentSchema = z.discriminatedUnion("type", [
+  headerComponentSchema,
+  bodyComponentSchema,
+  footerComponentSchema,
+  buttonsComponentSchema,
+]);

package/src/schemas/templates/index.ts

@@ -0,0 +1,4 @@
+export * from "./component";
+export * from "./request";
+export * from "./response";
+

package/src/schemas/templates/request.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { componentSchema } from "./component";
+
+/**
+ * Schema for creating a template
+ * Simplified - no variables/examples for now
+ */
+export const createTemplateRequestSchema = z.object({
+  name: z.string().min(1).max(512, "Template name must be 512 characters or less"),
+  language: z.string().min(2).max(5, "Language code must be 2-5 characters (e.g., 'en' or 'en_US')"),
+  category: z.enum(["AUTHENTICATION", "MARKETING", "UTILITY"]),
+  components: z
+    .array(componentSchema)
+    .min(1, "At least one component is required")
+    .refine(
+      (components) => {
+        // Body component is required
+        return components.some((c) => c.type === "BODY");
+      },
+      { message: "BODY component is required" }
+    )
+    .refine(
+      (components) => {
+        // Only one header allowed
+        const headers = components.filter((c) => c.type === "HEADER");
+        return headers.length <= 1;
+      },
+      { message: "Only one HEADER component is allowed" }
+    )
+    .refine(
+      (components) => {
+        // Only one footer allowed
+        const footers = components.filter((c) => c.type === "FOOTER");
+        return footers.length <= 1;
+      },
+      { message: "Only one FOOTER component is allowed" }
+    )
+    .refine(
+      (components) => {
+        // Only one buttons component allowed
+        const buttons = components.filter((c) => c.type === "BUTTONS");
+        return buttons.length <= 1;
+      },
+      { message: "Only one BUTTONS component is allowed" }
+    ),
+});
+
+/**
+ * Schema for updating a template
+ * All fields optional - only update what's provided
+ */
+export const updateTemplateRequestSchema = z.object({
+  category: z.enum(["AUTHENTICATION", "MARKETING", "UTILITY"]).optional(),
+  components: z.array(componentSchema).optional(),
+  language: z.string().min(2).max(5).optional(),
+  name: z.string().min(1).max(512).optional(),
+});
+
+/**
+ * Schema for listing templates
+ */
+export const listTemplatesRequestSchema = z.object({
+  name: z.string().optional(), // Filter by template name
+});
+
+/**
+ * Schema for deleting a template
+ * Either name or hsm_id must be provided
+ */
+export const deleteTemplateRequestSchema = z
+  .object({
+    name: z.string().optional(),
+    hsm_id: z.string().optional(),
+  })
+  .refine((data) => data.name || data.hsm_id, {
+    message: "Either name or hsm_id must be provided",
+  });
+