@radiusplus/api-sdk-v2 0.5.0

package/src/_generated/zod/yearlyTimeframeSchema.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+* Generated by Kubb (https://kubb.dev/).
+* Do not edit manually.
+*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yearlyTimeframeSchema = void 0;
+const z = __importStar(require("zod"));
+exports.yearlyTimeframeSchema = z.object({
+    rollup: z.enum(['yearly']).describe('Provides data as a yearly aggregate').meta({ examples: ['yearly'] }),
+    period: z.string().regex(/^\d{4}(?:\/\d{4})?$/).describe('Format is YYYY for single period or YYYY/YYYY for ranges').meta({ examples: ['2025'] }),
+}).describe('Yearly timeframe with yearly rollup aggregation');

package/src/index.d.ts

@@ -0,0 +1,20 @@
+export * from "./_generated/index.js";
+export { createRetryTransport, type RetryOptions } from "./retryTransport.js";
+export { createRateLimitedTransport, type RateLimitOptions, type RateLimitedTransport, } from "./rateLimitedTransport.js";
+export { RateLimitedQueue, QueueCancelledError } from "./rateLimitedQueue.js";
+export type { QueueConfig, QueueEvent, BackpressureSignal } from "./rateLimitedQueue.js";
+export { paginatePages, paginateItems, collect } from "./pagination.js";
+export type { Page, PaginateInit } from "./pagination.js";
+import { RadiusApiV2 } from "./_generated/index.js";
+import type { ClientConfig } from "./_generated/index.js";
+import { type RateLimitOptions } from "./rateLimitedTransport.js";
+export type RadiusApiConfig = ClientConfig & {
+    /** Rate-limit + retry tuning. Ignored when an explicit `transport` is supplied. */
+    rateLimit?: RateLimitOptions;
+};
+/**
+ * Batteries-included RadiusApiV2: wires the rate-limited transport (shared per-client queue with
+ * proactive `X-RateLimit-*` backpressure, `maxConcurrent`/`minTime`, 429 pause-and-retry, and
+ * 5xx/network retry + timeout) by default. Pass `transport` to opt out, or `rateLimit` to tune it.
+ */
+export declare function createRadiusApi(config?: RadiusApiConfig): RadiusApiV2;

package/src/index.js

@@ -0,0 +1,44 @@
+"use strict";
+// Hand-written barrel: re-exports the generated client + types + zod schemas, plus the manual
+// SDK extensions (batteries-included factory, rate-limit/retry transports). Manual files live
+// alongside the synced `_generated/` tree and survive regeneration.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collect = exports.paginateItems = exports.paginatePages = exports.QueueCancelledError = exports.RateLimitedQueue = exports.createRateLimitedTransport = exports.createRetryTransport = void 0;
+exports.createRadiusApi = createRadiusApi;
+__exportStar(require("./_generated/index.js"), exports);
+var retryTransport_js_1 = require("./retryTransport.js");
+Object.defineProperty(exports, "createRetryTransport", { enumerable: true, get: function () { return retryTransport_js_1.createRetryTransport; } });
+var rateLimitedTransport_js_1 = require("./rateLimitedTransport.js");
+Object.defineProperty(exports, "createRateLimitedTransport", { enumerable: true, get: function () { return rateLimitedTransport_js_1.createRateLimitedTransport; } });
+var rateLimitedQueue_js_1 = require("./rateLimitedQueue.js");
+Object.defineProperty(exports, "RateLimitedQueue", { enumerable: true, get: function () { return rateLimitedQueue_js_1.RateLimitedQueue; } });
+Object.defineProperty(exports, "QueueCancelledError", { enumerable: true, get: function () { return rateLimitedQueue_js_1.QueueCancelledError; } });
+var pagination_js_1 = require("./pagination.js");
+Object.defineProperty(exports, "paginatePages", { enumerable: true, get: function () { return pagination_js_1.paginatePages; } });
+Object.defineProperty(exports, "paginateItems", { enumerable: true, get: function () { return pagination_js_1.paginateItems; } });
+Object.defineProperty(exports, "collect", { enumerable: true, get: function () { return pagination_js_1.collect; } });
+const index_js_1 = require("./_generated/index.js");
+const rateLimitedTransport_js_2 = require("./rateLimitedTransport.js");
+/**
+ * Batteries-included RadiusApiV2: wires the rate-limited transport (shared per-client queue with
+ * proactive `X-RateLimit-*` backpressure, `maxConcurrent`/`minTime`, 429 pause-and-retry, and
+ * 5xx/network retry + timeout) by default. Pass `transport` to opt out, or `rateLimit` to tune it.
+ */
+function createRadiusApi(config = {}) {
+    const { rateLimit, transport, ...rest } = config;
+    return new index_js_1.RadiusApiV2({ transport: transport ?? (0, rateLimitedTransport_js_2.createRateLimitedTransport)(rateLimit), ...rest });
+}

package/src/pagination.d.ts

@@ -0,0 +1,43 @@
+import type { PaginationRequest, PaginationResponse } from "./_generated/index.js";
+export interface PaginateInit {
+    /** Page size, sent as `pagination.limit` on every request. */
+    limit?: number;
+    /** Abort the walk between pages. */
+    signal?: AbortSignal;
+}
+/** A page must expose pagination metadata so the walker knows when to stop. */
+export type Page = {
+    pagination: PaginationResponse;
+};
+/**
+ * Lazily walk a cursor-paginated endpoint, yielding one page per request.
+ *
+ * `fetchPage` receives the pagination params (`limit` + the current `cursor`) to spread into the
+ * request body; the walker threads `nextCursor` for you and stops when `hasMore` is false. Each call
+ * runs through the client's normal pipeline, so rate limiting and retries apply per page.
+ *
+ * @example
+ * for await (const page of paginatePages(
+ *   (pagination) => api.search.searchFacilities({ body: { geography, pagination } }).then((r) => r.data),
+ * )) {
+ *   console.log(page.data.facilities, page.pagination.resultCount);
+ * }
+ */
+export declare function paginatePages<TPage extends Page>(fetchPage: (pagination: PaginationRequest) => Promise<TPage>, init?: PaginateInit): AsyncGenerator<TPage>;
+/**
+ * As {@link paginatePages}, but flattens each page to its items via `selectItems`.
+ *
+ * @example
+ * for await (const facility of paginateItems(
+ *   (pagination) => api.search.searchFacilities({ body: { geography, pagination } }).then((r) => r.data),
+ *   (page) => page.data.facilities,
+ * )) {
+ *   handle(facility);
+ * }
+ */
+export declare function paginateItems<TPage extends Page, TItem>(fetchPage: (pagination: PaginationRequest) => Promise<TPage>, selectItems: (page: TPage) => readonly TItem[], init?: PaginateInit): AsyncGenerator<TItem>;
+/**
+ * Opt-in eager collection: drain an async iterable into an array. `max` is required — it caps how
+ * many items are fetched so an accidental full-dataset walk can't run unbounded.
+ */
+export declare function collect<T>(source: AsyncIterable<T>, max: number): Promise<T[]>;

package/src/pagination.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginatePages = paginatePages;
+exports.paginateItems = paginateItems;
+exports.collect = collect;
+/**
+ * Lazily walk a cursor-paginated endpoint, yielding one page per request.
+ *
+ * `fetchPage` receives the pagination params (`limit` + the current `cursor`) to spread into the
+ * request body; the walker threads `nextCursor` for you and stops when `hasMore` is false. Each call
+ * runs through the client's normal pipeline, so rate limiting and retries apply per page.
+ *
+ * @example
+ * for await (const page of paginatePages(
+ *   (pagination) => api.search.searchFacilities({ body: { geography, pagination } }).then((r) => r.data),
+ * )) {
+ *   console.log(page.data.facilities, page.pagination.resultCount);
+ * }
+ */
+async function* paginatePages(fetchPage, init = {}) {
+    let cursor;
+    for (;;) {
+        if (init.signal?.aborted)
+            return;
+        const page = await fetchPage({ limit: init.limit, cursor });
+        yield page;
+        const { hasMore, nextCursor } = page.pagination;
+        if (!hasMore || !nextCursor)
+            return;
+        cursor = nextCursor;
+    }
+}
+/**
+ * As {@link paginatePages}, but flattens each page to its items via `selectItems`.
+ *
+ * @example
+ * for await (const facility of paginateItems(
+ *   (pagination) => api.search.searchFacilities({ body: { geography, pagination } }).then((r) => r.data),
+ *   (page) => page.data.facilities,
+ * )) {
+ *   handle(facility);
+ * }
+ */
+async function* paginateItems(fetchPage, selectItems, init = {}) {
+    for await (const page of paginatePages(fetchPage, init)) {
+        for (const item of selectItems(page))
+            yield item;
+    }
+}
+/**
+ * Opt-in eager collection: drain an async iterable into an array. `max` is required — it caps how
+ * many items are fetched so an accidental full-dataset walk can't run unbounded.
+ */
+async function collect(source, max) {
+    const out = [];
+    for await (const item of source) {
+        out.push(item);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}

package/src/rateLimitedQueue.d.ts

@@ -0,0 +1,108 @@
+type Listener = (...args: unknown[]) => void;
+declare class TinyEmitter {
+    private readonly listeners;
+    on(event: string | symbol, listener: Listener): this;
+    off(event: string | symbol, listener: Listener): this;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    removeAllListeners(event?: string | symbol): this;
+}
+export interface BackpressureSignal {
+    remaining: number | null;
+    resetAt: number | null;
+}
+export interface ExecutorResult<R> {
+    result: R;
+    backpressure?: BackpressureSignal;
+}
+export type Executor<T, R> = (item: T, signal: AbortSignal) => Promise<ExecutorResult<R>>;
+export interface ErrorControls {
+    retryAfter(ms: number): void;
+    skip(): void;
+}
+export interface QueueConfig {
+    maxConcurrent?: number;
+    minTime?: number;
+    reservoir?: number;
+    reservoirRefreshAmount?: number;
+    reservoirRefreshInterval?: number;
+    maxRetries?: number;
+    onError?: (error: unknown, controls: ErrorControls) => void;
+    /** Injectable wait, for tests. Defaults to real (unref'd) setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export type QueueEvent<T, R> = {
+    event: "batchStart";
+    size: number;
+    items: T[];
+} | {
+    event: "batchComplete";
+    succeeded: number;
+    retried: number;
+    skipped: number;
+    items: T[];
+} | {
+    event: "itemStart";
+    item: T;
+} | {
+    event: "itemComplete";
+    item: T;
+    result: R;
+} | {
+    event: "retry";
+    item: T;
+    attempt: number;
+    ms: number;
+} | {
+    event: "skip";
+    item: T;
+    error: unknown;
+} | {
+    event: "pause";
+    reason: "limitExhausted" | "retryAfter";
+} | {
+    event: "resume";
+} | {
+    event: "cancel";
+} | {
+    event: "complete";
+};
+export declare class QueueCancelledError extends Error {
+    constructor();
+}
+export declare class RateLimitedQueue<T, R> extends TinyEmitter {
+    private readonly executor;
+    private readonly maxConcurrent;
+    private readonly minTime;
+    private readonly reservoirRefreshAmount;
+    private readonly reservoirRefreshInterval;
+    private readonly maxRetries;
+    private readonly onErrorCb;
+    private readonly sleepFn;
+    private queue;
+    private inflightCount;
+    private remaining;
+    private resetAt;
+    private staticRemaining;
+    private staticTimer;
+    private lastSendTime;
+    private controller;
+    private cancelled;
+    private paused;
+    private processing;
+    private pauseMs;
+    private epoch;
+    constructor(executor: Executor<T, R>, config?: QueueConfig);
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    push(item: T): Promise<R>;
+    pushAll(items: T[]): Promise<R[]>;
+    cancel(): void;
+    /** Tear down for good: cancel in-flight work, stop the reservoir refresh interval, drop listeners. */
+    dispose(): void;
+    get size(): number;
+    get inflight(): number;
+    private processBatch;
+    private updateBackpressure;
+    private effectiveBudget;
+    private scheduleWake;
+}
+export {};

package/src/rateLimitedQueue.js

@@ -0,0 +1,317 @@
+"use strict";
+// Ported from radius-api-client-v1 (src/queue.ts). Kept close to the original so fixes can flow
+// both ways. Only change: an injectable `sleep` (defaults to real timers) so every wait — request
+// spacing and pause/resume — is deterministic in tests.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitedQueue = exports.QueueCancelledError = void 0;
+class TinyEmitter {
+    listeners = new Map();
+    on(event, listener) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            handlers.push(listener);
+        }
+        else {
+            this.listeners.set(event, [listener]);
+        }
+        return this;
+    }
+    off(event, listener) {
+        const handlers = this.listeners.get(event);
+        if (!handlers)
+            return this;
+        const next = handlers.filter((h) => h !== listener);
+        if (next.length === 0) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.set(event, next);
+        }
+        return this;
+    }
+    emit(event, ...args) {
+        const handlers = this.listeners.get(event);
+        if (!handlers || handlers.length === 0)
+            return false;
+        for (const listener of handlers.slice()) {
+            listener(...args);
+        }
+        return true;
+    }
+    removeAllListeners(event) {
+        if (event === undefined) {
+            this.listeners.clear();
+        }
+        else {
+            this.listeners.delete(event);
+        }
+        return this;
+    }
+}
+class QueueCancelledError extends Error {
+    constructor() {
+        super("Queue was cancelled");
+        this.name = "QueueCancelledError";
+    }
+}
+exports.QueueCancelledError = QueueCancelledError;
+const defaultSleep = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+});
+class RateLimitedQueue extends TinyEmitter {
+    executor;
+    maxConcurrent;
+    minTime;
+    reservoirRefreshAmount;
+    reservoirRefreshInterval;
+    maxRetries;
+    onErrorCb;
+    sleepFn;
+    queue = [];
+    inflightCount = 0;
+    remaining = null;
+    resetAt = null;
+    staticRemaining;
+    staticTimer = null;
+    lastSendTime = 0;
+    controller;
+    cancelled = false;
+    paused = false;
+    processing = false;
+    pauseMs = 0;
+    // Bumped on cancel() so a pause/resume wake scheduled before the cancel cannot fire against a
+    // later (reused) run — the injectable sleep gives no timer handle to clear.
+    epoch = 0;
+    constructor(executor, config) {
+        super();
+        this.executor = executor;
+        this.maxConcurrent = config?.maxConcurrent ?? Infinity;
+        this.minTime = config?.minTime ?? 0;
+        this.reservoirRefreshAmount = config?.reservoirRefreshAmount ?? null;
+        this.reservoirRefreshInterval = config?.reservoirRefreshInterval ?? 60_000;
+        this.maxRetries = config?.maxRetries ?? 3;
+        this.onErrorCb = config?.onError ?? ((_error, controls) => controls.skip());
+        this.sleepFn = config?.sleep ?? defaultSleep;
+        this.controller = new AbortController();
+        const initialReservoir = config?.reservoir ?? this.reservoirRefreshAmount;
+        this.staticRemaining = initialReservoir ?? null;
+        if (this.staticRemaining !== null && this.reservoirRefreshAmount !== null) {
+            this.staticTimer = setInterval(() => {
+                this.staticRemaining = this.reservoirRefreshAmount;
+            }, this.reservoirRefreshInterval);
+            this.staticTimer.unref?.();
+        }
+    }
+    emit(event, ...args) {
+        if (event !== "all" && typeof event === "string") {
+            super.emit("all", ...args);
+        }
+        return super.emit(event, ...args);
+    }
+    push(item) {
+        if (this.cancelled) {
+            this.controller = new AbortController();
+            this.cancelled = false;
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push({ item, resolve, reject, retries: 0 });
+            this.processBatch();
+        });
+    }
+    pushAll(items) {
+        return Promise.all(items.map((item) => this.push(item)));
+    }
+    cancel() {
+        this.cancelled = true;
+        this.epoch++;
+        this.controller.abort();
+        while (this.queue.length > 0) {
+            const job = this.queue.shift();
+            job.reject(new QueueCancelledError());
+        }
+        this.paused = false;
+        this.processing = false;
+        this.pauseMs = 0;
+        this.emit("cancel", { event: "cancel" });
+    }
+    /** Tear down for good: cancel in-flight work, stop the reservoir refresh interval, drop listeners. */
+    dispose() {
+        this.cancel();
+        if (this.staticTimer) {
+            clearInterval(this.staticTimer);
+            this.staticTimer = null;
+        }
+        this.removeAllListeners();
+    }
+    get size() {
+        return this.queue.length;
+    }
+    get inflight() {
+        return this.inflightCount;
+    }
+    async processBatch() {
+        if (this.cancelled || this.paused || this.queue.length === 0 || this.processing)
+            return;
+        const budget = this.effectiveBudget();
+        if (budget === 0) {
+            this.scheduleWake("limitExhausted");
+            return;
+        }
+        this.processing = true;
+        this.pauseMs = 0;
+        let poisoned = false;
+        let succeeded = 0;
+        let retried = 0;
+        let skipped = 0;
+        const batchSize = Math.min(this.maxConcurrent, budget ?? this.maxConcurrent, this.queue.length);
+        const batchJobs = this.queue.splice(0, batchSize);
+        const batchItems = batchJobs.map((j) => j.item);
+        this.emit("batchStart", { event: "batchStart", size: batchJobs.length, items: batchItems });
+        const dispatched = [];
+        const inflightPromises = [];
+        for (const job of batchJobs) {
+            if (poisoned || this.cancelled) {
+                this.queue.unshift(job);
+                continue;
+            }
+            const elapsed = Date.now() - this.lastSendTime;
+            if (this.minTime > 0 && elapsed < this.minTime) {
+                await this.sleepFn(this.minTime - elapsed);
+            }
+            if (poisoned || this.cancelled) {
+                this.queue.unshift(job);
+                continue;
+            }
+            this.emit("itemStart", { event: "itemStart", item: job.item });
+            if (this.staticRemaining !== null)
+                this.staticRemaining--;
+            this.lastSendTime = Date.now();
+            this.inflightCount++;
+            dispatched.push(job.item);
+            const promise = this.executor(job.item, this.controller.signal)
+                .then((executorResult) => {
+                this.inflightCount--;
+                job.resolve(executorResult.result);
+                succeeded++;
+                this.emit("itemComplete", { event: "itemComplete", item: job.item, result: executorResult.result });
+                if (executorResult.backpressure) {
+                    poisoned = this.updateBackpressure(executorResult.backpressure) || poisoned;
+                }
+            })
+                .catch((error) => {
+                this.inflightCount--;
+                if (this.cancelled) {
+                    job.reject(new QueueCancelledError());
+                    return;
+                }
+                const decision = { action: "skip", ms: 0 };
+                const controls = {
+                    retryAfter: (ms) => {
+                        decision.action = "retryAfter";
+                        decision.ms = ms;
+                    },
+                    skip: () => {
+                        decision.action = "skip";
+                    },
+                };
+                this.onErrorCb(error, controls);
+                if (decision.action === "retryAfter") {
+                    job.retries++;
+                    if (job.retries > this.maxRetries) {
+                        job.reject(error);
+                        skipped++;
+                        this.emit("skip", { event: "skip", item: job.item, error });
+                    }
+                    else {
+                        this.queue.unshift(job);
+                        retried++;
+                        poisoned = true;
+                        this.pauseMs = Math.max(this.pauseMs, decision.ms);
+                        this.emit("retry", { event: "retry", item: job.item, attempt: job.retries, ms: decision.ms });
+                    }
+                }
+                else {
+                    job.reject(error);
+                    skipped++;
+                    this.emit("skip", { event: "skip", item: job.item, error });
+                }
+            });
+            inflightPromises.push(promise);
+            const currentBudget = this.effectiveBudget();
+            if (currentBudget === 0)
+                poisoned = true;
+        }
+        await Promise.all(inflightPromises);
+        this.emit("batchComplete", {
+            event: "batchComplete",
+            succeeded,
+            retried,
+            skipped,
+            items: dispatched,
+        });
+        this.processing = false;
+        if (this.cancelled)
+            return;
+        if (this.queue.length === 0) {
+            this.emit("complete", { event: "complete" });
+            return;
+        }
+        if (poisoned || this.effectiveBudget() === 0) {
+            this.scheduleWake(this.pauseMs > 0 ? "retryAfter" : "limitExhausted");
+            return;
+        }
+        this.processBatch();
+    }
+    updateBackpressure(signal) {
+        if (signal.remaining === null && signal.resetAt === null)
+            return false;
+        if (signal.resetAt !== null && (this.resetAt === null || signal.resetAt > this.resetAt)) {
+            this.remaining = signal.remaining;
+            this.resetAt = signal.resetAt;
+        }
+        else if (signal.remaining !== null) {
+            this.remaining =
+                this.remaining !== null ? Math.min(this.remaining, signal.remaining) : signal.remaining;
+        }
+        return this.remaining === 0;
+    }
+    effectiveBudget() {
+        if (this.remaining !== null)
+            return this.remaining;
+        if (this.staticRemaining !== null)
+            return this.staticRemaining;
+        return null;
+    }
+    scheduleWake(reason) {
+        if (this.paused)
+            return;
+        this.paused = true;
+        this.emit("pause", { event: "pause", reason });
+        let delay;
+        if (this.pauseMs > 0) {
+            delay = this.pauseMs;
+        }
+        else if (this.resetAt !== null) {
+            delay = Math.max(1000, this.resetAt - Date.now());
+        }
+        else {
+            delay = this.reservoirRefreshInterval;
+        }
+        const wakeEpoch = this.epoch;
+        void this.sleepFn(delay).then(() => {
+            if (this.cancelled || wakeEpoch !== this.epoch)
+                return;
+            this.paused = false;
+            this.remaining = null;
+            this.resetAt = null;
+            if (this.reservoirRefreshAmount !== null) {
+                this.staticRemaining = this.reservoirRefreshAmount;
+            }
+            this.pauseMs = 0;
+            this.emit("resume", { event: "resume" });
+            this.processBatch();
+        });
+    }
+}
+exports.RateLimitedQueue = RateLimitedQueue;

package/src/rateLimitedTransport.d.ts

@@ -0,0 +1,39 @@
+import type { ResolvedRequest, Transport, TransportResult } from "./_generated/index.js";
+import { RateLimitedQueue } from "./rateLimitedQueue.js";
+export interface RateLimitOptions {
+    /** Max requests in flight at once. Default 10. */
+    maxConcurrent?: number;
+    /** Minimum ms between request starts. Default 0. */
+    minTime?: number;
+    /** Initial request budget before any response headers are seen. */
+    reservoir?: number;
+    /** Budget restored on each refresh interval. */
+    reservoirRefreshAmount?: number;
+    /** Reservoir refresh interval in ms, and the fallback pause when no reset time is known. Default 60_000. */
+    reservoirRefreshInterval?: number;
+    /** Retry attempts for 429 (queue) and for 5xx/network (inner). Default 3. */
+    maxRetries?: number;
+    /** Per-attempt timeout in ms. Unset = no timeout. */
+    timeoutMs?: number;
+    /** Base backoff for 5xx/network retries. Default 500. */
+    baseDelayMs?: number;
+    /** Backoff ceiling for 5xx/network retries. Default 10_000. */
+    maxDelayMs?: number;
+    /** Statuses the inner layer retries with backoff (429 is always driven by the queue). Default [408, 500, 502, 503, 504]. */
+    retryStatuses?: number[];
+    /** Base transport to wrap. Defaults to a built-in fetch transport. */
+    transport?: Transport;
+    /** Injectable wait, for tests. Applies to both the queue and the inner retry layer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export type RateLimitedTransport = Transport & {
+    /** The underlying queue: subscribe to events, `cancel()`, or read `size`/`inflight`. */
+    queue: RateLimitedQueue<ResolvedRequest, TransportResult>;
+};
+/**
+ * A rate-limited transport: a shared per-client queue enforcing `maxConcurrent`, `minTime`, and
+ * proactive backpressure from `X-RateLimit-*` headers (pausing before a 429), plus 429 pause-and-retry
+ * driven by `X-RateLimit-Reset`. Composed over {@link createRetryTransport} so 5xx and network errors
+ * are retried with backoff and each attempt can time out. Pass to `new RadiusApiV2({ transport })`.
+ */
+export declare function createRateLimitedTransport(options?: RateLimitOptions): RateLimitedTransport;