@cosmicdrift/kumiko-framework 0.413.0 → 0.413.1

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.
@@ -974,6 +974,7 @@ type JobDefinition = {
974
974
  runOnBoot?: boolean | undefined;
975
975
  bootGate?: boolean | undefined;
976
976
  perTenant?: boolean | undefined;
977
+ includeSystemTenant?: boolean | undefined;
977
978
  runIn?: JobRunIn | undefined;
978
979
  escapeHatch?: EscapeHatchDeclaration | undefined;
979
980
  tenantVisibleFailure?: { messageKey: string; subjectFields?: string[] | undefined; } | undefined;
@@ -18,7 +18,8 @@ SystemAdmins reply from the admin. Phone is off and Telegram is not mounted unle
18
18
  turns them on (`fields.phone`, `telegram: true`).
19
19
 
20
20
  **What the recipe demonstrates:**
21
- - Mounting `createHelpdeskFeature` with its companions (delivery, user-data-rights, files)
21
+ - Mounting `createHelpdeskFeature` with its companions (config, delivery, user-data-rights,
22
+ files, notes-history)
22
23
  - The anonymous flow: `helpdesk:query:challenge` hands out a proof-of-work challenge,
23
24
  `helpdesk:write:submit` verifies it; spam gets the same 200 body and stores nothing
24
25
  - The browser client at `GET /helpdesk/client.js` (`window.KumikoHelpdesk.load()` / `submit()`)
@@ -48,12 +49,15 @@ bun test --config=bunfig.integration.toml samples/recipes/helpdesk
48
49
  ## Integration into a real app
49
50
 
50
51
  1. Mount `createHelpdeskFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
51
- `files` with a file provider and `config`.
52
+ `files` with a file provider, `notes-history` and `config`.
52
53
  2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
53
54
  3. SystemAdmins set `helpdesk:config:reply-to` in the admin.
54
- 4. Embed `/helpdesk/client.js` on the website; the form is yours. A website served by another
55
- server can serve the same script from `HELPDESK_CLIENT_SOURCE` and type its calls with
56
- `HelpdeskWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/helpdesk/client`.
55
+ 4. Embed `/helpdesk/client.js` on the website; the form is yours. The client posts to the
56
+ relative paths `/api/query` and `/api/write` without cookies, so the page has to share the
57
+ app's origin. A website served by another server forwards `/api` to the app on its own
58
+ origin; it can then serve the same script from `HELPDESK_CLIENT_SOURCE` and type its calls
59
+ with `HelpdeskWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/helpdesk/client`.
60
+ `samples/apps/use-all-bundled/public/helpdesk-contact.html` (with `helpdesk-contact.js`) is a complete same-origin page.
57
61
 
58
62
  Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
59
63
  that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
@@ -150,8 +154,10 @@ describe("helpdesk sample", () => {
150
154
  // captcha: honeypot field, single-use proof-of-work challenge, minimum submit time, per-IP
151
155
  // and per-email rate limits. Rejected submits answer 200 with the normal body.
152
156
  //
153
- // The website embeds the anonymous client the feature serves itself:
154
- // <script src="https://api.example.com/helpdesk/client.js"></script>
157
+ // The website embeds the anonymous client the feature serves itself. The client posts to the
158
+ // relative paths /api/query and /api/write, so the page must share its origin with the app
159
+ // (or forward /api to it on its own origin):
160
+ // <script src="/helpdesk/client.js"></script>
155
161
  // const { kinds, phone } = await window.KumikoHelpdesk.load();
156
162
  // const result = await window.KumikoHelpdesk.submit({ kind, name, email, message, locale });
157
163
  // // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
@@ -159,7 +165,8 @@ describe("helpdesk sample", () => {
159
165
  // Prerequisites the app wires itself:
160
166
  // - `anonymousAccess` (defaultTenantId = SYSTEM_TENANT_ID) so the form needs no login
161
167
  // - delivery with a mail channel (channel-telegram only with `telegram: true`, off by default)
162
- // - a file provider, because the entities carry file fields
168
+ // - config, user-data-rights and notes-history (required features)
169
+ // - files with a file provider, because the entities carry file fields
163
170
  // - `kumiko schema generate` for the new tables
164
171
 
165
172
  import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk";
@@ -27,6 +27,7 @@ export declare function validateLifecycleHookTargets(state: RegistryState): void
27
27
  export declare function validateEntityHookTargets(state: RegistryState, features: readonly FeatureDefinition[]): void;
28
28
  export declare function resolveJobTriggers(state: RegistryState): void;
29
29
  export declare function validateLiveEntities(state: RegistryState): void;
30
+ export declare function validateIncludeSystemTenantJobs(state: RegistryState): void;
30
31
  export declare function validateBootGates(state: RegistryState): void;
31
32
  export declare function validateJobBackoff(state: RegistryState): void;
32
33
  export declare function validateMaxDefers(state: RegistryState): void;
@@ -744,6 +744,13 @@ export function validateLiveEntities(state) {
744
744
  }
745
745
  }
746
746
  }
747
+ export function validateIncludeSystemTenantJobs(state) {
748
+ for (const [jobName, jobDef] of state.jobMap) {
749
+ if (jobDef.includeSystemTenant && !jobDef.perTenant) {
750
+ throw new Error(`Job "${jobName}" sets includeSystemTenant without perTenant`);
751
+ }
752
+ }
753
+ }
747
754
  export function validateBootGates(state) {
748
755
  // Boot gates run inline in JobRunner.start(), which has neither the
749
756
  // per-tenant fan-out (that re-enqueues) nor the sequential lock's
@@ -4,7 +4,7 @@ import { buildRegistryFacade } from "./registry-facade.js";
4
4
  import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateSystemEvents, populateTranslations, } from "./registry-ingest.js";
5
5
  import { populateReadModelEntities } from "./registry-read-models.js";
6
6
  import { createInitialState } from "./registry-state.js";
7
- import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateMaxDefers, validateMaxPerTenant, validateNotificationRecordMappings, validateNotificationRenamedFrom, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
7
+ import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateIncludeSystemTenantJobs, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateMaxDefers, validateMaxPerTenant, validateNotificationRecordMappings, validateNotificationRenamedFrom, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
8
8
  // This is where the magic happens. By "magic" I mean: precomputed maps.
9
9
  // I build everything once at boot (hooks, relations, searchable fields, ...)
10
10
  // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
@@ -49,6 +49,7 @@ export function createRegistry(rawFeatures) {
49
49
  validateEntityHookTargets(state, features);
50
50
  resolveJobTriggers(state);
51
51
  validateBootGates(state);
52
+ validateIncludeSystemTenantJobs(state);
52
53
  validateLiveEntities(state);
53
54
  validateJobBackoff(state);
54
55
  validateMaxDefers(state);
@@ -62,7 +62,7 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
62
62
  if (!db || !registry) {
63
63
  throw new Error("soft-delete cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
64
64
  }
65
- // perTenant fan-out → one run per active tenant, systemUser scoped to it.
65
+ // perTenant fan-out → one run per active tenant plus the system tenant, systemUser scoped to it.
66
66
  // The job's db is a tenant-filtered TenantDb, but every delete is still
67
67
  // explicitly tenant-filtered below as defense-in-depth — otherwise a
68
68
  // tenant with a short grace would purge another tenant's still-within-grace
@@ -73,7 +73,7 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
73
73
  return;
74
74
  }
75
75
  const graceDays = await resolveGraceDays(ctx, tenantId, db);
76
- const cutoff = Temporal.Now.instant().subtract({ hours: graceDays * 24 });
76
+ const cutoff = ctx.tz.now().subtract({ hours: graceDays * 24 });
77
77
  for (const proj of registry.getAllProjections().values()) {
78
78
  if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
79
79
  continue;
@@ -143,7 +143,7 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
143
143
  if (!db || !registry) {
144
144
  throw new Error("soft-delete system cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
145
145
  }
146
- const cutoff = Temporal.Now.instant().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
146
+ const cutoff = ctx.tz.now().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
147
147
  for (const proj of registry.getAllProjections().values()) {
148
148
  if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
149
149
  continue;
@@ -168,6 +168,7 @@ export function buildSoftDeleteCleanupJob() {
168
168
  handler: softDeleteCleanupJob,
169
169
  trigger: { maintenance: true },
170
170
  perTenant: true,
171
+ includeSystemTenant: true,
171
172
  concurrency: "skip",
172
173
  runIn: "worker",
173
174
  };
@@ -42,6 +42,7 @@ export function createFilesFeature(options = {}) {
42
42
  name: "sweep-orphaned-uploads",
43
43
  trigger: { maintenance: true },
44
44
  perTenant: true,
45
+ includeSystemTenant: true,
45
46
  concurrency: "skip",
46
47
  handler: async (_payload, ctx) => {
47
48
  await sweepOrphanedUploads({
@@ -1,3 +1,4 @@
1
+ import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
1
2
  import { prepareJobRun } from "./job-runner-context.js";
2
3
  import { attemptNumberOf, buildRetryBullOpts, DEFER_COUNT_KEY, deferDelayMs, isFinalAttempt, priorAttemptsOf, priorDeferCountOf, } from "./job-runner-helpers.js";
3
4
  import { ACTIVE_TENANT_IDS_QUERY_NAME, perTenantChildJobId } from "./job-runner-schedulers.js";
@@ -35,7 +36,10 @@ async function enqueuePerTenantChildren(scope, bullJob, actualName) {
35
36
  if (!actualDef) {
36
37
  throw new Error(`Unknown job: ${actualName}`);
37
38
  }
38
- const tenantIds = await getActiveTenantIds();
39
+ const activeTenantIds = await getActiveTenantIds();
40
+ const tenantIds = actualDef.includeSystemTenant === true && !activeTenantIds.includes(SYSTEM_TENANT_ID)
41
+ ? [...activeTenantIds, SYSTEM_TENANT_ID]
42
+ : activeTenantIds;
39
43
  const targetQueue = scope.queues[laneForJob(actualDef)];
40
44
  // wrapperJobId is only absent for a Job BullMQ somehow never assigned
41
45
  // an id to (not observed in practice) — falling back to a constant
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-framework",
3
- "version": "0.413.0",
3
+ "version": "0.413.1",
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.413.0",
206
+ "@cosmicdrift/kumiko-types": "0.413.1",
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.413.0",
228
+ "@cosmicdrift/kumiko-testing": "0.413.1",
229
229
  "bun-types": "^1.4.4",
230
230
  "fflate": "^0.8.3",
231
231
  "meilisearch": "^0.62.0",