@enricai/barnacle 1.0.0

package/dist/lib/llm/schemas.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * Zod schemas for every Anthropic LLM call site's structured output. Every
+ * call in the engine goes through `client.messages.parse` + `zodOutputFormat`
+ * (or equivalent) so the SDK throws on schema violation rather than handing
+ * back malformed text the caller has to defensively parse. Co-locating the
+ * schemas here keeps the contracts visible in one file instead of buried
+ * inside ~4500-line scripts.
+ *
+ * Naming: each schema corresponds 1:1 to a `CALL_TYPE_*` constant in
+ * `src/lib/telemetry/call-types.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SELECT_OPTION_SCHEMA = exports.ERROR_MESSAGES_SCHEMA = exports.MODAL_PRIORITY_SCHEMA = exports.INVALID_FIELDS_SCHEMA = exports.SUBMIT_VERDICT_SCHEMA = exports.JUDGE_VERDICT_SCHEMA = exports.PATCH_RESPONSE_SCHEMA = exports.REPHRASE_RESPONSE_SCHEMA = exports.REPLAN_RESPONSE_SCHEMA = exports.RECON_FLOW_STEP_SCHEMA = exports.REPLAN_MAX_STEPS = void 0;
+const v4_1 = require("zod/v4");
+/**
+ * Cap on per-replan step list size. Anything beyond this is almost certainly
+ * the LLM hallucinating an entire flow from scratch instead of writing the
+ * minimum bridge needed to unstick the cascade. Matches the existing pre-move
+ * constant value so call-site behavior is identical.
+ */
+exports.REPLAN_MAX_STEPS = 30;
+/**
+ * Flow step shape consumed by every recon-flow consumer (file parsing,
+ * replanner output, normalizer). A bare string is a required step; the
+ * object form supports `optional` and `upload` flags.
+ *
+ * Moved here from recon-browser.ts so REPLAN_RESPONSE_SCHEMA can be defined
+ * alongside it without recon-browser.ts having to re-export both.
+ */
+exports.RECON_FLOW_STEP_SCHEMA = v4_1.z.union([
+    v4_1.z.string().min(1),
+    v4_1.z.object({
+        step: v4_1.z.string().min(1),
+        optional: v4_1.z.boolean().default(false),
+        upload: v4_1.z.boolean().default(false),
+        /**
+         * When true, the step is treated as the canonical submit click for the
+         * `submitEndpointPattern` verifier even when its position in the flow
+         * is not the last index. The pre-2026-06-15 implementation gated the
+         * pre-submit DOM probe on `isFinalStep` only, but real AppCast flows
+         * put the submit click in the middle of the step list (UVA Verona's
+         * Submit was at index 55/328) and follow it with post-submit
+         * verification steps. With this flag set, the probe + verifier fire
+         * at the actual submit click, not at the unrelated last step.
+         */
+        submitStep: v4_1.z.boolean().default(false),
+        /**
+         * Optional payload-field override for the generator's splicer. When set,
+         * `resolveStepPayloadField` returns this field name verbatim instead of
+         * inferring one from the instruction's English label — lets a flow author
+         * pin a step to a specific `payload.<field>` reference in the generated
+         * browser-flow. Ignored by the recon runtime; consumed only by
+         * recon-generate.ts.
+         */
+        payloadField: v4_1.z.string().optional(),
+        /**
+         * Optional opt-out for the generator's splicer. When true, the generator
+         * leaves the instruction literal even if its label would otherwise match a
+         * candidate payload field. Ignored by the recon runtime.
+         */
+        payloadFieldNone: v4_1.z.boolean().optional(),
+    }),
+]);
+/**
+ * Replanner response. Discriminated union on `outcome`. When the cascade has
+ * exhausted all per-step healing attempts, the replanner either proposes a
+ * bridge sequence (`replan` outcome) or admits the page state is
+ * unrecoverable (`impossible`). The single-action constraint on each step is
+ * enforced by the caller's normalizer, not the schema (the LLM emits
+ * arbitrary text inside `step`; we trust the caller's downstream parse).
+ */
+exports.REPLAN_RESPONSE_SCHEMA = v4_1.z.discriminatedUnion("outcome", [
+    v4_1.z.object({
+        outcome: v4_1.z.literal("replan"),
+        steps: v4_1.z.array(exports.RECON_FLOW_STEP_SCHEMA).min(1).max(exports.REPLAN_MAX_STEPS),
+    }),
+    v4_1.z.object({
+        outcome: v4_1.z.literal("impossible"),
+        reason: v4_1.z.string().min(1),
+    }),
+]);
+/**
+ * Rephrase response. Discriminated union on `outcome`. The pre-schema
+ * contract was free text plus the magic string "IMPOSSIBLE" — fragile and
+ * easy for the LLM to emit prose around. The schema makes the contract
+ * explicit and parses on the API side.
+ */
+exports.REPHRASE_RESPONSE_SCHEMA = v4_1.z.discriminatedUnion("outcome", [
+    v4_1.z.object({
+        outcome: v4_1.z.literal("rewrite"),
+        instruction: v4_1.z.string().min(1).max(400),
+    }),
+    v4_1.z.object({
+        outcome: v4_1.z.literal("impossible"),
+        reason: v4_1.z.string().min(1).max(200),
+    }),
+]);
+/**
+ * Patch generator response shape. Shared between `recon-flow-patch` and
+ * `llm-prompt-patch` — both follow the same anchor/replacement/strategy
+ * minimal-change discipline. The contract was identical at the prose level
+ * before this schema; making it shared explicit Zod cleans up two parallel
+ * `JSON.parse` ladders.
+ *
+ * Cross-field validation (anchor must exist in the artifact being patched)
+ * stays at the caller because the artifact isn't known to the schema.
+ */
+exports.PATCH_RESPONSE_SCHEMA = v4_1.z.object({
+    anchor: v4_1.z.string().min(1),
+    replacement: v4_1.z.string(),
+    strategy: v4_1.z.string().min(1).max(120),
+    pivot_reason: v4_1.z.string().nullable(),
+});
+/**
+ * Judge verdict shape. The existing judge prompt already specifies this
+ * structure in prose; moving it to a Zod schema makes the contract enforced
+ * by the SDK and removes the manual try/catch JSON-parse ladder.
+ */
+exports.JUDGE_VERDICT_SCHEMA = v4_1.z.object({
+    schemaOk: v4_1.z.boolean(),
+    schemaRationale: v4_1.z.string().min(1).max(400),
+    factuallyGrounded: v4_1.z.boolean(),
+    factualRationale: v4_1.z.string().min(1).max(400),
+    hallucinationFree: v4_1.z.boolean(),
+    hallucinationRationale: v4_1.z.string().min(1).max(400),
+    worstOffender: v4_1.z.enum(["schema", "factual", "hallucination"]).nullable().optional(),
+});
+/**
+ * Submit-verification verdict. Replaces the per-site `submitEndpointPattern`
+ * regex. Discriminated union forces the LLM to commit to verified=true|false
+ * — no in-between "maybe" state.
+ *
+ * The verified=true branch requires populating three signal fields (any can
+ * be null but at least one of dom_signal / url_signal SHOULD be non-null per
+ * the strict system prompt). The verifier's `rationale` must cite the
+ * strongest signal — keeps Haiku honest about why it ruled success.
+ *
+ * The verified=false branch requires a reason — keeps Haiku from waving
+ * failures away without explanation, and gives the rephrase prompt
+ * downstream a structured signal about what to look for.
+ *
+ * Empirically validated 2026-06-11 on two real production failure dumps
+ * (one wrongly-flagged-as-fail, one genuinely-stuck) — both verdicts
+ * correct, both rationale fields coherent.
+ */
+exports.SUBMIT_VERDICT_SCHEMA = v4_1.z.discriminatedUnion("verified", [
+    v4_1.z.object({
+        verified: v4_1.z.literal(true),
+        network_signal: v4_1.z
+            .object({
+            url: v4_1.z.string().max(2048),
+            status: v4_1.z.number(),
+            method: v4_1.z.string().max(16),
+        })
+            .nullable(),
+        dom_signal: v4_1.z.string().max(200).nullable(),
+        url_signal: v4_1.z.string().max(200).nullable(),
+        rationale: v4_1.z.string().min(1).max(400),
+    }),
+    v4_1.z.object({
+        verified: v4_1.z.literal(false),
+        reason: v4_1.z.string().min(1).max(400),
+    }),
+]);
+/**
+ * Invalid-field detection verdict. Replaces INVALID_CLASS_RX regex.
+ * `present` is the top-level boolean so a downstream consumer can
+ * short-circuit on "no invalid fields here" without iterating `fields`.
+ * `fields` carries the discovered structural markers per-container so
+ * the rephrase prompt can build its INTERACTIVE TARGETS section.
+ *
+ * Strict prompting requires: structural marker (class containing
+ * "invalid", aria-invalid="true", data-invalid, or visible error
+ * container near input). Visual-only styling does NOT count.
+ */
+exports.INVALID_FIELDS_SCHEMA = v4_1.z.object({
+    present: v4_1.z.boolean(),
+    fields: v4_1.z
+        .array(v4_1.z.object({
+        containerXpath: v4_1.z.string().min(1),
+        label: v4_1.z.string().nullable(),
+        markerKind: v4_1.z.enum(["class", "aria", "data", "error-container", "other"]),
+        framework: v4_1.z.enum(["angular", "react", "vue", "mantine", "chakra", "bootstrap", "other"]),
+    }))
+        .max(50),
+});
+/**
+ * Modal-priority verdict. Replaces MODAL_PRIORITY_RX keyword regex over
+ * Stagehand's English description strings. Returns indices into the
+ * caller-supplied unfocused-observe array — the engine just re-sorts
+ * its own list, the LLM doesn't see selectors or have to echo them
+ * back.
+ *
+ * Strict prompting requires: structurally blocking the form. Cookie
+ * banners and welcome modals ARE priority. Always-visible panels and
+ * sidebars are NOT.
+ */
+exports.MODAL_PRIORITY_SCHEMA = v4_1.z.object({
+    priorityIndices: v4_1.z.array(v4_1.z.number().int().min(0)).max(50),
+    rationale: v4_1.z.string().min(1).max(400),
+});
+/**
+ * Visible-error-message extraction verdict. Replaces `errorPattern`
+ * regex. Each entry carries the text, an optional field-name hint,
+ * and a severity ranking — the rephrase prompt today renders these as
+ * the VISIBLE ERROR / REQUIRED-FIELD MESSAGES section.
+ *
+ * Strict prompting: structurally-marked error containers + visible text
+ * only. Skip placeholder text, help text, and inactive tooltips.
+ */
+exports.ERROR_MESSAGES_SCHEMA = v4_1.z.object({
+    messages: v4_1.z
+        .array(v4_1.z.object({
+        text: v4_1.z.string().min(1).max(400),
+        fieldHint: v4_1.z.string().nullable(),
+        severity: v4_1.z.enum(["error", "warning", "info"]),
+    }))
+        .max(50),
+});
+/**
+ * Select-option picker verdict. When a flow step's hardcoded dropdown answer
+ * doesn't exist in a given requisition's option list (per-req variance —
+ * e.g. an ER-flavored answer on a Cardiac job), this judge picks the most
+ * plausible AVAILABLE option so the required question can be answered and the
+ * wizard advances. `selectIndex` picks which candidate dropdown answers the
+ * question (or null when none does); `optionIndex` picks the option within that
+ * dropdown (null when `selectIndex` is null).
+ */
+exports.SELECT_OPTION_SCHEMA = v4_1.z.object({
+    /** Index into the caller-supplied candidate dropdowns — which dropdown on the
+     *  page answers the question. Null when none does. */
+    selectIndex: v4_1.z.number().int().min(0).nullable(),
+    /** Index into that dropdown's options — which option to choose. Null when
+     *  selectIndex is null. */
+    optionIndex: v4_1.z.number().int().min(0).nullable(),
+    reason: v4_1.z.string().min(1).max(400),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/lib/llm/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/lib/llm/schemas.ts"],"names":[],"mappings":"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"}

package/dist/lib/logging.d.ts

@@ -0,0 +1,39 @@
+import pino from "pino";
+import type { Logger } from "../types/logging";
+/**
+ * Splits a message that exceeds CloudWatch's 256KB per-event cap. Prefers
+ * newline / space boundaries so chunks stay readable; falls back to a
+ * UTF-8-safe byte boundary so we don't slice through a multi-byte char.
+ *
+ * Exported for direct testing — the runtime emit path runs through a
+ * silent pino in NODE_ENV=test, so chunking is otherwise unobservable.
+ * Callers outside this module should use the logger methods instead.
+ */
+export declare function splitLargeMessage(message: string, maxSize?: number): string[];
+/**
+ * Wraps a pino logger with the project's extended Logger interface: CloudWatch
+ * message splitting on every level method, and `errorWithStack` for one-line
+ * error logs that include the stack inline. Used internally by `getLogger` and
+ * exported so callers with an existing pino instance (e.g. `request.log`) can
+ * promote it to the full Logger contract without creating a new logger.
+ */
+export declare function extendLogger(logger: pino.Logger): Logger;
+/**
+ * Returns a pino logger for one-shot CLI scripts. Uses pino-pretty in
+ * development (where the devDependency is installed) and falls back to raw
+ * JSON elsewhere, mirroring `getLogger`'s gating — `pino-pretty` is pruned
+ * from production images, so an unconditional transport crashes on module
+ * load in prod (see the pino-pretty prod-crash incident).
+ */
+export declare function getScriptLogger(name: string): Logger;
+/**
+ * Creates a named pino logger with the project's standard wiring:
+ * pino-pretty transport in dev, JSON in prod, silent in test, secrets
+ * redacted, and every string message auto-chunked under CloudWatch's
+ * 256KB event cap. `name` appears as `{appName}://{name}` on every line.
+ */
+export declare function getLogger({ name, level }: {
+    name: string;
+    level?: string;
+}): Logger;
+//# sourceMappingURL=logging.d.ts.map

package/dist/lib/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/lib/logging.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,MAAM,CAAC;AAIxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AA4D9C;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,GAAG,MAAM,EAAE,CAY/F;AA4DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAiCxD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQpD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CA0BnF"}

package/dist/lib/logging.js

@@ -0,0 +1,219 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitLargeMessage = splitLargeMessage;
+exports.extendLogger = extendLogger;
+exports.getScriptLogger = getScriptLogger;
+exports.getLogger = getLogger;
+const date_fns_1 = require("date-fns");
+const pino_1 = __importDefault(require("pino"));
+const datadog_1 = require("../lib/datadog");
+const env_1 = require("../lib/env");
+const nodeEnv = (0, env_1.getNodeEnv)();
+const isDevelopment = nodeEnv === "development";
+const isTest = nodeEnv === "test";
+const defaultLoggingLevel = process.env.LOG_LEVEL ?? (process.env.DEBUG ? "debug" : "info");
+const defaultAppName = process.env.APP_NAME || "barnacle";
+const ddEnabled = (0, env_1.getBoolEnv)("DD_TRACE_ENABLED", false);
+/**
+ * CloudWatch Logs has a hard limit of 256KB per log event.
+ * We split messages that exceed this limit to ensure all logs are captured.
+ */
+const CLOUDWATCH_MAX_LOG_SIZE = 256 * 1024;
+const MESSAGE_SPLIT_OVERHEAD = 2 * 1024;
+const MAX_MESSAGE_SIZE = CLOUDWATCH_MAX_LOG_SIZE - MESSAGE_SPLIT_OVERHEAD;
+const textEncoder = new TextEncoder();
+const transport = isDevelopment
+    ? {
+        target: "pino-pretty",
+        options: {
+            colorize: true,
+            translateTime: "SYS:standard",
+            ignore: "pid,hostname",
+        },
+    }
+    : undefined;
+function getTimestamp() {
+    return `,"time":"${(0, date_fns_1.formatISO)(new Date())}"`;
+}
+const redactPaths = [
+    "password",
+    "token",
+    "apiKey",
+    "secret",
+    "authorization",
+    "cookie",
+    "*.password",
+    "*.token",
+    "*.apiKey",
+    "*.secret",
+    "*.authorization",
+    "req.headers.authorization",
+    "req.headers.cookie",
+];
+// Emit `level` as its string label rather than pino's numeric default;
+// log aggregators (Datadog, CloudWatch Insights) filter on strings.
+const formatters = {
+    level: (label) => {
+        return { level: label };
+    },
+};
+/**
+ * Splits a message that exceeds CloudWatch's 256KB per-event cap. Prefers
+ * newline / space boundaries so chunks stay readable; falls back to a
+ * UTF-8-safe byte boundary so we don't slice through a multi-byte char.
+ *
+ * Exported for direct testing — the runtime emit path runs through a
+ * silent pino in NODE_ENV=test, so chunking is otherwise unobservable.
+ * Callers outside this module should use the logger methods instead.
+ */
+function splitLargeMessage(message, maxSize = MAX_MESSAGE_SIZE) {
+    const messageSize = textEncoder.encode(message).length;
+    if (messageSize <= maxSize) {
+        return [message];
+    }
+    const splitPoint = findSplitPoint(message, maxSize);
+    const firstChunk = message.slice(0, splitPoint);
+    const remainingMessage = message.slice(splitPoint);
+    return [firstChunk, ...splitLargeMessage(remainingMessage, maxSize)];
+}
+function findSplitPoint(message, maxSize) {
+    const newlineIndex = message.lastIndexOf("\n", maxSize);
+    const spaceIndex = message.lastIndexOf(" ", maxSize);
+    const halfMax = maxSize / 2;
+    if (newlineIndex > halfMax) {
+        return newlineIndex + 1;
+    }
+    if (spaceIndex > halfMax) {
+        return spaceIndex + 1;
+    }
+    return findCharacterBoundary(message, maxSize);
+}
+function findCharacterBoundary(message, maxSize) {
+    // Iterate by full code points (not UTF-16 code units) so surrogate
+    // pairs stay intact. `message[i]` returns a code unit — for emoji
+    // like 🎉 that's the high surrogate alone, which TextEncoder encodes
+    // as the 3-byte U+FFFD replacement character. A per-code-unit split
+    // could land between the pair and corrupt the character in the log.
+    let lastSafeCodeUnitIndex = 0;
+    let byteCount = 0;
+    let cuIndex = 0;
+    for (const char of message) {
+        const charCode = char.codePointAt(0) ?? 0;
+        const charSize = charCode < 128 ? 1 : textEncoder.encode(char).length;
+        if (byteCount + charSize > maxSize) {
+            break;
+        }
+        byteCount += charSize;
+        cuIndex += char.length;
+        lastSafeCodeUnitIndex = cuIndex;
+    }
+    return lastSafeCodeUnitIndex || 1;
+}
+function getChunkPrefix(index, totalChunks) {
+    return totalChunks > 1 ? `[${index + 1}/${totalChunks}] ` : "";
+}
+function logWithSplitting(originalLogFn, obj, ...args) {
+    if (typeof obj === "string") {
+        const chunks = splitLargeMessage(obj);
+        chunks.forEach((chunk, index) => {
+            const prefix = getChunkPrefix(index, chunks.length);
+            originalLogFn(`${prefix}${chunk}`, ...args);
+        });
+    }
+    else {
+        originalLogFn(obj, ...args);
+    }
+}
+function getLogName(name, appName) {
+    return `${appName}://${name}`;
+}
+/**
+ * Wraps a pino logger with the project's extended Logger interface: CloudWatch
+ * message splitting on every level method, and `errorWithStack` for one-line
+ * error logs that include the stack inline. Used internally by `getLogger` and
+ * exported so callers with an existing pino instance (e.g. `request.log`) can
+ * promote it to the full Logger contract without creating a new logger.
+ */
+function extendLogger(logger) {
+    const extendedLogger = logger;
+    const originalInfo = extendedLogger.info.bind(extendedLogger);
+    const originalError = extendedLogger.error.bind(extendedLogger);
+    const originalWarn = extendedLogger.warn.bind(extendedLogger);
+    const originalDebug = extendedLogger.debug.bind(extendedLogger);
+    extendedLogger.info = (obj, ...args) => {
+        logWithSplitting(originalInfo, obj, ...args);
+    };
+    extendedLogger.error = (obj, ...args) => {
+        logWithSplitting(originalError, obj, ...args);
+    };
+    extendedLogger.warn = (obj, ...args) => {
+        logWithSplitting(originalWarn, obj, ...args);
+    };
+    extendedLogger.debug = (obj, ...args) => {
+        logWithSplitting(originalDebug, obj, ...args);
+    };
+    extendedLogger.errorWithStack = (error, msg) => {
+        const message = error instanceof Error
+            ? `${msg || error.message}: ${error.stack}`
+            : `${msg || JSON.stringify(error)}`;
+        logWithSplitting(originalError, message);
+    };
+    return extendedLogger;
+}
+/**
+ * Returns a pino logger for one-shot CLI scripts. Uses pino-pretty in
+ * development (where the devDependency is installed) and falls back to raw
+ * JSON elsewhere, mirroring `getLogger`'s gating — `pino-pretty` is pruned
+ * from production images, so an unconditional transport crashes on module
+ * load in prod (see the pino-pretty prod-crash incident).
+ */
+function getScriptLogger(name) {
+    return extendLogger((0, pino_1.default)({
+        name: getLogName(name, defaultAppName),
+        level: process.env.LOG_LEVEL ?? "info",
+        transport,
+    }));
+}
+/**
+ * Creates a named pino logger with the project's standard wiring:
+ * pino-pretty transport in dev, JSON in prod, silent in test, secrets
+ * redacted, and every string message auto-chunked under CloudWatch's
+ * 256KB event cap. `name` appears as `{appName}://{name}` on every line.
+ */
+function getLogger({ name, level }) {
+    const options = {
+        name: getLogName(name, defaultAppName),
+        level: isTest ? "silent" : level || defaultLoggingLevel,
+        base: {
+            appName: defaultAppName,
+            env: nodeEnv,
+            ...(ddEnabled && {
+                dd: {
+                    service: (0, env_1.getEnv)("DD_SERVICE", "barnacle"),
+                    version: (0, env_1.getEnv)("DD_VERSION", "0.1.0"),
+                    env: (0, env_1.getEnv)("DD_ENV", nodeEnv),
+                },
+            }),
+        },
+        timestamp: getTimestamp,
+        formatters,
+        mixin: ddEnabled ? ddMixin : undefined,
+        redact: {
+            paths: redactPaths,
+            censor: "[REDACTED]",
+        },
+        transport,
+    };
+    return extendLogger((0, pino_1.default)(options));
+}
+function ddMixin() {
+    const span = datadog_1.tracer.scope().active();
+    if (!span)
+        return {};
+    const ctx = span.context();
+    return { "dd.trace_id": ctx.toTraceId(), "dd.span_id": ctx.toSpanId() };
+}
+//# sourceMappingURL=logging.js.map

package/dist/lib/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/lib/logging.ts"],"names":[],"mappings":"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"}

package/dist/lib/multipart.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RFC 7578 multipart/form-data byte-assembly primitives.
+ *
+ * Site-agnostic helpers for hand-building multipart bodies without the
+ * browser FormData API. Boundary generation follows WebKit's convention
+ * (`----WebKitFormBoundary` + 16 lowercase hex chars) so servers that
+ * parse the Content-Type boundary token recognise it as a browser upload.
+ */
+/**
+ * Generate a fresh multipart boundary using the WebKit convention.
+ * The prefix makes the boundary recognisable to parsers that inspect
+ * the User-Agent, and the 8 random bytes (16 hex chars) make collisions
+ * astronomically unlikely within a single request body.
+ */
+export declare function makeBoundary(): string;
+/**
+ * Append a `name=value` text part to the running parts list.
+ * Separating each part into a discrete push keeps the buffer assembly
+ * testable and avoids string-concatenating binary-adjacent content.
+ */
+export declare function appendTextPart(parts: Buffer[], boundary: string, name: string, value: string): void;
+/**
+ * Append a file part to the running parts list. The `filename=` token
+ * on the Content-Disposition header is what distinguishes a file part
+ * from a plain text part per RFC 7578 §4.2.
+ */
+export declare function appendFilePart(parts: Buffer[], boundary: string, name: string, filename: string, contentType: string, bytes: Buffer): void;
+/**
+ * Append the RFC 7578 §4.1 closing boundary marker (`--boundary--\r\n`).
+ * The trailing `--` after the boundary value is load-bearing: parsers
+ * that stream the body will wait for more parts if it is absent.
+ */
+export declare function appendClosingBoundary(parts: Buffer[], boundary: string): void;
+//# sourceMappingURL=multipart.d.ts.map

package/dist/lib/multipart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/lib/multipart.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,IAAI,CAIN;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,IAAI,CAQN;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE7E"}

package/dist/lib/multipart.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * RFC 7578 multipart/form-data byte-assembly primitives.
+ *
+ * Site-agnostic helpers for hand-building multipart bodies without the
+ * browser FormData API. Boundary generation follows WebKit's convention
+ * (`----WebKitFormBoundary` + 16 lowercase hex chars) so servers that
+ * parse the Content-Type boundary token recognise it as a browser upload.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeBoundary = makeBoundary;
+exports.appendTextPart = appendTextPart;
+exports.appendFilePart = appendFilePart;
+exports.appendClosingBoundary = appendClosingBoundary;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Generate a fresh multipart boundary using the WebKit convention.
+ * The prefix makes the boundary recognisable to parsers that inspect
+ * the User-Agent, and the 8 random bytes (16 hex chars) make collisions
+ * astronomically unlikely within a single request body.
+ */
+function makeBoundary() {
+    return `----WebKitFormBoundary${(0, node_crypto_1.randomBytes)(8).toString("hex")}`;
+}
+/**
+ * Append a `name=value` text part to the running parts list.
+ * Separating each part into a discrete push keeps the buffer assembly
+ * testable and avoids string-concatenating binary-adjacent content.
+ */
+function appendTextPart(parts, boundary, name, value) {
+    parts.push(Buffer.from(`--${boundary}\r\n`));
+    parts.push(Buffer.from(`Content-Disposition: form-data; name="${name}"\r\n\r\n`));
+    parts.push(Buffer.from(`${value}\r\n`));
+}
+/**
+ * Append a file part to the running parts list. The `filename=` token
+ * on the Content-Disposition header is what distinguishes a file part
+ * from a plain text part per RFC 7578 §4.2.
+ */
+function appendFilePart(parts, boundary, name, filename, contentType, bytes) {
+    parts.push(Buffer.from(`--${boundary}\r\n`));
+    parts.push(Buffer.from(`Content-Disposition: form-data; name="${name}"; filename="${filename}"\r\n`));
+    parts.push(Buffer.from(`Content-Type: ${contentType}\r\n\r\n`));
+    parts.push(bytes);
+    parts.push(Buffer.from("\r\n"));
+}
+/**
+ * Append the RFC 7578 §4.1 closing boundary marker (`--boundary--\r\n`).
+ * The trailing `--` after the boundary value is load-bearing: parsers
+ * that stream the body will wait for more parts if it is absent.
+ */
+function appendClosingBoundary(parts, boundary) {
+    parts.push(Buffer.from(`--${boundary}--\r\n`));
+}
+//# sourceMappingURL=multipart.js.map

package/dist/lib/multipart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.js","sourceRoot":"","sources":["../../src/lib/multipart.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAUH,oCAEC;AAOD,wCASC;AAOD,wCAeC;AAOD,sDAEC;AAzDD,6CAA0C;AAE1C;;;;;GAKG;AACH,SAAgB,YAAY;IAC1B,OAAO,yBAAyB,IAAA,yBAAW,EAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAC5B,KAAe,EACf,QAAgB,EAChB,IAAY,EACZ,KAAa;IAEb,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,QAAQ,MAAM,CAAC,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yCAAyC,IAAI,WAAW,CAAC,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAC5B,KAAe,EACf,QAAgB,EAChB,IAAY,EACZ,QAAgB,EAChB,WAAmB,EACnB,KAAa;IAEb,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,QAAQ,MAAM,CAAC,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CACR,MAAM,CAAC,IAAI,CAAC,yCAAyC,IAAI,gBAAgB,QAAQ,OAAO,CAAC,CAC1F,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,WAAW,UAAU,CAAC,CAAC,CAAC;IAChE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,KAAe,EAAE,QAAgB;IACrE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,QAAQ,QAAQ,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/lib/option-matcher.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Known synonyms keyed by their canonical option value (lowercased).
+ * When a payload sends a synonym, we return the canonical option.
+ */
+export declare const SEMANTIC_EQUIVALENCES: Record<string, string[]>;
+/**
+ * Match a raw value against a question's allowed options. Dropdown questions
+ * on ATS forms require the submitted value to be one of the declared options —
+ * sending an out-of-list value typically causes a server error.
+ *
+ * Matching cascade: exact → case-insensitive → US state name→abbrev →
+ * semantic equivalence → substring containment → fallback to first option.
+ */
+export declare function matchToOptions(rawValue: string, options: unknown[]): string;
+//# sourceMappingURL=option-matcher.d.ts.map

package/dist/lib/option-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"option-matcher.d.ts","sourceRoot":"","sources":["../../src/lib/option-matcher.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAe1D,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAmC3E"}