@dereekb/discord 13.33.0

package/src/lib/discord.api.page.d.ts

@@ -0,0 +1,108 @@
+import { type Maybe } from '@dereekb/util';
+import { type FetchPageFactory, type FetchPageFactoryConfigDefaults } from '@dereekb/util/fetch';
+import { type DiscordMessageId } from './discord.type';
+/**
+ * Default number of messages per page when fetching Discord channel messages.
+ */
+export declare const DEFAULT_DISCORD_MESSAGES_PER_PAGE = 100;
+/**
+ * Base pagination parameters for Discord channel message endpoints.
+ *
+ * Discord uses cursor-based pagination via snowflake IDs rather than page numbers.
+ * Only one of `before`, `after`, or `around` should be specified per request.
+ */
+export interface DiscordMessagePageFilter {
+    /**
+     * Fetch messages before this message ID.
+     */
+    readonly before?: Maybe<DiscordMessageId>;
+    /**
+     * Fetch messages after this message ID.
+     */
+    readonly after?: Maybe<DiscordMessageId>;
+    /**
+     * Fetch messages around this message ID.
+     */
+    readonly around?: Maybe<DiscordMessageId>;
+    /**
+     * Maximum number of messages to return per page (1-100).
+     *
+     * Defaults to {@link DEFAULT_DISCORD_MESSAGES_PER_PAGE}.
+     */
+    readonly limit?: Maybe<number>;
+}
+/**
+ * Result of a paginated Discord message fetch containing the array of messages.
+ *
+ * @typeParam T - The message type. Structural, so it fits a raw REST response as readily as a
+ * discord.js `Message`; this entry point carries no discord.js dependency of its own.
+ */
+export interface DiscordMessagePageResult<T> {
+    /**
+     * Array of messages returned.
+     */
+    readonly data: T[];
+}
+/**
+ * A fetch function that accepts {@link DiscordMessagePageFilter} input and returns a {@link DiscordMessagePageResult}.
+ * Used as the underlying data source for {@link discordFetchMessagePageFactory}.
+ */
+export type DiscordFetchMessagePageFetchFunction<I extends DiscordMessagePageFilter, T> = (input: I) => Promise<DiscordMessagePageResult<T>>;
+/**
+ * Configuration for {@link discordFetchMessagePageFactory}.
+ *
+ * @typeParam T - The message type
+ */
+export interface DiscordFetchMessagePageFactoryConfig<T> {
+    /**
+     * Extracts the snowflake ID from a message object. Used to determine the cursor for the next page.
+     *
+     * Defaults to reading the `id` property on the message.
+     */
+    readonly readMessageId?: (message: T) => DiscordMessageId;
+}
+/**
+ * Configuration for {@link discordFetchMessagePageFactory}.
+ *
+ * @typeParam I - The input filter type
+ * @typeParam T - The message type
+ */
+export interface DiscordFetchMessagePageFactoryInput<I extends DiscordMessagePageFilter, T> {
+    /**
+     * The Discord fetch function to paginate over.
+     */
+    readonly fetch: DiscordFetchMessagePageFetchFunction<I, T>;
+    /**
+     * Optional config for reading message IDs.
+     */
+    readonly config?: Maybe<DiscordFetchMessagePageFactoryConfig<T>>;
+    /**
+     * Optional default configuration for the page factory.
+     */
+    readonly defaults?: Maybe<FetchPageFactoryConfigDefaults>;
+}
+/**
+ * Creates a page factory that wraps a Discord message fetch function with automatic cursor-based pagination.
+ *
+ * Discord paginates via `before`/`after` snowflake IDs. This factory automatically reads the last
+ * message's ID from each response and sets it as the `before` cursor for the next request.
+ * When the number of returned messages is less than the requested limit, pagination stops.
+ *
+ * @param input - The factory input configuration.
+ * @returns A page factory that produces iterable page fetchers.
+ *
+ * @example
+ * ```typescript
+ * const pageFactory = discordFetchMessagePageFactory({ fetch: fetchChannelMessages });
+ *
+ * const fetchPage = pageFactory({ limit: 50 });
+ * const firstPage = await fetchPage.fetchNext();
+ *
+ * if (firstPage.hasNext) {
+ *   const secondPage = await firstPage.fetchNext();
+ * }
+ * ```
+ */
+export declare function discordFetchMessagePageFactory<I extends DiscordMessagePageFilter, T extends {
+    id: string;
+}>(input: DiscordFetchMessagePageFactoryInput<I, T>): FetchPageFactory<I, DiscordMessagePageResult<T>>;

package/src/lib/discord.config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OAuth2 client id of a Discord application.
+ *
+ * Identical to the value the developer portal labels "Application ID".
+ */
+export type DiscordOAuthClientId = string;
+/**
+ * OAuth2 client secret of a Discord application.
+ */
+export type DiscordOAuthClientSecret = string;
+/**
+ * The Discord REST API base, pinned to a version.
+ *
+ * Endpoint paths are appended to this base, so it intentionally carries no endpoint segment of its
+ * own. Discord requires an explicit version in the path; an unversioned base resolves to the oldest
+ * still-supported version.
+ */
+export declare const DISCORD_API_URL = "https://discord.com/api/v10";
+export type DiscordApiUrl = typeof DISCORD_API_URL;

package/src/lib/discord.type.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A Discord snowflake id.
+ *
+ * The canonical id type for this package, declared in the fetch-only core so both entry points can
+ * share one declaration. `@dereekb/discord/nestjs` imports these from here directly rather than
+ * re-exporting them (the `dereekb-util/no-sister-re-export` rule), so the dependency only ever points
+ * core -> nestjs: the core stays free of discord.js and of anything that asserts a bot token.
+ */
+export type DiscordSnowflake = string;
+/**
+ * A Discord snowflake id, when the kind of object it identifies is not significant.
+ *
+ * Prefer the specific alias ({@link DiscordChannelId}, {@link DiscordGuildId},
+ * {@link DiscordMessageId}) where one applies.
+ */
+export type DiscordId = DiscordSnowflake;
+/**
+ * A Discord channel id.
+ */
+export type DiscordChannelId = DiscordSnowflake;
+/**
+ * A Discord guild (server) id.
+ */
+export type DiscordGuildId = DiscordSnowflake;
+/**
+ * A Discord message id.
+ */
+export type DiscordMessageId = DiscordSnowflake;
+/**
+ * Bot token used to authenticate the Discord bot with the gateway.
+ *
+ * Declared here alongside the other scalars for one place to look, though only
+ * `@dereekb/discord/nestjs` consumes it — the core never authenticates as a bot.
+ */
+export type DiscordBotToken = string;
+/**
+ * The Ed25519 public key of your Discord application, used to verify interaction webhooks.
+ *
+ * Found in the Discord Developer Portal under your application's General Information page.
+ */
+export type DiscordPublicKey = string;

package/src/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './discord.api.page';
+export * from './discord.config';
+export * from './discord.type';
+export * from './oauth';

package/src/lib/oauth/index.d.ts

@@ -0,0 +1,6 @@
+export * from './oauth';
+export * from './oauth.api';
+export * from './oauth.authorize';
+export * from './oauth.config';
+export * from './oauth.error.api';
+export * from './oauth.factory';

package/src/lib/oauth/oauth.api.d.ts

@@ -0,0 +1,130 @@
+import { type Maybe, type Seconds } from '@dereekb/util';
+import { type DiscordSnowflake } from '../discord.type';
+import { type DiscordOAuthConfig, type DiscordOAuthContext } from './oauth.config';
+/**
+ * The `Content-Type` Discord's token endpoint requires.
+ *
+ * Discord rejects a JSON body outright, unlike Cal.com, which requires one.
+ *
+ * `@dereekb/util/oidc`'s `postTokenEndpoint` is the in-workspace precedent for this form-encoded
+ * shape and is deliberately NOT reused: its `exchangeAuthorizationCode` requires a PKCE
+ * `code_verifier`, it authenticates with `client_secret_post` rather than Basic, and it is
+ * discovery-driven. Discord is not an OIDC provider — there is no discovery document and no
+ * `id_token`.
+ */
+export declare const DISCORD_OAUTH_TOKEN_CONTENT_TYPE = "application/x-www-form-urlencoded";
+export interface DiscordOAuthExchangeAuthorizationCodeInput {
+    readonly code: string;
+    /**
+     * Must be byte-identical to the `redirect_uri` sent on the authorize request.
+     */
+    readonly redirectUri: string;
+}
+export interface DiscordOAuthRefreshTokenInput {
+    readonly refreshToken: string;
+}
+export interface DiscordOAuthReadCurrentUserInput {
+    /**
+     * The user's access token. NOT the client credentials.
+     */
+    readonly accessToken: string;
+}
+export interface DiscordOAuthTokenResponse {
+    readonly access_token: string;
+    readonly token_type: 'Bearer';
+    /**
+     * Seconds until expiry.
+     *
+     * Discord issues 604800 (7 days), far longer than most providers. Nothing structural depends on
+     * that, but it does mean an expiry bug surfaces a week after it is introduced rather than an hour.
+     */
+    readonly expires_in: Seconds;
+    readonly refresh_token: string;
+    /**
+     * The granted scopes, space-delimited.
+     */
+    readonly scope?: Maybe<string>;
+}
+/**
+ * The subset of Discord's user object this package reads.
+ *
+ * @see https://docs.discord.com/developers/resources/user
+ */
+export interface DiscordOAuthCurrentUser {
+    readonly id: DiscordSnowflake;
+    readonly username: string;
+    /**
+     * The user's chosen display name, which supersedes the legacy `username#discriminator` pair.
+     *
+     * Null for accounts that have not migrated.
+     */
+    readonly global_name?: Maybe<string>;
+    readonly discriminator?: Maybe<string>;
+    readonly avatar?: Maybe<string>;
+}
+/**
+ * Builds the HTTP Basic `Authorization` header value that authenticates the OAuth client.
+ *
+ * Discord accepts the client credentials as Basic auth rather than in the request body, which is why
+ * `client_id` / `client_secret` are absent from the exchange body below.
+ *
+ * Uses `btoa()` rather than `Buffer`, so this package stays usable outside Node — the same choice
+ * `@dereekb/util`'s PKCE helpers make.
+ *
+ * @param config - The client credentials to encode.
+ * @returns The `Authorization` header value, including the `Basic ` prefix.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function discordOAuthBasicAuthorizationHeader(config: DiscordOAuthConfig): string;
+/**
+ * Exchanges an OAuth authorization code for access and refresh tokens.
+ *
+ * Discord requires `application/x-www-form-urlencoded` — a JSON body is rejected — and authenticates
+ * the client with HTTP Basic rather than credentials in the body. Both differ from Cal.com, which
+ * posts JSON with the credentials inline. The Basic header rides on the context's configured fetch.
+ *
+ * @param context - The Discord OAuth context providing the authenticated fetch.
+ * @returns Exchanges an authorization code for access and refresh tokens.
+ *
+ * @see https://docs.discord.com/developers/topics/oauth2
+ *
+ * @example
+ * ```ts
+ * const response = await exchangeAuthorizationCode(context)({
+ *   code: 'auth-code-from-redirect',
+ *   redirectUri: 'http://localhost:9901/oauth/discord/callback'
+ * });
+ * ```
+ */
+export declare function exchangeAuthorizationCode(context: DiscordOAuthContext): (input: DiscordOAuthExchangeAuthorizationCodeInput) => Promise<DiscordOAuthTokenResponse>;
+/**
+ * Refreshes an access token.
+ *
+ * Discord's refresh response carries a `refresh_token` of its own, so persist whatever comes back
+ * rather than assuming the sent one stays valid. That is correct for rotating and non-rotating
+ * providers alike.
+ *
+ * Reached through `DiscordUserExternalConnectionOAuthService.refreshCredentials`, which the external
+ * connection reader dispatches to when a user's stored Discord credentials are near expiration.
+ *
+ * @param context - The Discord OAuth context providing the authenticated fetch.
+ * @returns Refreshes an access token using the given refresh token.
+ *
+ * @see https://docs.discord.com/developers/topics/oauth2
+ */
+export declare function refreshAccessToken(context: DiscordOAuthContext): (input: DiscordOAuthRefreshTokenInput) => Promise<DiscordOAuthTokenResponse>;
+/**
+ * Reads the user an access token belongs to. Requires the `identify` scope.
+ *
+ * Bearer-authenticated with the USER's token, not Basic-authenticated with the client credentials, so
+ * the `Authorization` header is passed per-request to override the one on the context's fetch. A
+ * per-request header wins over the base header of the same name, which is what makes one configured
+ * fetch enough for both shapes.
+ *
+ * @param context - The Discord OAuth context providing the authenticated fetch.
+ * @returns Reads the Discord user the given access token belongs to.
+ *
+ * @see https://docs.discord.com/developers/resources/user
+ */
+export declare function readCurrentUser(context: DiscordOAuthContext): (input: DiscordOAuthReadCurrentUserInput) => Promise<DiscordOAuthCurrentUser>;

package/src/lib/oauth/oauth.authorize.d.ts

@@ -0,0 +1,93 @@
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { type DiscordOAuthClientId } from '../discord.config';
+/**
+ * The Discord OAuth scopes this package models.
+ *
+ * A runtime list rather than a bare type union, so a configured scope can be validated instead of
+ * being passed through to the consent screen and refused there.
+ *
+ * Deliberately NOT Discord's full ~40-scope surface: only what a per-user account connect can
+ * legitimately ask for. Add a scope here when code actually uses it.
+ *
+ * @see https://docs.discord.com/developers/topics/oauth2
+ */
+export declare const ALL_DISCORD_OAUTH_SCOPES: readonly ["identify", "email", "guilds", "connections"];
+/**
+ * A Discord OAuth scope modeled by this package.
+ */
+export type DiscordOAuthScope = (typeof ALL_DISCORD_OAUTH_SCOPES)[number];
+/**
+ * Returns whether the input is a known {@link DiscordOAuthScope}.
+ *
+ * @param value - The value to check.
+ * @returns True when the value is a Discord OAuth scope this package models.
+ */
+export declare function isDiscordOAuthScope(value: string): value is DiscordOAuthScope;
+/**
+ * The delimiter used to join scopes in the `scope` query parameter.
+ *
+ * OAuth2 specifies a space-delimited list and Discord follows it. `URL.searchParams.set` handles the
+ * percent-encoding, so this stays a literal space.
+ */
+export declare const DISCORD_OAUTH_SCOPE_DELIMITER = " ";
+/**
+ * The `response_type` used by the authorization-code flow.
+ */
+export declare const DISCORD_OAUTH_AUTHORIZE_RESPONSE_TYPE = "code";
+export interface DiscordOAuthAuthorizeUrlFactoryConfig {
+    /**
+     * The OAuth client id to authorize as.
+     */
+    readonly clientId: DiscordOAuthClientId;
+    /**
+     * The redirect URI to return to after the user consents.
+     *
+     * Must match a URI registered on the Discord application byte-for-byte, including the port, and
+     * must be identical to the `redirectUri` later passed to the token exchange.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The scopes to request.
+     */
+    readonly scopes: readonly DiscordOAuthScope[];
+    /**
+     * Optional override of the authorize URL. Defaults to {@link DISCORD_OAUTH_AUTHORIZE_URL}.
+     */
+    readonly authorizeUrl?: Maybe<WebsiteUrl>;
+}
+export interface DiscordOAuthAuthorizeUrlParams {
+    /**
+     * Opaque state echoed back to the redirect URI.
+     *
+     * Carries the acting user and is the CSRF defense for the handoff, so it should be signed and
+     * short-lived.
+     */
+    readonly state?: Maybe<string>;
+}
+export type DiscordOAuthAuthorizeUrlFactory = (params?: Maybe<DiscordOAuthAuthorizeUrlParams>) => WebsiteUrl;
+/**
+ * Creates a {@link DiscordOAuthAuthorizeUrlFactory} that composes the Discord authorize URL a user's
+ * browser is redirected to in order to begin the authorization-code flow.
+ *
+ * The client id, redirect URI, and scopes are fixed by the config, since a consumer holds those
+ * constant and varies only the per-request `state`.
+ *
+ * @param config - The client id, redirect URI, and scopes to request.
+ * @returns A factory that builds an authorize URL for the given params.
+ *
+ * @see https://docs.discord.com/developers/topics/oauth2
+ *
+ * @example
+ * ```ts
+ * const authorizeUrlFactory = discordOAuthAuthorizeUrlFactory({
+ *   clientId: 'client-id',
+ *   redirectUri: 'http://localhost:9901/oauth/discord/callback',
+ *   scopes: ['identify']
+ * });
+ *
+ * const url = authorizeUrlFactory({ state: 'signed-state' });
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function discordOAuthAuthorizeUrlFactory(config: DiscordOAuthAuthorizeUrlFactoryConfig): DiscordOAuthAuthorizeUrlFactory;

package/src/lib/oauth/oauth.config.d.ts

@@ -0,0 +1,56 @@
+import { type FactoryWithRequiredInput } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchJsonFunction } from '@dereekb/util/fetch';
+import { type DiscordOAuthClientId, type DiscordOAuthClientSecret } from '../discord.config';
+/**
+ * The Discord OAuth2 authorize URL the user's browser is redirected to.
+ *
+ * Note this is NOT under `/api`: Discord serves the consent screen from the site root, while the
+ * token endpoint lives under {@link DISCORD_API_URL}. It is therefore a full URL rather than a path
+ * relative to the API base.
+ */
+export declare const DISCORD_OAUTH_AUTHORIZE_URL = "https://discord.com/oauth2/authorize";
+/**
+ * The Discord OAuth2 token endpoint path, relative to {@link DISCORD_API_URL}.
+ */
+export declare const DISCORD_OAUTH_TOKEN_PATH = "/oauth2/token";
+/**
+ * The Discord OAuth2 token revocation endpoint path, relative to {@link DISCORD_API_URL}.
+ */
+export declare const DISCORD_OAUTH_REVOKE_PATH = "/oauth2/token/revoke";
+/**
+ * Path of the endpoint returning the user an access token belongs to.
+ *
+ * Requires the `identify` scope.
+ */
+export declare const DISCORD_OAUTH_CURRENT_USER_PATH = "/users/@me";
+/**
+ * Configuration for a Discord OAuth client.
+ *
+ * Both values are required: unlike Cal.com, Discord has no api-key alternative to the
+ * client-credentials pair, so there is no valid partially-configured state.
+ */
+export interface DiscordOAuthConfig {
+    readonly clientId: DiscordOAuthClientId;
+    readonly clientSecret: DiscordOAuthClientSecret;
+}
+export interface DiscordOAuthFetchFactoryInput {
+    /**
+     * The client credentials the produced fetch authenticates the token endpoint with.
+     *
+     * Passed in rather than closed over, because the Basic authorization header is part of the fetch's
+     * baseRequest and so cannot be composed before the credentials are known.
+     */
+    readonly config: DiscordOAuthConfig;
+}
+export type DiscordOAuthFetchFactory = FactoryWithRequiredInput<ConfiguredFetch, DiscordOAuthFetchFactoryInput>;
+/**
+ * Context used for performing fetch() and fetchJson() calls with a configured fetch instance.
+ */
+export interface DiscordOAuthContext {
+    readonly fetch: ConfiguredFetch;
+    readonly fetchJson: FetchJsonFunction;
+    readonly config: DiscordOAuthConfig;
+}
+export interface DiscordOAuthContextRef {
+    readonly oauthContext: DiscordOAuthContext;
+}

package/src/lib/oauth/oauth.d.ts

@@ -0,0 +1,42 @@
+import { type Seconds } from '@dereekb/util';
+import { type DiscordOAuthTokenResponse } from './oauth.api';
+/**
+ * Access token string issued by Discord's token endpoint.
+ */
+export type DiscordAccessTokenString = string;
+/**
+ * Space-separated scopes string for a {@link DiscordAccessToken}.
+ */
+export type DiscordAccessTokenScopesString = string;
+/**
+ * Refresh token issued alongside a Discord access token.
+ *
+ * Discord's refresh response returns a refresh token of its own, so always persist the latest one
+ * rather than assuming the sent value survives.
+ */
+export type DiscordRefreshToken = string;
+/**
+ * A normalized Discord account access token.
+ */
+export interface DiscordAccessToken {
+    readonly accessToken: DiscordAccessTokenString;
+    readonly refreshToken: DiscordRefreshToken;
+    readonly scope: DiscordAccessTokenScopesString;
+    /**
+     * Length of time the token is valid for. Discord issues 7 days.
+     */
+    readonly expiresIn: Seconds;
+    /**
+     * Date the token expires at.
+     */
+    readonly expiresAt: Date;
+}
+/**
+ * Maps a {@link DiscordOAuthTokenResponse} to a {@link DiscordAccessToken}.
+ *
+ * @param response - The token response returned by the Discord token endpoint.
+ * @returns The equivalent DiscordAccessToken, with `expiresAt` resolved against the current time.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function discordAccessTokenFromTokenResponse(response: DiscordOAuthTokenResponse): DiscordAccessToken;

package/src/lib/oauth/oauth.error.api.d.ts

@@ -0,0 +1,65 @@
+import { type Maybe } from '@dereekb/util';
+import { type ConfiguredFetch, type FetchRequestFactoryError, FetchResponseError } from '@dereekb/util/fetch';
+import { BaseError } from 'make-error';
+/**
+ * Error code returned when a code or refresh token is invalid, expired, or was already spent.
+ */
+export declare const DISCORD_OAUTH_INVALID_GRANT_ERROR_CODE = "invalid_grant";
+/**
+ * Error code returned when the requested scope set is not one the application may ask for.
+ */
+export declare const DISCORD_OAUTH_INVALID_SCOPE_ERROR_CODE = "invalid_scope";
+/**
+ * The error body Discord's OAuth endpoints return.
+ *
+ * Discord follows RFC 6749's `error` / `error_description` shape rather than the `code` / `message`
+ * shape its own REST API uses, so this is deliberately not the REST error type.
+ */
+export interface DiscordOAuthErrorData {
+    readonly error: string;
+    readonly error_description?: Maybe<string>;
+}
+/**
+ * An error reported by a Discord OAuth endpoint.
+ */
+export declare class DiscordOAuthError<D extends DiscordOAuthErrorData = DiscordOAuthErrorData> extends BaseError {
+    readonly error: D;
+    get code(): string;
+    constructor(error: D);
+}
+/**
+ * A {@link DiscordOAuthError} that retains the HTTP response it was parsed from.
+ */
+export declare class DiscordOAuthFetchResponseError<D extends DiscordOAuthErrorData = DiscordOAuthErrorData> extends DiscordOAuthError<D> {
+    readonly data: D;
+    readonly responseError: FetchResponseError;
+    constructor(data: D, responseError: FetchResponseError);
+}
+export type LogDiscordOAuthErrorFunction = (error: FetchRequestFactoryError | DiscordOAuthError) => void;
+/**
+ * Creates a {@link LogDiscordOAuthErrorFunction} that logs the error to the console.
+ *
+ * @param discordApiNamePrefix - Prefix to use when logging, e.g. `DiscordOAuth`.
+ * @returns A log function that prefixes each logged error.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function logDiscordOAuthErrorFunction(discordApiNamePrefix: string): LogDiscordOAuthErrorFunction;
+export declare const logDiscordOAuthErrorToConsole: LogDiscordOAuthErrorFunction;
+/**
+ * Parses a {@link FetchResponseError} from a Discord OAuth call into a typed error.
+ *
+ * @param responseError - The fetch response error to parse.
+ * @returns The parsed error, or undefined when the body carried no OAuth error to parse.
+ */
+export declare function parseDiscordOAuthError(responseError: FetchResponseError): Promise<Maybe<DiscordOAuthFetchResponseError>>;
+/**
+ * Wraps a {@link ConfiguredFetch} so that Discord OAuth error responses surface as typed errors.
+ *
+ * @param fetch - The fetch to wrap.
+ * @param logError - Optional override of the error logging function.
+ * @returns The wrapped fetch.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function handleDiscordOAuthErrorFetch(fetch: ConfiguredFetch, logError?: LogDiscordOAuthErrorFunction): ConfiguredFetch;

package/src/lib/oauth/oauth.factory.d.ts

@@ -0,0 +1,36 @@
+import { type Maybe } from '@dereekb/util';
+import { type FetchHandler } from '@dereekb/util/fetch';
+import { type DiscordOAuthConfig, type DiscordOAuthContextRef, type DiscordOAuthFetchFactory } from './oauth.config';
+import { type LogDiscordOAuthErrorFunction } from './oauth.error.api';
+export type DiscordOAuth = DiscordOAuthContextRef;
+export interface DiscordOAuthFactoryConfig {
+    /**
+     * Creates a new fetch instance to use when making calls.
+     */
+    readonly fetchFactory?: DiscordOAuthFetchFactory;
+    /**
+     * Custom FetchHandler to use with the default fetchFactory.
+     *
+     * This is the seam specs use to intercept requests before they leave the process. Ignored when a
+     * `fetchFactory` is provided.
+     */
+    readonly fetchHandler?: Maybe<FetchHandler>;
+    /**
+     * Custom log error function.
+     */
+    readonly logDiscordOAuthErrorFunction?: LogDiscordOAuthErrorFunction;
+}
+export type DiscordOAuthFactory = (config: DiscordOAuthConfig) => DiscordOAuth;
+/**
+ * Creates a {@link DiscordOAuthFactory} that produces configured Discord OAuth instances.
+ *
+ * There is no access-token cache or per-user token factory here, unlike `calcomOAuthFactory`: the
+ * external-connection framework stores each user's credentials itself, so the client only ever needs
+ * to make the calls it is asked to make.
+ *
+ * @param factoryConfig - Configuration including an optional fetch factory, fetch handler, and error logging.
+ * @returns A factory accepting a DiscordOAuthConfig and producing a DiscordOAuth instance.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function discordOAuthFactory(factoryConfig: DiscordOAuthFactoryConfig): DiscordOAuthFactory;