@pellux/goodvibes-transport-http 0.18.3 → 0.30.0

package/README.md

@@ -1,18 +1,25 @@
 # @pellux/goodvibes-transport-http
 
-HTTP, JSON, path, and SSE helpers for GoodVibes SDK clients.
+Internal workspace package backing `@pellux/goodvibes-sdk/transport-http`.
 
-Install:
-
-```bash
-npm install @pellux/goodvibes-transport-http
-```
+Consumers should install `@pellux/goodvibes-sdk` and import this surface from the umbrella package.
 
 Exports include:
 - contract route invocation helpers
 - HTTP transport creation
+- direct JSON request helpers
 - header and auth token resolution helpers
 - retry/backoff helpers
 - SSE streaming helpers
 
-Use this package when you need lower-level HTTP/SSE control or when you are building a custom GoodVibes client on top of the synced contracts.
+Use this surface when you need lower-level HTTP/SSE control or when you are building a custom GoodVibes client on top of the synced contracts.
+
+```ts
+import { createJsonRequestInit, requestJson } from '@pellux/goodvibes-sdk/transport-http';
+
+const body = await requestJson(
+  fetch,
+  'http://127.0.0.1:3210/api/control-plane/auth',
+  createJsonRequestInit(process.env.GOODVIBES_TOKEN ?? null),
+);
+```

package/dist/auth.d.ts

@@ -1,7 +1,32 @@
 export type MaybePromise<T> = T | Promise<T>;
 export type AuthTokenResolver = () => MaybePromise<string | null | undefined>;
+/**
+ * Any supported public auth-token input form.
+ * Normalised to `AuthTokenResolver` at SDK/transport boundaries via `normalizeAuthToken`.
+ */
+export type AuthTokenInput = string | {
+    readonly token: string;
+} | AuthTokenResolver | (() => string | null | undefined | Promise<string | null | undefined>) | undefined;
 export type HeaderResolver = () => MaybePromise<HeadersInit | undefined>;
 export declare function mergeHeaders(...sources: Array<HeadersInit | undefined>): Headers;
+export declare function mergeHeaderRecord(...sources: Array<HeadersInit | undefined>): Record<string, string>;
+/**
+ * Accepts any supported auth token form and returns a canonical async resolver.
+ *
+ * - `string`           → resolver that always returns the string
+ * - `{ token: string }` → resolver that always returns `input.token`
+ * - sync function      → resolver that awaits `input()` (errors propagate)
+ * - async function     → passes through as-is
+ * - `undefined`        → resolver that returns `undefined`
+ */
+export declare function normalizeAuthToken(input: AuthTokenInput): AuthTokenResolver;
+/**
+ * Resolve the token for an outbound transport request.
+ *
+ * This helper is intentionally transport-facing: it does not read process
+ * environment variables, config files, or global SDK state. Higher layers are
+ * responsible for choosing a token source and passing it here explicitly.
+ */
 export declare function resolveAuthToken(authToken: string | null | undefined, getAuthToken?: AuthTokenResolver): Promise<string | null>;
 export declare function resolveHeaders(headers: HeadersInit | undefined, getHeaders?: HeaderResolver): Promise<Headers>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GAAG,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAE9E,MAAM,MAAM,cAAc,GAAG,MAAM,YAAY,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;AAuBzE,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,OAAO,CAMhF;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,YAAY,CAAC,EAAE,iBAAiB,GAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxB;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,UAAU,CAAC,EAAE,cAAc,GAC1B,OAAO,CAAC,OAAO,CAAC,CAGlB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GAAG,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1B,iBAAiB,GACjB,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,GACtE,SAAS,CAAC;AAEd,MAAM,MAAM,cAAc,GAAG,MAAM,YAAY,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;AA0CzE,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,OAAO,CAMhF;AAED,wBAAgB,iBAAiB,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpG;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAY3E;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,YAAY,CAAC,EAAE,iBAAiB,GAC/B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxB;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,UAAU,CAAC,EAAE,cAAc,GAC1B,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/auth.js

@@ -19,6 +19,26 @@ function appendHeaders(target, headers) {
         }
     }
 }
+function appendHeaderRecord(target, headers) {
+    if (!headers)
+        return;
+    if (headers instanceof Headers) {
+        headers.forEach((value, key) => {
+            target[key.toLowerCase()] = value;
+        });
+        return;
+    }
+    if (Array.isArray(headers)) {
+        for (const [key, value] of headers) {
+            target[key.toLowerCase()] = value;
+        }
+        return;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (value !== undefined)
+            target[key.toLowerCase()] = value;
+    }
+}
 export function mergeHeaders(...sources) {
     const headers = new Headers();
     for (const source of sources) {
@@ -26,6 +46,41 @@ export function mergeHeaders(...sources) {
     }
     return headers;
 }
+export function mergeHeaderRecord(...sources) {
+    const headers = {};
+    for (const source of sources)
+        appendHeaderRecord(headers, source);
+    return headers;
+}
+/**
+ * Accepts any supported auth token form and returns a canonical async resolver.
+ *
+ * - `string`           → resolver that always returns the string
+ * - `{ token: string }` → resolver that always returns `input.token`
+ * - sync function      → resolver that awaits `input()` (errors propagate)
+ * - async function     → passes through as-is
+ * - `undefined`        → resolver that returns `undefined`
+ */
+export function normalizeAuthToken(input) {
+    if (input === undefined) {
+        return async () => undefined;
+    }
+    if (typeof input === 'string') {
+        return async () => input;
+    }
+    if (typeof input === 'function') {
+        return async () => await input() ?? undefined;
+    }
+    // { token: string } wrapper object
+    return async () => input.token;
+}
+/**
+ * Resolve the token for an outbound transport request.
+ *
+ * This helper is intentionally transport-facing: it does not read process
+ * environment variables, config files, or global SDK state. Higher layers are
+ * responsible for choosing a token source and passing it here explicitly.
+ */
 export async function resolveAuthToken(authToken, getAuthToken) {
     if (getAuthToken) {
         const resolved = await getAuthToken();

package/dist/backoff.d.ts

@@ -11,6 +11,13 @@ export interface ResolvedBackoffPolicy {
     readonly backoffFactor: number;
 }
 export declare function normalizeBackoffPolicy(policy: BackoffPolicy | undefined, defaults: ResolvedBackoffPolicy): ResolvedBackoffPolicy;
+/**
+ * Return the retry delay for a one-based attempt number.
+ *
+ * Attempt `1` is the first retry and uses `baseDelayMs`; attempt `2` applies
+ * one backoff factor; attempt `0` or negative values return `0` so defensive
+ * callers do not schedule negative or NaN timers.
+ */
 export declare function computeBackoffDelay(attempt: number, policy: ResolvedBackoffPolicy): number;
 export declare function sleepWithSignal(delayMs: number, signal?: AbortSignal): Promise<void>;
 //# sourceMappingURL=backoff.d.ts.map

package/dist/backoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,QAAQ,EAAE,qBAAqB,GAC9B,qBAAqB,CAOvB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,qBAAqB,GAC5B,MAAM,CAKR;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../src/backoff.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,QAAQ,EAAE,qBAAqB,GAC9B,qBAAqB,CAOvB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,qBAAqB,GAC5B,MAAM,CAKR;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/backoff.js

@@ -6,10 +6,17 @@ export function normalizeBackoffPolicy(policy, defaults) {
         backoffFactor: Math.max(1, policy?.backoffFactor ?? defaults.backoffFactor),
     };
 }
+/**
+ * Return the retry delay for a one-based attempt number.
+ *
+ * Attempt `1` is the first retry and uses `baseDelayMs`; attempt `2` applies
+ * one backoff factor; attempt `0` or negative values return `0` so defensive
+ * callers do not schedule negative or NaN timers.
+ */
 export function computeBackoffDelay(attempt, policy) {
-    if (attempt <= 1)
+    if (attempt <= 0)
         return 0;
-    const exponent = Math.max(0, attempt - 2);
+    const exponent = Math.max(0, attempt - 1);
     const delay = policy.baseDelayMs * (policy.backoffFactor ** exponent);
     return Math.min(policy.maxDelayMs, Math.max(0, Math.floor(delay)));
 }
@@ -24,6 +31,7 @@ export async function sleepWithSignal(delayMs, signal) {
             cleanup();
             resolve();
         }, delayMs);
+        timer.unref?.();
         const onAbort = () => {
             clearTimeout(timer);
             cleanup();

package/dist/client-plumbing.d.ts

@@ -0,0 +1,32 @@
+export type RequiredKeys<T extends object> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+/**
+ * Maps a contract input object to the public client method argument tuple.
+ * Required input fields make the first argument required; fully optional input
+ * shapes keep it optional; `undefined` inputs expose only the options argument.
+ */
+export type MethodArgs<TInput, TOptions> = [
+    TInput
+] extends [undefined] ? [input?: undefined, options?: TOptions] : TInput extends object ? [RequiredKeys<TInput>] extends [never] ? [input?: TInput, options?: TOptions] : [input: TInput, options?: TOptions] : [input: TInput, options?: TOptions];
+/** Remove path-bound keys from a contract input before exposing method helpers. */
+export type WithoutKeys<TInput, TKeys extends PropertyKey> = [
+    TInput
+] extends [undefined] ? undefined : TInput extends object ? Omit<TInput, Extract<keyof TInput, TKeys>> : TInput;
+/**
+ * Splits a generated client helper's rest tuple into input and options.
+ * The tuple type already proves the argument shape; runtime work is only the
+ * array-position split used by generated path helpers.
+ */
+export declare function splitClientArgs<TInput, TOptions>(args: readonly unknown[]): readonly [TInput | undefined, TOptions | undefined];
+/** Convert a typed client input object into the record shape required by contract route helpers. */
+export declare function clientInputRecord<TInput>(input: TInput | undefined): Record<string, unknown> | undefined;
+/** Merge fixed path fields with the optional typed client input record. */
+export declare function mergeClientInput<TInput>(fixed: Record<string, unknown>, input: TInput | undefined): Record<string, unknown>;
+export interface JsonSchemaValidationFailure {
+    readonly path: string;
+    readonly expected: string;
+    readonly received: string;
+}
+export declare function firstJsonSchemaFailure(schema: Record<string, unknown>, value: unknown, path?: string, root?: Record<string, unknown>): JsonSchemaValidationFailure | undefined;
+//# sourceMappingURL=client-plumbing.d.ts.map

package/dist/client-plumbing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-plumbing.d.ts","sourceRoot":"","sources":["../src/client-plumbing.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI;KAC1C,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,SAAS,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC;CACpD,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,EAAE,QAAQ,IACrC;IAAC,MAAM;CAAC,SAAS,CAAC,SAAS,CAAC,GACxB,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,GACvC,MAAM,SAAS,MAAM,GACnB,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACpC,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,GACpC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,GACrC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;AAE5C,mFAAmF;AACnF,MAAM,MAAM,WAAW,CAAC,MAAM,EAAE,KAAK,SAAS,WAAW,IACvD;IAAC,MAAM;CAAC,SAAS,CAAC,SAAS,CAAC,GACxB,SAAS,GACT,MAAM,SAAS,MAAM,GACnB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,MAAM,EAAE,KAAK,CAAC,CAAC,GAC1C,MAAM,CAAC;AAEf;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,EAC9C,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC,CAKrD;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAIxG;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,MAAM,EACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,EAAE,OAAO,EACd,IAAI,SAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAU,GACrC,2BAA2B,GAAG,SAAS,CA2FzC"}

package/dist/client-plumbing.js

@@ -0,0 +1,243 @@
+/**
+ * Splits a generated client helper's rest tuple into input and options.
+ * The tuple type already proves the argument shape; runtime work is only the
+ * array-position split used by generated path helpers.
+ */
+export function splitClientArgs(args) {
+    if (args.length > 2) {
+        throw new ContractError(`Contract client helper expected at most 2 arguments but received ${args.length}.`);
+    }
+    return [args[0], args[1]];
+}
+/** Convert a typed client input object into the record shape required by contract route helpers. */
+export function clientInputRecord(input) {
+    return input && typeof input === 'object' && !Array.isArray(input)
+        ? input
+        : undefined;
+}
+/** Merge fixed path fields with the optional typed client input record. */
+export function mergeClientInput(fixed, input) {
+    return {
+        ...fixed,
+        ...(clientInputRecord(input) ?? {}),
+    };
+}
+export function firstJsonSchemaFailure(schema, value, path = '$', root = schema) {
+    if (typeof schema.$ref === 'string') {
+        const resolved = resolveLocalSchemaRef(root, schema.$ref);
+        return resolved ? firstJsonSchemaFailure(resolved, value, path, root) : undefined;
+    }
+    const allOf = readSchemaList(schema.allOf);
+    for (const child of allOf) {
+        const failure = firstJsonSchemaFailure(child, value, path, root);
+        if (failure)
+            return failure;
+    }
+    const anyOf = readSchemaList(schema.anyOf);
+    if (anyOf.length > 0) {
+        const failures = anyOf.map((child) => firstJsonSchemaFailure(child, value, path, root));
+        if (failures.every(Boolean))
+            return bestSchemaFailure(failures) ?? { path, expected: 'one matching schema', received: typeOfJsonValue(value) };
+    }
+    const oneOf = readSchemaList(schema.oneOf);
+    if (oneOf.length > 0) {
+        const matches = oneOf.filter((child) => !firstJsonSchemaFailure(child, value, path, root)).length;
+        if (matches !== 1)
+            return { path, expected: 'exactly one matching schema', received: `${matches} matches` };
+    }
+    const enumValues = schema.enum;
+    if (Array.isArray(enumValues) && !enumValues.some((candidate) => Object.is(candidate, value))) {
+        return { path, expected: `one of ${enumValues.map(String).join(', ')}`, received: typeOfJsonValue(value) };
+    }
+    if ('const' in schema && !Object.is(schema.const, value)) {
+        return { path, expected: JSON.stringify(schema.const), received: typeOfJsonValue(value) };
+    }
+    const types = readSchemaTypes(schema.type);
+    if (types.length > 0 && !types.some((type) => valueMatchesJsonType(value, type))) {
+        return { path, expected: types.join(' | '), received: typeOfJsonValue(value) };
+    }
+    const minimum = typeof schema.minimum === 'number' ? schema.minimum : undefined;
+    if (typeof value === 'number' && minimum !== undefined && value < minimum) {
+        return { path, expected: `>= ${minimum}`, received: String(value) };
+    }
+    const maximum = typeof schema.maximum === 'number' ? schema.maximum : undefined;
+    if (typeof value === 'number' && maximum !== undefined && value > maximum) {
+        return { path, expected: `<= ${maximum}`, received: String(value) };
+    }
+    const minLength = typeof schema.minLength === 'number' ? schema.minLength : undefined;
+    if (typeof value === 'string' && minLength !== undefined && value.length < minLength) {
+        return { path, expected: `length >= ${minLength}`, received: `length ${value.length}` };
+    }
+    const maxLength = typeof schema.maxLength === 'number' ? schema.maxLength : undefined;
+    if (typeof value === 'string' && maxLength !== undefined && value.length > maxLength) {
+        return { path, expected: `length <= ${maxLength}`, received: `length ${value.length}` };
+    }
+    if (typeof value === 'string' && typeof schema.pattern === 'string') {
+        const pattern = new RegExp(schema.pattern);
+        if (!pattern.test(value))
+            return { path, expected: `pattern ${schema.pattern}`, received: 'non-matching string' };
+    }
+    if (typeof value === 'string' && typeof schema.format === 'string' && !stringMatchesJsonSchemaFormat(value, schema.format)) {
+        return { path, expected: `format ${schema.format}`, received: 'non-matching string' };
+    }
+    if (value === null || value === undefined)
+        return undefined;
+    if (Array.isArray(value)) {
+        const itemSchema = schema.items;
+        if (itemSchema && typeof itemSchema === 'object' && !Array.isArray(itemSchema)) {
+            for (let index = 0; index < value.length; index++) {
+                const failure = firstJsonSchemaFailure(itemSchema, value[index], `${path}[${index}]`, root);
+                if (failure)
+                    return failure;
+            }
+        }
+        const minItems = typeof schema.minItems === 'number' ? schema.minItems : undefined;
+        if (minItems !== undefined && value.length < minItems)
+            return { path, expected: `items >= ${minItems}`, received: `${value.length} items` };
+        const maxItems = typeof schema.maxItems === 'number' ? schema.maxItems : undefined;
+        if (maxItems !== undefined && value.length > maxItems)
+            return { path, expected: `items <= ${maxItems}`, received: `${value.length} items` };
+        return undefined;
+    }
+    if (typeof value === 'object') {
+        const objectValue = value;
+        const required = Array.isArray(schema.required) ? schema.required.filter((entry) => typeof entry === 'string') : [];
+        for (const key of required) {
+            if (!(key in objectValue))
+                return { path: `${path}.${key}`, expected: 'required field', received: 'missing' };
+        }
+        const properties = schema.properties;
+        if (properties && typeof properties === 'object' && !Array.isArray(properties)) {
+            for (const [key, propertySchema] of Object.entries(properties)) {
+                if (!(key in objectValue))
+                    continue;
+                if (!propertySchema || typeof propertySchema !== 'object' || Array.isArray(propertySchema))
+                    continue;
+                const failure = firstJsonSchemaFailure(propertySchema, objectValue[key], `${path}.${key}`, root);
+                if (failure)
+                    return failure;
+            }
+        }
+        if (schema.additionalProperties === false && properties && typeof properties === 'object' && !Array.isArray(properties)) {
+            const allowed = new Set(Object.keys(properties));
+            const extra = Object.keys(objectValue).find((key) => !allowed.has(key));
+            if (extra)
+                return { path: `${path}.${extra}`, expected: 'no additional property', received: 'present' };
+        }
+    }
+    return undefined;
+}
+function resolveLocalSchemaRef(root, ref) {
+    if (!ref.startsWith('#/'))
+        return undefined;
+    let current = root;
+    for (const token of ref.slice(2).split('/')) {
+        if (!current || typeof current !== 'object' || Array.isArray(current))
+            return undefined;
+        const key = token.replace(/~1/g, '/').replace(/~0/g, '~');
+        current = current[key];
+    }
+    return current && typeof current === 'object' && !Array.isArray(current)
+        ? current
+        : undefined;
+}
+function bestSchemaFailure(failures) {
+    return failures
+        .filter((failure) => Boolean(failure))
+        .sort((left, right) => right.path.length - left.path.length)[0];
+}
+function readSchemaList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => Boolean(entry && typeof entry === 'object' && !Array.isArray(entry)));
+}
+function readSchemaTypes(type) {
+    if (typeof type === 'string')
+        return [type];
+    if (Array.isArray(type))
+        return type.filter((entry) => typeof entry === 'string');
+    return [];
+}
+function valueMatchesJsonType(value, type) {
+    switch (type) {
+        case 'null': return value === null;
+        case 'array': return Array.isArray(value);
+        case 'object': return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'integer': return Number.isInteger(value);
+        case 'number': return typeof value === 'number';
+        case 'string': return typeof value === 'string';
+        case 'boolean': return typeof value === 'boolean';
+        default: return true;
+    }
+}
+function stringMatchesJsonSchemaFormat(value, format) {
+    switch (format) {
+        case 'date-time':
+            return !Number.isNaN(Date.parse(value)) && /\dT\d/.test(value);
+        case 'date':
+            return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00.000Z`));
+        case 'time':
+            return /^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)?$/.test(value);
+        case 'duration':
+            return /^P(?!$)(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/.test(value);
+        case 'email':
+            return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+        case 'hostname':
+            return isValidHostname(value);
+        case 'ipv4':
+            return isValidIpv4(value);
+        case 'ipv6':
+            return isValidIpv6(value);
+        case 'uri':
+        case 'url':
+            return isValidUrl(value);
+        case 'uuid':
+            return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+        default:
+            return true;
+    }
+}
+function isValidUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isValidHostname(value) {
+    if (value.length === 0 || value.length > 253)
+        return false;
+    return value.split('.').every((label) => (label.length > 0
+        && label.length <= 63
+        && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(label)));
+}
+function isValidIpv4(value) {
+    const parts = value.split('.');
+    return parts.length === 4 && parts.every((part) => {
+        if (!/^\d{1,3}$/.test(part))
+            return false;
+        if (part.length > 1 && part.startsWith('0'))
+            return false;
+        const value = Number(part);
+        return value >= 0 && value <= 255;
+    });
+}
+function isValidIpv6(value) {
+    try {
+        new URL(`http://[${value}]`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function typeOfJsonValue(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+import { ContractError } from '@pellux/goodvibes-errors';

package/dist/contract-client.d.ts

@@ -1,3 +1,4 @@
+import type { ZodType } from 'zod/v4';
 import type { HttpTransport } from './http.js';
 import { type ServerSentEventHandlers } from './sse-stream.js';
 export interface ContractRouteDefinition {
@@ -6,16 +7,25 @@ export interface ContractRouteDefinition {
 }
 export interface ContractRouteLike {
     readonly id: string;
+    /** When true, this route is safe to retry on 5xx even for mutating HTTP verbs. */
+    readonly idempotent?: boolean;
 }
 export interface ContractInvokeOptions {
     readonly signal?: AbortSignal;
     readonly headers?: HeadersInit;
+    /**
+     * Optional Zod v4 schema to validate the parsed response body against.
+     * When provided, a failed parse throws a {@link ContractError} with
+     * field-level detail: operation, field path, expected type, and a
+     * recovery hint.
+     */
+    readonly responseSchema?: ZodType;
 }
 export interface ContractStreamOptions extends ContractInvokeOptions {
     readonly handlers: ServerSentEventHandlers;
 }
 export declare function buildContractInput(primaryKey: string, primaryValue: string, input?: Record<string, unknown>): Record<string, unknown>;
 export declare function requireContractRoute<TRoute extends ContractRouteLike>(routes: readonly TRoute[], routeId: string, kind: string): TRoute;
-export declare function invokeContractRoute<T = unknown>(transport: HttpTransport, route: ContractRouteDefinition, input?: Record<string, unknown>, options?: ContractInvokeOptions): Promise<T>;
+export declare function invokeContractRoute<T = unknown>(transport: HttpTransport, route: ContractRouteDefinition & ContractRouteLike, input?: Record<string, unknown>, options?: ContractInvokeOptions): Promise<T>;
 export declare function openContractRouteStream(transport: HttpTransport, route: ContractRouteDefinition, input: Record<string, unknown> | undefined, options: ContractStreamOptions): Promise<() => void>;
 //# sourceMappingURL=contract-client.d.ts.map

package/dist/contract-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-client.d.ts","sourceRoot":"","sources":["../src/contract-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAA6B,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE1F,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,iBAAiB,EACnE,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAC7C,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,uBAAuB,EAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,CAAC,CAAC,CAQZ;AAED,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,uBAAuB,EAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,MAAM,IAAI,CAAC,CAYrB"}
+{"version":3,"file":"contract-client.d.ts","sourceRoot":"","sources":["../src/contract-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAgC,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE7F,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,qBAAsB,SAAQ,qBAAqB;IAClE,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,iBAAiB,EACnE,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED,wBAAsB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EACnD,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,uBAAuB,GAAG,iBAAiB,EAClD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,uBAAuB,EAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,MAAM,IAAI,CAAC,CAYrB"}

package/dist/contract-client.js

@@ -1,4 +1,5 @@
-import { openServerSentEventStream } from './sse-stream.js';
+import { ContractError, GoodVibesSdkError } from '@pellux/goodvibes-errors';
+import { openRawServerSentEventStream } from './sse-stream.js';
 export function buildContractInput(primaryKey, primaryValue, input) {
     return {
         [primaryKey]: primaryValue,
@@ -8,22 +9,36 @@ export function buildContractInput(primaryKey, primaryValue, input) {
 export function requireContractRoute(routes, routeId, kind) {
     const route = routes.find((candidate) => candidate.id === routeId);
     if (!route) {
-        throw new Error(`Unknown ${kind} "${routeId}"`);
+        throw new GoodVibesSdkError(`Unknown ${kind} "${routeId}". Verify the method/route id is correct and that your contract manifest is up to date.`, { category: 'contract', source: 'contract', recoverable: false });
     }
     return route;
 }
-export function invokeContractRoute(transport, route, input, options = {}) {
+export async function invokeContractRoute(transport, route, input, options = {}) {
     const resolved = transport.resolveContractRequest(route.method, route.path, input);
-    return transport.requestJson(resolved.url, {
+    const body = await transport.requestJson(resolved.url, {
         method: resolved.method,
         body: resolved.body,
         headers: options.headers,
         signal: options.signal,
+        methodId: route.id,
+        idempotent: route.idempotent === true,
     });
+    if (options.responseSchema) {
+        const result = options.responseSchema.safeParse(body);
+        if (!result.success) {
+            const issue = result.error.issues[0];
+            const fieldPath = issue ? issue.path.join('.') || '(root)' : '(unknown)';
+            const expected = issue ? issue.expected ?? issue.code : 'unknown';
+            const received = issue ? issue.received ?? 'unknown' : 'unknown';
+            throw new ContractError(`Response validation failed for "${route.method} ${route.path}": field "${fieldPath}" expected ${expected} but received ${received}. Ensure the server is running the matching GoodVibes contract version.`, { source: 'contract' });
+        }
+        return result.data;
+    }
+    return body;
 }
 export async function openContractRouteStream(transport, route, input, options) {
     const resolved = transport.resolveContractRequest(route.method, route.path, input);
-    return await openServerSentEventStream(transport.fetchImpl, resolved.url, options.handlers, {
+    return await openRawServerSentEventStream(transport.fetchImpl, resolved.url, options.handlers, {
         authToken: transport.authToken,
         headers: options.headers,
         signal: options.signal,

package/dist/http-core.d.ts

@@ -1,13 +1,22 @@
+import { HttpStatusError } from '@pellux/goodvibes-errors';
 import { type AuthTokenResolver, type HeaderResolver } from './auth.js';
 import { type HttpRetryPolicy } from './retry.js';
 import { type TransportPaths } from './paths.js';
-export type { HttpRetryPolicy } from './retry.js';
+import { type TransportMiddleware, type TransportObserver } from '@pellux/goodvibes-transport-core';
+export type { HttpRetryPolicy, PerMethodRetryPolicy } from './retry.js';
+export type { TransportContext, TransportMiddleware } from '@pellux/goodvibes-transport-core';
 export type JsonValue = string | number | boolean | null | {
     readonly [key: string]: JsonValue;
 } | readonly JsonValue[];
 export type JsonObject = {
     readonly [key: string]: JsonValue;
 };
+/**
+ * Generate a UUID v4 idempotency key.
+ * Uses `crypto.randomUUID()` when available (Bun, browsers, Workers, Node 14.17+).
+ * Falls back to a manual RFC 4122 v4 implementation otherwise.
+ */
+export declare function generateIdempotencyKey(): string;
 export interface HttpJsonTransportOptions {
     readonly baseUrl: string;
     readonly authToken?: string | null;
@@ -17,6 +26,9 @@ export interface HttpJsonTransportOptions {
     readonly headers?: HeadersInit;
     readonly getHeaders?: HeaderResolver;
     readonly retry?: HttpRetryPolicy;
+    readonly observer?: TransportObserver;
+    /** Middleware chain applied to every HTTP request/response cycle. */
+    readonly middleware?: readonly TransportMiddleware[];
 }
 export interface HttpJsonRequestOptions {
     readonly method?: string;
@@ -24,6 +36,19 @@ export interface HttpJsonRequestOptions {
     readonly headers?: HeadersInit;
     readonly signal?: AbortSignal;
     readonly retry?: false | HttpRetryPolicy;
+    /**
+     * Contract method / endpoint ID used to look up per-method retry policy overrides.
+     * Populated automatically by `invokeContractRoute`; callers outside the contract
+     * layer may also set this to opt into `perMethodPolicy` overrides.
+     */
+    readonly methodId?: string;
+    /**
+     * When `true`, this call is considered idempotent even if the HTTP verb is a
+     * mutating method (POST/PUT/PATCH/DELETE). Enables retry-on-5xx for the call.
+     * Populated automatically from `contract.idempotent`; takes lower precedence
+     * than an explicit `perMethodPolicy` override.
+     */
+    readonly idempotent?: boolean;
 }
 export interface ResolvedContractRequest {
     readonly url: string;
@@ -35,6 +60,8 @@ export interface TransportJsonError {
     readonly body: unknown;
     readonly url: string;
     readonly method: string;
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
 }
 export interface HttpJsonTransport {
     readonly baseUrl: string;
@@ -45,11 +72,25 @@ export interface HttpJsonTransport {
     getAuthToken(): Promise<string | null>;
     requestJson<T>(pathOrUrl: string, options?: HttpJsonRequestOptions): Promise<T>;
     resolveContractRequest(method: string, path: string, input?: Record<string, unknown>): ResolvedContractRequest;
+    /** Append a middleware to the transport's middleware chain. */
+    use(middleware: TransportMiddleware): void;
 }
+export declare function inferTransportHint(status: number, url: string, retryAfterMs?: number): string | undefined;
+export declare function createTransportError(status: number, url: string, method: string, body: unknown, retryAfterMs?: number): HttpStatusError & {
+    readonly transport: TransportJsonError;
+};
+export declare function createNetworkTransportError(error: unknown, url: string, method: string): HttpStatusError & {
+    readonly transport: TransportJsonError;
+};
 export declare function createJsonRequestInit(token: string | null | undefined, body?: unknown, method?: string, headers?: HeadersInit, signal?: AbortSignal, defaultHeaders?: HeadersInit): RequestInit;
 export declare const createJsonInit: typeof createJsonRequestInit;
 export declare function createFetch(fetchImpl?: typeof fetch, fallbackFetch?: typeof fetch): typeof fetch;
 export declare function readJsonBody(response: Response): Promise<unknown>;
+/**
+ * @internal Low-level one-shot helper retained for legacy internal callers.
+ * Public code should use `createHttpTransport(...).requestJson()` so auth,
+ * middleware, retry policy, idempotency keys, and observers are applied.
+ */
 export declare function requestJson<T>(fetchImpl: typeof fetch, url: string, init?: RequestInit): Promise<T>;
 export declare function createHttpJsonTransport(options: HttpJsonTransportOptions): HttpJsonTransport;
 //# sourceMappingURL=http-core.d.ts.map