@cosmicdrift/kumiko-types 0.411.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.411.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"
@@ -329,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"