measurr 0.2.0 → 0.4.0

package/dist/{index-dj3369zz.js → index-4rmjas9h.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()
   });
@@ -317,7 +341,7 @@ 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,
@@ -411,14 +435,25 @@ function dimensionNodes(dataset, key, timezone) {
   }
 }
 function baseWhere(dataset, tenant, period) {
-  const where = tenant === allTenants2 ? [] : [
-    {
+  const where = [];
+  if (tenant !== allTenants2) {
+    if (!dataset.tenantColumn) {
+      throw new Error(`Dataset ${dataset.key} has no tenant column; only allTenants may query it`);
+    }
+    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) {
@@ -520,7 +555,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
@@ -702,6 +737,7 @@ function createAnalytics2(options) {
   const sourceNames = Object.keys(options.sources);
   const byKey = new Map;
   const sourceOf = new Map;
+  const restrictedOf = new Map;
   for (const dataset of datasets) {
     if (byKey.has(dataset.key))
       throw new Error(`Two datasets use the key ${dataset.key}`);
@@ -709,6 +745,11 @@ function createAnalytics2(options) {
     const source = resolveSource(dataset, options.sources, sourceNames);
     sourceOf.set(dataset.key, source);
     compileEverything(dataset, source.dialect);
+    const restricted = restrictedFields(dataset);
+    if (restricted.length > 0 && !options.authorizeField) {
+      throw new Error(`Dataset ${dataset.key} marks fields with access, but createAnalytics has no authorizeField`);
+    }
+    restrictedOf.set(dataset.key, restricted);
   }
   const now = options.now ?? (() => new Date);
   const querySchemas = new Map;
@@ -725,9 +766,17 @@ function createAnalytics2(options) {
       throw new Error(`No source for ${dataset.key}`);
     return source;
   };
-  const querySchemaFor = (keys) => {
-    const selected = keys ? keys.map(datasetOf) : datasets;
-    const selectionKey = selected.map((dataset) => dataset.key).sort().join(",");
+  const querySchemaFor = (selected) => {
+    const keyOf = (dataset) => {
+      if (byKey.get(dataset.key) === dataset)
+        return dataset.key;
+      const fields = [
+        ...Object.keys(dataset.measures),
+        ...Object.keys(dataset.dimensions)
+      ];
+      return `${dataset.key}(${fields.join(" ")})`;
+    };
+    const selectionKey = selected.map(keyOf).sort().join(",");
     let schema = querySchemas.get(selectionKey);
     if (!schema) {
       schema = buildQuerySchema(selected);
@@ -743,49 +792,79 @@ function createAnalytics2(options) {
     }
     return schema;
   };
+  const deniedFields = async (dataset, ctx) => {
+    const restricted = restrictedOf.get(dataset.key) ?? [];
+    const authorizeField = options.authorizeField;
+    if (restricted.length === 0 || !authorizeField)
+      return restricted;
+    const mayUse = async (field) => {
+      const answers = await Promise.all(field.access.map((access) => authorizeField(dataset, field.key, access, ctx)));
+      return answers.every(Boolean);
+    };
+    const allowed = await Promise.all(restricted.map(mayUse));
+    return restricted.filter((_, index) => !allowed[index]);
+  };
   const allowedDatasets = async (ctx) => {
-    const { authorize } = options;
-    if (!authorize)
-      return datasets;
-    const allowed = await Promise.all(datasets.map((dataset) => authorize(dataset, ctx)));
-    return datasets.filter((_, index) => allowed[index]);
+    const everyTenant = options.tenant(ctx) === allTenants2;
+    const views = await Promise.all(datasets.map(async (dataset) => {
+      if (!dataset.tenantColumn && !everyTenant)
+        return null;
+      if (options.authorize && !await options.authorize(dataset, ctx))
+        return null;
+      const view = withoutFields(dataset, await deniedFields(dataset, ctx));
+      return Object.keys(view.measures).length > 0 ? view : null;
+    }));
+    return views.filter((view) => view !== null);
   };
   const querySchemaForCtx = async (ctx) => {
     const allowed = await allowedDatasets(ctx);
     if (allowed.length === 0) {
       throw new AnalyticsError2("forbidden", "No dataset is allowed");
     }
-    return querySchemaFor(allowed.map((dataset) => dataset.key));
+    return querySchemaFor(allowed);
   };
   const prepare = async (input, ctx) => {
-    const parsed = querySchemaFor(undefined).safeParse(input);
+    const parsed = querySchemaFor(datasets).safeParse(input);
     if (!parsed.success) {
       throw new AnalyticsError2("invalid_query", `Invalid analytics query: ${z2.prettifyError(parsed.error)}`, parsed.error.issues);
     }
-    const dataset = datasetOf(parsed.data.dataset);
+    const parsedQuery = parsed.data;
+    const dataset = datasetOf(parsedQuery.dataset);
     if (options.authorize && !await options.authorize(dataset, ctx)) {
       throw new AnalyticsError2("forbidden", `Not allowed to query ${dataset.key}`);
     }
+    const dimensionsUsed = [
+      ...parsedQuery.groupBy ?? [],
+      ...(parsedQuery.filters ?? []).map((filter) => filter.dimension)
+    ];
+    const refused = (await deniedFields(dataset, ctx)).filter((field) => field.kind === "measure" ? parsedQuery.measures.includes(field.key) : dimensionsUsed.includes(field.key));
+    if (refused.length > 0) {
+      const names = refused.map((field) => `${field.kind} ${field.key}`);
+      throw new AnalyticsError2("forbidden", `Not allowed to use ${names.join(", ")} of ${dataset.key}`);
+    }
     const tenant = options.tenant(ctx);
     if (!isTenant(tenant)) {
       throw new AnalyticsError2("missing_tenant", "Refusing to query without a tenant");
     }
+    if (!dataset.tenantColumn && tenant !== allTenants2) {
+      throw new AnalyticsError2("forbidden", `${dataset.key} has no tenant column; only a caller allowed to see every tenant may query it`);
+    }
     const timezone = await options.timezone?.(ctx) || "UTC";
     if (!isValidTimezone(timezone)) {
       throw new AnalyticsError2("invalid_timezone", `Unknown timezone ${timezone}`);
     }
-    const query = normalizeQuery(dataset, parsed.data);
+    const query = normalizeQuery(dataset, parsedQuery);
     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) => {
@@ -809,24 +888,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
     };
@@ -882,13 +959,16 @@ function createAnalytics2(options) {
     datasets: options.datasets,
     query,
     explain,
-    querySchema: (schemaOptions) => schemaOptions && ("ctx" in schemaOptions) ? querySchemaForCtx(schemaOptions.ctx) : querySchemaFor(schemaOptions?.datasets),
+    querySchema: (schemaOptions) => schemaOptions && ("ctx" in schemaOptions) ? querySchemaForCtx(schemaOptions.ctx) : querySchemaFor(schemaOptions?.datasets?.map(datasetOf) ?? datasets),
     resultSchema: (key) => resultSchemaFor(key),
     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);
+  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;
@@ -910,7 +990,7 @@ function resolveSource(dataset, sources, sourceNames) {
 function compileEverything(dataset, dialect) {
   const now = new Date(0);
   const context = {
-    tenant: "tenant",
+    tenant: dataset.tenantColumn ? "tenant" : allTenants2,
     timezone: "UTC",
     period: resolvePeriod({ last: { days: 1 } }, "UTC", now),
     now,
@@ -976,6 +1056,38 @@ function decodeKey2(value, dialect) {
     return value;
   return dialect.decodeNumber(value) ?? String(value);
 }
+function restrictedFields(dataset) {
+  const measures = dataset.measures;
+  const accessOf = (key) => {
+    const entry = measures[key];
+    if (!entry)
+      return [];
+    const own = entry.access === undefined ? [] : [entry.access];
+    return entry.kind === "ratio" ? [...own, ...accessOf(entry.numerator), ...accessOf(entry.denominator)] : own;
+  };
+  return [
+    ...Object.keys(measures).map((key) => ({
+      kind: "measure",
+      key,
+      access: [...new Set(accessOf(key))]
+    })),
+    ...Object.entries(dataset.dimensions).map(([key, entry]) => ({
+      kind: "dimension",
+      key,
+      access: entry.access === undefined ? [] : [entry.access]
+    }))
+  ].filter((field) => field.access.length > 0);
+}
+function withoutFields(dataset, fields) {
+  if (fields.length === 0)
+    return dataset;
+  const keep = (kind, entries) => Object.fromEntries(Object.entries(entries).filter(([key]) => !fields.some((field) => field.kind === kind && field.key === key)));
+  return {
+    ...dataset,
+    measures: keep("measure", dataset.measures),
+    dimensions: keep("dimension", dataset.dimensions)
+  };
+}
 function catalogEntry(dataset) {
   return {
     key: dataset.key,
@@ -1013,6 +1125,7 @@ function aggregate(result, fn, arg, options) {
     result,
     label: options.label,
     description: options.description,
+    access: options.access,
     node: {
       kind: "aggregate",
       fn,
@@ -1046,6 +1159,7 @@ var measure2 = {
       result: "ratio",
       label: options.label,
       description: options.description,
+      access: options.access,
       numerator: options.numerator.node,
       denominator: options.denominator?.node ?? null
     };
@@ -1056,6 +1170,7 @@ var measure2 = {
       result: "ratio",
       label: options.label,
       description: options.description,
+      access: options.access,
       numerator,
       denominator
     };
@@ -1065,6 +1180,7 @@ function base(options) {
   return {
     label: options.label,
     description: options.description,
+    access: options.access,
     groupable: options.filterOnly !== true,
     filterable: options.groupOnly !== true
   };
@@ -1163,6 +1279,9 @@ function defineDataset2(definition) {
   if (!firstTime) {
     throw new Error(`Dataset ${definition.key}: declare at least one time field`);
   }
+  if (definition.tenantColumn === undefined) {
+    throw new Error(`Dataset ${definition.key}: declare tenantColumn, or null for a dataset without tenants`);
+  }
   const time = Object.fromEntries(timeEntries.map(([key, field]) => [
     key,
     { column: field.column.node, label: field.label }
@@ -1173,10 +1292,11 @@ function defineDataset2(definition) {
     description: definition.description,
     from: definition.from.ref,
     source: definition.source,
-    tenantColumn: definition.tenantColumn.node,
+    tenantColumn: definition.tenantColumn?.node ?? null,
     scope: definition.scope?.node ?? null,
     time,
     defaultTime: definition.defaultTime ?? firstTime[0],
+    defaultPeriod: definition.defaultPeriod ?? DEFAULT_PERIOD,
     measures: definition.measures,
     dimensions: definition.dimensions
   };
@@ -1196,7 +1316,8 @@ function validateDataset(dataset) {
       }
     });
   };
-  check(dataset.tenantColumn, "tenantColumn");
+  if (dataset.tenantColumn)
+    check(dataset.tenantColumn, "tenantColumn");
   if (dataset.scope)
     check(dataset.scope, "scope");
   for (const [key, field] of Object.entries(dataset.time)) {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { type Analytics, AnalyticsError, type AnalyticsErrorCode, type AnalyticsErrorDetails, type AnalyticsErrorOf, type AnalyticsOptions, type AnalyticsQuery, type AnalyticsQueryEvent, type AnalyticsResult, type AnalyticsSource, createAnalytics, type DatasetCatalogEntry, isAnalyticsError } from './analytics.js';
+export { type AccessKey, type Analytics, AnalyticsError, type AnalyticsErrorCode, type AnalyticsErrorDetails, type AnalyticsErrorOf, type AnalyticsOptions, type AnalyticsQuery, type AnalyticsQueryEvent, type AnalyticsResult, type AnalyticsSource, createAnalytics, type DatasetCatalogEntry, type FieldKey, isAnalyticsError } from './analytics.js';
 export { CompileError, type CompiledStatement, type Dialect, type JoinClause, type SelectItem, type SelectStatement, type SqlRenderer, decodeNumber, renderStatement } from './compile.js';
 export { type AnyDataset, type AnyDimension, type AnyMeasure, type Dataset, type DimensionValue, defineDataset, dimension, type MeasureValue, measure, type Ratio } from './dataset.js';
 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';
+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

@@ -7,7 +7,7 @@ import {
   measure2,
   dimension2,
   defineDataset2
-} from "./index-dj3369zz.js";
+} from "./index-4rmjas9h.js";
 import {
   CompileError2,
   decodeNumber2,
@@ -39,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.`;

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;
@@ -50,13 +50,15 @@ export declare function normalizeQuery(dataset: AnyDataset, parsed: ParsedQuery)
  * 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;
+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: 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. */

package/dist/query.d.ts

@@ -80,14 +80,30 @@ export type ResultRow<M, Dm, MeasureKey extends string, GroupKey extends string>
 export type ResultTotals<M, MeasureKey extends string> = Simplify<{
     [Key in MeasureKey & keyof M]: MeasureValue<M[Key]>;
 }>;
-export type QueryResult<Row, Totals> = {
-    period: {
-        from: string;
-        to: string;
-        timezone: string;
-    };
+/** The days a result covers: local days `from` to `to` (inclusive), or all time. */
+export type ResultPeriod = {
+    from: string;
+    to: string;
+    timezone: string;
+} | {
+    all: true;
+    timezone: string;
+};
+/** The period query `Q` names; null or none means the dataset's `Default`. */
+type QueryPeriod<Q, Default> = Q extends unknown ? 'period' extends keyof Q ? OrDefault<Q['period' & keyof Q], Default> : Default : never;
+type OrDefault<P, Default> = P extends null | undefined ? Default : P;
+type PeriodShape<P> = P extends {
+    all: true;
+} ? Extract<ResultPeriod, {
+    all: true;
+}> : Exclude<ResultPeriod, {
+    all: true;
+}>;
+export type QueryResult<Row, Totals, Period extends ResultPeriod = ResultPeriod> = {
+    period: Period;
     rows: Row[];
     totals: Totals;
+    /** Only for a range: an all-time period has no previous period. */
     previous?: {
         period: {
             from: string;
@@ -101,28 +117,10 @@ export type QueryResult<Row, Totals> = {
     truncated: boolean;
 };
 /** The typed result of query `Q` against the datasets `DS`. */
-export type ResultOf<DS, Q> = DS extends Dataset<infer K, infer M, infer Dm, string> ? Q extends {
+export type ResultOf<DS, Q> = DS extends Dataset<infer K, infer M, infer Dm, string, infer P> ? Q extends {
     dataset: K;
     measures: readonly (infer Mk extends string)[];
-} ? QueryResult<ResultRow<M, Dm, Mk, GroupKeys<Q>>, ResultTotals<M, Mk>> : never : never;
-export declare const periodSchema: z.ZodUnion<readonly [z.ZodObject<{
-    last: z.ZodObject<{
-        days: z.ZodNumber;
-    }, z.core.$strip>;
-}, z.core.$strip>, z.ZodObject<{
-    from: z.ZodISODate;
-    to: z.ZodISODate;
-}, z.core.$strip>, z.ZodObject<{
-    preset: z.ZodEnum<{
-        lastMonth: "lastMonth";
-        lastWeek: "lastWeek";
-        thisMonth: "thisMonth";
-        thisWeek: "thisWeek";
-        thisYear: "thisYear";
-        today: "today";
-        yesterday: "yesterday";
-    }>;
-}, z.core.$strip>]>;
+} ? QueryResult<ResultRow<M, Dm, Mk, GroupKeys<Q>>, ResultTotals<M, Mk>, PeriodShape<QueryPeriod<Q, P>>> : never : never;
 /** The input schema branch for one dataset. */
 export declare function datasetQuerySchema(dataset: AnyDataset): z.ZodObject<{
     dataset: z.ZodLiteral<string>;
@@ -250,6 +248,8 @@ export declare function datasetQuerySchema(dataset: AnyDataset): z.ZodObject<{
             today: "today";
             yesterday: "yesterday";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
     time?: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
@@ -393,6 +393,8 @@ export declare function buildQuerySchema(datasets: readonly AnyDataset[]): z.Zod
             today: "today";
             yesterday: "yesterday";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
     time?: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
@@ -534,6 +536,8 @@ export declare function buildQuerySchema(datasets: readonly AnyDataset[]): z.Zod
             today: "today";
             yesterday: "yesterday";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
     time?: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
@@ -552,11 +556,14 @@ export declare function buildQuerySchema(datasets: readonly AnyDataset[]): z.Zod
 }, z.core.$strip>[]], "dataset">;
 /** The result schema for one dataset. Row fields exist only for grouped dimensions. */
 export declare function datasetResultSchema(dataset: AnyDataset): z.ZodObject<{
-    period: z.ZodObject<{
+    period: z.ZodUnion<readonly [z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         timezone: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
+        timezone: z.ZodString;
+    }, z.core.$strip>]>;
     rows: z.ZodArray<z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodNullable<z.ZodNumber>> | z.ZodOptional<z.ZodObject<{
             key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
@@ -591,11 +598,14 @@ export declare function datasetResultSchema(dataset: AnyDataset): z.ZodObject<{
  * For contracts that must not depend on the dataset list, such as an LLM tool's output.
  */
 export declare const AnalyticsResultSchema: z.ZodObject<{
-    period: z.ZodObject<{
+    period: z.ZodUnion<readonly [z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         timezone: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
+        timezone: z.ZodString;
+    }, z.core.$strip>]>;
     rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         label: z.ZodString;