@zackbart/connecta 0.34.1 → 0.36.0

package/dist/providers/_shared/rest/kit.js

@@ -0,0 +1,146 @@
+// Shared REST call shapes, pinned-schema conversion and indexed vendor declarations.
+import { Effect, Schema } from "effect";
+import { ConnectorCallError } from "../../../errors.js";
+import { Refusal } from "../../../http/errors.js";
+import { Integer, isMinChars, isMaxChars } from "../../../http/json-schema.js";
+import { vendor as declareVendor, get, head, post, put, patch, del, } from "../../../http/vendor.js";
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function invalid(message) {
+    throw new ConnectorCallError("invalid_args", message);
+}
+export function checked(run) {
+    return Effect.try({ try: run, catch: (error) => error }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)));
+}
+/** Index matches retain encoded segments; HttpApiClient uses encodeURIComponent. */
+export function typedParams(params) {
+    return Object.fromEntries(Object.entries(params).map(([name, encoded]) => {
+        let value;
+        try {
+            value = decodeURIComponent(encoded);
+        }
+        catch {
+            return invalid(`Indexed path parameter ${name} is not valid URI encoding.`);
+        }
+        if (encodeURIComponent(value) !== encoded)
+            invalid(`Indexed path parameter ${name} does not round-trip through the typed path encoder.`);
+        return [name, value];
+    }));
+}
+/** Convert the JSON forms published by pinned indexes. No vendor encoders run here. */
+export function schema(node) {
+    const n = node;
+    let out;
+    const types = n["type"];
+    if (n["truncated"] === true)
+        out = Schema.Unknown;
+    else if (Array.isArray(n["enum"]))
+        out = n["enum"].length === 1 ? Schema.Literal(n["enum"][0]) : Schema.Literals(n["enum"]);
+    else if (Array.isArray(n["anyOf"]))
+        out = Schema.Union(n["anyOf"].map((v) => schema(v)));
+    else if (Array.isArray(types))
+        out = Schema.Union(types.map((type) => schema({ ...n, type, description: undefined })));
+    else if (types === "object" || isRecord(n["properties"])) {
+        const required = n["required"];
+        const fields = Object.fromEntries(Object.entries((n["properties"] ?? {})).map(([key, value]) => {
+            const part = schema(value);
+            const annotated = part.ast._tag === "Unknown" && isRecord(value) && typeof value["description"] === "string"
+                ? part.pipe(Schema.annotateKey({ description: value["description"] }))
+                : part;
+            return [key, required?.includes(key) ? annotated : Schema.optionalKey(annotated)];
+        }));
+        out =
+            n["properties"] && n["additionalProperties"] !== true
+                ? Schema.Struct(fields)
+                : Schema.StructWithRest(Schema.Struct(fields), [
+                    Schema.Record(Schema.String, isRecord(n["additionalProperties"]) ? schema(n["additionalProperties"]) : Schema.Unknown),
+                ]);
+    }
+    else if (types === "array") {
+        let array = Schema.Array(schema((n["items"] ?? {})));
+        if (typeof n["minItems"] === "number")
+            array = array.check(Schema.isMinLength(n["minItems"]));
+        if (typeof n["maxItems"] === "number")
+            array = array.check(Schema.isMaxLength(n["maxItems"]));
+        if (n["uniqueItems"] === true)
+            array = array.check(Schema.isUnique());
+        out = array;
+    }
+    else if (types === "string") {
+        let string = Schema.String;
+        if (typeof n["minLength"] === "number")
+            string = string.check(isMinChars(n["minLength"]));
+        if (typeof n["maxLength"] === "number")
+            string = string.check(isMaxChars(n["maxLength"]));
+        out = string;
+    }
+    else if (types === "integer" || types === "number") {
+        let number = types === "integer" ? Integer : Schema.Finite;
+        if (typeof n["minimum"] === "number")
+            number = number.check(Schema.isGreaterThanOrEqualTo(n["minimum"]));
+        if (typeof n["maximum"] === "number")
+            number = number.check(Schema.isLessThanOrEqualTo(n["maximum"]));
+        out = number;
+    }
+    else
+        out = types === "boolean" ? Schema.Boolean : types === "null" ? Schema.Null : Schema.Unknown;
+    if (n["nullable"] === true)
+        out = Schema.Union([out, Schema.Null]);
+    if (n["writeOnly"] === true)
+        out = out.annotate({ writeOnly: true });
+    return typeof n["description"] === "string" ? out.annotate({ description: n["description"] }) : out;
+}
+/** Declare each indexed operation once; request schema subtrees stay suspended until manifest/client use. */
+export function indexedVendor(name, index, named = []) {
+    for (const op of index.ops) {
+        if ([...op.path.matchAll(/\{([^}]*)\}/g)].some((match) => !/^[A-Za-z0-9_-]+$/.test(match[1])) ||
+            /[{}]/.test(op.path.replace(/\{[^}]*\}/g, "")))
+            throw new Error(`Indexed operation ${op.method} ${op.path} has an unsupported path parameter name.`);
+    }
+    const constructors = { GET: get, HEAD: head, POST: post, PUT: put, PATCH: patch, DELETE: del };
+    const overrides = new Map(named.map((op) => {
+        const declared = op;
+        return [`${declared.method} ${declared.path.replace(/:([^/]+)/g, "{$1}")}`, op];
+    }));
+    for (const key of overrides.keys())
+        if (!index.ops.some((op) => `${op.method} ${op.path}` === key))
+            throw new Error(`Named operation ${key} is absent from the pinned index.`);
+    const cache = new Map();
+    const cached = (node) => {
+        const key = JSON.stringify(node);
+        let found = cache.get(key);
+        if (!found) {
+            found = schema(node);
+            cache.set(key, found);
+        }
+        return found;
+    };
+    const build = () => {
+        const endpoints = index.ops.map((op) => overrides.get(`${op.method} ${op.path}`) ??
+            constructors[op.method]("indexed" + op.row, 
+            // These declarations feed only the manifest. The live client uses `named` below.
+            op.path, {
+                // Parameter names come directly from the vendor template; hatch validation still uses index.check.
+                params: Schema.Struct(Object.fromEntries([...op.path.matchAll(/\{([^}]+)\}/g)].map((match) => [match[1], Schema.String]))),
+                query: Schema.suspend(() => {
+                    const parameters = index.contract(op).parameters.filter((p) => p.in === "query");
+                    return Schema.Struct(Object.fromEntries(parameters.map((p) => [p.name, p.required ? cached(p.schema) : Schema.optionalKey(cached(p.schema))])));
+                }),
+                ...(op.method === "GET" || op.method === "HEAD"
+                    ? {}
+                    : { payload: Schema.suspend(() => cached(index.contract(op).body?.schema ?? {})) }),
+                success: Schema.Unknown,
+            }));
+        if (!endpoints.length)
+            throw new Error("An indexed vendor needs operations.");
+        return declareVendor(name, endpoints[0], ...endpoints.slice(1)).api;
+    };
+    if (!named.length)
+        throw new Error("An indexed vendor declares at least its typed credential probe.");
+    let built;
+    return {
+        ...declareVendor(name, named[0], ...named.slice(1)),
+        indexed: { operations: index.ops.map((op) => `${op.method} ${op.path}`).sort(), api: () => (built ??= build()) },
+    };
+}

package/dist/providers/_shared/rest/operation-index.js

@@ -1,3 +1,5 @@
+import { canonicalJson } from "../../../canonical-json.js";
+import { parseIndexDetails } from "./compact-index.js";
 // The pinned operation index a REST connector validates against before it
 // sends anything. `scripts/generate-openapi.mjs` compiles a vendor's OpenAPI
 // document into `OpenApiData` (search rows plus request-side details as one
@@ -114,16 +116,26 @@ export class OperationIndex {
     #vendor;
     #segments;
     #slashParams;
+    #uriTemplates;
+    get pathMatching() {
+        return this.#uriTemplates ? "uri-template" : "segments";
+    }
     #details;
+    #fields;
+    #requestSchemas;
     #words;
     /**
      * `vendor` is the tool-name prefix; `title` the display name in refusals.
      * `slashParams` names path parameters whose values may carry an encoded
      * "/" (`%2F`), such as an object key, and only as the path's last segment.
+     * `pathMatching: "uri-template"` opts into decoded literals and parameters
+     * embedded in a segment, such as Google's `{id}:batchUpdate`. The default
+     * retains exact literal segments and whole-segment parameters.
      */
     constructor(data, names) {
         const { title } = names;
         this.#slashParams = new Set(names.slashParams ?? []);
+        this.#uriTemplates = names.pathMatching === "uri-template";
         this.#data = data;
         this.#title = title;
         this.#vendor = names.vendor;
@@ -145,6 +157,46 @@ export class OperationIndex {
         this.#segments = this.ops.map((op) => op.path.slice(1).split("/"));
         this.methods = [...METHODS].filter((method) => this.ops.some((op) => op.method === method));
     }
+    /** Content binding for discovery continuations; labels alone never identify an index. */
+    async cursorRevision() {
+        const bytes = new TextEncoder().encode(canonicalJson([
+            this.#data,
+            this.revision,
+            [...this.#slashParams].sort(),
+            ...(this.#uriTemplates ? ["uri-template"] : []),
+        ]));
+        return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    }
+    /** The request and response properties this operation declares; none when the index carries no fields. */
+    fields(op) {
+        if (!this.#fields) {
+            const data = this.#data.fields;
+            if (typeof data === "string") {
+                // Generated REST indexes share response paths and complete rows. Kit
+                // vendor indexes retain their directly declared body/response fields.
+                const { p, d, o } = JSON.parse(data);
+                const rows = d.map((ids) => ids.map((id) => ({ in: "response", path: p[id] })));
+                this.#fields = o.map((id) => rows[id]);
+            }
+            else
+                this.#fields = data ?? [];
+        }
+        return this.#fields[op.row] ?? [];
+    }
+    /**
+     * The names a result's first dot-path segment may take: the success
+     * response's own properties, or its items' properties when it is an array.
+     * Undefined when the operation declares no response contract.
+     */
+    responseRoots(op) {
+        const paths = this.fields(op).filter((field) => field.in === "response");
+        if (paths.length === 0)
+            return undefined;
+        return new Set(paths.map((field) => field.path
+            .replace(/^\[\]\./, "")
+            .split(".")[0]
+            .replace(/\[\]$/, "")));
+    }
     /** The operation with this exact method and path template, if any. */
     operation(method, template) {
         return this.ops.find((op) => op.method === method && op.path === template);
@@ -165,11 +217,29 @@ export class OperationIndex {
                 return;
             let score = 0;
             for (const [index, part] of template.entries()) {
-                if (part.startsWith("{"))
+                if (!this.#uriTemplates) {
+                    if (part.startsWith("{"))
+                        continue;
+                    if (part !== segments[index])
+                        return;
+                    score += 1;
                     continue;
-                if (part !== segments[index])
-                    return;
-                score += 1;
+                }
+                const parameter = /^(.*)\{([^{}]+)\}(.*)$/.exec(part);
+                const value = decodeURIComponent(segments[index]);
+                if (parameter) {
+                    if (!value.startsWith(parameter[1]) ||
+                        !value.endsWith(parameter[3]) ||
+                        value.length <= parameter[1].length + parameter[3].length)
+                        return;
+                    if (parameter[1] || parameter[3])
+                        score += 0.5;
+                }
+                else {
+                    if (part !== value)
+                        return;
+                    score += 1;
+                }
             }
             if (score > best.score)
                 best = { score, rows: [row] };
@@ -195,9 +265,34 @@ export class OperationIndex {
         }
         const params = {};
         template.forEach((part, index) => {
-            if (part.startsWith("{"))
-                params[part.slice(1, -1)] = segments[index];
+            if (!this.#uriTemplates) {
+                if (part.startsWith("{"))
+                    params[part.slice(1, -1)] = segments[index];
+                return;
+            }
+            const parameter = /^(.*)\{([^{}]+)\}(.*)$/.exec(part);
+            if (parameter) {
+                const raw = segments[index];
+                const prefix = parameter[1], suffix = parameter[3];
+                params[parameter[2]] =
+                    raw.startsWith(prefix) && raw.endsWith(suffix)
+                        ? raw.slice(prefix.length, suffix ? -suffix.length : undefined)
+                        : encodeURIComponent(decodeURIComponent(raw).slice(prefix.length, suffix ? -suffix.length : undefined));
+            }
         });
+        const issues = [];
+        const repair = [];
+        for (const [name, at, , schema] of this.#row(op)?.[0] ?? []) {
+            if (at === "path" && params[name] !== undefined)
+                this.#check(schema, decodeURIComponent(params[name]), `/path/${name}`, issues, repair);
+        }
+        if (issues.length) {
+            const shown = issues
+                .slice(0, 5)
+                .map((issue) => `${issue.path} (${issue.code}: ${issue.expected})`)
+                .join("; ");
+            invalid(`Not sent: the path does not match ${op.method} ${op.path} in the pinned API index: ${shown}. Substitute real ids matching ${this.#vendorTool("details")}.${issues.some((issue) => issue.expected?.includes("safe integer")) ? " Integer ids use canonical ASCII decimal notation within the safe-integer range." : ""}`, issues.slice(0, MAX_ISSUES));
+        }
         return { op, params };
     }
     /** Up to five operations whose paths most resemble a missed one. */
@@ -231,6 +326,9 @@ export class OperationIndex {
      * the path, summary, operationId, or tag (plural-insensitive, prefixes of
      * three letters count), and path matches weigh most. A query that starts
      * with "/" also matches the templates that fit it.
+     * Standard hatches opt into partial matches, ordered by matched term count
+     * before relevance, including the person/people alias. Legacy callers keep
+     * the all-term contract.
      */
     search(query, options) {
         this.#words ??= this.ops.map((op) => ({
@@ -261,6 +359,12 @@ export class OperationIndex {
             if (set.has(term))
                 return 2;
             for (const word of set) {
+                if (options.partial && ((term === "person" && word === "people") || (term === "people" && word === "person")))
+                    return 2;
+                if (options.partial &&
+                    ((term.endsWith("y") && word === `${term.slice(0, -1)}ies`) ||
+                        (word.endsWith("y") && term === `${word.slice(0, -1)}ies`)))
+                    return 2;
                 if (word === `${term}s` || term === `${word}s` || word === `${term}es` || term === `${word}es`)
                     return 2;
                 if (term.length >= 3 && word.startsWith(term))
@@ -280,12 +384,13 @@ export class OperationIndex {
                     matched += 1;
                 score += path * 3 + summary * 1.5 + id;
             }
-            if (!fits.has(op.row) && (terms.length === 0 || matched < terms.length))
+            if (!fits.has(op.row) && (terms.length === 0 || matched < (options.partial ? 1 : terms.length)))
                 return [];
-            return [{ op, score }];
+            return [{ op, score, matched }];
         });
         return ranked
-            .sort((a, b) => b.score - a.score ||
+            .sort((a, b) => (options.partial ? b.matched - a.matched : 0) ||
+            b.score - a.score ||
             a.op.path.split("/").length - b.op.path.split("/").length ||
             a.op.path.localeCompare(b.op.path))
             .slice(0, options.limit)
@@ -302,8 +407,16 @@ export class OperationIndex {
         const declared = row ? row[0] : [];
         // A generator may omit plain-string path parameters (`pathParams:
         // "typed"`); the template still names them, so the contract does too.
-        const implied = this.#segments[op.row].filter((part) => part.startsWith("{") && !declared.some(([name, at]) => at === "path" && name === part.slice(1, -1)))
-            .map((part) => [part.slice(1, -1), "path", 1, { t: "string" }]);
+        const implied = this.#segments[op.row].flatMap((part) => {
+            const name = this.#uriTemplates
+                ? /\{([^{}]+)\}/.exec(part)?.[1]
+                : part.startsWith("{")
+                    ? part.slice(1, -1)
+                    : undefined;
+            return name !== undefined && !declared.some(([key, at]) => at === "path" && key === name)
+                ? [[name, "path", 1, { t: "string" }]]
+                : [];
+        });
         const parameters = [...implied, ...declared]
             .filter(([name]) => only === undefined || name === only)
             .map(([name, at, required, schema, description]) => ({
@@ -317,7 +430,22 @@ export class OperationIndex {
         if (row && row[1] !== 0) {
             const [contentType, schema] = row[1];
             const node = this.#deref(schema);
-            if (only !== undefined && node.p?.[only] !== undefined) {
+            const full = this.#requestSchema(op);
+            if (full && only === undefined) {
+                body = { contentType, ...(row[1][2] === 1 ? { required: true } : {}), schema: full };
+            }
+            else if (full && only !== undefined && full["properties"]?.[only]) {
+                body = {
+                    contentType,
+                    schema: {
+                        type: "object",
+                        properties: { [only]: full["properties"][only] },
+                        ...(Array.isArray(full["required"]) && full["required"].includes(only) ? { required: [only] } : {}),
+                        ...(full["$defs"] ? { $defs: full["$defs"] } : {}),
+                    },
+                };
+            }
+            else if (only !== undefined && node.p?.[only] !== undefined) {
                 body = {
                     contentType,
                     schema: {
@@ -402,8 +530,40 @@ export class OperationIndex {
     #vendorTool(kind) {
         return `${this.#vendor}_api_${kind}`;
     }
+    #requestSchema(op) {
+        if (!this.#data.requestSchemas)
+            return undefined;
+        this.#requestSchemas ??= JSON.parse(this.#data.requestSchemas);
+        const graph = this.#requestSchemas;
+        const root = graph.roots[op.row];
+        if (!root)
+            return undefined;
+        const definitions = {};
+        const visit = (value) => {
+            if (!value || typeof value !== "object")
+                return;
+            if (Array.isArray(value)) {
+                for (const child of value)
+                    visit(child);
+                return;
+            }
+            const object = value;
+            if (typeof object["$ref"] === "string" && object["$ref"].startsWith("#/$defs/")) {
+                const name = object["$ref"].slice(8);
+                if (!Object.hasOwn(definitions, name)) {
+                    definitions[name] = graph.definitions[name] ?? {};
+                    visit(definitions[name]);
+                }
+            }
+            for (const child of Object.values(object))
+                visit(child);
+        };
+        visit(root);
+        const resolved = typeof root["$ref"] === "string" ? graph.definitions[root["$ref"].slice(8)] : root;
+        return { ...resolved, ...(Object.keys(definitions).length ? { $defs: definitions } : {}) };
+    }
     #row(op) {
-        this.#details ??= JSON.parse(this.#data.details);
+        this.#details ??= parseIndexDetails(this.#data);
         const row = this.#details.o[op.row];
         return row === 0 ? undefined : row;
     }
@@ -427,6 +587,12 @@ export class OperationIndex {
             out["format"] = resolved.f;
         if (resolved.n === 1)
             out["nullable"] = true;
+        if (resolved.l !== undefined)
+            out["minimum"] = resolved.l;
+        if (resolved.u !== undefined)
+            out["maximum"] = resolved.u;
+        if (resolved.deprecated === true)
+            out["deprecated"] = true;
         if (resolved.a)
             out["anyOf"] = resolved.a.map((branch) => this.#schema(branch));
         if (resolved.p) {
@@ -446,6 +612,35 @@ export class OperationIndex {
         if (issues.length >= MAX_ISSUES)
             return;
         const schema = this.#deref(node);
+        const path = at.startsWith("/path/");
+        const types = typesOf(schema);
+        if (path && !schema.a && !types.includes("string") && (types.includes("integer") || types.includes("number"))) {
+            const integer = types.includes("integer") && !types.includes("number");
+            const numeric = typeof value === "string" ? Number(value) : NaN;
+            const syntax = integer ? /^(?:0|-?[1-9][0-9]*)$/ : /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/;
+            if (typeof value !== "string" ||
+                !syntax.test(value) ||
+                Object.is(numeric, -0) ||
+                !Number.isFinite(numeric) ||
+                Math.abs(numeric) > Number.MAX_SAFE_INTEGER ||
+                (integer && !Number.isSafeInteger(numeric))) {
+                issues.push({
+                    path: at,
+                    code: "type",
+                    expected: integer ? "a canonical ASCII decimal safe integer" : "a canonical ASCII decimal number",
+                });
+                return;
+            }
+            value = numeric;
+        }
+        else if (path && types.length && !types.includes("string") && !schema.a) {
+            if (types.includes("boolean") && (value === "true" || value === "false"))
+                value = value === "true";
+            else {
+                issues.push({ path: at, code: "type", expected: types.join(" or ") });
+                return;
+            }
+        }
         if (schema.x === 1)
             return;
         // Conflicting composed constraints (disjoint enums or types) admit nothing,
@@ -454,6 +649,28 @@ export class OperationIndex {
             issues.push({ path: at, code: "enum", expected: "no value: this field's combined constraints admit none" });
             return;
         }
+        // Only newly opted-in bounded schemas enforce scalar numeric values;
+        // existing indexes retain their previous validation behavior. HTTP query
+        // strings may represent numbers, but must match the declared numeric type.
+        if (schema.l !== undefined || schema.u !== undefined) {
+            if (value === null && schema.n === 1)
+                return;
+            const integer = typesOf(schema).includes("integer");
+            const syntax = integer ? /^-?\d+$/ : /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+            const numeric = typeof value === "number"
+                ? value
+                : at.startsWith("/query/") && typeof value === "string" && syntax.test(value)
+                    ? Number(value)
+                    : NaN;
+            if (!Number.isFinite(numeric) || (integer && !Number.isSafeInteger(numeric))) {
+                issues.push({ path: at, code: "type", expected: integer ? "integer" : "finite number" });
+                return;
+            }
+            if (schema.l !== undefined && numeric < schema.l)
+                issues.push({ path: at, code: "minimum", expected: `at least ${schema.l}` });
+            if (schema.u !== undefined && numeric > schema.u)
+                issues.push({ path: at, code: "maximum", expected: `at most ${schema.u}` });
+        }
         if (value === null || value === "")
             return;
         if (schema.a) {
@@ -472,7 +689,6 @@ export class OperationIndex {
             }
             return;
         }
-        const types = typesOf(schema);
         if (schema.e && (typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
             if (!schema.e.some((option) => option === value || String(option) === String(value))) {
                 issues.push({ path: at, code: "enum", expected: oneOf(schema.e.map(String)) });

package/dist/providers/_shared/rest/response-media.js

@@ -0,0 +1,11 @@
+/** Match a reviewed non-JSON success media type only on its pinned operation. */
+export function responseMedia(media, status, operation, contentType = "") {
+    if (status < 200 || status > 299)
+        return undefined;
+    const type = contentType.split(";", 1)[0].trim().toLowerCase();
+    const path = operation.template.replace(/:([^/]+)/g, "{$1}");
+    if (!type ||
+        !media[`${operation.method} ${path}`]?.some((declared) => declared === type || (declared.endsWith("/*") && type.startsWith(declared.slice(0, -1)))))
+        return undefined;
+    return /^text\/|\bxml\b|\bcsv\b|\b(?:x-ndjson|jsonl|stream\+json)\b/.test(type) ? "text" : "binary";
+}