@zeruxjs/reports 0.0.0-stage → 0.0.1

package/dist/dashboard.js

@@ -0,0 +1,68 @@
+export function reportDashboard(prefix) {
+    const p = JSON.stringify(prefix);
+    return `<!doctype html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Zerux Reports</title><style>
+:root{font:14px/1.5 system-ui,sans-serif;color-scheme:light dark}body{max-width:1280px;margin:auto;padding:24px}h1{margin-bottom:3px}nav{display:flex;flex-wrap:wrap;gap:10px;margin:18px 0}button,input,select,textarea{font:inherit;padding:8px 12px;border:1px solid #9998;border-radius:6px;background:transparent;color:inherit}button{cursor:pointer}input,select,textarea{max-width:100%;box-sizing:border-box}textarea{width:100%;height:200px;font-family:monospace}main{display:grid;grid-template-columns:minmax(230px,1fr) 3fr;gap:18px}aside,article,.chart{padding:15px;border:1px solid #8885;border-radius:10px}aside label{display:block;margin:8px 0}aside input,aside select{width:100%}#charts{display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:14px}.chart{min-height:180px}canvas{width:100%;height:200px}table{border-collapse:collapse;width:100%}td,th{text-align:left;padding:5px;border-bottom:1px solid #8885}.hint{color:#888}.warn{color:#b76a00}pre{white-space:pre-wrap;overflow-wrap:anywhere}@media(max-width:720px){main{display:block}aside{margin-bottom:12px}}
+</style></head><body><h1>Zerux Reports</h1><p class="hint">Internal analytics reporting • authenticated workspace • page &amp; chart designer</p>
+<nav><button id="reload">Reload</button><button id="newReport">New report</button><button id="newPage">Add page</button><button id="newChart">Add chart</button><button id="save">Save report</button><button id="csv">Export CSV</button><button id="json">Export JSON</button></nav><p class="hint">A saved report is private to your application-authorized tenant. Downloaded exports have their own permission check.</p><section aria-label="Report date filters"><label>From UTC <input id="since" type="date"></label> <label>To UTC <input id="until" type="date"></label> <button id="refreshCharts">Refresh charts</button> <span class="hint">An optional 366-day maximum date window; blank dates use each chart's saved filters.</span></section>
+<main><aside><label>Report<select id="report"></select></label><label>Page<select id="page"></select></label><label>Report title<input id="reportName"></label><label>Page title<input id="pageName"></label>
+<label>Chart<select id="chart"></select></label><label>Chart title<input id="chartTitle"></label>
+<label>Chart type<select id="chartType"><option>bar</option><option>horizontal-bar</option><option>line</option><option>area</option><option>pie</option><option>doughnut</option><option>scatter</option><option>stacked-bar</option><option>table</option><option>kpi</option></select></label>
+<label>Metric<select id="chartMetric"><option>count</option><option>sum</option><option>average</option><option>min</option><option>max</option><option>distinct</option></select></label>
+<label>Group by<input id="chartGroupBy" placeholder="event, day, source, property:plan"></label>
+<label>Numeric value field<input id="chartValueField" placeholder="price"></label><label>Filter event<input id="chartEvent" placeholder="purchase"></label>
+<button id="deleteChart">Delete chart</button>
+<p class="hint">Chart editor (JSON). Types: bar, horizontal-bar, line, area, pie, doughnut, scatter, stacked-bar, table, kpi.</p><textarea id="chartsJson" spellcheck="false"></textarea><button id="applyCharts">Apply charts</button><p><button id="deletePage">Delete page</button></p></aside><article><h2 id="pageTitle">Report preview</h2><p class="hint" id="notice"></p><div id="charts"></div></article></main><section aria-label="Marketing campaign reports"><h2>Campaign analytics</h2><p class="hint">Optional integration. SMTP acceptance is not inbox delivery; tracking events are not unique recipients.</p><label>Campaign code <input id="campaignCode" maxlength="96"></label> <label>Report <select id="campaignKind"><option value="delivery">Recipient delivery page</option><option value="performance">All-time durable states / provider notices</option><option value="daily">Daily outcome trends</option><option value="activity">Observed open / click events</option></select></label> <button id="loadCampaign">Load campaign</button> <button id="nextCampaign">Next recipient page</button> <div id="campaignCharts" aria-live="polite"></div><p id="campaignNotice" class="hint"></p></section><pre role="status" aria-live="polite" id="status"></pre>
+<script>(function(){'use strict';const prefix=${p},$=id=>document.getElementById(id);let doc,ridx=0,pidx=0,cidx=0,campaignCursor=null;
+const say=s=>$('status').textContent=s;
+function opt(select,list,field){select.replaceChildren();list.forEach((v,i)=>{const el=document.createElement('option');el.value=String(i);el.textContent=v[field];select.append(el);});}
+function selected(){return doc&&doc.reports[ridx]}function page(){return selected()&&selected().pages[pidx]}function chart(){return page()?.charts[cidx]}
+async function load(){try{const response=await fetch(prefix+'/api',{credentials:'same-origin',cache:'no-store'});if(!response.ok)throw Error('HTTP '+response.status);doc=await response.json();ridx=0;pidx=0;render();say('Reports loaded');}catch(e){say('Load failed: '+e.message);}}
+function render(){opt($('report'),doc.reports,'name');$('report').value=String(ridx);opt($('page'),selected()?.pages||[],'name');$('page').value=String(pidx);$('reportName').value=selected()?.name||'';$('pageName').value=page()?.name||'';opt($('chart'),page()?.charts||[],'title');$('chart').value=String(cidx);
+ for(const [input,key] of [['chartTitle','title'],['chartType','type'],['chartMetric','metric'],['chartGroupBy','groupBy'],['chartValueField','valueField'],['chartEvent','eventName']])$(''+input).value=chart()?.[key]||'';
+ $('chartsJson').value=JSON.stringify(page()?.charts||[],null,2);void preview();}
+$('report').onchange=e=>{ridx=Number(e.target.value);pidx=0;cidx=0;render();};$('page').onchange=e=>{pidx=Number(e.target.value);cidx=0;render();};
+$('chart').onchange=e=>{cidx=Number(e.target.value);render();};
+for(const [input,key] of [['chartTitle','title'],['chartType','type'],['chartMetric','metric'],['chartGroupBy','groupBy'],['chartValueField','valueField'],['chartEvent','eventName']])$(''+input).onchange=e=>{if(!chart())return;if(e.target.value)chart()[key]=e.target.value;else delete chart()[key];render();};
+$('deleteChart').onclick=()=>{if(!chart())return;page().charts.splice(cidx,1);cidx=0;render();};
+$('reportName').onchange=e=>{if(selected()){selected().name=e.target.value;render();}};
+$('pageName').onchange=e=>{if(page()){page().name=e.target.value;render();}};
+function uid(prefix){return prefix+'_'+Date.now().toString(36)+'_'+Math.floor(Math.random()*9999);}
+$('newReport').onclick=()=>{doc.reports.push({id:uid('report'),name:'New report',pages:[{id:uid('page'),name:'Overview',charts:[]}]});ridx=doc.reports.length-1;pidx=0;render();};
+$('newPage').onclick=()=>{if(!selected())return;selected().pages.push({id:uid('page'),name:'New page',charts:[]});pidx=selected().pages.length-1;cidx=0;render();};
+$('newChart').onclick=()=>{if(!page())return;page().charts.push({id:uid('chart'),title:'Events',type:'bar',groupBy:'event',metric:'count',limit:100});cidx=page().charts.length-1;render();};
+$('applyCharts').onclick=()=>{try{if(!page())return;page().charts=JSON.parse($('chartsJson').value);cidx=0;render();say('Applied chart definitions (publish to save)');}catch(e){say('Invalid JSON: '+e.message);}};
+$('deletePage').onclick=()=>{if(!selected()||!page())return;selected().pages.splice(pidx,1);pidx=0;render();};
+$('reload').onclick=load;
+$('refreshCharts').onclick=()=>void preview();
+function dateWindow(){const a=$('since').value,b=$('until').value;if(!a&&!b)return null;if(!a||!b)throw Error('Select both UTC dates');const since=Date.parse(a+'T00:00:00.000Z'),until=Date.parse(b+'T23:59:59.999Z');if(!Number.isFinite(since)||!Number.isFinite(until)||until<since||until-since>366*86400000)throw Error('UTC range must be within 366 days');return {since,until};}
+function applyWindow(url){const filter=dateWindow();if(filter){url.searchParams.set('since',String(filter.since));url.searchParams.set('until',String(filter.until));}}
+function exportFile(format){try{if(!page())throw Error('Select a report page');const url=new URL(prefix+'/export',location.origin);url.searchParams.set('report',selected().id);url.searchParams.set('page',page().id);url.searchParams.set('format',format);applyWindow(url);window.location.assign(url.toString());say('Requesting '+format.toUpperCase()+' export (requires export permission)');}catch(e){say('Export unavailable: '+e.message);}}
+$('csv').onclick=()=>exportFile('csv');$('json').onclick=()=>exportFile('json');
+async function loadCampaign(next=false){try{const code=$('campaignCode').value,kind=$('campaignKind').value;if(!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(code))throw Error('Invalid campaign code');if(!next)campaignCursor=null;const url=new URL(prefix+'/campaign',location.origin);url.searchParams.set('code',code);url.searchParams.set('kind',kind);if(kind==='delivery'&&campaignCursor)url.searchParams.set('cursor',campaignCursor);if(kind==='daily'||kind==='activity'){const a=$('since').value,b=$('until').value;if(!a||!b)throw Error('Choose both campaign UTC dates');url.searchParams.set('from',a);url.searchParams.set('to',b);}const response=await fetch(url,{credentials:'same-origin',cache:'no-store'});const result=await response.json();if(!response.ok)throw Error(result.error||response.status);const board=$('campaignCharts');board.replaceChildren();const values=result.charts?Object.values(result.charts):result.activity?[result.activity]:result.statuses?[result.statuses]:[];for(const item of values){if(!item)continue;const section=document.createElement('section');section.className='chart';const title=document.createElement('h3');title.textContent=item.title;section.append(title);draw(section,item);board.append(section);}campaignCursor=kind==='delivery'?result.coverage.nextCursor:null;$('nextCampaign').disabled=!campaignCursor;$('campaignNotice').textContent=kind==='delivery'?result.coverage.disclaimer+' Page size: '+result.coverage.scanned+'; scope: '+result.coverage.scope:result.disclaimer||JSON.stringify(result.coverage||{});say('Campaign report loaded');}catch(e){say('Campaign report unavailable: '+e.message);}}
+$('loadCampaign').onclick=()=>void loadCampaign();$('nextCampaign').onclick=()=>void loadCampaign(true);$('campaignKind').onchange=()=>{campaignCursor=null;$('nextCampaign').disabled=true;};$('nextCampaign').disabled=true;
+$('save').onclick=async()=>{try{const next=JSON.parse(JSON.stringify(doc));next.version++;const res=await fetch(prefix+'/api',{method:'PUT',credentials:'same-origin',headers:{'content-type':'application/json'},body:JSON.stringify(next)});const result=await res.json();if(!res.ok)throw Error(result.error||res.status);doc=next;render();say('Saved version '+next.version);}catch(e){say('Save failed: '+e.message);}};
+async function preview(){const board=$('charts');board.replaceChildren();$('pageTitle').textContent=page()?.name||'No page';$('notice').textContent='';if(!page())return;
+  if(page().charts.length>12)$('notice').textContent='Preview is limited to the first 12 charts to protect database performance.';
+  for(const chart of page().charts.slice(0,12)){const section=document.createElement('div');section.className='chart';const h=document.createElement('h3');h.textContent=chart.title;section.append(h);board.append(section);
+    try{const url=new URL(prefix+'/query',location.origin);url.searchParams.set('report',selected().id);url.searchParams.set('page',page().id);url.searchParams.set('chart',chart.id);applyWindow(url);
+      const response=await fetch(url,{credentials:'same-origin',cache:'no-store'});if(!response.ok)throw Error('HTTP '+response.status);const result=await response.json();
+      if(['pie','doughnut'].includes(chart.type)&&result.values.some(v=>v<0)){const note=document.createElement('p');note.className='warn';note.textContent='Pie and doughnut charts cannot display negative values. Choose bar, line or table.';section.append(note);continue;}
+      if(result.truncated||result.queryMode==='materialized'){const note=document.createElement('p');note.className='warn';note.textContent=result.queryMode==='materialized'?'Indexed numeric facts only ('+result.matchedFacts+' matching facts); older or failed writes may be missing.'+(result.truncated?' Group display limited.':''):result.queryMode==='database'?'Group display limited; total is a database event count.':'Sampled at most '+result.sampledRows+' source events; not a complete aggregate.';section.append(note);}draw(section,result);
+    }catch(e){const error=document.createElement('p');error.textContent='Query unavailable: '+e.message;section.append(error);}}
+}
+function draw(section,d){const labels=d.labels||[],v=d.values||[];
+  if(d.type==='kpi'){const h=document.createElement('h1');h.textContent=Number(d.total).toLocaleString();section.append(h);return;}
+  if(d.type==='table'){const table=document.createElement('table'),head=document.createElement('tr');for(const label of ['Dimension','Value']){const th=document.createElement('th');th.textContent=label;head.append(th);}table.append(head);labels.forEach((l,i)=>{const tr=document.createElement('tr');for(const text of [l,String(v[i])]){const cell=document.createElement('td');cell.textContent=text;tr.append(cell);}table.append(tr);});section.append(table);return;}
+  const canvas=document.createElement('canvas');canvas.width=640;canvas.height=320;section.append(canvas);const c=canvas.getContext('2d');if(!c)return;
+  const palette=['#2563eb','#0891b2','#d97706','#059669','#9333ea','#dc2626','#4f46e5','#64748b'];c.font='12px sans-serif';c.fillStyle='#777';
+  if(d.type==='pie'||d.type==='doughnut'){let angle=-Math.PI/2;const total=v.reduce((a,b)=>a+Math.max(0,b),0)||1;v.slice(0,15).forEach((value,i)=>{const sweep=Math.PI*2*Math.max(0,value)/total;c.beginPath();c.moveTo(210,155);c.arc(210,155,125,angle,angle+sweep);c.closePath();c.fillStyle=palette[i%palette.length];c.fill();angle+=sweep;});if(d.type==='doughnut'){c.beginPath();c.arc(210,155,62,0,Math.PI*2);c.fillStyle=getComputedStyle(document.body).backgroundColor||'#fff';c.fill();}labels.slice(0,8).forEach((l,i)=>{c.fillStyle=palette[i%palette.length];c.fillRect(370,20+i*28,12,12);c.fillStyle='#888';c.fillText(String(l).slice(0,25),390,31+i*28);});return;}
+  const lowest=Math.min(0,...v),highest=Math.max(0,...v),range=Math.max(1,highest-lowest),count=Math.max(v.length,1),w=520/count;
+  const yValue=value=>278-230*(value-lowest)/range,zeroY=yValue(0);
+  c.strokeStyle='#aaa';c.beginPath();c.moveTo(50,zeroY);c.lineTo(610,zeroY);c.stroke();
+  if(d.type==='horizontal-bar'){const height=Math.min(28,240/Math.max(1,count)),zeroX=145+430*(-lowest)/range;
+    v.slice(0,30).forEach((value,i)=>{const y=12+i*height,x=145+430*(value-lowest)/range;c.fillStyle=palette[i%palette.length];c.fillRect(Math.min(zeroX,x),y,Math.abs(x-zeroX),Math.max(2,height-4));c.fillStyle='#888';c.fillText(String(labels[i]).slice(0,18),4,y+height-5);});return;}
+  if(d.type==='line'||d.type==='area'||d.type==='scatter'){c.strokeStyle=palette[0];c.fillStyle=palette[0];c.beginPath();v.forEach((value,i)=>{const x=65+i*(520/Math.max(1,count-1)),y=yValue(value);if(i===0)c.moveTo(x,y);else c.lineTo(x,y);});if(d.type==='area'){c.lineTo(65+(count-1)*(520/Math.max(1,count-1)),zeroY);c.lineTo(65,zeroY);c.closePath();c.globalAlpha=.2;c.fillStyle=palette[0];c.fill();c.globalAlpha=1;}if(d.type!=='scatter')c.stroke();v.forEach((value,i)=>{const x=65+i*(520/Math.max(1,count-1)),y=yValue(value);c.beginPath();c.arc(x,y,3,0,Math.PI*2);c.fill();});}
+  else v.forEach((value,i)=>{c.fillStyle=palette[i%palette.length];const y=yValue(value);c.fillRect(60+i*w,Math.min(zeroY,y),Math.max(2,w-5),Math.abs(zeroY-y));});
+  c.fillStyle='#888';labels.slice(0,8).forEach((l,i)=>c.fillText(String(l).slice(0,13),60+i*(520/Math.max(1,Math.min(count,8))),304));}
+load();})();</script></body></html>`;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './model.js';
+export * from './runtime.js';
+export * from './campaign-delivery.js';
+export * from './campaign-reports.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './model.js';
+export * from './runtime.js';
+export * from './campaign-delivery.js';
+export * from './campaign-reports.js';

package/dist/model.d.ts

@@ -0,0 +1,5 @@
+import type { ReportsDocument, ReportsStore, ChartDefinition, ChartData, AnalyticsReportSource } from './types.js';
+export declare const isReportId: (v: unknown) => v is string;
+export declare function validateReports(input: unknown): ReportsDocument;
+export declare function createMemoryReportsStore(initial?: ReportsDocument): ReportsStore;
+export declare function queryChart(source: AnalyticsReportSource, chart: ChartDefinition, maxSourceRows?: number, site?: string): Promise<ChartData>;

package/dist/model.js

@@ -0,0 +1,124 @@
+const ident = /^[A-Za-z][A-Za-z0-9_.:-]{0,95}$/;
+const forbidden = new Set(['__proto__', 'constructor', 'prototype']);
+const chartTypes = ['bar', 'horizontal-bar', 'line', 'area', 'pie', 'doughnut', 'scatter', 'stacked-bar', 'table', 'kpi'];
+const metrics = ['count', 'sum', 'average', 'min', 'max', 'distinct'];
+export const isReportId = (v) => typeof v === 'string' && ident.test(v) && !v.split(/[.:-]/).some(k => forbidden.has(k));
+export function validateReports(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new TypeError('Invalid reports document');
+    const doc = input;
+    if (!Number.isSafeInteger(doc.version) || doc.version < 1 || !Array.isArray(doc.reports) || doc.reports.length > 100)
+        throw new TypeError('Invalid reports version or size');
+    const ids = new Set();
+    const unique = (id) => { if (!isReportId(id) || ids.has(id))
+        throw new TypeError('Invalid or repeated report ID'); ids.add(id); };
+    for (const report of doc.reports) {
+        unique(report.id);
+        if (typeof report.name !== 'string' || report.name.length < 1 || report.name.length > 128 || report.description !== undefined && (typeof report.description !== 'string' || report.description.length > 1024) || !Array.isArray(report.pages) || report.pages.length > 50)
+            throw new TypeError('Invalid report');
+        for (const page of report.pages) {
+            unique(page.id);
+            if (typeof page.name !== 'string' || page.name.length < 1 || page.name.length > 128 || !Array.isArray(page.charts) || page.charts.length > 50)
+                throw new TypeError('Invalid report page');
+            for (const chart of page.charts) {
+                unique(chart.id);
+                if (typeof chart.title !== 'string' || chart.title.length < 1 || chart.title.length > 128 || !chartTypes.includes(chart.type) || !metrics.includes(chart.metric) || !['event', 'day', 'source', 'site', 'pathname'].includes(chart.groupBy) && !/^property:[A-Za-z][A-Za-z0-9_.:-]{0,95}$/.test(chart.groupBy) || chart.groupBy.startsWith('property:') && !isReportId(chart.groupBy.slice(9)))
+                    throw new TypeError('Invalid chart');
+                // eslint-disable-next-line no-control-regex -- Intentionally matches control characters for validation or output sanitization.
+                if (chart.valueField !== undefined && !isReportId(chart.valueField) || chart.eventName !== undefined && !isReportId(chart.eventName) || chart.source !== undefined && !['web', 'server', 'email', 'system'].includes(chart.source) || chart.site !== undefined && (typeof chart.site !== 'string' || chart.site.length > 200 || /[\x00-\x1f]/.test(chart.site)) || chart.limit !== undefined && (!Number.isSafeInteger(chart.limit) || chart.limit < 1 || chart.limit > 500) || ['since', 'until'].some(k => { const n = chart[k]; return n !== undefined && (!Number.isSafeInteger(n) || n < 0); }) || chart.since !== undefined && chart.until !== undefined && chart.since > chart.until)
+                    throw new TypeError('Invalid chart query');
+            }
+        }
+    }
+    return structuredClone(doc);
+}
+export function createMemoryReportsStore(initial = { version: 1, reports: [] }) {
+    let current = validateReports(initial);
+    return { async load() { return structuredClone(current); }, async save(next, expected) { if (expected !== current.version || next.version !== expected + 1)
+            return false; current = validateReports(next); return true; } };
+}
+export async function queryChart(source, chart, maxSourceRows = 500, site) {
+    if (!Number.isSafeInteger(maxSourceRows) || maxSourceRows < 1 || maxSourceRows > 500)
+        throw new RangeError('Invalid source row limit');
+    // Direct programmatic callers receive the same chart validation as editor-saved definitions.
+    const reportId = chart.id === 'ReportValidation' ? 'ReportValidationTwo' : 'ReportValidation';
+    const pageId = [chart.id, reportId].includes('PageValidation') ? 'PageValidationTwo' : 'PageValidation';
+    validateReports({ version: 1, reports: [{ id: reportId, name: 'Validation', pages: [{ id: pageId, name: 'Preview', charts: [chart] }] }] });
+    const take = Math.min(chart.limit ?? maxSourceRows, maxSourceRows);
+    const scopedSite = site ?? chart.site;
+    if (chart.metric === 'count' && typeof source.aggregate === 'function' && (['event', 'source', 'site', 'pathname'].includes(chart.groupBy) || chart.groupBy === 'day' && chart.since !== undefined && chart.until !== undefined)) {
+        const result = await source.aggregate({ groupBy: chart.groupBy,
+            name: chart.eventName, source: chart.source, site: scopedSite, since: chart.since, until: chart.until, limit: chart.limit ?? 100 });
+        if (result.mode !== 'database' || result.groupBy !== chart.groupBy || !Number.isSafeInteger(result.total) || result.total < 0 ||
+            typeof result.truncated !== 'boolean' || !Array.isArray(result.groups) || result.groups.length > (chart.limit ?? 100) ||
+            result.groups.some(g => typeof g.category !== 'string' || g.category.length > 150 || !Number.isSafeInteger(g.value) || g.value < 0) ||
+            result.groups.reduce((n, g) => n + g.value, 0) > result.total)
+            throw new Error('Invalid native report count result');
+        const output = chart.groupBy === 'day' ? [...result.groups].sort((a, b) => a.category.localeCompare(b.category)) : result.groups;
+        const visible = output.slice(0, 60);
+        return { id: chart.id, title: chart.title, type: chart.type, labels: visible.map(g => g.category), values: visible.map(g => g.value),
+            total: result.total, sampledRows: 0, truncated: result.truncated || output.length > 60, queryMode: 'database', coverage: 'exact-persisted-event-count' };
+    }
+    if (chart.metric !== 'count' && chart.metric !== 'distinct' && chart.valueField && typeof source.aggregateNumeric === 'function' && (typeof source.supportsNumericField !== 'function' || source.supportsNumericField(chart.valueField)) && (['event', 'source', 'site', 'pathname'].includes(chart.groupBy) || chart.groupBy === 'day' && chart.since !== undefined && chart.until !== undefined)) {
+        const result = await source.aggregateNumeric({ groupBy: chart.groupBy,
+            metric: chart.metric, valueField: chart.valueField, name: chart.eventName, source: chart.source,
+            site: scopedSite, since: chart.since, until: chart.until, limit: chart.limit ?? 100 });
+        if (result.mode !== 'materialized' || result.groupBy !== chart.groupBy || result.metric !== chart.metric || result.valueField !== chart.valueField ||
+            result.coverage !== 'indexed-only' || typeof result.truncated !== 'boolean' || !Number.isSafeInteger(result.matchedFacts) || result.matchedFacts < 0 ||
+            !Number.isFinite(result.total) || !Array.isArray(result.groups) || result.groups.length > (chart.limit ?? 100) ||
+            result.groups.some(g => typeof g.category !== 'string' || g.category.length > 150 || !Number.isFinite(g.value)))
+            throw new Error('Invalid indexed numeric report result');
+        const output = chart.groupBy === 'day' ? [...result.groups].sort((a, b) => a.category.localeCompare(b.category)) : result.groups;
+        const visible = output.slice(0, 60);
+        return { id: chart.id, title: chart.title, type: chart.type, labels: visible.map(g => g.category), values: visible.map(g => g.value),
+            total: result.total, sampledRows: 0, truncated: result.truncated || output.length > 60, queryMode: 'materialized',
+            numericCoverage: result.coverage, matchedFacts: result.matchedFacts, coverage: 'indexed-numeric-facts-only' };
+    }
+    const rows = await source.events({ name: chart.eventName, source: chart.source, site: scopedSite, since: chart.since, until: chart.until, limit: take });
+    if (!Array.isArray(rows) || rows.length > take)
+        throw new Error('Source returned more than the bounded event page');
+    const groups = new Map();
+    const all = { count: 0, numericCount: 0, sum: 0, min: Infinity, max: -Infinity, unique: new Set() };
+    for (const row of rows) {
+        let props = {};
+        try {
+            const parsed = JSON.parse(row.properties_json);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                props = parsed;
+        }
+        catch { /* This optional failure is intentionally ignored. */ }
+        if (scopedSite !== undefined && row.site !== scopedSite)
+            throw new Error('Analytics source violated enforced site scope');
+        const raw = chart.groupBy === 'event' ? row.event_name : chart.groupBy === 'day' ? new Date(Number(row.occurred_at)).toISOString().slice(0, 10) : chart.groupBy === 'source' ? row.source : chart.groupBy === 'site' ? row.site : chart.groupBy === 'pathname' ? row.pathname : props[chart.groupBy.slice(9)];
+        const category = String(raw ?? '(not set)').slice(0, 150);
+        const value = chart.valueField ? props[chart.valueField] : 1;
+        let group = groups.get(category);
+        if (!group) {
+            group = { count: 0, numericCount: 0, sum: 0, min: Infinity, max: -Infinity, unique: new Set() };
+            groups.set(category, group);
+        }
+        group.count++;
+        all.count++;
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            for (const item of [group, all]) {
+                item.numericCount++;
+                item.sum += value;
+                item.min = Math.min(item.min, value);
+                item.max = Math.max(item.max, value);
+            }
+        }
+        const distinct = String(value ?? '');
+        if (group.unique.size < 10000)
+            group.unique.add(distinct);
+        if (all.unique.size < 10000)
+            all.unique.add(distinct);
+    }
+    const metric = (group, method) => ({ count: group.count, sum: group.sum, average: group.numericCount ? group.sum / group.numericCount : 0, min: Number.isFinite(group.min) ? group.min : 0, max: Number.isFinite(group.max) ? group.max : 0, distinct: group.unique.size })[method];
+    const items = [...groups].map(([category, group]) => ({ category, value: metric(group, chart.metric) }));
+    if (chart.groupBy === 'day')
+        items.sort((a, b) => a.category.localeCompare(b.category));
+    else
+        items.sort((a, b) => b.value - a.value);
+    const output = items.slice(0, 60);
+    return { id: chart.id, title: chart.title, type: chart.type, labels: output.map(i => i.category), values: output.map(i => i.value), total: metric(all, chart.metric), sampledRows: rows.length, truncated: rows.length >= take, queryMode: 'sampled', coverage: 'bounded-source-event-page' };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,9 @@
+import type { ReportsOptions, ReportsStore, ChartData } from './types.js';
+export declare function createReports(options: ReportsOptions): {
+    store: ReportsStore;
+    query: (reportId: string, pageId: string, chartId: string) => Promise<ChartData>;
+    routes(): {
+        pattern: string;
+        handler: (req: Request) => Promise<Response>;
+    }[];
+};

package/dist/runtime.js

@@ -0,0 +1,316 @@
+import { createHash } from 'node:crypto';
+import { createMemoryReportsStore, validateReports, queryChart, isReportId } from './model.js';
+import { campaignPerformanceCharts, campaignDailyTrendsCharts } from './campaign-delivery.js';
+import { marketingDeliveryPageCharts, campaignActivityCharts } from './campaign-reports.js';
+import { reportDashboard } from './dashboard.js';
+const headers = { 'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff', 'vary': 'Cookie, Authorization' };
+const json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { ...headers, 'content-type': 'application/json; charset=utf-8' } });
+const error = (message, status) => json({ error: message }, status);
+// eslint-disable-next-line no-control-regex -- Intentionally matches control characters for validation or output sanitization.
+const validSite = (site) => typeof site === 'string' && site.length > 0 && site.length <= 200 && !/[\x00-\x1f]/.test(site);
+const date = (s) => {
+    if (!s || !/^\d{4}-\d{2}-\d{2}$/.test(s) || new Date(s + 'T00:00:00Z').toISOString().slice(0, 10) !== s)
+        throw new TypeError('Invalid UTC date');
+    return Date.parse(s + 'T00:00:00Z');
+};
+function utcWindow(params, required = false) {
+    const since = params.get('since'), until = params.get('until');
+    if (!since && !until && !required)
+        return {};
+    if (!since || !until || !/^\d+$/.test(since) || !/^\d+$/.test(until))
+        throw new TypeError('Both numeric since and until must be supplied');
+    const a = Number(since), b = Number(until);
+    if (!Number.isSafeInteger(a) || !Number.isSafeInteger(b) || a < 0 || b < a || b - a > 366 * 86400000)
+        throw new RangeError('Date range must be bounded to 366 days');
+    return { since: a, until: b };
+}
+function campaignDays(params) {
+    const from = params.get('from'), to = params.get('to');
+    const first = date(from), last = date(to);
+    if (last < first || last - first > 365 * 86400000)
+        throw new RangeError('Campaign date range exceeds 366 days');
+    return { from: from, to: to };
+}
+const sha = (source) => "'sha256-" + createHash('sha256').update(source).digest('base64') + "'";
+const escapeCsv = (item) => {
+    const value = String(item ?? '');
+    // Spreadsheet formulas must remain literal data, even when preceded by whitespace.
+    const safe = /^[\s\uFEFF]*[=+@\-\t\r]/.test(value) ? "'" + value : value;
+    return '"' + safe.replace(/"/g, '""') + '"';
+};
+const csv = (items) => [
+    ['chartId', 'title', 'dimension', 'value', 'total', 'mode', 'coverage', 'truncated'].map(escapeCsv).join(','),
+    ...items.flatMap(item => item.labels.map((label, index) => [item.id, item.title, label, item.values[index], item.total, item.queryMode ?? 'unknown', item.coverage ?? item.numericCoverage ?? '', item.truncated].map(escapeCsv).join(',')))
+].join('\r\n') + '\r\n';
+function exported(data, format, filename) {
+    const payload = format === 'csv' ? csv(Array.isArray(data) ? data : [data]) : JSON.stringify(data);
+    if (Buffer.byteLength(payload) > 256 * 1024)
+        return error('Export exceeds 256 KiB limit; narrow your selection', 413);
+    return new Response(payload, { headers: { ...headers, 'content-type': format === 'csv' ? 'text/csv; charset=utf-8' : 'application/json; charset=utf-8',
+            'content-disposition': `attachment; filename="${filename}.${format}"` } });
+}
+export function createReports(options) {
+    if (!options?.analytics || typeof options.authorize !== 'function')
+        throw new TypeError('Reports requires analytics and an application authorizer');
+    if (options.resolveScope && typeof options.resolveScope !== 'function')
+        throw new TypeError('Invalid tenant resolver');
+    if (options.site !== undefined && !validSite(options.site))
+        throw new TypeError('Invalid enforced site');
+    const prefix = options.prefix ?? '/_reports';
+    if (!/^\/[A-Za-z0-9/_-]+$/.test(prefix) || prefix.includes('//') || prefix.endsWith('/'))
+        throw new TypeError('Invalid reports path');
+    if (options.dashboardHost && !/^[A-Za-z0-9.-]+(?::\d{2,5})?$/.test(options.dashboardHost))
+        throw new TypeError('Invalid reports dashboard host');
+    if (options.maxSourceRows !== undefined && (!Number.isSafeInteger(options.maxSourceRows) || options.maxSourceRows < 1 || options.maxSourceRows > 500))
+        throw new RangeError('Invalid report row cap');
+    const store = options.store ?? createMemoryReportsStore();
+    const source = options.source ?? options.analytics;
+    const authorized = async (req, action, id) => {
+        if (options.dashboardHost && new URL(req.url).host !== options.dashboardHost)
+            return false;
+        try {
+            return await options.authorize(req, action, id) === true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const scoped = async (req) => {
+        if (!options.resolveScope)
+            return { site: options.site, store, source };
+        const scope = await options.resolveScope(req);
+        if (!scope || !validSite(scope.site) || !scope.store || typeof scope.store.load !== 'function' || typeof scope.store.save !== 'function' ||
+            !scope.source && typeof source.events !== 'function' || scope.source && typeof scope.source.events !== 'function' ||
+            options.site !== undefined && scope.site !== options.site)
+            throw new Error('Untrusted reports tenant scope');
+        return { site: scope.site, store: scope.store, source: scope.source ?? source };
+    };
+    const main = async (req) => {
+        if (!await authorized(req, 'read'))
+            return new Response('Not found', { status: 404 });
+        const html = reportDashboard(prefix);
+        const script = html.match(/<script>([\s\S]*?)<\/script>/)?.[1] ?? '';
+        const style = html.match(/<style>([\s\S]*?)<\/style>/)?.[1] ?? '';
+        return new Response(html, { headers: { ...headers, 'content-type': 'text/html; charset=utf-8',
+                'content-security-policy': `default-src 'none'; script-src ${sha(script)}; style-src ${sha(style)}; connect-src 'self'; base-uri 'none'; form-action 'none'; object-src 'none'; frame-ancestors 'none'` } });
+    };
+    const api = async (req) => {
+        const action = req.method === 'PUT' ? 'edit' : 'read';
+        if (!await authorized(req, action))
+            return error('Forbidden', 403);
+        if (!['GET', 'PUT'].includes(req.method))
+            return error('Method not allowed', 405);
+        let tenantStore;
+        try {
+            tenantStore = (await scoped(req)).store;
+        }
+        catch {
+            return error('Report storage unavailable', 503);
+        }
+        if (req.method === 'GET') {
+            try {
+                return json(validateReports(await tenantStore.load()));
+            }
+            catch {
+                return error('Report storage unavailable', 503);
+            }
+        }
+        if (req.headers.get('origin') !== new URL(req.url).origin)
+            return error('Origin required', 403);
+        let next;
+        try {
+            const raw = await req.text();
+            if (Buffer.byteLength(raw) > 256 * 1024)
+                return error('Report document too large', 413);
+            next = validateReports(JSON.parse(raw));
+        }
+        catch {
+            return error('Invalid report document', 422);
+        }
+        try {
+            if (!await tenantStore.save(next, next.version - 1))
+                return error('Version conflict', 409);
+            return json({ ok: true, version: next.version });
+        }
+        catch {
+            return error('Report storage unavailable', 503);
+        }
+    };
+    const catalog = async (req) => {
+        if (!await authorized(req, 'read'))
+            return error('Forbidden', 403);
+        if (req.method !== 'GET')
+            return error('Method not allowed', 405);
+        try {
+            const params = new URL(req.url).searchParams;
+            const rawLimit = params.get('limit') ?? '20', rawCursor = params.get('cursor');
+            if (!/^\d{1,2}$/.test(rawLimit) || Number(rawLimit) < 1 || Number(rawLimit) > 50)
+                return error('Invalid page size', 422);
+            const doc = validateReports(await (await scoped(req)).store.load());
+            let offset = 0;
+            if (rawCursor) {
+                const match = /^(\d+):(\d{1,3})$/.exec(rawCursor);
+                if (!match)
+                    return error('Invalid page cursor', 422);
+                if (Number(match[1]) !== doc.version)
+                    return error('Report catalog changed; reload from first page', 409);
+                offset = Number(match[2]);
+                if (offset > doc.reports.length)
+                    return error('Invalid page cursor', 422);
+            }
+            const take = Number(rawLimit), items = doc.reports.slice(offset, offset + take).map(r => ({ id: r.id, name: r.name, description: r.description ?? '', pages: r.pages.length }));
+            return json({ version: doc.version, items, nextCursor: offset + take < doc.reports.length ? `${doc.version}:${offset + take}` : null, total: doc.reports.length });
+        }
+        catch {
+            return error('Report catalog unavailable', 503);
+        }
+    };
+    const locate = (doc, params) => {
+        const reportId = params.get('report'), pageId = params.get('page'), chartId = params.get('chart');
+        const report = doc.reports.find(r => r.id === reportId), page = report?.pages.find(p => p.id === pageId);
+        if (!page)
+            return null;
+        if (chartId && !page.charts.some(c => c.id === chartId))
+            return null;
+        return { report, page, charts: chartId ? page.charts.filter(c => c.id === chartId) : page.charts };
+    };
+    const charts = async (req, kind) => {
+        if (req.method !== 'GET')
+            return error('Method not allowed', 405);
+        const params = new URL(req.url).searchParams;
+        if (kind === 'export' && !['json', 'csv'].includes(params.get('format') ?? 'json'))
+            return error('Invalid export format', 422);
+        let window;
+        try {
+            window = utcWindow(params);
+        }
+        catch {
+            return error('Invalid or excessive UTC date window', 422);
+        }
+        try {
+            const scope = await scoped(req), doc = validateReports(await scope.store.load()), target = locate(doc, params);
+            if (!target)
+                return error('Unknown report page or chart', 404);
+            if (kind === 'query' && target.charts.length !== 1)
+                return error('Choose exactly one chart', 422);
+            if (target.charts.length > 12)
+                return error('Page export is limited to 12 charts', 422);
+            // 366-day native grouping issues one COUNT per UTC day; bound multi-chart amplification.
+            let estimatedQueries = 0;
+            for (const chart of target.charts) {
+                const merged = { ...chart, ...window };
+                if (merged.groupBy === 'day' && merged.since !== undefined && merged.until !== undefined) {
+                    const from = Date.UTC(new Date(merged.since).getUTCFullYear(), new Date(merged.since).getUTCMonth(), new Date(merged.since).getUTCDate());
+                    const to = Date.UTC(new Date(merged.until).getUTCFullYear(), new Date(merged.until).getUTCMonth(), new Date(merged.until).getUTCDate());
+                    estimatedQueries += 2 + Math.floor((to - from) / 86400000);
+                }
+                else
+                    estimatedQueries++;
+            }
+            if (estimatedQueries > 500)
+                return error('Export exceeds query budget; narrow the UTC date range or select one chart', 422);
+            for (const chart of target.charts)
+                if (chart.groupBy.startsWith('property:') && !await authorized(req, 'sensitive', chart.id))
+                    return error('Sensitive chart permission required', 403);
+            const results = [];
+            for (const chart of target.charts) {
+                const merged = { ...chart, ...window };
+                results.push(await queryChart(scope.source, merged, options.maxSourceRows ?? 500, scope.site));
+            }
+            if (kind === 'query')
+                return json(results[0]);
+            const format = params.get('format') ?? 'json';
+            return exported(format === 'csv' ? results : { report: target.report.id, page: target.page.id,
+                generatedAt: new Date().toISOString(), site: scope.site ?? null, charts: results,
+                disclaimer: 'Coverage is chart-specific. SMTP acceptance and provider notifications do not confirm inbox delivery.' }, format, `reports-${target.report.id}-${target.page.id}`);
+        }
+        catch {
+            return error('Report query unavailable', 503);
+        }
+    };
+    const query = async (req) => {
+        if (!await authorized(req, 'read'))
+            return error('Forbidden', 403);
+        return charts(req, 'query');
+    };
+    const exportRoute = async (req) => {
+        if (!await authorized(req, 'export'))
+            return error('Forbidden', 403);
+        return charts(req, 'export');
+    };
+    const campaign = async (req) => {
+        if (req.method !== 'GET')
+            return error('Method not allowed', 405);
+        if (!options.campaigns)
+            return error('Campaign reporting unavailable', 404);
+        const params = new URL(req.url).searchParams;
+        const code = params.get('code');
+        if (!isReportId(code))
+            return error('Invalid campaign code', 422);
+        if (!await authorized(req, 'campaign', code))
+            return error('Forbidden', 403);
+        const kind = params.get('kind') ?? 'delivery';
+        if (!['delivery', 'performance', 'daily', 'activity'].includes(kind))
+            return error('Invalid campaign report kind', 422);
+        let days;
+        if (kind === 'daily' || kind === 'activity')
+            try {
+                days = campaignDays(params);
+            }
+            catch {
+                return error('Invalid or excessive campaign UTC date window', 422);
+            }
+        const cursor = params.get('cursor');
+        const rawLimit = params.get('limit') ?? '200';
+        if (kind === 'delivery' && (!/^\d{1,3}$/.test(rawLimit) || Number(rawLimit) < 1 || Number(rawLimit) > 200 || cursor !== null && (cursor.length > 1024 || !cursor)))
+            return error('Invalid campaign recipient page', 422);
+        try {
+            // Scope resolution and the campaign service independently enforce the same application-selected tenant.
+            const site = (await scoped(req)).site;
+            if (kind === 'delivery') {
+                const page = await options.campaigns.report(code, { cursor, limit: Number(rawLimit), site });
+                if (page.campaignCode !== code)
+                    throw new Error('Campaign mismatch');
+                return json({ kind, code, ...marketingDeliveryPageCharts(page) });
+            }
+            if (kind === 'performance') {
+                if (!options.campaigns.performance)
+                    return error('Native campaign performance not configured', 404);
+                const snapshot = await options.campaigns.performance(code, site);
+                if (snapshot.campaignId !== code)
+                    throw new Error('Campaign mismatch');
+                return json({ kind, code, charts: campaignPerformanceCharts(snapshot), coverage: { smtp: 'durable-delivery-states', provider: 'reported-events-only' } });
+            }
+            if (kind === 'daily') {
+                if (!options.campaigns.dailyTrends)
+                    return error('Daily campaign trends not configured', 404);
+                const snapshot = await options.campaigns.dailyTrends(code, days.from, days.to, site);
+                if (snapshot.campaignId !== code || snapshot.from !== days.from || snapshot.to !== days.to)
+                    throw new Error('Campaign mismatch');
+                return json({ kind, code, charts: campaignDailyTrendsCharts(snapshot), coverage: { delivery: 'last-state-update-day', snapshotConsistent: false } });
+            }
+            if (!options.campaigns.activity)
+                return error('Campaign tracking reports not configured', 404);
+            const activity = await options.campaigns.activity(code, days.from, days.to, site);
+            if (activity.campaignCode !== code || activity.from !== days.from || activity.to !== days.to)
+                throw new Error('Campaign mismatch');
+            return json({ kind, code, ...campaignActivityCharts(activity) });
+        }
+        catch {
+            return error('Campaign report unavailable', 503);
+        }
+    };
+    return { store, query: async (reportId, pageId, chartId) => {
+            if (options.resolveScope)
+                throw new Error('Tenant-scoped reports require an authorized HTTP request');
+            const doc = validateReports(await store.load());
+            const chart = doc.reports.find(r => r.id === reportId)?.pages.find(p => p.id === pageId)?.charts.find(c => c.id === chartId);
+            if (!chart)
+                throw new Error('Unknown report chart');
+            return queryChart(source, chart, options.maxSourceRows ?? 500, options.site);
+        }, routes() {
+            return [{ pattern: prefix, handler: main }, { pattern: prefix + '/api', handler: api },
+                { pattern: prefix + '/catalog', handler: catalog }, { pattern: prefix + '/query', handler: query },
+                { pattern: prefix + '/export', handler: exportRoute }, { pattern: prefix + '/campaign', handler: campaign }];
+        } };
+}