whatsappd 0.1.0

package/dist/adapters/eve.d.mts

@@ -0,0 +1,83 @@
+import { s as WireMessage } from "../wire-Bx6OmkxC.mjs";
+import { Channel, ChannelEvents, RouteHandlerArgs } from "eve/channels";
+
+//#region src/adapters/eve.d.ts
+/** Durable per-session adapter state — enough to address the sidecar. */
+interface WhatsAppEveState {
+  accountId: string;
+  chatId: string;
+  [key: string]: unknown;
+}
+/** The `channel` context handed to event handlers. */
+interface WhatsAppEveContext {
+  readonly accountId: string;
+  readonly chatId: string;
+}
+/** Observability projection (a type alias so it satisfies eve's Record constraint). */
+type WhatsAppEveMetadata = {
+  readonly accountId: string;
+  readonly chatId: string;
+};
+interface WhatsAppEveOptions {
+  /** Sidecar base URL. Default: `WHATSAPP_SIDECAR_URL` env var. */
+  readonly sidecarUrl?: string;
+  /**
+   * Shared bearer token: required on inbound `/event` posts and sent on
+   * outbound sidecar calls. Default: `WHATSAPP_SIDECAR_TOKEN` env var.
+   */
+  readonly token?: string;
+  /** Mark the conversation read when the agent starts a turn. Default true. */
+  readonly markRead?: boolean;
+  /** Show typing presence while the agent works on a turn. Default true. */
+  readonly typing?: boolean;
+  /** `auth.authenticator` value on started sessions. Default "whatsapp-baileys". */
+  readonly authenticator?: string;
+  /** Testing seam — defaults to global fetch. */
+  readonly fetchFn?: typeof fetch;
+}
+type ContentPart = {
+  type: "text";
+  text: string;
+} | {
+  type: "file";
+  data: URL;
+  mediaType: string;
+};
+/**
+ * Project a wire message onto Eve `UserContent` parts: the text (or a
+ * `[kind]` preview), plus the media as a URL file part the framework stages
+ * through `fetchFile`.
+ */
+declare function toUserContent(message: WireMessage, sidecarUrl: string): ContentPart[];
+/**
+ * Handler for `POST /event` — the sidecar posts every inbound WhatsApp event
+ * here; message events start or resume the Eve session for that chat.
+ * Exported for tests; wired into the channel by `whatsappChannel`.
+ */
+declare function createEventRoute(opts: WhatsAppEveOptions): (req: Request, args: RouteHandlerArgs<WhatsAppEveState>) => Promise<Response>;
+/**
+ * Session lifecycle handlers: agent replies go back to the sidecar for
+ * delivery; turn start drives read receipts and typing presence.
+ * Exported for tests; wired into the channel by `whatsappChannel`.
+ */
+declare function createEventHandlers(opts: WhatsAppEveOptions): ChannelEvents<WhatsAppEveContext>;
+/**
+ * `fetchFile` hook — stages media file parts whose URL points at the
+ * sidecar, attaching the bearer token. Other URLs pass through untouched.
+ * Exported for tests; wired into the channel by `whatsappChannel`.
+ */
+declare function createFetchFile(opts: WhatsAppEveOptions): (url: string) => Promise<{
+  bytes: Buffer;
+  mediaType?: string;
+  filename?: string;
+} | null>;
+/**
+ * Build the WhatsApp channel for an Eve app. Place the result (or the
+ * default export) at `agent/channels/whatsapp.ts` — the file stem becomes
+ * the channel id.
+ */
+declare function whatsappChannel(opts?: WhatsAppEveOptions): Channel<WhatsAppEveState, Record<string, unknown>, WhatsAppEveMetadata>;
+/** Zero-config channel: reads `WHATSAPP_SIDECAR_URL` / `WHATSAPP_SIDECAR_TOKEN`. */
+declare const _default: Channel<WhatsAppEveState, Record<string, unknown>, WhatsAppEveMetadata>;
+//#endregion
+export { WhatsAppEveContext, WhatsAppEveMetadata, WhatsAppEveOptions, WhatsAppEveState, createEventHandlers, createEventRoute, createFetchFile, _default as default, toUserContent, whatsappChannel };

package/dist/adapters/eve.mjs

@@ -0,0 +1,181 @@
+import { t as messagePreview } from "../wire-CsVVkLhn.mjs";
+import { POST, defineChannel } from "eve/channels";
+//#region src/adapters/eve.ts
+/**
+* Eve channel adapter — a plug-and-play WhatsApp channel for the Eve
+* framework, bridged to the WhatsApp sidecar over HTTP.
+*
+* The sidecar owns the socket to WhatsApp; this adapter is a thin HTTP
+* client on both directions:
+*
+*   inbound   sidecar → POST /event → `send()` starts/resumes the session
+*             (`continuationToken` = chatId, so one WhatsApp conversation
+*             maps to one Eve session)
+*   outbound  "message.completed" → POST sidecar /send
+*             "turn.started"      → POST sidecar /markRead + /setTyping
+*   media     inbound media arrives as a sidecar URL; `fetchFile` stages
+*             the bytes with the shared bearer token
+*
+* Drop it into an Eve app as `agent/channels/whatsapp.ts`:
+*
+*   export { default } from "whatsappd/adapters/eve";
+*
+* or configure explicitly:
+*
+*   import { whatsappChannel } from "whatsappd/adapters/eve";
+*   export default whatsappChannel({ sidecarUrl: "http://localhost:8788" });
+*
+* @packageDocumentation
+*/
+/** Resolve lazily so env vars are read per call, not at import time. */
+function resolve(opts) {
+	const sidecarUrl = opts.sidecarUrl ?? process.env.WHATSAPP_SIDECAR_URL;
+	if (!sidecarUrl) throw new Error("whatsappd: set WHATSAPP_SIDECAR_URL or pass { sidecarUrl }");
+	return {
+		sidecarUrl,
+		token: opts.token ?? process.env.WHATSAPP_SIDECAR_TOKEN,
+		markRead: opts.markRead ?? true,
+		typing: opts.typing ?? true,
+		authenticator: opts.authenticator ?? "whatsapp-baileys",
+		fetchFn: opts.fetchFn ?? fetch
+	};
+}
+/**
+* Project a wire message onto Eve `UserContent` parts: the text (or a
+* `[kind]` preview), plus the media as a URL file part the framework stages
+* through `fetchFile`.
+*/
+function toUserContent(message, sidecarUrl) {
+	const parts = [];
+	const text = messagePreview(message);
+	if (text.length > 0) parts.push({
+		type: "text",
+		text
+	});
+	if ("media" in message && message.media.url) parts.push({
+		type: "file",
+		data: new URL(message.media.url, sidecarUrl),
+		mediaType: message.media.mimetype ?? "application/octet-stream"
+	});
+	return parts;
+}
+/**
+* Handler for `POST /event` — the sidecar posts every inbound WhatsApp event
+* here; message events start or resume the Eve session for that chat.
+* Exported for tests; wired into the channel by `whatsappChannel`.
+*/
+function createEventRoute(opts) {
+	return async (req, args) => {
+		const c = resolve(opts);
+		if (c.token && req.headers.get("authorization") !== `Bearer ${c.token}`) return Response.json({ error: "unauthorized" }, { status: 401 });
+		const event = await req.json();
+		if (event.type !== "message" || event.message.fromMe) return Response.json({ ignored: true });
+		const { accountId, chatId, isGroup, from, pushName, message } = event;
+		const session = await args.send(toUserContent(message, c.sidecarUrl), {
+			auth: {
+				authenticator: c.authenticator,
+				principalType: "contact",
+				principalId: from ?? chatId,
+				attributes: {
+					accountId,
+					chatId,
+					isGroup: String(isGroup),
+					...from !== void 0 && { from },
+					...pushName !== void 0 && { pushName }
+				}
+			},
+			continuationToken: chatId,
+			state: {
+				accountId,
+				chatId
+			},
+			title: `WhatsApp: ${pushName ?? chatId}`
+		});
+		return Response.json({ sessionId: session.id });
+	};
+}
+/**
+* Session lifecycle handlers: agent replies go back to the sidecar for
+* delivery; turn start drives read receipts and typing presence.
+* Exported for tests; wired into the channel by `whatsappChannel`.
+*/
+function createEventHandlers(opts) {
+	async function post(path, body) {
+		const c = resolve(opts);
+		return c.fetchFn(new URL(path, c.sidecarUrl), {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				...c.token && { authorization: `Bearer ${c.token}` }
+			},
+			body: JSON.stringify(body)
+		});
+	}
+	return {
+		async "turn.started"(_data, channel) {
+			const c = resolve(opts);
+			const target = {
+				accountId: channel.accountId,
+				chatId: channel.chatId
+			};
+			const signals = [];
+			if (c.markRead) signals.push(post("/markRead", target));
+			if (c.typing) signals.push(post("/setTyping", {
+				...target,
+				kind: "typing"
+			}));
+			await Promise.allSettled(signals);
+		},
+		async "message.completed"(data, channel) {
+			if (typeof data.message !== "string" || data.message.length === 0) return;
+			const res = await post("/send", {
+				accountId: channel.accountId,
+				chatId: channel.chatId,
+				content: { text: data.message }
+			});
+			if (!res.ok) throw new Error(`whatsappd: sidecar /send failed with ${res.status}`);
+		}
+	};
+}
+/**
+* `fetchFile` hook — stages media file parts whose URL points at the
+* sidecar, attaching the bearer token. Other URLs pass through untouched.
+* Exported for tests; wired into the channel by `whatsappChannel`.
+*/
+function createFetchFile(opts) {
+	return async (url) => {
+		const c = resolve(opts);
+		if (!url.startsWith(new URL("/", c.sidecarUrl).origin)) return null;
+		const res = await c.fetchFn(url, { headers: { ...c.token && { authorization: `Bearer ${c.token}` } } });
+		if (!res.ok) throw new Error(`whatsappd: media fetch failed with ${res.status}`);
+		return {
+			bytes: Buffer.from(await res.arrayBuffer()),
+			mediaType: res.headers.get("content-type") ?? void 0
+		};
+	};
+}
+/**
+* Build the WhatsApp channel for an Eve app. Place the result (or the
+* default export) at `agent/channels/whatsapp.ts` — the file stem becomes
+* the channel id.
+*/
+function whatsappChannel(opts = {}) {
+	return defineChannel({
+		kindHint: "whatsapp",
+		context: (state) => ({
+			accountId: state.accountId,
+			chatId: state.chatId
+		}),
+		metadata: (state) => ({
+			accountId: state.accountId,
+			chatId: state.chatId
+		}),
+		routes: [POST("/event", createEventRoute(opts))],
+		events: createEventHandlers(opts),
+		fetchFile: createFetchFile(opts)
+	});
+}
+/** Zero-config channel: reads `WHATSAPP_SIDECAR_URL` / `WHATSAPP_SIDECAR_TOKEN`. */
+var eve_default = whatsappChannel();
+//#endregion
+export { createEventHandlers, createEventRoute, createFetchFile, eve_default as default, toUserContent, whatsappChannel };

package/dist/index.d.mts

@@ -0,0 +1,283 @@
+import { A as MessageFlags, C as SendOptions, D as MediaHandle, E as InboundMessage, O as MediaMeta, S as Outbound, T as Addressing, _ as isRetryable, a as Status, b as BinaryInput, c as isOnline, d as FaultReason, f as PairingError, g as dispositionFor, h as classifyDisconnect, i as PairingState, k as MessageContext, l as isTerminal, m as assertE164, n as Update, o as SyncState, p as WhatsAppFault, r as ConnectionEvent, s as WaIdentity, t as ReceiptStatus, u as Disposition, v as PresenceKind, w as refOf, x as MessageRef, y as PresenceUpdate } from "./update-Bi5ZPUjP.mjs";
+import { i as qrAuth, n as SessionStore, r as pairingAuth, t as AuthStrategy } from "./ports-DeTIMztA.mjs";
+import { memoryStore } from "./stores/memory.mjs";
+import { i as WhatsAppChannelAdapter, n as ChannelHandlers, r as ConversationRef, t as ChannelEvent } from "./types-B8d1OyHV.mjs";
+import { AgentTool, DeleteInput, EditInput, MediaKind, ReactInput, ReplyInput, SendMediaInput, SendTextInput, SetTypingInput, ToolContext, allTools, bindTools, deleteMsg, edit, markRead, react, reply, sendMedia, sendText, setTyping } from "./tools/index.mjs";
+import { Logger } from "pino";
+
+//#region src/model/group.d.ts
+interface GroupParticipant {
+  readonly id: string;
+  readonly role?: string;
+}
+interface GroupMetadata {
+  readonly id: string;
+  readonly subject?: string;
+  readonly participants: readonly GroupParticipant[];
+}
+type GroupParticipantAction = "add" | "remove" | "promote" | "demote" | "modify";
+type GroupUpdate = {
+  readonly kind: "metadata";
+  readonly id: string;
+  readonly subject?: string;
+  readonly participants?: readonly GroupParticipant[];
+  readonly at: number;
+} | {
+  readonly kind: "participants";
+  readonly id: string;
+  readonly action: GroupParticipantAction;
+  readonly participants: readonly GroupParticipant[];
+  readonly at: number;
+};
+//#endregion
+//#region src/model/metrics.d.ts
+type MetricEvent = /** A connection state transition (`from` → `to` phase). */{
+  type: "transition";
+  from: Status["phase"];
+  to: Status["phase"];
+} /** A message crossed the inbound stream. */ | {
+  type: "message_in";
+  kind: InboundMessage["kind"];
+  live: boolean;
+} /** An update crossed the updates stream. */ | {
+  type: "update_in";
+  kind: Update["kind"];
+} /** A WhatsApp address-book contact update crossed the contacts stream. */ | {
+  type: "contact_in";
+  hasDisplayName: boolean;
+  identityCount: number;
+} /** An ephemeral remote presence signal crossed the presence stream. */ | {
+  type: "presence_in";
+  kind: PresenceUpdate["kind"];
+} /** A WhatsApp group metadata or participant update crossed the groups stream. */ | {
+  type: "group_in";
+  kind: GroupUpdate["kind"];
+} /** A `send()` completed successfully. */ | {
+  type: "message_out";
+} /** A reconnect attempt is starting (`attempt` is the retry count). */ | {
+  type: "reconnect";
+  attempt: number;
+};
+/** The hook signature a consumer supplies as {@link SessionConfig.metrics}. */
+type MetricsHook = (event: MetricEvent) => void;
+//#endregion
+//#region src/model/contact.d.ts
+/**
+ * A contact / address-book update, normalized from a WhatsApp contact event.
+ * Consume these to keep a local read model of contacts in sync.
+ */
+interface ContactUpdate {
+  /** The primary WhatsApp contact id from the event. */
+  readonly id: string;
+  /** Candidate identities for matching existing records, ordered by confidence. */
+  readonly nativeIds: readonly string[];
+  /** The saved address-book name, when present. */
+  readonly displayName?: string;
+  /** The profile/push name set by the remote user, when present. */
+  readonly profileName?: string;
+  /** A business-verified name, when present. */
+  readonly verifiedName?: string;
+  /** The contact's WhatsApp username, when present. */
+  readonly username?: string;
+  /**
+   * The profile-photo URL: a URL string, `null` when the contact has none, or
+   * omitted when the event carried no photo information.
+   */
+  readonly imgUrl?: string | null;
+  /** The contact's status/about text, when present. */
+  readonly status?: string;
+  /** When the update occurred, as a millisecond epoch timestamp. */
+  readonly at?: number;
+}
+//#endregion
+//#region src/model/history.d.ts
+interface HistoryChat {
+  readonly id: string;
+  readonly subject?: string;
+  readonly isGroup: boolean;
+  readonly lastMessageAt?: number;
+  readonly participants?: readonly GroupParticipant[];
+}
+interface HistoryContact {
+  readonly id: string;
+  readonly displayName?: string;
+}
+interface ConversationSyncBatch {
+  readonly chats: readonly HistoryChat[];
+  readonly contacts: readonly HistoryContact[];
+  readonly self?: HistoryContact;
+  readonly messages: readonly InboundMessage[];
+}
+type ConversationSyncChat = HistoryChat;
+type ConversationSyncContact = HistoryContact;
+type HistoryBatch = ConversationSyncBatch;
+//#endregion
+//#region src/session.d.ts
+/** Configuration for {@link createSession}. */
+interface SessionConfig {
+  /** Where this session's credentials are persisted. */
+  store: SessionStore;
+  /** How this session logs in — {@link qrAuth} or {@link pairingAuth}. */
+  auth: AuthStrategy;
+  /**
+   * Logger to use.
+   *
+   * @defaultValue a `pino` logger at the level in `WA_LOG_LEVEL`, or `warn`.
+   */
+  logger?: Logger;
+  /**
+   * How long to wait after a pairing attempt for confirmation before treating
+   * the silent rejection as final, in milliseconds.
+   */
+  verdictWindowMs?: number;
+  /**
+   * Grace period after the socket opens before forcing the `online` status if
+   * no history-sync signal has arrived, in milliseconds.
+   */
+  syncGraceMs?: number;
+  /** Base delay for reconnect backoff, in milliseconds. */
+  reconnectBaseMs?: number;
+  /** Maximum delay for reconnect backoff, in milliseconds. */
+  reconnectMaxMs?: number;
+  /**
+   * Whether to surface WhatsApp Status/story posts (`status@broadcast`) on the
+   * inbound stream.
+   *
+   * @defaultValue `false`
+   */
+  receiveStatusBroadcast?: boolean;
+  /**
+   * Minimum gap between outbound sends, in milliseconds, to reduce the risk of
+   * rate-limiting. Set to `0` to disable pacing.
+   *
+   * @defaultValue `1000`
+   */
+  sendMinGapMs?: number;
+  /**
+   * Fire-and-forget observability hook. Errors it throws are swallowed so
+   * instrumentation can never disrupt the session.
+   */
+  metrics?: MetricsHook;
+}
+/**
+ * One WhatsApp account's live session: a set of read-only event streams plus
+ * the commands that act on the connection. Create one with {@link createSession}
+ * and call {@link WhatsAppSession.start | start} to connect.
+ */
+interface WhatsAppSession {
+  /** The current connection status (also emitted on {@link connection}). */
+  readonly status: Status;
+  /** Connection-lifecycle events: pairing, online, backing off, terminal. */
+  readonly connection: AsyncIterable<ConnectionEvent>;
+  /** Incoming messages, normalized into a closed union. */
+  readonly inbound: AsyncIterable<InboundMessage>;
+  /** Batches of conversation history delivered during initial sync. */
+  readonly conversationSync: AsyncIterable<ConversationSyncBatch>;
+  /** Receipts, reactions, edits, and revokes on existing messages. */
+  readonly updates: AsyncIterable<Update>;
+  /** Address-book and profile-metadata updates from contact events. */
+  readonly contacts: AsyncIterable<ContactUpdate>;
+  /** Group metadata and participant updates from group events. */
+  readonly groups: AsyncIterable<GroupUpdate>;
+  /** Ephemeral remote typing/recording/availability signals. */
+  readonly presence: AsyncIterable<PresenceUpdate>;
+  /** Connect to WhatsApp and begin emitting on the streams above. */
+  start(): Promise<void>;
+  /**
+   * Send a message to a chat.
+   *
+   * @param to - The destination chat JID.
+   * @param msg - The message content to send.
+   * @param opts - Optional quoting and mentions.
+   * @returns A reference to the sent message, for later quote/react/edit/delete.
+   */
+  send(to: string, msg: Outbound, opts?: SendOptions): Promise<MessageRef>;
+  /**
+   * Mark messages as read (blue ticks).
+   *
+   * @param refs - References to the messages to acknowledge.
+   */
+  markRead(refs: MessageRef[]): Promise<void>;
+  /**
+   * Show or clear the typing indicator in a chat.
+   *
+   * @param chatId - The chat JID to signal in.
+   * @param on - `true` to show typing, `false` to clear it.
+   */
+  setTyping(chatId: string, on: boolean): Promise<void>;
+  /**
+   * Fetch normalized metadata for a group.
+   *
+   * @param chatId - The group JID.
+   */
+  groupMetadata(chatId: string): Promise<GroupMetadata>;
+  /**
+   * Fetch a profile picture URL.
+   *
+   * @param jid - A contact, account, or group JID.
+   * @param type - `"image"` for full size or `"preview"` for a thumbnail.
+   * @returns The URL, or `undefined` when none is available.
+   */
+  profilePictureUrl(jid: string, type?: "image" | "preview"): Promise<string | undefined>;
+  /**
+   * The connected account's own identity.
+   *
+   * @returns The identity once the socket is open, or `undefined` before then.
+   */
+  identity(): WaIdentity | undefined;
+  /** Tear down the session intentionally; never reported as a fault. */
+  stop(): Promise<void>;
+}
+/**
+ * Create a single WhatsApp account session.
+ *
+ * @remarks
+ * The returned session is inert until {@link WhatsAppSession.start | start} is
+ * called. Consume its streams to observe the connection lifecycle and incoming
+ * messages; call its command methods to send and interact.
+ *
+ * @param config - Store, auth strategy, and optional tuning — see
+ * {@link SessionConfig}.
+ * @returns A not-yet-connected {@link WhatsAppSession}.
+ *
+ * @example
+ * ```ts
+ * import { createSession, qrAuth, fileStore, refOf } from "whatsappd";
+ *
+ * const session = createSession({
+ *   store: fileStore("./.wa-auth"),
+ *   auth: qrAuth(),
+ * });
+ *
+ * for await (const status of session.connection) {
+ *   if (status.phase === "pairing" && status.pairing.step === "challenge_live") {
+ *     console.log("scan:", status.pairing.qr ?? status.pairing.code);
+ *   }
+ * }
+ *
+ * await session.start();
+ * ```
+ */
+declare function createSession(config: SessionConfig): WhatsAppSession;
+//#endregion
+//#region src/stores/file.d.ts
+declare function fileStore(dir: string): SessionStore;
+//#endregion
+//#region src/channel/adapter.d.ts
+interface CreateChannelAdapterOptions {
+  /** The single-account session to wrap. */
+  session: WhatsAppSession;
+  /** Label carried on status events and sidecar wire payloads. Default "default". */
+  accountId?: string;
+  /** Optional logger. */
+  logger?: Logger;
+}
+/**
+ * Create a `WhatsAppChannelAdapter` over one session.
+ *
+ * Construction does NOT connect — call `start()` to begin pumping the
+ * session's streams and open the socket to WhatsApp.
+ */
+declare function createChannelAdapter(opts: CreateChannelAdapterOptions): WhatsAppChannelAdapter;
+//#endregion
+export { type Addressing, type AgentTool, type AuthStrategy, type BinaryInput, type ChannelEvent, type ChannelHandlers, type ConnectionEvent, type ContactUpdate, type ConversationRef, type ConversationSyncBatch, type ConversationSyncChat, type ConversationSyncContact, type CreateChannelAdapterOptions, type DeleteInput, type Disposition, type EditInput, type FaultReason, type GroupMetadata, type GroupParticipant, type GroupParticipantAction, type GroupUpdate, type HistoryBatch, type HistoryChat, type HistoryContact, type InboundMessage, type MediaHandle, type MediaKind, type MediaMeta, type MessageContext, type MessageFlags, type MessageRef, type MetricEvent, type MetricsHook, type Outbound, PairingError, type PairingState, type PresenceKind, type PresenceUpdate, type ReactInput, type ReceiptStatus, type ReplyInput, type SendMediaInput, type SendOptions, type SendTextInput, type SessionConfig, type SessionStore, type SetTypingInput, type Status, type SyncState, type ToolContext, type Update, type WaIdentity, type WhatsAppChannelAdapter, type WhatsAppFault, type WhatsAppSession, allTools, assertE164, bindTools, classifyDisconnect, createChannelAdapter, createSession, deleteMsg, dispositionFor, edit, fileStore, isOnline, isRetryable, isTerminal, markRead, memoryStore, pairingAuth, qrAuth, react, refOf, reply, sendMedia, sendText, setTyping };

package/dist/index.mjs

@@ -0,0 +1,15 @@
+import { a as createSession, c as PairingError, d as dispositionFor, f as isRetryable, i as qrAuth, l as assertE164, n as fileStore, o as isOnline, r as pairingAuth, s as isTerminal, t as createChannelAdapter, u as classifyDisconnect } from "./adapter-BES4PRA9.mjs";
+import { memoryStore } from "./stores/memory.mjs";
+import { allTools, bindTools, deleteMsg, edit, markRead, react, reply, sendMedia, sendText, setTyping } from "./tools/index.mjs";
+//#region src/model/outbound.ts
+/** Build a `MessageRef` from a received message, for react/edit/delete/quote. */
+function refOf(m) {
+	return {
+		id: m.id,
+		chatId: m.chatId,
+		fromMe: m.fromMe,
+		...m.isGroup && { participant: m.from }
+	};
+}
+//#endregion
+export { PairingError, allTools, assertE164, bindTools, classifyDisconnect, createChannelAdapter, createSession, deleteMsg, dispositionFor, edit, fileStore, isOnline, isRetryable, isTerminal, markRead, memoryStore, pairingAuth, qrAuth, react, refOf, reply, sendMedia, sendText, setTyping };

package/dist/ports-DeTIMztA.d.mts

@@ -0,0 +1,60 @@
+//#region src/ports.d.ts
+/**
+ * An opaque key/value store for a session's credentials.
+ *
+ * @remarks
+ * The library serializes authentication state into plain strings (the root
+ * `creds` entry plus per-signal-key entries) and reads them back. The store
+ * only persists strings — it never interprets them, so values may be encrypted
+ * at rest without changing this contract.
+ *
+ * Keys look like `"creds"`, `"pre-key:42"`, `"session:123_1.0"`, or
+ * `"sender-key:…"`; a value is a serialized string, or `null` to delete the
+ * entry.
+ *
+ * @see {@link memoryStore}, {@link fileStore}, and `libsqlStore` for the
+ * built-in implementations.
+ */
+interface SessionStore {
+  /** Read one entry, resolving to `null` when the key is absent. */
+  read(key: string): Promise<string | null>;
+  /**
+   * Apply a batch of writes. Each value is a string to set, or `null` to
+   * delete that key.
+   */
+  write(entries: Record<string, string | null>): Promise<void>;
+  /**
+   * Erase every entry for this session. Called automatically on a terminal
+   * logout so dead credentials are never reused.
+   */
+  clear(): Promise<void>;
+}
+/**
+ * How a session authenticates: scan a QR code, or enter a pairing code on a
+ * known phone number.
+ *
+ * @see {@link qrAuth}, {@link pairingAuth}
+ */
+type AuthStrategy = {
+  method: "qr";
+} | {
+  method: "pairing_code";
+  phone: string;
+};
+/**
+ * Log in by scanning a QR code shown to the user.
+ *
+ * @returns A QR {@link AuthStrategy}.
+ */
+declare function qrAuth(): AuthStrategy;
+/**
+ * Log in with a pairing code delivered to a known phone number.
+ *
+ * @param phone - The phone number in E.164 format (e.g. `+15551234567`).
+ * @returns A pairing-code {@link AuthStrategy}.
+ * @throws {@link PairingError} with reason `"invalid_phone"` when `phone` is
+ * not valid E.164 — validated here so bad input fails before any network call.
+ */
+declare function pairingAuth(phone: string): AuthStrategy;
+//#endregion
+export { qrAuth as i, SessionStore as n, pairingAuth as r, AuthStrategy as t };

package/dist/sidecar/index.d.mts

@@ -0,0 +1,47 @@
+import { a as WireBinary, c as WireUpdate, d as toWireMessage, f as toWireUpdate, i as SidecarEvent, l as messagePreview, n as SendRequest, o as WireMedia, r as SetTypingRequest, s as WireMessage, t as MarkReadRequest, u as reviveOutbound } from "../wire-Bx6OmkxC.mjs";
+import { i as WhatsAppChannelAdapter } from "../types-B8d1OyHV.mjs";
+import { Logger } from "pino";
+import { Server } from "node:http";
+
+//#region src/sidecar/server.d.ts
+/** One URL the sidecar POSTs inbound `SidecarEvent`s to (e.g. Eve's `/event`). */
+interface ForwardTarget {
+  readonly url: string;
+  /** Sent as `Authorization: Bearer <token>` on every forwarded event. */
+  readonly token?: string;
+}
+interface SidecarServerOptions {
+  /** The account this sidecar serves. */
+  readonly adapter: WhatsAppChannelAdapter;
+  /** Where to POST inbound events. Empty = events are not forwarded. */
+  readonly forward?: readonly ForwardTarget[];
+  /** When set, every incoming request must carry `Authorization: Bearer <token>`. */
+  readonly token?: string;
+  /** Absolute base for media URLs in events; relative `/media/...` when unset. */
+  readonly baseUrl?: string;
+  readonly logger?: Logger;
+  /** How many recent media handles to keep downloadable. Default 512. */
+  readonly mediaCacheSize?: number;
+  /** Testing seam — defaults to global fetch. */
+  readonly fetchFn?: typeof fetch;
+}
+interface SidecarServer {
+  /** The underlying Node server, for hosts that need to attach to it. */
+  readonly server: Server;
+  listen(port: number, host?: string): Promise<{
+    port: number;
+  }>;
+  /** Unsubscribe from the adapter and close the HTTP server. */
+  close(): Promise<void>;
+}
+declare function createSidecarServer(options: SidecarServerOptions): SidecarServer;
+//#endregion
+//#region src/sidecar/index.d.ts
+interface RunningSidecar {
+  readonly port: number;
+  readonly server: SidecarServer;
+  close(): Promise<void>;
+}
+declare function runSidecar(env?: NodeJS.ProcessEnv): Promise<RunningSidecar>;
+//#endregion
+export { type ForwardTarget, MarkReadRequest, RunningSidecar, SendRequest, SetTypingRequest, SidecarEvent, type SidecarServer, type SidecarServerOptions, WireBinary, WireMedia, WireMessage, WireUpdate, createSidecarServer, messagePreview, reviveOutbound, runSidecar, toWireMessage, toWireUpdate };