@monetizationos/proxy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MonetizationOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+<div align="center">
+  <a href="https://monetizationos.com">
+  <img alt="MonetizationOS logo" src="https://app.monetizationos.com/static/monetizationos-logo.png" height="48">
+  </a>
+  <h1>MonetizationOS Proxy Core</h1>
+</div>
+
+A Fetch-based [MonetizationOS Proxy](https://docs.monetizationos.com/docs/api-reference/proxies) core: `Request` in, `Response` out, runtime-agnostic.
+
+This package contains the shared pipeline that powers the MonetizationOS proxy workers on Cloudflare, Fastly, Akamai, and any other runtime that speaks the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). Platform-specific concerns — origin dispatch, config/secret loading, HTML rewriting — are supplied by each consumer as adapters.
+
+## Install
+
+```sh
+npm install @monetizationos/proxy
+```
+
+## Usage
+
+```ts
+import { MOSProxyBuilder } from "@monetizationos/proxy";
+
+const proxy = new MOSProxyBuilder()
+    .withConfig({
+        originUrl: "https://news.example.com",
+        surfaceSlug: "web",
+        mosHost: "https://api.monetizationos.com",
+        mosSecretKey: process.env.MONETIZATION_OS_SECRET_KEY!,
+        mosEndpointsPrefix: "/mos-endpoints/",
+        anonymousSessionCookieName: "anon-session-id",
+        authenticatedUserJwtCookieName: "__session",
+        injectScriptUrl: "https://assets.monetizationos.com/web-components-latest.js",
+        originRequestHeaders: { "X-Api-Key": process.env.ORIGIN_API_KEY! },
+    })
+    .withHtmlRewriter(myHtmlRewriterAdapter)
+    .build();
+
+export default {
+    fetch: (request: Request) => proxy.handle(request),
+};
+```
+
+## Pipeline
+
+1. Custom endpoint routing (`/mos-endpoints/*` → MOS API)
+2. Origin fetch
+3. Link rewriting and `<meta>` extraction
+4. Surface decisions
+5. Surface behavior (HTTP-level mutations)
+6. Surface components (DOM-level transforms)
+
+Stages 3–6 run on HTML responses only and auto-skip for everything else. Call `.withoutHtmlTransformation()` to disable them entirely.
+
+## Adapters
+
+- `Fetcher` — `(request: Request) => Promise<Response>`. Configure separately for origin traffic (`.withOriginFetcher`) and MOS API traffic (`.withApiFetcher`). Both default to `globalThis.fetch`; override on runtimes that need a backend binding (e.g. Fastly Compute) or custom dispatch.
+- `HtmlRewriterAdapter` — wraps the platform's lol-html binding.
+- `ClientMetadataProvider` — optional; exposes platform-specific request metadata (Cloudflare's `cf` object, Fastly's `event.client`, etc.).
+
+## API-only mode
+
+Skip HTML transformation entirely when the proxy only needs to handle API traffic:
+
+```ts
+const proxy = new MOSProxyBuilder().withConfig(config).withoutHtmlTransformation().build();
+```
+
+## Error handling and logging
+
+The HTML pipeline fails open by default: on error, the proxy logs a structured event and returns the last safe response so the origin page still gets served. Register an error handler to shape that response yourself — render a custom error page, return a 503, or rethrow so the host runtime's error middleware takes over.
+
+```ts
+const proxy = new MOSProxyBuilder()
+    .withConfig(config)
+    .withHtmlRewriter(myHtmlRewriterAdapter)
+    .withHtmlPipelineErrorHandler(({ error, stage, lastSafeResponse }) => {
+        // Inspect `error` / `stage`, or return your own Response.
+        return lastSafeResponse;
+    })
+    .withLogger({
+        log(event) {
+            console[event.level](event.message, event.context, event.error);
+        },
+    })
+    .build();
+```
+
+## License
+
+MIT

package/dist/MOSProxy.d.ts

@@ -0,0 +1,43 @@
+import type { ClientMetadataProvider } from './adapters/ClientMetadataProvider';
+import type { Fetcher } from './adapters/Fetcher';
+import type { HtmlRewriterAdapter } from './adapters/HtmlRewriterAdapter';
+import { type MOSProxyLogger } from './logger';
+import type { MOSConfigInput } from './types';
+export type MOSProxyHtmlPipelineStage = 'origin-response' | 'link-rewriting' | 'surface-decisions' | 'surface-behavior' | 'surface-components';
+export interface MOSProxyHtmlPipelineErrorContext {
+    error: unknown;
+    stage: MOSProxyHtmlPipelineStage;
+    request: Request;
+    lastSafeResponse: Response;
+}
+/**
+ * Called when the HTML pipeline throws. Return a `Response` to fully control the proxy's reply, or
+ * re-throw to surface the error to the platform handler. If omitted, the proxy fails open and
+ * returns `lastSafeResponse`. If the callback itself throws or returns a non-Response value, the
+ * proxy logs a warning and falls back to `lastSafeResponse` so the site cannot be taken down by a
+ * bug in the handler.
+ */
+export type MOSProxyHtmlPipelineErrorHandler = (ctx: MOSProxyHtmlPipelineErrorContext) => Response | Promise<Response>;
+export interface MOSProxyOptions {
+    config: MOSConfigInput;
+    originFetcher: Fetcher;
+    apiFetcher: Fetcher | null;
+    htmlRewriter: HtmlRewriterAdapter | null;
+    clientMetadataProvider: ClientMetadataProvider | null;
+    logger?: MOSProxyLogger;
+    onHtmlPipelineError?: MOSProxyHtmlPipelineErrorHandler;
+    customEndpointsEnabled: boolean;
+    linkRewritingEnabled: boolean;
+    surfaceDecisionsEnabled: boolean;
+    htmlTransformationEnabled: boolean;
+}
+/**
+ * Platform-agnostic MonetizationOS proxy. Build one with `MOSProxyBuilder`, then call
+ * `proxy.handle(request)` from your platform's fetch entry point.
+ */
+export declare class MOSProxy {
+    private readonly opts;
+    private readonly config;
+    constructor(opts: MOSProxyOptions);
+    handle(request: Request): Promise<Response>;
+}

package/dist/MOSProxy.js

@@ -0,0 +1,140 @@
+import { normalizeMOSConfig } from './config';
+import { consoleLogger } from './logger';
+import customEndpointRequest from './stages/customEndpoint';
+import isRedirectResponse from './stages/isRedirectResponse';
+import rewriteOriginResponse from './stages/linkRewriting';
+import performOriginRequest from './stages/originRequest';
+import shouldIgnorePath from './stages/shouldIgnorePath';
+import handleSurfaceBehavior from './stages/surfaceBehavior';
+import handleSurfaceComponents from './stages/surfaceComponents';
+import getSurfaceDecisions from './stages/surfaceDecisions';
+/**
+ * Platform-agnostic MonetizationOS proxy. Build one with `MOSProxyBuilder`, then call
+ * `proxy.handle(request)` from your platform's fetch entry point.
+ */
+export class MOSProxy {
+    opts;
+    config;
+    constructor(opts) {
+        this.opts = opts;
+        this.config = normalizeMOSConfig(opts.config, opts.logger ?? consoleLogger);
+    }
+    async handle(request) {
+        const { originFetcher, apiFetcher, htmlRewriter, clientMetadataProvider, onHtmlPipelineError } = this.opts;
+        const logger = this.opts.logger ?? consoleLogger;
+        const ctx = { config: this.config, logger };
+        // Stage 1a: custom endpoint routing
+        if (this.opts.customEndpointsEnabled) {
+            if (!apiFetcher) {
+                throw new Error('MOSProxy: customEndpoints is enabled but no API fetcher is configured');
+            }
+            const customEndpointResponse = await customEndpointRequest(ctx, request, apiFetcher);
+            if (customEndpointResponse) {
+                return customEndpointResponse;
+            }
+        }
+        // Stage 1b: origin fetch
+        const originResponse = await performOriginRequest(ctx, request, originFetcher);
+        // Auto-skip HTML pipeline for non-HTML content, or when HTML transformation is disabled entirely
+        const isHtml = originResponse.headers.get('Content-Type')?.startsWith('text/html') ?? false;
+        if (!isHtml || !this.opts.htmlTransformationEnabled) {
+            return originResponse;
+        }
+        let stage = 'origin-response';
+        let failOpenResponse = cloneResponseForFallback(originResponse, logger, stage);
+        try {
+            // Stage 2: rewrite origin links (optional)
+            let rewrittenResponse = originResponse;
+            if (this.opts.linkRewritingEnabled) {
+                stage = 'link-rewriting';
+                rewrittenResponse = await rewriteOriginResponse(ctx, request, originResponse);
+                failOpenResponse = cloneResponseForFallback(rewrittenResponse, logger, stage);
+            }
+            // Stage 3: surface decisions (optional)
+            if (!this.opts.surfaceDecisionsEnabled) {
+                return rewrittenResponse;
+            }
+            if (shouldIgnorePath(ctx, request) || isRedirectResponse(rewrittenResponse)) {
+                return rewrittenResponse;
+            }
+            if (!apiFetcher) {
+                throw new Error('MOSProxy: surfaceDecisions is enabled but no API fetcher is configured');
+            }
+            stage = 'surface-decisions';
+            const [modifiedResponse, surfaceDecisions] = await getSurfaceDecisions(ctx, request, rewrittenResponse, apiFetcher, htmlRewriter, clientMetadataProvider);
+            if (!surfaceDecisions) {
+                return modifiedResponse;
+            }
+            failOpenResponse = cloneResponseForFallback(modifiedResponse, logger, stage);
+            // Stage 4: surface behavior (HTTP-level)
+            stage = 'surface-behavior';
+            const [surfaceDecisionResponse, returnImmediately] = handleSurfaceBehavior(modifiedResponse, surfaceDecisions);
+            if (returnImmediately) {
+                return surfaceDecisionResponse;
+            }
+            failOpenResponse = cloneResponseForFallback(surfaceDecisionResponse, logger, stage);
+            // Stage 5: surface components (HTML-level) — requires an HTML rewriter
+            if (!htmlRewriter) {
+                return surfaceDecisionResponse;
+            }
+            stage = 'surface-components';
+            return await handleSurfaceComponents(ctx, surfaceDecisionResponse, surfaceDecisions, htmlRewriter);
+        }
+        catch (error) {
+            logger.log({
+                level: 'error',
+                code: 'html-pipeline-failed',
+                message: 'HTML pipeline failed.',
+                context: { stage, hasErrorHandler: Boolean(onHtmlPipelineError) },
+                error,
+            });
+            if (!onHtmlPipelineError) {
+                return failOpenResponse;
+            }
+            try {
+                const handlerResponse = await onHtmlPipelineError({
+                    error,
+                    stage,
+                    request,
+                    lastSafeResponse: failOpenResponse,
+                });
+                if (!(handlerResponse instanceof Response)) {
+                    logger.log({
+                        level: 'warn',
+                        code: 'html-pipeline-error-handler-invalid',
+                        message: 'onHtmlPipelineError did not return a Response; falling back to the last safe response.',
+                        context: { stage },
+                    });
+                    return failOpenResponse;
+                }
+                return handlerResponse;
+            }
+            catch (handlerError) {
+                logger.log({
+                    level: 'warn',
+                    code: 'html-pipeline-error-handler-threw',
+                    message: 'onHtmlPipelineError threw; falling back to the last safe response.',
+                    context: { stage },
+                    error: handlerError,
+                });
+                return failOpenResponse;
+            }
+        }
+    }
+}
+const cloneResponseForFallback = (response, logger, stage) => {
+    try {
+        return response.clone();
+    }
+    catch (error) {
+        logger.log({
+            level: 'warn',
+            code: 'response-clone-failed',
+            message: 'Could not clone response for fail-open fallback.',
+            context: { stage },
+            error,
+        });
+        return response;
+    }
+};
+//# sourceMappingURL=MOSProxy.js.map

package/dist/MOSProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MOSProxy.js","sourceRoot":"","sources":["../src/MOSProxy.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ClientMetadataProvider } from './adapters/ClientMetadataProvider'\nimport type { Fetcher } from './adapters/Fetcher'\nimport type { HtmlRewriterAdapter } from './adapters/HtmlRewriterAdapter'\nimport { type MOSConfig, normalizeMOSConfig } from './config'\nimport type { PipelineContext } from './context'\nimport { consoleLogger, type MOSProxyLogger } from './logger'\nimport customEndpointRequest from './stages/customEndpoint'\nimport isRedirectResponse from './stages/isRedirectResponse'\nimport rewriteOriginResponse from './stages/linkRewriting'\nimport performOriginRequest from './stages/originRequest'\nimport shouldIgnorePath from './stages/shouldIgnorePath'\nimport handleSurfaceBehavior from './stages/surfaceBehavior'\nimport handleSurfaceComponents from './stages/surfaceComponents'\nimport getSurfaceDecisions from './stages/surfaceDecisions'\nimport type { MOSConfigInput } from './types'\n\nexport type MOSProxyHtmlPipelineStage =\n    | 'origin-response'\n    | 'link-rewriting'\n    | 'surface-decisions'\n    | 'surface-behavior'\n    | 'surface-components'\n\nexport interface MOSProxyHtmlPipelineErrorContext {\n    error: unknown\n    stage: MOSProxyHtmlPipelineStage\n    request: Request\n    lastSafeResponse: Response\n}\n\n/**\n * Called when the HTML pipeline throws. Return a `Response` to fully control the proxy's reply, or\n * re-throw to surface the error to the platform handler. If omitted, the proxy fails open and\n * returns `lastSafeResponse`. If the callback itself throws or returns a non-Response value, the\n * proxy logs a warning and falls back to `lastSafeResponse` so the site cannot be taken down by a\n * bug in the handler.\n */\nexport type MOSProxyHtmlPipelineErrorHandler = (ctx: MOSProxyHtmlPipelineErrorContext) => Response | Promise<Response>\n\nexport interface MOSProxyOptions {\n    config: MOSConfigInput\n    originFetcher: Fetcher\n    apiFetcher: Fetcher | null\n    htmlRewriter: HtmlRewriterAdapter | null\n    clientMetadataProvider: ClientMetadataProvider | null\n    logger?: MOSProxyLogger\n    onHtmlPipelineError?: MOSProxyHtmlPipelineErrorHandler\n    customEndpointsEnabled: boolean\n    linkRewritingEnabled: boolean\n    surfaceDecisionsEnabled: boolean\n    htmlTransformationEnabled: boolean\n}\n\n/**\n * Platform-agnostic MonetizationOS proxy. Build one with `MOSProxyBuilder`, then call\n * `proxy.handle(request)` from your platform's fetch entry point.\n */\nexport class MOSProxy {\n    private readonly config: MOSConfig\n\n    constructor(private readonly opts: MOSProxyOptions) {\n        this.config = normalizeMOSConfig(opts.config, opts.logger ?? consoleLogger)\n    }\n\n    async handle(request: Request): Promise<Response> {\n        const { originFetcher, apiFetcher, htmlRewriter, clientMetadataProvider, onHtmlPipelineError } = this.opts\n        const logger = this.opts.logger ?? consoleLogger\n        const ctx: PipelineContext = { config: this.config, logger }\n\n        // Stage 1a: custom endpoint routing\n        if (this.opts.customEndpointsEnabled) {\n            if (!apiFetcher) {\n                throw new Error('MOSProxy: customEndpoints is enabled but no API fetcher is configured')\n            }\n            const customEndpointResponse = await customEndpointRequest(ctx, request, apiFetcher)\n            if (customEndpointResponse) {\n                return customEndpointResponse\n            }\n        }\n\n        // Stage 1b: origin fetch\n        const originResponse = await performOriginRequest(ctx, request, originFetcher)\n\n        // Auto-skip HTML pipeline for non-HTML content, or when HTML transformation is disabled entirely\n        const isHtml = originResponse.headers.get('Content-Type')?.startsWith('text/html') ?? false\n        if (!isHtml || !this.opts.htmlTransformationEnabled) {\n            return originResponse\n        }\n\n        let stage: MOSProxyHtmlPipelineStage = 'origin-response'\n        let failOpenResponse = cloneResponseForFallback(originResponse, logger, stage)\n\n        try {\n            // Stage 2: rewrite origin links (optional)\n            let rewrittenResponse: Response = originResponse\n            if (this.opts.linkRewritingEnabled) {\n                stage = 'link-rewriting'\n                rewrittenResponse = await rewriteOriginResponse(ctx, request, originResponse)\n                failOpenResponse = cloneResponseForFallback(rewrittenResponse, logger, stage)\n            }\n\n            // Stage 3: surface decisions (optional)\n            if (!this.opts.surfaceDecisionsEnabled) {\n                return rewrittenResponse\n            }\n            if (shouldIgnorePath(ctx, request) || isRedirectResponse(rewrittenResponse)) {\n                return rewrittenResponse\n            }\n\n            if (!apiFetcher) {\n                throw new Error('MOSProxy: surfaceDecisions is enabled but no API fetcher is configured')\n            }\n\n            stage = 'surface-decisions'\n            const [modifiedResponse, surfaceDecisions] = await getSurfaceDecisions(\n                ctx,\n                request,\n                rewrittenResponse,\n                apiFetcher,\n                htmlRewriter,\n                clientMetadataProvider,\n            )\n            if (!surfaceDecisions) {\n                return modifiedResponse\n            }\n            failOpenResponse = cloneResponseForFallback(modifiedResponse, logger, stage)\n\n            // Stage 4: surface behavior (HTTP-level)\n            stage = 'surface-behavior'\n            const [surfaceDecisionResponse, returnImmediately] = handleSurfaceBehavior(modifiedResponse, surfaceDecisions)\n            if (returnImmediately) {\n                return surfaceDecisionResponse\n            }\n            failOpenResponse = cloneResponseForFallback(surfaceDecisionResponse, logger, stage)\n\n            // Stage 5: surface components (HTML-level) — requires an HTML rewriter\n            if (!htmlRewriter) {\n                return surfaceDecisionResponse\n            }\n            stage = 'surface-components'\n            return await handleSurfaceComponents(ctx, surfaceDecisionResponse, surfaceDecisions, htmlRewriter)\n        } catch (error) {\n            logger.log({\n                level: 'error',\n                code: 'html-pipeline-failed',\n                message: 'HTML pipeline failed.',\n                context: { stage, hasErrorHandler: Boolean(onHtmlPipelineError) },\n                error,\n            })\n\n            if (!onHtmlPipelineError) {\n                return failOpenResponse\n            }\n\n            try {\n                const handlerResponse = await onHtmlPipelineError({\n                    error,\n                    stage,\n                    request,\n                    lastSafeResponse: failOpenResponse,\n                })\n                if (!(handlerResponse instanceof Response)) {\n                    logger.log({\n                        level: 'warn',\n                        code: 'html-pipeline-error-handler-invalid',\n                        message: 'onHtmlPipelineError did not return a Response; falling back to the last safe response.',\n                        context: { stage },\n                    })\n                    return failOpenResponse\n                }\n                return handlerResponse\n            } catch (handlerError) {\n                logger.log({\n                    level: 'warn',\n                    code: 'html-pipeline-error-handler-threw',\n                    message: 'onHtmlPipelineError threw; falling back to the last safe response.',\n                    context: { stage },\n                    error: handlerError,\n                })\n                return failOpenResponse\n            }\n        }\n    }\n}\n\nconst cloneResponseForFallback = (response: Response, logger: MOSProxyLogger, stage: MOSProxyHtmlPipelineStage): Response => {\n    try {\n        return response.clone()\n    } catch (error) {\n        logger.log({\n            level: 'warn',\n            code: 'response-clone-failed',\n            message: 'Could not clone response for fail-open fallback.',\n            context: { stage },\n            error,\n        })\n        return response\n    }\n}\n"]}

package/dist/MOSProxyBuilder.d.ts

@@ -0,0 +1,75 @@
+import type { ClientMetadataProvider } from './adapters/ClientMetadataProvider';
+import type { Fetcher } from './adapters/Fetcher';
+import type { HtmlRewriterAdapter } from './adapters/HtmlRewriterAdapter';
+import type { MOSProxyLogger } from './logger';
+import { MOSProxy, type MOSProxyHtmlPipelineErrorHandler } from './MOSProxy';
+import type { MOSConfigInput } from './types';
+/**
+ * Fluent builder for `MOSProxy`. Provide configuration and platform adapters, then `build()`.
+ *
+ * Defaults:
+ * - custom endpoint routing: enabled
+ * - link rewriting: enabled
+ * - surface decisions: enabled
+ * - HTML transformation: enabled (auto-skipped per request for non-HTML responses)
+ * - origin/API fetcher: `globalThis.fetch` (override on runtimes that need a backend binding, e.g. Fastly)
+ *
+ * @example
+ * ```ts
+ * const proxy = new MOSProxyBuilder()
+ *     .withConfig({
+ *         originUrl: 'https://news.example.com',
+ *         surfaceSlug: 'web',
+ *         mosHost: 'https://api.monetizationos.com',
+ *         mosSecretKey: process.env.MONETIZATION_OS_SECRET_KEY!,
+ *         mosEndpointsPrefix: '/mos-endpoints/',
+ *         anonymousSessionCookieName: 'anon-session-id',
+ *         authenticatedUserJwtCookieName: '__session',
+ *         injectScriptUrl: 'https://assets.monetizationos.com/web-components-latest.js',
+ *         surfaceDecisionsIgnorePaths: '',
+ *         originRequestHeaders: { 'X-Api-Key': process.env.ORIGIN_API_KEY! },
+ *     })
+ *     .withHtmlRewriter(myHtmlRewriterAdapter)
+ *     .build()
+ *
+ * export default { fetch: (request: Request) => proxy.handle(request) }
+ * ```
+ */
+export declare class MOSProxyBuilder {
+    private _config;
+    private _originFetcher;
+    private _apiFetcher;
+    private _htmlRewriter;
+    private _clientMetadataProvider;
+    private _logger;
+    private _onHtmlPipelineError;
+    private _customEndpoints;
+    private _linkRewriting;
+    private _surfaceDecisions;
+    private _htmlTransformation;
+    withConfig(config: MOSConfigInput): this;
+    withOriginFetcher(fetcher: Fetcher): this;
+    withApiFetcher(fetcher: Fetcher): this;
+    withHtmlRewriter(rewriter: HtmlRewriterAdapter): this;
+    withClientMetadata(provider: ClientMetadataProvider): this;
+    withLogger(logger: MOSProxyLogger): this;
+    /**
+     * Register a callback to handle HTML pipeline errors. The proxy fails open by default and
+     * returns the last safe (unconsumed) response — provide this if you want to shape that
+     * response yourself (e.g. render a custom error page, return a 503, or re-throw so your
+     * platform's error middleware handles it). If the callback throws or returns a non-Response
+     * value, the proxy logs a warning and falls back to the last safe response.
+     */
+    withHtmlPipelineErrorHandler(handler: MOSProxyHtmlPipelineErrorHandler): this;
+    withoutCustomEndpoints(): this;
+    withoutLinkRewriting(): this;
+    withoutSurfaceDecisions(): this;
+    /**
+     * Disable the HTML transformation pipeline entirely (stages 3–6).
+     *
+     * Use for API-only proxies: neither an HTML rewriter adapter nor an API fetcher is required
+     * if custom endpoints and surface decisions are both disabled alongside this.
+     */
+    withoutHtmlTransformation(): this;
+    build(): MOSProxy;
+}

package/dist/MOSProxyBuilder.js

@@ -0,0 +1,126 @@
+import { MOSProxy } from './MOSProxy';
+/**
+ * Fluent builder for `MOSProxy`. Provide configuration and platform adapters, then `build()`.
+ *
+ * Defaults:
+ * - custom endpoint routing: enabled
+ * - link rewriting: enabled
+ * - surface decisions: enabled
+ * - HTML transformation: enabled (auto-skipped per request for non-HTML responses)
+ * - origin/API fetcher: `globalThis.fetch` (override on runtimes that need a backend binding, e.g. Fastly)
+ *
+ * @example
+ * ```ts
+ * const proxy = new MOSProxyBuilder()
+ *     .withConfig({
+ *         originUrl: 'https://news.example.com',
+ *         surfaceSlug: 'web',
+ *         mosHost: 'https://api.monetizationos.com',
+ *         mosSecretKey: process.env.MONETIZATION_OS_SECRET_KEY!,
+ *         mosEndpointsPrefix: '/mos-endpoints/',
+ *         anonymousSessionCookieName: 'anon-session-id',
+ *         authenticatedUserJwtCookieName: '__session',
+ *         injectScriptUrl: 'https://assets.monetizationos.com/web-components-latest.js',
+ *         surfaceDecisionsIgnorePaths: '',
+ *         originRequestHeaders: { 'X-Api-Key': process.env.ORIGIN_API_KEY! },
+ *     })
+ *     .withHtmlRewriter(myHtmlRewriterAdapter)
+ *     .build()
+ *
+ * export default { fetch: (request: Request) => proxy.handle(request) }
+ * ```
+ */
+export class MOSProxyBuilder {
+    _config = null;
+    _originFetcher = globalThis.fetch;
+    _apiFetcher = globalThis.fetch;
+    _htmlRewriter = null;
+    _clientMetadataProvider = null;
+    _logger = null;
+    _onHtmlPipelineError = null;
+    _customEndpoints = true;
+    _linkRewriting = true;
+    _surfaceDecisions = true;
+    _htmlTransformation = true;
+    withConfig(config) {
+        this._config = config;
+        return this;
+    }
+    withOriginFetcher(fetcher) {
+        this._originFetcher = fetcher;
+        return this;
+    }
+    withApiFetcher(fetcher) {
+        this._apiFetcher = fetcher;
+        return this;
+    }
+    withHtmlRewriter(rewriter) {
+        this._htmlRewriter = rewriter;
+        return this;
+    }
+    withClientMetadata(provider) {
+        this._clientMetadataProvider = provider;
+        return this;
+    }
+    withLogger(logger) {
+        this._logger = logger;
+        return this;
+    }
+    /**
+     * Register a callback to handle HTML pipeline errors. The proxy fails open by default and
+     * returns the last safe (unconsumed) response — provide this if you want to shape that
+     * response yourself (e.g. render a custom error page, return a 503, or re-throw so your
+     * platform's error middleware handles it). If the callback throws or returns a non-Response
+     * value, the proxy logs a warning and falls back to the last safe response.
+     */
+    withHtmlPipelineErrorHandler(handler) {
+        this._onHtmlPipelineError = handler;
+        return this;
+    }
+    withoutCustomEndpoints() {
+        this._customEndpoints = false;
+        return this;
+    }
+    withoutLinkRewriting() {
+        this._linkRewriting = false;
+        return this;
+    }
+    withoutSurfaceDecisions() {
+        this._surfaceDecisions = false;
+        return this;
+    }
+    /**
+     * Disable the HTML transformation pipeline entirely (stages 3–6).
+     *
+     * Use for API-only proxies: neither an HTML rewriter adapter nor an API fetcher is required
+     * if custom endpoints and surface decisions are both disabled alongside this.
+     */
+    withoutHtmlTransformation() {
+        this._htmlTransformation = false;
+        return this;
+    }
+    build() {
+        if (!this._config) {
+            throw new Error('MOSProxyBuilder: withConfig(...) is required');
+        }
+        const needsHtmlRewriter = this._htmlTransformation && this._surfaceDecisions;
+        if (needsHtmlRewriter && !this._htmlRewriter) {
+            throw new Error('MOSProxyBuilder: withHtmlRewriter(...) is required when surface decisions is enabled; call withoutSurfaceDecisions() or withoutHtmlTransformation() if you do not need it');
+        }
+        const opts = {
+            config: this._config,
+            originFetcher: this._originFetcher,
+            apiFetcher: this._apiFetcher,
+            htmlRewriter: this._htmlRewriter,
+            clientMetadataProvider: this._clientMetadataProvider,
+            logger: this._logger ?? undefined,
+            onHtmlPipelineError: this._onHtmlPipelineError ?? undefined,
+            customEndpointsEnabled: this._customEndpoints,
+            linkRewritingEnabled: this._linkRewriting,
+            surfaceDecisionsEnabled: this._surfaceDecisions,
+            htmlTransformationEnabled: this._htmlTransformation,
+        };
+        return new MOSProxy(opts);
+    }
+}
+//# sourceMappingURL=MOSProxyBuilder.js.map

package/dist/MOSProxyBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MOSProxyBuilder.js","sourceRoot":"","sources":["../src/MOSProxyBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ClientMetadataProvider } from './adapters/ClientMetadataProvider'\nimport type { Fetcher } from './adapters/Fetcher'\nimport type { HtmlRewriterAdapter } from './adapters/HtmlRewriterAdapter'\nimport type { MOSProxyLogger } from './logger'\nimport { MOSProxy, type MOSProxyHtmlPipelineErrorHandler, type MOSProxyOptions } from './MOSProxy'\nimport type { MOSConfigInput } from './types'\n\n/**\n * Fluent builder for `MOSProxy`. Provide configuration and platform adapters, then `build()`.\n *\n * Defaults:\n * - custom endpoint routing: enabled\n * - link rewriting: enabled\n * - surface decisions: enabled\n * - HTML transformation: enabled (auto-skipped per request for non-HTML responses)\n * - origin/API fetcher: `globalThis.fetch` (override on runtimes that need a backend binding, e.g. Fastly)\n *\n * @example\n * ```ts\n * const proxy = new MOSProxyBuilder()\n *     .withConfig({\n *         originUrl: 'https://news.example.com',\n *         surfaceSlug: 'web',\n *         mosHost: 'https://api.monetizationos.com',\n *         mosSecretKey: process.env.MONETIZATION_OS_SECRET_KEY!,\n *         mosEndpointsPrefix: '/mos-endpoints/',\n *         anonymousSessionCookieName: 'anon-session-id',\n *         authenticatedUserJwtCookieName: '__session',\n *         injectScriptUrl: 'https://assets.monetizationos.com/web-components-latest.js',\n *         surfaceDecisionsIgnorePaths: '',\n *         originRequestHeaders: { 'X-Api-Key': process.env.ORIGIN_API_KEY! },\n *     })\n *     .withHtmlRewriter(myHtmlRewriterAdapter)\n *     .build()\n *\n * export default { fetch: (request: Request) => proxy.handle(request) }\n * ```\n */\nexport class MOSProxyBuilder {\n    private _config: MOSConfigInput | null = null\n    private _originFetcher: Fetcher = globalThis.fetch\n    private _apiFetcher: Fetcher = globalThis.fetch\n    private _htmlRewriter: HtmlRewriterAdapter | null = null\n    private _clientMetadataProvider: ClientMetadataProvider | null = null\n    private _logger: MOSProxyLogger | null = null\n    private _onHtmlPipelineError: MOSProxyHtmlPipelineErrorHandler | null = null\n    private _customEndpoints = true\n    private _linkRewriting = true\n    private _surfaceDecisions = true\n    private _htmlTransformation = true\n\n    withConfig(config: MOSConfigInput): this {\n        this._config = config\n        return this\n    }\n\n    withOriginFetcher(fetcher: Fetcher): this {\n        this._originFetcher = fetcher\n        return this\n    }\n\n    withApiFetcher(fetcher: Fetcher): this {\n        this._apiFetcher = fetcher\n        return this\n    }\n\n    withHtmlRewriter(rewriter: HtmlRewriterAdapter): this {\n        this._htmlRewriter = rewriter\n        return this\n    }\n\n    withClientMetadata(provider: ClientMetadataProvider): this {\n        this._clientMetadataProvider = provider\n        return this\n    }\n\n    withLogger(logger: MOSProxyLogger): this {\n        this._logger = logger\n        return this\n    }\n\n    /**\n     * Register a callback to handle HTML pipeline errors. The proxy fails open by default and\n     * returns the last safe (unconsumed) response — provide this if you want to shape that\n     * response yourself (e.g. render a custom error page, return a 503, or re-throw so your\n     * platform's error middleware handles it). If the callback throws or returns a non-Response\n     * value, the proxy logs a warning and falls back to the last safe response.\n     */\n    withHtmlPipelineErrorHandler(handler: MOSProxyHtmlPipelineErrorHandler): this {\n        this._onHtmlPipelineError = handler\n        return this\n    }\n\n    withoutCustomEndpoints(): this {\n        this._customEndpoints = false\n        return this\n    }\n\n    withoutLinkRewriting(): this {\n        this._linkRewriting = false\n        return this\n    }\n\n    withoutSurfaceDecisions(): this {\n        this._surfaceDecisions = false\n        return this\n    }\n\n    /**\n     * Disable the HTML transformation pipeline entirely (stages 3–6).\n     *\n     * Use for API-only proxies: neither an HTML rewriter adapter nor an API fetcher is required\n     * if custom endpoints and surface decisions are both disabled alongside this.\n     */\n    withoutHtmlTransformation(): this {\n        this._htmlTransformation = false\n        return this\n    }\n\n    build(): MOSProxy {\n        if (!this._config) {\n            throw new Error('MOSProxyBuilder: withConfig(...) is required')\n        }\n\n        const needsHtmlRewriter = this._htmlTransformation && this._surfaceDecisions\n        if (needsHtmlRewriter && !this._htmlRewriter) {\n            throw new Error(\n                'MOSProxyBuilder: withHtmlRewriter(...) is required when surface decisions is enabled; call withoutSurfaceDecisions() or withoutHtmlTransformation() if you do not need it',\n            )\n        }\n\n        const opts: MOSProxyOptions = {\n            config: this._config,\n            originFetcher: this._originFetcher,\n            apiFetcher: this._apiFetcher,\n            htmlRewriter: this._htmlRewriter,\n            clientMetadataProvider: this._clientMetadataProvider,\n            logger: this._logger ?? undefined,\n            onHtmlPipelineError: this._onHtmlPipelineError ?? undefined,\n            customEndpointsEnabled: this._customEndpoints,\n            linkRewritingEnabled: this._linkRewriting,\n            surfaceDecisionsEnabled: this._surfaceDecisions,\n            htmlTransformationEnabled: this._htmlTransformation,\n        }\n        return new MOSProxy(opts)\n    }\n}\n"]}

package/dist/adapters/ClientMetadataProvider.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Supplies platform-specific request metadata forwarded to the surface-decisions API
+ * under the `cloudflare` field of the request payload (kept for backwards-compat;
+ * future schema may rename).
+ *
+ * - Cloudflare: `{ cf: request.cf }`
+ * - Fastly: `{ fastly: { client: event.client, sigsci: {...} } }`
+ * - Akamai / unknown: `{}` is fine
+ */
+export interface ClientMetadataProvider {
+    build(request: Request): Record<string, unknown>;
+}

package/dist/adapters/ClientMetadataProvider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ClientMetadataProvider.js.map

package/dist/adapters/ClientMetadataProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientMetadataProvider.js","sourceRoot":"","sources":["../../src/adapters/ClientMetadataProvider.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Supplies platform-specific request metadata forwarded to the surface-decisions API\n * under the `cloudflare` field of the request payload (kept for backwards-compat;\n * future schema may rename).\n *\n * - Cloudflare: `{ cf: request.cf }`\n * - Fastly: `{ fastly: { client: event.client, sigsci: {...} } }`\n * - Akamai / unknown: `{}` is fine\n */\nexport interface ClientMetadataProvider {\n    build(request: Request): Record<string, unknown>\n}\n"]}

package/dist/adapters/Fetcher.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Dispatches an outbound HTTP request and returns its response.
+ *
+ * Used for both origin and MOS API traffic. Defaults to `globalThis.fetch`; override on
+ * runtimes that need a backend binding or custom dispatch:
+ * - Cloudflare: `fetch` (global fetch)
+ * - Fastly: `(req) => fetch(req, { backend: 'origin' })` (separate backend per use)
+ * - Akamai: wrap `httpRequest()` so surrounding code keeps talking web-standard `Request`/`Response`
+ */
+export type Fetcher = (request: Request) => Promise<Response>;

package/dist/adapters/Fetcher.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Fetcher.js.map

package/dist/adapters/Fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Fetcher.js","sourceRoot":"","sources":["../../src/adapters/Fetcher.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Dispatches an outbound HTTP request and returns its response.\n *\n * Used for both origin and MOS API traffic. Defaults to `globalThis.fetch`; override on\n * runtimes that need a backend binding or custom dispatch:\n * - Cloudflare: `fetch` (global fetch)\n * - Fastly: `(req) => fetch(req, { backend: 'origin' })` (separate backend per use)\n * - Akamai: wrap `httpRequest()` so surrounding code keeps talking web-standard `Request`/`Response`\n */\nexport type Fetcher = (request: Request) => Promise<Response>\n"]}

package/dist/adapters/HtmlRewriterAdapter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Platform-agnostic contract over lol-html-style streaming HTML rewriters
+ * (Cloudflare's `HTMLRewriter`, Fastly's `HTMLRewritingStream`, Akamai's `HtmlRewritingStream`).
+ *
+ * An adapter creates a new rewriter session per call to `create()`; the session is a builder
+ * that accepts selectors + handlers via `.on(...)` and produces a transformed `Response` via
+ * `.transform(response)`.
+ *
+ * `capabilities` advertises which lol-html features the underlying implementation supports.
+ * Consumers dispatch on these flags to enable or fall back paths (e.g., range-replacement
+ * via `element.onEndTag` vs. a sentinel post-process).
+ */
+export interface HtmlRewriterAdapter {
+    readonly capabilities: HtmlRewriterCapabilities;
+    create(): HtmlRewriterSession;
+}
+export interface HtmlRewriterCapabilities {
+    /** Element handlers can register an end-tag callback via `element.onEndTag(cb)`. */
+    onEndTag: boolean;
+    /** `:nth-child()` CSS pseudo-class is supported in selectors. */
+    nthChild: boolean;
+}
+export interface HtmlRewriterSession {
+    on(selector: string, handlers: ElementHandlers): HtmlRewriterSession;
+    transform(response: Response): Response;
+}
+export interface ElementHandlers {
+    element?(element: RewriterElement): void | Promise<void>;
+    text?(text: RewriterText): void | Promise<void>;
+}
+export interface ContentOptions {
+    html?: boolean;
+}
+/**
+ * Mirrors the Cloudflare `Element` API (a lol-html `HTMLRewriterElement`).
+ *
+ * Adapters may throw from `onEndTag` on runtimes that don't support it; callers should
+ * check `capabilities.onEndTag` before relying on it, or catch the error.
+ */
+export interface RewriterElement {
+    readonly removed: boolean;
+    readonly tagName: string;
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    before(content: string, options?: ContentOptions): void;
+    after(content: string, options?: ContentOptions): void;
+    prepend(content: string, options?: ContentOptions): void;
+    append(content: string, options?: ContentOptions): void;
+    replace(content: string, options?: ContentOptions): void;
+    remove(): void;
+    onEndTag?(callback: () => void | Promise<void>): void;
+}
+export interface RewriterText {
+    readonly text: string;
+    readonly lastInTextNode: boolean;
+    readonly removed: boolean;
+    remove(): void;
+}

package/dist/adapters/HtmlRewriterAdapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=HtmlRewriterAdapter.js.map