@obelism/numbers-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obelism
+
+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

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Obelism numbers SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Page views, events and clicks on tagged elements, sent to
+[Obelism numbers](https://numbers.obelism.studio): the events every Obelism
+product shares, and their dashboard. The improve SDK sends its events
+through this client, so a site with improve already has it; this package is
+for numbers on its own.
+
+## Script tag
+
+No bundler needed:
+
+```html
+<script
+	defer
+	src="https://numbers.obelism.studio/script.js"
+	data-organization="org_…"
+	data-environment="production"
+></script>
+```
+
+It sends a page view on load and on every client-side navigation, a `click`
+for clicks on (or inside) an element with `data-numbers-id="…"`, and puts the
+client on `window.numbers`:
+
+```js
+numbers.track('sign_up', 'footer_form')
+```
+
+`data-endpoint="https://…"` sends somewhere else, e.g. a proxy on your own
+domain. npm CDNs serve the same file from
+`@obelism/numbers-sdk/dist/script.global.js`.
+
+## Module
+
+```bash
+npm i @obelism/numbers-sdk
+```
+
+```ts
+import { createNumbers } from '@obelism/numbers-sdk'
+
+const numbers = createNumbers({
+	organizationId: 'org_…',
+	environment: 'production', // default; or 'develop', 'staging'
+	// endpoint: 'https://numbers.obelism.studio/api/log',
+	// disableWarnings: true,
+})
+
+// Page views now and on every navigation, and clicks on tagged elements.
+const stop = numbers.autoTrack() // { pageViews?: boolean, clicks?: boolean }
+
+numbers.track('add_to_cart', 'product_page', {
+	value: 59.95,
+	currency: 'EUR',
+	params: { ecommerce: { items: [{ item_id: 'sku_1' }] } },
+})
+numbers.track('view_item', 'list', { dedupeKey: 'sku_1' }) // once per key
+numbers.pageView() // by hand, without autoTrack
+```
+
+The client is safe to create during server rendering: outside the browser
+every call does nothing and returns `null`.
+
+### Events
+
+An event is a name and a scope. Use snake_case names, the GA4 recommended
+ones where they fit (`sign_up`, `add_to_cart`, `purchase`): the client warns
+once about any other. The scope is the stable second half of its identity,
+where or what it is about (`homepage_hero_signup`); it defaults to the page's
+path. Every event carries the page's path and UTM tags, the first page view
+also the referrer when it is another site. Query strings never leave the
+browser.
+
+`value` and `currency` are summed into revenue per variant in improve.
+`params` are stored as JSON. `track` returns `null` when it sent nothing,
+otherwise a promise of the response (`undefined` when the request failed; it
+never rejects).
+
+### Tagged elements
+
+```html
+<section data-numbers-id="hero_signup">…</section>
+```
+
+A click on or inside it is a `click` event with scope `hero_signup`. numbers
+shows the most clicked elements; Content tags its blocks with their id, so
+its visual editor shows each block's click rate.
+
+### Visitors
+
+A visitor is a random id in the `visitorId` cookie (`visi_` and 26
+characters, 30 days from the last visit), the same cookie the improve SDK
+uses. `numbers.visitor()` returns `{ id, recurring }`. The device categories
+(pointer, device, browser, os, screen size) come from the user agent; pass
+`device` to `createNumbers` (or call `setDevice`) to use your own.
+
+### Limits
+
+Strings are capped to what numbers accepts (256 characters, currency 8),
+and the client warns about a request over 8 KB, which numbers refuses. After
+a `429` it stops sending for the `Retry-After`, or a minute.

package/dist/index.d.mts

@@ -0,0 +1,135 @@
+type Environment = 'develop' | 'staging' | 'production';
+/**
+ * The visitor's device categories, as improve's audiences know them. The
+ * client works them out from the user agent; an SDK that parses it more
+ * thoroughly (improve's) passes its own.
+ */
+type Device = {
+    pointer: 'coarse' | 'fine';
+    device: string;
+    browser: string;
+    os: string;
+};
+type NumbersOptions = {
+    organizationId: string;
+    /** Default `production`. */
+    environment?: Environment;
+    /**
+     * Where events go. Default `https://numbers.obelism.studio/api/log`; point
+     * it at a proxy on your own domain to get past ad blockers.
+     */
+    endpoint?: string;
+    /** The device categories, when you parse the user agent yourself. */
+    device?: Device;
+    /** Silence the development warnings (e.g. a name that isn't snake_case). */
+    disableWarnings?: boolean;
+};
+/**
+ * Event names GA4 / Google Tag Manager recommend. Reusing them lines your
+ * numbers up with any GA4 tagging you have.
+ *
+ * @see https://support.google.com/analytics/answer/9267735
+ */
+type RecommendedEventName = 'page_view' | 'view_item' | 'view_item_list' | 'select_item' | 'add_to_cart' | 'remove_from_cart' | 'view_cart' | 'begin_checkout' | 'add_payment_info' | 'add_shipping_info' | 'purchase' | 'refund' | 'sign_up' | 'login' | 'search' | 'select_content' | 'share' | 'generate_lead';
+/** An event's name: snake_case, any string, the GA4 ones suggested. */
+type EventName = RecommendedEventName | (string & {});
+type TrackOptions = {
+    /** A numeric value, e.g. an order total (GA4 `value`). */
+    value?: number;
+    /** ISO 4217 currency for `value`, e.g. `'EUR'`. */
+    currency?: string;
+    /** Extra parameters, stored as JSON (e.g. a GA4 `ecommerce` object). */
+    params?: Record<string, unknown>;
+    /**
+     * Sends the event once per client for this event and key, e.g. an item id
+     * for a `view_item` fired every render. Not sent; without it every call
+     * sends.
+     */
+    dedupeKey?: string;
+};
+/**
+ * A visitor's assignment to a test's or flag's variant, for SDKs that run
+ * them (improve's). numbers attributes the visitor's events to it.
+ */
+type Exposure = {
+    subjectKind: 'test' | 'flag';
+    subjectId: string;
+    variant: string;
+};
+/** Fields every request carries. */
+type BeaconCommon<T extends 'event' | 'exposure'> = {
+    type: T;
+    organizationId: string;
+    environment: Environment;
+    visitorId: string;
+    pointer: string;
+    device: string;
+    screen: string;
+    browser: string;
+    os: string;
+    visitor: 'new' | 'recurring';
+};
+/** The page an event happened on. Paths leave without their query string. */
+type PageContext = {
+    path?: string;
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+};
+type EventBeacon = BeaconCommon<'event'> & PageContext & {
+    event: string;
+    scope: string;
+    value?: number;
+    currency?: string;
+    params?: Record<string, unknown>;
+};
+type ExposureBeacon = BeaconCommon<'exposure'> & Exposure;
+
+type Visitor = {
+    id: string;
+    /** Whether the visitor had a cookie already: `recurring` on the server. */
+    recurring: boolean;
+};
+
+type AutoTrackOptions = {
+    /** A page view now and on every client-side navigation. Default on. */
+    pageViews?: boolean;
+    /**
+     * A `click` event, scoped to the id, for every click on or inside an
+     * element with `data-numbers-id="…"`. Default on.
+     */
+    clicks?: boolean;
+};
+/** What a send resolves to: the response, or nothing when it failed. */
+type Sent = Promise<Response | undefined>;
+type NumbersClient = {
+    readonly organizationId: string;
+    readonly environment: Environment;
+    /** The visitor, from the cookie or new. `null` outside the browser. */
+    visitor: () => Visitor | null;
+    /** Replaces the device categories, e.g. from a fuller user-agent parser. */
+    setDevice: (device: Device) => void;
+    setEndpoint: (endpoint: string) => void;
+    /**
+     * Sends an event. `scope` is the stable second half of its identity, e.g.
+     * `'homepage_hero_signup'` (default: the page's path). `null` when nothing
+     * was sent: outside the browser, deduplicated, or paused after a 429.
+     */
+    track: (event: EventName, scope?: string, options?: TrackOptions) => Sent | null;
+    /** Sends a page view of the current page. */
+    pageView: () => Sent | null;
+    /** Sends a test's or flag's assignment, once per subject per client. */
+    expose: (exposure: Exposure) => Sent | null;
+    /** Starts page views and click tracking; returns a function that stops them. */
+    autoTrack: (options?: AutoTrackOptions) => () => void;
+};
+declare const createNumbers: ({ organizationId, environment, endpoint, device: givenDevice, disableWarnings, }: NumbersOptions) => NumbersClient;
+
+declare const DEFAULT_ENDPOINT = "https://numbers.obelism.studio/api/log";
+
+declare const detectDevice: (userAgent: string) => Device;
+
+export { DEFAULT_ENDPOINT, createNumbers, detectDevice };
+export type { AutoTrackOptions, BeaconCommon, Device, Environment, EventBeacon, EventName, Exposure, ExposureBeacon, NumbersClient, NumbersOptions, PageContext, RecommendedEventName, Sent, TrackOptions, Visitor };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sources":["../src/types.ts","../src/visitor.ts","../src/client.ts","../src/constants.ts","../src/device.ts"],"mappings":"AAAA,KAAK,WAAW;AAChB;AACA;AACA;AACA;AACA;AACA,KAAK,MAAM;AACX;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB;AACA;AACA,kBAAkB,WAAW;AAC7B;AACA;AACA;AACA;AACA;AACA;AACA,aAAa,MAAM;AACnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,oBAAoB;AACzB;AACA,KAAK,SAAS,GAAG,oBAAoB;AACrC,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA,aAAa,MAAM;AACnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,QAAQ;AACb;AACA;AACA;AACA;AACA;AACA,KAAK,YAAY;AACjB;AACA;AACA,iBAAiB,WAAW;AAC5B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,WAAW;AAChB;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,WAAW,GAAG,YAAY,YAAY,WAAW;AACtD;AACA;AACA;AACA;AACA,aAAa,MAAM;AACnB;AACA,KAAK,cAAc,GAAG,YAAY,eAAe,QAAQ;;ACtFzD,KAAK,OAAO;AACZ;AACA;AACA;AACA;;ACFA,KAAK,gBAAgB;AACrB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,IAAI,GAAG,OAAO,CAAC,QAAQ;AAC5B,KAAK,aAAa;AAClB;AACA,0BAA0B,WAAW;AACrC;AACA,mBAAmB,OAAO;AAC1B;AACA,wBAAwB,MAAM;AAC9B;AACA;AACA;AACA;AACA;AACA;AACA,mBAAmB,SAAS,4BAA4B,YAAY,KAAK,IAAI;AAC7E;AACA,oBAAoB,IAAI;AACxB;AACA,uBAAuB,QAAQ,KAAK,IAAI;AACxC;AACA,0BAA0B,gBAAgB;AAC1C;AACA,cAAc,aAAa,qFAAqF,cAAc,KAAK,aAAa;;AClChJ,cAAc,gBAAgB;;ACC9B,cAAc,YAAY,yBAAyB,MAAM;;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+type Environment = 'develop' | 'staging' | 'production';
+/**
+ * The visitor's device categories, as improve's audiences know them. The
+ * client works them out from the user agent; an SDK that parses it more
+ * thoroughly (improve's) passes its own.
+ */
+type Device = {
+    pointer: 'coarse' | 'fine';
+    device: string;
+    browser: string;
+    os: string;
+};
+type NumbersOptions = {
+    organizationId: string;
+    /** Default `production`. */
+    environment?: Environment;
+    /**
+     * Where events go. Default `https://numbers.obelism.studio/api/log`; point
+     * it at a proxy on your own domain to get past ad blockers.
+     */
+    endpoint?: string;
+    /** The device categories, when you parse the user agent yourself. */
+    device?: Device;
+    /** Silence the development warnings (e.g. a name that isn't snake_case). */
+    disableWarnings?: boolean;
+};
+/**
+ * Event names GA4 / Google Tag Manager recommend. Reusing them lines your
+ * numbers up with any GA4 tagging you have.
+ *
+ * @see https://support.google.com/analytics/answer/9267735
+ */
+type RecommendedEventName = 'page_view' | 'view_item' | 'view_item_list' | 'select_item' | 'add_to_cart' | 'remove_from_cart' | 'view_cart' | 'begin_checkout' | 'add_payment_info' | 'add_shipping_info' | 'purchase' | 'refund' | 'sign_up' | 'login' | 'search' | 'select_content' | 'share' | 'generate_lead';
+/** An event's name: snake_case, any string, the GA4 ones suggested. */
+type EventName = RecommendedEventName | (string & {});
+type TrackOptions = {
+    /** A numeric value, e.g. an order total (GA4 `value`). */
+    value?: number;
+    /** ISO 4217 currency for `value`, e.g. `'EUR'`. */
+    currency?: string;
+    /** Extra parameters, stored as JSON (e.g. a GA4 `ecommerce` object). */
+    params?: Record<string, unknown>;
+    /**
+     * Sends the event once per client for this event and key, e.g. an item id
+     * for a `view_item` fired every render. Not sent; without it every call
+     * sends.
+     */
+    dedupeKey?: string;
+};
+/**
+ * A visitor's assignment to a test's or flag's variant, for SDKs that run
+ * them (improve's). numbers attributes the visitor's events to it.
+ */
+type Exposure = {
+    subjectKind: 'test' | 'flag';
+    subjectId: string;
+    variant: string;
+};
+/** Fields every request carries. */
+type BeaconCommon<T extends 'event' | 'exposure'> = {
+    type: T;
+    organizationId: string;
+    environment: Environment;
+    visitorId: string;
+    pointer: string;
+    device: string;
+    screen: string;
+    browser: string;
+    os: string;
+    visitor: 'new' | 'recurring';
+};
+/** The page an event happened on. Paths leave without their query string. */
+type PageContext = {
+    path?: string;
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+};
+type EventBeacon = BeaconCommon<'event'> & PageContext & {
+    event: string;
+    scope: string;
+    value?: number;
+    currency?: string;
+    params?: Record<string, unknown>;
+};
+type ExposureBeacon = BeaconCommon<'exposure'> & Exposure;
+
+type Visitor = {
+    id: string;
+    /** Whether the visitor had a cookie already: `recurring` on the server. */
+    recurring: boolean;
+};
+
+type AutoTrackOptions = {
+    /** A page view now and on every client-side navigation. Default on. */
+    pageViews?: boolean;
+    /**
+     * A `click` event, scoped to the id, for every click on or inside an
+     * element with `data-numbers-id="…"`. Default on.
+     */
+    clicks?: boolean;
+};
+/** What a send resolves to: the response, or nothing when it failed. */
+type Sent = Promise<Response | undefined>;
+type NumbersClient = {
+    readonly organizationId: string;
+    readonly environment: Environment;
+    /** The visitor, from the cookie or new. `null` outside the browser. */
+    visitor: () => Visitor | null;
+    /** Replaces the device categories, e.g. from a fuller user-agent parser. */
+    setDevice: (device: Device) => void;
+    setEndpoint: (endpoint: string) => void;
+    /**
+     * Sends an event. `scope` is the stable second half of its identity, e.g.
+     * `'homepage_hero_signup'` (default: the page's path). `null` when nothing
+     * was sent: outside the browser, deduplicated, or paused after a 429.
+     */
+    track: (event: EventName, scope?: string, options?: TrackOptions) => Sent | null;
+    /** Sends a page view of the current page. */
+    pageView: () => Sent | null;
+    /** Sends a test's or flag's assignment, once per subject per client. */
+    expose: (exposure: Exposure) => Sent | null;
+    /** Starts page views and click tracking; returns a function that stops them. */
+    autoTrack: (options?: AutoTrackOptions) => () => void;
+};
+declare const createNumbers: ({ organizationId, environment, endpoint, device: givenDevice, disableWarnings, }: NumbersOptions) => NumbersClient;
+
+declare const DEFAULT_ENDPOINT = "https://numbers.obelism.studio/api/log";
+
+declare const detectDevice: (userAgent: string) => Device;
+
+export { DEFAULT_ENDPOINT, createNumbers, detectDevice };
+export type { AutoTrackOptions, BeaconCommon, Device, Environment, EventBeacon, EventName, Exposure, ExposureBeacon, NumbersClient, NumbersOptions, PageContext, RecommendedEventName, Sent, TrackOptions, Visitor };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sources":["../src/types.ts","../src/visitor.ts","../src/client.ts","../src/constants.ts","../src/device.ts"],"mappings":"AAAA,KAAK,WAAW;AAChB;AACA;AACA;AACA;AACA;AACA,KAAK,MAAM;AACX;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB;AACA;AACA,kBAAkB,WAAW;AAC7B;AACA;AACA;AACA;AACA;AACA;AACA,aAAa,MAAM;AACnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,oBAAoB;AACzB;AACA,KAAK,SAAS,GAAG,oBAAoB;AACrC,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA,aAAa,MAAM;AACnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,QAAQ;AACb;AACA;AACA;AACA;AACA;AACA,KAAK,YAAY;AACjB;AACA;AACA,iBAAiB,WAAW;AAC5B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,WAAW;AAChB;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,WAAW,GAAG,YAAY,YAAY,WAAW;AACtD;AACA;AACA;AACA;AACA,aAAa,MAAM;AACnB;AACA,KAAK,cAAc,GAAG,YAAY,eAAe,QAAQ;;ACtFzD,KAAK,OAAO;AACZ;AACA;AACA;AACA;;ACFA,KAAK,gBAAgB;AACrB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,IAAI,GAAG,OAAO,CAAC,QAAQ;AAC5B,KAAK,aAAa;AAClB;AACA,0BAA0B,WAAW;AACrC;AACA,mBAAmB,OAAO;AAC1B;AACA,wBAAwB,MAAM;AAC9B;AACA;AACA;AACA;AACA;AACA;AACA,mBAAmB,SAAS,4BAA4B,YAAY,KAAK,IAAI;AAC7E;AACA,oBAAoB,IAAI;AACxB;AACA,uBAAuB,QAAQ,KAAK,IAAI;AACxC;AACA,0BAA0B,gBAAgB;AAC1C;AACA,cAAc,aAAa,qFAAqF,cAAc,KAAK,aAAa;;AClChJ,cAAc,gBAAgB;;ACC9B,cAAc,YAAY,yBAAyB,MAAM;;","names":[]}

package/dist/index.js

@@ -0,0 +1,278 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const DEFAULT_ENDPOINT = 'https://numbers.obelism.studio/api/log';
+// The visitor cookie and id format, shared with the improve SDK so a visitor
+// is the same one in both: `visi_` and 26 characters.
+const VISITOR_COOKIE = 'visitorId';
+const VISITOR_ID_PREFIX = 'visi';
+const VISITOR_ID_SEPARATOR = '_';
+const VISITOR_ID_LENGTH = 26;
+const VISITOR_COOKIE_DAYS = 30;
+// numbers' limits (`POST /api/log`): a longer string is a 400 and a bigger
+// body a 413, and either loses the event, so the client caps what it can.
+const MAX_FIELD_LENGTH = 256;
+const MAX_CURRENCY_LENGTH = 8;
+const MAX_URL_LENGTH = 1024;
+const MAX_BODY_BYTES = 8 * 1024;
+// How long to stop sending after a 429 without a `Retry-After`.
+const RATE_LIMIT_COOLDOWN_MS = 60_000;
+
+// improve's audience categories from the user agent, the short version
+// (improve's SDK uses ua-parser-js; pass its result as `device` to match it
+// exactly).
+const detectDevice = (userAgent)=>{
+    const ua = userAgent.toLowerCase();
+    const device = /ipad|tablet|android(?!.*mobile)/.test(ua) ? 'tablet' : /mobi|iphone|ipod|android/.test(ua) ? 'mobile' : 'desktop';
+    const browser = /edg\//.test(ua) ? 'edge' : /samsungbrowser/.test(ua) ? 'samsung internet' : /instagram|fban|fbav|tiktok|snapchat|wechat|line\//.test(ua) ? 'social' : /firefox|fxios/.test(ua) ? 'firefox' : /chrome|crios|chromium/.test(ua) ? 'chrome' : /safari/.test(ua) ? 'safari' : 'other';
+    const os = /iphone|ipad|ipod/.test(ua) ? 'ios' : /android/.test(ua) ? 'android' : /windows/.test(ua) ? 'windows' : /mac os/.test(ua) ? 'mac os' : 'unix';
+    return {
+        pointer: device === 'desktop' ? 'fine' : 'coarse',
+        device,
+        browser,
+        os
+    };
+};
+const getScreenSize = ()=>{
+    const width = window.innerWidth;
+    if (width <= 768) return 'small';
+    if (width <= 1024) return 'medium';
+    if (width <= 1200) return 'large';
+    return 'huge';
+};
+
+const utm = (params, name)=>params.get(name)?.slice(0, MAX_FIELD_LENGTH) || undefined;
+// The page now: its path (without the query string, which numbers drops too)
+// and the UTM tags.
+const getPageContext = ()=>{
+    const params = new URLSearchParams(location.search);
+    const context = {
+        path: location.pathname.slice(0, MAX_URL_LENGTH)
+    };
+    const utmSource = utm(params, 'utm_source');
+    const utmMedium = utm(params, 'utm_medium');
+    const utmCampaign = utm(params, 'utm_campaign');
+    if (utmSource) context.utmSource = utmSource;
+    if (utmMedium) context.utmMedium = utmMedium;
+    if (utmCampaign) context.utmCampaign = utmCampaign;
+    return context;
+};
+// Where the visit came from: another site's origin and path, never this
+// site's own pages or a query string.
+const getExternalReferrer = ()=>{
+    if (!document.referrer) return undefined;
+    try {
+        const referrer = new URL(document.referrer);
+        if (referrer.host === location.host) return undefined;
+        return `${referrer.origin}${referrer.pathname}`.slice(0, MAX_URL_LENGTH);
+    } catch  {
+        return undefined;
+    }
+};
+
+const CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+const readCookie = (name)=>{
+    const row = document.cookie.split('; ').find((entry)=>entry.split('=')[0] === name);
+    return row ? row.split('=')[1] ?? '' : '';
+};
+const writeCookie = (name, value)=>{
+    const expires = new Date(Date.now() + VISITOR_COOKIE_DAYS * 86_400_000);
+    document.cookie = `${name}=${value};path=/;expires=${expires.toUTCString()};SameSite=Lax` + (location.protocol === 'https:' ? ';Secure' : '');
+};
+// The improve SDK's check, so an id it (or its middleware) made stays valid.
+const isVisitorId = (value)=>{
+    const parts = value.split(VISITOR_ID_SEPARATOR);
+    return parts.length === 2 && parts[0] === VISITOR_ID_PREFIX && parts[1].length === VISITOR_ID_LENGTH;
+};
+const createVisitorId = ()=>{
+    const random = new Uint8Array(VISITOR_ID_LENGTH);
+    crypto.getRandomValues(random);
+    let id = '';
+    for (const byte of random)id += CHARACTERS[byte % CHARACTERS.length];
+    return `${VISITOR_ID_PREFIX}${VISITOR_ID_SEPARATOR}${id}`;
+};
+// The visitor in the cookie, or a new one; either way the cookie is set
+// again, so it lasts 30 days from the last visit.
+const loadVisitor = ()=>{
+    const existing = readCookie(VISITOR_COOKIE);
+    const recurring = isVisitorId(existing);
+    const id = recurring ? existing : createVisitorId();
+    writeCookie(VISITOR_COOKIE, id);
+    return {
+        id,
+        recurring
+    };
+};
+
+const SNAKE_CASE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+const parseRetryAfterMs = (header)=>{
+    if (!header) return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+};
+const isBrowser = ()=>typeof window !== 'undefined' && typeof document !== 'undefined';
+const createNumbers = ({ organizationId, environment = 'production', endpoint = DEFAULT_ENDPOINT, device: givenDevice, disableWarnings = false })=>{
+    let visitor = null;
+    let device = givenDevice;
+    let url = endpoint;
+    // Epoch ms until which sending is paused after a 429.
+    let pausedUntil = 0;
+    let firstPageView = true;
+    const sentKeys = new Set();
+    const exposed = new Set();
+    const warned = new Set();
+    const warn = (key, message)=>{
+        if (disableWarnings || warned.has(key)) return;
+        warned.add(key);
+        if (typeof console !== 'undefined') console.warn(`[numbers] ${message}`);
+    };
+    const getVisitor = ()=>{
+        if (!isBrowser()) return null;
+        visitor ??= loadVisitor();
+        return visitor;
+    };
+    const common = (type, current)=>{
+        device ??= detectDevice(navigator.userAgent);
+        return {
+            type,
+            organizationId,
+            environment,
+            visitorId: current.id,
+            pointer: device.pointer,
+            device: device.device,
+            screen: getScreenSize(),
+            browser: device.browser,
+            os: device.os,
+            visitor: current.recurring ? 'recurring' : 'new'
+        };
+    };
+    // A `keepalive` fetch, so it outlives a navigation. Never rejects.
+    const send = (body, label)=>{
+        const serialized = JSON.stringify(body);
+        if (typeof TextEncoder !== 'undefined' && new TextEncoder().encode(serialized).length > MAX_BODY_BYTES) warn(`size:${label}`, `"${label}" is over ${MAX_BODY_BYTES} bytes and will be refused: trim its \`params\`.`);
+        return fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: serialized,
+            keepalive: true
+        }).then((response)=>{
+            // Over the Organization's limit: back off, by Retry-After when given.
+            if (response.status === 429) pausedUntil = Date.now() + (parseRetryAfterMs(response.headers.get('Retry-After')) ?? RATE_LIMIT_COOLDOWN_MS);
+            return response;
+        }, ()=>undefined);
+    };
+    const paused = ()=>Date.now() < pausedUntil;
+    const sendEvent = (event, scope, options, referrer)=>{
+        const current = getVisitor();
+        if (!current || paused()) return null;
+        const { value, currency, params, dedupeKey } = options;
+        if (dedupeKey !== undefined) {
+            const key = `${event}:${dedupeKey}`;
+            if (sentKeys.has(key)) return null;
+            sentKeys.add(key);
+        }
+        const body = {
+            ...common('event', current),
+            ...getPageContext(),
+            event: event.slice(0, MAX_FIELD_LENGTH),
+            scope: scope.slice(0, MAX_FIELD_LENGTH)
+        };
+        if (referrer) body.referrer = referrer;
+        if (typeof value === 'number' && Number.isFinite(value)) body.value = value;
+        if (currency) body.currency = currency.slice(0, MAX_CURRENCY_LENGTH);
+        // numbers refuses `params` that aren't a plain object, and the event
+        // with it: leave them out instead.
+        if (params && typeof params === 'object' && !Array.isArray(params)) body.params = params;
+        return send(body, event);
+    };
+    const track = (event, scope, options = {})=>{
+        if (!isBrowser()) return null;
+        if (!SNAKE_CASE.test(event)) warn(`name:${event}`, `"${event}" isn't snake_case. Prefer GA4-style names like "add_to_cart" or "sign_up"; \`disableWarnings: true\` silences this.`);
+        return sendEvent(event, scope || location.pathname, options);
+    };
+    const pageView = ()=>{
+        if (!isBrowser()) return null;
+        // Where the visit came from belongs to its first page view only.
+        const referrer = firstPageView ? getExternalReferrer() : undefined;
+        firstPageView = false;
+        return sendEvent('page_view', location.pathname, {}, referrer);
+    };
+    const expose = (exposure)=>{
+        const current = getVisitor();
+        if (!current || paused()) return null;
+        const key = `${exposure.subjectKind}:${exposure.subjectId}`;
+        if (exposed.has(key)) return null;
+        exposed.add(key);
+        return send({
+            ...common('exposure', current),
+            ...exposure
+        }, key);
+    };
+    const autoTrack = ({ pageViews = true, clicks = true } = {})=>{
+        if (!isBrowser()) return ()=>{};
+        const stops = [];
+        if (pageViews) {
+            // One page view per path: replaceState for a query or hash change
+            // isn't a new page.
+            let lastPath = null;
+            const onNavigate = ()=>{
+                if (location.pathname === lastPath) return;
+                lastPath = location.pathname;
+                pageView();
+            };
+            const wrap = (name)=>{
+                const original = history[name];
+                const wrapped = function(...args) {
+                    const result = original.apply(this, args);
+                    onNavigate();
+                    return result;
+                };
+                history[name] = wrapped;
+                stops.push(()=>{
+                    // Leave a wrapper someone added after ours in place.
+                    if (history[name] === wrapped) history[name] = original;
+                });
+            };
+            wrap('pushState');
+            wrap('replaceState');
+            window.addEventListener('popstate', onNavigate);
+            stops.push(()=>window.removeEventListener('popstate', onNavigate));
+            onNavigate();
+        }
+        if (clicks) {
+            // Captured, so a handler that stops the click still counts it.
+            const onClick = (event)=>{
+                const target = event.target;
+                const id = target?.closest?.('[data-numbers-id]')?.getAttribute('data-numbers-id');
+                if (id) track('click', id);
+            };
+            document.addEventListener('click', onClick, true);
+            stops.push(()=>document.removeEventListener('click', onClick, true));
+        }
+        return ()=>{
+            for (const stop of stops)stop();
+        };
+    };
+    return {
+        organizationId,
+        environment,
+        visitor: getVisitor,
+        setDevice: (next)=>{
+            device = next;
+        },
+        setEndpoint: (next)=>{
+            url = next;
+        },
+        track,
+        pageView,
+        expose,
+        autoTrack
+    };
+};
+
+exports.DEFAULT_ENDPOINT = DEFAULT_ENDPOINT;
+exports.createNumbers = createNumbers;
+exports.detectDevice = detectDevice;

package/dist/index.mjs

@@ -0,0 +1,274 @@
+const DEFAULT_ENDPOINT = 'https://numbers.obelism.studio/api/log';
+// The visitor cookie and id format, shared with the improve SDK so a visitor
+// is the same one in both: `visi_` and 26 characters.
+const VISITOR_COOKIE = 'visitorId';
+const VISITOR_ID_PREFIX = 'visi';
+const VISITOR_ID_SEPARATOR = '_';
+const VISITOR_ID_LENGTH = 26;
+const VISITOR_COOKIE_DAYS = 30;
+// numbers' limits (`POST /api/log`): a longer string is a 400 and a bigger
+// body a 413, and either loses the event, so the client caps what it can.
+const MAX_FIELD_LENGTH = 256;
+const MAX_CURRENCY_LENGTH = 8;
+const MAX_URL_LENGTH = 1024;
+const MAX_BODY_BYTES = 8 * 1024;
+// How long to stop sending after a 429 without a `Retry-After`.
+const RATE_LIMIT_COOLDOWN_MS = 60_000;
+
+// improve's audience categories from the user agent, the short version
+// (improve's SDK uses ua-parser-js; pass its result as `device` to match it
+// exactly).
+const detectDevice = (userAgent)=>{
+    const ua = userAgent.toLowerCase();
+    const device = /ipad|tablet|android(?!.*mobile)/.test(ua) ? 'tablet' : /mobi|iphone|ipod|android/.test(ua) ? 'mobile' : 'desktop';
+    const browser = /edg\//.test(ua) ? 'edge' : /samsungbrowser/.test(ua) ? 'samsung internet' : /instagram|fban|fbav|tiktok|snapchat|wechat|line\//.test(ua) ? 'social' : /firefox|fxios/.test(ua) ? 'firefox' : /chrome|crios|chromium/.test(ua) ? 'chrome' : /safari/.test(ua) ? 'safari' : 'other';
+    const os = /iphone|ipad|ipod/.test(ua) ? 'ios' : /android/.test(ua) ? 'android' : /windows/.test(ua) ? 'windows' : /mac os/.test(ua) ? 'mac os' : 'unix';
+    return {
+        pointer: device === 'desktop' ? 'fine' : 'coarse',
+        device,
+        browser,
+        os
+    };
+};
+const getScreenSize = ()=>{
+    const width = window.innerWidth;
+    if (width <= 768) return 'small';
+    if (width <= 1024) return 'medium';
+    if (width <= 1200) return 'large';
+    return 'huge';
+};
+
+const utm = (params, name)=>params.get(name)?.slice(0, MAX_FIELD_LENGTH) || undefined;
+// The page now: its path (without the query string, which numbers drops too)
+// and the UTM tags.
+const getPageContext = ()=>{
+    const params = new URLSearchParams(location.search);
+    const context = {
+        path: location.pathname.slice(0, MAX_URL_LENGTH)
+    };
+    const utmSource = utm(params, 'utm_source');
+    const utmMedium = utm(params, 'utm_medium');
+    const utmCampaign = utm(params, 'utm_campaign');
+    if (utmSource) context.utmSource = utmSource;
+    if (utmMedium) context.utmMedium = utmMedium;
+    if (utmCampaign) context.utmCampaign = utmCampaign;
+    return context;
+};
+// Where the visit came from: another site's origin and path, never this
+// site's own pages or a query string.
+const getExternalReferrer = ()=>{
+    if (!document.referrer) return undefined;
+    try {
+        const referrer = new URL(document.referrer);
+        if (referrer.host === location.host) return undefined;
+        return `${referrer.origin}${referrer.pathname}`.slice(0, MAX_URL_LENGTH);
+    } catch  {
+        return undefined;
+    }
+};
+
+const CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+const readCookie = (name)=>{
+    const row = document.cookie.split('; ').find((entry)=>entry.split('=')[0] === name);
+    return row ? row.split('=')[1] ?? '' : '';
+};
+const writeCookie = (name, value)=>{
+    const expires = new Date(Date.now() + VISITOR_COOKIE_DAYS * 86_400_000);
+    document.cookie = `${name}=${value};path=/;expires=${expires.toUTCString()};SameSite=Lax` + (location.protocol === 'https:' ? ';Secure' : '');
+};
+// The improve SDK's check, so an id it (or its middleware) made stays valid.
+const isVisitorId = (value)=>{
+    const parts = value.split(VISITOR_ID_SEPARATOR);
+    return parts.length === 2 && parts[0] === VISITOR_ID_PREFIX && parts[1].length === VISITOR_ID_LENGTH;
+};
+const createVisitorId = ()=>{
+    const random = new Uint8Array(VISITOR_ID_LENGTH);
+    crypto.getRandomValues(random);
+    let id = '';
+    for (const byte of random)id += CHARACTERS[byte % CHARACTERS.length];
+    return `${VISITOR_ID_PREFIX}${VISITOR_ID_SEPARATOR}${id}`;
+};
+// The visitor in the cookie, or a new one; either way the cookie is set
+// again, so it lasts 30 days from the last visit.
+const loadVisitor = ()=>{
+    const existing = readCookie(VISITOR_COOKIE);
+    const recurring = isVisitorId(existing);
+    const id = recurring ? existing : createVisitorId();
+    writeCookie(VISITOR_COOKIE, id);
+    return {
+        id,
+        recurring
+    };
+};
+
+const SNAKE_CASE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+const parseRetryAfterMs = (header)=>{
+    if (!header) return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+};
+const isBrowser = ()=>typeof window !== 'undefined' && typeof document !== 'undefined';
+const createNumbers = ({ organizationId, environment = 'production', endpoint = DEFAULT_ENDPOINT, device: givenDevice, disableWarnings = false })=>{
+    let visitor = null;
+    let device = givenDevice;
+    let url = endpoint;
+    // Epoch ms until which sending is paused after a 429.
+    let pausedUntil = 0;
+    let firstPageView = true;
+    const sentKeys = new Set();
+    const exposed = new Set();
+    const warned = new Set();
+    const warn = (key, message)=>{
+        if (disableWarnings || warned.has(key)) return;
+        warned.add(key);
+        if (typeof console !== 'undefined') console.warn(`[numbers] ${message}`);
+    };
+    const getVisitor = ()=>{
+        if (!isBrowser()) return null;
+        visitor ??= loadVisitor();
+        return visitor;
+    };
+    const common = (type, current)=>{
+        device ??= detectDevice(navigator.userAgent);
+        return {
+            type,
+            organizationId,
+            environment,
+            visitorId: current.id,
+            pointer: device.pointer,
+            device: device.device,
+            screen: getScreenSize(),
+            browser: device.browser,
+            os: device.os,
+            visitor: current.recurring ? 'recurring' : 'new'
+        };
+    };
+    // A `keepalive` fetch, so it outlives a navigation. Never rejects.
+    const send = (body, label)=>{
+        const serialized = JSON.stringify(body);
+        if (typeof TextEncoder !== 'undefined' && new TextEncoder().encode(serialized).length > MAX_BODY_BYTES) warn(`size:${label}`, `"${label}" is over ${MAX_BODY_BYTES} bytes and will be refused: trim its \`params\`.`);
+        return fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: serialized,
+            keepalive: true
+        }).then((response)=>{
+            // Over the Organization's limit: back off, by Retry-After when given.
+            if (response.status === 429) pausedUntil = Date.now() + (parseRetryAfterMs(response.headers.get('Retry-After')) ?? RATE_LIMIT_COOLDOWN_MS);
+            return response;
+        }, ()=>undefined);
+    };
+    const paused = ()=>Date.now() < pausedUntil;
+    const sendEvent = (event, scope, options, referrer)=>{
+        const current = getVisitor();
+        if (!current || paused()) return null;
+        const { value, currency, params, dedupeKey } = options;
+        if (dedupeKey !== undefined) {
+            const key = `${event}:${dedupeKey}`;
+            if (sentKeys.has(key)) return null;
+            sentKeys.add(key);
+        }
+        const body = {
+            ...common('event', current),
+            ...getPageContext(),
+            event: event.slice(0, MAX_FIELD_LENGTH),
+            scope: scope.slice(0, MAX_FIELD_LENGTH)
+        };
+        if (referrer) body.referrer = referrer;
+        if (typeof value === 'number' && Number.isFinite(value)) body.value = value;
+        if (currency) body.currency = currency.slice(0, MAX_CURRENCY_LENGTH);
+        // numbers refuses `params` that aren't a plain object, and the event
+        // with it: leave them out instead.
+        if (params && typeof params === 'object' && !Array.isArray(params)) body.params = params;
+        return send(body, event);
+    };
+    const track = (event, scope, options = {})=>{
+        if (!isBrowser()) return null;
+        if (!SNAKE_CASE.test(event)) warn(`name:${event}`, `"${event}" isn't snake_case. Prefer GA4-style names like "add_to_cart" or "sign_up"; \`disableWarnings: true\` silences this.`);
+        return sendEvent(event, scope || location.pathname, options);
+    };
+    const pageView = ()=>{
+        if (!isBrowser()) return null;
+        // Where the visit came from belongs to its first page view only.
+        const referrer = firstPageView ? getExternalReferrer() : undefined;
+        firstPageView = false;
+        return sendEvent('page_view', location.pathname, {}, referrer);
+    };
+    const expose = (exposure)=>{
+        const current = getVisitor();
+        if (!current || paused()) return null;
+        const key = `${exposure.subjectKind}:${exposure.subjectId}`;
+        if (exposed.has(key)) return null;
+        exposed.add(key);
+        return send({
+            ...common('exposure', current),
+            ...exposure
+        }, key);
+    };
+    const autoTrack = ({ pageViews = true, clicks = true } = {})=>{
+        if (!isBrowser()) return ()=>{};
+        const stops = [];
+        if (pageViews) {
+            // One page view per path: replaceState for a query or hash change
+            // isn't a new page.
+            let lastPath = null;
+            const onNavigate = ()=>{
+                if (location.pathname === lastPath) return;
+                lastPath = location.pathname;
+                pageView();
+            };
+            const wrap = (name)=>{
+                const original = history[name];
+                const wrapped = function(...args) {
+                    const result = original.apply(this, args);
+                    onNavigate();
+                    return result;
+                };
+                history[name] = wrapped;
+                stops.push(()=>{
+                    // Leave a wrapper someone added after ours in place.
+                    if (history[name] === wrapped) history[name] = original;
+                });
+            };
+            wrap('pushState');
+            wrap('replaceState');
+            window.addEventListener('popstate', onNavigate);
+            stops.push(()=>window.removeEventListener('popstate', onNavigate));
+            onNavigate();
+        }
+        if (clicks) {
+            // Captured, so a handler that stops the click still counts it.
+            const onClick = (event)=>{
+                const target = event.target;
+                const id = target?.closest?.('[data-numbers-id]')?.getAttribute('data-numbers-id');
+                if (id) track('click', id);
+            };
+            document.addEventListener('click', onClick, true);
+            stops.push(()=>document.removeEventListener('click', onClick, true));
+        }
+        return ()=>{
+            for (const stop of stops)stop();
+        };
+    };
+    return {
+        organizationId,
+        environment,
+        visitor: getVisitor,
+        setDevice: (next)=>{
+            device = next;
+        },
+        setEndpoint: (next)=>{
+            url = next;
+        },
+        track,
+        pageView,
+        expose,
+        autoTrack
+    };
+};
+
+export { DEFAULT_ENDPOINT, createNumbers, detectDevice };

package/dist/script.global.js

@@ -0,0 +1 @@
+!/*! Obelism numbers (@obelism/numbers-sdk), MIT. https://numbers.obelism.studio */function(){"use strict";let e="https://numbers.obelism.studio/api/log",t="visitorId",r="visi",n=(e,t)=>e.get(t)?.slice(0,256)||void 0,i="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",o=/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,a=()=>"u">typeof window&&"u">typeof document;((s,l)=>{if(!l||s.numbers)return;let u=l.dataset.organization;if(!u)return;let c=(({organizationId:s,environment:l="production",endpoint:u=e,device:c,disableWarnings:d=!1})=>{let p=null,m=c,h=u,f=0,w=!0,b=new Set,g=new Set,v=new Set,y=(e,t)=>{!(d||v.has(e))&&(v.add(e),"u">typeof console&&console.warn(`[numbers] ${t}`))},$=()=>a()?(p??(p=(()=>{let e,n,o,a=(e=document.cookie.split("; ").find(e=>e.split("=")[0]===t))?e.split("=")[1]??"":"",s=2===(n=a.split("_")).length&&n[0]===r&&26===n[1].length,l=s?a:(()=>{let e=new Uint8Array(26);crypto.getRandomValues(e);let t="";for(let r of e)t+=i[r%i.length];return`${r}_${t}`})();return o=new Date(Date.now()+2592e6),document.cookie=`${t}=${l};path=/;expires=${o.toUTCString()};SameSite=Lax`+("https:"===location.protocol?";Secure":""),{id:l,recurring:s}})()),p):null,S=(e,t)=>{let r,n,i;return m??(r=navigator.userAgent.toLowerCase(),n=/ipad|tablet|android(?!.*mobile)/.test(r)?"tablet":/mobi|iphone|ipod|android/.test(r)?"mobile":"desktop",m={pointer:"desktop"===n?"fine":"coarse",device:n,browser:/edg\//.test(r)?"edge":/samsungbrowser/.test(r)?"samsung internet":/instagram|fban|fbav|tiktok|snapchat|wechat|line\//.test(r)?"social":/firefox|fxios/.test(r)?"firefox":/chrome|crios|chromium/.test(r)?"chrome":/safari/.test(r)?"safari":"other",os:/iphone|ipad|ipod/.test(r)?"ios":/android/.test(r)?"android":/windows/.test(r)?"windows":/mac os/.test(r)?"mac os":"unix"}),{type:e,organizationId:s,environment:l,visitorId:t.id,pointer:m.pointer,device:m.device,screen:(i=window.innerWidth)<=768?"small":i<=1024?"medium":i<=1200?"large":"huge",browser:m.browser,os:m.os,visitor:t.recurring?"recurring":"new"}},k=(e,t)=>{let r=JSON.stringify(e);return"u">typeof TextEncoder&&new TextEncoder().encode(r).length>8192&&y(`size:${t}`,`"${t}" is over 8192 bytes and will be refused: trim its \`params\`.`),fetch(h,{method:"POST",headers:{"Content-Type":"application/json"},body:r,keepalive:!0}).then(e=>(429===e.status&&(f=Date.now()+((e=>{if(!e)return;let t=Number(e);if(Number.isFinite(t))return Math.max(0,1e3*t);let r=Date.parse(e);return Number.isNaN(r)?void 0:Math.max(0,r-Date.now())})(e.headers.get("Retry-After"))??6e4)),e),()=>void 0)},x=(e,t,r,i)=>{let o,a,s,l,u,c=$();if(!c||Date.now()<f)return null;let{value:d,currency:p,params:m,dedupeKey:h}=r;if(void 0!==h){let t=`${e}:${h}`;if(b.has(t))return null;b.add(t)}let w={...S("event",c),...(o=new URLSearchParams(location.search),a={path:location.pathname.slice(0,1024)},s=n(o,"utm_source"),l=n(o,"utm_medium"),u=n(o,"utm_campaign"),s&&(a.utmSource=s),l&&(a.utmMedium=l),u&&(a.utmCampaign=u),a),event:e.slice(0,256),scope:t.slice(0,256)};return i&&(w.referrer=i),"number"==typeof d&&Number.isFinite(d)&&(w.value=d),p&&(w.currency=p.slice(0,8)),m&&"object"==typeof m&&!Array.isArray(m)&&(w.params=m),k(w,e)},_=(e,t,r={})=>a()?(o.test(e)||y(`name:${e}`,`"${e}" isn't snake_case. Prefer GA4-style names like "add_to_cart" or "sign_up"; \`disableWarnings: true\` silences this.`),x(e,t||location.pathname,r)):null,L=()=>{if(!a())return null;let e=w?(()=>{if(document.referrer)try{let e=new URL(document.referrer);if(e.host===location.host)return;return`${e.origin}${e.pathname}`.slice(0,1024)}catch{return}})():void 0;return w=!1,x("page_view",location.pathname,{},e)};return{organizationId:s,environment:l,visitor:$,setDevice:e=>{m=e},setEndpoint:e=>{h=e},track:_,pageView:L,expose:e=>{let t=$();if(!t||Date.now()<f)return null;let r=`${e.subjectKind}:${e.subjectId}`;return g.has(r)?null:(g.add(r),k({...S("exposure",t),...e},r))},autoTrack:({pageViews:e=!0,clicks:t=!0}={})=>{if(!a())return()=>{};let r=[];if(e){let e=null,t=()=>{location.pathname!==e&&(e=location.pathname,L())},n=e=>{let n=history[e],i=function(...e){let r=n.apply(this,e);return t(),r};history[e]=i,r.push(()=>{history[e]===i&&(history[e]=n)})};n("pushState"),n("replaceState"),window.addEventListener("popstate",t),r.push(()=>window.removeEventListener("popstate",t)),t()}if(t){let e=e=>{let t=e.target,r=t?.closest?.("[data-numbers-id]")?.getAttribute("data-numbers-id");r&&_("click",r)};document.addEventListener("click",e,!0),r.push(()=>document.removeEventListener("click",e,!0))}return()=>{for(let e of r)e()}}}})({organizationId:u,environment:l.dataset.environment||"production",endpoint:l.dataset.endpoint||new URL("/api/log",l.src||location.href).href,disableWarnings:!0});return s.numbers=c,c.autoTrack()})(window,document.currentScript)}();

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@obelism/numbers-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@obelism/numbers-sdk",
+	"description": "Obelism numbers SDK: page views, events and clicks on tagged elements, sent to numbers.obelism.studio",
+	"version": "0.1.0",
+	"keywords": [
+		"analytics",
+		"events",
+		"page-views",
+		"typescript",
+		"obelism"
+	],
+	"license": "MIT",
+	"author": "Obelism <hello@obelism.studio> (https://www.obelism.studio)",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Obelism/sdk",
+		"directory": "packages/numbers"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			}
+		}
+	},
+	"scripts": {
+		"build": "bunchee && rollup --config rollup.script.config.mjs",
+		"dev": "bunchee --watch --no-clean",
+		"test": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"test:ci": "vitest run",
+		"lint": "npm-run-all --parallel lint:*",
+		"lint:oxlint": "oxlint",
+		"lint:types": "tsc --noEmit",
+		"clean": "rm -rf ./node_modules && rm -rf ./dist && rm -rf ./.turbo"
+	},
+	"devDependencies": {
+		"@obelism/sdk-typescript-config": "^0.0.0",
+		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@typescript/typescript6": "^6.0.2",
+		"bunchee": "^7.0.2",
+		"jsdom": "^30.1.2",
+		"npm-run-all2": "^9.0.2",
+		"oxlint": "^1.88.0",
+		"rollup": "^4.64.7",
+		"rollup-plugin-swc3": "^0.12.1",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.4"
+	},
+	"engines": {
+		"node": ">=20"
+	}
+}