@zintrust/core 3.5.1 → 3.5.2

package/src/tools/broadcast/Broadcast.js

@@ -0,0 +1,686 @@
+import { isArray, isNonEmptyString, isObject } from '../../helper/index.js';
+import { InMemoryDriver } from './drivers/InMemory.js';
+import { PusherDriver } from './drivers/Pusher.js';
+import { RedisDriver } from './drivers/Redis.js';
+import { RedisHttpsDriver } from './drivers/RedisHttps.js';
+import { delay } from '../../common/index.js';
+import broadcastConfig from '../../config/broadcast.js';
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+const BROADCAST_CHANNEL_SCOPES = new Set([
+    'public',
+    'private',
+    'presence',
+    'persistent',
+]);
+const INTERNAL_SOCKET_SECRET_HEADER = 'x-zintrust-socket-secret';
+const DEFAULT_BROADCAST_EVENTS_PATH_TEMPLATE = '/apps/{appId}/events';
+// A POST that returns one of these never completed at the application origin, so
+// re-sending it cannot duplicate a delivered event. 520-524 are the edge->origin
+// (e.g. Cloudflare) statuses: a 522 means the edge could not connect to the origin,
+// not that the broadcast was processed. Genuine application responses (2xx and 4xx
+// such as 401/403/422) reached the origin and are never retried.
+const TRANSIENT_PUBLISH_STATUSES = new Set([
+    408, 425, 429, 500, 502, 503, 504, 520, 521, 522, 523, 524,
+]);
+const resolveInternalPublishRetryConfig = () => ({
+    maxAttempts: Math.max(1, Env.getInt('BROADCAST_INTERNAL_PUBLISH_RETRIES', 3)),
+    baseDelayMs: Math.max(0, Env.getInt('BROADCAST_INTERNAL_PUBLISH_RETRY_BASE_MS', 200)),
+});
+// exponential backoff + full jitter
+const computeRetryDelayMs = (baseDelayMs, attempt) => {
+    const exponential = baseDelayMs * Math.pow(2, attempt - 1);
+    const num = Math.random(); // NOSONAR
+    const jitter = baseDelayMs === 0 ? 0 : Math.floor(num * baseDelayMs);
+    return exponential + jitter;
+};
+const pickFirstNonEmpty = (...values) => {
+    for (const value of values) {
+        if (value.trim() !== '') {
+            return value.trim();
+        }
+    }
+    return '';
+};
+const normalizeChannelScope = (value) => {
+    if (!isNonEmptyString(value)) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (BROADCAST_CHANNEL_SCOPES.has(normalized)) {
+        return normalized;
+    }
+    return undefined;
+};
+const getQualifiedChannelScope = (channel) => {
+    if (channel.startsWith('private-'))
+        return 'private';
+    if (channel.startsWith('presence-'))
+        return 'presence';
+    if (channel.startsWith('persistent-'))
+        return 'persistent';
+    return undefined;
+};
+const applyChannelScope = (channel, scope) => {
+    const normalizedChannel = channel.trim();
+    const existingScope = getQualifiedChannelScope(normalizedChannel);
+    if (existingScope !== undefined) {
+        if (scope !== undefined && scope !== existingScope) {
+            throw ErrorFactory.createValidationError(`Broadcast channel scope ${scope} conflicts with fully-qualified channel ${normalizedChannel}.`);
+        }
+        return normalizedChannel;
+    }
+    if (scope === undefined || scope === 'public') {
+        return normalizedChannel;
+    }
+    return `${scope}-${normalizedChannel}`;
+};
+const normalizeChannels = (input) => {
+    const scope = normalizeChannelScope(input.channelScope ?? input.scope);
+    if (isArray(input.channels)) {
+        return input.channels
+            .filter(isNonEmptyString)
+            .map((channel) => applyChannelScope(channel, scope));
+    }
+    if (isNonEmptyString(input.channel)) {
+        return [applyChannelScope(input.channel, scope)];
+    }
+    return [];
+};
+const appendUnique = (values, nextValue) => {
+    if (nextValue !== '' && !values.includes(nextValue)) {
+        values.push(nextValue);
+    }
+};
+const toAbsoluteBaseUrl = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '' || trimmed.startsWith('/')) {
+        return '';
+    }
+    try {
+        return new URL(trimmed).toString();
+    }
+    catch {
+        try {
+            return new URL(`http://${trimmed}`).toString();
+        }
+        catch {
+            return '';
+        }
+    }
+};
+const getLoopbackAlternativeBaseUrl = (value) => {
+    try {
+        const parsed = new URL(value);
+        if (parsed.hostname === '127.0.0.1') {
+            parsed.hostname = 'localhost';
+            return parsed.toString();
+        }
+        if (parsed.hostname === 'localhost' ||
+            parsed.hostname === '[::1]' ||
+            parsed.hostname === '::1') {
+            parsed.hostname = '127.0.0.1';
+            return parsed.toString();
+        }
+    }
+    catch {
+        return '';
+    }
+    return '';
+};
+const resolveBroadcastAppId = () => {
+    return (pickFirstNonEmpty(Env.get('PUSHER_APP_ID', ''), Env.get('BROADCAST_APP_ID', '')) || 'internal');
+};
+const resolveBroadcastSecret = () => {
+    return pickFirstNonEmpty(Env.get('BROADCAST_BRIDGE_SECRET', ''), Env.get('X_ZINTRUST_SOCKET_SEC', ''), Env.get('BROADCAST_SECRET', ''), Env.get('PUSHER_APP_SECRET', ''), Env.get('BROADCAST_APP_SECRET', ''));
+};
+const resolveBridgePath = (appId, value) => {
+    const raw = (value ?? DEFAULT_BROADCAST_EVENTS_PATH_TEMPLATE).trim();
+    const withLeadingSlash = raw === '' ? DEFAULT_BROADCAST_EVENTS_PATH_TEMPLATE : raw;
+    const normalized = withLeadingSlash.startsWith('/') ? withLeadingSlash : `/${withLeadingSlash}`;
+    return normalized
+        .replaceAll('{appId}', encodeURIComponent(appId))
+        .replaceAll(':appId', encodeURIComponent(appId));
+};
+const resolveExplicitEndpoint = (value, appId) => {
+    const absoluteUrl = toAbsoluteBaseUrl(value);
+    if (absoluteUrl === '') {
+        return '';
+    }
+    try {
+        const parsed = new URL(absoluteUrl);
+        if (parsed.pathname === '/' || parsed.pathname.trim() === '') {
+            parsed.pathname = resolveBridgePath(appId);
+        }
+        return parsed.toString();
+    }
+    catch {
+        return '';
+    }
+};
+const resolveLegacyBridgeEndpoint = (appId) => {
+    const host = Env.get('ZINTRUST_SOCKET_HOST', '').trim();
+    if (host === '') {
+        return '';
+    }
+    const port = Env.get('ZINTRUST_SOCKET_PORT', '').trim();
+    const protocol = pickFirstNonEmpty(Env.get('BROADCAST_BRIDGE_PROTOCOL', ''), 'http');
+    const portSuffix = port === '' ? '' : `:${port}`;
+    const baseUrl = `${protocol}://${host}${portSuffix}`;
+    try {
+        return new URL(resolveBridgePath(appId, Env.get('BROADCAST_BRIDGE_PATH', '')), baseUrl).toString();
+    }
+    catch {
+        return '';
+    }
+};
+const buildEndpointCandidates = (values) => {
+    const resolved = [];
+    for (const value of values) {
+        appendUnique(resolved, value);
+        appendUnique(resolved, getLoopbackAlternativeBaseUrl(value));
+    }
+    return resolved;
+};
+const getInternalPublishConfig = () => {
+    const baseUrls = [];
+    appendUnique(baseUrls, toAbsoluteBaseUrl(Env.get('BROADCAST_INTERNAL_URL', '')));
+    appendUnique(baseUrls, toAbsoluteBaseUrl(Env.get('APP_URL', '')));
+    appendUnique(baseUrls, toAbsoluteBaseUrl(Env.get('BASE_URL', '')));
+    const appId = resolveBroadcastAppId();
+    const secret = resolveBroadcastSecret();
+    return Object.freeze({
+        endpoints: buildEndpointCandidates(baseUrls).map((baseUrl) => new URL(`/apps/${encodeURIComponent(appId)}/events`, baseUrl).toString()),
+        appId,
+        secret,
+    });
+};
+const getBridgePublishConfig = () => {
+    const appId = resolveBroadcastAppId();
+    return Object.freeze({
+        endpoints: buildEndpointCandidates([
+            resolveExplicitEndpoint(Env.get('BROADCAST_BRIDGE_URL', ''), appId),
+            resolveLegacyBridgeEndpoint(appId),
+        ]),
+        secret: resolveBroadcastSecret(),
+    });
+};
+const isIsolatedWorkerRuntime = () => {
+    return Env.getBool('WORKER_ISOLATED', false) || Env.getBool('DOCKER_WORKER', false);
+};
+const parseJsonResponseSafe = async (response) => {
+    const raw = await response.text();
+    if (raw.trim() === '') {
+        return {};
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return { raw };
+    }
+};
+const getDeliveries = (payload) => {
+    if (!isObject(payload)) {
+        return undefined;
+    }
+    const deliveries = payload['deliveries'];
+    return typeof deliveries === 'number' && Number.isFinite(deliveries) ? deliveries : undefined;
+};
+import { tracedFetch } from '../../common/ExternalServiceUtils.js';
+const describeError = (error) => {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+        };
+    }
+    return String(error);
+};
+const logTransportFallback = (transport, details) => {
+    Logger.warn('Broadcast publish transport failed; falling back.', {
+        transport,
+        ...details,
+    });
+};
+const attemptInternalPublishEndpoint = async (endpoint, secret, payload) => {
+    try {
+        const response = await tracedFetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                ...(secret === ''
+                    ? {}
+                    : {
+                        [INTERNAL_SOCKET_SECRET_HEADER]: secret,
+                        authorization: `Bearer ${secret}`,
+                    }),
+            },
+            body: JSON.stringify(payload),
+        }, { source: 'broadcast-internal-http' });
+        const responseBody = await parseJsonResponseSafe(response);
+        if (!response.ok) {
+            const error = ErrorFactory.createTryCatchError(`Internal socket publish request failed (${response.status})`, {
+                status: response.status,
+                endpoint,
+                body: responseBody,
+            });
+            logTransportFallback('internal-http', {
+                endpoint,
+                status: response.status,
+                body: responseBody,
+            });
+            return {
+                result: null,
+                error,
+                status: response.status,
+                transient: TRANSIENT_PUBLISH_STATUSES.has(response.status),
+            };
+        }
+        const resolvedChannels = isObject(responseBody) && isArray(responseBody['channels'])
+            ? responseBody['channels'].filter(isNonEmptyString).map((channel) => channel.trim())
+            : payload.channels;
+        const resolvedEvent = isObject(responseBody) && isNonEmptyString(responseBody['event'])
+            ? responseBody['event'].trim()
+            : payload.event;
+        return {
+            result: {
+                ok: true,
+                transport: 'internal-http',
+                channels: resolvedChannels,
+                event: resolvedEvent,
+                deliveries: getDeliveries(responseBody),
+                endpoint,
+                result: responseBody,
+            },
+        };
+    }
+    catch (error) {
+        logTransportFallback('internal-http', {
+            endpoint,
+            error: describeError(error),
+        });
+        // A thrown error means the POST never completed at the application origin, so
+        // it is safe to retry.
+        return { result: null, error, transient: true };
+    }
+};
+const requestInternalPublishEndpoint = async (endpoint, secret, payload, attempt = 1, retryConfig) => {
+    const { maxAttempts, baseDelayMs } = retryConfig ?? resolveInternalPublishRetryConfig();
+    const result = await attemptInternalPublishEndpoint(endpoint, secret, payload);
+    if (result.result !== null) {
+        return result;
+    }
+    // Non-transient failures (application 4xx, etc.) reached the origin; do not retry.
+    if (result.transient !== true || attempt >= maxAttempts) {
+        return result;
+    }
+    const delayMs = computeRetryDelayMs(baseDelayMs, attempt);
+    Logger.warn('Broadcast internal publish retrying transient failure.', {
+        endpoint,
+        attempt,
+        maxAttempts,
+        delayMs,
+        status: result.status,
+    });
+    await delay(delayMs);
+    return requestInternalPublishEndpoint(endpoint, secret, payload, attempt + 1, {
+        maxAttempts,
+        baseDelayMs,
+    });
+};
+const tryInternalPublishEndpoints = async (endpoints, secret, payload, index = 0, lastError) => {
+    const endpoint = endpoints[index];
+    if (endpoint === undefined) {
+        return { result: null, error: lastError };
+    }
+    const attempt = await requestInternalPublishEndpoint(endpoint, secret, payload);
+    if (attempt.result !== null) {
+        return attempt;
+    }
+    return tryInternalPublishEndpoints(endpoints, secret, payload, index + 1, attempt.error ?? lastError);
+};
+const resolveBroadcasterConfig = async (name) => {
+    const selection = (name ?? broadcastConfig.getDriverName()).toString().trim().toLowerCase();
+    try {
+        const { BroadcastRegistry } = await import('./BroadcastRegistry.js');
+        if (BroadcastRegistry.has(selection)) {
+            return BroadcastRegistry.get(selection);
+        }
+        try {
+            const { registerBroadcastersFromRuntimeConfig } = await import('./BroadcastRuntimeRegistration.js');
+            registerBroadcastersFromRuntimeConfig(broadcastConfig);
+        }
+        catch {
+            // best-effort
+        }
+        if (BroadcastRegistry.has(selection)) {
+            return BroadcastRegistry.get(selection);
+        }
+    }
+    catch {
+        // best-effort
+    }
+    // Fallback to config lookup (throws on explicit unknown).
+    return broadcastConfig.getDriverConfig(name);
+};
+const sendWithConfig = async (config, channel, event, data) => {
+    const driverName = config.driver;
+    if (driverName === 'inmemory') {
+        return InMemoryDriver.send(undefined, channel, event, data);
+    }
+    if (driverName === 'pusher') {
+        return PusherDriver.send(config, channel, event, data);
+    }
+    if (driverName === 'redis') {
+        return RedisDriver.send(config, channel, event, data);
+    }
+    if (driverName === 'redishttps') {
+        return RedisHttpsDriver.send(config, channel, event, data);
+    }
+    if (driverName === 'http-bridge') {
+        return publishViaHttpBridgeDriver(toHttpBridgeRuntimeConfig(config), normalizePublishInput({ channel, event, data }));
+    }
+    throw ErrorFactory.createConfigError(`Broadcast driver not implemented: ${driverName}`);
+};
+const normalizeDelivery = (value) => {
+    if (value === 'socket' || value === 'driver') {
+        return value;
+    }
+    return 'auto';
+};
+const normalizePublishInput = (input) => {
+    let event = '';
+    if (isNonEmptyString(input.event)) {
+        event = input.event.trim();
+    }
+    else if (isNonEmptyString(input.name)) {
+        event = input.name.trim();
+    }
+    const channels = normalizeChannels(input);
+    if (event === '' || channels.length === 0) {
+        throw ErrorFactory.createValidationError('Broadcast.publish requires event/name and channel/channels.');
+    }
+    return {
+        channels,
+        event,
+        data: input.data ?? {},
+        ...(isNonEmptyString(input.socketId) ? { socketId: input.socketId.trim() } : {}),
+        delivery: normalizeDelivery(input.delivery),
+        ...(isNonEmptyString(input.broadcaster) ? { broadcaster: input.broadcaster.trim() } : {}),
+        ...(input.request === undefined ? {} : { request: input.request }),
+        ...(input.user === undefined ? {} : { user: input.user }),
+    };
+};
+/**
+ * Error codes from publishSocketEventFromServer that represent policy/auth failures.
+ * These must not be swallowed in auto delivery mode — the socket publish policy must
+ * be respected even when a driver fallback is available.
+ */
+const NON_TRANSIENT_SOCKET_ERROR_CODES = new Set([
+    'FORBIDDEN',
+    'UNAUTHORIZED',
+    'VALIDATION_ERROR',
+    'SECURITY_ERROR',
+    'SANITIZER_ERROR',
+]);
+/**
+ * Returns true for authorization/validation/policy errors from the socket module.
+ * Returns false for "socket unavailable" errors (module missing, disabled, connection
+ * failure, config) which are safe to fall back from.
+ */
+const isNonTransientSocketError = (error) => {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    return typeof code === 'string' && NON_TRANSIENT_SOCKET_ERROR_CODES.has(code);
+};
+const tryPublishViaSocket = async (input) => {
+    try {
+        const socketModule = (await import('@zintrust/socket'));
+        const socketResult = await socketModule.publishSocketEventFromServer({
+            channels: input.channels,
+            event: input.event,
+            data: input.data,
+            socketId: input.socketId,
+            request: input.request,
+            user: input.user,
+        });
+        return {
+            result: {
+                ok: true,
+                transport: 'socket',
+                channels: socketResult.channels,
+                event: socketResult.event,
+                deliveries: socketResult.deliveries,
+                result: socketResult,
+            },
+        };
+    }
+    catch (error) {
+        // For authorization/validation/policy errors, rethrow even in auto delivery mode
+        // to prevent bypassing socket publish policy via driver fallback.
+        // Only allow fallback for "socket unavailable" cases (module missing, disabled, connection issues).
+        if (isNonTransientSocketError(error)) {
+            throw error;
+        }
+        return { result: null, error };
+    }
+};
+const tryPublishViaInternalHttp = async (input) => {
+    const config = getInternalPublishConfig();
+    if (config.endpoints.length === 0 || typeof globalThis.fetch !== 'function') {
+        return { result: null };
+    }
+    const payload = {
+        channels: input.channels,
+        event: input.event,
+        data: input.data,
+        ...(input.socketId === undefined ? {} : { socket_id: input.socketId }),
+    };
+    return tryInternalPublishEndpoints(config.endpoints, config.secret, payload);
+};
+const tryPublishViaConfiguredBridge = async (input, config) => {
+    if (config.endpoints.length === 0 || typeof globalThis.fetch !== 'function') {
+        return { result: null };
+    }
+    const payload = {
+        channels: input.channels,
+        event: input.event,
+        data: input.data,
+        ...(input.socketId === undefined ? {} : { socket_id: input.socketId }),
+    };
+    return tryInternalPublishEndpoints(config.endpoints, config.secret, payload);
+};
+const shouldUseAutomaticHttpBridge = (config, input) => {
+    if (input.delivery === 'driver') {
+        return false;
+    }
+    return config.driver === 'inmemory' && isIsolatedWorkerRuntime();
+};
+const toHttpBridgeRuntimeConfig = (config) => {
+    return Object.freeze({
+        url: config.url,
+        secret: config.secret,
+    });
+};
+const publishViaHttpBridgeDriver = async (config, input) => {
+    const bridgeConfig = Object.freeze({
+        endpoints: buildEndpointCandidates([
+            resolveExplicitEndpoint(config.url, resolveBroadcastAppId()),
+        ]),
+        secret: config.secret.trim(),
+    });
+    const bridgeResult = await tryPublishViaConfiguredBridge(input, bridgeConfig);
+    if (bridgeResult.result !== null) {
+        return {
+            ok: true,
+            transport: 'driver',
+            channels: bridgeResult.result.channels,
+            event: bridgeResult.result.event,
+            deliveries: bridgeResult.result.deliveries,
+            driver: 'http-bridge',
+            endpoint: bridgeResult.result.endpoint,
+            result: bridgeResult.result.result,
+        };
+    }
+    if (bridgeResult.error instanceof Error) {
+        throw bridgeResult.error;
+    }
+    throw ErrorFactory.createConfigError('HTTP bridge broadcast driver misconfigured: BROADCAST_BRIDGE_URL is required');
+};
+const tryPublishNonDriverTransports = async (normalized, selectedConfig) => {
+    const attemptedTransports = [];
+    let lastTransportError;
+    if (shouldUseAutomaticHttpBridge(selectedConfig, normalized)) {
+        attemptedTransports.push('internal-http');
+        const bridgeResult = await tryPublishViaConfiguredBridge(normalized, getBridgePublishConfig());
+        if (bridgeResult.result !== null) {
+            return { result: bridgeResult.result, attemptedTransports, lastTransportError };
+        }
+        if (bridgeResult.error !== undefined) {
+            lastTransportError = bridgeResult.error;
+        }
+    }
+    attemptedTransports.push('internal-http');
+    const internalHttpResult = await tryPublishViaInternalHttp(normalized);
+    if (internalHttpResult.result !== null) {
+        return { result: internalHttpResult.result, attemptedTransports, lastTransportError };
+    }
+    if (internalHttpResult.error !== undefined) {
+        lastTransportError = internalHttpResult.error;
+    }
+    attemptedTransports.push('socket');
+    const socketResult = await tryPublishViaSocket(normalized);
+    if (socketResult.result !== null) {
+        return { result: socketResult.result, attemptedTransports, lastTransportError };
+    }
+    if (socketResult.error !== undefined) {
+        lastTransportError = socketResult.error;
+        logTransportFallback('socket', {
+            error: describeError(socketResult.error),
+        });
+    }
+    return { result: null, attemptedTransports, lastTransportError };
+};
+const publishWithConfig = async (config, broadcasterName, input) => {
+    if (config.driver === 'http-bridge') {
+        return {
+            ...(await publishViaHttpBridgeDriver(toHttpBridgeRuntimeConfig(config), input)),
+            ...(broadcasterName === undefined ? {} : { broadcaster: broadcasterName }),
+        };
+    }
+    const results = await Promise.all(input.channels.map(async (channel) => sendWithConfig(config, channel, input.event, input.data)));
+    return {
+        ok: true,
+        transport: 'driver',
+        channels: input.channels,
+        event: input.event,
+        driver: config.driver,
+        ...(broadcasterName === undefined ? {} : { broadcaster: broadcasterName }),
+        ...(results.length === 1 ? { result: results[0] } : { results }),
+    };
+};
+const publishInternal = async (input) => {
+    const normalized = normalizePublishInput(input);
+    const selectedConfig = await resolveBroadcasterConfig(normalized.broadcaster);
+    const autoTransportResult = normalized.delivery === 'driver'
+        ? { result: null, attemptedTransports: [] }
+        : await tryPublishNonDriverTransports(normalized, selectedConfig);
+    if (autoTransportResult.result !== null) {
+        return {
+            ...autoTransportResult.result,
+            attemptedTransports: autoTransportResult.attemptedTransports,
+        };
+    }
+    if (normalized.delivery === 'socket') {
+        // Socket delivery was forced but the socket transport is unavailable
+        // (e.g. worker-runtime env missing SOCKET_ENABLED / PUSHER_APP_KEY).
+        // Fall through to the configured driver instead of dropping the event,
+        // matching the recoverable-error handling that auto mode already implements.
+        const socketError = autoTransportResult.lastTransportError instanceof Error
+            ? autoTransportResult.lastTransportError
+            : undefined;
+        logTransportFallback('socket', {
+            error: describeError(socketError),
+            attemptedTransports: autoTransportResult.attemptedTransports,
+        });
+    }
+    const attemptedTransports = [
+        ...autoTransportResult.attemptedTransports,
+        'driver',
+    ];
+    return {
+        ...(await publishWithConfig(selectedConfig, normalized.broadcaster, normalized)),
+        attemptedTransports,
+    };
+};
+const publishLaterInternal = async (input, options = {}) => {
+    const normalized = normalizePublishInput(input);
+    const { queueName = 'broadcasts', timestamp = Date.now() } = options;
+    const { Queue } = await import('../queue/Queue.js');
+    const payload = {
+        type: 'broadcast',
+        channel: normalized.channels[0],
+        channels: normalized.channels,
+        event: normalized.event,
+        data: normalized.data,
+        ...(normalized.socketId === undefined ? {} : { socketId: normalized.socketId }),
+        ...(normalized.broadcaster === undefined ? {} : { broadcaster: normalized.broadcaster }),
+        delivery: normalized.delivery,
+        timestamp,
+        attempts: 0,
+    };
+    Logger.debug('Broadcast queued publish prepared', {
+        queueName,
+        channels: payload.channels,
+        compatibilityChannel: payload.channel,
+        event: payload.event,
+        delivery: payload.delivery,
+        broadcaster: payload.broadcaster,
+        timestamp: payload.timestamp,
+    });
+    return Queue.enqueue(queueName, payload);
+};
+export const Broadcast = Object.freeze({
+    async publish(input) {
+        return publishInternal(input);
+    },
+    async send(channel, event, data) {
+        const result = await publishInternal({ channel, event, data });
+        if (result.transport === 'driver') {
+            return result.result ?? result.results ?? result;
+        }
+        return result.result ?? result;
+    },
+    // Alias for send() - explicit intent for immediate broadcast
+    async broadcastNow(channel, event, data) {
+        return this.send(channel, event, data);
+    },
+    async publishLater(input, options = {}) {
+        return publishLaterInternal(input, options);
+    },
+    // Queue broadcast for async processing
+    async BroadcastLater(channel, event, data, options = {}) {
+        return publishLaterInternal({ channel, event, data }, options);
+    },
+    queue(queueName) {
+        return Object.freeze({
+            publishLater: async (input, options = {}) => publishLaterInternal(input, { ...options, queueName }),
+            BroadcastLater: async (channel, event, data, options = {}) => publishLaterInternal({ channel, event, data }, { ...options, queueName }),
+        });
+    },
+    broadcaster(name) {
+        return Object.freeze({
+            send: async (channel, event, data) => {
+                const result = await publishWithConfig(await resolveBroadcasterConfig(name), name, normalizePublishInput({ channel, event, data, delivery: 'driver', broadcaster: name }));
+                return result.result ?? result.results ?? result;
+            },
+            publish: async (input) => {
+                return publishWithConfig(await resolveBroadcasterConfig(name), name, normalizePublishInput({ ...input, delivery: 'driver', broadcaster: name }));
+            },
+        });
+    },
+});
+export default Broadcast;

package/src/tools/broadcast/BroadcastRegistry.d.ts

@@ -0,0 +1,15 @@
+import type { KnownBroadcastDriverConfig } from '../../config/type.js';
+declare function register(name: string, config: KnownBroadcastDriverConfig): void;
+declare function get(name: string): KnownBroadcastDriverConfig;
+declare function has(name: string): boolean;
+declare function list(): string[];
+declare function reset(): void;
+export declare const BroadcastRegistry: Readonly<{
+    register: typeof register;
+    get: typeof get;
+    has: typeof has;
+    list: typeof list;
+    reset: typeof reset;
+}>;
+export {};
+//# sourceMappingURL=BroadcastRegistry.d.ts.map