@tabai/sdk 0.2.0

package/dist/server/adapters/express.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Express middleware over the post-paid plugin.
+ *
+ * Express is the one framework of the three that does not hand a middleware a
+ * response object to inspect. A handler writes into `res` and the bytes leave as
+ * they are written, so "meter after the handler produced its response" has to be
+ * arranged rather than expressed, and the two release orderings need genuinely
+ * different plumbing:
+ *
+ * **`before-metering` intercepts nothing.** The middleware registers a `finish`
+ * listener and calls `next()`. Express writes the response exactly as it would
+ * without this SDK installed, and the delivery is recorded once the bytes are
+ * gone. Nothing is buffered, nothing is delayed, and a streamed endpoint keeps
+ * streaming. A refusal cannot reach this request, because the response left
+ * before the charge was known.
+ *
+ * **`after-metering` holds the body, and only the body.** `res.write` and
+ * `res.end` are intercepted, the chunks are collected, and the moment the handler
+ * ends the response the delivery is recorded. Then either the collected bytes go
+ * out with their charge headers, or, on the one refusal an Agent must clear -
+ * the refusal goes out instead. The handler is never delayed: it writes, it ends,
+ * it returns. What waits is the flush, and it waits on one credit record, never on
+ * a payment.
+ *
+ * That interception is worth naming plainly: under `after-metering` this adapter
+ * buffers the response body in memory until the handler ends the response, so it
+ * is the wrong choice for a streamed or long-lived response. Use
+ * `before-metering` for those, and the bytes are never touched.
+ *
+ * ## No dependency on Express
+ *
+ * The three parameter types are structural and describe only the fields the
+ * middleware touches. Nothing here imports `express`, so a consumer on Hono
+ * installs nothing extra and there is no Express version to keep in step.
+ *
+ * Requirements: 23.3, 12.1
+ */
+import type { Logger } from "../../logger.js";
+import type { MeteredRequest, MeteringOutcome, PostPaidPlugin } from "../post-paid.js";
+/** The request fields the middleware reads. An Express `req` satisfies it. */
+export interface ExpressLikeRequest {
+    readonly method?: string | undefined;
+    readonly url?: string | undefined;
+    /** Express's pre-router URL. Preferred over `url`, which a router rewrites. */
+    readonly originalUrl?: string | undefined;
+    readonly headers?: Readonly<Record<string, string | string[] | undefined>> | undefined;
+}
+/** The response fields the middleware touches. An Express `res` satisfies it. */
+export interface ExpressLikeResponse {
+    statusCode: number;
+    readonly headersSent?: boolean;
+    setHeader(name: string, value: string): unknown;
+    removeHeader?(name: string): unknown;
+    write(...args: unknown[]): boolean;
+    end(...args: unknown[]): unknown;
+    on(event: string, listener: () => void): unknown;
+}
+/** Express's continuation. An argument means the handler chain failed. */
+export type ExpressLikeNext = (error?: unknown) => void;
+export type ExpressLikeMiddleware = (request: ExpressLikeRequest, response: ExpressLikeResponse, next: ExpressLikeNext) => void;
+export interface ExpressTabPostPaidOptions {
+    /**
+     * Receives the pending recording, so a host, or a test, can await it. Called
+     * with the same promise the plugin is working on, once per metered response.
+     */
+    readonly onMetering?: (metering: Promise<MeteringOutcome>) => void;
+    /** Base URL used to make a relative Express URL absolute. Defaults to `http://localhost`. */
+    readonly baseUrl?: string;
+    readonly logger?: Logger;
+}
+/**
+ * Builds the middleware. Install it before the handlers it should meter.
+ *
+ * ```ts
+ * app.use(expressTabPostPaid(tabPostPaid({ ... })));
+ * ```
+ */
+export declare function expressTabPostPaid(plugin: PostPaidPlugin, options?: ExpressTabPostPaidOptions): ExpressLikeMiddleware;
+/**
+ * Builds the framework-free request the plugin reads, without touching the body.
+ *
+ * The header lookup is `headerReaderOf` from the shared header contract, so the
+ * case-insensitive matching and the repeated-value handling are the same code the
+ * 402 client uses rather than a second copy of the same rules. Node lower-cases
+ * every incoming header name and the plugin asks in canonical casing, which is
+ * exactly the mismatch that reader exists to absorb.
+ */
+export declare function meteredRequestFrom(request: ExpressLikeRequest, baseUrl?: string): MeteredRequest;
+//# sourceMappingURL=express.d.ts.map

package/dist/server/adapters/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEvF,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;CACxF;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAChD,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACnC,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACjC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CAClD;AAED,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAExD,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,EAAE,eAAe,KAClB,IAAI,CAAC;AAEV,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,CAAC,KAAK,IAAI,CAAC;IACnE,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,yBAA8B,GACtC,qBAAqB,CAiDvB;AA0ED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,SAAqB,GAC3B,cAAc,CAOhB"}

package/dist/server/adapters/express.js

@@ -0,0 +1,215 @@
+/**
+ * Express middleware over the post-paid plugin.
+ *
+ * Express is the one framework of the three that does not hand a middleware a
+ * response object to inspect. A handler writes into `res` and the bytes leave as
+ * they are written, so "meter after the handler produced its response" has to be
+ * arranged rather than expressed, and the two release orderings need genuinely
+ * different plumbing:
+ *
+ * **`before-metering` intercepts nothing.** The middleware registers a `finish`
+ * listener and calls `next()`. Express writes the response exactly as it would
+ * without this SDK installed, and the delivery is recorded once the bytes are
+ * gone. Nothing is buffered, nothing is delayed, and a streamed endpoint keeps
+ * streaming. A refusal cannot reach this request, because the response left
+ * before the charge was known.
+ *
+ * **`after-metering` holds the body, and only the body.** `res.write` and
+ * `res.end` are intercepted, the chunks are collected, and the moment the handler
+ * ends the response the delivery is recorded. Then either the collected bytes go
+ * out with their charge headers, or, on the one refusal an Agent must clear -
+ * the refusal goes out instead. The handler is never delayed: it writes, it ends,
+ * it returns. What waits is the flush, and it waits on one credit record, never on
+ * a payment.
+ *
+ * That interception is worth naming plainly: under `after-metering` this adapter
+ * buffers the response body in memory until the handler ends the response, so it
+ * is the wrong choice for a streamed or long-lived response. Use
+ * `before-metering` for those, and the bytes are never touched.
+ *
+ * ## No dependency on Express
+ *
+ * The three parameter types are structural and describe only the fields the
+ * middleware touches. Nothing here imports `express`, so a consumer on Hono
+ * installs nothing extra and there is no Express version to keep in step.
+ *
+ * Requirements: 23.3, 12.1
+ */
+import { defaultLogger } from "../../logger.js";
+import { headerReaderOf } from "../../http/headers.js";
+/**
+ * Builds the middleware. Install it before the handlers it should meter.
+ *
+ * ```ts
+ * app.use(expressTabPostPaid(tabPostPaid({ ... })));
+ * ```
+ */
+export function expressTabPostPaid(plugin, options = {}) {
+    const logger = options.logger ?? defaultLogger;
+    const baseUrl = options.baseUrl ?? "http://localhost";
+    return (request, response, next) => {
+        const metered = meteredRequestFrom(request, baseUrl);
+        if (plugin.release === "before-metering") {
+            // Nothing is intercepted. The bytes leave, then the charge is recorded.
+            response.on("finish", () => {
+                const metering = plugin.meter(metered, { status: response.statusCode });
+                options.onMetering?.(metering);
+            });
+            next();
+            return;
+        }
+        const chunks = [];
+        const originalWrite = response.write.bind(response);
+        const originalEnd = response.end.bind(response);
+        let ended = false;
+        response.write = (...args) => {
+            const chunk = chunkOf(args, logger);
+            if (chunk !== undefined)
+                chunks.push(chunk);
+            callbackOf(args)?.();
+            return true;
+        };
+        response.end = (...args) => {
+            if (ended)
+                return response;
+            ended = true;
+            const chunk = chunkOf(args, logger);
+            if (chunk !== undefined)
+                chunks.push(chunk);
+            const done = callbackOf(args);
+            // Restore before anything asynchronous, so the flush below writes through
+            // the real methods and a second `end` from the framework is a no-op.
+            response.write = originalWrite;
+            response.end = originalEnd;
+            const metering = plugin.meter(metered, { status: response.statusCode });
+            options.onMetering?.(metering);
+            void flush({ plugin, response, chunks, metering, done, originalEnd, logger });
+            return response;
+        };
+        next();
+    };
+}
+/** Records the delivery, then sends either the handler's bytes or the refusal. */
+async function flush(input) {
+    const { plugin, response, chunks, originalEnd, logger } = input;
+    const body = concat(chunks);
+    let outcome;
+    try {
+        outcome = await input.metering;
+    }
+    catch (thrown) {
+        // The plugin does not reject. If it somehow did, the delivered response is
+        // still the delivered response.
+        logger.error("post-paid metering rejected, and the handler's response was sent unchanged", {
+            message: String(thrown),
+        });
+        send(response, originalEnd, body, input.done);
+        return;
+    }
+    if (response.headersSent === true) {
+        // The handler flushed its own headers, so neither a status nor a header can
+        // change now. The bytes go out as written and the charge is already recorded.
+        logger.warn("post-paid could not attach charge headers because the handler had already sent them");
+        send(response, originalEnd, body, input.done);
+        return;
+    }
+    if (outcome.kind === "refused") {
+        const refusal = plugin.refusalResponseFor(outcome);
+        let payload;
+        try {
+            payload = new Uint8Array(await refusal.arrayBuffer());
+        }
+        catch (thrown) {
+            logger.error("post-paid could not read the refusal body, so the delivered response was sent", {
+                message: String(thrown),
+            });
+            send(response, originalEnd, body, input.done);
+            return;
+        }
+        response.statusCode = refusal.status;
+        refusal.headers.forEach((value, name) => {
+            response.setHeader(name, value);
+        });
+        send(response, originalEnd, payload, input.done);
+        return;
+    }
+    for (const [name, value] of Object.entries(plugin.headersFor(outcome))) {
+        response.setHeader(name, value);
+    }
+    send(response, originalEnd, body, input.done);
+}
+/** Writes the payload, restating `Content-Length` because the body may have changed. */
+function send(response, originalEnd, body, done) {
+    response.setHeader("Content-Length", String(body.byteLength));
+    if (done === undefined)
+        originalEnd(body);
+    else
+        originalEnd(body, done);
+}
+/**
+ * Builds the framework-free request the plugin reads, without touching the body.
+ *
+ * The header lookup is `headerReaderOf` from the shared header contract, so the
+ * case-insensitive matching and the repeated-value handling are the same code the
+ * 402 client uses rather than a second copy of the same rules. Node lower-cases
+ * every incoming header name and the plugin asks in canonical casing, which is
+ * exactly the mismatch that reader exists to absorb.
+ */
+export function meteredRequestFrom(request, baseUrl = "http://localhost") {
+    const path = request.originalUrl ?? request.url ?? "/";
+    return {
+        method: request.method ?? "GET",
+        url: absolute(path, baseUrl),
+        headers: headerReaderOf(request.headers ?? {}),
+    };
+}
+/** Makes an Express path absolute, because a `MeteredRequest` carries a URL. */
+function absolute(path, baseUrl) {
+    if (/^https?:\/\//i.test(path))
+        return path;
+    try {
+        return new URL(path, baseUrl).toString();
+    }
+    catch {
+        return `${baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+    }
+}
+/** The chunk a `write` or `end` call carried, as bytes. */
+function chunkOf(args, logger) {
+    const chunk = args[0];
+    if (chunk === undefined || chunk === null || typeof chunk === "function")
+        return undefined;
+    if (chunk instanceof Uint8Array)
+        return chunk;
+    if (typeof chunk !== "string")
+        return undefined;
+    const declared = typeof args[1] === "string" ? args[1] : "utf8";
+    try {
+        return new Uint8Array(Buffer.from(chunk, declared));
+    }
+    catch {
+        logger.debug("post-paid read a response chunk as utf8 because its encoding was not recognised", {
+            declared,
+        });
+        return new Uint8Array(Buffer.from(chunk, "utf8"));
+    }
+}
+/** The completion callback a `write` or `end` call carried, if any. */
+function callbackOf(args) {
+    const last = args[args.length - 1];
+    return typeof last === "function" ? last : undefined;
+}
+/** Joins the collected chunks into one payload. */
+function concat(chunks) {
+    if (chunks.length === 1)
+        return chunks[0];
+    const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return joined;
+}
+//# sourceMappingURL=express.js.map

package/dist/server/adapters/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../../src/server/adapters/express.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Express middleware over the post-paid plugin.\n *\n * Express is the one framework of the three that does not hand a middleware a\n * response object to inspect. A handler writes into `res` and the bytes leave as\n * they are written, so \"meter after the handler produced its response\" has to be\n * arranged rather than expressed, and the two release orderings need genuinely\n * different plumbing:\n *\n * **`before-metering` intercepts nothing.** The middleware registers a `finish`\n * listener and calls `next()`. Express writes the response exactly as it would\n * without this SDK installed, and the delivery is recorded once the bytes are\n * gone. Nothing is buffered, nothing is delayed, and a streamed endpoint keeps\n * streaming. A refusal cannot reach this request, because the response left\n * before the charge was known.\n *\n * **`after-metering` holds the body, and only the body.** `res.write` and\n * `res.end` are intercepted, the chunks are collected, and the moment the handler\n * ends the response the delivery is recorded. Then either the collected bytes go\n * out with their charge headers, or, on the one refusal an Agent must clear -\n * the refusal goes out instead. The handler is never delayed: it writes, it ends,\n * it returns. What waits is the flush, and it waits on one credit record, never on\n * a payment.\n *\n * That interception is worth naming plainly: under `after-metering` this adapter\n * buffers the response body in memory until the handler ends the response, so it\n * is the wrong choice for a streamed or long-lived response. Use\n * `before-metering` for those, and the bytes are never touched.\n *\n * ## No dependency on Express\n *\n * The three parameter types are structural and describe only the fields the\n * middleware touches. Nothing here imports `express`, so a consumer on Hono\n * installs nothing extra and there is no Express version to keep in step.\n *\n * Requirements: 23.3, 12.1\n */\n\nimport type { Logger } from \"../../logger.js\";\nimport { defaultLogger } from \"../../logger.js\";\nimport { headerReaderOf } from \"../../http/headers.js\";\nimport type { MeteredRequest, MeteringOutcome, PostPaidPlugin } from \"../post-paid.js\";\n\n/** The request fields the middleware reads. An Express `req` satisfies it. */\nexport interface ExpressLikeRequest {\n  readonly method?: string | undefined;\n  readonly url?: string | undefined;\n  /** Express's pre-router URL. Preferred over `url`, which a router rewrites. */\n  readonly originalUrl?: string | undefined;\n  readonly headers?: Readonly<Record<string, string | string[] | undefined>> | undefined;\n}\n\n/** The response fields the middleware touches. An Express `res` satisfies it. */\nexport interface ExpressLikeResponse {\n  statusCode: number;\n  readonly headersSent?: boolean;\n  setHeader(name: string, value: string): unknown;\n  removeHeader?(name: string): unknown;\n  write(...args: unknown[]): boolean;\n  end(...args: unknown[]): unknown;\n  on(event: string, listener: () => void): unknown;\n}\n\n/** Express's continuation. An argument means the handler chain failed. */\nexport type ExpressLikeNext = (error?: unknown) => void;\n\nexport type ExpressLikeMiddleware = (\n  request: ExpressLikeRequest,\n  response: ExpressLikeResponse,\n  next: ExpressLikeNext,\n) => void;\n\nexport interface ExpressTabPostPaidOptions {\n  /**\n   * Receives the pending recording, so a host, or a test, can await it. Called\n   * with the same promise the plugin is working on, once per metered response.\n   */\n  readonly onMetering?: (metering: Promise<MeteringOutcome>) => void;\n  /** Base URL used to make a relative Express URL absolute. Defaults to `http://localhost`. */\n  readonly baseUrl?: string;\n  readonly logger?: Logger;\n}\n\n/**\n * Builds the middleware. Install it before the handlers it should meter.\n *\n * ```ts\n * app.use(expressTabPostPaid(tabPostPaid({ ... })));\n * ```\n */\nexport function expressTabPostPaid(\n  plugin: PostPaidPlugin,\n  options: ExpressTabPostPaidOptions = {},\n): ExpressLikeMiddleware {\n  const logger = options.logger ?? defaultLogger;\n  const baseUrl = options.baseUrl ?? \"http://localhost\";\n\n  return (request, response, next) => {\n    const metered = meteredRequestFrom(request, baseUrl);\n\n    if (plugin.release === \"before-metering\") {\n      // Nothing is intercepted. The bytes leave, then the charge is recorded.\n      response.on(\"finish\", () => {\n        const metering = plugin.meter(metered, { status: response.statusCode });\n        options.onMetering?.(metering);\n      });\n      next();\n      return;\n    }\n\n    const chunks: Uint8Array[] = [];\n    const originalWrite = response.write.bind(response);\n    const originalEnd = response.end.bind(response);\n    let ended = false;\n\n    response.write = (...args: unknown[]): boolean => {\n      const chunk = chunkOf(args, logger);\n      if (chunk !== undefined) chunks.push(chunk);\n      callbackOf(args)?.();\n      return true;\n    };\n\n    response.end = (...args: unknown[]): unknown => {\n      if (ended) return response;\n      ended = true;\n      const chunk = chunkOf(args, logger);\n      if (chunk !== undefined) chunks.push(chunk);\n      const done = callbackOf(args);\n\n      // Restore before anything asynchronous, so the flush below writes through\n      // the real methods and a second `end` from the framework is a no-op.\n      response.write = originalWrite;\n      response.end = originalEnd;\n\n      const metering = plugin.meter(metered, { status: response.statusCode });\n      options.onMetering?.(metering);\n      void flush({ plugin, response, chunks, metering, done, originalEnd, logger });\n      return response;\n    };\n\n    next();\n  };\n}\n\n/** Records the delivery, then sends either the handler's bytes or the refusal. */\nasync function flush(input: {\n  readonly plugin: PostPaidPlugin;\n  readonly response: ExpressLikeResponse;\n  readonly chunks: readonly Uint8Array[];\n  readonly metering: Promise<MeteringOutcome>;\n  readonly done: (() => void) | undefined;\n  readonly originalEnd: (...args: unknown[]) => unknown;\n  readonly logger: Logger;\n}): Promise<void> {\n  const { plugin, response, chunks, originalEnd, logger } = input;\n  const body = concat(chunks);\n\n  let outcome: MeteringOutcome;\n  try {\n    outcome = await input.metering;\n  } catch (thrown) {\n    // The plugin does not reject. If it somehow did, the delivered response is\n    // still the delivered response.\n    logger.error(\"post-paid metering rejected, and the handler's response was sent unchanged\", {\n      message: String(thrown),\n    });\n    send(response, originalEnd, body, input.done);\n    return;\n  }\n\n  if (response.headersSent === true) {\n    // The handler flushed its own headers, so neither a status nor a header can\n    // change now. The bytes go out as written and the charge is already recorded.\n    logger.warn(\"post-paid could not attach charge headers because the handler had already sent them\");\n    send(response, originalEnd, body, input.done);\n    return;\n  }\n\n  if (outcome.kind === \"refused\") {\n    const refusal = plugin.refusalResponseFor(outcome);\n    let payload: Uint8Array;\n    try {\n      payload = new Uint8Array(await refusal.arrayBuffer());\n    } catch (thrown) {\n      logger.error(\"post-paid could not read the refusal body, so the delivered response was sent\", {\n        message: String(thrown),\n      });\n      send(response, originalEnd, body, input.done);\n      return;\n    }\n    response.statusCode = refusal.status;\n    refusal.headers.forEach((value, name) => {\n      response.setHeader(name, value);\n    });\n    send(response, originalEnd, payload, input.done);\n    return;\n  }\n\n  for (const [name, value] of Object.entries(plugin.headersFor(outcome))) {\n    response.setHeader(name, value);\n  }\n  send(response, originalEnd, body, input.done);\n}\n\n/** Writes the payload, restating `Content-Length` because the body may have changed. */\nfunction send(\n  response: ExpressLikeResponse,\n  originalEnd: (...args: unknown[]) => unknown,\n  body: Uint8Array,\n  done: (() => void) | undefined,\n): void {\n  response.setHeader(\"Content-Length\", String(body.byteLength));\n  if (done === undefined) originalEnd(body);\n  else originalEnd(body, done);\n}\n\n/**\n * Builds the framework-free request the plugin reads, without touching the body.\n *\n * The header lookup is `headerReaderOf` from the shared header contract, so the\n * case-insensitive matching and the repeated-value handling are the same code the\n * 402 client uses rather than a second copy of the same rules. Node lower-cases\n * every incoming header name and the plugin asks in canonical casing, which is\n * exactly the mismatch that reader exists to absorb.\n */\nexport function meteredRequestFrom(\n  request: ExpressLikeRequest,\n  baseUrl = \"http://localhost\",\n): MeteredRequest {\n  const path = request.originalUrl ?? request.url ?? \"/\";\n  return {\n    method: request.method ?? \"GET\",\n    url: absolute(path, baseUrl),\n    headers: headerReaderOf(request.headers ?? {}),\n  };\n}\n\n/** Makes an Express path absolute, because a `MeteredRequest` carries a URL. */\nfunction absolute(path: string, baseUrl: string): string {\n  if (/^https?:\\/\\//i.test(path)) return path;\n  try {\n    return new URL(path, baseUrl).toString();\n  } catch {\n    return `${baseUrl}${path.startsWith(\"/\") ? \"\" : \"/\"}${path}`;\n  }\n}\n\n/** The chunk a `write` or `end` call carried, as bytes. */\nfunction chunkOf(args: readonly unknown[], logger: Logger): Uint8Array | undefined {\n  const chunk = args[0];\n  if (chunk === undefined || chunk === null || typeof chunk === \"function\") return undefined;\n  if (chunk instanceof Uint8Array) return chunk;\n  if (typeof chunk !== \"string\") return undefined;\n\n  const declared = typeof args[1] === \"string\" ? args[1] : \"utf8\";\n  try {\n    return new Uint8Array(Buffer.from(chunk, declared as BufferEncoding));\n  } catch {\n    logger.debug(\"post-paid read a response chunk as utf8 because its encoding was not recognised\", {\n      declared,\n    });\n    return new Uint8Array(Buffer.from(chunk, \"utf8\"));\n  }\n}\n\n/** The completion callback a `write` or `end` call carried, if any. */\nfunction callbackOf(args: readonly unknown[]): (() => void) | undefined {\n  const last = args[args.length - 1];\n  return typeof last === \"function\" ? (last as () => void) : undefined;\n}\n\n/** Joins the collected chunks into one payload. */\nfunction concat(chunks: readonly Uint8Array[]): Uint8Array {\n  if (chunks.length === 1) return chunks[0] as Uint8Array;\n  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);\n  const joined = new Uint8Array(total);\n  let offset = 0;\n  for (const chunk of chunks) {\n    joined.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  return joined;\n}\n"]}

package/dist/server/adapters/hono.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Hono middleware over the post-paid plugin.
+ *
+ * Hono already speaks the web standard, so this adapter is almost nothing: it
+ * awaits `next()`, hands `c.res` to the plugin, and puts back whatever the plugin
+ * says goes out. The whole of the ordering guarantee is the `await next()` on the
+ * first line of the handler closure, the handler chain runs to completion, and
+ * only the response it produced is metered.
+ *
+ * ## No dependency on Hono
+ *
+ * The context and next types below are structural, so this file compiles with no
+ * `hono` import, no `hono` dependency, and no `hono` version to keep in step. A
+ * consumer using Express should not be made to install Hono to use this SDK, and
+ * the two fields the middleware touches, `c.req.raw` and `c.res`, are stable
+ * across Hono 3 and 4.
+ *
+ * `c.executionCtx` is read through a `try`, because on a Hono context with no
+ * execution context the getter throws rather than returning undefined. Where it
+ * exists, a Worker, a runtime with a request lifetime, a `before-metering`
+ * recording is handed to `waitUntil` so the runtime does not tear down while the
+ * charge is still in flight.
+ *
+ * Requirements: 23.3, 12.1
+ */
+import type { PostPaidPlugin } from "../post-paid.js";
+/** The two fields of a Hono context this middleware touches, and nothing else. */
+export interface HonoLikeContext {
+    readonly req: {
+        readonly raw: Request;
+    };
+    res: Response;
+    /** Present on a runtime with a request lifetime. Reading it may throw. */
+    readonly executionCtx?: {
+        waitUntil(promise: Promise<unknown>): void;
+    };
+}
+/** Hono's downstream continuation. */
+export type HonoLikeNext = () => Promise<void>;
+/** What Hono expects a middleware to be. */
+export type HonoLikeMiddleware = (context: HonoLikeContext, next: HonoLikeNext) => Promise<void>;
+/**
+ * Builds the middleware.
+ *
+ * On `handler-failed` the thrown value is re-raised unchanged so Hono's own
+ * `onError` sees exactly what the handler threw. That re-raise is the one place
+ * this file throws, and it is the adapter boundary the zero-throw rule names: the
+ * plugin returned a value, and the framework's contract for a failed handler is
+ * an exception.
+ */
+export declare function honoTabPostPaid(plugin: PostPaidPlugin): HonoLikeMiddleware;
+//# sourceMappingURL=hono.d.ts.map

package/dist/server/adapters/hono.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/hono.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtE,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;IACxC,GAAG,EAAE,QAAQ,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;CACxE;AAED,sCAAsC;AACtC,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/C,4CAA4C;AAC5C,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjG;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,kBAAkB,CAmB1E"}

package/dist/server/adapters/hono.js

@@ -0,0 +1,61 @@
+/**
+ * Hono middleware over the post-paid plugin.
+ *
+ * Hono already speaks the web standard, so this adapter is almost nothing: it
+ * awaits `next()`, hands `c.res` to the plugin, and puts back whatever the plugin
+ * says goes out. The whole of the ordering guarantee is the `await next()` on the
+ * first line of the handler closure, the handler chain runs to completion, and
+ * only the response it produced is metered.
+ *
+ * ## No dependency on Hono
+ *
+ * The context and next types below are structural, so this file compiles with no
+ * `hono` import, no `hono` dependency, and no `hono` version to keep in step. A
+ * consumer using Express should not be made to install Hono to use this SDK, and
+ * the two fields the middleware touches, `c.req.raw` and `c.res`, are stable
+ * across Hono 3 and 4.
+ *
+ * `c.executionCtx` is read through a `try`, because on a Hono context with no
+ * execution context the getter throws rather than returning undefined. Where it
+ * exists, a Worker, a runtime with a request lifetime, a `before-metering`
+ * recording is handed to `waitUntil` so the runtime does not tear down while the
+ * charge is still in flight.
+ *
+ * Requirements: 23.3, 12.1
+ */
+/**
+ * Builds the middleware.
+ *
+ * On `handler-failed` the thrown value is re-raised unchanged so Hono's own
+ * `onError` sees exactly what the handler threw. That re-raise is the one place
+ * this file throws, and it is the adapter boundary the zero-throw rule names: the
+ * plugin returned a value, and the framework's contract for a failed handler is
+ * an exception.
+ */
+export function honoTabPostPaid(plugin) {
+    return async (context, next) => {
+        // A web-standard `Request` already satisfies `MeteredRequest`, so nothing is
+        // rebuilt and no header is copied.
+        const request = context.req.raw;
+        const execution = await plugin.execute(request, async () => {
+            await next();
+            return context.res;
+        });
+        if (execution.kind === "handler-failed")
+            throw execution.thrown;
+        context.res = execution.response;
+        if (execution.kind === "delivered" && plugin.release === "before-metering") {
+            waitUntil(context, execution.metering);
+        }
+    };
+}
+/** Hands the pending recording to the runtime's request lifetime, where there is one. */
+function waitUntil(context, metering) {
+    try {
+        context.executionCtx?.waitUntil(metering);
+    }
+    catch {
+        // No execution context. The recording still runs; nothing is waiting on it.
+    }
+}
+//# sourceMappingURL=hono.js.map

package/dist/server/adapters/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.js","sourceRoot":"","sources":["../../../src/server/adapters/hono.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAkBH;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,MAAsB;IACpD,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,6EAA6E;QAC7E,mCAAmC;QACnC,MAAM,OAAO,GAAmB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QAEhD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YACzD,MAAM,IAAI,EAAE,CAAC;YACb,OAAO,OAAO,CAAC,GAAG,CAAC;QACrB,CAAC,CAAC,CAAC;QAEH,IAAI,SAAS,CAAC,IAAI,KAAK,gBAAgB;YAAE,MAAM,SAAS,CAAC,MAAM,CAAC;QAEhE,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC;QAEjC,IAAI,SAAS,CAAC,IAAI,KAAK,WAAW,IAAI,MAAM,CAAC,OAAO,KAAK,iBAAiB,EAAE,CAAC;YAC3E,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,SAAS,SAAS,CAAC,OAAwB,EAAE,QAA0B;IACrE,IAAI,CAAC;QACH,OAAO,CAAC,YAAY,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;IAC9E,CAAC;AACH,CAAC","sourcesContent":["/**\n * Hono middleware over the post-paid plugin.\n *\n * Hono already speaks the web standard, so this adapter is almost nothing: it\n * awaits `next()`, hands `c.res` to the plugin, and puts back whatever the plugin\n * says goes out. The whole of the ordering guarantee is the `await next()` on the\n * first line of the handler closure, the handler chain runs to completion, and\n * only the response it produced is metered.\n *\n * ## No dependency on Hono\n *\n * The context and next types below are structural, so this file compiles with no\n * `hono` import, no `hono` dependency, and no `hono` version to keep in step. A\n * consumer using Express should not be made to install Hono to use this SDK, and\n * the two fields the middleware touches, `c.req.raw` and `c.res`, are stable\n * across Hono 3 and 4.\n *\n * `c.executionCtx` is read through a `try`, because on a Hono context with no\n * execution context the getter throws rather than returning undefined. Where it\n * exists, a Worker, a runtime with a request lifetime, a `before-metering`\n * recording is handed to `waitUntil` so the runtime does not tear down while the\n * charge is still in flight.\n *\n * Requirements: 23.3, 12.1\n */\n\nimport type { MeteredRequest, PostPaidPlugin } from \"../post-paid.js\";\n\n/** The two fields of a Hono context this middleware touches, and nothing else. */\nexport interface HonoLikeContext {\n  readonly req: { readonly raw: Request };\n  res: Response;\n  /** Present on a runtime with a request lifetime. Reading it may throw. */\n  readonly executionCtx?: { waitUntil(promise: Promise<unknown>): void };\n}\n\n/** Hono's downstream continuation. */\nexport type HonoLikeNext = () => Promise<void>;\n\n/** What Hono expects a middleware to be. */\nexport type HonoLikeMiddleware = (context: HonoLikeContext, next: HonoLikeNext) => Promise<void>;\n\n/**\n * Builds the middleware.\n *\n * On `handler-failed` the thrown value is re-raised unchanged so Hono's own\n * `onError` sees exactly what the handler threw. That re-raise is the one place\n * this file throws, and it is the adapter boundary the zero-throw rule names: the\n * plugin returned a value, and the framework's contract for a failed handler is\n * an exception.\n */\nexport function honoTabPostPaid(plugin: PostPaidPlugin): HonoLikeMiddleware {\n  return async (context, next) => {\n    // A web-standard `Request` already satisfies `MeteredRequest`, so nothing is\n    // rebuilt and no header is copied.\n    const request: MeteredRequest = context.req.raw;\n\n    const execution = await plugin.execute(request, async () => {\n      await next();\n      return context.res;\n    });\n\n    if (execution.kind === \"handler-failed\") throw execution.thrown;\n\n    context.res = execution.response;\n\n    if (execution.kind === \"delivered\" && plugin.release === \"before-metering\") {\n      waitUntil(context, execution.metering);\n    }\n  };\n}\n\n/** Hands the pending recording to the runtime's request lifetime, where there is one. */\nfunction waitUntil(context: HonoLikeContext, metering: Promise<unknown>): void {\n  try {\n    context.executionCtx?.waitUntil(metering);\n  } catch {\n    // No execution context. The recording still runs; nothing is waiting on it.\n  }\n}\n"]}

package/dist/server/adapters/next.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Next.js route-handler wrapper over the post-paid plugin.
+ *
+ * A Next.js route handler is `(request: Request, context) => Response`, which is
+ * the web standard with a second argument for the matched route parameters. So
+ * this adapter is a function that returns a function: the handler is called with
+ * both arguments untouched, its response is metered, and the response the plugin
+ * says goes out is returned.
+ *
+ * ## No dependency on Next.js
+ *
+ * Nothing here imports `next`. The handler shape is standard, and the one
+ * Next-specific facility the adapter can use, a hook that keeps work alive after
+ * the response has been sent, is taken as an argument rather than imported, so
+ * this file has no framework version to track and a consumer on another framework
+ * installs nothing.
+ *
+ * Under `release: "before-metering"` the recording is still in flight when the
+ * response is returned. On a serverless runtime that is a real hazard: the
+ * invocation can be frozen the moment the response is written. Pass `after` from
+ * `next/server` where the Next version has it, and the recording is kept alive:
+ *
+ * ```ts
+ * import { after } from "next/server";
+ * export const GET = withTabPostPaid(plugin, handler, { after });
+ * ```
+ *
+ * With no `after` and `before-metering`, the recording is best-effort, which is
+ * why `after-metering` is the default the plugin ships with.
+ *
+ * Requirements: 23.3, 12.1
+ */
+import type { PostPaidPlugin } from "../post-paid.js";
+/** A Next.js App Router route handler. `Ctx` carries the matched route parameters. */
+export type NextRouteHandler<Ctx> = (request: Request, context: Ctx) => Response | Promise<Response>;
+export interface NextTabPostPaidOptions {
+    /**
+     * A hook that keeps work alive past the response, such as `after` from
+     * `next/server`. Used under `release: "before-metering"` and ignored otherwise.
+     */
+    readonly after?: (task: () => Promise<unknown>) => void;
+}
+/**
+ * Wraps one route handler.
+ *
+ * A handler that throws is re-raised unchanged, so Next's own error handling sees
+ * what the handler threw and nothing is metered for a delivery that did not
+ * happen. That re-raise is the adapter boundary where a returned value becomes the
+ * exception the framework's contract expects.
+ */
+export declare function withTabPostPaid<Ctx>(plugin: PostPaidPlugin, handler: NextRouteHandler<Ctx>, options?: NextTabPostPaidOptions): NextRouteHandler<Ctx>;
+//# sourceMappingURL=next.d.ts.map

package/dist/server/adapters/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtE,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAErG,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EACjC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAC9B,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,CAAC,GAAG,CAAC,CAgBvB"}

package/dist/server/adapters/next.js

@@ -0,0 +1,56 @@
+/**
+ * Next.js route-handler wrapper over the post-paid plugin.
+ *
+ * A Next.js route handler is `(request: Request, context) => Response`, which is
+ * the web standard with a second argument for the matched route parameters. So
+ * this adapter is a function that returns a function: the handler is called with
+ * both arguments untouched, its response is metered, and the response the plugin
+ * says goes out is returned.
+ *
+ * ## No dependency on Next.js
+ *
+ * Nothing here imports `next`. The handler shape is standard, and the one
+ * Next-specific facility the adapter can use, a hook that keeps work alive after
+ * the response has been sent, is taken as an argument rather than imported, so
+ * this file has no framework version to track and a consumer on another framework
+ * installs nothing.
+ *
+ * Under `release: "before-metering"` the recording is still in flight when the
+ * response is returned. On a serverless runtime that is a real hazard: the
+ * invocation can be frozen the moment the response is written. Pass `after` from
+ * `next/server` where the Next version has it, and the recording is kept alive:
+ *
+ * ```ts
+ * import { after } from "next/server";
+ * export const GET = withTabPostPaid(plugin, handler, { after });
+ * ```
+ *
+ * With no `after` and `before-metering`, the recording is best-effort, which is
+ * why `after-metering` is the default the plugin ships with.
+ *
+ * Requirements: 23.3, 12.1
+ */
+/**
+ * Wraps one route handler.
+ *
+ * A handler that throws is re-raised unchanged, so Next's own error handling sees
+ * what the handler threw and nothing is metered for a delivery that did not
+ * happen. That re-raise is the adapter boundary where a returned value becomes the
+ * exception the framework's contract expects.
+ */
+export function withTabPostPaid(plugin, handler, options = {}) {
+    return async (request, context) => {
+        // A web-standard `Request` already satisfies `MeteredRequest`.
+        const metered = request;
+        const execution = await plugin.execute(metered, () => handler(request, context));
+        if (execution.kind === "handler-failed")
+            throw execution.thrown;
+        if (execution.kind === "delivered" && plugin.release === "before-metering") {
+            const keepAlive = options.after;
+            if (keepAlive !== undefined)
+                keepAlive(() => execution.metering);
+        }
+        return execution.response;
+    };
+}
+//# sourceMappingURL=next.js.map

package/dist/server/adapters/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../../../src/server/adapters/next.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAeH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAsB,EACtB,OAA8B,EAC9B,UAAkC,EAAE;IAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;QAChC,+DAA+D;QAC/D,MAAM,OAAO,GAAmB,OAAO,CAAC;QAExC,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAEjF,IAAI,SAAS,CAAC,IAAI,KAAK,gBAAgB;YAAE,MAAM,SAAS,CAAC,MAAM,CAAC;QAEhE,IAAI,SAAS,CAAC,IAAI,KAAK,WAAW,IAAI,MAAM,CAAC,OAAO,KAAK,iBAAiB,EAAE,CAAC;YAC3E,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;YAChC,IAAI,SAAS,KAAK,SAAS;gBAAE,SAAS,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,SAAS,CAAC,QAAQ,CAAC;IAC5B,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Next.js route-handler wrapper over the post-paid plugin.\n *\n * A Next.js route handler is `(request: Request, context) => Response`, which is\n * the web standard with a second argument for the matched route parameters. So\n * this adapter is a function that returns a function: the handler is called with\n * both arguments untouched, its response is metered, and the response the plugin\n * says goes out is returned.\n *\n * ## No dependency on Next.js\n *\n * Nothing here imports `next`. The handler shape is standard, and the one\n * Next-specific facility the adapter can use, a hook that keeps work alive after\n * the response has been sent, is taken as an argument rather than imported, so\n * this file has no framework version to track and a consumer on another framework\n * installs nothing.\n *\n * Under `release: \"before-metering\"` the recording is still in flight when the\n * response is returned. On a serverless runtime that is a real hazard: the\n * invocation can be frozen the moment the response is written. Pass `after` from\n * `next/server` where the Next version has it, and the recording is kept alive:\n *\n * ```ts\n * import { after } from \"next/server\";\n * export const GET = withTabPostPaid(plugin, handler, { after });\n * ```\n *\n * With no `after` and `before-metering`, the recording is best-effort, which is\n * why `after-metering` is the default the plugin ships with.\n *\n * Requirements: 23.3, 12.1\n */\n\nimport type { MeteredRequest, PostPaidPlugin } from \"../post-paid.js\";\n\n/** A Next.js App Router route handler. `Ctx` carries the matched route parameters. */\nexport type NextRouteHandler<Ctx> = (request: Request, context: Ctx) => Response | Promise<Response>;\n\nexport interface NextTabPostPaidOptions {\n  /**\n   * A hook that keeps work alive past the response, such as `after` from\n   * `next/server`. Used under `release: \"before-metering\"` and ignored otherwise.\n   */\n  readonly after?: (task: () => Promise<unknown>) => void;\n}\n\n/**\n * Wraps one route handler.\n *\n * A handler that throws is re-raised unchanged, so Next's own error handling sees\n * what the handler threw and nothing is metered for a delivery that did not\n * happen. That re-raise is the adapter boundary where a returned value becomes the\n * exception the framework's contract expects.\n */\nexport function withTabPostPaid<Ctx>(\n  plugin: PostPaidPlugin,\n  handler: NextRouteHandler<Ctx>,\n  options: NextTabPostPaidOptions = {},\n): NextRouteHandler<Ctx> {\n  return async (request, context) => {\n    // A web-standard `Request` already satisfies `MeteredRequest`.\n    const metered: MeteredRequest = request;\n\n    const execution = await plugin.execute(metered, () => handler(request, context));\n\n    if (execution.kind === \"handler-failed\") throw execution.thrown;\n\n    if (execution.kind === \"delivered\" && plugin.release === \"before-metering\") {\n      const keepAlive = options.after;\n      if (keepAlive !== undefined) keepAlive(() => execution.metering);\n    }\n\n    return execution.response;\n  };\n}\n"]}

package/dist/server/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The server-side surface: the post-paid plugin, the metering seam, and the three
+ * framework adapters.
+ *
+ * `tabPostPaid` is the whole product claim in one function. A Service installs it,
+ * keeps writing handlers the way it already does, and its Open Tab accrues behind
+ * each delivered response. No caller prepays, no response waits on a payment, and
+ * the one status this surface adds is a `402` on `LimitExceeded`, a credit
+ * decision, not a prepayment demand (R23.3, R12.1).
+ *
+ * The adapters are thin by design and carry no dependency on the framework they
+ * adapt: every framework type in here is structural, so a Service on Hono installs
+ * nothing for Express and nothing for Next.js.
+ *
+ * The wire format is not defined here. `src/http/headers.ts` owns it, this surface
+ * is its emitting half, and the 402 client of R23.2 is its reading half, so a
+ * disagreement about a header is a test failure in one file rather than a silent
+ * mis-parse between two.
+ *
+ * Nothing exported here throws, with one named exception: the Hono and Next.js
+ * adapters re-raise a handler's own thrown value, because a framework's contract
+ * for a failed handler is an exception and the adapter is the boundary where a
+ * `Result` becomes whatever the host expects.
+ */
+export * from "./metering.js";
+export * from "./post-paid.js";
+export * from "./adapters/hono.js";
+export * from "./adapters/express.js";
+export * from "./adapters/next.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC"}