whatsappd 0.1.0

package/dist/types-B8d1OyHV.d.mts

@@ -0,0 +1,71 @@
+import { C as SendOptions, E as InboundMessage, S as Outbound, a as Status, n as Update, v as PresenceKind, x as MessageRef } from "./update-Bi5ZPUjP.mjs";
+
+//#region src/channel/types.d.ts
+/**
+ * A resolved WhatsApp conversation — enough context for both Eve and Flue to
+ * address a session. `chatId` is always the JID (`xxx@s.whatsapp.net` or
+ * `xxx@g.us`). `from` is the sender within that chat (equal to `chatId` for
+ * DMs, the participant JID for groups).
+ */
+interface ConversationRef {
+  readonly chatId: string;
+  readonly isGroup: boolean;
+  /** Sender JID — equal to chatId for DMs, participant for groups. */
+  readonly from?: string;
+  /** Sender display name from WhatsApp. */
+  readonly pushName?: string;
+}
+/**
+ * Events the channel adapter emits to its handlers. Framework adapters
+ * translate these into their own session-start/dispatch calls.
+ */
+type ChannelEvent = {
+  type: "message";
+  ref: ConversationRef;
+  message: InboundMessage;
+} | {
+  type: "update";
+  ref: ConversationRef;
+  update: Update;
+} | {
+  type: "status";
+  accountId: string;
+  status: Status;
+};
+/**
+ * Callbacks the framework adapter provides. The channel adapter calls these
+ * when WhatsApp events arrive. Returning a Promise is fine — the adapter
+ * awaits before continuing to drain its event queue.
+ */
+interface ChannelHandlers {
+  onEvent(event: ChannelEvent): void | Promise<void>;
+}
+/**
+ * The framework-agnostic WhatsApp channel surface: one adapter wraps one
+ * account's session. Framework adapters (and the sidecar) hold one of these
+ * and call its methods; the deep module sits behind it.
+ */
+interface WhatsAppChannelAdapter {
+  /** Label for this account, carried on status events and wire payloads. */
+  readonly accountId: string;
+  /** Start the underlying session (connects to WhatsApp). */
+  start(): Promise<void>;
+  /**
+   * Send an outbound message to a chat. Returns a ref for follow-up
+   * react/edit/delete/quote operations.
+   */
+  send(chatId: string, content: Outbound, opts?: SendOptions): Promise<MessageRef>;
+  /** Mark a chat as read (blue ticks). */
+  markRead(chatId: string): Promise<void>;
+  /** Set or clear typing/recording presence in a chat. */
+  setTyping(chatId: string, kind: PresenceKind): Promise<void>;
+  /**
+   * Subscribe to channel events. Returns an unsubscribe function.
+   * Multiple subscribers are supported; each receives every event.
+   */
+  subscribe(handlers: ChannelHandlers): () => void;
+  /** Intentional teardown. */
+  stop(): Promise<void>;
+}
+//#endregion
+export { WhatsAppChannelAdapter as i, ChannelHandlers as n, ConversationRef as r, ChannelEvent as t };

package/dist/update-Bi5ZPUjP.d.mts

@@ -0,0 +1,341 @@
+//#region src/model/message.d.ts
+/**
+ * Inbound message shapes. Protocol-free types.
+ *
+ * @remarks
+ * A closed discriminated union with an `unsupported` catch-all, so it is
+ * type-impossible to crash on — or silently drop — a message. Media bodies are
+ * a lazy {@link MediaHandle}: the bytes never sit in the event stream and are
+ * fetched on demand, so the media kinds carry metadata only until you download.
+ *
+ * @packageDocumentation
+ */
+/** Quote / mentions, lifted from the proto contextInfo (WAProto ContextInfo). */
+interface MessageContext {
+  /** the message being replied to: contextInfo.stanzaId + participant */
+  readonly quoted?: {
+    readonly id: string;
+    readonly from: string;
+  };
+  /** contextInfo.mentionedJid */
+  readonly mentions?: readonly string[];
+}
+/**
+ * How the sender identity was resolved. `from` on the message is the resolved
+ * id; `alt` carries the alternate form so a host can map between the two
+ * identity schemes (LID and phone number).
+ */
+interface Addressing {
+  readonly mode: "lid" | "pn";
+  /** The alternate identity, when available. */
+  readonly alt?: string;
+}
+/** Unwrapped wrapper flags — kept even though we detect on the inner content. */
+interface MessageFlags {
+  readonly viewOnce?: boolean;
+  readonly ephemeral?: boolean;
+  readonly edited?: boolean;
+}
+interface Base {
+  readonly id: string;
+  readonly chatId: string;
+  /** resolved sender identity (see `addressing` for the alternate form) */
+  readonly from: string;
+  /** sender's WhatsApp display name (proto pushName), when present. */
+  readonly pushName?: string;
+  readonly fromMe: boolean;
+  readonly timestamp: number;
+  /** true = live (`messages.upsert` type "notify"); false = history ("append"). */
+  readonly live: boolean;
+  readonly isGroup: boolean;
+  readonly context?: MessageContext;
+  readonly addressing?: Addressing;
+  readonly flags?: MessageFlags;
+}
+/** Media metadata, lifted from the proto. The bytes are fetched via `MediaHandle`. */
+interface MediaMeta {
+  readonly mimetype?: string;
+  readonly fileLength?: number;
+  readonly fileName?: string;
+  readonly seconds?: number;
+  readonly ptt?: boolean;
+  readonly width?: number;
+  readonly height?: number;
+  readonly caption?: string;
+}
+/**
+ * Opaque, on-demand media: metadata now, bytes when you ask.
+ * `download()` fetches + decrypts, transparently re-uploading expired media.
+ * Bytes never travel in the event stream — the consumer pulls them when ready.
+ */
+interface MediaHandle extends MediaMeta {
+  download(): Promise<Buffer>;
+}
+type InboundMessage = Base & ({
+  kind: "text";
+  text: string;
+} | {
+  kind: "image" | "video" | "audio" | "document" | "sticker";
+  media: MediaHandle;
+  text?: string;
+} | {
+  kind: "location";
+  lat: number;
+  lng: number;
+  name?: string;
+  address?: string;
+} | {
+  kind: "contacts";
+  contacts: readonly {
+    name?: string;
+    vcard: string;
+  }[];
+} | {
+  kind: "poll";
+  name: string;
+  options: readonly string[];
+  selectableCount: number;
+} | {
+  kind: "unsupported";
+  rawType: string;
+});
+//#endregion
+//#region src/model/outbound.d.ts
+/** Bytes to send: an in-memory buffer, a URL Baileys fetches, or a byte stream. */
+type BinaryInput = Buffer | {
+  url: string;
+} | {
+  stream: AsyncIterable<Uint8Array>;
+};
+/**
+ * A plain reference to an existing message — enough to rebuild the Baileys key
+ * for react/edit/delete/quote WITHOUT leaking the proto. Build one from an
+ * `InboundMessage` via `refOf`, or construct it yourself.
+ */
+interface MessageRef {
+  readonly id: string;
+  readonly chatId: string;
+  readonly fromMe: boolean;
+  /** group sender, if the target is a group message */
+  readonly participant?: string;
+}
+type Outbound = {
+  text: string;
+} | {
+  image: BinaryInput;
+  caption?: string;
+} | {
+  video: BinaryInput;
+  caption?: string;
+  gifPlayback?: boolean;
+} /** `ptt: true` sends a voice note (mimetype defaults to ogg/opus). */ | {
+  audio: BinaryInput;
+  ptt?: boolean;
+  seconds?: number;
+  mimetype?: string;
+} | {
+  document: BinaryInput;
+  fileName: string;
+  mimetype: string;
+  caption?: string;
+} | {
+  sticker: BinaryInput;
+} | {
+  location: {
+    lat: number;
+    lng: number;
+    name?: string;
+    address?: string;
+  };
+} | {
+  contacts: {
+    displayName?: string;
+    vcards: readonly string[];
+  };
+} /** React to a message; `emoji: ""` clears the reaction. */ | {
+  react: {
+    to: MessageRef;
+    emoji: string;
+  };
+} | {
+  edit: {
+    target: MessageRef;
+    text: string;
+  };
+} | {
+  delete: MessageRef;
+};
+interface SendOptions {
+  /** reply to / quote this message */
+  readonly quote?: MessageRef;
+  /** jids to @mention (must also appear in the text) */
+  readonly mentions?: readonly string[];
+}
+/** Build a `MessageRef` from a received message, for react/edit/delete/quote. */
+declare function refOf(m: InboundMessage): MessageRef;
+//#endregion
+//#region src/model/presence.d.ts
+/**
+ * Ephemeral WhatsApp presence. These signals are stream-only: they should drive
+ * live UI affordances and expire quickly, not become durable message history.
+ */
+type PresenceKind = "typing" | "recording" | "available" | "idle" | "unavailable";
+interface PresenceUpdate {
+  readonly chatId: string;
+  readonly participant?: string;
+  readonly kind: PresenceKind;
+  readonly at?: number;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Closed union of domain reasons a WhatsApp connection can fault on, mapped
+ * from the transport's status codes rather than any raw error payload.
+ */
+type FaultReason = "restart_required" | "connection_lost" | "timed_out" | "service_unavailable" | "logged_out_remote" | "connection_replaced" | "credentials_invalid" | "multidevice_mismatch" | "bad_session" | "pairing_rejected" | "intentional" | "unknown";
+/**
+ * Which terminal sink a fault lands in — the single source of truth.
+ *   "retryable"  → the spine reconnects automatically.
+ *   "logged_out" → creds are dead; wipe the SessionStore and re-pair.
+ *   "suspended"  → account/device problem; re-pairing won't help.
+ */
+type Disposition = "retryable" | "logged_out" | "suspended";
+/** Which sink this reason lands in. */
+declare function dispositionFor(reason: FaultReason): Disposition;
+interface WhatsAppFault {
+  readonly reason: FaultReason;
+  readonly statusCode?: number;
+  /** Whether reconnecting with the same creds could plausibly help. */
+  readonly retryable: boolean;
+  /** Which terminal sink (or retry) this fault lands in. */
+  readonly disposition: Disposition;
+}
+/** Reconnect only what is genuinely retryable. No fix-by-retry. */
+declare function isRetryable(reason: FaultReason): boolean;
+/**
+ * Classify a disconnect into a sanitized domain {@link WhatsAppFault}.
+ *
+ * @param error - The transport error that closed the connection, or a falsy
+ * value for an intentional teardown. The raw payload is never surfaced on the
+ * result — only its mapped status code.
+ * @param intentional - `true` when the caller closed the connection on purpose;
+ * such a close is never treated as a fault.
+ * @returns The classified fault, including its {@link Disposition}.
+ */
+declare function classifyDisconnect(error: unknown, intentional: boolean): WhatsAppFault;
+/** Why a pairing attempt failed. */
+type PairingErrorReason = "connection_closed_before_ready" | "pairing_readiness_timeout" | "pairing_rejected" | "invalid_phone";
+/**
+ * A tagged error for the pairing flow. Carries only safe metadata (the reason
+ * and an optional status code); the underlying error is logged, never attached.
+ */
+declare class PairingError extends Error {
+  readonly _tag = "PairingError";
+  readonly reason: PairingErrorReason;
+  readonly statusCode?: number;
+  constructor(reason: PairingErrorReason, statusCode?: number);
+}
+/** Validate E.164 at the edge so bad input fails loudly before reaching Baileys. */
+declare function assertE164(input: string): string;
+//#endregion
+//#region src/model/status.d.ts
+/** The pairing sub-state, present while `Status.phase` is `"pairing"`. */
+type PairingState = /** waiting for the first qr (ws open + handshake done); for pairing-code, also awaiting the code */{
+  step: "awaiting_ready";
+} /** the qr/code is live and shown to the human */ | {
+  step: "challenge_live";
+  method: "qr" | "pairing_code";
+  qr?: string;
+  code?: string;
+  expiresAt: number;
+} /** paired; awaiting the expected 515 restart before reconnecting with creds */ | {
+  step: "restart_pending";
+};
+/** The sync sub-state — an open socket is not yet sendable until sync settles. */
+type SyncState = /** socket open; awaiting receivedPendingNotifications */{
+  step: "draining";
+} /** history sync in flight */ | {
+  step: "syncing";
+  progress?: number;
+};
+/** The connection lifecycle, with the pairing and sync sub-states nested in. */
+type Status = {
+  phase: "disconnected";
+} | {
+  phase: "connecting";
+  retryAttempt?: number;
+} | {
+  phase: "pairing";
+  pairing: PairingState;
+} | {
+  phase: "authenticated";
+  sync: SyncState;
+} | {
+  phase: "online";
+} | {
+  phase: "backing_off";
+  reason: FaultReason;
+  retryAttempt: number;
+  nextRetryAt: number;
+} | {
+  phase: "logged_out";
+  reason: FaultReason;
+} | {
+  phase: "suspended";
+  reason: FaultReason;
+};
+/** Stream element on `session.connection` — a Status emitted on transition. */
+type ConnectionEvent = Status;
+/** True once a status is terminal (the `connection` stream ends here). */
+declare function isTerminal(status: Status): boolean;
+/** True once the device is genuinely sendable. */
+declare function isOnline(status: Status): boolean;
+/** The connected account's own identity, read from the live socket once open. */
+interface WaIdentity {
+  /** the account's own jid (e.g. `15551234567:12@s.whatsapp.net`). */
+  readonly jid: string;
+  readonly pushName?: string;
+  /** E.164, derived from the jid's number part when it is purely numeric. */
+  readonly phoneE164?: string;
+}
+//#endregion
+//#region src/model/update.d.ts
+/**
+ * Delivery progression of a message. Mirrors WhatsApp's own ladder; in practice
+ * monotonic (`server_ack → delivered → read → played`). `error` means the send
+ * was rejected after the fact.
+ */
+type ReceiptStatus = "pending" | "server_ack" | "delivered" | "read" | "played" | "error";
+interface UpdateBase {
+  /** The message this update is about. */
+  ref: MessageRef;
+  /** When it happened (ms epoch), when the wire tells us. */
+  at?: number;
+}
+type Update =
+/** A receipt for a message — usually one we sent. `by` is set for the
+ *  per-participant receipts that groups produce. */
+(UpdateBase & {
+  kind: "receipt";
+  status: ReceiptStatus;
+  by?: string;
+})
+/** Someone reacted, or cleared their reaction (`removed: true`, `emoji`
+ *  undefined). `by` is the reactor. */
+| (UpdateBase & {
+  kind: "reaction";
+  emoji?: string;
+  by?: string;
+  removed: boolean;
+})
+/** A message was edited; `message` is the new content, re-mapped to the same
+ *  shape as anything on the `inbound` stream. */
+| (UpdateBase & {
+  kind: "edit";
+  message: InboundMessage;
+}) /** A message was deleted for everyone (revoked). `by` is who revoked it. */ | (UpdateBase & {
+  kind: "revoke";
+  by?: string;
+});
+//#endregion
+export { MessageFlags as A, SendOptions as C, MediaHandle as D, InboundMessage as E, MediaMeta as O, Outbound as S, Addressing as T, isRetryable as _, Status as a, BinaryInput as b, isOnline as c, FaultReason as d, PairingError as f, dispositionFor as g, classifyDisconnect as h, PairingState as i, MessageContext as k, isTerminal as l, assertE164 as m, Update as n, SyncState as o, WhatsAppFault as p, ConnectionEvent as r, WaIdentity as s, ReceiptStatus as t, Disposition as u, PresenceKind as v, refOf as w, MessageRef as x, PresenceUpdate as y };

package/dist/wire-Bx6OmkxC.d.mts

@@ -0,0 +1,135 @@
+import { C as SendOptions, E as InboundMessage, O as MediaMeta, S as Outbound, a as Status, n as Update, t as ReceiptStatus, v as PresenceKind, x as MessageRef } from "./update-Bi5ZPUjP.mjs";
+
+//#region src/sidecar/wire.d.ts
+/** Media metadata plus an optional sidecar URL where the bytes are served. */
+interface WireMedia extends MediaMeta {
+  /**
+   * Where to fetch the decrypted bytes. Relative (`/media/...`) unless the
+   * sidecar was configured with a base URL — resolve against the sidecar URL.
+   */
+  readonly url?: string;
+}
+/** `InboundMessage` with `MediaHandle` flattened to `WireMedia`. */
+type WireMessage = {
+  readonly id: string;
+  readonly chatId: string;
+  readonly from: string;
+  readonly pushName?: string;
+  readonly fromMe: boolean;
+  readonly timestamp: number;
+  readonly isGroup: boolean;
+} & ({
+  kind: "text";
+  text: string;
+} | {
+  kind: "image" | "video" | "audio" | "document" | "sticker";
+  media: WireMedia;
+  text?: string;
+} | {
+  kind: "location";
+  lat: number;
+  lng: number;
+  name?: string;
+  address?: string;
+} | {
+  kind: "contacts";
+  contacts: readonly {
+    name?: string;
+    vcard: string;
+  }[];
+} | {
+  kind: "poll";
+  name: string;
+  options: readonly string[];
+  selectableCount: number;
+} | {
+  kind: "unsupported";
+  rawType: string;
+});
+/** `Update` with the edit arm's `InboundMessage` flattened to `WireMessage`. */
+type WireUpdate = {
+  kind: "receipt";
+  ref: MessageRef;
+  at?: number;
+  status: ReceiptStatus;
+  by?: string;
+} | {
+  kind: "reaction";
+  ref: MessageRef;
+  at?: number;
+  emoji?: string;
+  by?: string;
+  removed: boolean;
+} | {
+  kind: "edit";
+  ref: MessageRef;
+  at?: number;
+  message: WireMessage;
+} | {
+  kind: "revoke";
+  ref: MessageRef;
+  at?: number;
+  by?: string;
+};
+/** One event POSTed by the sidecar to each forward target. */
+type SidecarEvent = {
+  type: "message";
+  accountId: string;
+  chatId: string;
+  isGroup: boolean;
+  from?: string;
+  pushName?: string;
+  message: WireMessage;
+} | {
+  type: "update";
+  accountId: string;
+  chatId: string;
+  update: WireUpdate;
+} | {
+  type: "status";
+  accountId: string;
+  status: Status;
+};
+/**
+ * Media bytes in a request body: base64, or a URL Baileys fetches itself.
+ * (A raw Buffer cannot travel as JSON.)
+ */
+type WireBinary = {
+  b64: string;
+} | {
+  url: string;
+};
+/** Body of `POST /send`. `content` is `Outbound` with `WireBinary` media. */
+interface SendRequest {
+  readonly accountId: string;
+  readonly chatId: string;
+  readonly content: Record<string, unknown>;
+  readonly opts?: SendOptions;
+}
+/** Body of `POST /markRead`. */
+interface MarkReadRequest {
+  readonly accountId: string;
+  readonly chatId: string;
+}
+/** Body of `POST /setTyping`. */
+interface SetTypingRequest {
+  readonly accountId: string;
+  readonly chatId: string;
+  readonly kind?: PresenceKind;
+}
+/**
+ * Flatten an `InboundMessage` for the wire. `mediaUrl` is the sidecar path
+ * serving this message's bytes (set only for media kinds).
+ */
+declare function toWireMessage(msg: InboundMessage, mediaUrl?: string): WireMessage;
+/** Flatten an `Update` for the wire (the edit arm carries an `InboundMessage`). */
+declare function toWireUpdate(update: Update): WireUpdate;
+/**
+ * Revive a `POST /send` body's content into a real `Outbound`: `{ b64 }`
+ * media becomes a Buffer, `{ url }` passes through for Baileys to fetch.
+ */
+declare function reviveOutbound(content: Record<string, unknown>): Outbound;
+/** A short human-readable placeholder for non-text message kinds. */
+declare function messagePreview(msg: WireMessage): string;
+//#endregion
+export { WireBinary as a, WireUpdate as c, toWireMessage as d, toWireUpdate as f, SidecarEvent as i, messagePreview as l, SendRequest as n, WireMedia as o, SetTypingRequest as r, WireMessage as s, MarkReadRequest as t, reviveOutbound as u };

package/dist/wire-CsVVkLhn.mjs

@@ -0,0 +1,122 @@
+//#region src/sidecar/wire.ts
+/** Drop undefined values so wire objects survive a JSON round-trip unchanged. */
+function compact(obj) {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+}
+/**
+* Flatten an `InboundMessage` for the wire. `mediaUrl` is the sidecar path
+* serving this message's bytes (set only for media kinds).
+*/
+function toWireMessage(msg, mediaUrl) {
+	const base = {
+		id: msg.id,
+		chatId: msg.chatId,
+		from: msg.from,
+		...msg.pushName !== void 0 && { pushName: msg.pushName },
+		fromMe: msg.fromMe,
+		timestamp: msg.timestamp,
+		isGroup: msg.isGroup
+	};
+	switch (msg.kind) {
+		case "text": return {
+			...base,
+			kind: msg.kind,
+			text: msg.text
+		};
+		case "image":
+		case "video":
+		case "audio":
+		case "document":
+		case "sticker": {
+			const { mimetype, fileLength, fileName, seconds, ptt, width, height, caption } = msg.media;
+			const media = compact({
+				mimetype,
+				fileLength,
+				fileName,
+				seconds,
+				ptt,
+				width,
+				height,
+				caption,
+				url: mediaUrl
+			});
+			return {
+				...base,
+				kind: msg.kind,
+				media,
+				...msg.text !== void 0 && { text: msg.text }
+			};
+		}
+		case "location": return compact({
+			...base,
+			kind: msg.kind,
+			lat: msg.lat,
+			lng: msg.lng,
+			name: msg.name,
+			address: msg.address
+		});
+		case "contacts": return {
+			...base,
+			kind: msg.kind,
+			contacts: msg.contacts
+		};
+		case "poll": return {
+			...base,
+			kind: msg.kind,
+			name: msg.name,
+			options: msg.options,
+			selectableCount: msg.selectableCount
+		};
+		case "unsupported": return {
+			...base,
+			kind: msg.kind,
+			rawType: msg.rawType
+		};
+	}
+}
+/** Flatten an `Update` for the wire (the edit arm carries an `InboundMessage`). */
+function toWireUpdate(update) {
+	if (update.kind === "edit") return compact({
+		kind: "edit",
+		ref: update.ref,
+		at: update.at,
+		message: toWireMessage(update.message)
+	});
+	return update;
+}
+const MEDIA_KEYS = [
+	"image",
+	"video",
+	"audio",
+	"document",
+	"sticker"
+];
+/**
+* Revive a `POST /send` body's content into a real `Outbound`: `{ b64 }`
+* media becomes a Buffer, `{ url }` passes through for Baileys to fetch.
+*/
+function reviveOutbound(content) {
+	const out = { ...content };
+	for (const key of MEDIA_KEYS) {
+		const media = out[key];
+		if (media && typeof media === "object" && "b64" in media) out[key] = Buffer.from(media.b64, "base64");
+	}
+	return out;
+}
+/** A short human-readable placeholder for non-text message kinds. */
+function messagePreview(msg) {
+	switch (msg.kind) {
+		case "text": return msg.text;
+		case "image":
+		case "video":
+		case "audio":
+		case "document":
+		case "sticker": return msg.text ?? msg.media.caption ?? `[${msg.kind}]`;
+		case "location": return `[location${msg.name ? `: ${msg.name}` : ""} ${msg.lat},${msg.lng}]`;
+		case "contacts": return `[contact card${msg.contacts.length > 1 ? `s (${msg.contacts.length})` : ""}]`;
+		case "poll": return `[poll: ${msg.name}]`;
+		case "unsupported": return `[unsupported: ${msg.rawType}]`;
+	}
+}
+//#endregion
+export { toWireUpdate as i, reviveOutbound as n, toWireMessage as r, messagePreview as t };