@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
@@ -0,0 +1,34 @@
1
+ import type { WebhookEventContract, WebhookEventHandle } from "@cosmicdrift/kumiko-types/feature";
2
+ import { ZodObject } from "zod";
3
+ import type { FeatureBuilderState } from "./feature-builder-state.ts";
4
+ export type WebhookPayloadIssue = {
5
+ readonly path: string;
6
+ readonly message: string;
7
+ };
8
+ export type WebhookPayloadResult = {
9
+ readonly ok: true;
10
+ readonly payload: Record<string, unknown>;
11
+ } | {
12
+ readonly ok: false;
13
+ readonly issues: readonly WebhookPayloadIssue[];
14
+ };
15
+ /** Delivery sends the returned payload, never the input: zod strips keys the contract does not
16
+ * declare, so a field added to the source row cannot leak into a webhook by accident. */
17
+ export declare function parseWebhookPayload(contract: Pick<WebhookEventContract, "payload">, payload: unknown): WebhookPayloadResult;
18
+ /** Maps a stored entity lifecycle event to the contract's payload: the aggregate id joins the
19
+ * event payload, and the contract parse drops every field it does not release, personal ones
20
+ * included, even when the event payload carries them. */
21
+ export declare function toEntityWebhookPayload(contract: Pick<WebhookEventContract, "payload" | "verb">, event: {
22
+ readonly aggregateId: string;
23
+ readonly payload: Readonly<Record<string, unknown>>;
24
+ }): WebhookPayloadResult;
25
+ export declare function formatWebhookPayloadIssues(issues: readonly WebhookPayloadIssue[]): string;
26
+ export declare function buildWebhookEventMethods(state: FeatureBuilderState, featureName: string): {
27
+ defineWebhookEvent(definition: {
28
+ readonly name: string;
29
+ readonly description: string;
30
+ readonly payload: ZodObject;
31
+ readonly version: number;
32
+ readonly wireName?: string;
33
+ }): WebhookEventHandle;
34
+ };
@@ -0,0 +1,71 @@
1
+ import { ZodObject } from "zod";
2
+ import { isObjectArgument, throwObjectArgumentRequired } from "./object-form.js";
3
+ import { isKebabSegment, toKebab } from "./qualified-name.js";
4
+ /** Delivery sends the returned payload, never the input: zod strips keys the contract does not
5
+ * declare, so a field added to the source row cannot leak into a webhook by accident. */
6
+ export function parseWebhookPayload(contract, payload) {
7
+ const parsed = contract.payload.safeParse(payload);
8
+ if (parsed.success)
9
+ return { ok: true, payload: parsed.data };
10
+ return {
11
+ ok: false,
12
+ issues: parsed.error.issues.map((issue) => ({
13
+ path: issue.path.map(String).join("."),
14
+ message: issue.message,
15
+ })),
16
+ };
17
+ }
18
+ /** Maps a stored entity lifecycle event to the contract's payload: the aggregate id joins the
19
+ * event payload, and the contract parse drops every field it does not release, personal ones
20
+ * included, even when the event payload carries them. */
21
+ export function toEntityWebhookPayload(contract, event) {
22
+ const { aggregateId, payload } = event;
23
+ const shaped = contract.verb === "created"
24
+ ? { ...payload, id: aggregateId }
25
+ : { id: aggregateId, changes: payload["changes"], previous: payload["previous"] };
26
+ return parseWebhookPayload(contract, shaped);
27
+ }
28
+ export function formatWebhookPayloadIssues(issues) {
29
+ return issues
30
+ .map((issue) => `${issue.path === "" ? "(root)" : issue.path}: ${issue.message}`)
31
+ .join("; ");
32
+ }
33
+ export function buildWebhookEventMethods(state, featureName) {
34
+ return {
35
+ defineWebhookEvent(definition) {
36
+ if (!isObjectArgument(definition))
37
+ throwObjectArgumentRequired(featureName, "defineWebhookEvent");
38
+ const { name, description, payload, version } = definition;
39
+ const where = `[Feature ${featureName}] defineWebhookEvent`;
40
+ if (typeof name !== "string" || !isKebabSegment(name)) {
41
+ throw new Error(`${where}: name must be kebab-case, got ${JSON.stringify(name)}`);
42
+ }
43
+ if (typeof description !== "string" || description.trim() === "") {
44
+ throw new Error(`${where}("${name}"): description must be a non-empty sentence`);
45
+ }
46
+ if (!(payload instanceof ZodObject)) {
47
+ throw new Error(`${where}("${name}"): payload must be a zod object schema`);
48
+ }
49
+ if (!Number.isInteger(version) || version < 1) {
50
+ throw new Error(`${where}("${name}"): version must be a positive integer`);
51
+ }
52
+ if (definition.wireName !== undefined &&
53
+ (typeof definition.wireName !== "string" || definition.wireName.trim() === "")) {
54
+ throw new Error(`${where}("${name}"): wireName must be a non-empty string`);
55
+ }
56
+ const wireName = definition.wireName?.trim() ?? name;
57
+ const qn = `${toKebab(featureName)}:${name}`;
58
+ if (state.webhookEvents[qn] !== undefined) {
59
+ throw new Error(`${where}("${name}"): already registered in this feature`);
60
+ }
61
+ state.webhookEvents[qn] = {
62
+ qn,
63
+ wireName,
64
+ description: description.trim(),
65
+ payload,
66
+ version,
67
+ };
68
+ return { name: qn, payload, version };
69
+ },
70
+ };
71
+ }
@@ -1,3 +1,4 @@
1
+ import { frameworkErrorHttpStatus } from "./error-codes.js";
1
2
  import { AgentReasons, FrameworkReasons } from "./reasons.js";
2
3
  const DEFAULT_DOCS_BASE_URL = "https://docs.kumiko.rocks";
3
4
  const REASON_SLUG_RE = /^[a-z0-9_.-]+$/;
@@ -6,25 +7,7 @@ const frameworkReasons = new Set([
6
7
  ...Object.values(AgentReasons),
7
8
  ]);
8
9
  // Codes of the built-in error classes: only these have a framework docs page.
9
- const frameworkErrorCodes = new Set([
10
- "validation_error",
11
- "feature_disabled",
12
- "access_denied",
13
- "unauthenticated",
14
- "not_found",
15
- "conflict",
16
- "version_conflict",
17
- "precondition_failed",
18
- "record_locked",
19
- "idempotent_replay",
20
- "unique_violation",
21
- "unprocessable",
22
- "unconfigured",
23
- "internal_error",
24
- "member_read_timeout",
25
- "rate_limited",
26
- "rate_limit_unavailable",
27
- ]);
10
+ const frameworkErrorCodes = new Set(Object.keys(frameworkErrorHttpStatus));
28
11
  function reasonOf(err) {
29
12
  if (!err.details || typeof err.details !== "object")
30
13
  return undefined;
@@ -0,0 +1,20 @@
1
+ export declare const frameworkErrorHttpStatus: {
2
+ readonly validation_error: 400;
3
+ readonly feature_disabled: 403;
4
+ readonly access_denied: 403;
5
+ readonly unauthenticated: 401;
6
+ readonly not_found: 404;
7
+ readonly conflict: 409;
8
+ readonly version_conflict: 409;
9
+ readonly precondition_failed: 409;
10
+ readonly record_locked: 409;
11
+ readonly idempotent_replay: 409;
12
+ readonly unique_violation: 409;
13
+ readonly unprocessable: 422;
14
+ readonly unconfigured: 422;
15
+ readonly internal_error: 500;
16
+ readonly member_read_timeout: 504;
17
+ readonly rate_limited: 429;
18
+ readonly rate_limit_unavailable: 503;
19
+ };
20
+ export type FrameworkErrorCode = keyof typeof frameworkErrorHttpStatus;
@@ -0,0 +1,19 @@
1
+ export const frameworkErrorHttpStatus = {
2
+ validation_error: 400,
3
+ feature_disabled: 403,
4
+ access_denied: 403,
5
+ unauthenticated: 401,
6
+ not_found: 404,
7
+ conflict: 409,
8
+ version_conflict: 409,
9
+ precondition_failed: 409,
10
+ record_locked: 409,
11
+ idempotent_replay: 409,
12
+ unique_violation: 409,
13
+ unprocessable: 422,
14
+ unconfigured: 422,
15
+ internal_error: 500,
16
+ member_read_timeout: 504,
17
+ rate_limited: 429,
18
+ rate_limit_unavailable: 503,
19
+ };
@@ -1,6 +1,8 @@
1
1
  export type { FieldIssue } from "./classes.ts";
2
2
  export { AccessDeniedError, ConflictError, FeatureDisabledError, InternalError, NotFoundError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.ts";
3
3
  export type { ErrorDocsConfig } from "./docs-url.ts";
4
+ export type { FrameworkErrorCode } from "./error-codes.ts";
5
+ export { frameworkErrorHttpStatus } from "./error-codes.ts";
4
6
  export { isKumikoError, KumikoError } from "./kumiko-error.ts";
5
7
  export { FrameworkReasons } from "./reasons.ts";
6
8
  export { subjectErasedConflict } from "./subject-erased.ts";
@@ -1,4 +1,5 @@
1
1
  export { AccessDeniedError, ConflictError, FeatureDisabledError, InternalError, NotFoundError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
2
+ export { frameworkErrorHttpStatus } from "./error-codes.js";
2
3
  export { isKumikoError, KumikoError } from "./kumiko-error.js";
3
4
  export { FrameworkReasons } from "./reasons.js";
4
5
  export { subjectErasedConflict } from "./subject-erased.js";
@@ -14,6 +14,10 @@ export declare const PROJECTION_DETAIL_ENTITY = "__projection-detail__";
14
14
  export declare const WRITE_FORM_SECTION_ENTITY = "__write-form-section__";
15
15
  export declare function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string;
16
16
  export declare function handlerTitleKey(handlerQn: string): string;
17
+ export declare function handlerDescriptionKey(handlerQn: string): string;
18
+ export declare function webhookEventDescriptionKey(webhookEventQn: string): string;
19
+ /** `fieldPath` is the payload row name as the docs list it, nested fields dotted. */
20
+ export declare function webhookEventFieldKey(webhookEventQn: string, fieldPath: string): string;
17
21
  export declare function handlerFieldLabelKey(handlerQn: string, fieldName: string): string;
18
22
  export declare function booleanFacetOptionKeys(featureName: string, entityName: string, fieldName: string): readonly string[];
19
23
  export declare function selectFacetOptionKey(featureName: string, entityName: string, fieldName: string, value: string): string;
@@ -16,6 +16,21 @@ export function fieldLabelKey(featureName, entityName, fieldName) {
16
16
  export function handlerTitleKey(handlerQn) {
17
17
  return `${handlerQn}:title`;
18
18
  }
19
+ export function handlerDescriptionKey(handlerQn) {
20
+ return `${handlerQn}:description`;
21
+ }
22
+ // `feature:name` becomes `feature:webhook:name`, so the keys never collide with handler keys.
23
+ function webhookEventKeyBase(webhookEventQn) {
24
+ const separator = webhookEventQn.indexOf(":");
25
+ return `${webhookEventQn.slice(0, separator)}:webhook:${webhookEventQn.slice(separator + 1)}`;
26
+ }
27
+ export function webhookEventDescriptionKey(webhookEventQn) {
28
+ return `${webhookEventKeyBase(webhookEventQn)}:description`;
29
+ }
30
+ /** `fieldPath` is the payload row name as the docs list it, nested fields dotted. */
31
+ export function webhookEventFieldKey(webhookEventQn, fieldPath) {
32
+ return `${webhookEventKeyBase(webhookEventQn)}:field:${fieldPath}`;
33
+ }
19
34
  export function handlerFieldLabelKey(handlerQn, fieldName) {
20
35
  return `${handlerQn}:field:${fieldName}`;
21
36
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-framework",
3
- "version": "0.411.0",
3
+ "version": "0.412.0",
4
4
  "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
203
203
  "./package.json": "./package.json"
204
204
  },
205
205
  "dependencies": {
206
- "@cosmicdrift/kumiko-types": "0.411.0",
206
+ "@cosmicdrift/kumiko-types": "0.412.0",
207
207
  "bullmq": "^5.81.5",
208
208
  "hono": "^4.13.14",
209
209
  "i18next": "^26.5.12",
@@ -225,7 +225,7 @@
225
225
  }
226
226
  },
227
227
  "devDependencies": {
228
- "@cosmicdrift/kumiko-testing": "0.411.0",
228
+ "@cosmicdrift/kumiko-testing": "0.412.0",
229
229
  "bun-types": "^1.4.4",
230
230
  "fflate": "^0.8.3",
231
231
  "meilisearch": "^0.62.0",
package/src/changes.json CHANGED
@@ -1,4 +1,34 @@
1
1
  [
2
+ {
3
+ "version": "0.412.0",
4
+ "type": "fix",
5
+ "title": "readGate.fileOwner counts read-model entities as file owners",
6
+ "detail": "A document whose file is attached to a projection entity (for example a mail attachment owned by `inbound-message`) was invisible to everyone but the framework system user, because only `r.entity` entities were owner candidates. Read-model entities with a file field now count, with the same rules as entities (no parentRef, no readGate, uuid ids, tenant scope, soft delete) plus two fail-closed conditions: the viewer's roles must pass the access rule of the read model's `<source>:detail` query, and the entity must declare `access.read`, since its queries filter rows by hand and the gate can only reproduce `access.read`. A read model without `access.read` never makes a document visible. `ParentVisibilityOption` has the optional `readModelEntities` map (entity and projection table) for this; `resolveTable`, link and parentRef gates are unchanged."
7
+ },
8
+ {
9
+ "version": "0.412.0",
10
+ "type": "fix",
11
+ "title": "Scaleway Key Manager and Transactional Email listed as active sub-processor",
12
+ "detail": "The `KUMIKO_SUB_PROCESSORS` entry \"Platform key custody (Key Manager) and Transactional Email Delivery\" moves from `status: \"planned\"` to `\"active\"` (`addedAt` 2026-11-01), so `getActiveSubProcessors()` and the generated privacy texts name it. Transactional mail of the Kumiko apps now goes through Scaleway TEM; the Brevo entry stays until that account is closed, because Brevo still holds the logs of mail it sent."
13
+ },
14
+ {
15
+ "version": "0.412.0",
16
+ "type": "improvement",
17
+ "title": "entity webhook events need `webhookEvents: true` on the entity",
18
+ "detail": "`<entity>.created`, `.updated` and `.deleted` get a derived webhook contract only for entities that set `webhookEvents: true`, so bundle system entities such as `config-value` or `tenant-secret` can never be released through a token scope. Without the flag the entity has no contract and a scope that lists its events fails at boot, with a message naming the entity and the option. Add `webhookEvents: true` to every entity whose events a scope lists; the field exclusions still apply."
19
+ },
20
+ {
21
+ "version": "0.412.0",
22
+ "type": "improvement",
23
+ "title": "r.defineWebhookEvent takes an optional wireName",
24
+ "detail": "`wireName` is the event name receivers see in the delivered webhook, for example `incident.created` for the contract `publicstatus:incident-created`. It defaults to the unqualified `name`, must not be empty, and is `entity.verb` for derived entity contracts. `WebhookEventContract` and `WebhookEventDef` carry it."
25
+ },
26
+ {
27
+ "version": "0.412.0",
28
+ "type": "improvement",
29
+ "title": "r.defineWebhookEvent declares a public webhook event contract",
30
+ "detail": "`r.defineWebhookEvent({ name, description, payload, version })` registers a contract under `<feature>:<name>`, separate from `r.defineEvent`, so an internal event is never released by accident. `registry.getWebhookEventContract(qn)` also returns the contract derived for an entity event (`ticket.created`, `ticket.updated`, `ticket.deleted`): every payload carries the entity `id`, created adds the releasable fields, updated adds `changes` and `previous`, deleted adds `previous`; `toEntityWebhookPayload(contract, event)` maps a stored entity event (aggregate id plus payload) to that shape and drops everything the contract does not release; personal fields, the CRUD `excludedFields`, money and located timestamp fields and encrypted, write-only or sensitive text fields are left out. `registry.getWebhookEventContracts()` lists the declared ones sorted by name. `parseWebhookPayload(contract, payload)` validates a payload and strips unknown keys. New exports: `WebhookEventContract`, `WebhookEventHandle`, `parseWebhookPayload`, `toEntityWebhookPayload`."
31
+ },
2
32
  {
3
33
  "version": "0.411.0",
4
34
  "type": "fix",