@enricai/barnacle 1.0.0

package/dist/scraper/errors.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Error hierarchy produced by the scraper. These are internal — they stay
+ * inside the scraper + service layer and are translated into API envelope
+ * errors (via src/api/errors.ts) before they reach the client.
+ *
+ * Why: each class encodes a distinct recovery policy that p-retry and the
+ * session pool key off of. Some failures abort the whole call (no retry
+ * can resolve them); others are retryable in place because a fresh AI
+ * resolution or DOM re-settle usually fixes them; some need a brand-new
+ * Steel session before retrying, in which case retry.ts invokes its
+ * onRestart callback. See each class's TSDoc for its specific policy
+ * and the diagnostic it represents.
+ */
+/**
+ * Base class for all scraper-internal errors. Each subclass encodes a
+ * distinct recovery policy (retryable or not) that retry.ts and loader.ts
+ * key off of to decide whether to retry, restart the session, or abort.
+ */
+export declare abstract class ScraperError extends Error {
+    readonly retryable: boolean;
+    constructor(message: string, retryable: boolean);
+}
+/**
+ * The scraper encountered a CAPTCHA challenge Steel couldn't solve on our
+ * behalf. Propagate upstream as error code 2004.
+ */
+export declare class CaptchaError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * The scrape completed but returned no data. This is not a failure — it's
+ * a legitimate empty result (e.g. a search returned zero matches). The
+ * service layer handles this without throwing.
+ */
+export declare class EmptyResultsError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * Stagehand failed to resolve a selector or an `act()` call. The most
+ * likely cause is that the cached action hash is stale because the target
+ * page's UI changed. Retries bust the cache and fall back to fresh AI inference.
+ */
+export declare class SelectorFailureError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * The upstream Steel browser session timed out or closed unexpectedly.
+ * Needs a fresh session to retry — the session pool wrapper in retry.ts
+ * honors this by invoking its `onRestart` hook before re-running.
+ */
+export declare class SessionTimeoutError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * Catch-all for unclassified scraper failures. Retryable by default so
+ * transient issues (DOM not settled, network blips) get a second chance.
+ */
+export declare class UnknownScraperError extends ScraperError {
+    constructor(message?: string);
+}
+/** Discriminator for {@link StepVerificationError}. See the class TSDoc for the per-variant semantics. */
+export type StepVerificationErrorKind = "cascade-exhausted" | "probe-absent" | "backend-error-unrecoverable" | "replan-cycle-detected" | "wizard-regression";
+/**
+ * Recon-only: a flow step in recon-browser.ts could not be acted on. Four
+ * variants per `kind`:
+ *
+ *   - "cascade-exhausted": the full 4-attempt self-healing cascade ran and
+ *     none of the attempts produced an observable effect. Expensive (the
+ *     cascade burned its full LLM/observe budget) — counted against the
+ *     cascade replan budget.
+ *   - "probe-absent": the cheap page-state probe ran BEFORE the cascade
+ *     and observed zero candidates for the step's instruction. We skip the
+ *     cascade and ask for a replan immediately because the page state is
+ *     clearly off (e.g. flow expected the form-fill page but the SPA is
+ *     still on the resume-upload screen). Cheap (~1 observe + 1 LLM call)
+ *     — counted against the probe replan budget.
+ *   - "backend-error-unrecoverable": the cascade detected a same-window
+ *     5xx response from the configured submit endpoint. No amount of
+ *     retry or replan can heal a server crash — the main flow loop
+ *     special-cases this kind to bypass the replan dispatcher and
+ *     propagate the error out, terminating the run with the diagnostic.
+ *   - "replan-cycle-detected": the engine observed the replanner proposing
+ *     the same multi-step instruction sequence under unchanged page state
+ *     N times in a row (default 3). Further replans on this trajectory
+ *     cannot converge — the main loop short-circuits to terminate the run
+ *     instead of burning the remaining replan budget on a known fixed point.
+ *   - "wizard-regression": a multi-page wizard navigated BACKWARD / restarted
+ *     mid-flow (e.g. a mis-clicked control fired a save-and-restart, resetting
+ *     the app to page 1). Detected via a configured restart-signal URL pattern
+ *     in the recent captures (e.g. `init-apply` with `application_canceled`).
+ *     The remaining flow steps now target a reset page, so continuing — or
+ *     replanning against the restarted wizard — is futile. The main loop
+ *     bypasses the replan dispatcher and propagates out, like
+ *     backend-error-unrecoverable.
+ *
+ * Non-retryable — the runtime path never sees this.
+ */
+export declare class StepVerificationError extends ScraperError {
+    readonly kind: StepVerificationErrorKind;
+    constructor(message?: string, kind?: StepVerificationErrorKind);
+}
+/**
+ * The direct-HTTP hot path received a response that did not match the plugin's
+ * Zod response schema. Non-retryable on the hot path — the dispatch layer uses
+ * this as the trigger to fall back to the Stagehand browser path instead.
+ */
+export declare class HttpSchemaError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * The direct-HTTP hot path received a non-2xx response that signals a bot
+ * challenge or auth wall (403, 401). Non-retryable — fall back to Stagehand.
+ */
+export declare class HttpBotChallengeError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * The direct-HTTP hot path received a 5xx server error. Non-retryable on the
+ * hot path — dispatch uses this as a fallback trigger just like HttpSchemaError.
+ * Kept distinct from HttpBotChallengeError so metrics and logs can tell apart
+ * a target server outage from a bot-detection block.
+ */
+export declare class HttpServerError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * The direct-HTTP hot path received a 429 rate-limit response. Non-retryable
+ * and NOT a fallback trigger — a 429 means the configured rps ceiling is too
+ * high; the right response is to back off and surface the metric, not burn a
+ * Steel browser session.
+ */
+export declare class HttpRateLimitError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * Oracle HCM returned a plain-text `ORA_URL_LOCKED` sentinel body, meaning the
+ * requisition URL has been locked by Oracle after repeated requests. Non-retryable
+ * and NOT a browser-fallback trigger — the URL is locked at Oracle's end, so
+ * neither a retry of the identical HTTP request nor a fresh Stagehand browser
+ * session can succeed. The caller must back off and surface a "retry later"
+ * state rather than burning a Steel session. Kept distinct from HttpRateLimitError
+ * so metrics/logs (classifyDispatchError) can tell an Oracle requisition lock
+ * apart from a self-inflicted 429 rate limit.
+ */
+export declare class HttpUrlLockedError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * Oracle HCM returned a plain-text `ORA_IRC_TOKEN_EXPIRED` sentinel body during
+ * a burst / rate-limit / token-expiry window. Retryable so pRetry keeps retrying,
+ * but kept distinct from the generic {@link UnknownScraperError} so the encompass
+ * http-flow can catch exactly this class and re-mint the AccessCode before
+ * retrying — replaying the same stale token would produce the same sentinel
+ * indefinitely. Distinct from {@link HttpUrlLockedError} which is terminal.
+ */
+export declare class OracleTokenExpiredError extends ScraperError {
+    constructor(message?: string);
+}
+/**
+ * Structured result returned (not thrown) by the hot path when it cannot
+ * complete the application because the user must supply additional data.
+ * Assignable as the `data` payload of a `SitePluginResult` so dispatch can
+ * detect it without instanceof checks on thrown errors.
+ */
+export type NeedsUserInfoResult = {
+    verified: false;
+    needsUserInfo: true;
+    missingFields: {
+        field: string;
+        question: string;
+    }[];
+    requiresOtp: boolean;
+};
+/**
+ * Thrown when code that translates stable semantic field keys (`address.city`,
+ * `firstName`, `applicantGender`) into tenant-specific GUIDs via a runtime
+ * form-map lookup cannot resolve one or more required keys.
+ *
+ * Use this in any future form-map / response-builder code so a missing field
+ * surfaces LOUDLY with an actionable error in the server log — instead of
+ * silently emitting an empty GUID and producing an HTTP 200 with missing data
+ * (which is how the StatusCode="unlocked" bug on 2026-06-04 hid for hours).
+ *
+ * Non-retryable — a missing key in the form definition is a configuration /
+ * tenant mismatch that retries won't fix; the dispatch layer should treat
+ * this as a hot-path failure and engage the browser fallback.
+ */
+export declare class MissingFormMapKeyError extends ScraperError {
+    readonly missingKeys: readonly string[];
+    readonly context: string;
+    constructor(missingKeys: readonly string[], context: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/scraper/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/scraper/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,8BAAsB,YAAa,SAAQ,KAAK;IAC9C,SAAgB,SAAS,EAAE,OAAO,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO;CAKhD;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,YAAY;gBAChC,OAAO,SAAkC;CAGtD;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,SAA+B;CAGnD;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,SAA6B;CAGjD;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,SAA8B;CAGlD;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,SAA4B;CAGhD;AAED,0GAA0G;AAC1G,MAAM,MAAM,yBAAyB,GACjC,mBAAmB,GACnB,cAAc,GACd,6BAA6B,GAC7B,uBAAuB,GACvB,mBAAmB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;gBAEvC,OAAO,SAA2D,EAClE,IAAI,GAAE,yBAA+C;CAKxD;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,SAAkC;CAGtD;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,OAAO,SAAwC;CAG5D;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,SAA0B;CAG9C;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,SAAiC;CAGrD;AAED;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,SAAmD;CAGvE;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,OAAO,SAAiD;CAGrE;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,KAAK,CAAC;IAChB,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM;CAK5D"}

package/dist/scraper/errors.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Error hierarchy produced by the scraper. These are internal — they stay
+ * inside the scraper + service layer and are translated into API envelope
+ * errors (via src/api/errors.ts) before they reach the client.
+ *
+ * Why: each class encodes a distinct recovery policy that p-retry and the
+ * session pool key off of. Some failures abort the whole call (no retry
+ * can resolve them); others are retryable in place because a fresh AI
+ * resolution or DOM re-settle usually fixes them; some need a brand-new
+ * Steel session before retrying, in which case retry.ts invokes its
+ * onRestart callback. See each class's TSDoc for its specific policy
+ * and the diagnostic it represents.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingFormMapKeyError = exports.OracleTokenExpiredError = exports.HttpUrlLockedError = exports.HttpRateLimitError = exports.HttpServerError = exports.HttpBotChallengeError = exports.HttpSchemaError = exports.StepVerificationError = exports.UnknownScraperError = exports.SessionTimeoutError = exports.SelectorFailureError = exports.EmptyResultsError = exports.CaptchaError = exports.ScraperError = void 0;
+/**
+ * Base class for all scraper-internal errors. Each subclass encodes a
+ * distinct recovery policy (retryable or not) that retry.ts and loader.ts
+ * key off of to decide whether to retry, restart the session, or abort.
+ */
+class ScraperError extends Error {
+    retryable;
+    constructor(message, retryable) {
+        super(message);
+        this.name = new.target.name;
+        this.retryable = retryable;
+    }
+}
+exports.ScraperError = ScraperError;
+/**
+ * The scraper encountered a CAPTCHA challenge Steel couldn't solve on our
+ * behalf. Propagate upstream as error code 2004.
+ */
+class CaptchaError extends ScraperError {
+    constructor(message = "captcha challenge encountered") {
+        super(message, false);
+    }
+}
+exports.CaptchaError = CaptchaError;
+/**
+ * The scrape completed but returned no data. This is not a failure — it's
+ * a legitimate empty result (e.g. a search returned zero matches). The
+ * service layer handles this without throwing.
+ */
+class EmptyResultsError extends ScraperError {
+    constructor(message = "scrape returned no results") {
+        super(message, false);
+    }
+}
+exports.EmptyResultsError = EmptyResultsError;
+/**
+ * Stagehand failed to resolve a selector or an `act()` call. The most
+ * likely cause is that the cached action hash is stale because the target
+ * page's UI changed. Retries bust the cache and fall back to fresh AI inference.
+ */
+class SelectorFailureError extends ScraperError {
+    constructor(message = "scraper selector failure") {
+        super(message, true);
+    }
+}
+exports.SelectorFailureError = SelectorFailureError;
+/**
+ * The upstream Steel browser session timed out or closed unexpectedly.
+ * Needs a fresh session to retry — the session pool wrapper in retry.ts
+ * honors this by invoking its `onRestart` hook before re-running.
+ */
+class SessionTimeoutError extends ScraperError {
+    constructor(message = "scraper session timed out") {
+        super(message, true);
+    }
+}
+exports.SessionTimeoutError = SessionTimeoutError;
+/**
+ * Catch-all for unclassified scraper failures. Retryable by default so
+ * transient issues (DOM not settled, network blips) get a second chance.
+ */
+class UnknownScraperError extends ScraperError {
+    constructor(message = "unknown scraper failure") {
+        super(message, true);
+    }
+}
+exports.UnknownScraperError = UnknownScraperError;
+/**
+ * Recon-only: a flow step in recon-browser.ts could not be acted on. Four
+ * variants per `kind`:
+ *
+ *   - "cascade-exhausted": the full 4-attempt self-healing cascade ran and
+ *     none of the attempts produced an observable effect. Expensive (the
+ *     cascade burned its full LLM/observe budget) — counted against the
+ *     cascade replan budget.
+ *   - "probe-absent": the cheap page-state probe ran BEFORE the cascade
+ *     and observed zero candidates for the step's instruction. We skip the
+ *     cascade and ask for a replan immediately because the page state is
+ *     clearly off (e.g. flow expected the form-fill page but the SPA is
+ *     still on the resume-upload screen). Cheap (~1 observe + 1 LLM call)
+ *     — counted against the probe replan budget.
+ *   - "backend-error-unrecoverable": the cascade detected a same-window
+ *     5xx response from the configured submit endpoint. No amount of
+ *     retry or replan can heal a server crash — the main flow loop
+ *     special-cases this kind to bypass the replan dispatcher and
+ *     propagate the error out, terminating the run with the diagnostic.
+ *   - "replan-cycle-detected": the engine observed the replanner proposing
+ *     the same multi-step instruction sequence under unchanged page state
+ *     N times in a row (default 3). Further replans on this trajectory
+ *     cannot converge — the main loop short-circuits to terminate the run
+ *     instead of burning the remaining replan budget on a known fixed point.
+ *   - "wizard-regression": a multi-page wizard navigated BACKWARD / restarted
+ *     mid-flow (e.g. a mis-clicked control fired a save-and-restart, resetting
+ *     the app to page 1). Detected via a configured restart-signal URL pattern
+ *     in the recent captures (e.g. `init-apply` with `application_canceled`).
+ *     The remaining flow steps now target a reset page, so continuing — or
+ *     replanning against the restarted wizard — is futile. The main loop
+ *     bypasses the replan dispatcher and propagates out, like
+ *     backend-error-unrecoverable.
+ *
+ * Non-retryable — the runtime path never sees this.
+ */
+class StepVerificationError extends ScraperError {
+    kind;
+    constructor(message = "recon step failed verification after all heal attempts", kind = "cascade-exhausted") {
+        super(message, false);
+        this.kind = kind;
+    }
+}
+exports.StepVerificationError = StepVerificationError;
+/**
+ * The direct-HTTP hot path received a response that did not match the plugin's
+ * Zod response schema. Non-retryable on the hot path — the dispatch layer uses
+ * this as the trigger to fall back to the Stagehand browser path instead.
+ */
+class HttpSchemaError extends ScraperError {
+    constructor(message = "http response schema mismatch") {
+        super(message, false);
+    }
+}
+exports.HttpSchemaError = HttpSchemaError;
+/**
+ * The direct-HTTP hot path received a non-2xx response that signals a bot
+ * challenge or auth wall (403, 401). Non-retryable — fall back to Stagehand.
+ */
+class HttpBotChallengeError extends ScraperError {
+    constructor(message = "http bot challenge or auth required") {
+        super(message, false);
+    }
+}
+exports.HttpBotChallengeError = HttpBotChallengeError;
+/**
+ * The direct-HTTP hot path received a 5xx server error. Non-retryable on the
+ * hot path — dispatch uses this as a fallback trigger just like HttpSchemaError.
+ * Kept distinct from HttpBotChallengeError so metrics and logs can tell apart
+ * a target server outage from a bot-detection block.
+ */
+class HttpServerError extends ScraperError {
+    constructor(message = "http 5xx server error") {
+        super(message, false);
+    }
+}
+exports.HttpServerError = HttpServerError;
+/**
+ * The direct-HTTP hot path received a 429 rate-limit response. Non-retryable
+ * and NOT a fallback trigger — a 429 means the configured rps ceiling is too
+ * high; the right response is to back off and surface the metric, not burn a
+ * Steel browser session.
+ */
+class HttpRateLimitError extends ScraperError {
+    constructor(message = "http 429 rate limit exceeded") {
+        super(message, false);
+    }
+}
+exports.HttpRateLimitError = HttpRateLimitError;
+/**
+ * Oracle HCM returned a plain-text `ORA_URL_LOCKED` sentinel body, meaning the
+ * requisition URL has been locked by Oracle after repeated requests. Non-retryable
+ * and NOT a browser-fallback trigger — the URL is locked at Oracle's end, so
+ * neither a retry of the identical HTTP request nor a fresh Stagehand browser
+ * session can succeed. The caller must back off and surface a "retry later"
+ * state rather than burning a Steel session. Kept distinct from HttpRateLimitError
+ * so metrics/logs (classifyDispatchError) can tell an Oracle requisition lock
+ * apart from a self-inflicted 429 rate limit.
+ */
+class HttpUrlLockedError extends ScraperError {
+    constructor(message = "oracle requisition url locked (ORA_URL_LOCKED)") {
+        super(message, false);
+    }
+}
+exports.HttpUrlLockedError = HttpUrlLockedError;
+/**
+ * Oracle HCM returned a plain-text `ORA_IRC_TOKEN_EXPIRED` sentinel body during
+ * a burst / rate-limit / token-expiry window. Retryable so pRetry keeps retrying,
+ * but kept distinct from the generic {@link UnknownScraperError} so the encompass
+ * http-flow can catch exactly this class and re-mint the AccessCode before
+ * retrying — replaying the same stale token would produce the same sentinel
+ * indefinitely. Distinct from {@link HttpUrlLockedError} which is terminal.
+ */
+class OracleTokenExpiredError extends ScraperError {
+    constructor(message = "oracle token expired (ORA_IRC_TOKEN_EXPIRED)") {
+        super(message, true);
+    }
+}
+exports.OracleTokenExpiredError = OracleTokenExpiredError;
+/**
+ * Thrown when code that translates stable semantic field keys (`address.city`,
+ * `firstName`, `applicantGender`) into tenant-specific GUIDs via a runtime
+ * form-map lookup cannot resolve one or more required keys.
+ *
+ * Use this in any future form-map / response-builder code so a missing field
+ * surfaces LOUDLY with an actionable error in the server log — instead of
+ * silently emitting an empty GUID and producing an HTTP 200 with missing data
+ * (which is how the StatusCode="unlocked" bug on 2026-06-04 hid for hours).
+ *
+ * Non-retryable — a missing key in the form definition is a configuration /
+ * tenant mismatch that retries won't fix; the dispatch layer should treat
+ * this as a hot-path failure and engage the browser fallback.
+ */
+class MissingFormMapKeyError extends ScraperError {
+    missingKeys;
+    context;
+    constructor(missingKeys, context) {
+        super(`form-map missing required keys [${missingKeys.join(", ")}] in ${context}`, false);
+        this.missingKeys = missingKeys;
+        this.context = context;
+    }
+}
+exports.MissingFormMapKeyError = MissingFormMapKeyError;
+//# sourceMappingURL=errors.js.map

package/dist/scraper/errors.js.map

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

package/dist/scraper/fixtures.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Runtime helper for loading committed static JSON fixtures captured during
+ * the recon playbook (Step 3B — auxiliary endpoints). Use this instead of
+ * re-fetching static reference data (markets, currencies, labels, etc.) on
+ * every production call — these fixtures are cheap memory reads and should
+ * be re-generated by re-running recon when drift is detected.
+ */
+import type { z } from "zod/v4";
+/**
+ * Loads a committed JSON fixture from the `sites/<siteId>/fixtures/<filename>`
+ * directory alongside the running module and validates it with the provided Zod
+ * schema. Throws on missing file or schema mismatch — both indicate the fixture
+ * is stale and recon needs re-running.
+ *
+ * Path is resolved relative to `__dirname` so it works in both environments:
+ * - Dev (`tsx src/scraper/fixtures.ts`): `__dirname` = `src/scraper/`,
+ *   resolves to `src/sites/<id>/fixtures/<filename>`.
+ * - Prod (`node dist/scraper/fixtures.js`): `__dirname` = `dist/scraper/`,
+ *   resolves to `dist/sites/<id>/fixtures/<filename>` — which `pnpm run build`
+ *   populates by copying `src/sites/` to `dist/sites/`.
+ */
+export declare function loadFixture<T>(siteId: string, filename: string, schema: z.ZodType<T>): T;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/scraper/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/scraper/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CA0BxF"}

package/dist/scraper/fixtures.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Runtime helper for loading committed static JSON fixtures captured during
+ * the recon playbook (Step 3B — auxiliary endpoints). Use this instead of
+ * re-fetching static reference data (markets, currencies, labels, etc.) on
+ * every production call — these fixtures are cheap memory reads and should
+ * be re-generated by re-running recon when drift is detected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadFixture = loadFixture;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Loads a committed JSON fixture from the `sites/<siteId>/fixtures/<filename>`
+ * directory alongside the running module and validates it with the provided Zod
+ * schema. Throws on missing file or schema mismatch — both indicate the fixture
+ * is stale and recon needs re-running.
+ *
+ * Path is resolved relative to `__dirname` so it works in both environments:
+ * - Dev (`tsx src/scraper/fixtures.ts`): `__dirname` = `src/scraper/`,
+ *   resolves to `src/sites/<id>/fixtures/<filename>`.
+ * - Prod (`node dist/scraper/fixtures.js`): `__dirname` = `dist/scraper/`,
+ *   resolves to `dist/sites/<id>/fixtures/<filename>` — which `pnpm run build`
+ *   populates by copying `src/sites/` to `dist/sites/`.
+ */
+function loadFixture(siteId, filename, schema) {
+    const fixturePath = (0, node_path_1.resolve)(__dirname, "..", "sites", siteId, "fixtures", filename);
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(fixturePath, "utf8");
+    }
+    catch {
+        throw new Error(`fixture not found: ${fixturePath} — run recon-http.ts and commit the output to src/sites/${siteId}/fixtures/${filename}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`fixture is not valid JSON: ${fixturePath}`);
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`fixture schema mismatch: ${fixturePath} — re-run recon-http.ts to refresh. Issues: ${JSON.stringify(result.error.issues)}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=fixtures.js.map

package/dist/scraper/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../src/scraper/fixtures.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAoBH,kCA0BC;AA5CD,qCAAuC;AACvC,yCAAoC;AAIpC;;;;;;;;;;;;GAYG;AACH,SAAgB,WAAW,CAAI,MAAc,EAAE,QAAgB,EAAE,MAAoB;IACnF,MAAM,WAAW,GAAG,IAAA,mBAAO,EAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IACpF,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,IAAA,sBAAY,EAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,sBAAsB,WAAW,2DAA2D,MAAM,aAAa,QAAQ,EAAE,CAC1H,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,8BAA8B,WAAW,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,4BAA4B,WAAW,+CAA+C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAC5H,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}