@mazyos/lp-tracker 0.1.0

package/AGENTS.md

@@ -0,0 +1,71 @@
+# LP tracker maintenance rules
+
+Apply these rules to every change under `packages/lp-tracker`.
+
+## Protect the event boundary
+
+- Keep `BrowserEventName` closed. Permit only `PageView`, `ViewContent`, `Lead`,
+  `AddToCart`, `InitiateCheckout`, `CompleteRegistration`, and `Contact`.
+- Never add `Purchase`, `Subscribe`, `Refund`, or `Chargeback` to a browser
+  type, delegated hook, or collect route allowlist. Those events belong to
+  authenticated checkout/provider ingestion.
+- Never hash PII in browser code. Send raw normalized values only to the
+  same-origin collect route and let the core apply hashing.
+- Strip browser-supplied IP and user-agent values in the Next handler. Trust
+  only the documented proxy-header order.
+
+## Preserve consent and attribution
+
+- Keep `required` as the default consent mode.
+- Do not initialize pixels, POST events, or persist pre-consent events.
+- Keep pre-consent events in memory only. Clear memory when consent is denied.
+- Generate `_mzc` only with Web Crypto as exactly 22 base62 characters.
+- Prefer query attribution over cookies and rewrite first-party attribution
+  cookies without replacing a valid value with an empty value.
+- Preserve `event_id` and `event_time` across every retry.
+- Keep the retry key versioned, capped at 50 items, and limited to 72 hours.
+
+## Keep client interactions immediate
+
+- Return from `track()` synchronously with the event ID.
+- Never await network activity in delegated click or submit listeners.
+- Rewrite an existing checkout anchor's `href`; never call `preventDefault()`
+  and never call `window.open()`.
+- Use one Meta event ID for both pixel and collect delivery.
+- Do not add an implicit Meta `PageView`; the normal event pipeline owns it.
+
+## Keep server credentials server-only
+
+- Read `MAZYOS_SITE_SECRET` only in `./next`, `./server`, or CLI code.
+- Never expose secrets in response bodies, cache keys, errors, logs, or public
+  health output.
+- Keep production public health output limited to `ok` and `version`.
+- Bound request bodies and network timeouts.
+- Retry only one network or upstream 5xx failure.
+- Do not add mutable request-scoped module state.
+- Keep Next.js `config`, `runtime`, and `dynamic` literals in consumer
+  file-convention modules; Next.js cannot statically analyze reexported values.
+
+## Treat checkout mappings as evidence-based
+
+- Keep unknown checkout URLs on the verified `generic` profile.
+- Mark a provider profile `verified` only with a checked-in real echo fixture
+  proving its accepted parameter names.
+- Keep provisional profiles conservative: `mzc`, UTM, and no invented
+  provider-specific attribution parameters.
+- Preserve existing query parameters and never overwrite them.
+
+## Validate every change
+
+Run:
+
+```bash
+pnpm --filter @mazyos/lp-tracker run lint
+pnpm --filter @mazyos/lp-tracker run typecheck
+pnpm --filter @mazyos/lp-tracker run test:run
+pnpm --filter @mazyos/lp-tracker run build
+```
+
+Retain tests for consent, event-ID parity, retries, middleware cookies, handler
+filtering, checkout length bounds, doctor checks, and compile-time rejection of
+server-only events.

package/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2026 MazyOS
+
+Permission is hereby granted to use, copy, and modify this software solely
+to instrument landing pages that send conversion events to a MazyOS
+workspace.
+
+Redistribution of this software as a competing tracking SDK, and use of
+this software independently of MazyOS, are not granted.
+
+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,208 @@
+# @mazyos/lp-tracker
+
+First-party, full-funnel conversion tracking for React 19 and Next.js 16
+landing pages. The package keeps browser events deliberately narrower than the
+server conversion contract: a landing page cannot type-check a `Purchase`,
+`Subscribe`, `Refund`, or `Chargeback`.
+
+## Install
+
+```bash
+pnpm add @mazyos/lp-tracker
+```
+
+Use Node.js 22 or newer. Configure server credentials only on the Next.js
+server:
+
+```dotenv
+MAZYOS_CORE_URL=https://api.example.com
+MAZYOS_SITE_SECRET=
+MAZYOS_DIAGNOSTICS_TOKEN=
+```
+
+Never prefix `MAZYOS_SITE_SECRET` with `NEXT_PUBLIC_`.
+
+## Next.js wiring
+
+Reexport attribution middleware:
+
+```ts
+// middleware.ts
+export { middleware } from "@mazyos/lp-tracker/middleware";
+
+// Next.js requires this configuration to be a local literal.
+export const config = {
+  matcher: [
+    "/((?!api(?:/|$)|_next(?:/|$)|static(?:/|$)|\\.well-known(?:/|$)|.*\\.[^/]+$).*)",
+  ],
+};
+```
+
+Reexport the first-party collection route:
+
+```ts
+// app/api/mazyos/collect/route.ts
+export { GET, POST } from "@mazyos/lp-tracker/next";
+
+// Next.js requires route configuration to be locally analyzable.
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+```
+
+The package also exports ready `config`, `runtime`, and `dynamic` values for
+inspection and non-route composition. Do not reexport those constants from a
+Next.js file convention: Next.js 16 rejects non-local route configuration.
+
+Mount one provider in the root layout:
+
+```tsx
+import { MazyosProvider } from "@mazyos/lp-tracker";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="pt-BR">
+      <body>
+        <MazyosProvider consentMode="implied" pageviewPolicy="ledger">
+          {children}
+        </MazyosProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+The MazyOS operational profile is explicit `implied` collection with PageViews
+in the ledger, so tracking starts on the first load without a banner callback.
+The package keeps `required` only as a backwards-compatible library fallback.
+Configure Meta limited data use when required:
+
+```tsx
+<MazyosProvider
+  dataProcessingOptions={{ options: ["LDU"], country: 1, state: 1000 }}
+/>
+```
+
+## Events and markup
+
+Only these browser events are exported:
+
+- `PageView`
+- `ViewContent`
+- `Lead`
+- `AddToCart`
+- `InitiateCheckout`
+- `CompleteRegistration`
+- `Contact`
+
+Use delegated markup for ordinary interactions:
+
+```tsx
+<form data-mazyos-lead>
+  <input name="email" type="email" />
+  <button type="submit">Quero participar</button>
+</form>
+
+<section data-mazyos-view="Offer name" />
+
+<a
+  data-mazyos-checkout
+  data-mazyos-gateway="hotmart"
+  href="https://pay.hotmart.com/example?offer=primary"
+>
+  Comprar
+</a>
+```
+
+The provider emits `ViewContent` when 35% of the marked element is visible or
+after eight seconds. It emits `PageView` when the SPA pathname changes. Checkout
+links are rewritten in place before the browser follows them; the tracker never
+calls `preventDefault()` or opens another window.
+
+The provider also records first-party `page_start`, heartbeat, visibility,
+route-change and `page_exit` pulses with engagement time, interaction count and
+maximum scroll depth. Pulses are stored in the MazyOS ledger and are never sent
+to ad destinations as conversion events.
+
+Use the API after a real application outcome:
+
+```ts
+import { identify, track } from "@mazyos/lp-tracker";
+
+track("Lead", {
+  contentName: "Lead magnet",
+  userData: { email: "person@example.com" },
+});
+
+identify({ email: "person@example.com" });
+```
+
+`identify()` emits `CompleteRegistration` only when it receives PII not already
+known by the current tracker runtime. PII is sent unhashed to the same-origin
+collect route; hashing is a server responsibility.
+
+## Checkout profiles
+
+`@mazyos/lp-tracker/checkout` exports the profile registry,
+`defineCheckoutProfile`, `resolveCheckoutProfile`, and `resolveCheckoutUrl`.
+Resolution order is explicit `data-mazyos-gateway`, environment default,
+checkout hostname, then `generic`.
+
+The `generic` profile is verified for conservative `mzc` and standard UTM
+propagation. Built-in host recognition for Kirvano, Hotmart, Kiwify, Eduzz,
+PerfectPay, Ticto, Braip, Monetizze, Cakto, and Stripe is explicitly
+`provisional`; those profiles do not claim undocumented provider-specific
+parameter mapping.
+
+Cakto (`pay.cakto.com.br`) drops query parameters it does not know, so its
+profile carries the `mzc` token in `sck` — the free-form tracking slot Cakto
+documents and echoes back on the order. Standard UTM parameters pass through
+unchanged.
+
+## Server configuration
+
+Read validated runtime configuration with a bounded 60-second in-memory cache:
+
+```ts
+import { getMazyosSite } from "@mazyos/lp-tracker/server";
+
+const site = await getMazyosSite();
+```
+
+The cache key contains a SHA-256 lookup digest, never the raw site secret.
+
+## Doctor
+
+Run all static checks and any remote checks enabled by environment variables:
+
+```bash
+npx @mazyos/lp-tracker doctor
+npx @mazyos/lp-tracker doctor --json
+```
+
+Set `MAZYOS_COLLECT_URL` or `MAZYOS_LP_URL` to check a deployed route. The
+command exits nonzero on any failed check.
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---|---|
+| Doctor fails on `config` / `runtime` / `dynamic` | Those values must be **local literals** in the Next 16 file. Do not reexport them from the package. |
+| `401` on forward | `MAZYOS_SITE_SECRET` is missing, expired after rotation, or leaked into `NEXT_PUBLIC_*`. |
+| Card stays “no traffic” | The browser must hit same-origin `/api/mazyos/collect`, not the core URL. Confirm `202` in Network. |
+| Lead does not become a person | The form needs email or phone. `mzc` never creates `customer_id`. |
+| Checkout has no attribution | Mark the CTA with `data-mazyos-checkout`. Do not strip click IDs in the root layout. |
+| Safari drops the cookie | HTML snippet cookies may be shortened by ITP. Use Next middleware for the configured 400-day first-party horizon. |
+| Apex cookie missing | Set `NEXT_PUBLIC_MAZYOS_COOKIE_DOMAIN`. |
+| Pixel and CAPI disagree | Same `event_id`. Do not add a second Meta snippet or a second `PageView`. |
+
+Operator-facing Portuguese docs live in the backoffice:
+`docs/integrations/landing-pages.md`. This README stays the maintainer contract.
+
+## Delivery behavior
+
+Failed requests use `mazyos:queue:v1`, capped at 50 entries with a 72-hour TTL.
+Choose `local`, `session`, or `off` storage. IDs and event timestamps survive
+retries. Cumulative offline heartbeats are coalesced, and telemetry is evicted
+before conversion events if the queue reaches its cap. On hidden-page flush,
+same-origin events use `sendBeacon` with `text/plain`, followed by a keepalive
+fetch fallback.

package/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: mazyos-lp-tracker
+description: Install and validate @mazyos/lp-tracker in React 19 and Next.js 16 landing pages.
+---
+
+# Instrument a MazyOS landing page
+
+Use this skill when adding first-party MazyOS conversion tracking to a landing
+page.
+
+## Install the package
+
+1. Add `@mazyos/lp-tracker` with the repository package manager.
+2. Reexport `middleware` from `@mazyos/lp-tracker/middleware` in the project's
+   root `middleware.ts`, and copy the documented matcher into a local `config`
+   literal. Next.js rejects reexported file-convention configuration.
+3. Reexport `POST` and `GET` from `@mazyos/lp-tracker/next` in
+   `app/api/mazyos/collect/route.ts`. Declare local literal
+   `runtime = "nodejs"` and `dynamic = "force-dynamic"` exports so Next.js can
+   statically analyze them.
+4. Render one `MazyosProvider` around root-layout children.
+5. Put `MAZYOS_CORE_URL` and `MAZYOS_SITE_SECRET` in server-only environment
+   configuration and document them in `.env.example`.
+6. Never use a `NEXT_PUBLIC_*` name for a value beginning with `sk_lp_`.
+
+## Mark interactions
+
+- Add `data-mazyos-lead` to native lead forms. Ensure each form has an email or
+  phone field.
+- Add `data-mazyos-view` to the primary offer content.
+- Add `data-mazyos-checkout` to every checkout anchor or button.
+- Add `data-mazyos-cart`, `data-mazyos-contact`, or
+  `data-mazyos-register` only at the corresponding confirmed interaction.
+- Add `data-mazyos-gateway="slug"` only when explicit profile selection is
+  needed.
+- Call `track("Lead")` only after actual success when no native form submit
+  exists.
+- Call `identify()` when new PII becomes known outside a funnel event.
+
+## Enforce the browser boundary
+
+Use only `PageView`, `ViewContent`, `Lead`, `AddToCart`,
+`InitiateCheckout`, `CompleteRegistration`, and `Contact`. Do not bypass the
+types to send `Purchase`, `Subscribe`, `Refund`, or `Chargeback`.
+
+Do not:
+
+- hash PII in the client;
+- add a second Meta snippet or manual `fbq` PageView;
+- add a browser `gtag` conversion;
+- clear attribution query parameters in the root layout;
+- interrupt checkout navigation with `preventDefault()` or `window.open()`;
+- invent checkout-provider parameter names.
+
+## Use the MazyOS operational profile
+
+Mount the provider with `consentMode="implied"` and
+`pageviewPolicy="ledger"`. Do not gate tracker startup behind a banner or a
+later callback. The package's `required` mode exists only for older external
+integrations.
+
+## Validate
+
+Run:
+
+```bash
+npx @mazyos/lp-tracker doctor
+```
+
+Use `--json` in automation. Configure `MAZYOS_COLLECT_URL` or `MAZYOS_LP_URL`
+for deployed health checks. Treat a nonzero exit as a release blocker.

package/dist/attribution.d.ts

@@ -0,0 +1,16 @@
+export declare const CLICK_ID_FIELDS: readonly ["fbclid", "gclid", "gbraid", "wbraid", "ttclid"];
+export declare const UTM_FIELDS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"];
+export declare const ATTRIBUTION_FIELDS: readonly ["fbclid", "gclid", "gbraid", "wbraid", "ttclid", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "fbp", "fbc", "ttp"];
+export type ClickIdField = (typeof CLICK_ID_FIELDS)[number];
+export type UtmField = (typeof UTM_FIELDS)[number];
+export type AttributionField = (typeof ATTRIBUTION_FIELDS)[number];
+export declare const ATTRIBUTION_COOKIE_MAX_AGE: number;
+export declare function firstNonEmpty(...values: ReadonlyArray<string | null | undefined>): string | undefined;
+export declare function normalizeAttributionValue(value: string | null | undefined): string | undefined;
+export declare function mazyosCookieName(field: string): string;
+export declare function isUtmField(value: string): boolean;
+export declare function queryMap(searchParams: URLSearchParams): Record<string, string[]>;
+export declare function createFbc(clickId: string, arrivalMs: number): string;
+export declare function googleCookieClickId(value: string | null | undefined): string | undefined;
+export declare function isMzc(value: string | null | undefined): value is string;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,YAC1B,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,QAAQ,CACA,CAAC;AAEX,eAAO,MAAM,UAAU,YACrB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,CACF,CAAC;AAEX,eAAO,MAAM,kBAAkB,wJAMrB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,eAAO,MAAM,0BAA0B,QAAqB,CAAC;AAE7D,wBAAgB,aAAa,CAC3B,GAAG,MAAM,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAClD,MAAM,GAAG,SAAS,CAQpB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,wBAAgB,QAAQ,CAAC,YAAY,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAgBhF;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CASpB;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,MAAM,CAEvE"}

package/dist/attribution.js

@@ -0,0 +1,77 @@
+export const CLICK_ID_FIELDS = [
+    "fbclid",
+    "gclid",
+    "gbraid",
+    "wbraid",
+    "ttclid",
+];
+export const UTM_FIELDS = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_content",
+    "utm_term",
+];
+export const ATTRIBUTION_FIELDS = [
+    ...CLICK_ID_FIELDS,
+    ...UTM_FIELDS,
+    "fbp",
+    "fbc",
+    "ttp",
+];
+export const ATTRIBUTION_COOKIE_MAX_AGE = 60 * 60 * 24 * 400;
+export function firstNonEmpty(...values) {
+    for (const value of values) {
+        const normalized = normalizeAttributionValue(value);
+        if (normalized) {
+            return normalized;
+        }
+    }
+    return undefined;
+}
+export function normalizeAttributionValue(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.slice(0, 512) : undefined;
+}
+export function mazyosCookieName(field) {
+    return `_mzy_${field}`;
+}
+export function isUtmField(value) {
+    return /^utm_[a-z0-9_]{1,60}$/.test(value);
+}
+export function queryMap(searchParams) {
+    const output = {};
+    let count = 0;
+    for (const [rawKey, rawValue] of searchParams) {
+        if (count >= 100)
+            break;
+        const key = rawKey.trim().slice(0, 128);
+        const value = normalizeAttributionValue(rawValue);
+        if (!key || !value)
+            continue;
+        const values = output[key] ?? [];
+        if (values.length < 20) {
+            values.push(value);
+            output[key] = values;
+        }
+        count += 1;
+    }
+    return output;
+}
+export function createFbc(clickId, arrivalMs) {
+    return `fb.1.${Math.trunc(arrivalMs)}.${clickId}`;
+}
+export function googleCookieClickId(value) {
+    const normalized = normalizeAttributionValue(value);
+    if (!normalized) {
+        return undefined;
+    }
+    const segments = normalized.split(".");
+    return segments.length >= 3
+        ? normalizeAttributionValue(segments.slice(2).join("."))
+        : normalized;
+}
+export function isMzc(value) {
+    return typeof value === "string" && /^[A-Za-z0-9]{22}$/.test(value);
+}
+//# sourceMappingURL=attribution.js.map

package/dist/attribution.js.map

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

package/dist/checkout/profiles.d.ts

@@ -0,0 +1,18 @@
+import type { AttributionData } from "../types.js";
+export type CheckoutProfileStatus = "provisional" | "verified";
+export type CheckoutAttributionKey = Exclude<keyof AttributionData, "mzc" | `utm_${string}`>;
+export interface CheckoutProfile {
+    attributionParams: Readonly<Partial<Record<CheckoutAttributionKey, string>>>;
+    hostnames: readonly string[];
+    maxUrlLength: number;
+    slug: string;
+    status: CheckoutProfileStatus;
+    tokenParam: string;
+}
+export declare function defineCheckoutProfile(profile: CheckoutProfile): CheckoutProfile;
+export declare const BUILTIN_CHECKOUT_PROFILES: readonly CheckoutProfile[];
+export declare function registerCheckoutProfile(profile: CheckoutProfile): () => void;
+export declare function getCheckoutProfile(slug: string): CheckoutProfile | undefined;
+export declare function listCheckoutProfiles(): readonly CheckoutProfile[];
+export declare function genericCheckoutProfile(): CheckoutProfile;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/checkout/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/checkout/profiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,UAAU,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAC1C,MAAM,eAAe,EACrB,KAAK,GAAG,OAAO,MAAM,EAAE,CACxB,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,iBAAiB,EAAE,QAAQ,CACzB,OAAO,CAAC,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC,CAChD,CAAC;IACF,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,qBAAqB,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,GACvB,eAAe,CAsBjB;AAmCD,eAAO,MAAM,yBAAyB,EAAE,SAAS,eAAe,EAuB5D,CAAC;AAOL,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,eAAe,GACvB,MAAM,IAAI,CAWZ;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE5E;AAED,wBAAgB,oBAAoB,IAAI,SAAS,eAAe,EAAE,CAEjE;AAED,wBAAgB,sBAAsB,IAAI,eAAe,CAExD"}

package/dist/checkout/profiles.js

@@ -0,0 +1,89 @@
+export function defineCheckoutProfile(profile) {
+    if (!/^[a-z0-9_-]{2,32}$/.test(profile.slug)) {
+        throw new TypeError("Checkout profile slug must be 2-32 lowercase characters");
+    }
+    if (!isParameterName(profile.tokenParam)) {
+        throw new TypeError("Checkout token parameter is invalid");
+    }
+    if (profile.maxUrlLength < 256 || profile.maxUrlLength > 16_384) {
+        throw new TypeError("Checkout maxUrlLength must be between 256 and 16384");
+    }
+    for (const parameter of Object.values(profile.attributionParams)) {
+        if (parameter && !isParameterName(parameter)) {
+            throw new TypeError(`Invalid checkout attribution parameter: ${parameter}`);
+        }
+    }
+    return Object.freeze({
+        ...profile,
+        attributionParams: Object.freeze({ ...profile.attributionParams }),
+        hostnames: Object.freeze(profile.hostnames.map((host) => host.trim().toLowerCase())),
+    });
+}
+const genericProfile = defineCheckoutProfile({
+    attributionParams: {},
+    hostnames: [],
+    maxUrlLength: 2_048,
+    slug: "generic",
+    status: "verified",
+    tokenParam: "mzc",
+});
+function provisional(slug, hostnames, options = {}) {
+    return defineCheckoutProfile({
+        attributionParams: {},
+        hostnames,
+        maxUrlLength: 2_048,
+        slug,
+        status: "provisional",
+        tokenParam: options.tokenParam ?? "mzc",
+    });
+}
+export const BUILTIN_CHECKOUT_PROFILES = Object.freeze([
+    genericProfile,
+    provisional("kirvano", ["checkout.kirvano.com", "pay.kirvano.com"]),
+    provisional("hotmart", ["pay.hotmart.com"]),
+    provisional("kiwify", ["pay.kiwify.com.br"]),
+    provisional("eduzz", ["checkout.eduzz.com", "sun.eduzz.com"]),
+    provisional("perfectpay", [
+        "checkout.perfectpay.com.br",
+        "perfectpay.com.br",
+    ]),
+    provisional("ticto", ["checkout.ticto.app", "pay.ticto.com.br"]),
+    provisional("braip", ["pay.braip.com"]),
+    provisional("monetizze", [
+        "app.monetizze.com.br",
+        "pay.monetizze.com.br",
+    ]),
+    // Cakto discards unknown query parameters; `sck` is its documented
+    // free-form tracking slot and is echoed back on the order.
+    provisional("cakto", ["pay.cakto.com.br", "checkout.cakto.com.br"], {
+        tokenParam: "sck",
+    }),
+    provisional("stripe", ["checkout.stripe.com"]),
+]);
+const customProfiles = new Map();
+const builtinsBySlug = new Map(BUILTIN_CHECKOUT_PROFILES.map((profile) => [profile.slug, profile]));
+export function registerCheckoutProfile(profile) {
+    const defined = defineCheckoutProfile(profile);
+    if (builtinsBySlug.has(defined.slug)) {
+        throw new TypeError(`Cannot replace built-in checkout profile: ${defined.slug}`);
+    }
+    customProfiles.set(defined.slug, defined);
+    return () => {
+        if (customProfiles.get(defined.slug) === defined) {
+            customProfiles.delete(defined.slug);
+        }
+    };
+}
+export function getCheckoutProfile(slug) {
+    return customProfiles.get(slug) ?? builtinsBySlug.get(slug);
+}
+export function listCheckoutProfiles() {
+    return [...BUILTIN_CHECKOUT_PROFILES, ...customProfiles.values()];
+}
+export function genericCheckoutProfile() {
+    return genericProfile;
+}
+function isParameterName(value) {
+    return /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(value);
+}
+//# sourceMappingURL=profiles.js.map

package/dist/checkout/profiles.js.map

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

package/dist/checkout/resolve.d.ts

@@ -0,0 +1,16 @@
+import type { AttributionData } from "../types.js";
+import { type CheckoutProfile } from "./profiles.js";
+export interface ResolveCheckoutProfileOptions {
+    defaultSlug?: string | undefined;
+    explicitSlug?: string | undefined;
+    url: URL | string;
+}
+export interface ResolveCheckoutUrlOptions {
+    attribution: Partial<AttributionData>;
+    defaultProfile?: string | undefined;
+    explicitProfile?: string | undefined;
+    maxLength?: number | undefined;
+}
+export declare function resolveCheckoutProfile(options: ResolveCheckoutProfileOptions): CheckoutProfile;
+export declare function resolveCheckoutUrl(input: URL | string, options: ResolveCheckoutUrlOptions): string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/checkout/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/checkout/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAqBvB,MAAM,WAAW,6BAA6B;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACtC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,eAAe,CA2BjB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,GAAG,GAAG,MAAM,EACnB,OAAO,EAAE,yBAAyB,GACjC,MAAM,CAgCR"}