@forgeintel/sdk 0.2.0-beta.0

package/dist/id.js

@@ -0,0 +1,32 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+// 16 bytes -> 22 base64url chars: [0-3] issued-at seconds, [4-9] random, [10-15] HMAC tag.
+export const FEEDBACK_ID_PATTERN = /^[A-Za-z0-9_-]{22}$/;
+export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const HEAD_BYTES = 10;
+const TAG_BYTES = 6;
+const CLOCK_SKEW_MS = 5 * 60 * 1000;
+function tag(key, head) {
+    return createHmac("sha256", key).update(head).digest().subarray(0, TAG_BYTES);
+}
+export function mintFeedbackId(key, now = Date.now()) {
+    const head = Buffer.alloc(HEAD_BYTES);
+    head.writeUInt32BE(Math.floor(now / 1000) >>> 0, 0);
+    randomBytes(HEAD_BYTES - 4).copy(head, 4);
+    return Buffer.concat([head, tag(key, head)]).toString("base64url");
+}
+export function verifyFeedbackId(key, id, { ttlMs = DEFAULT_TTL_MS, now = Date.now() } = {}) {
+    if (typeof id !== "string" || !FEEDBACK_ID_PATTERN.test(id))
+        return { valid: false, reason: "malformed" };
+    const raw = Buffer.from(id, "base64url");
+    // Reject non-canonical encodings so one ID can't be submitted under several spellings.
+    if (raw.length !== HEAD_BYTES + TAG_BYTES || raw.toString("base64url") !== id) {
+        return { valid: false, reason: "malformed" };
+    }
+    const head = raw.subarray(0, HEAD_BYTES);
+    if (!timingSafeEqual(raw.subarray(HEAD_BYTES), tag(key, head)))
+        return { valid: false, reason: "bad_signature" };
+    const issuedAt = head.readUInt32BE(0) * 1000;
+    if (issuedAt > now + CLOCK_SKEW_MS || now - issuedAt > ttlMs)
+        return { valid: false, reason: "expired" };
+    return { valid: true, issuedAt };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createForge, createForgeFeedback } from "./express.js";
+export type { Forge, ForgeFeedback } from "./express.js";
+export { createForgeCore, checkOptions, BODY_LIMIT, SPEC_LIMIT } from "./core.js";
+export type { ForgeCall, ForgeCore, ForgeDiagnostics, ForgeFeedbackOptions, ForgeOptions, ForgeRequest, ForgeResponse, OpenApiOptions } from "./core.js";
+export { enrichOpenApi, detectVersion } from "./openapi.js";
+export type { EnrichOptions, EnrichReport, OperationReport, ResponseSupport, SpecVersion } from "./openapi.js";
+export { mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS } from "./id.js";
+export type { FeedbackIdCheck } from "./id.js";
+export { OUTCOMES, ISSUES, NOTE_MAX_LENGTH, PROTOCOL, parseSubmission } from "./values.js";
+export type { Outcome, Issue, Submission } from "./values.js";
+export { describeChallenge, describeChallengeBody, feedbackExtension, FEEDBACK_EXTENSION, readPaymentHeader } from "./x402.js";
+export type { ChallengeAdditions } from "./x402.js";
+export type { ForgeEvent } from "./reporter.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createForge, createForgeFeedback } from "./express.js";
+export { createForgeCore, checkOptions, BODY_LIMIT, SPEC_LIMIT } from "./core.js";
+export { enrichOpenApi, detectVersion } from "./openapi.js";
+export { mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS } from "./id.js";
+export { OUTCOMES, ISSUES, NOTE_MAX_LENGTH, PROTOCOL, parseSubmission } from "./values.js";
+export { describeChallenge, describeChallengeBody, feedbackExtension, FEEDBACK_EXTENSION, readPaymentHeader } from "./x402.js";

package/dist/openapi.d.ts

@@ -0,0 +1,44 @@
+type Json = Record<string, any>;
+export type SpecVersion = "2.0" | "3.0" | "3.1" | "3.2";
+export type ResponseSupport = "extended" | "incompatible" | "undocumented";
+export interface EnrichOptions {
+    /** Merchant public origin, e.g. https://api.example.com */
+    publicUrl: string;
+    /** Public path of the feedback routes, e.g. /feedback */
+    basePath: string;
+    /** Sentence appended to x-guidance and paid operation descriptions. */
+    sentence: string;
+    /** Substring that marks the sentence as already present. */
+    marker: string;
+    /** Override paid-operation detection. Default: the operation declares a 402 response or x-payment-info. */
+    isPaidOperation?: (method: string, path: string, operation: Json) => boolean;
+    /** Append the sentence to paid operation descriptions. Default true. */
+    describeOperations?: boolean;
+    /** Also document the optional rate_this_call body field (when the SDK's rateHint is on). */
+    hintField?: boolean;
+}
+export interface OperationReport {
+    method: string;
+    /** Path as written in the document (relative to the server URL). */
+    path: string;
+    /** Per 2xx status code: whether feedback_id was added to its JSON schema. */
+    responses: Record<string, ResponseSupport>;
+    reasons: string[];
+}
+export interface EnrichReport {
+    version: SpecVersion | null;
+    enriched: boolean;
+    /** Path prefix from servers[0] / basePath that document paths are relative to. */
+    serverPrefix: string;
+    feedbackPaths: "added" | "conflict" | "skipped";
+    operations: OperationReport[];
+    warnings: string[];
+}
+export declare function detectVersion(doc: unknown): SpecVersion | null;
+export declare function enrichOpenApi(input: unknown, options: EnrichOptions): {
+    document: unknown;
+    report: EnrichReport;
+};
+/** Runtime lookup: may feedback fields be added to this response body without contradicting the document? */
+export declare function createOperationIndex(report: EnrichReport): (method: string, path: string, status: number) => boolean;
+export {};

package/dist/openapi.js

@@ -0,0 +1,357 @@
+// Additive, idempotent OpenAPI enrichment for Swagger 2.0 and OpenAPI 3.0 / 3.1 / 3.2.
+// Rules: never mutate the input, never modify a shared $ref target, never override merchant paths,
+// and on any unexpected input return the original document unchanged.
+import { FEEDBACK_ID_PATTERN } from "./id.js";
+import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL } from "./values.js";
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+const ANNOTATIONS = new Set(["$ref", "description", "title", "summary", "example", "examples", "deprecated", "readOnly", "writeOnly", "$comment"]);
+const COMPOSITION = ["oneOf", "anyOf", "not", "if", "then", "else", "$dynamicRef", "discriminator"];
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const clone = (v) => structuredClone(v);
+export function detectVersion(doc) {
+    if (!isObj(doc))
+        return null;
+    if (doc.swagger === "2.0")
+        return "2.0";
+    const match = typeof doc.openapi === "string" && /^3\.([0-2])\.\d+/.exec(doc.openapi);
+    return match ? `3.${match[1]}` : null;
+}
+function resolveRef(doc, ref) {
+    let current = doc;
+    let target = ref;
+    for (let hops = 0; hops < 16; hops++) {
+        if (!target.startsWith("#/"))
+            return undefined;
+        current = doc;
+        for (const raw of target.slice(2).split("/")) {
+            const key = decodeURIComponent(raw).replace(/~1/g, "/").replace(/~0/g, "~");
+            current = isObj(current) || Array.isArray(current) ? current[key] : undefined;
+        }
+        if (!isObj(current))
+            return undefined;
+        if (typeof current.$ref !== "string")
+            return current;
+        target = current.$ref;
+    }
+    return undefined;
+}
+function feedbackProperties(rateUrl, hintField = false) {
+    return {
+        ...(hintField ? { rate_this_call: { type: "string", description: "How to rate this paid call in one free request." } } : {}),
+        feedback_id: {
+            type: "string",
+            pattern: FEEDBACK_ID_PATTERN.source,
+            description: "Rating ID for this paid call (also sent as the Forge-Feedback-Id header). See x-forge-feedback.",
+        },
+        feedback_url: {
+            type: "string",
+            format: "uri",
+            description: `Quick-rating URL with outcome left blank; outcome values: ${Object.keys(OUTCOMES).join(", ")}. Base: ${rateUrl}`,
+        },
+    };
+}
+/** Returns an extended copy of an object schema, or a reason it can't be extended safely. */
+function extendSchema(doc, schema, props) {
+    if (!isObj(schema))
+        return { reason: "no_schema" };
+    let target = schema;
+    let siblings = {};
+    if (typeof schema.$ref === "string") {
+        if (!schema.$ref.startsWith("#/"))
+            return { reason: "external_ref" };
+        const extra = Object.keys(schema).filter((k) => !ANNOTATIONS.has(k));
+        if (extra.length)
+            return { reason: "ref_with_constraints" };
+        const resolved = resolveRef(doc, schema.$ref);
+        if (!resolved)
+            return { reason: "unresolvable_ref" };
+        const { $ref: _ref, ...rest } = schema;
+        target = resolved;
+        siblings = rest;
+    }
+    // Copy the resolved schema inline so shared components stay untouched.
+    const copy = { ...clone(target), ...clone(siblings) };
+    if (COMPOSITION.some((k) => k in copy))
+        return { reason: "composition" };
+    const types = Array.isArray(copy.type) ? copy.type : [copy.type];
+    const objectish = types.includes("object") || (copy.type === undefined && (isObj(copy.properties) || Array.isArray(copy.allOf)));
+    if (!objectish)
+        return { reason: "not_object" };
+    if ("propertyNames" in copy || "maxProperties" in copy)
+        return { reason: "property_constraints" };
+    if (isObj(copy.properties) && Object.keys(props).some((k) => k in copy.properties)) {
+        return { reason: "field_collision" };
+    }
+    if (Array.isArray(copy.allOf)) {
+        for (const member of copy.allOf) {
+            const m = isObj(member) && typeof member.$ref === "string" ? resolveRef(doc, member.$ref) : member;
+            if (!isObj(m))
+                return { reason: "unresolvable_ref" };
+            // A strict allOf member would reject properties it doesn't declare itself.
+            if (m.additionalProperties === false || m.unevaluatedProperties === false || COMPOSITION.some((k) => k in m) || Array.isArray(m.allOf)) {
+                return { reason: "strict_composition" };
+            }
+            if (isObj(m.properties) && Object.keys(props).some((k) => k in m.properties))
+                return { reason: "field_collision" };
+        }
+    }
+    copy.properties = { ...(isObj(copy.properties) ? copy.properties : {}), ...clone(props) };
+    return { schema: copy };
+}
+const isJsonMedia = (type) => /^application\/(?:[\w.+-]+\+)?json\b/i.test(type);
+const is2xx = (code) => /^2(\d\d|XX)$/i.test(code);
+function appendSentence(text, sentence, marker) {
+    const current = typeof text === "string" ? text.trimEnd() : "";
+    if (current.includes(marker))
+        return current;
+    return current ? `${current}${current.includes("\n") ? "\n\n" : " "}${sentence}` : sentence;
+}
+/** Work out the path prefix document paths are relative to, and whether it's this service's origin. */
+function serverBase(doc, version, publicUrl) {
+    const origin = new URL(publicUrl).origin;
+    try {
+        if (version === "2.0") {
+            const scheme = Array.isArray(doc.schemes) && doc.schemes[0] ? doc.schemes[0] : new URL(publicUrl).protocol.slice(0, -1);
+            const base = typeof doc.basePath === "string" ? doc.basePath : "";
+            const url = typeof doc.host === "string" ? new URL(`${scheme}://${doc.host}${base}`) : new URL(base || "/", publicUrl);
+            return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+        }
+        const server = Array.isArray(doc.servers) ? doc.servers[0] : undefined;
+        if (!isObj(server) || typeof server.url !== "string")
+            return { prefix: "", sameOrigin: true };
+        const raw = server.url.replace(/\{([^}]+)\}/g, (_, name) => server.variables?.[name]?.default ?? "");
+        const url = new URL(raw, publicUrl);
+        return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+    }
+    catch {
+        return { prefix: "", sameOrigin: false };
+    }
+}
+function feedbackOperations(version, formUrl, rateUrl, existingIds) {
+    const id = (name) => (existingIds.has(name) ? {} : { operationId: name });
+    const idSchema = { type: "string", pattern: FEEDBACK_ID_PATTERN.source };
+    const outcome = { type: "string", enum: Object.keys(OUTCOMES) };
+    const issue = { type: "string", enum: Object.keys(ISSUES) };
+    const result = {
+        type: "object",
+        properties: { recorded: { type: "boolean" }, updated: { type: "boolean" }, error: { type: "string" } },
+    };
+    const submission = {
+        type: "object",
+        required: ["feedback_id", "outcome"],
+        additionalProperties: false,
+        properties: { feedback_id: idSchema, outcome, issue, note: { type: "string", maxLength: NOTE_MAX_LENGTH } },
+    };
+    const common = { security: [], "x-forge-feedback": true };
+    const descr = {
+        rate: `Records a free rating for a paid call. Enum values only. Same as: ${rateUrl}?feedback_id=FEEDBACK_ID&outcome=OUTCOME`,
+        summary: "Public summary of ratings that agents gave this service after paid calls.",
+        form: "Describes the rating fields and both submission methods. Submits nothing.",
+        submit: `Records a free rating with an optional note (max ${NOTE_MAX_LENGTH} characters, no user data).`,
+    };
+    if (version === "2.0") {
+        const ok = (description) => ({ description, schema: result });
+        const q = (name, required, s) => ({ name, in: "query", required, ...s });
+        return {
+            form: { ...common, ...id("forgeFeedbackForm"), summary: "Rating form", description: descr.form, produces: ["application/json"], responses: { "200": { description: "Rating fields" } } },
+            summary: { ...common, ...id("forgeFeedbackSummary"), summary: "Public rating summary", description: descr.summary, produces: ["application/json"], responses: { "200": { description: "Rating summary" } } },
+            submit: {
+                ...common, ...id("forgeFeedbackSubmit"), summary: "Rate a paid call", description: descr.submit,
+                consumes: ["application/json"], produces: ["application/json"],
+                parameters: [{ name: "body", in: "body", required: true, schema: submission }],
+                responses: { "200": ok("Recorded"), default: ok("Not recorded") },
+            },
+            rate: {
+                ...common, ...id("forgeFeedbackRate"), summary: "Rate a paid call (quick)", description: descr.rate, produces: ["application/json"],
+                parameters: [q("feedback_id", true, idSchema), q("outcome", true, outcome), q("issue", false, issue)],
+                responses: { "200": ok("Recorded"), default: ok("Not recorded") },
+            },
+        };
+    }
+    const json = (schema) => ({ content: { "application/json": { schema } } });
+    const q = (name, required, schema) => ({ name, in: "query", required, schema });
+    return {
+        form: { ...common, ...id("forgeFeedbackForm"), summary: "Rating form", description: descr.form, responses: { "200": { description: "Rating fields", ...json({ type: "object" }) } } },
+        summary: { ...common, ...id("forgeFeedbackSummary"), summary: "Public rating summary", description: descr.summary, responses: { "200": { description: "Rating summary", ...json({ type: "object" }) } } },
+        submit: {
+            ...common, ...id("forgeFeedbackSubmit"), summary: "Rate a paid call", description: descr.submit,
+            requestBody: { required: true, ...json(submission) },
+            responses: { "200": { description: "Recorded", ...json(result) }, default: { description: "Not recorded", ...json(result) } },
+        },
+        rate: {
+            ...common, ...id("forgeFeedbackRate"), summary: "Rate a paid call (quick)", description: descr.rate,
+            parameters: [q("feedback_id", true, idSchema), q("outcome", true, outcome), q("issue", false, issue)],
+            responses: { "200": { description: "Recorded", ...json(result) }, default: { description: "Not recorded", ...json(result) } },
+        },
+    };
+}
+export function enrichOpenApi(input, options) {
+    const report = { version: null, enriched: false, serverPrefix: "", feedbackPaths: "skipped", operations: [], warnings: [] };
+    const version = detectVersion(input);
+    report.version = version;
+    if (!version) {
+        report.warnings.push("Not an OpenAPI 3.0-3.2 or Swagger 2.0 document; left unchanged.");
+        return { document: input, report };
+    }
+    const original = input;
+    if (isObj(original["x-forge-feedback"])) {
+        report.warnings.push("Document already carries x-forge-feedback; left unchanged.");
+        return { document: input, report };
+    }
+    try {
+        const doc = clone(original);
+        const origin = new URL(options.publicUrl).origin;
+        const base = options.basePath.replace(/\/+$/, "");
+        const rateUrl = `${origin}${base}/rate`;
+        const formUrl = `${origin}${base}`;
+        const props = feedbackProperties(rateUrl, options.hintField);
+        const isPaid = options.isPaidOperation ??
+            ((_m, _p, op) => (isObj(op.responses) && "402" in op.responses) || isObj(op["x-payment-info"]));
+        const methods = version === "3.2" ? [...METHODS, "query"] : METHODS;
+        const { prefix, sameOrigin } = serverBase(doc, version, options.publicUrl);
+        report.serverPrefix = prefix;
+        if (!isObj(doc.paths)) {
+            if (version === "3.1" || version === "3.2")
+                doc.paths = {};
+            else
+                throw new Error("paths is missing");
+        }
+        const operationIds = new Set();
+        for (const [path, item] of Object.entries(doc.paths)) {
+            if (!isObj(item))
+                continue;
+            for (const method of methods) {
+                const op = item[method];
+                if (!isObj(op))
+                    continue;
+                if (typeof op.operationId === "string")
+                    operationIds.add(op.operationId);
+                if (typeof item.$ref === "string") {
+                    report.warnings.push(`${method.toUpperCase()} ${path}: path item uses $ref; not modified.`);
+                    continue;
+                }
+                if (!isPaid(method, path, op))
+                    continue;
+                const opReport = { method: method.toUpperCase(), path, responses: {}, reasons: [] };
+                report.operations.push(opReport);
+                if (options.describeOperations ?? true)
+                    op.description = appendSentence(op.description, options.sentence, options.marker);
+                const produces = (op.produces ?? doc.produces);
+                for (const [code, rawResponse] of Object.entries(isObj(op.responses) ? op.responses : {})) {
+                    if (!is2xx(code))
+                        continue;
+                    let response = rawResponse;
+                    if (isObj(response) && typeof response.$ref === "string") {
+                        const resolved = resolveRef(doc, response.$ref);
+                        if (!resolved) {
+                            opReport.responses[code] = "incompatible";
+                            opReport.reasons.push(`${code}: unresolvable_ref`);
+                            continue;
+                        }
+                        response = clone(resolved);
+                    }
+                    if (!isObj(response))
+                        continue;
+                    const schemas = [];
+                    if (version === "2.0") {
+                        const jsonish = !Array.isArray(produces) || produces.some((t) => typeof t === "string" && isJsonMedia(t));
+                        if (jsonish && "schema" in response)
+                            schemas.push({ get: () => response.schema, set: (s) => (response.schema = s) });
+                    }
+                    else if (isObj(response.content)) {
+                        for (const [media, entry] of Object.entries(response.content)) {
+                            if (isJsonMedia(media) && isObj(entry) && "schema" in entry) {
+                                schemas.push({ get: () => entry.schema, set: (s) => (entry.schema = s) });
+                            }
+                        }
+                    }
+                    if (!schemas.length) {
+                        opReport.responses[code] = "undocumented";
+                        continue;
+                    }
+                    const results = schemas.map((s) => extendSchema(doc, s.get(), props));
+                    const failure = results.find((r) => "reason" in r);
+                    if (failure) {
+                        opReport.responses[code] = "incompatible";
+                        opReport.reasons.push(`${code}: ${failure.reason}`);
+                        continue;
+                    }
+                    results.forEach((r, i) => schemas[i].set(r.schema));
+                    op.responses[code] = response; // inline copy if it was a shared $ref
+                    opReport.responses[code] = "extended";
+                }
+                // agentcash-style payment metadata carries its own output schema.
+                const info = op["x-payment-info"];
+                if (isObj(info) && isObj(info.outputSchema)) {
+                    const r = extendSchema(doc, info.outputSchema, props);
+                    if ("schema" in r)
+                        info.outputSchema = r.schema;
+                }
+            }
+        }
+        // Feedback routes. Paths are relative to the server prefix when it's this origin;
+        // otherwise (3.x) the path items carry their own servers entry.
+        const inPrefix = sameOrigin && (base === prefix || base.startsWith(`${prefix}/`));
+        const docBase = inPrefix ? base.slice(prefix.length) || "/" : base;
+        const paths = doc.paths;
+        const conflicts = [docBase, `${docBase}/rate`, `${docBase}/summary`].filter((p) => isObj(paths[p]));
+        if (conflicts.length) {
+            report.feedbackPaths = "conflict";
+            report.warnings.push(`Document already defines ${conflicts.join(" and ")}. The SDK's routes answer these paths at runtime; set basePath to avoid shadowing them.`);
+        }
+        else if (!inPrefix && version === "2.0") {
+            report.warnings.push("Swagger 2.0 host/basePath doesn't cover the feedback path; feedback routes not documented.");
+        }
+        else {
+            const ops = feedbackOperations(version, formUrl, rateUrl, operationIds);
+            const servers = inPrefix ? {} : { servers: [{ url: origin }] };
+            paths[docBase] = { ...servers, get: ops.form, post: ops.submit };
+            paths[`${docBase}/rate`] = { ...servers, get: ops.rate };
+            paths[`${docBase}/summary`] = { ...servers, get: ops.summary };
+            report.feedbackPaths = "added";
+        }
+        // Guidance: append to whichever x-guidance exists, preferring info-level.
+        if (isObj(doc.info)) {
+            if (typeof doc.info["x-guidance"] === "string" || typeof doc["x-guidance"] !== "string") {
+                doc.info["x-guidance"] = appendSentence(doc.info["x-guidance"], options.sentence, options.marker);
+            }
+            if (typeof doc["x-guidance"] === "string")
+                doc["x-guidance"] = appendSentence(doc["x-guidance"], options.sentence, options.marker);
+        }
+        doc["x-forge-feedback"] = {
+            protocol: PROTOCOL,
+            rate: `${rateUrl}?feedback_id={feedback_id}&outcome={outcome}`,
+            submit: formUrl,
+            id_header: "Forge-Feedback-Id",
+            outcomes: Object.keys(OUTCOMES),
+            issues: Object.keys(ISSUES),
+        };
+        JSON.stringify(doc); // must stay serializable
+        report.enriched = true;
+        return { document: doc, report };
+    }
+    catch (error) {
+        report.warnings.push(`Enrichment failed (${error instanceof Error ? error.message : String(error)}); served unchanged.`);
+        report.enriched = false;
+        report.operations = [];
+        return { document: input, report };
+    }
+}
+/** Runtime lookup: may feedback fields be added to this response body without contradicting the document? */
+export function createOperationIndex(report) {
+    const entries = report.operations.map((op) => {
+        const full = `${report.serverPrefix}${op.path}`;
+        const pattern = full
+            .split(/(\{[^}]+\})/)
+            .map((part) => (/^\{[^}]+\}$/.test(part) ? "[^/]+" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
+            .join("");
+        return { method: op.method, regex: new RegExp(`^${pattern}/?$`), responses: op.responses };
+    });
+    return (method, path, status) => {
+        const op = entries.find((e) => e.method === method && e.regex.test(path));
+        if (!op)
+            return true; // undocumented operation: nothing to contradict
+        const support = op.responses[String(status)] ?? op.responses[`${String(status)[0]}XX`] ?? op.responses[`${String(status)[0]}xx`];
+        return support !== "incompatible";
+    };
+}

package/dist/reporter.d.ts

@@ -0,0 +1,34 @@
+export type ForgeEvent = {
+    type: "challenge";
+    route: string;
+    ts: number;
+    user_agent?: string;
+} | {
+    type: "interaction";
+    feedback_id: string;
+    route: string;
+    status: number;
+    latency_ms: number;
+    payer?: string;
+    network?: string;
+    amount?: string;
+    user_agent?: string;
+    ts: number;
+};
+/** Batches events to the backend in the background. Drops the oldest events if the backend stays down. */
+export declare class EventReporter {
+    private readonly url;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly onError;
+    private queue;
+    private timer;
+    private flushing;
+    sent: number;
+    dropped: number;
+    constructor(url: string, apiKey: string, fetchImpl: typeof fetch, onError: (error: unknown) => void, intervalMs: number);
+    push(event: ForgeEvent): void;
+    flush(): Promise<void>;
+    private drain;
+    close(): Promise<void>;
+}

package/dist/reporter.js

@@ -0,0 +1,59 @@
+const MAX_QUEUE = 1000;
+const BATCH_SIZE = 100;
+/** Batches events to the backend in the background. Drops the oldest events if the backend stays down. */
+export class EventReporter {
+    url;
+    apiKey;
+    fetchImpl;
+    onError;
+    queue = [];
+    timer;
+    flushing = null;
+    sent = 0;
+    dropped = 0;
+    constructor(url, apiKey, fetchImpl, onError, intervalMs) {
+        this.url = url;
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+        this.onError = onError;
+        this.timer = setInterval(() => void this.flush(), intervalMs);
+        this.timer.unref();
+    }
+    push(event) {
+        this.queue.push(event);
+        if (this.queue.length > MAX_QUEUE)
+            this.dropped += this.queue.splice(0, this.queue.length - MAX_QUEUE).length;
+        if (this.queue.length >= BATCH_SIZE)
+            void this.flush();
+    }
+    flush() {
+        if (!this.flushing)
+            this.flushing = this.drain().finally(() => (this.flushing = null));
+        return this.flushing;
+    }
+    async drain() {
+        while (this.queue.length) {
+            const batch = this.queue.splice(0, BATCH_SIZE);
+            try {
+                const response = await this.fetchImpl(this.url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", authorization: `Bearer ${this.apiKey}` },
+                    body: JSON.stringify({ events: batch }),
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (!response.ok)
+                    throw new Error(`event ingest returned ${response.status}`);
+                this.sent += batch.length;
+            }
+            catch (error) {
+                this.queue.unshift(...batch);
+                this.onError(error);
+                return;
+            }
+        }
+    }
+    async close() {
+        clearInterval(this.timer);
+        await this.flush();
+    }
+}

package/dist/values.d.ts

@@ -0,0 +1,35 @@
+export declare const PROTOCOL = "forge-feedback/0";
+export declare const OUTCOMES: {
+    readonly fully: "The call accomplished what you called it for.";
+    readonly partially: "It helped, but only partly.";
+    readonly no: "It did not accomplish what you called it for.";
+    readonly not_evaluated: "You did not check the result.";
+};
+export declare const ISSUES: {
+    readonly wrong_output: "The result is incorrect or poor quality.";
+    readonly unmet_expectation: "It worked as built, but not what the description or schema led you to expect.";
+    readonly schema_mismatch: "The response shape did not match the declared schema.";
+    readonly slow: "Too slow for the task.";
+    readonly unclear_docs: "Hard to work out how to call it.";
+    readonly too_expensive: "The price was not worth the result.";
+};
+export type Outcome = keyof typeof OUTCOMES;
+export type Issue = keyof typeof ISSUES;
+export declare const NOTE_MAX_LENGTH = 280;
+export interface Submission {
+    feedback_id: string;
+    outcome: Outcome;
+    issue: Issue | null;
+    note: string | null;
+}
+export type ParseResult = {
+    ok: true;
+    value: Submission;
+} | {
+    ok: false;
+    error: string;
+};
+/** Validate a submission from either the GET query or the POST body. Empty strings count as absent. */
+export declare function parseSubmission(input: Record<string, unknown>, { allowNote }: {
+    allowNote: boolean;
+}): ParseResult;

package/dist/values.js

@@ -0,0 +1,46 @@
+export const PROTOCOL = "forge-feedback/0";
+export const OUTCOMES = {
+    fully: "The call accomplished what you called it for.",
+    partially: "It helped, but only partly.",
+    no: "It did not accomplish what you called it for.",
+    not_evaluated: "You did not check the result.",
+};
+export const ISSUES = {
+    wrong_output: "The result is incorrect or poor quality.",
+    unmet_expectation: "It worked as built, but not what the description or schema led you to expect.",
+    schema_mismatch: "The response shape did not match the declared schema.",
+    slow: "Too slow for the task.",
+    unclear_docs: "Hard to work out how to call it.",
+    too_expensive: "The price was not worth the result.",
+};
+export const NOTE_MAX_LENGTH = 280;
+const isOutcome = (v) => typeof v === "string" && Object.hasOwn(OUTCOMES, v);
+const isIssue = (v) => typeof v === "string" && Object.hasOwn(ISSUES, v);
+/** Validate a submission from either the GET query or the POST body. Empty strings count as absent. */
+export function parseSubmission(input, { allowNote }) {
+    const present = (v) => v !== undefined && v !== null && v !== "";
+    const { feedback_id, outcome, issue, note } = input;
+    if (typeof feedback_id !== "string" || !feedback_id)
+        return { ok: false, error: "missing_feedback_id" };
+    if (!present(outcome))
+        return { ok: false, error: "missing_outcome" };
+    if (!isOutcome(outcome))
+        return { ok: false, error: "invalid_outcome" };
+    if (present(issue) && !isIssue(issue))
+        return { ok: false, error: "invalid_issue" };
+    if (present(note)) {
+        if (!allowNote)
+            return { ok: false, error: "note_requires_post" };
+        if (typeof note !== "string" || note.length > NOTE_MAX_LENGTH)
+            return { ok: false, error: "invalid_note" };
+    }
+    return {
+        ok: true,
+        value: {
+            feedback_id,
+            outcome,
+            issue: present(issue) ? issue : null,
+            note: present(note) ? note.trim() || null : null,
+        },
+    };
+}