@canonry/canonry 4.177.1 → 4.177.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/assets/agent-workspace/skills/canonry/references/server-side-traffic.md +92 -57
  2. package/package.json +12 -12
package/assets/agent-workspace/skills/canonry/references/server-side-traffic.md CHANGED
@@ -72,21 +72,17 @@ sync flow does NOT echo the private key back in any response.
72
72
  ## Connecting a WordPress source
73
73
 
74
74
  The WordPress adapter pulls events from the **Canonry Traffic Logger**
75
- WordPress plugin, which captures every non-admin GET page-load **that
76
- reaches PHP** and exposes a paginated REST endpoint protected by an
77
- Application Password.
78
-
79
- > **Cache blind spot.** The plugin is a PHP hook, so it only sees
80
- > requests that execute WordPress. A full-page cache (LiteSpeed, WP
81
- > Rocket, W3 Total Cache, WP Super Cache) or CDN serves cached pages
82
- > before PHP runs, so cache-served page views, including live AI
83
- > user-fetches (Claude-User, ChatGPT-User), are NOT logged. Bot crawls
84
- > of uncached endpoints (sitemap, feeds, assets, cache misses) still
85
- > come through, which can make capture look healthy while real page
86
- > views go uncounted. Exclude AI user-agents from the cache (and any
87
- > CDN), or capture from access/edge logs instead. The
88
- > `traffic.source.cache-blindspot` doctor check warns whenever a
89
- > WordPress source is connected.
75
+ WordPress plugin, which is PHP-only: it captures non-admin GET page-loads
76
+ **that reach PHP** and exposes a paginated REST endpoint protected by an
77
+ Application Password. It has no browser-side capture path.
78
+
79
+ > **Cache blind spot.** Cache-served requests never execute PHP, so they
80
+ > produce no plugin event. A full-page cache (LiteSpeed, WP Rocket, W3 Total
81
+ > Cache, WP Super Cache) or any CDN can therefore make the source look active
82
+ > while real page views, AI crawlers, and live AI user-fetches such as
83
+ > `Claude-User` and `ChatGPT-User` go uncounted. To use this source for
84
+ > AI-agent traffic, bypass **every** cache layer for the selected AI user
85
+ > agents, or capture from access/edge logs instead.
90
86
 
91
87
  **Which user-agents to exclude from the cache** (one per line in
92
88
  LiteSpeed's "Do Not Cache User Agents", WP Rocket's
@@ -94,23 +90,61 @@ LiteSpeed's "Do Not Cache User Agents", WP Rocket's
94
90
  Agents"):
95
91
 
96
92
  ```
97
- Claude-User
98
- ClaudeBot
99
- ChatGPT-User
100
- OAI-SearchBot
101
93
  GPTBot
94
+ OAI-SearchBot
95
+ OAI-AdsBot
96
+ ChatGPT-User
97
+ openai-mcp
98
+ ClaudeBot
99
+ Claude-
100
+ anthropic-ai
102
101
  PerplexityBot
103
102
  Perplexity-User
103
+ ShapBot
104
+ Shap-User
105
+ Google-Agent
106
+ Google-GeminiNotebook
107
+ Google-NotebookLM
108
+ Google-CloudVertexBot
109
+ Bytespider
110
+ Applebot
111
+ meta-externalagent
112
+ CCBot
113
+ cohere-ai
114
+ Diffbot
115
+ MistralAI-User
116
+ MistralAI-Index
117
+ MistralAI-Training
118
+ MistralBot
119
+ DeepSeekBot
120
+ xAI-Bot
121
+ Grok-Bot
122
+ GrokBot
123
+ YouBot
124
+ DuckAssistBot
125
+ Amazonbot
126
+ Amzn-SearchBot
127
+ Amzn-User
104
128
  ```
105
129
 
106
- These are the answer-engine fetchers in both live-user-fetch (`*-User`)
107
- and crawler forms. Do NOT add `Googlebot` or `Bingbot`: caching helps
108
- search crawlers (page speed is a ranking signal, and cached pages let
109
- them crawl more per visit, which matters most on crawl-budget-starved
110
- sites), and their crawl stats are already authoritative in GSC and Bing
111
- Webmaster Tools. Rule of thumb: bypass cache only for agents you cannot
112
- measure elsewhere and that gain nothing from being cached. Answer-engine
113
- fetchers fit both; search crawlers fit neither.
130
+ This list mirrors Canonry's current classifier: answer-engine user-fetch,
131
+ crawl, search, and training agents for which WordPress has no cache-independent
132
+ measurement surface. `ClaudeBot` covers Anthropic's unhyphenated core crawler;
133
+ `Claude-` is a separate family rule so newly named `Claude-*Bot` variants
134
+ inherit the bypass. Do NOT add traditional search agents
135
+ `Googlebot`, `bingbot`, `DuckDuckBot`, `YandexBot`, or `Baiduspider`: caching
136
+ helps them crawl efficiently, and the important Google/Bing crawl evidence is
137
+ available through their webmaster tools.
138
+
139
+ > **1.1.0 -> 1.1.1 measurement boundary.** Plugin 1.1.0 briefly added a
140
+ > JavaScript beacon to recover browser/referral page views served from cache.
141
+ > Plugin 1.1.1 removes it and returns to PHP-only capture. This intentionally
142
+ > means cache-served browser referrals can again be absent even when GA4
143
+ > reports sessions; neither version made cache-served crawler requests visible
144
+ > to PHP. Annotate the upgrade time, do not interpret a trend spanning it as
145
+ > like-for-like traffic, and purge HTML from both the WordPress cache and every
146
+ > outer CDN. A temporary `/wp-json/canonry/v1/pv` compatibility route returns
147
+ > `204` for scripts stranded in old cached HTML, but never records an event.
114
148
 
115
149
  ```bash
116
150
  # 1. Install the plugin. Download the latest release zip from the
@@ -978,7 +1012,7 @@ The doctor checks are adapter-agnostic. When they fail or warn:
978
1012
  | `traffic.source.queue-backlog` | `traffic.queue-backlog.within-drain-budget` | 1–1,000 Queue messages remain. If no new messages arrive, the next scheduled sync can drain them. Run a manual sync to accelerate. |
979
1013
  | `traffic.source.queue-backlog` | `traffic.queue-backlog.remaining` | More than 1,000 Queue messages remain. Run a manual sync. If the backlog persists, shorten the traffic-sync schedule. |
980
1014
  | `traffic.source.credentials` | `traffic.credentials.resolve-failed` | Reconnect from the host that owns the source credentials. Queue pull requires a non-empty Account Queues Edit token paired by source ID. |
981
- | `traffic.source.cache-blindspot` | `traffic.cache-blindspot.wordpress-plugin` | A WordPress source is connected, so the plugin cannot see cache-served page views. Exclude AI user-agents from the page cache and any CDN, or switch to a log/edge source. Warns only, not a failure. |
1015
+ | `traffic.source.cache-blindspot` | `traffic.cache-blindspot.wordpress-plugin` | Cache-served requests never execute PHP and produce no event, so a source can look active while real page views go uncounted. Exclude selected AI user agents from every page-cache and CDN layer, or switch to a log/edge source. Warns only, not a failure. |
982
1016
  | `traffic.source.worker-version` | `traffic.worker-version.waiting-for-first-event` | Send a smoke-test request through the Worker. For Queue delivery, run a sync to ingest it. Then run the doctor again. |
983
1017
  | `traffic.source.worker-version` | `traffic.worker-version.stale` | Regenerate and redeploy the Worker from the credential-owning host with the source's existing delivery mode, then verify the route or Queue binding. |
984
1018
 
@@ -1043,21 +1077,18 @@ domains, or PII are surfaced.
1043
1077
 
1044
1078
  ## Limits & caveats
1045
1079
 
1046
- - **The WordPress plugin is blind to cache-served traffic.** The
1047
- `wordpress` adapter logs only requests that reach PHP. A full-page
1048
- cache or CDN serves cached pages from the edge, so cache-served page
1049
- views, including live AI user-fetches (Claude-User, ChatGPT-User),
1050
- never reach the plugin and go uncounted, even though bot crawls of
1051
- uncached endpoints (sitemap, assets) still appear. On a cached
1052
- WordPress site, treat the plugin's page-view counts as a floor, not a
1053
- total. Either exclude AI user-agents from the cache + CDN, or capture
1054
- cache-independent via a `cloud-run` / `vercel` / edge-log source. The
1055
- `traffic.source.cache-blindspot` doctor check surfaces this. Adapter
1056
- coverage differs: `vercel` ingests edge request-logs so cache hits are
1057
- captured (it records the `cache` HIT/MISS label), and `cloud-run` logs
1058
- every request that reaches the service, missing only what a CDN placed
1059
- in front of Cloud Run serves from its own edge cache. Only the
1060
- hook-based `wordpress` adapter has the always-present blind spot.
1080
+ - **The WordPress plugin is PHP-only.** The `wordpress` adapter records only
1081
+ requests that reach PHP. Cache-served page requests, including AI crawlers
1082
+ and live AI user-fetches, go uncounted even while crawls of uncached
1083
+ sitemaps, assets, or cache misses appear. On a cached WordPress site, treat
1084
+ this source as a floor unless the selected AI user agents bypass every
1085
+ page-cache and CDN layer. The static doctor warning surfaces this limitation
1086
+ without requesting the origin. Otherwise, use a cache-independent
1087
+ `cloud-run`, `vercel`, or edge-log source. Adapter coverage
1088
+ differs: `vercel` ingests edge request logs so cache hits are captured (it
1089
+ records the `cache` HIT/MISS label), and `cloud-run` logs every request that
1090
+ reaches the service, missing only what a CDN ahead of Cloud Run serves at its
1091
+ own edge.
1061
1092
  - **Path-level citation cross-reference is not implemented yet.** The
1062
1093
  citation store is domain-grain (`query_snapshots.cited_domains`). A
1063
1094
  future iteration that lands URL-grain citation evidence will extend
@@ -1078,17 +1109,21 @@ domains, or PII are surfaced.
1078
1109
  `traffic_sources.source_type` and a `TrafficSourceValidator`
1079
1110
  registration.
1080
1111
 
1081
- ### Page caches and the beacon lane
1082
-
1083
- A page cache (LiteSpeed, WP Rocket, Super Cache, any `advanced-cache.php`
1084
- drop-in) serves visitors before WordPress PHP boots, so the plugin's request
1085
- hook never sees those page views: on a cached site the PHP lane records only
1086
- redirects, errors, and crawlers on uncached URLs, and landed AI referrals read
1087
- as zero while GA4 shows sessions. Plugin 1.1.0 adds a beacon lane — a
1088
- first-party inline ping to the plugin's own REST route (never page-cached) —
1089
- that records real browser views, cached or not. It auto-enables when a page
1090
- cache is detected (`Settings → Canonry Traffic Logger` can force on/off).
1091
- Bots and non-200s stay in the PHP lane; browser 200s belong to the beacon, so
1092
- uncached views are not double-counted. On sites running plugin ≤ 1.0.x behind
1093
- a cache, treat GA4 as the landed-visit signal and the server source as the
1094
- bot/crawler signal only.
1112
+ ### Page caches and PHP-only coverage
1113
+
1114
+ A page cache (LiteSpeed, WP Rocket, Super Cache, or any
1115
+ `advanced-cache.php` drop-in) can serve a request before WordPress boots. The
1116
+ plugin therefore has one capture lane only: PHP. It cannot recover a
1117
+ cache-served crawler, user fetch, referral, or browser page view after the
1118
+ fact.
1119
+
1120
+ For the AI agents measured by this source, configure cache bypasses at every
1121
+ layer that can answer the public request: the WordPress cache, a host/CDN cache,
1122
+ and any edge cache. A LiteSpeed exclusion alone is insufficient when an outer
1123
+ CDN can return a cached response first.
1124
+
1125
+ Cache exclusions for the selected AI agents can recover crawler and user-fetch
1126
+ coverage, but they do not recover ordinary browser referrals served from cache.
1127
+ Use GA4 for landed browser visits or edge/access logs for cache-independent
1128
+ request coverage. The `traffic.source.cache-blindspot` doctor check is a static
1129
+ warning; it does not request or impersonate traffic against the public origin.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@canonry/canonry",
3
- "version": "4.177.1",
3
+ "version": "4.177.2",
4
4
  "type": "module",
5
5
  "description": "Self-hosted AI visibility (AEO) platform: track how ChatGPT, Claude, Gemini, and Perplexity cite your domain, join it with Search Console, GA4, server-side traffic, and paid media, and fix what you find through agent tools (CLI, REST, MCP). Local SQLite.",
6
6
  "license": "FSL-1.1-ALv2",
@@ -70,31 +70,31 @@
70
70
  "@types/node-cron": "^3.0.11",
71
71
  "tsup": "^8.5.1",
72
72
  "tsx": "^4.19.0",
73
- "@ainyc/canonry-api-routes": "0.0.0",
73
+ "@ainyc/canonry-api-client": "0.0.0",
74
74
  "@ainyc/canonry-contracts": "0.0.0",
75
+ "@ainyc/canonry-api-routes": "0.0.0",
75
76
  "@ainyc/canonry-config": "0.0.0",
76
- "@ainyc/canonry-api-client": "0.0.0",
77
77
  "@ainyc/canonry-db": "0.0.0",
78
78
  "@ainyc/canonry-integration-bing": "0.0.0",
79
- "@ainyc/canonry-integration-cloud-run": "0.0.0",
80
- "@ainyc/canonry-integration-cloudflare-queue": "0.0.0",
81
79
  "@ainyc/canonry-integration-cloudflare-worker": "0.0.0",
82
- "@ainyc/canonry-integration-commoncrawl": "0.0.0",
80
+ "@ainyc/canonry-integration-cloudflare-queue": "0.0.0",
81
+ "@ainyc/canonry-integration-cloud-run": "0.0.0",
83
82
  "@ainyc/canonry-integration-google": "0.0.0",
83
+ "@ainyc/canonry-integration-commoncrawl": "0.0.0",
84
84
  "@ainyc/canonry-integration-google-ads": "0.0.0",
85
- "@ainyc/canonry-integration-google-places": "0.0.0",
86
85
  "@ainyc/canonry-integration-google-business-profile": "0.0.0",
86
+ "@ainyc/canonry-integration-google-places": "0.0.0",
87
87
  "@ainyc/canonry-integration-google-tag-manager": "0.0.0",
88
- "@ainyc/canonry-integration-wordpress": "0.0.0",
89
88
  "@ainyc/canonry-integration-openai-ads": "0.0.0",
90
- "@ainyc/canonry-integration-traffic": "0.0.0",
89
+ "@ainyc/canonry-integration-wordpress": "0.0.0",
91
90
  "@ainyc/canonry-intelligence": "0.0.0",
91
+ "@ainyc/canonry-provider-claude": "0.0.0",
92
92
  "@ainyc/canonry-provider-cdp": "0.0.0",
93
- "@ainyc/canonry-provider-gemini": "0.0.0",
94
93
  "@ainyc/canonry-provider-local": "0.0.0",
95
94
  "@ainyc/canonry-provider-openai": "0.0.0",
96
- "@ainyc/canonry-provider-claude": "0.0.0",
97
- "@ainyc/canonry-provider-perplexity": "0.0.0"
95
+ "@ainyc/canonry-provider-gemini": "0.0.0",
96
+ "@ainyc/canonry-provider-perplexity": "0.0.0",
97
+ "@ainyc/canonry-integration-traffic": "0.0.0"
98
98
  },
99
99
  "scripts": {
100
100
  "build": "tsx scripts/copy-agent-assets.ts && tsup && tsx build-web.ts",