@enricai/barnacle 1.0.0

package/dist/scripts/smoke-test.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type FastifyInstance, type RawServerDefault } from "fastify";
+import type { Logger } from "./types/logging";
+/**
+ * Builds a configured (but not-yet-listening) Fastify instance. Split out
+ * from `main()` so tests can call `buildServer()` and use `inject()`
+ * instead of binding to a port.
+ */
+export declare function buildServer(): Promise<FastifyInstance<RawServerDefault, IncomingMessage, ServerResponse, Logger>>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMjE,OAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAqB/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAM9C;;;;GAIG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAC1C,eAAe,CAAC,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,CAAC,CAC3E,CA6GA"}

package/dist/server.js

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServer = buildServer;
+const node_crypto_1 = require("node:crypto");
+const compress_1 = __importDefault(require("@fastify/compress"));
+const helmet_1 = __importDefault(require("@fastify/helmet"));
+const rate_limit_1 = __importDefault(require("@fastify/rate-limit"));
+const swagger_1 = __importDefault(require("@fastify/swagger"));
+const swagger_ui_1 = __importDefault(require("@fastify/swagger-ui"));
+const fastify_1 = __importDefault(require("fastify"));
+const fastify_type_provider_zod_1 = require("fastify-type-provider-zod");
+const auth_1 = __importDefault(require("./api/plugins/auth"));
+const error_handler_1 = __importDefault(require("./api/plugins/error-handler"));
+const request_context_1 = __importDefault(require("./api/plugins/request-context"));
+const health_1 = require("./api/routes/health");
+const plugins_introspection_1 = require("./api/routes/plugins-introspection");
+const config_1 = require("./config");
+const errors_1 = require("./lib/errors");
+const http_1 = require("./lib/http");
+const logging_1 = require("./lib/logging");
+const statsd_1 = require("./lib/statsd");
+const s3_sink_1 = require("./lib/telemetry/s3-sink");
+const tracking_click_1 = require("./lib/tracking-click");
+const discover_1 = require("./plugins/discover");
+const loader_1 = require("./plugins/loader");
+const pool_1 = require("./scraper/pool");
+const logger = (0, logging_1.getLogger)({ name: "server" });
+(0, http_1.configureHttpDispatcher)();
+/**
+ * Builds a configured (but not-yet-listening) Fastify instance. Split out
+ * from `main()` so tests can call `buildServer()` and use `inject()`
+ * instead of binding to a port.
+ */
+async function buildServer() {
+    // Load a fresh config per build so tests can toggle env vars between
+    // buildServer() invocations. The exported `defaultConfig` is still
+    // used for module-level pieces (logger) that are process-wide.
+    const cfg = (0, config_1.loadConfig)();
+    const app = (0, fastify_1.default)({
+        loggerInstance: logger,
+        disableRequestLogging: false,
+        // TRUST_PROXY=true is correct when behind a reverse proxy (ALB,
+        // nginx, Cloudflare) — Fastify reads the real client IP from
+        // X-Forwarded-For. Set TRUST_PROXY=false for bare-metal deployments
+        // so attackers can't spoof the header to bypass IP-based rate
+        // limiting on unauthenticated traffic.
+        trustProxy: cfg.trustProxy,
+        ajv: { customOptions: { strict: false } },
+    });
+    app.setValidatorCompiler(fastify_type_provider_zod_1.validatorCompiler);
+    app.setSerializerCompiler(fastify_type_provider_zod_1.serializerCompiler);
+    await app.register(helmet_1.default, {
+        contentSecurityPolicy: false,
+    });
+    await app.register(compress_1.default, { encodings: ["gzip", "br"] });
+    await app.register(rate_limit_1.default, {
+        global: true,
+        max: cfg.rateLimit.max,
+        timeWindow: cfg.rateLimit.windowMs,
+        keyGenerator: (request) => {
+            // Rate-limit runs in onRequest, before auth populates the
+            // fingerprint — so we key off the raw Authorization header here.
+            // Hashing it first keeps plaintext tokens out of the rate-limit
+            // plugin's in-memory key→count map.
+            const auth = request.headers.authorization;
+            if (typeof auth === "string" && auth.length > 0) {
+                return (0, node_crypto_1.createHash)("sha256").update(auth).digest("hex");
+            }
+            return request.ip;
+        },
+        // We don't pass a custom errorResponseBuilder — fastify-rate-limit
+        // throws a FastifyError with statusCode=429 which our setErrorHandler
+        // catches and emits as the error envelope (code 1010). Keeping a single
+        // error-rendering path avoids schema-serializer mismatches.
+    });
+    await app.register(request_context_1.default);
+    await app.register(error_handler_1.default);
+    await app.register(auth_1.default);
+    if (cfg.docs.enabled) {
+        await app.register(swagger_1.default, {
+            openapi: {
+                openapi: "3.1.0",
+                info: {
+                    title: "Barnacle Automation API",
+                    description: "Site-agnostic browser automation engine. POST a structured payload to a typed endpoint; Barnacle drives a Steel + Stagehand session through the target site and returns a structured result via a plugin adapter.",
+                    version: "0.1.0",
+                },
+                servers: [{ url: `http://${cfg.host}:${cfg.port}` }],
+                components: {
+                    securitySchemes: {
+                        bearerAuth: { type: "http", scheme: "bearer" },
+                    },
+                },
+            },
+            transform: fastify_type_provider_zod_1.jsonSchemaTransform,
+        });
+        await app.register(swagger_ui_1.default, { routePrefix: "/docs" });
+    }
+    const { plugins, report } = await (0, discover_1.loadAllPlugins)(cfg);
+    await app.register(health_1.healthRoutes);
+    await (0, loader_1.registerRoutes)(app, cfg, plugins);
+    await app.register(plugins_introspection_1.pluginsIntrospectionRoutes, { report });
+    (0, s3_sink_1.startS3SinkTimer)();
+    // Drain in-flight scrape sessions when the app shuts down. Without
+    // this, SIGTERM leaves Steel sessions alive until their own idle
+    // timeout kicks in (billable minutes wasted).
+    app.addHook("onClose", async () => {
+        try {
+            await (0, pool_1.drainPool)();
+        }
+        catch (err) {
+            logger.warn(`drainPool failed during shutdown: ${(0, errors_1.toErrorMessage)(err).slice(0, 200)}`);
+        }
+        try {
+            await (0, tracking_click_1.drainTrackingClicks)();
+        }
+        catch (err) {
+            logger.warn(`drainTrackingClicks failed during shutdown: ${(0, errors_1.toErrorMessage)(err).slice(0, 200)}`);
+        }
+        try {
+            await (0, statsd_1.shutdownStatsD)();
+        }
+        catch (err) {
+            logger.warn(`shutdownStatsD failed during shutdown: ${(0, errors_1.toErrorMessage)(err).slice(0, 200)}`);
+        }
+        try {
+            await (0, s3_sink_1.shutdownS3Sink)();
+        }
+        catch (err) {
+            logger.warn(`shutdownS3Sink failed during shutdown: ${(0, errors_1.toErrorMessage)(err).slice(0, 200)}`);
+        }
+    });
+    return app;
+}
+/**
+ * Boots the HTTP server. Entry point for `pnpm run dev` and `pnpm start`.
+ */
+async function main() {
+    const app = await buildServer();
+    try {
+        await app.listen({ host: config_1.config.host, port: config_1.config.port });
+        logger.info(`server listening on http://${config_1.config.host}:${config_1.config.port}`);
+    }
+    catch (err) {
+        logger.errorWithStack(err, "server failed to start");
+        process.exit(1);
+    }
+    // Guard against double signals — an impatient orchestrator sending
+    // SIGTERM twice while the first shutdown is mid-flight would spawn a
+    // second concurrent shutdown, racing `app.close()` and `process.exit()`.
+    // The flag makes subsequent signals idempotent: log-and-ignore.
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown) {
+            logger.info(`received ${signal} during shutdown — ignoring`);
+            return;
+        }
+        shuttingDown = true;
+        logger.info(`received ${signal}, shutting down`);
+        try {
+            await app.close();
+            process.exit(0);
+        }
+        catch (err) {
+            logger.errorWithStack(err, "graceful shutdown failed");
+            process.exit(1);
+        }
+    };
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    // Last-line-of-defense for errors escaping every `try` boundary.
+    process.on("uncaughtException", (err) => {
+        logger.errorWithStack(err, "uncaughtException — process will exit");
+        process.exit(1);
+    });
+    process.on("unhandledRejection", (reason) => {
+        const err = reason instanceof Error ? reason : new Error(String(reason));
+        logger.errorWithStack(err, "unhandledRejection — process will exit");
+        process.exit(1);
+    });
+}
+const entry = process.argv[1];
+if (entry && (entry.endsWith("server.ts") || entry.endsWith("server.js"))) {
+    void main();
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;;;;AAuCA,kCA+GC;AAtJD,6CAAyC;AAEzC,iEAAgD;AAChD,6DAA4C;AAC5C,qEAAmD;AACnD,+DAA8C;AAC9C,qEAAmD;AACnD,sDAA+E;AAC/E,yEAImC;AACnC,8DAA4C;AAC5C,gFAA6D;AAC7D,oFAAiE;AACjE,gDAAmD;AACnD,8EAAgF;AAChF,qCAA+D;AAC/D,yCAA8C;AAC9C,qCAAqD;AACrD,2CAA0C;AAC1C,yCAA8C;AAC9C,qDAA2E;AAC3E,yDAA2D;AAC3D,iDAAoD;AACpD,6CAAkD;AAClD,yCAA2C;AAG3C,MAAM,MAAM,GAAG,IAAA,mBAAS,EAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE7C,IAAA,8BAAuB,GAAE,CAAC;AAE1B;;;;GAIG;AACI,KAAK,UAAU,WAAW;IAG/B,qEAAqE;IACrE,mEAAmE;IACnE,+DAA+D;IAC/D,MAAM,GAAG,GAAG,IAAA,mBAAU,GAAE,CAAC;IAEzB,MAAM,GAAG,GAAG,IAAA,iBAAO,EAAC;QAClB,cAAc,EAAE,MAAM;QACtB,qBAAqB,EAAE,KAAK;QAC5B,gEAAgE;QAChE,6DAA6D;QAC7D,oEAAoE;QACpE,8DAA8D;QAC9D,uCAAuC;QACvC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,GAAG,EAAE,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;KAC1C,CAAC,CAAC;IAEH,GAAG,CAAC,oBAAoB,CAAC,6CAAiB,CAAC,CAAC;IAC5C,GAAG,CAAC,qBAAqB,CAAC,8CAAkB,CAAC,CAAC;IAE9C,MAAM,GAAG,CAAC,QAAQ,CAAC,gBAAa,EAAE;QAChC,qBAAqB,EAAE,KAAK;KAC7B,CAAC,CAAC;IACH,MAAM,GAAG,CAAC,QAAQ,CAAC,kBAAe,EAAE,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAEnE,MAAM,GAAG,CAAC,QAAQ,CAAC,oBAAgB,EAAE;QACnC,MAAM,EAAE,IAAI;QACZ,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,GAAG;QACtB,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,QAAQ;QAClC,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE;YACxB,0DAA0D;YAC1D,iEAAiE;YACjE,gEAAgE;YAChE,oCAAoC;YACpC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;YAC3C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChD,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,CAAC;YACD,OAAO,OAAO,CAAC,EAAE,CAAC;QACpB,CAAC;QACD,mEAAmE;QACnE,sEAAsE;QACtE,wEAAwE;QACxE,4DAA4D;KAC7D,CAAC,CAAC;IAEH,MAAM,GAAG,CAAC,QAAQ,CAAC,yBAAoB,CAAC,CAAC;IACzC,MAAM,GAAG,CAAC,QAAQ,CAAC,uBAAkB,CAAC,CAAC;IACvC,MAAM,GAAG,CAAC,QAAQ,CAAC,cAAU,CAAC,CAAC;IAE/B,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,GAAG,CAAC,QAAQ,CAAC,iBAAc,EAAE;YACjC,OAAO,EAAE;gBACP,OAAO,EAAE,OAAO;gBAChB,IAAI,EAAE;oBACJ,KAAK,EAAE,yBAAyB;oBAChC,WAAW,EACT,mNAAmN;oBACrN,OAAO,EAAE,OAAO;iBACjB;gBACD,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,UAAU,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;gBACpD,UAAU,EAAE;oBACV,eAAe,EAAE;wBACf,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE;qBAC/C;iBACF;aACF;YACD,SAAS,EAAE,+CAAmB;SAC/B,CAAC,CAAC;QACH,MAAM,GAAG,CAAC,QAAQ,CAAC,oBAAgB,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,IAAA,yBAAc,EAAC,GAAG,CAAC,CAAC;IACtD,MAAM,GAAG,CAAC,QAAQ,CAAC,qBAAY,CAAC,CAAC;IACjC,MAAM,IAAA,uBAAc,EAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,GAAG,CAAC,QAAQ,CAAC,kDAA0B,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAE3D,IAAA,0BAAgB,GAAE,CAAC;IAEnB,mEAAmE;IACnE,iEAAiE;IACjE,8CAA8C;IAC9C,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAChC,IAAI,CAAC;YACH,MAAM,IAAA,gBAAS,GAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,qCAAqC,IAAA,uBAAc,EAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAA,oCAAmB,GAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CACT,+CAA+C,IAAA,uBAAc,EAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACnF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAA,uBAAc,GAAE,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,0CAA0C,IAAA,uBAAc,EAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAA,wBAAc,GAAE,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,0CAA0C,IAAA,uBAAc,EAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,GAAG,GAAG,MAAM,WAAW,EAAE,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,eAAa,CAAC,IAAI,EAAE,IAAI,EAAE,eAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QACzE,MAAM,CAAC,IAAI,CAAC,8BAA8B,eAAa,CAAC,IAAI,IAAI,eAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IACxF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,mEAAmE;IACnE,qEAAqE;IACrE,yEAAyE;IACzE,gEAAgE;IAChE,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAiB,EAAE;QACvD,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,CAAC,IAAI,CAAC,YAAY,MAAM,6BAA6B,CAAC,CAAC;YAC7D,OAAO;QACT,CAAC;QACD,YAAY,GAAG,IAAI,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,YAAY,MAAM,iBAAiB,CAAC,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,0BAA0B,CAAC,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACtD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEpD,iEAAiE;IACjE,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACtC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,uCAAuC,CAAC,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;QAC1C,MAAM,GAAG,GAAG,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACzE,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,wCAAwC,CAAC,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9B,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;IAC1E,KAAK,IAAI,EAAE,CAAC;AACd,CAAC"}

package/dist/site-plugin.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Contract every site plugin implements and that core's dispatch layer consumes.
+ * Lives at the top of `src/` alongside `config.ts` and `server.ts` because it
+ * is engine-level infrastructure, not site-specific logic — any new site drops
+ * a plugin into `src/sites/<id>/` and satisfies this interface without touching
+ * core.
+ *
+ * All imports are type-only: this file has zero runtime side effects and is safe
+ * to import from any layer without pulling in browser or config initialization.
+ */
+import type { ZodType } from "zod/v4";
+import type { AppConfig } from "./config";
+import type { MetricsCollector } from "./lib/dispatch-metrics";
+import type { ScraperError } from "./scraper/errors";
+import type { BrowserSession } from "./scraper/session";
+import type { DispatchMetrics } from "./types/dispatch-metrics";
+import type { Logger } from "./types/logging";
+/**
+ * Minimal request surface exposed to extra-route handlers. Core passes a
+ * Fastify `FastifyRequest` here; the interface is narrowed so handlers stay
+ * decoupled from Fastify internals and testable with plain objects.
+ */
+export interface SitePluginExtraRouteRequest<TBody = unknown, TParams = Record<string, string>> {
+    /** Parsed and Zod-validated request body. Present when `bodySchema` is set on the route. */
+    body: TBody;
+    /** Parsed and Zod-validated route params. Present when `paramsSchema` is set on the route. */
+    params: TParams;
+    /** Request-scoped Fastify/Pino logger. */
+    log: Logger;
+}
+/**
+ * Declares one extra non-run route a plugin owns. Core iterates
+ * `meta.extraRoutes` at startup and registers each as an authenticated Fastify
+ * route, building the same `SitePluginContext` it uses for `/run`.
+ *
+ * Error rendering is always delegated to the app-level `errorHandlerPlugin` —
+ * handlers throw typed `ApiError`s; never return error shapes directly.
+ * `envelope` governs only the success reply shape.
+ */
+export interface SitePluginExtraRoute {
+    /** HTTP method for the route (lowercase). */
+    method: "get" | "post" | "put" | "patch" | "delete";
+    /**
+     * Absolute route path (e.g. `/v1/my-site/trigger-otp`). Core registers it
+     * verbatim — no prefix is added.
+     */
+    path: string;
+    /** Zod schema for the request body. When absent, the body is not validated. */
+    bodySchema?: ZodType;
+    /** Zod schema for route path params. When absent, params are not validated. */
+    paramsSchema?: ZodType;
+    /**
+     * When true, the route accepts `multipart/form-data`. Core ensures
+     * `@fastify/multipart` is registered when any plugin declares a multipart
+     * extra route.
+     */
+    multipart?: boolean;
+    /**
+     * When false, the handler's return value is sent as-is (raw reply). When
+     * true or absent, core wraps the return value in the standard success
+     * envelope. Defaults to true.
+     */
+    envelope?: boolean;
+    /** Handles the request and returns the (pre-envelope) response body. */
+    handler(request: SitePluginExtraRouteRequest, context: SitePluginContext): Promise<unknown>;
+}
+/**
+ * Static metadata that core reads at startup to register the plugin's Fastify
+ * route. Separating metadata from `execute()` lets the loader validate config
+ * and build routes before any session is acquired.
+ */
+export interface SitePluginMeta {
+    /** Stable identifier used as the `config.scraper.siteBaseUrls` lookup key. */
+    siteId: string;
+    /** Human-readable label used in logs and Swagger docs. */
+    displayName: string;
+    /** Zod schema for the route request body — validated by core before execute(). */
+    bodySchema: ZodType;
+    /** Zod schema for the successful response body — drives the Swagger response shape. */
+    responseSchema: ZodType;
+    /**
+     * Full route path override. When set, the loader uses this verbatim instead
+     * of `/v1/{siteId}/run`. Intended for legacy compatibility where an existing
+     * client contract cannot change.
+     */
+    routeOverride?: string;
+    /**
+     * Fallback base URL used by the loader when `config.scraper.siteBaseUrls[siteId]`
+     * is absent. Plugins read their own env vars here so core config stays generic.
+     */
+    defaultBaseUrl?: string;
+    /**
+     * Per-task hard timeout in ms passed to the pool's runWithSession.
+     * Overrides the pool's 60-minute default. Only set when a plugin needs
+     * a shorter ceiling than the default.
+     */
+    taskTimeoutMs?: number;
+    /**
+     * When true, the loader registers the route to accept `multipart/form-data`
+     * via `@fastify/multipart` in `attachFieldsToBody: 'keyValues'` mode. Text
+     * parts arrive as strings on `request.body`; file parts arrive as `Buffer`s.
+     * Generator emits this for flows whose recon includes a binary upload step.
+     */
+    multipart?: boolean;
+    /**
+     * When true, sessions allocated for this plugin's browser fallback opt
+     * into Browserbase's Scale Plan stealth profile (Windows desktop fingerprint
+     * + solveCaptchas). DataDome-protected flows (notably apply.appcast.io
+     * postings) need this to clear the silent fingerprint wall. Defaults to
+     * false to avoid the cost penalty on plugins that don't need it.
+     */
+    advancedStealth?: boolean;
+    /**
+     * Optional semver range string declaring which plugin API version this plugin
+     * targets (e.g. `"^1.0.0"`). Core compares this against `PLUGIN_API_VERSION`
+     * at load time and disables the plugin on a major-version mismatch. Absent
+     * means "accept any version."
+     */
+    apiVersion?: string;
+    /**
+     * Extra non-run routes this plugin owns (e.g. OTP trigger, resume). Core
+     * registers each at startup as an authenticated Fastify route, building the
+     * same `SitePluginContext` as for `/run`. Error rendering is always delegated
+     * to the app-level error handler; `envelope` on each route governs only the
+     * success reply.
+     */
+    extraRoutes?: readonly SitePluginExtraRoute[];
+}
+/**
+ * Runtime dependencies injected by core immediately before `execute()` is called.
+ * Plugins receive this instead of importing config or loggers directly, which
+ * keeps each plugin self-contained and testable without the full app wired up.
+ */
+export interface SitePluginContext {
+    /**
+     * Resolved from `config.scraper.siteBaseUrls[meta.siteId]` by core. Plugins
+     * should use this rather than reading config directly to stay decoupled from
+     * the config shape.
+     */
+    baseUrl: string;
+    /**
+     * Request-scoped logger with `siteId` and `requestId` already bound by core.
+     * Plugins log here without needing to create or configure their own logger.
+     */
+    logger: Logger;
+    /**
+     * Full application config. Prefer `baseUrl` for site URL resolution; reach
+     * into `config` only for cross-cutting settings (timeouts, feature flags, etc.)
+     * that core does not already surface through the context.
+     */
+    config: AppConfig;
+    /**
+     * Fastify-issued correlation ID for this inbound request. Core threads it
+     * into the submission-envelope telemetry record so downstream tooling can
+     * tie a captured outcome back to the originating API call.
+     */
+    requestId: string;
+    /**
+     * Step-timing accumulator for the current dispatch. Plugins call
+     * `metricsCollector.startStep()` / `endStep()` at phase boundaries;
+     * core finalizes and attaches the result to the response envelope.
+     */
+    metricsCollector: MetricsCollector;
+}
+/**
+ * Value returned by `execute()` and consumed by core's dispatch layer. Core
+ * merges `data` into the response envelope and emits a `submission-envelope`
+ * telemetry record carrying `auditPayload` so audit and replay work without
+ * re-running the browser flow.
+ */
+export interface SitePluginResult<TData = Record<string, unknown>> {
+    /** Merged verbatim into the response envelope by core. */
+    data: TData;
+    /**
+     * Written to the `submission-envelope` telemetry record by core. If absent, core
+     * writes `data` instead. Intentionally not generic so plugins can redact PII
+     * freely — only `Record<string, unknown>` is required, not a shape that
+     * matches `TData`.
+     */
+    auditPayload?: Record<string, unknown>;
+    /**
+     * Step-level dispatch metrics attached by core after finalize(). Included in
+     * the response envelope so Vivian can forward into Segment events for A/B
+     * warehouse analysis.
+     */
+    metrics?: DispatchMetrics;
+}
+/**
+ * Contract every site plugin must satisfy. Core's dispatch layer types its
+ * `SITE_PLUGINS` registry and `dispatch()` function against this interface so
+ * adding a new site never requires changes to core — only a new file in
+ * `src/sites/<id>/`.
+ */
+export interface SitePlugin<TPayload = unknown, TResult = Record<string, unknown>> {
+    /** Static metadata used by the loader to register this plugin's Fastify route. */
+    meta: SitePluginMeta;
+    /**
+     * Optional direct-HTTP hot path. When present, dispatch() tries this first.
+     * On `HttpSchemaError`, `HttpBotChallengeError`, or `HttpServerError` it falls
+     * through to `execute()` automatically — the plugin never has to wire the
+     * fallback itself.
+     *
+     * Use `createHttpClient()` from `src/scraper/http-client.ts` to get a typed
+     * fetch wrapper pre-wired with Bottleneck rate-limiting and Zod boundary
+     * parsing. No browser, no LLM tokens — millisecond latency when it works.
+     */
+    executeHttp?: (payload: TPayload, context: SitePluginContext) => Promise<SitePluginResult<TResult>>;
+    /**
+     * Performs the full browser-automation flow for one submission. Core acquires
+     * `session` from the pool and injects `context` before calling this; the plugin
+     * must not create or close sessions itself.
+     *
+     * Invoked automatically when `executeHttp` is absent or when it throws
+     * `HttpSchemaError`, `HttpBotChallengeError`, or `HttpServerError`.
+     */
+    execute(payload: TPayload, session: BrowserSession, context: SitePluginContext): Promise<SitePluginResult<TResult>>;
+    /**
+     * Optional hook called by core's retry layer before each retry attempt. Plugins
+     * use this for telemetry or local cleanup (e.g. resetting in-memory state).
+     * Async work is supported. Note: this hook is NOT called on `CaptchaError` or
+     * `EmptyResultsError` — p-retry skips `onFailedAttempt` for AbortError, so
+     * those abort paths bypass this hook entirely.
+     */
+    onRetry?: (error: ScraperError, attempt: number) => void | Promise<void>;
+}
+//# sourceMappingURL=site-plugin.d.ts.map

package/dist/site-plugin.d.ts.map

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

package/dist/site-plugin.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Contract every site plugin implements and that core's dispatch layer consumes.
+ * Lives at the top of `src/` alongside `config.ts` and `server.ts` because it
+ * is engine-level infrastructure, not site-specific logic — any new site drops
+ * a plugin into `src/sites/<id>/` and satisfies this interface without touching
+ * core.
+ *
+ * All imports are type-only: this file has zero runtime side effects and is safe
+ * to import from any layer without pulling in browser or config initialization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=site-plugin.js.map

package/dist/site-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-plugin.js","sourceRoot":"","sources":["../src/site-plugin.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/dist/testing/answers-fixture.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical ApplicationAnswers fixture for all plugin tests. Centralised so
+ * a 21-field answer block is defined once and downstream consumers spread +
+ * override the handful of fields they assert differently — a field-type change
+ * or new tenant default is a one-edit propagation.
+ *
+ * Values are seeded from the AppCast/Encompass Health recon run so they satisfy
+ * every tenant-level question the question-mapper knows about. Demographic
+ * fields default to the least-disclosing option ("Prefer not to say").
+ */
+import type { ApplicationAnswers } from "../lib/application-answers";
+export declare const TEST_ANSWERS: ApplicationAnswers;
+//# sourceMappingURL=answers-fixture.d.ts.map

package/dist/testing/answers-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answers-fixture.d.ts","sourceRoot":"","sources":["../../src/testing/answers-fixture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,eAAO,MAAM,YAAY,EAAE,kBAsB1B,CAAC"}

package/dist/testing/answers-fixture.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Canonical ApplicationAnswers fixture for all plugin tests. Centralised so
+ * a 21-field answer block is defined once and downstream consumers spread +
+ * override the handful of fields they assert differently — a field-type change
+ * or new tenant default is a one-edit propagation.
+ *
+ * Values are seeded from the AppCast/Encompass Health recon run so they satisfy
+ * every tenant-level question the question-mapper knows about. Demographic
+ * fields default to the least-disclosing option ("Prefer not to say").
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEST_ANSWERS = void 0;
+exports.TEST_ANSWERS = {
+    WorkAuthorization: "Yes",
+    VisaSponsorship: "NA",
+    NonCompete: "No",
+    OIGGSAOFACExcluded: "No",
+    FormerEmployee: "Not Applicable",
+    CurrentNonEmployeeId: "NA",
+    OtherOpportunities: "Yes",
+    RelatedToEmployee: "No",
+    PreviouslyEmployedAtEncompass: "No",
+    EverSanctionedOrOnProbation: "No",
+    EverTerminated: "No",
+    EverExcludedFromFederalProgram: "No",
+    LegallyEligibleToWorkUS: "Yes",
+    CanPerformJobFunctions: "Yes",
+    Gender: "Prefer not to say",
+    Degree: "Nursing",
+    EducationLevel: "Bachelor's Degree",
+    SignatureFullName: "Reginald Reconaldo",
+    MeetsMinimumAge: "Yes",
+    AppliedToSanfordOrGoodSamaritanLast6Months: "No",
+    HasOrWillObtainLicense: "Yes",
+};
+//# sourceMappingURL=answers-fixture.js.map

package/dist/testing/answers-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answers-fixture.js","sourceRoot":"","sources":["../../src/testing/answers-fixture.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAIU,QAAA,YAAY,GAAuB;IAC9C,iBAAiB,EAAE,KAAK;IACxB,eAAe,EAAE,IAAI;IACrB,UAAU,EAAE,IAAI;IAChB,kBAAkB,EAAE,IAAI;IACxB,cAAc,EAAE,gBAAgB;IAChC,oBAAoB,EAAE,IAAI;IAC1B,kBAAkB,EAAE,KAAK;IACzB,iBAAiB,EAAE,IAAI;IACvB,6BAA6B,EAAE,IAAI;IACnC,2BAA2B,EAAE,IAAI;IACjC,cAAc,EAAE,IAAI;IACpB,8BAA8B,EAAE,IAAI;IACpC,uBAAuB,EAAE,KAAK;IAC9B,sBAAsB,EAAE,KAAK;IAC7B,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE,mBAAmB;IACnC,iBAAiB,EAAE,oBAAoB;IACvC,eAAe,EAAE,KAAK;IACtB,0CAA0C,EAAE,IAAI;IAChD,sBAAsB,EAAE,KAAK;CAC9B,CAAC"}

package/dist/testing/batch-email-confirmation.d.ts

@@ -0,0 +1,58 @@
+import type { TestmailInbox, TestmailMessage } from "../testmail/client";
+/**
+ * Outcome of a single job's submit phase: either a successful submit (with
+ * the allocated inbox) or a failed one (with an error message).
+ */
+export type SubmitOutcome = {
+    ok: true;
+    inbox: TestmailInbox;
+    durationMs: number;
+} | {
+    ok: false;
+    error: string;
+    durationMs: number;
+};
+/**
+ * Outcome of a single job's email-poll phase. Only run for jobs that passed
+ * phase 1.
+ */
+export type PollOutcome = {
+    received: true;
+    message: TestmailMessage;
+    waitMs: number;
+} | {
+    received: false;
+    waitMs: number;
+};
+/**
+ * Dependency-injected callbacks that make the harness site-agnostic. Callers
+ * provide the site-specific logic; the harness owns the phase-1/phase-2 loop,
+ * inbox allocation, and summary rendering.
+ */
+export interface BatchEmailConfirmationOptions<TJob, TVerdict> {
+    /** Allocate a fresh testmail inbox for the job. Defaults to testmail client's `allocateTestmailInbox`. */
+    allocateInbox: (job: TJob) => TestmailInbox;
+    /** Submit the job with the given inbox address. Should throw on hard failure, or return a value. */
+    submit: (job: TJob, inbox: TestmailInbox) => Promise<SubmitOutcome>;
+    /**
+     * Poll for a confirmation email in the inbox after a successful submit.
+     * Defaults to 90 s. Should return PollOutcome whether email arrived or not.
+     */
+    pollEmail: (inbox: TestmailInbox) => Promise<PollOutcome>;
+    /** Map the raw phase outcomes into the caller's verdict shape. */
+    mapVerdict: (job: TJob, submitOutcome: SubmitOutcome, pollOutcome: PollOutcome | null) => TVerdict;
+    /** Max parallel phase-1 submits. Default 1 (serial). */
+    concurrency?: number;
+}
+/**
+ * Site-agnostic two-phase batch runner: submit each job with a fresh testmail
+ * inbox (phase 1), then poll each successful inbox for a confirmation email
+ * (phase 2). Returns one verdict per input job.
+ *
+ * Phase separation is intentional — all submits complete before any polling
+ * begins, matching the expected cadence for ATS email confirmations that
+ * arrive seconds after submission. The caller supplies all site-specific
+ * behaviour via injected callbacks.
+ */
+export declare function runBatchEmailConfirmation<TJob, TVerdict>(jobs: TJob[], opts: BatchEmailConfirmationOptions<TJob, TVerdict>): Promise<TVerdict[]>;
+//# sourceMappingURL=batch-email-confirmation.d.ts.map

package/dist/testing/batch-email-confirmation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-email-confirmation.d.ts","sourceRoot":"","sources":["../../src/testing/batch-email-confirmation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIxE;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;;;GAIG;AACH,MAAM,WAAW,6BAA6B,CAAC,IAAI,EAAE,QAAQ;IAC3D,0GAA0G;IAC1G,aAAa,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,aAAa,CAAC;IAC5C,oGAAoG;IACpG,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACpE;;;OAGG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1D,kEAAkE;IAClE,UAAU,EAAE,CACV,GAAG,EAAE,IAAI,EACT,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,WAAW,GAAG,IAAI,KAC5B,QAAQ,CAAC;IACd,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,QAAQ,EAC5D,IAAI,EAAE,IAAI,EAAE,EACZ,IAAI,EAAE,6BAA6B,CAAC,IAAI,EAAE,QAAQ,CAAC,GAClD,OAAO,CAAC,QAAQ,EAAE,CAAC,CAuDrB"}