@tabai/sdk 0.2.0

package/dist/mcp/json-schema.js

@@ -0,0 +1,215 @@
+/**
+ * The JSON Schema subset the MCP tools declare, and a validator for it.
+ *
+ * ## Why this is written here rather than pulled in
+ *
+ * An MCP tool declares its input and output shape as JSON Schema, and a model
+ * reads that declaration to decide what to send. A declaration nothing enforces
+ * is a promise, not a contract: the first tool that accepts an out-of-range
+ * `limit` or emits an amount as a `number` has broken the schema its caller was
+ * reasoning against, and nothing in the process notices. So the four tools in
+ * this package validate every input against the schema they publish, and the
+ * test suite validates every output against the schema they publish (task 16.3).
+ *
+ * The validator is 200 lines rather than a dependency because the schemas here
+ * use ten keywords between them, this package adds no dependency for the MCP
+ * surface, and a validator whose supported keyword set is visible in one file
+ * cannot silently ignore a keyword a schema relies on. {@link validateJsonValue}
+ * fails loudly on a keyword it does not implement instead of passing the value,
+ * which is the property a hand-written validator has to have to be trustworthy.
+ *
+ * ## Everything returns a Result
+ *
+ * Nothing here throws, including on a malformed schema. A schema is authored in
+ * this package, so a bad one is a bug rather than input, but a bug that surfaces
+ * as an `INTERNAL` `Result` at a tool boundary is reported to the model as a
+ * failed call, and a bug that surfaces as a thrown value takes the stdio
+ * transport down with it.
+ *
+ * Requirements: 21.5, 25.1, 25.2
+ */
+import { ok } from "../_shared/index.js";
+import { fail, validationError } from "../errors.js";
+/** Every keyword {@link validateJsonValue} understands. Anything else is a failure, not a pass. */
+export const SUPPORTED_KEYWORDS = [
+    "type",
+    "title",
+    "description",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "enum",
+    "const",
+    "pattern",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "minItems",
+    "maxItems",
+    "default",
+    "examples",
+];
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const typeNameOf = (value) => {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    if (typeof value === "string")
+        return "string";
+    return "object";
+};
+/**
+ * Does a value satisfy one declared type name?
+ *
+ * `integer` accepts only a safe integer, and `number` accepts an integer too,
+ * which is JSON Schema's own rule. A `bigint` matches nothing: an amount in
+ * Asset base units crosses this boundary as a decimal string and never as a
+ * JavaScript number, so a `bigint` that reached a tool payload is a bug in the
+ * mapping and is reported rather than coerced.
+ */
+const matchesType = (value, declared) => {
+    if (typeof value === "bigint")
+        return false;
+    const actual = typeNameOf(value);
+    if (declared === "number")
+        return actual === "number" || actual === "integer";
+    if (declared === "integer")
+        return actual === "integer" && Number.isSafeInteger(value);
+    return actual === declared;
+};
+const declaredTypes = (schema) => {
+    if (schema.type === undefined)
+        return undefined;
+    return typeof schema.type === "string" ? [schema.type] : schema.type;
+};
+/** A dotted path into the value, so a problem names the field a caller has to fix. */
+const child = (path, segment) => (path === "" ? segment : `${path}.${segment}`);
+/** Every unsupported keyword found anywhere in a schema, deepest last. */
+function unsupportedKeywords(schema, path, found) {
+    for (const keyword of Object.keys(schema)) {
+        if (!SUPPORTED_KEYWORDS.includes(keyword)) {
+            found.push(`${path === "" ? "<root>" : path}: ${keyword}`);
+        }
+    }
+    if (schema.properties !== undefined) {
+        for (const [name, property] of Object.entries(schema.properties)) {
+            unsupportedKeywords(property, child(path, name), found);
+        }
+    }
+    if (schema.items !== undefined)
+        unsupportedKeywords(schema.items, `${path}[]`, found);
+}
+function collect(schema, value, path, problems) {
+    const where = path === "" ? "value" : path;
+    const types = declaredTypes(schema);
+    if (types !== undefined && !types.some((declared) => matchesType(value, declared))) {
+        problems.push(`${where}: expected ${types.join(" or ")}, received ${typeNameOf(value)}`);
+        return;
+    }
+    if (schema.const !== undefined && value !== schema.const) {
+        problems.push(`${where}: must equal ${JSON.stringify(schema.const)}`);
+    }
+    if (schema.enum !== undefined && !schema.enum.includes(value)) {
+        problems.push(`${where}: must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`);
+    }
+    if (typeof value === "string") {
+        if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) {
+            problems.push(`${where}: must match ${schema.pattern}`);
+        }
+        if (schema.minLength !== undefined && value.length < schema.minLength) {
+            problems.push(`${where}: must be at least ${schema.minLength} characters`);
+        }
+        if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+            problems.push(`${where}: must be at most ${schema.maxLength} characters`);
+        }
+    }
+    if (typeof value === "number") {
+        if (schema.minimum !== undefined && value < schema.minimum) {
+            problems.push(`${where}: must be at least ${schema.minimum}`);
+        }
+        if (schema.maximum !== undefined && value > schema.maximum) {
+            problems.push(`${where}: must be at most ${schema.maximum}`);
+        }
+    }
+    if (Array.isArray(value)) {
+        if (schema.minItems !== undefined && value.length < schema.minItems) {
+            problems.push(`${where}: must hold at least ${schema.minItems} items`);
+        }
+        if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+            problems.push(`${where}: must hold at most ${schema.maxItems} items`);
+        }
+        if (schema.items !== undefined) {
+            value.forEach((entry, index) => collect(schema.items, entry, `${where}[${index}]`, problems));
+        }
+    }
+    if (isPlainObject(value)) {
+        for (const name of schema.required ?? []) {
+            if (value[name] === undefined)
+                problems.push(`${child(where, name)}: required`);
+        }
+        const properties = schema.properties;
+        if (properties !== undefined) {
+            for (const [name, property] of Object.entries(properties)) {
+                // An absent optional property is absent, not null. `exactOptionalPropertyTypes`
+                // holds the same line in the types, so the two agree.
+                if (value[name] !== undefined)
+                    collect(property, value[name], child(where, name), problems);
+            }
+            if (schema.additionalProperties === false) {
+                for (const name of Object.keys(value)) {
+                    if (!(name in properties))
+                        problems.push(`${child(where, name)}: not a declared property`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Validates a value against a schema and returns it unchanged when it conforms.
+ *
+ * `code` names the failure so a caller can tell an input rejection from an
+ * output-shape bug without parsing the message.
+ */
+export function validateJsonValue(schema, value, label, code = "SCHEMA_MISMATCH") {
+    const unsupported = [];
+    unsupportedKeywords(schema, "", unsupported);
+    if (unsupported.length > 0) {
+        return fail("INTERNAL", "SCHEMA_KEYWORD_UNSUPPORTED", `the ${label} schema uses keywords this validator does not implement, so nothing was checked: ${unsupported.join("; ")}`, { details: { label, unsupported: unsupported.join("; ") } });
+    }
+    const problems = [];
+    collect(schema, value, "", problems);
+    if (problems.length > 0) {
+        return validationError(code, `${label} does not match its declared schema: ${problems.join("; ")}`, {
+            details: { label, problems: problems.join("; ") },
+        });
+    }
+    return ok(value);
+}
+/**
+ * Fills in the declared top-level defaults of an object schema.
+ *
+ * Only the top level, because that is where every default in this package's
+ * schemas sits and a defaulting pass that reached into arrays would be inventing
+ * entries a caller did not send. A non-object value is handed back untouched for
+ * {@link validateJsonValue} to reject with a type problem, which is a better
+ * message than one about defaults.
+ */
+export function applyJsonDefaults(schema, value) {
+    const properties = schema.properties;
+    if (properties === undefined || !isPlainObject(value))
+        return value;
+    const filled = { ...value };
+    for (const [name, property] of Object.entries(properties)) {
+        if (filled[name] === undefined && property.default !== undefined)
+            filled[name] = property.default;
+    }
+    return filled;
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/mcp/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["../../src/mcp/json-schema.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The JSON Schema subset the MCP tools declare, and a validator for it.\n *\n * ## Why this is written here rather than pulled in\n *\n * An MCP tool declares its input and output shape as JSON Schema, and a model\n * reads that declaration to decide what to send. A declaration nothing enforces\n * is a promise, not a contract: the first tool that accepts an out-of-range\n * `limit` or emits an amount as a `number` has broken the schema its caller was\n * reasoning against, and nothing in the process notices. So the four tools in\n * this package validate every input against the schema they publish, and the\n * test suite validates every output against the schema they publish (task 16.3).\n *\n * The validator is 200 lines rather than a dependency because the schemas here\n * use ten keywords between them, this package adds no dependency for the MCP\n * surface, and a validator whose supported keyword set is visible in one file\n * cannot silently ignore a keyword a schema relies on. {@link validateJsonValue}\n * fails loudly on a keyword it does not implement instead of passing the value,\n * which is the property a hand-written validator has to have to be trustworthy.\n *\n * ## Everything returns a Result\n *\n * Nothing here throws, including on a malformed schema. A schema is authored in\n * this package, so a bad one is a bug rather than input, but a bug that surfaces\n * as an `INTERNAL` `Result` at a tool boundary is reported to the model as a\n * failed call, and a bug that surfaces as a thrown value takes the stdio\n * transport down with it.\n *\n * Requirements: 21.5, 25.1, 25.2\n */\n\nimport type { Result } from \"../_shared/index.js\";\nimport { ok } from \"../_shared/index.js\";\n\nimport { fail, validationError } from \"../errors.js\";\n\n/** The seven JSON Schema primitive type names. */\nexport type JsonSchemaType =\n  | \"object\"\n  | \"array\"\n  | \"string\"\n  | \"number\"\n  | \"integer\"\n  | \"boolean\"\n  | \"null\";\n\n/** Every keyword {@link validateJsonValue} understands. Anything else is a failure, not a pass. */\nexport const SUPPORTED_KEYWORDS = [\n  \"type\",\n  \"title\",\n  \"description\",\n  \"properties\",\n  \"required\",\n  \"additionalProperties\",\n  \"items\",\n  \"enum\",\n  \"const\",\n  \"pattern\",\n  \"minLength\",\n  \"maxLength\",\n  \"minimum\",\n  \"maximum\",\n  \"minItems\",\n  \"maxItems\",\n  \"default\",\n  \"examples\",\n] as const;\n\n/**\n * One node of the schema subset.\n *\n * `type` may be an array, which is how a nullable field is declared here:\n * `{ type: [\"string\", \"null\"] }`. There is no `nullable` keyword, because that\n * one is OpenAPI's rather than JSON Schema's and a model reading the tool\n * declaration would be reading a keyword that does not mean what it says.\n */\nexport interface JsonSchema {\n  readonly type?: JsonSchemaType | readonly JsonSchemaType[];\n  readonly title?: string;\n  readonly description?: string;\n  readonly properties?: Readonly<Record<string, JsonSchema>>;\n  readonly required?: readonly string[];\n  readonly additionalProperties?: boolean;\n  readonly items?: JsonSchema;\n  readonly enum?: readonly (string | number | boolean | null)[];\n  readonly const?: string | number | boolean | null;\n  readonly pattern?: string;\n  readonly minLength?: number;\n  readonly maxLength?: number;\n  readonly minimum?: number;\n  readonly maximum?: number;\n  readonly minItems?: number;\n  readonly maxItems?: number;\n  readonly default?: unknown;\n  readonly examples?: readonly unknown[];\n}\n\n/** An object-typed schema, which is what every tool input and output is. */\nexport interface JsonObjectSchema extends JsonSchema {\n  readonly type: \"object\";\n  readonly properties: Readonly<Record<string, JsonSchema>>;\n}\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst typeNameOf = (value: unknown): JsonSchemaType => {\n  if (value === null) return \"null\";\n  if (Array.isArray(value)) return \"array\";\n  if (typeof value === \"boolean\") return \"boolean\";\n  if (typeof value === \"number\") return Number.isInteger(value) ? \"integer\" : \"number\";\n  if (typeof value === \"string\") return \"string\";\n  return \"object\";\n};\n\n/**\n * Does a value satisfy one declared type name?\n *\n * `integer` accepts only a safe integer, and `number` accepts an integer too,\n * which is JSON Schema's own rule. A `bigint` matches nothing: an amount in\n * Asset base units crosses this boundary as a decimal string and never as a\n * JavaScript number, so a `bigint` that reached a tool payload is a bug in the\n * mapping and is reported rather than coerced.\n */\nconst matchesType = (value: unknown, declared: JsonSchemaType): boolean => {\n  if (typeof value === \"bigint\") return false;\n  const actual = typeNameOf(value);\n  if (declared === \"number\") return actual === \"number\" || actual === \"integer\";\n  if (declared === \"integer\") return actual === \"integer\" && Number.isSafeInteger(value);\n  return actual === declared;\n};\n\nconst declaredTypes = (schema: JsonSchema): readonly JsonSchemaType[] | undefined => {\n  if (schema.type === undefined) return undefined;\n  return typeof schema.type === \"string\" ? [schema.type] : schema.type;\n};\n\n/** A dotted path into the value, so a problem names the field a caller has to fix. */\nconst child = (path: string, segment: string): string => (path === \"\" ? segment : `${path}.${segment}`);\n\n/** Every unsupported keyword found anywhere in a schema, deepest last. */\nfunction unsupportedKeywords(schema: JsonSchema, path: string, found: string[]): void {\n  for (const keyword of Object.keys(schema)) {\n    if (!(SUPPORTED_KEYWORDS as readonly string[]).includes(keyword)) {\n      found.push(`${path === \"\" ? \"<root>\" : path}: ${keyword}`);\n    }\n  }\n  if (schema.properties !== undefined) {\n    for (const [name, property] of Object.entries(schema.properties)) {\n      unsupportedKeywords(property, child(path, name), found);\n    }\n  }\n  if (schema.items !== undefined) unsupportedKeywords(schema.items, `${path}[]`, found);\n}\n\nfunction collect(schema: JsonSchema, value: unknown, path: string, problems: string[]): void {\n  const where = path === \"\" ? \"value\" : path;\n\n  const types = declaredTypes(schema);\n  if (types !== undefined && !types.some((declared) => matchesType(value, declared))) {\n    problems.push(`${where}: expected ${types.join(\" or \")}, received ${typeNameOf(value)}`);\n    return;\n  }\n\n  if (schema.const !== undefined && value !== schema.const) {\n    problems.push(`${where}: must equal ${JSON.stringify(schema.const)}`);\n  }\n  if (schema.enum !== undefined && !schema.enum.includes(value as string)) {\n    problems.push(`${where}: must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(\", \")}`);\n  }\n\n  if (typeof value === \"string\") {\n    if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) {\n      problems.push(`${where}: must match ${schema.pattern}`);\n    }\n    if (schema.minLength !== undefined && value.length < schema.minLength) {\n      problems.push(`${where}: must be at least ${schema.minLength} characters`);\n    }\n    if (schema.maxLength !== undefined && value.length > schema.maxLength) {\n      problems.push(`${where}: must be at most ${schema.maxLength} characters`);\n    }\n  }\n\n  if (typeof value === \"number\") {\n    if (schema.minimum !== undefined && value < schema.minimum) {\n      problems.push(`${where}: must be at least ${schema.minimum}`);\n    }\n    if (schema.maximum !== undefined && value > schema.maximum) {\n      problems.push(`${where}: must be at most ${schema.maximum}`);\n    }\n  }\n\n  if (Array.isArray(value)) {\n    if (schema.minItems !== undefined && value.length < schema.minItems) {\n      problems.push(`${where}: must hold at least ${schema.minItems} items`);\n    }\n    if (schema.maxItems !== undefined && value.length > schema.maxItems) {\n      problems.push(`${where}: must hold at most ${schema.maxItems} items`);\n    }\n    if (schema.items !== undefined) {\n      value.forEach((entry, index) => collect(schema.items!, entry, `${where}[${index}]`, problems));\n    }\n  }\n\n  if (isPlainObject(value)) {\n    for (const name of schema.required ?? []) {\n      if (value[name] === undefined) problems.push(`${child(where, name)}: required`);\n    }\n    const properties = schema.properties;\n    if (properties !== undefined) {\n      for (const [name, property] of Object.entries(properties)) {\n        // An absent optional property is absent, not null. `exactOptionalPropertyTypes`\n        // holds the same line in the types, so the two agree.\n        if (value[name] !== undefined) collect(property, value[name], child(where, name), problems);\n      }\n      if (schema.additionalProperties === false) {\n        for (const name of Object.keys(value)) {\n          if (!(name in properties)) problems.push(`${child(where, name)}: not a declared property`);\n        }\n      }\n    }\n  }\n}\n\n/**\n * Validates a value against a schema and returns it unchanged when it conforms.\n *\n * `code` names the failure so a caller can tell an input rejection from an\n * output-shape bug without parsing the message.\n */\nexport function validateJsonValue<T>(\n  schema: JsonSchema,\n  value: unknown,\n  label: string,\n  code = \"SCHEMA_MISMATCH\",\n): Result<T> {\n  const unsupported: string[] = [];\n  unsupportedKeywords(schema, \"\", unsupported);\n  if (unsupported.length > 0) {\n    return fail(\n      \"INTERNAL\",\n      \"SCHEMA_KEYWORD_UNSUPPORTED\",\n      `the ${label} schema uses keywords this validator does not implement, so nothing was checked: ${unsupported.join(\"; \")}`,\n      { details: { label, unsupported: unsupported.join(\"; \") } },\n    );\n  }\n\n  const problems: string[] = [];\n  collect(schema, value, \"\", problems);\n  if (problems.length > 0) {\n    return validationError(code, `${label} does not match its declared schema: ${problems.join(\"; \")}`, {\n      details: { label, problems: problems.join(\"; \") },\n    });\n  }\n  return ok(value as T);\n}\n\n/**\n * Fills in the declared top-level defaults of an object schema.\n *\n * Only the top level, because that is where every default in this package's\n * schemas sits and a defaulting pass that reached into arrays would be inventing\n * entries a caller did not send. A non-object value is handed back untouched for\n * {@link validateJsonValue} to reject with a type problem, which is a better\n * message than one about defaults.\n */\nexport function applyJsonDefaults(schema: JsonSchema, value: unknown): unknown {\n  const properties = schema.properties;\n  if (properties === undefined || !isPlainObject(value)) return value;\n  const filled: Record<string, unknown> = { ...value };\n  for (const [name, property] of Object.entries(properties)) {\n    if (filled[name] === undefined && property.default !== undefined) filled[name] = property.default;\n  }\n  return filled;\n}\n"]}

package/dist/mcp/json.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Defensive readers for JSON this package did not produce.
+ *
+ * The registry read API is a separate process on a separate release cadence, and
+ * a Service endpoint is a third party's code. Neither is a compile-time
+ * dependency of this package and neither should be: an interface mirrored here
+ * would be a copy that goes stale silently, and the failure it produces is a
+ * `TypeError` deep inside a tool handler rather than a message naming the field.
+ *
+ * So every field is read through one of these, each of which answers a value or
+ * a stated fallback and never throws. A field that went missing upstream becomes
+ * a null in the tool's output, which the schema declares as possible, instead of
+ * taking the call down.
+ *
+ * Requirements: 25.1, 25.2
+ */
+/** A JSON object, as far as anything here is concerned. */
+export type JsonRecord = Readonly<Record<string, unknown>>;
+export declare const isRecord: (value: unknown) => value is JsonRecord;
+/** The value at `key`, when the container is an object. */
+export declare const field: (value: unknown, key: string) => unknown;
+/** The value at a dotted path, stopping at the first non-object. */
+export declare const path: (value: unknown, ...keys: readonly string[]) => unknown;
+export declare const asRecord: (value: unknown) => JsonRecord;
+export declare const asArray: (value: unknown) => readonly unknown[];
+export declare const asString: (value: unknown, fallback: string) => string;
+export declare const asStringOrNull: (value: unknown) => string | null;
+/** A finite number, or the fallback. `NaN` and an infinity are not numbers a schema accepts. */
+export declare const asNumber: (value: unknown, fallback: number) => number;
+export declare const asBoolean: (value: unknown, fallback: boolean) => boolean;
+/**
+ * A `uint256` as the decimal string every amount crosses this boundary as.
+ *
+ * A JavaScript number is accepted only when it is a safe integer, because a
+ * larger one has already lost digits by the time it arrives and stringifying it
+ * would launder a rounded amount into something that looks exact.
+ */
+export declare const asDigits: (value: unknown, fallback: string) => string;
+/** The same, but absence stays absence. */
+export declare const asDigitsOrNull: (value: unknown) => string | null;
+/** Seconds since the epoch, as an ISO instant. Null for anything unreadable. */
+export declare const secondsToIso: (value: unknown) => string | null;
+//# sourceMappingURL=json.d.ts.map

package/dist/mcp/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/mcp/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3D,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,UACmB,CAAC;AAEvE,2DAA2D;AAC3D,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,EAAE,KAAK,MAAM,KAAG,OAAqD,CAAC;AAE1G,oEAAoE;AACpE,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,EAAE,GAAG,MAAM,SAAS,MAAM,EAAE,KAAG,OACE,CAAC;AAErE,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,UAA4C,CAAC;AAEvF,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,KAAG,SAAS,OAAO,EAAyC,CAAC;AAEnG,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MACd,CAAC;AAE/C,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAAkD,CAAC;AAE5G,gGAAgG;AAChG,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MAO3D,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,EAAE,UAAU,OAAO,KAAG,OACf,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MAK3D,CAAC;AAEF,2CAA2C;AAC3C,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAGxD,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAMtD,CAAC"}

package/dist/mcp/json.js

@@ -0,0 +1,69 @@
+/**
+ * Defensive readers for JSON this package did not produce.
+ *
+ * The registry read API is a separate process on a separate release cadence, and
+ * a Service endpoint is a third party's code. Neither is a compile-time
+ * dependency of this package and neither should be: an interface mirrored here
+ * would be a copy that goes stale silently, and the failure it produces is a
+ * `TypeError` deep inside a tool handler rather than a message naming the field.
+ *
+ * So every field is read through one of these, each of which answers a value or
+ * a stated fallback and never throws. A field that went missing upstream becomes
+ * a null in the tool's output, which the schema declares as possible, instead of
+ * taking the call down.
+ *
+ * Requirements: 25.1, 25.2
+ */
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The value at `key`, when the container is an object. */
+export const field = (value, key) => (isRecord(value) ? value[key] : undefined);
+/** The value at a dotted path, stopping at the first non-object. */
+export const path = (value, ...keys) => keys.reduce((current, key) => field(current, key), value);
+export const asRecord = (value) => (isRecord(value) ? value : {});
+export const asArray = (value) => (Array.isArray(value) ? value : []);
+export const asString = (value, fallback) => typeof value === "string" ? value : fallback;
+export const asStringOrNull = (value) => (typeof value === "string" ? value : null);
+/** A finite number, or the fallback. `NaN` and an infinity are not numbers a schema accepts. */
+export const asNumber = (value, fallback) => {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && /^-?[0-9]+$/.test(value)) {
+        const parsed = Number(value);
+        if (Number.isSafeInteger(parsed))
+            return parsed;
+    }
+    return fallback;
+};
+export const asBoolean = (value, fallback) => typeof value === "boolean" ? value : fallback;
+/**
+ * A `uint256` as the decimal string every amount crosses this boundary as.
+ *
+ * A JavaScript number is accepted only when it is a safe integer, because a
+ * larger one has already lost digits by the time it arrives and stringifying it
+ * would launder a rounded amount into something that looks exact.
+ */
+export const asDigits = (value, fallback) => {
+    if (typeof value === "string" && /^[0-9]{1,39}$/.test(value))
+        return value;
+    if (typeof value === "bigint" && value >= 0n)
+        return value.toString();
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+        return String(value);
+    return fallback;
+};
+/** The same, but absence stays absence. */
+export const asDigitsOrNull = (value) => {
+    const digits = asDigits(value, "");
+    return digits === "" ? null : digits;
+};
+/** Seconds since the epoch, as an ISO instant. Null for anything unreadable. */
+export const secondsToIso = (value) => {
+    const seconds = asDigits(value, "");
+    if (seconds === "")
+        return null;
+    const millis = Number(seconds) * 1000;
+    if (!Number.isFinite(millis) || millis <= 0)
+        return null;
+    return new Date(millis).toISOString();
+};
+//# sourceMappingURL=json.js.map

package/dist/mcp/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/mcp/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAuB,EAAE,CAC9D,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAc,EAAE,GAAW,EAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAE1G,oEAAoE;AACpE,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,GAAG,IAAuB,EAAW,EAAE,CAC1E,IAAI,CAAC,MAAM,CAAU,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;AAErE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAEvF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAc,EAAsB,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAEnG,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAE,QAAgB,EAAU,EAAE,CACnE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAAiB,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAE5G,gGAAgG;AAChG,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAE,QAAgB,EAAU,EAAE;IACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;IAClD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAE,QAAiB,EAAW,EAAE,CACtE,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAE,QAAgB,EAAU,EAAE;IACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACjG,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF,2CAA2C;AAC3C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAAiB,EAAE;IAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AACvC,CAAC,CAAC;AAEF,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAc,EAAiB,EAAE;IAC5D,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;AACxC,CAAC,CAAC","sourcesContent":["/**\n * Defensive readers for JSON this package did not produce.\n *\n * The registry read API is a separate process on a separate release cadence, and\n * a Service endpoint is a third party's code. Neither is a compile-time\n * dependency of this package and neither should be: an interface mirrored here\n * would be a copy that goes stale silently, and the failure it produces is a\n * `TypeError` deep inside a tool handler rather than a message naming the field.\n *\n * So every field is read through one of these, each of which answers a value or\n * a stated fallback and never throws. A field that went missing upstream becomes\n * a null in the tool's output, which the schema declares as possible, instead of\n * taking the call down.\n *\n * Requirements: 25.1, 25.2\n */\n\n/** A JSON object, as far as anything here is concerned. */\nexport type JsonRecord = Readonly<Record<string, unknown>>;\n\nexport const isRecord = (value: unknown): value is JsonRecord =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\n/** The value at `key`, when the container is an object. */\nexport const field = (value: unknown, key: string): unknown => (isRecord(value) ? value[key] : undefined);\n\n/** The value at a dotted path, stopping at the first non-object. */\nexport const path = (value: unknown, ...keys: readonly string[]): unknown =>\n  keys.reduce<unknown>((current, key) => field(current, key), value);\n\nexport const asRecord = (value: unknown): JsonRecord => (isRecord(value) ? value : {});\n\nexport const asArray = (value: unknown): readonly unknown[] => (Array.isArray(value) ? value : []);\n\nexport const asString = (value: unknown, fallback: string): string =>\n  typeof value === \"string\" ? value : fallback;\n\nexport const asStringOrNull = (value: unknown): string | null => (typeof value === \"string\" ? value : null);\n\n/** A finite number, or the fallback. `NaN` and an infinity are not numbers a schema accepts. */\nexport const asNumber = (value: unknown, fallback: number): number => {\n  if (typeof value === \"number\" && Number.isFinite(value)) return value;\n  if (typeof value === \"string\" && /^-?[0-9]+$/.test(value)) {\n    const parsed = Number(value);\n    if (Number.isSafeInteger(parsed)) return parsed;\n  }\n  return fallback;\n};\n\nexport const asBoolean = (value: unknown, fallback: boolean): boolean =>\n  typeof value === \"boolean\" ? value : fallback;\n\n/**\n * A `uint256` as the decimal string every amount crosses this boundary as.\n *\n * A JavaScript number is accepted only when it is a safe integer, because a\n * larger one has already lost digits by the time it arrives and stringifying it\n * would launder a rounded amount into something that looks exact.\n */\nexport const asDigits = (value: unknown, fallback: string): string => {\n  if (typeof value === \"string\" && /^[0-9]{1,39}$/.test(value)) return value;\n  if (typeof value === \"bigint\" && value >= 0n) return value.toString();\n  if (typeof value === \"number\" && Number.isSafeInteger(value) && value >= 0) return String(value);\n  return fallback;\n};\n\n/** The same, but absence stays absence. */\nexport const asDigitsOrNull = (value: unknown): string | null => {\n  const digits = asDigits(value, \"\");\n  return digits === \"\" ? null : digits;\n};\n\n/** Seconds since the epoch, as an ISO instant. Null for anything unreadable. */\nexport const secondsToIso = (value: unknown): string | null => {\n  const seconds = asDigits(value, \"\");\n  if (seconds === \"\") return null;\n  const millis = Number(seconds) * 1000;\n  if (!Number.isFinite(millis) || millis <= 0) return null;\n  return new Date(millis).toISOString();\n};\n"]}

package/dist/mcp/registry-client.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The keyless read client for the Tab registry read API.
+ *
+ * `tab_discover` and `tab_status` answer questions about chain state -- which
+ * Services are registered, what each tool costs, what an Agent owes -- and every
+ * one of those answers is a public fact. Nothing here signs, nothing here
+ * authenticates, and nothing here writes. That is why `tab connect` can wire a
+ * client up without ever touching a key, and why `tab doctor` can check a
+ * deployment end to end from a laptop that holds none.
+ *
+ * ## Why the read API rather than the chain
+ *
+ * A Credit Limit is not a storage slot. It is `LimitLib` recomputed over an
+ * Agent's committed Settlement history and the Bond ledger, cross-checked
+ * against `TabBook.creditLimit` at the same block before it is served. A Bond
+ * figure is a sum of `Bond`'s own events, checked against `Bond.ledgerOf`. An
+ * MCP server that read the chain directly would have to restate both, and a
+ * second restatement that drifts from the first is worse than one source of
+ * truth: it would put two different Credit Limits in front of the same model.
+ * So the figures come from the one process that already computes and checks
+ * them, and this client's whole job is to fetch and not to interpret.
+ *
+ * The consequence is stated rather than hidden: with no registry read API
+ * configured, `tab_discover` and `tab_status` fail with `UPSTREAM` and say so.
+ * `tab_call` does not go through here at all -- it reads its figures off the
+ * Service's own charge headers -- so a model can still call and be metered while
+ * the index is down.
+ *
+ * ## Structural web types
+ *
+ * This package compiles against ES2023 with no DOM types, so `fetch`, its
+ * response, and the abort signal are described by the shapes this module
+ * touches, exactly as `client-402.ts` does. A host `fetch`, `undici`, and a test
+ * closure all satisfy {@link RegistryFetch} without any of them being named.
+ *
+ * Requirements: 24.1, 24.4, 25.1, 25.3
+ */
+import type { Result } from "../_shared/index.js";
+import { type Logger } from "../logger.js";
+/** The two fields of a response this client reads. */
+export interface RegistryResponse {
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+/** The `fetch` this client calls. A host `fetch` satisfies it as it stands. */
+export type RegistryFetch = (url: string, init: Readonly<Record<string, unknown>>) => Promise<RegistryResponse>;
+export interface RegistryReadClientOptions {
+    /** Absolute base URL of the read API, with or without a trailing slash. */
+    readonly baseUrl: string;
+    readonly fetchImpl?: RegistryFetch;
+    /** How long one read may take. Defaults to 10 seconds. */
+    readonly timeoutMs?: number;
+    readonly logger?: Logger;
+}
+/** Every read `tab_discover` and `tab_status` make, and nothing else. */
+export interface RegistryReadClient {
+    /** The base URL reads go to, normalised, so an error message can name it. */
+    readonly baseUrl: string;
+    /** `GET /healthz`, which is what `doctor` asks before it trusts anything else. */
+    health(): Promise<Result<unknown>>;
+    /** A page of registered Services, hydrated with prices, collections and Bond. */
+    services(limit: number): Promise<Result<unknown>>;
+    /** One Service, or `NOT_FOUND` when nothing ever registered under the id. */
+    service(serviceId: string): Promise<Result<unknown>>;
+    /** One Agent's credit picture per Asset. An address with no history is a 200 with empty arrays. */
+    agent(address: string): Promise<Result<unknown>>;
+    /** Settlements, newest first, filtered by Agent and optionally by Asset. */
+    settlements(query: SettlementQuery): Promise<Result<unknown>>;
+    /** One Settlement with the transaction that paid it, named by its `settlementId`. */
+    settlement(settlementId: string): Promise<Result<unknown>>;
+}
+export interface SettlementQuery {
+    readonly agent: string;
+    /** The token address alone, which is how the index keys an Asset. */
+    readonly asset?: string;
+    readonly limit: number;
+}
+/** Drops a trailing slash so path joining never produces a double one. */
+export declare const normaliseBaseUrl: (baseUrl: string) => string;
+/**
+ * Builds the client.
+ *
+ * Construction is total, like every other factory in this package: an unusable
+ * base URL is reported by the first read, which is the only place a caller can
+ * act on it.
+ */
+export declare function createRegistryReadClient(options: RegistryReadClientOptions): RegistryReadClient;
+//# sourceMappingURL=registry-client.d.ts.map

package/dist/mcp/registry-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-client.d.ts","sourceRoot":"","sources":["../../src/mcp/registry-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAY,MAAM,eAAe,CAAC;AAItD,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAG1D,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEhH,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,6EAA6E;IAC7E,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,mGAAmG;IACnG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACjD,4EAA4E;IAC5E,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,qFAAqF;IACrF,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MAAqC,CAAC;AAsDzF;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAsF/F"}

package/dist/mcp/registry-client.js

@@ -0,0 +1,158 @@
+/**
+ * The keyless read client for the Tab registry read API.
+ *
+ * `tab_discover` and `tab_status` answer questions about chain state -- which
+ * Services are registered, what each tool costs, what an Agent owes -- and every
+ * one of those answers is a public fact. Nothing here signs, nothing here
+ * authenticates, and nothing here writes. That is why `tab connect` can wire a
+ * client up without ever touching a key, and why `tab doctor` can check a
+ * deployment end to end from a laptop that holds none.
+ *
+ * ## Why the read API rather than the chain
+ *
+ * A Credit Limit is not a storage slot. It is `LimitLib` recomputed over an
+ * Agent's committed Settlement history and the Bond ledger, cross-checked
+ * against `TabBook.creditLimit` at the same block before it is served. A Bond
+ * figure is a sum of `Bond`'s own events, checked against `Bond.ledgerOf`. An
+ * MCP server that read the chain directly would have to restate both, and a
+ * second restatement that drifts from the first is worse than one source of
+ * truth: it would put two different Credit Limits in front of the same model.
+ * So the figures come from the one process that already computes and checks
+ * them, and this client's whole job is to fetch and not to interpret.
+ *
+ * The consequence is stated rather than hidden: with no registry read API
+ * configured, `tab_discover` and `tab_status` fail with `UPSTREAM` and say so.
+ * `tab_call` does not go through here at all -- it reads its figures off the
+ * Service's own charge headers -- so a model can still call and be metered while
+ * the index is down.
+ *
+ * ## Structural web types
+ *
+ * This package compiles against ES2023 with no DOM types, so `fetch`, its
+ * response, and the abort signal are described by the shapes this module
+ * touches, exactly as `client-402.ts` does. A host `fetch`, `undici`, and a test
+ * closure all satisfy {@link RegistryFetch} without any of them being named.
+ *
+ * Requirements: 24.1, 24.4, 25.1, 25.3
+ */
+import { ok } from "../_shared/index.js";
+import { tabError, upstreamError, validationError } from "../errors.js";
+import { defaultLogger } from "../logger.js";
+import { asString, isRecord } from "./json.js";
+/** Drops a trailing slash so path joining never produces a double one. */
+export const normaliseBaseUrl = (baseUrl) => baseUrl.replace(/\/+$/, "");
+/**
+ * An abort signal that fires after `ms`, when the host has one.
+ *
+ * Described structurally rather than typed as `AbortSignal`, for the same reason
+ * `fetch` is: no DOM types here. A host without `AbortSignal.timeout` gets no
+ * signal and the read runs to whatever timeout its transport imposes, which is
+ * worse than a bounded read but better than a failure to construct one.
+ */
+const timeoutSignal = (ms) => {
+    const ctor = globalThis.AbortSignal;
+    return typeof ctor?.timeout === "function" ? ctor.timeout(ms) : undefined;
+};
+const hostFetch = () => {
+    const candidate = globalThis.fetch;
+    return typeof candidate === "function" ? candidate : undefined;
+};
+const CATEGORIES = ["VALIDATION", "NOT_FOUND", "CONFLICT", "UPSTREAM", "CHAIN", "TIMEOUT", "INTERNAL"];
+/**
+ * Reads the read API's own error body back into a `TabError`.
+ *
+ * Every route there fails with `{ error: { category, code, message } }` in this
+ * package's own vocabulary, so a 404 for an unregistered serviceId arrives here
+ * as `NOT_FOUND` / `SERVICE_NOT_REGISTERED` and reaches the model unchanged.
+ * Rewriting it as a generic upstream failure would throw away the one part a
+ * caller can act on.
+ */
+function upstreamFailure(url, status, body) {
+    const error = isRecord(body) ? body["error"] : undefined;
+    if (isRecord(error)) {
+        const category = asString(error["category"], "");
+        if (CATEGORIES.includes(category)) {
+            return {
+                ok: false,
+                error: tabError(category, asString(error["code"], "REGISTRY_READ_FAILED"), asString(error["message"], `the registry read API answered ${status} for ${url}`), { details: { url, status } }),
+            };
+        }
+    }
+    return upstreamError("REGISTRY_READ_FAILED", `the registry read API answered ${status} for ${url}`, { retryable: status >= 500, details: { url, status } });
+}
+/**
+ * Builds the client.
+ *
+ * Construction is total, like every other factory in this package: an unusable
+ * base URL is reported by the first read, which is the only place a caller can
+ * act on it.
+ */
+export function createRegistryReadClient(options) {
+    const baseUrl = normaliseBaseUrl(options.baseUrl);
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const logger = options.logger ?? defaultLogger;
+    const get = async (pathname, query = {}) => {
+        if (!/^https?:\/\/[^\s]+$/.test(baseUrl)) {
+            return validationError("REGISTRY_URL_INVALID", `the registry read API base URL must be an absolute http or https URL, received \`${options.baseUrl}\``, { details: { baseUrl: options.baseUrl } });
+        }
+        const send = options.fetchImpl ?? hostFetch();
+        if (send === undefined) {
+            return upstreamError("FETCH_UNAVAILABLE", "this host has no global fetch; supply fetchImpl, or run on Node 20.10 or later");
+        }
+        const search = Object.entries(query)
+            .filter((entry) => entry[1] !== undefined)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+            .join("&");
+        const url = `${baseUrl}${pathname}${search === "" ? "" : `?${search}`}`;
+        const signal = timeoutSignal(timeoutMs);
+        let response;
+        try {
+            response = await send(url, {
+                method: "GET",
+                headers: { accept: "application/json" },
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            // A transport failure and a timeout are the same shape here and different
+            // things to a caller, so the category splits on the abort name.
+            const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+            logger.warn("registry read failed", { url, reason });
+            // Both are UPSTREAM: the category vocabulary has no timeout of its own, and a
+            // read API that answered nothing in time is an upstream failure whichever way
+            // it failed. The code is what tells the two apart, and both are retryable.
+            return timedOut
+                ? upstreamError("REGISTRY_READ_TIMEOUT", `the registry read API at ${url} did not answer within ${timeoutMs}ms`, { retryable: true, details: { url, timeoutMs } })
+                : upstreamError("REGISTRY_UNREACHABLE", `the registry read API at ${url} could not be reached: ${reason}`, {
+                    retryable: true,
+                    details: { url },
+                });
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return upstreamError("REGISTRY_BODY_UNREADABLE", `the registry read API at ${url} answered ${response.status} with a body that is not JSON: ${reason}`, { details: { url, status: response.status } });
+        }
+        if (response.status < 200 || response.status >= 300)
+            return upstreamFailure(url, response.status, body);
+        return ok(body);
+    };
+    return {
+        baseUrl,
+        health: () => get("/healthz"),
+        services: (limit) => get("/services", { limit: String(limit) }),
+        service: (serviceId) => get(`/services/${encodeURIComponent(serviceId.toLowerCase())}`),
+        agent: (address) => get(`/agents/${encodeURIComponent(address.toLowerCase())}`),
+        settlements: (query) => get("/settlements", {
+            agent: query.agent.toLowerCase(),
+            asset: query.asset?.toLowerCase(),
+            limit: String(query.limit),
+        }),
+        settlement: (settlementId) => get(`/settlements/${encodeURIComponent(settlementId.toLowerCase())}`),
+    };
+}
+//# sourceMappingURL=registry-client.js.map