@a.svetlitskiy/yandex-metrika 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.3.0 (2026-08-30)
+
+### Summary
+
+- Package is now published under the `@a.svetlitskiy` npm scope.
+- Install and import examples updated to use `@a.svetlitskiy/yandex-metrika`.
+- Fixed README table alignment for the new package name.
+- Documentation for browser and server usage updated to match the new scope.
+- Releasing and contributing guides now reference the correct npm scope.
+- CI workflow updated to reflect the new package name and publish prerequisites.
+- No changes to browser or server SDK behavior; this release is purely packaging and documentation.
+
+### Areas changed
+
+- Docs: 4
+- Other: 3
+- CI: 1
+
+Links: https://github.com/svetlitskiy/yandex-metrika/compare/v0.2.0...v0.3.0
+
+## v0.2.0 (2026-08-30)
+
+### Summary
+
+- Initial public release of a framework-neutral TypeScript SDK for Yandex Metrica browser goals and server-side Measurement Protocol events.
+- Ships ESM, CommonJS, and TypeScript declarations through isolated package entry points.
+- Adds server helpers to read a Yandex Metrica ClientID from incoming requests, preferring the `X-Yandex-Metrika-Client-Id` header and falling back to the `_ym_uid` cookie.
+- Adds a browser helper that attaches the ClientID to an existing business request, removing the need for a dedicated `/api/analytics/client-id` endpoint.
+- Introduces `getPropagationHeaders` for easy server-side header propagation when a ClientID is available.
+- Breaking change: browser `getClientID` is now Promise-based and resolves to `string | null`; the callback form was removed, and it resolves to `null` instead of waiting indefinitely on missing counters, invalid values, or timeouts.
+- Adds complete English documentation, practical examples, security guidance, and release instructions.
+- Includes tests, package artifact validation, and an automated npm publication via Trusted Publishing.
+
+### Areas changed
+
+- Other: 14
+- Server: 4
+- Docs: 4
+- Shared: 3
+- Tests: 3
+- CI: 3
+- Browser: 1
+
+Links: https://github.com/svetlitskiy/yandex-metrika/compare/d2b883df8cab0fe7cd05404980fe7db94e057fe0...v0.2.0
+
+## [0.1.0] - 2026-08-29
+
+### Added
+
+- SSR-safe browser client for goals, hits, UserID, user parameters, and ClientID.
+- Framework-neutral server client for Yandex Metrica Measurement Protocol goals.
+- Optional pageview delivery before server-side goals.
+- ESM, CommonJS, and TypeScript package exports.
+- Package validation, CI, Trusted Publishing workflow, and English documentation.
+
+[0.1.0]: https://github.com/svetlitskiy/yandex-metrika/releases/tag/v0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,241 @@
+# @a.svetlitskiy/yandex-metrika
+
+[![npm version](https://img.shields.io/npm/v/@a.svetlitskiy/yandex-metrika.svg)](https://www.npmjs.com/package/@a.svetlitskiy/yandex-metrika)
+[![CI](https://github.com/svetlitskiy/yandex-metrika/actions/workflows/ci.yml/badge.svg)](https://github.com/svetlitskiy/yandex-metrika/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@a.svetlitskiy/yandex-metrika.svg)](./LICENSE)
+
+A small, framework-neutral TypeScript SDK for sending custom events to
+[Yandex Metrica](https://metrica.yandex.com/) from both the browser and the
+server.
+
+Use the browser entry point for the standard `window.ym` API. Use the server
+entry point for events that happen after the browser request: completed
+payments, webhooks, background jobs, CRM updates, bots, or other server-side
+workflows.
+
+## Why this package exists
+
+The Yandex Metrica browser API is convenient for UI interactions, but many
+important conversions do not finish in a browser. Yandex Metrica's Measurement
+Protocol can report those conversions from a server, but it has a different
+HTTP API and requires careful handling of ClientID values and secret tokens.
+
+This package provides one typed, dependency-free transport layer for both
+environments while keeping application policy in your application:
+
+- browser calls are SSR-safe and become no-ops until `window.ym` is available;
+- server calls use the official Measurement Protocol collect endpoint;
+- browser and server code are exposed through separate package entry points;
+- the package does not depend on React, Next.js, Express, Fastify, or a database;
+- the package never invents a ClientID or decides how long your application
+  should store it.
+
+Measurement Protocol supplements the regular Metrica tag; it is not a complete
+replacement for it.
+
+## Installation
+
+```bash
+npm install @a.svetlitskiy/yandex-metrika
+```
+
+The package ships ESM, CommonJS, and TypeScript declarations. It has no runtime
+dependencies and supports Node.js 18.18 or newer.
+
+## Package entry points
+
+| Import                                  | Purpose                                 |
+| --------------------------------------- | --------------------------------------- |
+| `@a.svetlitskiy/yandex-metrika/browser` | The `window.ym` browser client          |
+| `@a.svetlitskiy/yandex-metrika/server`  | Server-side Measurement Protocol events |
+| `@a.svetlitskiy/yandex-metrika`         | Shared helpers and types                |
+| `@a.svetlitskiy/yandex-metrika/types`   | Explicit type-only imports              |
+
+## Browser quick start
+
+Loading and configuring the Yandex Metrica tag remains the host application's
+responsibility. Once the tag has created `window.ym`, create a client:
+
+```ts
+import {
+  createMetrikaBrowserClient,
+  parseMetrikaTagId,
+} from "@a.svetlitskiy/yandex-metrika/browser";
+
+const metrika = createMetrikaBrowserClient({
+  tagId: () => parseMetrikaTagId(process.env.NEXT_PUBLIC_YANDEX_METRIKA_ID),
+});
+
+metrika.reachGoal("signup", { plan: "pro" });
+metrika.hit(window.location.href, { params: { section: "account" } });
+metrika.setUserID("user-123");
+metrika.userParams({ plan: "pro" });
+```
+
+Importing this module does not access `window`. Calls are safe during SSR and
+become no-ops when the counter ID or `window.ym` is unavailable.
+
+See [Browser usage](./docs/browser.md) for ClientID capture and framework notes.
+
+## Server quick start
+
+First enable Measurement Protocol in the counter's **Data security and usage**
+settings and create a secret token. Never expose that token to browser code.
+
+```ts
+import { createMetrikaServerClient } from "@a.svetlitskiy/yandex-metrika/server";
+
+const metrika = createMetrikaServerClient({
+  counterId: process.env.YANDEX_METRIKA_COUNTER_ID,
+  measurementToken: process.env.YANDEX_METRIKA_MEASUREMENT_TOKEN,
+});
+
+const result = await metrika.reachGoal({
+  clientId: storedMetrikaClientId,
+  name: "purchase",
+  url: "https://example.com/checkout/success",
+  params: { orderId: "order-123", plan: "pro" },
+});
+
+// "sent" | "skipped_unconfigured" | "skipped_no_client_id"
+```
+
+The method throws when a configured collect request fails. Missing credentials
+and ClientID values return explicit skip results, making optional analytics easy
+to integrate without masking transport failures.
+
+See [Server usage](./docs/server.md) for new visits, event timestamps, injected
+`fetch`, and error handling.
+
+## Connecting browser and server events
+
+Measurement Protocol uses the Metrica ClientID to associate a server event with
+a visitor. How that value reaches the backend depends on where the backend runs,
+so the package supports the three realistic cases without requiring a dedicated
+analytics endpoint.
+
+### Same domain: read it from the incoming request
+
+When the backend shares a registrable domain with the site, the Metrica
+`_ym_uid` cookie arrives with ordinary business requests:
+
+```ts
+import { getMetrikaClientIdFromRequest } from "@a.svetlitskiy/yandex-metrika/server";
+
+const clientId = getMetrikaClientIdFromRequest(request);
+```
+
+The helper accepts a fetch `Request`, a Node.js `IncomingMessage`, or any object
+with headers. `getMetrikaClientIdFromHeaders` and `getMetrikaClientIdFromCookie`
+are available when only headers or only a cookie string are at hand.
+
+### Different domains: propagate an explicit header
+
+A browser does not send `example.com` cookies to `api.other-service.io`. Attach
+the ClientID to the business request you already make:
+
+```ts
+await fetch("https://api.other-service.io/orders", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    ...(await metrika.getPropagationHeaders()),
+  },
+  body: JSON.stringify(order),
+});
+```
+
+`getPropagationHeaders` resolves to `{ "X-Yandex-Metrika-Client-Id": "..." }`, or
+to an empty object when no ClientID is available, so spreading it is always
+safe. The server helpers read that header before falling back to the cookie.
+
+The package never patches global `fetch` and never sends the ClientID anywhere
+on its own. The application decides which requests carry the header.
+
+### Delayed events: persist the ClientID
+
+Payment webhooks, background jobs, and CRM updates run when no browser request
+exists. Store the extracted value with the entity the later event belongs to:
+
+```ts
+order.metrikaClientId = getMetrikaClientIdFromRequest(request);
+
+// later, from a webhook:
+await metrika.reachGoal({
+  clientId: order.metrikaClientId,
+  name: "payment_completed",
+  url: "https://example.com/orders/payment",
+});
+```
+
+### Optional: a dedicated synchronization endpoint
+
+A separate endpoint is still useful when the ClientID must be attached to a
+signed-in user before any business request happens:
+
+```ts
+const clientId = await metrika.getClientID();
+```
+
+Send that value wherever your application needs it. This is one option, not the
+required integration path.
+
+Your application decides how the ClientID maps to a user, where it is stored,
+when it expires, and whether analytics consent permits storing it. A propagated
+ClientID is untrusted input; the helpers validate it with `isMetrikaClientId`,
+and it must never be treated as authentication or authorization data.
+
+## Starting a server-side visit
+
+If an event cannot extend a recent browser visit, send a pageview immediately
+before the goal:
+
+```ts
+await metrika.reachGoal({
+  clientId: storedMetrikaClientId,
+  name: "subscription_renewed",
+  url: "https://example.com/_channel/background-job",
+  pageview: {
+    referrer: "https://example.com",
+    title: "Background job",
+  },
+});
+```
+
+The pageview metadata is required because Yandex Metrica requires `dr`, `dl`,
+and `dt` when creating a pageview. Measurement Protocol accepts events up to 12
+hours in the past; use `eventTime` only within that window.
+
+## What the package does not do
+
+- It does not load or configure Yandex's browser tag.
+- It does not store ClientID or UserID values.
+- It does not manage consent, cookies, authentication, or user mapping.
+- It does not retry failed requests or hide HTTP errors.
+- It does not define goal names or application-specific event schemas.
+- It does not send secret Measurement Protocol credentials from the browser.
+
+These boundaries keep the package reusable and prevent analytics transport from
+silently making product or privacy decisions.
+
+## Security and privacy
+
+- Import Measurement Protocol code only from the `/server` entry point.
+- Keep `measurementToken` in a server-only secret store.
+- Do not put personal data or secrets into goal parameters.
+- Treat ClientID as user-associated analytics data and apply your consent and
+  retention policy.
+- Rotate the Measurement Protocol token if it is ever exposed.
+
+Please report package vulnerabilities according to [SECURITY.md](./SECURITY.md).
+
+## Documentation
+
+- [Browser usage](./docs/browser.md)
+- [Server and Measurement Protocol usage](./docs/server.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Release process](./docs/releasing.md)
+
+## License
+
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest published minor version.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting feature for this repository.
+Do not open a public issue containing exploit details, Measurement Protocol
+tokens, ClientID values, or other sensitive data.
+
+Reports should include the affected version, impact, reproduction steps, and any
+suggested mitigation. You can expect an acknowledgement within seven days.
+
+## Secret handling
+
+The `measurementToken` option is a server credential. Applications must never
+place it in browser code, public environment variables, analytics parameters,
+logs, or error responses. Rotate the token in Yandex Metrica if exposure is
+suspected.

package/dist/browser/index.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+// src/shared.ts
+var METRIKA_CLIENT_ID_PATTERN = /^\d{1,32}$/;
+var METRIKA_CLIENT_ID_HEADER = "X-Yandex-Metrika-Client-Id";
+var METRIKA_CLIENT_ID_TIMEOUT_MS = 2e3;
+function isMetrikaClientId(value) {
+  return METRIKA_CLIENT_ID_PATTERN.test(value);
+}
+function parseMetrikaTagId(value) {
+  if (!value) return null;
+  const id = Number(value);
+  return Number.isSafeInteger(id) && id > 0 ? id : null;
+}
+
+// src/browser/index.ts
+function getYm() {
+  if (!("window" in globalThis)) return null;
+  const maybeWindow = globalThis.window;
+  if (!maybeWindow || typeof maybeWindow !== "object") return null;
+  if (!("ym" in maybeWindow)) return null;
+  return typeof maybeWindow.ym === "function" ? maybeWindow.ym : null;
+}
+function resolveTagId(tagId) {
+  return typeof tagId === "function" ? tagId() : tagId;
+}
+function createMetrikaBrowserClient(options) {
+  function resolveTarget() {
+    const id = resolveTagId(options.tagId);
+    const ym = getYm();
+    if (!id || !Number.isSafeInteger(id) || id < 1 || !ym) return null;
+    return { id, ym };
+  }
+  function call(method, ...args) {
+    const target = resolveTarget();
+    if (!target) return;
+    target.ym(target.id, method, ...args);
+  }
+  function readClientId(clientIdOptions) {
+    const target = resolveTarget();
+    if (!target) return Promise.resolve(null);
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = (clientId) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(clientId);
+      };
+      const timer = setTimeout(
+        () => finish(null),
+        clientIdOptions?.timeoutMs ?? METRIKA_CLIENT_ID_TIMEOUT_MS
+      );
+      target.ym(target.id, "getClientID", (clientId) => {
+        finish(
+          typeof clientId === "string" && isMetrikaClientId(clientId) ? clientId : null
+        );
+      });
+    });
+  }
+  return {
+    reachGoal(name, params) {
+      params === void 0 ? call("reachGoal", name) : call("reachGoal", name, params);
+    },
+    hit(url, hitOptions) {
+      hitOptions === void 0 ? call("hit", url) : call("hit", url, hitOptions);
+    },
+    setUserID(userId) {
+      call("setUserID", userId);
+    },
+    userParams(params) {
+      call("userParams", params);
+    },
+    getClientID(clientIdOptions) {
+      return readClientId(clientIdOptions);
+    },
+    async getPropagationHeaders(clientIdOptions) {
+      const clientId = await readClientId(clientIdOptions);
+      return clientId ? { [METRIKA_CLIENT_ID_HEADER]: clientId } : {};
+    }
+  };
+}
+
+exports.METRIKA_CLIENT_ID_HEADER = METRIKA_CLIENT_ID_HEADER;
+exports.METRIKA_CLIENT_ID_PATTERN = METRIKA_CLIENT_ID_PATTERN;
+exports.METRIKA_CLIENT_ID_TIMEOUT_MS = METRIKA_CLIENT_ID_TIMEOUT_MS;
+exports.createMetrikaBrowserClient = createMetrikaBrowserClient;
+exports.isMetrikaClientId = isMetrikaClientId;
+exports.parseMetrikaTagId = parseMetrikaTagId;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/browser/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared.ts","../../src/browser/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/** A conservative validation pattern for Yandex Metrica ClientID values. */\nexport const METRIKA_CLIENT_ID_PATTERN = /^\\d{1,32}$/;\n\n/** The public Measurement Protocol collection endpoint. */\nexport const METRIKA_COLLECT_ORIGIN = \"https://mc.yandex.ru/collect\";\n\n/** The default timeout for Measurement Protocol requests. */\nexport const METRIKA_COLLECT_TIMEOUT_MS = 5_000;\n\n/** The header used to propagate a ClientID from the browser to a backend. */\nexport const METRIKA_CLIENT_ID_HEADER = \"X-Yandex-Metrika-Client-Id\";\n\n/** The cookie the Yandex Metrica tag uses to store the ClientID. */\nexport const METRIKA_CLIENT_ID_COOKIE = \"_ym_uid\";\n\n/** The default timeout for reading a ClientID from the browser tag. */\nexport const METRIKA_CLIENT_ID_TIMEOUT_MS = 2_000;\n\n/** Returns whether a value looks like a Yandex Metrica ClientID. */\nexport function isMetrikaClientId(value: string): boolean {\n  return METRIKA_CLIENT_ID_PATTERN.test(value);\n}\n\n/** Parses a counter ID from an environment variable or other string input. */\nexport function parseMetrikaTagId(\n  value: string | undefined | null,\n): number | null {\n  if (!value) return null;\n  const id = Number(value);\n  return Number.isSafeInteger(id) && id > 0 ? id : null;\n}\n","import {\n  METRIKA_CLIENT_ID_HEADER,\n  METRIKA_CLIENT_ID_PATTERN,\n  METRIKA_CLIENT_ID_TIMEOUT_MS,\n  isMetrikaClientId,\n  parseMetrikaTagId,\n} from \"../shared\";\nimport type {\n  MetrikaBrowserClient,\n  MetrikaBrowserHitOptions,\n  MetrikaClientIdOptions,\n  MetrikaParams,\n  MetrikaPropagationHeaders,\n} from \"../types\";\n\nexport {\n  METRIKA_CLIENT_ID_HEADER,\n  METRIKA_CLIENT_ID_PATTERN,\n  METRIKA_CLIENT_ID_TIMEOUT_MS,\n  isMetrikaClientId,\n  parseMetrikaTagId,\n};\nexport type {\n  MetrikaBrowserClient,\n  MetrikaBrowserHitOptions,\n  MetrikaClientIdOptions,\n  MetrikaParams,\n  MetrikaPropagationHeaders,\n};\n\nexport type YmFunction = (\n  id: number,\n  method: string,\n  ...args: unknown[]\n) => void;\n\nexport type MetrikaTagIdInput = number | null | (() => number | null);\n\nexport type CreateMetrikaBrowserClientOptions = {\n  tagId: MetrikaTagIdInput;\n};\n\nfunction getYm(): YmFunction | null {\n  if (!(\"window\" in globalThis)) return null;\n  const maybeWindow = globalThis.window as unknown;\n  if (!maybeWindow || typeof maybeWindow !== \"object\") return null;\n  if (!(\"ym\" in maybeWindow)) return null;\n  return typeof maybeWindow.ym === \"function\"\n    ? (maybeWindow.ym as YmFunction)\n    : null;\n}\n\nfunction resolveTagId(tagId: MetrikaTagIdInput): number | null {\n  return typeof tagId === \"function\" ? tagId() : tagId;\n}\n\n/**\n * Creates a browser client backed by the global `window.ym` function.\n *\n * Importing and calling the client is safe during SSR. Calls become no-ops\n * until both a valid counter ID and `window.ym` are available.\n */\nexport function createMetrikaBrowserClient(\n  options: CreateMetrikaBrowserClientOptions,\n): MetrikaBrowserClient {\n  function resolveTarget(): { id: number; ym: YmFunction } | null {\n    const id = resolveTagId(options.tagId);\n    const ym = getYm();\n    if (!id || !Number.isSafeInteger(id) || id < 1 || !ym) return null;\n    return { id, ym };\n  }\n\n  function call(method: string, ...args: unknown[]): void {\n    const target = resolveTarget();\n    if (!target) return;\n    target.ym(target.id, method, ...args);\n  }\n\n  /**\n   * Reads the ClientID assigned by the Metrica tag.\n   *\n   * Resolves with `null` instead of waiting forever when the tag is missing,\n   * blocked, or slow: the `ym` stub queues calls before `tag.js` loads, so a\n   * blocked tag would otherwise never invoke the callback.\n   */\n  function readClientId(\n    clientIdOptions?: MetrikaClientIdOptions,\n  ): Promise<string | null> {\n    const target = resolveTarget();\n    if (!target) return Promise.resolve(null);\n\n    return new Promise<string | null>((resolve) => {\n      let settled = false;\n      const finish = (clientId: string | null) => {\n        if (settled) return;\n        settled = true;\n        clearTimeout(timer);\n        resolve(clientId);\n      };\n\n      const timer = setTimeout(\n        () => finish(null),\n        clientIdOptions?.timeoutMs ?? METRIKA_CLIENT_ID_TIMEOUT_MS,\n      );\n\n      target.ym(target.id, \"getClientID\", (clientId: unknown) => {\n        finish(\n          typeof clientId === \"string\" && isMetrikaClientId(clientId)\n            ? clientId\n            : null,\n        );\n      });\n    });\n  }\n\n  return {\n    reachGoal(name: string, params?: MetrikaParams) {\n      params === undefined\n        ? call(\"reachGoal\", name)\n        : call(\"reachGoal\", name, params);\n    },\n    hit(url: string, hitOptions?: MetrikaBrowserHitOptions) {\n      hitOptions === undefined\n        ? call(\"hit\", url)\n        : call(\"hit\", url, hitOptions);\n    },\n    setUserID(userId: string) {\n      call(\"setUserID\", userId);\n    },\n    userParams(params: MetrikaParams) {\n      call(\"userParams\", params);\n    },\n    getClientID(clientIdOptions?: MetrikaClientIdOptions) {\n      return readClientId(clientIdOptions);\n    },\n    async getPropagationHeaders(\n      clientIdOptions?: MetrikaClientIdOptions,\n    ): Promise<MetrikaPropagationHeaders> {\n      const clientId = await readClientId(clientIdOptions);\n      return clientId ? { [METRIKA_CLIENT_ID_HEADER]: clientId } : {};\n    },\n  };\n}\n"]}

package/dist/browser/index.d.cts

@@ -0,0 +1,18 @@
+export { METRIKA_CLIENT_ID_HEADER, METRIKA_CLIENT_ID_PATTERN, METRIKA_CLIENT_ID_TIMEOUT_MS, isMetrikaClientId, parseMetrikaTagId } from '../index.cjs';
+import { MetrikaBrowserClient } from '../types.cjs';
+export { MetrikaBrowserHitOptions, MetrikaClientIdOptions, MetrikaParams, MetrikaPropagationHeaders } from '../types.cjs';
+
+type YmFunction = (id: number, method: string, ...args: unknown[]) => void;
+type MetrikaTagIdInput = number | null | (() => number | null);
+type CreateMetrikaBrowserClientOptions = {
+    tagId: MetrikaTagIdInput;
+};
+/**
+ * Creates a browser client backed by the global `window.ym` function.
+ *
+ * Importing and calling the client is safe during SSR. Calls become no-ops
+ * until both a valid counter ID and `window.ym` are available.
+ */
+declare function createMetrikaBrowserClient(options: CreateMetrikaBrowserClientOptions): MetrikaBrowserClient;
+
+export { type CreateMetrikaBrowserClientOptions, MetrikaBrowserClient, type MetrikaTagIdInput, type YmFunction, createMetrikaBrowserClient };

package/dist/browser/index.d.ts

@@ -0,0 +1,18 @@
+export { METRIKA_CLIENT_ID_HEADER, METRIKA_CLIENT_ID_PATTERN, METRIKA_CLIENT_ID_TIMEOUT_MS, isMetrikaClientId, parseMetrikaTagId } from '../index.js';
+import { MetrikaBrowserClient } from '../types.js';
+export { MetrikaBrowserHitOptions, MetrikaClientIdOptions, MetrikaParams, MetrikaPropagationHeaders } from '../types.js';
+
+type YmFunction = (id: number, method: string, ...args: unknown[]) => void;
+type MetrikaTagIdInput = number | null | (() => number | null);
+type CreateMetrikaBrowserClientOptions = {
+    tagId: MetrikaTagIdInput;
+};
+/**
+ * Creates a browser client backed by the global `window.ym` function.
+ *
+ * Importing and calling the client is safe during SSR. Calls become no-ops
+ * until both a valid counter ID and `window.ym` are available.
+ */
+declare function createMetrikaBrowserClient(options: CreateMetrikaBrowserClientOptions): MetrikaBrowserClient;
+
+export { type CreateMetrikaBrowserClientOptions, MetrikaBrowserClient, type MetrikaTagIdInput, type YmFunction, createMetrikaBrowserClient };

package/dist/browser/index.js

@@ -0,0 +1,84 @@
+// src/shared.ts
+var METRIKA_CLIENT_ID_PATTERN = /^\d{1,32}$/;
+var METRIKA_CLIENT_ID_HEADER = "X-Yandex-Metrika-Client-Id";
+var METRIKA_CLIENT_ID_TIMEOUT_MS = 2e3;
+function isMetrikaClientId(value) {
+  return METRIKA_CLIENT_ID_PATTERN.test(value);
+}
+function parseMetrikaTagId(value) {
+  if (!value) return null;
+  const id = Number(value);
+  return Number.isSafeInteger(id) && id > 0 ? id : null;
+}
+
+// src/browser/index.ts
+function getYm() {
+  if (!("window" in globalThis)) return null;
+  const maybeWindow = globalThis.window;
+  if (!maybeWindow || typeof maybeWindow !== "object") return null;
+  if (!("ym" in maybeWindow)) return null;
+  return typeof maybeWindow.ym === "function" ? maybeWindow.ym : null;
+}
+function resolveTagId(tagId) {
+  return typeof tagId === "function" ? tagId() : tagId;
+}
+function createMetrikaBrowserClient(options) {
+  function resolveTarget() {
+    const id = resolveTagId(options.tagId);
+    const ym = getYm();
+    if (!id || !Number.isSafeInteger(id) || id < 1 || !ym) return null;
+    return { id, ym };
+  }
+  function call(method, ...args) {
+    const target = resolveTarget();
+    if (!target) return;
+    target.ym(target.id, method, ...args);
+  }
+  function readClientId(clientIdOptions) {
+    const target = resolveTarget();
+    if (!target) return Promise.resolve(null);
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = (clientId) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(clientId);
+      };
+      const timer = setTimeout(
+        () => finish(null),
+        clientIdOptions?.timeoutMs ?? METRIKA_CLIENT_ID_TIMEOUT_MS
+      );
+      target.ym(target.id, "getClientID", (clientId) => {
+        finish(
+          typeof clientId === "string" && isMetrikaClientId(clientId) ? clientId : null
+        );
+      });
+    });
+  }
+  return {
+    reachGoal(name, params) {
+      params === void 0 ? call("reachGoal", name) : call("reachGoal", name, params);
+    },
+    hit(url, hitOptions) {
+      hitOptions === void 0 ? call("hit", url) : call("hit", url, hitOptions);
+    },
+    setUserID(userId) {
+      call("setUserID", userId);
+    },
+    userParams(params) {
+      call("userParams", params);
+    },
+    getClientID(clientIdOptions) {
+      return readClientId(clientIdOptions);
+    },
+    async getPropagationHeaders(clientIdOptions) {
+      const clientId = await readClientId(clientIdOptions);
+      return clientId ? { [METRIKA_CLIENT_ID_HEADER]: clientId } : {};
+    }
+  };
+}
+
+export { METRIKA_CLIENT_ID_HEADER, METRIKA_CLIENT_ID_PATTERN, METRIKA_CLIENT_ID_TIMEOUT_MS, createMetrikaBrowserClient, isMetrikaClientId, parseMetrikaTagId };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared.ts","../../src/browser/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** A conservative validation pattern for Yandex Metrica ClientID values. */\nexport const METRIKA_CLIENT_ID_PATTERN = /^\\d{1,32}$/;\n\n/** The public Measurement Protocol collection endpoint. */\nexport const METRIKA_COLLECT_ORIGIN = \"https://mc.yandex.ru/collect\";\n\n/** The default timeout for Measurement Protocol requests. */\nexport const METRIKA_COLLECT_TIMEOUT_MS = 5_000;\n\n/** The header used to propagate a ClientID from the browser to a backend. */\nexport const METRIKA_CLIENT_ID_HEADER = \"X-Yandex-Metrika-Client-Id\";\n\n/** The cookie the Yandex Metrica tag uses to store the ClientID. */\nexport const METRIKA_CLIENT_ID_COOKIE = \"_ym_uid\";\n\n/** The default timeout for reading a ClientID from the browser tag. */\nexport const METRIKA_CLIENT_ID_TIMEOUT_MS = 2_000;\n\n/** Returns whether a value looks like a Yandex Metrica ClientID. */\nexport function isMetrikaClientId(value: string): boolean {\n  return METRIKA_CLIENT_ID_PATTERN.test(value);\n}\n\n/** Parses a counter ID from an environment variable or other string input. */\nexport function parseMetrikaTagId(\n  value: string | undefined | null,\n): number | null {\n  if (!value) return null;\n  const id = Number(value);\n  return Number.isSafeInteger(id) && id > 0 ? id : null;\n}\n","import {\n  METRIKA_CLIENT_ID_HEADER,\n  METRIKA_CLIENT_ID_PATTERN,\n  METRIKA_CLIENT_ID_TIMEOUT_MS,\n  isMetrikaClientId,\n  parseMetrikaTagId,\n} from \"../shared\";\nimport type {\n  MetrikaBrowserClient,\n  MetrikaBrowserHitOptions,\n  MetrikaClientIdOptions,\n  MetrikaParams,\n  MetrikaPropagationHeaders,\n} from \"../types\";\n\nexport {\n  METRIKA_CLIENT_ID_HEADER,\n  METRIKA_CLIENT_ID_PATTERN,\n  METRIKA_CLIENT_ID_TIMEOUT_MS,\n  isMetrikaClientId,\n  parseMetrikaTagId,\n};\nexport type {\n  MetrikaBrowserClient,\n  MetrikaBrowserHitOptions,\n  MetrikaClientIdOptions,\n  MetrikaParams,\n  MetrikaPropagationHeaders,\n};\n\nexport type YmFunction = (\n  id: number,\n  method: string,\n  ...args: unknown[]\n) => void;\n\nexport type MetrikaTagIdInput = number | null | (() => number | null);\n\nexport type CreateMetrikaBrowserClientOptions = {\n  tagId: MetrikaTagIdInput;\n};\n\nfunction getYm(): YmFunction | null {\n  if (!(\"window\" in globalThis)) return null;\n  const maybeWindow = globalThis.window as unknown;\n  if (!maybeWindow || typeof maybeWindow !== \"object\") return null;\n  if (!(\"ym\" in maybeWindow)) return null;\n  return typeof maybeWindow.ym === \"function\"\n    ? (maybeWindow.ym as YmFunction)\n    : null;\n}\n\nfunction resolveTagId(tagId: MetrikaTagIdInput): number | null {\n  return typeof tagId === \"function\" ? tagId() : tagId;\n}\n\n/**\n * Creates a browser client backed by the global `window.ym` function.\n *\n * Importing and calling the client is safe during SSR. Calls become no-ops\n * until both a valid counter ID and `window.ym` are available.\n */\nexport function createMetrikaBrowserClient(\n  options: CreateMetrikaBrowserClientOptions,\n): MetrikaBrowserClient {\n  function resolveTarget(): { id: number; ym: YmFunction } | null {\n    const id = resolveTagId(options.tagId);\n    const ym = getYm();\n    if (!id || !Number.isSafeInteger(id) || id < 1 || !ym) return null;\n    return { id, ym };\n  }\n\n  function call(method: string, ...args: unknown[]): void {\n    const target = resolveTarget();\n    if (!target) return;\n    target.ym(target.id, method, ...args);\n  }\n\n  /**\n   * Reads the ClientID assigned by the Metrica tag.\n   *\n   * Resolves with `null` instead of waiting forever when the tag is missing,\n   * blocked, or slow: the `ym` stub queues calls before `tag.js` loads, so a\n   * blocked tag would otherwise never invoke the callback.\n   */\n  function readClientId(\n    clientIdOptions?: MetrikaClientIdOptions,\n  ): Promise<string | null> {\n    const target = resolveTarget();\n    if (!target) return Promise.resolve(null);\n\n    return new Promise<string | null>((resolve) => {\n      let settled = false;\n      const finish = (clientId: string | null) => {\n        if (settled) return;\n        settled = true;\n        clearTimeout(timer);\n        resolve(clientId);\n      };\n\n      const timer = setTimeout(\n        () => finish(null),\n        clientIdOptions?.timeoutMs ?? METRIKA_CLIENT_ID_TIMEOUT_MS,\n      );\n\n      target.ym(target.id, \"getClientID\", (clientId: unknown) => {\n        finish(\n          typeof clientId === \"string\" && isMetrikaClientId(clientId)\n            ? clientId\n            : null,\n        );\n      });\n    });\n  }\n\n  return {\n    reachGoal(name: string, params?: MetrikaParams) {\n      params === undefined\n        ? call(\"reachGoal\", name)\n        : call(\"reachGoal\", name, params);\n    },\n    hit(url: string, hitOptions?: MetrikaBrowserHitOptions) {\n      hitOptions === undefined\n        ? call(\"hit\", url)\n        : call(\"hit\", url, hitOptions);\n    },\n    setUserID(userId: string) {\n      call(\"setUserID\", userId);\n    },\n    userParams(params: MetrikaParams) {\n      call(\"userParams\", params);\n    },\n    getClientID(clientIdOptions?: MetrikaClientIdOptions) {\n      return readClientId(clientIdOptions);\n    },\n    async getPropagationHeaders(\n      clientIdOptions?: MetrikaClientIdOptions,\n    ): Promise<MetrikaPropagationHeaders> {\n      const clientId = await readClientId(clientIdOptions);\n      return clientId ? { [METRIKA_CLIENT_ID_HEADER]: clientId } : {};\n    },\n  };\n}\n"]}

package/dist/index.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+// src/shared.ts
+var METRIKA_CLIENT_ID_PATTERN = /^\d{1,32}$/;
+var METRIKA_COLLECT_ORIGIN = "https://mc.yandex.ru/collect";
+var METRIKA_COLLECT_TIMEOUT_MS = 5e3;
+var METRIKA_CLIENT_ID_HEADER = "X-Yandex-Metrika-Client-Id";
+var METRIKA_CLIENT_ID_COOKIE = "_ym_uid";
+var METRIKA_CLIENT_ID_TIMEOUT_MS = 2e3;
+function isMetrikaClientId(value) {
+  return METRIKA_CLIENT_ID_PATTERN.test(value);
+}
+function parseMetrikaTagId(value) {
+  if (!value) return null;
+  const id = Number(value);
+  return Number.isSafeInteger(id) && id > 0 ? id : null;
+}
+
+exports.METRIKA_CLIENT_ID_COOKIE = METRIKA_CLIENT_ID_COOKIE;
+exports.METRIKA_CLIENT_ID_HEADER = METRIKA_CLIENT_ID_HEADER;
+exports.METRIKA_CLIENT_ID_PATTERN = METRIKA_CLIENT_ID_PATTERN;
+exports.METRIKA_CLIENT_ID_TIMEOUT_MS = METRIKA_CLIENT_ID_TIMEOUT_MS;
+exports.METRIKA_COLLECT_ORIGIN = METRIKA_COLLECT_ORIGIN;
+exports.METRIKA_COLLECT_TIMEOUT_MS = METRIKA_COLLECT_TIMEOUT_MS;
+exports.isMetrikaClientId = isMetrikaClientId;
+exports.parseMetrikaTagId = parseMetrikaTagId;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared.ts"],"names":[],"mappings":";;;AACO,IAAM,yBAAA,GAA4B;AAGlC,IAAM,sBAAA,GAAyB;AAG/B,IAAM,0BAAA,GAA6B;AAGnC,IAAM,wBAAA,GAA2B;AAGjC,IAAM,wBAAA,GAA2B;AAGjC,IAAM,4BAAA,GAA+B;AAGrC,SAAS,kBAAkB,KAAA,EAAwB;AACxD,EAAA,OAAO,yBAAA,CAA0B,KAAK,KAAK,CAAA;AAC7C;AAGO,SAAS,kBACd,KAAA,EACe;AACf,EAAA,IAAI,CAAC,OAAO,OAAO,IAAA;AACnB,EAAA,MAAM,EAAA,GAAK,OAAO,KAAK,CAAA;AACvB,EAAA,OAAO,OAAO,aAAA,CAAc,EAAE,CAAA,IAAK,EAAA,GAAK,IAAI,EAAA,GAAK,IAAA;AACnD","file":"index.cjs","sourcesContent":["/** A conservative validation pattern for Yandex Metrica ClientID values. */\nexport const METRIKA_CLIENT_ID_PATTERN = /^\\d{1,32}$/;\n\n/** The public Measurement Protocol collection endpoint. */\nexport const METRIKA_COLLECT_ORIGIN = \"https://mc.yandex.ru/collect\";\n\n/** The default timeout for Measurement Protocol requests. */\nexport const METRIKA_COLLECT_TIMEOUT_MS = 5_000;\n\n/** The header used to propagate a ClientID from the browser to a backend. */\nexport const METRIKA_CLIENT_ID_HEADER = \"X-Yandex-Metrika-Client-Id\";\n\n/** The cookie the Yandex Metrica tag uses to store the ClientID. */\nexport const METRIKA_CLIENT_ID_COOKIE = \"_ym_uid\";\n\n/** The default timeout for reading a ClientID from the browser tag. */\nexport const METRIKA_CLIENT_ID_TIMEOUT_MS = 2_000;\n\n/** Returns whether a value looks like a Yandex Metrica ClientID. */\nexport function isMetrikaClientId(value: string): boolean {\n  return METRIKA_CLIENT_ID_PATTERN.test(value);\n}\n\n/** Parses a counter ID from an environment variable or other string input. */\nexport function parseMetrikaTagId(\n  value: string | undefined | null,\n): number | null {\n  if (!value) return null;\n  const id = Number(value);\n  return Number.isSafeInteger(id) && id > 0 ? id : null;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,20 @@
+export { CreateMetrikaServerClientOptions, MetrikaBrowserClient, MetrikaBrowserHitOptions, MetrikaClientIdLookupOptions, MetrikaClientIdOptions, MetrikaCollectHit, MetrikaFetch, MetrikaHeadersLike, MetrikaPageviewOptions, MetrikaParams, MetrikaPropagationHeaders, MetrikaReachGoalInput, MetrikaRequestLike, MetrikaServerClient, MetrikaServerConfig, MetrikaServerGoalResult, MetrikaTagId } from './types.cjs';
+
+/** A conservative validation pattern for Yandex Metrica ClientID values. */
+declare const METRIKA_CLIENT_ID_PATTERN: RegExp;
+/** The public Measurement Protocol collection endpoint. */
+declare const METRIKA_COLLECT_ORIGIN = "https://mc.yandex.ru/collect";
+/** The default timeout for Measurement Protocol requests. */
+declare const METRIKA_COLLECT_TIMEOUT_MS = 5000;
+/** The header used to propagate a ClientID from the browser to a backend. */
+declare const METRIKA_CLIENT_ID_HEADER = "X-Yandex-Metrika-Client-Id";
+/** The cookie the Yandex Metrica tag uses to store the ClientID. */
+declare const METRIKA_CLIENT_ID_COOKIE = "_ym_uid";
+/** The default timeout for reading a ClientID from the browser tag. */
+declare const METRIKA_CLIENT_ID_TIMEOUT_MS = 2000;
+/** Returns whether a value looks like a Yandex Metrica ClientID. */
+declare function isMetrikaClientId(value: string): boolean;
+/** Parses a counter ID from an environment variable or other string input. */
+declare function parseMetrikaTagId(value: string | undefined | null): number | null;
+
+export { METRIKA_CLIENT_ID_COOKIE, METRIKA_CLIENT_ID_HEADER, METRIKA_CLIENT_ID_PATTERN, METRIKA_CLIENT_ID_TIMEOUT_MS, METRIKA_COLLECT_ORIGIN, METRIKA_COLLECT_TIMEOUT_MS, isMetrikaClientId, parseMetrikaTagId };