@riebeckite/plugin-analytics 0.0.1 → 0.0.3

package/README.md

@@ -1,136 +1,84 @@
 # @riebeckite/plugin-analytics
 
-Provider analytics injection for Riebeckite sites: a static bootstrap endpoint
-plus a browser entry that loads it.
+Storage-independent analytics primitives and browser page-view tracking for
+Riebeckite. It contains no Cloudflare, Worker, database, or vendor code.
 
 [日本語](./README_ja.md)
 
-## Overview
+## Design
 
-`analytics()` registers:
-
-- one GET endpoint (default `/_analytics.js`) that serves a small provider
-  bootstrap written in JavaScript, and
-- one client entry, `initAnalytics`, that appends
-  `<script defer src="/_analytics.js">` to `document.head` exactly once.
-
-The plugin is build-time only. It never executes provider code during the static
-build.
+- `AnalyticsEvent` includes a typed `page_view` event and can be extended with
+  provider-specific event unions.
+- `AnalyticsProvider` declares discoverable capabilities and exposes `capture`
+  and `query`. Queries cover per-content page views and popular content, with
+  optional ISO-8601 time ranges.
+- `UnsupportedAnalyticsQueryError` makes unsupported query capabilities
+  explicit. `MemoryAnalyticsProvider` is included for tests and local examples.
+- Provider runtime configuration (credentials, storage, bindings) stays inside
+  the provider. The browser receives only `AnalyticsPublicConfig`.
 
 ## Usage
 
 ```ts
-import { defineConfig } from "@riebeckite/core";
-import { analytics } from "@riebeckite/plugin-analytics";
+import { analytics, MemoryAnalyticsProvider } from "@riebeckite/plugin-analytics";
+
+const provider = new MemoryAnalyticsProvider();
 
-export default defineConfig({
-  // ...
+export default {
   plugins: [
-    analytics({ provider: "plausible", domain: "example.com" }),
+    analytics({
+      provider,
+      publicConfig: { collectorUrl: "/analytics/events" },
+    }),
   ],
-});
+};
 ```
 
-Provider examples:
-
-```ts
-analytics({ provider: "plausible", domain: "example.com" });
-analytics({ provider: "umami", siteId: "xxxxxxxx-xxxx-xxxx" });
-analytics({ provider: "umami", siteId: "…", domain: "example.com" });
-analytics({ provider: "google-analytics", measurementId: "G-XXXXXXXXXX" });
-analytics({ provider: "custom", scriptUrl: "https://cdn.example.com/a.js" });
-analytics({ provider: "custom", snippet: "window.__analytics = true;" });
-```
-
-## Options
-
-| Option | Type | Required | Description |
-| ------ | ---- | -------- | ----------- |
-| `provider` | `"plausible" \| "umami" \| "google-analytics" \| "custom"` | yes | Provider whose bootstrap is served |
-| `domain` | `string` | Plausible; optional for Umami | Plausible `data-domain`, or Umami `data-domains` |
-| `siteId` | `string` | Umami | Umami `data-website-id` |
-| `measurementId` | `string` | google-analytics | GA measurement id (`G-…`) |
-| `scriptUrl` | `string` | Provider default | Overrides the provider script URL; the custom script URL when no `snippet` is given |
-| `snippet` | `string` | custom (with no `scriptUrl`) | Raw bootstrap JavaScript, served verbatim |
-| `scriptPath` | `string` | `/_analytics.js` | Endpoint and client script path |
-
-`validateOptions` reports missing or mistyped fields through the standard
-Riebeckite config validation, so `riebeckite check` fails fast on a bad setup.
-
-Provider script URL defaults:
+`collectorUrl` is intentionally public. It is a relative path or an HTTP(S)
+URL for a collector that accepts a JSON `POST` body. A future provider package
+can expose a collector backed by its own private runtime configuration.
 
-| Provider | Default URL |
-| -------- | ----------- |
-| `plausible` | `https://plausible.io/js/script.js` |
-| `umami` | `https://cloud.umami.is/script.js` |
-| `google-analytics` | `https://www.googletagmanager.com/gtag/js` |
+## Browser behavior
 
-## Endpoint contract
+For every published content entry with Core's source-authored stable `id` (or
+legacy `uid`), the plugin places a small content-ID marker in rendered HTML and
+registers `initAnalytics` with the generic public-config client mechanism.
 
-- `GET /_analytics.js`
-- `200 OK`
-- `Content-Type: application/javascript; charset=utf-8`
-- `Cache-Control: public, max-age=3600`
-- Body: a self-executing snippet that creates the provider `<script>` tag
-  (`async`/`defer` as appropriate). All configured values are JSON-encoded, so
-  they cannot break out of their string literals.
+In a browser, the initializer sends exactly one event per document:
 
-`google-analytics` also defines `window.dataLayer` and `window.gtag` before
-configuring the measurement id. `custom` returns the `snippet` verbatim, or a
-generic loader for `scriptUrl`.
-
-## Client behavior (`initAnalytics`)
-
-- Runs on page load through `initRiebeckiteClient()`; no component or layout
-  change is required.
-- Appends one `<script defer src="/_analytics.js" data-riebeckite-analytics>`
-  to `document.head`, and is a no-op if that tag already exists.
-
-## Privacy and trust boundary
-
-- No analytics data is collected at build time; the endpoint only serves code.
-- The `custom` provider's `snippet` (or any `scriptUrl`) is injected as-is into
-  visitors' pages. Treat it as trusted configuration, never as user input.
-- Nothing is sanitized or proxied: whatever provider you configure receives the
-  requests directly from the browser, under the site's own origin and privacy
-  policy.
+```json
+{
+  "type": "page_view",
+  "contentId": "guide-1",
+  "occurredAt": "2026-01-01T00:00:00.000Z",
+  "path": "/guide",
+  "lang": "en"
+}
+```
 
-## Verifiability
+`path` and `lang` are contextual metadata, not identity. Content without a
+stable ID is not tracked. The initializer is a no-op during builds/SSR and is
+idempotent in a document. Riebeckite's current static document navigation needs
+no SPA route hooks; SPA navigation is not tracked automatically.
 
-Static builds do not execute client JavaScript. To keep analytics verifiable in
-built HTML, `onManifestCreated` appends functional tags to every entry:
+## Provider contract
 
-```html
-<link rel="preload" as="script" href="/_analytics.js" />
-<script defer src="/_analytics.js" data-riebeckite-analytics></script>
+```ts
+const result = await provider.query({
+  type: "popular_content",
+  limit: 10,
+  timeRange: { from: "2026-01-01T00:00:00.000Z" },
+});
 ```
 
-These are the real tags the browser would load, so no fabricated marker is
-inserted. The injection is idempotent (guarded by `data-riebeckite-analytics`)
-and does not alter the surrounding document structure.
-
-## Limitations
-
-- **Static client path.** The client entry receives no options, so it always
-  loads `/_analytics.js`. If you override `scriptPath`, mount the endpoint and
-  load it yourself with a custom client entry.
-- **No SPA route tracking.** Client-side routed SPA navigations are not
-  reported automatically; configure the provider or send events manually.
-- **Document lifecycle only.** The bootstrap runs once on initial load. Provide
-  your own `snippet` if you need a more involved lifecycle.
-- **No consent management.** The plugin does not gate loading on user consent;
-  add that in a client entry if your jurisdiction requires it.
+Capabilities are `capture`, `content_page_views`, and `popular_content`. Call
+`assertAnalyticsQuerySupported(provider, query)` when implementing a provider
+that may not support all queries.
 
 ## Exports
 
-- `analytics(options)` / `analyticsPlugin(options)` — plugin factory
-- `initAnalytics` — browser initializer (also via
-  `@riebeckite/plugin-analytics/client`)
-- `buildAnalyticsScript(options)` — pure bootstrap builder
-- `validateAnalyticsOptions(options)` — options validator
-- Constants: `ANALYTICS_SCRIPT_PATH`, `ANALYTICS_SCRIPT_ATTRIBUTE`
-- Types: `AnalyticsOptions`, `AnalyticsProvider`
-
-## See also
-
-- [Plugin guide](../../docs/plugins_en.md)
+- `analytics()` / `analyticsPlugin()`
+- `initAnalytics` (`@riebeckite/plugin-analytics/client`)
+- `MemoryAnalyticsProvider`
+- Event, query/result, provider/capability, and public-config types
+- `UnsupportedAnalyticsQueryError` and capability helpers

package/README_ja.md

@@ -1,113 +1,53 @@
 # @riebeckite/plugin-analytics
 
-サイトに外部プロバイダの解析タグを挿入するプラグインです。静的なブートストラップ用エンドポイントと、それを読み込むクライアントエントリを提供します。
+Riebeckite 向けの、ストレージや実行環境に依存しないアクセス解析の基盤です。Cloudflare、Worker、データベース、特定ベンダーの実装は含みません。
 
 [English](./README.md)
 
-## 概要
+## 設計
 
-`analytics()` は次の2つを登録します。
-
-- プロバイダのブートストラップ JavaScript を返す GET エンドポイント（既定は `/_analytics.js`）
-- `document.head` に `<script defer src="/_analytics.js">` を一度だけ追加するクライアントエントリ `initAnalytics`
-
-このプラグインはビルド時に完結します。静的ビルド中にプロバイダのコードを実行することはありません。
+- `AnalyticsEvent` は型付きの `page_view` を持ち、プロバイダ固有イベントの union に拡張できます。
+- `AnalyticsProvider` は対応機能を明示し、`capture` と `query` を提供します。コンテンツ別 PV、人気コンテンツ、任意の ISO 8601 期間を扱えます。
+- 未対応クエリは `UnsupportedAnalyticsQueryError` で明示されます。テスト・ローカル用途には `MemoryAnalyticsProvider` を用意しています。
+- 認証情報・ストレージ・ランタイムバインディングはプロバイダ内部の非公開設定です。ブラウザへ渡すのは `AnalyticsPublicConfig` だけです。
 
 ## 使い方
 
 ```ts
-import { defineConfig } from "@riebeckite/core";
-import { analytics } from "@riebeckite/plugin-analytics";
+import { analytics, MemoryAnalyticsProvider } from "@riebeckite/plugin-analytics";
 
-export default defineConfig({
-  // ...
+export default {
   plugins: [
-    analytics({ provider: "plausible", domain: "example.com" }),
+    analytics({
+      provider: new MemoryAnalyticsProvider(),
+      publicConfig: { collectorUrl: "/analytics/events" },
+    }),
   ],
-});
-```
-
-プロバイダごとの例:
-
-```ts
-analytics({ provider: "plausible", domain: "example.com" });
-analytics({ provider: "umami", siteId: "xxxxxxxx-xxxx-xxxx" });
-analytics({ provider: "umami", siteId: "…", domain: "example.com" });
-analytics({ provider: "google-analytics", measurementId: "G-XXXXXXXXXX" });
-analytics({ provider: "custom", scriptUrl: "https://cdn.example.com/a.js" });
-analytics({ provider: "custom", snippet: "window.__analytics = true;" });
+};
 ```
 
-## オプション
-
-| 項目 | 型 | 必須 | 説明 |
-| --- | --- | --- | --- |
-| `provider` | `"plausible" \| "umami" \| "google-analytics" \| "custom"` | はい | 使用するプロバイダ |
-| `domain` | `string` | Plausible では必須、Umami では任意 | Plausible の `data-domain`、または Umami の `data-domains` |
-| `siteId` | `string` | Umami | Umami の `data-website-id` |
-| `measurementId` | `string` | google-analytics | GA の測定 ID（`G-…`） |
-| `scriptUrl` | `string` | プロバイダの既定値 | プロバイダのスクリプト URL を上書きします。`snippet` がない custom では読み込む URL |
-| `snippet` | `string` | custom（`scriptUrl` がない場合） | そのまま配信される生のブートストラップ JavaScript |
-| `scriptPath` | `string` | `/_analytics.js` | エンドポイント兼クライアントスクリプトのパス |
-
-`validateOptions` は不足・型違いのフィールドを標準の設定検証として報告するため、設定ミスは `riebeckite check` で早い段階に失敗します。
-
-プロバイダの既定スクリプト URL:
-
-| プロバイダ | 既定 URL |
-| --- | --- |
-| `plausible` | `https://plausible.io/js/script.js` |
-| `umami` | `https://cloud.umami.is/script.js` |
-| `google-analytics` | `https://www.googletagmanager.com/gtag/js` |
-
-## エンドポイントの契約
+`collectorUrl` は公開してよい収集先 URL です。相対パスまたは HTTP(S) URL を指定し、JSON の `POST` を受け付ける収集側を用意します。将来のプロバイダパッケージは、非公開ランタイム設定を使ってその収集側を提供できます。
 
-- `GET /_analytics.js`
-- `200 OK`
-- `Content-Type: application/javascript; charset=utf-8`
-- `Cache-Control: public, max-age=3600`
-- 本文: プロバイダの `<script>` タグ（必要に応じて `async` / `defer`）を生成する即時実行スニペット。設定値はすべて JSON エンコードされるため、文字列リテラルを壊すことはできません。
+## ブラウザでの動作
 
-`google-analytics` は測定 ID を設定する前に `window.dataLayer` と `window.gtag` を定義します。`custom` は `snippet` をそのまま返すか、`scriptUrl` 用の汎用ローダーを返します。
+Core の安定コンテンツ ID（フロントマターの `id`、互換用の `uid`）がある公開コンテンツにだけ識別子マーカーを出力します。汎用 `publicConfig` 経由で登録された `initAnalytics` は、ブラウザでドキュメントごとに一度だけ次のようなイベントを送ります。
 
-## クライアントの挙動（`initAnalytics`）
-
-- `initRiebeckiteClient()` 経由でページ読み込み時に実行されます。コンポーネントやレイアウトの変更は不要です。
-- `<script defer src="/_analytics.js" data-riebeckite-analytics>` を `document.head` に1つ追加します。すでに存在する場合は何もしません。
-
-## プライバシーと信頼境界
-
-- ビルド時に解析データを収集することはありません。エンドポイントはコードを返すだけです。
-- `custom` の `snippet`（および任意の `scriptUrl`）は訪問者のページにそのまま挿入されます。信頼できる設定として扱い、ユーザー入力から組み立てないでください。
-- 内容のサニタイズやプロキシは行いません。設定したプロバイダは、サイト自身のオリジンとプライバシー方針のもとでブラウザから直接リクエストを受け取ります。
-
-## 検証しやすさ
-
-静的ビルドではクライアント JavaScript を実行しません。そのため、`onManifestCreated` が全エントリの HTML に実際に機能するタグを付与します。
-
-```html
-<link rel="preload" as="script" href="/_analytics.js" />
-<script defer src="/_analytics.js" data-riebeckite-analytics></script>
+```json
+{
+  "type": "page_view",
+  "contentId": "guide-1",
+  "occurredAt": "2026-01-01T00:00:00.000Z",
+  "path": "/guide",
+  "lang": "ja"
+}
 ```
 
-これはブラウザが実際に読み込むタグそのもので、検証用のダミーマーカーは挿入しません。付与は冪等（`data-riebeckite-analytics` で判定）で、周囲の HTML 構造を変えません。
-
-## 制限事項
-
-- **クライアント側のパスは固定です。** クライアントエントリはオプションを受け取らないため、常に `/_analytics.js` を読み込みます。`scriptPath` を変更する場合は、エンドポイントのマウントと読み込みを独自のクライアントエントリで行ってください。
-- **SPA のルート遷移には対応しません。** クライアントサイドのルーティングによる画面遷移は自動では計測されません。プロバイダ側で設定するか、手動でイベントを送信してください。
-- **ドキュメントのライフサイクルは初回読み込みのみです。** より複雑なライフサイクルが必要な場合は独自の `snippet` を用意してください。
-- **同意管理は行いません。** 法令上必要な場合は、クライアントエントリ側で同意を得るまで読み込みを止めてください。
+`path` と `lang` は補助情報であり、ID ではありません。安定 ID のないコンテンツは誤って計測しません。ビルド時・SSR 時は何もせず、同じドキュメント内での初期化も冪等です。現行リポジトリは静的なドキュメント遷移のため SPA フックは追加しておらず、SPA 遷移は自動計測しません。
 
 ## 主なエクスポート
 
-- `analytics(options)` / `analyticsPlugin(options)`: プラグインを作成する
-- `initAnalytics`: クライアント側の初期化（`@riebeckite/plugin-analytics/client` からも利用可）
-- `buildAnalyticsScript(options)`: ブートストラップを生成する純粋関数
-- `validateAnalyticsOptions(options)`: オプションの検証
-- 定数: `ANALYTICS_SCRIPT_PATH`、`ANALYTICS_SCRIPT_ATTRIBUTE`
-- 型: `AnalyticsOptions`、`AnalyticsProvider`
-
-## 関連資料
-
-- [プラグインガイド](../../../docs/ja/plugin-system.md)
+- `analytics()` / `analyticsPlugin()`
+- `initAnalytics`（`@riebeckite/plugin-analytics/client`）
+- `MemoryAnalyticsProvider`
+- イベント、クエリ／結果、プロバイダ／機能、公開設定の型
+- `UnsupportedAnalyticsQueryError` と機能確認ヘルパー

package/dist/client.d.ts

@@ -1,3 +1,2 @@
-export { ANALYTICS_SCRIPT_PATH } from "./src/constants.js";
-export { initAnalytics } from "./src/init.js";
-export type { AnalyticsProvider } from "./src/options.js";
+export { ANALYTICS_CONTENT_ID_ATTRIBUTE, initAnalytics, } from "./src/init.js";
+export type { AnalyticsPublicConfig } from "./src/options.js";

package/dist/client.js

@@ -1,18 +1,31 @@
-// src/constants.ts
-var ANALYTICS_SCRIPT_PATH = "/_analytics.js";
-var ANALYTICS_SCRIPT_ATTRIBUTE = "data-riebeckite-analytics";
-
 // src/init.ts
-function initAnalytics() {
-  if (typeof document === "undefined") return;
-  if (document.querySelector(`script[${ANALYTICS_SCRIPT_ATTRIBUTE}]`)) return;
-  const script = document.createElement("script");
-  script.defer = true;
-  script.src = ANALYTICS_SCRIPT_PATH;
-  script.setAttribute(ANALYTICS_SCRIPT_ATTRIBUTE, "");
-  document.head.appendChild(script);
+var ANALYTICS_CONTENT_ID_ATTRIBUTE = "data-riebeckite-content-id";
+var INITIALIZED_ATTRIBUTE = "data-riebeckite-analytics-initialized";
+function initAnalytics(config) {
+  if (typeof window === "undefined" || typeof document === "undefined") return;
+  if (document.documentElement.hasAttribute(INITIALIZED_ATTRIBUTE)) return;
+  document.documentElement.setAttribute(INITIALIZED_ATTRIBUTE, "");
+  const contentId = document.querySelector(`[${ANALYTICS_CONTENT_ID_ATTRIBUTE}]`)?.getAttribute(ANALYTICS_CONTENT_ID_ATTRIBUTE);
+  if (!contentId) return;
+  const event = {
+    type: "page_view",
+    contentId,
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+    path: window.location.pathname,
+    ...document.documentElement.lang ? { lang: document.documentElement.lang } : {}
+  };
+  void sendAnalyticsEvent(config.collectorUrl, event);
+}
+async function sendAnalyticsEvent(collectorUrl, event) {
+  await fetch(collectorUrl, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(event),
+    keepalive: true,
+    credentials: "same-origin"
+  }).catch(() => void 0);
 }
 export {
-  ANALYTICS_SCRIPT_PATH,
+  ANALYTICS_CONTENT_ID_ATTRIBUTE,
   initAnalytics
 };

package/dist/index.d.ts

@@ -1,18 +1,19 @@
 import { type AnalyticsOptions } from "./src/options.js";
-export { ANALYTICS_SCRIPT_ATTRIBUTE, ANALYTICS_SCRIPT_PATH, } from "./src/constants.js";
-export { initAnalytics } from "./src/init.js";
-export type { AnalyticsOptions, AnalyticsProvider } from "./src/options.js";
-export { ANALYTICS_PROVIDERS, validateAnalyticsOptions } from "./src/options.js";
-export { buildAnalyticsScript } from "./src/script.js";
+export type { AnalyticsCustomEvent, AnalyticsEvent, AnalyticsPageViewEvent, AnalyticsTimeRange, } from "./src/event.js";
+export { ANALYTICS_CONTENT_ID_ATTRIBUTE, initAnalytics } from "./src/init.js";
+export { MemoryAnalyticsProvider } from "./src/memory_provider.js";
+export type { AnalyticsOptions, AnalyticsPublicConfig } from "./src/options.js";
+export { validateAnalyticsOptions } from "./src/options.js";
+export type { AnalyticsCapability, AnalyticsProvider } from "./src/provider.js";
+export { ANALYTICS_CAPABILITIES, assertAnalyticsQuerySupported, requiredCapabilityForQuery, supportsAnalyticsCapability, UnsupportedAnalyticsQueryError, } from "./src/provider.js";
+export type { AnalyticsQuery, AnalyticsResult, ContentPageViewsQuery, ContentPageViewsResult, PopularContentItem, PopularContentQuery, PopularContentResult, } from "./src/query.js";
 /**
- * Injects a provider analytics bootstrap into every page.
- *
- * The provider snippet is served from a static endpoint (`/_analytics.js` by
- * default) and loaded by the `initAnalytics` client entry. Because client
- * entries are static and receive no plugin options, the endpoint path is a
- * compile-time constant; overriding `scriptPath` requires a custom client
- * entry (see the README).
+ * Registers browser page-view tracking for content with a stable content ID.
+ * Provider runtime state remains server-side; only public collector metadata is
+ * registered with the browser entry.
  */
-export declare function analytics(options: AnalyticsOptions): import("@riebeckite/core").RiebeckitePlugin<AnalyticsOptions>;
-/** Alias kept for symmetry with the other `*Plugin` factories. */
+export declare function analytics(options: AnalyticsOptions): import("@riebeckite/core").RiebeckitePlugin<Readonly<{
+    provider: import("./index.js").AnalyticsProvider;
+    publicConfig: import("./client.js").AnalyticsPublicConfig;
+}>>;
 export declare const analyticsPlugin: typeof analytics;

package/dist/index.js

@@ -1,246 +1,183 @@
 // index.ts
 import {
   createClientEntry,
-  defineEndpoint,
   definePlugin,
   escapeHtmlAttribute
 } from "@riebeckite/core";
 
-// src/constants.ts
-var ANALYTICS_SCRIPT_PATH = "/_analytics.js";
-var ANALYTICS_SCRIPT_ATTRIBUTE = "data-riebeckite-analytics";
+// src/init.ts
+var ANALYTICS_CONTENT_ID_ATTRIBUTE = "data-riebeckite-content-id";
+var INITIALIZED_ATTRIBUTE = "data-riebeckite-analytics-initialized";
+function initAnalytics(config) {
+  if (typeof window === "undefined" || typeof document === "undefined") return;
+  if (document.documentElement.hasAttribute(INITIALIZED_ATTRIBUTE)) return;
+  document.documentElement.setAttribute(INITIALIZED_ATTRIBUTE, "");
+  const contentId = document.querySelector(`[${ANALYTICS_CONTENT_ID_ATTRIBUTE}]`)?.getAttribute(ANALYTICS_CONTENT_ID_ATTRIBUTE);
+  if (!contentId) return;
+  const event = {
+    type: "page_view",
+    contentId,
+    occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+    path: window.location.pathname,
+    ...document.documentElement.lang ? { lang: document.documentElement.lang } : {}
+  };
+  void sendAnalyticsEvent(config.collectorUrl, event);
+}
+async function sendAnalyticsEvent(collectorUrl, event) {
+  await fetch(collectorUrl, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(event),
+    keepalive: true,
+    credentials: "same-origin"
+  }).catch(() => void 0);
+}
 
 // src/options.ts
-var ANALYTICS_PROVIDERS = [
-  "plausible",
-  "umami",
-  "google-analytics",
-  "custom"
-];
 function validateAnalyticsOptions(options) {
   const issues = [];
-  if (!options) {
-    issues.push({ path: "provider", message: providerMessage() });
-    return issues;
-  }
-  if (!isProvider(options.provider)) {
-    issues.push({ path: "provider", message: providerMessage() });
-  }
-  validateOptionalString(options.domain, "domain", issues);
-  validateOptionalString(options.siteId, "siteId", issues);
-  validateOptionalString(options.measurementId, "measurementId", issues);
-  validateOptionalString(options.scriptUrl, "scriptUrl", issues);
-  validateOptionalString(options.snippet, "snippet", issues);
-  if (options.provider === "plausible" && !hasText(options.domain)) {
-    issues.push({ path: "domain", message: "Plausible requires a domain." });
-  }
-  if (options.provider === "umami" && !hasText(options.siteId)) {
-    issues.push({ path: "siteId", message: "Umami requires a site id." });
-  }
-  if (options.provider === "google-analytics" && !hasText(options.measurementId)) {
+  if (!options || !isAnalyticsProvider(options.provider)) {
     issues.push({
-      path: "measurementId",
-      message: "google-analytics requires a measurement id."
+      path: "provider",
+      message: "Expected an analytics provider."
     });
   }
-  if (options.provider === "custom" && !hasText(options.snippet) && !hasText(options.scriptUrl)) {
+  if (!options?.publicConfig || !isCollectorUrl(options.publicConfig.collectorUrl)) {
     issues.push({
-      path: "snippet",
-      message: "custom requires a snippet or a scriptUrl."
-    });
-  }
-  if (options.scriptPath !== void 0 && !isStaticPath(options.scriptPath)) {
-    issues.push({
-      path: "scriptPath",
-      message: 'Expected a static path starting with "/".'
+      path: "publicConfig.collectorUrl",
+      message: "Expected a non-empty absolute URL or site-relative path."
     });
   }
   return issues;
 }
-function isProvider(value) {
-  return typeof value === "string" && ANALYTICS_PROVIDERS.includes(value);
-}
-function providerMessage() {
-  return `Expected one of: ${ANALYTICS_PROVIDERS.join(", ")}.`;
+function isAnalyticsProvider(value) {
+  return typeof value === "object" && value !== null && "capabilities" in value && "capture" in value && typeof value.capture === "function" && "query" in value && typeof value.query === "function";
 }
-function hasText(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-function validateOptionalString(value, path, issues) {
-  if (value !== void 0 && typeof value !== "string") {
-    issues.push({ path, message: "Expected a string." });
+function isCollectorUrl(value) {
+  if (typeof value !== "string" || value.trim() !== value || value.length === 0) {
+    return false;
+  }
+  if (value.startsWith("/")) return !value.startsWith("//");
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
   }
-}
-function isStaticPath(value) {
-  return value.startsWith("/") && value.length > 1 && !/[\s?#:]/.test(value) && !value.includes("//") && value !== "/assets" && !value.startsWith("/assets/");
 }
 
-// src/script.ts
-var PLAUSIBLE_SCRIPT_URL = "https://plausible.io/js/script.js";
-var UMAMI_SCRIPT_URL = "https://cloud.umami.is/script.js";
-var GOOGLE_ANALYTICS_SCRIPT_URL = "https://www.googletagmanager.com/gtag/js";
-function buildAnalyticsScript(options) {
-  switch (options.provider) {
-    case "plausible":
-      return buildPlausibleScript(options);
-    case "umami":
-      return buildUmamiScript(options);
-    case "google-analytics":
-      return buildGoogleAnalyticsScript(options);
-    case "custom":
-      return buildCustomScript(options);
-    default:
-      return "/* @riebeckite/plugin-analytics: unsupported provider */\n";
+// src/provider.ts
+var ANALYTICS_CAPABILITIES = [
+  "capture",
+  "content_page_views",
+  "popular_content"
+];
+function supportsAnalyticsCapability(provider, capability) {
+  return provider.capabilities.has(capability);
+}
+var UnsupportedAnalyticsQueryError = class extends Error {
+  constructor(query, requiredCapability) {
+    super(`Analytics provider does not support ${requiredCapability} queries.`);
+    this.query = query;
+    this.requiredCapability = requiredCapability;
   }
+  query;
+  requiredCapability;
+  name = "UnsupportedAnalyticsQueryError";
+};
+function requiredCapabilityForQuery(query) {
+  return query.type;
 }
-function buildPlausibleScript(options) {
-  const domain = options.domain ?? "";
-  const url = options.scriptUrl ?? PLAUSIBLE_SCRIPT_URL;
-  return [
-    "/* @riebeckite/plugin-analytics: plausible */",
-    "(function () {",
-    '  var script = document.createElement("script");',
-    "  script.defer = true;",
-    `  script.setAttribute("data-domain", ${jsString(domain)});`,
-    `  script.src = ${jsString(url)};`,
-    "  document.head.appendChild(script);",
-    "})();",
-    ""
-  ].join("\n");
-}
-function buildUmamiScript(options) {
-  const siteId = options.siteId ?? "";
-  const domain = options.domain;
-  const url = options.scriptUrl ?? UMAMI_SCRIPT_URL;
-  const lines = [
-    "/* @riebeckite/plugin-analytics: umami */",
-    "(function () {",
-    '  var script = document.createElement("script");',
-    "  script.defer = true;",
-    `  script.setAttribute("data-website-id", ${jsString(siteId)});`
-  ];
-  if (domain) {
-    lines.push(`  script.setAttribute("data-domains", ${jsString(domain)});`);
+function assertAnalyticsQuerySupported(provider, query) {
+  const capability = requiredCapabilityForQuery(query);
+  if (!supportsAnalyticsCapability(provider, capability)) {
+    throw new UnsupportedAnalyticsQueryError(query, capability);
   }
-  lines.push(
-    `  script.src = ${jsString(url)};`,
-    "  document.head.appendChild(script);",
-    "})();",
-    ""
-  );
-  return lines.join("\n");
-}
-function buildGoogleAnalyticsScript(options) {
-  const measurementId = options.measurementId ?? "";
-  const base = options.scriptUrl ?? GOOGLE_ANALYTICS_SCRIPT_URL;
-  const source = `${base}?id=${encodeURIComponent(measurementId)}`;
-  return [
-    "/* @riebeckite/plugin-analytics: google-analytics */",
-    "(function () {",
-    `  var id = ${jsString(measurementId)};`,
-    '  var script = document.createElement("script");',
-    "  script.async = true;",
-    `  script.src = ${jsString(source)};`,
-    "  document.head.appendChild(script);",
-    "  window.dataLayer = window.dataLayer || [];",
-    "  function gtag() { window.dataLayer.push(arguments); }",
-    "  window.gtag = gtag;",
-    '  gtag("js", new Date());',
-    '  gtag("config", id);',
-    "})();",
-    ""
-  ].join("\n");
 }
-function buildCustomScript(options) {
-  if (options.snippet?.trim()) {
-    return `${options.snippet.trimEnd()}
-`;
+
+// src/memory_provider.ts
+var MemoryAnalyticsProvider = class {
+  capabilities = new Set(ANALYTICS_CAPABILITIES);
+  #events;
+  constructor(initialEvents = []) {
+    this.#events = [...initialEvents];
   }
-  const url = options.scriptUrl ?? "";
-  return [
-    "/* @riebeckite/plugin-analytics: custom */",
-    "(function () {",
-    '  var script = document.createElement("script");',
-    "  script.defer = true;",
-    `  script.src = ${jsString(url)};`,
-    "  document.head.appendChild(script);",
-    "})();",
-    ""
-  ].join("\n");
-}
-function jsString(value) {
-  const encoded = JSON.stringify(value);
-  return encoded === void 0 ? '""' : encoded;
+  async capture(event) {
+    this.#events.push(event);
+  }
+  async query(query) {
+    assertAnalyticsQuerySupported(this, query);
+    const pageViews = this.#events.filter(isPageView).filter((event) => isInTimeRange(event.occurredAt, query.timeRange));
+    if (query.type === "content_page_views") {
+      return {
+        type: query.type,
+        contentId: query.contentId,
+        pageViews: pageViews.filter(
+          (event) => event.contentId === query.contentId
+        ).length
+      };
+    }
+    const counts = /* @__PURE__ */ new Map();
+    for (const event of pageViews) {
+      counts.set(event.contentId, (counts.get(event.contentId) ?? 0) + 1);
+    }
+    const items = [...counts.entries()].map(([contentId, pageViews2]) => ({ contentId, pageViews: pageViews2 })).sort(
+      (left, right) => right.pageViews - left.pageViews || left.contentId.localeCompare(right.contentId)
+    ).slice(0, query.limit ?? 10);
+    return { type: query.type, items };
+  }
+};
+function isPageView(event) {
+  return event.type === "page_view";
 }
-
-// src/init.ts
-function initAnalytics() {
-  if (typeof document === "undefined") return;
-  if (document.querySelector(`script[${ANALYTICS_SCRIPT_ATTRIBUTE}]`)) return;
-  const script = document.createElement("script");
-  script.defer = true;
-  script.src = ANALYTICS_SCRIPT_PATH;
-  script.setAttribute(ANALYTICS_SCRIPT_ATTRIBUTE, "");
-  document.head.appendChild(script);
+function isInTimeRange(occurredAt, timeRange) {
+  if (!timeRange) return true;
+  return (timeRange.from === void 0 || occurredAt >= timeRange.from) && (timeRange.to === void 0 || occurredAt <= timeRange.to);
 }
 
 // index.ts
 function analytics(options) {
-  const scriptPath = options.scriptPath ?? ANALYTICS_SCRIPT_PATH;
   const tracked = /* @__PURE__ */ new Map();
   return definePlugin({
     name: "analytics",
     options,
     validateOptions: validateAnalyticsOptions,
-    endpoints: [
-      defineEndpoint(
-        scriptPath,
-        () => ({
-          headers: {
-            "content-type": "application/javascript; charset=utf-8"
-          },
-          body: buildAnalyticsScript(options)
-        }),
-        { cacheControl: "public, max-age=3600" }
-      )
+    clientEntries: [
+      createClientEntry("analytics", "initAnalytics", options.publicConfig)
     ],
-    clientEntries: [createClientEntry("analytics", "initAnalytics")],
-    onPostProcessed: (context) => {
-      tracked.set(context.slug, context.content);
+    onPostProcessed: ({ slug, content }) => {
+      tracked.set(slug, content);
     },
-    onManifestCreated: (context) => {
-      const tags = buildAnalyticsTags(scriptPath);
-      for (const entry of context.manifest.entries) {
-        appendAnalyticsTags(entry, tracked.get(entry.slug), tags);
+    onManifestCreated: ({ manifest }) => {
+      for (const entry of manifest.entries) {
+        appendContentIdentity(entry, tracked.get(entry.slug));
       }
     }
   });
 }
 var analyticsPlugin = analytics;
-function buildAnalyticsTags(scriptPath) {
-  const href = escapeHtmlAttribute(scriptPath);
-  return [
-    `<link rel="preload" as="script" href="${href}" />`,
-    `<script defer src="${href}" ${ANALYTICS_SCRIPT_ATTRIBUTE}></script>`
-  ].join("\n");
-}
-function appendAnalyticsTags(entry, content, tags) {
-  if (!entry.html.includes(ANALYTICS_SCRIPT_ATTRIBUTE)) {
+function appendContentIdentity(entry, content) {
+  if (!entry.contentId) return;
+  const marker = `<span hidden ${ANALYTICS_CONTENT_ID_ATTRIBUTE}="${escapeHtmlAttribute(entry.contentId)}"></span>`;
+  if (!entry.html.includes(ANALYTICS_CONTENT_ID_ATTRIBUTE)) {
     entry.html = `${entry.html}
-${tags}`;
+${marker}`;
   }
-  if (content && !content.html.includes(ANALYTICS_SCRIPT_ATTRIBUTE)) {
+  if (content && !content.html.includes(ANALYTICS_CONTENT_ID_ATTRIBUTE)) {
     content.html = `${content.html}
-${tags}`;
+${marker}`;
   }
 }
 export {
-  ANALYTICS_PROVIDERS,
-  ANALYTICS_SCRIPT_ATTRIBUTE,
-  ANALYTICS_SCRIPT_PATH,
+  ANALYTICS_CAPABILITIES,
+  ANALYTICS_CONTENT_ID_ATTRIBUTE,
+  MemoryAnalyticsProvider,
+  UnsupportedAnalyticsQueryError,
   analytics,
   analyticsPlugin,
-  buildAnalyticsScript,
+  assertAnalyticsQuerySupported,
   initAnalytics,
+  requiredCapabilityForQuery,
+  supportsAnalyticsCapability,
   validateAnalyticsOptions
 };

package/dist/src/event.d.ts

@@ -0,0 +1,23 @@
+/** An ISO 8601 time interval. Bounds are inclusive when a provider supports them. */
+export type AnalyticsTimeRange = Readonly<{
+    from?: string;
+    to?: string;
+}>;
+/** A content page view always uses the stable, source-authored content ID. */
+export type AnalyticsPageViewEvent = Readonly<{
+    type: "page_view";
+    contentId: string;
+    occurredAt: string;
+    path?: string;
+    lang?: string;
+}>;
+/** Base shape for provider-specific events. Consumers can narrow this type. */
+export type AnalyticsCustomEvent = Readonly<{
+    type: string;
+    occurredAt: string;
+}>;
+/**
+ * Events accepted by an analytics provider. Supplying a custom event union
+ * preserves the strongly typed built-in `page_view` event.
+ */
+export type AnalyticsEvent<TCustomEvent extends AnalyticsCustomEvent = AnalyticsCustomEvent> = AnalyticsPageViewEvent | TCustomEvent;

package/dist/src/init.d.ts

@@ -1,8 +1,7 @@
+import type { AnalyticsPublicConfig } from "./options.js";
+export declare const ANALYTICS_CONTENT_ID_ATTRIBUTE = "data-riebeckite-content-id";
 /**
- * Injects the analytics bootstrap `<script>` into `document.head` exactly once.
- * The bootstrap endpoint then loads the configured provider script.
- *
- * This initializer is static: it always loads `ANALYTICS_SCRIPT_PATH`. It has
- * no SPA route awareness — see the README for the documented limitations.
+ * Sends one document-level page view. Static Riebeckite sites reload documents
+ * on navigation; SPA history hooks are intentionally not installed.
  */
-export declare function initAnalytics(): void;
+export declare function initAnalytics(config: AnalyticsPublicConfig): void;

package/dist/src/memory_provider.d.ts

@@ -0,0 +1,11 @@
+import type { AnalyticsEvent } from "./event.js";
+import { type AnalyticsProvider } from "./provider.js";
+import type { AnalyticsQuery, AnalyticsResult } from "./query.js";
+/** In-memory provider for tests, local experiments, and provider contract examples. */
+export declare class MemoryAnalyticsProvider implements AnalyticsProvider {
+    #private;
+    readonly capabilities: Set<"content_page_views" | "popular_content" | "capture">;
+    constructor(initialEvents?: readonly AnalyticsEvent[]);
+    capture(event: AnalyticsEvent): Promise<void>;
+    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
+}

package/dist/src/options.d.ts

@@ -1,32 +1,16 @@
 import type { ConfigValidationIssue } from "@riebeckite/core";
-/** Analytics providers supported by the built-in bootstrap. */
-export declare const ANALYTICS_PROVIDERS: readonly ["plausible", "umami", "google-analytics", "custom"];
-export type AnalyticsProvider = (typeof ANALYTICS_PROVIDERS)[number];
-export type AnalyticsOptions = {
-    /** Provider whose bootstrap is served. */
+import type { AnalyticsProvider } from "./provider.js";
+/** Browser-safe configuration. It must never contain provider credentials. */
+export type AnalyticsPublicConfig = Readonly<{
+    /** Public collector URL. The browser POSTs JSON analytics events here. */
+    collectorUrl: string;
+}>;
+/**
+ * Private provider runtime and public browser configuration are deliberately
+ * separate. A provider can retain credentials, bindings, and storage handles.
+ */
+export type AnalyticsOptions = Readonly<{
     provider: AnalyticsProvider;
-    /** Plausible domain, or optional Umami `data-domains` value. */
-    domain?: string;
-    /** Umami website id (`data-website-id`). */
-    siteId?: string;
-    /** Google Analytics measurement id (`G-XXXXXXX`). */
-    measurementId?: string;
-    /**
-     * Overrides the provider's default script URL. For `provider: "custom"` this
-     * is the script URL loaded when no `snippet` is given.
-     */
-    scriptUrl?: string;
-    /**
-     * Raw bootstrap JavaScript for `provider: "custom"`. This value is trusted:
-     * it is served verbatim from the endpoint. Do not build it from untrusted
-     * input.
-     */
-    snippet?: string;
-    /**
-     * Endpoint and client script path. Defaults to `ANALYTICS_SCRIPT_PATH`
-     * (`/_analytics.js`). The built-in client entry always uses the default, so
-     * changing this requires a matching custom client entry.
-     */
-    scriptPath?: string;
-};
+    publicConfig: AnalyticsPublicConfig;
+}>;
 export declare function validateAnalyticsOptions(options: AnalyticsOptions | undefined): readonly ConfigValidationIssue[];

package/dist/src/provider.d.ts

@@ -0,0 +1,24 @@
+import type { AnalyticsEvent } from "./event.js";
+import type { AnalyticsQuery, AnalyticsResult } from "./query.js";
+export declare const ANALYTICS_CAPABILITIES: readonly ["capture", "content_page_views", "popular_content"];
+export type AnalyticsCapability = (typeof ANALYTICS_CAPABILITIES)[number];
+/**
+ * Storage- and runtime-independent analytics boundary.
+ *
+ * Implementations may keep private credentials or runtime bindings internally.
+ * Only an explicit `AnalyticsPublicConfig` is ever passed to browser code.
+ */
+export interface AnalyticsProvider {
+    readonly capabilities: ReadonlySet<AnalyticsCapability>;
+    capture(event: AnalyticsEvent): Promise<void>;
+    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
+}
+export declare function supportsAnalyticsCapability(provider: AnalyticsProvider, capability: AnalyticsCapability): boolean;
+export declare class UnsupportedAnalyticsQueryError extends Error {
+    readonly query: AnalyticsQuery;
+    readonly requiredCapability: AnalyticsCapability;
+    readonly name = "UnsupportedAnalyticsQueryError";
+    constructor(query: AnalyticsQuery, requiredCapability: AnalyticsCapability);
+}
+export declare function requiredCapabilityForQuery(query: AnalyticsQuery): AnalyticsCapability;
+export declare function assertAnalyticsQuerySupported(provider: AnalyticsProvider, query: AnalyticsQuery): void;

package/dist/src/query.d.ts

@@ -0,0 +1,26 @@
+import type { AnalyticsTimeRange } from "./event.js";
+export type ContentPageViewsQuery = Readonly<{
+    type: "content_page_views";
+    contentId: string;
+    timeRange?: AnalyticsTimeRange;
+}>;
+export type PopularContentQuery = Readonly<{
+    type: "popular_content";
+    limit?: number;
+    timeRange?: AnalyticsTimeRange;
+}>;
+export type AnalyticsQuery = ContentPageViewsQuery | PopularContentQuery;
+export type ContentPageViewsResult = Readonly<{
+    type: "content_page_views";
+    contentId: string;
+    pageViews: number;
+}>;
+export type PopularContentItem = Readonly<{
+    contentId: string;
+    pageViews: number;
+}>;
+export type PopularContentResult = Readonly<{
+    type: "popular_content";
+    items: readonly PopularContentItem[];
+}>;
+export type AnalyticsResult = ContentPageViewsResult | PopularContentResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-analytics",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
     }
   },
   "dependencies": {
-    "@riebeckite/core": "0.0.1"
+    "@riebeckite/core": "0.0.3"
   },
   "publishConfig": {
     "access": "public"
@@ -40,7 +40,7 @@
   "bugs": {
     "url": "https://github.com/Rerurate514/riebeckite/issues"
   },
-  "description": "Analytics provider integration for Riebeckite sites.",
+  "description": "Storage-independent analytics foundation for Riebeckite sites.",
   "keywords": [
     "riebeckite",
     "plugin",
@@ -52,6 +52,7 @@
   },
   "sideEffects": false,
   "scripts": {
-    "build": "node ../../../scripts/build_package.mjs"
+    "build": "node ../../../scripts/build_package.mjs",
+    "test": "pnpm exec tsx --test \"test/*.test.ts\""
   }
 }

package/dist/src/constants.d.ts

@@ -1,18 +0,0 @@
-/**
- * Default path of the analytics bootstrap endpoint and of the `<script>` tag
- * the client entry injects.
- *
- * Client entries are static — they receive no plugin options — so the built-in
- * `initAnalytics` always loads this exact path. Overriding `scriptPath` mounts
- * the endpoint elsewhere and requires a custom client entry; the default is
- * kept here so both sides share one compile-time constant.
- */
-export declare const ANALYTICS_SCRIPT_PATH = "/_analytics.js";
-/**
- * `data-*` attribute that marks the analytics `<script>` tag.
- *
- * The server-side injection (`onManifestCreated`) and the browser initializer
- * (`initAnalytics`) both carry this attribute, so a built page can be verified
- * from its real output and the initializer stays idempotent.
- */
-export declare const ANALYTICS_SCRIPT_ATTRIBUTE = "data-riebeckite-analytics";

package/dist/src/script.d.ts

@@ -1,10 +0,0 @@
-import type { AnalyticsOptions } from "./options.js";
-/**
- * Builds the JavaScript served from the analytics endpoint.
- *
- * Every configured value is JSON-encoded before it is embedded, so a value can
- * never break out of the string literal that holds it. The one exception is
- * `provider: "custom"` with a `snippet`, which is intentionally trusted and
- * returned verbatim.
- */
-export declare function buildAnalyticsScript(options: AnalyticsOptions): string;