chore: release v4.8.4

Author: zeative

.changeset/auto-reject-call.md

@@ -1,5 +1,11 @@
 # zaileys
 
+## 4.8.4
+
+### Patch Changes
+
+- bd6be18: Auto-reject incoming calls. New `autoRejectCall` client option (`true`, or `{ enabled, allow, onReject }`) hangs up incoming WhatsApp calls automatically — with an allow-list (jid/digits array or predicate) and an `onReject` hook to notify the caller. The underlying `client.rejectCall(call)` / `client.rejectCall(callId, from)` method is exposed for manual control from a `call-incoming` handler. Off by default; unofficial provider only (the Cloud API has no calls — it throws `UNSUPPORTED_ON_CLOUD`).
+
 ## 4.8.3
 
 ### Patch Changes

CHANGELOG.md

@@ -1,7 +1,7 @@
 {
   "name": "zaileys",
   "description": "Zaileys - Simplified WhatsApp Node.js TypeScript/JavaScript API",
-  "version": "4.8.3",
+  "version": "4.8.4",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",

package.json

@@ -1,133 +1,153 @@
-# Plan — Full rewrite of the zaileys Agent Skill suite (provider-aware)
+# Plan — Auto-reject calls (`autoRejectCall` config + `client.rejectCall()` method)
+
+Team ask: auto-reject incoming WhatsApp calls, **toggleable via `Client` config**, and **expose the
+method** so it can be called manually. Then update docs.
+
+## Findings (read-only investigation)
+
+- **Primitive exists**: baileys exposes `rejectCall(callId: string, callFrom: string): Promise<void>`
+  (`node_modules/baileys/lib/Socket/index.d.ts:66`). No wrapper in zaileys today (`grep rejectCall src/` = 0).
+- **Call events already wired**: `call-incoming` / `call-ended` emit `CallPayload`
+  (`{ callId, from, isGroup, isVideo, timestamp, status }`) — `src/events/decoders/calls.ts`,
+  `src/events/pipeline.ts:274`.
+- **Toggle pattern to mirror**: `autoDelete?: AutoDeleteOptions | false` in `ClientOptions` →
+  `AutoDeleteSweeper` module in `src/automation/`, constructed in the Client ctor, started on connect,
+  stopped on close. `PresenceModule` shows the options+method shape.
+- **Provider dimension (blast radius)**: calls are **WhatsApp-Web-only**. The Cloud API provider has no
+  call events, so `rejectCall()` must throw `ZaileysProviderError('UNSUPPORTED_ON_CLOUD')` like
+  `edit`/`delete`/`pin`, and `autoRejectCall` must be inert on cloud (never wired).
+
+## Design (decided)
+
+```ts
+// config — OFF by default (rejecting calls is destructive; must be opt-in)
+new Client({ autoRejectCall: true })
+new Client({ autoRejectCall: { enabled: true, allow: ['628owner@s.whatsapp.net'], onReject: (call) => … } })
+
+// method — accepts the event payload OR raw ids
+await client.rejectCall(call)               // call = CallPayload from 'call-incoming'
+await client.rejectCall(callId, from)
+```
 
-Source of truth: [SPEC.md](../SPEC.md). Goal: **full rewrite** of every skill file so both providers
-(🔗 unofficial / ☁️ official Cloud API) are native throughout — not appended. Canonical lives in
-`skills/*`; `plugins/zaileys-official/skills/*` is generated by `npm run skill:sync` (never hand-edit).
+`AutoRejectCallOptions = { enabled?: boolean; allow?: string[] | ((jid: string) => boolean | Promise<boolean>); onReject?: (call) => void | Promise<void> }`
+— `allow` = whitelist (skip rejecting these callers, mirrors the `citation` predicate style);
+`onReject` = post-reject hook (e.g. send "sorry, calls not supported"). Keep it lean — no
+video/voice/group sub-filters until asked (`isVideo`/`isGroup` are already on the payload, so users
+can filter inside `allow`).
 
-## Files & dependency graph
+## Dependency graph
 
 ```
-                 ┌───────────────────────────────┐
-                 │ T1 references/cloud.md (NEW)   │  ← single source of cloud truth
-                 │ T2 references/api.md (+provider)│     everything else cites these
-                 └───────────────┬───────────────┘
-        ┌────────────────────────┼────────────────────────┐
-        ▼                        ▼                         ▼
-  ┌───────────────┐   ┌───────────────────────┐   ┌──────────────────────┐
-  │ T3 assist     │   │ T4 errors  T5 pitfalls│   │ T8 scaffold          │
-  │   SKILL.md    │   │ T6 recipes T7 trouble │   │ T9 debug T10 review  │
-  └───────┬───────┘   └───────────┬───────────┘   └──────────┬───────────┘
-          └───────────────────────┼──────────────────────────┘
-                                  ▼
-                     ┌──────────────────────────┐
-                     │ T11 skill:sync + verify   │  ← mirror + diff + snippet audit
-                     └──────────────────────────┘
+        ┌──────────────────────────────────────┐
+        │ T1 automation/auto-reject-call.ts    │  module: options, allow-predicate, reject+hook
+        │    + unit tests                       │  (pure, socket injected)
+        └───────────────┬──────────────────────┘
+                        ▼
+        ┌──────────────────────────────────────┐
+        │ T2 Client wiring                      │  ClientOptions.autoRejectCall, ctor, attach on
+        │    + client.rejectCall() + guard      │  connect (baileys only), web-only guard, exports
+        └───────────────┬──────────────────────┘
+                ┌───────┴────────┐
+                ▼                ▼
+        ┌───────────────┐  ┌──────────────────┐
+        │ T3 docs site  │  │ T4 skill suite   │   (independent of each other)
+        └───────┬───────┘  └────────┬─────────┘
+                └────────┬──────────┘
+                         ▼
+                 ┌───────────────┐
+                 │ T5 changeset  │  minor + release-ready
+                 └───────────────┘
 ```
 
-- **T1 (cloud.md) + T2 (api.md provider section) block everything** — they are the referenced truth.
-- T3 (orchestrator) references all references incl. cloud.md.
-- T4–T7 (references) each cite cloud.md for cloud detail; independent of each other.
-- T8–T10 (sibling skills) cite cloud.md + recipes; independent of each other.
-- T11 (sync + verify) is last — mirrors canonical to the plugin copy and audits.
+- **T1 blocks T2** (Client constructs the module).
+- **T3 / T4 need T2** (document the shipped API); independent of each other.
+- **T5** last.
 
 ## Phases & checkpoints
 
-- **Phase A = T1 + T2.** → 🚩 CP1: cloud reference complete + api.md provider section; every snippet valid vs `src/cloud/*` and 4.8.1.
-- **Phase B = T3 + T4 + T5 + T6 + T7.** → 🚩 CP2: orchestrator + all 6 references provider-aware; routing covers every cloud intent.
-- **Phase C = T8 + T9 + T10.** → 🚩 CP3: scaffold/debug/review all provider-aware.
-- **Phase D = T11.** → 🚩 CP4: `diff -r skills plugins/.../skills` clean; ready to commit.
-
-Slicing note: these are docs, so each task = **one file rewritten completely with both providers**,
-ordered by dependency (the referenced `cloud.md` first). Each task is independently verifiable and
-leaves the suite coherent.
+- **Phase A = T1 + T2.** → 🚩 CP1: feature works + guarded; full suite green; typecheck clean.
+- **Phase B = T3 + T4.** → 🚩 CP2: docs site builds; skill synced (`diff -r` clean).
+- **Phase C = T5.** → 🚩 CP3: changeset in; ready to release (publish = user's call).
 
 ---
 
 ## Tasks
 
-### Phase A — Cloud source of truth
-
-**T1 — `references/cloud.md` (NEW).** The self-contained official-provider reference.
-Sections: provider switch + `CloudOptions` (accessToken/phoneNumberId/wabaId/verifyToken/appSecret/
-apiVersion/baseUrl); `connect()` = health-check (no socket/QR); `webhook()` — framework-agnostic
-handler + Next/Hono/Express/node:http mounts + Meta dashboard setup; **sending differences** (shared
-builder → cite api.md; cloud caveats: buttons max 3, no carousel/poll, `markRead(id,{typing})`,
-contact first-name, media sizes); `sendTemplate(to,name,lang,components)`; OTP create+send; marketing
-campaigns; **full `wa.cloud.*`** (templates CRUD+get, profile, info, phoneNumbers, flows, commerce
-catalogs/products/send, blocklist, qr, analytics, phone, sendAddressRequest); cloud events
-(`message-status`/`template-status`/`flow-response`/`order`); the 24-hour window; limits & gotchas
-with fixes; `UNSUPPORTED_ON_CLOUD` for web-only.
-- *Accept*: every method/param matches `src/cloud/*` (the live-tested surface); no invented API;
-  web-only features stated as ❌ with the fix.
-- *Verify*: grep each `wa.cloud.X`/`send*` against `src/cloud/module.ts`, `transport.ts`,
-  `client.ts`; snippets compile-plausible.
-
-**T2 — `references/api.md` provider section.** Add a top-of-file **Providers** subsection (`provider`
-option, cloud config shape, "shared vs cloud-only", link to cloud.md). Mark the web-only domain
-namespaces (`group`/`newsletter`/`community`/`privacy`/`presence`, `edit`/`delete`/`pin`) as
-**unofficial-only — throw `UNSUPPORTED_ON_CLOUD` on cloud**.
-- *Accept*: reader knows provider exists before the builder section; web-only surfaces flagged.
-- *Verify*: cross-check the guard list against `assertWebProvider` sites in `src/client/client.ts`.
+### T1 — `src/automation/auto-reject-call.ts` + unit tests
 
-🚩 **CP1** — cloud reference + api provider section accurate & cross-linked.
+Module owning the policy. Socket + logger injected (testable, no Client dependency).
 
-### Phase B — Orchestrator + references
-
-**T3 — `zaileys-assist/SKILL.md` full rewrite.** Provider-aware intro ("two providers, one API,
-baileys default"); routing table gains rows for cloud/webhook/template/OTP/campaign/Flows/commerce/
-`wa.cloud.*` → cloud.md; mental model adds the provider dimension (cloud = token auth + webhook, no
-socket); golden rules provider-aware (cold send needs template; web-only throws on cloud); references
-list includes cloud.md.
-- *Accept*: any cloud intent routes to cloud.md; baileys stays the default framing.
-- *Verify*: every cloud intent in SPEC §2.1 has a routing row.
-
-**T4 — `references/errors.md`.** Add `ZaileysCloudError` (CONFIG/AUTH/REQUEST_FAILED/RATE_LIMITED/
-NOT_IMPLEMENTED), `ZaileysProviderError` (UNSUPPORTED_ON_CLOUD), + Graph codes (131047, 132000,
-131009, 190, 131026, 131056) with cause→fix. Keep existing baileys error classes.
-- *Verify*: codes match `src/cloud/errors.ts` + the docs error table.
+```ts
+export interface AutoRejectCallOptions { enabled?: boolean; allow?: …; onReject?: … }
+export interface CallSocketLike { rejectCall(callId: string, callFrom: string): Promise<void> }
+export class AutoRejectCallModule {
+  constructor(getSocket: () => CallSocketLike | undefined, options: AutoRejectCallOptions, logger?)
+  reject(callId: string, from: string): Promise<void>     // raw reject (used by the public method)
+  handle(call: CallPayload): Promise<void>                 // policy: allow-check → reject → onReject
+}
+```
 
-**T5 — `references/pitfalls.md`.** Add cloud anti-patterns → correct way: cold send w/o template
-(131047); param count mismatch (132000); `rich:true` on cloud (web-only); calling `group`/`newsletter`
-on cloud; forgetting the webhook; body-parser eating the raw body; not making inbound idempotent.
+- *Accept*: `handle()` rejects a call when enabled; **skips** when the caller matches `allow`
+  (array or predicate); runs `onReject` **after** a successful reject; a throwing `onReject` or
+  `rejectCall` is logged, never crashes the client; `reject()` throws a typed error when there's no
+  socket (not connected).
+- *Verify*: `tests/automation/auto-reject-call.test.ts` — enabled/disabled, allow-array, allow-predicate
+  (sync+async), onReject called once with the payload, reject failure swallowed+logged, no-socket error.
 
-**T6 — `references/recipes.md`.** Add runnable cloud recipes: cloud echo bot + webhook (Next/Hono/
-Express), send OTP (create+send), marketing campaign (create→approve→broadcast→track), receive
-`order`/`flow-response`.
-- *Verify*: recipes use only real 4.8.1 API.
+### T2 — Client wiring + public `rejectCall()` + guards
 
-**T7 — `references/troubleshooting.md`.** Add cloud runtime symptoms: webhook verify 403 / signature
-401, events not firing (webhook needs no connect() but must be mounted; check subscribe `messages`),
-`131047` outside window, token expired 190.
+- `ClientOptions.autoRejectCall?: boolean | AutoRejectCallOptions` (default **off**), normalized in the
+  ctor (`true` → `{ enabled: true }`).
+- Construct the module; **attach to `call-incoming` only on the baileys provider** when enabled
+  (wire where the inbound pipeline is attached; detach on close alongside the other handles).
+- Public method `client.rejectCall(callOrId: CallPayload | string, from?: string): Promise<void>` —
+  `assertWebProvider('rejectCall')` first (throws `UNSUPPORTED_ON_CLOUD` on cloud), then delegate.
+- Export `AutoRejectCallOptions` from `src/automation/index.ts` (and thus the package root).
+- *Accept*: `new Client({ autoRejectCall: true })` auto-rejects an emitted `call-incoming`;
+  default (unset) does **not** reject; `client.rejectCall(call)` and `client.rejectCall(id, from)` both
+  work; on `provider:'cloud'` the method throws `UNSUPPORTED_ON_CLOUD` and the config is never wired;
+  handlers detach on disconnect (no double-reject after reconnect).
+- *Verify*: `tests/client/auto-reject-call.test.ts` with the existing mock socket
+  (`makeIntegrationSocket` + `triggerCall`-style ev emit): toggle on/off, both method arities, cloud
+  guard, allow-list end-to-end. Then `pnpm test` (full suite) + `npx tsc --noEmit`.
 
-🚩 **CP2** — orchestrator + all references provider-aware; routing complete.
+🚩 **CP1** — feature + guard done; 2482+ tests green; typecheck clean.
 
-### Phase C — Sibling skills
+### T3 — Docs site
 
-**T8 — `zaileys-scaffold/SKILL.md`.** Ask **which provider** first; scaffold a cloud project variant
-(client + `webhook()` route + `.env` for token/phone/verify/appSecret) alongside the baileys variant.
-Description mentions cloud/official/webhook.
+- `docs/content/configuration.mdx` — add the `autoRejectCall` row/section (type, default `false`,
+  options table, examples incl. `allow` + `onReject`).
+- `docs/content/events.mdx` — under the call events, cross-link auto-reject + `client.rejectCall()`.
+- `docs/content/api-reference.mdx` — add `rejectCall` to the client-methods list.
+- `docs/content/providers.mdx` + `docs/content/official/limits.mdx` — mark calls / `rejectCall` as
+  **🔗 unofficial-only** (they don't exist on the Cloud API).
+- *Verify*: `cd docs && npm run build` → clean; `out/index.html` present.
 
-**T9 — `zaileys-debug/SKILL.md`.** Add cloud error taxonomy + webhook symptoms to the doctor;
-description mentions cloud error codes.
+### T4 — Skill suite (canonical `skills/*`, then sync)
 
-**T10 — `zaileys-review/SKILL.md`.** Add cloud checks: template-gated cold sends, webhook signature +
-idempotency, no web-only calls on cloud, secret handling. Description mentions cloud review.
+- `references/api.md` — `autoRejectCall` in the ClientOptions table; `rejectCall` in client methods;
+  flag as unofficial-only.
+- `references/recipes.md` — a short "auto-reject calls" recipe (config + manual + notify-caller hook).
+- `zaileys-review/SKILL.md` quick-cues — `rejectCall` in the method list.
+- `npm run skill:sync` → `diff -r skills plugins/zaileys-official/skills` clean.
+- *Verify*: snippets match the shipped API exactly (grep against `src/`); diff clean.
 
-🚩 **CP3** — all four skills provider-aware.
+🚩 **CP2** — docs build green; skill synced.
 
-### Phase D — Sync + verify
+### T5 — Changeset
 
-**T11 — `npm run skill:sync` + verify.** Mirror canonical → plugin copy. `diff -r skills
-plugins/zaileys-official/skills` = clean (minus intentional plugin-only files). Audit: every cloud
-snippet valid vs `src/cloud/*`; routing covers all cloud intents; unofficial content un-regressed.
-- *Verify*: `diff -r` empty; spot-check 5 cloud snippets against source.
+- `.changeset/*.md` **minor** (additive feature): config `autoRejectCall` + `client.rejectCall()`.
+- *Verify*: `npx changeset version` dry-sane (do NOT version/publish without the user's go-ahead).
 
-🚩 **CP4** — plugin copy matches canonical; ready to commit (release/publish = ask user).
+🚩 **CP3** — ready to release.
 
 ## Risks
 
-- **Snippet drift** — inventing Cloud-API methods. Mitigate: grep every call against `src/cloud/*`
-  before writing; T1 is the vetted source all others cite.
-- **Sync drift** — hand-editing the plugin copy. Mitigate: edit only `skills/*`, T11 regenerates.
-- **Over-duplication** — re-teaching shared builder per provider. Mitigate: cloud.md documents only
-  differences + cloud-exclusive; cites api.md for shared.
+- **Destructive default** — auto-rejecting calls without opt-in would surprise users. Mitigate: default
+  **off**; `true` must be explicit.
+- **Double-reject / leaks after reconnect** — the `call-incoming` handler must be detached with the
+  other pipeline handles. Mitigate: attach/detach beside the existing `inboundHandle` lifecycle; test
+  reconnect.
+- **Provider drift** — calls are web-only; forgetting the guard means a confusing cloud crash.
+  Mitigate: `assertWebProvider` + a cloud-guard test (T2), docs/skill flagged (T3/T4).
+- **Hook failures** — a user `onReject` that throws must not kill the client. Mitigate: catch+log (T1).