Add multi-provider analytics with Plausible

DESIGN.md

@@ -1,6 +1,6 @@
 ---
 name: Web Analytics
-description: A native editorial instrument for clear Vercel traffic insight inside Umbraco.
+description: A native editorial instrument for clear web analytics insight inside Umbraco.
 colors:
   backoffice-ink: "#060606"
   backoffice-ink-muted: "#2e2b29"
@@ -88,9 +88,9 @@ components:
 
 **Creative North Star: "The Editorial Instrument"**
 
-Web Analytics is a precise but approachable instrument inside the editorial workspace. It should reveal the traffic signal an editor needs, then get out of the way. The visual language is friendly and conversational, but its structure is disciplined: familiar Umbraco controls, clear hierarchy, compact reporting, and feedback close to the action that caused it.
+Web Analytics is a precise but approachable instrument inside the editorial workspace. It should reveal the site-wide or page-level traffic signal an editor needs, then get out of the way. The visual language is friendly and conversational, but its structure is disciplined: familiar Umbraco controls, clear hierarchy, compact reporting, capability-aware depth, and feedback close to the action that caused it.
 
-The extension belongs to the backoffice rather than merely living inside it. It inherits Umbraco UI Library semantics, Lato typography, spacing, focus treatment, and surface hierarchy. Custom analytics patterns may borrow the clarity of Vercel Analytics, but they must be translated into Umbraco's interaction language.
+The extension belongs to the backoffice rather than merely living inside it. It inherits Umbraco UI Library semantics, Lato typography, spacing, focus treatment, and surface hierarchy. Custom analytics patterns may borrow the clarity of Vercel Analytics, but Umbraco owns the interaction language: provider capabilities change the available depth, not the identity or basic behavior of the interface.
 
 The system explicitly rejects the density, configuration burden, and specialist terminology of an overly dense enterprise analytics platform. It is not Google Analytics, and it must never feel like a separate third-party dashboard embedded in Umbraco.
 

PRODUCT.md

@@ -14,13 +14,15 @@ The primary users are content editors and marketing staff working in the authent
 
 ## Product Purpose
 
-Web Analytics brings Vercel Web Analytics into the Umbraco backoffice. It helps editors understand site and page traffic where they already manage content, while administrators retain secure control of project connections and server-side credentials.
+Web Analytics brings insights from Vercel Web Analytics and Plausible into the Umbraco editorial workflow. It gives editors clear site-wide and page-level traffic context where they already manage content, while administrators retain secure control of connections and server-side credentials.
 
-Success means that an editor can open Analytics, understand the important traffic signals quickly, and return to their content work without needing to visit Vercel or a separate analytics suite.
+Vercel and Plausible are bundled integrations. Reporting depth adapts to the capabilities and data available from the selected provider, while the editorial experience remains consistent and focused.
+
+Success means that an editor can open Analytics, understand the important traffic signals quickly, and return to their content work without needing to visit a separate analytics suite.
 
 ## Positioning
 
-Vercel traffic insights where editors already work, without exposing credentials or requiring another analytics dashboard.
+Clear site-wide and page-level insight where editors already work, without exposing credentials or requiring another analytics dashboard.
 
 ## Brand Personality
 

samples/TheBuilder.WebAnalytics.Example/VercelAnalyticsOpenApiComposer.cs → samples/TheBuilder.WebAnalytics.Example/WebAnalyticsOpenApiComposer.cs

@@ -9,6 +9,7 @@
 using Microsoft.Extensions.Options;
 using Microsoft.OpenApi;
 using Swashbuckle.AspNetCore.SwaggerGen;
+using System.Text.Json;
 using Umbraco.Cms.Api.Common.OpenApi;
 using Umbraco.Cms.Api.Management.OpenApi;
 #endif
@@ -18,7 +19,7 @@
 
 namespace TheBuilder.WebAnalytics.Example;
 
-public sealed class VercelAnalyticsOpenApiComposer : IComposer
+public sealed class WebAnalyticsOpenApiComposer : IComposer
 {
     public void Compose(IUmbracoBuilder builder)
     {
@@ -42,7 +43,7 @@ public void Compose(IUmbracoBuilder builder)
                         return Task.CompletedTask;
                     })));
 #else
-        builder.Services.AddSingleton<IOperationIdHandler, VercelAnalyticsOperationIdHandler>();
+        builder.Services.AddSingleton<IOperationIdHandler, WebAnalyticsOperationIdHandler>();
         builder.Services.Configure<SwaggerGenOptions>(options =>
         {
             options.SwaggerDoc(
@@ -52,18 +53,41 @@ public void Compose(IUmbracoBuilder builder)
                     Title = "Web Analytics Backoffice API",
                     Version = "1.0",
                 });
-            options.OperationFilter<VercelAnalyticsOperationSecurityFilter>();
+            options.OperationFilter<WebAnalyticsOperationSecurityFilter>();
+            options.SchemaFilter<NullableEnumSchemaFilter>();
         });
 #endif
     }
 
 #if !UMBRACO_18_OR_LATER
-    private sealed class VercelAnalyticsOperationSecurityFilter : BackOfficeSecurityRequirementsOperationFilterBase
+    private sealed class WebAnalyticsOperationSecurityFilter : BackOfficeSecurityRequirementsOperationFilterBase
     {
         protected override string ApiName => Constants.ApiName;
     }
 
-    private sealed class VercelAnalyticsOperationIdHandler(IOptions<ApiVersioningOptions> apiVersioningOptions)
+    private sealed class NullableEnumSchemaFilter : ISchemaFilter
+    {
+        public void Apply(IOpenApiSchema schema, SchemaFilterContext context)
+        {
+            foreach (var property in context.Type.GetProperties())
+            {
+                if (Nullable.GetUnderlyingType(property.PropertyType)?.IsEnum is not true)
+                    continue;
+
+                var propertyName = JsonNamingPolicy.CamelCase.ConvertName(property.Name);
+                schema.Required?.Remove(propertyName);
+                if (schema.Properties?.TryGetValue(propertyName, out var propertySchema) is true)
+                {
+                    schema.Properties[propertyName] = new OpenApiSchema
+                    {
+                        AnyOf = [propertySchema, new OpenApiSchema { Type = JsonSchemaType.Null }]
+                    };
+                }
+            }
+        }
+    }
+
+    private sealed class WebAnalyticsOperationIdHandler(IOptions<ApiVersioningOptions> apiVersioningOptions)
         : OperationIdHandler(apiVersioningOptions)
     {
         protected override bool CanHandle(

src/TheBuilder.WebAnalytics/Client/scripts/generate-openapi.js

@@ -1,6 +1,7 @@
 import fetch from 'node-fetch';
 import chalk from 'chalk';
 import { createClient, defaultPlugins } from '@hey-api/openapi-ts';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 
 const getSwaggerUrl = (argumentsToParse) => argumentsToParse.find((argument) => argument !== '--');
@@ -24,10 +25,23 @@ const printGenerationError = (error, message) => {
   error('Review the generator error and the client configuration in generate-openapi.js.');
 };
 
+export async function normalizeGeneratedClient(output = 'src/api') {
+  const files = await readdir(output);
+  await Promise.all(files
+    .filter((file) => file.endsWith('.ts'))
+    .map(async (file) => {
+      const path = `${output}/${file}`;
+      const source = await readFile(path, 'utf8');
+      const normalized = source.replace(/[\t ]+(?=\r?$)/gm, '');
+      if (normalized !== source) await writeFile(path, normalized);
+    }));
+}
+
 export async function generateOpenApiClient({
   swaggerUrl = getSwaggerUrl(process.argv.slice(2)),
   fetchImplementation = fetch,
   createClientImplementation = createClient,
+  normalizeGeneratedOutput = normalizeGeneratedClient,
   log = console.log,
   error = console.error,
 } = {}) {
@@ -61,19 +75,21 @@ export async function generateOpenApiClient({
 
   log(`Calling ${chalk.yellow('hey-api')} to generate TypeScript client`);
   try {
+    const openApiDocument = await response.json();
     await createClientImplementation({
-      input: swaggerUrl,
+      input: openApiDocument,
       output: 'src/api',
       plugins: [
         ...defaultPlugins,
         '@hey-api/client-fetch',
         {
           name: '@hey-api/sdk',
           asClass: true,
-          classNameBuilder: '{{name}}Service',
+          classNameBuilder: 'WebAnalyticsService',
         },
       ],
     });
+    await normalizeGeneratedOutput();
     log('OpenAPI client generated successfully');
     return true;
   } catch (exception) {

src/TheBuilder.WebAnalytics/Client/scripts/generate-openapi.test.js

@@ -1,8 +1,11 @@
 import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it } from 'vitest';
-import { generateOpenApiClient } from './generate-openapi.js';
+import { generateOpenApiClient, normalizeGeneratedClient } from './generate-openapi.js';
 
 const scriptPath = fileURLToPath(new URL('./generate-openapi.js', import.meta.url));
 
@@ -86,7 +89,7 @@ describe('generate-openapi', () => {
     const errors = [];
     const succeeded = await generateOpenApiClient({
       swaggerUrl: 'http://localhost/openapi.json',
-      fetchImplementation: async () => ({ ok: true }),
+      fetchImplementation: async () => ({ ok: true, json: async () => ({ openapi: '3.0.0', paths: {} }) }),
       createClientImplementation: async () => {
         throw new Error('generation failed');
       },
@@ -104,12 +107,16 @@ describe('generate-openapi', () => {
   it('does not report success until the client generator resolves', async () => {
     const logs = [];
     let resolveGeneration;
+    let normalized = false;
     const generation = generateOpenApiClient({
       swaggerUrl: 'http://localhost/openapi.json',
-      fetchImplementation: async () => ({ ok: true }),
+      fetchImplementation: async () => ({ ok: true, json: async () => ({ openapi: '3.0.0', paths: {} }) }),
       createClientImplementation: () => new Promise((resolve) => {
         resolveGeneration = resolve;
       }),
+      normalizeGeneratedOutput: async () => {
+        normalized = true;
+      },
       log: (message) => logs.push(message),
       error: () => {},
     });
@@ -121,6 +128,22 @@ describe('generate-openapi', () => {
     resolveGeneration();
 
     await expect(generation).resolves.toBe(true);
+    expect(normalized).toBe(true);
     expect(logs).toContain('OpenAPI client generated successfully');
   });
+
+  it('normalizes trailing whitespace from generated TypeScript files', async () => {
+    const output = await mkdtemp(join(tmpdir(), 'web-analytics-openapi-'));
+    const generatedFile = join(output, 'sdk.gen.ts');
+    try {
+      await writeFile(generatedFile, 'export const generated = true;  \r\n    \r\n');
+
+      await normalizeGeneratedClient(output);
+
+      await expect(readFile(generatedFile, 'utf8')).resolves.toBe('export const generated = true;\r\n\r\n');
+    } finally {
+      await rm(output, { recursive: true, force: true });
+    }
+  });
+
 });

src/TheBuilder.WebAnalytics/Client/src/analytics/analytics-breakdown-grid.element.ts

@@ -11,8 +11,8 @@ import "./event-table.element.js";
 import "./flag-card.element.js";
 import { stateData, type AsyncState } from "./async-state.js";
 
-@customElement("vercel-analytics-breakdown-grid")
-export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElement) {
+@customElement("web-analytics-breakdown-grid")
+export class WebAnalyticsBreakdownGridElement extends UmbElementMixin(LitElement) {
   @property({ attribute: false }) cards: ReadonlyArray<DashboardCard> = [];
   @property({ attribute: false }) breakdowns: Partial<Record<AnalyticsDimension, AsyncState<AnalyticsBreakdown>>> = {};
   @property({ attribute: false }) events: AsyncState<AnalyticsEventsReport> = { status: "loading" };
@@ -24,6 +24,10 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
   @property() acquisitionView: AcquisitionView = "referrers";
   @property() utmDimension: UtmDimension = "UtmSource";
   @property() baseUrl?: string;
+  @property({ type: Boolean }) supportsEvents = true;
+  @property({ type: Boolean }) supportsGlobalEventFiltering = false;
+  @property({ type: Boolean }) supportsEventDetails = true;
+  @property({ type: Boolean }) supportsFlags = true;
 
   #dispatch(name: string, detail?: unknown): void {
     this.dispatchEvent(new CustomEvent(name, { bubbles: true, composed: true, detail }));
@@ -112,7 +116,7 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
     return html`
       <uui-box class=${`breakdown-card ${card.span === "wide" ? "wide" : ""}`}>
         <div class="breakdown-card-layout">
-          <vercel-analytics-breakdown-table
+          <web-analytics-breakdown-table
             .headline=${selected.headline}
             .dimension=${selected.dimension}
             .metric=${this.metric}
@@ -124,8 +128,8 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
             .linkValues=${linkValues}
             .unavailable=${unavailable}>
             ${card.kind === "tabbed-breakdown" ? this.#renderTabs(card) : ""}
-          </vercel-analytics-breakdown-table>
-          ${planLimited && unavailable ? html`<p class="hint breakdown-hint">UTM reporting availability depends on your Vercel plan and reporting window.</p>` : ""}
+          </web-analytics-breakdown-table>
+          ${planLimited && unavailable ? html`<p class="hint breakdown-hint">UTM reporting availability depends on your analytics plan and reporting window.</p>` : ""}
           <footer class="breakdown-footer">
             ${!loading && !unavailable && rows.length ? html`
               <uui-button look="secondary" label=${`View all ${selected.headline}`} @click=${() => this.#dispatch("view-breakdown", selected)}>View all</uui-button>
@@ -154,7 +158,7 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
     return html`
       <uui-box class="breakdown-card wide">
         <div class="breakdown-card-layout">
-          <vercel-analytics-breakdown-table
+          <web-analytics-breakdown-table
             .headline=${selected.headline}
             .dimension=${selected.dimension}
             .metric=${this.metric}
@@ -167,7 +171,7 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
             .unavailable=${unavailable}>
             ${this.#renderAcquisitionTabs(utmAvailable)}
             ${showingUtm ? this.#renderUtmTabs(utmCard) : ""}
-          </vercel-analytics-breakdown-table>
+          </web-analytics-breakdown-table>
           <footer class="breakdown-footer">
             ${!loading && !unavailable && rows.length ? html`
               <uui-button look="secondary" label=${`View all ${selected.headline}`} @click=${() => this.#dispatch("view-breakdown", selected)}>View all</uui-button>
@@ -187,7 +191,7 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
     return html`
       <uui-box class="breakdown-card wide">
         <div class=${`breakdown-card-layout${empty ? " empty-card-layout" : ""}`}>
-          <vercel-analytics-event-table .rows=${rows} .filters=${this.filters} .loading=${loading}></vercel-analytics-event-table>
+          <web-analytics-event-table .rows=${rows} .filters=${this.filters} .loading=${loading} .detailsEnabled=${this.supportsEventDetails} .filteringEnabled=${this.supportsGlobalEventFiltering}></web-analytics-event-table>
           ${empty ? "" : html`<footer class="breakdown-footer">
             ${!loading && rows.length ? html`<uui-button look="secondary" label="View all events" @click=${() => this.#dispatch("view-events")}>View all</uui-button>` : ""}
           </footer>`}
@@ -199,19 +203,19 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
   render() {
     const standardCards = this.cards.filter((card) => card.kind !== "tabbed-breakdown" || card.id !== "utm");
     const utmCard = this.cards.find((card): card is Extract<DashboardCard, { kind: "tabbed-breakdown" }> => card.kind === "tabbed-breakdown" && card.id === "utm");
-    const referrerCard = standardCards.find((card) => card.kind === "breakdown" && card.dimension === "ReferrerHostname");
+    const referrerCard = standardCards.find((card) => card.kind === "breakdown" && (card.dimension === "ReferrerHostname" || card.dimension === "Referrer"));
     const renderCard = (card: DashboardCard) => card === referrerCard ? this.#renderAcquisitionCard(card, utmCard) : this.#renderCard(card);
     const documentScoped = !standardCards.some((card) => card.kind === "breakdown" && card.dimension === "RequestPath");
     const cardsBeforeEvents = documentScoped ? standardCards.slice(0, 1) : standardCards;
     const cardsAfterEvents = documentScoped ? standardCards.slice(1) : [];
     return html`
       <section class="grid" aria-label="Traffic breakdowns">
         ${cardsBeforeEvents.map(renderCard)}
-        ${this.#renderEvents()}
+        ${this.supportsEvents ? this.#renderEvents() : ""}
         ${cardsAfterEvents.map(renderCard)}
-        <uui-box class=${`breakdown-card flags-card${documentScoped ? " document-flags-card" : " wide"}`}>
-          <vercel-analytics-flag-card .report=${this.flags} .selected=${this.selectedFlag}></vercel-analytics-flag-card>
-        </uui-box>
+        ${this.supportsFlags ? html`<uui-box class=${`breakdown-card flags-card${documentScoped ? " document-flags-card" : " wide"}`}>
+          <web-analytics-flag-card .report=${this.flags} .selected=${this.selectedFlag}></web-analytics-flag-card>
+        </uui-box>` : ""}
       </section>
     `;
   }
@@ -249,4 +253,4 @@ export class VercelAnalyticsBreakdownGridElement extends UmbElementMixin(LitElem
   `];
 }
 
-declare global { interface HTMLElementTagNameMap { "vercel-analytics-breakdown-grid": VercelAnalyticsBreakdownGridElement; } }
+declare global { interface HTMLElementTagNameMap { "web-analytics-breakdown-grid": WebAnalyticsBreakdownGridElement; } }