@oxidezap/baileyrs 0.0.35 → 0.1.1

package/lib/Socket/server-queries.js

@@ -0,0 +1,121 @@
+import { Boom } from '../Utils/boom.js';
+/**
+ * Every section, flattened and deduplicated, rather than only the section the
+ * server types `all`.
+ *
+ * Upstream reads that one section, and the core deliberately refused to: the
+ * real client walks every section and uses the type only for layout, so a bot
+ * that appears solely under a category is dropped by the narrower reading. A
+ * caller iterating this list handles the extra entries; one that silently lost
+ * a bot has no way to notice.
+ */
+const flattenBotList = (list) => {
+    const seen = new Set();
+    const bots = [];
+    for (const section of list.sections) {
+        for (const bot of section.bots) {
+            if (seen.has(bot.jid))
+                continue;
+            seen.add(bot.jid);
+            bots.push({ jid: bot.jid, personaId: bot.personaId });
+        }
+    }
+    return bots;
+};
+/**
+ * Upstream names these in snake case and types the three timestamps as
+ * strings. Every field is optional because the server omits whatever does not
+ * apply to the account's tier, and an absent quota stays absent: `0` here means
+ * the quota is spent.
+ */
+const toCapInfo = (result) => ({
+    ...(result.totalQuota !== undefined ? { total_quota: result.totalQuota } : {}),
+    ...(result.usedQuota !== undefined ? { used_quota: result.usedQuota } : {}),
+    ...(result.remainingQuota !== undefined ? { remaining_quota: result.remainingQuota } : {}),
+    ...(result.cycleStartTimestamp !== undefined ? { cycle_start_timestamp: String(result.cycleStartTimestamp) } : {}),
+    ...(result.cycleEndTimestamp !== undefined ? { cycle_end_timestamp: String(result.cycleEndTimestamp) } : {}),
+    ...(result.serverSentTimestamp !== undefined ? { server_sent_timestamp: String(result.serverSentTimestamp) } : {}),
+    ...(result.oteStatus !== undefined ? { ote_status: result.oteStatus } : {}),
+    ...(result.mvStatus !== undefined ? { mv_status: result.mvStatus } : {}),
+    ...(result.cappingStatus !== undefined
+        ? { capping_status: result.cappingStatus }
+        : {})
+});
+export const makeServerQueryMethods = (ctx) => {
+    /** Last host seen, so the synchronous accessor upstream exposes can answer. */
+    let mediaHost = '';
+    /**
+     * When the credentials were obtained, not when they were last handed out.
+     * The engine serves a live connection from its cache and gives no signal
+     * for which calls were actual fetches, so the stamp is kept only while the
+     * connection it describes is still live: past its own ttl, on a forced
+     * call, or on rotated credentials, whatever comes back is a fetch.
+     *
+     * A caller renewing on `fetchDate + ttl` needs both halves of that. Always
+     * restamping would push its deadline forward forever; never restamping
+     * would leave it renewing against a moment that has already passed.
+     */
+    let fetched;
+    const isLive = (held) => Date.now() - held.at.getTime() < held.ttl * 1000;
+    return {
+        /**
+         * `maxContentLengthBytes` is absent by design: the core's hosts carry
+         * nothing but a hostname, so the field upstream declares has no source
+         * and is not invented here.
+         */
+        refreshMediaConn: async (forceGet = false) => {
+            // Forced on the first call, as upstream's first call is: the engine may
+            // already hold a connection acquired by an upload, and stamping that
+            // one as fetched now would report it fresher than it is.
+            const held = fetched;
+            const conn = await (await ctx.getClient()).getMediaConn(forceGet || !held);
+            mediaHost = conn.hosts[0]?.hostname ?? mediaHost;
+            const isFetch = forceGet || !held || held.auth !== conn.auth || !isLive(held);
+            fetched = isFetch ? { auth: conn.auth, ttl: conn.ttl, at: new Date() } : held;
+            // A copy: the stored instant decides when the next call restamps, and a
+            // consumer holding the same Date could move it.
+            return { auth: conn.auth, ttl: conn.ttl, hosts: conn.hosts, fetchDate: new Date(fetched.at) };
+        },
+        /** Synchronous, as upstream has it, so it reads what the last refresh saw. */
+        getMediaHost: () => mediaHost,
+        getBotListV2: async () => {
+            return flattenBotList(await (await ctx.getClient()).getBotList());
+        },
+        fetchNewChatMessageCap: async () => {
+            return toCapInfo(await (await ctx.getClient()).fetchNewChatMessageCappingInfo());
+        },
+        cleanDirtyBits: async (type, fromTimestamp) => {
+            let timestamp = null;
+            if (fromTimestamp !== undefined) {
+                // A blank string is not a timestamp, and `Number('')` is the epoch,
+                // so without this a caller meaning "no timestamp" would ask the
+                // server to clean from the beginning of time.
+                const blank = typeof fromTimestamp === 'string' && fromTimestamp.trim() === '';
+                timestamp = typeof fromTimestamp === 'string' ? Number(fromTimestamp) : fromTimestamp;
+                if (blank || !Number.isFinite(timestamp)) {
+                    throw new Boom(`cleanDirtyBits: fromTimestamp '${fromTimestamp}' is not a number`, { statusCode: 400 });
+                }
+            }
+            await (await ctx.getClient()).cleanDirtyBits(type, timestamp);
+        },
+        /**
+         * Refused rather than wired up. The core already fires a peer data
+         * request itself when a message fails to decrypt, with its own age
+         * policy, so a second one here would duplicate it. The request a
+         * consumer actually drives, asking for history, is `fetchMessageHistory`.
+         */
+        sendPeerDataOperationMessage: async (_pdoMessage) => {
+            throw new Boom('sendPeerDataOperationMessage is not supported: use fetchMessageHistory to request history, and note the engine issues its own peer data request when a message fails to decrypt', { statusCode: 501 });
+        },
+        /**
+         * Refused one layer down, as a build decision. `create_call_link` exists
+         * in the core behind its voip feature, and the bridge pins the core with
+         * default features off, so it is not compiled into the wasm artifact at
+         * all. Reaching it would pull the webrtc stack into the bundle.
+         */
+        createCallLink: async (_type, _event, _timeoutMs) => {
+            throw new Boom('createCallLink is not available: the call-link operation sits behind the core voip feature, which is not compiled into the wasm bridge', { statusCode: 501 });
+        }
+    };
+};
+//# sourceMappingURL=server-queries.js.map

package/lib/Socket/terminal-close-reporter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Reports the terminal `connection.update { close }` — exactly once, after
+ * teardown, and never silently not at all.
+ *
+ * That sentence is the whole contract this branch sells, and getting it wrong
+ * has two opposite failure modes, both bad:
+ *
+ *  - **Not reported.** The consumer's handler never runs, so it never builds a
+ *    replacement socket. A bot offline with nothing in its logs — the original
+ *    bug this branch exists to fix.
+ *  - **Reported early, or twice.** The replacement socket overlaps the old
+ *    one's auth-store flush and `free()`, or every listener sees two terminal
+ *    notifications for one socket and a handler that cleans up on close loops.
+ *
+ * Keeping both away used to be inline logic split across the dispatcher hook
+ * and `logout()`, sharing a counter and a promise. Nine separate bugs came out
+ * of that in review — a publish that could never run, a throwing listener
+ * taking the process down, `logout()` resolving before the close it caused,
+ * the watchdog not releasing its waiters, a suppression check that also
+ * matched non-terminal teardown, a fallback that did not count itself. Every
+ * one was a different way of answering the same question, so it is one object
+ * now, with the answer in one place.
+ */
+import type { ILogger } from '../Utils/logger.js';
+/**
+ * How long teardown may run before the close is reported anyway.
+ *
+ * A deliberate trade of one guarantee for the other: past this point the close
+ * goes out with teardown still running, because losing the event entirely is
+ * the worse of the two failures. Teardown takes milliseconds in practice, so
+ * reaching this means a consumer end handler or a store flush never settled —
+ * and the error logged alongside says exactly that. Generous rather than
+ * tight, since firing early is the harmful direction.
+ */
+export declare const TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS = 60000;
+export interface TerminalCloseReporter {
+    /**
+     * Run `teardown`, then publish. Used by the dispatcher, which learns about
+     * the close first and hands over the publishing so the socket can finish
+     * releasing its resources before a consumer can react.
+     *
+     * Never rejects and never leaves `publish` uncalled: teardown failures are
+     * logged, a throwing listener is contained, and a teardown that hangs is
+     * cut short by the watchdog.
+     */
+    reportAfter: (teardown: () => Promise<void>, publish: () => void) => void;
+    /**
+     * Publish immediately, for a close nothing else will announce — a `logout()`
+     * with no live client, or one whose `logout()` threw before the bridge
+     * dispatched anything.
+     */
+    reportNow: (publish: () => void) => void;
+    /**
+     * Whether a terminal close has been *claimed* — reported, or reported-and-
+     * still-tearing-down. Not "published": `reportAfter` publishes only once
+     * teardown finishes, so a check keyed on delivery would see `false` right
+     * after the bridge announced the logout and let `logout()` add a second
+     * close of its own.
+     *
+     * `logout()` uses this rather than "is the socket closing", which is also
+     * true for a plain `end()` — and those report nothing, so keying off them
+     * would let a logout racing one finish with no close at all.
+     */
+    hasReported: () => boolean;
+    /**
+     * Settles once the most recent report has been published — the moment the
+     * consumer sees it, not the moment teardown finishes, so a waiter is not
+     * left hanging when the watchdog is what released the event.
+     *
+     * Resolves immediately when nothing has been reported.
+     */
+    published: () => Promise<void>;
+}
+export declare const makeTerminalCloseReporter: (opts: {
+    logger: ILogger;
+    /** Overridable for tests; production uses the constant above. */
+    publishTimeoutMs?: number;
+}) => TerminalCloseReporter;
+//# sourceMappingURL=terminal-close-reporter.d.ts.map

package/lib/Socket/terminal-close-reporter.js

@@ -0,0 +1,108 @@
+/**
+ * Reports the terminal `connection.update { close }` — exactly once, after
+ * teardown, and never silently not at all.
+ *
+ * That sentence is the whole contract this branch sells, and getting it wrong
+ * has two opposite failure modes, both bad:
+ *
+ *  - **Not reported.** The consumer's handler never runs, so it never builds a
+ *    replacement socket. A bot offline with nothing in its logs — the original
+ *    bug this branch exists to fix.
+ *  - **Reported early, or twice.** The replacement socket overlaps the old
+ *    one's auth-store flush and `free()`, or every listener sees two terminal
+ *    notifications for one socket and a handler that cleans up on close loops.
+ *
+ * Keeping both away used to be inline logic split across the dispatcher hook
+ * and `logout()`, sharing a counter and a promise. Nine separate bugs came out
+ * of that in review — a publish that could never run, a throwing listener
+ * taking the process down, `logout()` resolving before the close it caused,
+ * the watchdog not releasing its waiters, a suppression check that also
+ * matched non-terminal teardown, a fallback that did not count itself. Every
+ * one was a different way of answering the same question, so it is one object
+ * now, with the answer in one place.
+ */
+/**
+ * How long teardown may run before the close is reported anyway.
+ *
+ * A deliberate trade of one guarantee for the other: past this point the close
+ * goes out with teardown still running, because losing the event entirely is
+ * the worse of the two failures. Teardown takes milliseconds in practice, so
+ * reaching this means a consumer end handler or a store flush never settled —
+ * and the error logged alongside says exactly that. Generous rather than
+ * tight, since firing early is the harmful direction.
+ */
+export const TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS = 60000;
+export const makeTerminalCloseReporter = (opts) => {
+    const { logger } = opts;
+    const publishTimeoutMs = opts.publishTimeoutMs ?? TERMINAL_CLOSE_PUBLISH_TIMEOUT_MS;
+    /** Claims, not deliveries — see `hasReported`. */
+    let claimed = 0;
+    let publishedPromise;
+    /** One publish per claim, whatever gets there first, and never throwing. */
+    const makeOnce = (publish, settle) => {
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            try {
+                publish();
+            }
+            catch (err) {
+                // `publish` emits on the consumer's bus. Letting this escape
+                // would surface as an unhandled rejection on a detached chain —
+                // process exit under Node's default handler.
+                logger.error({ err }, 'connection.update listener threw on the terminal close');
+            }
+            settle();
+        };
+    };
+    return {
+        reportAfter: (teardown, publish) => {
+            claimed++;
+            let settle;
+            publishedPromise = new Promise(resolve => {
+                settle = resolve;
+            });
+            const publishOnce = makeOnce(publish, settle);
+            // Deliberately referenced: a pending promise does not keep Node's
+            // event loop alive, so an unref'd timer lets a minimal bot exit
+            // before it can publish — and the close handler that would have
+            // built the replacement never runs, which is what this guards.
+            // Cleared the moment teardown settles, so it holds the loop only
+            // while one is in flight.
+            const watchdog = setTimeout(() => {
+                logger.error({ afterMs: publishTimeoutMs }, 'socket teardown is still running; reporting the close anyway');
+                publishOnce();
+            }, publishTimeoutMs);
+            const finish = (err) => {
+                clearTimeout(watchdog);
+                if (err)
+                    logger.error({ err }, 'socket teardown failed after a terminal disconnect');
+                publishOnce();
+            };
+            // `teardown()` is called inside the try because it can throw
+            // *synchronously*, before returning a promise — `.then` would never
+            // run and the close would stay unpublished until the watchdog, or
+            // forever if the timer were ever removed. The no-silent-failure
+            // promise has to hold for that path too.
+            try {
+                void teardown().then(() => finish(), finish);
+            }
+            catch (err) {
+                finish(err);
+            }
+        },
+        reportNow: publish => {
+            claimed++;
+            let settle;
+            publishedPromise = new Promise(resolve => {
+                settle = resolve;
+            });
+            makeOnce(publish, settle)();
+        },
+        hasReported: () => claimed > 0,
+        published: () => publishedPromise ?? Promise.resolve()
+    };
+};
+//# sourceMappingURL=terminal-close-reporter.js.map

package/lib/Socket/terminal-close.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Which bridge disconnects end the socket for good.
+ *
+ * This mirrors one decision that lives in the Rust engine, so keep it honest:
+ * `whatsapp-rust` clears `enable_auto_reconnect` and breaks out of its run loop
+ * on exactly these, and retries everything else on the WA Web Fibonacci backoff
+ * (`client/lifecycle.rs`).
+ *
+ * The socket layer needs the answer because `WasmWhatsAppClient.run()` returns
+ * `void` — it spawns the loop as a background task, so the loop's exit is not
+ * observable from JS (`whatsapp_rust_bridge.d.ts`, `run(): void`). Until the
+ * bridge exposes loop completion, this table is how the socket knows a client
+ * has become dead weight that only `free()` can reclaim.
+ *
+ * The upstream Baileys contract this buys us: `connection.update { close }`
+ * means "this socket is finished, build a new one" — which is what every
+ * consumer written against upstream already assumes, because upstream has no
+ * auto-reconnect at all. Transient drops therefore never surface as `close`;
+ * they surface as `connecting`.
+ *
+ * Events deliberately absent from the terminal set, and why:
+ *  - `disconnected` — the engine only dispatches `Event::Disconnected` for an
+ *    *unexpected* loop exit, and every terminal path sets `expected_disconnect`
+ *    first, which suppresses it (`client/lifecycle.rs`). So this one is the
+ *    "engine is retrying" signal — with one exception the dispatcher handles:
+ *    under `setAutoReconnect(false)` the run loop dispatches `Disconnected`
+ *    and only *then* tests the flag and breaks out, which makes the very same
+ *    event terminal. Absence from this list means "not terminal on its own",
+ *    not "never terminal".
+ *  - `streamError` — reaches JS only from the engine's catch-all `<stream:error>`
+ *    branch (unknown code, `<ack/>`, `<xml-not-well-formed>`); the coded ones
+ *    (401/409/515/516/429/503) dispatch their own events instead. Every case
+ *    that gets here keeps the connection or recycles it deliberately.
+ *  - `pairError` — pairing failed, but the engine keeps its loop and re-emits a
+ *    QR; nothing about the client is dead.
+ */
+/** True when the engine will keep retrying after this `<failure>`. */
+export declare const isReconnectableConnectFailure: (reason: number | undefined) => boolean;
+//# sourceMappingURL=terminal-close.d.ts.map

package/lib/Socket/terminal-close.js

@@ -0,0 +1,51 @@
+/**
+ * Which bridge disconnects end the socket for good.
+ *
+ * This mirrors one decision that lives in the Rust engine, so keep it honest:
+ * `whatsapp-rust` clears `enable_auto_reconnect` and breaks out of its run loop
+ * on exactly these, and retries everything else on the WA Web Fibonacci backoff
+ * (`client/lifecycle.rs`).
+ *
+ * The socket layer needs the answer because `WasmWhatsAppClient.run()` returns
+ * `void` — it spawns the loop as a background task, so the loop's exit is not
+ * observable from JS (`whatsapp_rust_bridge.d.ts`, `run(): void`). Until the
+ * bridge exposes loop completion, this table is how the socket knows a client
+ * has become dead weight that only `free()` can reclaim.
+ *
+ * The upstream Baileys contract this buys us: `connection.update { close }`
+ * means "this socket is finished, build a new one" — which is what every
+ * consumer written against upstream already assumes, because upstream has no
+ * auto-reconnect at all. Transient drops therefore never surface as `close`;
+ * they surface as `connecting`.
+ *
+ * Events deliberately absent from the terminal set, and why:
+ *  - `disconnected` — the engine only dispatches `Event::Disconnected` for an
+ *    *unexpected* loop exit, and every terminal path sets `expected_disconnect`
+ *    first, which suppresses it (`client/lifecycle.rs`). So this one is the
+ *    "engine is retrying" signal — with one exception the dispatcher handles:
+ *    under `setAutoReconnect(false)` the run loop dispatches `Disconnected`
+ *    and only *then* tests the flag and breaks out, which makes the very same
+ *    event terminal. Absence from this list means "not terminal on its own",
+ *    not "never terminal".
+ *  - `streamError` — reaches JS only from the engine's catch-all `<stream:error>`
+ *    branch (unknown code, `<ack/>`, `<xml-not-well-formed>`); the coded ones
+ *    (401/409/515/516/429/503) dispatch their own events instead. Every case
+ *    that gets here keeps the connection or recycles it deliberately.
+ *  - `pairError` — pairing failed, but the engine keeps its loop and re-emits a
+ *    QR; nothing about the client is dead.
+ */
+/**
+ * `ConnectFailureReason` wire codes the engine retries — the JS mirror of
+ * `ConnectFailureReason::should_reconnect()`, which matches only
+ * `InternalServerError | ServiceUnavailable`.
+ *
+ * A `<failure>` with no reason at all is NOT retried: the engine parses it as
+ * `Unknown(0)`, which fails `should_reconnect()`.
+ */
+const RECONNECTABLE_CONNECT_FAILURE_REASONS = new Set([
+    500, // InternalServerError
+    503 // ServiceUnavailable
+]);
+/** True when the engine will keep retrying after this `<failure>`. */
+export const isReconnectableConnectFailure = (reason) => reason !== undefined && RECONNECTABLE_CONNECT_FAILURE_REASONS.has(reason);
+//# sourceMappingURL=terminal-close.js.map

package/lib/Socket/types.d.ts

@@ -23,6 +23,12 @@ export interface SocketContext {
     getClientSync: () => WasmWhatsAppClient;
     /** Raw stanza EventEmitter for CB: pattern compat */
     ws: EventEmitter;
+    /**
+     * Where a failure goes when it has nowhere else to go: a dispatcher that
+     * threw, a wire batch that would not decode. Also what the socket exposes
+     * as `onUnexpectedError`, so the two are one reporter rather than two.
+     */
+    reportUnexpectedError: (err: unknown, msg: string) => void;
 }
 /** Convert a bridge Jid struct to a string */
 export declare const jidStr: (jid: {

package/lib/Types/Product.d.ts

@@ -1,4 +1,13 @@
+import type { CatalogResult as CatalogPageResult, CollectionsResult } from '@oxidezap/whatsapp-rust-bridge';
 import type { WAMediaUpload } from './Message.js';
+/**
+ * What `getCatalog` returns, under a name of its own. The `CatalogResult`
+ * below is the raw catalog envelope and is a different shape, so a consumer
+ * typing the call has one name to reach for and it is this one.
+ */
+export type CatalogPage = CatalogPageResult;
+/** As `CatalogPage`, for `getCollections`. */
+export type CollectionsPage = CollectionsResult;
 export type CatalogResult = {
     data: {
         paging: {

package/lib/Utils/event-buffer.js

@@ -362,6 +362,37 @@ export const makeEventBuffer = (logger) => {
     let flushPendingTimeout;
     ev.on('event', (events) => {
         for (const event of Object.keys(events)) {
+            if (event === 'connection.update') {
+                // Delivered listener by listener, unlike every other event.
+                // `EventEmitter.emit()` stops at the first listener that throws,
+                // so one bad handler would keep the rest — including the app's
+                // reconnect handler — from ever seeing a terminal `close`, and
+                // the bot would stay offline. This is the lifecycle channel;
+                // losing delivery here is the failure mode the socket's whole
+                // close contract exists to prevent.
+                // `rawListeners`, not `listeners`: the latter unwraps `once()`
+                // handlers to the function underneath, so calling that would
+                // never run the wrapper that unregisters them and the listener
+                // would stay subscribed for every later update. `once` is not on
+                // `BaileysEventEmitter` today, so this is unreachable rather than
+                // broken — but the two differ only in this respect and the raw
+                // one is the correct primitive for calling listeners by hand.
+                for (const listener of ev.rawListeners(event)) {
+                    try {
+                        // `.call(ev, …)` so `this` is still the emitter, as it
+                        // would be under `emit()`. A listener declared as a
+                        // normal function that does `this.off('connection.update', …)`
+                        // — a common self-removing pattern — would otherwise
+                        // throw on `undefined` and be swallowed by the catch.
+                        ;
+                        listener.call(ev, events[event]);
+                    }
+                    catch (err) {
+                        logger.error({ err, event }, 'connection.update listener threw; continuing with the rest');
+                    }
+                }
+                continue;
+            }
             ev.emit(event, events[event]);
         }
     });

package/lib/Utils/index.d.ts

@@ -3,6 +3,7 @@ export * from './auth-utils.js';
 export * from './crypto.js';
 export * from './generics.js';
 export * from './messages.js';
+export { getUrlInfo, type URLGenerationOptions } from './link-preview.js';
 export * from './messages-media.js';
 export * from './process-history-message.js';
 export * from './process-message.js';

package/lib/Utils/index.js

@@ -3,6 +3,9 @@ export * from './auth-utils.js';
 export * from './crypto.js';
 export * from './generics.js';
 export * from './messages.js';
+// Named rather than `*`: the underscore hooks in that file exist for the tests
+// and would otherwise become released API.
+export { getUrlInfo } from './link-preview.js';
 export * from './messages-media.js';
 export * from './process-history-message.js';
 export * from './process-message.js';

package/lib/Utils/link-preview.d.ts

@@ -0,0 +1,60 @@
+import type { WAUrlInfo } from '../Types/Message.js';
+import type { ILogger } from './logger.js';
+/**
+ * The first link in a piece of text, or undefined when there is none. Exported
+ * under an underscore so the extraction can be tested without a network.
+ *
+ * Trailing prose punctuation is dropped: a link at the end of a sentence
+ * carries the full stop with it, and `https://example.com.` is not what the
+ * writer meant. A closing bracket goes the same way, which costs the rare url
+ * that genuinely ends in one and saves the common case of a link in
+ * parentheses.
+ */
+export declare const _firstLink: (text: string) => string | undefined;
+export type URLGenerationOptions = {
+    thumbnailWidth: number;
+    fetchOpts: {
+        /** Timeout in ms */
+        timeout: number;
+        proxyUrl?: string;
+        headers?: HeadersInit;
+    };
+    uploadImage?: (encFilePath: string, opts: {
+        fileEncSha256B64: string;
+        mediaType: string;
+    }) => Promise<unknown>;
+    logger?: ILogger;
+};
+/**
+ * Fetched here rather than through `getHttpStream`, which forwards neither the
+ * timeout nor the proxy and validates no destination. The credentials in
+ * `headers` are for the page, so they are sent to the thumbnail only when it
+ * is the same origin; another host advertised by that page must not receive
+ * them.
+ */
+/** Exported under an underscore so the destination guard can be driven directly. */
+export declare const _getCompressedJpegThumbnail: (url: string, pageUrl: string, { thumbnailWidth, fetchOpts }: URLGenerationOptions) => Promise<{
+    buffer: any;
+    original: {
+        width: any;
+        height: any;
+    };
+}>;
+/**
+ * Reads the first URL out of a piece of text and fetches what a link preview
+ * needs. Nothing here is protocol: it is an HTTP fetch, an OpenGraph parse and
+ * a thumbnail, which is why it belongs in this layer rather than the engine.
+ *
+ * Resolves to undefined for the two cases that mean "no preview": text with no
+ * link in it, and a page with no title. Everything else throws, including a
+ * timeout, because a swallowed failure is indistinguishable from a page that
+ * genuinely had nothing, and a caller retrying the first would give up on the
+ * second.
+ *
+ * The metadata parse comes from `link-preview-js`, an optional peer dependency
+ * this package already declares and had no reader for, so nothing new is
+ * pulled in: a consumer who does not want link previews does not install it
+ * and never calls this.
+ */
+export declare const getUrlInfo: (text: string, opts?: URLGenerationOptions) => Promise<WAUrlInfo | undefined>;
+//# sourceMappingURL=link-preview.d.ts.map