zaileys 4.15.1 → 4.17.0

package/README.md

@@ -118,20 +118,22 @@ Pick your provider → **[Choose Your Provider](https://zaileys.kejaa.id/provide
 
 ## Build with AI
 
-Zaileys ships an **official Agent Skill suite** so your AI assistant writes, reviews, and
-debugs zaileys code with best practices — it knows the exact API, common pitfalls, and how
-to fix errors. Install it straight from this repo:
+Zaileys ships an **official Agent Skill**, `zaileys`, so your AI assistant builds, extends, debugs, reviews,
+upgrades, and deploys zaileys bots with the real API instead of guessing. It covers both providers, includes
+runnable templates and a read-only project doctor, and is checked against the source on every change.
+Install it straight from this repo:
 
 ```bash
-# Claude Code (native plugin — supports auto-update)
+# Claude Code plugin
 /plugin marketplace add zeative/zaileys
 /plugin install zaileys-official@zeative
 
-# npx skills (multi-agent: Claude Code, Codex, Cursor, OpenCode)
+# npx skills (Claude Code, Codex, Cursor, OpenCode, and more)
 npx skills add zeative/zaileys        # add -g for a global install
 ```
 
-The suite has an orchestrator that auto-routes plus focused scaffold, debug, and review skills. See the full guide → **[zaileys.kejaa.id/ai](https://zaileys.kejaa.id/ai)**.
+Upgrading from the four earlier skills (`zaileys-assist`, `-scaffold`, `-debug`, `-review`)? See
+**[zaileys.kejaa.id/ai](https://zaileys.kejaa.id/ai#upgrade-from-the-four-skills)**.
 
 ## Why Zaileys
 
@@ -281,7 +283,7 @@ Package managers: **npm**, **pnpm**, **yarn**, and **bun** are all supported.
   - [Recipes](https://zaileys.kejaa.id/recipes/auto-reply) — complete bots you can copy
   - [Reference](https://zaileys.kejaa.id/reference/client) — every method, option, and event
   - [Feature matrix](https://zaileys.kejaa.id/feature-matrix) — what works on which provider
-- 🤖 [**Build with AI**](https://zaileys.kejaa.id/ai) — official Claude Code / `npx skills` skill
+- 🤖 [**Build with AI**](https://zaileys.kejaa.id/ai) — official agent skill for Claude Code, Codex, Cursor, and more
 - 📦 [**examples/**](./examples) — runnable bots: quickstart, interactive buttons, AIRich, storage adapters, broadcast
 - 🔀 [**MIGRATION.md**](./MIGRATION.md) — upgrading from v3.x to v4.0.0 (breaking changes, side-by-side snippets)
 - 🤝 [**CONTRIBUTING.md**](./CONTRIBUTING.md) — dev setup, tests, commit convention, release flow

package/dist/builder/builder.d.ts

@@ -3,6 +3,7 @@ import { type ButtonsContentOptions } from './content/buttons.js';
 import { type CarouselCard } from './content/carousel.js';
 import { type AIRichOptions } from './content/airich.js';
 import { type HtmlAppOptions } from './content/html-app.js';
+import type { SafeHtml } from './html.js';
 import { type BuilderInternalState } from './state.js';
 import type { AlbumItem, AudioOptions, BuilderState, ButtonDef, DocumentOptions, EventOptions, GroupInviteOptions, GroupStatusOptions, GroupStatusRepostOptions, GroupStatusSource, ImageOptions, InteractiveButton, ListOptions, LocationOptions, MediaSource, PollOptions, ProductOptions, StickerOptions, TemplateOptions, VideoNoteOptions, VideoOptions } from './types.js';
 export interface BuilderSocketLike {
@@ -30,7 +31,8 @@ export declare class MessageBuilder<State extends BuilderState> {
     static create(socket: BuilderSocketLike, recipient: string, resolveRecipient?: (raw: string) => Promise<string>, recordSent?: (message: WAMessage) => void, inheritDisappearing?: (jid: string) => number | undefined): MessageBuilder<'init'>;
     to(this: MessageBuilder<'init'>, recipient: string): MessageBuilder<'init'>;
     text(this: MessageBuilder<'init'>, content: string, opts?: TextOptions): MessageBuilder<'content-set'>;
-    htmlApp(this: MessageBuilder<'init'>, html: string, opts?: HtmlAppOptions): MessageBuilder<'content-set'>;
+    /** Sends an HTML page that runs inside the bubble on WhatsApp Android. Experimental WhatsApp format. */
+    htmlApp(this: MessageBuilder<'init'>, markup: string | SafeHtml, opts?: HtmlAppOptions): MessageBuilder<'content-set'>;
     image(this: MessageBuilder<'init'>, src: MediaSource, opts?: ImageOptions): MessageBuilder<'content-set'>;
     videoNote(this: MessageBuilder<'init'>, src: MediaSource, opts?: VideoNoteOptions): MessageBuilder<'content-set'>;
     video(this: MessageBuilder<'init'>, src: MediaSource, opts?: VideoOptions): MessageBuilder<'content-set'>;
@@ -77,10 +79,8 @@ export declare class MessageBuilder<State extends BuilderState> {
     private applyRelayMentions;
     private sendRelay;
     /**
-     * Re-sends the card as an edit of itself. Without it the recipient gets WhatsApp's
-     * "can't verify the security of this media" prompt and has to tap Download before the page renders.
-     * The edit must sit inside `botForwardedMessage` like the original, otherwise it lands as its own
-     * broken message instead of replacing the card.
+     * Re-sends the card as an edit of itself, which renders it without WhatsApp's download prompt. The edit
+     * must sit inside `botForwardedMessage` like the original, or it lands as its own broken message.
      */
     private relayIdenticalEdit;
 }

package/dist/builder/content/airich.d.ts

@@ -31,7 +31,6 @@ export type AIRichPart = {
 } | {
     type: 'html';
     html: string;
-    trustedSources?: string[];
     height?: number;
 } | {
     type: 'suggest';
@@ -82,6 +81,6 @@ export type AIRichOptions = {
     footer?: string;
     sources?: Array<[profileUrl: string, url: string, text: string]>;
 };
-/** Android renders no other primitive; Web, Desktop and iOS map it to an empty section. */
+/** Undocumented WhatsApp primitive; only Android renders it, and it runs with no network access. */
 export declare const AI_RICH_HTML_PRIMITIVE = "GenAIaeacdsnwHtmlPrimitive";
 export declare const buildAIRichContent: (parts: AIRichPart[], opts?: AIRichOptions) => AnyMessageContent;

package/dist/builder/content/html-app.d.ts

@@ -1,26 +1,24 @@
 import type { AnyMessageContent } from 'baileys';
-export type HtmlAppDevice = 'android' | 'ios' | 'web' | 'desktop' | 'unknown';
-export type HtmlAppOptions = {
-    /** From baileys' `getDevice(messageId)`. Anything but `android` takes the fallback. */
-    device?: HtmlAppDevice;
-    /** Where non-Android clients open the page instead. Required unless the device is android. */
-    fallbackUrl?: string;
-    fallbackButtonText?: string;
-    /** Rendered above the card, and as the body of the fallback message. */
-    text?: string;
-    footer?: string;
-    trustedSources?: string[];
-    /** Pins the page height so the host stops re-measuring a bubble whose height follows its width. */
+import { SafeHtml } from '../html.js';
+/** Default byte ceiling for `htmlApp()` markup. */
+export declare const HTML_APP_MAX_BYTES: number;
+export interface HtmlAppOptions {
+    /** Small label shown above the card. Default: none. */
+    title?: string;
+    /** Pins the card height in CSS pixels (1–4096) so the bubble stops re-measuring. Default: the page's own height. */
     height?: number;
+    /** Recipient device, usually `ctx.senderDevice`; non-`'android'` sends `fallback` or throws. Default: Android. */
+    device?: string;
+    /** Plain text sent instead of the card when `device` is not Android. Default: none. */
+    fallback?: string;
+    /** Byte ceiling for the UTF-8 markup. Default 256 KB. */
+    maxBytes?: number;
     /**
-     * Follows the card with an identical edit so it renders immediately instead of behind WhatsApp's
-     * "can't verify the security of this media" prompt. Costs one extra relay and one re-render, so a
-     * page running an animation restarts once. Defaults to on.
+     * Follow the card with an identical edit so it renders without WhatsApp's Download prompt. Costs one extra
+     * relay, and the card reloads whenever the recipient opens the keyboard. Default `true`; `false` for pages
+     * that keep state, such as games.
      */
     bypassDownload?: boolean;
-};
-/**
- * Only WhatsApp Android renders an inline HTML primitive. Every other client drops the section and
- * leaves an empty bubble, so they get a webview button to the same page instead.
- */
-export declare const buildHtmlAppContent: (html: string, opts?: HtmlAppOptions) => AnyMessageContent;
+}
+/** Builds an inline HTML card. WhatsApp renders it only on Android, with no network or storage access. */
+export declare const buildHtmlAppContent: (markup: string | SafeHtml, opts?: HtmlAppOptions) => AnyMessageContent;

package/dist/builder/html.d.ts

@@ -0,0 +1,14 @@
+/** Markup that `html` inserts verbatim. Build it with `html`, `rawHtml` or `htmlJson`, never from user input. */
+export declare class SafeHtml {
+    readonly value: string;
+    constructor(value: string);
+    toString(): string;
+}
+/** Escapes the characters that can open a tag or close an attribute. */
+export declare const escapeHtml: (value: string) => string;
+/** Marks trusted markup so `html` does not escape it. */
+export declare const rawHtml: (markup: string) => SafeHtml;
+/** Serialises a value for `<script>`, escaping the sequences that could close the tag early. */
+export declare const htmlJson: (value: unknown) => SafeHtml;
+/** Escapes interpolated values; `SafeHtml` and arrays of it pass through, `null`/`undefined`/`false` vanish. */
+export declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => SafeHtml;

package/dist/builder/index.d.ts

@@ -2,7 +2,7 @@ export * from './types.js';
 export * from './errors.js';
 export { MessageBuilder, type BuilderSocketLike, type TextOptions } from './builder.js';
 export { EditBuilder } from './edit-builder.js';
-export { buildHtmlAppContent, type HtmlAppDevice, type HtmlAppOptions, } from './content/html-app.js';
-export { AI_RICH_HTML_PRIMITIVE, type AIRichPart } from './content/airich.js';
+export { HTML_APP_MAX_BYTES, type HtmlAppOptions } from './content/html-app.js';
+export { SafeHtml, escapeHtml, html, htmlJson, rawHtml } from './html.js';
 export { deleteMessage, reactToMessage, forwardMessage, pinMessage, type DeleteOptions, type PinOptions, } from './mutations.js';
 export { isJid, resolveUsername, type UsernameResolveSocketLike, } from './username-resolve.js';