lunibee 0.1.6 → 0.1.8

package/dist/rest/decoder.d.ts

@@ -0,0 +1,23 @@
+/** Normalised shape of a Discord error payload. */
+export interface DecodedError {
+    message?: string;
+    code?: number;
+    retry_after?: number;
+    global?: boolean;
+}
+/** Turns a raw {@link Response} into a payload and the error metadata retries need. */
+export declare class ResponseDecoder {
+    /** Reads a Discord response payload as JSON, text, or nothing for 204. */
+    read(response: Response): Promise<unknown>;
+    /** Extracts Discord's error metadata from a decoded payload. */
+    errorData(payload: unknown): DecodedError;
+    /**
+     * Resolves Retry-After (seconds) from the payload, falling back to the
+     * header and finally to one second.
+     *
+     * An absent header is explicitly *not* a zero delay: `Number(null)` is 0,
+     * which is finite, so reading it directly would answer a 429 that carries
+     * no Retry-After by retrying immediately — exactly when backing off matters.
+     */
+    retryAfter(response: Response, data: DecodedError): number;
+}

package/dist/rest/errors.d.ts

@@ -0,0 +1,20 @@
+/** Error thrown when Discord rejects a REST request. */
+export declare class RESTError extends Error {
+    /** HTTP status returned by Discord. */ readonly status: number;
+    /** Discord API error code, when provided. */ readonly code?: number;
+    /** Raw Discord validation/error payload. */ readonly errors?: unknown;
+    /** HTTP method used for the failed request. */ readonly method?: string;
+    /** API path used for the failed request. */ readonly path?: string;
+    /** Creates a REST error with request context. @param message Error message. @param status HTTP status. @param code Discord error code. @param errors Raw error payload. @param options Request context and cause. */
+    constructor(message: string, status: number, code?: number, errors?: unknown, options?: {
+        method?: string;
+        path?: string;
+        cause?: unknown;
+    });
+}
+/** Creates the cancellation error shared by every stage of the request pipeline. */
+export declare function abortError(path: string, reason: unknown): RESTError;
+/** Waits for a delay, rejecting early if the signal aborts. */
+export declare function sleep(delay: number, signal: AbortSignal | undefined, path: string): Promise<void>;
+/** Awaits a promise, rejecting early if the signal aborts. */
+export declare function abortable(promise: Promise<void>, signal: AbortSignal | undefined, path: string): Promise<void>;

package/dist/rest/index.d.ts

@@ -1,26 +1,84 @@
-/** Error thrown when Discord rejects a REST request. */
-export declare class RESTError extends Error {
-    /** HTTP status returned by Discord. */ readonly status: number;
-    /** Discord API error code, when provided. */ readonly code?: number;
-    /** Raw Discord validation/error payload. */ readonly errors?: unknown;
-    /** HTTP method used for the failed request. */ readonly method?: string;
-    /** API path used for the failed request. */ readonly path?: string;
-    /** Creates a REST error with request context. @param message Error message. @param status HTTP status. @param code Discord error code. @param errors Raw error payload. @param options Request context and cause. */
-    constructor(message: string, status: number, code?: number, errors?: unknown, options?: {
-        method?: string;
-        path?: string;
-        cause?: unknown;
-    });
-}
-/** Options controlling an individual REST request. */
-export interface RESTRequestOptions {
-    /** Abort signal used to cancel the request and any queued wait. */ signal?: AbortSignal;
-}
+import { type RateLimitStore } from "./store.js";
+import { RESTError } from "./errors.js";
+import { type RESTQuery } from "./route.js";
+import { HttpTransport } from "./transport.js";
+/** A file attachment sent as part of a multipart REST request. */
 export interface RESTFileAttachment {
     name: string;
     data: Blob | Uint8Array | ArrayBuffer;
     contentType?: string;
 }
+/**
+ * Options controlling an individual REST request.
+ *
+ * Lunibee's canonical call shape is positional (`post(path, body)`); these options
+ * add the Discord.js-`@discordjs/rest`-familiar per-request knobs (`query`, `headers`,
+ * `reason`, `auth`) additively without changing that positional default.
+ */
+export interface RESTRequestOptions {
+    /** Abort signal used to cancel the request and any queued wait. */ signal?: AbortSignal;
+    /** Query-string appended to the path (`URLSearchParams`, a record, or a raw string). */ query?: RESTQuery;
+    /** Extra request headers merged in (library headers such as `Authorization` win). */ headers?: Record<string, string>;
+    /** Audit-log reason, sent as the `X-Audit-Log-Reason` header. */ reason?: string;
+    /** Set `false` to omit the `Authorization` header for this request. Defaults to `true`. */ auth?: boolean;
+}
+/**
+ * Discord.js-familiar request payload. Superset of {@link RESTRequestOptions} that also
+ * carries the `body` and `files`, matching `@discordjs/rest`'s `RequestData`. It powers the
+ * additive `method(path, { body })` overloads without breaking the positional signature.
+ */
+export interface RequestData extends RESTRequestOptions {
+    /** Request body. Encoded as JSON unless `files` are present (then multipart). */ body?: unknown;
+    /** File attachments; presence upgrades the request to `multipart/form-data`. */ files?: RESTFileAttachment[];
+}
+/** Context passed to `RESTHooks.onRequest`. */
+export interface RESTRequestContext {
+    method: string;
+    path: string;
+    attempt: number;
+}
+/** Context passed to `RESTHooks.onResponse`. */
+export interface RESTResponseContext {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+}
+/** Context passed to `RESTHooks.onRateLimit`. */
+export interface RESTRateLimitContext {
+    method: string;
+    path: string;
+    retryAfterMs: number;
+    global: boolean;
+    bucket?: string;
+}
+/** Context passed to `RESTHooks.onRetry`. */
+export interface RESTRetryContext {
+    method: string;
+    path: string;
+    attempt: number;
+    status: number;
+    delayMs: number;
+}
+/**
+ * Lightweight callback hooks for REST request lifecycle events.
+ *
+ * All callbacks are optional. They are dispatched in isolation from the request
+ * path (deferred to a microtask, and any thrown error is swallowed), so a hook
+ * cannot break or reject a request. Even so, hooks **must** be fast and
+ * non-blocking: heavy synchronous work in a hook still steals event-loop time
+ * from in-flight requests. Offload anything expensive to your own queue.
+ */
+export interface RESTHooks {
+    /** Called just before every HTTP attempt. */
+    onRequest?(ctx: RESTRequestContext): void;
+    /** Called after a successful or failed response is received. */
+    onResponse?(ctx: RESTResponseContext): void;
+    /** Called when a rate limit is encountered and the client is about to wait. */
+    onRateLimit?(ctx: RESTRateLimitContext): void;
+    /** Called when a failed request is about to be retried. */
+    onRetry?(ctx: RESTRetryContext): void;
+}
 /** Configures which REST failures may be retried. */
 export interface RetryPolicy {
     /** Maximum retry attempts. */ maxRetries: number;
@@ -39,7 +97,22 @@ export declare class REST {
         retries?: number;
         retryPolicy?: RetryPolicy;
         baseURL?: string;
+        hooks?: RESTHooks;
+        store?: RateLimitStore;
+        /** Replaces the HTTP stage, e.g. with a recording transport in tests. */
+        transport?: HttpTransport;
+        /**
+         * Lets requests on a bucket whose limit is known run concurrently, up
+         * to its `remaining` allowance, instead of one at a time. Requires a
+         * store with `reserve`. Requests on one bucket may then complete out
+         * of order (e.g. messages to one channel). Defaults to `false`.
+         */
+        concurrentBuckets?: boolean;
     });
+    /** The rate-limit store backing this transport. */
+    get store(): RateLimitStore;
+    /** Replaces the current hook set. Pass an empty object to clear all hooks. */
+    setHooks(hooks: RESTHooks): this;
     /** Sets the authentication token. @param token Discord bot token. @returns Nothing. @throws {TypeError} If token is empty. */
     setToken(token: string): void;
     /** Executes an HTTP request with Discord bucket/global rate limits, retry handling, and AbortSignal support.
@@ -47,16 +120,23 @@ export declare class REST {
      * @param method HTTP method.
      * @param path API path.
      * @param body Optional JSON body, FormData for file uploads, or undefined.
-     * @param options Cancellation options.
+     * @param options Request options: cancellation `signal` plus the Discord.js-familiar
+     *   `query`, `headers`, `reason`, `auth`, and `files` (which upgrade to multipart).
      * @returns Decoded response body.
      * @throws {RESTError} If Discord or transport rejects the request.
      */
-    request<T>(method: string, path: string, body?: unknown, options?: RESTRequestOptions): Promise<T>;
-    /** Sends a GET request. @param path API path. @param options Cancellation options. @returns Decoded response. @throws {RESTError} When the request fails. */ get<T>(path: string, options?: RESTRequestOptions): Promise<T>;
-    /** Sends a POST request. @param path API path. @param body Optional JSON body. @param options Cancellation options. @returns Decoded response. @throws {RESTError} When the request fails. */ post<T>(path: string, body?: unknown, options?: RESTRequestOptions): Promise<T>;
-    /** Sends a PATCH request. @param path API path. @param body Optional JSON body. @param options Cancellation options. @returns Decoded response. @throws {RESTError} When the request fails. */ patch<T>(path: string, body?: unknown, options?: RESTRequestOptions): Promise<T>;
-    /** Sends a PUT request. @param path API path. @param body Optional JSON body. @param options Cancellation options. @returns Decoded response. @throws {RESTError} When the request fails. */ put<T>(path: string, body?: unknown, options?: RESTRequestOptions): Promise<T>;
-    /** Sends a DELETE request. @param path API path. @param options Cancellation options. @returns Decoded response. @throws {RESTError} When the request fails. */ delete<T>(path: string, options?: RESTRequestOptions): Promise<T>;
+    request<T>(method: string, path: string, body?: unknown, options?: RequestData): Promise<T>;
+    /** Sends a GET request. @param path API path. @param options Request options (`query`, `headers`, `signal`, …). @returns Decoded response. @throws {RESTError} When the request fails. */ get<T>(path: string, options?: RequestData): Promise<T>;
+    /** Sends a POST request. Accepts a raw body (`post(path, body)`) or a Discord.js-familiar `post(path, { body })`. @param path API path. @param body Optional JSON body, or a `RequestData` wrapper. @param options Request options. @returns Decoded response. @throws {RESTError} When the request fails. */
+    post<T>(path: string, options: RequestData): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestData): Promise<T>;
+    /** Sends a PATCH request. Accepts a raw body (`patch(path, body)`) or a Discord.js-familiar `patch(path, { body })`. @param path API path. @param body Optional JSON body, or a `RequestData` wrapper. @param options Request options. @returns Decoded response. @throws {RESTError} When the request fails. */
+    patch<T>(path: string, options: RequestData): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: RequestData): Promise<T>;
+    /** Sends a PUT request. Accepts a raw body (`put(path, body)`) or a Discord.js-familiar `put(path, { body })`. @param path API path. @param body Optional JSON body, or a `RequestData` wrapper. @param options Request options. @returns Decoded response. @throws {RESTError} When the request fails. */
+    put<T>(path: string, options: RequestData): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: RequestData): Promise<T>;
+    /** Sends a DELETE request. @param path API path. @param options Request options (`reason`, `headers`, `signal`, …). @returns Decoded response. @throws {RESTError} When the request fails. */ delete<T>(path: string, options?: RequestData): Promise<T>;
     /**
      * Sends a multipart/form-data POST request for file uploads.
      * Attaches a JSON payload as `payload_json` and files as additional fields.
@@ -80,4 +160,18 @@ export declare class REST {
     patchWithFiles<T>(path: string, payload: unknown, files: RESTFileAttachment[], options?: RESTRequestOptions): Promise<T>;
 }
 export { Routes } from "./routes.js";
+export { RESTError, abortError } from "./errors.js";
+export { createRouteKey, normalizeRoutePath, majorParameter, scopeBucket, serializeQuery, type RouteKey, type RESTQuery, } from "./route.js";
+export { RequestScheduler } from "./scheduler.js";
+export { RateLimiter } from "./limiter.js";
+export { HttpTransport, TransportError, type TransportRequest, type FetchLike, } from "./transport.js";
+export { ResponseDecoder, type DecodedError } from "./decoder.js";
+export { type RateLimitStore, type BucketState, type Reservation, MemoryRateLimitStore, } from "./store.js";
+export { RedisRateLimitStore, type RedisRateLimitStoreOptions, type MinimalRedisClient, } from "./redis.js";
 export { WebhookClient, type WebhookClientOptions, type WebhookMessageOptions, } from "./webhook.js";
+/**
+ * Discord.js-familiar alias for {@link RESTError}. `@discordjs/rest` throws `DiscordAPIError`
+ * on a Discord-rejected request; Lunibee keeps `RESTError` as the canonical class and exports
+ * this alias so Discord.js-shaped `catch (err) { if (err instanceof DiscordAPIError) … }` works.
+ */
+export { RESTError as DiscordAPIError };