@farthershore/backend 0.13.0 → 0.15.0

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

@@ -1,3 +1,4 @@
+import type { ReportUsageResult, RequestScopedReportUsageInput } from "./post-stream-usage.js";
 import { type FartherShoreSignedContext } from "./verifyContext.js";
 import type { JwksClient } from "./jwks.js";
 import type { NonceCache } from "./nonceCache.js";
@@ -22,7 +23,7 @@ export type HeadersLike = Headers | Record<string, string | string[] | undefined
 /** The verified request context attached to req.fartherShore. */
 export type FartherShoreRequestContext = {
     requestId: string;
-    productId: string;
+    businessId: string;
     backendId: string;
     routeId: string;
     policyVersion: string;
@@ -48,12 +49,14 @@ export type FartherShoreRequestContext = {
     signedContext?: FartherShoreSignedContext;
     /** Managed-RBAC role keys the acting user holds (display/audit only). */
     roles?: string[];
+    /** Request-bound post-stream reporter, attached by the runtime facade. */
+    reportUsage?: (input: RequestScopedReportUsageInput) => Promise<ReportUsageResult>;
 };
 export type VerifyRequestDeps = {
     jwks: JwksClient;
     nonceCache: NonceCache;
-    /** Expected product id (from bootstrap). When set, must match the signed claim. */
-    productId?: string;
+    /** Expected business id (from bootstrap). When set, must match the signed claim. */
+    businessId?: string;
     /** Expected backend id (from bootstrap). When set, must match. */
     backendId?: string;
     /**

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

@@ -73,7 +73,7 @@ export declare const RUNTIME_SIGNING_CONTRACT: {
         readonly keyValueSeparator: ":";
         readonly trailingNewline: false;
         readonly fieldEncoding: "utf-8";
-        readonly fields: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "product-id", "backend-id", "route-id", "policy-version"];
+        readonly fields: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version"];
         readonly fieldRules: {
             readonly method: "Uppercased HTTP method (e.g. GET, POST).";
             readonly path: "Request path, percent-encoded as received, no host, no query string. Always begins with '/'.";
@@ -81,7 +81,7 @@ export declare const RUNTIME_SIGNING_CONTRACT: {
             readonly "body-hash": "Lowercase hex SHA-256 of the RAW request body bytes. For an empty body, the SHA-256 of zero bytes (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Streaming-exempt requests use the literal token 'STREAM'.";
             readonly "request-id": "Opaque unique request id minted by the gateway (also the replay-cache nonce).";
             readonly timestamp: "Integer Unix epoch seconds (UTC) at signing time, as a base-10 string with no padding.";
-            readonly "product-id": "Product id the request is routed to.";
+            readonly "business-id": "Business id the request is routed to.";
             readonly "backend-id": "Backend id the route binds to.";
             readonly "route-id": "Resolved route id; empty string if the route is unresolved.";
             readonly "policy-version": "Tenant artifact / policy version the gateway signed under.";
@@ -92,7 +92,7 @@ export declare const RUNTIME_SIGNING_CONTRACT: {
  * Ordered list of fields in the canonical signing string. The order here is
  * load-bearing and identical across all language SDKs.
  */
-export declare const RUNTIME_CANONICAL_FIELDS: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "product-id", "backend-id", "route-id", "policy-version"];
+export declare const RUNTIME_CANONICAL_FIELDS: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version"];
 export declare const RUNTIME_BODY_HASH_CONTRACT: {
     readonly algorithm: "SHA-256";
     readonly encoding: "hex-lower";
@@ -108,7 +108,7 @@ export declare const RUNTIME_HEADERS: {
     readonly keyId: "x-fs-key-id";
     readonly requestId: "x-fs-request-id";
     readonly timestamp: "x-fs-timestamp";
-    readonly productId: "x-fs-product-id";
+    readonly businessId: "x-fs-business-id";
     readonly backendId: "x-fs-backend-id";
     readonly routeId: "x-fs-route-id";
     readonly policyVersion: "x-fs-policy-version";
@@ -145,18 +145,33 @@ export declare const RUNTIME_METERING_CONTRACT: {
     readonly credential: "reusable-bearer";
     readonly event: {
         readonly event_id: "string";
-        readonly product_id: "string";
+        readonly business_id: "string";
         readonly backend_id: "string";
         readonly route_id: "string?";
         readonly request_id: "string?";
+        readonly requestId: "string?";
+        readonly subscriptionId: "string";
+        readonly nonce: "string?";
         readonly meter: "string";
         readonly qty: "number";
         readonly timestamp: "string";
     };
+    readonly postStreamEvent: {
+        readonly requestId: "string";
+        readonly subscriptionId: "string?";
+        readonly nonce: "string";
+        readonly meters: "Record<string, number>";
+        readonly creditUnitsConsumed: "Record<string, number>?";
+        readonly measureContext: "Record<string, unknown>?";
+        readonly signature: "string";
+    };
     readonly idempotencyKey: "event_id";
     readonly delivery: "at-least-once";
     readonly billingOnly: true;
     readonly realtimeEnforced: false;
+    readonly postStreamBillingOnly: true;
+    readonly postStreamRealtimeEnforced: false;
+    readonly postStreamTrustModel: "HMAC-attested and bound to one served postStreamBilling gateway request. Core writes one billable UsageEvent using the served plan and time. The callback never mutates Durable Object enforcement windows.";
     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: {

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions } from "./core/nonceCache.js";
 export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";
 export { MeteringClient, type MeteringClientOptions, type MeterOptions, } from "./core/metering.js";
+export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type RequestScopedReportUsageInput, type ReportUsageResult, } from "./core/post-stream-usage.js";
 export { buildHealthReport, reportHealth, type HealthSnapshot, type HealthStatus, type HeartbeatOptions, } from "./core/health.js";
 export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
 export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";

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

@@ -126,7 +126,7 @@ export declare const RUNTIME_HEADER_NAMES: {
     readonly keyId: "x-fs-key-id";
     readonly requestId: "x-fs-request-id";
     readonly timestamp: "x-fs-timestamp";
-    readonly productId: "x-fs-product-id";
+    readonly businessId: "x-fs-business-id";
     readonly backendId: "x-fs-backend-id";
     readonly routeId: "x-fs-route-id";
     readonly policyVersion: "x-fs-policy-version";
@@ -166,7 +166,7 @@ export type CanonicalSigningInput = {
     requestId: string;
     /** Unix epoch seconds at signing time. */
     timestamp: number;
-    productId: string;
+    businessId: string;
     backendId: string;
     /** Resolved route id; "" when unresolved. */
     routeId: string;
@@ -221,7 +221,7 @@ export type RuntimeLockDescriptor = {
     lockVersion: number;
 };
 export type RuntimeBootstrapResponse = {
-    product: {
+    business: {
         id: string;
         slug: string;
     };
@@ -247,14 +247,29 @@ export type RuntimeBootstrapResponse = {
 };
 export type RuntimeMeteringEvent = {
     event_id: string;
-    product_id: string;
+    business_id: string;
     backend_id: string;
     route_id?: string;
     request_id?: string;
+    /** Subscription the usage belongs to (billing attribution). Optional and
+     *  additive: legacy emitters omit it; core then falls back to resolving the
+     *  served gateway request via `request_id`, and rows that resolve neither
+     *  way are persisted unbilled + flagged unattributable. */
+    subscription_id?: string;
     meter: string;
     qty: number;
     timestamp: string;
 };
+/** Attested, request-bound billing callback sent after a stream completes. */
+export type RuntimePostStreamUsageEvent = {
+    requestId: string;
+    subscriptionId: string;
+    nonce: string;
+    meters: Record<string, number>;
+    creditUnitsConsumed?: Record<string, number>;
+    measureContext?: Record<string, unknown>;
+    signature: string;
+};
 export declare const RUNTIME_READINESS_STATES: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
 export type RuntimeReadinessState = (typeof RUNTIME_READINESS_STATES)[number];
 export type RuntimeHealthReport = {

package/dist/types/testing/devGateway.d.ts

@@ -1,4 +1,4 @@
-import { type RuntimeBootstrapResponse, type RuntimeMeteringEvent } from "../runtime-types.js";
+import { type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimePostStreamUsageEvent } from "../runtime-types.js";
 import type { DevMode } from "./traceSink.js";
 import type { DevSignerKeys } from "./signers.js";
 export declare const DEV_CORE_URL = "https://dev-gateway.farthershore.local";
@@ -7,14 +7,16 @@ export declare const DEV_METERING_ENDPOINT = "https://dev-gateway.farthershore.l
 export type DevGatewayOptions = {
     mode: DevMode;
     keys: DevSignerKeys;
-    productId?: string;
+    businessId?: string;
     backendId?: string;
-    productSlug?: string;
+    businessSlug?: string;
     backendSlug?: string;
     /** Extra route ids to expose in bootstrap for route-binding tests. */
     routeIds?: string[];
     /** Called for each captured metering event (at-least-once ACK). */
     onMeterEvent?: (event: RuntimeMeteringEvent) => void;
+    /** Called for each captured attested post-stream report. */
+    onReportUsage?: (event: RuntimePostStreamUsageEvent) => void;
 };
 export type DevGateway = {
     /** Inject this as `fetchImpl` when constructing the FartherShore runtime. */
@@ -23,7 +25,9 @@ export type DevGateway = {
     bootstrap: RuntimeBootstrapResponse;
     /** Every captured background metering event (a capture == an ACK). */
     meterEvents: RuntimeMeteringEvent[];
-    productId: string;
+    /** Every captured attested post-stream usage report. */
+    reportUsageEvents: RuntimePostStreamUsageEvent[];
+    businessId: string;
     backendId: string;
     jwksUrl: string;
 };

package/dist/types/testing/devRuntime.d.ts

@@ -24,7 +24,7 @@ export type CreateDevRuntimeOptions = {
     routes?: string[];
     /** Meter keys (informational — the dev gateway accepts any meter). */
     meters?: string[];
-    productId?: string;
+    businessId?: string;
     backendId?: string;
     /** Optional app transport for persona `.fetch()`; defaults to global fetch. */
     appFetch?: typeof fetch;

package/dist/types/testing/keysFile.d.ts

@@ -7,7 +7,7 @@ export type DevKeysFile = {
     version: 1;
     mode: DevMode;
     keys: DevSignerKeys;
-    productId: string;
+    businessId: string;
     backendId: string;
     /** Persona definitions in effect for this dev session. */
     personas: Record<string, PersonaDefinition>;

package/dist/types/testing/personas.d.ts

@@ -53,7 +53,7 @@ export type PersonaRequestSpec = {
 /** The context a persona client signs against (bootstrap ids + dev keys). */
 export type PersonaClientContext = {
     keys: DevSignerKeys;
-    productId: string;
+    businessId: string;
     backendId: string;
     contextSecret: string;
     contextKid: string;
@@ -96,7 +96,7 @@ export declare const SIGNED_HEADER_NAMES: {
     readonly keyId: "x-fs-key-id";
     readonly requestId: "x-fs-request-id";
     readonly timestamp: "x-fs-timestamp";
-    readonly productId: "x-fs-product-id";
+    readonly businessId: "x-fs-business-id";
     readonly backendId: "x-fs-backend-id";
     readonly routeId: "x-fs-route-id";
     readonly policyVersion: "x-fs-policy-version";

package/dist/types/testing/signers.d.ts

@@ -13,7 +13,7 @@ export type SignedHeaderOverrides = Partial<{
     kid: string;
     requestId: string;
     timestamp: number;
-    productId: string;
+    businessId: string;
     backendId: string;
     routeId: string;
     policyVersion: string;
@@ -25,7 +25,7 @@ export type SignedRequestSpec = {
     query?: string;
     body?: Uint8Array | null;
     streamingExempt?: boolean;
-    productId?: string;
+    businessId?: string;
     backendId?: string;
     routeId?: string;
     policyVersion?: string;

package/dist/types/testing/usageSink.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeMeteringEvent } from "../runtime-types.js";
+import type { RuntimeMeteringEvent, RuntimePostStreamUsageEvent } from "../runtime-types.js";
 /** One recorded usage observation. `source` distinguishes the two channels. */
 export type DevUsageEvent = {
     source: "response";
@@ -16,6 +16,12 @@ export type DevUsageEvent = {
     event: RuntimeMeteringEvent;
     requestId?: string;
     at: number;
+} | {
+    source: "reportUsage";
+    meters: Record<string, number>;
+    event: RuntimePostStreamUsageEvent;
+    requestId: string;
+    at: number;
 };
 /** In-memory, assertable sink for all dev usage. */
 export declare class DevUsageSink {
@@ -24,6 +30,8 @@ export declare class DevUsageSink {
     recordResponse(payload: Record<string, unknown>, requestId?: string): void;
     /** Record a background `fs.meter()` event captured by the dev gateway. */
     recordMeterEvent(event: RuntimeMeteringEvent): void;
+    /** Record an attested post-stream report captured by the dev gateway. */
+    recordReportUsage(event: RuntimePostStreamUsageEvent): void;
     /** Total quantity per meter key across every recorded event. */
     byMeter(): Record<string, number>;
     /** Clear all recorded usage. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.13.0",
+  "version": "0.15.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",