@cosmicdrift/kumiko-samples 0.412.0 → 0.413.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 (132) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +13 -13
  3. package/packages/bundled-features/src/admin-shell/feature.ts +1 -1
  4. package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +1 -1
  5. package/packages/bundled-features/src/auth-email-password/boot-rules.ts +9 -0
  6. package/packages/bundled-features/src/auth-email-password/feature.ts +6 -19
  7. package/packages/bundled-features/src/auth-email-password/validate-options.ts +20 -0
  8. package/packages/bundled-features/src/billing-foundation/boot-rules.ts +26 -0
  9. package/packages/bundled-features/src/billing-foundation/validate-options.ts +59 -46
  10. package/packages/bundled-features/src/cap-overview/boot-rules.ts +14 -0
  11. package/packages/bundled-features/src/cap-overview/feature.ts +12 -5
  12. package/packages/bundled-features/src/documents/boot-rules.ts +14 -0
  13. package/packages/bundled-features/src/documents/feature.ts +8 -4
  14. package/packages/bundled-features/src/file-derivatives/boot-rules.ts +9 -0
  15. package/packages/bundled-features/src/file-derivatives/feature.ts +6 -3
  16. package/packages/bundled-features/src/folders/boot-rules.ts +9 -0
  17. package/packages/bundled-features/src/folders/feature.ts +6 -3
  18. package/packages/bundled-features/src/helpdesk/boot-rules.ts +9 -0
  19. package/packages/bundled-features/src/{contact → helpdesk}/challenge.ts +2 -2
  20. package/packages/bundled-features/src/{contact → helpdesk}/changes.json +6 -0
  21. package/packages/bundled-features/src/{contact/client/contact-client-source.ts → helpdesk/client/helpdesk-client-source.ts} +4 -4
  22. package/packages/bundled-features/src/helpdesk/client/helpdesk-website-client.ts +29 -0
  23. package/packages/bundled-features/src/helpdesk/client/index.ts +9 -0
  24. package/packages/bundled-features/src/{contact → helpdesk}/entity.ts +35 -31
  25. package/packages/bundled-features/src/{contact → helpdesk}/feature.ts +56 -52
  26. package/packages/bundled-features/src/{contact → helpdesk}/handlers/attempts.ts +3 -3
  27. package/packages/bundled-features/src/{contact → helpdesk}/handlers/challenge.query.ts +10 -10
  28. package/packages/bundled-features/src/{contact → helpdesk}/handlers/forward-request.write.ts +25 -23
  29. package/packages/bundled-features/src/{contact → helpdesk}/handlers/mark-done.write.ts +11 -11
  30. package/packages/bundled-features/src/{contact → helpdesk}/handlers/notify-reporter-in-app.write.ts +14 -14
  31. package/packages/bundled-features/src/{contact → helpdesk}/handlers/open-count.query.ts +4 -4
  32. package/packages/bundled-features/src/{contact → helpdesk}/handlers/open-count.ts +2 -2
  33. package/packages/bundled-features/src/{contact → helpdesk}/handlers/replies.query.ts +6 -6
  34. package/packages/bundled-features/src/{contact → helpdesk}/handlers/reply.write.ts +30 -30
  35. package/packages/bundled-features/src/{contact → helpdesk}/handlers/report.write.ts +29 -29
  36. package/packages/bundled-features/src/{contact → helpdesk}/handlers/request-delivery.query.ts +40 -40
  37. package/packages/bundled-features/src/{contact → helpdesk}/handlers/request-detail.query.ts +15 -15
  38. package/packages/bundled-features/src/{contact → helpdesk}/handlers/request-list.query.ts +2 -2
  39. package/packages/bundled-features/src/{contact → helpdesk}/handlers/send-reply-mail.write.ts +24 -24
  40. package/packages/bundled-features/src/{contact → helpdesk}/handlers/send-test.write.ts +18 -14
  41. package/packages/bundled-features/src/{contact → helpdesk}/handlers/submit.write.ts +32 -31
  42. package/packages/bundled-features/src/{contact → helpdesk}/handlers/take-over-uploads.ts +5 -5
  43. package/packages/bundled-features/src/{contact → helpdesk}/i18n.ts +78 -75
  44. package/packages/bundled-features/src/helpdesk/index.ts +29 -0
  45. package/packages/bundled-features/src/{contact → helpdesk}/lib.ts +32 -28
  46. package/packages/bundled-features/src/{contact → helpdesk}/mail.ts +56 -56
  47. package/packages/bundled-features/src/{contact → helpdesk}/options.ts +18 -16
  48. package/packages/bundled-features/src/helpdesk/panels.ts +28 -0
  49. package/packages/bundled-features/src/{contact → helpdesk}/payloads.ts +33 -33
  50. package/packages/bundled-features/src/{contact → helpdesk}/screens.ts +104 -104
  51. package/packages/bundled-features/src/{contact → helpdesk}/subject.ts +3 -3
  52. package/packages/bundled-features/src/{contact → helpdesk}/user-data-hooks.ts +17 -17
  53. package/packages/bundled-features/src/helpdesk/web/constants.ts +160 -0
  54. package/packages/bundled-features/src/helpdesk/web/index.ts +29 -0
  55. package/packages/bundled-features/src/host-routing/boot-rules.ts +27 -0
  56. package/packages/bundled-features/src/host-routing/validate-options.ts +36 -27
  57. package/packages/bundled-features/src/jobs/boot-rules.ts +9 -0
  58. package/packages/bundled-features/src/jobs/feature.ts +9 -4
  59. package/packages/bundled-features/src/legal-pages/boot-rules.ts +19 -0
  60. package/packages/bundled-features/src/legal-pages/feature.ts +6 -3
  61. package/packages/bundled-features/src/legal-pages/lib/validate-routes.ts +11 -5
  62. package/packages/bundled-features/src/metrics/boot-rules.ts +15 -0
  63. package/packages/bundled-features/src/metrics/validate.ts +8 -2
  64. package/packages/bundled-features/src/notes-history/boot-rules.ts +9 -0
  65. package/packages/bundled-features/src/notes-history/feature.ts +6 -3
  66. package/packages/bundled-features/src/personal-access-tokens/boot-rules.ts +9 -0
  67. package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +6 -3
  68. package/packages/bundled-features/src/presence/boot-rules.ts +9 -0
  69. package/packages/bundled-features/src/presence/options.ts +5 -1
  70. package/packages/bundled-features/src/readiness/boot-rules.ts +14 -0
  71. package/packages/bundled-features/src/readiness/probe-boot-check.ts +8 -6
  72. package/packages/bundled-features/src/shared/assert-no-where-rule-in-ownership-write.ts +6 -4
  73. package/packages/bundled-features/src/shared/boot-rules.ts +9 -0
  74. package/packages/bundled-features/src/subscription-mollie/boot-rules.ts +19 -0
  75. package/packages/bundled-features/src/subscription-mollie/feature.ts +18 -10
  76. package/packages/bundled-features/src/tags/boot-rules.ts +9 -0
  77. package/packages/bundled-features/src/tags/feature.ts +6 -3
  78. package/packages/bundled-features/src/template-resolver/boot-rules.ts +19 -0
  79. package/packages/bundled-features/src/template-resolver/feature.ts +14 -10
  80. package/packages/bundled-features/src/tenant/boot-rules.ts +9 -0
  81. package/packages/bundled-features/src/tenant/feature.ts +5 -3
  82. package/samples/apps/marketing-demo/README.md +1 -1
  83. package/samples/apps/marketing-demo/playwright.config.ts +1 -1
  84. package/samples/apps/marketing-demo/src/app/client.tsx +3 -3
  85. package/samples/apps/marketing-demo/src/app/seed-data.ts +1 -1
  86. package/samples/apps/marketing-demo/src/app/seed.ts +4 -4
  87. package/samples/apps/marketing-demo/src/app/server.ts +3 -3
  88. package/samples/apps/marketing-demo/src/features/{helpdesk → ticketing}/feature.ts +15 -12
  89. package/samples/apps/marketing-demo/src/features/ticketing/i18n.ts +100 -0
  90. package/samples/apps/marketing-demo/src/features/{helpdesk → ticketing}/schema/ticket.ts +4 -4
  91. package/samples/apps/marketing-demo/src/features/ticketing/web/index.ts +7 -0
  92. package/samples/apps/use-all-bundled/feature-manifest.json +67 -67
  93. package/samples/apps/use-all-bundled/kumiko/migrations/0064_helpdesk-rename.rebuild.json +4 -0
  94. package/samples/apps/use-all-bundled/package.json +1 -1
  95. package/samples/apps/use-all-bundled/src/app/client.tsx +1 -1
  96. package/samples/apps/use-all-bundled/src/app/screens-feature.ts +10 -10
  97. package/samples/apps/use-all-bundled/src/run-config.ts +6 -6
  98. package/samples/recipes/api-docs/README.md +3 -3
  99. package/samples/recipes/api-docs/api-docs/de/events.md +14 -14
  100. package/samples/recipes/api-docs/api-docs/de/overview.md +3 -3
  101. package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +10 -10
  102. package/samples/recipes/api-docs/api-docs/de/tokens.md +4 -4
  103. package/samples/recipes/api-docs/api-docs/en/events.md +14 -14
  104. package/samples/recipes/api-docs/api-docs/en/overview.md +3 -3
  105. package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +10 -10
  106. package/samples/recipes/api-docs/api-docs/en/tokens.md +4 -4
  107. package/samples/recipes/api-docs/api-docs/index.json +22 -22
  108. package/samples/recipes/api-docs/api-docs/openapi.json +67 -67
  109. package/samples/recipes/api-docs/api-examples/ticket-close.json +1 -1
  110. package/samples/recipes/api-docs/api-examples/ticket-create.json +1 -1
  111. package/samples/recipes/api-docs/api-examples/ticket-detail.json +1 -1
  112. package/samples/recipes/api-docs/api-examples/ticket-list.json +1 -1
  113. package/samples/recipes/api-docs/api-examples/ticket-update.json +1 -1
  114. package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +1 -1
  115. package/samples/recipes/api-docs/kumiko.config.ts +4 -4
  116. package/samples/recipes/api-docs/src/feature.ts +44 -44
  117. package/samples/recipes/golden-path/src/feature.ts +1 -1
  118. package/samples/recipes/{contact → helpdesk}/README.md +16 -16
  119. package/samples/recipes/{contact → helpdesk}/package.json +2 -2
  120. package/samples/recipes/{contact → helpdesk}/src/feature.ts +6 -6
  121. package/packages/bundled-features/src/contact/client/contact-website-client.ts +0 -29
  122. package/packages/bundled-features/src/contact/client/index.ts +0 -9
  123. package/packages/bundled-features/src/contact/index.ts +0 -29
  124. package/packages/bundled-features/src/contact/panels.ts +0 -28
  125. package/packages/bundled-features/src/contact/web/constants.ts +0 -160
  126. package/packages/bundled-features/src/contact/web/index.ts +0 -29
  127. package/samples/apps/marketing-demo/src/features/helpdesk/i18n.ts +0 -100
  128. package/samples/apps/marketing-demo/src/features/helpdesk/web/index.ts +0 -7
  129. /package/packages/bundled-features/src/{contact → helpdesk}/handlers/access.ts +0 -0
  130. /package/packages/bundled-features/src/{contact → helpdesk}/pow.ts +0 -0
  131. /package/packages/bundled-features/src/{contact → helpdesk}/user-agent.ts +0 -0
  132. /package/samples/apps/marketing-demo/src/features/{helpdesk → ticketing}/schema/index.ts +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-samples",
3
- "version": "0.412.0",
3
+ "version": "0.413.0",
4
4
  "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-bundled-features",
3
- "version": "0.412.0",
3
+ "version": "0.413.0",
4
4
  "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -157,10 +157,10 @@
157
157
  "./legal-pages": "./src/legal-pages/index.ts",
158
158
  "./legal-pages/constants": "./src/legal-pages/web/constants.ts",
159
159
  "./legal-pages/web": "./src/legal-pages/web/index.ts",
160
- "./contact": "./src/contact/index.ts",
160
+ "./helpdesk": "./src/helpdesk/index.ts",
161
161
  "./presence": "./src/presence/index.ts",
162
- "./contact/web": "./src/contact/web/index.ts",
163
- "./contact/client": "./src/contact/client/index.ts",
162
+ "./helpdesk/web": "./src/helpdesk/web/index.ts",
163
+ "./helpdesk/client": "./src/helpdesk/client/index.ts",
164
164
  "./waitlist": "./src/waitlist/index.ts",
165
165
  "./waitlist/static-submit": "./src/waitlist/static-submit.ts",
166
166
  "./page-render": "./src/page-render/index.ts",
@@ -747,21 +747,21 @@
747
747
  "types": "./dist/legal-pages/web/index.d.ts",
748
748
  "default": "./dist/legal-pages/web/index.js"
749
749
  },
750
- "./contact": {
751
- "types": "./dist/contact/index.d.ts",
752
- "default": "./dist/contact/index.js"
750
+ "./helpdesk": {
751
+ "types": "./dist/helpdesk/index.d.ts",
752
+ "default": "./dist/helpdesk/index.js"
753
753
  },
754
754
  "./presence": {
755
755
  "types": "./dist/presence/index.d.ts",
756
756
  "default": "./dist/presence/index.js"
757
757
  },
758
- "./contact/web": {
759
- "types": "./dist/contact/web/index.d.ts",
760
- "default": "./dist/contact/web/index.js"
758
+ "./helpdesk/web": {
759
+ "types": "./dist/helpdesk/web/index.d.ts",
760
+ "default": "./dist/helpdesk/web/index.js"
761
761
  },
762
- "./contact/client": {
763
- "types": "./dist/contact/client/index.d.ts",
764
- "default": "./dist/contact/client/index.js"
762
+ "./helpdesk/client": {
763
+ "types": "./dist/helpdesk/client/index.d.ts",
764
+ "default": "./dist/helpdesk/client/index.js"
765
765
  },
766
766
  "./waitlist": {
767
767
  "types": "./dist/waitlist/index.d.ts",
@@ -49,7 +49,7 @@ export type CreateAdminShellOptions = {
49
49
  * createMetricsFeature / createSystemMetricsFeature. Panels exist only for
50
50
  * ids in this list. Default DEFAULT_METRICS. */
51
51
  readonly metrics?: readonly MetricDefinition[];
52
- /** Panels appended to the platform overview, for tiles a mounted feature owns (e.g. the contact inbox count). */
52
+ /** Panels appended to the platform overview, for tiles a mounted feature owns (e.g. the helpdesk inbox count). */
53
53
  readonly extraPlatformPanels?: readonly DashboardPanelDefinition[];
54
54
  };
55
55
 
@@ -1,7 +1,7 @@
1
1
  const QN_TYPE_SEGMENTS = new Set(["query", "write"]);
2
2
  const HEADING_SEPARATOR = ": ";
3
3
 
4
- /** `helpdesk:write:ticket:close` becomes ["ticket", "close"]: the feature prefix and
4
+ /** `ticketing:write:ticket:close` becomes ["ticket", "close"]: the feature prefix and
5
5
  * the `query`/`write` kind are noise inside a page that already names both. */
6
6
  function tailSegments(qn: string): readonly string[] {
7
7
  const segments = qn.split(":");
@@ -0,0 +1,9 @@
1
+ import type { BootRuleTable } from "@cosmicdrift/kumiko-framework/engine";
2
+
3
+ export const AUTH_EMAIL_PASSWORD_BOOT_RULES = {
4
+ hmacSecretTooShort: {
5
+ id: "auth-email-password/hmac-secret-too-short",
6
+ summary: "Each configured token hmacSecret is at least the minimum length.",
7
+ fix: "Pass an hmacSecret of at least the minimum length.",
8
+ },
9
+ } as const satisfies BootRuleTable;
@@ -37,7 +37,7 @@ import {
37
37
  INVITE_MAIL_VARIABLES,
38
38
  sendsMagicLinkMail,
39
39
  } from "./mail-notifications.ts";
40
- import { MIN_HMAC_SECRET_LENGTH } from "./web/constants.ts";
40
+ import { assertSignedTokenSecretsLongEnough } from "./validate-options.ts";
41
41
  import { AUTH_EMAIL_PASSWORD_MAIL_I18N } from "./web/mail-i18n.ts";
42
42
 
43
43
  /**
@@ -154,24 +154,11 @@ export type AuthEmailPasswordOptions = {
154
154
  export function createAuthEmailPasswordFeature(
155
155
  opts: AuthEmailPasswordOptions = {},
156
156
  ): FeatureWithEnvSchema<FeatureDefinition, typeof authEmailPasswordEnvSchema.shape> {
157
- // ≥32 chars, symmetric to the JWT_SECRET env check: a short HMAC secret
158
- // makes reset/verify tokens forgeable — that's account takeover, so the
159
- // factory fails fast instead of trusting the caller.
160
- if (opts.passwordReset && opts.passwordReset.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
161
- throw new Error(
162
- `[auth-email-password] passwordReset.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
163
- );
164
- }
165
- if (opts.emailVerification && opts.emailVerification.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
166
- throw new Error(
167
- `[auth-email-password] emailVerification.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
168
- );
169
- }
170
- if (opts.accountUnlock && opts.accountUnlock.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
171
- throw new Error(
172
- `[auth-email-password] accountUnlock.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
173
- );
174
- }
157
+ assertSignedTokenSecretsLongEnough({
158
+ passwordReset: opts.passwordReset,
159
+ emailVerification: opts.emailVerification,
160
+ accountUnlock: opts.accountUnlock,
161
+ });
175
162
 
176
163
  const strictVerification =
177
164
  opts.emailVerification !== undefined && (opts.emailVerification.mode ?? "strict") === "strict";
@@ -0,0 +1,20 @@
1
+ import { bootRuleError } from "@cosmicdrift/kumiko-framework/engine";
2
+ import { AUTH_EMAIL_PASSWORD_BOOT_RULES } from "./boot-rules.ts";
3
+ import { MIN_HMAC_SECRET_LENGTH } from "./web/constants.ts";
4
+
5
+ type SignedTokenFlowOptions = { readonly hmacSecret: string } | undefined;
6
+
7
+ // ≥32 chars, symmetric to the JWT_SECRET env check: a short HMAC secret
8
+ // makes reset/verify tokens forgeable — that's account takeover, so the
9
+ // factory fails fast instead of trusting the caller.
10
+ export function assertSignedTokenSecretsLongEnough(
11
+ signedTokenFlows: Readonly<Record<string, SignedTokenFlowOptions>>,
12
+ ): void {
13
+ for (const [optionName, flow] of Object.entries(signedTokenFlows)) {
14
+ if (flow && flow.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
15
+ throw bootRuleError(AUTH_EMAIL_PASSWORD_BOOT_RULES.hmacSecretTooShort, {
16
+ message: `[auth-email-password] ${optionName}.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
17
+ });
18
+ }
19
+ }
20
+ }
@@ -0,0 +1,26 @@
1
+ import type { BootRuleTable } from "@cosmicdrift/kumiko-framework/engine";
2
+
3
+ export const BILLING_FOUNDATION_BOOT_RULES = {
4
+ consumerProtectionInvalid: {
5
+ id: "billing-foundation/consumer-protection-invalid",
6
+ summary:
7
+ "consumerProtection options carry non-empty texts, a valid operator email, a valid termination scope and valid legal links.",
8
+ fix: "Fix the consumerProtection option named in the error message.",
9
+ },
10
+ baseUrlInvalid: {
11
+ id: "billing-foundation/base-url-invalid",
12
+ summary: "baseUrl is a parseable absolute http or https URL.",
13
+ fix: "Pass an absolute http(s) URL as baseUrl.",
14
+ },
15
+ baseUrlRequired: {
16
+ id: "billing-foundation/base-url-required",
17
+ summary: "baseUrl is set whenever consumerProtection or a catalog is configured.",
18
+ fix: "Pass baseUrl, checkout redirect URLs are built from it.",
19
+ },
20
+ catalogInvalid: {
21
+ id: "billing-foundation/catalog-invalid",
22
+ summary:
23
+ "The catalog declares unique plans, root-relative paths, view roles and a valid contact card.",
24
+ fix: "Fix the catalog option named in the error message.",
25
+ },
26
+ } as const satisfies BootRuleTable;
@@ -1,3 +1,5 @@
1
+ import { bootRuleError } from "@cosmicdrift/kumiko-framework/engine";
2
+ import { BILLING_FOUNDATION_BOOT_RULES } from "./boot-rules.ts";
1
3
  // Feature-definition-time validation for createBillingFoundationFeature's
2
4
  // options — split out of feature.ts to keep that file at registration-only
3
5
  // concerns (app-feature-structure guard's 300-line budget). Internal — not
@@ -37,9 +39,9 @@ function validateProviderTexts(cp: ConsumerProtectionOptions): void {
37
39
  if (text === undefined) continue;
38
40
  for (const locale of ["de", "en"] as const) {
39
41
  if (!text[locale]?.trim()) {
40
- throw new Error(
41
- `createBillingFoundationFeature: consumerProtection.providerTexts.${providerName}.${textName} needs a non-empty "${locale}" entry.`,
42
- );
42
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
43
+ message: `createBillingFoundationFeature: consumerProtection.providerTexts.${providerName}.${textName} needs a non-empty "${locale}" entry.`,
44
+ });
43
45
  }
44
46
  }
45
47
  }
@@ -48,30 +50,33 @@ function validateProviderTexts(cp: ConsumerProtectionOptions): void {
48
50
 
49
51
  function validateConsumerProtection(cp: ConsumerProtectionOptions): void {
50
52
  if (cp.termsTextBlock.trim() === "") {
51
- throw new Error("createBillingFoundationFeature: consumerProtection.termsTextBlock is empty.");
53
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
54
+ message: "createBillingFoundationFeature: consumerProtection.termsTextBlock is empty.",
55
+ });
52
56
  }
53
57
  for (const locale of ["de", "en"] as const) {
54
58
  if (!cp.vatNote[locale]?.trim()) {
55
- throw new Error(
56
- `createBillingFoundationFeature: consumerProtection.vatNote needs a non-empty "${locale}" entry.`,
57
- );
59
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
60
+ message: `createBillingFoundationFeature: consumerProtection.vatNote needs a non-empty "${locale}" entry.`,
61
+ });
58
62
  }
59
63
  }
60
64
  validateProviderTexts(cp);
61
65
  if (!z.email().safeParse(cp.operatorEmail).success) {
62
- throw new Error(
63
- `createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`,
64
- );
66
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
67
+ message: `createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`,
68
+ });
65
69
  }
66
70
  if (cp.oneOffItemLabel !== undefined && typeof cp.oneOffItemLabel !== "function") {
67
- throw new Error(
68
- "createBillingFoundationFeature: consumerProtection.oneOffItemLabel must be a function.",
69
- );
71
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
72
+ message:
73
+ "createBillingFoundationFeature: consumerProtection.oneOffItemLabel must be a function.",
74
+ });
70
75
  }
71
76
  if (cp.terminationScope !== undefined && !isTerminationScope(cp.terminationScope)) {
72
- throw new Error(
73
- `createBillingFoundationFeature: consumerProtection.terminationScope "${String(cp.terminationScope)}" must be one of ${TERMINATION_SCOPES.map((scope) => `"${scope}"`).join(", ")}.`,
74
- );
77
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
78
+ message: `createBillingFoundationFeature: consumerProtection.terminationScope "${String(cp.terminationScope)}" must be one of ${TERMINATION_SCOPES.map((scope) => `"${scope}"`).join(", ")}.`,
79
+ });
75
80
  }
76
81
  if (isLegalLinkSet(cp.legalLinks)) {
77
82
  validateLegalLinkSet(cp.legalLinks, "legalLinks");
@@ -86,9 +91,9 @@ function validatePerLocaleLegalLinks(
86
91
  for (const locale of CONSENT_LOCALES) {
87
92
  const set = legalLinks[locale];
88
93
  if (!set) {
89
- throw new Error(
90
- `createBillingFoundationFeature: consumerProtection.legalLinks needs a "${locale}" entry when given per locale.`,
91
- );
94
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
95
+ message: `createBillingFoundationFeature: consumerProtection.legalLinks needs a "${locale}" entry when given per locale.`,
96
+ });
92
97
  }
93
98
  validateLegalLinkSet(set, `legalLinks.${locale}`);
94
99
  }
@@ -99,9 +104,9 @@ function validateLegalLinkSet(set: LegalLinkSet, path: string): void {
99
104
  // skip: refund is optional
100
105
  if (key === "refund" && link === undefined) continue;
101
106
  if (typeof link !== "string" || !isRootRelativeOrHttpsUrl(link)) {
102
- throw new Error(
103
- `createBillingFoundationFeature: consumerProtection.${path}.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`,
104
- );
107
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.consumerProtectionInvalid, {
108
+ message: `createBillingFoundationFeature: consumerProtection.${path}.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`,
109
+ });
105
110
  }
106
111
  }
107
112
  }
@@ -109,13 +114,15 @@ function validateLegalLinkSet(set: LegalLinkSet, path: string): void {
109
114
  function validateContactCard(contact: BillingPlanContactCard): void {
110
115
  for (const key of ["labelKey", "actionLabelKey"] as const) {
111
116
  if (contact[key].trim() === "") {
112
- throw new Error(`createBillingFoundationFeature: catalog.contact.${key} must not be empty.`);
117
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.catalogInvalid, {
118
+ message: `createBillingFoundationFeature: catalog.contact.${key} must not be empty.`,
119
+ });
113
120
  }
114
121
  }
115
122
  if (!isContactCardHref(contact.href)) {
116
- throw new Error(
117
- `createBillingFoundationFeature: catalog.contact.href "${contact.href}" must be an absolute https: or mailto: URL.`,
118
- );
123
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.catalogInvalid, {
124
+ message: `createBillingFoundationFeature: catalog.contact.href "${contact.href}" must be an absolute https: or mailto: URL.`,
125
+ });
119
126
  }
120
127
  }
121
128
 
@@ -124,14 +131,14 @@ function validateBaseUrl(baseUrl: string): void {
124
131
  try {
125
132
  parsed = new URL(baseUrl);
126
133
  } catch {
127
- throw new Error(
128
- `createBillingFoundationFeature: baseUrl "${baseUrl}" is not a parseable absolute URL.`,
129
- );
134
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.baseUrlInvalid, {
135
+ message: `createBillingFoundationFeature: baseUrl "${baseUrl}" is not a parseable absolute URL.`,
136
+ });
130
137
  }
131
138
  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
132
- throw new Error(
133
- `createBillingFoundationFeature: baseUrl "${baseUrl}" must use http or https (parsed protocol "${parsed.protocol}").`,
134
- );
139
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.baseUrlInvalid, {
140
+ message: `createBillingFoundationFeature: baseUrl "${baseUrl}" must use http or https (parsed protocol "${parsed.protocol}").`,
141
+ });
135
142
  }
136
143
  }
137
144
 
@@ -143,9 +150,10 @@ export function validateOptions(options: BillingFoundationOptions): void {
143
150
  if (options.baseUrl !== undefined) validateBaseUrl(options.baseUrl);
144
151
  if (options.consumerProtection) {
145
152
  if (options.baseUrl === undefined) {
146
- throw new Error(
147
- "createBillingFoundationFeature: consumerProtection requires baseUrl (checkout redirect URLs are built from it).",
148
- );
153
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.baseUrlRequired, {
154
+ message:
155
+ "createBillingFoundationFeature: consumerProtection requires baseUrl (checkout redirect URLs are built from it).",
156
+ });
149
157
  }
150
158
  validateConsumerProtection(options.consumerProtection);
151
159
  }
@@ -153,19 +161,22 @@ export function validateOptions(options: BillingFoundationOptions): void {
153
161
  // skip: no catalog configured, nothing more to validate.
154
162
  if (!catalog) return;
155
163
  if (options.baseUrl === undefined) {
156
- throw new Error(
157
- "createBillingFoundationFeature: catalog requires baseUrl (plan checkouts need it to build success/cancel/return URLs).",
158
- );
164
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.baseUrlRequired, {
165
+ message:
166
+ "createBillingFoundationFeature: catalog requires baseUrl (plan checkouts need it to build success/cancel/return URLs).",
167
+ });
159
168
  }
160
169
  if (catalog.plans.length === 0) {
161
- throw new Error("createBillingFoundationFeature: catalog.plans must not be empty.");
170
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.catalogInvalid, {
171
+ message: "createBillingFoundationFeature: catalog.plans must not be empty.",
172
+ });
162
173
  }
163
174
  const seen = new Set<string>();
164
175
  for (const tier of catalog.plans) {
165
176
  if (seen.has(tier)) {
166
- throw new Error(
167
- `createBillingFoundationFeature: catalog.plans has a duplicate tier "${tier}".`,
168
- );
177
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.catalogInvalid, {
178
+ message: `createBillingFoundationFeature: catalog.plans has a duplicate tier "${tier}".`,
179
+ });
169
180
  }
170
181
  seen.add(tier);
171
182
  }
@@ -175,13 +186,15 @@ export function validateOptions(options: BillingFoundationOptions): void {
175
186
  ["returnPath", catalog.returnPath],
176
187
  ] as const) {
177
188
  if (path !== undefined && !isRootRelativePath(path)) {
178
- throw new Error(
179
- `createBillingFoundationFeature: catalog.${key} "${path}" must start with "/" and not "//".`,
180
- );
189
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.catalogInvalid, {
190
+ message: `createBillingFoundationFeature: catalog.${key} "${path}" must start with "/" and not "//".`,
191
+ });
181
192
  }
182
193
  }
183
194
  if (catalog.viewRoles.length === 0) {
184
- throw new Error("createBillingFoundationFeature: catalog.viewRoles must not be empty.");
195
+ throw bootRuleError(BILLING_FOUNDATION_BOOT_RULES.catalogInvalid, {
196
+ message: "createBillingFoundationFeature: catalog.viewRoles must not be empty.",
197
+ });
185
198
  }
186
199
  if (catalog.contact !== undefined) validateContactCard(catalog.contact);
187
200
  }
@@ -0,0 +1,14 @@
1
+ import type { BootRuleTable } from "@cosmicdrift/kumiko-framework/engine";
2
+
3
+ export const CAP_OVERVIEW_BOOT_RULES = {
4
+ emptyCaps: {
5
+ id: "cap-overview/empty-caps",
6
+ summary: "createCapOverviewFeature receives at least one cap.",
7
+ fix: "Pass a non-empty caps list.",
8
+ },
9
+ unknownListCap: {
10
+ id: "cap-overview/unknown-list-cap",
11
+ summary: "listCaps only references cap ids declared in caps.",
12
+ fix: "Use ids from caps in listCaps.",
13
+ },
14
+ } as const satisfies BootRuleTable;
@@ -15,8 +15,13 @@
15
15
  // - No nav wiring — a separate cut adds `r.nav(...)` entries.
16
16
  //
17
17
  // **Boot-Dependencies:** tenant, tier-engine, billing-foundation.
18
- import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
18
+ import {
19
+ bootRuleError,
20
+ defineFeature,
21
+ type FeatureDefinition,
22
+ } from "@cosmicdrift/kumiko-framework/engine";
19
23
  import { resolveCapUsageRoles } from "./access.ts";
24
+ import { CAP_OVERVIEW_BOOT_RULES } from "./boot-rules.ts";
20
25
  import { createCapsUsageQuery } from "./handlers/caps-usage.query.ts";
21
26
  import { createTenantCapsListQuery } from "./handlers/tenant-caps-list.query.ts";
22
27
  import { tenantOptionsQuery } from "./handlers/tenant-options.query.ts";
@@ -47,16 +52,18 @@ export type CreateCapOverviewOptions = {
47
52
 
48
53
  export function createCapOverviewFeature(opts: CreateCapOverviewOptions): FeatureDefinition {
49
54
  if (opts.caps.length === 0) {
50
- throw new Error("createCapOverviewFeature: `caps` must not be empty.");
55
+ throw bootRuleError(CAP_OVERVIEW_BOOT_RULES.emptyCaps, {
56
+ message: "createCapOverviewFeature: `caps` must not be empty.",
57
+ });
51
58
  }
52
59
  const usageRoles = resolveCapUsageRoles(opts.usageVisibleTo);
53
60
  const capIds = new Set(opts.caps.map((cap) => cap.id));
54
61
  const listCaps = opts.listCaps ?? opts.caps.slice(0, 3).map((cap) => cap.id);
55
62
  for (const id of listCaps) {
56
63
  if (!capIds.has(id)) {
57
- throw new Error(
58
- `createCapOverviewFeature: listCaps references unknown cap id "${id}" — known ids: ${[...capIds].join(", ")}`,
59
- );
64
+ throw bootRuleError(CAP_OVERVIEW_BOOT_RULES.unknownListCap, {
65
+ message: `createCapOverviewFeature: listCaps references unknown cap id "${id}" — known ids: ${[...capIds].join(", ")}`,
66
+ });
60
67
  }
61
68
  }
62
69
 
@@ -0,0 +1,14 @@
1
+ import type { BootRuleTable } from "@cosmicdrift/kumiko-framework/engine";
2
+
3
+ export const DOCUMENTS_BOOT_RULES = {
4
+ negativeExpiringWithinDays: {
5
+ id: "documents/negative-expiring-within-days",
6
+ summary: "expiringWithinDays is not negative.",
7
+ fix: "Pass zero or a positive number.",
8
+ },
9
+ categoryLabelUnknownCategory: {
10
+ id: "documents/category-label-unknown-category",
11
+ summary: "categoryLabels only names categories listed in categories.",
12
+ fix: "Add the category to categories or drop its label.",
13
+ },
14
+ } as const satisfies BootRuleTable;
@@ -5,6 +5,7 @@
5
5
 
6
6
  import {
7
7
  type AccessRule,
8
+ bootRuleError,
8
9
  defineEntityCreateHandler,
9
10
  defineEntityDeleteHandler,
10
11
  defineEntityDetailHandler,
@@ -14,6 +15,7 @@ import {
14
15
  type EntityDefinition,
15
16
  type FeatureRegistrar,
16
17
  } from "@cosmicdrift/kumiko-framework/engine";
18
+ import { DOCUMENTS_BOOT_RULES } from "./boot-rules.ts";
17
19
  import { type DocumentCaptureRule, registerCapture, validateCaptureRules } from "./capture.ts";
18
20
  import {
19
21
  DEFAULT_ADMIN_ROLES,
@@ -213,13 +215,15 @@ function registerDocuments(
213
215
 
214
216
  export function createDocumentsFeature(opts: DocumentsFeatureOptions) {
215
217
  if (opts.expiringWithinDays !== undefined && opts.expiringWithinDays < 0) {
216
- throw new Error("createDocumentsFeature({ expiringWithinDays }) must not be negative.");
218
+ throw bootRuleError(DOCUMENTS_BOOT_RULES.negativeExpiringWithinDays, {
219
+ message: "createDocumentsFeature({ expiringWithinDays }) must not be negative.",
220
+ });
217
221
  }
218
222
  for (const category of Object.keys(opts.categoryLabels ?? {})) {
219
223
  if (!opts.categories.includes(category)) {
220
- throw new Error(
221
- `createDocumentsFeature({ categoryLabels }) names "${category}", which is not in categories.`,
222
- );
224
+ throw bootRuleError(DOCUMENTS_BOOT_RULES.categoryLabelUnknownCategory, {
225
+ message: `createDocumentsFeature({ categoryLabels }) names "${category}", which is not in categories.`,
226
+ });
223
227
  }
224
228
  }
225
229
  return defineFeature(DOCUMENTS_FEATURE_NAME, (r) => registerDocuments(r, opts));
@@ -0,0 +1,9 @@
1
+ import type { BootRuleTable } from "@cosmicdrift/kumiko-framework/engine";
2
+
3
+ export const FILE_DERIVATIVES_BOOT_RULES = {
4
+ publicTenantResolutionWithoutApexResolver: {
5
+ id: "file-derivatives/public-tenant-resolution-without-apex-resolver",
6
+ summary: "publicTenantResolution is only set together with resolveApexTenant.",
7
+ fix: "Pass resolveApexTenant or drop publicTenantResolution.",
8
+ },
9
+ } as const satisfies BootRuleTable;
@@ -8,6 +8,7 @@
8
8
 
9
9
  import { cachedResponse, computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
10
10
  import {
11
+ bootRuleError,
11
12
  defineFeature,
12
13
  EXT_DERIVATIVE_OVERLAY_RESOLVER,
13
14
  EXT_DERIVATIVE_PUBLIC_PREDICATE,
@@ -17,6 +18,7 @@ import {
17
18
  type TenantId,
18
19
  } from "@cosmicdrift/kumiko-framework/engine";
19
20
  import { RateLimitError } from "@cosmicdrift/kumiko-framework/errors";
21
+ import { FILE_DERIVATIVES_BOOT_RULES } from "./boot-rules.ts";
20
22
  import { PUBLIC_VARIANT_QN, publicVariantQuery } from "./handlers/public-variant.query.ts";
21
23
  import {
22
24
  PUBLIC_VARIANT_BY_FILE_REF_QN,
@@ -95,9 +97,10 @@ type PublicVariantQueryResult = {
95
97
  export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}): FeatureDefinition {
96
98
  const basePath = opts.basePath ?? "/media";
97
99
  if (opts.publicTenantResolution !== undefined && !opts.resolveApexTenant) {
98
- throw new Error(
99
- "createFileDerivativesFeature: publicTenantResolution requires resolveApexTenant — it only changes which tenant a variant is read from, resolveApexTenant still gates the host.",
100
- );
100
+ throw bootRuleError(FILE_DERIVATIVES_BOOT_RULES.publicTenantResolutionWithoutApexResolver, {
101
+ message:
102
+ "createFileDerivativesFeature: publicTenantResolution requires resolveApexTenant — it only changes which tenant a variant is read from, resolveApexTenant still gates the host.",
103
+ });
101
104
  }
102
105
 
103
106
  return defineFeature(
@@ -0,0 +1,9 @@
1
+ import type { BootRuleTable } from "@cosmicdrift/kumiko-framework/engine";
2
+
3
+ export const FOLDERS_BOOT_RULES = {
4
+ emptyParentsAllowlist: {
5
+ id: "folders/empty-parents-allowlist",
6
+ summary: "The parents allowlist is omitted or non-empty.",
7
+ fix: "Omit parents or list at least one entity.",
8
+ },
9
+ } as const satisfies BootRuleTable;
@@ -17,6 +17,7 @@
17
17
 
18
18
  import {
19
19
  type AccessRule,
20
+ bootRuleError,
20
21
  defineEntityCreateHandler,
21
22
  defineEntityDetailHandler,
22
23
  defineEntityListHandler,
@@ -26,6 +27,7 @@ import {
26
27
  type FeatureRegistrar,
27
28
  } from "@cosmicdrift/kumiko-framework/engine";
28
29
  import { assertNoWhereRuleInOwnershipWrite, resolveFeatureAccess } from "../shared/index.ts";
30
+ import { FOLDERS_BOOT_RULES } from "./boot-rules.ts";
29
31
  import { createFolderAssignmentEntity, folderEntity } from "./entity.ts";
30
32
  import { createClearFolderHandler } from "./handlers/clear-folder.write.ts";
31
33
  import { createDeleteFolderHandler } from "./handlers/delete-folder.write.ts";
@@ -164,12 +166,13 @@ export function createFoldersFeature(
164
166
  }
165
167
  assertNoWhereRuleInOwnershipWrite("createFoldersFeature", opts.ownership?.write);
166
168
  if (opts.parents !== undefined && opts.parents.length === 0) {
167
- throw new Error(
168
- "createFoldersFeature({ parents }): parents must not be an empty array — " +
169
+ throw bootRuleError(FOLDERS_BOOT_RULES.emptyParentsAllowlist, {
170
+ message:
171
+ "createFoldersFeature({ parents }): parents must not be an empty array — " +
169
172
  "an empty allowlist rejects every set-folder call and hides every " +
170
173
  "assignment row. Omit `parents` to keep every registered entity " +
171
174
  "admissible as a host instead.",
172
- );
175
+ });
173
176
  }
174
177
  const access = resolveFeatureAccess(opts, DEFAULT_FOLDER_ACCESS);
175
178
  return defineFeature(FOLDERS_FEATURE_NAME, (r) =>
@@ -0,0 +1,9 @@
1
+ import type { BootRuleTable } from "@cosmicdrift/kumiko-framework/engine";
2
+
3
+ export const HELPDESK_BOOT_RULES = {
4
+ invalidProofOfWorkBits: {
5
+ id: "helpdesk/invalid-proof-of-work-bits",
6
+ summary: "spamProtection.proofOfWorkBits is an integer within the allowed range.",
7
+ fix: "Use an integer inside the documented bounds.",
8
+ },
9
+ } as const satisfies BootRuleTable;
@@ -1,7 +1,7 @@
1
1
  import { randomBytes } from "node:crypto";
2
2
  import type { Redis } from "ioredis";
3
3
  import * as z from "zod";
4
- import { CONTACT_CHALLENGE_REDIS_PREFIX } from "./web/constants.ts";
4
+ import { HELPDESK_CHALLENGE_REDIS_PREFIX } from "./web/constants.ts";
5
5
 
6
6
  const CHALLENGE_BYTES = 16;
7
7
 
@@ -11,7 +11,7 @@ const StoredChallengeSchema = z.object({
11
11
  });
12
12
  export type StoredChallenge = z.infer<typeof StoredChallengeSchema>;
13
13
 
14
- const challengeKey = (challenge: string) => `${CONTACT_CHALLENGE_REDIS_PREFIX}${challenge}`;
14
+ const challengeKey = (challenge: string) => `${HELPDESK_CHALLENGE_REDIS_PREFIX}${challenge}`;
15
15
 
16
16
  export async function issueChallenge(
17
17
  redis: Redis,
@@ -1,4 +1,10 @@
1
1
  [
2
+ {
3
+ "version": "0.413.0",
4
+ "type": "breaking",
5
+ "title": "contact feature renamed to helpdesk",
6
+ "migration": "The bundled feature contact is renamed to helpdesk; nothing keeps the old names. Imports: @cosmicdrift/kumiko-bundled-features/contact, /contact/web and /contact/client become /helpdesk, /helpdesk/web and /helpdesk/client; createContactFeature, contactOpenRequestsPanels, ContactOptions and the other Contact*/CONTACT_* exports become Helpdesk*/HELPDESK_* (createHelpdeskFeature, helpdeskOpenRequestsPanels, HelpdeskOptions). The feature name, handler, screen, config and i18n keys move from contact: to helpdesk:, the entities from contact-request/contact-reply to helpdesk-request/helpdesk-reply with the tables read_helpdesk_requests/read_helpdesk_replies, and error codes from contact_* to helpdesk_*. The browser client is served at GET /helpdesk/client.js and registers window.KumikoHelpdesk; update script tags, same-origin ingress paths and nav/legal references to the feature name. Notification preferences and opt-outs stored under contact:notify: are not carried over; the six notifications start with their defaults. Run kumiko schema generate and commit the migration. Data stored under the old names is not carried over: requests, replies and their events stay inert under contact-request/contact-reply, and the config values contact:config:reply-to and contact:config:telegram-chat are not read any more. Close open requests before upgrading and set reply-to and the Telegram chat again on the forwarding screen."
7
+ },
2
8
  {
3
9
  "version": "0.410.0",
4
10
  "type": "improvement",
@@ -1,12 +1,12 @@
1
1
  // The browser client ships as a string so it survives the tsc-only dist build, which copies no
2
2
  // loose .js assets. Keep it free of backslashes, backticks and template placeholders.
3
- export const CONTACT_CLIENT_SOURCE = `(function () {
3
+ export const HELPDESK_CLIENT_SOURCE = `(function () {
4
4
  "use strict";
5
5
 
6
6
  var QUERY_PATH = "/api/query";
7
7
  var WRITE_PATH = "/api/write";
8
- var CHALLENGE_QUERY = "contact:query:challenge";
9
- var SUBMIT_WRITE = "contact:write:submit";
8
+ var CHALLENGE_QUERY = "helpdesk:query:challenge";
9
+ var SUBMIT_WRITE = "helpdesk:write:submit";
10
10
  var CSRF_COOKIE_NAME = "kumiko_csrf";
11
11
  var CSRF_HEADER_NAME = "X-CSRF-Token";
12
12
  var LOCALE_HEADER_NAME = "X-Locale";
@@ -198,6 +198,6 @@ export const CONTACT_CLIENT_SOURCE = `(function () {
198
198
  });
199
199
  }
200
200
 
201
- window.KumikoContact = { load: load, submit: submit };
201
+ window.KumikoHelpdesk = { load: load, submit: submit };
202
202
  })();
203
203
  `;