measurr 0.1.0 → 0.3.0

package/README.md

@@ -10,7 +10,9 @@ 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. A caller can be scoped to one tenant or a list of them;
+  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,15 +152,59 @@ ${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 (`TenantId`, a non-empty string or a finite number), a readonly
+list of them, or `allTenants` to drop the tenant filter for a caller allowed to see every
+tenant. Anything else is refused with `AnalyticsError('missing_tenant')`: null, undefined,
+`''`, a list containing one of those or `allTenants`, or any other value. A missing
+organization never widens a query.
+
+A list compiles to `tenantColumn IN (...)` with one parameter per id; a one-element list is
+the same statement as its id. An empty list is a scope that matches no rows: a reseller with
+no connected organizations sees zeros, never everything. Lists are for callers scoped to a set
+of organizations, such as an organization-group admin, a reseller, or either narrowed to a
+region:
+
+```ts
+tenant: (ctx: Ctx) => ctx.visibleOrganizationIds // readonly OrganizationId[]
+```
+
+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 |
 | --- | --- |
-| Dataset | One fact table: tenant column, optional scope, time fields, measures, dimensions, source. |
+| Dataset | One fact table: tenant column, optional scope, time fields, default period, measures, dimensions, source. |
 | Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another) or `ratio` (one measure over another, after aggregation). |
 | Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). |
 | Query | `dataset`, 1-4 `measures`, 0-2 `groupBy`, `filters`, `period`, `time`, `compareToPrevious`, `sort` (by an asked measure or grouped dimension), `limit` (1-100, default 20). |
-| Result | `{ period, rows, totals, previous?, notes, truncated }`. |
+| Result | `{ period, rows, totals, previous?, notes, truncated }`; `period` is `{ from, to, timezone }` or `{ all: true, timezone }`. |
 
 **Operators per dimension kind.** Closed and open dimensions take `in`, `notIn`, `isEmpty`
 and `isNotEmpty`; numeric and time dimensions take `between`, `isEmpty` and `isNotEmpty`. The
@@ -189,6 +235,21 @@ try {
 The previous period has the same length and ends the day before. Time buckets use the same
 timezone. `time` picks the time field the period applies to; a time dimension names its own.
 
+`{ all: true }` drops the time filter: every row counts, and time buckets and parts still group
+by the time field. It has no previous period, so `compareToPrevious` with it is an
+`invalid_query`. The result's `period` is then `{ all: true, timezone }` instead of
+`{ from, to, timezone }`; `previous.period` is always a range. The type follows the query. A
+query that names a range, or names no period on a dataset whose default is a range, gets
+`{ from, to, timezone }`, so `result.period.from` needs no narrowing. A query typed only as
+`AnalyticsQuery` (parsed from the schema) gets the `ResultPeriod` union; narrow it with
+`'all' in result.period`.
+
+A query that names no period (or sends null) gets the dataset's `defaultPeriod`, the last 30
+days unless the dataset says otherwise. A dataset that describes current state (units,
+organizations) sets `defaultPeriod: { all: true }`, so "how many units per status" counts
+every unit. The generated schema states each dataset's default, so a model knows what leaving
+`period` out means.
+
 **Totals are a separate, ungrouped statement**, so a many-to-many grouping (an order with
 two tags appears in two rows) never inflates them. Filters on many-to-many dimensions compile
 to `EXISTS`, so they never multiply rows either.
@@ -282,8 +343,8 @@ await assertDatasetContract({ dataset: orders, source, tenant: seededTenantId })
 It checks that every measure runs and returns a number or null, every grouping runs and its
 groups add up to the total (except many-to-many), `isEmpty` plus `isNotEmpty` equals the total,
 open dimensions filter by label to their group's count, closed dimensions filter by value, an
-empty tenant sees nothing (tenant isolation), and day buckets in a far-from-UTC timezone
-(default `Pacific/Auckland`) agree with single-day periods.
+empty tenant and an empty tenant list see nothing (tenant isolation), and day buckets in a
+far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods.
 
 ## Extending
 
@@ -301,13 +362,13 @@ 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
-`AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
-`assertDatasetContract`; and the types
-`AnalyticsQuery`, `AnalyticsResult`, `Ratio`, `AnalyticsError` codes and their details
+`analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset` (with `defaultPeriod`),
+`measure.*`, `dimension.*`, `table` / `Table`, the expression builders; the `Dialect`,
+`SqlRenderer` and `AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
+`assertDatasetContract`; and the types `AnalyticsQuery`, `AnalyticsResult`, `ResultPeriod`,
+`PeriodInput`, `Tenant`, `TenantId`, `Ratio`, `AnalyticsError` codes and their details
 (`isAnalyticsError`). `ExprNode` and `SelectStatement` are
 exported for dialect authors and may grow new node kinds.
 

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,13 @@ 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, or a list of them (an empty list matches no rows).
+     * Queries without one (null, undefined, '', a list holding one of those) 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/dataset.d.ts

@@ -1,4 +1,5 @@
 import { type Expr, type ExprNode, type SqlType, type Table, type TableRef, type TimeBucketUnit, type TimePartName } from './expr.js';
+import { DEFAULT_PERIOD, type PeriodInput } from './period.js';
 declare const ratioBrand: unique symbol;
 /** A share or ratio between 0 and 1. Branded so nobody renders 0.42 as "0.42%". */
 export type Ratio = number & {
@@ -241,7 +242,7 @@ export type TimeField = {
     readonly column: ExprNode;
     readonly label: string;
 };
-export type Dataset<K extends string = string, M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>, T extends string = string> = {
+export type Dataset<K extends string = string, M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>, T extends string = string, P extends PeriodInput = PeriodInput> = {
     readonly key: K;
     readonly label: string;
     readonly description: string;
@@ -251,6 +252,8 @@ export type Dataset<K extends string = string, M extends Record<string, AnyMeasu
     readonly scope: ExprNode | null;
     readonly time: Readonly<Record<T, TimeField>>;
     readonly defaultTime: T;
+    /** Kept as a type, so results know whether a query without a period covers all time. */
+    readonly defaultPeriod: P;
     readonly measures: M;
     readonly dimensions: Dm;
 };
@@ -272,7 +275,7 @@ type CheckDimensions<Dm, T extends string> = {
         time: T;
     } : unknown;
 };
-export type DatasetDefinition<K extends string, M extends Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension>, T extends string> = {
+export type DatasetDefinition<K extends string, M extends Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension>, T extends string, P extends PeriodInput> = {
     key: K;
     label: string;
     /** Tells a reader (and a model) what one row of the dataset is. */
@@ -292,6 +295,11 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
     }>;
     /** The time field periods apply to when a query names none; the first one by default. */
     defaultTime?: NoInfer<T> | undefined;
+    /**
+     * The period of a query that names none; the last 30 days by default. A dataset of current
+     * state (units, organizations) sets `{ all: true }`.
+     */
+    defaultPeriod?: P | undefined;
     measures: M & CheckMeasures<M>;
     dimensions: Dm & CheckDimensions<Dm, NoInfer<T>>;
 };
@@ -299,5 +307,5 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
  * Declares a dataset: one fact table with its tenant column, time fields, measures and
  * dimensions. Keys stay literal types, so queries and result rows are typed from it.
  */
-export declare function defineDataset<const K extends string, const M extends Record<string, AnyMeasure>, const Dm extends Record<string, AnyDimension>, const T extends string>(definition: DatasetDefinition<K, M, Dm, T>): Dataset<K, M, Dm, T>;
+export declare function defineDataset<const K extends string, const M extends Record<string, AnyMeasure>, const Dm extends Record<string, AnyDimension>, const T extends string, const P extends PeriodInput = typeof DEFAULT_PERIOD>(definition: DatasetDefinition<K, M, Dm, T, P>): Dataset<K, M, Dm, T, P>;
 export {};

package/dist/guidance.d.ts

@@ -2,4 +2,4 @@
  * How a model should use an analytics query tool, as markdown bullets for its instructions.
  * It does not name the tool, so add a line that does.
  */
-export declare const analyticsToolGuidance = "- Answer every \"how many\", \"how much\", \"per week\" or \"split by\" question with the analytics tool. Never count by hand from lists or pages.\n- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.\n- Say which period and filters the numbers cover, using the dates in the result (\"1-30 September\").\n- Compare with the previous period (compareToPrevious) when the change is the point, such as \"is it going up\".\n- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.\n- Ask one short question only when the period is genuinely ambiguous (\"this season\") and someone can answer; otherwise take the natural reading and state it.";
+export declare const analyticsToolGuidance = "- Answer every \"how many\", \"how much\", \"per week\" or \"split by\" question with the analytics tool. Never count by hand from lists or pages.\n- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.\n- Say which period and filters the numbers cover, using the dates in the result (\"1-30 September\", or \"all time\").\n- Compare with the previous period (compareToPrevious) when the change is the point, such as \"is it going up\".\n- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.\n- Ask one short question only when the period is genuinely ambiguous (\"this season\") and someone can answer; otherwise take the natural reading and state it.";

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

@@ -8,7 +8,9 @@ import { z } from "zod";
 
 // src/period.ts
 var MAX_PERIOD_DAYS = 731;
-var DEFAULT_PERIOD = { last: { days: 30 } };
+var DEFAULT_PERIOD = {
+  last: { days: 30 }
+};
 var DAY_MS = 86400000;
 var formatterCache = new Map;
 function formatter(timezone) {
@@ -165,8 +167,18 @@ var periodSchema = z.union([
     })
   }),
   z.object({ from: isoDate, to: isoDate.describe("Last day, inclusive.") }),
-  z.object({ preset: z.enum(PERIOD_PRESETS) })
-]).describe("Which days to count, in the organization timezone. Defaults to the last 30 days. At most two years.");
+  z.object({ preset: z.enum(PERIOD_PRESETS) }),
+  z.object({ all: z.literal(true) }).describe("Every row, with no time filter.")
+]);
+function describePeriod(period) {
+  if ("all" in period)
+    return "all time (no time filter)";
+  if ("last" in period)
+    return `the last ${period.last.days} days`;
+  if ("from" in period)
+    return `${period.from} to ${period.to}`;
+  return period.preset;
+}
 function describeList(entries) {
   return entries.map(([key, entry]) => `${key}: ${entry.label}${entry.description ? ` (${entry.description})` : ""}`).join(" · ");
 }
@@ -247,11 +259,11 @@ function datasetQuerySchema(dataset) {
     ...firstFilter && {
       filters: z.array(z.discriminatedUnion("dimension", [firstFilter, ...otherFilters])).optional().describe("Every filter must match.")
     },
-    period: periodSchema.nullish(),
+    period: periodSchema.describe(`Which days to count, in the organization timezone. Defaults to ${describePeriod(dataset.defaultPeriod)}. A range covers at most two years.`).nullish(),
     ...timeKeys && {
       time: z.enum(timeKeys).optional().describe(`Which time field the period applies to; time dimensions name their own. Defaults to ${dataset.defaultTime}. ${describeList(Object.entries(dataset.time))}`)
     },
-    compareToPrevious: z.boolean().optional().describe("Also return the previous period of the same length."),
+    compareToPrevious: z.boolean().optional().describe("Also return the previous period of the same length. Not for all-time periods."),
     sort: z.object({
       by: z.enum(sortKeys),
       direction: z.enum(["asc", "desc"]).optional()
@@ -268,6 +280,14 @@ function datasetQuerySchema(dataset) {
         message: `Sort by one of the asked measures or grouped dimensions: ${returned.join(", ")}`
       });
     }
+    const period = query.period ?? dataset.defaultPeriod;
+    if (query.compareToPrevious && "all" in period) {
+      context.addIssue({
+        code: "custom",
+        path: ["compareToPrevious"],
+        message: "An all-time period has no previous period to compare with"
+      });
+    }
   });
 }
 function buildQuerySchema(datasets) {
@@ -276,11 +296,15 @@ function buildQuerySchema(datasets) {
     throw new Error("querySchema needs at least one dataset");
   return z.discriminatedUnion("dataset", [first, ...rest]);
 }
-var periodOutput = z.object({
+var rangeOutput = z.object({
   from: z.string(),
   to: z.string(),
   timezone: z.string()
 });
+var periodOutput = z.union([
+  rangeOutput,
+  z.object({ all: z.literal(true), timezone: z.string() })
+]);
 var measureValue = z.number().nullable();
 var dimensionValue = z.object({
   key: z.union([z.string(), z.number()]).nullable(),
@@ -291,7 +315,7 @@ function resultSchemaOf(row, totals) {
     period: periodOutput,
     rows: z.array(row),
     totals,
-    previous: z.object({ period: periodOutput, rows: z.array(row), totals }).optional(),
+    previous: z.object({ period: rangeOutput, rows: z.array(row), totals }).optional(),
     notes: z.array(z.string()),
     truncated: z.boolean()
   });
@@ -309,9 +333,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);
@@ -320,13 +341,14 @@ function normalizeQuery(dataset, parsed) {
     measures: [...new Set(parsed.measures)],
     groupBy: [...new Set(parsed.groupBy ?? [])],
     filters,
-    period: parsed.period ?? DEFAULT_PERIOD,
+    period: parsed.period ?? dataset.defaultPeriod,
     time: parsed.time ?? dataset.defaultTime,
     compareToPrevious: parsed.compareToPrevious ?? false,
     sort: parsed.sort ? { by: parsed.sort.by, direction: parsed.sort.direction ?? "desc" } : null,
     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,14 +435,22 @@ function dimensionNodes(dataset, key, timezone) {
   }
 }
 function baseWhere(dataset, tenant, period) {
-  const where = [
-    {
+  const where = [];
+  if (tenant !== allTenants2) {
+    const ids = typeof tenant === "object" ? [...new Set(tenant)] : [tenant];
+    const [only] = ids;
+    where.push(ids.length === 1 && only !== undefined ? {
       kind: "compare",
       op: "=",
       left: dataset.tenantColumn,
-      right: param(tenant)
-    }
-  ];
+      right: param(only)
+    } : {
+      kind: "in",
+      item: dataset.tenantColumn,
+      values: ids.map(param),
+      negated: false
+    });
+  }
   if (dataset.scope)
     where.push(dataset.scope);
   if (period) {
@@ -522,7 +552,7 @@ function planQuery(dataset, query, context, grouped) {
     });
   }
   const where = [
-    ...baseWhere(dataset, context.tenant, {
+    ...baseWhere(dataset, context.tenant, context.period && {
       time: query.time,
       start: context.period.start,
       end: context.period.end
@@ -685,6 +715,7 @@ function resultNotes(dataset, query) {
 }
 
 // src/analytics.ts
+import { z as z2 } from "zod";
 class AnalyticsError2 extends Error {
   code;
   name = "AnalyticsError";
@@ -768,7 +799,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";
@@ -779,14 +810,14 @@ function createAnalytics2(options) {
     const at = now();
     let period;
     try {
-      period = resolvePeriod(query.period, timezone, at);
+      period = "all" in query.period ? null : resolvePeriod(query.period, timezone, at);
     } catch (error) {
       if (error instanceof PeriodError) {
         throw new AnalyticsError2("invalid_period", error.message);
       }
       throw error;
     }
-    const previous = query.compareToPrevious ? previousPeriod(period) : null;
+    const previous = query.compareToPrevious && period ? previousPeriod(period) : null;
     return { dataset, query, tenant, timezone, period, previous, now: at };
   };
   const runQuery = async (input, ctx) => {
@@ -810,24 +841,22 @@ function createAnalytics2(options) {
       const { rows, truncated } = shapeRows(dataset, query, rawRows, dialect);
       const totalsRow = (rawTotals ?? rawRows)[0] ?? {};
       const totals = shapeMeasures(dataset, query.measures, totalsRow, dialect);
-      const periodOut = { from: target.from, to: target.to, timezone };
-      return { period: periodOut, rows, totals, truncated };
+      return { rows, totals, truncated };
     };
+    const range = ({ from, to }) => ({ from, to, timezone });
     const [current, before] = await Promise.all([
       runPeriod(period),
-      previous ? runPeriod(previous) : null
+      previous && runPeriod(previous).then(({ rows, totals }) => ({
+        period: range(previous),
+        rows,
+        totals
+      }))
     ]);
     return {
-      period: current.period,
+      period: period ? range(period) : { all: true, timezone },
       rows: current.rows,
       totals: current.totals,
-      ...before && {
-        previous: {
-          period: before.period,
-          rows: before.rows,
-          totals: before.totals
-        }
-      },
+      ...before && { previous: before },
       notes: resultNotes(dataset, query),
       truncated: current.truncated
     };
@@ -888,6 +917,12 @@ function createAnalytics2(options) {
     listDatasets: async (ctx) => (await allowedDatasets(ctx)).map((dataset) => catalogEntry(dataset))
   };
 }
+function isTenant(value) {
+  return value === allTenants2 || isTenantId(value) || Array.isArray(value) && value.every(isTenantId);
+}
+function isTenantId(value) {
+  return typeof value === "string" && value !== "" || typeof value === "number" && Number.isFinite(value);
+}
 function periodStatements(dataset, query, context) {
   const grouped = query.groupBy.length > 0;
   return {
@@ -1175,6 +1210,7 @@ function defineDataset2(definition) {
     scope: definition.scope?.node ?? null,
     time,
     defaultTime: definition.defaultTime ?? firstTime[0],
+    defaultPeriod: definition.defaultPeriod ?? DEFAULT_PERIOD,
     measures: definition.measures,
     dimensions: definition.dimensions
   };
@@ -1289,4 +1325,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 { AnalyticsResultSchema, type DatasetFilter, type DatasetQuery, type QueryResult, type ResultOf } from './query.js';
+export { allTenants, type Tenant, type TenantId } from './plan.js';
+export { AnalyticsResultSchema, type DatasetFilter, type DatasetQuery, type QueryResult, type ResultOf, type ResultPeriod } 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-wrr67sxq.js";
 import {
   CompileError2,
   decodeNumber2,
@@ -38,7 +39,7 @@ import {
 // src/guidance.ts
 var analyticsToolGuidance = `- Answer every "how many", "how much", "per week" or "split by" question with the analytics tool. Never count by hand from lists or pages.
 - Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.
-- Say which period and filters the numbers cover, using the dates in the result ("1-30 September").
+- Say which period and filters the numbers cover, using the dates in the result ("1-30 September", or "all time").
 - Compare with the previous period (compareToPrevious) when the change is the point, such as "is it going up".
 - When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.
 - Ask one short question only when the period is genuinely ambiguous ("this season") and someone can answer; otherwise take the natural reading and state it.`;
@@ -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/period.d.ts

@@ -4,7 +4,8 @@
  * database compares plain timestamps and can use its time index.
  */
 export type PeriodPreset = 'today' | 'yesterday' | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'thisYear';
-export type PeriodInput = {
+/** A range of days: what `resolvePeriod` turns into instants. */
+export type PeriodRange = {
     last: {
         days: number;
     };
@@ -14,6 +15,10 @@ export type PeriodInput = {
 } | {
     preset: PeriodPreset;
 };
+/** A range of days, or `{ all: true }` for no time filter. */
+export type PeriodInput = PeriodRange | {
+    all: true;
+};
 export type ResolvedPeriod = {
     /** First local day, `YYYY-MM-DD`. */
     from: string;
@@ -27,7 +32,11 @@ export type ResolvedPeriod = {
     days: number;
 };
 export declare const MAX_PERIOD_DAYS = 731;
-export declare const DEFAULT_PERIOD: PeriodInput;
+export declare const DEFAULT_PERIOD: {
+    readonly last: {
+        readonly days: 30;
+    };
+};
 /** True for an IANA name the runtime knows. Names are also inlined in SQL, so be strict. */
 export declare function isValidTimezone(timezone: string): boolean;
 /** The local calendar date of `instant` in `timezone`, as `YYYY-MM-DD`. */
@@ -39,6 +48,6 @@ export declare class PeriodError extends Error {
     readonly name = "PeriodError";
 }
 /** Resolves a period input to local days and instants in `timezone`. */
-export declare function resolvePeriod(input: PeriodInput, timezone: string, now: Date): ResolvedPeriod;
+export declare function resolvePeriod(input: PeriodRange, timezone: string, now: Date): ResolvedPeriod;
 /** The period of equal length that ends the day before `period` starts. */
 export declare function previousPeriod(period: ResolvedPeriod): ResolvedPeriod;

package/dist/plan.d.ts

@@ -1,6 +1,6 @@
 import type { Dialect, SelectStatement } from './compile.js';
 import type { AnyDataset } from './dataset.js';
-import { type PeriodInput, type ResolvedPeriod } from './period.js';
+import type { PeriodInput, ResolvedPeriod } from './period.js';
 /** A parsed query with every default filled in and duplicates removed. */
 export type NormalizedQuery = {
     dataset: string;
@@ -45,11 +45,20 @@ 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;
+export type TenantId = string | number;
+/** One tenant's id, a list of them (an empty list matches no rows), or `allTenants`. */
+export type Tenant = TenantId | readonly TenantId[] | 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;
+    /** Null for an all-time period: no time filter. */
+    period: ResolvedPeriod | null;
     /** The moment the query runs. */
     now: Date;
     /** Keys for filters on open dimensions, after label resolution, by dimension. */
@@ -70,7 +79,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;