@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/currencies-global.md

@@ -0,0 +1,609 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/currencies-global. Do not edit. -->
+
+# currencies-global
+
+Shared money fields across tenants. Commas still matter.
+
+## README
+
+# Currencies Global
+
+Multi-currency money with a global rate table.
+
+## What it shows
+
+- Money field type + global FX rates
+- Conversion helpers shared across tenants
+
+## 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-global
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Money Sample — Integration Test
+// Proves: money fields store correctly, per-tenant currency validation works,
+// reference data seeding, custom currencies, assertExistsIn from framework
+//
+// ┌──────────┬────────────────────────────┬──────────────────────────┐
+// │          │ Tenant 1                   │ Tenant 2                 │
+// ├──────────┼────────────────────────────┼──────────────────────────┤
+// │ Standard │ EUR, USD                   │ USD, GBP, JPY            │
+// │ Custom   │ BHD, XYZ                   │ TRY, KRW, BRL            │
+// │ Inactive │ —                          │ KRW (isActive: false)    │
+// ├──────────┼────────────────────────────┼──────────────────────────┤
+// │ Allowed  │ EUR, USD, BHD, XYZ         │ USD, GBP, JPY, TRY, BRL │
+// │ Denied   │ GBP, TRY, KRW, ...        │ EUR, BHD, XYZ, KRW, ... │
+// └──────────┴────────────────────────────┴──────────────────────────┘
+// XYZ is NOT in DEFAULT_CURRENCIES — proves custom currencies work end-to-end
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { seedReferenceData } from "@cosmicdrift/kumiko-framework/db";
+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, currencyTable } from "../entities/currency";
+import { invoiceEntity } from "../entities/invoice";
+import { tenantCurrencyEntity } from "../entities/tenant-currency";
+import { currenciesGlobalFeature } 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: [currenciesGlobalFeature],
+    systemHooks: [],
+  });
+
+  await unsafeCreateEntityTable(stack.db, currencyEntity);
+  await unsafeCreateEntityTable(stack.db, tenantCurrencyEntity);
+  await unsafeCreateEntityTable(stack.db, invoiceEntity);
+
+  // Seed global currency table — same as r.referenceData() does at boot
+  const tables = new Map([["currency", currencyTable]]);
+  await seedReferenceData(currenciesGlobalFeature.referenceData, tables, stack.db);
+
+  // --- Assign currencies to tenant 1: EUR, USD (standard) + BHD, XYZ (custom) ---
+  for (const currencyCode of ["EUR", "USD", "BHD", "XYZ"]) {
+    await stack.http.writeOk<SaveContext>(
+      "currencies-global:write:tenant-currency:assign",
+      { currencyCode },
+      tenant1Admin,
+    );
+  }
+
+  // --- Assign currencies to tenant 2: USD, GBP, JPY (standard) + TRY, KRW, BRL (custom) ---
+  for (const currencyCode of ["USD", "GBP", "JPY", "TRY", "KRW", "BRL"]) {
+    await stack.http.writeOk<SaveContext>(
+      "currencies-global:write:tenant-currency:assign",
+      { currencyCode, isActive: currencyCode !== "KRW" },
+      tenant2Admin,
+    );
+  }
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// --- Tenant 1: EUR, USD, BHD, XYZ allowed ---
+
+describe("tenant 1: allowed currencies", () => {
+  test("create invoice with EUR (standard) succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-global: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 BHD (custom, in DEFAULT_CURRENCIES) succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-global:write:invoice:create",
+      { title: "Invoice T1-BHD", amount: 25075, amountCurrency: "BHD" },
+      tenant1Admin,
+    );
+    expect(data.isNew).toBe(true);
+    expect(asMoney(data.data["amount"]).currency).toBe("BHD");
+  });
+
+  test("create invoice with XYZ (NOT in DEFAULT_CURRENCIES) succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-global: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");
+  });
+
+  test("create invoice with shipping cost in different currency", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-global:write:invoice:create",
+      {
+        title: "Invoice with shipping",
+        amount: 1000,
+        amountCurrency: "EUR",
+        shippingCost: 4999,
+        shippingCostCurrency: "USD",
+      },
+      tenant1Admin,
+    );
+    expect(data.isNew).toBe(true);
+    expect(asMoney(data.data["amount"]).currency).toBe("EUR");
+    expect(asMoney(data.data["shippingCost"]).currency).toBe("USD");
+  });
+});
+
+// --- Tenant 1: denied currencies ---
+
+describe("tenant 1: denied currencies", () => {
+  test("create invoice with GBP fails (not assigned to tenant 1)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global:write:invoice:create",
+      { title: "Should fail", amount: 100, amountCurrency: "GBP" },
+      tenant1Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+
+  test("create invoice with TRY fails (not assigned to tenant 1)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global:write:invoice:create",
+      { title: "Should fail", amount: 100, amountCurrency: "TRY" },
+      tenant1Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+});
+
+// --- Tenant 2: USD, GBP, JPY, TRY, BRL allowed (KRW inactive) ---
+
+describe("tenant 2: allowed currencies", () => {
+  test("create invoice with GBP succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-global: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");
+  });
+
+  test("create invoice with TRY (custom) succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "currencies-global:write:invoice:create",
+      { title: "Invoice T2-TRY", amount: 50000, amountCurrency: "TRY" },
+      tenant2Admin,
+    );
+    expect(data.isNew).toBe(true);
+    expect(asMoney(data.data["amount"]).currency).toBe("TRY");
+  });
+});
+
+// --- Tenant 2: denied currencies ---
+
+describe("tenant 2: denied currencies", () => {
+  test("create invoice with EUR fails (not assigned to tenant 2)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global:write:invoice:create",
+      { title: "Should fail", amount: 100, amountCurrency: "EUR" },
+      tenant2Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+
+  test("create invoice with KRW fails (inactive in tenant 2)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global:write:invoice:create",
+      { title: "Should fail", amount: 100, amountCurrency: "KRW" },
+      tenant2Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+
+  test("create invoice with BHD fails (not assigned to tenant 2)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global:write:invoice:create",
+      { title: "Should fail", amount: 100, amountCurrency: "BHD" },
+      tenant2Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+});
+
+// --- Cross-tenant isolation ---
+
+describe("tenant isolation", () => {
+  test("tenant 2 cannot use tenant 1's BHD", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global:write:invoice:create",
+      { title: "Cross-tenant", amount: 100, amountCurrency: "BHD" },
+      tenant2Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+
+  test("tenant 2 cannot use tenant 1's XYZ (not in DEFAULT_CURRENCIES)", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global: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-global:write:invoice:create",
+      { title: "Cross-tenant", amount: 100, amountCurrency: "TRY" },
+      tenant1Admin,
+    );
+    expectErrorIncludes(error, "currency_not_allowed");
+  });
+});
+
+// --- Shipping currency validation ---
+
+describe("shipping currency validation", () => {
+  test("valid amount + invalid shipping currency fails", async () => {
+    const error = await stack.http.writeErr(
+      "currencies-global:write:invoice:create",
+      {
+        title: "Bad shipping",
+        amount: 100,
+        amountCurrency: "EUR",
+        shippingCost: 10,
+        shippingCostCurrency: "GBP", // not assigned to tenant 1
+      },
+      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-global:write:invoice:create",
+      { title: "Detail-First", amount: 100, amountCurrency: "EUR" },
+      tenant1Admin,
+    );
+    const second = await stack.http.writeOk<SaveContext>(
+      "currencies-global:write:invoice:create",
+      { title: "Detail-Second", amount: 200, amountCurrency: "USD" },
+      tenant1Admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "currencies-global: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-global:write:invoice:create",
+      { title: "Tenant1-Only", amount: 50, amountCurrency: "EUR" },
+      tenant1Admin,
+    );
+
+    const detail = await stack.http.queryOk<null>(
+      "currencies-global:query:invoice:detail",
+      { id: created.id },
+      tenant2Admin,
+    );
+    expect(detail).toBeNull();
+  });
+});
+```
+
+### src/entities/currency.ts
+
+```ts
+// Currency — global reference data table
+// Seeded from CURRENCY_CATALOG in feature.ts via r.referenceData()
+
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+export const currencyEntity = createEntity({
+  table: "read_sample_currencies",
+  fields: {
+    code: createTextField({ personal: false, reason: "is_reference_data", required: true }),
+    name: createTextField({ personal: false, reason: "is_reference_data", required: 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_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/entities/tenant-currency.ts
+
+```ts
+// TenantCurrency — which currencies each tenant is allowed to use
+// References currency.code, adds isActive flag per tenant
+
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const tenantCurrencyEntity = createEntity({
+  table: "read_sample_tenant_currencies",
+  fields: {
+    currencyCode: createTextField({ personal: false, reason: "is_reference_data", required: true }),
+    isActive: createBooleanField({ default: true }),
+  },
+});
+
+export const tenantCurrencyTable = buildEntityTable("tenant-currency", tenantCurrencyEntity);
+```
+
+### src/feature.ts
+
+```ts
+// Money Shared Sample
+// Shows: Shared (global) currencies via r.referenceData(), per-tenant assignment
+//
+// Pattern: Currencies are global master data — tenants pick which ones they use.
+// Use this when: All tenants share the same currency catalog (ISO 4217 etc.)
+//
+// Tables:
+//   currency         — global reference data (seeded from CURRENCY_CATALOG below)
+//   tenantCurrency   — which currencies each tenant may use (with isActive flag)
+//   invoice          — money fields validated against tenantCurrency
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { currencyEntity } from "./entities/currency";
+import { invoiceEntity } from "./entities/invoice";
+import { tenantCurrencyEntity } from "./entities/tenant-currency";
+import { invoiceCreate } from "./handlers/invoice-create.write";
+import { invoiceDetail } from "./handlers/invoice-detail.query";
+import { tenantCurrencyAssign } from "./handlers/tenant-currency-assign.write";
+
+export { currencyEntity } from "./entities/currency";
+export { invoiceEntity } from "./entities/invoice";
+export { tenantCurrencyEntity } from "./entities/tenant-currency";
+
+// All currencies available in this app — seeded as global reference data
+const CURRENCY_CATALOG = [
+  // Standard currencies
+  { code: "EUR", name: "Euro" },
+  { code: "USD", name: "US Dollar" },
+  { code: "GBP", name: "British Pound" },
+  { code: "CHF", name: "Swiss Franc" },
+  { code: "JPY", name: "Japanese Yen" },
+  { code: "SEK", name: "Swedish Krona" },
+  { code: "NOK", name: "Norwegian Krone" },
+  { code: "DKK", name: "Danish Krone" },
+  { code: "PLN", name: "Polish Zloty" },
+  { code: "CZK", name: "Czech Koruna" },
+  { code: "CAD", name: "Canadian Dollar" },
+  { code: "AUD", name: "Australian Dollar" },
+  { code: "NZD", name: "New Zealand Dollar" },
+  { code: "CNY", name: "Chinese Yuan" },
+  { code: "INR", name: "Indian Rupee" },
+  // Custom currencies added by this app
+  { code: "BHD", name: "Bahraini Dinar" },
+  { code: "SAR", name: "Saudi Riyal" },
+  { code: "TRY", name: "Turkish Lira" },
+  { code: "KRW", name: "South Korean Won" },
+  { code: "BRL", name: "Brazilian Real" },
+  { code: "XYZ", name: "Custom Token" },
+] as const;
+
+export const currenciesGlobalFeature = defineFeature("currenciesGlobal", (r) => {
+  const currency = r.entity("currency", currencyEntity);
+  r.entity("tenant-currency", tenantCurrencyEntity);
+  r.entity("invoice", invoiceEntity);
+
+  // Seed global currency table — available for all tenants to pick from
+  r.referenceData(currency, [...CURRENCY_CATALOG], { upsertKey: "code" });
+
+  r.writeHandler(tenantCurrencyAssign);
+  r.writeHandler(invoiceCreate);
+  r.queryHandler(invoiceDetail);
+});
+```
+
+### 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 { invoiceEntity, invoiceTable } from "../entities/invoice";
+import { tenantCurrencyTable } from "../entities/tenant-currency";
+
+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 amount currency against tenant's allowed currencies. This is a
+    // business-rule violation (currency not permitted here), not a missing
+    // entity, so 422 + reason="currency_not_allowed" is the right shape.
+    const amountMissing = await assertExistsIn(ctx.db, tenantCurrencyTable, {
+      field: "currencyCode",
+      value: amountCurrency,
+      where: { isActive: true },
+    });
+    if (amountMissing) {
+      return failUnprocessable("currency_not_allowed", {
+        field: "amountCurrency",
+        value: amountCurrency,
+      });
+    }
+
+    if (shippingCostCurrency) {
+      const shippingMissing = await assertExistsIn(ctx.db, tenantCurrencyTable, {
+        field: "currencyCode",
+        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 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;
+  },
+});
+```
+
+### src/handlers/tenant-currency-assign.write.ts
+
+```ts
+// Assigns an existing currency to a tenant (creates tenantCurrency entry)
+// The currency must exist in the global currency table
+
+import { assertExistsIn, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { currencyTable } from "../entities/currency";
+import { tenantCurrencyEntity, tenantCurrencyTable } from "../entities/tenant-currency";
+
+const tenantCurrencyCrud = createEventStoreExecutor(tenantCurrencyTable, tenantCurrencyEntity, {
+  entityName: "tenant-currency",
+});
+
+export const tenantCurrencyAssign = defineWriteHandler({
+  name: "tenant-currency:assign",
+  schema: z.object({
+    currencyCode: z.string().length(3),
+    isActive: z.boolean().optional(),
+  }),
+  access: { roles: ["Admin"] },
+  handler: async (event, ctx) => {
+    // Validate that the currency exists in the global reference table (no tenantId — global data)
+    const notFound = await assertExistsIn(ctx.db, currencyTable, {
+      field: "code",
+      value: event.payload.currencyCode,
+      entityName: "currency",
+    });
+    if (notFound) return writeFailure(notFound);
+
+    return tenantCurrencyCrud.create(
+      {
+        currencyCode: event.payload.currencyCode,
+        isActive: event.payload.isActive ?? true,
+      },
+      event.user,
+      ctx.db,
+    );
+  },
+});
+```