better-zap 0.2.0 → 0.2.1

package/dist/client-DNlBPLBd.d.cts

@@ -0,0 +1,850 @@
+//#region src/types/whatsapp.types.d.ts
+/**
+ * Meta WhatsApp Cloud API v25.0 Type Definitions
+ * https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages
+ */
+interface WhatsAppTextMessage {
+  messaging_product: "whatsapp";
+  recipient_type: "individual";
+  to: string;
+  type: "text";
+  text: {
+    preview_url?: boolean;
+    body: string;
+  };
+}
+interface WhatsAppTemplateMessage {
+  messaging_product: "whatsapp";
+  to: string;
+  type: "template";
+  template: {
+    name: string;
+    language: {
+      code: string;
+    };
+    components?: TemplateComponent[];
+  };
+}
+interface WhatsAppInteractiveButtonsMessage {
+  messaging_product: "whatsapp";
+  recipient_type: "individual";
+  to: string;
+  type: "interactive";
+  interactive: {
+    type: "button";
+    body: {
+      text: string;
+    };
+    action: {
+      buttons: Array<{
+        type: "reply";
+        reply: {
+          id: string;
+          title: string;
+        };
+      }>;
+    };
+  };
+}
+interface WhatsAppInteractiveListMessage {
+  messaging_product: "whatsapp";
+  recipient_type: "individual";
+  to: string;
+  type: "interactive";
+  interactive: {
+    type: "list";
+    body: {
+      text: string;
+    };
+    action: {
+      button: string;
+      sections: Array<{
+        title: string;
+        rows: Array<{
+          id: string;
+          title: string;
+          description?: string;
+        }>;
+      }>;
+    };
+  };
+}
+interface WhatsAppInteractiveMediaCarouselMessage {
+  messaging_product: "whatsapp";
+  recipient_type: "individual";
+  to: string;
+  type: "interactive";
+  interactive: {
+    type: "carousel";
+    body: {
+      text: string;
+    };
+    action: {
+      cards: WhatsAppCarouselCard[];
+    };
+  };
+}
+interface InteractiveMediaCarouselCardInput {
+  header: {
+    type: "image" | "video";
+    link: string;
+  };
+  bodyText?: string;
+  button: {
+    displayText: string;
+    url: string;
+  };
+}
+interface SendInteractiveMediaCarouselData {
+  to: string;
+  body: string;
+  cards: InteractiveMediaCarouselCardInput[];
+}
+interface WhatsAppCarouselCard {
+  card_index: number;
+  type: "cta_url";
+  header: {
+    type: "image" | "video";
+    image?: {
+      link: string;
+    };
+    video?: {
+      link: string;
+    };
+  };
+  body?: {
+    text: string;
+  };
+  action: {
+    name: "cta_url";
+    parameters: {
+      display_text: string;
+      url: string;
+    };
+  };
+}
+interface WhatsAppLocationMessage {
+  messaging_product: "whatsapp";
+  recipient_type: "individual";
+  to: string;
+  type: "location";
+  location: {
+    latitude: number;
+    longitude: number;
+    name: string;
+    address: string;
+  };
+}
+interface TemplateComponent {
+  type: "header" | "body" | "button";
+  sub_type?: "url" | "quick_reply";
+  index?: string;
+  parameters: TemplateParameter[];
+}
+interface TemplateParameter {
+  type: "text" | "currency" | "date_time" | "image" | "document" | "video" | "location" | "payload";
+  parameter_name?: string;
+  text?: string;
+  currency?: {
+    fallback_value: string;
+    code: string;
+    amount_1000: number;
+  };
+  date_time?: {
+    fallback_value: string;
+  };
+  image?: {
+    link: string;
+  };
+  video?: {
+    link: string;
+  };
+  document?: {
+    link: string;
+  };
+  location?: {
+    latitude: number;
+    longitude: number;
+    name: string;
+    address: string;
+  };
+  payload?: string;
+}
+interface SendMessageResponse {
+  messaging_product: "whatsapp";
+  contacts: Array<{
+    input: string;
+    wa_id: string;
+  }>;
+  messages: Array<{
+    id: string;
+  }>;
+}
+interface SendMessageError {
+  error: {
+    message: string;
+    type: string;
+    code: number;
+    error_subcode?: number;
+    error_data?: {
+      messaging_product: string;
+      details: string;
+    };
+    fbtrace_id: string;
+  };
+}
+interface WebhookPayload {
+  object: "whatsapp_business_account";
+  entry: WebhookEntry[];
+}
+interface WebhookEntry {
+  id: string;
+  changes: WebhookChange[];
+}
+interface WebhookChange {
+  value: WebhookValue;
+  field: WhatsAppWebhookField;
+}
+type WhatsAppWebhookField = "messages" | "message_template_status_update" | "message_template_quality_update" | "phone_number_name_update" | "phone_number_quality_update" | "account_update" | "security" | "history" | "smb_app_state_sync" | "smb_message_echoes" | "account_offboarded" | "account_reconnected" | (string & {});
+interface WebhookValue {
+  messaging_product: "whatsapp";
+  metadata: {
+    display_phone_number: string;
+    phone_number_id: string;
+  };
+  contacts?: WebhookContact[];
+  messages?: IncomingMessage[];
+  statuses?: MessageStatus[];
+  errors?: WebhookError[];
+}
+interface WebhookContact {
+  profile: {
+    name: string;
+  };
+  wa_id: string;
+}
+interface IncomingMessage {
+  from: string;
+  id: string;
+  timestamp: string;
+  type: "text" | "image" | "audio" | "video" | "document" | "location" | "contacts" | "interactive" | "button" | "reaction" | "sticker" | "unsupported" | (string & {});
+  text?: {
+    body: string;
+  };
+  image?: MediaMessage;
+  audio?: MediaMessage;
+  video?: MediaMessage;
+  document?: MediaMessage & {
+    filename?: string;
+  };
+  location?: {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+  };
+  button?: {
+    text: string;
+    payload: string;
+  };
+  interactive?: {
+    type: "button_reply" | "list_reply";
+    button_reply?: {
+      id: string;
+      title: string;
+    };
+    list_reply?: {
+      id: string;
+      title: string;
+      description?: string;
+    };
+  };
+  context?: {
+    from: string;
+    id: string;
+  };
+  referral?: {
+    source_url: string;
+    source_type: "ad" | "post";
+    source_id: string;
+    headline: string;
+    body: string;
+    ctwa_clid?: string;
+  };
+  errors?: MessageError[];
+  edited?: boolean;
+  revoked?: boolean;
+  unsupported?: true;
+  [key: string]: unknown;
+}
+interface MediaMessage {
+  id: string;
+  mime_type: string;
+  sha256?: string;
+  caption?: string;
+}
+interface MessageStatus {
+  id: string;
+  status: "sent" | "delivered" | "read" | "failed";
+  timestamp: string;
+  recipient_id: string;
+  conversation?: {
+    id: string;
+    origin: {
+      type: "business_initiated" | "user_initiated" | "referral_conversion";
+    };
+    expiration_timestamp?: string;
+  };
+  pricing?: {
+    billable: boolean;
+    pricing_model: "CBP";
+    category: "business_initiated" | "user_initiated" | "referral_conversion";
+  };
+  errors?: MessageError[];
+}
+interface MessageError {
+  code: number;
+  title: string;
+  message: string;
+  error_data?: {
+    details: string;
+  };
+}
+interface WebhookError {
+  code: number;
+  title: string;
+  message: string;
+  error_data: {
+    details: string;
+  };
+}
+interface SendResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+  errorCode?: number;
+  code?: string;
+  httpStatus?: number;
+  details?: Record<string, any>;
+}
+type FreeformMessageWindow = {
+  isOpen: boolean;
+  lastIncomingMessageAt: string | null;
+  expiresAt: string | null;
+};
+type ConversationRecord = {
+  id: string;
+  phone: string;
+  contactName: string | null;
+  unreadCount: number;
+  status: string;
+  lastMessageAt: string;
+  lastMessagePreview: string | null;
+  lastDirection: string;
+  messageCount: number;
+  lastIncomingMessageAt: string | null;
+};
+type Conversation = ConversationRecord & {
+  freeformMessageWindow: FreeformMessageWindow;
+};
+type UIMessageStatus = "sent" | "delivered" | "read" | "failed";
+type UIMessage = {
+  id: string;
+  phone?: string;
+  content: string | null;
+  direction: "incoming" | "outgoing";
+  status: UIMessageStatus | string;
+  sentAt: string;
+  templateName?: string | null;
+  messageType?: string | null;
+  metadata?: Record<string, any> | null;
+};
+//#endregion
+//#region src/types/config.d.ts
+/** Configuration for {@link WhatsAppService}. */
+interface WhatsAppConfig {
+  /** System User access token for the WhatsApp Cloud API. */
+  token: string;
+  /** Phone number ID registered in Meta Business Manager. */
+  phoneId: string;
+  /** Set to `"development"` to skip real API calls and return mock responses. */
+  environment?: string;
+}
+//#endregion
+//#region src/types/sync-events.d.ts
+type ConversationSummary = Conversation;
+type NewMessageEvent = {
+  type: "NEW_MESSAGE";
+  message: WhatsAppLogRecord;
+  conversation: ConversationSummary;
+};
+type StatusUpdateEvent = {
+  type: "STATUS_UPDATE";
+  waMessageId: string;
+  status: WhatsAppStatus;
+  timestamp: string;
+  deliveredAt?: string | null;
+  readAt?: string | null;
+};
+type ConversationUpdateEvent = {
+  type: "CONVERSATION_UPDATE";
+  conversationId: string;
+  updates: Partial<ConversationSummary>;
+};
+type SyncEvent = NewMessageEvent | StatusUpdateEvent | ConversationUpdateEvent;
+//#endregion
+//#region src/logger.d.ts
+/**
+ * Centralized Logger for Better Zap
+ *
+ * Lightweight, injectable logger with structured JSON output.
+ * Cloudflare Workers compatible (no external dependencies).
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/** User-facing configuration (on betterZap config). */
+interface LoggerConfig {
+  disabled?: boolean;
+  level?: LogLevel;
+  log?: (level: LogLevel, message: string, context: Record<string, unknown>) => void;
+}
+/** Internal logger interface injected into services. */
+interface Logger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+declare function createLogger(config?: LoggerConfig): Logger;
+declare const noopLogger: Logger;
+declare function serializeError(err: unknown): Record<string, unknown>;
+//#endregion
+//#region src/services/message-logger.service.d.ts
+type WhatsAppDirection = "incoming" | "outgoing";
+type WhatsAppStatus = "sent" | "delivered" | "read" | "failed";
+declare const WHATSAPP_MESSAGE_TYPES: readonly ["queue_position", "next_in_line", "queue_optin", "marketing", "bot_reply", "reminder", "satisfaction", "incoming"];
+type WhatsAppMessageType = (typeof WHATSAPP_MESSAGE_TYPES)[number];
+interface WhatsAppLogRecord {
+  id: string;
+  conversationId: string;
+  userId?: string | null;
+  phone: string;
+  waMessageId?: string | null;
+  direction: WhatsAppDirection;
+  messageType: WhatsAppMessageType;
+  content: string | null;
+  templateName?: string | null;
+  status: WhatsAppStatus;
+  errorMessage?: string | null;
+  metadata?: any;
+  sentAt: string;
+  deliveredAt?: string | null;
+  readAt?: string | null;
+}
+type CreateWhatsAppLogParams = {
+  phone: string;
+  userId?: string;
+  contactName?: string;
+  direction: WhatsAppDirection;
+  messageType: WhatsAppMessageType;
+  content: string;
+  templateName?: string;
+  waMessageId?: string;
+  status: WhatsAppStatus;
+  errorMessage?: string;
+  metadata?: any;
+  sentAt: string;
+};
+/**
+ * Interface for database persistence of WhatsApp logs.
+ * Decouples Better Zap from any specific application database package.
+ */
+interface WhatsAppLogStore {
+  createWhatsAppLog(params: CreateWhatsAppLogParams): Promise<{
+    record: WhatsAppLogRecord;
+    created: boolean;
+  }>;
+  getMessageByWaId(waMessageId: string): Promise<WhatsAppLogRecord | null>;
+  updateWhatsAppLogByWaMessageId(waMessageId: string, updates: Partial<WhatsAppLogRecord>): Promise<void>;
+  /**
+   * Atomically update status only if the new status advances the lifecycle.
+   * Returns true if the row was updated, false if skipped (duplicate/regression).
+   *
+   * Progression: sent(1) → delivered(2) → read(3). failed(4) always wins.
+   */
+  updateStatusIfProgressed(waMessageId: string, newStatus: WhatsAppStatus, updates: Partial<WhatsAppLogRecord>): Promise<boolean>;
+  getConversationById(conversationId: string): Promise<ConversationRecord | null>;
+  getConversationByPhone(phone: string): Promise<ConversationRecord | null>;
+  getConversations(): Promise<ConversationRecord[]>;
+  getMessagesByConversationPaginated(conversationId: string, cursor?: string | null, limit?: number): Promise<Array<{
+    id: string;
+    phone?: string;
+    content: string | null;
+    direction: string;
+    status: string;
+    sentAt: string;
+    templateName?: string | null;
+    messageType?: string | null;
+    metadata?: any;
+  }>>;
+  /**
+   * Check if there's a recent outgoing message to this phone within N hours.
+   * Used for consumer-defined cooldown checks.
+   */
+  hasRecentOutgoingMessage(phone: string, withinHours: number): Promise<boolean>;
+}
+interface MessageLoggerNotifier {
+  notify(event: SyncEvent): Promise<void>;
+}
+declare class MessageLoggerService {
+  private store;
+  private notifier?;
+  private log;
+  constructor(store: WhatsAppLogStore, log: Logger, notifier?: MessageLoggerNotifier | undefined);
+  private notify;
+  getConversationById(conversationId: string): Promise<Conversation | null>;
+  getConversationByPhone(phone: string): Promise<Conversation | null>;
+  getConversations(): Promise<Conversation[]>;
+  /** @deprecated Prefer `getFreeformMessageWindow()`. */
+  getCustomerCareWindow(phone: string): Promise<FreeformMessageWindow>;
+  getFreeformMessageWindow(phone: string): Promise<FreeformMessageWindow>;
+  /**
+   * Check if a message with this waMessageId was already processed.
+   */
+  isDuplicate(waMessageId: string): Promise<boolean>;
+  /**
+   * Log outgoing message for LGPD compliance
+   */
+  logOutgoing(params: {
+    phone: string;
+    userId?: string;
+    messageType: WhatsAppMessageType;
+    content: string;
+    result: SendResult;
+    templateName?: string;
+    metadata?: Record<string, any>;
+  }): Promise<string>;
+  /**
+   * Update message status from webhook callback.
+   * Only applies if the new status advances the lifecycle (atomic, no race conditions).
+   * Returns true if the update was applied, false if skipped.
+   */
+  updateStatus(waMessageId: string, status: WhatsAppStatus, timestamp: string, errorMessage?: string): Promise<boolean>;
+  /**
+   * Check if there's a recent outgoing message to this phone within N hours.
+   *
+   * @param {string} phone : The phone number to check (in E.164 format)
+   * @param {number} [withinHours=24] : Time in hours to look for incoming messages
+   */
+  hasRecentOutgoingMessage(phone: string, withinHours?: number): Promise<boolean>;
+  /**
+   * Log incoming message (for audit trail)
+   */
+  logIncoming(params: {
+    phone: string;
+    waMessageId: string;
+    content: string;
+    sentAt: string;
+    senderName?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<boolean>;
+  /**
+   * Log an imported WhatsApp message with an explicit direction and timestamp.
+   * Used by coexistence history imports and app echo webhooks where the message
+   * did not originate from the local send API call.
+   */
+  logImportedMessage(params: {
+    phone: string;
+    waMessageId: string;
+    direction: WhatsAppDirection;
+    content: string;
+    sentAt: string;
+    senderName?: string;
+    messageType?: WhatsAppMessageType;
+    metadata?: Record<string, unknown>;
+  }): Promise<boolean>;
+}
+//#endregion
+//#region src/services/whatsapp.service.d.ts
+interface OutgoingLoggingMetadata {
+  userId?: string;
+  messageType: WhatsAppMessageType;
+  /** Human-readable content of the message to be stored in the log */
+  content: string;
+  /** Optional metadata for the log entry (e.g. campaign ID, additional context) */
+  metadata?: Record<string, any>;
+}
+declare class WhatsAppService {
+  private baseUrl;
+  private token;
+  private isDev;
+  private logger;
+  private log;
+  constructor(config: WhatsAppConfig, logger: MessageLoggerService, log: Logger);
+  /** Send a text message within the 24h free-form message window only. */
+  sendText(to: string, body: string, logging?: Omit<OutgoingLoggingMetadata, "content">): Promise<SendResult>;
+  /** Send a template message (works outside service window). */
+  sendTemplate(to: string, templateName: string, languageCode?: string, components?: TemplateComponent[], logging?: OutgoingLoggingMetadata): Promise<SendResult>;
+  /** Send an interactive message with reply buttons (up to 3). */
+  sendInteractiveButtons(to: string, bodyText: string, buttons: Array<{
+    id: string;
+    title: string;
+  }>, logging?: Omit<OutgoingLoggingMetadata, "content">): Promise<SendResult>;
+  /** Send an interactive list message with sections and rows. */
+  sendInteractiveList(to: string, bodyText: string, buttonLabel: string, sections: Array<{
+    title: string;
+    rows: Array<{
+      id: string;
+      title: string;
+      description?: string;
+    }>;
+  }>, logging?: Omit<OutgoingLoggingMetadata, "content">): Promise<SendResult>;
+  /** Send an interactive media carousel message (2-10 cards). */
+  sendInteractiveMediaCarousel(data: SendInteractiveMediaCarouselData, logging?: Omit<OutgoingLoggingMetadata, "content">): Promise<SendResult>;
+  /** Send a location pin message. */
+  sendLocation(to: string, latitude: number, longitude: number, name: string, address: string, logging?: Omit<OutgoingLoggingMetadata, "content">): Promise<SendResult>;
+  /**
+   * Mark an inbound message as read.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/mark-messages-as-read
+   */
+  markAsRead(messageId: string): Promise<SendResult>;
+  /**
+   * Show or hide a typing indicator in the chat.
+   * When starting, the indicator auto-dismisses after 25 seconds or when a message is sent.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/typing-indicators/
+   */
+  typingIndicator(messageId: string, action?: "typing_on" | "typing_off"): Promise<SendResult>;
+  /**
+   * Add a reaction to a message.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/reaction-messages
+   */
+  sendReaction(to: string, messageId: string, emoji: string): Promise<SendResult>;
+  /** Core send method with retry logic (2 retries, exponential backoff). */
+  private send;
+  private logSendResult;
+  /** Actually performs the network request with retries. */
+  private performRequest;
+}
+//#endregion
+//#region src/template-registry.d.ts
+type Simplify<TValue> = { [TKey in keyof TValue]: TValue[TKey] } & {};
+type TemplateParameterInputMap = {
+  text: string;
+  payload: string;
+  location: {
+    latitude: number;
+    longitude: number;
+    name: string;
+    address: string;
+  };
+  image: {
+    link: string;
+  };
+  video: {
+    link: string;
+  };
+  document: {
+    link: string;
+  };
+  currency: {
+    fallback_value: string;
+    code: string;
+    amount_1000: number;
+  };
+  date_time: {
+    fallback_value: string;
+  };
+};
+type SupportedTemplateParameterType = keyof TemplateParameterInputMap;
+interface TemplateParameterDefinition<TType extends SupportedTemplateParameterType = SupportedTemplateParameterType> {
+  name: string;
+  parameterName?: string;
+  type: TType;
+}
+type TemplateComponentDefinition = {
+  type: "header";
+  parameters: readonly TemplateParameterDefinition[];
+} | {
+  type: "body";
+  parameters: readonly TemplateParameterDefinition[];
+} | {
+  type: "button";
+  subType: "url" | "quick_reply";
+  index: string;
+  parameters: readonly TemplateParameterDefinition[];
+};
+interface TemplateDefinition {
+  language: string;
+  components?: readonly TemplateComponentDefinition[];
+}
+type TemplateRegistry = Record<string, TemplateDefinition>;
+type TemplateParameterDefinitionUnion<TTemplate extends TemplateDefinition> = TTemplate["components"] extends readonly TemplateComponentDefinition[] ? TTemplate["components"][number]["parameters"][number] : never;
+type TemplateParameterInput<TParameter extends TemplateParameterDefinition> = TParameter["type"] extends keyof TemplateParameterInputMap ? TemplateParameterInputMap[TParameter["type"]] : never;
+type TemplateParams<TTemplate extends TemplateDefinition> = Simplify<{ [TParameter in TemplateParameterDefinitionUnion<TTemplate> as TParameter["name"]]: TemplateParameterInput<TParameter> }>;
+type TemplateName<TTemplates extends TemplateRegistry> = Extract<keyof TTemplates, string>;
+type TypedTemplateOptions<TTemplates extends TemplateRegistry, TName extends TemplateName<TTemplates>> = {
+  language?: string;
+  params: TemplateParams<TTemplates[TName]>;
+};
+declare const EMPTY_TEMPLATE_REGISTRY: {};
+declare function defineTemplates<const TTemplates extends TemplateRegistry>(templates: TTemplates): TTemplates;
+declare function hasConfiguredTemplates<TTemplates extends TemplateRegistry>(templates: TTemplates): boolean;
+declare function getTemplateNames<TTemplates extends TemplateRegistry>(templates: TTemplates): TemplateName<TTemplates>[];
+declare function serializeTemplateFromRegistry(templates: TemplateRegistry, templateName: string, options: {
+  language?: string;
+  params: Record<string, unknown>;
+}): {
+  language: string;
+  components?: TemplateComponent[];
+};
+declare function serializeTemplateFromRegistry<TTemplates extends TemplateRegistry, TName extends TemplateName<TTemplates>>(templates: TTemplates, templateName: TName, options: TypedTemplateOptions<TTemplates, TName>): {
+  language: string;
+  components?: TemplateComponent[];
+};
+//#endregion
+//#region src/client.d.ts
+interface ZapClientOptions<TTemplates extends TemplateRegistry = {}> {
+  /**
+   * Base URL for the API. Defaults to `window.location.origin` in the browser.
+   * Useful for SSR or custom proxy setups.
+   */
+  baseURL?: string;
+  /**
+   * Base path for all routes. Must match the `basePath` used in `betterZap()`.
+   * @default "/api/whatsapp"
+   */
+  basePath?: string;
+  /**
+   * Custom fetch implementation. Defaults to the global `fetch`.
+   */
+  fetch?: typeof fetch;
+  /**
+   * How requests authenticate to the Better Zap HTTP routes. Defaults to
+   * sending requests as-is (ambient same-origin cookies). See {@link ZapTransport}
+   * and the {@link sessionTransport} / {@link apiKeyTransport} built-ins.
+   */
+  transport?: ZapTransport;
+  /**
+   * Optional template registry used only for type inference.
+   * The HTTP server still owns runtime serialization and validation.
+   */
+  templates?: TTemplates;
+}
+/**
+ * Controls how the client authenticates its requests to the Better Zap HTTP
+ * routes. This is the seam that lets a browser client talk to the API without
+ * embedding an API key: the app proxies Better Zap behind its own
+ * session-authenticated routes and the client just forwards the session.
+ *
+ * Two built-ins cover the common cases:
+ * - {@link sessionTransport} — session/proxy auth: sends same-origin
+ *   credentials (cookies) and no API key. Use when a trusted server owns the
+ *   session and proxies Better Zap (e.g. a dashboard's own authed routes).
+ * - {@link apiKeyTransport} — sends `Authorization: Bearer <key>`. Use for
+ *   server-to-server calls in a trusted environment.
+ *
+ * Implement the interface directly for anything else (e.g. a rotating token).
+ */
+interface ZapTransport {
+  /** Extra headers merged onto every request. Called per request, may be async. */
+  headers?(): Record<string, string> | Promise<Record<string, string>>;
+  /** Fetch credentials mode; `sessionTransport` sets `"include"`. */
+  credentials?: RequestCredentials;
+}
+/**
+ * Session/proxy transport: send same-origin credentials (cookies), no API key.
+ * The recommended browser default when the app proxies Better Zap behind its
+ * own authenticated routes.
+ */
+declare function sessionTransport(): ZapTransport;
+/** API-key transport: send `Authorization: Bearer <apiKey>` on every request. */
+declare function apiKeyTransport(apiKey: string): ZapTransport;
+declare class BetterZapClientError extends Error {
+  status: number;
+  code?: string;
+  details?: unknown;
+  body?: unknown;
+  constructor(message: string, options: {
+    status: number;
+    code?: string;
+    details?: unknown;
+    body?: unknown;
+  });
+}
+interface SendTextParams {
+  to: string;
+  body: string;
+  messageType?: string;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface SendTemplateRawParams {
+  to: string;
+  template: string;
+  language?: string;
+  components?: unknown[];
+  logging?: OutgoingLoggingMetadata;
+}
+type SendTemplateTypedParams<TTemplates extends TemplateRegistry, TName extends TemplateName<TTemplates>> = {
+  to: string;
+  template: TName;
+  language?: string;
+  params: TemplateParams<TTemplates[TName]>;
+  logging?: OutgoingLoggingMetadata;
+};
+type SendTemplateMethod<TTemplates extends TemplateRegistry> = [TemplateName<TTemplates>] extends [never] ? (params: SendTemplateRawParams) => Promise<SendResult> : <TName extends TemplateName<TTemplates>>(params: SendTemplateTypedParams<TTemplates, TName>) => Promise<SendResult>;
+interface SendInteractiveParams {
+  to: string;
+  type: "button" | "list" | "carousel";
+  body: string;
+  buttons?: Array<{
+    id: string;
+    title: string;
+  }>;
+  buttonLabel?: string;
+  sections?: Array<{
+    title: string;
+    rows: Array<{
+      id: string;
+      title: string;
+      description?: string;
+    }>;
+  }>;
+  cards?: SendInteractiveMediaCarouselData["cards"];
+  messageType?: string;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface SendLocationParams {
+  to: string;
+  latitude: number;
+  longitude: number;
+  name: string;
+  address: string;
+  messageType?: string;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface GetMessagesOptions {
+  cursor?: string;
+  limit?: number;
+}
+interface ZapClient<TTemplates extends TemplateRegistry = {}> {
+  send: {
+    text(params: SendTextParams): Promise<SendResult>;
+    template: SendTemplateMethod<TTemplates>;
+    templateRaw(params: SendTemplateRawParams): Promise<SendResult>;
+    interactive(params: SendInteractiveParams): Promise<SendResult>;
+    location(params: SendLocationParams): Promise<SendResult>;
+  };
+  conversations: {
+    list(): Promise<Conversation[]>;
+    get(phone: string): Promise<Conversation | null>;
+    messages(phone: string, opts?: GetMessagesOptions): Promise<UIMessage[]>;
+  };
+}
+declare function createZapClient<TTemplates extends TemplateRegistry = {}>(options?: ZapClientOptions<TTemplates>): ZapClient<TTemplates>;
+//#endregion
+export { SendResult as $, LogLevel as A, SyncEvent as B, MessageLoggerService as C, WhatsAppLogStore as D, WhatsAppLogRecord as E, serializeError as F, IncomingMessage as G, Conversation as H, ConversationSummary as I, MessageError as J, InteractiveMediaCarouselCardInput as K, ConversationUpdateEvent as L, LoggerConfig as M, createLogger as N, WhatsAppMessageType as O, noopLogger as P, SendMessageResponse as Q, NewMessageEvent as R, MessageLoggerNotifier as S, WhatsAppDirection as T, ConversationRecord as U, WhatsAppConfig as V, FreeformMessageWindow as W, SendInteractiveMediaCarouselData as X, MessageStatus as Y, SendMessageError as Z, getTemplateNames as _, WhatsAppWebhookField as _t, createZapClient as a, WebhookContact as at, OutgoingLoggingMetadata as b, SupportedTemplateParameterType as c, WebhookPayload as ct, TemplateName as d, WhatsAppInteractiveButtonsMessage as dt, TemplateComponent as et, TemplateParameterDefinition as f, WhatsAppInteractiveListMessage as ft, defineTemplates as g, WhatsAppTextMessage as gt, TemplateRegistry as h, WhatsAppTemplateMessage as ht, apiKeyTransport as i, WebhookChange as it, Logger as j, WhatsAppStatus as k, TemplateComponentDefinition as l, WebhookValue as lt, TemplateParams as m, WhatsAppLocationMessage as mt, ZapClient as n, UIMessage as nt, sessionTransport as o, WebhookEntry as ot, TemplateParameterInputMap as p, WhatsAppInteractiveMediaCarouselMessage as pt, MediaMessage as q, ZapTransport as r, UIMessageStatus as rt, EMPTY_TEMPLATE_REGISTRY as s, WebhookError as st, BetterZapClientError as t, TemplateParameter as tt, TemplateDefinition as u, WhatsAppCarouselCard as ut, hasConfiguredTemplates as v, WHATSAPP_MESSAGE_TYPES as w, WhatsAppService as x, serializeTemplateFromRegistry as y, StatusUpdateEvent as z };