@cosmicdrift/kumiko-types 0.387.0 → 0.388.0

package/dist/config.d.ts

@@ -231,6 +231,8 @@ export type NotificationTemplateMeta = {
     readonly layoutSlug?: string;
     readonly category?: "transactional" | "marketing";
     readonly sender?: string;
+    readonly senderName?: string;
+    readonly replyTo?: string;
 };
 export type NotificationTemplateBody = {
     readonly body: string;

package/dist/define-handler.d.ts

@@ -14,6 +14,9 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: z.infer<TSchema>) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
@@ -31,6 +34,9 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: z.infer<TSchema>) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;

package/dist/event-store-executor-types.d.ts

@@ -3,6 +3,7 @@ import type { EntityDefinition } from "./fields.ts";
 import type { SessionUser, WriteResult } from "./handlers.ts";
 import type { DeleteContext, SaveContext } from "./hooks.ts";
 import type { EntityId, TenantId } from "./identifiers.ts";
+import type { ListAggregatePayload, ListAggregateResult } from "./list-aggregate-types.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { TenantDb } from "./tenant-db-types.ts";
 export type ParentVisibilityOption = {
@@ -21,6 +22,38 @@ export type LockGuardOption = {
     readonly unsafeSkipLockGuard?: boolean;
     readonly writePurpose?: WritePurpose;
 };
+export type ListRuntimeOptions = {
+    readonly searchAdapter?: SearchAdapter;
+    readonly includeDeleted?: boolean;
+    readonly referenceSearch?: {
+        readonly fields: ReadonlyArray<{
+            readonly fieldName: string;
+            readonly targetEntityName: string;
+            readonly labelField: string;
+        }>;
+        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+    };
+    readonly referenceSort?: {
+        readonly fields: ReadonlyArray<{
+            readonly fieldName: string;
+            readonly targetEntityName: string;
+            readonly labelField: string;
+        }>;
+        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+    };
+    readonly parentVisibility?: ParentVisibilityOption;
+};
+type ListFilterOption = {
+    readonly field: string;
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+    readonly value: unknown;
+};
+export type ListAggregateRequest = {
+    readonly search?: string | undefined;
+    readonly filter?: ListFilterOption | undefined;
+    readonly filters?: readonly ListFilterOption[] | undefined;
+    readonly aggregate: ListAggregatePayload;
+};
 export type EventStoreExecutor<Row extends Record<string, unknown> = Record<string, unknown>> = {
     create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: StreamTenantOption & {
         preSave?: PreSaveRunner;
@@ -70,30 +103,13 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
      *  one from ctx.searchAdapter here at runtime.
      *  options.searchAdapter (build-time) wins — the runtime override
      *  is the fallback for the default wrapper. */
-    runtimeOptions?: {
-        readonly searchAdapter?: SearchAdapter;
-        readonly includeDeleted?: boolean;
-        readonly referenceSearch?: {
-            readonly fields: ReadonlyArray<{
-                readonly fieldName: string;
-                readonly targetEntityName: string;
-                readonly labelField: string;
-            }>;
-            readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
-        };
-        readonly referenceSort?: {
-            readonly fields: ReadonlyArray<{
-                readonly fieldName: string;
-                readonly targetEntityName: string;
-                readonly labelField: string;
-            }>;
-            readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
-        };
-        readonly parentVisibility?: ParentVisibilityOption;
-    }) => Promise<CursorResult<Row>>;
+    runtimeOptions?: ListRuntimeOptions) => Promise<CursorResult<Row>>;
+    /** Groups and measures over the same WHERE as `list` (filters, search, ownership, field-read gates); paging and sort are ignored. */
+    aggregate: (payload: ListAggregateRequest, user: SessionUser, db: TenantDb, runtimeOptions?: ListRuntimeOptions) => Promise<ListAggregateResult>;
     detail: (payload: {
         id: EntityId;
     }, user: SessionUser, db: TenantDb, options?: {
         readonly parentVisibility?: ParentVisibilityOption;
     }) => Promise<Row | null>;
 };
+export {};

package/dist/fields.js

@@ -47,7 +47,7 @@ function isFieldTypeName(name) {
 export const FIELD_TYPE_NAMES = Object.keys(FIELD_TYPE_NAME_FLAGS).filter(isFieldTypeName);
 // Field types with no bound, editable widget on the auto-wired entityEdit
 // path (render-field.tsx renders a read-only banner instead) — shared by
-// the boot validator (packages/framework/src/engine/boot-validator/screens.ts)
+// the boot validator (packages/framework/src/engine/boot-validator/screens-forms.ts)
 // and the client-side required-field check (packages/renderer/src/app/form-schema.ts).
 // Embedded LIST fields (`multiple: true`) are the one exception — they get
 // their own EmbeddedListField grid widget — callers must check that

package/dist/handlers.d.ts

@@ -632,6 +632,9 @@ export type WriteHandlerDef = {
     /** Per-payload-field limits, e.g. per recipient address. Complements
      *  `rateLimit`; anonymous handlers still need an ip-keyed `rateLimit`. */
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: unknown) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     /** Reserves before the handler transaction opens. Reached through a nested ctx.write the
      *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */

package/dist/list-aggregate-types.d.ts

@@ -0,0 +1,38 @@
+import * as z from "zod";
+import type { AggregateKey } from "./aggregate-types.ts";
+export declare const MAX_LIST_AGGREGATE_MEASURES = 20;
+export declare const LIST_AGGREGATE_MEASURE_KINDS: readonly ["sum", "avg", "count", "min", "max"];
+export type ListAggregateMeasureKind = (typeof LIST_AGGREGATE_MEASURE_KINDS)[number];
+export declare const listAggregatePayloadSchema: z.ZodObject<{
+    groupBy: z.ZodOptional<z.ZodString>;
+    measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        kind: z.ZodEnum<{
+            avg: "avg";
+            count: "count";
+            max: "max";
+            min: "min";
+            sum: "sum";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ListAggregatePayload = {
+    readonly groupBy?: string | undefined;
+    readonly measures: readonly {
+        readonly field: string;
+        readonly kind: ListAggregateMeasureKind;
+    }[];
+};
+export type ListAggregateValue = number | string | null;
+export type ListAggregateGroup = {
+    readonly key: AggregateKey;
+    readonly label?: string | null;
+    readonly count: number;
+    readonly measures: readonly ListAggregateValue[];
+};
+export type ListAggregateResult = {
+    readonly groups: readonly ListAggregateGroup[];
+    readonly truncated?: true;
+    readonly searchTruncated?: true;
+};
+export declare function isListAggregateResult(value: unknown): value is ListAggregateResult;

package/dist/list-aggregate-types.js

@@ -0,0 +1,19 @@
+import * as z from "zod";
+import { isPlainObject } from "./type-guards.js";
+export const MAX_LIST_AGGREGATE_MEASURES = 20;
+export const LIST_AGGREGATE_MEASURE_KINDS = ["sum", "avg", "count", "min", "max"];
+export const listAggregatePayloadSchema = z.object({
+    groupBy: z.string().optional(),
+    measures: z
+        .array(z.object({ field: z.string(), kind: z.enum(LIST_AGGREGATE_MEASURE_KINDS) }))
+        .max(MAX_LIST_AGGREGATE_MEASURES)
+        .default([]),
+});
+const LIST_AGGREGATE_RESULT_KEYS = ["groups", "truncated", "searchTruncated"];
+// Closed key set: a row that merely has a `groups` field (jsonb column) must not
+// be mistaken for an aggregate and skip the row-level read filter.
+export function isListAggregateResult(value) {
+    return (isPlainObject(value) &&
+        Array.isArray(value["groups"]) &&
+        Object.keys(value).every((key) => LIST_AGGREGATE_RESULT_KEYS.includes(key)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.387.0",
+  "version": "0.388.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -154,6 +154,10 @@
       "types": "./dist/aggregate-types.d.ts",
       "default": "./dist/aggregate-types.js"
     },
+    "./list-aggregate-types": {
+      "types": "./dist/list-aggregate-types.d.ts",
+      "default": "./dist/list-aggregate-types.js"
+    },
     "./tenant-db-types": {
       "types": "./dist/tenant-db-types.d.ts",
       "default": "./dist/tenant-db-types.js"
@@ -281,7 +285,7 @@
   },
   "devDependencies": {
     "hono": "^4.13.1",
-    "postgres": "npm:@bender0oo0/postgres@3.4.9-kumiko.1",
+    "postgres": "npm:@bender0oo0/postgres@3.4.9-kumiko.2",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3",
     "ioredis": "^5.10.1"
@@ -433,6 +437,10 @@
         "types": "./dist/aggregate-types.d.ts",
         "default": "./dist/aggregate-types.js"
       },
+      "./list-aggregate-types": {
+        "types": "./dist/list-aggregate-types.d.ts",
+        "default": "./dist/list-aggregate-types.js"
+      },
       "./tenant-db-types": {
         "types": "./dist/tenant-db-types.d.ts",
         "default": "./dist/tenant-db-types.js"