@cosmicdrift/kumiko-bundled-features 0.256.0 → 0.257.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.256.0",
+  "version": "0.257.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.256.0",
-    "@cosmicdrift/kumiko-framework": "0.256.0",
-    "@cosmicdrift/kumiko-headless": "0.256.0",
-    "@cosmicdrift/kumiko-renderer": "0.256.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.256.0",
-    "@cosmicdrift/kumiko-types": "0.256.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.257.0",
+    "@cosmicdrift/kumiko-framework": "0.257.0",
+    "@cosmicdrift/kumiko-headless": "0.257.0",
+    "@cosmicdrift/kumiko-renderer": "0.257.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.257.0",
+    "@cosmicdrift/kumiko-types": "0.257.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.256.0",
-    "@cosmicdrift/kumiko-locale-es": "0.256.0"
+    "@cosmicdrift/kumiko-locale-de": "0.257.0",
+    "@cosmicdrift/kumiko-locale-es": "0.257.0"
   }
 }

package/src/ledger/__tests__/ledger.integration.test.ts

@@ -64,7 +64,12 @@ async function createAccount(name: string, type: AccountType, user = admin): Pro
 
 async function createTransaction(
   lines: readonly Posting[],
-  opts: { date?: string; description?: string } = {},
+  opts: {
+    date?: string;
+    description?: string;
+    subjectType?: string;
+    subjectId?: string;
+  } = {},
   user = admin,
 ): Promise<{ id: string }> {
   return stack.http.writeOk<{ id: string }>(
@@ -73,15 +78,20 @@ async function createTransaction(
       date: opts.date ?? "2026-01-15",
       description: opts.description ?? "Test entry",
       lines,
+      ...(opts.subjectType !== undefined && { subjectType: opts.subjectType }),
+      ...(opts.subjectId !== undefined && { subjectId: opts.subjectId }),
     },
     user,
   );
 }
 
-async function listTransactions(user = admin): Promise<Array<Record<string, unknown>>> {
+async function listTransactions(
+  user = admin,
+  query: Record<string, unknown> = {},
+): Promise<Array<Record<string, unknown>>> {
   const res = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
     LedgerQueries.transactionList,
-    {},
+    query,
     user,
   );
   return res.rows;
@@ -350,7 +360,13 @@ describe("ledger integration — confirm-schedule-period (recurring)", () => {
   async function createSchedule(
     debitAccountId: string,
     creditAccountId: string,
-    over: { amount?: number; description?: string; startDate?: string } = {},
+    over: {
+      amount?: number;
+      description?: string;
+      startDate?: string;
+      subjectType?: string;
+      subjectId?: string;
+    } = {},
   ): Promise<string> {
     const s = await stack.http.writeOk<{ id: string }>(
       LedgerHandlers.createSchedule,
@@ -361,6 +377,8 @@ describe("ledger integration — confirm-schedule-period (recurring)", () => {
         amount: over.amount ?? 50000,
         debitAccountId,
         creditAccountId,
+        ...(over.subjectType !== undefined && { subjectType: over.subjectType }),
+        ...(over.subjectId !== undefined && { subjectId: over.subjectId }),
       },
       admin,
     );
@@ -457,4 +475,93 @@ describe("ledger integration — confirm-schedule-period (recurring)", () => {
     // Books net to zero (original cancels Storno) plus the fresh 48000 confirmation.
     expect(trialBalance(rows)).toBe(0);
   });
+
+  test("confirming a period on a schedule with a subject stamps the same subject onto the transaction", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent, {
+      subjectType: "lease",
+      subjectId: "lease-1",
+    });
+
+    await confirm(scheduleId, "2026-01");
+
+    const rows = await listTransactions();
+    expect(rows[0]?.["subjectType"]).toBe("lease");
+    expect(rows[0]?.["subjectId"]).toBe("lease-1");
+  });
+
+  test("confirming a period on a schedule without a subject leaves the transaction without one", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+    const scheduleId = await createSchedule(bank, rent);
+
+    await confirm(scheduleId, "2026-01");
+
+    const rows = await listTransactions();
+    expect(rows[0]?.["subjectType"]).toBeNull();
+    expect(rows[0]?.["subjectId"]).toBeNull();
+  });
+});
+
+describe("ledger integration — subject dimension (filterable business-object reference)", () => {
+  test("a booking with subjectType/subjectId round-trips and is findable via an eq filter", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+
+    const tx = await createTransaction(
+      [
+        { accountId: bank, amount: 100000 },
+        { accountId: rent, amount: -100000 },
+      ],
+      { description: "Miete WE1", subjectType: "lease", subjectId: "lease-1" },
+    );
+    await createTransaction(
+      [
+        { accountId: bank, amount: 60000 },
+        { accountId: rent, amount: -60000 },
+      ],
+      { description: "Miete WE2", subjectType: "lease", subjectId: "lease-2" },
+    );
+
+    const rows = await listTransactions(admin, {
+      filter: { field: "subjectId", op: "eq", value: "lease-1" },
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["id"]).toBe(tx.id);
+    expect(rows[0]?.["subjectType"]).toBe("lease");
+    expect(rows[0]?.["subjectId"]).toBe("lease-1");
+  });
+
+  test("an in-filter over multiple subjectId values returns exactly the matching bookings", async () => {
+    const bank = await createAccount("Bank", "asset");
+    const rent = await createAccount("Mieterträge", "income");
+
+    await createTransaction(
+      [
+        { accountId: bank, amount: 10000 },
+        { accountId: rent, amount: -10000 },
+      ],
+      { subjectType: "lease", subjectId: "lease-1" },
+    );
+    await createTransaction(
+      [
+        { accountId: bank, amount: 20000 },
+        { accountId: rent, amount: -20000 },
+      ],
+      { subjectType: "lease", subjectId: "lease-2" },
+    );
+    await createTransaction(
+      [
+        { accountId: bank, amount: 30000 },
+        { accountId: rent, amount: -30000 },
+      ],
+      { subjectType: "lease", subjectId: "lease-3" },
+    );
+
+    const rows = await listTransactions(admin, {
+      filters: [{ field: "subjectId", op: "in", value: ["lease-1", "lease-3"] }],
+    });
+    expect(rows.map((r) => r["subjectId"]).sort()).toEqual(["lease-1", "lease-3"]);
+  });
 });

package/src/ledger/entity.ts

@@ -78,7 +78,22 @@ export const transactionEntity = createEntity({
       },
       { required: true },
     ),
+    // Optional business-object reference (e.g. a lease contract) so entries can
+    // be filtered by what they're about, not just grepped out of `reference`.
+    subjectType: createTextField({
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+    subjectId: createTextField({
+      maxLength: 128,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
   },
+  indexes: [{ columns: ["tenantId", "subjectType", "subjectId"] }],
 });
 
 // schedule — a recurring booking template (Dauerauftrag): "book `amount` from
@@ -116,5 +131,20 @@ export const scheduleEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
+    // Confirmed periods inherit this from the schedule (see
+    // confirm-schedule-period.write.ts) rather than repeating it per period.
+    subjectType: createTextField({
+      maxLength: 64,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
+    subjectId: createTextField({
+      maxLength: 128,
+      personal: false,
+      reason: "technical_reference",
+      filterable: true,
+    }),
   },
+  indexes: [{ columns: ["tenantId", "subjectType", "subjectId"] }],
 });

package/src/ledger/handlers/confirm-schedule-period.write.ts

@@ -96,6 +96,11 @@ export function createConfirmSchedulePeriodHandler(
       }
 
       const amount = payload.amount ?? Number(schedule["amount"]);
+      // The subject is a property of the schedule, not the confirm call — a
+      // period without one stays without one, no backfill/error.
+      const subjectType =
+        typeof schedule["subjectType"] === "string" ? schedule["subjectType"] : null;
+      const subjectId = typeof schedule["subjectId"] === "string" ? schedule["subjectId"] : null;
       const created = await transactionExecutor.create(
         {
           id: generateId(),
@@ -107,6 +112,8 @@ export function createConfirmSchedulePeriodHandler(
             { accountId: debitAccountId, amount },
             { accountId: creditAccountId, amount: -amount },
           ],
+          subjectType,
+          subjectId,
         },
         event.user,
         ctx.db,

package/src/ledger/handlers/create-transaction.write.ts

@@ -35,6 +35,8 @@ export function createCreateTransactionHandler(
           reference: payload.reference ?? null,
           status: payload.status ?? "posted",
           lines: payload.lines,
+          subjectType: payload.subjectType ?? null,
+          subjectId: payload.subjectId ?? null,
         },
         event.user,
         ctx.db,

package/src/ledger/schemas.ts

@@ -27,6 +27,9 @@ export const createTransactionPayloadSchema = z
     // the Soll/recurring work — Phase 0 only ever creates posted entries.
     status: z.enum(TRANSACTION_STATUS).optional(),
     lines: z.array(postingSchema).min(2),
+    // Business-object reference (e.g. a lease contract) this entry is about.
+    subjectType: z.string().max(64).optional(),
+    subjectId: z.string().max(128).optional(),
   })
   .refine((p) => sumIsZero(p.lines), {
     message: "Transaction must balance: Σ of posting amounts must equal 0",