@segmentstream-cloud/ontology 0.15.0 → 0.17.0

package/README.md

@@ -11,7 +11,7 @@ action and is kept in history.
 TypeScript definitions, handler records and SDK calls use camelCase: `jobTitle`,
 `assignedOwnerId`, `createdAt`, and `changeStatus`. The SDK converts ontology names,
 select identifiers and declared action input fields to snake_case for the generated
-REST API, version 6 manifest and storage. TypeScript helpers and options stay
+REST API, version 7 manifest and storage. TypeScript helpers and options stay
 camelCase. JSON property contents, provider payloads, opaque action results and
 historical change names remain data and are preserved. `formatManifest` serializes
 the canonical wire contract shared by REST, storage and future transports.
@@ -28,6 +28,15 @@ one Effect version.
 `ontology/` is a package of its own. The SDK is an ES module, so `ontology/package.json`
 must set `"type": "module"`.
 
+SDK 0.17.0 writes manifest version 7. It adds `m.avg`, `m.min` and `m.max`; a `where` option on
+every aggregate, so that a measure reads only the rows its conditions accept (`m.sum("amount",
+{ where: [{ property: "status", operator: "equals", value: "won" }], description })`); and
+`balanceOver`, which names the date a measure's rows are snapshots over, so that requests group by
+it or filter it to one day. Aggregate requests
+take the `notEquals`, `notIn`, `gt`, `gte`, `lt`, `lte`, `contains`, `startsWith`, `endsWith` and
+`inPeriod` operators, the `hour`, `quarter` and `year` granularities and a `timezone`. See
+[ontology aggregates](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-aggregates.md).
+
 SDK 0.14.0 lets the app's own agent call the service as a paired member (see
 [Agents](#agents)). Its migration adds the agent's runtime tables.
 
@@ -311,6 +320,45 @@ pair, or when the agent refuses, the action is rejected with the reason. Both ac
 `agent_chat:send_message`), which no role holds until the workspace grants it, and reading
 chats needs `agent_chat:read` by name: `*:read` and `*:*` do not cover `agent_chat`.
 
+### Agent attachments
+
+A file a member sends the agent is a temporary attachment: platform metadata in the runtime
+table `_agent_attachments`, never an ontology record, with its bytes stored once as a revision in
+the ontology's file storage, beside uploads. It belongs to the member, the chat it arrived in and
+the agent session that first reads it, holds its SHA-256, size, type and name, and expires 24
+hours after receipt (`received` → `ready` → `promoted`, `discarded` or `expired`). Files are up
+to 20 MB, what Telegram lets a bot download; a member holds at most 50 live attachments. The
+table exists on deployments with file storage; the migration adds it beside the file tables, also
+to a database an earlier SDK migrated.
+
+Only the agent calls these routes, with its runtime token, `X-SegmentStream-Act-As`, the chat in
+`X-SegmentStream-Agent-Conversation` (`telegram:<chat id>`) and, inside a turn, the session in
+`X-SegmentStream-Agent-Session`. Another member's attachment, another chat's or another
+session's answers 404; an expired or discarded one answers 409; a deactivated member's 403.
+
+| Route                                                | Does                                                                                                    |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `POST /api/ontology/agent/attachments`               | `{ source, source_ref, filename, content_type, size, sha256 }` → `{ attachment, upload? }`, a PUT grant |
+| `POST /api/ontology/agent/attachments/{id}/complete` | Verifies the stored bytes' size and SHA-256 → `{ attachment }` in `ready`                               |
+| `GET /api/ontology/agent/attachments`                | `{ attachments }`: the caller's readable attachments in this chat and session                           |
+| `GET /api/ontology/agent/attachments/{id}`           | `{ attachment, download }`: a one-minute GET grant                                                      |
+| `POST /api/ontology/agent/attachments/{id}/promote`  | `{ entity, action, input?, field?, record_id? }` → `{ attachment, deduplicated, result }`               |
+| `POST /api/ontology/agent/attachments/{id}/discard`  | Revokes it at once → `{ attachment }`                                                                   |
+
+Promotion keeps a file by running an action that takes an upload, such as an authored
+`document.upload` with `uploads.for(Document, "content")`, as the member and with their
+permissions. The service mints a completed upload ticket on the attachment's existing revision,
+fills the action's upload field (and `sha256`, when the input has one and the caller left it
+out), and runs the action with an idempotency key derived from the attachment, action and
+input, and the ticket's create intent; the action consumes the ticket as it would a browser
+upload, without copying the bytes. The target property's `accept` and `maxBytes` apply. A file
+whose SHA-256 an earlier attachment already promoted through the same action answers that
+promotion with `deduplicated: true` instead of a second record. Storage maintenance expires
+attachments past their deadline and removes the files no record adopted.
+
+An MCP action tool whose input takes an upload also accepts `_options: { idempotency_key,
+create_intent }`, the options the REST route takes beside `input`, so an MCP client can run it.
+
 ## The `segmentstream-ontology` binary
 
 Run the binary in the `ontology/` folder. The entry defaults to `./index.ts`. The binary

package/dist/aggregate-filters.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The filter operators of aggregates and the values each takes, shared by the service's request
+ * schemas and `check`'s measure conditions (docs/ontology-aggregates-release-2-spec.md, "Filters").
+ * The rules and messages are SegmentStream's own (backend-next's `semantics/core/predicates.ts`), so
+ * the SDK, the service and the platform refuse alike.
+ */
+/** A filter value: a literal. */
+export type AggregateValue = string | number | boolean;
+/** The operators of a model-level aggregate's filters. */
+export declare const AGGREGATE_FILTER_OPERATORS: readonly ["equals", "in", "isNull", "isNotNull", "between", "notEquals", "notIn", "gt", "gte", "lt", "lte", "contains", "startsWith", "endsWith", "inPeriod"];
+/**
+ * The operators of the per-entity shorthand, which bounds dates with `dateRange` instead of
+ * `between` and `inPeriod`.
+ */
+export declare const ENTITY_AGGREGATE_FILTER_OPERATORS: readonly ["equals", "in", "isNull", "isNotNull", "notEquals", "notIn", "gt", "gte", "lt", "lte", "contains", "startsWith", "endsWith"];
+/**
+ * The operators of a measure condition: a model-level filter's, except `inPeriod`, whose dates would
+ * move with the day a request runs.
+ */
+export declare const MEASURE_CONDITION_OPERATORS: readonly ["equals", "in", "notEquals", "notIn", "isNull", "isNotNull", "between", "gt", "gte", "lt", "lte", "contains", "startsWith", "endsWith"];
+export type MeasureConditionOperator = (typeof MEASURE_CONDITION_OPERATORS)[number];
+/** The periods `inPeriod` takes without a count. Weeks start on Monday. */
+export declare const AGGREGATE_PERIODS: readonly ["today", "yesterday", "this week", "this month", "this quarter", "this year", "this week to date", "this month to date", "this quarter to date", "this year to date", "last week", "last month", "last quarter", "last year"];
+/**
+ * The units of `last N <unit>`, N at least 1: `last N days` ends yesterday; the others are the N
+ * whole units before the current one.
+ */
+export declare const AGGREGATE_PERIOD_UNITS: readonly ["days", "weeks", "months", "quarters", "years"];
+/** The most values `in` and `notIn` take. */
+export declare const MAXIMUM_FILTER_VALUES = 100;
+/** An operator and the values given to it, before they are known to suit each other. */
+export interface FilterValues {
+    readonly operator: string;
+    readonly value?: unknown;
+    readonly values?: ReadonlyArray<unknown>;
+}
+/** Why an operator does not take the values given, or `undefined` when it does. */
+export declare function filterValuesIssue(filter: FilterValues): string | undefined;
+/** How SegmentStream compares a dimension's values. */
+export type DimensionType = "string" | "decimal" | "boolean" | "date" | "timestamp";
+/** The dimension type of a property type, or `undefined` for JSON and files, which are none. */
+export declare function dimensionTypeOf(propertyType: string): DimensionType | undefined;
+/**
+ * Why a filter's values do not suit its dimension's type, or `undefined` when they do: the operator
+ * must apply to the type and every value must match it. Their count is {@link filterValuesIssue}'s
+ * to check first. `inPeriod` values are periods, which SegmentStream resolves.
+ */
+export declare function filterTypeIssue(filter: FilterValues, type: DimensionType): string | undefined;

package/dist/aggregate-filters.js

@@ -0,0 +1,252 @@
+/**
+ * The filter operators of aggregates and the values each takes, shared by the service's request
+ * schemas and `check`'s measure conditions (docs/ontology-aggregates-release-2-spec.md, "Filters").
+ * The rules and messages are SegmentStream's own (backend-next's `semantics/core/predicates.ts`), so
+ * the SDK, the service and the platform refuse alike.
+ */
+/** The operators of a model-level aggregate's filters. */
+export const AGGREGATE_FILTER_OPERATORS = [
+    "equals",
+    "in",
+    "isNull",
+    "isNotNull",
+    "between",
+    "notEquals",
+    "notIn",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "contains",
+    "startsWith",
+    "endsWith",
+    "inPeriod",
+];
+/**
+ * The operators of the per-entity shorthand, which bounds dates with `dateRange` instead of
+ * `between` and `inPeriod`.
+ */
+export const ENTITY_AGGREGATE_FILTER_OPERATORS = [
+    "equals",
+    "in",
+    "isNull",
+    "isNotNull",
+    "notEquals",
+    "notIn",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "contains",
+    "startsWith",
+    "endsWith",
+];
+/**
+ * The operators of a measure condition: a model-level filter's, except `inPeriod`, whose dates would
+ * move with the day a request runs.
+ */
+export const MEASURE_CONDITION_OPERATORS = [
+    "equals",
+    "in",
+    "notEquals",
+    "notIn",
+    "isNull",
+    "isNotNull",
+    "between",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "contains",
+    "startsWith",
+    "endsWith",
+];
+/** The periods `inPeriod` takes without a count. Weeks start on Monday. */
+export const AGGREGATE_PERIODS = [
+    "today",
+    "yesterday",
+    "this week",
+    "this month",
+    "this quarter",
+    "this year",
+    "this week to date",
+    "this month to date",
+    "this quarter to date",
+    "this year to date",
+    "last week",
+    "last month",
+    "last quarter",
+    "last year",
+];
+/**
+ * The units of `last N <unit>`, N at least 1: `last N days` ends yesterday; the others are the N
+ * whole units before the current one.
+ */
+export const AGGREGATE_PERIOD_UNITS = ["days", "weeks", "months", "quarters", "years"];
+/** The most values `in` and `notIn` take. */
+export const MAXIMUM_FILTER_VALUES = 100;
+const COMPARISONS = new Set(["gt", "gte", "lt", "lte"]);
+const TEXT_OPERATORS = new Set(["contains", "startsWith", "endsWith"]);
+function oneValue({ value, values }) {
+    return value !== undefined && values === undefined;
+}
+function someValues({ value, values }) {
+    return (value === undefined &&
+        values !== undefined &&
+        values.length > 0 &&
+        values.length <= MAXIMUM_FILTER_VALUES);
+}
+/** Why an operator does not take the values given, or `undefined` when it does. */
+export function filterValuesIssue(filter) {
+    const { operator, value, values } = filter;
+    if (COMPARISONS.has(operator)) {
+        return oneValue(filter) ? undefined : "Comparison filters require one value.";
+    }
+    if (TEXT_OPERATORS.has(operator)) {
+        return oneValue(filter) && typeof value === "string" && value !== ""
+            ? undefined
+            : "Text filters require one non-empty string.";
+    }
+    switch (operator) {
+        case "equals":
+        case "notEquals":
+            return oneValue(filter) ? undefined : "Equality filters require one value.";
+        case "in":
+            return someValues(filter)
+                ? undefined
+                : "Membership filters require between 1 and 100 values.";
+        case "notIn":
+            return someValues(filter) ? undefined : "notIn requires between 1 and 100 values.";
+        case "between":
+            return value === undefined && values?.length === 2
+                ? undefined
+                : "between needs two values in order.";
+        case "inPeriod":
+            // Whether the value is a period is SegmentStream's to say: it resolves it.
+            return oneValue(filter) ? undefined : "inPeriod filters require one period.";
+        case "isNull":
+        case "isNotNull":
+            return value === undefined && values === undefined
+                ? undefined
+                : "Null filters do not accept values.";
+        default:
+            return undefined;
+    }
+}
+const DIMENSION_TYPES = {
+    text: "string",
+    email: "string",
+    url: "string",
+    select: "string",
+    integer: "decimal",
+    number: "decimal",
+    boolean: "boolean",
+    date: "date",
+    timestamp: "timestamp",
+};
+/** The dimension type of a property type, or `undefined` for JSON and files, which are none. */
+export function dimensionTypeOf(propertyType) {
+    return Object.hasOwn(DIMENSION_TYPES, propertyType) ? DIMENSION_TYPES[propertyType] : undefined;
+}
+function isDate(value) {
+    return (typeof value === "string" &&
+        /^\d{4}-\d{2}-\d{2}$/.test(value) &&
+        !Number.isNaN(Date.parse(value)) &&
+        new Date(value).toISOString().slice(0, 10) === value);
+}
+/** Whether a value is a literal of the type, as SegmentStream reads filter values. */
+function matches(value, type) {
+    if (type === "boolean") {
+        return typeof value === "boolean";
+    }
+    if (type === "decimal") {
+        return ((typeof value === "number" || typeof value === "string") &&
+            String(value).length <= 100 &&
+            /^[-+]?(?:\d+\.?\d*|\.\d+)$/.test(String(value)) &&
+            Number.isFinite(Number(value)));
+    }
+    if (typeof value !== "string" || value.length > 2048) {
+        return false;
+    }
+    if (type === "timestamp") {
+        return (/^\d{4}-\d{2}-\d{2}T/.test(value) &&
+            /(?:Z|[+-]\d{2}:\d{2})$/.test(value) &&
+            Number.isFinite(Date.parse(value)));
+    }
+    return type !== "date" || isDate(value);
+}
+/** Bounds of a timestamp may be dates, which cover whole days; then they are compared as dates. */
+function boundType(bounds, type) {
+    return type === "timestamp" && bounds.every(isDate) ? "date" : type;
+}
+/** Compares two decimal literals exactly, as their digits say, however many there are. */
+function compareDecimals(left, right) {
+    const parse = (value) => {
+        const negative = value.startsWith("-");
+        const [whole = "", fraction = ""] = value.replace(/^[-+]/, "").split(".");
+        const digits = whole.replace(/^0+/, "");
+        const decimals = fraction.replace(/0+$/, "");
+        const zero = digits === "" && decimals === "";
+        return { negative: negative && !zero, digits, decimals };
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (a.negative !== b.negative) {
+        return a.negative ? -1 : 1;
+    }
+    const width = Math.max(a.decimals.length, b.decimals.length);
+    const magnitude = (value) => value.digits.padStart(Math.max(a.digits.length, b.digits.length), "0") +
+        value.decimals.padEnd(width, "0");
+    // Equal-length digit strings order as their values do.
+    const [first, second] = [magnitude(a), magnitude(b)];
+    if (first === second) {
+        return 0;
+    }
+    const sign = first < second ? -1 : 1;
+    return a.negative ? -sign : sign;
+}
+function inOrder(from, to, type) {
+    if (type === "decimal") {
+        return compareDecimals(String(from), String(to)) <= 0;
+    }
+    if (type === "timestamp") {
+        return Date.parse(String(from)) <= Date.parse(String(to));
+    }
+    return String(from) <= String(to);
+}
+const MISMATCH = "Filter value does not match its dimension type.";
+const ORDERED_TYPES = new Set(["date", "timestamp", "decimal"]);
+/**
+ * Why a filter's values do not suit its dimension's type, or `undefined` when they do: the operator
+ * must apply to the type and every value must match it. Their count is {@link filterValuesIssue}'s
+ * to check first. `inPeriod` values are periods, which SegmentStream resolves.
+ */
+export function filterTypeIssue(filter, type) {
+    const { operator, value, values = [] } = filter;
+    const given = value === undefined ? values : [value];
+    if (operator === "between") {
+        const [from, to] = given;
+        const bounds = boundType([from, to], type);
+        if (!ORDERED_TYPES.has(type)) {
+            return "between filters date, timestamp and number dimensions.";
+        }
+        if (!matches(from, bounds) || !matches(to, bounds)) {
+            return MISMATCH;
+        }
+        return inOrder(from, to, bounds) ? undefined : "between needs two values in order.";
+    }
+    if (operator === "inPeriod") {
+        return type === "date" || type === "timestamp"
+            ? undefined
+            : "inPeriod filters date and timestamp dimensions.";
+    }
+    if (COMPARISONS.has(operator) && !ORDERED_TYPES.has(type)) {
+        return `${operator} filters date, timestamp and number dimensions.`;
+    }
+    if (TEXT_OPERATORS.has(operator) && type !== "string") {
+        return `${operator} filters text dimensions.`;
+    }
+    // A comparison bounds a timestamp by a date or by an exact instant, as `between` does.
+    const valueType = COMPARISONS.has(operator) ? boundType(given, type) : type;
+    return given.every((candidate) => matches(candidate, valueType)) ? undefined : MISMATCH;
+}

package/dist/authoring-records.d.ts

@@ -5,6 +5,11 @@ interface Definition {
     readonly properties: Properties;
     readonly relationships?: Relationships;
 }
+/**
+ * A select property's values as stored, the option values' wire names, or as authored when
+ * `decode`. Other properties' values are data and stay as they are.
+ */
+export declare function selectValue(value: unknown, property: unknown, decode: boolean): unknown;
 /** Only record keys and select identifiers convert; property values remain data. */
 export declare function recordFromWire<A>(value: unknown, definition?: Definition): A;
 export declare function valuesToWire(values: StoredValues, definition: Definition): StoredValues;

package/dist/authoring-records.js

@@ -6,7 +6,11 @@ function targetDefinition(target) {
     const resolved = typeof target === "function" ? target() : target;
     return isEntity(resolved) ? resolved.definition : undefined;
 }
-function selectValue(value, property, decode) {
+/**
+ * A select property's values as stored, the option values' wire names, or as authored when
+ * `decode`. Other properties' values are data and stay as they are.
+ */
+export function selectValue(value, property, decode) {
     const definition = propertyDefinition(property);
     if (definition?.type !== "select") {
         return value;

package/dist/authoring.js

@@ -2,6 +2,7 @@ import { Schema } from "effect";
 import { isAction } from "./action.js";
 import { actionInputToWire } from "./authoring-input.js";
 import { isRecord, nameToWire, permissionToWire } from "./authoring-names.js";
+import { selectValue } from "./authoring-records.js";
 import { isEntity } from "./entity.js";
 import { toCamelCase } from "./names.js";
 import { p, propertyDefinition } from "./property.js";
@@ -21,7 +22,29 @@ function indexToWire(index) {
     const definition = index;
     return { ...definition, properties: (definition.properties ?? []).map(nameToWire) };
 }
-function expressionToWire(value) {
+/**
+ * A measure condition with wire names: its property, as `property` or, in a `filtered` expression,
+ * `column`, and the values of a select property, which are option values.
+ */
+function conditionToWire(condition, properties) {
+    if (!isRecord(condition)) {
+        return condition;
+    }
+    const key = "property" in condition ? "property" : "column";
+    const name = condition[key];
+    if (typeof name !== "string") {
+        return condition;
+    }
+    const property = isRecord(properties) && Object.hasOwn(properties, name) ? properties[name] : undefined;
+    return {
+        ...condition,
+        [key]: nameToWire(name),
+        ...("value" in condition ? { value: selectValue(condition.value, property, false) } : {}),
+        ...("values" in condition ? { values: selectValue(condition.values, property, false) } : {}),
+    };
+}
+/** A measure expression with wire names: properties, measure references and conditions. */
+function expressionToWire(value, properties) {
     if (!isRecord(value)) {
         return value;
     }
@@ -30,7 +53,13 @@ function expressionToWire(value) {
         expression.name = nameToWire(value.name);
     }
     if (Array.isArray(value.args)) {
-        expression.args = value.args.map(expressionToWire);
+        expression.args = value.args.map((arg) => expressionToWire(arg, properties));
+    }
+    if (Array.isArray(value.where)) {
+        expression.where = value.where.map((condition) => conditionToWire(condition, properties));
+    }
+    if (typeof value.balanceOver === "string") {
+        expression.balanceOver = nameToWire(value.balanceOver);
     }
     return expression;
 }
@@ -141,7 +170,7 @@ class AuthoringEncoder {
             ...(original.measures === undefined
                 ? {}
                 : {
-                    measures: this.named(original.measures, `${entity.name}.measures`, (value) => expressionToWire(value)),
+                    measures: this.named(original.measures, `${entity.name}.measures`, (value) => expressionToWire(value, original.properties)),
                 }),
         };
         this.definitions.set(original, normalized);

package/dist/index.d.ts

@@ -2,7 +2,9 @@ export { BlobValue, BlobUpload, uploads, BLOB_CONTENT_TYPES, MAX_BLOB_BYTES } fr
 export { warehouse, compatibleWarehouseColumn, warehouseColumnType, validateWarehouseSource, } from "./source.js";
 export type { WarehouseSource } from "./source.js";
 export { m } from "./measure.js";
-export type { Measure, Measures, MeasureExpression, MeasureOptions } from "./measure.js";
+export type { AggregateDeclarations, AggregateOptions, Measure, MeasureColumnCondition, MeasureCondition, Measures, MeasureExpression, MeasureOptions, } from "./measure.js";
+export { MEASURE_CONDITION_OPERATORS } from "./aggregate-filters.js";
+export type { AggregateValue, MeasureConditionOperator } from "./aggregate-filters.js";
 export { action, isAction } from "./action.js";
 export type { Action, ActionConfig, ActionConfigWithConnections, ActionContext, ActionEncodedInput, ActionHints, ActionInput, ActionResult, Actions, AnyAction, PrepareContext, PrepareError, } from "./action.js";
 export { CONNECTION_ERROR_REASONS, CONNECTION_KEY, CONNECTION_METHODS, connection, ConnectionError, Connections, ConnectionTransport, isConnection, MAXIMUM_CONNECTION_BODY_BYTES, } from "./connection.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { BlobValue, BlobUpload, uploads, BLOB_CONTENT_TYPES, MAX_BLOB_BYTES } from "./blob.js";
 export { warehouse, compatibleWarehouseColumn, warehouseColumnType, validateWarehouseSource, } from "./source.js";
 export { m } from "./measure.js";
+export { MEASURE_CONDITION_OPERATORS } from "./aggregate-filters.js";
 export { action, isAction } from "./action.js";
 export { CONNECTION_ERROR_REASONS, CONNECTION_KEY, CONNECTION_METHODS, connection, ConnectionError, Connections, ConnectionTransport, isConnection, MAXIMUM_CONNECTION_BODY_BYTES, } from "./connection.js";
 export { Diagnostic, DIAGNOSTIC_CODES, formatDiagnostics, InvalidOntology } from "./diagnostics.js";