@bozonx/social-posting-discord 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @bozonx/social-posting-discord
+
+Discord support for [`@bozonx/social-posting`](https://www.npmjs.com/package/@bozonx/social-posting).
+Zero runtime dependencies, Web APIs only — it runs on Node, Bun, Deno and Cloudflare Workers.
+
+```bash
+pnpm add @bozonx/social-posting @bozonx/social-posting-discord
+```
+
+```ts
+import { createPostingClient } from '@bozonx/social-posting';
+import { discord } from '@bozonx/social-posting-discord';
+
+const client = createPostingClient({
+  platforms: [discord],
+  accounts: {
+    announcements: {
+      platform: 'discord',
+      auth: { webhookUrl: process.env.DISCORD_WEBHOOK_URL },
+    },
+  },
+});
+
+await client.post({ platform: 'discord', account: 'announcements', body: 'Ship it.' });
+```
+
+## Two access models, and why the difference matters
+
+Discord is the only network in this set where the credential and the destination can be the same
+string. Pick one per account; an account carrying both is refused rather than guessed at.
+
+|                               | `webhookUrl`                                                    | `botToken`                                                                                 |
+| ----------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Setup                         | Server settings → Integrations. No OAuth, no app review.        | A registered application, invited to the server with `Send Messages` (and `Attach Files`). |
+| Destination                   | **Baked into the URL.** No `target` needed.                     | `target.id` is the channel id, and it is required.                                         |
+| Replies                       | No.                                                             | Yes, via `inReplyTo`.                                                                      |
+| Name and avatar               | Overridable per message (`extra.username`, `extra.avatar_url`). | Fixed, the bot's own.                                                                      |
+| Deletes its own messages      | Yes, through the webhook token.                                 | Yes, by channel and message id.                                                            |
+| Reads the server's boost tier | No — keeps the unboosted attachment limit.                      | Yes, through `resolveCapabilities()`.                                                      |
+
+**A webhook URL is a secret, not a channel id.** Anyone holding it can post to that channel.
+Store it the way you store a token, never in a column named `channelId`.
+
+## Addressing
+
+The channel is `target.id`. Two further parts are declared in `capabilities.targetSchema`:
+
+```ts
+target: {
+  id: '1290000000000000002',      // channel id
+  guildId: '1280000000000000003', // server: used for permalinks and boost-tier limits
+  threadId: '1295000000000000007' // optional: post into a thread of that channel
+}
+```
+
+A scalar `target` is accepted as shorthand for `{ id }`, but then no permalink can be built:
+Discord message URLs contain the server id.
+
+## What it publishes
+
+| Type                                  | Support                                                           |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| `post`                                | Up to 2 000 characters, Discord-flavoured Markdown.               |
+| `image`, `video`, `audio`, `document` | One attachment, uploaded as `multipart/form-data`.                |
+| `album`                               | Up to 10 attachments of any mix.                                  |
+| `poll`                                | Native poll: `title` is the question, `poll.options` the answers. |
+
+Not supported, because Discord has no such product: `shortVideo`, `story`, `article`, scheduling
+and drafts. A vertical video is an ordinary attachment.
+
+### Media
+
+Discord never fetches a URL — every file is uploaded to it. A `url` source still works: this
+adapter downloads it first, which is why the declared transport is `both`. The URL therefore has
+to be reachable from **your** process, not from Discord, and no signed-URL lifetime requirement
+applies.
+
+Set `sensitive: true` on a media item to spoiler it. Discord has no flag for this: the adapter
+prefixes the file name with `SPOILER_`, which is the mechanism Discord actually uses.
+`altText` becomes the attachment description (max 1 024 characters).
+
+### Attachment size is a property of the server
+
+The shipped descriptor states the **unboosted** ceiling of 10 MiB. The real ceiling rises with the
+server's boost tier, so a bot-token account should ask before publishing:
+
+```ts
+const resolved = await platform.resolveCapabilities(accountConfig);
+// resolved.capabilities.media.video.maxBytes  → 10 / 50 / 100 MiB by boost tier
+// resolved.cacheableForSecs                   → 3600
+```
+
+The library caches nothing: it hands the reading back with a lifetime and your host decides where
+it lives. A webhook account cannot read the server and keeps the floor.
+
+## Platform options (`extra`)
+
+`embeds`, `tts`, `flags`, `allowed_mentions`, `components`, plus `username` and `avatar_url` for
+webhook accounts only. Keys the adapter builds itself — `content`, `attachments`, `poll`,
+`message_reference` — are refused rather than silently overwritten.
+
+## Errors
+
+| Code               | When                                                                     |
+| ------------------ | ------------------------------------------------------------------------ |
+| `RATE_LIMIT_ERROR` | 429, carrying Discord's own `retry_after` as `retryAfterMs`.             |
+| `AUTH_ERROR`       | 401 (token rejected) and 403 (the bot lacks permission in this channel). |
+| `VALIDATION_ERROR` | Unknown channel or deleted webhook (404), and malformed requests.        |
+| `CONTENT_REJECTED` | An attachment or embed Discord refuses (400 with code 50035, 413).       |
+| `PLATFORM_ERROR`   | 5xx, retryable.                                                          |
+
+Publishing is a single call, so there is no resume handle and no `processing` state.
+
+## A product note
+
+Discord is an announcement channel, not a social network. There are no impressions, no reach and
+no post analytics behind a message. Label it accordingly in your UI, or users will expect numbers
+that do not exist.
+
+## Sources
+
+- [Create Message](https://docs.discord.com/developers/resources/message#create-message)
+- [Execute Webhook](https://docs.discord.com/developers/resources/webhook#execute-webhook)
+- [Uploading files](https://docs.discord.com/developers/reference#uploading-files)
+
+## License
+
+MIT

package/dist/capabilities.d.ts

@@ -0,0 +1,33 @@
+import type { PlatformCapabilities } from '@bozonx/social-posting';
+/** Largest message content Discord accepts. */
+export declare const MAX_MESSAGE_LENGTH = 2000;
+/** Largest number of attachments one message may carry. */
+export declare const MAX_ATTACHMENTS = 10;
+/** Longest attachment description (alt text). */
+export declare const MAX_ALT_TEXT_LENGTH = 1024;
+/**
+ * Attachment size ceiling for a server with no boost.
+ *
+ * A floor, not a fact: the real ceiling rises with the guild's boost tier, and
+ * `resolveCapabilities()` reads it per account. Declaring the highest tier here
+ * would let the library promise an upload most servers refuse.
+ */
+export declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/** Attachment ceiling per guild premium tier, in bytes. */
+export declare const ATTACHMENT_BYTES_BY_BOOST_TIER: Record<number, number>;
+/** Discord poll limits. */
+export declare const MAX_POLL_ANSWERS = 10;
+export declare const MAX_POLL_ANSWER_LENGTH = 55;
+export declare const MAX_POLL_QUESTION_LENGTH = 300;
+/** Polls run for whole hours, from one hour to 32 days. */
+export declare const MIN_POLL_DURATION_SECS = 3600;
+export declare const MAX_POLL_DURATION_SECS: number;
+/**
+ * What Discord accepts, stated as data.
+ *
+ * Two things here are deliberately absent. There is no `shortVideo` or `story`:
+ * Discord has no such product, and a vertical video is an ordinary attachment.
+ * And `maxBytes` is the unboosted floor, because the real ceiling is a property
+ * of the server rather than of the network.
+ */
+export declare const discordCapabilities: PlatformCapabilities;

package/dist/capabilities.js

@@ -0,0 +1,211 @@
+import { PostType } from '@bozonx/social-posting';
+/** Largest message content Discord accepts. */
+export const MAX_MESSAGE_LENGTH = 2_000;
+/** Largest number of attachments one message may carry. */
+export const MAX_ATTACHMENTS = 10;
+/** Longest attachment description (alt text). */
+export const MAX_ALT_TEXT_LENGTH = 1_024;
+const MIB_BYTES = 1024 * 1024;
+/**
+ * Attachment size ceiling for a server with no boost.
+ *
+ * A floor, not a fact: the real ceiling rises with the guild's boost tier, and
+ * `resolveCapabilities()` reads it per account. Declaring the highest tier here
+ * would let the library promise an upload most servers refuse.
+ */
+export const DEFAULT_MAX_ATTACHMENT_BYTES = 10 * MIB_BYTES;
+/** Attachment ceiling per guild premium tier, in bytes. */
+export const ATTACHMENT_BYTES_BY_BOOST_TIER = {
+    0: 10 * MIB_BYTES,
+    1: 10 * MIB_BYTES,
+    2: 50 * MIB_BYTES,
+    3: 100 * MIB_BYTES,
+};
+/** Discord poll limits. */
+export const MAX_POLL_ANSWERS = 10;
+export const MAX_POLL_ANSWER_LENGTH = 55;
+export const MAX_POLL_QUESTION_LENGTH = 300;
+/** Polls run for whole hours, from one hour to 32 days. */
+export const MIN_POLL_DURATION_SECS = 3_600;
+export const MAX_POLL_DURATION_SECS = 768 * 3_600;
+/**
+ * Discord never fetches a URL: every file is uploaded to it as
+ * `multipart/form-data`. A `url` source is still accepted because this adapter
+ * downloads it first — which is why the transport is `both` rather than `push`,
+ * and why `requiresPubliclyFetchableUrl` is absent: the URL has to be reachable
+ * from this process, not from Discord.
+ */
+const attachment = {
+    acceptedSources: ['url', 'bytes', 'blob', 'stream'],
+    transport: 'both',
+    maxBytes: DEFAULT_MAX_ATTACHMENT_BYTES,
+};
+/**
+ * What Discord accepts, stated as data.
+ *
+ * Two things here are deliberately absent. There is no `shortVideo` or `story`:
+ * Discord has no such product, and a vertical video is an ordinary attachment.
+ * And `maxBytes` is the unboosted floor, because the real ceiling is a property
+ * of the server rather than of the network.
+ */
+export const discordCapabilities = {
+    name: 'discord',
+    displayName: 'Discord',
+    sources: [
+        {
+            url: 'https://docs.discord.com/developers/resources/message#create-message',
+            supports: ['message content limit', 'attachment count', 'poll object'],
+            verifiedAt: '2026-08-30',
+        },
+        {
+            url: 'https://docs.discord.com/developers/resources/webhook#execute-webhook',
+            supports: ['webhook execution', 'thread_id', 'wait parameter'],
+            verifiedAt: '2026-08-30',
+        },
+        {
+            url: 'https://docs.discord.com/developers/reference#uploading-files',
+            supports: ['multipart/form-data attachment upload', 'attachment descriptions'],
+            verifiedAt: '2026-08-30',
+        },
+    ],
+    postTypes: {
+        [PostType.POST]: {
+            requiredFields: ['body'],
+            forbiddenFields: ['media', 'poll'],
+        },
+        [PostType.IMAGE]: {
+            requiredFields: ['media'],
+            minMediaCount: 1,
+            maxMediaCount: 1,
+            mediaCounts: { image: { min: 1, max: 1 } },
+        },
+        [PostType.VIDEO]: {
+            requiredFields: ['media'],
+            minMediaCount: 1,
+            maxMediaCount: 1,
+            mediaCounts: { video: { min: 1, max: 1 } },
+        },
+        [PostType.SHORT_VIDEO]: {
+            requiredFields: ['media'],
+            minMediaCount: 1,
+            maxMediaCount: 1,
+            mediaCounts: { video: { min: 1, max: 1 } },
+        },
+        [PostType.AUDIO]: {
+            requiredFields: ['media'],
+            minMediaCount: 1,
+            maxMediaCount: 1,
+            mediaCounts: { audio: { min: 1, max: 1 } },
+        },
+        [PostType.DOCUMENT]: {
+            requiredFields: ['media'],
+            minMediaCount: 1,
+            maxMediaCount: 1,
+            mediaCounts: { document: { min: 1, max: 1 } },
+        },
+        [PostType.ALBUM]: {
+            requiredFields: ['media'],
+            minMediaCount: 2,
+            maxMediaCount: MAX_ATTACHMENTS,
+            // One message carries any mix of files; Discord draws no distinction.
+            allowsMixedMedia: true,
+        },
+        [PostType.POLL]: {
+            requiredFields: ['poll'],
+            forbiddenFields: ['media'],
+        },
+    },
+    maxBodyLength: MAX_MESSAGE_LENGTH,
+    bodyLengthRule: {},
+    // Discord renders its own Markdown flavour; HTML is not a thing there.
+    supportedBodyFormats: ['text', 'md'],
+    targetBodyFormat: 'md',
+    media: {
+        image: { ...attachment, acceptedSources: [...attachment.acceptedSources] },
+        video: { ...attachment, acceptedSources: [...attachment.acceptedSources] },
+        audio: { ...attachment, acceptedSources: [...attachment.acceptedSources] },
+        document: { ...attachment, acceptedSources: [...attachment.acceptedSources] },
+    },
+    altText: { supported: true, maxLength: MAX_ALT_TEXT_LENGTH },
+    // Discord has no per-message spoiler flag: a spoilered attachment is one
+    // whose file name starts with `SPOILER_`.
+    sensitive: { supportedValues: [false, true], default: false },
+    // The channel is `target.id`. A guild id is not part of the address Discord
+    // needs — the channel is globally unique — but it is what a permalink and the
+    // boost-tier lookup are built from, so it is part of the address we keep.
+    targetSchema: [
+        {
+            name: 'guildId',
+            type: 'string',
+            pattern: '^[0-9]{5,25}$',
+            label: 'Server id',
+            description: 'Guild the channel belongs to. Used for permalinks and boost-tier limits.',
+        },
+        {
+            name: 'threadId',
+            type: 'string',
+            pattern: '^[0-9]{5,25}$',
+            label: 'Thread id',
+            description: 'Post into a thread of the channel rather than the channel itself.',
+        },
+    ],
+    poll: {
+        minOptions: 1,
+        maxOptions: MAX_POLL_ANSWERS,
+        maxOptionLength: MAX_POLL_ANSWER_LENGTH,
+        minDurationSecs: MIN_POLL_DURATION_SECS,
+        maxDurationSecs: MAX_POLL_DURATION_SECS,
+        multiple: { supportedValues: [false, true], default: false },
+        anonymous: { supportedValues: [false] },
+    },
+    supportsReply: true,
+    supportsRepost: false,
+    supportsQuote: false,
+    extraFields: [
+        { name: 'embeds', type: 'object', label: 'Embeds', description: 'Discord embed objects.' },
+        { name: 'tts', type: 'boolean' },
+        { name: 'flags', type: 'number' },
+        { name: 'allowed_mentions', type: 'object' },
+        { name: 'components', type: 'object' },
+        {
+            name: 'username',
+            type: 'string',
+            label: 'Override name',
+            description: 'Webhook only: the name the message is posted under.',
+        },
+        {
+            name: 'avatar_url',
+            type: 'string',
+            label: 'Override avatar',
+            description: 'Webhook only: the avatar the message is posted with.',
+        },
+    ],
+    allowUnknownExtraFields: false,
+    auth: {
+        kind: 'apiKey',
+        // A webhook URL carries its own destination, so a target is not universally
+        // required; `validateExtra()` requires one for bot-token accounts.
+        requiresTarget: false,
+        docsUrl: 'https://docs.discord.com/developers/resources/webhook#execute-webhook',
+    },
+    rateLimits: {
+        note: 'Per-route buckets; hosts must honour retry_after from 429 responses. Discord does not publish a fixed per-channel message quota.',
+    },
+    supportsNativeScheduling: false,
+    supportsDraft: false,
+    supportsIdempotencyKey: false,
+    supportsDeletion: true,
+    ignoredFields: [
+        'title',
+        'description',
+        'language',
+        'tags',
+        'thumbnail',
+        'visibility',
+        'contentWarning',
+        'commentsEnabled',
+        'location',
+        'repostOf',
+    ],
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

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

package/dist/discord-api.d.ts

@@ -0,0 +1,59 @@
+/** The API version this package speaks, pinned deliberately. */
+export declare const API_VERSION = "v10";
+/** Default API root. Overridable per account through `apiBaseUrl`. */
+export declare const DEFAULT_API_BASE_URL = "https://discord.com/api";
+/** The message object Discord returns, in the fields this adapter reads. */
+export interface DiscordMessage {
+    id: string;
+    channel_id: string;
+    /** Present on webhook responses; absent on bot responses. */
+    guild_id?: string;
+    [key: string]: unknown;
+}
+/** How one request authorizes itself. */
+export type DiscordAuthorization = {
+    kind: 'bot';
+    token: string;
+}
+/** A webhook authorizes by its URL alone; there is no header. */
+ | {
+    kind: 'webhook';
+};
+export interface DiscordRequest {
+    /** Absolute URL to call. */
+    url: string;
+    method: 'POST' | 'DELETE' | 'GET' | 'PATCH';
+    authorization: DiscordAuthorization;
+    /** A JSON body, or a `FormData` when the message carries attachments. */
+    body?: FormData | Record<string, unknown>;
+    signal?: AbortSignal;
+}
+/**
+ * Discord's REST API over plain `fetch`.
+ *
+ * No SDK: discord.js wraps the failure in its own class and loses the HTTP
+ * status, Discord's own numeric code and the `retry_after` this library is
+ * built on — and it will not run on Workers.
+ */
+export declare class DiscordApi {
+    private readonly baseUrl;
+    private readonly timeoutMs?;
+    private readonly fetch?;
+    constructor(options?: {
+        baseUrl?: string;
+        timeoutSeconds?: number;
+        fetch?: typeof fetch;
+    });
+    /** Build an absolute URL for an API path such as `/channels/1/messages`. */
+    endpoint(path: string): string;
+    /**
+     * Perform one API call.
+     *
+     * @param request - Target, method, authorization and body.
+     * @returns The parsed JSON response, or undefined for a `204`.
+     * @throws PlatformError classified by {@link toPlatformError}.
+     */
+    call<T>(request: DiscordRequest): Promise<T | undefined>;
+    /** Combine the caller's signal with the account's own API timeout. */
+    private withTimeout;
+}

package/dist/discord-api.js

@@ -0,0 +1,81 @@
+import { httpRequest } from '@bozonx/social-posting/platform';
+import { toPlatformError } from './discord-error.js';
+/** The API version this package speaks, pinned deliberately. */
+export const API_VERSION = 'v10';
+/** Default API root. Overridable per account through `apiBaseUrl`. */
+export const DEFAULT_API_BASE_URL = 'https://discord.com/api';
+/**
+ * Discord's REST API over plain `fetch`.
+ *
+ * No SDK: discord.js wraps the failure in its own class and loses the HTTP
+ * status, Discord's own numeric code and the `retry_after` this library is
+ * built on — and it will not run on Workers.
+ */
+export class DiscordApi {
+    baseUrl;
+    timeoutMs;
+    fetch;
+    constructor(options = {}) {
+        this.baseUrl = trimTrailingSlash(options.baseUrl ?? DEFAULT_API_BASE_URL);
+        this.timeoutMs =
+            options.timeoutSeconds === undefined ? undefined : options.timeoutSeconds * 1000;
+        this.fetch = options.fetch;
+    }
+    /** Build an absolute URL for an API path such as `/channels/1/messages`. */
+    endpoint(path) {
+        return `${this.baseUrl}/${API_VERSION}${path}`;
+    }
+    /**
+     * Perform one API call.
+     *
+     * @param request - Target, method, authorization and body.
+     * @returns The parsed JSON response, or undefined for a `204`.
+     * @throws PlatformError classified by {@link toPlatformError}.
+     */
+    async call(request) {
+        const headers = {};
+        if (request.authorization.kind === 'bot') {
+            headers.authorization = `Bot ${request.authorization.token}`;
+        }
+        let body;
+        if (request.body instanceof FormData) {
+            // Never set content-type by hand for FormData: the boundary is generated
+            // by the runtime and a hand-written header loses it.
+            body = request.body;
+        }
+        else if (request.body !== undefined) {
+            headers['content-type'] = 'application/json';
+            body = JSON.stringify(request.body);
+        }
+        const response = await httpRequest(request.url, {
+            method: request.method,
+            headers,
+            body,
+            // An attachment upload is a one-shot stream and a mutating call: it must
+            // never be replayed behind the caller's back.
+            replayableBody: !(request.body instanceof FormData),
+            signal: this.withTimeout(request.signal),
+            fetch: this.fetch,
+        });
+        if (!response.ok) {
+            const parsed = (await response.json().catch(() => undefined));
+            throw toPlatformError(response.status, parsed, response.headers.get('retry-after'));
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return (await response.json().catch(() => undefined));
+    }
+    /** Combine the caller's signal with the account's own API timeout. */
+    withTimeout(signal) {
+        if (this.timeoutMs === undefined) {
+            return signal;
+        }
+        const timeout = AbortSignal.timeout(this.timeoutMs);
+        return signal ? AbortSignal.any([signal, timeout]) : timeout;
+    }
+}
+function trimTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+//# sourceMappingURL=discord-api.js.map

package/dist/discord-api.js.map

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

package/dist/discord-auth.validator.d.ts

@@ -0,0 +1,31 @@
+import type { AuthValidation, IAuthValidator } from '@bozonx/social-posting/platform';
+/** The two ways an account may address Discord. */
+export type DiscordAuthMode = 'webhook' | 'bot';
+/** A webhook URL split into the parts every webhook call needs. */
+export interface DiscordWebhookParts {
+    id: string;
+    token: string;
+}
+/**
+ * Validates the shape of Discord credentials.
+ *
+ * Discord is the one network in the set where the credential and the
+ * destination can be the same string: a webhook URL has the guild and channel
+ * baked into it. That is why this validator reports which of the two models an
+ * account uses — the rest of the adapter branches on the answer, and a host
+ * storing a webhook URL must treat it as a secret, not as a channel id.
+ */
+export declare class DiscordAuthValidator implements IAuthValidator {
+    readonly providerName = "discord";
+    validate(auth: Record<string, unknown>): AuthValidation;
+}
+/** Validate Discord auth without constructing an adapter or performing I/O. */
+export declare function validateDiscordAuth(auth: Record<string, unknown>): AuthValidation;
+/**
+ * Split a webhook URL into its id and token.
+ * @param url - The webhook URL from the account credentials.
+ * @returns The parts, or undefined when the URL is not a webhook URL.
+ */
+export declare function parseWebhookUrl(url: string): DiscordWebhookParts | undefined;
+/** Which access model an account's credentials select. */
+export declare function authModeOf(auth: Record<string, unknown>): DiscordAuthMode | undefined;

package/dist/discord-auth.validator.js

@@ -0,0 +1,76 @@
+/** Where a webhook URL lives, and the two ids inside it. */
+const WEBHOOK_URL_PATTERN = /^https:\/\/(?:[a-z0-9-]+\.)?discord(?:app)?\.com\/api(?:\/v\d+)?\/webhooks\/(\d{5,25})\/([\w-]{20,})$/i;
+/** What a bot token looks like: three dot-separated base64url segments. */
+const BOT_TOKEN_PATTERN = /^[\w-]{20,}\.[\w-]{5,}\.[\w-]{20,}$/;
+/**
+ * Validates the shape of Discord credentials.
+ *
+ * Discord is the one network in the set where the credential and the
+ * destination can be the same string: a webhook URL has the guild and channel
+ * baked into it. That is why this validator reports which of the two models an
+ * account uses — the rest of the adapter branches on the answer, and a host
+ * storing a webhook URL must treat it as a secret, not as a channel id.
+ */
+export class DiscordAuthValidator {
+    providerName = 'discord';
+    validate(auth) {
+        return validateDiscordAuth(auth);
+    }
+}
+/** Validate Discord auth without constructing an adapter or performing I/O. */
+export function validateDiscordAuth(auth) {
+    const errors = [];
+    const { webhookUrl, botToken } = auth;
+    const hasWebhook = webhookUrl !== undefined && webhookUrl !== null && webhookUrl !== '';
+    const hasBot = botToken !== undefined && botToken !== null && botToken !== '';
+    if (!hasWebhook && !hasBot) {
+        errors.push("Discord auth requires either 'webhookUrl' or 'botToken'");
+        return { errors };
+    }
+    if (hasWebhook && hasBot) {
+        // Not a convenience: the two models produce different messages, different
+        // permalinks and different delete calls. Guessing between them is worse
+        // than refusing.
+        errors.push("Discord auth must carry exactly one of 'webhookUrl' or 'botToken', not both — they are different access models");
+        return { errors };
+    }
+    if (hasWebhook) {
+        if (typeof webhookUrl !== 'string') {
+            errors.push("Field 'webhookUrl' must be a string");
+        }
+        else if (!parseWebhookUrl(webhookUrl)) {
+            errors.push("Field 'webhookUrl' has invalid format (expected: https://discord.com/api/webhooks/<id>/<token>)");
+        }
+        return { errors };
+    }
+    if (typeof botToken !== 'string') {
+        errors.push("Field 'botToken' must be a string");
+    }
+    else if (!BOT_TOKEN_PATTERN.test(botToken)) {
+        errors.push("Field 'botToken' has invalid format");
+    }
+    return { errors };
+}
+/**
+ * Split a webhook URL into its id and token.
+ * @param url - The webhook URL from the account credentials.
+ * @returns The parts, or undefined when the URL is not a webhook URL.
+ */
+export function parseWebhookUrl(url) {
+    const match = WEBHOOK_URL_PATTERN.exec(url.trim());
+    if (!match) {
+        return undefined;
+    }
+    return { id: match[1], token: match[2] };
+}
+/** Which access model an account's credentials select. */
+export function authModeOf(auth) {
+    if (typeof auth.webhookUrl === 'string' && auth.webhookUrl.length > 0) {
+        return 'webhook';
+    }
+    if (typeof auth.botToken === 'string' && auth.botToken.length > 0) {
+        return 'bot';
+    }
+    return undefined;
+}
+//# sourceMappingURL=discord-auth.validator.js.map