infinite-tag 0.1.1

package/dist/src/manifest.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertConfinedManifestFileEntry, resolveConfinedAppRoot, writeFileAtomic } from "./frameworks/shared.js";
+export const installManifestRelativePath = ".infinite/install.json";
+export function installManifestPath(root) {
+    return join(root, installManifestRelativePath);
+}
+export function readInstallManifest(root) {
+    const manifestPath = installManifestPath(root);
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    const raw = readFileSync(manifestPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Corrupt .infinite/install.json — cannot parse manifest. Remove it manually to reset.");
+    }
+    if (!isInstallManifestShape(parsed)) {
+        throw new Error("Corrupt .infinite/install.json — manifest is missing expected fields. Remove it manually to reset.");
+    }
+    assertManifestConfined(root, parsed);
+    return parsed;
+}
+// A tampered install.json must never drive reads/writes/removals outside the
+// workspace root. Validating here — the single place the manifest is read from
+// disk — confines every consumer (uninstall, verify, inspect) at once.
+function assertManifestConfined(root, manifest) {
+    resolveConfinedAppRoot(root, manifest.appRoot);
+    for (const relativePath of manifest.files) {
+        assertConfinedManifestFileEntry(root, relativePath);
+    }
+}
+function isInstallManifestShape(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.workspaceId === "string" &&
+        typeof candidate.appRoot === "string" &&
+        typeof candidate.framework === "string" &&
+        Array.isArray(candidate.providers) &&
+        Array.isArray(candidate.files) &&
+        Array.isArray(candidate.envKeys) &&
+        typeof candidate.contentHashes === "object" &&
+        candidate.contentHashes !== null);
+}
+export function writeInstallManifest(root, manifest) {
+    const manifestPath = installManifestPath(root);
+    writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return manifestPath;
+}
+export function writeInstallManifestIfChanged(root, manifest) {
+    const manifestPath = installManifestPath(root);
+    const nextContents = `${JSON.stringify(manifest, null, 2)}\n`;
+    const currentContents = existsSync(manifestPath) ? readFileSync(manifestPath, "utf8") : null;
+    if (currentContents === nextContents) {
+        return {
+            changed: false,
+            manifestPath
+        };
+    }
+    writeFileAtomic(manifestPath, nextContents);
+    return {
+        changed: true,
+        manifestPath
+    };
+}
+export function computeContentHashes(root, files) {
+    const contentHashes = {};
+    for (const relativePath of files) {
+        const absolutePath = join(root, relativePath);
+        if (!existsSync(absolutePath)) {
+            continue;
+        }
+        const hash = createHash("sha256").update(readFileSync(absolutePath)).digest("hex");
+        contentHashes[relativePath] = hash;
+    }
+    return contentHashes;
+}

package/dist/src/package-manager.d.ts

@@ -0,0 +1,6 @@
+import type { PackageManager, PackageManagerCommands, PackageManagerDetection } from "./types.js";
+export declare function detectPackageManager(root: string, override?: PackageManager): PackageManagerDetection;
+export declare function buildPackageManagerCommands(manager: PackageManager, options: {
+    pinnedVersion: string;
+    workspaceId: string;
+}): PackageManagerCommands;

package/dist/src/package-manager.js

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+const lockfileOrder = [
+    { manager: "pnpm", files: ["pnpm-lock.yaml"] },
+    { manager: "npm", files: ["package-lock.json"] },
+    { manager: "yarn", files: ["yarn.lock"] },
+    { manager: "bun", files: ["bun.lock", "bun.lockb"] }
+];
+function resolvePackageRoot() {
+    for (const relativePath of ["..", "../.."]) {
+        const candidate = fileURLToPath(new URL(relativePath, import.meta.url));
+        if (existsSync(join(candidate, "package.json"))) {
+            return candidate;
+        }
+    }
+    throw new Error("Unable to resolve the infinite-tag package root.");
+}
+const packageRoot = resolvePackageRoot();
+const instrumentPackage = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+const instrumentCliEntry = join(packageRoot, "dist/src/cli.js");
+const repoRoot = join(packageRoot, "../..");
+const instrumentBinaryName = Object.keys(instrumentPackage.bin ?? {})[0] ?? "infinite-tag";
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function buildPublishedCommands(manager, options) {
+    const pinnedPackage = `${instrumentPackage.name}@${options.pinnedVersion}`;
+    const workspaceFlag = `--workspace ${options.workspaceId}`;
+    switch (manager) {
+        case "npm":
+            return {
+                packageManager: manager,
+                oneOff: `npm exec ${pinnedPackage} -- install ${workspaceFlag}`,
+                repeatableInstall: `npm install -D ${pinnedPackage}`,
+                repeatableRun: `npm exec ${instrumentBinaryName} -- install ${workspaceFlag}`
+            };
+        case "pnpm":
+            return {
+                packageManager: manager,
+                oneOff: `pnpm dlx ${pinnedPackage} install ${workspaceFlag}`,
+                repeatableInstall: `pnpm add -D ${pinnedPackage}`,
+                repeatableRun: `pnpm exec ${instrumentBinaryName} install ${workspaceFlag}`
+            };
+        case "yarn":
+            return {
+                packageManager: manager,
+                oneOff: `yarn dlx ${pinnedPackage} install ${workspaceFlag}`,
+                repeatableInstall: `yarn add -D ${pinnedPackage}`,
+                repeatableRun: `yarn ${instrumentBinaryName} install ${workspaceFlag}`
+            };
+        case "bun":
+            return {
+                packageManager: manager,
+                oneOff: `bunx ${pinnedPackage} install ${workspaceFlag}`,
+                repeatableInstall: `bun add -d ${pinnedPackage}`,
+                repeatableRun: `bunx ${instrumentBinaryName} install ${workspaceFlag}`
+            };
+    }
+}
+function buildLocalWorkspaceCommand(options) {
+    return [
+        `pnpm --dir ${shellQuote(repoRoot)} --filter ${instrumentPackage.name} build`,
+        `node ${shellQuote(instrumentCliEntry)} install --root ${shellQuote(repoRoot)} --workspace ${options.workspaceId}`
+    ].join(" && ");
+}
+export function detectPackageManager(root, override) {
+    if (override) {
+        return {
+            kind: override,
+            reason: "override",
+            lockfiles: []
+        };
+    }
+    const matches = lockfileOrder.flatMap((entry) => entry.files
+        .filter((file) => existsSync(join(root, file)))
+        .map((file) => ({ manager: entry.manager, file })));
+    if (matches.length === 0) {
+        return {
+            kind: "unknown",
+            reason: "no-lockfile",
+            lockfiles: []
+        };
+    }
+    const uniqueManagers = [...new Set(matches.map((match) => match.manager))];
+    if (uniqueManagers.length > 1) {
+        return {
+            kind: "ambiguous",
+            reason: "multiple-lockfiles",
+            lockfiles: matches.map((match) => match.file)
+        };
+    }
+    return {
+        kind: uniqueManagers[0],
+        reason: "lockfile",
+        lockfiles: matches.map((match) => match.file)
+    };
+}
+export function buildPackageManagerCommands(manager, options) {
+    const publishedCommands = buildPublishedCommands(manager, options);
+    if (instrumentPackage.private !== true) {
+        return publishedCommands;
+    }
+    return {
+        packageManager: manager,
+        oneOff: buildLocalWorkspaceCommand({ workspaceId: options.workspaceId }),
+        repeatableInstall: `After publishing ${instrumentPackage.name}, install it with: ${publishedCommands.repeatableInstall}`,
+        repeatableRun: `After publishing ${instrumentPackage.name}, re-run it with: ${publishedCommands.repeatableRun}`
+    };
+}

package/dist/src/plan.d.ts

@@ -0,0 +1,9 @@
+import type { InspectResult, InstallPlan, PackageManager, WorkspaceInstallArtifacts } from "./types.js";
+export interface PlanInstallationOptions {
+    root: string;
+    inspect?: InspectResult;
+    workspaceId?: string;
+    packageManager?: PackageManager;
+    artifacts: WorkspaceInstallArtifacts;
+}
+export declare function planInstallation(options: PlanInstallationOptions): InstallPlan;

package/dist/src/plan.js

@@ -0,0 +1,97 @@
+import { join } from "node:path";
+import { getFrameworkAdapter, isSupportedFramework } from "./frameworks/index.js";
+import { normalizeAppRelativePath } from "./frameworks/shared.js";
+import { getProviderAdapter } from "./providers/index.js";
+import { detectUnmanagedProviders, inspectWorkspace } from "./inspect.js";
+const providerOrder = ["ga4", "posthog", "x"];
+function selectedProviders(artifacts) {
+    return providerOrder.filter((providerId) => artifacts[providerId] !== undefined);
+}
+export function planInstallation(options) {
+    const inspectResult = options.inspect ??
+        inspectWorkspace(options.root, {
+            packageManager: options.packageManager
+        });
+    const providers = selectedProviders(options.artifacts);
+    const assumptions = [...inspectResult.assumptions];
+    const blockers = [...inspectResult.blockers];
+    if (!isSupportedFramework(inspectResult.framework)) {
+        if (!blockers.includes("Unsupported repository shape for instrumentation.")) {
+            blockers.push("Unsupported repository shape for instrumentation.");
+        }
+        return {
+            framework: inspectResult.framework,
+            providers,
+            files: [],
+            envKeys: [],
+            applyMode: "plan-only",
+            instructions: [],
+            assumptions,
+            blockers,
+            confidence: Math.min(inspectResult.confidence, 0.45),
+            appRoot: inspectResult.appRoot,
+            packageManager: inspectResult.packageManager,
+            repoStatus: inspectResult.repoStatus,
+            workspaceId: options.workspaceId,
+            artifacts: options.artifacts
+        };
+    }
+    if (providers.length === 0) {
+        blockers.push("No supported public install artifacts were provided.");
+    }
+    const appRootAbsolute = inspectResult.appRoot === "." ? options.root : join(options.root, inspectResult.appRoot);
+    const frameworkAdapter = getFrameworkAdapter(inspectResult.framework);
+    const frameworkDraft = frameworkAdapter?.plan(appRootAbsolute);
+    if (frameworkDraft) {
+        assumptions.push(...frameworkDraft.assumptions);
+        blockers.push(...frameworkDraft.blockers);
+    }
+    const unmanagedProviders = detectUnmanagedProviders(appRootAbsolute);
+    const envKeys = [];
+    const instructions = [];
+    for (const providerId of providers) {
+        const adapter = getProviderAdapter(providerId);
+        if (unmanagedProviders.includes(providerId)) {
+            blockers.push(`Existing ${adapter.displayName} analytics wiring was detected in this repo and is not managed by Infinite. Remove or migrate the existing ${adapter.displayName} tag before installing it with infinite-tag.`);
+        }
+        const providerPlan = adapter.plan(inspectResult.framework, options.artifacts[providerId]);
+        assumptions.push(...providerPlan.assumptions);
+        blockers.push(...providerPlan.blockers);
+        instructions.push(...providerPlan.instructions);
+        envKeys.push(...adapter.envKeys(inspectResult.framework));
+    }
+    const uniqueEnvKeys = [...new Set(envKeys)];
+    const files = (frameworkDraft?.files ?? []).map((file) => normalizeAppRelativePath(inspectResult.appRoot, file));
+    const frameworkInstructions = (frameworkDraft?.instructions ?? []).map((instruction) => ({
+        ...instruction,
+        path: normalizeAppRelativePath(inspectResult.appRoot, instruction.path)
+    }));
+    const providerInstructions = instructions.map((instruction) => ({
+        ...instruction,
+        path: normalizeAppRelativePath(inspectResult.appRoot, instruction.path)
+    }));
+    const applyMode = frameworkDraft?.applyMode ?? "plan-only";
+    let confidence = frameworkDraft?.confidence ?? inspectResult.confidence;
+    if (providers.length > 0) {
+        confidence = Math.min(0.99, confidence + Math.min(providers.length, 3) * 0.03);
+    }
+    if (blockers.length > 0) {
+        confidence = Math.min(confidence, 0.45);
+    }
+    return {
+        framework: inspectResult.framework,
+        providers,
+        files,
+        envKeys: uniqueEnvKeys,
+        applyMode,
+        instructions: [...frameworkInstructions, ...providerInstructions],
+        assumptions: [...new Set(assumptions)],
+        blockers: [...new Set(blockers)],
+        confidence,
+        appRoot: inspectResult.appRoot,
+        packageManager: inspectResult.packageManager,
+        repoStatus: inspectResult.repoStatus,
+        workspaceId: options.workspaceId,
+        artifacts: options.artifacts
+    };
+}

package/dist/src/providers/ga4.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderAdapter } from "../types.js";
+export declare const ga4ProviderAdapter: ProviderAdapter;

package/dist/src/providers/ga4.js

@@ -0,0 +1,73 @@
+import { jsLiteral, urlQueryValue, validateGa4MeasurementId } from "./validate.js";
+function frameworkEnvKeys(framework) {
+    switch (framework) {
+        case "next-app-router":
+        case "next-pages-router":
+            return ["NEXT_PUBLIC_GA4_MEASUREMENT_ID"];
+        case "vite-react":
+            return ["VITE_GA4_MEASUREMENT_ID"];
+        case "static-html":
+            return [];
+    }
+}
+export const ga4ProviderAdapter = {
+    id: "ga4",
+    displayName: "GA4",
+    envKeys(framework) {
+        return frameworkEnvKeys(framework);
+    },
+    plan(framework, artifact) {
+        const measurementId = artifact && typeof artifact === "object" && "measurementId" in artifact
+            ? artifact.measurementId
+            : undefined;
+        const invalid = validateGa4MeasurementId(measurementId);
+        if (invalid) {
+            return { assumptions: [], blockers: [invalid], instructions: [] };
+        }
+        const instructions = [
+            {
+                path: frameworkInstructionPath(framework),
+                action: framework === "static-html" ? "modify" : "create",
+                description: framework === "static-html"
+                    ? "Inject the GA4 public loader and gtag bootstrap into index.html."
+                    : "Add the GA4 public loader and gtag bootstrap to the managed analytics module.",
+                provider: "ga4",
+                snippet: framework === "static-html"
+                    ? buildHtmlSnippet(measurementId)
+                    : buildBootstrapSnippet(measurementId)
+            }
+        ];
+        return {
+            assumptions: ["GA4 wiring will use only the public measurementId artifact."],
+            blockers: [],
+            instructions
+        };
+    }
+};
+function frameworkInstructionPath(framework) {
+    switch (framework) {
+        case "static-html":
+            return "index.html";
+        case "vite-react":
+            return "src/lib/infinite-analytics.ts";
+        case "next-app-router":
+        case "next-pages-router":
+            return "lib/infinite-analytics.ts";
+    }
+}
+function buildBootstrapSnippet(measurementId) {
+    return [
+        "window.dataLayer = window.dataLayer || [];",
+        "function gtag(){window.dataLayer.push(arguments);}",
+        "gtag('js', new Date());",
+        `gtag('config', ${jsLiteral(measurementId)});`
+    ].join("\n");
+}
+function buildHtmlSnippet(measurementId) {
+    return [
+        `<script async src="https://www.googletagmanager.com/gtag/js?id=${urlQueryValue(measurementId)}"></script>`,
+        "<script>",
+        buildBootstrapSnippet(measurementId),
+        "</script>"
+    ].join("\n");
+}

package/dist/src/providers/index.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderAdapter, ProviderId } from "../types.js";
+export declare const providerAdapters: Record<ProviderId, ProviderAdapter>;
+export declare function getProviderAdapter(providerId: ProviderId): ProviderAdapter;

package/dist/src/providers/index.js

@@ -0,0 +1,11 @@
+import { ga4ProviderAdapter } from "./ga4.js";
+import { posthogProviderAdapter } from "./posthog.js";
+import { xProviderAdapter } from "./x.js";
+export const providerAdapters = {
+    ga4: ga4ProviderAdapter,
+    posthog: posthogProviderAdapter,
+    x: xProviderAdapter
+};
+export function getProviderAdapter(providerId) {
+    return providerAdapters[providerId];
+}

package/dist/src/providers/posthog.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderAdapter } from "../types.js";
+export declare const posthogProviderAdapter: ProviderAdapter;

package/dist/src/providers/posthog.js

@@ -0,0 +1,77 @@
+import { jsLiteral, normalizePosthogApiHost, validatePosthogProjectKey } from "./validate.js";
+function frameworkEnvKeys(framework) {
+    switch (framework) {
+        case "next-app-router":
+        case "next-pages-router":
+            return ["NEXT_PUBLIC_POSTHOG_API_HOST", "NEXT_PUBLIC_POSTHOG_KEY"];
+        case "vite-react":
+            return ["VITE_POSTHOG_API_HOST", "VITE_POSTHOG_KEY"];
+        case "static-html":
+            return [];
+    }
+}
+export const posthogProviderAdapter = {
+    id: "posthog",
+    displayName: "PostHog",
+    envKeys(framework) {
+        return frameworkEnvKeys(framework);
+    },
+    plan(framework, artifact) {
+        const projectKey = artifact && typeof artifact === "object" && "projectKey" in artifact
+            ? artifact.projectKey
+            : undefined;
+        const apiHost = artifact && typeof artifact === "object" && "apiHost" in artifact ? artifact.apiHost : undefined;
+        const blockers = [];
+        const keyError = validatePosthogProjectKey(projectKey);
+        if (keyError) {
+            blockers.push(keyError);
+        }
+        const host = normalizePosthogApiHost(apiHost);
+        const apiHostOrigin = "origin" in host ? host.origin : undefined;
+        if ("error" in host) {
+            blockers.push(host.error);
+        }
+        const ready = blockers.length === 0 && typeof projectKey === "string" && apiHostOrigin !== undefined;
+        return {
+            assumptions: ready
+                ? ["PostHog wiring will use only the public projectKey and apiHost artifacts."]
+                : [],
+            blockers,
+            instructions: ready
+                ? [
+                    {
+                        path: frameworkInstructionPath(framework),
+                        action: framework === "static-html" ? "modify" : "create",
+                        description: framework === "static-html"
+                            ? "Inject the PostHog public bootstrap snippet into index.html."
+                            : "Add the PostHog public bootstrap snippet to the managed analytics module.",
+                        provider: "posthog",
+                        snippet: framework === "static-html"
+                            ? wrapHtmlSnippet(buildBootstrapSnippet(projectKey, apiHostOrigin))
+                            : buildBootstrapSnippet(projectKey, apiHostOrigin)
+                    }
+                ]
+                : []
+        };
+    }
+};
+function frameworkInstructionPath(framework) {
+    switch (framework) {
+        case "static-html":
+            return "index.html";
+        case "vite-react":
+            return "src/lib/infinite-analytics.ts";
+        case "next-app-router":
+        case "next-pages-router":
+            return "lib/infinite-analytics.ts";
+    }
+}
+function buildBootstrapSnippet(projectKey, apiHost) {
+    return [
+        "!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split('.');2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement('script')).type='text/javascript',p.crossOrigin='anonymous',p.async=!0,p.src=s.api_host.replace('.i.posthog.com','-assets.i.posthog.com')+'/static/array.js',(r=t.getElementsByTagName('script')[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a='posthog',u.people=u.people||[],u.toString=function(t){var e='posthog';return'posthog'!==a&&(e+='.'+a),t||(e+=' (stub)'),e},u.people.toString=function(){return u.toString(1)+'.people'},o='init capture register register_once unregister reset opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing set_config people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove_group people.set person.set_once person.unset person.increment person.append person.union person.track_charge person.clear_charges person.delete_user group.set group.set_once group.unset group.remove group.union group.track group.identify group.set_property feature_flags.isFeatureEnabled feature_flags.getFeatureFlag feature_flags.getFeatureFlagPayload feature_flags.reloadFeatureFlags feature_flags.updateEarlyAccessFeatureEnrollment feature_flags.getEarlyAccessFeatures feature_flags.onFeatureFlags sessionRecording.startSessionRecording sessionRecording.stopSessionRecording sessionRecording.getSessionRecordingUrl'.split(' '),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);",
+        `posthog.init(${jsLiteral(projectKey)}, { api_host: ${jsLiteral(apiHost)}, persistence: 'localStorage+cookie' });`
+    ].join("\n");
+}
+function wrapHtmlSnippet(source) {
+    return ["<script>", source, "</script>"].join("\n");
+}

package/dist/src/providers/validate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Strict validation + script-safe embedding for the PUBLIC analytics artifacts that get
+ * written into a founder's source code.
+ *
+ * Once infinite-tag ships as a public CLI, these values arrive as user-supplied
+ * flags (`--ga4-measurement-id`, `--posthog-project-key`, `--posthog-api-host`, …) or via
+ * `--artifact-file`. A malformed or hostile value must be REJECTED as a plan blocker, never
+ * interpolated raw into the founder's JS/HTML. Validation is the primary defense; the
+ * embedding helpers are belt-and-suspenders so even a validation gap cannot break out of a
+ * string literal or `</script>` block.
+ */
+export declare function validateGa4MeasurementId(value: unknown): string | null;
+export declare function validatePosthogProjectKey(value: unknown): string | null;
+/** Validates the PostHog apiHost and returns its clean host (preserving path, no credentials/query/hash). */
+export declare function normalizePosthogApiHost(value: unknown): {
+    origin: string;
+} | {
+    error: string;
+};
+export declare function validateXPixelId(value: unknown): string | null;
+export declare function validateXEventTagIds(value: unknown): string | null;
+/**
+ * Serialize a value as a JS literal that is safe to inline inside a `<script>` block.
+ * JSON.stringify handles quotes/backslashes/newlines; we additionally escape `<` (stops a
+ * value from closing the script element via `</script>`) and the raw line terminators
+ * U+2028 / U+2029 (legal in HTML/JSON but illegal mid JS string literal). Code points are
+ * compared numerically so the source stays ASCII-only.
+ */
+export declare function jsLiteral(value: unknown): string;
+/** Safe value for a URL query parameter such as the GA4 loader's `?id=...`. */
+export declare function urlQueryValue(value: string): string;

package/dist/src/providers/validate.js

@@ -0,0 +1,110 @@
+/**
+ * Strict validation + script-safe embedding for the PUBLIC analytics artifacts that get
+ * written into a founder's source code.
+ *
+ * Once infinite-tag ships as a public CLI, these values arrive as user-supplied
+ * flags (`--ga4-measurement-id`, `--posthog-project-key`, `--posthog-api-host`, …) or via
+ * `--artifact-file`. A malformed or hostile value must be REJECTED as a plan blocker, never
+ * interpolated raw into the founder's JS/HTML. Validation is the primary defense; the
+ * embedding helpers are belt-and-suspenders so even a validation gap cannot break out of a
+ * string literal or `</script>` block.
+ */
+// GA4/gtag measurement-style IDs: G-XXXX (GA4), and the other prefixes the gtag loader
+// accepts (GT- google tag, AW- ads, UA- legacy, DC- floodlight). Alphanumerics + hyphens
+// only — no quotes, angle brackets, slashes or whitespace can pass. At least one
+// alphanumeric is required in the body so all-hyphen bodies like `G-----` are rejected.
+const MEASUREMENT_ID = /^(?:G|GT|AW|UA|DC)-(?=[A-Za-z0-9-]*[A-Za-z0-9])[A-Za-z0-9-]{4,}$/;
+// PostHog public project keys look like `phc_<base62>`. The `phc_` prefix + an
+// alphanumeric-only charset is the security guarantee; we don't gate on length.
+const POSTHOG_PROJECT_KEY = /^phc_[A-Za-z0-9]+$/;
+// X/Twitter pixel ids + event-tag ids: alphanumerics, hyphens and underscores
+// (real event tags look like `tw-<pixel>-<event>`). The charset is what keeps a value
+// from breaking out of a string literal or `</script>`.
+const X_ID = /^[A-Za-z0-9_-]{2,}$/;
+export function validateGa4MeasurementId(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return "GA4 requires a public measurementId before planning can continue.";
+    }
+    if (!MEASUREMENT_ID.test(value)) {
+        return `GA4 measurementId ${JSON.stringify(value)} is not a valid Measurement ID (expected e.g. G-XXXXXXXXXX).`;
+    }
+    return null;
+}
+export function validatePosthogProjectKey(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return "PostHog requires a public projectKey before planning can continue.";
+    }
+    if (!POSTHOG_PROJECT_KEY.test(value)) {
+        return `PostHog projectKey ${JSON.stringify(value)} is not a valid public project key (expected phc_...).`;
+    }
+    return null;
+}
+/** Validates the PostHog apiHost and returns its clean host (preserving path, no credentials/query/hash). */
+export function normalizePosthogApiHost(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return { error: "PostHog requires a public apiHost before planning can continue." };
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { error: `PostHog apiHost ${JSON.stringify(value)} is not a valid URL.` };
+    }
+    if (url.protocol !== "https:") {
+        return { error: `PostHog apiHost must be an https URL (got ${JSON.stringify(value)}).` };
+    }
+    if (url.username || url.password) {
+        return { error: "PostHog apiHost must not contain embedded credentials." };
+    }
+    // Preserve the pathname so reverse-proxy configs like https://app.example.com/ingest work
+    // correctly. Strip any trailing slash, query string, and fragment — those must never ride
+    // along into the snippet.
+    const pathname = url.pathname.replace(/\/$/, "");
+    return { origin: url.origin + pathname };
+}
+export function validateXPixelId(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return "X requires a public pixelId before planning can continue.";
+    }
+    if (!X_ID.test(value)) {
+        return `X pixelId ${JSON.stringify(value)} is not a valid pixel id.`;
+    }
+    return null;
+}
+export function validateXEventTagIds(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return "X requires at least one public eventTagId before planning can continue.";
+    }
+    for (const id of value) {
+        if (typeof id !== "string" || !X_ID.test(id)) {
+            return `X eventTagId ${JSON.stringify(id)} is not a valid event tag id.`;
+        }
+    }
+    return null;
+}
+/**
+ * Serialize a value as a JS literal that is safe to inline inside a `<script>` block.
+ * JSON.stringify handles quotes/backslashes/newlines; we additionally escape `<` (stops a
+ * value from closing the script element via `</script>`) and the raw line terminators
+ * U+2028 / U+2029 (legal in HTML/JSON but illegal mid JS string literal). Code points are
+ * compared numerically so the source stays ASCII-only.
+ */
+export function jsLiteral(value) {
+    const json = JSON.stringify(value) ?? "undefined";
+    let out = "";
+    for (const ch of json) {
+        const code = ch.charCodeAt(0);
+        if (ch === "<" || code === 0x2028 || code === 0x2029) {
+            out += "\\u" + code.toString(16).padStart(4, "0");
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+/** Safe value for a URL query parameter such as the GA4 loader's `?id=...`. */
+export function urlQueryValue(value) {
+    return encodeURIComponent(value);
+}

package/dist/src/providers/x.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderAdapter } from "../types.js";
+export declare const xProviderAdapter: ProviderAdapter;