@oxygen-agent/cli 1.1010.905 → 1.1010.952

package/dist/sender-limits-flags.js

@@ -0,0 +1,157 @@
+// `oxygen senders limits set` (and `whatsapp limits set`, which shares the body
+// builder): flags generated from SENDER_LIMITS_PATCH_CONTRACT, the contract the
+// MCP tool and the route use too. This overlay only keeps the flag names and
+// help text the command shipped with before the contract existed.
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { LINKEDIN_SENDER_LIMIT_DEFAULTS, LINKEDIN_SENDER_LIMIT_MAXIMUMS, } from "@oxygen/shared/linkedin-sequences";
+import { SENDER_LIMITS_PATCH_CONTRACT } from "@oxygen/shared/contracts/sender-limits";
+import { readContractFlags } from "./contract-flags.js";
+/** "<text> (default N, max M)." for a LinkedIn sender limit flag, from the enforced constants. */
+function linkedInLimitHelp(key, text) {
+    return `${text} (default ${LINKEDIN_SENDER_LIMIT_DEFAULTS[key]}, max ${LINKEDIN_SENDER_LIMIT_MAXIMUMS[key]}).`;
+}
+const LIMIT_FLAG_HELP = {
+    invites_per_day: "Daily LinkedIn connection invites cap",
+    invites_per_week: "Weekly LinkedIn connection invites cap",
+    messages_per_day: "Daily direct messages cap",
+    inmails_per_day: "Daily InMail cap",
+    inmails_per_month: "InMail cap over a rolling 30 days",
+    profile_views_per_day: "Daily profile views cap; the member is notified",
+    profile_lookups_per_day: "Daily invisible profile and company lookups cap",
+    endorsements_per_day: "Daily skill endorsements cap",
+    withdrawals_per_day: "Daily cap on withdrawing sent invitations; reading the sent list uses the read budgets",
+    posts_per_day: "Daily posts to the account's own feed, from every caller; not counted in the total",
+    follows_per_day: "Daily follows cap",
+    likes_per_day: "Daily likes cap",
+    comments_per_day: "Daily comments cap",
+    total_actions_per_day: "Daily cap across all send/action types except posts",
+    relations_reads_per_day: "Daily cap on relations/connections list reads, the scrape ban vector",
+    messages_reads_per_day: "Daily cap on chat and message-history reads",
+    searches_per_day: "Daily cap on LinkedIn search executions",
+    sales_nav_search_results_per_day: "Daily cap on Sales Navigator search result rows fetched",
+    api_reads_per_day: "Daily cap on all other LinkedIn API reads",
+    total_reads_per_day: "Daily cap across all read units",
+    min_action_spacing_seconds: "Minimum seconds between actions",
+    action_spacing_jitter_seconds: "Random jitter seconds added to action spacing",
+    interactive_min_spacing_seconds: "Minimum seconds between human-sent Unibox actions",
+    interactive_spacing_jitter_seconds: "Random jitter seconds added to human-sent Unibox action spacing",
+    interactive_sends_per_hour: "Hourly cap on human-sent Unibox actions",
+    relations_ingest_reads_per_day: "Daily cap on background connection, follower and sent-invite list reads (imports and the withdrawal drip)",
+    api_ingest_reads_per_day: "Daily cap on background engagement, post-metric and profile-viewer reads",
+    messages_ingest_reads_per_day: "Daily cap on background message-history backfill reads",
+    network_backfill_reads_per_day: "Daily network-capture reads while the first walk of connections and followers runs",
+    network_delta_reads_per_day: "Daily network-capture reads once that first walk is done",
+};
+const LIMIT_FLAG_NAMES = {
+    min_action_spacing_seconds: "min-spacing-seconds",
+    action_spacing_jitter_seconds: "spacing-jitter-seconds",
+};
+const WORKING_DAY_NAMES = {
+    mon: 1, monday: 1, tue: 2, tues: 2, tuesday: 2, wed: 3, wednesday: 3, thu: 4, thur: 4, thurs: 4, thursday: 4,
+    fri: 5, friday: 5, sat: 6, saturday: 6, sun: 7, sunday: 7,
+};
+/**
+ * `--working-days` → ISO weekday numbers. Accepts day names or 1-7, comma
+ * separated, and ranges (`mon-fri`, `1-5`). A token it cannot read is sent as
+ * given so the server's invalid_working_hours error names it.
+ */
+export function parseWorkingDaysOption(value) {
+    const day = (token) => {
+        const lower = token.trim().toLowerCase();
+        if (/^[1-7]$/.test(lower))
+            return Number(lower);
+        return WORKING_DAY_NAMES[lower] ?? null;
+    };
+    const days = [];
+    for (const token of value.split(",").map((part) => part.trim()).filter(Boolean)) {
+        const [from, to, ...rest] = token.split("-");
+        const start = from !== undefined ? day(from) : null;
+        const end = to !== undefined ? day(to) : null;
+        if (rest.length === 0 && start !== null && end !== null && start <= end) {
+            for (let current = start; current <= end; current += 1)
+                days.push(current);
+        }
+        else if (to === undefined && start !== null) {
+            days.push(start);
+        }
+        else {
+            days.push(token);
+        }
+    }
+    return days;
+}
+const limitFlags = Object.fromEntries(Object.keys(LIMIT_FLAG_HELP).map((key) => [
+    `limits.${key}`,
+    {
+        ...(LIMIT_FLAG_NAMES[key] ? { flag: LIMIT_FLAG_NAMES[key] } : {}),
+        valueName: "<n>",
+        help: linkedInLimitHelp(key, LIMIT_FLAG_HELP[key]),
+    },
+]));
+export const SENDER_LIMITS_FLAG_OVERLAY = {
+    limits: { flatten: true },
+    ...limitFlags,
+    "working_hours.timezone": {
+        flag: "timezone",
+        valueName: "<tz>",
+        help: "IANA timezone for the working hours and the daily counter reset, e.g. Europe/Berlin. Defaults to the zone of the country chosen at connect.",
+    },
+    "working_hours.days": {
+        flag: "working-days",
+        valueName: "<days>",
+        parse: parseWorkingDaysOption,
+        help: "Days LinkedIn actions may run: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday). A weekday-only window leaves a visible two-day gap every week.",
+    },
+    "working_hours.start": { valueName: "<HH:MM>", help: "Local time working hours start, e.g. 09:00." },
+    "working_hours.end": { valueName: "<HH:MM>", help: "Local time working hours end (exclusive), e.g. 18:00. Must be after the start." },
+    "warmup.enabled": {
+        pair: {
+            on: "warmup-restart",
+            onHelp: "Start (or restart) the warm-up ramp now — gradually raises this account's invite + message caps to full over ~2 weeks.",
+            off: "warmup-disable",
+            offHelp: "Turn off warm-up for this account (treat it as already warm and use its full configured caps).",
+        },
+    },
+    // `--warmup-disable` already sends the disable; no separate --clear flag.
+    "warmup.start_date": {
+        valueName: "<date>",
+        noClear: true,
+        help: "Set the warm-up start date (ISO, e.g. 2026-01-31). A past date credits prior warming and advances the ramp.",
+    },
+    read_warmup: {
+        pair: {
+            on: "read-warmup-restart",
+            onHelp: "Restart the READ warm-up ramp from today, so network capture eases back in from 5 reads a day. Also clears --read-warmup-disable.",
+            off: "read-warmup-disable",
+            offHelp: "Turn off the READ warm-up ramp for this account. Network capture (`oxygen linkedin network setup`) eases a newly armed account in at 5 → 10 → 20 reads a day over two weeks; this runs it at the full read budget immediately. Separate from --warmup-disable, which governs invites and messages.",
+        },
+    },
+    warmup_preset: {
+        valueName: "<preset>",
+        help: "Warm-up ramp curve: conservative (~3 weeks), standard (~2 weeks, default), or fast (~1 week for an aged account).",
+    },
+    randomize_daily_caps: {
+        flag: "randomize-caps",
+        help: "Randomise this account's daily send caps to 80-100% of configured so daily volume varies instead of hitting the same cap every day.",
+        negateHelp: "Turn off randomised daily caps (use the exact configured caps every day).",
+    },
+    weekend_full_volume: {
+        help: "Keep full daily send caps on Saturday and Sunday (by default they run at half).",
+        negateHelp: "Run daily send caps at half on Saturday and Sunday again (the default).",
+    },
+};
+/**
+ * The limits PATCH body for the flags given. A warm-up start date wins over
+ * --warmup-restart/--warmup-disable (the route reads it first anyway), so the
+ * body carries only the one it will act on. Throws when no flag was given.
+ */
+export function buildSenderLimitsBody(options) {
+    const body = readContractFlags(options, SENDER_LIMITS_PATCH_CONTRACT, SENDER_LIMITS_FLAG_OVERLAY);
+    const warmup = body.warmup;
+    if (warmup && warmup.start_date !== undefined)
+        delete warmup.enabled;
+    if (Object.keys(body).length === 0) {
+        throw new OxygenError("invalid_request", "Pass at least one limit flag (e.g. --invites-per-day), a working-hours flag (--timezone, --working-days, --working-hours-start, --working-hours-end), a warm-up flag (--warmup-restart / --warmup-disable / --warmup-start-date), --read-warmup-disable / --read-warmup-restart, --warmup-preset, --randomize-caps, or --weekend-full-volume.", { exitCode: 1 });
+    }
+    return body;
+}

package/dist/ugc-commands.js

@@ -1,5 +1,19 @@
-import { registerUgcCommands as registerCommands, } from "@oxygen/cli-ugc";
+import { registerUgcCommands as registerCommands, UgcUsageError, } from "@oxygen/cli-ugc";
+import { OxygenError } from "@oxygen/shared/cli-result";
 import { requestOxygen } from "./http-client.js";
 export function registerUgcCommands(program, handle) {
-    registerCommands(program, { request: requestOxygen, handle });
+    registerCommands(program, {
+        request: requestOxygen,
+        // A malformed flag is the caller's input, so it reports as invalid_request.
+        handle: (command, options, action) => handle(command, options, async () => {
+            try {
+                return await action();
+            }
+            catch (error) {
+                if (error instanceof UgcUsageError)
+                    throw new OxygenError("invalid_request", error.message, { exitCode: 1 });
+                throw error;
+            }
+        }),
+    });
 }

package/node_modules/@oxygen/cli-ugc/dist/commands.js

@@ -1,4 +1,4 @@
-import { parseField } from "./field-parser.js";
+import { parseField, UgcUsageError } from "./field-parser.js";
 export function registerUgcCommands(program, { request: requestOxygen, handle }) {
     const ugc = program
         .command("ugc")
@@ -1316,10 +1316,10 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
             }
             if (spec.action === "invite_create") {
                 if ((body.email === undefined) === (body.emails === undefined))
-                    throw new Error("Pass exactly one of --email or --emails.");
+                    throw new UgcUsageError("Pass exactly one of --email or --emails.");
                 body.send_email = options.linkOnly !== true;
                 if (options.linkOnly && (body.approved || body.preview_token))
-                    throw new Error("--link-only cannot be combined with --approved or --preview-token.");
+                    throw new UgcUsageError("--link-only cannot be combined with --approved or --preview-token.");
             }
             return requestOxygen("/api/cli/ugc", {
                 method: "POST",

package/node_modules/@oxygen/cli-ugc/dist/field-parser.d.ts

@@ -1,3 +1,7 @@
+/** A malformed flag value: the CLI reports it as `invalid_request`, not `unexpected_error`. */
+export declare class UgcUsageError extends Error {
+    readonly code = "invalid_request";
+}
 export type Field = {
     name: string;
     kind: string;

package/node_modules/@oxygen/cli-ugc/dist/field-parser.js

@@ -1,3 +1,7 @@
+/** A malformed flag value: the CLI reports it as `invalid_request`, not `unexpected_error`. */
+export class UgcUsageError extends Error {
+    code = "invalid_request";
+}
 /** `2/week`, `4/month`, `10/total` or `none` (clears); a count of 1–100. */
 export function parsePostingTarget(value) {
     const text = value.trim().toLowerCase();
@@ -6,7 +10,7 @@ export function parsePostingTarget(value) {
     const match = /^(\d{1,3})\s*\/\s*(week|month|total)$/.exec(text);
     const count = match ? Number(match[1]) : 0;
     if (!match || count < 1 || count > 100)
-        throw new Error("--posting-target must be <n>/month, <n>/total or <n>/week with n from 1 to 100, or none.");
+        throw new UgcUsageError("--posting-target must be <n>/month, <n>/total or <n>/week with n from 1 to 100, or none.");
     return { count, period: match[2] };
 }
 /** A JSON array of emails, or emails separated by commas, semicolons or whitespace. */
@@ -14,15 +18,15 @@ export function parseEmailList(value) {
     const text = value.trim();
     let items;
     if (text.startsWith("[")) {
-        items = JSON.parse(text);
+        items = parseJson(text, "--emails");
         if (!Array.isArray(items) || !items.every((item) => typeof item === "string"))
-            throw new Error("--emails must be a JSON array of strings or a comma-separated list.");
+            throw new UgcUsageError("--emails must be a JSON array of strings or a comma-separated list.");
     }
     else
         items = text.split(/[\s,;]+/);
     const emails = items.map((item) => item.trim()).filter(Boolean);
     if (!emails.length)
-        throw new Error("--emails needs at least one email address.");
+        throw new UgcUsageError("--emails needs at least one email address.");
     return emails;
 }
 export function parseField(value, field) {
@@ -34,18 +38,18 @@ export function parseField(value, field) {
     if (field.kind === "text_list")
         return String(value).split(",").map((item) => item.trim()).filter(Boolean);
     if (field.kind === "array" || field.kind === "object") {
-        const parsed = JSON.parse(String(value));
+        const parsed = parseJson(String(value), field.name);
         if (field.kind === "array"
             ? !Array.isArray(parsed) ||
                 !parsed.every((item) => typeof item === "string")
             : !parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            throw new Error(`${field.name} must be a JSON ${field.kind === "array" ? "array of strings" : "object"}.`);
+            throw new UgcUsageError(`${field.name} must be a JSON ${field.kind === "array" ? "array of strings" : "object"}.`);
         return parsed;
     }
     if (field.kind === "number") {
         const parsed = Number(value);
         if (!Number.isFinite(parsed) || parsed < 0)
-            throw new Error(`${field.name} must be a nonnegative finite number.`);
+            throw new UgcUsageError(`${field.name} must be a nonnegative finite number.`);
         return parsed;
     }
     if (field.kind === "boolean") {
@@ -53,7 +57,15 @@ export function parseField(value, field) {
             return true;
         if (value === false || value === "false")
             return false;
-        throw new Error(`${field.name} must be true or false.`);
+        throw new UgcUsageError(`${field.name} must be true or false.`);
     }
     return value;
 }
+function parseJson(text, name) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UgcUsageError(`${name} must be valid JSON.`);
+    }
+}

package/node_modules/@oxygen/cli-ugc/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { Command } from "commander";
+export { UgcUsageError } from "./field-parser.js";
 /** The CLI owns authentication, transport, output and error presentation. */
 export interface UgcCommandDependencies {
     request: (path: string, options?: {

package/node_modules/@oxygen/cli-ugc/dist/index.js

@@ -1,4 +1,5 @@
 import { registerUgcCommands as registerCommands } from "./commands.js";
+export { UgcUsageError } from "./field-parser.js";
 /** Register the existing UGC command tree without performing requests. */
 export function registerUgcCommands(program, dependencies) {
     registerCommands(program, dependencies);

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -80,10 +80,10 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         execution: "Read billing state or set a hosted budget policy; exact action ceilings remain primitive-owned.",
         posture: "mixed",
         gatewayTools: ["oxygen_billing_balance", "oxygen_billing_usage", "oxygen_billing_estimate", "oxygen_budget_list"],
-        gatewayCommands: ["billing balance", "billing usage", "billing estimate", "budget list"],
+        gatewayCommands: ["billing balance", "billing usage", "billing estimate", "budget list", "billing invoices"],
         skills: ["oxygen-gtm", "oxygen-diagnostics"],
         endpointSections: ["billing", "budget", "limits"],
-        intentTerms: ["billing", "credits", "credit balance", "usage", "spend", "cost", "cost estimate", "monthly cost", "budget", "subscription", "invoice", "cancel plan", "change plan", "upgrade", "downgrade"],
+        intentTerms: ["billing", "credits", "credit balance", "usage", "spend", "cost", "cost estimate", "monthly cost", "budget", "subscription", "invoice", "vat", "vat number", "tax id", "cancel plan", "change plan", "upgrade", "downgrade"],
     },
     {
         id: "support-and-feedback",

package/node_modules/@oxygen/shared/dist/contracts/operations.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One entry per customer operation that edits a resource: the route it calls,
+ * the contract its body satisfies, and the names it carries on the CLI and MCP.
+ * The CLI command, the MCP tool and the route read the same spec, so the three
+ * cannot disagree on which fields exist. Leaf and browser-safe.
+ */
+import type { ContractObject } from "./schema.js";
+export type OperationSpec<C extends ContractObject = ContractObject> = {
+    /** Stable id, `<resource>.<verb>`. */
+    id: string;
+    /** Route template; `{name}` segments are path parameters. */
+    route: string;
+    method: "POST" | "PATCH";
+    /** When set, the contract describes `body[bodyKey]` rather than the whole body. */
+    bodyKey?: string;
+    contract: C;
+    cli: {
+        /** Command words after `oxygen`, e.g. `["senders", "limits", "set"]`. */
+        path: readonly string[];
+        summary: string;
+        /** The positional argument that fills the route's single path parameter. */
+        argument?: {
+            name: string;
+            description: string;
+        };
+    };
+    mcp: {
+        name: string;
+        title: string;
+        description: string;
+        /** The MCP toolset domain (pack) the tool registers under. */
+        pack: string;
+    };
+    mutates: boolean;
+    spends: boolean;
+};
+/** The route with its `{param}` segments filled in, each URL-encoded. */
+export declare function operationPath(spec: Pick<OperationSpec, "route">, params: Readonly<Record<string, string>>): string;
+export declare const OPERATION_SPECS: readonly OperationSpec[];

package/node_modules/@oxygen/shared/dist/contracts/operations.js

@@ -0,0 +1,11 @@
+import { SENDER_LIMITS_SET_OPERATION } from "./sender-limits.js";
+/** The route with its `{param}` segments filled in, each URL-encoded. */
+export function operationPath(spec, params) {
+    return spec.route.replace(/\{(\w+)\}/g, (_match, name) => {
+        const value = params[name];
+        if (value === undefined)
+            throw new Error(`Missing path parameter ${name} for ${spec.route}`);
+        return encodeURIComponent(value);
+    });
+}
+export const OPERATION_SPECS = [SENDER_LIMITS_SET_OPERATION];

package/node_modules/@oxygen/shared/dist/contracts/schema.d.ts

@@ -0,0 +1,186 @@
+/**
+ * One contract per editable resource, in the plain JSON-schema dialect MCP tool
+ * input schemas already use (founder decision 2026-09-28: no zod, no new
+ * dependency). The same object generates the CLI flags
+ * (`packages/cli/src/contract-flags.ts`), the MCP input schema
+ * (`packages/mcp-server/src/tools/contract-tool.ts`) and validates the API
+ * route body (`validateContract`), so a field cannot exist on one surface and
+ * not another.
+ *
+ * Leaf and browser-safe: no imports, no IO.
+ */
+export type StringProperty = {
+    type: "string";
+    description?: string;
+    enum?: readonly string[];
+    minLength?: number;
+    maxLength?: number;
+};
+export type NumberProperty = {
+    type: "number" | "integer";
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    /**
+     * The route clamps a value above `maximum` down to it instead of refusing
+     * it, when `validateContract` runs with `overMax: "clamp"`. Annotation only:
+     * `contractToolProperties` strips it from the MCP schema.
+     */
+    "x-clamp"?: true;
+};
+export type BooleanProperty = {
+    type: "boolean";
+    description?: string;
+};
+export type NullProperty = {
+    type: "null";
+};
+export interface ArrayProperty<I extends JsonProperty = JsonProperty> {
+    type: "array";
+    description?: string;
+    items: I;
+    minItems?: number;
+    maxItems?: number;
+}
+export interface ObjectProperty<P extends Record<string, JsonProperty> = Record<string, JsonProperty>> {
+    type: "object";
+    description?: string;
+    additionalProperties?: boolean | JsonProperty;
+    properties?: P;
+    required?: readonly string[];
+}
+export interface OneOfProperty {
+    oneOf: JsonProperty[];
+    description?: string;
+}
+export type JsonProperty = {
+    $ref: string;
+} | StringProperty | NumberProperty | BooleanProperty | NullProperty | ObjectProperty | ArrayProperty | OneOfProperty;
+/** The top level of a contract: a closed object. */
+export type ContractObject<P extends Record<string, JsonProperty> = Record<string, JsonProperty>, R extends string = string> = {
+    type: "object";
+    description?: string;
+    additionalProperties: false;
+    properties: P;
+    required?: readonly R[];
+};
+type Described = {
+    description?: string;
+};
+type NumberOptions = Described & {
+    minimum?: number;
+    maximum?: number;
+    clamp?: boolean;
+};
+export declare function int(options?: NumberOptions): {
+    type: "integer";
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    "x-clamp"?: true;
+};
+export declare function num(options?: NumberOptions): {
+    type: "number";
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    "x-clamp"?: true;
+};
+export declare function bool(options?: Described): BooleanProperty;
+export declare function str(options?: Described & {
+    minLength?: number;
+    maxLength?: number;
+}): StringProperty;
+export declare function enumOf<const V extends string>(values: readonly V[], options?: Described): {
+    type: "string";
+    enum: readonly V[];
+    description?: string;
+};
+export declare function arr<const I extends JsonProperty>(items: I, options?: Described & {
+    minItems?: number;
+    maxItems?: number;
+}): ArrayProperty<I>;
+export declare function obj<const P extends Record<string, JsonProperty>, const R extends keyof P & string = never>(properties: P, options?: Described & {
+    required?: readonly R[];
+}): ContractObject<P, R>;
+/** `null` is accepted and passed through; it means "clear this field". */
+export declare function nullable<const P extends JsonProperty>(property: P): {
+    oneOf: [P, NullProperty];
+    description?: string;
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type InferObject<M, R> = Simplify<{
+    [K in keyof M as K extends R ? K : never]: Infer<M[K]>;
+} & {
+    [K in keyof M as K extends R ? never : K]?: Infer<M[K]>;
+}>;
+/** The TypeScript type of a value that passes `validateContract`. Fields not in `required` are optional. */
+export type Infer<P> = P extends {
+    oneOf: readonly [infer A, NullProperty];
+} ? Infer<A> | null : P extends {
+    type: "integer" | "number";
+} ? number : P extends {
+    type: "boolean";
+} ? boolean : P extends {
+    type: "string";
+    enum: readonly (infer E)[];
+} ? E : P extends {
+    type: "string";
+} ? string : P extends {
+    type: "array";
+    items: infer I;
+} ? Infer<I>[] : P extends {
+    type: "object";
+    properties: infer M;
+} ? InferObject<M, P extends {
+    required?: readonly (infer R)[];
+} ? R : never> : unknown;
+/** A property's non-null branch, and whether null is allowed. */
+export declare function unwrapNullable(property: JsonProperty): {
+    property: JsonProperty;
+    nullable: boolean;
+};
+export type ContractLeaf = {
+    /** Dotted path, e.g. `limits.invites_per_day`. */
+    key: string;
+    path: readonly string[];
+    /** The leaf's non-null schema. */
+    property: JsonProperty;
+    nullable: boolean;
+};
+/** Every non-object field of a contract, depth first in declaration order. */
+export declare function contractLeafPaths(contract: ContractObject | ObjectProperty, prefix?: readonly string[]): ContractLeaf[];
+export type ContractIssue = {
+    path: string;
+    message: string;
+};
+export type ValidateContractOptions = {
+    /**
+     * `warn`: an unknown key is listed in `unknownKeys` AND kept in `value`, so a
+     * route that still reads it behaves exactly as before the contract existed.
+     * `reject`: an unknown key is an issue.
+     */
+    unknown: "warn" | "reject";
+    /** `clamp` lowers an over-maximum value to the maximum, only where the field carries `x-clamp`. */
+    overMax: "clamp" | "reject";
+};
+export type ContractValidation<T> = {
+    ok: true;
+    value: T;
+    unknownKeys: string[];
+    clamped: string[];
+} | {
+    ok: false;
+    issues: ContractIssue[];
+};
+/**
+ * Check a request body against its contract. Absent (`undefined`) fields are
+ * skipped, `null` passes only where the field is `nullable`, and every issue is
+ * collected rather than stopping at the first. On success `value` is a copy with
+ * clamps applied (see the options for what happens to unknown keys).
+ */
+export declare function validateContract<C extends ContractObject>(contract: C, value: unknown, options: ValidateContractOptions): ContractValidation<Infer<C>>;
+export {};