@pagepocket/lib 0.7.1 → 0.8.1

package/dist/plugins/ordering.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortPluginsDeterministically = void 0;
+const priorityOf = (plugin) => plugin.order?.priority ?? 0;
+const sortPluginsDeterministically = (plugins) => {
+    return plugins.slice().sort((left, right) => {
+        const pLeft = priorityOf(left);
+        const pRight = priorityOf(right);
+        if (pLeft !== pRight) {
+            return pRight - pLeft;
+        }
+        if (left.name < right.name)
+            return -1;
+        if (left.name > right.name)
+            return 1;
+        return 0;
+    });
+};
+exports.sortPluginsDeterministically = sortPluginsDeterministically;

package/dist/plugins/types.d.ts

@@ -0,0 +1,51 @@
+import type { ReplaceElementsConfig, PageSnapshot } from "../types";
+import type { CaptureBundle } from "../bundle/types";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface PluginContext {
+    entryUrl: string;
+    now(): number;
+    log(level: LogLevel, msg: string, meta?: unknown): void;
+    config: Record<string, unknown>;
+}
+export interface RunContext extends PluginContext {
+    bundle: CaptureBundle;
+    snapshot?: PageSnapshot;
+    sink: ArtifactSink;
+    outputDir?: string;
+}
+export type OutputRequirement = "bundle" | "snapshot";
+export interface OutputWriter {
+    id: string;
+    requires: OutputRequirement;
+    write(ctx: RunContext): Promise<void>;
+}
+export interface PluginOrder {
+    priority?: number;
+    before?: string[];
+    after?: string[];
+}
+export interface PagePocketPlugin {
+    name: string;
+    version?: string;
+    order?: PluginOrder;
+    /** Contribute Cheerio rewrite rules (applied only if snapshot is built). */
+    replaceElements?: (ctx: PluginContext) => ReplaceElementsConfig | Promise<ReplaceElementsConfig>;
+    outputs?: OutputWriter[];
+    hooks?: {
+        init?(ctx: PluginContext): void | Promise<void>;
+        shutdown?(ctx: PluginContext): void | Promise<void>;
+    };
+}
+export interface ArtifactSink {
+    writeFile(relativePath: string, data: Uint8Array, contentType?: string): Promise<void>;
+    writeJson(relativePath: string, value: unknown): Promise<void>;
+    createWriteStream?(relativePath: string, options?: {
+        contentType?: string;
+        overwrite?: boolean;
+    }): NodeJS.WritableStream | undefined;
+    record?(meta: {
+        relativePath: string;
+        contentType?: string;
+        role?: string;
+    }): void;
+}

package/dist/plugins/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/preload.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildPreloadScript = void 0;
-const hackers_1 = require("./hackers");
-const buildPreloadScript = () => {
+import { preloadHackers } from "./hackers/index.js";
+export const buildPreloadScript = () => {
     const context = { stage: "preload" };
-    const hackerScripts = hackers_1.preloadHackers
+    const hackerScripts = preloadHackers
         .map((hacker) => `  // hacker:${hacker.id}\n${hacker.build(context)}`)
         .join("\n");
     return `
@@ -57,4 +54,3 @@ ${hackerScripts}
 })();
 `;
 };
-exports.buildPreloadScript = buildPreloadScript;

package/dist/replace-elements/actions.d.ts

@@ -0,0 +1,5 @@
+import type { Cheerio, CheerioAPI } from "cheerio";
+import type { ReplaceAction } from "../types.js";
+export declare const isHtmlElement: ($: CheerioAPI, $el: Cheerio<any>) => boolean;
+export declare const applyReplaceAction: ($: CheerioAPI, $el: Cheerio<any>, action: ReplaceAction) => void;
+export declare const tagNameMatches: (el: unknown, expected?: string) => boolean;

package/dist/replace-elements/actions.js

@@ -0,0 +1,86 @@
+const getNodeName = (el) => {
+    if (!el || typeof el !== "object")
+        return null;
+    const name = el.name;
+    return typeof name === "string" ? name : null;
+};
+const getNodeType = (el) => {
+    if (!el || typeof el !== "object")
+        return null;
+    const type = el.type;
+    return typeof type === "string" ? type : null;
+};
+export const isHtmlElement = ($, $el) => {
+    if (!$el || !$el.length)
+        return false;
+    if (!$el.closest("html").length)
+        return false;
+    const el = $el.get(0);
+    if (!el)
+        return false;
+    const type = getNodeType(el);
+    if (type && type !== "tag")
+        return false;
+    return true;
+};
+export const applyReplaceAction = ($, $el, action) => {
+    switch (action.type) {
+        case "replaceWithHtml": {
+            $el.replaceWith(action.html);
+            return;
+        }
+        case "replaceWithElement": {
+            const next = $(`<${action.tagName}></${action.tagName}>`);
+            if (action.attrs) {
+                for (const [key, value] of Object.entries(action.attrs)) {
+                    if (value === null) {
+                        next.removeAttr(key);
+                        continue;
+                    }
+                    next.attr(key, value);
+                }
+            }
+            if (action.html !== undefined) {
+                next.html(action.html);
+            }
+            else if (action.textContent !== undefined) {
+                next.text(action.textContent);
+            }
+            $el.replaceWith(next);
+            return;
+        }
+        case "renameTag": {
+            const to = action.to;
+            const keepAttributes = action.keepAttributes !== false;
+            const keepChildren = action.keepChildren !== false;
+            const next = $(`<${to}></${to}>`);
+            if (keepAttributes) {
+                const attrs = ($el.attr() ?? {});
+                for (const [key, value] of Object.entries(attrs)) {
+                    next.attr(key, value);
+                }
+            }
+            if (keepChildren) {
+                next.append($el.contents());
+            }
+            $el.replaceWith(next);
+            return;
+        }
+        case "remove": {
+            $el.remove();
+            return;
+        }
+        default: {
+            const exhaustive = action;
+            throw new Error(`Unknown replace action: ${String(exhaustive?.type ?? "")}`);
+        }
+    }
+};
+export const tagNameMatches = (el, expected) => {
+    if (!expected)
+        return true;
+    const name = getNodeName(el);
+    if (!name)
+        return false;
+    return name.toLowerCase() === expected.toLowerCase();
+};

package/dist/replace-elements/match.d.ts

@@ -0,0 +1,5 @@
+import type { Cheerio, CheerioAPI } from "cheerio";
+import type { MatchQuery } from "../types.js";
+import { isHtmlElement } from "./actions.js";
+export declare const elementMatchesFilter: ($: CheerioAPI, $el: Cheerio<any>, filter: MatchQuery | null) => boolean;
+export { isHtmlElement };

package/dist/replace-elements/match.js

@@ -0,0 +1,46 @@
+import { isHtmlElement, tagNameMatches } from "./actions.js";
+const idMatches = (_$, $el, expected) => {
+    if (!expected)
+        return true;
+    return ($el.attr("id") || "") === expected;
+};
+const attrsMatch = ($el, attrs) => {
+    if (!attrs)
+        return true;
+    for (const [name, expected] of Object.entries(attrs)) {
+        const actual = $el.attr(name);
+        if (expected === true) {
+            if (actual === undefined)
+                return false;
+            continue;
+        }
+        if (typeof expected === "string") {
+            if (actual !== expected)
+                return false;
+            continue;
+        }
+        if (expected instanceof RegExp) {
+            if (actual === undefined)
+                return false;
+            if (!expected.test(actual))
+                return false;
+            continue;
+        }
+    }
+    return true;
+};
+export const elementMatchesFilter = ($, $el, filter) => {
+    if (!filter || typeof filter === "string")
+        return true;
+    const el = $el.get(0);
+    if (!el)
+        return false;
+    if (!tagNameMatches(el, filter.tagName))
+        return false;
+    if (!idMatches($, $el, filter.id))
+        return false;
+    if (!attrsMatch($el, filter.attrs))
+        return false;
+    return true;
+};
+export { isHtmlElement };

package/dist/replace-elements/normalize.d.ts

@@ -0,0 +1,21 @@
+import type { ApplyOptions, MatchQuery, ReplaceElementFn, ReplaceElementRule, ReplaceElementsConfig } from "../types.js";
+declare const defaultApply: Required<Pick<ApplyOptions, "scope" | "limit" | "onReplaced">>;
+type NormalizedItem = {
+    kind: "rule";
+    ruleIndex: number;
+    rule: ReplaceElementRule;
+    apply: typeof defaultApply;
+} | {
+    kind: "fn";
+    ruleIndex: number;
+    query: string;
+    run: ReplaceElementFn;
+    apply: typeof defaultApply;
+};
+export declare const normalizeMatchToSelector: (match: MatchQuery) => {
+    selector: string;
+    filter: MatchQuery | null;
+};
+export declare const normalizeReplaceElementsConfig: (replaceElements: ReplaceElementsConfig) => NormalizedItem[];
+export type { NormalizedItem };
+export { defaultApply };

package/dist/replace-elements/normalize.js

@@ -0,0 +1,50 @@
+const defaultApply = {
+    scope: "document",
+    limit: "all",
+    onReplaced: "stop"
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null;
+const normalizeApply = (apply) => ({
+    scope: apply?.scope ?? defaultApply.scope,
+    limit: apply?.limit ?? defaultApply.limit,
+    onReplaced: apply?.onReplaced ?? defaultApply.onReplaced
+});
+export const normalizeMatchToSelector = (match) => {
+    if (typeof match === "string") {
+        return { selector: match, filter: null };
+    }
+    return { selector: match.selector ?? "*", filter: match };
+};
+export const normalizeReplaceElementsConfig = (replaceElements) => {
+    const items = [];
+    replaceElements.forEach((item, ruleIndex) => {
+        if (typeof item === "function") {
+            items.push({
+                kind: "fn",
+                ruleIndex,
+                query: "*",
+                run: item,
+                apply: normalizeApply(undefined)
+            });
+            return;
+        }
+        if (!isPlainObject(item)) {
+            throw new Error("replaceElements item must be a rule object or function");
+        }
+        if ("run" in item && typeof item.run === "function") {
+            const fnItem = item;
+            items.push({
+                kind: "fn",
+                ruleIndex,
+                query: fnItem.query,
+                run: fnItem.run,
+                apply: normalizeApply(fnItem.apply)
+            });
+            return;
+        }
+        const rule = item;
+        items.push({ kind: "rule", ruleIndex, rule, apply: normalizeApply(rule.apply) });
+    });
+    return items;
+};
+export { defaultApply };

package/dist/replace-elements.d.ts

@@ -1,5 +1,5 @@
 import type { CheerioAPI } from "cheerio";
-import type { ReplaceElementsConfig } from "./types";
+import type { ReplaceElementsConfig } from "./types.js";
 export declare const applyReplaceElements: (input: {
     $: CheerioAPI;
     entryUrl: string;

package/dist/replace-elements.js

@@ -1,186 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyReplaceElements = void 0;
-const defaultApply = {
-    scope: "document",
-    limit: "all",
-    onReplaced: "stop"
-};
-const isPlainObject = (value) => typeof value === "object" && value !== null;
-const normalizeApply = (apply) => ({
-    scope: apply?.scope ?? defaultApply.scope,
-    limit: apply?.limit ?? defaultApply.limit,
-    onReplaced: apply?.onReplaced ?? defaultApply.onReplaced
-});
-const normalizeMatchToSelector = (match) => {
-    if (typeof match === "string") {
-        return { selector: match, filter: null };
-    }
-    return { selector: match.selector ?? "*", filter: match };
-};
-const getNodeName = (el) => {
-    if (!el || typeof el !== "object")
-        return null;
-    const name = el.name;
-    return typeof name === "string" ? name : null;
-};
-const getNodeType = (el) => {
-    if (!el || typeof el !== "object")
-        return null;
-    const type = el.type;
-    return typeof type === "string" ? type : null;
-};
-const tagNameMatches = (el, expected) => {
-    if (!expected)
-        return true;
-    const name = getNodeName(el);
-    if (!name)
-        return false;
-    return name.toLowerCase() === expected.toLowerCase();
-};
-const idMatches = (_$, $el, expected) => {
-    if (!expected)
-        return true;
-    return ($el.attr("id") || "") === expected;
-};
-const attrsMatch = ($el, attrs) => {
-    if (!attrs)
-        return true;
-    for (const [name, expected] of Object.entries(attrs)) {
-        const actual = $el.attr(name);
-        if (expected === true) {
-            if (actual === undefined)
-                return false;
-            continue;
-        }
-        if (typeof expected === "string") {
-            if (actual !== expected)
-                return false;
-            continue;
-        }
-        if (expected instanceof RegExp) {
-            if (actual === undefined)
-                return false;
-            if (!expected.test(actual))
-                return false;
-            continue;
-        }
-    }
-    return true;
-};
-const elementMatchesFilter = ($, $el, filter) => {
-    if (!filter || typeof filter === "string")
-        return true;
-    const el = $el.get(0);
-    if (!el)
-        return false;
-    if (!tagNameMatches(el, filter.tagName))
-        return false;
-    if (!idMatches($, $el, filter.id))
-        return false;
-    if (!attrsMatch($el, filter.attrs))
-        return false;
-    return true;
-};
-const isHtmlElement = ($, $el) => {
-    if (!$el || !$el.length)
-        return false;
-    if (!$el.closest("html").length)
-        return false;
-    const el = $el.get(0);
-    if (!el)
-        return false;
-    // Cheerio nodes for tags have a "type" of "tag".
-    const type = getNodeType(el);
-    if (type && type !== "tag")
-        return false;
-    return true;
-};
-const applyReplaceAction = ($, $el, action) => {
-    switch (action.type) {
-        case "replaceWithHtml": {
-            $el.replaceWith(action.html);
-            return;
-        }
-        case "replaceWithElement": {
-            const next = $(`<${action.tagName}></${action.tagName}>`);
-            if (action.attrs) {
-                for (const [key, value] of Object.entries(action.attrs)) {
-                    if (value === null) {
-                        next.removeAttr(key);
-                        continue;
-                    }
-                    next.attr(key, value);
-                }
-            }
-            if (action.html !== undefined) {
-                next.html(action.html);
-            }
-            else if (action.textContent !== undefined) {
-                next.text(action.textContent);
-            }
-            $el.replaceWith(next);
-            return;
-        }
-        case "renameTag": {
-            const to = action.to;
-            const keepAttributes = action.keepAttributes !== false;
-            const keepChildren = action.keepChildren !== false;
-            const next = $(`<${to}></${to}>`);
-            if (keepAttributes) {
-                const attrs = ($el.attr() ?? {});
-                for (const [key, value] of Object.entries(attrs)) {
-                    next.attr(key, value);
-                }
-            }
-            if (keepChildren) {
-                next.append($el.contents());
-            }
-            $el.replaceWith(next);
-            return;
-        }
-        case "remove": {
-            $el.remove();
-            return;
-        }
-        default: {
-            const exhaustive = action;
-            throw new Error(`Unknown replace action: ${String(exhaustive?.type ?? "")}`);
-        }
-    }
-};
-const normalizeReplaceElementsConfig = (replaceElements) => {
-    const items = [];
-    replaceElements.forEach((item, ruleIndex) => {
-        if (typeof item === "function") {
-            items.push({
-                kind: "fn",
-                ruleIndex,
-                query: "*",
-                run: item,
-                apply: normalizeApply(undefined)
-            });
-            return;
-        }
-        if (!isPlainObject(item)) {
-            throw new Error("replaceElements item must be a rule object or function");
-        }
-        if ("run" in item && typeof item.run === "function") {
-            const fnItem = item;
-            items.push({
-                kind: "fn",
-                ruleIndex,
-                query: fnItem.query,
-                run: fnItem.run,
-                apply: normalizeApply(fnItem.apply)
-            });
-            return;
-        }
-        const rule = item;
-        items.push({ kind: "rule", ruleIndex, rule, apply: normalizeApply(rule.apply) });
-    });
-    return items;
-};
+import { applyReplaceAction } from "./replace-elements/actions.js";
+import { elementMatchesFilter, isHtmlElement } from "./replace-elements/match.js";
+import { normalizeMatchToSelector, normalizeReplaceElementsConfig } from "./replace-elements/normalize.js";
+// helper logic moved to ./replace-elements/*
 const runFnRuleOnSelection = async (input) => {
     const { $, item } = input;
     const selection = $(item.query).toArray();
@@ -210,7 +31,7 @@ const runFnRuleOnSelection = async (input) => {
         }
     }
 };
-const applyReplaceElements = async (input) => {
+export const applyReplaceElements = async (input) => {
     if (!input.replaceElements || input.replaceElements.length === 0) {
         return;
     }
@@ -255,4 +76,3 @@ const applyReplaceElements = async (input) => {
         }
     }
 };
-exports.applyReplaceElements = applyReplaceElements;

package/dist/replay/match-api.d.ts

@@ -0,0 +1,10 @@
+import type { ApiRecord } from "../types.js";
+export type MatchApiOptions = {
+    records: ApiRecord[];
+    byKey?: Map<string, ApiRecord>;
+    baseUrl: string;
+    method: string;
+    url: string;
+    body?: unknown;
+};
+export declare function matchAPI(options: MatchApiOptions): ApiRecord | undefined;