better-zap 25.0.1 → 25.0.3

package/README.md

@@ -10,3 +10,33 @@ Framework-agnostic Better Zap core.
 - logging primitives and message log store interfaces
 - transport-neutral webhook event and plugin contracts
 - link preview helpers: `firstLinkIn(text)` and `parseOpenGraph(html, pageUrl)` (fetching stays in your app; see the [link previews guide](https://github.com/Dosbodoke/better-zap/blob/main/landing/content/docs/guides/link-previews.mdx))
+- `MediaStore` interface for keeping incoming media past Meta's 7-day expiry, and an S3-compatible adapter at `better-zap/s3` (`createS3MediaStore`, for R2, AWS S3, MinIO and B2; see the [media storage guide](https://github.com/Dosbodoke/better-zap/blob/main/landing/content/docs/guides/media-storage.mdx))
+
+## Coexistence onboarding
+
+`launchCoexistenceEmbeddedSignup()` waits for both halves of an Embedded Signup
+completion: the `FB.login` code and the `WA_EMBEDDED_SIGNUP` session event.
+They can arrive in either order. `controller.result` settles once with a
+`status`:
+
+| Status | Meaning |
+| --- | --- |
+| `completed` | FINISH event and code both arrived. |
+| `finished_without_code` | FINISH arrived without a code. Meta sends the code only when the customer clicks Finish. |
+| `missing_session` | A code arrived but no terminal event did within `joinTimeoutMs`. This is not a confirmed onboarding. |
+| `cancelled` / `error` | The latest terminal event was CANCEL / ERROR. |
+| `no_authorization` | The login callback had no code and no event arrived. |
+| `torn_down` | `teardown()` ran first. |
+
+Session events are accepted from `facebook.com` origins when they have no
+`version` (Meta's documented shape) or `version: 3`. Other versions and
+malformed data are ignored. `joinTimeoutMs` defaults to 5000. Codes expire after
+about 30 seconds, so keep it short. `result` rejects only if `FB.login` throws.
+
+`CoexistenceService.exchangeEmbeddedSignupCode()` sends `redirect_uri` only when
+you pass `redirectUri`. Failures keep `error`, `errorCode`, `httpStatus` and the
+raw `details` body. They also include `diagnostics`, a log-safe summary with
+`kind`, HTTP status, Graph code, subcode, type, `fbtraceId` and `retryable`. It
+never contains tokens, the app secret, the code, URLs or Meta's message text.
+Log `diagnostics`, not `details`. A 200 response without an access token
+returns `kind: "malformed_response"`.

package/dist/{client-DNlBPLBd.d.cts → client-B49AT0HF.d.mts}

@@ -1,3 +1,5 @@
+import { d as MessageMedia, o as MediaDownloadOptions, s as MediaDownloadResult } from "./types-B9sxujNH.mjs";
+
 //#region src/types/whatsapp.types.d.ts
 /**
  * Meta WhatsApp Cloud API v25.0 Type Definitions
@@ -227,7 +229,7 @@ interface IncomingMessage {
   from: string;
   id: string;
   timestamp: string;
-  type: "text" | "image" | "audio" | "video" | "document" | "location" | "contacts" | "interactive" | "button" | "reaction" | "sticker" | "unsupported" | (string & {});
+  type: "text" | "image" | "audio" | "video" | "document" | "location" | "contacts" | "interactive" | "button" | "reaction" | "sticker" | "unsupported" /** Coexistence history media with the content omitted. See `isMediaPlaceholder`. */ | "media_placeholder" | (string & {});
   text?: {
     body: string;
   };
@@ -237,6 +239,9 @@ interface IncomingMessage {
   document?: MediaMessage & {
     filename?: string;
   };
+  sticker?: MediaMessage & {
+    animated?: boolean;
+  };
   location?: {
     latitude: number;
     longitude: number;
@@ -391,7 +396,15 @@ type ConversationUpdateEvent = {
   conversationId: string;
   updates: Partial<ConversationSummary>;
 };
-type SyncEvent = NewMessageEvent | StatusUpdateEvent | ConversationUpdateEvent;
+/**
+ * An existing message changed, e.g. a history media placeholder was replaced
+ * by the real media, or its media file was stored (`metadata.media`).
+ */
+type MessageUpdateEvent = {
+  type: "MESSAGE_UPDATE";
+  message: WhatsAppLogRecord;
+};
+type SyncEvent = NewMessageEvent | StatusUpdateEvent | ConversationUpdateEvent | MessageUpdateEvent;
 //#endregion
 //#region src/logger.d.ts
 /**
@@ -501,6 +514,7 @@ declare class MessageLoggerService {
   private log;
   constructor(store: WhatsAppLogStore, log: Logger, notifier?: MessageLoggerNotifier | undefined);
   private notify;
+  private notifyNewMessage;
   getConversationById(conversationId: string): Promise<Conversation | null>;
   getConversationByPhone(phone: string): Promise<Conversation | null>;
   getConversations(): Promise<Conversation[]>;
@@ -551,18 +565,55 @@ declare class MessageLoggerService {
    * 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.
+   *
+   * Returns true only when a new row was created. See {@link importMessage}
+   * for the detailed result, including placeholder upgrades.
    */
-  logImportedMessage(params: {
-    phone: string;
-    waMessageId: string;
-    direction: WhatsAppDirection;
-    content: string;
-    sentAt: string;
-    senderName?: string;
-    messageType?: WhatsAppMessageType;
-    metadata?: Record<string, unknown>;
-  }): Promise<boolean>;
+  logImportedMessage(params: ImportMessageParams): Promise<boolean>;
+  /**
+   * Import a WhatsApp message, deduplicated by `waMessageId`.
+   *
+   * When a row with the same id already exists and still holds a history media
+   * placeholder (see {@link hasPendingMedia}), and the new message has real
+   * content, the stored content and metadata are replaced and a
+   * `MESSAGE_UPDATE` sync event is sent. A placeholder never overwrites real
+   * content.
+   *
+   * Relies on `createWhatsAppLog` returning the existing row with
+   * `created: false` for a known `waMessageId`.
+   */
+  importMessage(params: ImportMessageParams): Promise<ImportMessageResult>;
+  /**
+   * Save the result of a media download as `metadata.media` on a stored
+   * message and send a `MESSAGE_UPDATE` sync event.
+   *
+   * Only the `media` field is written; other metadata fields are kept. A
+   * stored file is never replaced by a failed or skipped result.
+   *
+   * Returns the updated record, or `null` when the message isn't stored or
+   * the update was skipped.
+   */
+  setMessageMedia(waMessageId: string, media: MessageMedia): Promise<WhatsAppLogRecord | null>;
+  /** Writes `updates` to a stored message and sends `MESSAGE_UPDATE`. */
+  private updateMessage;
+  private replaceMediaPlaceholder;
 }
+type ImportMessageParams = {
+  phone: string;
+  waMessageId: string;
+  direction: WhatsAppDirection;
+  content: string;
+  sentAt: string;
+  senderName?: string;
+  messageType?: WhatsAppMessageType;
+  metadata?: Record<string, unknown>;
+};
+/**
+ * - `created`: a new row was stored.
+ * - `duplicate`: a row with this `waMessageId` already existed and was left as is.
+ * - `upgraded`: a stored media placeholder was replaced with the real media.
+ */
+type ImportMessageResult = "created" | "duplicate" | "upgraded";
 //#endregion
 //#region src/services/whatsapp.service.d.ts
 interface OutgoingLoggingMetadata {
@@ -621,6 +672,17 @@ declare class WhatsAppService {
    * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/reaction-messages
    */
   sendReaction(to: string, messageId: string, emoji: string): Promise<SendResult>;
+  /**
+   * Download a media file received in a webhook (image, audio, video,
+   * document or sticker), using the configured access token.
+   *
+   * Meta deletes webhook media after 7 days. Never throws: failures and files
+   * over `maxBytes` are returned as results. Runs in development mode too,
+   * since it sends nothing.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media
+   */
+  downloadMedia(mediaId: string, options?: MediaDownloadOptions): Promise<MediaDownloadResult>;
   /** Core send method with retry logic (2 retries, exponential backoff). */
   private send;
   private logSendResult;
@@ -847,4 +909,4 @@ interface ZapClient<TTemplates extends TemplateRegistry = {}> {
 }
 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 };
+export { SendInteractiveMediaCarouselData as $, WhatsAppMessageType as A, MessageUpdateEvent as B, ImportMessageResult as C, WhatsAppDirection as D, WHATSAPP_MESSAGE_TYPES as E, createLogger as F, Conversation as G, StatusUpdateEvent as H, noopLogger as I, IncomingMessage as J, ConversationRecord as K, serializeError as L, LogLevel as M, Logger as N, WhatsAppLogRecord as O, LoggerConfig as P, MessageStatus as Q, ConversationSummary as R, ImportMessageParams as S, MessageLoggerService as T, SyncEvent as U, NewMessageEvent as V, WhatsAppConfig as W, MediaMessage as X, InteractiveMediaCarouselCardInput as Y, MessageError as Z, getTemplateNames as _, WhatsAppLocationMessage as _t, createZapClient as a, UIMessage as at, OutgoingLoggingMetadata as b, WhatsAppWebhookField as bt, SupportedTemplateParameterType as c, WebhookContact as ct, TemplateName as d, WebhookPayload as dt, SendMessageError as et, TemplateParameterDefinition as f, WebhookValue as ft, defineTemplates as g, WhatsAppInteractiveMediaCarouselMessage as gt, TemplateRegistry as h, WhatsAppInteractiveListMessage as ht, apiKeyTransport as i, TemplateParameter as it, WhatsAppStatus as j, WhatsAppLogStore as k, TemplateComponentDefinition as l, WebhookEntry as lt, TemplateParams as m, WhatsAppInteractiveButtonsMessage as mt, ZapClient as n, SendResult as nt, sessionTransport as o, UIMessageStatus as ot, TemplateParameterInputMap as p, WhatsAppCarouselCard as pt, FreeformMessageWindow as q, ZapTransport as r, TemplateComponent as rt, EMPTY_TEMPLATE_REGISTRY as s, WebhookChange as st, BetterZapClientError as t, SendMessageResponse as tt, TemplateDefinition as u, WebhookError as ut, hasConfiguredTemplates as v, WhatsAppTemplateMessage as vt, MessageLoggerNotifier as w, WhatsAppService as x, serializeTemplateFromRegistry as y, WhatsAppTextMessage as yt, ConversationUpdateEvent as z };

package/dist/{client-DiHHMG8t.d.mts → client-B6XKmfej.d.cts}

@@ -1,3 +1,5 @@
+import { d as MessageMedia, o as MediaDownloadOptions, s as MediaDownloadResult } from "./types-C3niCOVI.cjs";
+
 //#region src/types/whatsapp.types.d.ts
 /**
  * Meta WhatsApp Cloud API v25.0 Type Definitions
@@ -227,7 +229,7 @@ interface IncomingMessage {
   from: string;
   id: string;
   timestamp: string;
-  type: "text" | "image" | "audio" | "video" | "document" | "location" | "contacts" | "interactive" | "button" | "reaction" | "sticker" | "unsupported" | (string & {});
+  type: "text" | "image" | "audio" | "video" | "document" | "location" | "contacts" | "interactive" | "button" | "reaction" | "sticker" | "unsupported" /** Coexistence history media with the content omitted. See `isMediaPlaceholder`. */ | "media_placeholder" | (string & {});
   text?: {
     body: string;
   };
@@ -237,6 +239,9 @@ interface IncomingMessage {
   document?: MediaMessage & {
     filename?: string;
   };
+  sticker?: MediaMessage & {
+    animated?: boolean;
+  };
   location?: {
     latitude: number;
     longitude: number;
@@ -391,7 +396,15 @@ type ConversationUpdateEvent = {
   conversationId: string;
   updates: Partial<ConversationSummary>;
 };
-type SyncEvent = NewMessageEvent | StatusUpdateEvent | ConversationUpdateEvent;
+/**
+ * An existing message changed, e.g. a history media placeholder was replaced
+ * by the real media, or its media file was stored (`metadata.media`).
+ */
+type MessageUpdateEvent = {
+  type: "MESSAGE_UPDATE";
+  message: WhatsAppLogRecord;
+};
+type SyncEvent = NewMessageEvent | StatusUpdateEvent | ConversationUpdateEvent | MessageUpdateEvent;
 //#endregion
 //#region src/logger.d.ts
 /**
@@ -501,6 +514,7 @@ declare class MessageLoggerService {
   private log;
   constructor(store: WhatsAppLogStore, log: Logger, notifier?: MessageLoggerNotifier | undefined);
   private notify;
+  private notifyNewMessage;
   getConversationById(conversationId: string): Promise<Conversation | null>;
   getConversationByPhone(phone: string): Promise<Conversation | null>;
   getConversations(): Promise<Conversation[]>;
@@ -551,18 +565,55 @@ declare class MessageLoggerService {
    * 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.
+   *
+   * Returns true only when a new row was created. See {@link importMessage}
+   * for the detailed result, including placeholder upgrades.
    */
-  logImportedMessage(params: {
-    phone: string;
-    waMessageId: string;
-    direction: WhatsAppDirection;
-    content: string;
-    sentAt: string;
-    senderName?: string;
-    messageType?: WhatsAppMessageType;
-    metadata?: Record<string, unknown>;
-  }): Promise<boolean>;
+  logImportedMessage(params: ImportMessageParams): Promise<boolean>;
+  /**
+   * Import a WhatsApp message, deduplicated by `waMessageId`.
+   *
+   * When a row with the same id already exists and still holds a history media
+   * placeholder (see {@link hasPendingMedia}), and the new message has real
+   * content, the stored content and metadata are replaced and a
+   * `MESSAGE_UPDATE` sync event is sent. A placeholder never overwrites real
+   * content.
+   *
+   * Relies on `createWhatsAppLog` returning the existing row with
+   * `created: false` for a known `waMessageId`.
+   */
+  importMessage(params: ImportMessageParams): Promise<ImportMessageResult>;
+  /**
+   * Save the result of a media download as `metadata.media` on a stored
+   * message and send a `MESSAGE_UPDATE` sync event.
+   *
+   * Only the `media` field is written; other metadata fields are kept. A
+   * stored file is never replaced by a failed or skipped result.
+   *
+   * Returns the updated record, or `null` when the message isn't stored or
+   * the update was skipped.
+   */
+  setMessageMedia(waMessageId: string, media: MessageMedia): Promise<WhatsAppLogRecord | null>;
+  /** Writes `updates` to a stored message and sends `MESSAGE_UPDATE`. */
+  private updateMessage;
+  private replaceMediaPlaceholder;
 }
+type ImportMessageParams = {
+  phone: string;
+  waMessageId: string;
+  direction: WhatsAppDirection;
+  content: string;
+  sentAt: string;
+  senderName?: string;
+  messageType?: WhatsAppMessageType;
+  metadata?: Record<string, unknown>;
+};
+/**
+ * - `created`: a new row was stored.
+ * - `duplicate`: a row with this `waMessageId` already existed and was left as is.
+ * - `upgraded`: a stored media placeholder was replaced with the real media.
+ */
+type ImportMessageResult = "created" | "duplicate" | "upgraded";
 //#endregion
 //#region src/services/whatsapp.service.d.ts
 interface OutgoingLoggingMetadata {
@@ -621,6 +672,17 @@ declare class WhatsAppService {
    * @see https://developers.facebook.com/docs/whatsapp/cloud-api/messages/reaction-messages
    */
   sendReaction(to: string, messageId: string, emoji: string): Promise<SendResult>;
+  /**
+   * Download a media file received in a webhook (image, audio, video,
+   * document or sticker), using the configured access token.
+   *
+   * Meta deletes webhook media after 7 days. Never throws: failures and files
+   * over `maxBytes` are returned as results. Runs in development mode too,
+   * since it sends nothing.
+   *
+   * @see https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media
+   */
+  downloadMedia(mediaId: string, options?: MediaDownloadOptions): Promise<MediaDownloadResult>;
   /** Core send method with retry logic (2 retries, exponential backoff). */
   private send;
   private logSendResult;
@@ -847,4 +909,4 @@ interface ZapClient<TTemplates extends TemplateRegistry = {}> {
 }
 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 };
+export { SendInteractiveMediaCarouselData as $, WhatsAppMessageType as A, MessageUpdateEvent as B, ImportMessageResult as C, WhatsAppDirection as D, WHATSAPP_MESSAGE_TYPES as E, createLogger as F, Conversation as G, StatusUpdateEvent as H, noopLogger as I, IncomingMessage as J, ConversationRecord as K, serializeError as L, LogLevel as M, Logger as N, WhatsAppLogRecord as O, LoggerConfig as P, MessageStatus as Q, ConversationSummary as R, ImportMessageParams as S, MessageLoggerService as T, SyncEvent as U, NewMessageEvent as V, WhatsAppConfig as W, MediaMessage as X, InteractiveMediaCarouselCardInput as Y, MessageError as Z, getTemplateNames as _, WhatsAppLocationMessage as _t, createZapClient as a, UIMessage as at, OutgoingLoggingMetadata as b, WhatsAppWebhookField as bt, SupportedTemplateParameterType as c, WebhookContact as ct, TemplateName as d, WebhookPayload as dt, SendMessageError as et, TemplateParameterDefinition as f, WebhookValue as ft, defineTemplates as g, WhatsAppInteractiveMediaCarouselMessage as gt, TemplateRegistry as h, WhatsAppInteractiveListMessage as ht, apiKeyTransport as i, TemplateParameter as it, WhatsAppStatus as j, WhatsAppLogStore as k, TemplateComponentDefinition as l, WebhookEntry as lt, TemplateParams as m, WhatsAppInteractiveButtonsMessage as mt, ZapClient as n, SendResult as nt, sessionTransport as o, UIMessageStatus as ot, TemplateParameterInputMap as p, WhatsAppCarouselCard as pt, FreeformMessageWindow as q, ZapTransport as r, TemplateComponent as rt, EMPTY_TEMPLATE_REGISTRY as s, WebhookChange as st, BetterZapClientError as t, SendMessageResponse as tt, TemplateDefinition as u, WebhookError as ut, hasConfiguredTemplates as v, WhatsAppTemplateMessage as vt, MessageLoggerNotifier as w, WhatsAppService as x, serializeTemplateFromRegistry as y, WhatsAppTextMessage as yt, ConversationUpdateEvent as z };

package/dist/client.d.cts

@@ -1,2 +1,2 @@
-import { a as createZapClient, i as apiKeyTransport, n as ZapClient, o as sessionTransport, r as ZapTransport, t as BetterZapClientError } from "./client-DNlBPLBd.cjs";
+import { a as createZapClient, i as apiKeyTransport, n as ZapClient, o as sessionTransport, r as ZapTransport, t as BetterZapClientError } from "./client-B6XKmfej.cjs";
 export { BetterZapClientError, ZapClient, ZapTransport, apiKeyTransport, createZapClient, sessionTransport };

package/dist/client.d.mts

@@ -1,2 +1,2 @@
-import { a as createZapClient, i as apiKeyTransport, n as ZapClient, o as sessionTransport, r as ZapTransport, t as BetterZapClientError } from "./client-DiHHMG8t.mjs";
+import { a as createZapClient, i as apiKeyTransport, n as ZapClient, o as sessionTransport, r as ZapTransport, t as BetterZapClientError } from "./client-B49AT0HF.mjs";
 export { BetterZapClientError, ZapClient, ZapTransport, apiKeyTransport, createZapClient, sessionTransport };