@shware/analytics 8.12.0 → 8.13.0

package/dist/attribution/vocabulary.cjs

@@ -2,8 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/attribution/vocabulary.ts
 /**
 * The vocabulary attribution is built from, shared by every product's `session` table and by the
-* dashboards that read it. Data only: `classifyTouch` (./classify) turns it into a channel, and a
-* product's dashboards read the same names back. What stays with the product is its own hostnames
+* dashboards that read it. Data for `classifyTouch` (./classify), which turns it into a channel;
+* a product's dashboards read the same names back. What stays with the product is its own hostnames
 * (referrer exclusions) and its landing-page conventions.
 */
 /** A session that arrived through nothing we can name. GA's spelling, so dashboards read as GA. */
@@ -33,6 +33,19 @@ const CHANNELS = [
 	"brave",
 	"pinterest",
 	"youtube",
+	"chatgpt",
+	"perplexity",
+	"gemini",
+	"claude",
+	"copilot",
+	"grok",
+	"deepseek",
+	"doubao",
+	"kimi",
+	"qwen",
+	"yuanbao",
+	"ernie",
+	"zhipu",
 	"referral_program"
 ];
 /** GA4's default channel groups, as identifiers; a dashboard maps them to display names. */
@@ -45,6 +58,7 @@ const CHANNEL_GROUPS = [
 	"organic_search",
 	"organic_social",
 	"organic_video",
+	"organic_ai",
 	"referral",
 	"email",
 	"affiliate",
@@ -59,7 +73,19 @@ const SOURCE_ALIASES = {
 	facebook: "meta",
 	instagram: "meta",
 	bing: "microsoft",
-	twitter: "x"
+	twitter: "x",
+	"google ads": "google",
+	googleads: "google",
+	adwords: "google",
+	"chatgpt.com": "chatgpt",
+	"chat.openai.com": "chatgpt",
+	openai: "chatgpt",
+	"perplexity.ai": "perplexity",
+	"claude.ai": "claude",
+	"copilot.com": "copilot",
+	"deepseek.com": "deepseek",
+	"doubao.com": "doubao",
+	"kimi.com": "kimi"
 };
 /**
 * Which click id belongs to which channel, in priority order. Every key is a field this SDK
@@ -89,128 +115,273 @@ const CLICK_ID_CHANNELS = [
 * `/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]+)(?:[/?#]|$)";
+const AD_LANDING_PAGE = /^(?:https?:\/\/[^/]+)?\/lp\/([a-z]+)(?:[/?#]|$)/;
 /**
-* Referrer hosts that name a channel, as POSIX regular expressions over the lower-cased host,
+* Referrer hosts that name a channel, as 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.
+* never an open tail, so `google.com.evil.io` is not Google. In match order: the AI assistants
+* first, because `gemini.google.com`, `copilot.microsoft.com` and `yiyan.baidu.com` would
+* otherwise be Google, Microsoft and Baidu search.
 */
 const REFERRER_SITES = [
+	[
+		"chatgpt",
+		"ai",
+		/(^|\.)(chatgpt\.com|chat\.openai\.com)$/
+	],
+	[
+		"perplexity",
+		"ai",
+		/(^|\.)perplexity\.ai$/
+	],
+	[
+		"gemini",
+		"ai",
+		/^gemini\.google\.com$/
+	],
+	[
+		"claude",
+		"ai",
+		/(^|\.)claude\.ai$/
+	],
+	[
+		"copilot",
+		"ai",
+		/^copilot\.microsoft\.com$|(^|\.)copilot\.com$/
+	],
+	[
+		"grok",
+		"ai",
+		/(^|\.)(grok\.com|x\.ai)$/
+	],
+	[
+		"deepseek",
+		"ai",
+		/(^|\.)deepseek\.com$/
+	],
+	[
+		"doubao",
+		"ai",
+		/(^|\.)doubao\.com$/
+	],
+	[
+		"kimi",
+		"ai",
+		/(^|\.)(kimi\.com|kimi\.moonshot\.cn|moonshot\.cn)$/
+	],
+	[
+		"qwen",
+		"ai",
+		/^tongyi\.aliyun\.com$|(^|\.)(tongyi\.com|qianwen\.com|qwen\.ai)$/
+	],
+	[
+		"yuanbao",
+		"ai",
+		/^yuanbao\.tencent\.com$/
+	],
+	[
+		"ernie",
+		"ai",
+		/^yiyan\.baidu\.com$|(^|\.)ernie\.baidu\.com$/
+	],
+	[
+		"zhipu",
+		"ai",
+		/(^|\.)(chatglm\.cn|zhipuai\.cn|bigmodel\.cn)$/
+	],
 	[
 		"google",
 		"organic",
-		String.raw`(^|\.)google\.[a-z]{2,}(\.[a-z]{2,3})?$`
+		/(^|\.)google\.[a-z]{2,}(\.[a-z]{2,3})?$/
 	],
 	[
 		"microsoft",
 		"organic",
-		String.raw`(^|\.)bing\.com$`
+		/(^|\.)bing\.com$/
 	],
 	[
 		"yahoo",
 		"organic",
-		String.raw`(^|\.)yahoo\.[a-z]{2,}(\.[a-z]{2,3})?$`
+		/(^|\.)yahoo\.[a-z]{2,}(\.[a-z]{2,3})?$/
 	],
 	[
 		"duckduckgo",
 		"organic",
-		String.raw`(^|\.)duckduckgo\.com$`
+		/(^|\.)duckduckgo\.com$/
 	],
 	[
 		"baidu",
 		"organic",
-		String.raw`(^|\.)baidu\.com$`
+		/(^|\.)baidu\.com$/
 	],
 	[
 		"yandex",
 		"organic",
-		String.raw`(^|\.)yandex\.[a-z]{2,}(\.[a-z]{2,3})?$`
+		/(^|\.)yandex\.[a-z]{2,}(\.[a-z]{2,3})?$/
 	],
 	[
 		"ecosia",
 		"organic",
-		String.raw`(^|\.)ecosia\.org$`
+		/(^|\.)ecosia\.org$/
 	],
 	[
 		"naver",
 		"organic",
-		String.raw`(^|\.)naver\.com$`
+		/(^|\.)naver\.com$/
 	],
 	[
 		"brave",
 		"organic",
-		String.raw`^search\.brave\.com$`
+		/^search\.brave\.com$/
 	],
 	[
 		"meta",
 		"social",
-		String.raw`(^|\.)(facebook\.com|instagram\.com|fb\.com|threads\.net)$`
+		/(^|\.)(facebook\.com|instagram\.com|fb\.com|threads\.net)$/
 	],
 	[
 		"x",
 		"social",
-		String.raw`(^|\.)(twitter\.com|x\.com|t\.co)$`
+		/(^|\.)(twitter\.com|x\.com|t\.co)$/
 	],
 	[
 		"linkedin",
 		"social",
-		String.raw`(^|\.)(linkedin\.com|lnkd\.in)$`
+		/(^|\.)(linkedin\.com|lnkd\.in)$/
 	],
 	[
 		"reddit",
 		"social",
-		String.raw`(^|\.)reddit\.com$`
+		/(^|\.)reddit\.com$/
 	],
 	[
 		"tiktok",
 		"social",
-		String.raw`(^|\.)tiktok\.com$`
+		/(^|\.)tiktok\.com$/
 	],
 	[
 		"pinterest",
 		"social",
-		String.raw`(^|\.)pinterest\.[a-z]{2,}(\.[a-z]{2,3})?$`
+		/(^|\.)pinterest\.[a-z]{2,}(\.[a-z]{2,3})?$/
 	],
 	[
 		"snapchat",
 		"social",
-		String.raw`(^|\.)snapchat\.com$`
+		/(^|\.)snapchat\.com$/
 	],
 	[
 		"youtube",
 		"video",
-		String.raw`(^|\.)(youtube\.com|youtu\.be)$`
+		/(^|\.)(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
+* Referrer hosts that are navigation, not acquisition, when a session happens to start on the way
+* back from them: the local dev host; the payment providers a visitor is bounced through; the
+* sign-in providers whose login lives on a host of its own (Google, Apple, Microsoft, WeChat,
+* Kakao, LINE, Naver, Yahoo, Twitch, X's OAuth 1.0a endpoint); and the hosted auth services a
+* product may sit behind (Auth0, Okta, Supabase, Firebase, Clerk). 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.
+* them. Matched before `REFERRER_SITES`, so `nid.naver.com` and `login.yahoo.com` are not read as
+* a search. Providers whose login shares the host with their content — Facebook, X's OAuth 2.0,
+* LinkedIn, GitHub, Discord — cannot be told apart by host (referrer policies strip the path) and
+* are left as the referrers they usually are. 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$`
+	/^localhost(:|$)/,
+	/(^|\.)stripe\.com$/,
+	/^pay\.google\.com$/,
+	/(^|\.)paypal\.com$/,
+	/(^|\.)alipay\.com$/,
+	/(^|\.)paddle\.com$/,
+	/(^|\.)lemonsqueezy\.com$/,
+	/^apps\.apple\.com$/,
+	/^play\.google\.com$/,
+	/^accounts\.google\.com$/,
+	/^appleid\.apple\.com$/,
+	/^login\.(microsoftonline|live)\.com$/,
+	/^open\.weixin\.qq\.com$/,
+	/^(kauth|accounts)\.kakao\.com$/,
+	/^access\.line\.me$/,
+	/^nid\.naver\.com$/,
+	/^login\.yahoo\.com$/,
+	/^id\.twitch\.tv$/,
+	/^api\.twitter\.com$/,
+	/(^|\.)auth0\.com$/,
+	/(^|\.)okta\.com$/,
+	/(^|\.)supabase\.co$/,
+	/(^|\.)firebaseapp\.com$/,
+	/(^|\.)clerk\.accounts\.dev$/
+];
+/** GA4's paid mediums — cpc, cpm, ppc, retargeting, paid_social, … — plus Performance Max. */
+const PAID_MEDIUM = /^(.*cp.*|ppc|retargeting|paid.*|pmax|performance_max)$/;
+/**
+* Meta's `{{placement}}` values, lower-cased, which an ad URL template of `utm_medium={{placement}}`
+* puts in the medium. Only an ad carries one — an organic post arrives as a referrer, with no utm
+* at all — so a medium in this list is a paid Meta click whatever the source says (a template with
+* `utm_source=meta-websitekeyinfo` was seen). Listed one by one rather than matched by prefix, so
+* that a hand-tagged `instagram_stories` post cannot be mistaken for an ad only because of how it
+* is spelled … which means a placement Meta adds later shows up as unassigned until it is added
+* here. Meta's documented values plus the ones seen in the wild (`facebook_mobile_reels`,
+* `facebook_notification`, `an`), and the literal macro for a template that did not expand it.
+*/
+const META_PLACEMENTS = [
+	"facebook_desktop_feed",
+	"facebook_mobile_feed",
+	"facebook_mobile_reels",
+	"facebook_reels",
+	"facebook_reels_overlay",
+	"facebook_right_column",
+	"facebook_marketplace",
+	"facebook_video_feeds",
+	"facebook_stories",
+	"facebook_search",
+	"facebook_instream_video",
+	"facebook_instant_article",
+	"facebook_groups_feed",
+	"facebook_profile_feed",
+	"facebook_notification",
+	"facebook_notifications",
+	"facebook_business_explore",
+	"instagram_feed",
+	"instagram_stories",
+	"instagram_reels",
+	"instagram_reels_overlay",
+	"instagram_explore",
+	"instagram_explore_home",
+	"instagram_search",
+	"instagram_shop",
+	"instagram_profile_feed",
+	"instagram_profile_reels",
+	"instagram_igtv",
+	"messenger_inbox",
+	"messenger_stories",
+	"messenger_sponsored_messages",
+	"threads_feed",
+	"whatsapp_status",
+	"audience_network_classic",
+	"audience_network_rewarded_video",
+	"audience_network_native_banner_and_interstitial",
+	"an",
+	"others",
+	"{{placement}}"
 ];
-/** GA4's paid mediums: cpc, cpm, ppc, retargeting, paid_social, … */
-const PAID_MEDIUM = "^(.*cp.*|ppc|retargeting|paid.*)$";
 const DISPLAY_MEDIUMS = [
 	"display",
 	"banner",
 	"expandable",
 	"interstitial"
 ];
+/** GA4's email spellings, as a source or a medium. */
 const EMAIL_MEDIUMS = [
 	"email",
 	"e-mail",
 	"e_mail",
 	"e mail"
 ];
+/** A medium that says email or newsletter anywhere in it: `outbound email`, `cold_email`, `newsletter`, and GA4's four. */
+const EMAIL_MEDIUM = /(^|[^a-z])(e[-_ ]?mail|newsletter)([^a-z]|$)/;
 /** Where a touch came from: a tracked session, or a report by the user or staff. */
 const TOUCH_SOURCES = ["tracked", "reported"];
 /**
@@ -261,8 +432,10 @@ exports.CHANNEL_GROUPS = CHANNEL_GROUPS;
 exports.CLICK_ID_CHANNELS = CLICK_ID_CHANNELS;
 exports.DIRECT_CHANNEL = DIRECT_CHANNEL;
 exports.DISPLAY_MEDIUMS = DISPLAY_MEDIUMS;
+exports.EMAIL_MEDIUM = EMAIL_MEDIUM;
 exports.EMAIL_MEDIUMS = EMAIL_MEDIUMS;
 exports.MEDIUM_NOT_SET = MEDIUM_NOT_SET;
+exports.META_PLACEMENTS = META_PLACEMENTS;
 exports.NO_MEDIUM = NO_MEDIUM;
 exports.PAID_MEDIUM = PAID_MEDIUM;
 exports.REFERRERS_NOT_A_TOUCH = REFERRERS_NOT_A_TOUCH;

package/dist/attribution/vocabulary.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"vocabulary.cjs","names":[],"sources":["../../src/attribution/vocabulary.ts"],"sourcesContent":["import type { AdvertisingInfo } from '../track/types';\n\n/**\n * The vocabulary attribution is built from, shared by every product's `session` table and by the\n * dashboards that read it. Data only: `classifyTouch` (./classify) turns it into a channel, and a\n * product's dashboards read the same names back. What stays with the product is its own hostnames\n * (referrer exclusions) and its landing-page conventions.\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  /** the product's own referral programme: the session came through a member's link or code.\n   * How a product recognises one (a `/refer/<code>` path, a code at sign-up) is its own rule. Not\n   * `referral`: that word is the channel group of any outside site, and a channel of the same name\n   * would be impossible to tell apart in queries. */\n  'referral_program',\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. Stored on the session when it is classified, so\n * renumbering means reclassifying.\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":";;;;;;;;;AAUA,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;CAKA;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"}
+{"version":3,"file":"vocabulary.cjs","names":[],"sources":["../../src/attribution/vocabulary.ts"],"sourcesContent":["import type { AdvertisingInfo } from '../track/types';\n\n/**\n * The vocabulary attribution is built from, shared by every product's `session` table and by the\n * dashboards that read it. Data for `classifyTouch` (./classify), which turns it into a channel;\n * a product's dashboards read the same names back. What stays with the product is its own hostnames\n * (referrer exclusions) and its landing-page conventions.\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  /** AI assistants that send people to sites: ChatGPT tags its links `utm_source=chatgpt.com`, the\n   * others show as a referrer. Their own channel group, `organic_ai`, since GA4's default groups\n   * would file them under Referral / Unassigned and the question \"how much does AI bring\" comes up. */\n  'chatgpt',\n  'perplexity',\n  'gemini',\n  'claude',\n  'copilot',\n  'grok',\n  /** and the Chinese ones — DeepSeek, 豆包, Kimi, 通义, 腾讯元宝, 文心一言, 智谱清言 */\n  'deepseek',\n  'doubao',\n  'kimi',\n  'qwen',\n  'yuanbao',\n  'ernie',\n  'zhipu',\n  /** the product's own referral programme: the session came through a member's link or code.\n   * How a product recognises one (a `/refer/<code>` path, a code at sign-up) is its own rule. Not\n   * `referral`: that word is the channel group of any outside site, and a channel of the same name\n   * would be impossible to tell apart in queries. */\n  'referral_program',\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  /** not in GA4's default grouping: sessions an AI assistant sent, by referrer or by ChatGPT's utm */\n  'organic_ai',\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  'google ads': 'google',\n  googleads: 'google',\n  adwords: 'google',\n  'chatgpt.com': 'chatgpt',\n  'chat.openai.com': 'chatgpt',\n  openai: 'chatgpt',\n  'perplexity.ai': 'perplexity',\n  'claude.ai': 'claude',\n  'copilot.com': 'copilot',\n  'deepseek.com': 'deepseek',\n  'doubao.com': 'doubao',\n  'kimi.com': 'kimi',\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' | 'ai';\n\n/**\n * Referrer hosts that name a channel, as 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. In match order: the AI assistants\n * first, because `gemini.google.com`, `copilot.microsoft.com` and `yiyan.baidu.com` would\n * otherwise be Google, Microsoft and Baidu search.\n */\nexport const REFERRER_SITES = [\n  ['chatgpt', 'ai', /(^|\\.)(chatgpt\\.com|chat\\.openai\\.com)$/],\n  ['perplexity', 'ai', /(^|\\.)perplexity\\.ai$/],\n  ['gemini', 'ai', /^gemini\\.google\\.com$/],\n  ['claude', 'ai', /(^|\\.)claude\\.ai$/],\n  ['copilot', 'ai', /^copilot\\.microsoft\\.com$|(^|\\.)copilot\\.com$/],\n  ['grok', 'ai', /(^|\\.)(grok\\.com|x\\.ai)$/],\n  ['deepseek', 'ai', /(^|\\.)deepseek\\.com$/],\n  ['doubao', 'ai', /(^|\\.)doubao\\.com$/],\n  ['kimi', 'ai', /(^|\\.)(kimi\\.com|kimi\\.moonshot\\.cn|moonshot\\.cn)$/],\n  ['qwen', 'ai', /^tongyi\\.aliyun\\.com$|(^|\\.)(tongyi\\.com|qianwen\\.com|qwen\\.ai)$/],\n  ['yuanbao', 'ai', /^yuanbao\\.tencent\\.com$/],\n  ['ernie', 'ai', /^yiyan\\.baidu\\.com$|(^|\\.)ernie\\.baidu\\.com$/],\n  ['zhipu', 'ai', /(^|\\.)(chatglm\\.cn|zhipuai\\.cn|bigmodel\\.cn)$/],\n  ['google', 'organic', /(^|\\.)google\\.[a-z]{2,}(\\.[a-z]{2,3})?$/],\n  ['microsoft', 'organic', /(^|\\.)bing\\.com$/],\n  ['yahoo', 'organic', /(^|\\.)yahoo\\.[a-z]{2,}(\\.[a-z]{2,3})?$/],\n  ['duckduckgo', 'organic', /(^|\\.)duckduckgo\\.com$/],\n  ['baidu', 'organic', /(^|\\.)baidu\\.com$/],\n  ['yandex', 'organic', /(^|\\.)yandex\\.[a-z]{2,}(\\.[a-z]{2,3})?$/],\n  ['ecosia', 'organic', /(^|\\.)ecosia\\.org$/],\n  ['naver', 'organic', /(^|\\.)naver\\.com$/],\n  ['brave', 'organic', /^search\\.brave\\.com$/],\n  ['meta', 'social', /(^|\\.)(facebook\\.com|instagram\\.com|fb\\.com|threads\\.net)$/],\n  ['x', 'social', /(^|\\.)(twitter\\.com|x\\.com|t\\.co)$/],\n  ['linkedin', 'social', /(^|\\.)(linkedin\\.com|lnkd\\.in)$/],\n  ['reddit', 'social', /(^|\\.)reddit\\.com$/],\n  ['tiktok', 'social', /(^|\\.)tiktok\\.com$/],\n  ['pinterest', 'social', /(^|\\.)pinterest\\.[a-z]{2,}(\\.[a-z]{2,3})?$/],\n  ['snapchat', 'social', /(^|\\.)snapchat\\.com$/],\n  ['youtube', 'video', /(^|\\.)(youtube\\.com|youtu\\.be)$/],\n] as const satisfies readonly (readonly [Channel, ReferrerMedium, RegExp])[];\n\n/**\n * Referrer hosts that are navigation, not acquisition, when a session happens to start on the way\n * back from them: the local dev host; the payment providers a visitor is bounced through; the\n * sign-in providers whose login lives on a host of its own (Google, Apple, Microsoft, WeChat,\n * Kakao, LINE, Naver, Yahoo, Twitch, X's OAuth 1.0a endpoint); and the hosted auth services a\n * product may sit behind (Auth0, Okta, Supabase, Firebase, Clerk). A product appends its own\n * hostnames — a session that starts from an internal link after the session timeout refers to\n * them. Matched before `REFERRER_SITES`, so `nid.naver.com` and `login.yahoo.com` are not read as\n * a search. Providers whose login shares the host with their content — Facebook, X's OAuth 2.0,\n * LinkedIn, GitHub, Discord — cannot be told apart by host (referrer policies strip the path) and\n * are left as the referrers they usually are. Regular expressions over the lower-cased host.\n */\nexport const REFERRERS_NOT_A_TOUCH = [\n  /^localhost(:|$)/,\n  // payment\n  /(^|\\.)stripe\\.com$/,\n  /^pay\\.google\\.com$/,\n  /(^|\\.)paypal\\.com$/,\n  /(^|\\.)alipay\\.com$/,\n  /(^|\\.)paddle\\.com$/,\n  /(^|\\.)lemonsqueezy\\.com$/,\n  // app stores\n  /^apps\\.apple\\.com$/,\n  /^play\\.google\\.com$/,\n  // sign-in providers with a login host of their own\n  /^accounts\\.google\\.com$/,\n  /^appleid\\.apple\\.com$/,\n  /^login\\.(microsoftonline|live)\\.com$/,\n  /^open\\.weixin\\.qq\\.com$/,\n  /^(kauth|accounts)\\.kakao\\.com$/,\n  /^access\\.line\\.me$/,\n  /^nid\\.naver\\.com$/,\n  /^login\\.yahoo\\.com$/,\n  /^id\\.twitch\\.tv$/,\n  /^api\\.twitter\\.com$/,\n  // hosted auth services\n  /(^|\\.)auth0\\.com$/,\n  /(^|\\.)okta\\.com$/,\n  /(^|\\.)supabase\\.co$/,\n  /(^|\\.)firebaseapp\\.com$/,\n  /(^|\\.)clerk\\.accounts\\.dev$/,\n] as const;\n\n/** GA4's paid mediums — cpc, cpm, ppc, retargeting, paid_social, … — plus Performance Max. */\nexport const PAID_MEDIUM = /^(.*cp.*|ppc|retargeting|paid.*|pmax|performance_max)$/;\n/**\n * Meta's `{{placement}}` values, lower-cased, which an ad URL template of `utm_medium={{placement}}`\n * puts in the medium. Only an ad carries one — an organic post arrives as a referrer, with no utm\n * at all — so a medium in this list is a paid Meta click whatever the source says (a template with\n * `utm_source=meta-websitekeyinfo` was seen). Listed one by one rather than matched by prefix, so\n * that a hand-tagged `instagram_stories` post cannot be mistaken for an ad only because of how it\n * is spelled … which means a placement Meta adds later shows up as unassigned until it is added\n * here. Meta's documented values plus the ones seen in the wild (`facebook_mobile_reels`,\n * `facebook_notification`, `an`), and the literal macro for a template that did not expand it.\n */\nexport const META_PLACEMENTS = [\n  'facebook_desktop_feed',\n  'facebook_mobile_feed',\n  'facebook_mobile_reels',\n  'facebook_reels',\n  'facebook_reels_overlay',\n  'facebook_right_column',\n  'facebook_marketplace',\n  'facebook_video_feeds',\n  'facebook_stories',\n  'facebook_search',\n  'facebook_instream_video',\n  'facebook_instant_article',\n  'facebook_groups_feed',\n  'facebook_profile_feed',\n  'facebook_notification',\n  'facebook_notifications',\n  'facebook_business_explore',\n  'instagram_feed',\n  'instagram_stories',\n  'instagram_reels',\n  'instagram_reels_overlay',\n  'instagram_explore',\n  'instagram_explore_home',\n  'instagram_search',\n  'instagram_shop',\n  'instagram_profile_feed',\n  'instagram_profile_reels',\n  'instagram_igtv',\n  'messenger_inbox',\n  'messenger_stories',\n  'messenger_sponsored_messages',\n  'threads_feed',\n  'whatsapp_status',\n  'audience_network_classic',\n  'audience_network_rewarded_video',\n  'audience_network_native_banner_and_interstitial',\n  'an',\n  'others',\n  /** the macro itself, when Meta did not expand it (written in a field it does not substitute, or a\n   * preview click): still only ever produced by a Meta ad URL, so still a paid Meta click */\n  '{{placement}}',\n] as const;\nexport const DISPLAY_MEDIUMS = ['display', 'banner', 'expandable', 'interstitial'] as const;\n/** GA4's email spellings, as a source or a medium. */\nexport const EMAIL_MEDIUMS = ['email', 'e-mail', 'e_mail', 'e mail'] as const;\n/** A medium that says email or newsletter anywhere in it: `outbound email`, `cold_email`, `newsletter`, and GA4's four. */\nexport const EMAIL_MEDIUM = /(^|[^a-z])(e[-_ ]?mail|newsletter)([^a-z]|$)/;\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. Stored on the session when it is classified, so\n * renumbering means reclassifying.\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":"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"}

package/dist/attribution/vocabulary.d.cts

@@ -1,8 +1,8 @@
 //#region src/attribution/vocabulary.d.ts
 /**
  * The vocabulary attribution is built from, shared by every product's `session` table and by the
- * dashboards that read it. Data only: `classifyTouch` (./classify) turns it into a channel, and a
- * product's dashboards read the same names back. What stays with the product is its own hostnames
+ * dashboards that read it. Data for `classifyTouch` (./classify), which turns it into a channel;
+ * a product's dashboards read the same names back. What stays with the product is its own hostnames
  * (referrer exclusions) and its landing-page conventions.
  */
 /** A session that arrived through nothing we can name. GA's spelling, so dashboards read as GA. */
@@ -13,6 +13,12 @@ declare const NO_MEDIUM = "(none)";
 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',
+/** AI assistants that send people to sites: ChatGPT tags its links `utm_source=chatgpt.com`, the
+ * others show as a referrer. Their own channel group, `organic_ai`, since GA4's default groups
+ * would file them under Referral / Unassigned and the question "how much does AI bring" comes up. */
+'chatgpt', 'perplexity', 'gemini', 'claude', 'copilot', 'grok',
+/** and the Chinese ones — DeepSeek, 豆包, Kimi, 通义, 腾讯元宝, 文心一言, 智谱清言 */
+'deepseek', 'doubao', 'kimi', 'qwen', 'yuanbao', 'ernie', 'zhipu',
 /** the product's own referral programme: the session came through a member's link or code.
  * How a product recognises one (a `/refer/<code>` path, a code at sign-up) is its own rule. Not
  * `referral`: that word is the channel group of any outside site, and a channel of the same name
@@ -20,7 +26,9 @@ declare const CHANNELS: readonly ['meta', 'google', 'dv360', 'microsoft', 'tikto
 'referral_program'];
 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'];
+declare const CHANNEL_GROUPS: readonly ['direct', 'paid_search', 'paid_social', 'paid_other', 'display', 'organic_search', 'organic_social', 'organic_video',
+/** not in GA4's default grouping: sessions an AI assistant sent, by referrer or by ChatGPT's utm */
+'organic_ai', '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: {
@@ -32,6 +40,18 @@ declare const SOURCE_ALIASES: {
   readonly instagram: 'meta';
   readonly bing: 'microsoft';
   readonly twitter: 'x';
+  readonly 'google ads': 'google';
+  readonly googleads: 'google';
+  readonly adwords: 'google';
+  readonly 'chatgpt.com': 'chatgpt';
+  readonly 'chat.openai.com': 'chatgpt';
+  readonly openai: 'chatgpt';
+  readonly 'perplexity.ai': 'perplexity';
+  readonly 'claude.ai': 'claude';
+  readonly 'copilot.com': 'copilot';
+  readonly 'deepseek.com': 'deepseek';
+  readonly 'doubao.com': 'doubao';
+  readonly 'kimi.com': 'kimi';
 };
 /**
  * Which click id belongs to which channel, in priority order. Every key is a field this SDK
@@ -44,26 +64,51 @@ declare const CLICK_ID_CHANNELS: readonly [readonly ["fbclid", "meta"], readonly
  * `/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';
+declare const AD_LANDING_PAGE: RegExp;
+type ReferrerMedium = 'organic' | 'social' | 'video' | 'ai';
 /**
- * Referrer hosts that name a channel, as POSIX regular expressions over the lower-cased host,
+ * Referrer hosts that name a channel, as 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.
+ * never an open tail, so `google.com.evil.io` is not Google. In match order: the AI assistants
+ * first, because `gemini.google.com`, `copilot.microsoft.com` and `yiyan.baidu.com` would
+ * otherwise be Google, Microsoft and Baidu search.
  */
-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]];
+declare const REFERRER_SITES: readonly [readonly ["chatgpt", "ai", RegExp], readonly ["perplexity", "ai", RegExp], readonly ["gemini", "ai", RegExp], readonly ["claude", "ai", RegExp], readonly ["copilot", "ai", RegExp], readonly ["grok", "ai", RegExp], readonly ["deepseek", "ai", RegExp], readonly ["doubao", "ai", RegExp], readonly ["kimi", "ai", RegExp], readonly ["qwen", "ai", RegExp], readonly ["yuanbao", "ai", RegExp], readonly ["ernie", "ai", RegExp], readonly ["zhipu", "ai", RegExp], readonly ["google", "organic", RegExp], readonly ["microsoft", "organic", RegExp], readonly ["yahoo", "organic", RegExp], readonly ["duckduckgo", "organic", RegExp], readonly ["baidu", "organic", RegExp], readonly ["yandex", "organic", RegExp], readonly ["ecosia", "organic", RegExp], readonly ["naver", "organic", RegExp], readonly ["brave", "organic", RegExp], readonly ["meta", "social", RegExp], readonly ["x", "social", RegExp], readonly ["linkedin", "social", RegExp], readonly ["reddit", "social", RegExp], readonly ["tiktok", "social", RegExp], readonly ["pinterest", "social", RegExp], readonly ["snapchat", "social", RegExp], readonly ["youtube", "video", RegExp]];
 /**
- * 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
+ * Referrer hosts that are navigation, not acquisition, when a session happens to start on the way
+ * back from them: the local dev host; the payment providers a visitor is bounced through; the
+ * sign-in providers whose login lives on a host of its own (Google, Apple, Microsoft, WeChat,
+ * Kakao, LINE, Naver, Yahoo, Twitch, X's OAuth 1.0a endpoint); and the hosted auth services a
+ * product may sit behind (Auth0, Okta, Supabase, Firebase, Clerk). 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.
+ * them. Matched before `REFERRER_SITES`, so `nid.naver.com` and `login.yahoo.com` are not read as
+ * a search. Providers whose login shares the host with their content — Facebook, X's OAuth 2.0,
+ * LinkedIn, GitHub, Discord — cannot be told apart by host (referrer policies strip the path) and
+ * are left as the referrers they usually are. 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 REFERRERS_NOT_A_TOUCH: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+/** GA4's paid mediums — cpc, cpm, ppc, retargeting, paid_social, … — plus Performance Max. */
+declare const PAID_MEDIUM: RegExp;
+/**
+ * Meta's `{{placement}}` values, lower-cased, which an ad URL template of `utm_medium={{placement}}`
+ * puts in the medium. Only an ad carries one — an organic post arrives as a referrer, with no utm
+ * at all — so a medium in this list is a paid Meta click whatever the source says (a template with
+ * `utm_source=meta-websitekeyinfo` was seen). Listed one by one rather than matched by prefix, so
+ * that a hand-tagged `instagram_stories` post cannot be mistaken for an ad only because of how it
+ * is spelled … which means a placement Meta adds later shows up as unassigned until it is added
+ * here. Meta's documented values plus the ones seen in the wild (`facebook_mobile_reels`,
+ * `facebook_notification`, `an`), and the literal macro for a template that did not expand it.
+ */
+declare const META_PLACEMENTS: readonly ['facebook_desktop_feed', 'facebook_mobile_feed', 'facebook_mobile_reels', 'facebook_reels', 'facebook_reels_overlay', 'facebook_right_column', 'facebook_marketplace', 'facebook_video_feeds', 'facebook_stories', 'facebook_search', 'facebook_instream_video', 'facebook_instant_article', 'facebook_groups_feed', 'facebook_profile_feed', 'facebook_notification', 'facebook_notifications', 'facebook_business_explore', 'instagram_feed', 'instagram_stories', 'instagram_reels', 'instagram_reels_overlay', 'instagram_explore', 'instagram_explore_home', 'instagram_search', 'instagram_shop', 'instagram_profile_feed', 'instagram_profile_reels', 'instagram_igtv', 'messenger_inbox', 'messenger_stories', 'messenger_sponsored_messages', 'threads_feed', 'whatsapp_status', 'audience_network_classic', 'audience_network_rewarded_video', 'audience_network_native_banner_and_interstitial', 'an', 'others',
+/** the macro itself, when Meta did not expand it (written in a field it does not substitute, or a
+ * preview click): still only ever produced by a Meta ad URL, so still a paid Meta click */
+'{{placement}}'];
 declare const DISPLAY_MEDIUMS: readonly ['display', 'banner', 'expandable', 'interstitial'];
+/** GA4's email spellings, as a source or a medium. */
 declare const EMAIL_MEDIUMS: readonly ['email', 'e-mail', 'e_mail', 'e mail'];
+/** A medium that says email or newsletter anywhere in it: `outbound email`, `cold_email`, `newsletter`, and GA4's four. */
+declare const EMAIL_MEDIUM: RegExp;
 /** 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];
@@ -105,5 +150,5 @@ declare const REPORTED_TOUCH_PRIORITY: {
   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 };
+export { AD_LANDING_PAGE, CHANNELS, CHANNEL_GROUPS, CLICK_ID_CHANNELS, Channel, ChannelGroup, DIRECT_CHANNEL, DISPLAY_MEDIUMS, EMAIL_MEDIUM, EMAIL_MEDIUMS, MEDIUM_NOT_SET, META_PLACEMENTS, 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=vocabulary.d.cts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vocabulary.d.cts","names":[],"sources":["../../src/attribution/vocabulary.ts"],"mappings":";;;;;;;;cAUa;;cAEA;;cAEA;;cAGA;;;;;;KA2BD,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"}
+{"version":3,"file":"vocabulary.d.cts","names":[],"sources":["../../src/attribution/vocabulary.ts"],"mappings":";;;;;;;;cAUa;;cAEA;;cAEA;;cAGA;;;;;;;;;;;;KA4CD,kBAAkB;;cAGjB;;;KAiBD,uBAAuB;;cAGtB;WACP;WACA;WACA;WACC;WACK;WACC;WACL;WACG;WACK;WACH;WACF;WACM;WACI;WACX;WACS;WACJ;WACE;WACC;WACF;WACF;;;;;;;cAQD;;;;;;cAwBA,iBAAe;KAEhB;;;;;;;;;cAUC,qDAAc,uCAAA,mCAAA,mCAAA,oCAAA,iCAAA,qCAAA,mCAAA,iCAAA,iCAAA,oCAAA,kCAAA,kCAAA,wCAAA,2CAAA,uCAAA,4CAAA,uCAAA,wCAAA,wCAAA,uCAAA,uCAAA,qCAAA,kCAAA,yCAAA,uCAAA,uCAAA,0CAAA,yCAAA,uCAAA;;;;;;;;;;;;;cA6Cd,iCAAqB,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA,QAAA;;cAgCrB,aAAW;;;;;;;;;;;cAWX;;;;cA2CA;;cAEA;;cAEA,cAAY;;cAGZ;KACD,sBAAsB;;;;;;;;cASrB;KACD,4BAA4B;;;;;;;;;;;;cAa3B;;WAED;;WAEA;;WAEA;;WAED;;;cAIE"}