measurr 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,8 @@ returns shaped, typed rows.
 - Database-neutral definitions: dialects plug in through the `Dialect` interface, and Postgres
   ships today (`measurr/postgres`).
 - Tenant-scoped by construction: the engine adds the tenant filter to every statement and
-  refuses to run without a tenant.
+  refuses to run without a tenant. Platform admins can query every tenant only through an
+  explicit `allTenants` value that no query input can carry.
 - The query schema is generated with Zod, so it doubles as an LLM tool schema
   (`z.toJSONSchema`) and as the request validator. It can be built per caller, offering only
   the datasets they may query.
@@ -150,6 +151,38 @@ ${analyticsToolGuidance}`
 the input named no known dataset, so free text from a model never becomes a metric label.
 What the hook throws or rejects with is swallowed; it cannot fail a query.
 
+## Tenants and platform admins
+
+`tenant(ctx)` decides the scope of every statement, including the lookups that resolve filter
+labels. It returns a tenant id, or `allTenants` to drop the tenant filter for a caller allowed
+to see every tenant. Anything else (null, undefined, `''`, any other value) is refused with
+`AnalyticsError('missing_tenant')`, so a missing organization never widens a query.
+
+The scope comes only from `ctx`, which your server builds from the session. `allTenants` is a
+symbol, so a query (JSON, a model's tool call) cannot carry it. A discriminated context keeps
+the rule in one typed place:
+
+```ts
+import { allTenants } from 'measurr'
+
+type Ctx =
+	// A super admin may narrow to one organization, or see all of them.
+	| { role: 'superAdmin'; organizationId?: OrganizationId }
+	// Everyone else is always scoped to the organization they are signed in to.
+	| { role: 'member'; organizationId: OrganizationId }
+
+const analytics = createAnalytics({
+	// ...
+	tenant: (ctx: Ctx) =>
+		ctx.role === 'superAdmin' ? (ctx.organizationId ?? allTenants) : ctx.organizationId
+})
+```
+
+Resolve a super admin's optional organization id on the server (from the request, after
+checking the session) before building `ctx`; never read it from the query input. Unscoped
+lookups resolve labels across tenants, so `"Complaint"` matches every tenant's tag of that
+name.
+
 ## The model
 
 | Concept | What it is |
@@ -301,7 +334,7 @@ empty tenant sees nothing (tenant isolation), and day buckets in a far-from-UTC
 
 ## Stable API
 
-Kept stable for publishing: `createAnalytics` and its options, `analytics.query`,
+Kept stable for publishing: `createAnalytics` and its options, `allTenants`, `analytics.query`,
 `explain`, `querySchema`, `resultSchema`, `listDatasets`; `AnalyticsResultSchema`,
 `analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset`, `measure.*`,
 `dimension.*`, `table` / `Table`, the expression builders; the `Dialect`, `SqlRenderer` and

package/dist/analytics.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { CompiledStatement, Dialect } from './compile.js';
 import type { AnyDataset, AnyDimension } from './dataset.js';
+import { type Tenant } from './plan.js';
 import { type DatasetQuery, type QueryResult, type ResultOf } from './query.js';
 export type Row = Record<string, unknown>;
 /** A database: a dialect to compile with and a function that runs the compiled SQL. */
@@ -56,8 +57,12 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
     datasets: DS;
     /** Databases by name; a dataset's `source` picks one, or the only one is used. */
     sources: Record<string, AnalyticsSource>;
-    /** The tenant every query is scoped to. Queries without one are refused. */
-    tenant: (ctx: Ctx) => string | number | null | undefined;
+    /**
+     * The tenant every query is scoped to. Queries without one (null, undefined, '') are
+     * refused. Return `allTenants` to drop the tenant filter, only for callers allowed to see
+     * every tenant's rows.
+     */
+    tenant: (ctx: Ctx) => Tenant | null | undefined;
     /**
      * Whether `ctx` may query `dataset`. Everything is allowed when omitted. It decides what
      * `listDatasets(ctx)` and `querySchema({ ctx })` offer, and is checked again on every query.

package/dist/{index-m0czpsyv.js → index-dj3369zz.js}

@@ -309,9 +309,6 @@ function datasetResultSchema(dataset) {
 }
 var AnalyticsResultSchema2 = resultSchemaOf(z.record(z.string(), z.union([dimensionValue, measureValue])), z.record(z.string(), measureValue));
 
-// src/analytics.ts
-import { z as z2 } from "zod";
-
 // src/plan.ts
 function normalizeQuery(dataset, parsed) {
   const filters = (parsed.filters ?? []).map((filter) => filter.op === "in" || filter.op === "notIn" ? { ...filter, values: [...new Set(filter.values)] } : filter);
@@ -327,6 +324,7 @@ function normalizeQuery(dataset, parsed) {
     limit: parsed.limit ?? DEFAULT_LIMIT
   };
 }
+var allTenants2 = Symbol("measurr.allTenants");
 var param = (value) => ({ kind: "param", value });
 var and = (items) => items.length === 1 && items[0] ? items[0] : { kind: "logical", op: "and", items };
 function measureOf(dataset, key) {
@@ -413,7 +411,7 @@ function dimensionNodes(dataset, key, timezone) {
   }
 }
 function baseWhere(dataset, tenant, period) {
-  const where = [
+  const where = tenant === allTenants2 ? [] : [
     {
       kind: "compare",
       op: "=",
@@ -685,6 +683,7 @@ function resultNotes(dataset, query) {
 }
 
 // src/analytics.ts
+import { z as z2 } from "zod";
 class AnalyticsError2 extends Error {
   code;
   name = "AnalyticsError";
@@ -768,7 +767,7 @@ function createAnalytics2(options) {
       throw new AnalyticsError2("forbidden", `Not allowed to query ${dataset.key}`);
     }
     const tenant = options.tenant(ctx);
-    if (tenant === null || tenant === undefined || tenant === "") {
+    if (!isTenant(tenant)) {
       throw new AnalyticsError2("missing_tenant", "Refusing to query without a tenant");
     }
     const timezone = await options.timezone?.(ctx) || "UTC";
@@ -888,6 +887,9 @@ function createAnalytics2(options) {
     listDatasets: async (ctx) => (await allowedDatasets(ctx)).map((dataset) => catalogEntry(dataset))
   };
 }
+function isTenant(value) {
+  return value === allTenants2 || typeof value === "string" && value !== "" || typeof value === "number" && Number.isFinite(value);
+}
 function periodStatements(dataset, query, context) {
   const grouped = query.groupBy.length > 0;
   return {
@@ -1289,4 +1291,4 @@ function plainCaseValues(node) {
   return [];
 }
 
-export { MAX_MEASURES, AnalyticsResultSchema2, AnalyticsError2, isAnalyticsError2, createAnalytics2, measure2, dimension2, defineDataset2 };
+export { MAX_MEASURES, AnalyticsResultSchema2, allTenants2, AnalyticsError2, isAnalyticsError2, createAnalytics2, measure2, dimension2, defineDataset2 };

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { type AnyDataset, type AnyDimension, type AnyMeasure, type Dataset, type
 export { and, caseWhen, coalesce, type ColumnKey, eq, Expr, type ExprNode, exists, gt, gte, inList, isNotNull, isNull, literal, lt, lte, minutesAgo, ne, not, or, type SqlType, Table, type TableRef, table, toText } from './expr.js';
 export { analyticsToolGuidance } from './guidance.js';
 export type { PeriodInput, PeriodPreset } from './period.js';
+export { allTenants, type Tenant } from './plan.js';
 export { AnalyticsResultSchema, type DatasetFilter, type DatasetQuery, type QueryResult, type ResultOf } from './query.js';

package/dist/index.js

@@ -1,12 +1,13 @@
 import {
   AnalyticsResultSchema2,
+  allTenants2,
   AnalyticsError2,
   isAnalyticsError2,
   createAnalytics2,
   measure2,
   dimension2,
   defineDataset2
-} from "./index-m0czpsyv.js";
+} from "./index-dj3369zz.js";
 import {
   CompileError2,
   decodeNumber2,
@@ -48,6 +49,7 @@ export {
   CompileError2 as CompileError,
   Expr2 as Expr,
   Table2 as Table,
+  allTenants2 as allTenants,
   analyticsToolGuidance,
   and2 as and,
   caseWhen2 as caseWhen,

package/dist/plan.d.ts

@@ -45,9 +45,16 @@ export type ParsedQuery = {
     limit?: number | undefined;
 };
 export declare function normalizeQuery(dataset: AnyDataset, parsed: ParsedQuery): NormalizedQuery;
+/**
+ * What `tenant(ctx)` returns to query every tenant at once, for platform admins. It is a
+ * symbol, so no query input (JSON, a model's tool call) can ever carry it.
+ */
+export declare const allTenants: unique symbol;
+/** One tenant's id, or `allTenants`. */
+export type Tenant = string | number | typeof allTenants;
 /** What the planner needs besides the query: values from the hooks and resolved labels. */
 export type PlanContext = {
-    tenant: string | number;
+    tenant: Tenant;
     timezone: string;
     period: ResolvedPeriod;
     /** The moment the query runs. */
@@ -70,7 +77,7 @@ export declare function planQuery(dataset: AnyDataset, query: NormalizedQuery, c
  * Looks up an open dimension's keys and names. With `values`, only entries whose key or name
  * (case-insensitive) matches; without, the first entries by name, to list valid values.
  */
-export declare function planLookup(dataset: AnyDataset, dimensionKey: string, tenant: string | number, values: readonly string[] | null, now: Date): SelectStatement;
+export declare function planLookup(dataset: AnyDataset, dimensionKey: string, tenant: Tenant, values: readonly string[] | null, now: Date): SelectStatement;
 export type ShapedValue = {
     key: string | number | null;
     label: string;

package/dist/testing.js

@@ -3,7 +3,7 @@ import {
   createAnalytics2,
   measure2,
   dimension2
-} from "./index-m0czpsyv.js";
+} from "./index-dj3369zz.js";
 
 // src/testing.ts
 var COUNT = "__contractCount";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "measurr",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "A small typed semantic layer: datasets of measures and dimensions compiled to one SQL statement per dialect.",
 	"type": "module",
 	"module": "./dist/index.js",

package/src/analytics.ts

@@ -5,6 +5,8 @@ import {
 	type NormalizedQuery,
 	type ParsedQuery,
 	type PlanContext,
+	type Tenant,
+	allTenants,
 	normalizeQuery,
 	planLookup,
 	planQuery,
@@ -112,8 +114,12 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
 	datasets: DS
 	/** Databases by name; a dataset's `source` picks one, or the only one is used. */
 	sources: Record<string, AnalyticsSource>
-	/** The tenant every query is scoped to. Queries without one are refused. */
-	tenant: (ctx: Ctx) => string | number | null | undefined
+	/**
+	 * The tenant every query is scoped to. Queries without one (null, undefined, '') are
+	 * refused. Return `allTenants` to drop the tenant filter, only for callers allowed to see
+	 * every tenant's rows.
+	 */
+	tenant: (ctx: Ctx) => Tenant | null | undefined
 	/**
 	 * Whether `ctx` may query `dataset`. Everything is allowed when omitted. It decides what
 	 * `listDatasets(ctx)` and `querySchema({ ctx })` offer, and is checked again on every query.
@@ -195,6 +201,17 @@ export type AnalyticsResult<A, Q> =
 
 type ShapedResult = QueryResult<Row, Row>
 
+/** A parsed, authorized query with everything the hooks decide resolved. */
+type Prepared = {
+	dataset: AnyDataset
+	query: NormalizedQuery
+	tenant: Tenant
+	timezone: string
+	period: ResolvedPeriod
+	previous: ResolvedPeriod | null
+	now: Date
+}
+
 export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 	options: AnalyticsOptions<DS, Ctx>
 ): Analytics<DS, Ctx> {
@@ -273,7 +290,7 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 	}
 
 	/** Parse, authorize, and resolve everything that comes from hooks. */
-	const prepare = async (input: unknown, ctx: Ctx) => {
+	const prepare = async (input: unknown, ctx: Ctx): Promise<Prepared> => {
 		const parsed = querySchemaFor(undefined).safeParse(input)
 		if (!parsed.success) {
 			throw new AnalyticsError(
@@ -291,8 +308,8 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			)
 		}
 
-		const tenant = options.tenant(ctx)
-		if (tenant === null || tenant === undefined || tenant === '') {
+		const tenant: unknown = options.tenant(ctx)
+		if (!isTenant(tenant)) {
 			throw new AnalyticsError(
 				'missing_tenant',
 				'Refusing to query without a tenant'
@@ -469,6 +486,18 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 	}
 }
 
+/**
+ * Fails closed: only a non-empty string, a finite number or `allTenants` scopes a query, even
+ * when a JavaScript caller's hook returns something its type does not allow.
+ */
+function isTenant(value: unknown): value is Tenant {
+	return (
+		value === allTenants ||
+		(typeof value === 'string' && value !== '') ||
+		(typeof value === 'number' && Number.isFinite(value))
+	)
+}
+
 /** The statement for a period's rows, and for its totals when the query groups. */
 function periodStatements(
 	dataset: AnyDataset,
@@ -562,7 +591,7 @@ function compileEverything(dataset: AnyDataset, dialect: Dialect): void {
 async function resolveOpenValues(
 	dataset: AnyDataset,
 	query: NormalizedQuery,
-	tenant: string | number,
+	tenant: Tenant,
 	now: Date,
 	run: (statement: SelectStatement) => Promise<readonly Row[]>,
 	dialect: Dialect

package/src/index.ts

@@ -65,6 +65,7 @@ export {
 } from './expr.js'
 export { analyticsToolGuidance } from './guidance.js'
 export type { PeriodInput, PeriodPreset } from './period.js'
+export { allTenants, type Tenant } from './plan.js'
 export {
 	AnalyticsResultSchema,
 	type DatasetFilter,

package/src/plan.ts

@@ -75,9 +75,18 @@ export function normalizeQuery(
 	}
 }
 
+/**
+ * What `tenant(ctx)` returns to query every tenant at once, for platform admins. It is a
+ * symbol, so no query input (JSON, a model's tool call) can ever carry it.
+ */
+export const allTenants: unique symbol = Symbol('measurr.allTenants')
+
+/** One tenant's id, or `allTenants`. */
+export type Tenant = string | number | typeof allTenants
+
 /** What the planner needs besides the query: values from the hooks and resolved labels. */
 export type PlanContext = {
-	tenant: string | number
+	tenant: Tenant
 	timezone: string
 	period: ResolvedPeriod
 	/** The moment the query runs. */
@@ -203,17 +212,20 @@ function dimensionNodes(
 /** Tenant, scope and period: the conditions every statement of a query carries. */
 function baseWhere(
 	dataset: AnyDataset,
-	tenant: string | number,
+	tenant: Tenant,
 	period: { time: string; start: Date; end: Date } | null
 ): ExprNode[] {
-	const where: ExprNode[] = [
-		{
-			kind: 'compare',
-			op: '=',
-			left: dataset.tenantColumn,
-			right: param(tenant)
-		}
-	]
+	const where: ExprNode[] =
+		tenant === allTenants
+			? []
+			: [
+					{
+						kind: 'compare',
+						op: '=',
+						left: dataset.tenantColumn,
+						right: param(tenant)
+					}
+				]
 	if (dataset.scope) where.push(dataset.scope)
 
 	if (period) {
@@ -408,7 +420,7 @@ function orderBy(
 export function planLookup(
 	dataset: AnyDataset,
 	dimensionKey: string,
-	tenant: string | number,
+	tenant: Tenant,
 	values: readonly string[] | null,
 	now: Date
 ): SelectStatement {