@shware/analytics 10.1.0 → 10.2.0

package/README.md

@@ -63,22 +63,175 @@ changes. The framework `Analytics` components wire this up.
 ## 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 in the landing URL (`fbclid`,
-  `gclid`, … — never the cookie an earlier click left); 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.
+layers, each derived from the one below it:
+
+- **Session** — one row per `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. The
+  server reads its tags once, when it writes the session, with `classifyTouch`
+  (`@shware/analytics/attribution`) and stores the touch on the session row; a rule change is
+  applied to history by reclassifying.
+- **Touchpoint** — one row per touch: every session with its stored touch, plus the touches people
+  report (a survey answer, a call on a channel's number). Nothing is derived at query time.
+- **Attribution** — one row per session, credited to the strongest touch of the same person
+  (across devices) within a window, the session's own touch included. See the rules below.
+
+### How a session is read as a touch (`classifyTouch`)
+
+The channel and medium come from the first rule that says something:
+
+| Order | Signal                                                                                          | `channel`                                                                                                          | `medium`                                           |
+| ----- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| 1     | `utm_source` in the URL                                                                         | the source, aliases folded (`fb`, `ig` → `meta`)                                                                   | `utm_medium`, or `(not set)`                       |
+| 2     | A click id in the URL (`gclid`, `fbclid`, `rdt_cid`, …; never the cookie an earlier click left) | the id's platform                                                                                                  | `cpc`                                              |
+| 3     | An ad landing page, `/lp/<channel>`                                                             | that channel                                                                                                       | `cpc`                                              |
+| 4     | The product's own rules (`TouchRule`, e.g. a referral link)                                     | as the rule says                                                                                                   | as the rule says                                   |
+| 5     | The referrer's host                                                                             | a known search engine, social network, video site or AI assistant folded to its channel; any other host kept as is | `organic` / `social` / `video` / `ai` / `referral` |
+| 6     | Nothing                                                                                         | `(direct)`                                                                                                         | `(none)`                                           |
+
+One exception: an ad-only click id of the channel itself (`'ads'` in `CLICK_ID_CHANNELS`), or the
+channel's ad landing page, proves the click was paid, so the medium becomes `cpc` when it was left
+out or puts the touch in an organic group — a Reddit ad tagged `utm_source=reddit&utm_medium=social`
+that carries `rdt_cid`. A declared paid medium is kept as it is. `fbclid` never proves anything:
+Meta puts it on organic links too; nor does another channel's id (an ad link copied and shared
+under a utm of its own).
+
+`channel_group` is GA4's default channel grouping of the two (`channelGroupOf`): `paid_search`,
+`organic_search`, `paid_social`, `email`, ….
+
+The touch's `priority` (`TOUCH_PRIORITY`, lower is stronger) decides which touch wins in the
+attribution layer:
+
+| Priority         | Touches                                                                                                                                                                                                                                                                 |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1 — campaign** | A utm, click id or ad landing page whose group is paid, display, affiliate or unassigned; a product rule that says so (a referral link); a reported touch staff stand behind (`phone`, `manual`)                                                                        |
+| **2 — referrer** | A touch read from the referrer (organic search, social, other sites); **and** a utm, click id or ad landing page whose group comes out `organic_*`, `referral` or `email` (`utm_source=chatgpt.com` on ChatGPT's organic citations, `utm_medium=organic`, a newsletter) |
+| **3 — claimed**  | A reported touch that is the user's claim (`survey`, `promo_code`)                                                                                                                                                                                                      |
+| none             | Direct: no touch                                                                                                                                                                                                                                                        |
+
+When a product rule matched as well as a campaign rule, the stronger tier holds: a referral link
+shared under `utm_source=facebook` is named by the utm (`meta`, organic social) and still ranks as
+the referral programme declares.
+
+In short: a link someone paid for is 1; what the browser brought, a tag that calls itself organic,
+and our own emails are 2; what the user says is 3. Email is 2 because it reaches people we already
+know, often because an ad brought them, and its links (a welcome mail, a trial reminder) come
+between that ad and the purchase: it must not take the ad's credit, and with no ad in the window
+it still wins as the latest touch.
+
+### How a session is credited (the attribution view)
+
+For every session, among the same person's touches within the window (30 days in the reference
+views), **the session's own touch included**:
+
+1. the lowest `priority` wins;
+2. among equals, the latest wins;
+3. on a full tie, the session's own touch wins.
+
+| `touch_kind` | Meaning                                                              |
+| ------------ | -------------------------------------------------------------------- |
+| `own`        | The session's own touch won                                          |
+| `inherited`  | A direct session, credited to an earlier touch                       |
+| `overridden` | The session had a touch of its own, but an earlier, stronger one won |
+| `none`       | A direct session with no touch in the window                         |
+
+| #   | What happened                                                                      | The current session is credited to | `touch_kind` | Why                                 |
+| --- | ---------------------------------------------------------------------------------- | ---------------------------------- | ------------ | ----------------------------------- |
+| 1   | Day 1 a Meta ad click, day 2 a branded Google search                               | **Meta**                           | `overridden` | 1 beats 2                           |
+| 2   | Day 1 a Meta ad click, day 2 typed in                                              | **Meta**                           | `inherited`  | direct inherits                     |
+| 3   | Day 1 an organic search, day 2 a Meta ad click                                     | **Meta**                           | `own`        | its own touch is stronger           |
+| 4   | Day 1 a Meta ad click, day 3 a Google ad click                                     | **Google**                         | `own`        | both 1, the latest wins             |
+| 5   | Day 1 a Meta ad click, day 2 a ChatGPT citation with its utm                       | **Meta**                           | `overridden` | ChatGPT's organic utm ranks 2       |
+| 6   | Day 1 an organic search, day 5 a ChatGPT citation                                  | **ChatGPT**                        | `own`        | both 2, the latest wins             |
+| 7   | An ad click 45 days ago, an organic search today                                   | **Organic search**                 | `own`        | the ad is out of the window         |
+| 8   | A Reddit ad tagged `utm_medium=social` with `rdt_cid`                              | **reddit / cpc**                   | `own`        | the click id proves a paid click    |
+| 9   | Day 1 a Meta ad click, day 2 a newsletter link (`utm_medium=email`)                | **Meta**                           | `overridden` | email ranks 2                       |
+| 10  | Day 1 an organic search, day 2 a newsletter link, no ad in the window              | **Email**                          | `own`        | both 2, the latest wins             |
+| 11  | A survey answer "a podcast" (backdated to the first visit), then an organic search | **Organic search**                 | `own`        | 2 beats 3; a claim only fills a gap |
+
+**How this differs from GA4.** GA4's last non-direct click credits the latest touch that is not
+direct, whatever it was: cases 1, 5 and 9 go to the search, ChatGPT and the email. Here an ad click is not
+overwritten by the organic visit that follows it within the window, which is what a paid ROAS
+panel expects. The touchpoint layer still has every session's own touch, so the GA4-style figure
+is one query away, and `overridden` measures the difference.
+
+**Retargeting.** No click-based model can tell whether an ad caused the visit, and retargeting is
+where that shows: someone who would have come back anyway clicks a retargeting ad on the way in.
+For a returning customer who was going to buy anyway:
+
+| What happened                                                     | GA4 last non-direct click | This model |
+| ----------------------------------------------------------------- | ------------------------- | ---------- |
+| Clicks a retargeting ad, buys in that session                     | the ad                    | the ad     |
+| Clicks a retargeting ad, types the site in the next day and buys  | the ad (direct inherits)  | the ad     |
+| Clicks a retargeting ad, searches the brand the next day and buys | **the search**            | the ad     |
+
+GA4's model only removes the third row, and that row is the credit a prospecting ad deserves (the
+ad made the brand known, the search followed); the first two rows, where most of retargeting's
+inflation is, stay in both. So crediting the search is not a fix. Read retargeting through the
+report instead of the model:
+
+1. **Acquisition by first touch.** A person's first touch (`user_attribution` in the reference
+   views) is settled long before any retargeting reaches them, so new users and their lifetime
+   value by first channel leave retargeting out by construction. Judge acquisition ROAS there.
+2. **Keep retargeting apart.** Name retargeting campaigns so they can be told apart
+   (`utm_campaign` with an `rt_` prefix, say), and read the session-level attribution of those
+   campaigns split into new and returning people: a high share of returning people is credit that
+   was probably not incremental.
+3. **Measure the increment when the spend justifies it.** A holdout (Meta's Conversion Lift, a
+   geo split) is the only way to answer whether the ad caused the purchase.
+
+Special cases in the model ("an ad clicked by a paying customer does not override") are not
+worth it: the rules get harder to explain, and the first two rows remain.
+
+### Compared with other tools
+
+How other tools credit a visit, as far as their documented defaults go (they change often; check
+the vendor's documentation before relying on a detail):
+
+| Tool                                                | Main model                                                                                                                                                                   | Direct visits                                               | Priority between channels                                         | Window                                                   | Across devices                    |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------- |
+| **GA4**                                             | Data-driven by default; paid and organic last click, and Google paid channels last click, as options                                                                         | Inherit the last non-direct source                          | Only in "Google paid channels last click", for Google Ads         | 30 days (configurable)                                   | Signed-in user id, Google signals |
+| **PostHog**                                         | A session's entry source (`$entry_utm_*`, `$entry_referring_domain`, grouped GA4-style) and a person's first touch (`$initial_*`); funnels break down by first or last touch | A direct session stays direct: no look-back                 | None                                                              | —                                                        | Merged persons via `identify`     |
+| **Mixpanel**                                        | Picked per report: first touch, last touch, linear, U-shaped, time decay, participation                                                                                      | Only events with utm count as touches, so direct is skipped | None                                                              | Configurable look-back                                   | Identity merge                    |
+| **Amplitude**                                       | Initial / latest utm user properties (latest changes only on a new utm), plus multi-touch models                                                                             | Skipped                                                     | None                                                              | Configurable                                             | Identity merge                    |
+| **Adobe Analytics**                                 | Marketing channels classified by ordered processing rules; first and last touch channel with expiry; Attribution IQ models incl. algorithmic                                 | Usually set not to override                                 | **Yes**: per channel, whether it overrides the last touch         | Visit or days, configurable                              | Identity stitching                |
+| **Ad platforms** (Meta, Google Ads, …)              | Each claims the conversions it touched (Meta: 7-day click, 1-day view by default; Google Ads: data-driven)                                                                   | Not their concern                                           | Only themselves, so platforms **claim the same conversion twice** | Their own                                                | Their own accounts                |
+| **Mobile measurement partners** (AppsFlyer, Adjust) | Last click on install, with a **priority hierarchy** (click over view, device id match over probabilistic); organic when nothing in the window                               | Organic install                                             | **Yes**, the core of the model                                    | Click about 7 days, configurable; re-attribution windows | Device                            |
+| **HubSpot**                                         | A contact's original source (first touch) and multi-touch revenue models                                                                                                     | Does not change the first touch                             | None                                                              | —                                                        | Contact                           |
+
+Where this model stands:
+
+| Trait                                                 | Shared with                                                                                                         | Unlike                                                                                 |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Direct visits inherit an earlier source               | GA4, Mixpanel, Amplitude, Adobe — the common ground                                                                 | PostHog's session-level source, which does not look back                               |
+| Channels are ranked, a paid touch over an organic one | **Adobe's override rules, the MMPs' priority hierarchy** — the tools built for marketing and media-buying decisions | The product analytics tools (PostHog, Mixpanel, Amplitude), where every touch is equal |
+| One touch per session                                 | Every first- or last-touch model                                                                                    | Multi-touch models, which split the credit                                             |
+| A first-touch view per person                         | GA4's first user source, PostHog's and Amplitude's initial properties, HubSpot's original source                    | —                                                                                      |
+
+So this is a rule-based last-touch model with channel priority: more favourable to ads than the
+product analytics tools, in the same family as Adobe's and the MMPs' rules. Two consequences to
+expect: a platform's own dashboard will report more conversions than this model credits it with
+(it counts view-through, and every platform claims a shared conversion), and the sum of the
+platforms' own figures exceeds the real total.
+
+### Other models
+
+The touchpoint layer keeps every touch, so other models can be added next to this one as views,
+without changing it:
+
+- **Multi-touch (rule-based)**: the credit of one conversion is split across the touches on its
+  path, by a fixed rule — linear (equal shares), time decay (more to the recent ones), position
+  based (40% first, 40% last, 20% spread over the middle). Useful to see which channels open a
+  journey and which close it; the shares are a convention, not a measurement.
+- **Data-driven (algorithmic)**: a model learns from converting and non-converting paths how much
+  each touch raises the chance of converting (Shapley values or Markov chains), and splits the
+  credit by that. GA4's and Google Ads' default; it needs a large volume of conversions to be
+  stable, and it is still a model of correlation, not of causation.
+- **Incrementality**: only a holdout experiment (a conversion lift study, a geo split) measures
+  what an ad caused. It answers a different question from every model above, and is the one to
+  run when the spend on a channel is large enough to matter.
 
 What the SDK guarantees for this to hold:
 

package/dist/attribution/classify.cjs

@@ -2,6 +2,21 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_attribution_vocabulary = require("./vocabulary.cjs");
 //#region src/attribution/classify.ts
 const metaPlacements = new Set(require_attribution_vocabulary.META_PLACEMENTS);
+/** The groups no one paid for: a campaign rule landing in one of them ranks with a referrer. */
+const ORGANIC_GROUPS = /* @__PURE__ */ new Set([
+	"organic_search",
+	"organic_social",
+	"organic_video",
+	"organic_ai",
+	"referral"
+]);
+/**
+* The groups a campaign rule ranks with a referrer in: the organic ones, and email. Email reaches
+* people we already know — often because an ad brought them — and its links (a welcome mail, a
+* trial reminder) come between that ad and the purchase, so it must not take the ad's credit.
+* With no ad in the window it still wins as the latest touch.
+*/
+const REFERRER_TIER_GROUPS = /* @__PURE__ */ new Set([...ORGANIC_GROUPS, "email"]);
 const referrerHostOf = /^https?:\/\/([^/:?#]+)/i;
 const channelsBy = (medium) => new Set(require_attribution_vocabulary.REFERRER_SITES.filter(([, m]) => m === medium).map(([channel]) => channel));
 const searchChannels = channelsBy("organic");
@@ -20,10 +35,12 @@ function text(tags, key) {
 }
 /**
 * 1. What the campaign said: `utm_source`, with the aliases folded. It comes before the click
-* ids, as in GA4: a utm is written for this link by whoever placed it, while a click id can be
-* added by someone else — Meta puts `fbclid` on organic links too, and a shared or forwarded ad
-* link keeps the click id of the ad. When the two disagree, the utm is the one that was right:
-* an Instagram profile link carrying `fbclid`, a newsletter link copied from an ad.
+* ids — unlike GA4, where a `gclid` wins over the utm unless the property sets "manual tagging
+* overrides auto-tagging": a utm is written for this link by whoever placed it, while a click id
+* can be added by someone else — Meta puts `fbclid` on organic links too, and a shared or
+* forwarded ad link keeps the click id of the ad. When the two disagree, the utm is the one that
+* was right: an Instagram profile link carrying `fbclid`, a newsletter link copied from an ad.
+* The one exception is an ad-only click id of the utm's own channel, see `classifyTouch`.
 */
 function utmChannel(tags) {
 	const source = text(tags, "utm_source")?.toLowerCase().split(/[?&#]/)[0]?.replace(/\/+$/, "");
@@ -107,13 +124,19 @@ function channelGroupOf(channel, medium) {
 * The rules, in order, the first that says something naming the channel: an explicit
 * `utm_source`, a click id, an ad landing page, the product's own rules, the referrer's host;
 * `(direct)` when none does. `medium` is `utm_medium` as declared (lower-cased), else what that
-* rule implies: `(not set)` for a utm_source alone — but `cpc` when an ad-only click id of the
-* same channel came with it (`'ads'` in `CLICK_ID_CHANNELS`) — `cpc` for a bare click id or ad landing page,
+* rule implies: `(not set)` for a utm_source alone, `cpc` for a bare click id or ad landing page,
 * the product rule's own, `organic` / `social` / `video` / `referral` for a referrer, `(none)`
-* for direct. `campaign` is `utm_campaign`, else what a product rule captured — even when the
-* utm named the channel, so a tagged referral link keeps its code. `priority` is the tier of
-* the rule that named the channel (`TOUCH_PRIORITY`): campaign touches, then the product's own
-* as they declare, then the referrer.
+* for direct. An ad-only click id of the channel itself (`'ads'` in `CLICK_ID_CHANNELS`) or its ad
+* landing page makes it `cpc` when the medium was left out or puts the touch in an organic group:
+* the click was paid whatever the tag said — a Reddit ad tagged `utm_medium=social`, a ChatGPT ad
+* keeping the `utm_source=chatgpt.com` of its organic links. `campaign` is `utm_campaign`, else what a
+* product rule captured — even when the utm named the channel, so a tagged referral link keeps
+* its code. `priority` is the tier of the rule that named the channel (`TOUCH_PRIORITY`):
+* campaign touches, then the product's own as they declare, then the referrer — except that a
+* campaign rule whose touch lands in an organic group, referral (`utm_source=chatgpt.com`,
+* `utm_medium=organic`) or email ranks with a referrer: nobody paid for that click, and it should
+* not take the credit from an ad clicked earlier in the attribution window. When a product rule
+* matched too, the stronger of the two tiers holds.
 */
 function classifyTouch(tags, options = {}) {
 	const utm = utmChannel(tags);
@@ -122,15 +145,17 @@ function classifyTouch(tags, options = {}) {
 	const product = productTouch(tags, options.rules ?? []);
 	const referred = referrer(tags, options.ownHosts ?? []);
 	const channel = utm ?? click ?? landing ?? product?.channel ?? referred?.channel ?? "(direct)";
-	const medium = text(tags, "utm_medium")?.toLowerCase() ?? null ?? (utm ? adClickChannel(tags) === utm ? "cpc" : "(not set)" : click || landing ? "cpc" : product?.medium ?? referred?.medium ?? "(none)");
+	const namedMedium = text(tags, "utm_medium")?.toLowerCase() ?? null ?? (utm ? "(not set)" : click || landing ? "cpc" : product?.medium ?? referred?.medium ?? "(none)");
+	const medium = (adClickChannel(tags) === channel || landing === channel) && (namedMedium === "(not set)" || ORGANIC_GROUPS.has(channelGroupOf(channel, namedMedium))) ? "cpc" : namedMedium;
+	const channelGroup = channelGroupOf(channel, medium);
 	const campaign = text(tags, "utm_campaign") ?? product?.campaign ?? null;
-	const priority = utm || click || landing ? require_attribution_vocabulary.TOUCH_PRIORITY.campaign : product ? product.priority : referred ? require_attribution_vocabulary.TOUCH_PRIORITY.referrer : null;
+	const ranked = [utm || click || landing ? REFERRER_TIER_GROUPS.has(channelGroup) ? require_attribution_vocabulary.TOUCH_PRIORITY.referrer : require_attribution_vocabulary.TOUCH_PRIORITY.campaign : null, product?.priority ?? null].filter((tier) => tier !== null);
 	return {
 		channel,
 		medium,
-		channel_group: channelGroupOf(channel, medium),
+		channel_group: channelGroup,
 		campaign,
-		priority
+		priority: ranked.length > 0 ? Math.min(...ranked) : referred ? require_attribution_vocabulary.TOUCH_PRIORITY.referrer : null
 	};
 }
 //#endregion

package/dist/attribution/classify.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"classify.cjs","names":["META_PLACEMENTS","REFERRER_SITES","SOURCE_ALIASES","CLICK_ID_CHANNELS","AD_LANDING_PAGE","REFERRERS_NOT_A_TOUCH","DISPLAY_MEDIUMS","PAID_MEDIUM","EMAIL_MEDIUM","EMAIL_MEDIUMS","TOUCH_PRIORITY"],"sources":["../../src/attribution/classify.ts"],"sourcesContent":["import type { TrackTags } from '../track/types';\nimport {\n  AD_LANDING_PAGE,\n  CLICK_ID_CHANNELS,\n  type ChannelGroup,\n  DIRECT_CHANNEL,\n  DISPLAY_MEDIUMS,\n  EMAIL_MEDIUM,\n  EMAIL_MEDIUMS,\n  MEDIUM_NOT_SET,\n  META_PLACEMENTS,\n  NO_MEDIUM,\n  PAID_MEDIUM,\n  REFERRERS_NOT_A_TOUCH,\n  REFERRER_SITES,\n  SOURCE_ALIASES,\n  TOUCH_PRIORITY,\n} from './vocabulary';\n\n/** What a session's tags say about how it arrived: the touch, as the session row stores it. */\nexport interface Touch {\n  /** The source, as GA calls it: a `Channel`, a `utm_source` outside the list, a referring host, or `(direct)`. */\n  channel: string;\n  /** How, as GA calls it: `utm_medium` as declared, else what the rule that named the channel implies; `(none)` for direct. */\n  medium: string;\n  /** GA4's default channel group of the two. */\n  channel_group: ChannelGroup;\n  /** `utm_campaign`, else what a product rule captured (a referral code); null when neither. */\n  campaign: string | null;\n  /** `TOUCH_PRIORITY` of the rule that named the channel; null for direct, which is no touch. */\n  priority: number | null;\n}\n\n/** What a product rule names, when it recognises the session; the channel group is derived. */\nexport type ProductTouch = Omit<Touch, 'channel_group'>;\n\n/**\n * A product's own rule: a landing page convention, a code in the URL. Tried after the campaign\n * rules (utm, click id, ad landing page) and before the referrer, so a link shared on Facebook\n * or WhatsApp is credited to what the product recognises, not to the site it was shared on.\n * Returns null when the session is not one of its.\n */\nexport type TouchRule = (tags: TrackTags) => ProductTouch | null;\n\nexport interface ClassifyOptions {\n  /**\n   * The product's own hosts, as patterns over the lower-cased referrer host: a session that\n   * starts from an internal link after the session timeout refers to them, which is navigation,\n   * not acquisition. The SDK adds the payment and sign-in providers (`REFERRERS_NOT_A_TOUCH`).\n   */\n  ownHosts?: readonly RegExp[];\n  /** The product's rules, in order; the first that names the session wins. */\n  rules?: readonly TouchRule[];\n}\n\nconst metaPlacements = new Set<string>(META_PLACEMENTS);\nconst referrerHostOf = /^https?:\\/\\/([^/:?#]+)/i;\nconst channelsBy = (medium: string) =>\n  new Set<string>(REFERRER_SITES.filter(([, m]) => m === medium).map(([channel]) => channel));\nconst searchChannels = channelsBy('organic');\nconst socialChannels = channelsBy('social');\nconst videoChannels = channelsBy('video');\nconst aiChannels = channelsBy('ai');\n\n/**\n * A tag as text; absent when missing, empty, or the strings a broken template writes\n * (`undefined`, `null`, an unexpanded `{{macro}}` other than Meta's placement, read elsewhere).\n */\nfunction text(tags: TrackTags, key: string): string | null {\n  const value = tags[key];\n  if (value === undefined || value === null) return null;\n  const s = String(value);\n  return s === '' || s === 'undefined' || s === 'null' ? null : s;\n}\n\n/**\n * 1. What the campaign said: `utm_source`, with the aliases folded. It comes before the click\n * ids, as in GA4: a utm is written for this link by whoever placed it, while a click id can be\n * added by someone else — Meta puts `fbclid` on organic links too, and a shared or forwarded ad\n * link keeps the click id of the ad. When the two disagree, the utm is the one that was right:\n * an Instagram profile link carrying `fbclid`, a newsletter link copied from an ad.\n */\nfunction utmChannel(tags: TrackTags): string | null {\n  // A source with the rest of the query glued on (`email&utm_medium=promo`, `toolify/`,\n  // `x?utm_source=x`): a link built by hand or double-encoded. Keep the source.\n  const source = text(tags, 'utm_source')?.toLowerCase().split(/[?&#]/)[0]?.replace(/\\/+$/, '');\n  if (!source) return null;\n  return (SOURCE_ALIASES as Record<string, string>)[source] ?? source;\n}\n\n/**\n * 2. A click id in this page's URL — the tags never fill one from the cookie an earlier click\n * left (that is `_gcl_aw`, `_fbc`, …). Presence of the key is the signal, as it is for the pixel\n * that reads it.\n */\nfunction clickChannel(tags: TrackTags): string | null {\n  return CLICK_ID_CHANNELS.find(([key]) => key in tags)?.[1] ?? null;\n}\n\n/** The channel of the first click id in the tags that its platform puts on ad clicks only. */\nfunction adClickChannel(tags: TrackTags): string | null {\n  return CLICK_ID_CHANNELS.find(([key, , on]) => on === 'ads' && key in tags)?.[1] ?? null;\n}\n\n/** 3. A landing page reserved for one channel's ads. */\nfunction landingChannel(tags: TrackTags): string | null {\n  const location = text(tags, 'page_location');\n  return location ? (AD_LANDING_PAGE.exec(location)?.[1] ?? null) : null;\n}\n\n/** 4. The product's rules, in order. */\nfunction productTouch(tags: TrackTags, rules: readonly TouchRule[]): ProductTouch | null {\n  for (const rule of rules) {\n    const touch = rule(tags);\n    if (touch) return touch;\n  }\n  return null;\n}\n\n/**\n * 5. The referrer's host: a known search engine or social network folded to its channel, any\n * other site kept as its host, and null for no referrer or one that is no touch.\n */\nfunction referrer(\n  tags: TrackTags,\n  ownHosts: readonly RegExp[]\n): { channel: string; medium: string } | null {\n  const url = text(tags, 'page_referrer');\n  const host = url ? referrerHostOf.exec(url)?.[1]?.toLowerCase() : undefined;\n  if (!host) return null;\n  if (REFERRERS_NOT_A_TOUCH.some((pattern) => pattern.test(host))) return null;\n  if (ownHosts.some((pattern) => pattern.test(host))) return null;\n  const site = REFERRER_SITES.find(([, , pattern]) => pattern.test(host));\n  return site ? { channel: site[0], medium: site[1] } : { channel: host, medium: 'referral' };\n}\n\n/**\n * GA4's default channel group of a (channel, medium) pair, with GA4's rule that the source\n * decides too: `linkedin / (not set)` is Organic Social and `email / promo` is Email, because\n * GA4 matches its site lists on the source, not only the medium. Two additions to GA4: Meta's\n * placement names as a medium are a paid Meta click (see `META_PLACEMENTS`), and the AI\n * assistants have `organic_ai`. Checked in GA4's order — paid before organic, the organic groups before\n * email, referral last — so a pair that fits two rules lands where GA4 would put it.\n */\nexport function channelGroupOf(channel: string, medium: string): ChannelGroup {\n  if (channel === DIRECT_CHANNEL) return 'direct';\n  if ((DISPLAY_MEDIUMS as readonly string[]).includes(medium)) return 'display';\n  // A Meta placement as the medium is a Meta ad whatever the source was tagged as.\n  if (metaPlacements.has(medium)) return 'paid_social';\n  if (PAID_MEDIUM.test(medium)) {\n    if (socialChannels.has(channel) || videoChannels.has(channel)) return 'paid_social';\n    if (searchChannels.has(channel)) return 'paid_search';\n    return 'paid_other';\n  }\n  if (medium === 'social' || socialChannels.has(channel)) return 'organic_social';\n  if (medium === 'video' || videoChannels.has(channel)) return 'organic_video';\n  if (medium === 'ai' || aiChannels.has(channel)) return 'organic_ai';\n  if (medium === 'organic' || searchChannels.has(channel)) return 'organic_search';\n  if (EMAIL_MEDIUM.test(medium) || (EMAIL_MEDIUMS as readonly string[]).includes(channel))\n    return 'email';\n  if (medium === 'affiliate') return 'affiliate';\n  if (medium === 'referral') return 'referral';\n  return 'unassigned';\n}\n\n/**\n * Reads the tags a session arrived with (its `session_start` tags) as one touch. Run once, when\n * the session is written; the result is stored, and the views only read it.\n *\n * The rules, in order, the first that says something naming the channel: an explicit\n * `utm_source`, a click id, an ad landing page, the product's own rules, the referrer's host;\n * `(direct)` when none does. `medium` is `utm_medium` as declared (lower-cased), else what that\n * rule implies: `(not set)` for a utm_source alone — but `cpc` when an ad-only click id of the\n * same channel came with it (`'ads'` in `CLICK_ID_CHANNELS`) — `cpc` for a bare click id or ad landing page,\n * the product rule's own, `organic` / `social` / `video` / `referral` for a referrer, `(none)`\n * for direct. `campaign` is `utm_campaign`, else what a product rule captured — even when the\n * utm named the channel, so a tagged referral link keeps its code. `priority` is the tier of\n * the rule that named the channel (`TOUCH_PRIORITY`): campaign touches, then the product's own\n * as they declare, then the referrer.\n */\nexport function classifyTouch(tags: TrackTags, options: ClassifyOptions = {}): Touch {\n  const utm = utmChannel(tags);\n  const click = clickChannel(tags);\n  const landing = landingChannel(tags);\n  const product = productTouch(tags, options.rules ?? []);\n  const referred = referrer(tags, options.ownHosts ?? []);\n\n  const channel =\n    utm ?? click ?? landing ?? product?.channel ?? referred?.channel ?? DIRECT_CHANNEL;\n  const declaredMedium = text(tags, 'utm_medium')?.toLowerCase() ?? null;\n  const medium =\n    declaredMedium ??\n    (utm\n      ? adClickChannel(tags) === utm\n        ? 'cpc'\n        : MEDIUM_NOT_SET\n      : click || landing\n        ? 'cpc'\n        : (product?.medium ?? referred?.medium ?? NO_MEDIUM));\n  const campaign = text(tags, 'utm_campaign') ?? product?.campaign ?? null;\n  const priority =\n    utm || click || landing\n      ? TOUCH_PRIORITY.campaign\n      : product\n        ? product.priority\n        : referred\n          ? TOUCH_PRIORITY.referrer\n          : null;\n\n  return { channel, medium, channel_group: channelGroupOf(channel, medium), campaign, priority };\n}\n"],"mappings":"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"}
+{"version":3,"file":"classify.cjs","names":["META_PLACEMENTS","REFERRER_SITES","SOURCE_ALIASES","CLICK_ID_CHANNELS","AD_LANDING_PAGE","REFERRERS_NOT_A_TOUCH","DISPLAY_MEDIUMS","PAID_MEDIUM","EMAIL_MEDIUM","EMAIL_MEDIUMS","TOUCH_PRIORITY"],"sources":["../../src/attribution/classify.ts"],"sourcesContent":["import type { TrackTags } from '../track/types';\nimport {\n  AD_LANDING_PAGE,\n  CLICK_ID_CHANNELS,\n  type ChannelGroup,\n  DIRECT_CHANNEL,\n  DISPLAY_MEDIUMS,\n  EMAIL_MEDIUM,\n  EMAIL_MEDIUMS,\n  MEDIUM_NOT_SET,\n  META_PLACEMENTS,\n  NO_MEDIUM,\n  PAID_MEDIUM,\n  REFERRERS_NOT_A_TOUCH,\n  REFERRER_SITES,\n  SOURCE_ALIASES,\n  TOUCH_PRIORITY,\n} from './vocabulary';\n\n/** What a session's tags say about how it arrived: the touch, as the session row stores it. */\nexport interface Touch {\n  /** The source, as GA calls it: a `Channel`, a `utm_source` outside the list, a referring host, or `(direct)`. */\n  channel: string;\n  /** How, as GA calls it: `utm_medium` as declared, else what the rule that named the channel implies; `(none)` for direct. */\n  medium: string;\n  /** GA4's default channel group of the two. */\n  channel_group: ChannelGroup;\n  /** `utm_campaign`, else what a product rule captured (a referral code); null when neither. */\n  campaign: string | null;\n  /** `TOUCH_PRIORITY` of the rule that named the channel; null for direct, which is no touch. */\n  priority: number | null;\n}\n\n/** What a product rule names, when it recognises the session; the channel group is derived. */\nexport type ProductTouch = Omit<Touch, 'channel_group'>;\n\n/**\n * A product's own rule: a landing page convention, a code in the URL. Tried after the campaign\n * rules (utm, click id, ad landing page) and before the referrer, so a link shared on Facebook\n * or WhatsApp is credited to what the product recognises, not to the site it was shared on.\n * Returns null when the session is not one of its.\n */\nexport type TouchRule = (tags: TrackTags) => ProductTouch | null;\n\nexport interface ClassifyOptions {\n  /**\n   * The product's own hosts, as patterns over the lower-cased referrer host: a session that\n   * starts from an internal link after the session timeout refers to them, which is navigation,\n   * not acquisition. The SDK adds the payment and sign-in providers (`REFERRERS_NOT_A_TOUCH`).\n   */\n  ownHosts?: readonly RegExp[];\n  /** The product's rules, in order; the first that names the session wins. */\n  rules?: readonly TouchRule[];\n}\n\nconst metaPlacements = new Set<string>(META_PLACEMENTS);\n/** The groups no one paid for: a campaign rule landing in one of them ranks with a referrer. */\nconst ORGANIC_GROUPS = new Set<ChannelGroup>([\n  'organic_search',\n  'organic_social',\n  'organic_video',\n  'organic_ai',\n  'referral',\n]);\n/**\n * The groups a campaign rule ranks with a referrer in: the organic ones, and email. Email reaches\n * people we already know — often because an ad brought them — and its links (a welcome mail, a\n * trial reminder) come between that ad and the purchase, so it must not take the ad's credit.\n * With no ad in the window it still wins as the latest touch.\n */\nconst REFERRER_TIER_GROUPS = new Set<ChannelGroup>([...ORGANIC_GROUPS, 'email']);\nconst referrerHostOf = /^https?:\\/\\/([^/:?#]+)/i;\nconst channelsBy = (medium: string) =>\n  new Set<string>(REFERRER_SITES.filter(([, m]) => m === medium).map(([channel]) => channel));\nconst searchChannels = channelsBy('organic');\nconst socialChannels = channelsBy('social');\nconst videoChannels = channelsBy('video');\nconst aiChannels = channelsBy('ai');\n\n/**\n * A tag as text; absent when missing, empty, or the strings a broken template writes\n * (`undefined`, `null`, an unexpanded `{{macro}}` other than Meta's placement, read elsewhere).\n */\nfunction text(tags: TrackTags, key: string): string | null {\n  const value = tags[key];\n  if (value === undefined || value === null) return null;\n  const s = String(value);\n  return s === '' || s === 'undefined' || s === 'null' ? null : s;\n}\n\n/**\n * 1. What the campaign said: `utm_source`, with the aliases folded. It comes before the click\n * ids — unlike GA4, where a `gclid` wins over the utm unless the property sets \"manual tagging\n * overrides auto-tagging\": a utm is written for this link by whoever placed it, while a click id\n * can be added by someone else — Meta puts `fbclid` on organic links too, and a shared or\n * forwarded ad link keeps the click id of the ad. When the two disagree, the utm is the one that\n * was right: an Instagram profile link carrying `fbclid`, a newsletter link copied from an ad.\n * The one exception is an ad-only click id of the utm's own channel, see `classifyTouch`.\n */\nfunction utmChannel(tags: TrackTags): string | null {\n  // A source with the rest of the query glued on (`email&utm_medium=promo`, `toolify/`,\n  // `x?utm_source=x`): a link built by hand or double-encoded. Keep the source.\n  const source = text(tags, 'utm_source')?.toLowerCase().split(/[?&#]/)[0]?.replace(/\\/+$/, '');\n  if (!source) return null;\n  return (SOURCE_ALIASES as Record<string, string>)[source] ?? source;\n}\n\n/**\n * 2. A click id in this page's URL — the tags never fill one from the cookie an earlier click\n * left (that is `_gcl_aw`, `_fbc`, …). Presence of the key is the signal, as it is for the pixel\n * that reads it.\n */\nfunction clickChannel(tags: TrackTags): string | null {\n  return CLICK_ID_CHANNELS.find(([key]) => key in tags)?.[1] ?? null;\n}\n\n/** The channel of the first click id in the tags that its platform puts on ad clicks only. */\nfunction adClickChannel(tags: TrackTags): string | null {\n  return CLICK_ID_CHANNELS.find(([key, , on]) => on === 'ads' && key in tags)?.[1] ?? null;\n}\n\n/** 3. A landing page reserved for one channel's ads. */\nfunction landingChannel(tags: TrackTags): string | null {\n  const location = text(tags, 'page_location');\n  return location ? (AD_LANDING_PAGE.exec(location)?.[1] ?? null) : null;\n}\n\n/** 4. The product's rules, in order. */\nfunction productTouch(tags: TrackTags, rules: readonly TouchRule[]): ProductTouch | null {\n  for (const rule of rules) {\n    const touch = rule(tags);\n    if (touch) return touch;\n  }\n  return null;\n}\n\n/**\n * 5. The referrer's host: a known search engine or social network folded to its channel, any\n * other site kept as its host, and null for no referrer or one that is no touch.\n */\nfunction referrer(\n  tags: TrackTags,\n  ownHosts: readonly RegExp[]\n): { channel: string; medium: string } | null {\n  const url = text(tags, 'page_referrer');\n  const host = url ? referrerHostOf.exec(url)?.[1]?.toLowerCase() : undefined;\n  if (!host) return null;\n  if (REFERRERS_NOT_A_TOUCH.some((pattern) => pattern.test(host))) return null;\n  if (ownHosts.some((pattern) => pattern.test(host))) return null;\n  const site = REFERRER_SITES.find(([, , pattern]) => pattern.test(host));\n  return site ? { channel: site[0], medium: site[1] } : { channel: host, medium: 'referral' };\n}\n\n/**\n * GA4's default channel group of a (channel, medium) pair, with GA4's rule that the source\n * decides too: `linkedin / (not set)` is Organic Social and `email / promo` is Email, because\n * GA4 matches its site lists on the source, not only the medium. Two additions to GA4: Meta's\n * placement names as a medium are a paid Meta click (see `META_PLACEMENTS`), and the AI\n * assistants have `organic_ai`. Checked in GA4's order — paid before organic, the organic groups before\n * email, referral last — so a pair that fits two rules lands where GA4 would put it.\n */\nexport function channelGroupOf(channel: string, medium: string): ChannelGroup {\n  if (channel === DIRECT_CHANNEL) return 'direct';\n  if ((DISPLAY_MEDIUMS as readonly string[]).includes(medium)) return 'display';\n  // A Meta placement as the medium is a Meta ad whatever the source was tagged as.\n  if (metaPlacements.has(medium)) return 'paid_social';\n  if (PAID_MEDIUM.test(medium)) {\n    if (socialChannels.has(channel) || videoChannels.has(channel)) return 'paid_social';\n    if (searchChannels.has(channel)) return 'paid_search';\n    return 'paid_other';\n  }\n  if (medium === 'social' || socialChannels.has(channel)) return 'organic_social';\n  if (medium === 'video' || videoChannels.has(channel)) return 'organic_video';\n  if (medium === 'ai' || aiChannels.has(channel)) return 'organic_ai';\n  if (medium === 'organic' || searchChannels.has(channel)) return 'organic_search';\n  if (EMAIL_MEDIUM.test(medium) || (EMAIL_MEDIUMS as readonly string[]).includes(channel))\n    return 'email';\n  if (medium === 'affiliate') return 'affiliate';\n  if (medium === 'referral') return 'referral';\n  return 'unassigned';\n}\n\n/**\n * Reads the tags a session arrived with (its `session_start` tags) as one touch. Run once, when\n * the session is written; the result is stored, and the views only read it.\n *\n * The rules, in order, the first that says something naming the channel: an explicit\n * `utm_source`, a click id, an ad landing page, the product's own rules, the referrer's host;\n * `(direct)` when none does. `medium` is `utm_medium` as declared (lower-cased), else what that\n * rule implies: `(not set)` for a utm_source alone, `cpc` for a bare click id or ad landing page,\n * the product rule's own, `organic` / `social` / `video` / `referral` for a referrer, `(none)`\n * for direct. An ad-only click id of the channel itself (`'ads'` in `CLICK_ID_CHANNELS`) or its ad\n * landing page makes it `cpc` when the medium was left out or puts the touch in an organic group:\n * the click was paid whatever the tag said — a Reddit ad tagged `utm_medium=social`, a ChatGPT ad\n * keeping the `utm_source=chatgpt.com` of its organic links. `campaign` is `utm_campaign`, else what a\n * product rule captured — even when the utm named the channel, so a tagged referral link keeps\n * its code. `priority` is the tier of the rule that named the channel (`TOUCH_PRIORITY`):\n * campaign touches, then the product's own as they declare, then the referrer — except that a\n * campaign rule whose touch lands in an organic group, referral (`utm_source=chatgpt.com`,\n * `utm_medium=organic`) or email ranks with a referrer: nobody paid for that click, and it should\n * not take the credit from an ad clicked earlier in the attribution window. When a product rule\n * matched too, the stronger of the two tiers holds.\n */\nexport function classifyTouch(tags: TrackTags, options: ClassifyOptions = {}): Touch {\n  const utm = utmChannel(tags);\n  const click = clickChannel(tags);\n  const landing = landingChannel(tags);\n  const product = productTouch(tags, options.rules ?? []);\n  const referred = referrer(tags, options.ownHosts ?? []);\n\n  const channel =\n    utm ?? click ?? landing ?? product?.channel ?? referred?.channel ?? DIRECT_CHANNEL;\n  const declaredMedium = text(tags, 'utm_medium')?.toLowerCase() ?? null;\n  const namedMedium =\n    declaredMedium ??\n    (utm\n      ? MEDIUM_NOT_SET\n      : click || landing\n        ? 'cpc'\n        : (product?.medium ?? referred?.medium ?? NO_MEDIUM));\n  // What proves a paid click on this channel: an ad-only click id of it, or its ad landing page.\n  // Another channel's says nothing about this one (an ad link copied and shared under a utm of\n  // its own), and `fbclid` is on organic Meta links too, so neither counts here.\n  const paid = adClickChannel(tags) === channel || landing === channel;\n  const medium =\n    paid &&\n    (namedMedium === MEDIUM_NOT_SET || ORGANIC_GROUPS.has(channelGroupOf(channel, namedMedium)))\n      ? 'cpc'\n      : namedMedium;\n  const channelGroup = channelGroupOf(channel, medium);\n  const campaign = text(tags, 'utm_campaign') ?? product?.campaign ?? null;\n  const campaignTier =\n    utm || click || landing\n      ? REFERRER_TIER_GROUPS.has(channelGroup)\n        ? TOUCH_PRIORITY.referrer\n        : TOUCH_PRIORITY.campaign\n      : null;\n  // The stronger of the campaign rule's tier and the product rule's own: a referral link shared\n  // under `utm_source=whatsapp` is named by the utm, and still ranks as the programme declares.\n  const ranked = [campaignTier, product?.priority ?? null].filter((tier) => tier !== null);\n  const priority =\n    ranked.length > 0 ? Math.min(...ranked) : referred ? TOUCH_PRIORITY.referrer : null;\n\n  return { channel, medium, channel_group: channelGroup, campaign, priority };\n}\n"],"mappings":"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"}

package/dist/attribution/classify.d.cts

@@ -49,13 +49,19 @@ export declare function channelGroupOf(channel: string, medium: string): Channel
  * The rules, in order, the first that says something naming the channel: an explicit
  * `utm_source`, a click id, an ad landing page, the product's own rules, the referrer's host;
  * `(direct)` when none does. `medium` is `utm_medium` as declared (lower-cased), else what that
- * rule implies: `(not set)` for a utm_source alone — but `cpc` when an ad-only click id of the
- * same channel came with it (`'ads'` in `CLICK_ID_CHANNELS`) — `cpc` for a bare click id or ad landing page,
+ * rule implies: `(not set)` for a utm_source alone, `cpc` for a bare click id or ad landing page,
  * the product rule's own, `organic` / `social` / `video` / `referral` for a referrer, `(none)`
- * for direct. `campaign` is `utm_campaign`, else what a product rule captured — even when the
- * utm named the channel, so a tagged referral link keeps its code. `priority` is the tier of
- * the rule that named the channel (`TOUCH_PRIORITY`): campaign touches, then the product's own
- * as they declare, then the referrer.
+ * for direct. An ad-only click id of the channel itself (`'ads'` in `CLICK_ID_CHANNELS`) or its ad
+ * landing page makes it `cpc` when the medium was left out or puts the touch in an organic group:
+ * the click was paid whatever the tag said — a Reddit ad tagged `utm_medium=social`, a ChatGPT ad
+ * keeping the `utm_source=chatgpt.com` of its organic links. `campaign` is `utm_campaign`, else what a
+ * product rule captured — even when the utm named the channel, so a tagged referral link keeps
+ * its code. `priority` is the tier of the rule that named the channel (`TOUCH_PRIORITY`):
+ * campaign touches, then the product's own as they declare, then the referrer — except that a
+ * campaign rule whose touch lands in an organic group, referral (`utm_source=chatgpt.com`,
+ * `utm_medium=organic`) or email ranks with a referrer: nobody paid for that click, and it should
+ * not take the credit from an ad clicked earlier in the attribution window. When a product rule
+ * matched too, the stronger of the two tiers holds.
  */
 export declare function classifyTouch(tags: TrackTags, options?: ClassifyOptions): Touch;
 //#endregion

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

@@ -1 +1 @@
-{"version":3,"file":"classify.d.cts","names":[],"sources":["../../src/attribution/classify.ts"],"mappings":";;;;iBAoBiB;;EAEf;;EAEA;;EAEA,eAAe;;EAEf;;EAEA;;;YAIU,eAAe,KAAK;;;;;;;YAQpB,aAAa,MAAM,cAAc;iBAE5B;;;;;;EAMf,oBAAoB;;EAEpB,iBAAiB;;;;;;;;;;wBA4FH,eAAe,iBAAiB,iBAAiB;;;;;;;;;;;;;;;;wBAoCjD,cAAc,MAAM,WAAW,UAAS,kBAAuB"}
+{"version":3,"file":"classify.d.cts","names":[],"sources":["../../src/attribution/classify.ts"],"mappings":";;;;iBAoBiB;;EAEf;;EAEA;;EAEA,eAAe;;EAEf;;EAEA;;;YAIU,eAAe,KAAK;;;;;;;YAQpB,aAAa,MAAM,cAAc;iBAE5B;;;;;;EAMf,oBAAoB;;EAEpB,iBAAiB;;;;;;;;;;wBA6GH,eAAe,iBAAiB,iBAAiB;;;;;;;;;;;;;;;;;;;;;;wBA0CjD,cAAc,MAAM,WAAW,UAAS,kBAAuB"}

package/dist/attribution/classify.d.mts

@@ -49,13 +49,19 @@ export declare function channelGroupOf(channel: string, medium: string): Channel
  * The rules, in order, the first that says something naming the channel: an explicit
  * `utm_source`, a click id, an ad landing page, the product's own rules, the referrer's host;
  * `(direct)` when none does. `medium` is `utm_medium` as declared (lower-cased), else what that
- * rule implies: `(not set)` for a utm_source alone — but `cpc` when an ad-only click id of the
- * same channel came with it (`'ads'` in `CLICK_ID_CHANNELS`) — `cpc` for a bare click id or ad landing page,
+ * rule implies: `(not set)` for a utm_source alone, `cpc` for a bare click id or ad landing page,
  * the product rule's own, `organic` / `social` / `video` / `referral` for a referrer, `(none)`
- * for direct. `campaign` is `utm_campaign`, else what a product rule captured — even when the
- * utm named the channel, so a tagged referral link keeps its code. `priority` is the tier of
- * the rule that named the channel (`TOUCH_PRIORITY`): campaign touches, then the product's own
- * as they declare, then the referrer.
+ * for direct. An ad-only click id of the channel itself (`'ads'` in `CLICK_ID_CHANNELS`) or its ad
+ * landing page makes it `cpc` when the medium was left out or puts the touch in an organic group:
+ * the click was paid whatever the tag said — a Reddit ad tagged `utm_medium=social`, a ChatGPT ad
+ * keeping the `utm_source=chatgpt.com` of its organic links. `campaign` is `utm_campaign`, else what a
+ * product rule captured — even when the utm named the channel, so a tagged referral link keeps
+ * its code. `priority` is the tier of the rule that named the channel (`TOUCH_PRIORITY`):
+ * campaign touches, then the product's own as they declare, then the referrer — except that a
+ * campaign rule whose touch lands in an organic group, referral (`utm_source=chatgpt.com`,
+ * `utm_medium=organic`) or email ranks with a referrer: nobody paid for that click, and it should
+ * not take the credit from an ad clicked earlier in the attribution window. When a product rule
+ * matched too, the stronger of the two tiers holds.
  */
 export declare function classifyTouch(tags: TrackTags, options?: ClassifyOptions): Touch;
 //#endregion

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

@@ -1 +1 @@
-{"version":3,"file":"classify.d.mts","names":[],"sources":["../../src/attribution/classify.ts"],"mappings":";;;;iBAoBiB;;EAEf;;EAEA;;EAEA,eAAe;;EAEf;;EAEA;;;YAIU,eAAe,KAAK;;;;;;;YAQpB,aAAa,MAAM,cAAc;iBAE5B;;;;;;EAMf,oBAAoB;;EAEpB,iBAAiB;;;;;;;;;;wBA4FH,eAAe,iBAAiB,iBAAiB;;;;;;;;;;;;;;;;wBAoCjD,cAAc,MAAM,WAAW,UAAS,kBAAuB"}
+{"version":3,"file":"classify.d.mts","names":[],"sources":["../../src/attribution/classify.ts"],"mappings":";;;;iBAoBiB;;EAEf;;EAEA;;EAEA,eAAe;;EAEf;;EAEA;;;YAIU,eAAe,KAAK;;;;;;;YAQpB,aAAa,MAAM,cAAc;iBAE5B;;;;;;EAMf,oBAAoB;;EAEpB,iBAAiB;;;;;;;;;;wBA6GH,eAAe,iBAAiB,iBAAiB;;;;;;;;;;;;;;;;;;;;;;wBA0CjD,cAAc,MAAM,WAAW,UAAS,kBAAuB"}

package/dist/attribution/classify.mjs

@@ -1,6 +1,21 @@
 import { AD_LANDING_PAGE, CLICK_ID_CHANNELS, DISPLAY_MEDIUMS, EMAIL_MEDIUM, EMAIL_MEDIUMS, META_PLACEMENTS, PAID_MEDIUM, REFERRERS_NOT_A_TOUCH, REFERRER_SITES, SOURCE_ALIASES, TOUCH_PRIORITY } from "./vocabulary.mjs";
 //#region src/attribution/classify.ts
 const metaPlacements = new Set(META_PLACEMENTS);
+/** The groups no one paid for: a campaign rule landing in one of them ranks with a referrer. */
+const ORGANIC_GROUPS = /* @__PURE__ */ new Set([
+	"organic_search",
+	"organic_social",
+	"organic_video",
+	"organic_ai",
+	"referral"
+]);
+/**
+* The groups a campaign rule ranks with a referrer in: the organic ones, and email. Email reaches
+* people we already know — often because an ad brought them — and its links (a welcome mail, a
+* trial reminder) come between that ad and the purchase, so it must not take the ad's credit.
+* With no ad in the window it still wins as the latest touch.
+*/
+const REFERRER_TIER_GROUPS = /* @__PURE__ */ new Set([...ORGANIC_GROUPS, "email"]);
 const referrerHostOf = /^https?:\/\/([^/:?#]+)/i;
 const channelsBy = (medium) => new Set(REFERRER_SITES.filter(([, m]) => m === medium).map(([channel]) => channel));
 const searchChannels = channelsBy("organic");
@@ -19,10 +34,12 @@ function text(tags, key) {
 }
 /**
 * 1. What the campaign said: `utm_source`, with the aliases folded. It comes before the click
-* ids, as in GA4: a utm is written for this link by whoever placed it, while a click id can be
-* added by someone else — Meta puts `fbclid` on organic links too, and a shared or forwarded ad
-* link keeps the click id of the ad. When the two disagree, the utm is the one that was right:
-* an Instagram profile link carrying `fbclid`, a newsletter link copied from an ad.
+* ids — unlike GA4, where a `gclid` wins over the utm unless the property sets "manual tagging
+* overrides auto-tagging": a utm is written for this link by whoever placed it, while a click id
+* can be added by someone else — Meta puts `fbclid` on organic links too, and a shared or
+* forwarded ad link keeps the click id of the ad. When the two disagree, the utm is the one that
+* was right: an Instagram profile link carrying `fbclid`, a newsletter link copied from an ad.
+* The one exception is an ad-only click id of the utm's own channel, see `classifyTouch`.
 */
 function utmChannel(tags) {
 	const source = text(tags, "utm_source")?.toLowerCase().split(/[?&#]/)[0]?.replace(/\/+$/, "");
@@ -106,13 +123,19 @@ function channelGroupOf(channel, medium) {
 * The rules, in order, the first that says something naming the channel: an explicit
 * `utm_source`, a click id, an ad landing page, the product's own rules, the referrer's host;
 * `(direct)` when none does. `medium` is `utm_medium` as declared (lower-cased), else what that
-* rule implies: `(not set)` for a utm_source alone — but `cpc` when an ad-only click id of the
-* same channel came with it (`'ads'` in `CLICK_ID_CHANNELS`) — `cpc` for a bare click id or ad landing page,
+* rule implies: `(not set)` for a utm_source alone, `cpc` for a bare click id or ad landing page,
 * the product rule's own, `organic` / `social` / `video` / `referral` for a referrer, `(none)`
-* for direct. `campaign` is `utm_campaign`, else what a product rule captured — even when the
-* utm named the channel, so a tagged referral link keeps its code. `priority` is the tier of
-* the rule that named the channel (`TOUCH_PRIORITY`): campaign touches, then the product's own
-* as they declare, then the referrer.
+* for direct. An ad-only click id of the channel itself (`'ads'` in `CLICK_ID_CHANNELS`) or its ad
+* landing page makes it `cpc` when the medium was left out or puts the touch in an organic group:
+* the click was paid whatever the tag said — a Reddit ad tagged `utm_medium=social`, a ChatGPT ad
+* keeping the `utm_source=chatgpt.com` of its organic links. `campaign` is `utm_campaign`, else what a
+* product rule captured — even when the utm named the channel, so a tagged referral link keeps
+* its code. `priority` is the tier of the rule that named the channel (`TOUCH_PRIORITY`):
+* campaign touches, then the product's own as they declare, then the referrer — except that a
+* campaign rule whose touch lands in an organic group, referral (`utm_source=chatgpt.com`,
+* `utm_medium=organic`) or email ranks with a referrer: nobody paid for that click, and it should
+* not take the credit from an ad clicked earlier in the attribution window. When a product rule
+* matched too, the stronger of the two tiers holds.
 */
 function classifyTouch(tags, options = {}) {
 	const utm = utmChannel(tags);
@@ -121,15 +144,17 @@ function classifyTouch(tags, options = {}) {
 	const product = productTouch(tags, options.rules ?? []);
 	const referred = referrer(tags, options.ownHosts ?? []);
 	const channel = utm ?? click ?? landing ?? product?.channel ?? referred?.channel ?? "(direct)";
-	const medium = text(tags, "utm_medium")?.toLowerCase() ?? null ?? (utm ? adClickChannel(tags) === utm ? "cpc" : "(not set)" : click || landing ? "cpc" : product?.medium ?? referred?.medium ?? "(none)");
+	const namedMedium = text(tags, "utm_medium")?.toLowerCase() ?? null ?? (utm ? "(not set)" : click || landing ? "cpc" : product?.medium ?? referred?.medium ?? "(none)");
+	const medium = (adClickChannel(tags) === channel || landing === channel) && (namedMedium === "(not set)" || ORGANIC_GROUPS.has(channelGroupOf(channel, namedMedium))) ? "cpc" : namedMedium;
+	const channelGroup = channelGroupOf(channel, medium);
 	const campaign = text(tags, "utm_campaign") ?? product?.campaign ?? null;
-	const priority = utm || click || landing ? TOUCH_PRIORITY.campaign : product ? product.priority : referred ? TOUCH_PRIORITY.referrer : null;
+	const ranked = [utm || click || landing ? REFERRER_TIER_GROUPS.has(channelGroup) ? TOUCH_PRIORITY.referrer : TOUCH_PRIORITY.campaign : null, product?.priority ?? null].filter((tier) => tier !== null);
 	return {
 		channel,
 		medium,
-		channel_group: channelGroupOf(channel, medium),
+		channel_group: channelGroup,
 		campaign,
-		priority
+		priority: ranked.length > 0 ? Math.min(...ranked) : referred ? TOUCH_PRIORITY.referrer : null
 	};
 }
 //#endregion