@segmentstream/app 0.0.0-stage → 0.38.0

package/dist/ontology.d.ts

@@ -0,0 +1,381 @@
+import type { EntityMetricQuery, MetricQuery, MetricQueryResult } from "./data.js";
+import { type EarlierEntityQueryMetricsName, type EarlierMetricsOf, type EarlierModelMetricsOf, type EarlierQueryMetricsName } from "./legacy.js";
+import type { FileDownloadOptions, FileRevision, FileTransfer } from "./storage.js";
+/**
+ * The typed client for the app's ontology service, `/api/ontology`. The app imports its ontology as
+ * types only (`import type ontology from "../../ontology"`) and passes `typeof ontology` to
+ * `createSegmentStreamApp`; entity records, action inputs and action results are read from the
+ * ontology SDK's `Ontology`, `Entity` and `Action` types. The types are read structurally, so the
+ * app needs neither the ontology SDK nor Effect at runtime, and `app/` and `ontology/` may install
+ * their own copies.
+ */
+/** JSON as the ontology service sends and accepts it. */
+export type JsonValue = string | number | boolean | null | ReadonlyArray<JsonValue> | {
+    readonly [key: string]: JsonValue;
+};
+/** A record of an entity the client has no types for. */
+export type JsonRecord = {
+    readonly [field: string]: JsonValue;
+};
+/**
+ * Conditions on one field; all of them must hold. `contains` and `startsWith` ignore case;
+ * `between` includes both ends; `has` and `hasAny` match a list, such as `user.roles`, that holds
+ * the value or any of the values. In a `where`, a bare value stands for `{ eq: value }`.
+ */
+export interface FieldFilter {
+    readonly eq?: JsonValue;
+    readonly ne?: JsonValue;
+    readonly in?: ReadonlyArray<JsonValue>;
+    readonly isNull?: boolean;
+    readonly contains?: string;
+    readonly startsWith?: string;
+    readonly gt?: number | string;
+    readonly gte?: number | string;
+    readonly lt?: number | string;
+    readonly lte?: number | string;
+    readonly between?: readonly [number | string, number | string];
+    readonly has?: string;
+    readonly hasAny?: ReadonlyArray<string>;
+}
+/** A filter on a to-many relationship: some, none or every related record matches. */
+export interface ManyFilter {
+    readonly some?: Where;
+    readonly none?: Where;
+    readonly every?: Where;
+}
+/** Conditions on a record by field or relationship name, with `and`, `or` and `not`. */
+export interface Where {
+    readonly and?: ReadonlyArray<Where>;
+    readonly or?: ReadonlyArray<Where>;
+    readonly not?: Where;
+    readonly [field: string]: FieldFilter | ManyFilter | Where | ReadonlyArray<Where> | JsonValue | undefined;
+}
+export interface OrderBy<Field extends string = string> {
+    readonly field: Field;
+    readonly direction?: "asc" | "desc";
+}
+/** A query: the same language for `find` (as URL parameters) and `query` (as a JSON body). */
+export interface OntologyQuery<Row = JsonRecord, Selection extends readonly (keyof Row & string)[] | undefined = undefined> {
+    /** Base fields to return. The id and requested relationships are always returned. */
+    readonly select?: Selection;
+    readonly where?: Where;
+    readonly orderBy?: ReadonlyArray<OrderBy<keyof Row & string>>;
+    /**
+     * Related records to add to each record, by relationship name: `["owner"]` or `{ owner: true }`.
+     */
+    readonly include?: ReadonlyArray<string> | {
+        readonly [relationship: string]: true;
+    };
+    /** The `nextCursor` of the previous page. */
+    readonly after?: string;
+    /** Records per page, 50 by default and at most 200. */
+    readonly limit?: number;
+}
+/** A page of records. `nextCursor` is `null` on the last page. */
+export interface OntologyPage<Row> {
+    readonly items: ReadonlyArray<Row>;
+    readonly nextCursor: string | null;
+    readonly projected?: true;
+}
+/** Selected fields are required; other fields may be absent. Dynamic lists promise only id. */
+export type SelectedRecord<Row, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Partial<Row> & (number extends Selection["length"] ? object : Pick<Row, Extract<Selection[number], keyof Row>>) & {
+    readonly id: string;
+} : Row;
+type ReadQuery = OntologyQuery<JsonRecord, readonly string[] | undefined>;
+export type EditKind = "create" | "update" | "delete" | "link" | "unlink";
+export interface Change {
+    readonly before: JsonValue;
+    readonly after: JsonValue;
+}
+/** What one action changed on one record. */
+export interface Edit {
+    readonly entity: string;
+    readonly id: string;
+    readonly kind: EditKind;
+    readonly changes: {
+        readonly [field: string]: Change;
+    };
+}
+export interface HistoryEntry {
+    readonly id: string;
+    readonly recordId: string;
+    /** The qualified action, for example `lead.changeStatus`. */
+    readonly action: string;
+    /** Shared by every entry one run of an action wrote. */
+    readonly actionId: string;
+    readonly kind: EditKind;
+    /** The user who ran the action; `null` when the platform wrote. */
+    readonly principalId: string | null;
+    readonly at: string;
+    readonly changes: {
+        readonly [field: string]: Change;
+    };
+}
+export interface HistoryPage {
+    readonly items: ReadonlyArray<HistoryEntry>;
+    readonly nextCursor: string | null;
+}
+export interface ValidationIssue {
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+}
+/** `POST /api/ontology/<entity>/actions/<action>` answers `{ result, validation, edits }`. */
+export interface ActionResponse<Result = unknown> {
+    /** What the action returned; `null` under `validateOnly` and for actions without a result. */
+    readonly result: Result | null;
+    readonly validation: {
+        readonly ok: boolean;
+        readonly issues: ReadonlyArray<ValidationIssue>;
+    };
+    /** The records the action changed, as their history records each change. */
+    readonly edits: ReadonlyArray<Edit>;
+}
+export interface RequestOptions {
+    readonly signal?: AbortSignal;
+}
+export interface ActionOptions extends RequestOptions {
+    /** Validate the input and report issues in `validation` without a write. */
+    readonly validateOnly?: boolean;
+    readonly idempotencyKey?: string;
+    readonly createIntent?: string;
+}
+export interface HistoryOptions extends RequestOptions {
+    readonly after?: string;
+    /** Entries per page, at most 200. */
+    readonly limit?: number;
+}
+/** Runs one action: `lead.actions.changeStatus({ lead, status }, { validateOnly })`. */
+export type ActionCall<Input, Result> = (input: Input, options?: ActionOptions) => Promise<ActionResponse<Result>>;
+/** The generated actions every entity has; their inputs are not typed by the client. */
+export interface GeneratedActions {
+    readonly create: ActionCall<JsonRecord, JsonValue>;
+    readonly update: ActionCall<{
+        readonly id: string;
+    } & JsonRecord, JsonValue>;
+    readonly delete: ActionCall<{
+        readonly id: string;
+    }, JsonValue>;
+}
+/**
+ * The generated actions of the built-in `user`, which change a member's roles and activation. Role
+ * names are spelled as `requireUser().roles` spells them. Each returns the updated record.
+ */
+export interface UserGeneratedActions<Row = JsonRecord> {
+    readonly invite: ActionCall<{
+        readonly email: string;
+        readonly name?: string;
+        readonly roles?: ReadonlyArray<string>;
+    }, Row>;
+    readonly grantRoles: ActionCall<{
+        readonly id: string;
+        readonly roles: ReadonlyArray<string>;
+    }, Row>;
+    readonly revokeRoles: ActionCall<{
+        readonly id: string;
+        readonly roles: ReadonlyArray<string>;
+    } | {
+        readonly id: string;
+        readonly all: true;
+    }, Row>;
+    readonly deactivate: ActionCall<{
+        readonly id: string;
+    }, Row>;
+    readonly reactivate: ActionCall<{
+        readonly id: string;
+    }, Row>;
+}
+type BlobPropertyNames<Row> = string extends keyof Row ? string : {
+    [K in keyof Row]-?: [NonNullable<Row[K]>] extends [never] ? never : NonNullable<Row[K]> extends FileRevision ? K : never;
+}[keyof Row] & string;
+export interface EntityFilesClient<Property extends string = string> {
+    /**
+     * A short-lived GET grant for a blob property, authorized as the signed-in member.
+     * The ontology checks current read permission and record scopes before issuing the grant.
+     * File bytes are read from the grant's URL, outside ontology JSON responses.
+     */
+    readonly download: (id: string, property: Property, options?: FileDownloadOptions) => Promise<FileTransfer>;
+}
+export interface EntityClient<Row, Actions, Generated = GeneratedActions> {
+    /** `GET /api/ontology/<entity>`: filter, sort and page through records. */
+    readonly find: <const Selection extends readonly (keyof Row & string)[] | undefined = undefined>(query?: OntologyQuery<Row, Selection>, options?: RequestOptions) => Promise<OntologyPage<SelectedRecord<Row, Selection>>>;
+    /** `POST /api/ontology/<entity>/query`: the same query as a JSON body. */
+    readonly query: <const Selection extends readonly (keyof Row & string)[] | undefined = undefined>(query?: OntologyQuery<Row, Selection>, options?: RequestOptions) => Promise<OntologyPage<SelectedRecord<Row, Selection>>>;
+    /** `GET /api/ontology/<entity>/<id>`. */
+    readonly get: (id: string, options?: RequestOptions) => Promise<Row>;
+    /** `GET /api/ontology/<entity>/<id>/history`: what each action changed, newest first. */
+    readonly history: (id: string, options?: HistoryOptions) => Promise<HistoryPage>;
+    /** Read the entity's blob properties as the signed-in member. */
+    readonly files: EntityFilesClient<BlobPropertyNames<Row>>;
+    /**
+     * The entity's actions by name, authored and generated. An entity that declares
+     * `writes: "actions"` has no generated `create`, `update` or `delete`.
+     */
+    readonly actions: Actions & Generated;
+    /** Any action by name, for generated actions such as `upsertByEmail`, `link` and `unlink`. */
+    readonly action: (name: string, input: JsonRecord, options?: ActionOptions) => Promise<ActionResponse<JsonValue>>;
+}
+type EntitiesOf<O> = O extends {
+    readonly config: {
+        readonly entities: ReadonlyArray<infer E>;
+    };
+} ? E : never;
+type NameOf<E> = E extends {
+    readonly name: infer N extends string;
+} ? N : never;
+type RecordOf<E> = E extends {
+    readonly Type: infer T;
+} ? T : JsonRecord;
+type ActionsOf<E> = E extends {
+    readonly actions: infer A;
+} ? A : never;
+/** The generated writes of an entity: none when it declares `writes: "actions"`. */
+type GeneratedOf<E> = E extends {
+    readonly "~ontology.writes": infer W;
+} ? [W] extends ["actions"] ? unknown : GeneratedActions : GeneratedActions;
+type InputOf<A> = A extends {
+    readonly input: {
+        readonly Encoded: infer I;
+    };
+} ? I : JsonRecord;
+/** An Effect yields its success when iterated, as `yield*` in `Effect.gen` does. */
+type SuccessOf<F> = F extends {
+    [Symbol.iterator](): {
+        next(...args: ReadonlyArray<any>): IteratorResult<unknown, infer R>;
+    };
+} ? R : unknown;
+/** Actions without a result answer `result: null`. */
+type JsonResult<R> = [R] extends [void] ? null : R;
+type ResultOf<A> = A extends {
+    handler(context: never): infer F;
+} ? JsonResult<SuccessOf<F>> : unknown;
+type ActionClients<A> = {
+    readonly [K in keyof A & string]: ActionCall<InputOf<A[K]>, ResultOf<A[K]>>;
+};
+type PropertiesOf<E> = E extends {
+    readonly properties: infer P;
+} ? P : never;
+/** Declared names only: a definition typed as any `Metrics` names none the client can check. */
+export type DeclaredNames<M> = string extends keyof M ? never : keyof M & string;
+/**
+ * A warehouse-backed entity's `metrics`, or the metrics of a stored entity's definition. An
+ * ontology SDK before manifest version 14 declares them under their earlier name, which
+ * `EarlierMetricsOf` reads.
+ */
+type MetricsOf<E> = (E extends {
+    readonly metrics: infer M;
+} ? keyof M & string : E extends {
+    readonly definition: {
+        readonly metrics?: infer M;
+    };
+} ? DeclaredNames<NonNullable<M>> : never) | EarlierMetricsOf<E>;
+type RelationshipsOf<E> = E extends {
+    readonly relationships: infer R;
+} ? R : never;
+type IsWarehouseBacked<E> = E extends {
+    readonly definition: {
+        readonly source: object;
+    };
+} ? true : false;
+/**
+ * A `rel.one`, which metric queries may follow. Every relationship of a warehouse-backed entity is
+ * matched by value; a stored entity's may also be keyed (`<relationship>_id` joined to `id`).
+ */
+interface ToOne {
+    readonly cardinality: "one";
+}
+/** The target's name, or `string` when a thunk erased it or the ontology SDK predates the name. */
+type TargetNameOf<R> = R extends {
+    readonly "~ontology.target": infer Name extends string;
+} ? Name : string;
+/** The entity of `O` named `Name`. `User` is not replicated, so metric queries never reach it. */
+type EntityNamed<O, Name extends string> = Name extends "user" ? never : Extract<EntitiesOf<O>, {
+    readonly name: Name;
+}>;
+/** Properties whose values are scalars. json and blob values are objects, which queries skip. */
+type ScalarPropertiesOf<T> = {
+    [K in keyof PropertiesOf<T>]-?: PropertiesOf<T>[K] extends {
+        readonly Type: infer V;
+    } ? [Extract<V, object>] extends [never] ? K : never : K;
+}[keyof PropertiesOf<T>] & string;
+/** What a path may end on: the target's scalar properties, and `id` when the target is stored. */
+type FieldsOf<T> = ScalarPropertiesOf<T> | (IsWarehouseBacked<T> extends true ? never : "id");
+/** The rest of a path after reaching `T`: a field, or one more relationship when `Again`. */
+type PathEnds<T, O, Again extends boolean> = [T] extends [never] ? never : FieldsOf<T> | (Again extends true ? PathsFrom<T, O, false> : never);
+type PathsFrom<E, O, Again extends boolean> = {
+    [K in keyof RelationshipsOf<E> & string]: RelationshipsOf<E>[K] extends ToOne ? string extends TargetNameOf<RelationshipsOf<E>[K]> ? `${K}.${string}` : `${K}.${PathEnds<EntityNamed<O, TargetNameOf<RelationshipsOf<E>[K]>>, O, Again>}` : never;
+}[keyof RelationshipsOf<E> & string];
+/**
+ * Related properties of `E` as metric query paths through at most two `rel.one` relationships:
+ * `product.brand`, `product.brand.name`. A thunk target erases its entity, so any path may follow
+ * its relationship: `` `${relationship}.${string}` ``.
+ */
+type PathsOf<E, O> = PathsFrom<E, O, true>;
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/**
+ * A snake_case entity name in camelCase, keeping an `_` before a digit so the name converts back:
+ * `sales_2025` stays, `wb2_sales` is `wb2Sales`. The client decodes model-level names the same way.
+ */
+type CamelCase<S extends string> = S extends `${infer Head}_${infer Tail}` ? Tail extends `${Digit}${string}` ? `${Head}_${CamelCase<Tail>}` : `${Head}${Capitalize<CamelCase<Tail>>}` : S;
+/** `entity.metric` for every metric of every entity, warehouse-backed or stored. */
+type EntityMetricsOf<E> = E extends unknown ? `${CamelCase<NameOf<E>>}.${MetricsOf<E>}` : never;
+/**
+ * The model metrics, `defineOntology({ metrics })`, by their bare declared names, or under their
+ * earlier name from an ontology SDK before manifest version 14. An ontology SDK without them, or a
+ * definition typed as any record of metrics, names none.
+ */
+type ModelMetricsOf<O> = (O extends {
+    readonly config: {
+        readonly metrics?: infer M;
+    };
+} ? DeclaredNames<NonNullable<M>> : never) | EarlierModelMetricsOf<O>;
+/** A route picks how an entity with metrics reaches a property, so only such entities start one. */
+type RoutesOf<E, O> = [MetricsOf<E>] extends [never] ? never : PathsOf<E, O>;
+/**
+ * `entity.property` for every entity's scalar properties, and `id` for stored entities, plus the
+ * routes `entity.relationship.property` from each entity with metrics.
+ */
+type ModelDimensionsOf<E, O> = E extends unknown ? `${CamelCase<NameOf<E>>}.${FieldsOf<E> | RoutesOf<E, O>}` : never;
+/**
+ * `segmentstream.ontology.queryMetrics`: `POST /api/ontology/query_metrics`, as the signed-in user,
+ * who needs read permission on every entity the request reaches.
+ */
+export interface MetricQueryClient<Metric extends string = string, Dimension extends string = string> extends EarlierQueryMetricsName<Metric, Dimension> {
+    readonly queryMetrics: (request: MetricQuery<Metric, Dimension>, options?: RequestOptions) => Promise<MetricQueryResult>;
+}
+/**
+ * `segmentstream.ontology.<entity>.queryMetrics`: `POST /api/ontology/<entity>/query_metrics`, the
+ * entity's own metrics by the names relative to it, as the signed-in user.
+ */
+export interface EntityMetricQueryClient<Property extends string = string, Metric extends string = string, Temporal extends Property = Property, Path extends string = never> extends EarlierEntityQueryMetricsName<Property, Metric, Temporal, Path> {
+    readonly queryMetrics: (request: EntityMetricQuery<Property, Metric, Temporal, Path>, options?: RequestOptions) => Promise<MetricQueryResult>;
+}
+type ClientOf<E, O> = IsWarehouseBacked<E> extends true ? Pick<EntityClient<RecordOf<E>, never>, "find" | "query" | "get"> & EntityMetricQueryClient<keyof PropertiesOf<E> & string, MetricsOf<E>, keyof PropertiesOf<E> & string, PathsOf<E, O>> : EntityClient<RecordOf<E>, ActionClients<ActionsOf<E>> & (NameOf<E> extends "user" ? UserGeneratedActions<RecordOf<E>> : unknown), GeneratedOf<E>>;
+type TypedOntologyClient<O> = {
+    readonly [N in NameOf<EntitiesOf<O>>]: ClientOf<Extract<EntitiesOf<O>, {
+        readonly name: N;
+    }>, O>;
+} & MetricQueryClient<EntityMetricsOf<EntitiesOf<O>> | ModelMetricsOf<O>, ModelDimensionsOf<EntitiesOf<O>, O>>;
+/** A client for any entity, when the app passes no ontology type. */
+export type UntypedOntologyClient = MetricQueryClient & {
+    readonly [entity: string]: EntityClient<JsonRecord, {
+        readonly [action: string]: ActionCall<JsonRecord, JsonValue>;
+    }> & EntityMetricQueryClient;
+};
+/**
+ * `segmentstream.ontology`: one client per entity of `O`, the type of the app's ontology
+ * (`typeof ontology`), and `queryMetrics` across them, a name no entity takes. Without `O`, any
+ * entity name is accepted and records are untyped.
+ */
+export type OntologyClient<O = unknown> = unknown extends O ? UntypedOntologyClient : TypedOntologyClient<O>;
+/** Sends one ontology request with the caller's credentials. Paths are below `/api/ontology`. */
+export interface OntologyTransport {
+    readonly fetch: (path: string, init: RequestInit) => Promise<Response>;
+}
+/**
+ * Entities and actions exist only in the app's types, so the client resolves them by name when
+ * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/change_status`.
+ */
+export declare function createOntologyClient<O>(transport: OntologyTransport): OntologyClient<O>;
+/** `find` sends the query as URL parameters: `where` as JSON, `orderBy` as `field:direction`. */
+export declare function findParameters(query: ReadQuery): URLSearchParams;
+export {};