@farthershore/backend 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,8 @@
 # @farthershore/backend
 
-The secure BYO-backend runtime SDK. Install one package, set one token
-(`FS_RUNTIME_TOKEN`), and Farther Shore protects (signs every gateway→backend
-request; the SDK verifies and rejects anything not from Farther Shore) and meters
-your backend.
+Runtime metering and gateway-verification SDK for builder upstreams. Install one
+package, set one token (`FS_RUNTIME_TOKEN`), and Farther Shore handles signed
+gateway-to-upstream request verification plus response-bound usage reporting.
 
 ## Install
 
@@ -11,20 +10,43 @@ your backend.
 npm install @farthershore/backend
 ```
 
-## Quick start (Express)
+## Quick start (Fetch-compatible handlers)
 
 ```ts
-import { fartherShore } from "@farthershore/backend";
+import { fartherShore, withUsage } from "@farthershore/backend";
 
 const fs = fartherShore.initFromEnv(); // derives everything from FS_RUNTIME_TOKEN
 
-app.use(fs.middleware()); // fail-closed verify → req.fartherShore
+export async function POST(request: Request) {
+  const url = new URL(request.url);
+  const body = new Uint8Array(await request.clone().arrayBuffer());
+
+  await fs.verifyRequest({
+    method: request.method,
+    path: url.pathname,
+    query: url.search,
+    headers: request.headers,
+    body,
+  });
+
+  const result = await runWorkflow(await request.json());
+  return withUsage(request, Response.json(result), {
+    tokens_used: result.tokensUsed,
+  });
+}
+```
+
+## Express verification
+
+```ts
+import { fartherShore } from "@farthershore/backend";
+
+const fs = fartherShore.initFromEnv();
+
+app.use(fs.middleware()); // fail-closed verify -> req.fartherShore
 
 app.post("/v1/runs", async (req, res) => {
   const result = await runWorkflow(req.body);
-  await fs.meter("tokens", result.tokensUsed, {
-    requestId: req.fartherShore.requestId,
-  });
   res.json(result);
 });
 
@@ -35,7 +57,7 @@ process.on("SIGTERM", () => void fs.shutdown());
 ## What `initFromEnv()` derives
 
 The builder configures exactly one thing: `FS_RUNTIME_TOKEN`. Everything else —
-product/backend/environment ids, the JWKS url, the metering endpoint and
+product/upstream/environment ids, the JWKS url, the metering endpoint and
 credential, verification config, transport — is fetched from
 `POST /v1/runtime/bootstrap` and cached in memory (refreshed lazily).
 
@@ -43,7 +65,7 @@ credential, verification config, transport — is fetched from
 
 `fs.middleware()` (Express) and the framework-neutral
 `fs.verifyRequest({ method, path, query, headers, body })` recompute the
-[canonical signing string](../../docs/superpowers/specs/backend-runtime-spec.md)
+[canonical signing string](../../docs/superpowers/specs/metering-runtime-spec.md)
 from the actual request and verify the gateway's Ed25519 signature against a
 JWKS-resolved public key. The plaintext `X-FS-*` headers are **untrusted** —
 identity comes only from a signature whose claims match the real request.
@@ -53,18 +75,50 @@ wrong-route / body-hash-mismatch / replayed-nonce / unknown-kid /
 jwks-unavailable) returns a typed `FartherShoreError` → **HTTP 401** (413 for
 oversized bodies). There is no fail-open branch.
 
-## Metering (billing-only)
+## Response-bound metering
+
+Use `withUsage()` or `createUsage()` when usage is known while returning a
+gateway-handled response. These helpers make no network call. They sign dynamic
+usage into internal response headers, and the gateway verifies, settles, and
+strips those headers before the subscriber receives the response.
+
+```ts
+import { withUsage } from "@farthershore/backend";
+
+export async function POST(request: Request) {
+  const result = await runWorkflow(await request.json());
+  return withUsage(
+    request,
+    Response.json(result),
+    { tokens_used: result.tokensUsed },
+    {
+      measureContext: { model: result.model },
+      creditUnitsConsumed: { credits: result.creditsUsed },
+    },
+  );
+}
+```
+
+`measureContext` is free-form pricing/analytics context persisted with the usage
+event. `creditUnitsConsumed` is a numeric map for credit-wallet style products;
+keys and values are validated locally before signing. The gateway accepts actual
+request-bound usage only from the `x-fs-metering` response-header contract signed
+with `FS_RUNTIME_TOKEN`; retired `x-fs-usage` actual-report headers are stripped
+and ignored.
+
+## Async/background metering
 
-`fs.meter(meter, qty, { requestId, routeId })` enqueues an idempotent event and
+Use `fs.meter(meter, qty, { requestId, routeId })` only for async/background
+usage that is not tied to a gateway response. It enqueues an idempotent event and
 POSTs it to `/v1/metering/events` with a reusable bearer credential. Delivery is
 at-least-once; the `event_id` idempotency key keeps core's ingest safe. Values
 are tallied/billed post-cycle, not real-time enforced.
 
-## Migrating from `@farthershore/metering`
+The meter key is not hardcoded by the SDK. It must match a dynamic meter declared
+in the product contract, such as `tokens_used` in the Product SDK examples.
 
-`@farthershore/metering` is now a deprecated re-export shim of this package and
-will be removed after the metering cutover. Replace the import; for new code,
-prefer `fs.meter("tokens", n)` over the response-header signer.
+Product route defaults such as request counts remain platform-managed and
+require no upstream code.
 
 The signing primitives and contract constants are re-exported from
 `@farthershore/contracts/runtime`, the language-neutral source of truth every

package/dist/generated/runtime-contract.js

@@ -180,7 +180,44 @@ var RUNTIME_METERING_CONTRACT = {
   delivery: "at-least-once",
   billingOnly: true,
   realtimeEnforced: false,
-  trustModel: "backend-reported values are NOT cryptographically attested; a buggy or compromised backend can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert."
+  trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert."
+};
+var RUNTIME_RESPONSE_METERING_CONTRACT = {
+  headers: {
+    payload: "x-fs-metering",
+    signature: "x-fs-metering-sig",
+    token: "x-fs-metering-token"
+  },
+  token: {
+    environmentVariable: "FS_RUNTIME_TOKEN",
+    presentation: "x-fs-metering-token",
+    storage: "sha256-hash-only"
+  },
+  signature: {
+    algorithm: "HMAC-SHA256",
+    encoding: "base64url",
+    input: "payload-json",
+    secret: "presented-runtime-token"
+  },
+  payload: {
+    method: "string",
+    path: "string",
+    rawDimsUnits: "Record<string, number>",
+    measureContext: "Record<string, unknown>?",
+    creditUnitsConsumed: "Record<string, number>?"
+  },
+  errors: {
+    missingToken: "missing_token",
+    invalidMeterKey: "invalid_meter_key",
+    invalidMeterValue: "invalid_meter_value"
+  },
+  httpAdapter: {
+    input: "Request",
+    output: "Response",
+    networkCalls: false,
+    preserves: ["body", "headers", "status", "statusText"],
+    gatewayStripsInternalHeaders: true
+  }
 };
 var RUNTIME_HEALTH_CONTRACT = {
   endpoint: "/v1/runtime/health",
@@ -232,6 +269,7 @@ export {
   RUNTIME_HEALTH_CONTRACT,
   RUNTIME_METERING_CONTRACT,
   RUNTIME_REPLAY_CONTRACT,
+  RUNTIME_RESPONSE_METERING_CONTRACT,
   RUNTIME_SIGNING_CONTRACT,
   RUNTIME_TOKEN_CONTRACT,
   RUNTIME_TOKEN_ENV,

package/dist/index.js

@@ -30,6 +30,7 @@ var STREAMING_EXEMPT_BODY_HASH = "STREAM";
 var MAX_BODY_BYTES = 10 * 1024 * 1024;
 
 // ../contracts/dist/runtime.js
+var FS_RUNTIME_TOKEN_ENV2 = "FS_RUNTIME_TOKEN";
 var RUNTIME_TOKEN_PREFIXES2 = {
   live: "fsrt_live_",
   test: "fsrt_test_"
@@ -41,6 +42,16 @@ function runtimeTokenKind(token) {
     return "test";
   return null;
 }
+var RESPONSE_METERING_HEADER_NAMES = {
+  payload: "x-fs-metering",
+  signature: "x-fs-metering-sig",
+  token: "x-fs-metering-token"
+};
+var RESPONSE_METERING_TOKEN_CONTRACT = {
+  environmentVariable: FS_RUNTIME_TOKEN_ENV2,
+  presentation: RESPONSE_METERING_HEADER_NAMES.token,
+  storage: "sha256-hash-only"
+};
 var MAX_BODY_BYTES2 = 10 * 1024 * 1024;
 async function hashBody(body) {
   const bytes = new Uint8Array(body);
@@ -469,11 +480,19 @@ var MeteringClient = class {
         `meter '${meter}' is not in the token's allowedMeters`
       );
     }
-    if (options.routeId && this.config.allowedRoutes.length > 0 && !this.config.allowedRoutes.includes(options.routeId)) {
-      throw new FartherShoreError(
-        "invalid_token",
-        `route '${options.routeId}' is not in the token's allowedRoutes`
-      );
+    if (this.config.allowedRoutes.length > 0) {
+      if (!options.routeId) {
+        throw new FartherShoreError(
+          "invalid_token",
+          "routeId is required because this runtime token is route-scoped"
+        );
+      }
+      if (!this.config.allowedRoutes.includes(options.routeId)) {
+        throw new FartherShoreError(
+          "invalid_token",
+          `route '${options.routeId}' is not in the token's allowedRoutes`
+        );
+      }
     }
     if (this.config.perEventMax > 0 && qty > this.config.perEventMax) {
       throw new FartherShoreError(
@@ -521,9 +540,6 @@ var MeteringClient = class {
           body: JSON.stringify(event)
         });
         if (response.ok) return true;
-        if (response.status >= 400 && response.status < 500 && response.status !== 429) {
-          return true;
-        }
       } catch {
       }
     }
@@ -1029,8 +1045,8 @@ function headerGetter(headers) {
 }
 
 // src/core/runtime.ts
-var DEFAULT_CORE_URL = "https://api.farthershore.com";
-var SDK_VERSION = "0.1.0";
+var DEFAULT_CORE_URL = "https://core.farthershore.com";
+var SDK_VERSION = "0.2.0".length > 0 ? "0.2.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1244,6 +1260,43 @@ var RUNTIME_ERROR_CODES = {
   missingToken: "missing_token",
   invalidToken: "invalid_token"
 };
+var RUNTIME_RESPONSE_METERING_CONTRACT = {
+  headers: {
+    payload: "x-fs-metering",
+    signature: "x-fs-metering-sig",
+    token: "x-fs-metering-token"
+  },
+  token: {
+    environmentVariable: "FS_RUNTIME_TOKEN",
+    presentation: "x-fs-metering-token",
+    storage: "sha256-hash-only"
+  },
+  signature: {
+    algorithm: "HMAC-SHA256",
+    encoding: "base64url",
+    input: "payload-json",
+    secret: "presented-runtime-token"
+  },
+  payload: {
+    method: "string",
+    path: "string",
+    rawDimsUnits: "Record<string, number>",
+    measureContext: "Record<string, unknown>?",
+    creditUnitsConsumed: "Record<string, number>?"
+  },
+  errors: {
+    missingToken: "missing_token",
+    invalidMeterKey: "invalid_meter_key",
+    invalidMeterValue: "invalid_meter_value"
+  },
+  httpAdapter: {
+    input: "Request",
+    output: "Response",
+    networkCalls: false,
+    preserves: ["body", "headers", "status", "statusText"],
+    gatewayStripsInternalHeaders: true
+  }
+};
 
 // src/adapters/express.ts
 var STREAMING_CONTENT_TYPES = new Set(
@@ -1311,24 +1364,13 @@ function headerValue(headers, name) {
   return value;
 }
 
-// src/generated/metering-contract.ts
-var METERING_HEADERS = {
-  payload: "x-fs-metering",
-  signature: "x-fs-metering-sig",
-  token: "x-fs-metering-token"
-};
-var METERING_TOKEN_ENV = "FARTHERSHORE_METERING_TOKEN";
-var METERING_ERROR_CODES = {
-  missingToken: "missing_token",
-  invalidMeterKey: "invalid_meter_key",
-  invalidMeterValue: "invalid_meter_value"
-};
-
-// src/legacy/metering.ts
-var METERING_PAYLOAD_HEADER = METERING_HEADERS.payload;
-var METERING_SIGNATURE_HEADER = METERING_HEADERS.signature;
-var METERING_TOKEN_HEADER = METERING_HEADERS.token;
-var DEFAULT_TOKEN_ENV = METERING_TOKEN_ENV;
+// src/response-metering.ts
+var RESPONSE_METERING_HEADERS = RUNTIME_RESPONSE_METERING_CONTRACT.headers;
+var RESPONSE_METERING_ERROR_CODES = RUNTIME_RESPONSE_METERING_CONTRACT.errors;
+var METERING_PAYLOAD_HEADER = RESPONSE_METERING_HEADERS.payload;
+var METERING_SIGNATURE_HEADER = RESPONSE_METERING_HEADERS.signature;
+var METERING_TOKEN_HEADER = RESPONSE_METERING_HEADERS.token;
+var DEFAULT_TOKEN_ENV = RUNTIME_RESPONSE_METERING_CONTRACT.token.environmentVariable;
 var MeteringError = class extends Error {
   code;
   constructor(code, message) {
@@ -1344,8 +1386,8 @@ function createUsage(request, options = {}) {
       usage[assertMeterKey(meter)] = assertMeterValue(meter, value);
       return reporter;
     },
-    async wrap(response) {
-      return signResponse(request, response, usage, options);
+    async wrap(response, wrapOptions = {}) {
+      return signResponse(request, response, usage, options, wrapOptions);
     }
   };
   return reporter;
@@ -1357,9 +1399,9 @@ async function withUsage(request, response, usage, options = {}) {
   }
   return reporter.wrap(response);
 }
-async function signResponse(request, response, usage, options) {
+async function signResponse(request, response, usage, options, wrapOptions) {
   const token = resolveToken(options);
-  const payload = buildPayload(request, usage);
+  const payload = buildPayload(request, usage, options, wrapOptions);
   const signature = await signPayload(payload, token);
   const headers = new Headers(response.headers);
   headers.set(METERING_PAYLOAD_HEADER, payload);
@@ -1371,12 +1413,20 @@ async function signResponse(request, response, usage, options) {
     headers
   });
 }
-function buildPayload(request, usage) {
+function buildPayload(request, usage, options, wrapOptions) {
   const url = new URL(request.url);
+  const measureContext = wrapOptions.measureContext ?? options.measureContext;
+  const creditUnitsConsumed = wrapOptions.creditUnitsConsumed ?? options.creditUnitsConsumed;
   const payload = {
     method: request.method.toUpperCase(),
     path: url.pathname,
-    rawDimsUnits: sortUsage(usage)
+    rawDimsUnits: sortUsage(usage),
+    ...measureContext ? { measureContext } : {},
+    ...creditUnitsConsumed ? {
+      creditUnitsConsumed: sortUsage(
+        validateUsageMap(creditUnitsConsumed, "creditUnitsConsumed")
+      )
+    } : {}
   };
   return JSON.stringify(payload);
 }
@@ -1385,10 +1435,18 @@ function sortUsage(usage) {
     Object.entries(usage).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
   );
 }
+function validateUsageMap(usage, label) {
+  return Object.fromEntries(
+    Object.entries(usage).map(([meter, value]) => [
+      assertMeterKey(meter),
+      assertMeterValue(`${label}.${meter}`, value)
+    ])
+  );
+}
 function assertMeterKey(meter) {
   if (!/^[a-z0-9_]{1,64}$/.test(meter)) {
     throw new MeteringError(
-      METERING_ERROR_CODES.invalidMeterKey,
+      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
       `meter key "${meter}" must be lowercase alphanumeric with underscores`
     );
   }
@@ -1397,7 +1455,7 @@ function assertMeterKey(meter) {
 function assertMeterValue(meter, value) {
   if (!Number.isFinite(value) || value < 0) {
     throw new MeteringError(
-      METERING_ERROR_CODES.invalidMeterValue,
+      RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
       `meter "${meter}" value must be a non-negative finite number`
     );
   }
@@ -1407,7 +1465,7 @@ function resolveToken(options) {
   const token = options.token ?? options.env?.[DEFAULT_TOKEN_ENV] ?? processEnv(DEFAULT_TOKEN_ENV);
   if (!token) {
     throw new MeteringError(
-      METERING_ERROR_CODES.missingToken,
+      RESPONSE_METERING_ERROR_CODES.missingToken,
       `${DEFAULT_TOKEN_ENV} is required to sign Farther Shore metering reports`
     );
   }

package/dist/types/core/bootstrap.d.ts

@@ -2,7 +2,7 @@ import { type RuntimeBootstrapRequest, type RuntimeBootstrapResponse } from "../
 /** Where to reach core's bootstrap endpoint. Derived from the token's coreUrl. */
 export type BootstrapClientOptions = {
     runtimeToken: string;
-    /** Core base URL, e.g. https://api.farthershore.com. */
+    /** Core base URL, e.g. https://core.farthershore.com. */
     coreUrl: string;
     /** Optional bootstrap request metadata. */
     request?: RuntimeBootstrapRequest;

package/dist/types/core/runtime.d.ts

@@ -20,7 +20,7 @@ export type FartherShoreInitOptions = {
     runtimeToken?: string;
     /**
      * Core base URL. Defaults to FS_CORE_URL / FARTHERSHORE_CORE_URL or
-     * https://api.farthershore.com.
+     * https://core.farthershore.com.
      */
     coreUrl?: string;
     /** Env map (tests). Defaults to process.env. */
@@ -39,6 +39,7 @@ export type FartherShoreInitOptions = {
     /** SDK metadata forwarded to bootstrap. */
     instanceId?: string;
 };
+export declare const SDK_VERSION: string;
 /**
  * The runtime instance. Lazily bootstraps; holds the JWKS client, nonce cache,
  * metering buffer, and shutdown hooks.

package/dist/types/generated/runtime-contract.d.ts

@@ -156,7 +156,44 @@ export declare const RUNTIME_METERING_CONTRACT: {
     readonly delivery: "at-least-once";
     readonly billingOnly: true;
     readonly realtimeEnforced: false;
-    readonly trustModel: "backend-reported values are NOT cryptographically attested; a buggy or compromised backend can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
+    readonly trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
+};
+export declare const RUNTIME_RESPONSE_METERING_CONTRACT: {
+    readonly headers: {
+        readonly payload: "x-fs-metering";
+        readonly signature: "x-fs-metering-sig";
+        readonly token: "x-fs-metering-token";
+    };
+    readonly token: {
+        readonly environmentVariable: "FS_RUNTIME_TOKEN";
+        readonly presentation: "x-fs-metering-token";
+        readonly storage: "sha256-hash-only";
+    };
+    readonly signature: {
+        readonly algorithm: "HMAC-SHA256";
+        readonly encoding: "base64url";
+        readonly input: "payload-json";
+        readonly secret: "presented-runtime-token";
+    };
+    readonly payload: {
+        readonly method: "string";
+        readonly path: "string";
+        readonly rawDimsUnits: "Record<string, number>";
+        readonly measureContext: "Record<string, unknown>?";
+        readonly creditUnitsConsumed: "Record<string, number>?";
+    };
+    readonly errors: {
+        readonly missingToken: "missing_token";
+        readonly invalidMeterKey: "invalid_meter_key";
+        readonly invalidMeterValue: "invalid_meter_value";
+    };
+    readonly httpAdapter: {
+        readonly input: "Request";
+        readonly output: "Response";
+        readonly networkCalls: false;
+        readonly preserves: readonly ["body", "headers", "status", "statusText"];
+        readonly gatewayStripsInternalHeaders: true;
+    };
 };
 export declare const RUNTIME_HEALTH_CONTRACT: {
     readonly endpoint: "/v1/runtime/health";

package/dist/types/index.d.ts

@@ -16,7 +16,7 @@ export { createExpressMiddleware, type ExpressMiddleware, type ExpressRequestLik
 export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_CAPABILITIES, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenCapability, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, } from "./runtime-types.js";
 export { RUNTIME_ERROR_CODES } from "./generated/runtime-contract.js";
 export { hashBody, buildCanonicalSigningString, canonicalizeQuery, signCanonicalString, verifyCanonicalSignature, runtimeTokenKind, } from "./runtime-signing.js";
-export { createUsage, withUsage, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, } from "./legacy/metering.js";
+export { createUsage, withUsage, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, } from "./response-metering.js";
 /**
  * The conceptual public entrypoint. `fartherShore.initFromEnv()` mirrors the
  * language-neutral spec. The returned instance is augmented with `middleware()`

package/dist/types/response-metering.d.ts

@@ -0,0 +1,32 @@
+declare const RESPONSE_METERING_ERROR_CODES: {
+    readonly missingToken: "missing_token";
+    readonly invalidMeterKey: "invalid_meter_key";
+    readonly invalidMeterValue: "invalid_meter_value";
+};
+type ResponseMeteringErrorCode = (typeof RESPONSE_METERING_ERROR_CODES)[keyof typeof RESPONSE_METERING_ERROR_CODES];
+export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
+export declare const METERING_SIGNATURE_HEADER: "x-fs-metering-sig";
+export declare const METERING_TOKEN_HEADER: "x-fs-metering-token";
+export declare const DEFAULT_TOKEN_ENV: "FS_RUNTIME_TOKEN";
+export type UsageMap = Record<string, number>;
+export type MeteringOptions = {
+    token?: string;
+    env?: Record<string, string | undefined>;
+    measureContext?: Record<string, unknown>;
+    creditUnitsConsumed?: UsageMap;
+};
+export type UsageWrapOptions = {
+    measureContext?: Record<string, unknown>;
+    creditUnitsConsumed?: UsageMap;
+};
+export type UsageReporter = {
+    report(meter: string, value: number): UsageReporter;
+    wrap(response: Response, options?: UsageWrapOptions): Promise<Response>;
+};
+export declare class MeteringError extends Error {
+    readonly code: ResponseMeteringErrorCode;
+    constructor(code: ResponseMeteringErrorCode, message: string);
+}
+export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
+export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.1.0",
-  "description": "Farther Shore backend SDK: secure BYO-backend runtime — fail-closed gateway request verification, metering, health, and lifecycle, all derived from FS_RUNTIME_TOKEN",
+  "version": "0.2.0",
+  "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, health, and lifecycle from FS_RUNTIME_TOKEN",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/dist/types/generated/metering-contract.d.ts

@@ -1,36 +0,0 @@
-export declare const METERING_CONTRACT_VERSION: 1;
-export declare const METERING_HEADERS: {
-    readonly payload: "x-fs-metering";
-    readonly signature: "x-fs-metering-sig";
-    readonly token: "x-fs-metering-token";
-};
-export declare const METERING_TOKEN_ENV: "FARTHERSHORE_METERING_TOKEN";
-export declare const METERING_TOKEN_CONTRACT: {
-    readonly environmentVariable: "FARTHERSHORE_METERING_TOKEN";
-    readonly presentation: "x-fs-metering-token";
-    readonly storage: "sha256-hash-only";
-};
-export declare const METERING_SIGNATURE_CONTRACT: {
-    readonly algorithm: "HMAC-SHA256";
-    readonly encoding: "base64url";
-    readonly input: "payload-json";
-    readonly secret: "presented-metering-token";
-};
-export declare const METERING_ERROR_CODES: {
-    readonly missingToken: "missing_token";
-    readonly invalidMeterKey: "invalid_meter_key";
-    readonly invalidMeterValue: "invalid_meter_value";
-};
-export type MeteringErrorCode = (typeof METERING_ERROR_CODES)[keyof typeof METERING_ERROR_CODES];
-export declare const METERING_HTTP_ADAPTER_CONTRACT: {
-    readonly input: "Request";
-    readonly output: "Response";
-    readonly networkCalls: false;
-    readonly preserves: readonly ["body", "headers", "status", "statusText"];
-    readonly gatewayStripsInternalHeaders: true;
-};
-export type MeteringUsagePayload = {
-    method: string;
-    path: string;
-    rawDimsUnits: Record<string, number>;
-};

package/dist/types/legacy/metering.d.ts

@@ -1,20 +0,0 @@
-import { type MeteringErrorCode } from "../generated/metering-contract.js";
-export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
-export declare const METERING_SIGNATURE_HEADER: "x-fs-metering-sig";
-export declare const METERING_TOKEN_HEADER: "x-fs-metering-token";
-export declare const DEFAULT_TOKEN_ENV: "FARTHERSHORE_METERING_TOKEN";
-export type UsageMap = Record<string, number>;
-export type MeteringOptions = {
-    token?: string;
-    env?: Record<string, string | undefined>;
-};
-export type UsageReporter = {
-    report(meter: string, value: number): UsageReporter;
-    wrap(response: Response): Promise<Response>;
-};
-export declare class MeteringError extends Error {
-    readonly code: MeteringErrorCode;
-    constructor(code: MeteringErrorCode, message: string);
-}
-export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
-export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;