@shware/analytics 8.8.0 → 8.10.0

package/README.md

@@ -60,6 +60,40 @@ changes. The framework `Analytics` components wire this up.
 - /analytics/tracks: track events
 - /analytics/visitor: app visitors
 
+## Sessions and attribution
+
+How the events this SDK sends are meant to be read on the server side, for attribution. Three
+layers, each derived from the one below it, none needing a table of its own:
+
+- **Session** — `event where name = 'session_start'`. The SDK opens a session after 30 minutes
+  without an event and sends exactly one `session_start` at the head of the batch that opened it,
+  carrying the tags of the event that opened it: the landing page's URL, utm parameters and click
+  ids, captured when that event happened rather than when the batch went out. A partial unique
+  index on `event (session_id) where name = 'session_start'` makes that row the session's one
+  record on the server; there is no session table.
+- **Touchpoint** — a view over those rows that reads each session's tags as `channel`, `medium`
+  and `campaign`. An explicit `utm_source` wins; then a click id (`fbclid`, `gclid`, … — one a
+  first-party cookie may carry over from an earlier click); then a landing page reserved for one
+  channel's ads. The rules for what counts as which channel live here and nowhere else.
+- **Attribution** — a view over touchpoints that credits a session with no touch of its own to
+  the same person's most recent paid touch, across devices (visitors sharing a `user_id`), within a
+  window. Last paid touch, first touch and multi-touch are alternative models at this layer over
+  the same touchpoints.
+
+What the SDK guarantees for this to hold:
+
+- `session_start` is sent once per session, first in its batch, with the opening event's tags and
+  timestamp. If the server rejected that batch, it goes out again with the session's next batch
+  under the same session id; the server's unique index drops a duplicate should both land.
+- On native, the install referrer's `utm_*` are attached only on the launch that first resolves
+  the referrer, so a later session is a touch only when it actually arrived through something.
+- `session_id` is a client-generated uuidv7 persisted in `config.storage`, shared across tabs and
+  reloads. It is a grouping key, not an identity: event and visitor ids are the server's.
+- The person a visitor belongs to is the server's too: `visitor.distinct_id`, the visitor's own id
+  until someone signs in on it and the user's id from then on. The client never sends it;
+  `setVisitor` hands the server's value to the third-party user setters, and PostHog is identified
+  by it once a user is known.
+
 ## UTM params
 
 Typed as `UTMParams` (exported from `@shware/analytics`). Value unions follow the

package/dist/attribution/index.cjs

@@ -0,0 +1,274 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/attribution/index.ts
+/**
+* The vocabulary attribution is built from, shared by every product's `touchpoint` view and by the
+* dashboards that read it. Data only, no SQL: a product turns these into its view. What stays with
+* the product is its own hostnames (referrer exclusions) and its landing-page convention.
+*/
+/** A session that arrived through nothing we can name. GA's spelling, so dashboards read as GA. */
+const DIRECT_CHANNEL = "(direct)";
+/** The medium of a direct session. */
+const NO_MEDIUM = "(none)";
+/** The medium of a tagged link that named a source but no medium. */
+const MEDIUM_NOT_SET = "(not set)";
+/** The channels the rules below can name. A `utm_source` outside this list is its own channel. */
+const CHANNELS = [
+	"meta",
+	"google",
+	"dv360",
+	"microsoft",
+	"tiktok",
+	"reddit",
+	"linkedin",
+	"snapchat",
+	"x",
+	"kakao",
+	"yandex",
+	"yahoo",
+	"duckduckgo",
+	"baidu",
+	"ecosia",
+	"naver",
+	"brave",
+	"pinterest",
+	"youtube"
+];
+/** GA4's default channel groups, as identifiers; a dashboard maps them to display names. */
+const CHANNEL_GROUPS = [
+	"direct",
+	"paid_search",
+	"paid_social",
+	"paid_other",
+	"display",
+	"organic_search",
+	"organic_social",
+	"organic_video",
+	"referral",
+	"email",
+	"affiliate",
+	"unassigned"
+];
+/** `utm_source` spellings that mean the same channel: Meta's `{{site_source_name}}` values and the usual synonyms. */
+const SOURCE_ALIASES = {
+	fb: "meta",
+	ig: "meta",
+	an: "meta",
+	msg: "meta",
+	facebook: "meta",
+	instagram: "meta",
+	bing: "microsoft",
+	twitter: "x"
+};
+/**
+* Which click id belongs to which channel, in priority order. Every key is a field this SDK
+* collects (`AdvertisingInfo`); `fbp` and `rdt_uuid` are deliberately absent — they are pixel
+* browser ids, present with or without a click.
+*/
+const CLICK_ID_CHANNELS = [
+	["fbclid", "meta"],
+	["fbc", "meta"],
+	["gclid", "google"],
+	["gbraid", "google"],
+	["wbraid", "google"],
+	["gad_source", "google"],
+	["gad_campaignid", "google"],
+	["dclid", "dv360"],
+	["msclkid", "microsoft"],
+	["ttclid", "tiktok"],
+	["rdt_cid", "reddit"],
+	["li_fat_id", "linkedin"],
+	["sccid", "snapchat"],
+	["twclid", "x"],
+	["ko_click_id", "kakao"],
+	["yclid", "yandex"]
+];
+/**
+* A landing page reserved for one channel's ads, for ads that lost their parameters:
+* `/lp/<channel>`, with or without host, query and hash; the capture is the channel. A product
+* that names its landing pages differently replaces this.
+*/
+const AD_LANDING_PAGE = "^(?:https?://[^/]+)?/lp/([a-z]+)(?:[/?#]|$)";
+/**
+* Referrer hosts that name a channel, as POSIX regular expressions over the lower-cased host,
+* with the medium GA4 gives that kind of site. Anything else that refers is `referral`, kept as
+* its host. A country TLD is one or two labels (`google.com`, `google.co.uk`, `google.com.hk`),
+* never an open tail, so `google.com.evil.io` is not Google.
+*/
+const REFERRER_SITES = [
+	[
+		"google",
+		"organic",
+		String.raw`(^|\.)google\.[a-z]{2,}(\.[a-z]{2,3})?$`
+	],
+	[
+		"microsoft",
+		"organic",
+		String.raw`(^|\.)bing\.com$`
+	],
+	[
+		"yahoo",
+		"organic",
+		String.raw`(^|\.)yahoo\.[a-z]{2,}(\.[a-z]{2,3})?$`
+	],
+	[
+		"duckduckgo",
+		"organic",
+		String.raw`(^|\.)duckduckgo\.com$`
+	],
+	[
+		"baidu",
+		"organic",
+		String.raw`(^|\.)baidu\.com$`
+	],
+	[
+		"yandex",
+		"organic",
+		String.raw`(^|\.)yandex\.[a-z]{2,}(\.[a-z]{2,3})?$`
+	],
+	[
+		"ecosia",
+		"organic",
+		String.raw`(^|\.)ecosia\.org$`
+	],
+	[
+		"naver",
+		"organic",
+		String.raw`(^|\.)naver\.com$`
+	],
+	[
+		"brave",
+		"organic",
+		String.raw`^search\.brave\.com$`
+	],
+	[
+		"meta",
+		"social",
+		String.raw`(^|\.)(facebook\.com|instagram\.com|fb\.com|threads\.net)$`
+	],
+	[
+		"x",
+		"social",
+		String.raw`(^|\.)(twitter\.com|x\.com|t\.co)$`
+	],
+	[
+		"linkedin",
+		"social",
+		String.raw`(^|\.)(linkedin\.com|lnkd\.in)$`
+	],
+	[
+		"reddit",
+		"social",
+		String.raw`(^|\.)reddit\.com$`
+	],
+	[
+		"tiktok",
+		"social",
+		String.raw`(^|\.)tiktok\.com$`
+	],
+	[
+		"pinterest",
+		"social",
+		String.raw`(^|\.)pinterest\.[a-z]{2,}(\.[a-z]{2,3})?$`
+	],
+	[
+		"snapchat",
+		"social",
+		String.raw`(^|\.)snapchat\.com$`
+	],
+	[
+		"youtube",
+		"video",
+		String.raw`(^|\.)(youtube\.com|youtu\.be)$`
+	]
+];
+/**
+* Referrer hosts that are navigation, not acquisition: the payment and sign-in providers a
+* visitor is bounced through and back from, and the local dev host. A product appends its own
+* hostnames — a session that starts from an internal link after the session timeout refers to
+* them. POSIX regular expressions over the lower-cased host.
+*/
+const REFERRERS_NOT_A_TOUCH = [
+	String.raw`^localhost(:|$)`,
+	String.raw`(^|\.)stripe\.com$`,
+	String.raw`^(pay|accounts)\.google\.com$`,
+	String.raw`^(appleid|apps)\.apple\.com$`,
+	String.raw`^play\.google\.com$`,
+	String.raw`^login\.microsoftonline\.com$`
+];
+/** GA4's paid mediums: cpc, cpm, ppc, retargeting, paid_social, … */
+const PAID_MEDIUM = "^(.*cp.*|ppc|retargeting|paid.*)$";
+const DISPLAY_MEDIUMS = [
+	"display",
+	"banner",
+	"expandable",
+	"interstitial"
+];
+const EMAIL_MEDIUMS = [
+	"email",
+	"e-mail",
+	"e_mail",
+	"e mail"
+];
+/** Where a touch came from: a tracked session, or a report by the user or staff. */
+const TOUCH_SOURCES = ["tracked", "reported"];
+/**
+* How a reported touch was learned:
+* - survey: the user answered "how did you hear about us" (onboarding, checkout)
+* - promo_code: the user redeemed a code that belongs to a channel
+* - phone: a call came in on a channel's dedicated number, marked by staff or the phone system
+* - manual: staff recorded what a customer told them
+*/
+const REPORTED_TOUCH_KINDS = [
+	"survey",
+	"promo_code",
+	"phone",
+	"manual"
+];
+/**
+* How much a touch is worth against another when attribution has to choose between sessions;
+* lower wins, and the latest wins among equals. Derived in the views, never stored, so
+* renumbering is a view regeneration.
+*
+* This ranks touches against each other. Within one session the rules that name its channel have
+* their own order — `utm_source`, then a click id, then the ad landing page, then the referrer —
+* and the first that says something wins; the session's priority is then the tier of that rule.
+* So two sessions tagged with utm and gclid respectively are equal here (both `campaign`) and the
+* later one is credited, while one session carrying both is named by its utm.
+*/
+const TOUCH_PRIORITY = {
+	/** utm, click id, ad landing page: someone tagged that link (in that order within a session) */
+	campaign: 1,
+	/** a reported touch staff stand behind: a call on a channel's number, a recorded conversation */
+	verified: 1,
+	/** the browser said where the visitor came from; nobody chose it */
+	referrer: 2,
+	/** a reported touch that is the user's claim: a survey answer, a code that may have been shared */
+	claimed: 3
+};
+/** Which reported kinds are staff facts and which are the user's claims. */
+const REPORTED_TOUCH_PRIORITY = {
+	phone: TOUCH_PRIORITY.verified,
+	manual: TOUCH_PRIORITY.verified,
+	survey: TOUCH_PRIORITY.claimed,
+	promo_code: TOUCH_PRIORITY.claimed
+};
+//#endregion
+exports.AD_LANDING_PAGE = AD_LANDING_PAGE;
+exports.CHANNELS = CHANNELS;
+exports.CHANNEL_GROUPS = CHANNEL_GROUPS;
+exports.CLICK_ID_CHANNELS = CLICK_ID_CHANNELS;
+exports.DIRECT_CHANNEL = DIRECT_CHANNEL;
+exports.DISPLAY_MEDIUMS = DISPLAY_MEDIUMS;
+exports.EMAIL_MEDIUMS = EMAIL_MEDIUMS;
+exports.MEDIUM_NOT_SET = MEDIUM_NOT_SET;
+exports.NO_MEDIUM = NO_MEDIUM;
+exports.PAID_MEDIUM = PAID_MEDIUM;
+exports.REFERRERS_NOT_A_TOUCH = REFERRERS_NOT_A_TOUCH;
+exports.REFERRER_SITES = REFERRER_SITES;
+exports.REPORTED_TOUCH_KINDS = REPORTED_TOUCH_KINDS;
+exports.REPORTED_TOUCH_PRIORITY = REPORTED_TOUCH_PRIORITY;
+exports.SOURCE_ALIASES = SOURCE_ALIASES;
+exports.TOUCH_PRIORITY = TOUCH_PRIORITY;
+exports.TOUCH_SOURCES = TOUCH_SOURCES;
+
+//# sourceMappingURL=index.cjs.map

package/dist/attribution/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/attribution/index.ts"],"sourcesContent":["import type { AdvertisingInfo } from '../track/types';\n\n/**\n * The vocabulary attribution is built from, shared by every product's `touchpoint` view and by the\n * dashboards that read it. Data only, no SQL: a product turns these into its view. What stays with\n * the product is its own hostnames (referrer exclusions) and its landing-page convention.\n */\n\n/** A session that arrived through nothing we can name. GA's spelling, so dashboards read as GA. */\nexport const DIRECT_CHANNEL = '(direct)';\n/** The medium of a direct session. */\nexport const NO_MEDIUM = '(none)';\n/** The medium of a tagged link that named a source but no medium. */\nexport const MEDIUM_NOT_SET = '(not set)';\n\n/** The channels the rules below can name. A `utm_source` outside this list is its own channel. */\nexport const CHANNELS = [\n  'meta',\n  'google',\n  'dv360',\n  'microsoft',\n  'tiktok',\n  'reddit',\n  'linkedin',\n  'snapchat',\n  'x',\n  'kakao',\n  'yandex',\n  'yahoo',\n  'duckduckgo',\n  'baidu',\n  'ecosia',\n  'naver',\n  'brave',\n  'pinterest',\n  'youtube',\n] as const;\n\nexport type Channel = (typeof CHANNELS)[number];\n\n/** GA4's default channel groups, as identifiers; a dashboard maps them to display names. */\nexport const CHANNEL_GROUPS = [\n  'direct',\n  'paid_search',\n  'paid_social',\n  'paid_other',\n  'display',\n  'organic_search',\n  'organic_social',\n  'organic_video',\n  'referral',\n  'email',\n  'affiliate',\n  'unassigned',\n] as const;\n\nexport type ChannelGroup = (typeof CHANNEL_GROUPS)[number];\n\n/** `utm_source` spellings that mean the same channel: Meta's `{{site_source_name}}` values and the usual synonyms. */\nexport const SOURCE_ALIASES = {\n  fb: 'meta',\n  ig: 'meta',\n  an: 'meta',\n  msg: 'meta',\n  facebook: 'meta',\n  instagram: 'meta',\n  bing: 'microsoft',\n  twitter: 'x',\n} as const satisfies Record<string, Channel>;\n\n/**\n * Which click id belongs to which channel, in priority order. Every key is a field this SDK\n * collects (`AdvertisingInfo`); `fbp` and `rdt_uuid` are deliberately absent — they are pixel\n * browser ids, present with or without a click.\n */\nexport const CLICK_ID_CHANNELS = [\n  ['fbclid', 'meta'],\n  ['fbc', 'meta'],\n  ['gclid', 'google'],\n  ['gbraid', 'google'],\n  ['wbraid', 'google'],\n  ['gad_source', 'google'],\n  ['gad_campaignid', 'google'],\n  ['dclid', 'dv360'],\n  ['msclkid', 'microsoft'],\n  ['ttclid', 'tiktok'],\n  ['rdt_cid', 'reddit'],\n  ['li_fat_id', 'linkedin'],\n  ['sccid', 'snapchat'],\n  ['twclid', 'x'],\n  ['ko_click_id', 'kakao'],\n  ['yclid', 'yandex'],\n] as const satisfies readonly (readonly [keyof AdvertisingInfo, Channel])[];\n\n/**\n * A landing page reserved for one channel's ads, for ads that lost their parameters:\n * `/lp/<channel>`, with or without host, query and hash; the capture is the channel. A product\n * that names its landing pages differently replaces this.\n */\nexport const AD_LANDING_PAGE = '^(?:https?://[^/]+)?/lp/([a-z]+)(?:[/?#]|$)';\n\nexport type ReferrerMedium = 'organic' | 'social' | 'video';\n\n/**\n * Referrer hosts that name a channel, as POSIX regular expressions over the lower-cased host,\n * with the medium GA4 gives that kind of site. Anything else that refers is `referral`, kept as\n * its host. A country TLD is one or two labels (`google.com`, `google.co.uk`, `google.com.hk`),\n * never an open tail, so `google.com.evil.io` is not Google.\n */\nexport const REFERRER_SITES = [\n  ['google', 'organic', String.raw`(^|\\.)google\\.[a-z]{2,}(\\.[a-z]{2,3})?$`],\n  ['microsoft', 'organic', String.raw`(^|\\.)bing\\.com$`],\n  ['yahoo', 'organic', String.raw`(^|\\.)yahoo\\.[a-z]{2,}(\\.[a-z]{2,3})?$`],\n  ['duckduckgo', 'organic', String.raw`(^|\\.)duckduckgo\\.com$`],\n  ['baidu', 'organic', String.raw`(^|\\.)baidu\\.com$`],\n  ['yandex', 'organic', String.raw`(^|\\.)yandex\\.[a-z]{2,}(\\.[a-z]{2,3})?$`],\n  ['ecosia', 'organic', String.raw`(^|\\.)ecosia\\.org$`],\n  ['naver', 'organic', String.raw`(^|\\.)naver\\.com$`],\n  ['brave', 'organic', String.raw`^search\\.brave\\.com$`],\n  ['meta', 'social', String.raw`(^|\\.)(facebook\\.com|instagram\\.com|fb\\.com|threads\\.net)$`],\n  ['x', 'social', String.raw`(^|\\.)(twitter\\.com|x\\.com|t\\.co)$`],\n  ['linkedin', 'social', String.raw`(^|\\.)(linkedin\\.com|lnkd\\.in)$`],\n  ['reddit', 'social', String.raw`(^|\\.)reddit\\.com$`],\n  ['tiktok', 'social', String.raw`(^|\\.)tiktok\\.com$`],\n  ['pinterest', 'social', String.raw`(^|\\.)pinterest\\.[a-z]{2,}(\\.[a-z]{2,3})?$`],\n  ['snapchat', 'social', String.raw`(^|\\.)snapchat\\.com$`],\n  ['youtube', 'video', String.raw`(^|\\.)(youtube\\.com|youtu\\.be)$`],\n] as const satisfies readonly (readonly [Channel, ReferrerMedium, string])[];\n\n/**\n * Referrer hosts that are navigation, not acquisition: the payment and sign-in providers a\n * visitor is bounced through and back from, and the local dev host. A product appends its own\n * hostnames — a session that starts from an internal link after the session timeout refers to\n * them. POSIX regular expressions over the lower-cased host.\n */\nexport const REFERRERS_NOT_A_TOUCH = [\n  String.raw`^localhost(:|$)`,\n  String.raw`(^|\\.)stripe\\.com$`,\n  String.raw`^(pay|accounts)\\.google\\.com$`,\n  String.raw`^(appleid|apps)\\.apple\\.com$`,\n  String.raw`^play\\.google\\.com$`,\n  String.raw`^login\\.microsoftonline\\.com$`,\n] as const;\n\n/** GA4's paid mediums: cpc, cpm, ppc, retargeting, paid_social, … */\nexport const PAID_MEDIUM = '^(.*cp.*|ppc|retargeting|paid.*)$';\nexport const DISPLAY_MEDIUMS = ['display', 'banner', 'expandable', 'interstitial'] as const;\nexport const EMAIL_MEDIUMS = ['email', 'e-mail', 'e_mail', 'e mail'] as const;\n\n/** Where a touch came from: a tracked session, or a report by the user or staff. */\nexport const TOUCH_SOURCES = ['tracked', 'reported'] as const;\nexport type TouchSource = (typeof TOUCH_SOURCES)[number];\n\n/**\n * How a reported touch was learned:\n * - survey: the user answered \"how did you hear about us\" (onboarding, checkout)\n * - promo_code: the user redeemed a code that belongs to a channel\n * - phone: a call came in on a channel's dedicated number, marked by staff or the phone system\n * - manual: staff recorded what a customer told them\n */\nexport const REPORTED_TOUCH_KINDS = ['survey', 'promo_code', 'phone', 'manual'] as const;\nexport type ReportedTouchKind = (typeof REPORTED_TOUCH_KINDS)[number];\n\n/**\n * How much a touch is worth against another when attribution has to choose between sessions;\n * lower wins, and the latest wins among equals. Derived in the views, never stored, so\n * renumbering is a view regeneration.\n *\n * This ranks touches against each other. Within one session the rules that name its channel have\n * their own order — `utm_source`, then a click id, then the ad landing page, then the referrer —\n * and the first that says something wins; the session's priority is then the tier of that rule.\n * So two sessions tagged with utm and gclid respectively are equal here (both `campaign`) and the\n * later one is credited, while one session carrying both is named by its utm.\n */\nexport const TOUCH_PRIORITY = {\n  /** utm, click id, ad landing page: someone tagged that link (in that order within a session) */\n  campaign: 1,\n  /** a reported touch staff stand behind: a call on a channel's number, a recorded conversation */\n  verified: 1,\n  /** the browser said where the visitor came from; nobody chose it */\n  referrer: 2,\n  /** a reported touch that is the user's claim: a survey answer, a code that may have been shared */\n  claimed: 3,\n} as const satisfies Record<string, number>;\n\n/** Which reported kinds are staff facts and which are the user's claims. */\nexport const REPORTED_TOUCH_PRIORITY = {\n  phone: TOUCH_PRIORITY.verified,\n  manual: TOUCH_PRIORITY.verified,\n  survey: TOUCH_PRIORITY.claimed,\n  promo_code: TOUCH_PRIORITY.claimed,\n} as const satisfies Record<ReportedTouchKind, number>;\n"],"mappings":";;;;;;;;AASA,MAAa,iBAAiB;;AAE9B,MAAa,YAAY;;AAEzB,MAAa,iBAAiB;;AAG9B,MAAa,WAAW;CACtB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAKA,MAAa,iBAAiB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAKA,MAAa,iBAAiB;CAC5B,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,KAAK;CACL,UAAU;CACV,WAAW;CACX,MAAM;CACN,SAAS;AACX;;;;;;AAOA,MAAa,oBAAoB;CAC/B,CAAC,UAAU,MAAM;CACjB,CAAC,OAAO,MAAM;CACd,CAAC,SAAS,QAAQ;CAClB,CAAC,UAAU,QAAQ;CACnB,CAAC,UAAU,QAAQ;CACnB,CAAC,cAAc,QAAQ;CACvB,CAAC,kBAAkB,QAAQ;CAC3B,CAAC,SAAS,OAAO;CACjB,CAAC,WAAW,WAAW;CACvB,CAAC,UAAU,QAAQ;CACnB,CAAC,WAAW,QAAQ;CACpB,CAAC,aAAa,UAAU;CACxB,CAAC,SAAS,UAAU;CACpB,CAAC,UAAU,GAAG;CACd,CAAC,eAAe,OAAO;CACvB,CAAC,SAAS,QAAQ;AACpB;;;;;;AAOA,MAAa,kBAAkB;;;;;;;AAU/B,MAAa,iBAAiB;CAC5B;EAAC;EAAU;EAAW,OAAO,GAAG;CAAyC;CACzE;EAAC;EAAa;EAAW,OAAO,GAAG;CAAkB;CACrD;EAAC;EAAS;EAAW,OAAO,GAAG;CAAwC;CACvE;EAAC;EAAc;EAAW,OAAO,GAAG;CAAwB;CAC5D;EAAC;EAAS;EAAW,OAAO,GAAG;CAAmB;CAClD;EAAC;EAAU;EAAW,OAAO,GAAG;CAAyC;CACzE;EAAC;EAAU;EAAW,OAAO,GAAG;CAAoB;CACpD;EAAC;EAAS;EAAW,OAAO,GAAG;CAAmB;CAClD;EAAC;EAAS;EAAW,OAAO,GAAG;CAAsB;CACrD;EAAC;EAAQ;EAAU,OAAO,GAAG;CAA4D;CACzF;EAAC;EAAK;EAAU,OAAO,GAAG;CAAoC;CAC9D;EAAC;EAAY;EAAU,OAAO,GAAG;CAAiC;CAClE;EAAC;EAAU;EAAU,OAAO,GAAG;CAAoB;CACnD;EAAC;EAAU;EAAU,OAAO,GAAG;CAAoB;CACnD;EAAC;EAAa;EAAU,OAAO,GAAG;CAA4C;CAC9E;EAAC;EAAY;EAAU,OAAO,GAAG;CAAsB;CACvD;EAAC;EAAW;EAAS,OAAO,GAAG;CAAiC;AAClE;;;;;;;AAQA,MAAa,wBAAwB;CACnC,OAAO,GAAG;CACV,OAAO,GAAG;CACV,OAAO,GAAG;CACV,OAAO,GAAG;CACV,OAAO,GAAG;CACV,OAAO,GAAG;AACZ;;AAGA,MAAa,cAAc;AAC3B,MAAa,kBAAkB;CAAC;CAAW;CAAU;CAAc;AAAc;AACjF,MAAa,gBAAgB;CAAC;CAAS;CAAU;CAAU;AAAQ;;AAGnE,MAAa,gBAAgB,CAAC,WAAW,UAAU;;;;;;;;AAUnD,MAAa,uBAAuB;CAAC;CAAU;CAAc;CAAS;AAAQ;;;;;;;;;;;;AAc9E,MAAa,iBAAiB;;CAE5B,UAAU;;CAEV,UAAU;;CAEV,UAAU;;CAEV,SAAS;AACX;;AAGA,MAAa,0BAA0B;CACrC,OAAO,eAAe;CACtB,QAAQ,eAAe;CACvB,QAAQ,eAAe;CACvB,YAAY,eAAe;AAC7B"}

package/dist/attribution/index.d.cts

@@ -0,0 +1,103 @@
+//#region src/attribution/index.d.ts
+/**
+ * The vocabulary attribution is built from, shared by every product's `touchpoint` view and by the
+ * dashboards that read it. Data only, no SQL: a product turns these into its view. What stays with
+ * the product is its own hostnames (referrer exclusions) and its landing-page convention.
+ */
+/** A session that arrived through nothing we can name. GA's spelling, so dashboards read as GA. */
+declare const DIRECT_CHANNEL = "(direct)";
+/** The medium of a direct session. */
+declare const NO_MEDIUM = "(none)";
+/** The medium of a tagged link that named a source but no medium. */
+declare const MEDIUM_NOT_SET = "(not set)";
+/** The channels the rules below can name. A `utm_source` outside this list is its own channel. */
+declare const CHANNELS: readonly ['meta', 'google', 'dv360', 'microsoft', 'tiktok', 'reddit', 'linkedin', 'snapchat', 'x', 'kakao', 'yandex', 'yahoo', 'duckduckgo', 'baidu', 'ecosia', 'naver', 'brave', 'pinterest', 'youtube'];
+type Channel = (typeof CHANNELS)[number];
+/** GA4's default channel groups, as identifiers; a dashboard maps them to display names. */
+declare const CHANNEL_GROUPS: readonly ['direct', 'paid_search', 'paid_social', 'paid_other', 'display', 'organic_search', 'organic_social', 'organic_video', 'referral', 'email', 'affiliate', 'unassigned'];
+type ChannelGroup = (typeof CHANNEL_GROUPS)[number];
+/** `utm_source` spellings that mean the same channel: Meta's `{{site_source_name}}` values and the usual synonyms. */
+declare const SOURCE_ALIASES: {
+  readonly fb: 'meta';
+  readonly ig: 'meta';
+  readonly an: 'meta';
+  readonly msg: 'meta';
+  readonly facebook: 'meta';
+  readonly instagram: 'meta';
+  readonly bing: 'microsoft';
+  readonly twitter: 'x';
+};
+/**
+ * Which click id belongs to which channel, in priority order. Every key is a field this SDK
+ * collects (`AdvertisingInfo`); `fbp` and `rdt_uuid` are deliberately absent — they are pixel
+ * browser ids, present with or without a click.
+ */
+declare const CLICK_ID_CHANNELS: readonly [readonly ["fbclid", "meta"], readonly ["fbc", "meta"], readonly ["gclid", "google"], readonly ["gbraid", "google"], readonly ["wbraid", "google"], readonly ["gad_source", "google"], readonly ["gad_campaignid", "google"], readonly ["dclid", "dv360"], readonly ["msclkid", "microsoft"], readonly ["ttclid", "tiktok"], readonly ["rdt_cid", "reddit"], readonly ["li_fat_id", "linkedin"], readonly ["sccid", "snapchat"], readonly ["twclid", "x"], readonly ["ko_click_id", "kakao"], readonly ["yclid", "yandex"]];
+/**
+ * A landing page reserved for one channel's ads, for ads that lost their parameters:
+ * `/lp/<channel>`, with or without host, query and hash; the capture is the channel. A product
+ * that names its landing pages differently replaces this.
+ */
+declare const AD_LANDING_PAGE = "^(?:https?://[^/]+)?/lp/([a-z]+)(?:[/?#]|$)";
+type ReferrerMedium = 'organic' | 'social' | 'video';
+/**
+ * Referrer hosts that name a channel, as POSIX regular expressions over the lower-cased host,
+ * with the medium GA4 gives that kind of site. Anything else that refers is `referral`, kept as
+ * its host. A country TLD is one or two labels (`google.com`, `google.co.uk`, `google.com.hk`),
+ * never an open tail, so `google.com.evil.io` is not Google.
+ */
+declare const REFERRER_SITES: readonly [readonly ["google", "organic", string], readonly ["microsoft", "organic", string], readonly ["yahoo", "organic", string], readonly ["duckduckgo", "organic", string], readonly ["baidu", "organic", string], readonly ["yandex", "organic", string], readonly ["ecosia", "organic", string], readonly ["naver", "organic", string], readonly ["brave", "organic", string], readonly ["meta", "social", string], readonly ["x", "social", string], readonly ["linkedin", "social", string], readonly ["reddit", "social", string], readonly ["tiktok", "social", string], readonly ["pinterest", "social", string], readonly ["snapchat", "social", string], readonly ["youtube", "video", string]];
+/**
+ * Referrer hosts that are navigation, not acquisition: the payment and sign-in providers a
+ * visitor is bounced through and back from, and the local dev host. A product appends its own
+ * hostnames — a session that starts from an internal link after the session timeout refers to
+ * them. POSIX regular expressions over the lower-cased host.
+ */
+declare const REFERRERS_NOT_A_TOUCH: readonly [string, string, string, string, string, string];
+/** GA4's paid mediums: cpc, cpm, ppc, retargeting, paid_social, … */
+declare const PAID_MEDIUM = "^(.*cp.*|ppc|retargeting|paid.*)$";
+declare const DISPLAY_MEDIUMS: readonly ['display', 'banner', 'expandable', 'interstitial'];
+declare const EMAIL_MEDIUMS: readonly ['email', 'e-mail', 'e_mail', 'e mail'];
+/** Where a touch came from: a tracked session, or a report by the user or staff. */
+declare const TOUCH_SOURCES: readonly ['tracked', 'reported'];
+type TouchSource = (typeof TOUCH_SOURCES)[number];
+/**
+ * How a reported touch was learned:
+ * - survey: the user answered "how did you hear about us" (onboarding, checkout)
+ * - promo_code: the user redeemed a code that belongs to a channel
+ * - phone: a call came in on a channel's dedicated number, marked by staff or the phone system
+ * - manual: staff recorded what a customer told them
+ */
+declare const REPORTED_TOUCH_KINDS: readonly ['survey', 'promo_code', 'phone', 'manual'];
+type ReportedTouchKind = (typeof REPORTED_TOUCH_KINDS)[number];
+/**
+ * How much a touch is worth against another when attribution has to choose between sessions;
+ * lower wins, and the latest wins among equals. Derived in the views, never stored, so
+ * renumbering is a view regeneration.
+ *
+ * This ranks touches against each other. Within one session the rules that name its channel have
+ * their own order — `utm_source`, then a click id, then the ad landing page, then the referrer —
+ * and the first that says something wins; the session's priority is then the tier of that rule.
+ * So two sessions tagged with utm and gclid respectively are equal here (both `campaign`) and the
+ * later one is credited, while one session carrying both is named by its utm.
+ */
+declare const TOUCH_PRIORITY: {
+  /** utm, click id, ad landing page: someone tagged that link (in that order within a session) */
+  readonly campaign: 1;
+  /** a reported touch staff stand behind: a call on a channel's number, a recorded conversation */
+  readonly verified: 1;
+  /** the browser said where the visitor came from; nobody chose it */
+  readonly referrer: 2;
+  /** a reported touch that is the user's claim: a survey answer, a code that may have been shared */
+  readonly claimed: 3;
+};
+/** Which reported kinds are staff facts and which are the user's claims. */
+declare const REPORTED_TOUCH_PRIORITY: {
+  readonly phone: 1;
+  readonly manual: 1;
+  readonly survey: 3;
+  readonly promo_code: 3;
+};
+//#endregion
+export { AD_LANDING_PAGE, CHANNELS, CHANNEL_GROUPS, CLICK_ID_CHANNELS, Channel, ChannelGroup, DIRECT_CHANNEL, DISPLAY_MEDIUMS, EMAIL_MEDIUMS, MEDIUM_NOT_SET, NO_MEDIUM, PAID_MEDIUM, REFERRERS_NOT_A_TOUCH, REFERRER_SITES, REPORTED_TOUCH_KINDS, REPORTED_TOUCH_PRIORITY, ReferrerMedium, ReportedTouchKind, SOURCE_ALIASES, TOUCH_PRIORITY, TOUCH_SOURCES, TouchSource };
+//# sourceMappingURL=index.d.cts.map

package/dist/attribution/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/attribution/index.ts"],"mappings":";;;;;;;cASa;;cAEA;;cAEA;;cAGA;KAsBD,kBAAkB;;cAGjB;KAeD,uBAAuB;;cAGtB;WACP;WACA;WACA;WACC;WACK;WACC;WACL;WACG;;;;;;;cAQE;;;;;;cAwBA;KAED;;;;;;;cAQC;;;;;;;cA0BA;;cAUA;cACA;cACA;;cAGA;KACD,sBAAsB;;;;;;;;cASrB;KACD,4BAA4B;;;;;;;;;;;;cAa3B;;WAED;;WAEA;;WAEA;;WAED;;;cAIE"}

package/dist/attribution/index.d.mts

@@ -0,0 +1,103 @@
+//#region src/attribution/index.d.ts
+/**
+ * The vocabulary attribution is built from, shared by every product's `touchpoint` view and by the
+ * dashboards that read it. Data only, no SQL: a product turns these into its view. What stays with
+ * the product is its own hostnames (referrer exclusions) and its landing-page convention.
+ */
+/** A session that arrived through nothing we can name. GA's spelling, so dashboards read as GA. */
+declare const DIRECT_CHANNEL = "(direct)";
+/** The medium of a direct session. */
+declare const NO_MEDIUM = "(none)";
+/** The medium of a tagged link that named a source but no medium. */
+declare const MEDIUM_NOT_SET = "(not set)";
+/** The channels the rules below can name. A `utm_source` outside this list is its own channel. */
+declare const CHANNELS: readonly ['meta', 'google', 'dv360', 'microsoft', 'tiktok', 'reddit', 'linkedin', 'snapchat', 'x', 'kakao', 'yandex', 'yahoo', 'duckduckgo', 'baidu', 'ecosia', 'naver', 'brave', 'pinterest', 'youtube'];
+type Channel = (typeof CHANNELS)[number];
+/** GA4's default channel groups, as identifiers; a dashboard maps them to display names. */
+declare const CHANNEL_GROUPS: readonly ['direct', 'paid_search', 'paid_social', 'paid_other', 'display', 'organic_search', 'organic_social', 'organic_video', 'referral', 'email', 'affiliate', 'unassigned'];
+type ChannelGroup = (typeof CHANNEL_GROUPS)[number];
+/** `utm_source` spellings that mean the same channel: Meta's `{{site_source_name}}` values and the usual synonyms. */
+declare const SOURCE_ALIASES: {
+  readonly fb: 'meta';
+  readonly ig: 'meta';
+  readonly an: 'meta';
+  readonly msg: 'meta';
+  readonly facebook: 'meta';
+  readonly instagram: 'meta';
+  readonly bing: 'microsoft';
+  readonly twitter: 'x';
+};
+/**
+ * Which click id belongs to which channel, in priority order. Every key is a field this SDK
+ * collects (`AdvertisingInfo`); `fbp` and `rdt_uuid` are deliberately absent — they are pixel
+ * browser ids, present with or without a click.
+ */
+declare const CLICK_ID_CHANNELS: readonly [readonly ["fbclid", "meta"], readonly ["fbc", "meta"], readonly ["gclid", "google"], readonly ["gbraid", "google"], readonly ["wbraid", "google"], readonly ["gad_source", "google"], readonly ["gad_campaignid", "google"], readonly ["dclid", "dv360"], readonly ["msclkid", "microsoft"], readonly ["ttclid", "tiktok"], readonly ["rdt_cid", "reddit"], readonly ["li_fat_id", "linkedin"], readonly ["sccid", "snapchat"], readonly ["twclid", "x"], readonly ["ko_click_id", "kakao"], readonly ["yclid", "yandex"]];
+/**
+ * A landing page reserved for one channel's ads, for ads that lost their parameters:
+ * `/lp/<channel>`, with or without host, query and hash; the capture is the channel. A product
+ * that names its landing pages differently replaces this.
+ */
+declare const AD_LANDING_PAGE = "^(?:https?://[^/]+)?/lp/([a-z]+)(?:[/?#]|$)";
+type ReferrerMedium = 'organic' | 'social' | 'video';
+/**
+ * Referrer hosts that name a channel, as POSIX regular expressions over the lower-cased host,
+ * with the medium GA4 gives that kind of site. Anything else that refers is `referral`, kept as
+ * its host. A country TLD is one or two labels (`google.com`, `google.co.uk`, `google.com.hk`),
+ * never an open tail, so `google.com.evil.io` is not Google.
+ */
+declare const REFERRER_SITES: readonly [readonly ["google", "organic", string], readonly ["microsoft", "organic", string], readonly ["yahoo", "organic", string], readonly ["duckduckgo", "organic", string], readonly ["baidu", "organic", string], readonly ["yandex", "organic", string], readonly ["ecosia", "organic", string], readonly ["naver", "organic", string], readonly ["brave", "organic", string], readonly ["meta", "social", string], readonly ["x", "social", string], readonly ["linkedin", "social", string], readonly ["reddit", "social", string], readonly ["tiktok", "social", string], readonly ["pinterest", "social", string], readonly ["snapchat", "social", string], readonly ["youtube", "video", string]];
+/**
+ * Referrer hosts that are navigation, not acquisition: the payment and sign-in providers a
+ * visitor is bounced through and back from, and the local dev host. A product appends its own
+ * hostnames — a session that starts from an internal link after the session timeout refers to
+ * them. POSIX regular expressions over the lower-cased host.
+ */
+declare const REFERRERS_NOT_A_TOUCH: readonly [string, string, string, string, string, string];
+/** GA4's paid mediums: cpc, cpm, ppc, retargeting, paid_social, … */
+declare const PAID_MEDIUM = "^(.*cp.*|ppc|retargeting|paid.*)$";
+declare const DISPLAY_MEDIUMS: readonly ['display', 'banner', 'expandable', 'interstitial'];
+declare const EMAIL_MEDIUMS: readonly ['email', 'e-mail', 'e_mail', 'e mail'];
+/** Where a touch came from: a tracked session, or a report by the user or staff. */
+declare const TOUCH_SOURCES: readonly ['tracked', 'reported'];
+type TouchSource = (typeof TOUCH_SOURCES)[number];
+/**
+ * How a reported touch was learned:
+ * - survey: the user answered "how did you hear about us" (onboarding, checkout)
+ * - promo_code: the user redeemed a code that belongs to a channel
+ * - phone: a call came in on a channel's dedicated number, marked by staff or the phone system
+ * - manual: staff recorded what a customer told them
+ */
+declare const REPORTED_TOUCH_KINDS: readonly ['survey', 'promo_code', 'phone', 'manual'];
+type ReportedTouchKind = (typeof REPORTED_TOUCH_KINDS)[number];
+/**
+ * How much a touch is worth against another when attribution has to choose between sessions;
+ * lower wins, and the latest wins among equals. Derived in the views, never stored, so
+ * renumbering is a view regeneration.
+ *
+ * This ranks touches against each other. Within one session the rules that name its channel have
+ * their own order — `utm_source`, then a click id, then the ad landing page, then the referrer —
+ * and the first that says something wins; the session's priority is then the tier of that rule.
+ * So two sessions tagged with utm and gclid respectively are equal here (both `campaign`) and the
+ * later one is credited, while one session carrying both is named by its utm.
+ */
+declare const TOUCH_PRIORITY: {
+  /** utm, click id, ad landing page: someone tagged that link (in that order within a session) */
+  readonly campaign: 1;
+  /** a reported touch staff stand behind: a call on a channel's number, a recorded conversation */
+  readonly verified: 1;
+  /** the browser said where the visitor came from; nobody chose it */
+  readonly referrer: 2;
+  /** a reported touch that is the user's claim: a survey answer, a code that may have been shared */
+  readonly claimed: 3;
+};
+/** Which reported kinds are staff facts and which are the user's claims. */
+declare const REPORTED_TOUCH_PRIORITY: {
+  readonly phone: 1;
+  readonly manual: 1;
+  readonly survey: 3;
+  readonly promo_code: 3;
+};
+//#endregion
+export { AD_LANDING_PAGE, CHANNELS, CHANNEL_GROUPS, CLICK_ID_CHANNELS, Channel, ChannelGroup, DIRECT_CHANNEL, DISPLAY_MEDIUMS, EMAIL_MEDIUMS, MEDIUM_NOT_SET, NO_MEDIUM, PAID_MEDIUM, REFERRERS_NOT_A_TOUCH, REFERRER_SITES, REPORTED_TOUCH_KINDS, REPORTED_TOUCH_PRIORITY, ReferrerMedium, ReportedTouchKind, SOURCE_ALIASES, TOUCH_PRIORITY, TOUCH_SOURCES, TouchSource };
+//# sourceMappingURL=index.d.mts.map

package/dist/attribution/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/attribution/index.ts"],"mappings":";;;;;;;cASa;;cAEA;;cAEA;;cAGA;KAsBD,kBAAkB;;cAGjB;KAeD,uBAAuB;;cAGtB;WACP;WACA;WACA;WACC;WACK;WACC;WACL;WACG;;;;;;;cAQE;;;;;;cAwBA;KAED;;;;;;;cAQC;;;;;;;cA0BA;;cAUA;cACA;cACA;;cAGA;KACD,sBAAsB;;;;;;;;cASrB;KACD,4BAA4B;;;;;;;;;;;;cAa3B;;WAED;;WAEA;;WAEA;;WAED;;;cAIE"}