@komaa/standin-sdk 0.1.0

package/dist/delivery.d.ts

@@ -0,0 +1,81 @@
+import { OutboundPolicy, PendingMessages, type OutboundCaller } from "./outbound.js";
+/** Which organisation a placed call belongs to. Operator configuration only. */
+export declare const TENANT_ENV = "STANDIN_TENANT_ID";
+/**
+ * Something that can say a line on a call that is already up.
+ *
+ * Implemented by the plugin, because only it knows how to make its provider
+ * speak without stepping on whatever the agent was already saying.
+ */
+export interface LiveSpeaker {
+    say(text: string): Promise<void>;
+}
+/**
+ * Which calls are up, and how to speak into them.
+ *
+ * A call is filed under its own id and, when it has one, under the Microsoft
+ * Teams conversation it belongs to. Both, because a delivery addressed by
+ * conversation would otherwise miss a call that is only filed by call id, and
+ * the agent would place a second call to somebody already on the line with it.
+ */
+export declare class LiveCalls {
+    #private;
+    register(speaker: LiveSpeaker, callId: string, threadId?: string): void;
+    /**
+     * Remove this speaker's keys, and only this speaker's.
+     *
+     * The identity check is the point. A second call on the same thread can start
+     * before the first one's teardown runs, and a blind delete would then wipe
+     * the live call's entry: every later delivery for that thread would ring a
+     * fresh call, and the person would hear a second ring instead of an answer.
+     */
+    unregister(speaker: LiveSpeaker, callId: string, threadId?: string): void;
+    /** The first live call any of these keys names. Conversation first. */
+    find(...keys: string[]): LiveSpeaker | undefined;
+    get size(): number;
+}
+/** What happened to one line of text. */
+export interface Delivery {
+    readonly ok: boolean;
+    /**
+     * `"live-call"` when it was spoken into a call that was already up, or
+     * `"call-back"` when a call was placed and the line parked for the answer.
+     * Both strings are part of this API.
+     */
+    readonly mode?: "live-call" | "call-back";
+    /** The call that was placed, on the call-back path. */
+    readonly callId?: string;
+    /** One sentence, safe to read out loud. Absent when ok. */
+    readonly error?: string;
+}
+/** Options for {@link VoiceDelivery}. */
+export interface VoiceDeliveryOptions {
+    caller?: OutboundCaller;
+    policy?: OutboundPolicy;
+    pending?: PendingMessages;
+    /**
+     * The organisation to place calls into.
+     *
+     * Operator configuration only: this option, falling back to
+     * `STANDIN_TENANT_ID`. Never the message, the metadata, the model or the
+     * caller, because a model steered by whoever is talking must not be able to
+     * choose which organisation gets dialled.
+     */
+    tenantId?: string;
+    /** Directory id recorded against a parked message, for the audit trail. */
+    requestedBy?: string;
+}
+/**
+ * Speak into a live call if there is one, otherwise ring back.
+ *
+ * {@link deliver} never throws. Every refusal comes back as a sentence, because
+ * the thing reading the result is either a host that will mark the whole
+ * platform failed on an exception, or a model that will say it out loud.
+ */
+export declare class VoiceDelivery {
+    #private;
+    constructor(live: LiveCalls, options?: VoiceDeliveryOptions);
+    /** Say this line to that person, by whichever lane can reach them. */
+    deliver(text: string, target?: string, threadId?: string): Promise<Delivery>;
+}
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"AA2BA,OAAO,EAEL,cAAc,EACd,eAAe,EACf,KAAK,cAAc,EAEpB,MAAM,eAAe,CAAC;AAEvB,gFAAgF;AAChF,eAAO,MAAM,UAAU,sBAAsB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,qBAAa,SAAS;;IAGpB,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,IAAI;IAKnE;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,IAAI;IAOrE,uEAAuE;IACvE,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,SAAS;IAQhD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IAC1C,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;;gBAQZ,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,oBAAyB;IAS/D,sEAAsE;IAChE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,QAAQ,CAAC;CAoG3E"}

package/dist/delivery.js

@@ -0,0 +1,187 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/**
+ * Getting a line of text to a person, whether or not they are already on a call.
+ *
+ * Something outside the call wants to reach somebody: a scheduled job, a chat
+ * message, a host handing off a task. There are two ways that can land, and
+ * which one is right depends entirely on whether a call to that person is up
+ * right now.
+ *
+ * If one is, the line should be spoken into it. Ringing somebody who is mid
+ * sentence with you is the rudest possible way to tell them something.
+ *
+ * If one is not, the call has to be placed, and the line parked so it is said
+ * the moment they answer. `outbound.ts` already has every piece of that: who
+ * may be rung, how often, and the durable parking. What it has never had is a
+ * way to reach a call that is ALREADY up, so every plugin that wanted this
+ * wrote its own registry, and the ones that exist disagree with each other
+ * about identity and about what to do when the live path fails.
+ *
+ * Nothing in this module imports a provider or a host.
+ *
+ * Identical in shape to the Python SDK's `standin.delivery`.
+ */
+import { logger } from "./log.js";
+import { OutboundError, OutboundPolicy, PendingMessages, } from "./outbound.js";
+/** Which organisation a placed call belongs to. Operator configuration only. */
+export const TENANT_ENV = "STANDIN_TENANT_ID";
+/**
+ * Which calls are up, and how to speak into them.
+ *
+ * A call is filed under its own id and, when it has one, under the Microsoft
+ * Teams conversation it belongs to. Both, because a delivery addressed by
+ * conversation would otherwise miss a call that is only filed by call id, and
+ * the agent would place a second call to somebody already on the line with it.
+ */
+export class LiveCalls {
+    #speakers = new Map();
+    register(speaker, callId, threadId = "") {
+        if (callId.trim())
+            this.#speakers.set(callId.trim(), speaker);
+        if (threadId.trim())
+            this.#speakers.set(threadId.trim(), speaker);
+    }
+    /**
+     * Remove this speaker's keys, and only this speaker's.
+     *
+     * The identity check is the point. A second call on the same thread can start
+     * before the first one's teardown runs, and a blind delete would then wipe
+     * the live call's entry: every later delivery for that thread would ring a
+     * fresh call, and the person would hear a second ring instead of an answer.
+     */
+    unregister(speaker, callId, threadId = "") {
+        for (const key of [callId.trim(), threadId.trim()]) {
+            if (key && this.#speakers.get(key) === speaker)
+                this.#speakers.delete(key);
+        }
+    }
+    /** The first live call any of these keys names. Conversation first. */
+    find(...keys) {
+        for (const key of keys) {
+            const found = key ? this.#speakers.get(key.trim()) : undefined;
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    get size() {
+        return this.#speakers.size;
+    }
+}
+/**
+ * Speak into a live call if there is one, otherwise ring back.
+ *
+ * {@link deliver} never throws. Every refusal comes back as a sentence, because
+ * the thing reading the result is either a host that will mark the whole
+ * platform failed on an exception, or a model that will say it out loud.
+ */
+export class VoiceDelivery {
+    #live;
+    #caller;
+    #policy;
+    #pending;
+    #tenantId;
+    #requestedBy;
+    constructor(live, options = {}) {
+        this.#live = live;
+        this.#caller = options.caller;
+        this.#policy = options.policy ?? new OutboundPolicy({});
+        this.#pending = options.pending;
+        this.#tenantId = (options.tenantId ?? process.env[TENANT_ENV] ?? "").trim();
+        this.#requestedBy = options.requestedBy ?? "";
+    }
+    /** Say this line to that person, by whichever lane can reach them. */
+    async deliver(text, target = "", threadId = "") {
+        const line = (text ?? "").trim();
+        if (line === "") {
+            // Checked before the registry is even consulted: an empty message must
+            // never place a real phone call to a real person.
+            return { ok: false, error: "there was nothing to say" };
+        }
+        const speaker = this.#live.find(threadId, target);
+        if (speaker !== undefined) {
+            try {
+                await speaker.say(line);
+                return { ok: true, mode: "live-call" };
+            }
+            catch (err) {
+                // Falls through to the call-back rather than stopping here. A wedged
+                // provider socket would otherwise swallow the message with nobody
+                // told. The trade is deliberate: a half-spoken line can be repeated by
+                // the call-back, and a repeat beats silence.
+                logger.warn(`standin: could not speak into the live call, ringing back instead: ${String(err)}`);
+            }
+        }
+        return await this.#callBack(line, target, threadId);
+    }
+    async #callBack(line, target, threadId) {
+        if (this.#caller === undefined) {
+            return {
+                ok: false,
+                error: "no outbound caller is configured on this deployment",
+            };
+        }
+        const who = (target ?? "").trim();
+        try {
+            this.#policy.check(who);
+        }
+        catch (err) {
+            if (err instanceof OutboundError)
+                return { ok: false, error: err.message };
+            throw err;
+        }
+        if (this.#tenantId === "") {
+            return {
+                ok: false,
+                error: `no tenant is configured: set ${TENANT_ENV} to place calls`,
+            };
+        }
+        let callId = "";
+        try {
+            const placed = await this.#caller.placeCall({
+                userObjectId: who,
+                tenantId: this.#tenantId,
+            });
+            callId = (placed.callId ?? "").trim();
+        }
+        catch (err) {
+            return { ok: false, error: `could not place the call: ${String(err)}` };
+        }
+        if (callId === "")
+            return { ok: false, error: "the call was not placed" };
+        // Recorded only now. Counting the attempt instead would let a broken worker
+        // burn the hourly budget on calls that never rang anybody, and the next
+        // real delivery would be refused for an hour because of it.
+        this.#policy.record();
+        // Parked before this returns. The answering leg is a different call and can
+        // be answered before a later park would have run, and then the person picks
+        // up to silence.
+        const parked = {
+            callId,
+            text: line,
+            threadId: threadId.trim(),
+            requestedBy: this.#requestedBy,
+            tenantId: this.#tenantId,
+            target: who,
+        };
+        try {
+            // Guarded because parking writes to disk, and a full or read-only one
+            // would otherwise throw out of a method whose whole contract is that it
+            // does not. The call HAS been placed by now, so the honest answer names
+            // what was lost rather than pretending nothing rang.
+            this.#pending?.park(parked);
+        }
+        catch (err) {
+            logger.warn(`standin: the call was placed but the line was not parked: ${String(err)}`);
+            return {
+                ok: false,
+                mode: "call-back",
+                callId,
+                error: "the call was placed, but what to say could not be saved",
+            };
+        }
+        return { ok: true, mode: "call-back", callId };
+    }
+}
+//# sourceMappingURL=delivery.js.map

package/dist/delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"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"}

package/dist/echoGuard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The half-duplex echo guard.
+ *
+ * A Microsoft Teams call is one acoustic loop. When the caller is on a speakerphone, the
+ * agent's own voice comes back up the caller leg loudly enough for a realtime
+ * model's server-side VAD to hear it as a turn - so the model answers itself,
+ * interrupts itself, and re-greets, with the caller silent the whole time. That
+ * is not a hypothetical: it is the failure this guard was written to stop.
+ *
+ * The fix is a time window rather than acoustic cancellation: while our own audio
+ * is still PLAYING OUT on the call, caller input below a loudness threshold is
+ * treated as our own echo and dropped, and anything above it is treated as a real
+ * barge-in and passed through.
+ *
+ * It lives in the plugin rather than the SDK core: the SDK owns the wire,
+ * not the room's acoustics.
+ */
+/**
+ * How long after our audio finishes playing the guard stays armed. Playout is not
+ * instantaneous and neither is the echo path.
+ */
+export declare const ECHO_SUPPRESSION_WINDOW_MS = 600;
+/** Normalized RMS above which in-window caller input is a real barge-in, not echo. */
+export declare const ECHO_BARGE_IN_RMS = 0.04;
+import { pcm16Rms } from "./audio.js";
+export { pcm16Rms };
+/** Tunables, straight off the plugin's `realtime` config block. */
+export interface EchoGuardOptions {
+    /** Set false to disable the guard entirely. */
+    suppressInputDuringPlayback?: boolean;
+    /** Window in ms; default {@link ECHO_SUPPRESSION_WINDOW_MS}. */
+    echoSuppressionWindowMs?: number;
+    /** Barge-in RMS gate 0..1; default {@link ECHO_BARGE_IN_RMS}. */
+    echoBargeInRms?: number;
+    /**
+     * False drops the loudness exception and suppresses ALL in-window input.
+     *
+     * Used until the caller's first real turn. On a speakerphone the opening
+     * greeting echoes back loud enough to clear the barge-in RMS, so allowing
+     * barge-in from the first frame is exactly what starts the echo loop. Once the
+     * caller has genuinely spoken once, normal RMS barge-in resumes for the rest of
+     * the call.
+     */
+    allowBargeIn?: boolean;
+}
+/**
+ * True when this frame of caller audio should be withheld from the model.
+ *
+ * `playbackActiveUntil` is the estimated epoch-ms at which the audio we have
+ * already sent finishes PLAYING - not the time we last sent a chunk. A realtime
+ * model generates faster than realtime, so send-time and play-time diverge by
+ * seconds on a long answer, and a guard keyed on send-time disarms in the middle
+ * of the sentence it is supposed to cover.
+ */
+export declare function shouldSuppressEcho(pcm16k: Buffer, playbackActiveUntil: number, opts?: EchoGuardOptions): boolean;
+//# sourceMappingURL=echoGuard.d.ts.map

package/dist/echoGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echoGuard.d.ts","sourceRoot":"","sources":["../src/echoGuard.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAKtC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,gEAAgE;IAChE,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,mBAAmB,EAAE,MAAM,EAC3B,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAgBT"}

package/dist/echoGuard.js

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/**
+ * The half-duplex echo guard.
+ *
+ * A Microsoft Teams call is one acoustic loop. When the caller is on a speakerphone, the
+ * agent's own voice comes back up the caller leg loudly enough for a realtime
+ * model's server-side VAD to hear it as a turn - so the model answers itself,
+ * interrupts itself, and re-greets, with the caller silent the whole time. That
+ * is not a hypothetical: it is the failure this guard was written to stop.
+ *
+ * The fix is a time window rather than acoustic cancellation: while our own audio
+ * is still PLAYING OUT on the call, caller input below a loudness threshold is
+ * treated as our own echo and dropped, and anything above it is treated as a real
+ * barge-in and passed through.
+ *
+ * It lives in the plugin rather than the SDK core: the SDK owns the wire,
+ * not the room's acoustics.
+ */
+/**
+ * How long after our audio finishes playing the guard stays armed. Playout is not
+ * instantaneous and neither is the echo path.
+ */
+export const ECHO_SUPPRESSION_WINDOW_MS = 600;
+/** Normalized RMS above which in-window caller input is a real barge-in, not echo. */
+export const ECHO_BARGE_IN_RMS = 0.04;
+// The one definition lives in the SDK's core audio module, because an echo
+// guard, a barge-in check and a voice segmenter all want it. Imported for use
+// below and re-exported so this module keeps its historical surface.
+import { pcm16Rms } from "./audio.js";
+export { pcm16Rms };
+/**
+ * True when this frame of caller audio should be withheld from the model.
+ *
+ * `playbackActiveUntil` is the estimated epoch-ms at which the audio we have
+ * already sent finishes PLAYING - not the time we last sent a chunk. A realtime
+ * model generates faster than realtime, so send-time and play-time diverge by
+ * seconds on a long answer, and a guard keyed on send-time disarms in the middle
+ * of the sentence it is supposed to cover.
+ */
+export function shouldSuppressEcho(pcm16k, playbackActiveUntil, opts) {
+    if (opts?.suppressInputDuringPlayback === false) {
+        return false;
+    }
+    const inPlaybackWindow = Date.now() <
+        playbackActiveUntil +
+            (opts?.echoSuppressionWindowMs ?? ECHO_SUPPRESSION_WINDOW_MS);
+    if (!inPlaybackWindow) {
+        return false;
+    }
+    // Before the caller's first real turn, every in-window frame is echo.
+    if (opts?.allowBargeIn === false) {
+        return true;
+    }
+    return pcm16Rms(pcm16k) < (opts?.echoBargeInRms ?? ECHO_BARGE_IN_RMS);
+}
+//# sourceMappingURL=echoGuard.js.map

package/dist/echoGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"echoGuard.js","sourceRoot":"","sources":["../src/echoGuard.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,+BAA+B;AAE/B;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,2EAA2E;AAC3E,8EAA8E;AAC9E,qEAAqE;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAsBpB;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,mBAA2B,EAC3B,IAAuB;IAEvB,IAAI,IAAI,EAAE,2BAA2B,KAAK,KAAK,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,gBAAgB,GACpB,IAAI,CAAC,GAAG,EAAE;QACV,mBAAmB;YACjB,CAAC,IAAI,EAAE,uBAAuB,IAAI,0BAA0B,CAAC,CAAC;IAClE,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,sEAAsE;IACtE,IAAI,IAAI,EAAE,YAAY,KAAK,KAAK,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,cAAc,IAAI,iBAAiB,CAAC,CAAC;AACxE,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+/** Every error this SDK raises. Mirrors the Python SDK's `StandInError`. */
+export declare class StandInError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,4EAA4E;AAC5E,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,10 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/** Every error this SDK raises. Mirrors the Python SDK's `StandInError`. */
+export class StandInError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StandInError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,+BAA+B;AAE/B,4EAA4E;AAC5E,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/fetch.d.ts

@@ -0,0 +1,40 @@
+/** Resolves a hostname to addresses. Replaceable so tests can drive a rebind. */
+export type LookupFn = (hostname: string, opts: {
+    all: true;
+    verbatim: true;
+}) => Promise<Array<{
+    address: string;
+    family: number;
+}>>;
+/** Decides whether an address may be fetched. Replaceable for tests. */
+export type ForbiddenIpFn = (ip: string) => boolean;
+/** True for any IPv4 address that must never be fetched server-side. */
+export declare function isForbiddenIpv4(ip: string): boolean;
+/** True for any IPv6 address that must never be fetched server-side. */
+export declare function isForbiddenIpv6(ip: string): boolean;
+/**
+ * True for any address that must never be fetched server-side.
+ *
+ * Unparseable input is forbidden too: something that is not an address cannot be
+ * proven safe, and failing closed is the only correct direction here.
+ */
+export declare function isForbiddenIp(ip: string): boolean;
+/**
+ * Check a URL is safe to fetch, or throw saying why.
+ *
+ * http and https only, no embedded credentials, and every address the host
+ * resolves to must be public.
+ */
+export declare function assertPublicHttpUrl(raw: string, lookupFn?: LookupFn, isForbiddenFn?: ForbiddenIpFn): Promise<URL>;
+/**
+ * Fetch an image from an untrusted URL.
+ *
+ * Bounded in every direction that matters: total time, declared length, streamed
+ * length, and one redirect hop. Throws for anything that fails, so a caller can
+ * hand the reason straight back to the agent that supplied the URL.
+ */
+export declare function fetchPublicImage(rawUrl: string, maxBytes: number, timeoutMs?: number, lookupFn?: LookupFn, isForbiddenFn?: ForbiddenIpFn, redirectsLeft?: number): Promise<{
+    bytes: Buffer;
+    mime: string;
+}>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAiCA,iFAAiF;AACjF,MAAM,MAAM,QAAQ,GAAG,CACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,KAChC,OAAO,CAAC,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC;AAEzD,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;AAepD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAcnD;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAsBnD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKjD;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,QAA6B,EACvC,aAAa,GAAE,aAA6B,GAC3C,OAAO,CAAC,GAAG,CAAC,CAoCd;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,SAAS,EAClB,QAAQ,GAAE,QAA6B,EACvC,aAAa,GAAE,aAA6B,EAC5C,aAAa,SAAI,GAChB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA6I1C"}