@portalshq/capability-queue-broadcast 0.1.2

package/README.md

@@ -0,0 +1,131 @@
+# `@portalshq/capability-queue-broadcast`
+
+Server-only producer API for one isolated Queue Broadcast Server endpoint.
+
+The queue is deliberately separate from playback: a trusted application backend
+uses this package to enqueue and observe jobs; its browser player gets only the
+public HLS manifest returned by `getPlayback()`. Use
+`@portalshq/capability-video-delivery`'s `HlsPlaybackSession` in a player or
+another stream-delivery integration.
+
+## Backend flow
+
+```ts
+import { QueueBroadcastClient } from "@portalshq/capability-queue-broadcast";
+
+const broadcast = new QueueBroadcastClient({
+  endpoint: process.env.STREAMER_ENDPOINT!, // no token/query/fragment
+  token: process.env.STREAMER_API_TOKEN!,   // backend secret only
+});
+
+const slotKey = `${generationRunId}:turn:1`;
+const image = await broadcast.stageUpload({
+  mediaType: "image",
+  asset: { data: finishedImageBlob, filename: "scene.jpg", sha256: imageSha256 },
+  imageDuration: 18,
+  idempotencyKey: `${slotKey}:image`,
+  slotKey,
+});
+await broadcast.stageUpload({
+  mediaType: "audio",
+  asset: { data: finishedAudioBlob, filename: "narration.wav", sha256: audioSha256 },
+  idempotencyKey: `${slotKey}:audio`,
+  slotKey,
+});
+await broadcast.releaseSlot(slotKey);
+
+for await (const update of broadcast.watchJob(image.id)) {
+  if (update.status === "failed") throw new Error(update.error ?? "queue job failed");
+}
+
+// Pass this descriptor to the application player; do not send `token` to it.
+const playback = await broadcast.getPlayback();
+```
+
+`enqueueUpload` is the preferred distributed ingestion path. A trusted backend
+sends each completed `image`, `audio`, or `video` asset over authenticated
+multipart HTTP to its separately running Queue Broadcast Server. The server
+owns the bytes after receipt, checks the supplied SHA-256, and plays eligible
+items in FIFO order. Standalone audio is valid for capability consumers; an
+application may choose to discard it by policy.
+
+For a multi-asset generation turn or scheduled pre-roll, call `stageUpload` for
+each successful asset with the same `slotKey`, then call `releaseSlot(slotKey)`.
+Release is idempotent and atomically makes all staged items FIFO-eligible, so a
+partially generated turn cannot air early. Adjacent image/audio items can then
+be composited by the Streamer; image-only and video items play independently.
+The `QueueUploadAsset` SHA-256 field lets the server verify bytes without an
+extra producer-side copy. Identical idempotency retries return the original job
+receipt; conflicting reuse maps to `QueueBroadcastError` status `409`.
+
+`enqueuePairUpload` and `stagePair` remain supported for legacy producers, but
+new applications should use individual uploads and slots.
+
+`enqueueUrl` remains for backwards-compatible server-to-server URL ingestion.
+It is not the recommended path for applications that already have the finished
+media bytes.
+
+## Availability preflight
+
+Run this immediately before costly generation, archive recovery, or a direct
+upload. `health` confirms that the Streamer's media service is ready;
+`getPlayback` is authenticated and therefore also detects a bad control URL or
+queue bearer token. Both accept an `AbortSignal`, so an operator stop or process
+shutdown can cancel a pending availability check promptly.
+
+```ts
+const controller = new AbortController();
+const health = await broadcast.health({ signal: controller.signal });
+if (!health.ok) throw new Error("Streamer media service is unavailable");
+
+const playback = await broadcast.getPlayback({ signal: controller.signal });
+// Generate or upload only after both probes have succeeded.
+```
+
+Do not treat a queue-capacity response from a later upload as a preflight
+failure: it means the service is reachable but has applied normal backpressure.
+
+## `massively-social-ebook` example
+
+Its generation worker owns a per-channel `STREAMER_ENDPOINT` and secret. It
+generates image and narration independently in memory, computes SHA-256,
+archives canonical media independently, then stages the successful image and
+optional narration under one slot before releasing it. If narration fails, it
+releases the image alone; if the image fails, it discards lone narration. The chapter page obtains
+`getPlayback()` from its backend and gives the resulting HLS manifest to its
+existing HLS-capable player. The page never calls queue endpoints or receives
+the bearer token.
+
+For chat from another broadcast platform, pass normalized provider events to
+`ExternalChatIngress` in `@portalshq/capability-realtime-fanout` with the same
+endpoint. That produces the `chat:<normalized endpoint>` topic; platform OAuth,
+webhooks, storage, and relays remain outside this capability.
+
+## Generated API
+
+`src/generated/api.ts` is generated from the Streamer repository's checked-in
+`openapi.json` contract using Orval:
+
+```bash
+npm run generate -w @portalshq/capability-queue-broadcast
+```
+
+Commit generated changes with the matching Streamer OpenAPI artifact. The
+hand-written `QueueBroadcastClient` owns authentication, error mapping,
+endpoint validation, and polling semantics.
+
+## RTMP frame delivery
+
+`RTMPStreamer` accepts Base64-encoded JPEG frames (a `data:image/jpeg;base64,`
+prefix is also accepted) and pipes decoded JPEGs to FFmpeg. Set `ffmpegPath`
+when the executable is not available as `ffmpeg` on `PATH`. The streamer owns
+one RTMP destination, bounded buffering, process shutdown, and health status;
+the consuming application owns generation and starts a separate instance for
+each destination.
+
+`GenerationContext.textOverlay` configures FFmpeg's `drawtext` filter. Pass the
+same configuration to `RTMPStreamer` and set `audioDurationSeconds` from the
+generated audio: the overlay is visible for the audio duration plus 1.5 seconds
+at both the head and tail. With no audio it remains visible for five seconds.
+The deployment FFmpeg build must include the `drawtext` filter (libfreetype);
+set `fontFile` when it has no usable default font.

package/dist/client.d.ts

@@ -0,0 +1,174 @@
+import type { HlsPlaybackSession } from "@portalshq/capability-video-delivery";
+import type { ChatMessage } from "@portalshq/capability-realtime-fanout";
+import type { HealthResponse, JobResponse, JobResponseMediaType, JobResponseStatus, QueuePairResponse, QueueSlotResponse } from "./generated/api.js";
+export type QueueMediaType = JobResponseMediaType;
+export type QueueJobStatus = JobResponseStatus;
+export type QueueBroadcastJob = JobResponse;
+export type QueueBroadcastHealth = HealthResponse;
+export type QueueBroadcastPair = QueuePairResponse;
+export type QueueBroadcastSlot = QueueSlotResponse;
+export interface QueueBroadcastClientOptions {
+    /** The control-plane URL for one isolated Queue Broadcast Server instance. */
+    endpoint: string | URL;
+    /** Server-only bearer token. Never expose this value to a browser. */
+    token: string;
+    /** Injection point for tests or a server runtime with a custom fetch implementation. */
+    fetch?: typeof fetch;
+    /** Optional longer timeout policy for multipart media upload requests. */
+    uploadFetch?: typeof fetch;
+}
+export interface EnqueueUrlInput {
+    mediaType: QueueMediaType;
+    /** A completed, permitted media URL. Signed query strings are allowed here. */
+    url: string;
+    imageDuration?: number;
+    /** Required so producer retries are safe. */
+    idempotencyKey: string;
+}
+export interface WatchJobOptions {
+    signal?: AbortSignal;
+    intervalMs?: number;
+    onUpdate?: (job: QueueBroadcastJob) => void | Promise<void>;
+}
+/** A finished file held by the trusted producer process. */
+export interface QueueUploadAsset {
+    /** Native Blob keeps the multipart request streamable across processes. */
+    data: Blob;
+    /** Metadata only; the streamer validates the actual bytes with sha256. */
+    filename: string;
+    /** SHA-256 of `data`, as lowercase hexadecimal. */
+    sha256: string;
+}
+export interface EnqueuePairUploadInput {
+    image: QueueUploadAsset;
+    audio: QueueUploadAsset;
+    /** The image's real composite duration, normally the narration duration. */
+    imageDuration: number;
+    /** Required, stable producer key. Retries return the original pair. */
+    idempotencyKey: string;
+    /** Persist the pair, but hold it from playout until `releasePair`. */
+    staged?: boolean;
+}
+/** One independently playable finished asset uploaded to the Streamer. */
+export interface EnqueueUploadInput {
+    mediaType: QueueMediaType;
+    asset: QueueUploadAsset;
+    /** Optional image duration. Omit it to use the Streamer's configured default. */
+    imageDuration?: number;
+    /** Required, stable producer key. Retries return the original job. */
+    idempotencyKey: string;
+    /** Hold this item until its slot is atomically released. */
+    staged?: boolean;
+    /** Required when `staged` is true; identifies the producer's logical turn. */
+    slotKey?: string;
+}
+export type StageUploadInput = Omit<EnqueueUploadInput, "staged" | "slotKey"> & {
+    slotKey: string;
+};
+/** Text rendered by the streamer's FFmpeg `drawtext` filter. */
+export interface TextOverlayConfig {
+    text: string;
+    position?: "top" | "center" | "bottom";
+    fontSize?: number;
+    fontColor?: string;
+    /** Optional absolute path for deployments that do not have a default font. */
+    fontFile?: string;
+}
+export interface GenerationContext {
+    /** Base64 encoded last frame from previous generation for visual continuity */
+    previousFrame?: string;
+    /** History of prompts used in previous generations */
+    previousPrompts: string[];
+    /** Chat messages available for context (if chat integration enabled) */
+    chatMessages?: ChatMessage[];
+    /** Optional text overlay to render in the RTMP stream. */
+    textOverlay?: TextOverlayConfig;
+    /** Generation parameters for the current request */
+    generationParams: Record<string, unknown>;
+}
+export interface GeneratedFrames {
+    /** Base64 encoded video frames */
+    frames: string[];
+    /** Optional audio data in PCM format */
+    audio?: ArrayBuffer;
+    /** Duration of the attached audio, used to time a text overlay. */
+    audioDurationSeconds?: number;
+    /** Duration of the generated content in seconds */
+    duration: number;
+}
+/**
+ * Callback interface for real-time video generation.
+ * The consuming application provides the AI implementation while queue-broadcast
+ * handles streaming infrastructure, frame buffering, and RTMP output.
+ */
+export interface GenerationCallback {
+    (context: GenerationContext): Promise<GeneratedFrames>;
+}
+/** Error returned by the queue control plane, including its HTTP status. */
+export declare class QueueBroadcastError extends Error {
+    readonly status: number;
+    readonly detail?: string | undefined;
+    constructor(message: string, status: number, detail?: string | undefined);
+}
+/**
+ * Canonicalize a Queue Broadcast Server endpoint before it becomes a queue or
+ * chat namespace. Credentials, query parameters, and fragments are not part
+ * of an endpoint identity and could otherwise leak secret or routing data.
+ */
+export declare function normalizeBroadcastEndpoint(endpoint: string | URL): string;
+/**
+ * Server-only producer client. It controls one broadcast endpoint while
+ * browser clients receive only `getPlayback().playbackManifestUrl`.
+ */
+export declare class QueueBroadcastClient {
+    private readonly endpoint;
+    private readonly token;
+    private readonly requestFetch;
+    private readonly uploadRequestFetch;
+    constructor(options: QueueBroadcastClientOptions);
+    enqueueUrl(input: EnqueueUrlInput): Promise<QueueBroadcastJob>;
+    /**
+     * Upload one finished image, audio, or video asset. The Streamer owns its
+     * bytes and schedules it in FIFO order; adjacent image/audio jobs may be
+     * composited there when both are ready.
+     */
+    enqueueUpload(input: EnqueueUploadInput): Promise<QueueBroadcastJob>;
+    /** Persist one item under a turn slot; use `releaseSlot` after all successes. */
+    stageUpload(input: StageUploadInput): Promise<QueueBroadcastJob>;
+    /**
+     * Send finished media bytes directly to the remote Streamer process.
+     * This is the preferred ingestion path: the streamer does not download the
+     * asset from an application-owned URL, and it only exposes both jobs after
+     * its durable pair receipt has committed.
+     */
+    enqueuePairUpload(input: EnqueuePairUploadInput): Promise<QueueBroadcastPair>;
+    /** Persist a canonical pair during pre-roll, then activate it later. */
+    stagePair(input: Omit<EnqueuePairUploadInput, "staged">): Promise<QueueBroadcastPair>;
+    getPair(pairId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<QueueBroadcastPair>;
+    /** Idempotently make a previously staged pair eligible for FIFO playout. */
+    releasePair(pairId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<QueueBroadcastPair>;
+    getSlot(slotKey: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<QueueBroadcastSlot>;
+    /** Idempotently make every staged item in a logical turn FIFO-eligible. */
+    releaseSlot(slotKey: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<QueueBroadcastSlot>;
+    getJob(jobId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<QueueBroadcastJob>;
+    /** Watch a job without retaining a subscription or exposing queue tokens to a browser. */
+    watchJob(jobId: string, options?: WatchJobOptions): AsyncGenerator<QueueBroadcastJob>;
+    getPlayback(options?: {
+        signal?: AbortSignal;
+    }): Promise<HlsPlaybackSession>;
+    health(options?: {
+        signal?: AbortSignal;
+    }): Promise<QueueBroadcastHealth>;
+    private request;
+    private requestMultipart;
+}

package/dist/client.js

@@ -0,0 +1,312 @@
+/** Error returned by the queue control plane, including its HTTP status. */
+export class QueueBroadcastError extends Error {
+    status;
+    detail;
+    constructor(message, status, detail) {
+        super(message);
+        this.status = status;
+        this.detail = detail;
+        this.name = "QueueBroadcastError";
+    }
+}
+/**
+ * Canonicalize a Queue Broadcast Server endpoint before it becomes a queue or
+ * chat namespace. Credentials, query parameters, and fragments are not part
+ * of an endpoint identity and could otherwise leak secret or routing data.
+ */
+export function normalizeBroadcastEndpoint(endpoint) {
+    const url = new URL(endpoint.toString());
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new TypeError("Queue Broadcast endpoint must use http or https");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new TypeError("Queue Broadcast endpoint cannot contain credentials, query parameters, or a fragment");
+    }
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    return url.toString().replace(/\/$/, "");
+}
+function validateSourceUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new TypeError("media url must use http or https");
+    }
+    if (url.username || url.password || url.hash) {
+        throw new TypeError("media url cannot contain credentials or a fragment");
+    }
+}
+function isTerminal(status) {
+    return status === "done" || status === "failed";
+}
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+function validateUploadAsset(asset, field) {
+    if (!(asset.data instanceof Blob) || asset.data.size <= 0) {
+        throw new TypeError(`${field}.data must be a non-empty Blob`);
+    }
+    if (!asset.filename.trim())
+        throw new TypeError(`${field}.filename is required`);
+    if (!SHA256_HEX.test(asset.sha256)) {
+        throw new TypeError(`${field}.sha256 must be a lowercase SHA-256 hex digest`);
+    }
+}
+function validateImageDuration(mediaType, imageDuration) {
+    if (mediaType === "image") {
+        if (imageDuration !== undefined && (!Number.isFinite(imageDuration) || imageDuration < 1 || imageDuration > 30)) {
+            throw new TypeError("imageDuration must be a finite number between 1 and 30 seconds");
+        }
+    }
+    else if (imageDuration !== undefined) {
+        throw new TypeError("imageDuration is only valid for image media");
+    }
+}
+function validateSlotKey(slotKey, staged) {
+    const normalized = slotKey?.trim();
+    if (staged && !normalized)
+        throw new TypeError("slotKey is required for staged uploads");
+    if (!staged && normalized)
+        throw new TypeError("slotKey is only valid for staged uploads");
+    if (normalized && normalized.length > 255)
+        throw new TypeError("slotKey must be at most 255 characters");
+    return normalized;
+}
+function waitForPoll(intervalMs, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, intervalMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Server-only producer client. It controls one broadcast endpoint while
+ * browser clients receive only `getPlayback().playbackManifestUrl`.
+ */
+export class QueueBroadcastClient {
+    endpoint;
+    token;
+    requestFetch;
+    uploadRequestFetch;
+    constructor(options) {
+        this.endpoint = normalizeBroadcastEndpoint(options.endpoint);
+        if (!options.token.trim()) {
+            throw new TypeError("Queue Broadcast bearer token is required");
+        }
+        this.token = options.token;
+        this.requestFetch = options.fetch ?? fetch;
+        this.uploadRequestFetch = options.uploadFetch ?? this.requestFetch;
+    }
+    async enqueueUrl(input) {
+        validateSourceUrl(input.url);
+        const idempotencyKey = input.idempotencyKey.trim();
+        if (!idempotencyKey) {
+            throw new TypeError("idempotencyKey is required");
+        }
+        validateImageDuration(input.mediaType, input.imageDuration);
+        return this.request("/v1/queue", {
+            method: "POST",
+            headers: { "Idempotency-Key": idempotencyKey },
+            body: JSON.stringify({
+                media_type: input.mediaType,
+                url: input.url,
+                ...(input.imageDuration === undefined ? {} : { duration: input.imageDuration }),
+            }),
+        });
+    }
+    /**
+     * Upload one finished image, audio, or video asset. The Streamer owns its
+     * bytes and schedules it in FIFO order; adjacent image/audio jobs may be
+     * composited there when both are ready.
+     */
+    async enqueueUpload(input) {
+        validateUploadAsset(input.asset, input.mediaType);
+        validateImageDuration(input.mediaType, input.imageDuration);
+        const idempotencyKey = input.idempotencyKey.trim();
+        if (!idempotencyKey)
+            throw new TypeError("idempotencyKey is required");
+        const slotKey = validateSlotKey(input.slotKey, input.staged);
+        const form = new FormData();
+        form.append("file", input.asset.data, input.asset.filename);
+        form.append("media_type", input.mediaType);
+        form.append("sha256", input.asset.sha256);
+        if (input.imageDuration !== undefined)
+            form.append("duration", String(input.imageDuration));
+        if (input.staged)
+            form.append("staged", "true");
+        if (slotKey)
+            form.append("slot_key", slotKey);
+        return this.requestMultipart("/v1/queue/upload", form, {
+            method: "POST",
+            headers: { "Idempotency-Key": idempotencyKey },
+        });
+    }
+    /** Persist one item under a turn slot; use `releaseSlot` after all successes. */
+    async stageUpload(input) {
+        return this.enqueueUpload({ ...input, staged: true });
+    }
+    /**
+     * Send finished media bytes directly to the remote Streamer process.
+     * This is the preferred ingestion path: the streamer does not download the
+     * asset from an application-owned URL, and it only exposes both jobs after
+     * its durable pair receipt has committed.
+     */
+    async enqueuePairUpload(input) {
+        validateUploadAsset(input.image, "image");
+        validateUploadAsset(input.audio, "audio");
+        const idempotencyKey = input.idempotencyKey.trim();
+        if (!idempotencyKey)
+            throw new TypeError("idempotencyKey is required");
+        if (!Number.isFinite(input.imageDuration) || input.imageDuration < 1 || input.imageDuration > 30) {
+            throw new TypeError("imageDuration must be a finite number between 1 and 30 seconds");
+        }
+        const form = new FormData();
+        form.append("image", input.image.data, input.image.filename);
+        form.append("audio", input.audio.data, input.audio.filename);
+        form.append("image_duration", String(input.imageDuration));
+        form.append("image_sha256", input.image.sha256);
+        form.append("audio_sha256", input.audio.sha256);
+        if (input.staged)
+            form.append("staged", "true");
+        return this.requestMultipart("/v1/queue/pairs/upload", form, {
+            method: "POST",
+            headers: { "Idempotency-Key": idempotencyKey },
+        });
+    }
+    /** Persist a canonical pair during pre-roll, then activate it later. */
+    async stagePair(input) {
+        return this.enqueuePairUpload({ ...input, staged: true });
+    }
+    async getPair(pairId, options = {}) {
+        if (!pairId.trim())
+            throw new TypeError("pairId is required");
+        return this.request(`/v1/queue/pairs/${encodeURIComponent(pairId)}`, options);
+    }
+    /** Idempotently make a previously staged pair eligible for FIFO playout. */
+    async releasePair(pairId, options = {}) {
+        if (!pairId.trim())
+            throw new TypeError("pairId is required");
+        return this.request(`/v1/queue/pairs/${encodeURIComponent(pairId)}/release`, {
+            ...options,
+            method: "POST",
+        });
+    }
+    async getSlot(slotKey, options = {}) {
+        const normalized = validateSlotKey(slotKey, true);
+        return this.request(`/v1/queue/slots/${encodeURIComponent(normalized)}`, options);
+    }
+    /** Idempotently make every staged item in a logical turn FIFO-eligible. */
+    async releaseSlot(slotKey, options = {}) {
+        const normalized = validateSlotKey(slotKey, true);
+        return this.request(`/v1/queue/slots/${encodeURIComponent(normalized)}/release`, {
+            ...options,
+            method: "POST",
+        });
+    }
+    async getJob(jobId, options = {}) {
+        if (!jobId.trim())
+            throw new TypeError("jobId is required");
+        return this.request(`/v1/queue/${encodeURIComponent(jobId)}`, options);
+    }
+    /** Watch a job without retaining a subscription or exposing queue tokens to a browser. */
+    async *watchJob(jobId, options = {}) {
+        const intervalMs = Math.max(50, Math.floor(options.intervalMs ?? 1_000));
+        let previousRevision;
+        while (!options.signal?.aborted) {
+            let job;
+            try {
+                job = await this.getJob(jobId, { signal: options.signal });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    return;
+                throw error;
+            }
+            const revision = `${job.status}:${job.updated_at}:${job.error ?? ""}`;
+            if (revision !== previousRevision) {
+                previousRevision = revision;
+                await options.onUpdate?.(job);
+                yield job;
+            }
+            if (isTerminal(job.status) || options.signal?.aborted)
+                return;
+            await waitForPoll(intervalMs, options.signal);
+        }
+    }
+    async getPlayback(options = {}) {
+        const stream = await this.request("/v1/stream", options);
+        const hls = new URL(stream.hls);
+        if (hls.protocol !== "http:" && hls.protocol !== "https:") {
+            throw new QueueBroadcastError("queue server returned a non-http HLS URL", 502);
+        }
+        return { sessionId: this.endpoint, playbackManifestUrl: hls.toString() };
+    }
+    async health(options = {}) {
+        return this.request("/health", options, false);
+    }
+    async request(path, init = {}, authenticated = true) {
+        const headers = new Headers(init.headers);
+        headers.set("Accept", "application/json");
+        if (init.body !== undefined && !headers.has("Content-Type")) {
+            headers.set("Content-Type", "application/json");
+        }
+        if (authenticated)
+            headers.set("Authorization", `Bearer ${this.token}`);
+        let response;
+        try {
+            response = await this.requestFetch(`${this.endpoint}${path}`, { ...init, headers });
+        }
+        catch (cause) {
+            throw new QueueBroadcastError(`Queue Broadcast request failed: ${cause instanceof Error ? cause.message : String(cause)}`, 0);
+        }
+        const text = await response.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            data = undefined;
+        }
+        if (!response.ok) {
+            const detail = typeof data === "object" && data !== null && "detail" in data && typeof data.detail === "string"
+                ? data.detail
+                : text || response.statusText;
+            throw new QueueBroadcastError(`Queue Broadcast request failed (${response.status}): ${detail}`, response.status, detail);
+        }
+        return data;
+    }
+    async requestMultipart(path, body, init) {
+        const headers = new Headers(init.headers);
+        headers.set("Accept", "application/json");
+        headers.set("Authorization", `Bearer ${this.token}`);
+        // Do not set Content-Type: fetch supplies the multipart boundary.
+        let response;
+        try {
+            response = await this.uploadRequestFetch(`${this.endpoint}${path}`, { ...init, headers, body });
+        }
+        catch (cause) {
+            throw new QueueBroadcastError(`Queue Broadcast request failed: ${cause instanceof Error ? cause.message : String(cause)}`, 0);
+        }
+        const text = await response.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            data = undefined;
+        }
+        if (!response.ok) {
+            const detail = typeof data === "object" && data !== null && "detail" in data && typeof data.detail === "string"
+                ? data.detail
+                : text || response.statusText;
+            throw new QueueBroadcastError(`Queue Broadcast request failed (${response.status}): ${detail}`, response.status, detail);
+        }
+        return data;
+    }
+}