@segmentstream-cloud/app 0.11.0 → 0.13.0

package/README.md

@@ -468,9 +468,9 @@ const { fields, rows, execution } = await segmentstream.ontology.aggregate({
 - It posts to the ontology service's `/api/ontology/aggregate` as the signed-in user, who needs
   read permission on every entity the request reaches. Previews and local development answer
   `aggregate_unavailable`.
-- Date bounds are `between` filters, inclusive. Each partitioned entity needs one on its own
-  partition property. Currency measures need their entity filtered to one currency, the same
-  for every entity.
+- Date bounds are `between` filters, inclusive, or `inPeriod` filters. Each partitioned entity
+  needs one on its own partition property. Currency measures need their entity filtered to one
+  currency, the same for every entity.
 - A measure field's `filters` lists the filters applied to it, and `execution.warnings` names
   each filter that did not reach a measure's entity. `additive: false` marks a measure whose
   rows don't add up to a total.
@@ -480,6 +480,43 @@ const { fields, rows, execution } = await segmentstream.ontology.aggregate({
   `aggregate_scope_mismatch`. See
   [ontology aggregates](../../docs/ontology-aggregates.md#errors).
 
+Since 0.13.0, both aggregates take more conditions, buckets and a timezone:
+
+```ts
+const { rows, execution } = await segmentstream.ontology.aggregate({
+  measures: ["trendtoysSales.wonOrders"],
+  dimensions: ["trendtoysSales.orderDate"],
+  granularity: "week",
+  granularityOf: "trendtoysSales.orderDate",
+  filters: [
+    { dimension: "trendtoysSales.orderDate", operator: "inPeriod", value: "last 4 weeks" },
+    { dimension: "trendtoysProduct.brand", operator: "notIn", values: ["Unknown", "Test"] },
+  ],
+  timezone: "Europe/Moscow",
+});
+```
+
+- Filter operators are `equals`, `in`, `notEquals`, `notIn`, `isNull`, `isNotNull`, `gt`,
+  `gte`, `lt`, `lte`, `contains`, `startsWith` and `endsWith`; the model-level call adds
+  `between` and `inPeriod`. `notEquals` and `notIn` also match nulls and rows whose
+  relationship found no target. Text operators are case-sensitive and take no wildcards.
+- `inPeriod` takes a period relative to today, typed as `RelativePeriod`: `today`,
+  `yesterday`, `this month`, `last quarter`, `this year to date`, `last 7 days`,
+  `last 4 weeks`. `execution.periods` gives the dates each one resolved to and the timezone
+  that decided today. Only `between` and `inPeriod` bound a partitioned entity.
+- `granularity` is `hour`, `day`, `week`, `month`, `quarter` or `year`; `hour` needs a
+  timestamp dimension.
+- `timezone`, an IANA name or `UTC`, replaces the entities' timezones for timestamp buckets,
+  date bounds on timestamps and the today of `inPeriod`.
+- A balance measure's field carries `balanceOver`, the date dimension its rows snapshot.
+  Group by that dimension or filter it to one day. `balanceOver` and each period's
+  `dimension` come back camelCase per segment, like field names.
+- The per-entity call takes the new operators, granularities and `timezone`, but neither
+  `between` nor `inPeriod`: `dateRange` stays its partition bound.
+- These requests need app SDK 0.13.0 and the workspace's ontology deployed with
+  `@segmentstream-cloud/ontology` 0.17.0 or later, whose service accepts them; earlier
+  versions refuse them. See [Upgrading to 0.13](#upgrading-to-013).
+
 ## How requests are handled
 
 - Page navigations without a session are redirected to `/sign-in?returnTo=<path>` and
@@ -579,3 +616,14 @@ Replace segmentstream.semantic with typed warehouse-backed entity aggregates. Se
 - Deploy the workspace's ontology with `@segmentstream-cloud/ontology` 0.13.0 or later. It
   serves `/api/ontology/<entity>/aggregate` and `/api/ontology/aggregate`; earlier versions
   don't.
+
+## Upgrading to 0.13
+
+- `ModelAggregateFilter` is now a union: a filter with `value` or `values`, or an `inPeriod`
+  filter whose `value` is a `RelativePeriod`. An interface cannot extend a union, so
+  `interface X extends ModelAggregateFilter` no longer compiles; write
+  `type X = ModelAggregateFilter & { … }` instead. Reading `filter.values` still compiles: it
+  is always `undefined` on an `inPeriod` filter.
+- The new operators, `inPeriod`, granularities and `timezone` need the workspace's ontology
+  deployed with `@segmentstream-cloud/ontology` 0.17.0 or later. Requests that use none of
+  them work as before.

package/dist/data.d.ts

@@ -43,6 +43,27 @@ export interface WarehouseDryRun {
     readonly bytesProcessed: string | null;
     readonly maximumBytesBilled: string;
 }
+/**
+ * The filter operators of both aggregates. `equals` and `notEquals` take one `value`; `in` and
+ * `notIn` take 1–100 `values`; `isNull` and `isNotNull` take none. `notEquals` and `notIn` also
+ * match nulls and rows whose relationship found no target, so they are the exact complements of
+ * `equals` and `in`. `gt`, `gte`, `lt` and `lte` compare a date, timestamp or number dimension
+ * with one `value`; a date bound on a timestamp covers whole days. `contains`, `startsWith` and
+ * `endsWith` match one non-empty string in a text dimension, case-sensitively, without wildcards.
+ */
+export type AggregateFilterOperator = "equals" | "in" | "notEquals" | "notIn" | "isNull" | "isNotNull" | "gt" | "gte" | "lt" | "lte" | "contains" | "startsWith" | "endsWith";
+/** How a date or timestamp dimension is bucketed. `hour` needs a timestamp and yields one. */
+export type AggregateGranularity = "hour" | "day" | "week" | "month" | "quarter" | "year";
+type CalendarUnit = "week" | "month" | "quarter" | "year";
+/**
+ * A period relative to today, which the platform resolves to two inclusive dates: `today`,
+ * `yesterday`; the whole current or previous week, month, quarter or year (`this month`,
+ * `last quarter`); the current one through today (`this year to date`); the N days ending
+ * yesterday (`last 7 days`); or the N whole weeks, months, quarters or years before the current
+ * one (`last 4 weeks`). N is at least 1, weeks start on Monday, and a period covers at most 3660
+ * days.
+ */
+export type RelativePeriod = "today" | "yesterday" | `this ${CalendarUnit}` | `this ${CalendarUnit} to date` | `last ${CalendarUnit}` | `last ${number} ${"days" | "weeks" | "months" | "quarters" | "years"}`;
 /**
  * An aggregate query. Dimensions, filters and ordering name the entity's own properties, or a
  * related entity's property through to-one relationships: `Path`, such as `product.brand`.
@@ -50,16 +71,22 @@ export interface WarehouseDryRun {
 export interface AggregateRequest<Property extends string = string, Measure extends string = string, Temporal extends Property = Property, Path extends string = never> {
     readonly dimensions: readonly (Property | Path)[];
     readonly measures: readonly Measure[];
+    /** The only partition bound this request takes: it has neither `between` nor `inPeriod`. */
     readonly dateRange?: {
         readonly from: string;
         readonly to: string;
     };
     /** The selected date or timestamp dimension to bucket, which may be a related one. */
     readonly granularityOf?: Temporal | Path;
-    readonly granularity?: "day" | "week" | "month";
+    readonly granularity?: AggregateGranularity;
+    /**
+     * An IANA timezone, such as `Europe/Moscow`, or `UTC`. It replaces the entities' timezones for
+     * timestamp buckets and date bounds on timestamps; measure conditions keep their own.
+     */
+    readonly timezone?: string;
     readonly filters?: ReadonlyArray<{
         readonly dimension: Property | Path;
-        readonly operator: "equals" | "in" | "isNull" | "isNotNull";
+        readonly operator: AggregateFilterOperator;
         readonly value?: string | number | boolean;
         readonly values?: ReadonlyArray<string | number | boolean>;
     }>;
@@ -70,26 +97,42 @@ export interface AggregateRequest<Property extends string = string, Measure exte
     }>;
     readonly limit?: number;
 }
-/** A filter of a model-level aggregate. `between` takes two inclusive `values`, the lower first. */
-export interface ModelAggregateFilter<Dimension extends string = string> {
+/**
+ * A filter of a model-level aggregate. Besides the shared operators, `between` takes two inclusive
+ * `values`, the lower first, and `inPeriod` a period relative to today as its `value`; the answer's
+ * `execution.periods` gives the dates it resolved to. Only these two bound a partitioned entity.
+ */
+export type ModelAggregateFilter<Dimension extends string = string> = {
     readonly dimension: Dimension;
-    readonly operator: "equals" | "in" | "isNull" | "isNotNull" | "between";
+    readonly operator: AggregateFilterOperator | "between";
     readonly value?: string | number | boolean;
     readonly values?: ReadonlyArray<string | number | boolean>;
-}
+} | {
+    readonly dimension: Dimension;
+    readonly operator: "inPeriod";
+    readonly value: RelativePeriod;
+    /** Never set; declared so code reading `values` from any filter still compiles. */
+    readonly values?: undefined;
+};
 /**
  * A model-level aggregate: measures of one or more entities, as `entity.measure`, grouped by
  * `entity.property` dimensions. A dimension may instead be a route from a measure's entity,
  * `entity.relationship.property`, which picks the way that entity reaches the property. Date bounds
- * are `between` filters.
+ * are `between` or `inPeriod` filters.
  */
 export interface ModelAggregateRequest<Measure extends string = string, Dimension extends string = string> {
     readonly measures: readonly Measure[];
     readonly dimensions?: readonly Dimension[];
     readonly filters?: ReadonlyArray<ModelAggregateFilter<Dimension>>;
-    readonly granularity?: "day" | "week" | "month";
+    readonly granularity?: AggregateGranularity;
     /** The requested date or timestamp dimension to bucket by `granularity`. */
     readonly granularityOf?: Dimension;
+    /**
+     * An IANA timezone, such as `Europe/Moscow`, or `UTC`. It replaces the entities' timezones for
+     * timestamp buckets, date bounds on timestamps and the today of `inPeriod`; measure conditions
+     * keep their own.
+     */
+    readonly timezone?: string;
     readonly orderBy?: ReadonlyArray<{
         readonly measure?: Measure;
         readonly dimension?: Dimension;
@@ -108,6 +151,11 @@ export interface AggregateField {
     readonly filters?: readonly string[];
     /** `false` on a measure whose rows don't add up to a total, such as a distinct count or a ratio. */
     readonly additive?: boolean;
+    /**
+     * On a balance measure: the date or timestamp dimension, as `entity.property`, whose days its
+     * rows snapshot. The request groups by it or filters it to one day.
+     */
+    readonly balanceOver?: string;
 }
 export interface AggregateResult<Row = Record<string, string | boolean | null>> {
     readonly deploymentId: string | null;
@@ -129,6 +177,17 @@ export interface AggregateResult<Row = Record<string, string | boolean | null>>
             readonly entity: string;
             readonly asOf: string;
         }>;
+        /**
+         * Each `inPeriod` filter in request order: its dimension as requested, its period, the
+         * inclusive dates it resolved to and the timezone whose today decided them.
+         */
+        readonly periods?: ReadonlyArray<{
+            readonly dimension: string;
+            readonly value: string;
+            readonly from: string;
+            readonly to: string;
+            readonly timezone: string;
+        }>;
     };
 }
 export interface WarehouseClient {

package/dist/index.d.ts

@@ -28,7 +28,7 @@ export type { CurrentUser } from "./me.js";
 export type { AuthRouteHandler, AuthRouteHandlers, SignOutOptions } from "./neon.js";
 export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, ModelAggregateClient, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
 export type { PermissionHolder } from "./permissions.js";
-export type { AggregateField, AggregateRequest, AggregateResult, ModelAggregateFilter, ModelAggregateRequest, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
+export type { AggregateField, AggregateFilterOperator, AggregateGranularity, AggregateRequest, AggregateResult, ModelAggregateFilter, ModelAggregateRequest, RelativePeriod, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
 export type { ParameterType, QueryParameterValue, QueryParameters, TypedParameter, } from "./parameters.js";
 export type { SegmentStreamAppConfig } from "./config.js";
 export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";

package/dist/ontology.js

@@ -245,8 +245,8 @@ function aggregateToWire(request) {
     };
 }
 /**
- * Field names, the filters each measure applied and row keys come back camelCase per segment;
- * `execution` is passed on as sent.
+ * Field names, the filters each measure applied, a balance's dimension and row keys come back
+ * camelCase per segment; `execution` is passed on as sent.
  */
 function aggregateResultFromWire(result, decodeName) {
     return {
@@ -255,25 +255,41 @@ function aggregateResultFromWire(result, decodeName) {
             ...field,
             name: decodeName(field.name),
             ...(field.filters === undefined ? {} : { filters: field.filters.map(decodeName) }),
+            ...(field.balanceOver === undefined ? {} : { balanceOver: decodeName(field.balanceOver) }),
         })),
         rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [decodeName(name), value]))),
     };
 }
-/** Model-level names keep an `_` before a digit, and the entities in `sources` convert too. */
+/**
+ * Model-level names keep an `_` before a digit; the entities in `sources` and the dimensions in
+ * `periods` convert too.
+ */
 function modelAggregateResultFromWire(wire) {
     const result = aggregateResultFromWire(wire, toReversibleCamelCase);
-    const sources = result.execution.sources;
-    if (sources === undefined) {
+    const { sources, periods } = result.execution;
+    if (sources === undefined && periods === undefined) {
         return result;
     }
     return {
         ...result,
         execution: {
             ...result.execution,
-            sources: sources.map((source) => ({
-                ...source,
-                entity: toReversibleCamelCase(source.entity),
-            })),
+            ...(sources === undefined
+                ? {}
+                : {
+                    sources: sources.map((source) => ({
+                        ...source,
+                        entity: toReversibleCamelCase(source.entity),
+                    })),
+                }),
+            ...(periods === undefined
+                ? {}
+                : {
+                    periods: periods.map((period) => ({
+                        ...period,
+                        dimension: toReversibleCamelCase(period.dimension),
+                    })),
+                }),
         },
     };
 }

package/dist/permissions.d.ts

@@ -1,7 +1,8 @@
 /**
  * Permissions are `<entity>:<verb>` strings, such as `lead:changeStatus`. A role may use `*` for the
  * entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
- * holds a wildcard.
+ * holds a wildcard. A wildcard entity does not cover the built-in `agent_chat`: only a permission
+ * that names it does.
  *
  * The matching rule is the ontology service's, copied from `@segmentstream-cloud/ontology`
  * (`src/permissions.ts`) so that the app SDK and its browser components do not depend on the

package/dist/permissions.js

@@ -1,7 +1,8 @@
 /**
  * Permissions are `<entity>:<verb>` strings, such as `lead:changeStatus`. A role may use `*` for the
  * entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
- * holds a wildcard.
+ * holds a wildcard. A wildcard entity does not cover the built-in `agent_chat`: only a permission
+ * that names it does.
  *
  * The matching rule is the ontology service's, copied from `@segmentstream-cloud/ontology`
  * (`src/permissions.ts`) so that the app SDK and its browser components do not depend on the
@@ -9,6 +10,8 @@
  */
 import { toSnakeCase } from "./ontology-names.js";
 const WILDCARD = "*";
+/** Entities only a permission that names them covers; `*:read` and `*:*` grant nothing on them. */
+const EXPLICIT_GRANT_ENTITIES = new Set(["agent_chat"]);
 /** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
 const PERMISSION = /^(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*)$/;
 function parsePermission(value) {
@@ -27,7 +30,9 @@ export function grants(granted, required) {
     if (held === undefined || wanted === undefined) {
         return false;
     }
-    return ((held.entity === WILDCARD || held.entity === wanted.entity) &&
+    return ((held.entity === WILDCARD
+        ? !EXPLICIT_GRANT_ENTITIES.has(wanted.entity)
+        : held.entity === wanted.entity) &&
         (held.verb === WILDCARD || held.verb === wanted.verb));
 }
 /** Whether one of the holder's permissions equals `required` or covers it through a wildcard. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",