@cosmicdrift/kumiko-types 0.339.0 → 0.341.0

package/dist/aggregate-types.d.ts

@@ -16,6 +16,8 @@ export type AggregateSpec = {
     readonly measure: AggregateMeasure;
     readonly groupBy?: readonly AggregateDimension[];
     readonly orderByValue?: "asc" | "desc";
+    /** Direction of the group-key ordering (default asc). orderByValue stays the primary key when set. */
+    readonly orderByKeys?: "asc" | "desc";
     readonly limit?: number;
 };
 export type AggregateKey = string | number | boolean | null;

package/dist/cache-sync-types.d.ts

@@ -0,0 +1,8 @@
+export type CacheSyncBus = {
+    publish(topic: string, message: unknown): void;
+    subscribe(topic: string, listener: (message: unknown) => void): () => void;
+    onResync(listener: () => void): () => void;
+};
+export type ClosableCacheSyncBus = CacheSyncBus & {
+    close(): Promise<void>;
+};

package/dist/cache-sync-types.js

@@ -0,0 +1 @@
+export {};

package/dist/define-handler.d.ts

@@ -1,7 +1,7 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
 import type { KumikoEventTypeMap } from "./event-type-map.js";
-import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, HandlerContext, QueryEvent, RateLimitDeclaration, WriteEvent, WriteResult } from "./handlers.js";
+import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, HandlerContext, PayloadRateLimitOption, QueryEvent, RateLimitDeclaration, WriteEvent, WriteResult } from "./handlers.js";
 import type { PipelineDef } from "./step.js";
 export type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
     readonly name: TName;
@@ -11,6 +11,7 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly agent?: AgentHandlerHints;
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
+    readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly tenantlessAnonymous?: boolean;
     readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
@@ -24,6 +25,7 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly agent?: AgentHandlerHints;
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
+    readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly tenantlessAnonymous?: boolean;
 } & ({

package/dist/feature.d.ts

@@ -6,7 +6,7 @@ import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { EntityTableMeta } from "./entity-table-meta-types.js";
 import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.js";
 import type { EntityDefinition } from "./fields.js";
-import type { AccessRule, AgentHandlerHints, AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventMigrationDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, StreamHandlerDef, StreamHandlerFn, WriteHandlerDef, WriteHandlerFn } from "./handlers.js";
+import type { AccessRule, AgentHandlerHints, AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventMigrationDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, PayloadRateLimitOption, QualifiedEventName, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, StreamHandlerDef, StreamHandlerFn, WriteHandlerDef, WriteHandlerFn } from "./handlers.js";
 import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.js";
 import type { HttpRouteDefinition } from "./http-route.js";
 import type { ContentCollectionDefinition, NavDefinition } from "./nav.js";
@@ -40,6 +40,7 @@ export type SecretKeyDefinition = {
     readonly scope: "tenant";
     readonly required?: boolean;
     readonly writeRoles?: readonly string[];
+    readonly valueSchema?: ZodType<string>;
 };
 export type SecretOptions = Omit<SecretKeyDefinition, "shortName" | "qualifiedName">;
 export type SecretNamespaceDefinition = {
@@ -54,6 +55,7 @@ export type SecretNamespaceDefinition = {
     readonly scope: "tenant";
     readonly writeRoles?: readonly string[];
     readonly nameSchema?: ZodType<string>;
+    readonly valueSchema?: ZodType<string>;
 };
 export type SecretNamespaceOptions = Omit<SecretNamespaceDefinition, "shortName" | "qualifiedPrefix">;
 export type SecretNamespaceHandle = {
@@ -236,6 +238,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     writeHandler<TSchema extends ZodType>(name: string, schema: TSchema, handler: WriteHandlerFn<z.infer<TSchema>>, options: {
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;
+        additionalRateLimits?: readonly PayloadRateLimitOption[];
         description?: string;
         agent?: AgentHandlerHints;
         escapeHatch?: EscapeHatchDeclaration;

package/dist/handlers.d.ts

@@ -1,5 +1,6 @@
 import type { Redis } from "ioredis";
 import type { ZodType } from "zod";
+import type { CacheSyncBus } from "./cache-sync-types.js";
 import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./config.js";
 import type { DbConnection } from "./db-connection.js";
 import type { DerivativesContext } from "./derivatives-types.js";
@@ -135,9 +136,27 @@ export type NotifyOptions = {
     readonly priority?: NotifyPriority;
     readonly idempotencyKey?: string;
     readonly recipientId?: string;
+    readonly immediate?: boolean;
+    readonly locale?: string;
+};
+export type NotifyDeliveryStatus = "queued" | "sent" | "failed" | "skipped";
+export type NotifyDelivery = {
+    readonly channel: string;
+    readonly recipientId: string | null;
+    readonly status: NotifyDeliveryStatus;
+    readonly error: string | null;
+    readonly deliveryAttemptId?: string;
+};
+export type NotifyResult = {
+    readonly deliveries: readonly NotifyDelivery[];
 };
-export type NotifyFn = (notificationType: string, options: NotifyOptions) => Promise<void>;
-export type NotifyFactory = (user: SessionUser, tenantId: TenantId) => NotifyFn;
+export type NotifyFn = (notificationType: string, options: NotifyOptions) => Promise<NotifyResult>;
+export type NotifyJobDispatcher = {
+    dispatch(jobName: string, payload: Record<string, unknown>, meta?: {
+        readonly priority?: number;
+    }): Promise<unknown>;
+};
+export type NotifyFactory = (user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher) => NotifyFn;
 export type EscapeHatchKind = "unsafe-raw" | "acknowledge-cross-tenant" | "global-write" | "identity-switch" | "unsafe-all-tenants";
 export type EscapeHatchTarget = {
     readonly id: string;
@@ -155,6 +174,7 @@ export type EscapeHatchAuditSink = (event: EscapeHatchUseEvent) => Promise<void>
 export type EscapeHatchReporter = (kind: EscapeHatchKind, reason: string, target?: EscapeHatchTarget) => void;
 type SharedContextFields = {
     readonly redis?: Redis;
+    readonly cacheSync?: CacheSyncBus;
     readonly jobRunner?: JobRunnerRef;
     readonly configResolver?: ConfigResolver;
     readonly config?: ConfigAccessor;
@@ -169,6 +189,7 @@ type SharedContextFields = {
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.js").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.js").RateLimitResolver;
+    readonly _rateLimitPayloadDigest?: (value: string) => string;
     readonly searchAdapter?: SearchAdapter;
     readonly files?: FileContext;
     readonly derivatives?: DerivativesContext;
@@ -446,6 +467,15 @@ export type RateLimitOption = {
     readonly windowSeconds: number;
     readonly cost?: number;
 };
+export type RateLimitPayloadBucket = {
+    readonly payloadField: string;
+};
+export type PayloadRateLimitOption = {
+    readonly per: RateLimitPayloadBucket;
+    readonly limit: number;
+    readonly windowSeconds: number;
+    readonly cost?: number;
+};
 export type RateLimitDisabled = {
     readonly disabled: true;
     readonly reason: string;
@@ -472,6 +502,9 @@ export type WriteHandlerDef = {
     readonly agent?: AgentHandlerHints;
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
+    /** Per-payload-field limits, e.g. per recipient address. Complements
+     *  `rateLimit`; anonymous handlers still need an ip-keyed `rateLimit`. */
+    readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
     /** Lets an anonymous `POST /api/write` for this handler proceed under
      *  SYSTEM_TENANT_ID when the host resolves no tenant. Boot requires

package/dist/http-route.d.ts

@@ -1,4 +1,5 @@
 import type { Context } from "hono";
+import type { RateLimitOption } from "./handlers.js";
 /** Subset von HTTP-Methoden den wir aktiv unterstützen. Hono spricht
  *  alle, aber das hier sind die einzigen die ein Feature-Author
  *  realistisch deklariert. */
@@ -36,6 +37,13 @@ export type HttpRouteHandlerDeps = {
     readonly clientIp: string;
 };
 export type HttpRouteHandler = (c: Context<any, any>, deps: HttpRouteHandlerDeps) => Response | Promise<Response>;
+/** Same shape as a handler's `rateLimit`, restricted to the IP-keyed
+ *  buckets: a route has no dispatcher identity to key on. `"ip+handler"`
+ *  keeps one bucket per route ("METHOD path"), `"ip"` shares one across
+ *  every route that declares it. */
+export type HttpRouteRateLimit = Omit<RateLimitOption, "per"> & {
+    readonly per: "ip" | "ip+handler";
+};
 export type HttpRouteDefinition = {
     /** HTTP-Methode — bei Hono-Mount via app.{get,post,...}(path). */
     readonly method: HttpRouteMethod;
@@ -49,4 +57,8 @@ export type HttpRouteDefinition = {
     /** Hono-Handler. Bekommt Hono-Context + Framework-Deps; returnt
      *  Response (sync oder async). */
     readonly handler: HttpRouteHandler;
+    /** Enforced before the route's guards through the server's rate-limit
+     *  resolver (fail-closed like the global L1 limiter: a limiter outage
+     *  answers 503 instead of letting the request through). */
+    readonly rateLimit?: HttpRouteRateLimit;
 };

package/dist/projection.d.ts

@@ -7,10 +7,12 @@ import type { SchemaTable } from "./schema-table-types.js";
 export type ProjectionTable = SchemaTable;
 export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: DbRunner, table: ProjectionTable) => Promise<void>;
 export type MultiStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: DbRunner, ctx: MultiStreamApplyContext) => Promise<void>;
+export type ProjectionRowIdOf = (source: Pick<StoredEvent, "tenantId" | "aggregateId">) => string;
 export type ProjectionDefinition = {
     readonly name: string;
     readonly source: string | readonly string[];
     readonly extraSources?: readonly string[];
+    readonly extraSourceRowIds?: Readonly<Record<string, ProjectionRowIdOf>>;
     readonly table: ProjectionTable;
     readonly entity?: EntityDefinition;
     readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
@@ -18,6 +20,7 @@ export type ProjectionDefinition = {
 };
 export type EntityProjectionExtension = {
     readonly sources?: readonly string[];
+    readonly rowIdOf?: ProjectionRowIdOf;
     readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
 };
 export type MspErrorPolicy = {

package/dist/step.js

@@ -1,4 +1,4 @@
-// Step-Vocabulary Types — see docs/plans/architecture/intern/step-vocabulary.md
+// Step-Vocabulary Types — see kumiko-platform/docs/archive/plans/architecture/intern/step-vocabulary.md
 //
 // M.1 minimal scope:
 //   - Steps execute against the existing HandlerContext (no per-step subset).

package/dist/where-clause-types.d.ts

@@ -1,3 +1,8 @@
+export type JsonTextMatch = {
+    /** Top-level keys, tried in order; the first non-null text value is compared (COALESCE). */
+    readonly keys: readonly [string, ...string[]];
+    readonly eq: string;
+};
 export type WhereOperator = {
     readonly gt?: unknown;
     readonly gte?: unknown;
@@ -6,6 +11,8 @@ export type WhereOperator = {
     readonly ne?: unknown;
     readonly in?: readonly unknown[];
     readonly like?: string;
+    /** jsonb columns only; cannot be combined with other operators in the same object. */
+    readonly jsonText?: JsonTextMatch | readonly JsonTextMatch[];
 };
 export type WherePrimitive = string | number | boolean | bigint | Date | null | undefined;
 export type WhereValue = WherePrimitive | readonly WherePrimitive[] | WhereOperator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.339.0",
+  "version": "0.341.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": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -222,6 +222,10 @@
       "types": "./dist/file-provider-resolver-types.d.ts",
       "default": "./dist/file-provider-resolver-types.js"
     },
+    "./cache-sync-types": {
+      "types": "./dist/cache-sync-types.d.ts",
+      "default": "./dist/cache-sync-types.js"
+    },
     "./derivatives-types": {
       "types": "./dist/derivatives-types.d.ts",
       "default": "./dist/derivatives-types.js"
@@ -481,6 +485,10 @@
         "types": "./dist/file-provider-resolver-types.d.ts",
         "default": "./dist/file-provider-resolver-types.js"
       },
+      "./cache-sync-types": {
+        "types": "./dist/cache-sync-types.d.ts",
+        "default": "./dist/cache-sync-types.js"
+      },
       "./derivatives-types": {
         "types": "./dist/derivatives-types.d.ts",
         "default": "./dist/derivatives-types.js"

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Where clauses and aggregate options describe jsonb text matches and key ordering",
+    "detail": "`WhereOperator` gains `jsonText?: JsonTextMatch | readonly JsonTextMatch[]` with `JsonTextMatch = { keys: readonly [string, ...string[]]; eq: string }`, and the aggregate options gain `orderByKeys?: \"asc\" | \"desc\"`.",
+    "migration": "keine"
+  },
   {
     "version": "0.338.0",
     "type": "improvement",