@foundatiofx/fetchclient 0.47.0

package/types/src/ProblemDetails.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Represents a problem details object.
+ */
+export declare class ProblemDetails implements Record<string, unknown> {
+    [key: string]: unknown;
+    /**
+     * The type of the problem details.
+     */
+    type?: string;
+    /**
+     * The title of the problem details.
+     */
+    title?: string;
+    /**
+     * The HTTP status code of the problem details.
+     */
+    status?: number;
+    /**
+     * Additional details about the problem.
+     */
+    detail?: string;
+    /**
+     * The URI of the specific occurrence of the problem.
+     */
+    instance?: string;
+    /**
+     * Represents the errors associated with a problem details response.
+     */
+    errors: Record<string, string[] | undefined>;
+    /**
+     * Clears the error with the specified name.
+     * @param name - The name of the error to clear.
+     * @returns The updated ProblemDetails instance.
+     */
+    clear(name: string): ProblemDetails;
+    /**
+     * Sets the error message for the general error.
+     * @param message - The error message to set.
+     * @returns The updated ProblemDetails instance.
+     */
+    setErrorMessage(message: string): ProblemDetails;
+}
+//# sourceMappingURL=ProblemDetails.d.ts.map

package/types/src/ProblemDetails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProblemDetails.d.ts","sourceRoot":"","sources":["../../src/src/ProblemDetails.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,YAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAM;IAElD;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAKnC;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc;CAIjD"}

package/types/src/RateLimit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimit.test.d.ts","sourceRoot":"","sources":["../../src/src/RateLimit.test.ts"],"names":[],"mappings":""}

package/types/src/RateLimitMiddleware.d.ts

@@ -0,0 +1,50 @@
+import type { FetchClientMiddleware } from "./FetchClientMiddleware.js";
+import { RateLimiter, type RateLimiterOptions } from "./RateLimiter.js";
+/**
+ * Rate limiting error thrown when requests exceed the rate limit.
+ */
+export declare class RateLimitError extends Error {
+    readonly resetTime: number;
+    readonly remainingRequests: number;
+    constructor(resetTime: number, remainingRequests: number, message?: string);
+}
+/**
+ * Configuration options for the rate limiting middleware.
+ */
+export interface RateLimitMiddlewareOptions extends RateLimiterOptions {
+    /**
+     * Whether to throw an error when rate limit is exceeded.
+     * If false, the middleware will set a 429 status response.
+     * @default true
+     */
+    throwOnRateLimit?: boolean;
+    /**
+     * Custom error message when rate limit is exceeded.
+     */
+    errorMessage?: string;
+    /**
+     * Whether to automatically update rate limits based on response headers.
+     * @default true
+     */
+    autoUpdateFromHeaders?: boolean;
+}
+/**
+ * Rate limiting middleware instance that can be shared across requests.
+ */
+export declare class RateLimitMiddleware {
+    #private;
+    private readonly throwOnRateLimit;
+    private readonly errorMessage?;
+    private readonly autoUpdateFromHeaders;
+    constructor(options: RateLimitMiddlewareOptions);
+    /**
+     * Gets the underlying rate limiter instance.
+     */
+    get rateLimiter(): RateLimiter;
+    /**
+     * Creates the middleware function.
+     * @returns The middleware function
+     */
+    middleware(): FetchClientMiddleware;
+}
+//# sourceMappingURL=RateLimitMiddleware.d.ts.map

package/types/src/RateLimitMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimitMiddleware.d.ts","sourceRoot":"","sources":["../../src/src/RateLimitMiddleware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,OAAO,EAGL,WAAW,EACX,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,iBAAiB,EAAE,MAAM,CAAC;gBAE9B,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAW3E;AAED;;GAEG;AACH,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,qBAAa,mBAAmB;;IAG9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAU;gBAEpC,OAAO,EAAE,0BAA0B;IAO/C;;OAEG;IACH,IAAW,WAAW,IAAI,WAAW,CAEpC;IAED;;;OAGG;IACI,UAAU,IAAI,qBAAqB;CA8F3C"}

package/types/src/RateLimiter.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Per-group rate limiter options that can override the global options.
+ */
+export interface GroupRateLimiterOptions {
+    /**
+     * Maximum number of requests allowed per time window for this group.
+     */
+    maxRequests?: number;
+    /**
+     * Time window in milliseconds for this group.
+     */
+    windowSeconds?: number;
+    /**
+     * Callback function called when rate limit is exceeded for this group.
+     * @param resetTime - Time when the rate limit will reset (in milliseconds since epoch)
+     */
+    onRateLimitExceeded?: (resetTime: number) => void;
+}
+/**
+ * Configuration options for the rate limiter.
+ */
+export interface RateLimiterOptions {
+    /**
+     * Maximum number of requests allowed per time window.
+     */
+    maxRequests: number;
+    /**
+     * Time window in seconds.
+     */
+    windowSeconds: number;
+    /**
+     * Optional group generator function to create unique rate limit buckets.
+     * If not provided, a global rate limit is applied.
+     * @param url - The request URL
+     * @returns A string group to identify the rate limit bucket
+     */
+    getGroupFunc?: (url: string) => string;
+    /**
+     * Callback function called when rate limit is exceeded.
+     * @param resetTime - Time when the rate limit will reset (in milliseconds since epoch)
+     */
+    onRateLimitExceeded?: (resetTime: number) => void;
+    /**
+     * Optional group-specific rate limit options.
+     * Map of group keys to their specific rate limit options.
+     */
+    groups?: Record<string, GroupRateLimiterOptions>;
+}
+/**
+ * A rate limiter that tracks requests per time window.
+ */
+export declare class RateLimiter {
+    private readonly options;
+    private readonly buckets;
+    private readonly groupOptions;
+    constructor(options: RateLimiterOptions);
+    /**
+     * Checks if a request is allowed and updates the rate limit state.
+     * @param url - The request URL
+     * @returns True if the request is allowed, false if rate limit is exceeded
+     */
+    isAllowed(url: string): boolean;
+    /**
+     * Gets the current request count for a specific key.
+     * @param url - The request URL
+     * @returns The current number of requests in the time window
+     */
+    getRequestCount(url: string): number;
+    /**
+     * Gets the remaining requests allowed for a specific key.
+     * @param url - The request URL
+     * @returns The number of remaining requests allowed
+     */
+    getRemainingRequests(url: string): number;
+    /**
+     * Gets the time when the rate limit will reset for a specific key.
+     * @param url - The request URL
+     * @returns The reset time in milliseconds since epoch, or null if no bucket exists
+     */
+    getResetTime(url: string): number | null;
+    /**
+     * Clears the rate limit state for a specific key.
+     * @param url - The request URL
+     */
+    clearBucket(url: string): void;
+    /**
+     * Gets the group key for a URL.
+     * @param url - The request URL
+     * @returns The group key
+     */
+    getGroup(url: string): string;
+    /**
+     * Gets the options for a specific group. Falls back to global options if not set.
+     * @param group - The group key
+     * @returns The options for the group
+     */
+    getGroupOptions(group: string): GroupRateLimiterOptions;
+    /**
+     * Checks if a group has specific options set.
+     * @param group - The group key
+     * @returns True if the group has options, false otherwise
+     */
+    hasGroupOptions(group: string): boolean;
+    /**
+     * Sets options for a specific group.
+     * @param group - The group key
+     * @param options - The options to set
+     */
+    setGroupOptions(group: string, options: GroupRateLimiterOptions): void;
+    /**
+     * Sets rate limit options for a request.
+     * @param url - The request URL
+     * @param options - The options to set for this group
+     */
+    setOptionsForRequest(url: string, options: GroupRateLimiterOptions): void;
+    /**
+     * Updates rate limit options for a request based on standard rate limit headers.
+     * @param url - The request URL
+     * @param method - The HTTP method
+     * @param headers - The response headers containing rate limit information
+     */
+    updateFromHeadersForRequest(url: string, headers: Headers): void;
+    /**
+     * Updates rate limit options based on standard rate limit headers.
+     * @param group - The group key
+     * @param headers - The response headers containing rate limit information
+     */
+    updateFromHeaders(group: string, headers: Headers): void;
+    /**
+     * Clears all rate limit state.
+     */
+    clearAll(): void;
+}
+/**
+ * Creates a group generator function that groups requests by domain only (no protocol).
+ * @param url - The request URL
+ * @returns A string representing the domain without protocol
+ */
+export declare function groupByDomain(url: string): string;
+/**
+ * IETF rate limit header information structure.
+ */
+export interface RateLimitInfo {
+    /** The policy name/identifier */
+    policy: string;
+    /** Maximum requests allowed (quota) */
+    limit: number;
+    /** Remaining requests */
+    remaining: number;
+    /** Reset time in seconds from now */
+    resetSeconds: number;
+    /** Window duration in seconds */
+    windowSeconds?: number;
+}
+/**
+ * Creates an IETF standard RateLimit header value.
+ * @param info - The rate limit information
+ * @returns The formatted RateLimit header value
+ */
+export declare function buildRateLimitHeader(info: Omit<RateLimitInfo, "limit" | "windowSeconds">): string;
+/**
+ * Creates an IETF standard RateLimit-Policy header value.
+ * @param info - The rate limit information
+ * @returns The formatted RateLimit-Policy header value
+ */
+export declare function buildRateLimitPolicyHeader(info: Omit<RateLimitInfo, "remaining" | "resetSeconds">): string;
+/**
+ * Parses an IETF standard RateLimit header value.
+ * @param headerValue - The RateLimit header value to parse
+ * @returns The parsed rate limit information or null if invalid
+ */
+export declare function parseRateLimitHeader(headerValue: string): Partial<RateLimitInfo> | null;
+/**
+ * Parses an IETF standard RateLimit-Policy header value.
+ * @param headerValue - The RateLimit-Policy header value to parse
+ * @returns The parsed rate limit policy information or null if invalid
+ */
+export declare function parseRateLimitPolicyHeader(headerValue: string): Partial<RateLimitInfo> | null;
+//# sourceMappingURL=RateLimiter.d.ts.map

package/types/src/RateLimiter.d.ts.map

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

package/types/src/RequestOptions.d.ts

@@ -0,0 +1,64 @@
+import type { CacheKey } from "./FetchClientCache.js";
+import type { FetchClientResponse } from "./FetchClientResponse.js";
+/**
+ * Represents the options for making a request using the FetchClient.
+ */
+export type RequestOptions = {
+    /**
+     * Specifies whether the model should be validated before making the request.
+     */
+    shouldValidateModel?: boolean;
+    /**
+     * Additional parameters to be included in the request.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * By default, the client will throw an error on non-successful and unexpected status codes (outside of 200-299). Use this option to disable that behavior off.
+     */
+    shouldThrowOnUnexpectedStatusCodes?: boolean;
+    /**
+     * By default, non-successful status codes (outside of 200-299) will throw an error. Any status code that you wish to
+     * handle manually instead of an error being thrown should be included here.
+     */
+    expectedStatusCodes?: number[];
+    /**
+     * Additional headers to be included in the request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * A callback function to handle non-expected errors that occur during the request. By default, non-successful status
+     * codes (outside of 200-299) are considered errors and will throw. If the callback returns true, the error will
+     * be treated as handled and ignored. If the callback returns false or doesn't return a value, the error will be thrown.
+     */
+    errorCallback?: (error: FetchClientResponse<unknown>) => boolean | void;
+    /**
+     * Timeout duration for the request in milliseconds. If the request takes longer than this duration, it will be aborted and will throw an error.
+     */
+    timeout?: number;
+    /**
+     * An AbortSignal object that can be used to cancel the request.
+     */
+    signal?: AbortSignal;
+    /**
+     * Specifies whether the JSON parsing should convert strings that look like dates into Date instances.
+     */
+    shouldParseDates?: boolean;
+    /**
+     * Specifies a reviver function to use for JSON response parsing.
+     */
+    reviver?: (this: unknown, key: string, value: unknown) => unknown;
+} & Record<string, unknown>;
+/**
+ * Represents the options for a GET request.
+ */
+export type GetRequestOptions = RequestOptions & {
+    /**
+     * The cache key for the request.
+     */
+    cacheKey?: CacheKey;
+    /**
+     * The duration for which the response should be cached, in milliseconds.
+     */
+    cacheDuration?: number;
+};
+//# sourceMappingURL=RequestOptions.d.ts.map

package/types/src/RequestOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestOptions.d.ts","sourceRoot":"","sources":["../../src/src/RequestOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC;;OAEG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;IAE7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,KAAK,OAAO,GAAG,IAAI,CAAC;IAExE;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACnE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC"}