@fluojs/discord 1.0.0-beta.1

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+import type { AsyncModuleOptions, MaybePromise } from '@fluojs/core';
+import type { NotificationDispatchRequest } from '@fluojs/notifications';
+/** Opaque Discord embed object forwarded to one transport implementation. */
+export type DiscordEmbed = Readonly<Record<string, unknown>>;
+/** Opaque Discord component object forwarded to one transport implementation. */
+export type DiscordComponent = Readonly<Record<string, unknown>>;
+/** Opaque Discord attachment object forwarded to one transport implementation. */
+export type DiscordAttachment = Readonly<Record<string, unknown>>;
+/** Opaque Discord poll object forwarded to one transport implementation. */
+export type DiscordPoll = Readonly<Record<string, unknown>>;
+/** Opaque Discord allowed-mentions object forwarded to one transport implementation. */
+export type DiscordAllowedMentions = Readonly<Record<string, unknown>>;
+/** Caller-supplied Discord message shape used for standalone delivery. */
+export interface DiscordMessage {
+    allowedMentions?: DiscordAllowedMentions;
+    attachments?: readonly DiscordAttachment[];
+    avatarUrl?: string;
+    components?: readonly DiscordComponent[];
+    content?: string;
+    embeds?: readonly DiscordEmbed[];
+    flags?: number;
+    metadata?: Record<string, unknown>;
+    poll?: DiscordPoll;
+    threadId?: string;
+    threadName?: string;
+    tts?: boolean;
+    username?: string;
+}
+/** Normalized Discord message passed to one transport implementation. */
+export interface NormalizedDiscordMessage {
+    allowedMentions?: DiscordAllowedMentions;
+    attachments: readonly DiscordAttachment[];
+    avatarUrl?: string;
+    components: readonly DiscordComponent[];
+    content?: string;
+    embeds: readonly DiscordEmbed[];
+    flags?: number;
+    metadata?: Record<string, unknown>;
+    poll?: DiscordPoll;
+    threadId?: string;
+    threadName?: string;
+    tts?: boolean;
+    username?: string;
+}
+/** Context object forwarded to transport implementations per delivery attempt. */
+export interface DiscordTransportContext {
+    signal?: AbortSignal;
+}
+/** Provider-specific receipt returned by one Discord transport. */
+export interface DiscordTransportReceipt {
+    channelId?: string;
+    guildId?: string;
+    messageId?: string;
+    metadata?: Record<string, unknown>;
+    ok?: boolean;
+    response?: string;
+    statusCode?: number;
+    threadId?: string;
+    warnings?: readonly string[];
+}
+/** Transport contract implemented by runtime-specific or provider-specific Discord adapters. */
+export interface DiscordTransport {
+    /**
+     * Sends one normalized Discord message.
+     *
+     * @param message Normalized message with resolved defaults and one target webhook/thread route.
+     * @param context Optional abort context propagated from the caller.
+     * @returns Provider-specific receipt details normalized for the Fluo Discord contract.
+     */
+    send(message: NormalizedDiscordMessage, context: DiscordTransportContext): Promise<DiscordTransportReceipt>;
+    /**
+     * Verifies transport readiness during bootstrap when configured.
+     *
+     * @returns A promise that resolves when the transport is ready for delivery.
+     */
+    verify?(): MaybePromise<void>;
+    /**
+     * Closes underlying transport resources during application shutdown.
+     *
+     * @returns A promise that resolves when resource cleanup completes.
+     */
+    close?(): MaybePromise<void>;
+}
+/** Factory used to construct a transport lazily during module bootstrap. */
+export interface DiscordTransportFactory {
+    /**
+     * Creates the transport instance used by {@link DiscordService}.
+     *
+     * @returns The transport implementation that will own Discord delivery.
+     */
+    create(): MaybePromise<DiscordTransport>;
+    /**
+     * Stable diagnostic label describing the injected transport kind.
+     *
+     * @remarks
+     * This value is surfaced through platform status snapshots so applications can
+     * tell which adapter is currently wired without the package hard-coding a
+     * provider-specific runtime dependency.
+     */
+    kind?: string;
+    /**
+     * Declares whether the factory-created transport owns resources that the package should close.
+     *
+     * @remarks
+     * Factories default to `true` because they typically allocate the transport instance.
+     * Directly injected transport instances default to `false` because the caller owns them.
+     */
+    ownsResources?: boolean;
+}
+/** Minimal fetch-compatible response contract used by the built-in webhook transport helper. */
+export interface DiscordFetchResponse {
+    ok: boolean;
+    status: number;
+    statusText?: string;
+    text(): MaybePromise<string>;
+}
+/** Minimal fetch-compatible function signature used by the built-in webhook transport helper. */
+export type DiscordFetchLike = (input: string, init?: {
+    body?: string;
+    headers?: Readonly<Record<string, string>>;
+    method?: string;
+    signal?: AbortSignal;
+}) => MaybePromise<DiscordFetchResponse>;
+/** Options accepted by {@link createDiscordWebhookTransport}. */
+export interface DiscordWebhookTransportOptions {
+    fetch?: DiscordFetchLike;
+    wait?: boolean;
+    webhookUrl: string;
+}
+/** Template render input used for `NotificationDispatchRequest.template` integration. */
+export interface DiscordTemplateRenderInput<TPayload extends DiscordNotificationPayload = DiscordNotificationPayload> {
+    locale?: string;
+    metadata?: Record<string, unknown>;
+    payload: TPayload;
+    subject?: string;
+    template: string;
+}
+/** Render result returned by an optional Discord template renderer. */
+export interface DiscordTemplateRenderResult {
+    components?: readonly DiscordComponent[];
+    content?: string;
+    embeds?: readonly DiscordEmbed[];
+}
+/** Optional renderer used to turn notification templates into concrete Discord content. */
+export interface DiscordTemplateRenderer {
+    /**
+     * Renders one notification template into Discord content and/or embed fragments.
+     *
+     * @typeParam TPayload Payload shape carried by the notification request.
+     * @param input Template render input including the template key and opaque payload.
+     * @returns Rendered content or embed fragments that are merged with explicit payload overrides.
+     */
+    render<TPayload extends DiscordNotificationPayload = DiscordNotificationPayload>(input: DiscordTemplateRenderInput<TPayload>): MaybePromise<DiscordTemplateRenderResult>;
+}
+/** Notification payload understood by {@link DiscordChannel} and {@link DiscordService.sendNotification}. */
+export interface DiscordNotificationPayload extends Record<string, unknown> {
+    allowedMentions?: DiscordAllowedMentions;
+    attachments?: readonly DiscordAttachment[];
+    avatarUrl?: string;
+    components?: readonly DiscordComponent[];
+    content?: string;
+    embeds?: readonly DiscordEmbed[];
+    flags?: number;
+    metadata?: Record<string, unknown>;
+    poll?: DiscordPoll;
+    threadId?: string;
+    threadName?: string;
+    tts?: boolean;
+    username?: string;
+}
+/** Shared notification request subtype consumed by the Discord channel implementation. */
+export interface DiscordNotificationDispatchRequest extends NotificationDispatchRequest<DiscordNotificationPayload> {
+    channel: string;
+}
+/** Caller-visible result returned by standalone and notification-backed Discord delivery. */
+export interface DiscordSendResult extends DiscordTransportReceipt {
+    ok: boolean;
+    warnings: readonly string[];
+}
+/** Failure entry returned by tolerant batch delivery. */
+export interface DiscordSendFailure {
+    error: Error;
+    message: DiscordMessage;
+}
+/** Summary returned by {@link DiscordService.sendMany}. */
+export interface DiscordSendBatchResult {
+    failed: number;
+    failures: readonly DiscordSendFailure[];
+    results: readonly DiscordSendResult[];
+    succeeded: number;
+}
+/** Additional send controls applied to one Discord delivery attempt. */
+export interface DiscordSendOptions {
+    signal?: AbortSignal;
+}
+/** Additional controls applied to one batch send operation. */
+export interface DiscordSendManyOptions extends DiscordSendOptions {
+    continueOnError?: boolean;
+}
+/** Module options accepted by {@link DiscordModule.forRoot} and `forRootAsync`. */
+export interface DiscordModuleOptions {
+    defaultThreadId?: string;
+    notifications?: {
+        channel?: string;
+    };
+    renderer?: DiscordTemplateRenderer;
+    transport: DiscordTransport | DiscordTransportFactory;
+    verifyOnModuleInit?: boolean;
+}
+/** Async registration options for Discord modules that derive config through DI. */
+export type DiscordAsyncModuleOptions = AsyncModuleOptions<DiscordModuleOptions>;
+/** Normalized module options resolved once during module registration. */
+export interface NormalizedDiscordModuleOptions {
+    defaultThreadId?: string;
+    notifications: {
+        channel: string;
+    };
+    renderer?: DiscordTemplateRenderer;
+    transport: {
+        create: () => Promise<DiscordTransport>;
+        kind: string;
+        ownsResources: boolean;
+    };
+    verifyOnModuleInit: boolean;
+}
+/** Discord facade exposed to application code and the compatibility token. */
+export interface Discord {
+    /**
+     * Sends one Discord message directly through the configured transport.
+     *
+     * @param message Caller-supplied Discord message with content, embeds, or component payloads.
+     * @param options Optional abort signal propagated to the transport.
+     * @returns A normalized delivery receipt describing the transport response.
+     */
+    send(message: DiscordMessage, options?: DiscordSendOptions): Promise<DiscordSendResult>;
+    /**
+     * Sends multiple Discord messages in input order with optional tolerant failure handling.
+     *
+     * @param messages Ordered message list to deliver through the configured transport.
+     * @param options Optional tolerant batch controls such as `continueOnError`.
+     * @returns A batch summary containing successes and any captured failures.
+     */
+    sendMany(messages: readonly DiscordMessage[], options?: DiscordSendManyOptions): Promise<DiscordSendBatchResult>;
+    /**
+     * Converts one notifications foundation request into a concrete Discord delivery.
+     *
+     * @param notification Shared notification envelope interpreted by the Discord package.
+     * @param options Optional abort signal propagated to rendering and transport work.
+     * @returns A normalized delivery receipt for the resulting Discord message.
+     */
+    sendNotification(notification: DiscordNotificationDispatchRequest, options?: DiscordSendOptions): Promise<DiscordSendResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhook.d.ts

@@ -0,0 +1,19 @@
+import type { DiscordTransport, DiscordWebhookTransportOptions } from './types.js';
+/**
+ * Creates a webhook-first Discord transport backed by an explicit fetch-compatible boundary.
+ *
+ * @param options Webhook URL plus an optional injected fetch implementation for portable runtimes.
+ * @returns A Discord transport that posts JSON payloads to one Discord webhook endpoint.
+ * @throws {DiscordConfigurationError} When the webhook url is empty or no fetch implementation is available.
+ * @throws {DiscordTransportError} When Discord responds with a non-success HTTP status.
+ *
+ * @example
+ * ```ts
+ * const transport = createDiscordWebhookTransport({
+ *   fetch: runtime.fetch,
+ *   webhookUrl: 'https://discord.com/api/webhooks/123/abc',
+ * });
+ * ```
+ */
+export declare function createDiscordWebhookTransport(options: DiscordWebhookTransportOptions): DiscordTransport;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,gBAAgB,EAEhB,8BAA8B,EAE/B,MAAM,YAAY,CAAC;AAiIpB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,gBAAgB,CAyEvG"}

package/dist/webhook.js

@@ -0,0 +1,200 @@
+import { DiscordConfigurationError, DiscordTransportError } from './errors.js';
+const DEFAULT_RETRY_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 250;
+function normalizeOptionalString(value) {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+function getStringField(body, key) {
+  const value = body?.[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function createWebhookPayload(message) {
+  return {
+    ...(message.allowedMentions ? {
+      allowed_mentions: message.allowedMentions
+    } : {}),
+    ...(message.attachments.length > 0 ? {
+      attachments: message.attachments
+    } : {}),
+    ...(message.avatarUrl ? {
+      avatar_url: message.avatarUrl
+    } : {}),
+    ...(message.components.length > 0 ? {
+      components: message.components
+    } : {}),
+    ...(message.content ? {
+      content: message.content
+    } : {}),
+    ...(message.embeds.length > 0 ? {
+      embeds: message.embeds
+    } : {}),
+    ...(typeof message.flags === 'number' ? {
+      flags: message.flags
+    } : {}),
+    ...(message.poll ? {
+      poll: message.poll
+    } : {}),
+    ...(message.threadName ? {
+      thread_name: message.threadName
+    } : {}),
+    ...(typeof message.tts === 'boolean' ? {
+      tts: message.tts
+    } : {}),
+    ...(message.username ? {
+      username: message.username
+    } : {})
+  };
+}
+function resolveFetch(fetchLike) {
+  if (fetchLike) {
+    return fetchLike;
+  }
+  if (typeof globalThis.fetch !== 'function') {
+    throw new DiscordConfigurationError('Discord webhook transport requires an explicit fetch implementation when `globalThis.fetch` is unavailable.');
+  }
+  return (input, init) => globalThis.fetch(input, init);
+}
+function parseWebhookUrl(webhookUrl) {
+  try {
+    return new URL(webhookUrl);
+  } catch {
+    throw new DiscordConfigurationError('Discord webhook transport requires a valid absolute `webhookUrl`.');
+  }
+}
+function resolveWebhookUrl(webhookUrl, message, wait) {
+  const url = new URL(webhookUrl.toString());
+  url.searchParams.set('wait', String(wait));
+  if (message.threadId) {
+    url.searchParams.set('thread_id', message.threadId);
+  }
+  return url.toString();
+}
+async function readResponseBody(response) {
+  try {
+    return await response.text();
+  } catch {
+    return '';
+  }
+}
+function createStatusFailureMessage(response, attempt) {
+  return `Discord webhook delivery failed with status ${response.status}${response.statusText ? ` ${response.statusText}` : ''} after ${String(attempt)} attempt(s). Upstream response body was omitted from the caller-visible error.`;
+}
+function createTransportFailureMessage(attempt) {
+  return `Discord webhook delivery failed after ${String(attempt)} attempt(s). Upstream response details were omitted from the caller-visible error.`;
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === 'AbortError';
+}
+function isTransientStatus(status) {
+  return status === 408 || status === 429 || status >= 500 && status <= 599;
+}
+async function waitForRetry(delayMs, signal) {
+  if (delayMs <= 0) {
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, delayMs);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+    }
+    if (signal) {
+      signal.addEventListener('abort', onAbort, {
+        once: true
+      });
+    }
+  });
+}
+function parseJsonRecord(body) {
+  if (!body) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(body);
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Creates a webhook-first Discord transport backed by an explicit fetch-compatible boundary.
+ *
+ * @param options Webhook URL plus an optional injected fetch implementation for portable runtimes.
+ * @returns A Discord transport that posts JSON payloads to one Discord webhook endpoint.
+ * @throws {DiscordConfigurationError} When the webhook url is empty or no fetch implementation is available.
+ * @throws {DiscordTransportError} When Discord responds with a non-success HTTP status.
+ *
+ * @example
+ * ```ts
+ * const transport = createDiscordWebhookTransport({
+ *   fetch: runtime.fetch,
+ *   webhookUrl: 'https://discord.com/api/webhooks/123/abc',
+ * });
+ * ```
+ */
+export function createDiscordWebhookTransport(options) {
+  const webhookUrl = normalizeOptionalString(options.webhookUrl);
+  if (!webhookUrl) {
+    throw new DiscordConfigurationError('Discord webhook transport requires a non-empty `webhookUrl`.');
+  }
+  const parsedWebhookUrl = parseWebhookUrl(webhookUrl);
+  const fetchLike = resolveFetch(options.fetch);
+  const wait = options.wait ?? true;
+  return {
+    async send(message, context) {
+      for (let attempt = 1; attempt <= DEFAULT_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+          const response = await fetchLike(resolveWebhookUrl(parsedWebhookUrl, message, wait), {
+            body: JSON.stringify(createWebhookPayload(message)),
+            headers: {
+              'content-type': 'application/json; charset=utf-8'
+            },
+            method: 'POST',
+            signal: context.signal
+          });
+          const body = await readResponseBody(response);
+          if (!response.ok) {
+            if (attempt < DEFAULT_RETRY_ATTEMPTS && isTransientStatus(response.status)) {
+              await waitForRetry(DEFAULT_RETRY_DELAY_MS * 2 ** (attempt - 1), context.signal);
+              continue;
+            }
+            throw new DiscordTransportError(createStatusFailureMessage(response, attempt));
+          }
+          const parsed = parseJsonRecord(body);
+          const warnings = [];
+          if (body && !parsed) {
+            warnings.push('Discord webhook returned a non-JSON success body.');
+          }
+          return {
+            channelId: getStringField(parsed, 'channel_id'),
+            guildId: getStringField(parsed, 'guild_id'),
+            messageId: getStringField(parsed, 'id'),
+            ok: true,
+            response: body || undefined,
+            statusCode: response.status,
+            threadId: getStringField(parsed, 'thread_id') ?? message.threadId,
+            warnings
+          };
+        } catch (error) {
+          if (isAbortError(error) || context.signal?.aborted) {
+            throw error;
+          }
+          if (attempt < DEFAULT_RETRY_ATTEMPTS) {
+            await waitForRetry(DEFAULT_RETRY_DELAY_MS * 2 ** (attempt - 1), context.signal);
+            continue;
+          }
+          if (error instanceof DiscordTransportError) {
+            throw error;
+          }
+          throw new DiscordTransportError(createTransportFailureMessage(attempt));
+        }
+      }
+      throw new DiscordTransportError(createTransportFailureMessage(DEFAULT_RETRY_ATTEMPTS));
+    }
+  };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@fluojs/discord",
+  "description": "Webhook-first, transport-agnostic Discord delivery core for Fluo with notifications integration.",
+  "keywords": [
+    "fluo",
+    "discord",
+    "webhook",
+    "notifications",
+    "portable",
+    "fetch"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/discord"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/notifications": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}