@jaredwray/mockhttp 1.6.1 → 1.8.1

package/README.md

@@ -13,6 +13,7 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 # Features
 * All the features of [httpbin](https://httpbin.org/)
 * Taps - Inject custom responses for testing and development
+* Bins - Capture and inspect incoming HTTP requests (great for webhook debugging)
 * `@fastify/helmet` built in by default
 * Built with `nodejs`, `typescript`, and `fastify`
 * Deploy via `docker` or `nodejs`
@@ -28,6 +29,7 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 - [HTTPS Support](#https-support)
 - [HTTP/2 Support](#http2-support)
 - [Response Injection (Tap Feature)](#response-injection-tap-feature)
+- [Request Bins](#request-bins)
 - [Rate Limiting](#rate-limiting)
 - [Logging](#logging)
 - [Flexible URL Matching](#flexible-url-matching)
@@ -431,6 +433,362 @@ const tap = mock.taps.inject(
 );
 ```
 
+# Request Bins
+
+Bins are ephemeral URL endpoints that **capture incoming HTTP requests** so you
+can inspect them later. They're the inverse of Taps: instead of injecting a
+response, they record everything they receive. Useful for:
+
+- **Debugging webhooks** — point Stripe / GitHub / Slack at a bin URL and see
+  exactly what they send
+- **Exercising client SDKs** — verify your SDK sends the request shape you expect
+- **Recording fixtures** — capture real traffic to replay in tests later
+
+There are two URL prefixes:
+
+- **`/bins`** — JSON management API: create, list, inspect, delete bins
+- **`/b/:id`** — the capture URL. Any HTTP method, any sub-path, any body sent
+  here is stored against bin `:id`
+
+## Quick Start
+
+```bash
+# 1. create a bin
+curl -s -X POST http://localhost:3000/bins
+# → { "id": "abc123def456", "url": "http://localhost:3000/b/abc123def456",
+#     "createdAt": "2026-05-18T12:00:00.000Z",
+#     "expiresAt": "2026-05-19T12:00:00.000Z",
+#     "requestCount": 0 }
+
+# 2. send anything to the capture URL
+curl -X POST "http://localhost:3000/b/abc123def456/webhook?source=stripe" \
+  -H 'content-type: application/json' \
+  -d '{"event":"payment.succeeded"}'
+# → { "ok": true, "binId": "abc123def456", "requestId": "f9c2e1a40b3d" }
+
+# 3. list captured requests (newest first)
+curl http://localhost:3000/bins/abc123def456/requests
+```
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/bins` | Create a new bin |
+| GET | `/bins` | List all active bins |
+| GET | `/bins/:id` | Get bin metadata |
+| GET | `/bins/:id/requests` | List captured requests (newest first) |
+| GET | `/bins/:id/requests/:reqId` | Get a single captured request |
+| DELETE | `/bins/:id/requests` | Clear all captured requests in a bin |
+| DELETE | `/bins/:id` | Delete a bin |
+| ANY | `/b/:id` and `/b/:id/*` | Capture requests sent to a bin |
+
+## End-to-End Webhook Debugging Example
+
+A complete walkthrough using curl:
+
+```bash
+BASE=http://localhost:3000
+
+# Create the bin and grab its id
+ID=$(curl -s -X POST $BASE/bins | jq -r .id)
+echo "Bin URL: $BASE/b/$ID"
+
+# Simulate a Stripe webhook
+curl -s -X POST "$BASE/b/$ID/stripe/events?secret=whsec_test" \
+  -H 'content-type: application/json' \
+  -H 'stripe-signature: t=1700000000,v1=abc123' \
+  -d '{"id":"evt_1","type":"payment_intent.succeeded","data":{"object":{"amount":2000}}}'
+
+# Simulate a GitHub webhook
+curl -s -X POST "$BASE/b/$ID/github" \
+  -H 'content-type: application/json' \
+  -H 'x-github-event: pull_request' \
+  -d '{"action":"opened","number":42}'
+
+# Inspect everything that arrived
+curl -s "$BASE/bins/$ID/requests" | jq
+
+# Drill into the most recent one
+RID=$(curl -s "$BASE/bins/$ID/requests" | jq -r '.requests[0].id')
+curl -s "$BASE/bins/$ID/requests/$RID" | jq
+#   {
+#     "id": "f9c2e1a40b3d",
+#     "binId": "abc123def456",
+#     "method": "POST",
+#     "url": "/github",
+#     "path": "/github",
+#     "query": {},
+#     "headers": {
+#       "host": "localhost:3000",
+#       "content-type": "application/json",
+#       "x-github-event": "pull_request"
+#     },
+#     "remoteAddress": "127.0.0.1",
+#     "contentType": "application/json",
+#     "bodySize": 32,
+#     "body": "{\"action\":\"opened\",\"number\":42}",
+#     "bodyEncoding": "utf8",
+#     "truncated": false,
+#     "capturedAt": "2026-05-18T12:00:01.234Z"
+#   }
+
+# Clean up
+curl -s -X DELETE "$BASE/bins/$ID/requests"  # clear captures, keep the bin
+curl -s -X DELETE "$BASE/bins/$ID"           # delete the bin entirely
+```
+
+## Captured Request Shape
+
+```json
+{
+  "id": "f9c2e1a40b3d",
+  "binId": "abc123def456",
+  "method": "POST",
+  "url": "/webhook?source=stripe",
+  "path": "/webhook",
+  "query": { "source": "stripe" },
+  "headers": { "content-type": "application/json", "...": "..." },
+  "remoteAddress": "127.0.0.1",
+  "contentType": "application/json",
+  "bodySize": 32,
+  "body": "{\"event\":\"payment.succeeded\"}",
+  "bodyEncoding": "utf8",
+  "truncated": false,
+  "capturedAt": "2026-05-18T12:00:00.000Z"
+}
+```
+
+- **`url`** is the request URL relative to the bin (everything after `/b/:id`).
+- **`path`** is the sub-path only, without the query string.
+- **`bodyEncoding`** is `"utf8"` for text content types (text/*, application/json,
+  application/xml, application/x-www-form-urlencoded, application/javascript),
+  `"base64"` for everything else (binary payloads), or `"none"` when no body
+  was sent.
+- **`truncated`** is `true` when the body exceeded `maxBodySize` and was cut
+  off. `bodySize` reflects the original length.
+
+## Body Encoding Examples
+
+### Text Content (UTF-8)
+
+JSON, XML, form-encoded, plain text, and JavaScript are stored as UTF-8 strings
+so you can read them directly:
+
+```bash
+curl -X POST "http://localhost:3000/b/$ID" \
+  -H 'content-type: application/json' \
+  -d '{"hello":"world"}'
+
+curl -s "http://localhost:3000/bins/$ID/requests" | jq '.requests[0] | {bodyEncoding, body}'
+# {
+#   "bodyEncoding": "utf8",
+#   "body": "{\"hello\":\"world\"}"
+# }
+```
+
+### Binary Content (Base64)
+
+Any non-text content type is base64-encoded, preserving the bytes exactly:
+
+```bash
+# Upload a PNG to the bin
+curl -X POST "http://localhost:3000/b/$ID/upload" \
+  -H 'content-type: image/png' \
+  --data-binary @logo.png
+
+curl -s "http://localhost:3000/bins/$ID/requests" | jq '.requests[0] | {bodyEncoding, bodySize}'
+# {
+#   "bodyEncoding": "base64",
+#   "bodySize": 14823
+# }
+
+# Decode the body back to bytes
+curl -s "http://localhost:3000/bins/$ID/requests" \
+  | jq -r '.requests[0].body' | base64 -d > recovered.png
+```
+
+### Truncation
+
+Bodies larger than `maxBodySize` (1 MiB by default) are cut off and flagged:
+
+```javascript
+// In test setup
+import { MockHttp, BinManager } from '@jaredwray/mockhttp';
+const mock = new MockHttp();
+mock.bins = new BinManager({ maxBodySize: 1024 }); // 1 KiB cap
+await mock.start();
+```
+
+```bash
+# Send 5000 bytes to a bin with a 1 KiB cap
+head -c 5000 /dev/urandom | curl -X POST "http://localhost:3000/b/$ID" \
+  -H 'content-type: application/octet-stream' \
+  --data-binary @-
+
+curl -s "http://localhost:3000/bins/$ID/requests" | jq '.requests[0] | {bodySize, truncated, body_len: (.body | length)}'
+# {
+#   "bodySize": 5000,        ← original size
+#   "truncated": true,
+#   "body_len": 1368         ← base64 of the first 1024 bytes
+# }
+```
+
+## FIFO Eviction Example
+
+Once a bin reaches `maxRequestsPerBin` captures (100 by default), the oldest
+ones are dropped:
+
+```bash
+# Send 105 requests
+for i in $(seq 1 105); do
+  curl -s -X POST "http://localhost:3000/b/$ID/event/$i" > /dev/null
+done
+
+# The bin holds the most recent 100; the first 5 are gone
+curl -s "http://localhost:3000/bins/$ID/requests" | jq '.requests | length'
+# 100
+
+# Newest is at the top
+curl -s "http://localhost:3000/bins/$ID/requests" | jq '.requests[0].path'
+# "/event/105"
+```
+
+## Programmatic Access
+
+The bin manager is exposed on the `MockHttp` instance as `mock.bins`. This
+makes it easy to drive bins from a test suite without going through HTTP:
+
+```javascript
+import { MockHttp } from '@jaredwray/mockhttp';
+
+const mock = new MockHttp({ logging: false });
+await mock.start();
+
+// Create a bin
+const bin = mock.bins.createBin();
+console.log(`Webhook target: http://localhost:${mock.port}/b/${bin.id}`);
+
+// ... point your code-under-test at that URL ...
+
+// Read captured requests (newest first)
+const requests = mock.bins.getRequests(bin.id);
+console.log(`Captured ${requests.length} requests`);
+
+for (const req of requests) {
+  console.log(`${req.method} ${req.path} (${req.bodySize} bytes)`);
+}
+
+// Clean up
+mock.bins.deleteBin(bin.id);
+await mock.close(); // also stops the bin cleanup timer
+```
+
+### Using Bins in a Vitest Test
+
+```typescript
+import { afterAll, beforeAll, expect, test } from 'vitest';
+import { MockHttp } from '@jaredwray/mockhttp';
+
+let mock: MockHttp;
+
+beforeAll(async () => {
+  mock = new MockHttp({ logging: false });
+  await mock.start();
+});
+
+afterAll(async () => {
+  await mock.close();
+});
+
+test('my SDK sends the right webhook payload', async () => {
+  const bin = mock.bins.createBin();
+  const webhookUrl = `http://localhost:${mock.port}/b/${bin.id}`;
+
+  // Drive your SDK at the bin
+  await mySdk.notify(webhookUrl, { event: 'user.created', id: 42 });
+
+  // Assert on what actually arrived
+  const [captured] = mock.bins.getRequests(bin.id);
+  expect(captured.method).toBe('POST');
+  expect(captured.contentType).toBe('application/json');
+  expect(JSON.parse(captured.body!)).toEqual({
+    event: 'user.created',
+    id: 42,
+  });
+  expect(captured.headers['x-signature']).toBeDefined();
+});
+```
+
+## Configuration
+
+Bins are enabled by default. To disable the routes entirely:
+
+```javascript
+const mock = new MockHttp({
+  httpBin: { bins: false },
+});
+```
+
+To tune limits, replace the default `BinManager` before starting:
+
+```javascript
+import { MockHttp, BinManager } from '@jaredwray/mockhttp';
+
+const mock = new MockHttp();
+mock.bins = new BinManager({
+  defaultTtlMs: 60 * 60 * 1000,    // 1 hour (default: 24h)
+  maxRequestsPerBin: 500,           // (default: 100)
+  maxBodySize: 5 * 1024 * 1024,     // 5 MiB (default: 1 MiB)
+  idLength: 16,                     // (default: 12)
+  cleanupIntervalMs: 30 * 1000,     // sweep every 30s (default: 60s)
+});
+
+await mock.start();
+```
+
+### Defaults
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `defaultTtlMs` | `86400000` (24h) | Bin lifetime. Expired bins return 404 and are lazily removed. |
+| `maxRequestsPerBin` | `100` | When exceeded, oldest captures are dropped (FIFO). |
+| `maxBodySize` | `1048576` (1 MiB) | Larger bodies are truncated; `truncated: true` is set on the capture. |
+| `idLength` | `12` | Length of generated bin and request ids. |
+| `cleanupIntervalMs` | `60000` (1 min) | How often expired bins are swept. The timer is `unref()`'d so it never keeps the process alive. |
+
+### Pluggable Storage
+
+`BinManager` accepts a `store: BinStore` so you can plug in alternative
+backends (Redis, SQLite, etc.) without changing the rest of the codebase. The
+default `InMemoryBinStore` keeps state in process memory.
+
+```typescript
+import {
+  BinManager,
+  InMemoryBinStore,
+  type Bin,
+  type BinStore,
+  type CapturedRequest,
+} from '@jaredwray/mockhttp';
+
+class RedisBinStore implements BinStore {
+  createBin(bin: Bin): void { /* SET bin:${bin.id} ... */ }
+  getBin(id: string): Bin | undefined { /* GET ... */ }
+  listBins(): Bin[] { /* SCAN ... */ }
+  deleteBin(id: string): boolean { /* DEL ... */ }
+  addRequest(binId: string, req: CapturedRequest, max: number): void {
+    /* LPUSH bin:${binId}:requests + LTRIM to max */
+  }
+  getRequests(binId: string): CapturedRequest[] { /* LRANGE ... */ }
+  getRequest(binId: string, reqId: string): CapturedRequest | undefined { /* ... */ }
+  clearRequests(binId: string): void { /* DEL bin:${binId}:requests */ }
+  cleanupExpired(now: number): string[] { /* scan + delete */ return []; }
+}
+
+mock.bins = new BinManager({ store: new RedisBinStore() });
+```
+
 # Rate Limiting
 
 MockHttp supports rate limiting using [@fastify/rate-limit](https://github.com/fastify/fastify-rate-limit). Rate limiting is **enabled by default** at **1000 requests per minute** with **localhost (127.0.0.1 and ::1) excluded** from rate limiting.
@@ -654,6 +1012,7 @@ new MockHttp(options?)
     - `anything?`: boolean - Enable anything routes (default: true)
     - `auth?`: boolean - Enable authentication routes (default: true)
     - `images?`: boolean - Enable image routes (default: true)
+    - `bins?`: boolean - Enable request bin routes /bins and /b/:id (default: true)
   - `https?`: boolean | HttpsOptions - Enable HTTPS with auto-generated or custom certificates (default: undefined/disabled)
   - `http2?`: boolean - Enable HTTP/2 support (default: false)
   - `http1?`: boolean - Allow HTTP/1.1 fallback when using HTTP/2 with HTTPS (default: true)
@@ -675,6 +1034,7 @@ new MockHttp(options?)
 - `http1`: boolean - Get/set HTTP/1.1 fallback for HTTP/2 with HTTPS
 - `server`: FastifyInstance - Get/set the Fastify server instance
 - `taps`: TapManager - Get/set the TapManager instance
+- `bins`: BinManager - Get/set the BinManager instance for request bins
 
 ### Methods
 
@@ -736,6 +1096,68 @@ Register authentication routes (basic, bearer, digest, hidden-basic).
 
 Register image routes (jpeg, png, svg, webp) with content negotiation support.
 
+#### `async registerBinRoutes(fastifyInstance?)`
+
+Register the request bin routes — management at `/bins` and capture at `/b/:id`.
+
+## Bins (Request Capture)
+
+Access the BinManager via `mockHttp.bins` to manage request bins programmatically. See [Request Bins](#request-bins) for usage examples.
+
+### `bins.createBin()`
+
+Create a new bin with the configured TTL.
+
+**Returns:** `Bin` — `{ id, createdAt, expiresAt, requestCount }`
+
+### `bins.getBin(id)`
+
+Look up a bin by id. Returns `undefined` if the bin does not exist or has expired (and lazily removes the expired entry).
+
+**Returns:** `Bin | undefined`
+
+### `bins.listBins()`
+
+List all non-expired bins.
+
+**Returns:** `Bin[]`
+
+### `bins.deleteBin(id)`
+
+Delete a bin and all its captured requests.
+
+**Returns:** `boolean` — `true` if the bin existed
+
+### `bins.getRequests(binId)`
+
+List captured requests for a bin, newest first.
+
+**Returns:** `CapturedRequest[]`
+
+### `bins.getRequest(binId, reqId)`
+
+Look up a single captured request.
+
+**Returns:** `CapturedRequest | undefined`
+
+### `bins.clearRequests(binId)`
+
+Clear all captured requests in a bin (the bin itself is preserved).
+
+### `bins.recordRequest(binId, raw)`
+
+Manually record a captured request. Returns `undefined` if the bin does not exist or is expired. Normally invoked by the capture route, but available for programmatic use.
+
+**Returns:** `CapturedRequest | undefined`
+
+### `bins.start()` / `bins.stop()`
+
+Start or stop the periodic cleanup of expired bins. `MockHttp.start()` and `MockHttp.close()` call these automatically. The interval is `unref()`'d so it never keeps the Node process alive.
+
+### `bins.maxBodySize` / `bins.maxRequestsPerBin` / `bins.defaultTtlMs`
+
+Read-only getters for the currently-configured limits.
+
 ## Taps (Response Injection)
 
 Access the TapManager via `mockHttp.taps` to inject custom responses.

package/dist/index.d.mts

@@ -2,6 +2,147 @@ import { RateLimitPluginOptions } from "@fastify/rate-limit";
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Hookified, HookifiedOptions } from "hookified";
 
+//#region src/bin-store.d.ts
+/**
+ * A request captured by a bin, including method, headers, body and metadata.
+ */
+type CapturedRequest = {
+  /** Unique identifier for this captured request */id: string; /** Identifier of the bin that captured this request */
+  binId: string; /** HTTP method (GET, POST, etc.) */
+  method: string; /** Request URL path + query, relative to the bin (e.g. "/foo?x=1") */
+  url: string; /** Sub-path after the bin id ("/" if the request hit the bin root) */
+  path: string; /** Parsed query string parameters */
+  query: Record<string, string | string[]>; /** Request headers */
+  headers: Record<string, string | string[]>; /** Client IP address as reported by Fastify */
+  remoteAddress: string; /** Content-Type header value, if any */
+  contentType?: string; /** Original body length in bytes */
+  bodySize: number; /** Body payload as utf8 text, base64-encoded bytes, or null when empty */
+  body: string | null; /** Encoding used for the `body` field */
+  bodyEncoding: "utf8" | "base64" | "none"; /** True if the body was longer than the configured `maxBodySize` */
+  truncated: boolean; /** ISO timestamp of when the request was captured */
+  capturedAt: string;
+};
+/**
+ * Metadata for a bin (without its captured requests).
+ */
+type Bin = {
+  /** Unique short identifier for the bin */id: string; /** ISO timestamp of bin creation */
+  createdAt: string; /** ISO timestamp at which the bin expires */
+  expiresAt: string; /** Number of requests currently stored in the bin */
+  requestCount: number;
+};
+/**
+ * Storage backend for bins and their captured requests. The default
+ * implementation is in-memory; alternative backends (Redis, SQLite, etc.) can
+ * implement this interface without changes to the rest of the codebase.
+ */
+interface BinStore {
+  /** Create a new bin record. */
+  createBin(bin: Bin): void;
+  /** Look up a bin by id. */
+  getBin(id: string): Bin | undefined;
+  /** Return all bins. */
+  listBins(): Bin[];
+  /** Remove a bin and all its captured requests. Returns true if removed. */
+  deleteBin(id: string): boolean;
+  /**
+   * Append a captured request to a bin, dropping the oldest if the bin has
+   * already reached `max` requests (FIFO).
+   */
+  addRequest(binId: string, req: CapturedRequest, max: number): void;
+  /** List captured requests for a bin (newest first). */
+  getRequests(binId: string): CapturedRequest[];
+  /** Look up a single captured request by id. */
+  getRequest(binId: string, reqId: string): CapturedRequest | undefined;
+  /** Clear all captured requests in a bin (the bin itself is preserved). */
+  clearRequests(binId: string): void;
+  /**
+   * Remove bins whose `expiresAt` is in the past relative to `now`.
+   * Returns the ids of bins that were removed.
+   */
+  cleanupExpired(now: number): string[];
+}
+/**
+ * In-memory implementation of {@link BinStore} backed by two Maps. State is
+ * lost when the process exits.
+ */
+declare class InMemoryBinStore implements BinStore {
+  private readonly _bins;
+  private readonly _requests;
+  createBin(bin: Bin): void;
+  getBin(id: string): Bin | undefined;
+  listBins(): Bin[];
+  deleteBin(id: string): boolean;
+  addRequest(binId: string, req: CapturedRequest, max: number): void;
+  getRequests(binId: string): CapturedRequest[];
+  getRequest(binId: string, reqId: string): CapturedRequest | undefined;
+  clearRequests(binId: string): void;
+  cleanupExpired(now: number): string[];
+}
+//#endregion
+//#region src/bin-manager.d.ts
+/**
+ * Configuration options for {@link BinManager}.
+ */
+type BinManagerOptions = {
+  /** Storage backend. Defaults to a new {@link InMemoryBinStore}. */store?: BinStore; /** Bin lifetime in milliseconds. Defaults to 24 hours. */
+  defaultTtlMs?: number; /** Maximum number of requests retained per bin (FIFO). Defaults to 100. */
+  maxRequestsPerBin?: number; /** Maximum captured body size in bytes. Larger bodies are truncated. Defaults to 1 MiB. */
+  maxBodySize?: number; /** Length of generated bin and request ids. Defaults to 12. */
+  idLength?: number; /** Interval between cleanup sweeps in milliseconds. Defaults to 1 minute. */
+  cleanupIntervalMs?: number;
+};
+/**
+ * Manages request bins: ephemeral URL endpoints that capture incoming HTTP
+ * requests so they can be inspected later.
+ */
+declare class BinManager {
+  private readonly _store;
+  private readonly _defaultTtlMs;
+  private readonly _maxRequestsPerBin;
+  private readonly _maxBodySize;
+  private readonly _idLength;
+  private readonly _cleanupIntervalMs;
+  private _cleanupTimer;
+  constructor(options?: BinManagerOptions);
+  /** Underlying storage backend. */
+  get store(): BinStore;
+  /** Maximum captured body size in bytes. */
+  get maxBodySize(): number;
+  /** Maximum number of requests retained per bin. */
+  get maxRequestsPerBin(): number;
+  /** Default bin lifetime in milliseconds. */
+  get defaultTtlMs(): number;
+  /** Create a new bin with the configured TTL. */
+  createBin(): Bin;
+  /**
+   * Look up a bin by id. Returns `undefined` if the bin does not exist or
+   * has expired (in which case it is also lazily removed).
+   */
+  getBin(id: string): Bin | undefined;
+  /** List all non-expired bins. */
+  listBins(): Bin[];
+  /** Delete a bin. Returns true if the bin existed. */
+  deleteBin(id: string): boolean;
+  /**
+   * Record an incoming request against a bin. Returns the stored
+   * {@link CapturedRequest}, or `undefined` if the bin does not exist or is
+   * expired.
+   */
+  recordRequest(binId: string, raw: Omit<CapturedRequest, "id" | "binId" | "capturedAt">): CapturedRequest | undefined;
+  /** List captured requests for a bin (newest first). */
+  getRequests(binId: string): CapturedRequest[];
+  /** Look up a single captured request. */
+  getRequest(binId: string, reqId: string): CapturedRequest | undefined;
+  /** Clear all captured requests in a bin. */
+  clearRequests(binId: string): void;
+  /** Start the periodic cleanup of expired bins. */
+  start(): void;
+  /** Stop the periodic cleanup. Idempotent. */
+  stop(): void;
+  private generateId;
+}
+//#endregion
 //#region src/certificate.d.ts
 type CertificateOptions = {
   /**
@@ -191,6 +332,7 @@ type HttpBinOptions = {
   auth?: boolean;
   images?: boolean;
   dynamicData?: boolean;
+  bins?: boolean;
 };
 type HttpsOptions = {
   /**
@@ -282,6 +424,7 @@ declare class MockHttp extends Hookified {
   private _httpsCredentials;
   private _server;
   private _taps;
+  private _bins;
   constructor(options?: MockHttpOptions);
   /**
    * The port to listen on. If not provided, defaults to 3000 and detects the next available port if in use.
@@ -415,6 +558,14 @@ declare class MockHttp extends Hookified {
    * The TapManager instance for managing injection taps.
    */
   set taps(taps: TapManager);
+  /**
+   * The BinManager instance for managing request bins.
+   */
+  get bins(): BinManager;
+  /**
+   * The BinManager instance for managing request bins.
+   */
+  set bins(bins: BinManager);
   /**
    * Start the Fastify server. If the server is already running, it will be closed and restarted.
    */
@@ -484,6 +635,11 @@ declare class MockHttp extends Hookified {
    * @param fastifyInstance - the server instance to register the routes on.
    */
   registerDynamicDataRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the request bin routes (management at /bins and capture at /b/:id).
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerBinRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
   private resolveHttpsCredentials;
   private loadPemValue;
 }
@@ -491,4 +647,4 @@ declare class MockHttp extends Hookified {
 //#region src/index.d.ts
 declare const start: () => Promise<MockHttp>;
 //#endregion
-export { type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };
+export { type Bin, BinManager, type BinManagerOptions, type BinStore, type CapturedRequest, type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, InMemoryBinStore, type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };