@cosmicdrift/kumiko-types 0.410.0 → 0.412.0

package/dist/api-example.d.ts

@@ -0,0 +1,32 @@
+import * as z from "zod";
+export declare const apiExampleEndpoints: readonly ["/api/query", "/api/write", "/api/batch"];
+export type ApiExampleEndpoint = (typeof apiExampleEndpoints)[number];
+export declare const ApiExampleFileSchema: z.ZodObject<{
+    request: z.ZodObject<{
+        endpoint: z.ZodEnum<{
+            "/api/batch": "/api/batch";
+            "/api/query": "/api/query";
+            "/api/write": "/api/write";
+        }>;
+        body: z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            payload: z.ZodOptional<z.ZodUnknown>;
+            commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                type: z.ZodString;
+                payload: z.ZodOptional<z.ZodUnknown>;
+            }, z.core.$strip>>>;
+            requestId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+        status: z.ZodNumber;
+        body: z.ZodUnknown;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ApiExampleFile = z.infer<typeof ApiExampleFileSchema>;
+export declare const WebhookExampleFileSchema: z.ZodObject<{
+    event: z.ZodString;
+    version: z.ZodNumber;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type WebhookExampleFile = z.infer<typeof WebhookExampleFileSchema>;

package/dist/api-example.js

@@ -0,0 +1,24 @@
+import * as z from "zod";
+// One recorded HTTP exchange, shared by the recorder (testing) and the API docs generator (bundled-features).
+export const apiExampleEndpoints = ["/api/query", "/api/write", "/api/batch"];
+export const ApiExampleFileSchema = z.object({
+    request: z.object({
+        endpoint: z.enum(apiExampleEndpoints),
+        body: z.object({
+            type: z.string().optional(),
+            payload: z.unknown().optional(),
+            commands: z.array(z.object({ type: z.string(), payload: z.unknown().optional() })).optional(),
+            requestId: z.string().optional(),
+        }),
+    }),
+    response: z.object({
+        status: z.number().int(),
+        body: z.unknown(),
+    }),
+});
+// One recorded webhook delivery payload; `event` is the QN of its contract.
+export const WebhookExampleFileSchema = z.object({
+    event: z.string(),
+    version: z.number().int().positive(),
+    payload: z.record(z.string(), z.unknown()),
+});

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

@@ -9,6 +9,10 @@ import type { SearchAdapter } from "./search-adapter.ts";
 import type { TenantDb } from "./tenant-db-types.ts";
 export type ParentVisibilityOption = {
     readonly entities: ReadonlyMap<string, EntityDefinition>;
+    readonly readModelEntities?: ReadonlyMap<string, {
+        readonly entity: EntityDefinition;
+        readonly table: SchemaTable;
+    }>;
     readonly canReadEntity?: (entityName: string) => boolean;
     readonly resolveTable?: (entityName: string) => SchemaTable;
 };

package/dist/feature-registrar.d.ts

@@ -6,7 +6,7 @@ import type { RegisterEntityCrudOptions } from "./entity-handlers.ts";
 import type { EntityTableMeta } from "./entity-table-meta-types.ts";
 import type { KumikoEventTypeMap } from "./event-type-map.ts";
 import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.ts";
-import type { BootCheckFn, MetricOptions, SecretKeyHandle, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableOptions, UiHints } from "./feature.ts";
+import type { BootCheckFn, MetricOptions, SecretKeyHandle, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableOptions, UiHints, WebhookEventHandle } from "./feature.ts";
 import type { EntityDefinition } from "./fields.ts";
 import type { AccessRule, AuthClaimsFn, BeforeTransactionWhenNested, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, RateLimitDeclaration, StreamHandlerFn } from "./handlers.ts";
 import type { HookPhase, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
@@ -184,6 +184,14 @@ export type FeatureRegistrar<TFeature extends string = string> = {
             readonly transform: EventUpcastFn | DeclarativeEventMigration;
         }[];
     }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
+    defineWebhookEvent(definition: {
+        readonly name: string;
+        readonly description: string;
+        readonly payload: z.ZodObject;
+        readonly version: number;
+        /** Name in the delivered webhook and in the generated docs. Defaults to `name`. */
+        readonly wireName?: string;
+    }): WebhookEventHandle;
     readsConfig(...qualifiedKeys: string[]): void;
     readsConfig(options: {
         readonly keys: readonly string[];

package/dist/feature.d.ts

@@ -108,6 +108,33 @@ export type UiHints = {
     readonly recommended?: boolean;
     readonly configurableOptions?: readonly UiHintOption[];
 };
+/** Lifecycle verbs of an entity that can be released as webhook events. */
+export type WebhookEntityVerb = "created" | "updated" | "deleted";
+/** What `r.defineWebhookEvent` stores; `qn` is `<feature>:<name>`. */
+export type WebhookEventDef = {
+    readonly qn: string;
+    readonly wireName: string;
+    readonly description: string;
+    readonly payload: z.ZodObject;
+    readonly version: number;
+};
+export type WebhookEventHandle = {
+    readonly name: string;
+    readonly payload: z.ZodObject;
+    readonly version: number;
+};
+/** Public payload contract of a webhook event: declared by a feature or derived from an entity. */
+export type WebhookEventContract = {
+    readonly qn: string;
+    /** The event name receivers see in the delivered webhook: `wireName` of a declared event, `entity.verb` of a derived one. */
+    readonly wireName: string;
+    readonly description: string;
+    readonly payload: z.ZodObject;
+    readonly version: number;
+    readonly origin: "declared" | "entity";
+    readonly entity?: string;
+    readonly verb?: WebhookEntityVerb;
+};
 export type BootCheckContext = {
     readonly features: readonly FeatureDefinition[];
 };
@@ -174,6 +201,8 @@ export type FeatureDefinition = {
     readonly referenceData: readonly ReferenceDataDef[];
     readonly notifications: Readonly<Record<string, NotificationDefinition>>;
     readonly events: Readonly<Record<string, EventDef>>;
+    /** Public webhook contracts from r.defineWebhookEvent, keyed by QN. Absent when the feature declares none. */
+    readonly webhookEvents?: Readonly<Record<string, WebhookEventDef>>;
     readonly eventMigrations: Readonly<Record<string, readonly EventMigrationDef[]>>;
     readonly configReads: readonly string[];
     readonly handlerEntityMappings: Readonly<Record<string, string>>;
@@ -257,6 +286,8 @@ export type Registry = {
     getJob(qualifiedName: string): JobDefinition | undefined;
     getAllJobs(): ReadonlyMap<string, JobDefinition>;
     getEvent(qualifiedName: string): EventDef | undefined;
+    getWebhookEventContract(qualifiedName: string): WebhookEventContract | undefined;
+    getWebhookEventContracts(): readonly WebhookEventContract[];
     getEventUpcasters(): ReadonlyMap<string, {
         readonly currentVersion: number;
         readonly chain: ReadonlyMap<number, EventUpcastFn>;

package/dist/fields.d.ts

@@ -728,6 +728,8 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
      *  only for genuinely tenant-independent aggregates like `user`. The first
      *  event (create) is what's routed; updates resolve the stream tenant upstream. */
     readonly systemStream?: boolean;
+    /** Lets token scopes release `<entity>.created/.updated/.deleted` as webhook events. Off by default: bundle entities can hold secrets. */
+    readonly webhookEvents?: boolean;
     /** Schema version stamped on every lifecycle event (default 1, integer 1..999). Bump it together with a step in `eventMigrations`. */
     readonly eventVersion?: number;
     /** One step per version, fromVersion → fromVersion+1. Transforms run on row-shaped field records; the record may be partial, touch only keys that are present.

package/dist/handler-context-services.d.ts

@@ -12,6 +12,14 @@ import type { KmsAdapter } from "./kms-adapter-types.ts";
 import type { RateLimitResolver } from "./rate-limit-types.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { MasterKeyProvider, SecretsContext } from "./secrets-types.ts";
+/** Addressed live signal: the SSE frame reaches only the listed users of the caller's own tenant. */
+export type UserLiveSignals = {
+    push(userIds: readonly string[], signal: {
+        readonly type: string;
+        readonly entity?: string;
+        readonly id?: string;
+    }): Promise<void>;
+};
 /**
  * Infrastructure the app wired at boot, as the handler or job sees it. extraContext keys the
  * framework does not know land in `extensions`.
@@ -19,6 +27,7 @@ import type { MasterKeyProvider, SecretsContext } from "./secrets-types.ts";
 export type ContextServices = {
     readonly redis?: Redis;
     readonly cacheSync?: CacheSyncBus;
+    readonly userLiveSignals?: UserLiveSignals;
     readonly jobRunner?: JobRunnerRef;
     readonly searchAdapter?: SearchAdapter;
     readonly entityCache?: EntityCache;

package/dist/handlers.d.ts

@@ -12,14 +12,14 @@ import type { FileContext } from "./file-handle-types.ts";
 import type { FileProviderResolver } from "./file-provider-resolver-types.ts";
 import type { GeoTzProvider } from "./geo-tz.ts";
 import type { BeforeTransactionContext, HandlerAuth, HandlerDb, HandlerDispatch, HandlerEvents, HandlerObservability, JobDispatch, JobEvents, JobObservability, ReservationContext } from "./handler-context-facets.ts";
-import type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle } from "./handler-context-services.ts";
+import type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle, UserLiveSignals } from "./handler-context-services.ts";
 import type { Logger } from "./logger.ts";
 import type { Meter, Tracer } from "./observability/index.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { CrossTenantReads, TenantDb } from "./tenant-db-types.ts";
 import type { Clock, TzContext } from "./tz-context.ts";
 export type { BeforeTransactionContext, HandlerAuth, HandlerDb, HandlerDispatch, HandlerEvents, HandlerObservability, JobDispatch, JobEvents, JobObservability, ReservationContext, } from "./handler-context-facets.ts";
-export type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle, } from "./handler-context-services.ts";
+export type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle, UserLiveSignals, } from "./handler-context-services.ts";
 import type { AgentHandlerHints } from "./agent-hints.ts";
 export type OpenToAllPersonalData = "tenant-members";
 export type OpenToAllDeclaration = {
@@ -222,6 +222,7 @@ export type TenantWriteTarget = {
 type SharedContextFields = {
     readonly redis?: Redis;
     readonly cacheSync?: CacheSyncBus;
+    readonly userLiveSignals?: UserLiveSignals;
     readonly jobRunner?: JobRunnerRef;
     readonly configResolver?: ConfigResolver;
     readonly config?: ConfigAccessor;

package/dist/presence-types.d.ts

@@ -0,0 +1,42 @@
+export declare const PRESENCE_FEATURE: "presence";
+export declare const PRESENCE_WRITES: {
+    readonly heartbeat: "presence:write:heartbeat";
+    readonly leave: "presence:write:leave";
+};
+export declare const PRESENCE_QUERIES: {
+    readonly list: "presence:query:list";
+};
+export declare const PRESENCE_CHANGED_EVENT: "presence:event:changed";
+export declare const PRESENCE_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const PRESENCE_LIST_REFETCH_INTERVAL_MS = 25000;
+export declare const PRESENCE_FOCUS_MAX_LENGTH = 128;
+export declare const PRESENCE_LIST_MAX_IDS = 100;
+export type PresenceActivity = "viewing" | "editing";
+export type PresenceEntry = {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly activity: PresenceActivity;
+    readonly focus?: string;
+    /** ISO timestamp from which the user has been in this activity and focus. */
+    readonly since: string;
+};
+export type PresenceHeartbeatPayload = {
+    readonly entity: string;
+    readonly id: string;
+    readonly activity: PresenceActivity;
+    readonly focus?: string;
+};
+export type PresenceLeavePayload = {
+    readonly entity: string;
+    readonly id: string;
+};
+export type PresenceListPayload = {
+    readonly entity: string;
+    readonly ids: readonly string[];
+};
+export type PresenceHeartbeatResult = {
+    readonly others: readonly PresenceEntry[];
+};
+export type PresenceListResult = {
+    readonly byId: Readonly<Record<string, readonly PresenceEntry[]>>;
+};

package/dist/presence-types.js

@@ -0,0 +1,15 @@
+// Contract between the presence feature (server) and the presence hooks and widgets in the
+// renderer. The renderer must not import bundled-features, so both sides share this file.
+export const PRESENCE_FEATURE = "presence";
+export const PRESENCE_WRITES = {
+    heartbeat: "presence:write:heartbeat",
+    leave: "presence:write:leave",
+};
+export const PRESENCE_QUERIES = {
+    list: "presence:query:list",
+};
+export const PRESENCE_CHANGED_EVENT = "presence:event:changed";
+export const PRESENCE_HEARTBEAT_INTERVAL_MS = 15_000;
+export const PRESENCE_LIST_REFETCH_INTERVAL_MS = 25_000;
+export const PRESENCE_FOCUS_MAX_LENGTH = 128;
+export const PRESENCE_LIST_MAX_IDS = 100;

package/dist/screen-entity-edit.d.ts

@@ -127,6 +127,10 @@ type EditFieldsSectionBase = {
      *  and in the "up next" box. Wizard layouts only; unlike `description` it
      *  is not shown inside the step. */
     readonly subtitle?: string;
+    /** Wizard layouts only: text under this step's title in the "up next" box while the step before it is active; falls back to `subtitle`. */
+    readonly upNextHint?: string;
+    /** Wizard layouts only: field of this section whose formatted value shows under the step label in the step rail once the step is done. Needs a field of this section. */
+    readonly summaryField?: string;
     /** Rendered top-right in the section's Card title row — same
      *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
      *  evaluated against the same record. Every action must resolve an icon
@@ -154,6 +158,14 @@ export type EditExtensionSection = {
     readonly id?: string;
     readonly kind: "extension";
     readonly title: string;
+    /** Wizard layouts only: intro text above the step, same slot as `EditFieldsSection.description`. */
+    readonly description?: string;
+    /** Wizard layouts only: short line under this step's title in the step rail and the "up next" box. */
+    readonly subtitle?: string;
+    /** Wizard layouts only: text under this step's title in the "up next" box while the step before it is active; falls back to `subtitle`. */
+    readonly upNextHint?: string;
+    /** Wizard layouts only: field whose formatted value shows under the step label once the step is done. On an `actionForm` it names a field of the screen's `fields`; elsewhere a field of a fields section of the layout. */
+    readonly summaryField?: string;
     readonly component: PlatformComponent;
     /** When true, the extension registers via `useExtensionFormSubmit` and the
      *  surrounding form's Save button should activate for its dirty state.
@@ -374,16 +386,24 @@ export type EditLayout = {
      *  list of independent preferences rather than one record form. Default
      *  "form" keeps the grid of cells. */
     readonly variant?: "form" | "settings-list";
+    /** Hides the asterisk after required field labels. Default false (shown). */
+    readonly hideRequiredMarker?: boolean;
     /** Persists in-progress wizard state as a resumable draft instead of
      *  discarding it on navigation away. */
     readonly draft?: boolean;
-    /** Wizard layouts only. `upNext: true` adds an "up next" box to the step
-     *  rail with the following step's title and `subtitle`; the last step
-     *  shows none. */
+    /** Wizard layouts only. `aside.upNext: true` adds an "up next" box to the step
+     *  rail with the following step's title and its `upNextHint` (else `subtitle`) only.
+     *  The last step shows the box only with `finishDescription` (i18n key): the
+     *  finish action as title, that text under it. */
     readonly wizard?: {
         readonly aside?: {
             readonly upNext: true;
+            readonly finishDescription?: string;
         };
+        /** Also offers "Save and close" while creating a record (default: update mode only). */
+        readonly saveAndCloseOnCreate?: boolean;
+        /** Disables the finish button (and blocks the submit) while the condition holds on the form values. */
+        readonly submitDisabledWhen?: FieldCondition;
     };
 };
 export type EntityWriteExcludedFields = {

package/dist/screen-entity-list.d.ts

@@ -146,6 +146,8 @@ export type RowActionWriteHandler = {
     readonly confirmLabel?: string;
     /** Conditional visibility per row. */
     readonly visible?: FieldCondition;
+    /** projectionDetail header action only: shown while one of these tab (section) ids is active. Needs `layout.mode: "tabs"`; default every tab. */
+    readonly showOnTabs?: readonly string[];
     /** Visual style. "danger" renders red + forces a confirm dialog (even
      *  without an explicit `confirm` key). */
     readonly style?: "primary" | "secondary" | "danger";
@@ -185,6 +187,8 @@ export type RowActionNavigateBase = {
     readonly tab?: string;
     /** Conditional visibility per row. */
     readonly visible?: FieldCondition;
+    /** projectionDetail header action only: shown while one of these tab (section) ids is active. Needs `layout.mode: "tabs"`; default every tab. */
+    readonly showOnTabs?: readonly string[];
     /** Visual style only — unlike the writeHandler variants, "danger" does not
      *  force a confirm dialog here: the target form is the confirmation. */
     readonly style?: "primary" | "secondary" | "danger";
@@ -228,6 +232,8 @@ export type RowActionDrawer = {
     readonly params?: RowFieldExtractor;
     /** Per-row conditional visibility. */
     readonly visible?: FieldCondition;
+    /** projectionDetail header action only: shown while one of these tab (section) ids is active. Needs `layout.mode: "tabs"`; default every tab. */
+    readonly showOnTabs?: readonly string[];
     /** Visual style only — unlike the writeHandler variants, "danger" does not
      *  force a confirm dialog here: the target form is the confirmation. */
     readonly style?: "primary" | "secondary" | "danger";
@@ -266,6 +272,8 @@ export type RowActionClientAction = {
     readonly confirmLabel?: string;
     /** Conditional visibility per row. */
     readonly visible?: FieldCondition;
+    /** projectionDetail header action only: shown while one of these tab (section) ids is active. Needs `layout.mode: "tabs"`; default every tab. */
+    readonly showOnTabs?: readonly string[];
     /** Visual style. "danger" forces a confirm dialog, like a writeHandler. */
     readonly style?: "primary" | "secondary" | "danger";
     /** Overrides the id-based default icon, see `RowActionWriteHandler.icon`. */

package/dist/screen-list-table.d.ts

@@ -3,7 +3,7 @@ export declare const LIST_TABLE_DENSITIES: readonly ["comfortable", "compact"];
 export type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
 export declare const LIST_COLUMN_PINS: readonly ["left", "right"];
 export type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
-export declare const LIST_TABLE_OPTION_KEYS: readonly ["rememberState", "resetAll", "columnPicker", "density", "pinning", "resizing", "keyboardNavigation", "export", "grouping", "totals"];
+export declare const LIST_TABLE_OPTION_KEYS: readonly ["rememberState", "resetAll", "columnPicker", "density", "pinning", "resizing", "keyboardNavigation", "export", "grouping", "totals", "compactHeader"];
 export declare const LIST_TABLE_GROUPING_KEYS: readonly ["field", "label", "labels", "collapsedWhen", "userChoice", "fields"];
 export declare const LIST_TABLE_TOTAL_KEYS: readonly ["field", "kind"];
 export declare const LIST_TABLE_EXPORT_KEYS: readonly ["xlsx", "maxRows"];
@@ -25,6 +25,8 @@ export type ListTableOptions = {
     readonly resizing?: boolean;
     /** Rows become one tab stop; ArrowUp/ArrowDown move, Home/End jump, Enter runs the row click. Space stays reserved for selection. */
     readonly keyboardNavigation?: boolean;
+    /** Renders the header row smaller (12px) and semibold. */
+    readonly compactHeader?: boolean;
     readonly density?: {
         /** Row density on first visit. Default "comfortable". */
         readonly default?: ListTableDensity;

package/dist/screen-list-table.js

@@ -11,6 +11,7 @@ export const LIST_TABLE_OPTION_KEYS = [
     "export",
     "grouping",
     "totals",
+    "compactHeader",
 ];
 export const LIST_TABLE_GROUPING_KEYS = [
     "field",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.410.0",
+  "version": "0.412.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>",
@@ -22,6 +22,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./api-example": {
+      "types": "./dist/api-example.d.ts",
+      "default": "./dist/api-example.js"
+    },
     "./kebab-case": {
       "types": "./dist/kebab-case.d.ts",
       "default": "./dist/kebab-case.js"
@@ -46,6 +50,10 @@
       "types": "./dist/in-app-notification-types.d.ts",
       "default": "./dist/in-app-notification-types.js"
     },
+    "./presence-types": {
+      "types": "./dist/presence-types.d.ts",
+      "default": "./dist/presence-types.js"
+    },
     "./target-ref": {
       "types": "./dist/target-ref.d.ts",
       "default": "./dist/target-ref.js"
@@ -325,6 +333,10 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       },
+      "./api-example": {
+        "types": "./dist/api-example.d.ts",
+        "default": "./dist/api-example.js"
+      },
       "./kebab-case": {
         "types": "./dist/kebab-case.d.ts",
         "default": "./dist/kebab-case.js"
@@ -349,6 +361,10 @@
         "types": "./dist/in-app-notification-types.d.ts",
         "default": "./dist/in-app-notification-types.js"
       },
+      "./presence-types": {
+        "types": "./dist/presence-types.d.ts",
+        "default": "./dist/presence-types.js"
+      },
       "./target-ref": {
         "types": "./dist/target-ref.d.ts",
         "default": "./dist/target-ref.js"