@dereekb/discord 14.0.1 → 14.2.0

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

@@ -0,0 +1,257 @@
+import { type Factory, type IndexNumber, type Maybe, type Milliseconds, type PromiseOrValue } from '@dereekb/util';
+import { type DiscordFetchMessagePageFetchFunction, type DiscordMessagePageFilter } from './discord.api.page';
+import { type DiscordMessageId } from './discord.type';
+/**
+ * Why a scan stopped walking messages.
+ *
+ * `stop_bound` and `channel_start` mean the scan is caught up; the rest mean it exhausted a budget
+ * and can be resumed from {@link DiscordScanMessagesResult.resumeBeforeMessageId}.
+ */
+export type DiscordScanStopReason = 
+/**
+ * Reached the `afterMessageId` stop bound. Everything newer than it has been handled.
+ */
+'stop_bound'
+/**
+ * Reached a short page, meaning no older messages exist in the channel.
+ */
+ | 'channel_start'
+/**
+ * Loaded as many messages as the scan was budgeted for.
+ */
+ | 'max_messages'
+/**
+ * Loaded as many pages as the scan was budgeted for.
+ */
+ | 'max_pages'
+/**
+ * Ran out of the scan's time budget.
+ */
+ | 'time_budget';
+/**
+ * A single page's worth of messages delivered to a {@link DiscordScanMessagesBatchHandler}.
+ *
+ * @typeParam T - The message type.
+ */
+export interface DiscordScanMessagesBatch<T> {
+    /**
+     * The messages in this batch, newest-first, as Discord returns them.
+     *
+     * Never empty: a batch with no messages is not delivered to the handler at all.
+     */
+    readonly messages: T[];
+    /**
+     * The id of the newest message in this batch.
+     */
+    readonly newestMessageId: DiscordMessageId;
+    /**
+     * The id of the oldest message in this batch.
+     */
+    readonly oldestMessageId: DiscordMessageId;
+    /**
+     * The zero-based index of the page this batch came from within this scan.
+     */
+    readonly page: IndexNumber;
+    /**
+     * The total number of messages handed to the handler by this scan so far, including this batch.
+     */
+    readonly totalMessagesHandled: number;
+}
+/**
+ * Handles a single batch of messages during a scan.
+ *
+ * Batches arrive one at a time, newest page first, and the scan waits for each one before fetching
+ * the next page.
+ */
+export type DiscordScanMessagesBatchHandler<T> = (batch: DiscordScanMessagesBatch<T>) => Promise<void>;
+/**
+ * The work budget for a scan.
+ *
+ * Every value is optional; an unset value means that particular budget is unbounded. A scan with no
+ * budget at all walks back to the start of the channel or to its stop bound.
+ */
+export interface DiscordScanMessagesBounds {
+    /**
+     * The number of messages to request per page.
+     *
+     * Defaults to {@link DEFAULT_DISCORD_MESSAGES_PER_PAGE}.
+     */
+    readonly messagesPerPage?: Maybe<number>;
+    /**
+     * The maximum number of pages to fetch.
+     */
+    readonly maxPages?: Maybe<number>;
+    /**
+     * The maximum number of messages to load, counted before filtering.
+     *
+     * Counted pre-filter so that a scan whose filter rejects everything still terminates.
+     */
+    readonly maxMessages?: Maybe<number>;
+    /**
+     * The maximum amount of time the scan may spend, checked after each page.
+     */
+    readonly maxDuration?: Maybe<Milliseconds>;
+    /**
+     * The amount of time to wait between page fetches.
+     */
+    readonly waitBetweenPages?: Maybe<Milliseconds>;
+}
+/**
+ * Configuration for {@link discordScanMessagesFactory}.
+ *
+ * @typeParam I - The fetch input filter type.
+ * @typeParam T - The message type.
+ */
+export interface DiscordScanMessagesFactoryConfig<I extends DiscordMessagePageFilter, T extends {
+    id: string;
+}> {
+    /**
+     * The Discord message fetch function to scan with.
+     */
+    readonly fetch: DiscordFetchMessagePageFetchFunction<I, T>;
+    /**
+     * Reads the snowflake id from a message. Defaults to reading the `id` property.
+     */
+    readonly readMessageId?: Maybe<(message: T) => DiscordMessageId>;
+    /**
+     * Default bounds applied to every scan, overridden per-scan by the scan input.
+     */
+    readonly defaults?: Maybe<DiscordScanMessagesBounds>;
+    /**
+     * Factory for the current time, used for the `maxDuration` budget.
+     *
+     * Exists as a seam so a spec can drive the time budget deterministically.
+     */
+    readonly nowFactory?: Maybe<Factory<Date>>;
+}
+/**
+ * Input for a single scan.
+ *
+ * @typeParam I - The fetch input filter type.
+ * @typeParam T - The message type.
+ */
+export interface DiscordScanMessagesInput<I extends DiscordMessagePageFilter, T extends {
+    id: string;
+}> extends DiscordScanMessagesBounds {
+    /**
+     * The non-pagination part of the fetch input, such as the channel id.
+     *
+     * The pagination fields are owned by the scan and are built from the bounds below.
+     */
+    readonly baseInput: Omit<I, keyof DiscordMessagePageFilter>;
+    /**
+     * The START bound, exclusive. The scan begins with the messages immediately older than this id.
+     *
+     * Leave undefined to start from the newest message in the channel. Resume an interrupted scan by
+     * passing its {@link DiscordScanMessagesResult.resumeBeforeMessageId} here.
+     */
+    readonly beforeMessageId?: Maybe<DiscordMessageId>;
+    /**
+     * The STOP bound, exclusive. The scan stops once it walks back to this id.
+     *
+     * Leave undefined to walk back to the start of the channel. This is typically the high-water mark
+     * from the previous completed scan.
+     */
+    readonly afterMessageId?: Maybe<DiscordMessageId>;
+    /**
+     * Optional filter applied to each page before the handler sees it.
+     *
+     * Filtered-out messages are still counted as loaded and still move the resume cursor past
+     * themselves, so they are never revisited.
+     */
+    readonly filterMessages?: Maybe<(messages: T[]) => PromiseOrValue<T[]>>;
+    /**
+     * Handles each batch of messages. Not invoked for an empty batch.
+     */
+    readonly handleMessages: DiscordScanMessagesBatchHandler<T>;
+}
+/**
+ * The outcome of a scan.
+ */
+export interface DiscordScanMessagesResult {
+    /**
+     * Why the scan stopped.
+     */
+    readonly stopReason: DiscordScanStopReason;
+    /**
+     * Whether the scan reached its stop bound or the start of the channel.
+     *
+     * When true the caller has seen everything it asked for and should promote
+     * {@link newestMessageId} to its high-water mark. When false the scan ran out of budget and
+     * should be resumed from {@link resumeBeforeMessageId}.
+     */
+    readonly complete: boolean;
+    /**
+     * The id of the newest message the scan loaded, before filtering.
+     *
+     * Undefined when the scan loaded nothing.
+     */
+    readonly newestMessageId: Maybe<DiscordMessageId>;
+    /**
+     * The id to pass as `beforeMessageId` to resume this scan.
+     *
+     * This is the oldest message the scan LOADED, not the oldest it delivered, so filtered-out
+     * messages are not revisited. Only meaningful when {@link complete} is false.
+     */
+    readonly resumeBeforeMessageId: Maybe<DiscordMessageId>;
+    /**
+     * The number of pages fetched.
+     */
+    readonly totalPages: number;
+    /**
+     * The number of messages loaded, before filtering and before the stop bound truncated a page.
+     */
+    readonly totalMessagesLoaded: number;
+    /**
+     * The number of messages delivered to the handler.
+     */
+    readonly totalMessagesHandled: number;
+    /**
+     * When the scan started.
+     */
+    readonly startedAt: Date;
+    /**
+     * When the scan ended.
+     */
+    readonly endedAt: Date;
+}
+/**
+ * Scans a Discord channel's messages, handing each batch to the input handler.
+ *
+ * @typeParam I - The fetch input filter type.
+ * @typeParam T - The message type.
+ */
+export type DiscordScanMessagesFunction<I extends DiscordMessagePageFilter, T extends {
+    id: string;
+}> = (input: DiscordScanMessagesInput<I, T>) => Promise<DiscordScanMessagesResult>;
+/**
+ * Creates a {@link DiscordScanMessagesFunction} that walks a channel's messages backwards in time
+ * and hands each page to a caller-supplied handler.
+ *
+ * The scan is persistence-agnostic: it knows nothing about where a cursor is stored. It walks from
+ * `beforeMessageId` (or the newest message) back towards `afterMessageId` (or the start of the
+ * channel), stops as soon as a budget is exhausted, and reports where it stopped so the caller can
+ * resume from exactly there.
+ *
+ * @param config - The fetch function and scan defaults.
+ * @returns A scan function.
+ *
+ * @example
+ * ```ts
+ * const scan = discordScanMessagesFactory({ fetch: fetchChannelMessages });
+ *
+ * const result = await scan({
+ *   baseInput: { channelId },
+ *   afterMessageId: lastScannedMessageId,
+ *   maxMessages: 1000,
+ *   handleMessages: async ({ messages }) => saveMessages(messages)
+ * });
+ *
+ * if (result.complete) {
+ *   lastScannedMessageId = result.newestMessageId ?? lastScannedMessageId;
+ * }
+ * ```
+ */
+export declare function discordScanMessagesFactory<I extends DiscordMessagePageFilter, T extends {
+    id: string;
+}>(config: DiscordScanMessagesFactoryConfig<I, T>): DiscordScanMessagesFunction<I, T>;

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

@@ -0,0 +1,70 @@
+import { type Milliseconds } from '@dereekb/util';
+import { type DiscordSnowflake } from './discord.type';
+/**
+ * The Discord epoch, the first second of 2015, expressed as a unix timestamp in milliseconds.
+ *
+ * Every snowflake encodes its creation time as an offset from this value.
+ */
+export declare const DISCORD_EPOCH_MS: Milliseconds;
+/**
+ * The number of low bits in a snowflake reserved for the worker id, process id, and increment.
+ *
+ * The timestamp occupies every bit above these.
+ */
+export declare const DISCORD_SNOWFLAKE_TIMESTAMP_SHIFT = 22n;
+/**
+ * Returns the creation time encoded in the input snowflake.
+ *
+ * The arithmetic is performed with BigInt: a snowflake exceeds 53 bits, so the naive
+ * `Number(snowflake) >> 22` coerces to a 32-bit integer and returns a time near the Discord
+ * epoch for every modern id.
+ *
+ * @param snowflake - The snowflake id to read the timestamp from.
+ * @returns The Date the snowflake was created at.
+ *
+ * @example
+ * ```ts
+ * discordSnowflakeToDate('1480401620608090182'); // 2026-03-09T03:07:30.885Z
+ * ```
+ */
+export declare function discordSnowflakeToDate(snowflake: DiscordSnowflake): Date;
+/**
+ * Returns the lowest snowflake id that could have been created at the input date.
+ *
+ * Useful as a `before`/`after` pagination bound: an id built this way sorts before every real
+ * message created in the same millisecond, so it can bound a scan by time without knowing any
+ * actual message id.
+ *
+ * @param date - The date to build a snowflake bound for.
+ * @returns The lowest snowflake id for that millisecond.
+ *
+ * @example
+ * ```ts
+ * const twoWeeksAgo = discordSnowflakeForDate(addDays(new Date(), -14));
+ * ```
+ */
+export declare function discordSnowflakeForDate(date: Date): DiscordSnowflake;
+/**
+ * Compares two snowflakes by their numeric value.
+ *
+ * Compared as BigInt values rather than strings: a plain string comparison is only correct for
+ * ids of equal length, and snowflake ids grow a digit over time.
+ *
+ * @param a - The first snowflake.
+ * @param b - The second snowflake.
+ * @returns A negative number when a is older than b, a positive number when a is newer, and 0 when equal.
+ */
+export declare function compareDiscordSnowflakes(a: DiscordSnowflake, b: DiscordSnowflake): number;
+/**
+ * Returns true if snowflake a was created after snowflake b.
+ *
+ * @param a - The snowflake to test.
+ * @param b - The snowflake to test against.
+ * @returns True when a is strictly newer than b.
+ *
+ * @example
+ * ```ts
+ * discordSnowflakeIsAfter('1480401620608090182', '1480401620608090181'); // true
+ * ```
+ */
+export declare function discordSnowflakeIsAfter(a: DiscordSnowflake, b: DiscordSnowflake): boolean;

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

@@ -26,6 +26,10 @@ export type DiscordGuildId = DiscordSnowflake;
  * A Discord message id.
  */
 export type DiscordMessageId = DiscordSnowflake;
+/**
+ * A Discord user id.
+ */
+export type DiscordUserId = DiscordSnowflake;
 /**
  * Bot token used to authenticate the Discord bot with the gateway.
  *

package/src/lib/index.d.ts

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

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

@@ -1,4 +1,4 @@
-import { type Maybe, type Seconds } from '@dereekb/util';
+import { type EmailAddress, type Maybe, type Seconds } from '@dereekb/util';
 import { type DiscordSnowflake } from '../discord.type';
 import { type DiscordOAuthConfig, type DiscordOAuthContext } from './oauth.config';
 /**
@@ -6,11 +6,16 @@ import { type DiscordOAuthConfig, type DiscordOAuthContext } from './oauth.confi
  *
  * 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`.
+ * Discord IS an OIDC provider, contrary to what this file previously claimed. Verified directly:
+ * `https://discord.com/.well-known/openid-configuration` returns 200 with every required discovery
+ * field, `https://discord.com/api/oauth2/keys` serves a JWKS, and the `openid` scope yields an
+ * `id_token` on the authorization-code grant. The relying-party calls below therefore delegate to
+ * `@dereekb/util/oidc`, passing `clientAuth: 'client_secret_basic'` (Discord's discovery document
+ * omits `token_endpoint_auth_methods_supported`, whose OIDC Discovery default is Basic — which is
+ * what Discord in fact requires).
+ *
+ * Discovery itself is not performed: the endpoints are stable, and skipping the extra round trip
+ * keeps the per-request cost the same as before.
  */
 export declare const DISCORD_OAUTH_TOKEN_CONTENT_TYPE = "application/x-www-form-urlencoded";
 export interface DiscordOAuthExchangeAuthorizationCodeInput {
@@ -19,6 +24,23 @@ export interface DiscordOAuthExchangeAuthorizationCodeInput {
      * Must be byte-identical to the `redirect_uri` sent on the authorize request.
      */
     readonly redirectUri: string;
+    /**
+     * The PKCE code verifier whose challenge was sent on the authorize request.
+     *
+     * Optional, and must be omitted when the authorize request carried no `code_challenge` — Discord
+     * rejects a `code_verifier` for a code minted without one.
+     */
+    readonly codeVerifier?: Maybe<string>;
+}
+export interface DiscordOAuthRevokeTokenInput {
+    /**
+     * The access or refresh token to revoke.
+     */
+    readonly token: string;
+    /**
+     * Optional hint telling Discord which kind of token was passed.
+     */
+    readonly tokenTypeHint?: Maybe<'access_token' | 'refresh_token'>;
 }
 export interface DiscordOAuthRefreshTokenInput {
     readonly refreshToken: string;
@@ -61,15 +83,30 @@ export interface DiscordOAuthCurrentUser {
     readonly global_name?: Maybe<string>;
     readonly discriminator?: Maybe<string>;
     readonly avatar?: Maybe<string>;
+    /**
+     * The user's email. Present only when the `email` scope was granted.
+     *
+     * Never key an identity on this — it is mutable, and {@link DiscordOAuthCurrentUser.id} is the
+     * stable account identifier.
+     */
+    readonly email?: Maybe<EmailAddress>;
+    /**
+     * Whether Discord has verified {@link DiscordOAuthCurrentUser.email}. Present only when the
+     * `email` scope was granted.
+     *
+     * A sign-in must not adopt an existing account by email unless this is true.
+     */
+    readonly verified?: Maybe<boolean>;
 }
 /**
  * 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
+ * Discord requires 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.
+ * A thin alias of the generic {@link oidcClientSecretBasicAuthorizationHeader}, kept because the
+ * configured fetch bakes the header into its `baseRequest` and so needs it as a value, not as a
+ * per-request auth mode.
  *
  * @param config - The client credentials to encode.
  * @returns The `Authorization` header value, including the `Basic ` prefix.
@@ -80,9 +117,10 @@ export declare function discordOAuthBasicAuthorizationHeader(config: DiscordOAut
 /**
  * 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.
+ * Delegates to `@dereekb/util/oidc`'s relying-party `exchangeAuthorizationCode` with
+ * `clientAuth: 'client_secret_basic'`, which produces exactly the form-encoded, Basic-authenticated
+ * request Discord requires. The context's configured fetch supplies the base URL and surfaces
+ * Discord's RFC-6749 error bodies as typed {@link DiscordOAuthError}s.
  *
  * @param context - The Discord OAuth context providing the authenticated fetch.
  * @returns Exchanges an authorization code for access and refresh tokens.
@@ -114,6 +152,18 @@ export declare function exchangeAuthorizationCode(context: DiscordOAuthContext):
  * @see https://docs.discord.com/developers/topics/oauth2
  */
 export declare function refreshAccessToken(context: DiscordOAuthContext): (input: DiscordOAuthRefreshTokenInput) => Promise<DiscordOAuthTokenResponse>;
+/**
+ * Revokes an access or refresh token, ending Discord's side of the authorization.
+ *
+ * Called when a user disconnects their Discord account: deleting the stored credentials alone leaves
+ * the grant live on Discord, so the token stays usable by anyone who captured it.
+ *
+ * @param context - The Discord OAuth context providing the authenticated fetch.
+ * @returns Revokes the given token.
+ *
+ * @see https://docs.discord.com/developers/topics/oauth2
+ */
+export declare function revokeToken(context: DiscordOAuthContext): (input: DiscordOAuthRevokeTokenInput) => Promise<void>;
 /**
  * Reads the user an access token belongs to. Requires the `identify` scope.
  *

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

@@ -6,12 +6,16 @@ import { type DiscordOAuthClientId } from '../discord.config';
  * 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.
+ * Deliberately NOT Discord's full ~40-scope surface: only what a per-user account connect or sign-in
+ * can legitimately ask for. Add a scope here when code actually uses it.
+ *
+ * `openid` is included because Discord is an OIDC provider (its discovery document and JWKS are
+ * live) and requesting it yields an `id_token`. Nothing in this workspace consumes that token —
+ * identity is read server-side from `/users/@me` — but the scope is legal to request.
  *
  * @see https://docs.discord.com/developers/topics/oauth2
  */
-export declare const ALL_DISCORD_OAUTH_SCOPES: readonly ["identify", "email", "guilds", "connections"];
+export declare const ALL_DISCORD_OAUTH_SCOPES: readonly ["openid", "identify", "email", "guilds", "connections"];
 /**
  * A Discord OAuth scope modeled by this package.
  */
@@ -34,6 +38,13 @@ 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";
+/**
+ * The only PKCE challenge method this package emits.
+ *
+ * `plain` is not offered: it provides no protection against an attacker who can read the
+ * authorization request, which is the threat PKCE exists to address.
+ */
+export declare const DISCORD_OAUTH_AUTHORIZE_CODE_CHALLENGE_METHOD = "S256";
 export interface DiscordOAuthAuthorizeUrlFactoryConfig {
     /**
      * The OAuth client id to authorize as.
@@ -63,6 +74,14 @@ export interface DiscordOAuthAuthorizeUrlParams {
      * short-lived.
      */
     readonly state?: Maybe<string>;
+    /**
+     * The PKCE code challenge — the base64url SHA-256 digest of a code verifier the caller retains.
+     *
+     * Discord supports PKCE S256. Optional because a state minted before PKCE was added carries no
+     * verifier, and sending a challenge the later exchange cannot answer would break that flow; every
+     * new authorization should set it.
+     */
+    readonly codeChallenge?: Maybe<string>;
 }
 export type DiscordOAuthAuthorizeUrlFactory = (params?: Maybe<DiscordOAuthAuthorizeUrlParams>) => WebsiteUrl;
 /**
@@ -85,7 +104,7 @@ export type DiscordOAuthAuthorizeUrlFactory = (params?: Maybe<DiscordOAuthAuthor
  *   scopes: ['identify']
  * });
  *
- * const url = authorizeUrlFactory({ state: 'signed-state' });
+ * const url = authorizeUrlFactory({ state: 'signed-state', codeChallenge: 's256-challenge' });
  * ```
  *
  * @__NO_SIDE_EFFECTS__

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

@@ -1,4 +1,4 @@
-import { type FactoryWithRequiredInput } from '@dereekb/util';
+import { type FactoryWithRequiredInput, type OidcClientAuthMethod } from '@dereekb/util';
 import { type ConfiguredFetch, type FetchJsonFunction } from '@dereekb/util/fetch';
 import { type DiscordOAuthClientId, type DiscordOAuthClientSecret } from '../discord.config';
 /**
@@ -17,6 +17,22 @@ 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";
+/**
+ * How this client authenticates itself at Discord's token and revocation endpoints.
+ *
+ * Discord's discovery document omits `token_endpoint_auth_methods_supported`, whose OIDC Discovery
+ * default is `client_secret_basic` — and Discord does in fact require Basic, rejecting the
+ * credentials-in-body form the OAuth relying-party layer otherwise defaults to.
+ */
+export declare const DISCORD_OAUTH_CLIENT_AUTH_METHOD: OidcClientAuthMethod;
+/**
+ * Discord's OIDC issuer.
+ *
+ * `https://discord.com/.well-known/openid-configuration` resolves against it, though this package
+ * does not perform discovery — the endpoint paths above are stable, so the extra round trip buys
+ * nothing. Exported for consumers that do want to discover.
+ */
+export declare const DISCORD_OIDC_ISSUER = "https://discord.com";
 /**
  * Path of the endpoint returning the user an access token belongs to.
  *