zapo-js 0.2.0 → 1.0.0

package/dist/util/clock.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServerClock = createServerClock;
+function createServerClock(getClockSkewMs) {
+    return {
+        nowMs() {
+            const skewMs = getClockSkewMs();
+            const nowMs = Date.now();
+            return Number.isFinite(skewMs) ? nowMs + skewMs : nowMs;
+        },
+        nowSeconds() {
+            const skewMs = getClockSkewMs();
+            const nowMs = Date.now();
+            const correctedMs = Number.isFinite(skewMs) ? nowMs + skewMs : nowMs;
+            return Math.floor(correctedMs / 1000);
+        }
+    };
+}

package/dist/util/coercion.js

@@ -8,47 +8,67 @@ exports.asBytes = asBytes;
 exports.asOptionalBytes = asOptionalBytes;
 exports.toBoolOrUndef = toBoolOrUndef;
 exports.resolvePositive = resolvePositive;
+exports.tryAsString = tryAsString;
+exports.tryAsNumber = tryAsNumber;
+exports.tryAsRecord = tryAsRecord;
 const bytes_1 = require("./bytes");
 const primitives_1 = require("./primitives");
+/**
+ * Coerces `value` to a safe-integer/finite number, accepting `number` and
+ * `bigint` inputs. Throws with a `${field}`-suffixed message on any other type.
+ */
 function asNumber(value, field) {
-    if (typeof value === 'bigint') {
-        return (0, primitives_1.toSafeNumber)(Number(value), field);
-    }
     if (typeof value === 'number') {
         return (0, primitives_1.toSafeNumber)(value, field);
     }
+    if (typeof value === 'bigint') {
+        return (0, primitives_1.toSafeNumber)(Number(value), field);
+    }
     throw new Error(`invalid number value for ${field}`);
 }
+/** Optional variant of {@link asNumber}; returns `undefined` when input is nullish. */
 function asOptionalNumber(value, field = 'optional number') {
     if (value === null || value === undefined)
         return undefined;
     return asNumber(value, field);
 }
+/** Asserts that `value` is a string. Throws with a `${field}`-suffixed message otherwise. */
 function asString(value, field) {
     if (typeof value === 'string') {
         return value;
     }
     throw new Error(`invalid string value for ${field}`);
 }
+/** Optional variant of {@link asString}; returns `undefined` when input is nullish. */
 function asOptionalString(value, field = 'optional string') {
     if (value === null || value === undefined)
         return undefined;
     return asString(value, field);
 }
+/**
+ * Coerces `value` to a Uint8Array view, accepting `Uint8Array`, `ArrayBuffer`,
+ * and any `ArrayBufferView`. Throws with a `${field}`-suffixed message otherwise.
+ */
 function asBytes(value, field) {
     if (value instanceof Uint8Array || value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
         return (0, bytes_1.toBytesView)(value);
     }
     throw new Error(`invalid bytes value for ${field}`);
 }
+/** Optional variant of {@link asBytes}; returns `undefined` when input is nullish. */
 function asOptionalBytes(value, field = 'optional bytes') {
     if (value === null || value === undefined)
         return undefined;
     return asBytes(value, field);
 }
+/** Returns `undefined` when `value` is nullish, otherwise `Boolean(value)`. */
 function toBoolOrUndef(value) {
     return value === null || value === undefined ? undefined : Boolean(value);
 }
+/**
+ * Returns `value` when it is a positive safe-integer, `fallback` when it is
+ * undefined, and throws otherwise.
+ */
 function resolvePositive(value, fallback, name) {
     if (value === undefined)
         return fallback;
@@ -56,3 +76,28 @@ function resolvePositive(value, fallback, name) {
         return value;
     throw new Error(`${name} must be a positive safe integer`);
 }
+/**
+ * Lenient variants for parsing external JSON payloads (GraphQL responses,
+ * Mex notifications) where fields may be missing, empty, or arrive as the
+ * wrong primitive. Return null instead of throwing.
+ */
+function tryAsString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function tryAsNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim();
+        if (normalized.length === 0)
+            return null;
+        const parsed = Number(normalized);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function tryAsRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/util/collections.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveCleanupIntervalMs = resolveCleanupIntervalMs;
+exports.createPeriodicCleanup = createPeriodicCleanup;
 exports.normalizeQueryLimit = normalizeQueryLimit;
 exports.setBoundedMapEntry = setBoundedMapEntry;
 function resolveCleanupIntervalMs(ttlMs, maxIntervalMs = 60000) {
@@ -9,6 +10,17 @@ function resolveCleanupIntervalMs(ttlMs, maxIntervalMs = 60000) {
     }
     return Math.min(maxIntervalMs, Math.floor(ttlMs / 2));
 }
+function createPeriodicCleanup(ttlMs, run) {
+    const timer = setInterval(run, resolveCleanupIntervalMs(ttlMs));
+    timer.unref?.();
+    return {
+        destroy: () => clearInterval(timer)
+    };
+}
+/**
+ * Returns a validated positive-safe-integer query limit, falling back to
+ * `defaultLimit` when `limit` is undefined. Throws on invalid input.
+ */
 function normalizeQueryLimit(limit, defaultLimit) {
     if (limit === undefined) {
         return defaultLimit;

package/dist/util/index.js

@@ -1,9 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isBunRuntime = exports.toSafeNumber = exports.normalizeQueryLimit = exports.toBoolOrUndef = exports.resolvePositive = exports.asString = exports.asOptionalString = exports.asOptionalNumber = exports.asOptionalBytes = exports.asNumber = exports.asBytes = exports.uint8Equal = exports.toBytesView = exports.hexToBytes = exports.bytesToHex = void 0;
+exports.isBunRuntime = exports.toSafeNumber = exports.toError = exports.normalizeQueryLimit = exports.toBoolOrUndef = exports.resolvePositive = exports.asString = exports.asOptionalString = exports.asOptionalNumber = exports.asOptionalBytes = exports.asNumber = exports.asBytes = exports.uint8Equal = exports.toBytesView = exports.TEXT_DECODER = exports.hexToBytes = exports.decodeBase64Url = exports.bytesToHex = exports.bytesToBase64UrlSafe = exports.bytesToBase64 = exports.base64ToBytes = void 0;
 var bytes_1 = require("./bytes");
+Object.defineProperty(exports, "base64ToBytes", { enumerable: true, get: function () { return bytes_1.base64ToBytes; } });
+Object.defineProperty(exports, "bytesToBase64", { enumerable: true, get: function () { return bytes_1.bytesToBase64; } });
+Object.defineProperty(exports, "bytesToBase64UrlSafe", { enumerable: true, get: function () { return bytes_1.bytesToBase64UrlSafe; } });
 Object.defineProperty(exports, "bytesToHex", { enumerable: true, get: function () { return bytes_1.bytesToHex; } });
+Object.defineProperty(exports, "decodeBase64Url", { enumerable: true, get: function () { return bytes_1.decodeBase64Url; } });
 Object.defineProperty(exports, "hexToBytes", { enumerable: true, get: function () { return bytes_1.hexToBytes; } });
+Object.defineProperty(exports, "TEXT_DECODER", { enumerable: true, get: function () { return bytes_1.TEXT_DECODER; } });
 Object.defineProperty(exports, "toBytesView", { enumerable: true, get: function () { return bytes_1.toBytesView; } });
 Object.defineProperty(exports, "uint8Equal", { enumerable: true, get: function () { return bytes_1.uint8Equal; } });
 var coercion_1 = require("./coercion");
@@ -18,6 +23,7 @@ Object.defineProperty(exports, "toBoolOrUndef", { enumerable: true, get: functio
 var collections_1 = require("./collections");
 Object.defineProperty(exports, "normalizeQueryLimit", { enumerable: true, get: function () { return collections_1.normalizeQueryLimit; } });
 var primitives_1 = require("./primitives");
+Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return primitives_1.toError; } });
 Object.defineProperty(exports, "toSafeNumber", { enumerable: true, get: function () { return primitives_1.toSafeNumber; } });
 var runtime_1 = require("./runtime");
 Object.defineProperty(exports, "isBunRuntime", { enumerable: true, get: function () { return runtime_1.isBunRuntime; } });

package/dist/util/primitives.js

@@ -5,7 +5,15 @@ exports.toSafeNumber = toSafeNumber;
 exports.longToNumber = longToNumber;
 exports.normalizeNonNegativeInteger = normalizeNonNegativeInteger;
 exports.parseOptionalInt = parseOptionalInt;
+exports.parseOptionalSignedInt = parseOptionalSignedInt;
 const DIGITS_ONLY_RE = /^\d+$/;
+const SIGNED_DIGITS_RE = /^-?\d+$/;
+/**
+ * Normalizes an unknown thrown value into an `Error` – `Error` instances are
+ * returned unchanged, strings/numbers are wrapped, and objects with `message`
+ * or `code` fields are mapped to readable messages. Use in `catch` blocks
+ * before logging.
+ */
 function toError(value) {
     if (value instanceof Error)
         return value;
@@ -32,6 +40,10 @@ function assertSafeInteger(value, field, nullishBehavior) {
     const prefix = nullishBehavior === 'throw' ? `invalid ${field}` : 'invalid long numeric value';
     throw new Error(`${prefix}: ${value}`);
 }
+/**
+ * Coerces a `number` or `{ toNumber() }` (protobufjs `Long`) to a finite
+ * safe-integer. Throws on missing/non-numeric/out-of-range inputs.
+ */
 function toSafeNumber(value, field) {
     if (value === null || value === undefined)
         throw new Error(`missing ${field}`);
@@ -63,3 +75,11 @@ function parseOptionalInt(value) {
         return undefined;
     return parseStrictUnsignedInt(value);
 }
+function parseOptionalSignedInt(value) {
+    if (!value)
+        return undefined;
+    if (!SIGNED_DIGITS_RE.test(value))
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}

package/dist/util/runtime.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRuntimeOsDisplayName = getRuntimeOsDisplayName;
 exports.isBunRuntime = isBunRuntime;
+/**
+ * Returns a human-friendly OS name (`Windows` / `Mac OS` / `Linux`) for the
+ * current process, falling back to `process.platform` for other OSes.
+ */
 function getRuntimeOsDisplayName() {
     switch (process.platform) {
         case 'win32':
@@ -14,6 +18,7 @@ function getRuntimeOsDisplayName() {
             return process.platform;
     }
 }
+/** Returns `true` when running under the Bun runtime. */
 function isBunRuntime() {
     return typeof globalThis.Bun !== 'undefined';
 }

package/dist/version-spec.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WA_VERSION = void 0;
+var version_1 = require("../spec/version");
+Object.defineProperty(exports, "WA_VERSION", { enumerable: true, get: function () { return version_1.WA_VERSION; } });

package/package.json

@@ -1,7 +1,9 @@
 {
     "name": "zapo-js",
-    "version": "0.2.0",
+    "version": "1.0.0",
     "description": "High-performance WhatsApp Web TypeScript library",
+    "license": "MIT",
+    "author": "vinikjkkj <contact@vinicius.email> (https://github.com/vinikjkkj)",
     "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/vinikjkkj"
@@ -99,8 +101,15 @@
     },
     "files": [
         "dist",
-        "proto/index.js",
-        "proto/index.d.ts",
+        "spec/proto/index.js",
+        "spec/proto/index.d.ts",
+        "spec/mex/index.js",
+        "spec/mex/index.d.ts",
+        "spec/appstate/index.js",
+        "spec/appstate/index.d.ts",
+        "spec/version/version.json",
+        "spec/version/index.js",
+        "spec/version/index.d.ts",
         "scripts/check-node-version.cjs"
     ],
     "workspaces": [
@@ -111,6 +120,7 @@
     },
     "scripts": {
         "preinstall": "node ./scripts/check-node-version.cjs",
+        "prepack": "npm run build",
         "changeset": "changeset",
         "changeset:status": "changeset status --verbose",
         "version:packages": "changeset version",
@@ -119,7 +129,7 @@
         "build:cjs": "tsc -p tsconfig.build.cjs.json && tsc-alias -p tsconfig.build.cjs.json",
         "build:esm": "tsc -p tsconfig.build.esm.json && tsc-alias -p tsconfig.build.esm.json",
         "build:types": "tsc -p tsconfig.build.types.json && tsc-alias -p tsconfig.build.types.json",
-        "build:esm:finalize": "node ./scripts/finalize-esm-build.cjs",
+        "build:esm:finalize": "node ./scripts/finalize-esm-build.cjs --proto-bridge",
         "build": "npm run clean && npm run build:cjs && npm run build:esm && npm run build:types && npm run build:esm:finalize",
         "build:packages": "turbo run build",
         "proto:generate": "node ./scripts/generate-proto.cjs",
@@ -140,20 +150,23 @@
         "test:coverage": "npm run test:structure && c8 --all --include \"src/**/*.ts\" --exclude \"src/**/*.d.ts\" --exclude \"src/**/__tests__/**\" --exclude \"src/**/types.ts\" --exclude \"src/store/contracts/**/*.ts\" --reporter text --reporter html --reporter lcov node --import tsx --test --test-skip-pattern \"\\\\[flow\\\\]\" \"src/**/__tests__/**/*.test.ts\"",
         "test:coverage:open": "node -e \"require('node:child_process').execSync(process.platform === 'win32' ? 'start coverage\\\\index.html' : process.platform === 'darwin' ? 'open coverage/index.html' : 'xdg-open coverage/index.html', { stdio: 'inherit' })\"",
         "typecheck": "tsc -p tsconfig.json --noEmit",
+        "typecheck:examples": "tsc -p examples/tsconfig.json",
+        "typecheck:bench": "tsc -p bench/tsconfig.json",
         "typecheck:packages": "turbo run typecheck",
+        "typecheck:all": "npm run typecheck && npm run typecheck:examples && npm run typecheck:bench && npm run typecheck:packages",
         "lint": "eslint . --ext .ts,.js,.cjs",
         "lint:fix": "eslint . --ext .ts,.js,.cjs --fix",
         "format": "prettier . --write",
         "format:check": "prettier . --check"
     },
     "peerDependencies": {
-        "got": "14.6.4",
+        "argo-codec": "^0.2.1",
         "pino": "^9.0.0",
         "pino-pretty": "^13.0.0",
-        "ws": "^8.18.3"
+        "ws": "^8.20.1"
     },
     "peerDependenciesMeta": {
-        "got": {
+        "argo-codec": {
             "optional": true
         },
         "pino": {
@@ -171,20 +184,33 @@
         "@types/node": "^22.13.14",
         "@types/ws": "^8.18.1",
         "@typescript-eslint/parser": "^8.56.1",
-        "@vinikjkkj/eslint-config": "^1.0.0",
+        "@vinikjkkj/eslint-config": "1.0.2",
+        "argo-codec": "^0.2.1",
         "better-sqlite3": "^12.6.2",
         "c8": "^11.0.0",
         "eslint": "^9.39.4",
+        "eslint-import-resolver-typescript": "^4.4.4",
         "eslint-plugin-import": "^2.32.0",
-        "got": "14.6.4",
+        "eslint-plugin-n": "^17.24.0",
         "pino": "^10.3.1",
         "pino-pretty": "^13.1.3",
         "prettier": "^3.8.1",
         "tsc-alias": "^1.8.16",
         "tsx": "^4.20.6",
-        "turbo": "^2.8.20",
+        "turbo": "^2.9.14",
         "typescript": "^5.7.3",
         "typescript-eslint": "^8.56.1",
-        "ws": "^8.18.3"
+        "ws": "^8.20.1"
+    },
+    "overrides": {
+        "ws": "^8.20.1",
+        "qs": "6.15.2",
+        "flatted": "^3.4.2",
+        "picomatch@<2.3.2": "2.3.2",
+        "picomatch@4": "^4.0.4",
+        "brace-expansion@1": "1.1.13",
+        "brace-expansion@2": "^2.0.3",
+        "brace-expansion@4": "^4.0.2",
+        "brace-expansion@5": "^5.0.6"
     }
 }

package/spec/appstate/index.d.ts

@@ -0,0 +1,188 @@
+// AUTO-GENERATED — do not edit. Regenerated daily by wa-spec.
+// WhatsApp Version: 2.3000.1040072419
+
+export type WaAppstateCollection = 'regular' | 'regular_low' | 'regular_high' | 'critical_block' | 'critical_unblock_low'
+
+export type WaAppstateScope =
+    | 'account'
+    | 'chat'
+    | 'chatOrContact'
+    | 'message'
+    | 'chatMessageRange'
+
+// Discriminated union — `type` narrows the shape:
+//   - 'literal'    fixed `value` (the action wire name, position 0)
+//   - 'jid'        WhatsApp JID string (`<user>@<domain>`, legacy-encoded)
+//   - 'boolString' '0' or '1' — WA's mutation-index bool encoding
+//   - 'jidOrZero'  participant slot in message scope — JID, or literal '0'
+//                  when fromMe is true or participant is null
+//   - 'enum'       stringified protobuf-enum integer; `protoEnum` is the
+//                  enum's nested path inside SyncActionValue (e.g.
+//                  `SettingsSyncAction.SettingKey`), look it up in
+//                  @vinikjkkj/wa-proto for the value set.
+//   - 'string'     opaque identifier (msg id, label id, agent id, etc.)
+//   - 'unknown'    unrecognised slot (fallback)
+export type WaAppstateIndexPart =
+    | { readonly type: 'literal'; readonly value: string }
+    | { readonly type: 'jid'; readonly name: string }
+    | { readonly type: 'boolString'; readonly name: string }
+    | { readonly type: 'jidOrZero'; readonly name: string }
+    | { readonly type: 'enum'; readonly name: string; readonly protoEnum: string }
+    | { readonly type: 'string'; readonly name: string }
+    | { readonly type: 'unknown'; readonly name: string }
+
+export type WaAppstateValueEnumFields = Readonly<Record<string, string>>
+
+export interface WaAppstateSchema<
+    Name extends string = string,
+    Collection extends WaAppstateCollection = WaAppstateCollection,
+    Scope extends WaAppstateScope = WaAppstateScope,
+    ValueField extends string | null = string | null,
+    ValueProtoType extends string | null = string | null,
+    ValueEnumFields extends WaAppstateValueEnumFields | null = WaAppstateValueEnumFields | null,
+    IndexParts extends ReadonlyArray<WaAppstateIndexPart> = ReadonlyArray<WaAppstateIndexPart>
+> {
+    readonly name: Name
+    readonly collection: Collection
+    readonly version: number
+    readonly scope: Scope
+    readonly valueField: ValueField
+    // Dotted path to the value's protobuf message inside @vinikjkkj/wa-proto's
+    // `waproto` namespace. Nested types under SyncActionValue read as
+    // `SyncActionValue.<X>` (most actions); top-level types (e.g.
+    // `ChatLockSettings`, `DeviceCapabilities`) read as just `<X>`.
+    // Resolve with a `GetByPath`-style helper to obtain the typed value.
+    readonly valueProtoType: ValueProtoType
+    // For every enum-typed field inside the value message, a dotted path to
+    // the enum inside `waproto.SyncActionValue` (e.g. `StatusPrivacyAction.
+    // StatusDistributionMode`). Lets a typed-mutation API surface enum
+    // string literals (`'ALLOW_LIST'`) instead of magic integers (`1`).
+    // `null` when the value message has no enum fields.
+    readonly valueEnumFields: ValueEnumFields
+    readonly indexParts: IndexParts
+}
+
+export declare const WA_APPSTATE_COLLECTIONS: ReadonlyArray<WaAppstateCollection>
+
+export declare const WA_APPSTATE_SCHEMAS: {
+    readonly AdsCtwaPerCustomerDataSharing: WaAppstateSchema<'ctwaPerCustomerDataSharing', 'regular_high', 'account', 'ctwaPerCustomerDataSharingAction', 'SyncActionValue.CtwaPerCustomerDataSharingAction', null, readonly [{ readonly type: 'literal'; readonly value: 'ctwaPerCustomerDataSharing' }, { readonly type: 'string'; readonly name: 'accountLid' }]>
+    readonly Agent: WaAppstateSchema<'deviceAgent', 'regular', 'account', 'agentAction', 'SyncActionValue.AgentAction', null, readonly [{ readonly type: 'literal'; readonly value: 'deviceAgent' }, { readonly type: 'string'; readonly name: 'agentId' }]>
+    readonly AiThreadDelete: WaAppstateSchema<'ai_thread_delete', 'regular_high', 'chat', null, null, null, readonly [{ readonly type: 'literal'; readonly value: 'ai_thread_delete' }, { readonly type: 'jid'; readonly name: 'chatJid' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly AiThreadPin: WaAppstateSchema<'thread_pin', 'regular_low', 'chat', 'threadPinAction', 'SyncActionValue.ThreadPinAction', null, readonly [{ readonly type: 'literal'; readonly value: 'thread_pin' }, { readonly type: 'jid'; readonly name: 'chatJid' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly AiThreadRename: WaAppstateSchema<'ai_thread_rename', 'regular_low', 'chat', 'aiThreadRenameAction', 'SyncActionValue.AiThreadRenameAction', null, readonly [{ readonly type: 'literal'; readonly value: 'ai_thread_rename' }, { readonly type: 'jid'; readonly name: 'chatJid' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly AndroidUnsupportedActions: WaAppstateSchema<'android_unsupported_actions', 'regular_low', 'account', 'androidUnsupportedActions', 'SyncActionValue.AndroidUnsupportedActions', null, readonly [{ readonly type: 'literal'; readonly value: 'android_unsupported_actions' }]>
+    readonly Archive: WaAppstateSchema<'archive', 'regular_low', 'chatMessageRange', 'archiveChatAction', 'SyncActionValue.ArchiveChatAction', null, readonly [{ readonly type: 'literal'; readonly value: 'archive' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly AvatarUpdated: WaAppstateSchema<'avatar_updated_action', 'regular', 'account', 'avatarUpdatedAction', 'SyncActionValue.AvatarUpdatedAction', { readonly 'eventType': 'AvatarUpdatedAction.AvatarEventType' }, readonly [{ readonly type: 'literal'; readonly value: 'avatar_updated_action' }]>
+    readonly BizAiSettingsNudge: WaAppstateSchema<'biz_ai_settings_nudge', 'regular_high', 'account', 'bizAiSettingsNudgeAction', 'SyncActionValue.BizAISettingsNudgeAction', { readonly 'category': 'BizAISettingsNudgeAction.BizAISettingsCategory' }, readonly [{ readonly type: 'literal'; readonly value: 'biz_ai_settings_nudge' }]>
+    readonly BotWelcomeRequest: WaAppstateSchema<'bot_welcome_request', 'regular_low', 'chat', 'botWelcomeRequestAction', 'SyncActionValue.BotWelcomeRequestAction', null, readonly [{ readonly type: 'literal'; readonly value: 'bot_welcome_request' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly BusinessBroadcastCampaign: WaAppstateSchema<'business_broadcast_campaign', 'regular', 'account', 'businessBroadcastCampaignAction', 'SyncActionValue.BusinessBroadcastCampaignAction', { readonly 'status': 'BusinessBroadcastCampaignStatus' }, readonly [{ readonly type: 'literal'; readonly value: 'business_broadcast_campaign' }, { readonly type: 'string'; readonly name: 'campaign' }]>
+    readonly BusinessBroadcastInsights: WaAppstateSchema<'business_broadcast_insights_sync', 'regular', 'account', 'businessBroadcastInsightsAction', 'SyncActionValue.BusinessBroadcastInsightsAction', null, readonly [{ readonly type: 'literal'; readonly value: 'business_broadcast_insights_sync' }, { readonly type: 'string'; readonly name: 'campaign' }]>
+    readonly BusinessBroadcastList: WaAppstateSchema<'business_broadcast_list', 'regular', 'account', 'businessBroadcastListAction', 'SyncActionValue.BusinessBroadcastListAction', null, readonly [{ readonly type: 'literal'; readonly value: 'business_broadcast_list' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly CallLog: WaAppstateSchema<'call_log', 'regular', 'account', 'callLogAction', 'SyncActionValue.CallLogAction', { readonly 'callLogRecord.callResult': 'CallLogRecord.CallResult'; readonly 'callLogRecord.silenceReason': 'CallLogRecord.SilenceReason'; readonly 'callLogRecord.participants.callResult': 'CallLogRecord.CallResult'; readonly 'callLogRecord.callType': 'CallLogRecord.CallType' }, readonly [{ readonly type: 'literal'; readonly value: 'call_log' }]>
+    readonly ChatAssignment: WaAppstateSchema<'agentChatAssignment', 'regular', 'chat', 'chatAssignment', 'SyncActionValue.ChatAssignmentAction', null, readonly [{ readonly type: 'literal'; readonly value: 'agentChatAssignment' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly ChatAssignmentOpenedStatus: WaAppstateSchema<'agentChatAssignmentOpenedStatus', 'regular', 'chat', 'chatAssignmentOpenedStatus', 'SyncActionValue.ChatAssignmentOpenedStatusAction', null, readonly [{ readonly type: 'literal'; readonly value: 'agentChatAssignmentOpenedStatus' }, { readonly type: 'jid'; readonly name: 'chatJid' }, { readonly type: 'string'; readonly name: 'agentId' }]>
+    readonly ChatLockSettings: WaAppstateSchema<'setting_chatLock', 'regular_low', 'account', 'chatLockSettings', 'ChatLockSettings', null, readonly [{ readonly type: 'literal'; readonly value: 'setting_chatLock' }]>
+    readonly ClearChat: WaAppstateSchema<'clearChat', 'regular_high', 'chatMessageRange', 'clearChatAction', 'SyncActionValue.ClearChatAction', null, readonly [{ readonly type: 'literal'; readonly value: 'clearChat' }, { readonly type: 'jid'; readonly name: 'chatJid' }, { readonly type: 'string'; readonly name: 'deleteStarred' }, { readonly type: 'string'; readonly name: 'deleteMedia' }]>
+    readonly Contact: WaAppstateSchema<'contact', 'critical_unblock_low', 'account', 'contactAction', 'SyncActionValue.ContactAction', null, readonly [{ readonly type: 'literal'; readonly value: 'contact' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly CustomPaymentMethods: WaAppstateSchema<'custom_payment_methods', 'regular_low', 'account', 'customPaymentMethodsAction', 'SyncActionValue.CustomPaymentMethodsAction', null, readonly [{ readonly type: 'literal'; readonly value: 'custom_payment_methods' }]>
+    readonly CustomerData: WaAppstateSchema<'customer_data', 'regular_low', 'account', 'customerDataAction', 'SyncActionValue.CustomerDataAction', null, readonly [{ readonly type: 'literal'; readonly value: 'customer_data' }, { readonly type: 'string'; readonly name: 'chatJid' }]>
+    readonly DeleteChat: WaAppstateSchema<'deleteChat', 'regular_high', 'chatMessageRange', 'deleteChatAction', 'SyncActionValue.DeleteChatAction', null, readonly [{ readonly type: 'literal'; readonly value: 'deleteChat' }, { readonly type: 'jid'; readonly name: 'chatJid' }, { readonly type: 'string'; readonly name: 'deleteMedia' }]>
+    readonly DeleteMessageForMe: WaAppstateSchema<'deleteMessageForMe', 'regular_high', 'message', 'deleteMessageForMeAction', 'SyncActionValue.DeleteMessageForMeAction', null, readonly [{ readonly type: 'literal'; readonly value: 'deleteMessageForMe' }, { readonly type: 'jid'; readonly name: 'remote' }, { readonly type: 'string'; readonly name: 'id' }, { readonly type: 'boolString'; readonly name: 'fromMe' }, { readonly type: 'jidOrZero'; readonly name: 'participant' }]>
+    readonly DetectedOutcomeStatus: WaAppstateSchema<'detected_outcomes_status_action', 'regular', 'account', 'detectedOutcomesStatusAction', 'SyncActionValue.DetectedOutcomesStatusAction', null, readonly [{ readonly type: 'literal'; readonly value: 'detected_outcomes_status_action' }]>
+    readonly DeviceCapabilities: WaAppstateSchema<'device_capabilities', 'regular_low', 'account', 'deviceCapabilities', 'DeviceCapabilities', null, readonly [{ readonly type: 'literal'; readonly value: 'device_capabilities' }]>
+    readonly DisableLinkPreviews: WaAppstateSchema<'setting_disableLinkPreviews', 'regular', 'account', 'privacySettingDisableLinkPreviewsAction', 'SyncActionValue.PrivacySettingDisableLinkPreviewsAction', null, readonly [{ readonly type: 'literal'; readonly value: 'setting_disableLinkPreviews' }]>
+    readonly ExternalWebBeta: WaAppstateSchema<'external_web_beta', 'regular', 'account', 'externalWebBetaAction', 'SyncActionValue.ExternalWebBetaAction', null, readonly [{ readonly type: 'literal'; readonly value: 'external_web_beta' }]>
+    readonly FavoriteSticker: WaAppstateSchema<'favoriteSticker', 'regular_low', 'account', 'stickerAction', 'SyncActionValue.StickerAction', null, readonly [{ readonly type: 'literal'; readonly value: 'favoriteSticker' }, { readonly type: 'string'; readonly name: 'filehash' }]>
+    readonly Favorites: WaAppstateSchema<'favorites', 'regular_high', 'account', 'favoritesAction', 'SyncActionValue.FavoritesAction', null, readonly [{ readonly type: 'literal'; readonly value: 'favorites' }]>
+    readonly InteractiveMessageAction: WaAppstateSchema<'interactive_message_action', 'regular_low', 'message', 'interactiveMessageAction', 'SyncActionValue.InteractiveMessageAction', { readonly 'type': 'InteractiveMessageAction.InteractiveMessageActionMode' }, readonly [{ readonly type: 'literal'; readonly value: 'interactive_message_action' }, { readonly type: 'jid'; readonly name: 'remote' }, { readonly type: 'string'; readonly name: 'id' }, { readonly type: 'boolString'; readonly name: 'fromMe' }, { readonly type: 'jidOrZero'; readonly name: 'participant' }, { readonly type: 'string'; readonly name: 'arg5' }]>
+    readonly LabelEdit: WaAppstateSchema<'label_edit', 'regular', 'account', 'labelEditAction', 'SyncActionValue.LabelEditAction', { readonly 'type': 'LabelEditAction.ListType' }, readonly [{ readonly type: 'literal'; readonly value: 'label_edit' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly LabelJid: WaAppstateSchema<'label_jid', 'regular', 'chatOrContact', 'labelAssociationAction', 'SyncActionValue.LabelAssociationAction', null, readonly [{ readonly type: 'literal'; readonly value: 'label_jid' }, { readonly type: 'string'; readonly name: 'labelId' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly LabelReordering: WaAppstateSchema<'label_reordering', 'regular', 'account', 'labelReorderingAction', 'SyncActionValue.LabelReorderingAction', null, readonly [{ readonly type: 'literal'; readonly value: 'label_reordering' }]>
+    readonly LidContact: WaAppstateSchema<'lid_contact', 'critical_unblock_low', 'account', 'lidContactAction', 'SyncActionValue.LidContactAction', null, readonly [{ readonly type: 'literal'; readonly value: 'lid_contact' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly LocaleSetting: WaAppstateSchema<'setting_locale', 'critical_block', 'account', 'localeSetting', 'SyncActionValue.LocaleSetting', null, readonly [{ readonly type: 'literal'; readonly value: 'setting_locale' }]>
+    readonly LockChat: WaAppstateSchema<'lock', 'regular_low', 'chat', 'lockChatAction', 'SyncActionValue.LockChatAction', null, readonly [{ readonly type: 'literal'; readonly value: 'lock' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly MarkChatAsRead: WaAppstateSchema<'markChatAsRead', 'regular_low', 'chatMessageRange', 'markChatAsReadAction', 'SyncActionValue.MarkChatAsReadAction', null, readonly [{ readonly type: 'literal'; readonly value: 'markChatAsRead' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly MarketingMessage: WaAppstateSchema<'marketingMessage', 'regular', 'account', 'marketingMessageAction', 'SyncActionValue.MarketingMessageAction', { readonly 'type': 'MarketingMessageAction.MarketingMessagePrototypeType' }, readonly [{ readonly type: 'literal'; readonly value: 'marketingMessage' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly MarketingMessageBroadcast: WaAppstateSchema<'marketingMessageBroadcast', 'regular', 'account', null, null, null, readonly [{ readonly type: 'literal'; readonly value: 'marketingMessageBroadcast' }, { readonly type: 'string'; readonly name: 'premiumMessageId' }, { readonly type: 'string'; readonly name: 'messageId' }]>
+    readonly MerchantPaymentPartner: WaAppstateSchema<'merchant_payment_partner', 'regular_low', 'account', 'merchantPaymentPartnerAction', 'SyncActionValue.MerchantPaymentPartnerAction', { readonly 'status': 'MerchantPaymentPartnerAction.Status' }, readonly [{ readonly type: 'literal'; readonly value: 'merchant_payment_partner' }]>
+    readonly Mute: WaAppstateSchema<'mute', 'regular_high', 'chat', 'muteAction', 'SyncActionValue.MuteAction', null, readonly [{ readonly type: 'literal'; readonly value: 'mute' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly NctSaltSync: WaAppstateSchema<'nct_salt_sync', 'regular_high', 'account', 'nctSaltSyncAction', 'SyncActionValue.NctSaltSyncAction', null, readonly [{ readonly type: 'literal'; readonly value: 'nct_salt_sync' }]>
+    readonly NoteEdit: WaAppstateSchema<'note_edit', 'regular_low', 'account', 'noteEditAction', 'SyncActionValue.NoteEditAction', { readonly 'type': 'NoteEditAction.NoteType' }, readonly [{ readonly type: 'literal'; readonly value: 'note_edit' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly Nux: WaAppstateSchema<'nux', 'regular_low', 'account', 'nuxAction', 'SyncActionValue.NuxAction', null, readonly [{ readonly type: 'literal'; readonly value: 'nux' }, { readonly type: 'string'; readonly name: 'nuxKey' }]>
+    readonly OutContact: WaAppstateSchema<'out_contact', 'regular_low', 'account', 'outContactAction', 'SyncActionValue.OutContactAction', null, readonly [{ readonly type: 'literal'; readonly value: 'out_contact' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly PaymentInfo: WaAppstateSchema<'payment_info', 'regular_low', 'account', 'paymentInfoAction', 'SyncActionValue.PaymentInfoAction', null, readonly [{ readonly type: 'literal'; readonly value: 'payment_info' }]>
+    readonly PaymentTos: WaAppstateSchema<'payment_tos', 'regular_low', 'account', 'paymentTosAction', 'SyncActionValue.PaymentTosAction', { readonly 'paymentNotice': 'PaymentTosAction.PaymentNotice' }, readonly [{ readonly type: 'literal'; readonly value: 'payment_tos' }]>
+    readonly Pin: WaAppstateSchema<'pin_v1', 'regular_low', 'chat', 'pinAction', 'SyncActionValue.PinAction', null, readonly [{ readonly type: 'literal'; readonly value: 'pin_v1' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly PnForLidChat: WaAppstateSchema<'pnForLidChat', 'regular', 'account', 'pnForLidChatAction', 'SyncActionValue.PnForLidChatAction', null, readonly [{ readonly type: 'literal'; readonly value: 'pnForLidChat' }, { readonly type: 'string'; readonly name: 'lid' }]>
+    readonly PrimaryFeature: WaAppstateSchema<'primary_feature', 'regular', 'account', 'primaryFeature', 'SyncActionValue.PrimaryFeature', null, readonly [{ readonly type: 'literal'; readonly value: 'primary_feature' }]>
+    readonly PrimaryVersion: WaAppstateSchema<'primary_version', 'regular_low', 'account', 'primaryVersionAction', 'SyncActionValue.PrimaryVersionAction', null, readonly [{ readonly type: 'literal'; readonly value: 'primary_version' }, { readonly type: 'string'; readonly name: 'key1' }]>
+    readonly QuickReply: WaAppstateSchema<'quick_reply', 'regular', 'account', 'quickReplyAction', 'SyncActionValue.QuickReplyAction', null, readonly [{ readonly type: 'literal'; readonly value: 'quick_reply' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly RemoveRecentSticker: WaAppstateSchema<'removeRecentSticker', 'regular_low', 'account', 'removeRecentStickerAction', 'SyncActionValue.RemoveRecentStickerAction', null, readonly [{ readonly type: 'literal'; readonly value: 'removeRecentSticker' }, { readonly type: 'string'; readonly name: 'filehash' }]>
+    readonly Sentinel: WaAppstateSchema<'sentinel', 'regular_low', 'account', 'keyExpiration', 'SyncActionValue.KeyExpiration', null, readonly [{ readonly type: 'literal'; readonly value: 'sentinel' }]>
+    readonly SettingPushName: WaAppstateSchema<'setting_pushName', 'critical_block', 'account', 'pushNameSetting', 'SyncActionValue.PushNameSetting', null, readonly [{ readonly type: 'literal'; readonly value: 'setting_pushName' }]>
+    readonly SettingsSync: WaAppstateSchema<'settings_sync', 'regular_low', 'account', 'settingsSyncAction', 'SyncActionValue.SettingsSyncAction', { readonly 'bannerNotificationDisplayMode': 'SettingsSyncAction.DisplayMode'; readonly 'unreadCounterBadgeDisplayMode': 'SettingsSyncAction.DisplayMode'; readonly 'mediaUploadQuality': 'SettingsSyncAction.MediaQualitySetting' }, readonly [{ readonly type: 'literal'; readonly value: 'settings_sync' }, { readonly type: 'enum'; readonly name: 'settingPlatform'; readonly protoEnum: 'SettingsSyncAction.SettingPlatform' }, { readonly type: 'enum'; readonly name: 'settingKey'; readonly protoEnum: 'SettingsSyncAction.SettingKey' }, { readonly type: 'jid'; readonly name: 'chatJid' }]>
+    readonly ShareOwnPn: WaAppstateSchema<'shareOwnPn', 'regular', 'account', null, null, null, readonly [{ readonly type: 'literal'; readonly value: 'shareOwnPn' }, { readonly type: 'string'; readonly name: 'lid' }]>
+    readonly Star: WaAppstateSchema<'star', 'regular_high', 'message', 'starAction', 'SyncActionValue.StarAction', null, readonly [{ readonly type: 'literal'; readonly value: 'star' }, { readonly type: 'jid'; readonly name: 'remote' }, { readonly type: 'string'; readonly name: 'id' }, { readonly type: 'boolString'; readonly name: 'fromMe' }, { readonly type: 'jidOrZero'; readonly name: 'participant' }]>
+    readonly StatusPrivacy: WaAppstateSchema<'status_privacy', 'regular_high', 'account', 'statusPrivacy', 'SyncActionValue.StatusPrivacyAction', { readonly 'mode': 'StatusPrivacyAction.StatusDistributionMode'; readonly 'modes': 'StatusPrivacyAction.StatusDistributionMode' }, readonly [{ readonly type: 'literal'; readonly value: 'status_privacy' }]>
+    readonly SubscriptionsSyncV2: WaAppstateSchema<'subscriptions_sync_v2', 'regular', 'account', 'subscriptionsSyncV2Action', 'SyncActionValue.SubscriptionsSyncV2Action', null, readonly [{ readonly type: 'literal'; readonly value: 'subscriptions_sync_v2' }]>
+    readonly TimeFormat: WaAppstateSchema<'time_format', 'regular_low', 'account', 'timeFormatAction', 'SyncActionValue.TimeFormatAction', null, readonly [{ readonly type: 'literal'; readonly value: 'time_format' }]>
+    readonly UnarchiveChatsSetting: WaAppstateSchema<'setting_unarchiveChats', 'regular_low', 'account', 'unarchiveChatsSetting', 'SyncActionValue.UnarchiveChatsSetting', null, readonly [{ readonly type: 'literal'; readonly value: 'setting_unarchiveChats' }]>
+    readonly UserStatusMute: WaAppstateSchema<'userStatusMute', 'regular_high', 'account', 'userStatusMuteAction', 'SyncActionValue.UserStatusMuteAction', null, readonly [{ readonly type: 'literal'; readonly value: 'userStatusMute' }, { readonly type: 'string'; readonly name: 'id' }]>
+    readonly VoipRelayAllCalls: WaAppstateSchema<'setting_relayAllCalls', 'regular', 'account', 'privacySettingRelayAllCalls', 'SyncActionValue.PrivacySettingRelayAllCalls', null, readonly [{ readonly type: 'literal'; readonly value: 'setting_relayAllCalls' }]>
+    readonly WaffleAccountLinkState: WaAppstateSchema<'waffle_account_link_state', 'regular_high', 'account', 'waffleAccountLinkStateAction', 'SyncActionValue.WaffleAccountLinkStateAction', { readonly 'linkState': 'WaffleAccountLinkStateAction.AccountLinkState' }, readonly [{ readonly type: 'literal'; readonly value: 'waffle_account_link_state' }]>
+}
+
+export type WaAppstateActionKey = keyof typeof WA_APPSTATE_SCHEMAS
+
+// --- Derived helpers ------------------------------------------------------
+
+// Turn a schema's `indexParts` tuple into the runtime value tuple — the
+// array you'd `JSON.stringify` to produce the wire-level index string.
+// Literals are pinned to their constant value; boolString slots widen to
+// '0' | '1' (WA encodes mutation-index booleans this way — see
+// WAWebSyncdUtils.constructMsgKeySegments). The wire format on the bus
+// is `JSON.stringify(WaAppstateIndexValueOf<S>)`.
+//
+//   WaAppstateIndexValueOf<typeof WA_APPSTATE_SCHEMAS.Mute>
+//     → readonly ['mute', string]
+//   WaAppstateIndexValueOf<typeof WA_APPSTATE_SCHEMAS.Star>
+//     → readonly ['star', string, string, '0' | '1', string]
+export type WaAppstateIndexValueOf<S> = S extends {
+    indexParts: infer P extends ReadonlyArray<WaAppstateIndexPart>
+}
+    ? {
+          readonly [K in keyof P]: P[K] extends { type: 'literal'; value: infer V }
+              ? V
+              : P[K] extends { type: 'boolString' }
+                ? '0' | '1'
+                : string
+      }
+    : never
+
+// Turn a schema's `indexParts` tuple into the keyword args object — what
+// a typed builder would accept. Literal slots are auto-filled by the
+// builder and dropped from the args; non-literals contribute their `name`.
+// boolString slots take a JS boolean (encoder writes '0'/'1'); jidOrZero
+// slots take `string | null` (encoder writes '0' when null or when
+// fromMe is true).
+//
+//   WaAppstateIndexArgs<'Mute'>  → { readonly chatJid: string }
+//   WaAppstateIndexArgs<'Star'>  → {
+//       readonly remote: string
+//       readonly id: string
+//       readonly fromMe: boolean
+//       readonly participant: string | null
+//   }
+export type WaAppstateIndexArgs<K extends WaAppstateActionKey> = {
+    readonly [Part in (typeof WA_APPSTATE_SCHEMAS)[K]['indexParts'][number] as Part extends {
+        type: 'literal'
+    }
+        ? never
+        : Part extends { name: infer N extends string }
+          ? N
+          : never]: Part extends { type: 'boolString' }
+        ? boolean
+        : Part extends { type: 'jidOrZero' }
+          ? string | null
+          : string
+}