@decocms/apps-vtex 8.1.0-next.1 → 8.1.0-next.3

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@decocms/apps-vtex`: a thin, instrumented VTEX client (`createVtexClient`).
+ * See ./vtexClient.ts and /next/upstream-clients.
+ */
+export { createVtexClient, type VtexCatalogSearchArgs, type VtexClient, type VtexClientConfig, VtexError, type VtexRequestOptions, type VtexResponse, type VtexSearchArgs, } from "./vtexClient.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@decocms/apps-vtex`: a thin, instrumented VTEX client (`createVtexClient`).
+ * See ./vtexClient.ts and /next/upstream-clients.
+ */
+export { createVtexClient, VtexError, } from "./vtexClient.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,gBAAgB,EAIhB,SAAS,GAIV,MAAM,iBAAiB,CAAC"}

package/dist/utils/constants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tuning knobs for VTEX request resilience (timeouts, retries, circuit
+ * breaker), with the reasoning for each number next to it.
+ */
+export interface ResilienceConfig {
+    /** Per-attempt timeout in ms. Aborts the socket. */
+    perAttemptTimeoutMs: number;
+    /** Total time budget across all attempts (incl. backoff) in ms. */
+    totalTimeoutMs: number;
+    /** Max retries for idempotent requests (attempts = maxRetries + 1). */
+    maxRetries: number;
+    /** Exponential backoff base in ms. */
+    backoffBaseMs: number;
+    /** Exponential backoff cap in ms. */
+    backoffCapMs: number;
+    /** Consecutive failures before the breaker opens. */
+    breakerConsecutiveFailures: number;
+    /** How long the breaker stays open before half-opening, in ms. */
+    breakerOpenCooldownMs: number;
+    /** Number of probe requests allowed while half-open. */
+    breakerHalfOpenProbes: number;
+    /** Max retry tokens per host (token bucket). */
+    retryBudgetMax: number;
+    /** Token refill rate per second. */
+    retryBudgetRefillPerSec: number;
+}
+export declare const DEFAULT_RESILIENCE_CONFIG: ResilienceConfig;
+//# sourceMappingURL=constants.d.ts.map

package/dist/utils/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,0BAA0B,EAAE,MAAM,CAAC;IACnC,kEAAkE;IAClE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAWvC,CAAC"}

package/dist/utils/constants.js

@@ -0,0 +1,17 @@
+/**
+ * Tuning knobs for VTEX request resilience (timeouts, retries, circuit
+ * breaker), with the reasoning for each number next to it.
+ */
+export const DEFAULT_RESILIENCE_CONFIG = {
+    perAttemptTimeoutMs: 8_000,
+    totalTimeoutMs: 12_000,
+    maxRetries: 2,
+    backoffBaseMs: 150,
+    backoffCapMs: 1_000,
+    breakerConsecutiveFailures: 5,
+    breakerOpenCooldownMs: 5_000,
+    breakerHalfOpenProbes: 3,
+    retryBudgetMax: 20,
+    retryBudgetRefillPerSec: 5,
+};
+//# sourceMappingURL=constants.js.map

package/dist/utils/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6BH,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,mBAAmB,EAAE,KAAK;IAC1B,cAAc,EAAE,MAAM;IACtB,UAAU,EAAE,CAAC;IACb,aAAa,EAAE,GAAG;IAClB,YAAY,EAAE,KAAK;IACnB,0BAA0B,EAAE,CAAC;IAC7B,qBAAqB,EAAE,KAAK;IAC5B,qBAAqB,EAAE,CAAC;IACxB,cAAc,EAAE,EAAE;IAClB,uBAAuB,EAAE,CAAC;CAC3B,CAAC"}

package/dist/utils/cookieSanitizer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Outbound cookie sanitization for VTEX API calls.
+ *
+ * VTEX's janus gateway strictly enforces RFC 6265: any cookie value containing
+ * non-ASCII bytes causes the gateway to return `503 Service Unavailable` with
+ * an empty body, before the request reaches the backing service. This is
+ * deterministic — a single poisoned cookie (e.g. an analytics tag writing a
+ * category name with accents into `document.cookie` without encoding) can
+ * break every checkout call for a user.
+ *
+ * This module provides two filters:
+ *
+ * - `sanitizeOutboundCookieHeader()` — drops cookies whose value contains
+ *   non-ASCII bytes or that look malformed. Default for cookie forwarding
+ *   in `vtexFetchWithCookies`. Safe to apply to any cookie payload.
+ *
+ * - `extractVtexCookies()` — allowlist mode. Drops anything that isn't on
+ *   `VTEX_COOKIE_PREFIXES`. Use when calling endpoints that have no business
+ *   seeing the user's full cookie soup (e.g. logout, masterdata, profile).
+ *
+ * The allowlist is the canonical list of cookie name prefixes that VTEX APIs
+ * actually consume. It lives here so it's the single source of truth for the
+ * package — both `getVtexCookies()` (cookies.ts) and
+ * `extractVtexCookiesFromHeader()` (authHelpers.ts) delegate to this module.
+ */
+/**
+ * Cookie name prefixes that are VTEX-relevant and safe to forward to
+ * `*.vtexcommercestable.com.br` / `*.myvtex.com` / `secure.<storefront>` APIs.
+ */
+export declare const VTEX_COOKIE_PREFIXES: readonly string[];
+export type DropReason = "non_ascii" | "not_in_allowlist" | "malformed";
+export interface DroppedCookie {
+    name: string;
+    reason: DropReason;
+}
+export interface CookieSanitizeResult {
+    /** Cookie header string ready to forward (may be empty). */
+    cookies: string;
+    /** Cookies that were filtered out, with the reason per cookie. */
+    dropped: DroppedCookie[];
+}
+export interface CookieSanitizeOptions {
+    /**
+     * When true, additionally enforces an allowlist: only cookies whose name
+     * starts with one of `VTEX_COOKIE_PREFIXES` are kept.
+     * @default false
+     */
+    allowlist?: boolean;
+}
+/**
+ * Filter a `Cookie:` request header so it's safe to forward to a VTEX origin.
+ *
+ * Drops:
+ *   - pairs without `=` (malformed)
+ *   - pairs whose name isn't a valid HTTP token (malformed)
+ *   - pairs whose value contains non-ASCII bytes (`non_ascii`)
+ *   - when `opts.allowlist` is true: pairs not on `VTEX_COOKIE_PREFIXES`
+ *     (`not_in_allowlist`)
+ *
+ * Returns the cleaned header plus a per-cookie drop report so callers can
+ * log/observe which cookies were removed.
+ *
+ * @example
+ * ```ts
+ * const { cookies, dropped } = sanitizeOutboundCookieHeader(
+ *   request.headers.get("cookie") ?? "",
+ * );
+ * if (dropped.length) console.warn("[vtex] dropped cookies", dropped);
+ * fetch(vtexUrl, { headers: { cookie: cookies } });
+ * ```
+ */
+export declare function sanitizeOutboundCookieHeader(raw: string, opts?: CookieSanitizeOptions): CookieSanitizeResult;
+/**
+ * Allowlist convenience wrapper — keep only VTEX-prefixed, ASCII-clean cookies.
+ *
+ * Equivalent to `sanitizeOutboundCookieHeader(raw, { allowlist: true }).cookies`.
+ */
+export declare function extractVtexCookies(raw: string): string;
+/**
+ * Emit a structured `console.warn` for each dropped cookie, deduped by
+ * `name+reason` for the lifetime of the worker isolate. Call sites pass an
+ * arbitrary `host` label so we can correlate in logs.
+ */
+export declare function warnDroppedCookies(dropped: DroppedCookie[], host: string): void;
+/** Reset the dedup set — exposed for tests. */
+export declare function _resetCookieWarnDedupForTests(): void;
+//# sourceMappingURL=cookieSanitizer.d.ts.map

package/dist/utils/cookieSanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookieSanitizer.d.ts","sourceRoot":"","sources":["../../src/utils/cookieSanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAQjD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,kBAAkB,GAAG,WAAW,CAAC;AAExE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAWD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,qBAA0B,GAC/B,oBAAoB,CAuCtB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AASD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQ/E;AAED,+CAA+C;AAC/C,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/utils/cookieSanitizer.js

@@ -0,0 +1,136 @@
+/**
+ * Outbound cookie sanitization for VTEX API calls.
+ *
+ * VTEX's janus gateway strictly enforces RFC 6265: any cookie value containing
+ * non-ASCII bytes causes the gateway to return `503 Service Unavailable` with
+ * an empty body, before the request reaches the backing service. This is
+ * deterministic — a single poisoned cookie (e.g. an analytics tag writing a
+ * category name with accents into `document.cookie` without encoding) can
+ * break every checkout call for a user.
+ *
+ * This module provides two filters:
+ *
+ * - `sanitizeOutboundCookieHeader()` — drops cookies whose value contains
+ *   non-ASCII bytes or that look malformed. Default for cookie forwarding
+ *   in `vtexFetchWithCookies`. Safe to apply to any cookie payload.
+ *
+ * - `extractVtexCookies()` — allowlist mode. Drops anything that isn't on
+ *   `VTEX_COOKIE_PREFIXES`. Use when calling endpoints that have no business
+ *   seeing the user's full cookie soup (e.g. logout, masterdata, profile).
+ *
+ * The allowlist is the canonical list of cookie name prefixes that VTEX APIs
+ * actually consume. It lives here so it's the single source of truth for the
+ * package — both `getVtexCookies()` (cookies.ts) and
+ * `extractVtexCookiesFromHeader()` (authHelpers.ts) delegate to this module.
+ */
+/**
+ * Cookie name prefixes that are VTEX-relevant and safe to forward to
+ * `*.vtexcommercestable.com.br` / `*.myvtex.com` / `secure.<storefront>` APIs.
+ */
+export const VTEX_COOKIE_PREFIXES = [
+    "VtexIdclientAutCookie",
+    "checkout.vtex.com",
+    "CheckoutOrderFormOwnership",
+    "vtex_session",
+    "vtex_segment",
+    "vtex_is_",
+    "janus_sid",
+];
+/**
+ * Cookie pairs are `name=value`, where `name` (token) must be visible ASCII
+ * with no separators, and `value` must be ASCII (`0x20–0x7E`) per RFC 6265.
+ * We intentionally allow `=` inside the value (some VTEX cookies are
+ * URL-encoded JWTs).
+ */
+const TOKEN_RE = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
+const ASCII_VALUE_RE = /^[\x20-\x7E]*$/;
+/**
+ * Filter a `Cookie:` request header so it's safe to forward to a VTEX origin.
+ *
+ * Drops:
+ *   - pairs without `=` (malformed)
+ *   - pairs whose name isn't a valid HTTP token (malformed)
+ *   - pairs whose value contains non-ASCII bytes (`non_ascii`)
+ *   - when `opts.allowlist` is true: pairs not on `VTEX_COOKIE_PREFIXES`
+ *     (`not_in_allowlist`)
+ *
+ * Returns the cleaned header plus a per-cookie drop report so callers can
+ * log/observe which cookies were removed.
+ *
+ * @example
+ * ```ts
+ * const { cookies, dropped } = sanitizeOutboundCookieHeader(
+ *   request.headers.get("cookie") ?? "",
+ * );
+ * if (dropped.length) console.warn("[vtex] dropped cookies", dropped);
+ * fetch(vtexUrl, { headers: { cookie: cookies } });
+ * ```
+ */
+export function sanitizeOutboundCookieHeader(raw, opts = {}) {
+    if (!raw)
+        return { cookies: "", dropped: [] };
+    const kept = [];
+    const dropped = [];
+    const allowlist = opts.allowlist === true;
+    for (const segment of raw.split(";")) {
+        const pair = segment.trim();
+        if (!pair)
+            continue;
+        const eq = pair.indexOf("=");
+        if (eq <= 0) {
+            dropped.push({ name: pair.slice(0, 32), reason: "malformed" });
+            continue;
+        }
+        const name = pair.slice(0, eq);
+        const value = pair.slice(eq + 1);
+        if (!TOKEN_RE.test(name)) {
+            dropped.push({ name, reason: "malformed" });
+            continue;
+        }
+        if (!ASCII_VALUE_RE.test(value)) {
+            dropped.push({ name, reason: "non_ascii" });
+            continue;
+        }
+        if (allowlist && !VTEX_COOKIE_PREFIXES.some((p) => name.startsWith(p))) {
+            dropped.push({ name, reason: "not_in_allowlist" });
+            continue;
+        }
+        kept.push(`${name}=${value}`);
+    }
+    return { cookies: kept.join("; "), dropped };
+}
+/**
+ * Allowlist convenience wrapper — keep only VTEX-prefixed, ASCII-clean cookies.
+ *
+ * Equivalent to `sanitizeOutboundCookieHeader(raw, { allowlist: true }).cookies`.
+ */
+export function extractVtexCookies(raw) {
+    return sanitizeOutboundCookieHeader(raw, { allowlist: true }).cookies;
+}
+/**
+ * Track which cookie names we've already warned about to avoid spamming
+ * the worker logs. Process-scoped — Cloudflare Workers reset this on each
+ * isolate restart, which is exactly the cadence we want.
+ */
+const _warned = new Set();
+/**
+ * Emit a structured `console.warn` for each dropped cookie, deduped by
+ * `name+reason` for the lifetime of the worker isolate. Call sites pass an
+ * arbitrary `host` label so we can correlate in logs.
+ */
+export function warnDroppedCookies(dropped, host) {
+    if (dropped.length === 0)
+        return;
+    for (const d of dropped) {
+        const key = `${host}::${d.name}::${d.reason}`;
+        if (_warned.has(key))
+            continue;
+        _warned.add(key);
+        console.warn(`[vtex.cookie.dropped] host=${host} name=${d.name} reason=${d.reason}`);
+    }
+}
+/** Reset the dedup set — exposed for tests. */
+export function _resetCookieWarnDedupForTests() {
+    _warned.clear();
+}
+//# sourceMappingURL=cookieSanitizer.js.map

package/dist/utils/cookieSanitizer.js.map

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

package/dist/utils/operationRouter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * URL-derived operation name router for VTEX API calls.
+ *
+ * Plugged into `createInstrumentedFetch` (`@decocms/blocks/fetch`) via the
+ * `resolveOperation(url, method)` option. The resolved string becomes the
+ * span suffix (`vtex.<operation>`) and the `fetch.operation` span +
+ * histogram label, so it must be:
+ *
+ *   - low-cardinality (no IDs, slugs, search terms, account names);
+ *   - stable across deploys (used for alerting + dashboards);
+ *   - human-debuggable in a trace view.
+ *
+ * The router is intentionally a flat ordered list of regex matchers,
+ * not a tree. Adding/auditing routes is a one-line patch and routes
+ * are evaluated in priority order (most specific first). Unknown URLs
+ * return `undefined` so the framework falls back to the generic
+ * `vtex.fetch` span name — observable, just less specific.
+ *
+ * Callers that need finer granularity than the URL can express (e.g.
+ * `POST /orderForm/{id}/items` is one URL but covers add / update /
+ * remove flows) should set `init.operation` explicitly per call; that
+ * always wins over the router.
+ */
+export declare function vtexOperationRouter(url: string, method: string): string | undefined;
+//# sourceMappingURL=operationRouter.d.ts.map

package/dist/utils/operationRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operationRouter.d.ts","sourceRoot":"","sources":["../../src/utils/operationRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA8GH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUnF"}

package/dist/utils/operationRouter.js

@@ -0,0 +1,120 @@
+/**
+ * URL-derived operation name router for VTEX API calls.
+ *
+ * Plugged into `createInstrumentedFetch` (`@decocms/blocks/fetch`) via the
+ * `resolveOperation(url, method)` option. The resolved string becomes the
+ * span suffix (`vtex.<operation>`) and the `fetch.operation` span +
+ * histogram label, so it must be:
+ *
+ *   - low-cardinality (no IDs, slugs, search terms, account names);
+ *   - stable across deploys (used for alerting + dashboards);
+ *   - human-debuggable in a trace view.
+ *
+ * The router is intentionally a flat ordered list of regex matchers,
+ * not a tree. Adding/auditing routes is a one-line patch and routes
+ * are evaluated in priority order (most specific first). Unknown URLs
+ * return `undefined` so the framework falls back to the generic
+ * `vtex.fetch` span name — observable, just less specific.
+ *
+ * Callers that need finer granularity than the URL can express (e.g.
+ * `POST /orderForm/{id}/items` is one URL but covers add / update /
+ * remove flows) should set `init.operation` explicitly per call; that
+ * always wins over the router.
+ */
+const m = (pattern, operation) => ({ pattern, operation });
+/**
+ * Ordered list of `(regex, operation)` matchers. The first match wins.
+ *
+ * Patterns match against the URL pathname (the host is ignored — VTEX
+ * spreads the same API surface across `*.vtexcommercestable.*`,
+ * `*.myvtex.com`, and storefront origins, all on identical paths).
+ *
+ * Operation strings are bare (no `vtex.` prefix) — the framework
+ * prefixes them with the integration name at span time.
+ */
+const MATCHERS = [
+    m(/^\/api\/io\/_v\/api\/intelligent-search\/([a-z_-]+)/, (mm) => `intelligent-search.${mm[1]}`),
+    m(/^\/_v\/private\/graphql\/v1/, "io.graphql"),
+    m(/^\/_v\/segment\//, "io.segment"),
+    m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/items\/update/, (_mm, method) => method === "POST" ? "checkout.orderform.items.update" : "checkout.orderform.items"),
+    m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/items/, (_mm, method) => {
+        if (method === "DELETE")
+            return "checkout.orderform.items.remove";
+        if (method === "PATCH" || method === "PUT")
+            return "checkout.orderform.items.update";
+        return "checkout.orderform.items.add";
+    }),
+    m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/coupons/, "checkout.orderform.coupons"),
+    m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/profile/, "checkout.orderform.profile"),
+    m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/shippingData/, "checkout.orderform.shipping"),
+    m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/paymentData/, "checkout.orderform.payment"),
+    m(/^\/api\/checkout\/pub\/orderForm\/[^/]+/, (_mm, method) => method === "GET" ? "checkout.orderform.get" : "checkout.orderform.update"),
+    m(/^\/api\/checkout\/pub\/orderForm(?:\/?$)/, (_mm, method) => method === "POST" ? "checkout.orderform.create" : "checkout.orderform.get"),
+    m(/^\/api\/checkout\/pub\/orderForms\/simulation/, "checkout.simulation"),
+    m(/^\/api\/checkout\/pub\/regions/, "checkout.regions"),
+    m(/^\/api\/checkout\/pub\/postal-code/, "checkout.postal-code"),
+    m(/^\/api\/sessions/, (_mm, method) => (method === "POST" ? "sessions.update" : "sessions.get")),
+    m(/^\/api\/segments\//, "segments.get"),
+    m(/^\/api\/catalog_system\/pub\/portal\/pagetype\//, "catalog.pagetype"),
+    m(/^\/api\/catalog_system\/pub\/products\/crossselling\/([^/]+)/, (mm) => `catalog.crossselling.${mm[1]}`),
+    m(/^\/api\/catalog_system\/pub\/products\/variations\//, "catalog.products.variations"),
+    m(/^\/api\/catalog_system\/pub\/products\/search/, "catalog.products.search"),
+    m(/^\/api\/catalog_system\/pub\/facets\/search/, "catalog.facets.search"),
+    m(/^\/api\/catalog_system\/pub\/category\/tree/, "catalog.category.tree"),
+    m(/^\/api\/catalog_system\/(?:pub|pvt)\/specification/, "catalog.specification"),
+    m(/^\/api\/catalog_system\/pub\/brand/, "catalog.brand"),
+    m(/^\/api\/catalog_system\/pvt\/sku\//, "catalog.sku"),
+    m(/^\/api\/catalog_system\//, "catalog.other"),
+    m(/^\/api\/wishlist\//, "wishlist"),
+    m(/^\/api\/profile-system\/profile\//, "profile"),
+    m(/^\/api\/dataentities\/([^/]+)/, (mm) => `masterdata.${mm[1]}`),
+    m(/^\/api\/oms\/user\/orders\/[^/]+\/cancel/, "oms.orders.cancel"),
+    m(/^\/api\/oms\/user\/orders/, "oms.orders"),
+    m(/^\/api\/oms\/pvt\/orders/, "oms.orders.pvt"),
+    m(/^\/api\/vtexid\/pub\/logout/, "vtexid.logout"),
+    m(/^\/api\/vtexid\/pub\/authentication\/start/, "vtexid.authentication.start"),
+    m(/^\/api\/vtexid\/pub\/authentication\/[a-z]+\/validate/, "vtexid.authentication.validate"),
+    m(/^\/api\/vtexid\/pub\/authenticated\/user/, "vtexid.user"),
+    m(/^\/api\/vtexid\//, "vtexid.other"),
+    m(/^\/api\/events\/v1\//, "events.send"),
+    m(/^\/sitemap.*\.xml$/, "sitemap"),
+    m(/^\/api\/license-manager/, "license-manager"),
+];
+/**
+ * Resolve an operation name for a VTEX URL. Returns `undefined` if no
+ * matcher fires, which causes the framework to fall back to
+ * `vtex.fetch`.
+ *
+ * Designed to be passed directly to `createInstrumentedFetch`:
+ *
+ * ```ts
+ * createInstrumentedFetch({
+ *   name: "vtex",
+ *   resolveOperation: vtexOperationRouter,
+ * });
+ * ```
+ */
+/** The URL's pathname; tolerates relative or malformed URLs by stripping `?`/`#`. */
+function extractPathname(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        const qs = url.indexOf("?");
+        const hash = url.indexOf("#");
+        const end = [qs, hash].filter((i) => i >= 0).sort((a, b) => a - b)[0];
+        return end === undefined ? url : url.slice(0, end);
+    }
+}
+export function vtexOperationRouter(url, method) {
+    const pathname = extractPathname(url);
+    const upperMethod = method.toUpperCase();
+    for (const { pattern, operation } of MATCHERS) {
+        const match = pathname.match(pattern);
+        if (!match)
+            continue;
+        return typeof operation === "function" ? operation(match, upperMethod) : operation;
+    }
+    return undefined;
+}
+//# sourceMappingURL=operationRouter.js.map

package/dist/utils/operationRouter.js.map

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