lunibee 0.1.7 → 0.2.0

package/dist/managers/message.d.ts

@@ -1,4 +1,12 @@
 import { Collection } from "@lunibee/collection";
+/** Opt-in per-channel message cache. Messages are temporary data, so they
+ * use bounded TTL/LRU storage rather than permanent resource storage. */
+export interface MessageCacheOptions {
+    /** Messages kept per channel; least-recently-used are evicted. Default 100. */
+    maxSize?: number;
+    /** Sliding TTL in ms. Omit for no expiry. */
+    ttl?: number;
+}
 import { REST } from "@lunibee/rest";
 import { Message, type ResourceContext } from "@lunibee/structures";
 export type MessageCreateOptions = Record<string, unknown> & {
@@ -9,8 +17,9 @@ export type MessageEditOptions = Record<string, unknown> & {
 };
 export declare class MessageManager {
     #private;
+    /** Cached messages; always empty unless a message cache is configured. */
     readonly cache: Collection<string, Message>;
-    constructor(rest: REST, context: ResourceContext, channelId: string);
+    constructor(rest: REST, context: ResourceContext, channelId: string, cache?: MessageCacheOptions);
     resolve(messageId: string): Promise<Message>;
     send(options: MessageCreateOptions): Promise<Message>;
     fetch(messageId: string): Promise<Message>;

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,53 @@
+/** Why a REST request failed, for handling without matching on status codes. */
+export type RESTErrorKind = 
+/** Cancelled through an AbortSignal. */
+"aborted"
+/** The attempt exceeded the transport timeout. */
+ | "timeout"
+/** No response: DNS, TLS, connection reset. */
+ | "network"
+/** 429 that outlived the retry budget. */
+ | "rateLimited"
+/** 401: invalid or revoked token. */
+ | "authentication"
+/** 403: missing access or permissions. */
+ | "permission"
+/** 404: unknown resource. */
+ | "notFound"
+/** 400 / 422: the request body or parameters were rejected. */
+ | "validation"
+/** 5xx: Discord failed to handle the request. */
+ | "server"
+/** Any other 4xx. */
+ | "client";
+/**
+ * Replaces the token segment of webhook and interaction paths with `:token`,
+ * so request paths can appear in errors, hooks and logs without leaking a
+ * credential.
+ */
+export declare function redactPath(path: string): string;
+/** Error thrown when Discord rejects a REST request. */
+export declare class RESTError extends Error {
+    /** Failure category. */ readonly kind: RESTErrorKind;
+    /** 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;
+        kind?: RESTErrorKind;
+    });
+    /** Whether sending the same request again later could succeed. Validation,
+     * permission, authentication and not-found failures never will. */
+    get retryable(): boolean;
+}
+/** 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,13 @@
-/** 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;
-    });
-}
 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;
 }
-/** Query-string value accepted by {@link RESTRequestOptions.query}. */
-export type RESTQuery = URLSearchParams | Record<string, string | number | boolean | null | undefined> | string;
 /**
  * Options controlling an individual REST request.
  *
@@ -112,7 +99,18 @@ export declare class REST {
         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. */
@@ -162,7 +160,13 @@ export declare class REST {
     patchWithFiles<T>(path: string, payload: unknown, files: RESTFileAttachment[], options?: RESTRequestOptions): Promise<T>;
 }
 export { Routes } from "./routes.js";
-export { type RateLimitStore, type BucketState, MemoryRateLimitStore, } from "./store.js";
+export { RESTError, abortError, redactPath, type RESTErrorKind, } 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";
 /**