@boxrouter/sdk 0.0.1-alpha.0 → 0.12.190

package/dist/server-timing.d.ts

@@ -0,0 +1,19 @@
+/** Safe, opt-in Server-Timing measurements for a BoxRouter fetch hook. */
+import type { RequestTiming, ServerTimingMeasurements } from './server-timing.gen';
+export type { AggregateTiming, OperationTiming, OmittedTiming, OperationCoverage, OperationOutcome, RequestTiming, ServerTimingMeasurements, } from './server-timing.gen';
+/** Carry opt-in timing across the generated API call, fetch and response validation. */
+export declare function withClientTiming<T>(run: () => Promise<T>, enabled: boolean): Promise<T>;
+/** Mark TCP and TLS separately when the SDK's owned connector exposes both events. */
+/** Capture the current operation before Undici invokes its asynchronous connector callbacks. */
+export declare function connectionSegmentRecorder(field: 'dnsMs' | 'connectMs' | 'tlsMs'): ((started: number, ended: number) => void) & {
+    dnsEndedAt(): number | undefined;
+};
+/** Timestamp after DNS, used by the owned Undici connector to isolate TCP time. */
+export declare function connectionSegmentStart(): number | undefined;
+/** Parse bounded, independent measurements without inferring complete coverage. */
+export declare function parseServerTiming(header: string | null): ServerTimingMeasurements;
+export declare function usesClientOwnedFetch(fetch: typeof globalThis.fetch | undefined): boolean;
+export declare function usesClientTimingFetch(fetch: typeof globalThis.fetch | undefined): boolean;
+/** Use the BoxRouter-owned Node pool behind a timing hook created without a custom fetch. */
+export declare function useClientOwnedFetch(fetch: typeof globalThis.fetch | undefined, clientFetch: typeof globalThis.fetch | undefined): typeof globalThis.fetch | undefined;
+export declare function createServerTimingFetch(onTiming: (timing: RequestTiming) => void, fetchImpl?: typeof globalThis.fetch): typeof globalThis.fetch;

package/dist/server-timing.gen.d.ts

@@ -0,0 +1,265 @@
+export declare const timingContract: {
+    readonly version: 1;
+    readonly unit: "ms";
+    readonly serviceAggregateMetric: "service";
+    readonly maxHeaderBytes: 8192;
+    readonly maxOperationRows: 32;
+    readonly decimalPlaces: 3;
+    readonly safeNamePattern: "^[A-Za-z0-9_.:-]{1,64}$";
+    readonly aggregates: readonly [{
+        readonly metric: "service";
+        readonly fieldStem: "cloud";
+    }, {
+        readonly metric: "database";
+        readonly fieldStem: "database";
+    }, {
+        readonly metric: "code";
+        readonly fieldStem: "code";
+    }, {
+        readonly metric: "provider_connect";
+        readonly fieldStem: "provider_connect";
+    }, {
+        readonly metric: "provider_wait";
+        readonly fieldStem: "provider_wait";
+    }, {
+        readonly metric: "accept";
+        readonly fieldStem: "accept";
+    }, {
+        readonly metric: "queue";
+        readonly fieldStem: "queue";
+    }, {
+        readonly metric: "admission";
+        readonly fieldStem: "admission";
+    }, {
+        readonly metric: "encode";
+        readonly fieldStem: "encode";
+    }];
+    readonly aggregateGrammar: {
+        readonly duration: {
+            readonly parameter: "dur";
+            readonly type: "number";
+            readonly finite: true;
+            readonly minimum: 0;
+        };
+        readonly descriptionParameter: "desc";
+        readonly unknownDescription: "unknown";
+        readonly missingMeans: "unreported";
+    };
+    readonly operationGrammar: {
+        readonly metric: "op";
+        readonly nameParameter: "desc";
+        readonly namePattern: "safeNamePattern";
+        readonly start: {
+            readonly parameter: "start";
+            readonly type: "number";
+            readonly finite: true;
+            readonly sign: "signed";
+            readonly relativeTo: "recorderWindow";
+        };
+        readonly duration: {
+            readonly parameter: "dur";
+            readonly type: "number";
+            readonly finite: true;
+            readonly minimum: 0;
+        };
+        readonly outcomeParameter: "outcome";
+        readonly outcomes: readonly ["returned", "raised"];
+        readonly requiresAggregateDependencyUnion: false;
+    };
+    readonly omissionGrammar: {
+        readonly metric: "op-omitted";
+        readonly count: {
+            readonly parameter: "desc";
+            readonly type: "integer";
+            readonly minimum: 0;
+        };
+        readonly duration: {
+            readonly parameter: "dur";
+            readonly type: "number";
+            readonly finite: true;
+            readonly minimum: 0;
+            readonly sumOf: "knownOmittedMeasuredRows";
+        };
+        readonly requiresAggregateDependencyUnion: false;
+    };
+    readonly coverageGrammar: {
+        readonly metric: "op-coverage";
+        readonly descriptionParameter: "desc";
+        readonly unknownValue: "unknown";
+        readonly absentState: "unreported";
+        readonly states: readonly ["unknown", "unreported"];
+        readonly absenceImpliesCompleteness: false;
+    };
+};
+export declare const aggregateBindings: readonly [{
+    readonly metric: "service";
+    readonly field: "cloudMs";
+}, {
+    readonly metric: "database";
+    readonly field: "databaseMs";
+}, {
+    readonly metric: "code";
+    readonly field: "codeMs";
+}, {
+    readonly metric: "provider_connect";
+    readonly field: "providerConnectMs";
+}, {
+    readonly metric: "provider_wait";
+    readonly field: "providerWaitMs";
+}, {
+    readonly metric: "accept";
+    readonly field: "acceptMs";
+}, {
+    readonly metric: "queue";
+    readonly field: "queueMs";
+}, {
+    readonly metric: "admission";
+    readonly field: "admissionMs";
+}, {
+    readonly metric: "encode";
+    readonly field: "encodeMs";
+}];
+export declare const clientTimingContract: readonly [{
+    readonly field: "dns";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "DNS lookup duration in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "connect";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "TCP connect duration in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "tls";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "TLS handshake duration in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "request_sent";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "Time to send the request body in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "first_byte";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "Time from request sent to the first response byte, in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "body_read";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "Time to read the response body in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "sdk_build";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "Time from call entry to the request handed to HTTP, in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "sdk_decode";
+    readonly unit: "ms";
+    readonly nullable: true;
+    readonly description: "Time from body bytes to the validated model, in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "connection_reused";
+    readonly unit: "boolean";
+    readonly nullable: true;
+    readonly description: "Whether the HTTP connection was reused. Null means not observable on this transport.";
+}];
+export declare const clientTimingBindings: readonly [{
+    readonly field: "dnsMs";
+    readonly unit: "ms";
+    readonly description: "DNS lookup duration in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "connectMs";
+    readonly unit: "ms";
+    readonly description: "TCP connect duration in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "tlsMs";
+    readonly unit: "ms";
+    readonly description: "TLS handshake duration in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "requestSentMs";
+    readonly unit: "ms";
+    readonly description: "Time to send the request body in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "firstByteMs";
+    readonly unit: "ms";
+    readonly description: "Time from request sent to the first response byte, in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "bodyReadMs";
+    readonly unit: "ms";
+    readonly description: "Time to read the response body in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "sdkBuildMs";
+    readonly unit: "ms";
+    readonly description: "Time from call entry to the request handed to HTTP, in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "sdkDecodeMs";
+    readonly unit: "ms";
+    readonly description: "Time from body bytes to the validated model, in milliseconds. Null means not observable on this transport.";
+}, {
+    readonly field: "connectionReused";
+    readonly unit: "boolean";
+    readonly description: "Whether the HTTP connection was reused. Null means not observable on this transport.";
+}];
+export type AggregateMetric = "service" | "database" | "code" | "provider_connect" | "provider_wait" | "accept" | "queue" | "admission" | "encode";
+export type OperationOutcome = "returned" | "raised";
+export type OperationCoverage = "unknown" | "unreported";
+export interface AggregateTiming {
+    durationMs: number | null;
+    state: 'measured' | OperationCoverage;
+}
+export interface OperationTiming {
+    name: string;
+    startMs: number;
+    durationMs: number;
+    outcome: OperationOutcome;
+}
+export interface OmittedTiming {
+    /** Exact count; decimal text is used only beyond JavaScript's safe integer range. */
+    count: number | string;
+    durationMs: number;
+}
+export interface ServerTimingMeasurements {
+    aggregates: Record<AggregateMetric, AggregateTiming>;
+    operations: OperationTiming[];
+    omissions: OmittedTiming | null;
+    operationCoverage: OperationCoverage;
+    /** Client parsing hit a bound; this does not change the server's coverage claim. */
+    parseLimited: boolean;
+}
+export interface RequestTiming {
+    /** Elapsed milliseconds through response body consumption. */
+    clientMs: number;
+    /** Client duration minus measured Cloud duration, clamped at zero. */
+    networkMs: number | null;
+    cloudMs: number | null;
+    databaseMs: number | null;
+    codeMs: number | null;
+    providerConnectMs: number | null;
+    providerWaitMs: number | null;
+    acceptMs: number | null;
+    queueMs: number | null;
+    admissionMs: number | null;
+    encodeMs: number | null;
+    /** DNS lookup duration in milliseconds. Null means not observable on this transport. */
+    dnsMs?: number | null;
+    /** TCP connect duration in milliseconds. Null means not observable on this transport. */
+    connectMs?: number | null;
+    /** TLS handshake duration in milliseconds. Null means not observable on this transport. */
+    tlsMs?: number | null;
+    /** Time to send the request body in milliseconds. Null means not observable on this transport. */
+    requestSentMs?: number | null;
+    /** Time from request sent to the first response byte, in milliseconds. Null means not observable on this transport. */
+    firstByteMs?: number | null;
+    /** Time to read the response body in milliseconds. Null means not observable on this transport. */
+    bodyReadMs?: number | null;
+    /** Time from call entry to the request handed to HTTP, in milliseconds. Null means not observable on this transport. */
+    sdkBuildMs?: number | null;
+    /** Time from body bytes to the validated model, in milliseconds. Null means not observable on this transport. */
+    sdkDecodeMs?: number | null;
+    /** Whether the HTTP connection was reused. Null means not observable on this transport. */
+    connectionReused?: boolean | null;
+    /** Detailed server measurements; optional for existing callback-value constructions. */
+    serverTiming?: ServerTimingMeasurements;
+}

package/dist/server-timing.gen.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientTimingBindings = exports.clientTimingContract = exports.aggregateBindings = exports.timingContract = void 0;
+// Generated from canonical Server-Timing metadata. Do not edit.
+exports.timingContract = {
+    "version": 1,
+    "unit": "ms",
+    "serviceAggregateMetric": "service",
+    "maxHeaderBytes": 8192,
+    "maxOperationRows": 32,
+    "decimalPlaces": 3,
+    "safeNamePattern": "^[A-Za-z0-9_.:-]{1,64}$",
+    "aggregates": [
+        {
+            "metric": "service",
+            "fieldStem": "cloud"
+        },
+        {
+            "metric": "database",
+            "fieldStem": "database"
+        },
+        {
+            "metric": "code",
+            "fieldStem": "code"
+        },
+        {
+            "metric": "provider_connect",
+            "fieldStem": "provider_connect"
+        },
+        {
+            "metric": "provider_wait",
+            "fieldStem": "provider_wait"
+        },
+        {
+            "metric": "accept",
+            "fieldStem": "accept"
+        },
+        {
+            "metric": "queue",
+            "fieldStem": "queue"
+        },
+        {
+            "metric": "admission",
+            "fieldStem": "admission"
+        },
+        {
+            "metric": "encode",
+            "fieldStem": "encode"
+        }
+    ],
+    "aggregateGrammar": {
+        "duration": {
+            "parameter": "dur",
+            "type": "number",
+            "finite": true,
+            "minimum": 0
+        },
+        "descriptionParameter": "desc",
+        "unknownDescription": "unknown",
+        "missingMeans": "unreported"
+    },
+    "operationGrammar": {
+        "metric": "op",
+        "nameParameter": "desc",
+        "namePattern": "safeNamePattern",
+        "start": {
+            "parameter": "start",
+            "type": "number",
+            "finite": true,
+            "sign": "signed",
+            "relativeTo": "recorderWindow"
+        },
+        "duration": {
+            "parameter": "dur",
+            "type": "number",
+            "finite": true,
+            "minimum": 0
+        },
+        "outcomeParameter": "outcome",
+        "outcomes": [
+            "returned",
+            "raised"
+        ],
+        "requiresAggregateDependencyUnion": false
+    },
+    "omissionGrammar": {
+        "metric": "op-omitted",
+        "count": {
+            "parameter": "desc",
+            "type": "integer",
+            "minimum": 0
+        },
+        "duration": {
+            "parameter": "dur",
+            "type": "number",
+            "finite": true,
+            "minimum": 0,
+            "sumOf": "knownOmittedMeasuredRows"
+        },
+        "requiresAggregateDependencyUnion": false
+    },
+    "coverageGrammar": {
+        "metric": "op-coverage",
+        "descriptionParameter": "desc",
+        "unknownValue": "unknown",
+        "absentState": "unreported",
+        "states": [
+            "unknown",
+            "unreported"
+        ],
+        "absenceImpliesCompleteness": false
+    }
+};
+exports.aggregateBindings = [
+    {
+        "metric": "service",
+        "field": "cloudMs"
+    },
+    {
+        "metric": "database",
+        "field": "databaseMs"
+    },
+    {
+        "metric": "code",
+        "field": "codeMs"
+    },
+    {
+        "metric": "provider_connect",
+        "field": "providerConnectMs"
+    },
+    {
+        "metric": "provider_wait",
+        "field": "providerWaitMs"
+    },
+    {
+        "metric": "accept",
+        "field": "acceptMs"
+    },
+    {
+        "metric": "queue",
+        "field": "queueMs"
+    },
+    {
+        "metric": "admission",
+        "field": "admissionMs"
+    },
+    {
+        "metric": "encode",
+        "field": "encodeMs"
+    }
+];
+exports.clientTimingContract = [
+    {
+        "field": "dns",
+        "unit": "ms",
+        "nullable": true,
+        "description": "DNS lookup duration in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "connect",
+        "unit": "ms",
+        "nullable": true,
+        "description": "TCP connect duration in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "tls",
+        "unit": "ms",
+        "nullable": true,
+        "description": "TLS handshake duration in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "request_sent",
+        "unit": "ms",
+        "nullable": true,
+        "description": "Time to send the request body in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "first_byte",
+        "unit": "ms",
+        "nullable": true,
+        "description": "Time from request sent to the first response byte, in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "body_read",
+        "unit": "ms",
+        "nullable": true,
+        "description": "Time to read the response body in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "sdk_build",
+        "unit": "ms",
+        "nullable": true,
+        "description": "Time from call entry to the request handed to HTTP, in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "sdk_decode",
+        "unit": "ms",
+        "nullable": true,
+        "description": "Time from body bytes to the validated model, in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "connection_reused",
+        "unit": "boolean",
+        "nullable": true,
+        "description": "Whether the HTTP connection was reused. Null means not observable on this transport."
+    }
+];
+exports.clientTimingBindings = [
+    {
+        "field": "dnsMs",
+        "unit": "ms",
+        "description": "DNS lookup duration in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "connectMs",
+        "unit": "ms",
+        "description": "TCP connect duration in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "tlsMs",
+        "unit": "ms",
+        "description": "TLS handshake duration in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "requestSentMs",
+        "unit": "ms",
+        "description": "Time to send the request body in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "firstByteMs",
+        "unit": "ms",
+        "description": "Time from request sent to the first response byte, in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "bodyReadMs",
+        "unit": "ms",
+        "description": "Time to read the response body in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "sdkBuildMs",
+        "unit": "ms",
+        "description": "Time from call entry to the request handed to HTTP, in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "sdkDecodeMs",
+        "unit": "ms",
+        "description": "Time from body bytes to the validated model, in milliseconds. Null means not observable on this transport."
+    },
+    {
+        "field": "connectionReused",
+        "unit": "boolean",
+        "description": "Whether the HTTP connection was reused. Null means not observable on this transport."
+    }
+];