@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/currencies-per-tenant.md

@@ -0,0 +1,453 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/currencies-per-tenant. Do not edit. -->
+
+# currencies-per-tenant
+
+Tenant-scoped money fields. Commas matter.
+
+## README
+
+# Currencies Per Tenant
+
+Multi-currency money with per-tenant rate tables.
+
+## What it shows
+
+- Tenant-scoped FX rates
+- Same money field API as the global recipe
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/currencies-per-tenant
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Money Tenant Sample — Integration Test
+// Proves: tenant-owned currencies, each tenant has their own list,
+// no shared data, isActive filter, cross-tenant isolation
+//
+// ┌──────────┬─────────────────────────┬─────────────────────────┐
+// │          │ Tenant 1                │ Tenant 2                │
+// ├──────────┼─────────────────────────┼─────────────────────────┤
+// │ Active   │ EUR, USD, XYZ           │ GBP, JPY, TRY           │
+// │ Inactive │ —                       │ KRW                     │
+// ├──────────┼─────────────────────────┼─────────────────────────┤
+// │ Allowed  │ EUR, USD, XYZ           │ GBP, JPY, TRY           │
+// │ Denied   │ GBP, JPY, TRY, KRW     │ EUR, USD, XYZ, KRW      │
+// └──────────┴─────────────────────────┴─────────────────────────┘
+// XYZ is a custom currency — not ISO, created by tenant 1
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { currencyEntity } from "../entities/currency";
+import { invoiceEntity } from "../entities/invoice";
+import { currenciesPerTenantFeature } from "../feature";
+
+// The executor returns the rehydrated read-form: money is the combined
+// { amount, currency }, not the flat amount/amountCurrency columns insertOne leaked.
+const asMoney = (v: unknown) => v as { amount: number; currency: string };
+
+let stack: TestStack;
+
+const tenant1Admin = TestUsers.admin;
+const tenant2Admin = createTestUser({ id: 2, tenantId: "00000000-0000-4000-8000-000000000002" });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [currenciesPerTenantFeature],
+    systemHooks: [],
+  });
+
+  await unsafeCreateEntityTable(stack.db, currencyEntity);
+  await unsafeCreateEntityTable(stack.db, invoiceEntity);
+
+  // Tenant 1 creates their own currencies: EUR, USD, XYZ
+  for (const { code, name } of [
+    { code: "EUR", name: "Euro" },
+    { code: "USD", name: "US Dollar" },
+    { code: "XYZ", name: "Custom Token" },
+  ]) {
+    await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:currency:create",
+      { code, name },
+      tenant1Admin,
+    );
+  }
+
+  // Tenant 2 creates their own currencies: GBP, JPY, TRY, KRW (inactive)
+  for (const { code, name, isActive } of [
+    { code: "GBP", name: "British Pound", isActive: true },
+    { code: "JPY", name: "Japanese Yen", isActive: true },
+    { code: "TRY", name: "Turkish Lira", isActive: true },
+    { code: "KRW", name: "Korean Won", isActive: false },
+  ]) {
+    await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:currency:create",
+      { code, name, isActive },
+      tenant2Admin,
+    );
+  }
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// --- Tenant 1 ---
+
+describe("tenant 1: allowed currencies", () => {
+  test("create invoice with EUR succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Invoice T1-EUR", amount: 150050, amountCurrency: "EUR" },
+      tenant1Admin,
+    );
+    expect(data.isNew).toBe(true);
+    expect(asMoney(data.data["amount"]).amount).toBe(150050);
+    expect(asMoney(data.data["amount"]).currency).toBe("EUR");
+  });
+
+  test("create invoice with XYZ (custom tenant currency) succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Invoice T1-XYZ", amount: 42, amountCurrency: "XYZ" },
+      tenant1Admin,
+    );
+    expect(data.isNew).toBe(true);
+    expect(asMoney(data.data["amount"]).currency).toBe("XYZ");
+  });
+});
+
+describe("tenant 1: denied currencies", () => {
+  test("GBP fails (tenant 1 never created it)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Fail", amount: 100, amountCurrency: "GBP" },
+      tenant1Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+});
+
+// --- Tenant 2 ---
+
+describe("tenant 2: allowed currencies", () => {
+  test("create invoice with GBP succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Invoice T2-GBP", amount: 99999, amountCurrency: "GBP" },
+      tenant2Admin,
+    );
+    expect(data.isNew).toBe(true);
+    expect(asMoney(data.data["amount"]).currency).toBe("GBP");
+  });
+});
+
+describe("tenant 2: denied currencies", () => {
+  test("EUR fails (tenant 2 never created it)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Fail", amount: 100, amountCurrency: "EUR" },
+      tenant2Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+
+  test("KRW fails (inactive)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Fail", amount: 100, amountCurrency: "KRW" },
+      tenant2Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+});
+
+// --- Cross-tenant isolation ---
+
+describe("tenant isolation", () => {
+  test("tenant 2 cannot use tenant 1's XYZ", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Cross-tenant", amount: 100, amountCurrency: "XYZ" },
+      tenant2Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+
+  test("tenant 1 cannot use tenant 2's TRY", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Cross-tenant", amount: 100, amountCurrency: "TRY" },
+      tenant1Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+});
+
+// --- Detail query ---
+
+describe("invoice detail", () => {
+  test("detail returns the correct invoice by id", async () => {
+    const _first = await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Detail-First", amount: 100, amountCurrency: "EUR" },
+      tenant1Admin,
+    );
+    const second = await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Detail-Second", amount: 200, amountCurrency: "USD" },
+      tenant1Admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "currencies-per-tenant:query:invoice:detail",
+      { id: second.id },
+      tenant1Admin,
+    );
+    expect(detail["id"]).toBe(second.id);
+    expect(detail["title"]).toBe("Detail-Second");
+    expect(detail["amountCurrency"]).toBe("USD");
+  });
+
+  test("detail returns null for other tenant's invoice", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "currencies-per-tenant:write:invoice:create",
+      { title: "Tenant1-Only", amount: 50, amountCurrency: "EUR" },
+      tenant1Admin,
+    );
+
+    const detail = await stack.http.queryOk<null>(
+      "currencies-per-tenant:query:invoice:detail",
+      { id: created.id },
+      tenant2Admin,
+    );
+    expect(detail).toBeNull();
+  });
+});
+```
+
+### src/entities/currency.ts
+
+```ts
+// Currency — tenant-owned, each tenant manages their own currency list
+// No global reference data — tenants create currencies themselves
+
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const currencyEntity = createEntity({
+  table: "read_sample_mt_currencies",
+  fields: {
+    code: createTextField({ personal: false, reason: "is_reference_data", required: true }),
+    name: createTextField({ personal: false, reason: "is_reference_data", required: true }),
+    isActive: createBooleanField({ default: true }),
+  },
+});
+
+export const currencyTable = buildEntityTable("currency", currencyEntity);
+```
+
+### src/entities/invoice.ts
+
+```ts
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createMoneyField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const invoiceEntity = createEntity({
+  table: "read_sample_mt_invoices",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    amount: createMoneyField({ required: true }),
+    shippingCost: createMoneyField(),
+  },
+  defaultCurrency: "EUR",
+});
+
+export const invoiceTable = buildEntityTable("invoice", invoiceEntity);
+```
+
+### src/feature.ts
+
+```ts
+// Money Tenant Sample
+// Shows: Tenant-owned currencies — each tenant manages their own currency list
+//
+// Pattern: No global currency catalog. Each tenant creates currencies themselves.
+// Use this when: Tenants need custom currencies (loyalty points, crypto, internal units)
+//
+// Tables:
+//   currency   — tenant-owned, created by tenant admin (with isActive flag)
+//   invoice    — money fields validated against tenant's currency table
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { currencyEntity } from "./entities/currency";
+import { invoiceEntity } from "./entities/invoice";
+import { currencyCreate } from "./handlers/currency-create.write";
+import { invoiceCreate } from "./handlers/invoice-create.write";
+import { invoiceDetail } from "./handlers/invoice-detail.query";
+
+export { currencyEntity } from "./entities/currency";
+export { invoiceEntity } from "./entities/invoice";
+
+export const currenciesPerTenantFeature = defineFeature("currenciesPerTenant", (r) => {
+  r.entity("currency", currencyEntity);
+  r.entity("invoice", invoiceEntity);
+
+  // No r.referenceData() — tenants create currencies themselves
+  r.writeHandler(currencyCreate);
+  r.writeHandler(invoiceCreate);
+  r.queryHandler(invoiceDetail);
+});
+```
+
+### src/handlers/currency-create.write.ts
+
+```ts
+// Tenant creates their own currency — no global table needed
+
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { currencyEntity, currencyTable } from "../entities/currency";
+
+const currencyCrud = createEventStoreExecutor(currencyTable, currencyEntity, {
+  entityName: "currency",
+});
+
+export const currencyCreate = defineWriteHandler({
+  name: "currency:create",
+  schema: z.object({
+    code: z.string().length(3),
+    name: z.string().min(1),
+    isActive: z.boolean().optional(),
+  }),
+  access: { roles: ["Admin"] },
+  // Event-sourced create — the executor appends `currency.created` + applies the
+  // projection in one TX (id + audit columns are set for us). A direct insertOne
+  // would drift the row past its event stream and a rebuild would wipe it.
+  handler: async (event, ctx) => currencyCrud.create(event.payload, event.user, ctx.db),
+});
+```
+
+### src/handlers/invoice-create.write.ts
+
+```ts
+import { assertExistsIn, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { currencyTable } from "../entities/currency";
+import { invoiceEntity, invoiceTable } from "../entities/invoice";
+
+const invoiceCrud = createEventStoreExecutor(invoiceTable, invoiceEntity, {
+  entityName: "invoice",
+});
+
+export const invoiceCreate = defineWriteHandler({
+  name: "invoice:create",
+  schema: z.object({
+    title: z.string().min(1),
+    amount: z.number(),
+    amountCurrency: z.string().length(3),
+    shippingCost: z.number().optional(),
+    shippingCostCurrency: z.string().length(3).optional(),
+  }),
+  access: { roles: ["Admin"] },
+  handler: async (event, ctx) => {
+    const { title, amount, amountCurrency, shippingCost, shippingCostCurrency } = event.payload;
+
+    // Validate currency against tenant's own currency list
+    const amountMissing = await assertExistsIn(ctx.db, currencyTable, {
+      field: "code",
+      value: amountCurrency,
+      where: { isActive: true },
+    });
+    if (amountMissing) {
+      return failUnprocessable("currency_not_allowed", {
+        field: "amountCurrency",
+        value: amountCurrency,
+      });
+    }
+
+    if (shippingCostCurrency) {
+      const shippingMissing = await assertExistsIn(ctx.db, currencyTable, {
+        field: "code",
+        value: shippingCostCurrency,
+        where: { isActive: true },
+      });
+      if (shippingMissing) {
+        return failUnprocessable("currency_not_allowed", {
+          field: "shippingCostCurrency",
+          value: shippingCostCurrency,
+        });
+      }
+    }
+
+    // Money fields go in as the combined { amount, currency } API form; the
+    // executor flattens them into the invoice's own amount/amountCurrency columns.
+    return invoiceCrud.create(
+      {
+        title,
+        amount: { amount, currency: amountCurrency },
+        ...(shippingCost !== undefined
+          ? { shippingCost: { amount: shippingCost, currency: shippingCostCurrency } }
+          : {}),
+      },
+      event.user,
+      ctx.db,
+    );
+  },
+});
+```
+
+### src/handlers/invoice-detail.query.ts
+
+```ts
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { invoiceTable } from "../entities/invoice";
+
+export const invoiceDetail = defineQueryHandler({
+  name: "invoice:detail",
+  schema: z.object({ id: z.uuid() }),
+  access: {
+    openToAll: {
+      reason:
+        "demo recipe: any signed-in user may look up any invoice in their own tenant " +
+        "by id; the sample focuses on currency formatting, not access control",
+    },
+  },
+  handler: async (query, ctx) => {
+    const [row] = await ctx.db.selectMany(invoiceTable, { id: query.payload.id });
+    return (row as Record<string, unknown>) ?? null;
+  },
+});
+```