@oxidezap/baileyrs 0.1.0 → 0.1.2

package/README.md

@@ -220,6 +220,76 @@ A few behaviors that differ from upstream — almost always to your advantage:
   `(err as Boom).output.statusCode` pattern works unchanged. If your
   `package.json` was pulling `@hapi/boom` only for baileys, you can drop
   the dependency.
+- **Your key store also holds bridge state, so "empty" is not "unpaired".**
+  See [Bridge state in your key store](#bridge-state-in-your-key-store) — this
+  one can break a boot path, so it has its own section.
+
+### Bridge state in your key store
+
+Upstream Baileys keeps engine state in `creds` (persisted by `saveCreds`) and
+puts only Signal key material in `keys`. baileyrs uses that same `keys` store
+as the persistence channel for the Rust core's own state as well: its device
+record, and the byte-level records the Signal namespaces are projected from.
+Those live under namespaces reserved with the **`bridge-` prefix**:
+
+| namespace | what it holds |
+| --- | --- |
+| `bridge-native-*` | the core's own encoding of a namespace that also has a Baileys projection (`bridge-native-session`, `bridge-native-prekey`, `bridge-native-device`, …) |
+| `bridge-*` | core records with no Baileys equivalent (`bridge-signed-prekey`, `bridge-sent-message`, `bridge-msg-secret`, `bridge-meta`, …) |
+
+No upstream Baileys namespace starts with `bridge-`, and none of your data is
+stored under one. Which of them you actually see depends on what the engine
+touches; `bridge-native-device` shows up first, because the core reads its
+device record while the socket is still `connecting` — **before any QR, before
+any pairing**.
+
+That last point is the one that bites. A store that counted rows to decide
+whether this was a first run reports a session that does not exist:
+
+```js
+// WRONG on baileyrs: bridge-native-device is already in the table before pairing,
+// so this never reports empty again — the bot skips its pairing flow and hangs.
+const isEmpty = () => !creds.registered && !creds.me?.id && countKeys() === 0
+
+// Right, on baileyrs and upstream alike: creds are the pairing record.
+const isEmpty = () => !creds.registered && !creds.me?.id
+```
+
+**A non-empty key store is not evidence of a session.** `creds.registered` and
+`creds.me?.id` are, and they are the only thing to check.
+
+When you need to present a store the way upstream would — counting rows,
+listing the Signal namespaces, exporting an upstream-shaped dump — filter the
+bridge rows out with the exported classifier rather than matching the prefix
+yourself. It is derived from the internal routing catalog, so a namespace added
+in a later release is covered without you changing anything:
+
+```ts
+// Aliased install? Import from '@whiskeysockets/baileys' instead; it resolves here.
+import { BRIDGE_INTERNAL_KEY_TYPES, isBridgeInternalKeyType } from '@oxidezap/baileyrs'
+
+isBridgeInternalKeyType('bridge-native-device') // true
+isBridgeInternalKeyType('pre-key')              // false
+
+// Every bridge-internal namespace, e.g. for a SQL `NOT IN (...)` clause. The
+// store also holds the Baileys namespaces the engine projects into it.
+BRIDGE_INTERNAL_KEY_TYPES
+```
+
+> **Do not drop these rows from a backup or a store-to-store move.** They are
+> effective state, not metadata. `bridge-signed-prekey`, `bridge-sender-key-devices`,
+> `bridge-base-key`, `bridge-sent-message`, `bridge-msg-secret`,
+> `bridge-mutation-mac` and `bridge-meta` have no Baileys projection at all, and
+> a Signal session that turned native-only lives under `bridge-native-session`
+> alone. Restoring only the non-bridge rows rolls those sessions back or loses
+> the state outright. Filter the bridge rows only where the destination is an
+> upstream-shaped view that cannot represent them; a full backup, or a move
+> between two baileyrs stores, carries every `bridge-` row across.
+
+This applies to stores you own — the upstream `{ creds, keys }` shape that
+baileyrs auto-wraps, including `useLegacyMultiFileAuthState`. It does not apply
+to `useMultiFileAuthState`, whose `keys` is a projection over the engine's own
+store; the `bridge-` namespaces never surface through it.
 
 ## Disclaimer
 

package/lib/Compatibility/legacy-store/namespaces.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Namespace prefix reserved for bridge-internal state. Every namespace the
+ * routing catalog writes back to a legacy key store starts with it, and no
+ * Baileys Signal namespace does, so the prefix is treated as reserved: a
+ * namespace added to the catalog later is classified without a code change.
+ */
+export declare const BRIDGE_INTERNAL_KEY_PREFIX = "bridge-";
+/**
+ * Every namespace `wrapLegacyStore` can write that is not a Signal key.
+ * Derived from the routing catalog so it cannot drift from what is written.
+ */
+export declare const BRIDGE_INTERNAL_KEY_TYPES: readonly string[];
+/**
+ * Whether a `SignalKeyStore` namespace holds bridge-internal state rather than
+ * Signal key material. Custom stores use it to skip those rows when they
+ * enumerate, count or migrate. Never throws: anything that is not a known
+ * namespace, including a non-string, is reported as not internal.
+ */
+export declare function isBridgeInternalKeyType(type: unknown): boolean;
+//# sourceMappingURL=namespaces.d.ts.map

package/lib/Compatibility/legacy-store/namespaces.js

@@ -0,0 +1,27 @@
+// Public classifier for the namespaces the bridge parks in a consumer's key store.
+import { StoreCatalog } from './constants.js';
+/**
+ * Namespace prefix reserved for bridge-internal state. Every namespace the
+ * routing catalog writes back to a legacy key store starts with it, and no
+ * Baileys Signal namespace does, so the prefix is treated as reserved: a
+ * namespace added to the catalog later is classified without a code change.
+ */
+export const BRIDGE_INTERNAL_KEY_PREFIX = 'bridge-';
+/**
+ * Every namespace `wrapLegacyStore` can write that is not a Signal key.
+ * Derived from the routing catalog so it cannot drift from what is written.
+ */
+export const BRIDGE_INTERNAL_KEY_TYPES = Object.freeze([...new Set(Object.values(StoreCatalog).map(route => route.nativeType))].toSorted());
+const internalTypes = new Set(BRIDGE_INTERNAL_KEY_TYPES);
+/**
+ * Whether a `SignalKeyStore` namespace holds bridge-internal state rather than
+ * Signal key material. Custom stores use it to skip those rows when they
+ * enumerate, count or migrate. Never throws: anything that is not a known
+ * namespace, including a non-string, is reported as not internal.
+ */
+export function isBridgeInternalKeyType(type) {
+    if (typeof type !== 'string' || type.length === 0)
+        return false;
+    return type.startsWith(BRIDGE_INTERNAL_KEY_PREFIX) || internalTypes.has(type);
+}
+//# sourceMappingURL=namespaces.js.map

package/lib/Compatibility/legacy-store/routing.js

@@ -48,16 +48,21 @@ function legacySignalAddress(address) {
         : `${parsed.user}${SignalAddressSyntax.DOMAIN_TYPE}${parsed.domainType}`;
     return `${user}${SignalAddressSyntax.SIGNAL_DEVICE}${parsed.device}`;
 }
+/** A sender key is `<chatJid>:<signalAddress>`, and the chat is a group, status
+ *  or a broadcast list. Which chats fan out through sender keys is the core's
+ *  namespace, so the boundary validates the JID shape, not the domain. No JID
+ *  carries whitespace or a control character, and letting one through would
+ *  mint a storage key that no later lookup can match. */
+const CHAT_JID = /^[^\s:@\p{Cc}]+@[^\s:@\p{Cc}]+$/u;
 function legacySenderKey(key) {
-    const groupTerminator = `${SignalAddressSyntax.DOMAIN}${SignalDomain.GROUP}${SignalAddressSyntax.JID_DEVICE}`;
-    const groupEnd = key.indexOf(groupTerminator);
-    if (groupEnd < 0)
+    const chatDomain = key.indexOf(SignalAddressSyntax.DOMAIN);
+    const chatEnd = chatDomain < 0 ? -1 : key.indexOf(SignalAddressSyntax.JID_DEVICE, chatDomain);
+    const chat = chatEnd < 0 ? '' : key.slice(0, chatEnd);
+    if (!CHAT_JID.test(chat))
         throw new TypeError(`invalid native sender-key address: ${key}`);
-    const addressStart = groupEnd + groupTerminator.length;
-    const group = key.slice(0, addressStart - SignalAddressSyntax.JID_DEVICE.length);
-    const address = legacySignalAddress(key.slice(addressStart));
+    const address = legacySignalAddress(key.slice(chatEnd + SignalAddressSyntax.JID_DEVICE.length));
     const deviceSeparator = address.lastIndexOf(SignalAddressSyntax.SIGNAL_DEVICE);
-    return [group, address.slice(0, deviceSeparator), address.slice(deviceSeparator + 1)].join(SignalAddressSyntax.SENDER_KEY_PART);
+    return [chat, address.slice(0, deviceSeparator), address.slice(deviceSeparator + 1)].join(SignalAddressSyntax.SENDER_KEY_PART);
 }
 const passthroughKey = (_store, key) => key;
 const keyTranslators = Object.freeze({
@@ -114,7 +119,7 @@ function nativeSignalAddress(address) {
 }
 function nativeSenderKey(key) {
     const parts = key.split(SignalAddressSyntax.SENDER_KEY_PART);
-    if (parts.length !== 3 || !parts[0] || !parts[1] || !parts[2]) {
+    if (parts.length !== 3 || !CHAT_JID.test(parts[0]) || !parts[1] || !parts[2]) {
         throw new TypeError(`invalid legacy sender-key address: ${key}`);
     }
     return `${parts[0]}${SignalAddressSyntax.JID_DEVICE}${nativeSignalAddress(`${parts[1]}.${parts[2]}`)}`;

package/lib/Compatibility/newsletter-results.d.ts

@@ -0,0 +1,15 @@
+import type { NewsletterMetadataResult } from '@oxidezap/whatsapp-rust-bridge';
+import type { NewsletterMetadata, NewsletterViewRole } from '../Types/Newsletter.js';
+/** Upstream's `NewsletterViewRole`, or undefined for a role it does not name. */
+export declare const bridgeNewsletterRoleToBaileys: (role: string | undefined) => NewsletterViewRole | undefined;
+/**
+ * Neutral newsletter metadata in upstream's shape.
+ *
+ * Four upstream fields have no source in the bridge result and stay absent
+ * rather than being invented: `owner` (the result carries the viewer's role,
+ * not the owner's jid), `mute_state` (the result's `state` is the newsletter's
+ * lifecycle, Active/Suspended, not a mute), `reaction_codes`, and
+ * `thread_metadata`.
+ */
+export declare const bridgeNewsletterMetadataToBaileys: (result: NewsletterMetadataResult) => NewsletterMetadata;
+//# sourceMappingURL=newsletter-results.d.ts.map

package/lib/Compatibility/newsletter-results.js

@@ -0,0 +1,38 @@
+/**
+ * The bridge spells these the way the core's enums are named, and upstream
+ * spells them in screaming case. Written out rather than upper-cased blindly so
+ * a variant the core adds later shows up as `undefined` instead of as a string
+ * nobody declared.
+ */
+const VERIFICATION = {
+    Verified: 'VERIFIED',
+    Unverified: 'UNVERIFIED'
+};
+const VIEW_ROLE = {
+    Owner: 'OWNER',
+    Admin: 'ADMIN',
+    Subscriber: 'SUBSCRIBER',
+    Guest: 'GUEST'
+};
+/** Upstream's `NewsletterViewRole`, or undefined for a role it does not name. */
+export const bridgeNewsletterRoleToBaileys = (role) => role === undefined ? undefined : VIEW_ROLE[role];
+/**
+ * Neutral newsletter metadata in upstream's shape.
+ *
+ * Four upstream fields have no source in the bridge result and stay absent
+ * rather than being invented: `owner` (the result carries the viewer's role,
+ * not the owner's jid), `mute_state` (the result's `state` is the newsletter's
+ * lifecycle, Active/Suspended, not a mute), `reaction_codes`, and
+ * `thread_metadata`.
+ */
+export const bridgeNewsletterMetadataToBaileys = (result) => ({
+    id: result.jid,
+    name: result.name,
+    ...(result.description !== undefined ? { description: result.description } : {}),
+    ...(result.inviteCode !== undefined ? { invite: result.inviteCode } : {}),
+    ...(result.creationTime !== undefined ? { creation_time: result.creationTime } : {}),
+    subscribers: result.subscriberCount,
+    ...(VERIFICATION[result.verification] !== undefined ? { verification: VERIFICATION[result.verification] } : {}),
+    ...(result.pictureUrl !== undefined ? { picture: { url: result.pictureUrl } } : {})
+});
+//# sourceMappingURL=newsletter-results.js.map

package/lib/Socket/business.d.ts

@@ -0,0 +1,29 @@
+import type { OrderResult } from '@oxidezap/whatsapp-rust-bridge';
+import type { CatalogPage, CollectionsPage, GetCatalogOptions, ProductCreate, ProductUpdate } from '../Types/Product.js';
+import type { UpdateBussinesProfileProps } from '../Types/Bussines.js';
+import type { WAMediaUpload } from '../Types/Message.js';
+import type { SocketContext } from './types.js';
+export declare const makeBusinessMethods: (ctx: SocketContext) => {
+    getCatalog: ({ jid, limit, cursor }: GetCatalogOptions) => Promise<CatalogPage>;
+    getCollections: (jid?: string, limit?: number) => Promise<CollectionsPage>;
+    /**
+     * `sellerJid` is not in upstream's signature because upstream reads orders
+     * over the legacy `fb:thrift_iq` route, which addresses the server. The
+     * route the real client uses is a MEX query keyed by the seller, so the JID
+     * is required here. It is on the order message the token came from.
+     */
+    getOrderDetails: (orderId: string, tokenBase64: string, sellerJid?: string) => Promise<OrderResult>;
+    updateBussinesProfile: (args: UpdateBussinesProfileProps) => Promise<void>;
+    /**
+     * Declared but not callable end to end. The core and the bridge take the
+     * `{fbid, meta_hmac, ts}` receipt of a cover photo upload, and this
+     * package's upload path cannot produce one: it requires a url and a
+     * direct path, which that endpoint does not return.
+     */
+    updateCoverPhoto: (photo: WAMediaUpload) => Promise<never>;
+    removeCoverPhoto: (id: string) => Promise<void>;
+    productCreate: (create: ProductCreate) => Promise<never>;
+    productUpdate: (productId: string, update: ProductUpdate) => Promise<never>;
+    productDelete: (productIds: string[]) => Promise<never>;
+};
+//# sourceMappingURL=business.d.ts.map

package/lib/Socket/business.js

@@ -0,0 +1,104 @@
+import { Boom } from '../Utils/boom.js';
+import { jidNormalizedUser } from '../WABinary/jid-utils.js';
+/**
+ * Product create, update and delete exist only in Baileys: the operations they
+ * send appear in no WhatsApp Web bundle. Declared so a migrating caller reads
+ * why instead of a bare TypeError, and rejecting because there is nothing to
+ * call.
+ */
+const noProductWriteRoute = (method, ...ignored) => {
+    void ignored;
+    throw new Boom(`${method} is not supported: the WhatsApp Web client has no product create, edit or delete operation, so there is nothing for this to call. Manage the catalog from the WhatsApp Business app.`, { statusCode: 501 });
+};
+/**
+ * Upstream types these as strings, so an empty one is reachable from an
+ * unfilled form. `Number('')` is midnight, which would quietly rewrite the
+ * schedule instead of being refused.
+ */
+const minutesPastMidnight = (value, which) => {
+    const minutes = Number(value);
+    if (value.trim() === '' || !Number.isInteger(minutes) || minutes < 0 || minutes > 1440) {
+        throw new Boom(`updateBussinesProfile: ${which} time '${value}' is not a count of minutes past midnight`, {
+            statusCode: 400
+        });
+    }
+    return minutes;
+};
+/**
+ * Both catalog reads take an optional jid and mean "mine" without one, as
+ * upstream does. `getMe` rather than `getUser`, because it reads through to the
+ * persisted credentials, which is the same place upstream reads from and is
+ * populated before the socket finishes its own initialisation.
+ */
+const catalogSubject = (method, ctx, jid) => {
+    const subject = jidNormalizedUser(jid || ctx.getMe()?.id);
+    if (!subject) {
+        throw new Boom(`${method}: no jid was given and there is no authenticated account, so there is no own catalog to read`, {
+            statusCode: 400
+        });
+    }
+    return subject;
+};
+export const makeBusinessMethods = (ctx) => ({
+    getCatalog: async ({ jid, limit, cursor }) => {
+        const subject = catalogSubject('getCatalog', ctx, jid);
+        return await (await ctx.getClient()).getCatalog(subject, { limit, after: cursor });
+    },
+    getCollections: async (jid, limit) => {
+        const subject = catalogSubject('getCollections', ctx, jid);
+        return await (await ctx.getClient()).getCollections(subject, { collectionLimit: limit });
+    },
+    /**
+     * `sellerJid` is not in upstream's signature because upstream reads orders
+     * over the legacy `fb:thrift_iq` route, which addresses the server. The
+     * route the real client uses is a MEX query keyed by the seller, so the JID
+     * is required here. It is on the order message the token came from.
+     */
+    getOrderDetails: async (orderId, tokenBase64, sellerJid) => {
+        if (!sellerJid) {
+            throw new Boom('getOrderDetails: a third argument with the seller jid is required, because orders are read through a query keyed by the business rather than the legacy server-addressed one', { statusCode: 400 });
+        }
+        return await (await ctx.getClient()).getOrder(sellerJid, orderId, tokenBase64);
+    },
+    updateBussinesProfile: async (args) => {
+        const update = {
+            address: args.address,
+            description: args.description,
+            email: args.email,
+            websites: args.websites,
+            ...(args.hours !== undefined
+                ? {
+                    businessHours: {
+                        timezone: args.hours.timezone,
+                        // Minutes past midnight as a number; upstream types the two
+                        // as strings and the core rejects them on the other modes.
+                        config: args.hours.days.map(day => ({
+                            dayOfWeek: day.day,
+                            mode: day.mode,
+                            openTime: day.mode === 'specific_hours' ? minutesPastMidnight(day.openTimeInMinutes, 'open') : undefined,
+                            closeTime: day.mode === 'specific_hours' ? minutesPastMidnight(day.closeTimeInMinutes, 'close') : undefined
+                        }))
+                    }
+                }
+                : {})
+        };
+        await (await ctx.getClient()).updateBusinessProfile(update);
+    },
+    /**
+     * Declared but not callable end to end. The core and the bridge take the
+     * `{fbid, meta_hmac, ts}` receipt of a cover photo upload, and this
+     * package's upload path cannot produce one: it requires a url and a
+     * direct path, which that endpoint does not return.
+     */
+    updateCoverPhoto: async (photo) => {
+        void photo;
+        throw new Boom('updateCoverPhoto is not available yet: the cover photo upload returns an {fbid, meta_hmac, ts} receipt that this package cannot obtain. removeCoverPhoto works.', { statusCode: 501 });
+    },
+    removeCoverPhoto: async (id) => {
+        await (await ctx.getClient()).removeBusinessCoverPhoto(id);
+    },
+    productCreate: async (create) => noProductWriteRoute('productCreate', create),
+    productUpdate: async (productId, update) => noProductWriteRoute('productUpdate', productId, update),
+    productDelete: async (productIds) => noProductWriteRoute('productDelete', productIds)
+});
+//# sourceMappingURL=business.js.map

package/lib/Socket/chat-actions.d.ts

@@ -1,4 +1,7 @@
-import type { ChatModification, WAPatchName } from '../Types/index.js';
+import type { proto } from '../WAProto/runtime.js';
+import type { QuickReplyAction } from '../Types/Bussines.js';
+import type { LabelActionBody } from '../Types/Label.js';
+import type { ChatModification } from '../Types/index.js';
 import type { SocketContext } from './types.js';
 export declare const makeChatActionMethods: (ctx: SocketContext) => {
     pinChat: (jid: string, pin: boolean) => Promise<void>;
@@ -9,17 +12,23 @@ export declare const makeChatActionMethods: (ctx: SocketContext) => {
      * Compatibility wrapper for original Baileys chatModify API.
      * Routes to the appropriate bridge method based on the modification type.
      *
-     * Fully supported: archive, pin, mute, star, markRead, delete, deleteForMe, pushNameSetting, contact, clear
-     * Not yet in bridge (app-state patches): disableLinkPreviews, labels, quickReply
+     * Every variant either runs or throws. A variant that resolved without
+     * doing anything told the caller their chat was labelled when nothing was
+     * synced, and no signature or type catches that.
      */
     chatModify: (mod: ChatModification, jid: string) => Promise<void>;
-    /**
-     * Force re-sync of app state collections.
-     *
-     * In the Rust bridge architecture, app state is managed internally by the engine
-     * and synced automatically on connect. This method is a no-op provided for API
-     * compatibility with upstream Baileys.
-     */
-    resyncAppState: (_collections?: readonly WAPatchName[], _isInitialSync?: boolean) => Promise<void>;
+    addOrEditContact: (jid: string, contact: proto.SyncActionValue.IContactAction) => Promise<void>;
+    removeContact: (jid: string) => Promise<void>;
+    addLabel: (jid: string, labels: LabelActionBody) => Promise<void>;
+    addChatLabel: (jid: string, labelId: string) => Promise<void>;
+    removeChatLabel: (jid: string, labelId: string) => Promise<void>;
+    addMessageLabel: (jid: string, messageId: string, labelId: string) => Promise<void>;
+    removeMessageLabel: (jid: string, messageId: string, labelId: string) => Promise<void>;
+    star: (jid: string, messages: {
+        id: string;
+        fromMe?: boolean;
+    }[], star: boolean) => Promise<void>;
+    addOrEditQuickReply: (quickReply: QuickReplyAction) => Promise<void>;
+    removeQuickReply: (timestamp: string) => Promise<void>;
 };
 //# sourceMappingURL=chat-actions.d.ts.map