whatsapp-cloud 0.0.3 → 0.0.5

package/src/services/messages/methods/send-image.ts

@@ -0,0 +1,33 @@
+import type { MessagesClient } from "../MessagesClient";
+import { sendImageRequestSchema } from "../../../schemas/messages/request";
+import type { SendImageRequest } from "../../../types/messages/request";
+import type { MessageResponse } from "../../../types/messages/response";
+import { buildMessagePayload } from "../utils/build-message-payload";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Send an image message
+ *
+ * @param messagesClient - Messages client with phone number ID baked in
+ * @param request - Image message request (to, image)
+ */
+export async function sendImage(
+  messagesClient: MessagesClient,
+  request: SendImageRequest
+): Promise<MessageResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = sendImageRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build message payload using common structure
+  // The request.image already matches the API structure, so we can pass it directly
+  const payload = buildMessagePayload(data.to, "image", {
+    image: data.image,
+  });
+
+  // Make API request - messagesClient handles the phoneNumberId prefix automatically
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}

package/src/services/messages/methods/send-location.ts

@@ -0,0 +1,32 @@
+import type { MessagesClient } from "../MessagesClient";
+import { sendLocationRequestSchema } from "../../../schemas/messages/request";
+import type { SendLocationRequest } from "../../../types/messages/request";
+import type { MessageResponse } from "../../../types/messages/response";
+import { buildMessagePayload } from "../utils/build-message-payload";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Send a location message
+ * 
+ * @param messagesClient - Messages client with phone number ID baked in
+ * @param request - Location message request (to, location)
+ */
+export async function sendLocation(
+  messagesClient: MessagesClient,
+  request: SendLocationRequest
+): Promise<MessageResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = sendLocationRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build message payload using common structure
+  const payload = buildMessagePayload(data.to, "location", {
+    location: data.location,
+  });
+
+  // Make API request - messagesClient handles the phoneNumberId prefix automatically
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}

package/src/services/messages/methods/send-reaction.ts

@@ -0,0 +1,33 @@
+import type { MessagesClient } from "../MessagesClient";
+import { sendReactionRequestSchema } from "../../../schemas/messages/request";
+import type { SendReactionRequest } from "../../../types/messages/request";
+import type { MessageResponse } from "../../../types/messages/response";
+import { buildMessagePayload } from "../utils/build-message-payload";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Send a reaction message
+ * 
+ * @param messagesClient - Messages client with phone number ID baked in
+ * @param request - Reaction message request (to, reaction)
+ */
+export async function sendReaction(
+  messagesClient: MessagesClient,
+  request: SendReactionRequest
+): Promise<MessageResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = sendReactionRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build message payload using common structure
+  const payload = buildMessagePayload(data.to, "reaction", {
+    reaction: data.reaction,
+  });
+
+  // Make API request - messagesClient handles the phoneNumberId prefix automatically
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}
+

package/src/services/messages/methods/send-text.ts

@@ -0,0 +1,32 @@
+import type { MessagesClient } from "../MessagesClient";
+import { sendTextRequestSchema } from "../../../schemas/messages/request";
+import type { SendTextRequest } from "../../../types/messages/request";
+import type { MessageResponse } from "../../../types/messages/response";
+import { buildMessagePayload } from "../utils/build-message-payload";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Send a text message
+ *
+ * @param messagesClient - Messages client with phone number ID baked in
+ * @param request - Text message request (to, text)
+ */
+export async function sendText(
+  messagesClient: MessagesClient,
+  request: SendTextRequest
+): Promise<MessageResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = sendTextRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build message payload using common structure
+  const payload = buildMessagePayload(data.to, "text", {
+    text: data.text,
+  });
+
+  // Make API request - messagesClient handles the phoneNumberId prefix automatically
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}

package/src/services/messages/utils/build-message-payload.ts

@@ -0,0 +1,32 @@
+/**
+ * Builds the base message payload structure that's common to all WhatsApp messages
+ *
+ * According to WhatsApp API docs, all messages follow this structure:
+ * {
+ *   "messaging_product": "whatsapp",
+ *   "recipient_type": "individual",
+ *   "to": "<WHATSAPP_USER_PHONE_NUMBER>",
+ *   "type": "<MESSAGE_TYPE>",
+ *   "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
+ * }
+ *
+ * Note: undefined values in content are automatically omitted by JSON.stringify
+ *
+ * @param to - WhatsApp phone number (E.164 format)
+ * @param type - Message type (text, image, video, etc.)
+ * @param content - Message-specific content object
+ * @returns Complete message payload ready for API request
+ */
+export function buildMessagePayload<T extends Record<string, unknown>>(
+  to: string,
+  type: string,
+  content: T
+) {
+  return {
+    messaging_product: "whatsapp" as const,
+    recipient_type: "individual" as const,
+    to,
+    type,
+    ...content,
+  };
+}

package/src/services/templates/TemplatesClient.ts

@@ -0,0 +1,35 @@
+import type { HttpClient } from "../../client/HttpClient";
+
+/**
+ * Templates client - wraps HttpClient with WABA ID as base endpoint
+ *
+ * This client automatically prepends `/${businessAccountId}` to all request paths.
+ * Similar to AccountsClient, since templates are scoped to WABA.
+ */
+export class TemplatesClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly businessAccountId: string
+  ) {}
+
+  /**
+   * Make a GET request with WABA ID prefix
+   */
+  async get<T>(path: string): Promise<T> {
+    return this.httpClient.get<T>(`/${this.businessAccountId}${path}`);
+  }
+
+  /**
+   * Make a POST request with WABA ID prefix
+   */
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.post<T>(`/${this.businessAccountId}${path}`, body);
+  }
+
+  /**
+   * Make a DELETE request with WABA ID prefix
+   */
+  async delete<T>(path: string): Promise<T> {
+    return this.httpClient.delete<T>(`/${this.businessAccountId}${path}`);
+  }
+}

package/src/services/templates/TemplatesService.ts

@@ -0,0 +1,117 @@
+import type { HttpClient } from "../../client/HttpClient";
+import { TemplatesClient } from "./TemplatesClient";
+import { createTemplate } from "./methods/create";
+import { listTemplates } from "./methods/list";
+import { getTemplate } from "./methods/get";
+import { updateTemplate } from "./methods/update";
+import { deleteTemplate } from "./methods/delete";
+import { WhatsAppValidationError } from "../../errors";
+import type {
+  CreateTemplateRequest,
+  UpdateTemplateRequest,
+  ListTemplatesRequest,
+  DeleteTemplateRequest,
+} from "../../types/templates/request";
+import type {
+  CreateTemplateResponse,
+  ListTemplatesResponse,
+  TemplateResponse,
+  UpdateTemplateResponse,
+  DeleteTemplateResponse,
+} from "../../types/templates/response";
+
+/**
+ * Templates service for managing message templates
+ *
+ * This service handles template operations like creating, listing, and deleting templates.
+ * It supports both a globally configured businessAccountId (in WhatsAppClient)
+ * and per-request businessAccountId overrides.
+ *
+ * Note: Get and Update operations use template ID directly (no WABA prefix needed).
+ */
+export class TemplatesService {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * Helper to create a Scoped Client (prefer override, fallback to config)
+   */
+  private getClient(overrideId?: string): TemplatesClient {
+    const id = overrideId || this.httpClient.businessAccountId;
+    if (!id) {
+      throw new WhatsAppValidationError(
+        "businessAccountId (WABA ID) is required for templates. Provide it in WhatsAppClient config or as a parameter.",
+        "businessAccountId"
+      );
+    }
+
+    return new TemplatesClient(this.httpClient, id);
+  }
+
+  /**
+   * Create a message template
+   *
+   * @param request - Template creation request
+   * @param businessAccountId - Optional WABA ID (overrides client config)
+   */
+  async create(
+    request: CreateTemplateRequest,
+    businessAccountId?: string
+  ): Promise<CreateTemplateResponse> {
+    const client = this.getClient(businessAccountId);
+    return createTemplate(client, request);
+  }
+
+  /**
+   * List message templates
+   *
+   * @param options - Optional filter options (name)
+   * @param businessAccountId - Optional WABA ID (overrides client config)
+   */
+  async list(
+    options?: ListTemplatesRequest,
+    businessAccountId?: string
+  ): Promise<ListTemplatesResponse> {
+    const client = this.getClient(businessAccountId);
+    return listTemplates(client, options);
+  }
+
+  /**
+   * Get a template by ID
+   *
+   * Note: This uses the template ID directly (no WABA prefix needed)
+   *
+   * @param templateId - Template ID
+   */
+  async get(templateId: string): Promise<TemplateResponse> {
+    return getTemplate(this.httpClient, templateId);
+  }
+
+  /**
+   * Update a template
+   *
+   * Note: This uses the template ID directly (no WABA prefix needed)
+   *
+   * @param templateId - Template ID
+   * @param request - Template update request
+   */
+  async update(
+    templateId: string,
+    request: UpdateTemplateRequest
+  ): Promise<UpdateTemplateResponse> {
+    return updateTemplate(this.httpClient, templateId, request);
+  }
+
+  /**
+   * Delete a template
+   *
+   * @param options - Delete options (name or hsm_id)
+   * @param businessAccountId - Optional WABA ID (overrides client config)
+   */
+  async delete(
+    options: DeleteTemplateRequest,
+    businessAccountId?: string
+  ): Promise<DeleteTemplateResponse> {
+    const client = this.getClient(businessAccountId);
+    return deleteTemplate(client, options);
+  }
+}

package/src/services/templates/index.ts

@@ -0,0 +1,3 @@
+export * from "./TemplatesService";
+export * from "./TemplatesClient";
+

package/src/services/templates/methods/create.ts

@@ -0,0 +1,27 @@
+import type { TemplatesClient } from "../TemplatesClient";
+import { createTemplateRequestSchema } from "../../../schemas/templates/request";
+import type { CreateTemplateRequest } from "../../../types/templates/request";
+import type { CreateTemplateResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Create a message template
+ *
+ * @param templatesClient - Templates client with WABA ID baked in
+ * @param request - Template creation request
+ */
+export async function createTemplate(
+  templatesClient: TemplatesClient,
+  request: CreateTemplateRequest
+): Promise<CreateTemplateResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = createTemplateRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Make API request - templatesClient handles the WABA ID prefix automatically
+  return templatesClient.post<CreateTemplateResponse>("/message_templates", data);
+}
+

package/src/services/templates/methods/delete.ts

@@ -0,0 +1,38 @@
+import type { TemplatesClient } from "../TemplatesClient";
+import { deleteTemplateRequestSchema } from "../../../schemas/templates/request";
+import type { DeleteTemplateRequest } from "../../../types/templates/request";
+import type { DeleteTemplateResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Delete a template
+ *
+ * @param templatesClient - Templates client with WABA ID baked in
+ * @param options - Delete options (name or hsm_id)
+ */
+export async function deleteTemplate(
+  templatesClient: TemplatesClient,
+  options: DeleteTemplateRequest
+): Promise<DeleteTemplateResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = deleteTemplateRequestSchema.safeParse(options);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build query string
+  const params = new URLSearchParams();
+  if (data.name) {
+    params.append("name", data.name);
+  }
+  if (data.hsm_id) {
+    params.append("hsm_id", data.hsm_id);
+  }
+  const queryString = params.toString();
+  const path = `/message_templates?${queryString}`;
+
+  // Make API request - templatesClient handles the WABA ID prefix automatically
+  return templatesClient.delete<DeleteTemplateResponse>(path);
+}
+

package/src/services/templates/methods/get.ts

@@ -0,0 +1,23 @@
+import type { HttpClient } from "../../../client/HttpClient";
+import type { TemplateResponse } from "../../../types/templates/response";
+
+/**
+ * Get a template by ID
+ *
+ * Note: This uses the template ID directly (no WABA prefix needed)
+ *
+ * @param httpClient - HTTP client
+ * @param templateId - Template ID
+ */
+export async function getTemplate(
+  httpClient: HttpClient,
+  templateId: string
+): Promise<TemplateResponse> {
+  if (!templateId || templateId.trim().length === 0) {
+    throw new Error("Template ID is required");
+  }
+
+  // Make API request - template ID is used directly, no WABA prefix
+  return httpClient.get<TemplateResponse>(`/${templateId}`);
+}
+

package/src/services/templates/methods/list.ts

@@ -0,0 +1,36 @@
+import type { TemplatesClient } from "../TemplatesClient";
+import { listTemplatesRequestSchema } from "../../../schemas/templates/request";
+import type { ListTemplatesRequest } from "../../../types/templates/request";
+import type { ListTemplatesResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * List message templates
+ *
+ * @param templatesClient - Templates client with WABA ID baked in
+ * @param options - Optional filter options (name)
+ */
+export async function listTemplates(
+  templatesClient: TemplatesClient,
+  options?: ListTemplatesRequest
+): Promise<ListTemplatesResponse> {
+  // Validate options if provided
+  if (options) {
+    const result = listTemplatesRequestSchema.safeParse(options);
+    if (!result.success) {
+      throw transformZodError(result.error);
+    }
+  }
+
+  // Build query string
+  const params = new URLSearchParams();
+  if (options?.name) {
+    params.append("name", options.name);
+  }
+  const queryString = params.toString();
+  const path = queryString ? `/message_templates?${queryString}` : "/message_templates";
+
+  // Make API request - templatesClient handles the WABA ID prefix automatically
+  return templatesClient.get<ListTemplatesResponse>(path);
+}
+

package/src/services/templates/methods/update.ts

@@ -0,0 +1,35 @@
+import type { HttpClient } from "../../../client/HttpClient";
+import { updateTemplateRequestSchema } from "../../../schemas/templates/request";
+import type { UpdateTemplateRequest } from "../../../types/templates/request";
+import type { UpdateTemplateResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Update a template
+ *
+ * Note: This uses the template ID directly (no WABA prefix needed)
+ *
+ * @param httpClient - HTTP client
+ * @param templateId - Template ID
+ * @param request - Template update request
+ */
+export async function updateTemplate(
+  httpClient: HttpClient,
+  templateId: string,
+  request: UpdateTemplateRequest
+): Promise<UpdateTemplateResponse> {
+  if (!templateId || templateId.trim().length === 0) {
+    throw new Error("Template ID is required");
+  }
+
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = updateTemplateRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Make API request - template ID is used directly, no WABA prefix
+  return httpClient.post<UpdateTemplateResponse>(`/${templateId}`, data);
+}
+

package/src/types/accounts/index.ts

@@ -0,0 +1 @@
+export type * from "./phone-number";

package/src/types/accounts/phone-number.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import { phoneNumberListResponseSchema } from "../../schemas/accounts/phone-number";
+
+/**
+ * Type for phone number list response
+ */
+export type PhoneNumberListResponse = z.infer<
+  typeof phoneNumberListResponseSchema
+>;

package/src/types/business/account.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { businessAccountsListResponseSchema } from "../../schemas/business/account";
+
+/**
+ * Type for WhatsApp Business Accounts list response
+ */
+export type BusinessAccountsListResponse = z.infer<
+  typeof businessAccountsListResponseSchema
+>;
+

package/src/types/business/index.ts

@@ -0,0 +1,2 @@
+export type * from "./account";
+

package/src/types/client.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { clientConfigSchema } from "../schemas/client";
+
+/**
+ * Client configuration type
+ */
+export type ClientConfig = z.infer<typeof clientConfigSchema>;
+

package/src/types/debug.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { debugTokenResponseSchema } from "../schemas/debug";
+
+/**
+ * Type for debug token response
+ */
+export type DebugTokenResponse = z.infer<typeof debugTokenResponseSchema>;
+

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export type * from "./client";
+export type * from "./messages/index";
+export type * from "./accounts/index";
+export type * from "./business/index";
+export type * from "./templates/index";
+export type * from "./debug";

package/src/types/messages/index.ts

@@ -0,0 +1,2 @@
+export type * from "./request";
+export type * from "./response";

package/src/types/messages/request.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import {
+  sendTextRequestSchema,
+  sendImageRequestSchema,
+  sendLocationRequestSchema,
+  sendReactionRequestSchema,
+} from "../../schemas/messages/request";
+
+/**
+ * Type for sending a text message
+ */
+export type SendTextRequest = z.infer<typeof sendTextRequestSchema>;
+
+/**
+ * Type for sending an image message
+ */
+export type SendImageRequest = z.infer<typeof sendImageRequestSchema>;
+
+/**
+ * Type for sending a location message
+ */
+export type SendLocationRequest = z.infer<typeof sendLocationRequestSchema>;
+
+/**
+ * Type for sending a reaction message
+ */
+export type SendReactionRequest = z.infer<typeof sendReactionRequestSchema>;

package/src/types/messages/response.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { messageResponseSchema } from "../../schemas/messages/response";
+
+/**
+ * Type for message response
+ */
+export type MessageResponse = z.infer<typeof messageResponseSchema>;

package/src/types/templates/component.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import {
+  buttonSchema,
+  componentSchema,
+  quickReplyButtonSchema,
+  urlButtonSchema,
+  phoneNumberButtonSchema,
+  copyCodeButtonSchema,
+  flowButtonSchema,
+  headerComponentSchema,
+  bodyComponentSchema,
+  footerComponentSchema,
+  buttonsComponentSchema,
+} from "../../schemas/templates/component";
+
+/**
+ * Button types
+ */
+export type QuickReplyButton = z.infer<typeof quickReplyButtonSchema>;
+export type UrlButton = z.infer<typeof urlButtonSchema>;
+export type PhoneNumberButton = z.infer<typeof phoneNumberButtonSchema>;
+export type CopyCodeButton = z.infer<typeof copyCodeButtonSchema>;
+export type FlowButton = z.infer<typeof flowButtonSchema>;
+export type Button = z.infer<typeof buttonSchema>;
+
+/**
+ * Component types
+ */
+export type HeaderComponent = z.infer<typeof headerComponentSchema>;
+export type BodyComponent = z.infer<typeof bodyComponentSchema>;
+export type FooterComponent = z.infer<typeof footerComponentSchema>;
+export type ButtonsComponent = z.infer<typeof buttonsComponentSchema>;
+export type Component = z.infer<typeof componentSchema>;

package/src/types/templates/index.ts

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

package/src/types/templates/request.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import {
+  createTemplateRequestSchema,
+  updateTemplateRequestSchema,
+  listTemplatesRequestSchema,
+  deleteTemplateRequestSchema,
+} from "../../schemas/templates/request";
+
+/**
+ * Type for creating a template
+ */
+export type CreateTemplateRequest = z.infer<typeof createTemplateRequestSchema>;
+
+/**
+ * Type for updating a template
+ */
+export type UpdateTemplateRequest = z.infer<typeof updateTemplateRequestSchema>;
+
+/**
+ * Type for listing templates
+ */
+export type ListTemplatesRequest = z.infer<typeof listTemplatesRequestSchema>;
+
+/**
+ * Type for deleting a template
+ */
+export type DeleteTemplateRequest = z.infer<typeof deleteTemplateRequestSchema>;
+