@cosmicdrift/kumiko-framework 0.411.0 → 0.412.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/agents/api/framework-db.md +1 -1
  2. package/agents/api/framework-engine.md +48 -1
  3. package/agents/api/framework-errors.md +2 -0
  4. package/agents/api/types.md +8 -0
  5. package/agents/api.md +2 -2
  6. package/agents/examples/api-docs.md +702 -0
  7. package/agents/examples.md +1 -0
  8. package/dist/api/auth-middleware.d.ts +1 -0
  9. package/dist/api/index.d.ts +3 -0
  10. package/dist/api/index.js +3 -0
  11. package/dist/api/pat-auth-reject.d.ts +7 -0
  12. package/dist/api/pat-auth-reject.js +7 -0
  13. package/dist/api/server-middleware.js +2 -1
  14. package/dist/compliance/sub-processors.js +2 -2
  15. package/dist/config/index.d.ts +25 -0
  16. package/dist/config/index.js +28 -1
  17. package/dist/db/event-store-executor-read-paging.d.ts +1 -0
  18. package/dist/db/event-store-executor-read-paging.js +2 -1
  19. package/dist/db/read-gate-clause.js +26 -7
  20. package/dist/db/table-builder.d.ts +1 -2
  21. package/dist/engine/define-feature.js +3 -0
  22. package/dist/engine/entity-list-runtime-options.js +12 -0
  23. package/dist/engine/factories.d.ts +2 -0
  24. package/dist/engine/feature-builder-state.d.ts +2 -1
  25. package/dist/engine/feature-builder-state.js +1 -0
  26. package/dist/engine/index.d.ts +5 -2
  27. package/dist/engine/index.js +4 -1
  28. package/dist/engine/registry-facade.js +13 -0
  29. package/dist/engine/webhook-contracts.d.ts +12 -0
  30. package/dist/engine/webhook-contracts.js +172 -0
  31. package/dist/engine/webhook-events.d.ts +34 -0
  32. package/dist/engine/webhook-events.js +71 -0
  33. package/dist/errors/docs-url.js +2 -19
  34. package/dist/errors/error-codes.d.ts +20 -0
  35. package/dist/errors/error-codes.js +19 -0
  36. package/dist/errors/index.d.ts +2 -0
  37. package/dist/errors/index.js +1 -0
  38. package/dist/i18n/required-surface-keys.d.ts +4 -0
  39. package/dist/i18n/required-surface-keys.js +15 -0
  40. package/package.json +3 -3
  41. package/src/changes.json +30 -0
@@ -109,7 +109,7 @@ function listEventTenantIds(db: AnyDb): Promise<string[]>;
109
109
  function loadSnapshotJson(path: string): Snapshot | null;
110
110
  function nullBlindIndexesForSubject(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectKey: string): Promise<void>;
111
111
  function outsideTransactionPoolOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
112
- function physicalColumnName(table: Table, field: string): string;
112
+ function physicalColumnName(table: unknown, field: string): string;
113
113
  function primaryKey(opts: { columns: ColumnHandle[]; name?: string; }): PrimaryKeyDescriptor;
114
114
  function readDatabaseNow(db: TenantDb): Promise<Date>; // Postgres clock; inside a transaction `now()` is the transaction start, so repeated reads agree.
115
115
  function recordEventsOwnedExclusivelyByTenant(db: DbRunner, aggregateType: string, aggregateId: string, tenantId: string): Promise<boolean>;
@@ -35,7 +35,7 @@ function createDecimalField<R extends true | false = false>(config: { precision:
35
35
  function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
36
36
  function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
37
37
  function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & { multiple: true; };
38
- function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
38
+ function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; webhookEvents?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; readGate?: EntityDefinition["readGate"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; namedFilters?: EntityDefinition["namedFilters"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
39
39
  function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): { table: EntityTable; executor: EventStoreExecutor<EntityRow<E>>; };
40
40
  function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
41
41
  function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
@@ -60,6 +60,7 @@ function createTextField<R extends true | false = false>(overrides: Partial<Omit
60
60
  function createTimestampField<R extends true | false = false>(overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TimestampFieldDef & { required: R; }; // UTC instant for events occurring at a specific point in time (createdAt, loginAt, actualPickupAt).
61
61
  function createTzField<R extends true | false = false>(overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TzFieldDef & { required: R; }; // IANA time-zone name (for example, "Europe/Berlin").
62
62
  function createUserConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
63
+ function createWebhookContractResolver(features: FeatureDefinition[]): WebhookContractResolver; // Works on the feature list so a boot check, which has no registry, resolves the same contracts.
63
64
  function declareEscapeHatch(declaration: EscapeHatchDeclaration): void;
64
65
  function dedupeFeatures(features: FeatureDefinition[]): FeatureDefinition[];
65
66
  function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
@@ -95,9 +96,11 @@ function findForbiddenMembershipRole(roles: string[]): string | undefined;
95
96
  function findForbiddenRoleAssignment(actorRoles: string[], assignedRoles: string[], targetCurrentRoles: string[], assignableAppRoles?: AssignableAppRoles): string | undefined;
96
97
  function findOverDeepTransferChain(adjacency: TransferAdjacency, onPath: string[]): string[] | undefined;
97
98
  function findTierResolverUsage(features: FeatureDefinition[]): RegistrarExtensionRegistration | undefined;
99
+ function formatWebhookPayloadIssues(issues: WebhookPayloadIssue[]): string;
98
100
  function from(ref: OwnershipRef, column?: string): FromRule;
99
101
  function getStep(kind: StepKind): StepDef | undefined;
100
102
  function guardTransition<TStates extends string>(transitions: TransitionGraph<TStates>, from: TStates, to: TStates): void; // Asserts a state transition is allowed.
103
+ function handlerDescriptionKey(handlerQn: string): string;
101
104
  function handlerFieldLabelKey(handlerQn: string, fieldName: string): string;
102
105
  function handlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReference | undefined;
103
106
  function handlerTitleKey(handlerQn: string): string;
@@ -131,6 +134,7 @@ function parseQn(value: string): ParsedQn;
131
134
  function parseRefTarget(raw: string, currentFeature: string): ParsedRefTarget;
132
135
  function parseRefTargetEntityName(raw: string): string;
133
136
  function parseTenantId(value: unknown): TenantId | null;
137
+ function parseWebhookPayload(contract: Pick<WebhookEventContract, "payload">, payload: unknown): WebhookPayloadResult; // Delivery sends the returned payload, never the input: zod strips keys the contract does not declare, so a field added to the source row cannot leak into a webhook by accident.
134
138
  function projectAppSchemaForRoles(schema: AppSchema, roles: string[]): AppSchema;
135
139
  function qn(scope: string, type: QnType, name: string): string;
136
140
  function readClaim<T extends ClaimKeyType>(user: SessionUser, handle: ClaimKeyHandle<T>): ClaimKeyJsType<T> | undefined;
@@ -149,6 +153,7 @@ function setFields(table: ProjectionTable, fields: Record<string, unknown> | ((e
149
153
  function stepsPipeline<TPayload = unknown, TData = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>>(closure: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => StepInstance[]): PipelineDef<TPayload, TData, TAwaits>;
150
154
  function templateVariablesToZod(variables: TemplateVariables): z.ZodObject;
151
155
  function tenantChannel(tenantId: TenantId): string;
156
+ function toEntityWebhookPayload(contract: Pick<WebhookEventContract, "payload" | "verb">, event: { aggregateId: string; payload: Readonly<Record<string, unknown>>; }): WebhookPayloadResult; // Maps a stored entity lifecycle event to the contract's payload: the aggregate id joins the event payload, and the contract parse drops every field it does not release, personal ones included, even when the event payload carries them.
152
157
  function toKebab(input: string): string;
153
158
  function typedPayload<TPayload>(event: { type: string; payload: Record<string, unknown>; }, eventDef: EventDef<TPayload>): TPayload;
154
159
  function unwrapWorkflowStepError(error: unknown): unknown;
@@ -157,6 +162,8 @@ function validateAppCustomScreenWriteQns(appRoot: string, knownQns: ReadonlySet<
157
162
  function validateBoot(rawFeatures: FeatureDefinition[], options?: ValidateBootOptions): void; // Validates all feature configurations at boot time.
158
163
  function validateBundledListsOptions(options: unknown): void;
159
164
  function walkStepInstances(steps: StepInstance[], where: string): Generator<StepInstance, void, void>;
165
+ function webhookEventDescriptionKey(webhookEventQn: string): string;
166
+ function webhookEventFieldKey(webhookEventQn: string, fieldPath: string): string; // `fieldPath` is the payload row name as the docs list it, nested fields dotted.
160
167
  function withFormDerivations<Schema extends z.ZodType>(schema: Schema, screen: FormDerivationScreen): z.ZodPreprocess<Schema, unknown>; // Server counterpart of an actionForm's `derive`: recomputes the derived head fields before the schema validates them, so client-sent totals never count.
161
168
  function withResponseData<T>(result: WriteResult<unknown>, data: T): WriteResult<T>; // Override the success-side `data` of a WriteResult while forwarding the failure half untouched.
162
169
  ```
@@ -170,6 +177,7 @@ const BUILT_IN_MEMBERSHIP_ROLES: string[]; // Every membership role the engine r
170
177
  const CODEMOD_PLACEHOLDER_REASON_MARKER: "state the operator use case here";
171
178
  const ConfigScopes: { system: "system"; tenant: "tenant"; user: "user"; };
172
179
  const DEFAULT_CURRENCIES: ["EUR", "USD", "GBP", "CHF", "JPY", "SEK", "NOK", "DKK", "PLN", "CZK", "CAD", "AUD", "NZD", "CNY", "INR"];
180
+ const DEFAULT_LIST_LIMIT: 50;
173
181
  const DEFAULT_LOCALES: ["de", "en", "es"];
174
182
  const DELIVERY_FAILURE_CODES;
175
183
  const DELIVERY_SKIP_REASONS: ["channel_disabled", "preference_disabled", "rate_limited", "no_address", "unsubscribed", "duplicate_idempotency_key"];
@@ -559,6 +567,7 @@ type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy =
559
567
  softDelete?: boolean;
560
568
  tenancy?: T; // "tenant" (default): auto-filtered by every db accessor.
561
569
  systemStream?: boolean; // This aggregate's event stream lives on SYSTEM_TENANT_ID rather than the creator's tenant.
570
+ webhookEvents?: boolean; // Lets token scopes release `<entity>.created/.updated/.deleted` as webhook events.
562
571
  eventVersion?: number; // Schema version stamped on every lifecycle event (default 1, integer 1..999).
563
572
  eventMigrations?: EntityEventMigration[]; // One step per version, fromVersion → fromVersion+1.
564
573
  searchWeight?: number;
@@ -706,6 +715,7 @@ type FeatureDefinition = {
706
715
  referenceData: ReferenceDataDef[];
707
716
  notifications: Readonly<Record<string, NotificationDefinition>>;
708
717
  events: Readonly<Record<string, EventDef>>;
718
+ webhookEvents?: Readonly<Record<string, WebhookEventDef>>; // Public webhook contracts from r.defineWebhookEvent, keyed by QN.
709
719
  eventMigrations: Readonly<Record<string, EventMigrationDef[]>>;
710
720
  configReads: string[];
711
721
  handlerEntityMappings: Readonly<Record<string, string>>;
@@ -763,6 +773,7 @@ type FeatureRegistrar<TFeature extends string = string> = { // `TFeature` is the
763
773
  notification(definition: { name: string; trigger?: { on: NameOrRef; }; recipient?: NotificationRecipientFn; data?: NotificationDataFn; templates?: Readonly<Record<string, NotificationTemplateFn>>; variables?: TemplateVariables; record?: NotificationRecordMapping; template?: Readonly<Record<string, NotificationTemplateBody>>; meta?: Readonly<Record<string, NotificationTemplateMeta>>; localizedTemplate?: () => NotificationLocalizedTemplate; renamedFrom?: string[]; systemOnly?: boolean; unsubscribe?: boolean; tenantTransport?: boolean; }): void;
764
774
  translations(def: TranslationsDef): void;
765
775
  defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: { version?: number; piiFields: EventPiiStance; migrations?: { fromVersion: number; toVersion: number; transform: EventUpcastFn | DeclarativeEventMigration; }[]; }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
776
+ defineWebhookEvent(definition: { name: string; description: string; payload: z.ZodObject; version: number; wireName?: string; }): WebhookEventHandle;
766
777
  readsConfig(...qualifiedKeys: string[]): void;
767
778
  readsConfig(options: { keys: string[]; }): void;
768
779
  referenceData(entity: NameOrRef, data: Record<string, unknown>[], options?: { upsertKey?: string; }): void;
@@ -1458,6 +1469,8 @@ type Registry = {
1458
1469
  getJob(qualifiedName: string): JobDefinition | undefined;
1459
1470
  getAllJobs(): ReadonlyMap<string, JobDefinition>;
1460
1471
  getEvent(qualifiedName: string): EventDef | undefined;
1472
+ getWebhookEventContract(qualifiedName: string): WebhookEventContract | undefined;
1473
+ getWebhookEventContracts(): WebhookEventContract[];
1461
1474
  getEventUpcasters(): ReadonlyMap<string, { currentVersion: number; chain: ReadonlyMap<number, EventUpcastFn>; }>;
1462
1475
  getExtension(name: string): RegistrarExtensionDef | undefined;
1463
1476
  getExtensionUsages(extensionName: string): RegistrarExtensionRegistration[];
@@ -1772,6 +1785,40 @@ type ValidationError = {
1772
1785
  error: string;
1773
1786
  };
1774
1787
  type ValidationHookFn = (data: Readonly<Record<string, unknown>>) => ValidationError[] | null;
1788
+ type WebhookContractResolver = {
1789
+ get(qualifiedName: string): WebhookEventContract | undefined; // Declared contract, or one derived from an entity lifecycle event (`entity.verb`).
1790
+ declared(): WebhookEventContract[]; // Declared contracts only, sorted by QN.
1791
+ };
1792
+ type WebhookEntityVerb = "created" | "updated" | "deleted"; // Lifecycle verbs of an entity that can be released as webhook events.
1793
+ type WebhookEventContract = { // Public payload contract of a webhook event: declared by a feature or derived from an entity.
1794
+ qn: string;
1795
+ wireName: string; // The event name receivers see in the delivered webhook: `wireName` of a declared event, `entity.verb` of a derived one.
1796
+ description: string;
1797
+ payload: z.ZodObject;
1798
+ version: number;
1799
+ origin: "declared" | "entity";
1800
+ entity?: string;
1801
+ verb?: WebhookEntityVerb;
1802
+ };
1803
+ type WebhookEventHandle = {
1804
+ name: string;
1805
+ payload: z.ZodObject;
1806
+ version: number;
1807
+ };
1808
+ type WebhookPayloadIssue = {
1809
+ path: string;
1810
+ message: string;
1811
+ };
1812
+ type WebhookPayloadResult =
1813
+ | {
1814
+ ok: true;
1815
+ payload: Record<string, unknown>;
1816
+ }
1817
+ | {
1818
+ ok: false;
1819
+ issues: WebhookPayloadIssue[];
1820
+ }
1821
+ ;
1775
1822
  type WorkflowDefinition<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>> = { // Workflow definition — the result of defineWorkflow().
1776
1823
  __kind: "workflow";
1777
1824
  name: string;
@@ -21,6 +21,7 @@ function writeFailure(err: KumikoError): WriteFailure;
21
21
 
22
22
  ```ts
23
23
  const FrameworkReasons: { staleState; invalidTransition; fieldAccessDenied; deleteRestricted; featureDisabled; systemIdentitySwitchDenied; identitySwitchDenied; tenantOverrideRequiresSystemAdmin; notifyForeignTenantBroadcast; unsafeAllTenantsDenied; memberResolutionDenied; memberResolutionReadOnly; publicIntakeRequired; irreversibleOperationRequiresHighRisk; instructionFieldWriteRequiresHighRisk; subjectErased; fileRejected; fileViolatesBindTarget };
24
+ const frameworkErrorHttpStatus: { validation_error; feature_disabled; access_denied; unauthenticated; not_found; conflict; version_conflict; precondition_failed; record_locked; idempotent_replay; unique_violation; unprocessable; unconfigured; internal_error; member_read_timeout; rate_limited; rate_limit_unavailable };
24
25
  ```
25
26
 
26
27
  ## Classes
@@ -103,6 +104,7 @@ type FieldIssue = {
103
104
  i18nKey: string;
104
105
  params?: Readonly<Record<string, unknown>>;
105
106
  };
107
+ type FrameworkErrorCode = keyof typeof frameworkErrorHttpStatus;
106
108
  type WriteErrorInfo = {
107
109
  code: string;
108
110
  httpStatus: number;
@@ -3340,6 +3340,7 @@ type ParentVisibilityGateOption = {
3340
3340
  };
3341
3341
  type ParentVisibilityOption = {
3342
3342
  entities: ReadonlyMap<string, EntityDefinition>;
3343
+ readModelEntities?: ReadonlyMap<string, { entity: EntityDefinition; table: SchemaTable; }>;
3343
3344
  canReadEntity?: (entityName: string) => boolean;
3344
3345
  resolveTable?: (entityName: string) => SchemaTable;
3345
3346
  };
@@ -3460,6 +3461,13 @@ type UiHints = {
3460
3461
  recommended?: boolean;
3461
3462
  configurableOptions?: UiHintOption[];
3462
3463
  };
3464
+ type WebhookEventDef = { // What `r.defineWebhookEvent` stores; `qn` is `<feature>:<name>`.
3465
+ qn: string;
3466
+ wireName: string;
3467
+ description: string;
3468
+ payload: z.ZodObject;
3469
+ version: number;
3470
+ };
3463
3471
  ```
3464
3472
 
3465
3473
  ## packages/types/src/field-state-conditions.ts
package/agents/api.md CHANGED
@@ -8,8 +8,8 @@ Format: one line per function or constant, object and options types as property
8
8
 
9
9
  | Import path | File | Exports |
10
10
  | --- | --- | --- |
11
- | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 426 |
12
- | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 25 |
11
+ | `@cosmicdrift/kumiko-framework/engine` | `api/framework-engine.md` | 440 |
12
+ | `@cosmicdrift/kumiko-framework/errors` | `api/framework-errors.md` | 27 |
13
13
  | `@cosmicdrift/kumiko-framework/ui-types` | `api/framework-ui-types.md` | 156 |
14
14
  | `@cosmicdrift/kumiko-framework/db` | `api/framework-db.md` | 151 |
15
15
  | `@cosmicdrift/kumiko-framework/event-store` | `api/framework-event-store.md` | 38 |