create-protobase 0.23.13 → 0.23.14

package/dist/templates/real-estate/db/migrations/008_auth_snake_case.sql

@@ -0,0 +1,109 @@
+-- The auth schema changes this version of Protobase needs, written by `protobase auth migration`.
+-- Applied with the project's other migrations; edit or remove statements the project handles differently.
+
+-- Renames the auth store of Protobase 0.6 to snake_case. A store set up with the snake_case names has no "emailVerified"
+-- and is left as it is.
+do $$
+declare
+  constraint_row record;
+begin
+  if not exists (select from information_schema.columns where table_schema = 'auth' and table_name = 'user' and column_name = 'emailVerified') then
+    return;
+  end if;
+
+  alter table "auth"."twoFactor" rename to two_factor;
+  alter table "auth"."signInPolicy" rename to sign_in_policy;
+  alter table "auth"."staffSignIn" rename to staff_sign_in;
+
+  alter table "auth"."user" rename column "emailVerified" to email_verified;
+  alter table "auth"."user" rename column "createdAt" to created_at;
+  alter table "auth"."user" rename column "updatedAt" to updated_at;
+  alter table "auth"."user" rename column "banReason" to ban_reason;
+  alter table "auth"."user" rename column "banExpires" to ban_expires;
+  alter table "auth"."user" rename column "twoFactorEnabled" to two_factor_enabled;
+
+  alter table "auth".session rename column "expiresAt" to expires_at;
+  alter table "auth".session rename column "createdAt" to created_at;
+  alter table "auth".session rename column "updatedAt" to updated_at;
+  alter table "auth".session rename column "ipAddress" to ip_address;
+  alter table "auth".session rename column "userAgent" to user_agent;
+  alter table "auth".session rename column "userId" to user_id;
+  alter table "auth".session rename column "impersonatedBy" to impersonated_by;
+
+  alter table "auth".account rename column "accountId" to account_id;
+  alter table "auth".account rename column "providerId" to provider_id;
+  alter table "auth".account rename column "userId" to user_id;
+  alter table "auth".account rename column "accessToken" to access_token;
+  alter table "auth".account rename column "refreshToken" to refresh_token;
+  alter table "auth".account rename column "idToken" to id_token;
+  alter table "auth".account rename column "accessTokenExpiresAt" to access_token_expires_at;
+  alter table "auth".account rename column "refreshTokenExpiresAt" to refresh_token_expires_at;
+  alter table "auth".account rename column "createdAt" to created_at;
+  alter table "auth".account rename column "updatedAt" to updated_at;
+
+  alter table "auth".verification rename column "expiresAt" to expires_at;
+  alter table "auth".verification rename column "createdAt" to created_at;
+  alter table "auth".verification rename column "updatedAt" to updated_at;
+
+  alter table "auth".jwks rename column "publicKey" to public_key;
+  alter table "auth".jwks rename column "privateKey" to private_key;
+  alter table "auth".jwks rename column "createdAt" to created_at;
+  alter table "auth".jwks rename column "expiresAt" to expires_at;
+
+  alter table "auth".two_factor rename column "backupCodes" to backup_codes;
+  alter table "auth".two_factor rename column "userId" to user_id;
+  alter table "auth".two_factor rename column "failedVerificationCount" to failed_verification_count;
+  alter table "auth".two_factor rename column "lockedUntil" to locked_until;
+
+  alter table "auth".passkey rename column "publicKey" to public_key;
+  alter table "auth".passkey rename column "userId" to user_id;
+  alter table "auth".passkey rename column "credentialID" to credential_id;
+  alter table "auth".passkey rename column "deviceType" to device_type;
+  alter table "auth".passkey rename column "backedUp" to backed_up;
+  alter table "auth".passkey rename column "createdAt" to created_at;
+
+  alter table "auth".sign_in_policy rename column "emailCode" to email_code;
+  alter table "auth".sign_in_policy rename column "twoFactor" to two_factor;
+  alter table "auth".sign_in_policy rename column "staffAccess" to staff_access;
+  alter table "auth".sign_in_policy rename column "platformSignIn" to platform_sign_in;
+  alter table "auth".sign_in_policy rename column "createdAt" to created_at;
+  alter table "auth".sign_in_policy rename column "createdBy" to created_by;
+
+  alter table "auth".staff_sign_in rename column "userId" to user_id;
+  alter table "auth".staff_sign_in rename column "userEmail" to user_email;
+  alter table "auth".staff_sign_in rename column "staffName" to staff_name;
+  alter table "auth".staff_sign_in rename column "staffSubject" to staff_subject;
+  alter table "auth".staff_sign_in rename column "sessionId" to session_id;
+  alter table "auth".staff_sign_in rename column "startedAt" to started_at;
+  alter table "auth".staff_sign_in rename column "expiresAt" to expires_at;
+  alter table "auth".staff_sign_in rename column "endedAt" to ended_at;
+
+  -- A primary key's index takes the new name with it.
+  alter table "auth".two_factor rename constraint "twoFactor_pkey" to two_factor_pkey;
+  alter table "auth".sign_in_policy rename constraint "signInPolicy_pkey" to sign_in_policy_pkey;
+  alter table "auth".staff_sign_in rename constraint "staffSignIn_pkey" to staff_sign_in_pkey;
+  alter table "auth".session rename constraint "session_userId_fkey" to session_user_id_fkey;
+  alter table "auth".account rename constraint "account_userId_fkey" to account_user_id_fkey;
+  alter table "auth".two_factor rename constraint "twoFactor_userId_fkey" to two_factor_user_id_fkey;
+  alter table "auth".passkey rename constraint "passkey_userId_fkey" to passkey_user_id_fkey;
+
+  alter index "auth"."session_userId_idx" rename to session_user_id_idx;
+  alter index "auth"."account_userId_idx" rename to account_user_id_idx;
+  alter index "auth"."twoFactor_secret_idx" rename to two_factor_secret_idx;
+  alter index "auth"."twoFactor_userId_idx" rename to two_factor_user_id_idx;
+  alter index "auth"."passkey_userId_idx" rename to passkey_user_id_idx;
+  alter index "auth"."passkey_credentialID_idx" rename to passkey_credential_id_idx;
+
+  -- Postgres 18 names each not-null constraint after its table and column, as "user_emailVerified_not_null"; earlier
+  -- versions keep no such constraints, so there is nothing to rename there.
+  for constraint_row in
+    select c.conrelid::regclass as table_name, c.conname as old_name, t.relname || '_' || a.attname || '_not_null' as new_name
+    from pg_constraint c
+    join pg_class t on t.oid = c.conrelid
+    join pg_attribute a on a.attrelid = c.conrelid and a.attnum = c.conkey[1]
+    where c.contype = 'n' and t.relnamespace = (select oid from pg_namespace where nspname = 'auth') and c.conname ~ '[A-Z]'
+  loop
+    execute format('alter table %s rename constraint %I to %I', constraint_row.table_name, constraint_row.old_name, constraint_row.new_name);
+  end loop;
+end
+$$;

package/dist/templates/real-estate/db/migrations/009_auth.sql

@@ -0,0 +1,6 @@
+-- The auth schema changes this version of Protobase needs, written by `protobase auth migration`.
+-- Applied with the project's other migrations; edit or remove statements the project handles differently.
+
+alter table "auth"."user" add column if not exists "last_role" text;
+
+alter table "auth"."session" add column if not exists "active_role" text;

package/dist/templates/real-estate/db/migrations/010_auth.sql

@@ -0,0 +1,4 @@
+-- The auth schema changes this version of Protobase needs, written by `protobase migration`.
+-- Applied with the project's other migrations; edit or remove statements the project handles differently.
+
+alter table "auth"."passkey" add column if not exists "rp_id" text;

package/dist/templates/real-estate/db/migrations/011_filter_indexes.sql

@@ -0,0 +1,8 @@
+-- A filter, sort or search reads only columns an index serves.
+create index inspections_condition_idx on maintenance.inspections (organization_id, condition);
+create index lease_tenants_role_idx on leasing.lease_tenants (organization_id, role);
+create index leases_term_idx on leasing.leases (organization_id, term);
+create index rent_charges_outstanding_idx on billing.rent_charges (outstanding);
+create index tenants_first_name_trgm_idx on leasing.tenants using gin (first_name gin_trgm_ops);
+create index tenants_phone_digits_idx on leasing.tenants using gin ((regexp_replace(phone, '[^0-9]', '', 'g')) gin_trgm_ops);
+create index tickets_number_trgm_idx on maintenance.tickets using gin (number gin_trgm_ops);

package/dist/templates/real-estate/db/migrations/012_sort_indexes.sql

@@ -0,0 +1,2 @@
+-- Each sortable column is served alone too, as a list sorted by it is; the tenant is pinned, so it leads.
+create index tenants_last_name_idx on leasing.tenants (organization_id, last_name);

package/dist/templates/real-estate/db/migrations/013_auth_users.sql

@@ -0,0 +1,17 @@
+-- Everyone who signs in is one of the example's users: their Better Auth id is the next core.users id
+-- (`generateUserId` in auth/auth.ts), which tickets name as their assignee, and their row there, in organization 1
+-- where everyone works, comes with their account. The roles they hold in the app live in the auth schema, so the
+-- example's own role column stays empty for them.
+alter table core.users alter column role drop not null;
+
+create function core.add_auth_user() returns trigger language plpgsql as $$
+begin
+  insert into core.users (id, organization_id, email, name)
+  select new.id::integer, 1, new.email, new.name
+  where new.id ~ '^[0-9]+$'
+  on conflict do nothing;
+  return new;
+end
+$$;
+
+create trigger auth_user after insert on auth."user" for each row execute function core.add_auth_user();

package/dist/templates/real-estate/node-types.d.ts

@@ -0,0 +1 @@
+/// <reference types="node" />

package/dist/templates/real-estate/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "real-estate",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "db:migrate": "bun db/migrate.ts",
+    "db:seed:base": "bun seed/base.ts",
+    "db:seed": "bun seed/cli.ts",
+    "db:reset": "bun db/drop.ts && bun db/migrate.ts && bun seed/cli.ts --scale small",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "protobase": "protobase",
+    "build": "protobase build",
+    "serve": "protobase build && protobase serve dist",
+    "dev": "protobase dev"
+  },
+  "dependencies": {
+    "@protobase/cli": ">=0.23.14 <1",
+    "@protobase/layout": ">=0.23.14 <1",
+    "@protobase/schema": ">=0.23.14 <1",
+    "@protobase/server": ">=0.23.14 <1",
+    "@protobase/ui": ">=0.23.14 <1",
+    "better-auth": "^1.7.7",
+    "jose": "^6.2.12",
+    "kysely": "^0.29.6",
+    "pg": "^8.23.1",
+    "postgres": "^3.4.9",
+    "react": "^19.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/pg": "^8.23.1",
+    "@types/react": "^19.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3"
+  }
+}

package/dist/templates/real-estate/protobase.config.ts

@@ -0,0 +1,5 @@
+import * as config from './config'
+import { roles } from './config/roles'
+import { auth, authenticate } from './auth/auth'
+
+export default { config, auth, authenticate, options: { roles } }

package/dist/templates/real-estate/protobase.ui.tsx

@@ -0,0 +1,16 @@
+import { defineUi, type ActionContext } from '@protobase/ui'
+
+/** "Send reminder" on an arrears row: opens a mail to the lease's primary tenant about what is outstanding, with the note it asked for. */
+const remind = async ({ record, client, values }: ActionContext) => {
+  const leaseId = String(record!.lease_id)
+  const signers = await client.list('lease_tenants', { filter: `lease_id = ${leaseId} AND role = "primary"`, pageSize: 1 })
+  const tenantId = signers.items[0]?.tenant_id
+  const tenant = tenantId === undefined ? undefined : await client.get('tenants', String(tenantId))
+  const lease = await client.get('leases', leaseId)
+  const subject = encodeURIComponent(`Rent outstanding on lease ${String(lease.record.number)}`)
+  const outstanding = `€${String(record!.balance)} is outstanding, the oldest since ${String(record!.oldest_due_on)}.`
+  const body = encodeURIComponent(values?.note ? `${outstanding}\n\n${String(values.note)}` : outstanding)
+  window.location.assign(`mailto:${String(tenant?.record.email ?? '')}?subject=${subject}&body=${body}`)
+}
+
+export default defineUi({ actions: { remind } })

package/dist/templates/real-estate/seed/base-organization.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { baseOrganization } from './base-organization'
+
+describe('baseOrganization', () => {
+  it('is organization 1, named after the app, with its city and KvK number left for the owner', () => {
+    expect(baseOrganization('Acme Rentals')).toEqual({ id: 1, name: 'Acme Rentals', slug: 'acme-rentals', city: '', kvk_number: '' })
+  })
+
+  it('makes a slug of any name', () => {
+    expect(baseOrganization('Grachtenhof Vastgoed B.V.').slug).toBe('grachtenhof-vastgoed-b-v')
+    expect(baseOrganization('!!!').slug).toBe('organization')
+  })
+
+  it('refuses an empty name', () => {
+    expect(() => baseOrganization('  ')).toThrow('name')
+  })
+})

package/dist/templates/real-estate/seed/base-organization.ts

@@ -0,0 +1,10 @@
+// Lowercase ASCII words joined by dashes; diacritics are dropped, so Müller becomes muller.
+const slugOf = (name: string) =>
+  name.normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'organization'
+
+/** Organization 1, the one every user works in (auth/auth.ts), named after the app; the owner fills in the rest. */
+export const baseOrganization = (name: string) => {
+  const trimmed = name.trim()
+  if (!trimmed) throw new Error('The organization needs a name: pass --name "<the app name>"')
+  return { id: 1, name: trimmed, slug: slugOf(trimmed), city: '', kvk_number: '' }
+}

package/dist/templates/real-estate/seed/base.ts

@@ -0,0 +1,18 @@
+import { connect } from '../db/connection'
+import { baseOrganization } from './base-organization'
+import { amenities } from './data/reference'
+
+// `db:seed:base [--name <app name>]`: what a new app starts with, the amenities and organization 1. Rows already
+// there stay as they are, so it can run again and after the sample seed (`db:seed`).
+const flag = process.argv.indexOf('--name')
+const organization = baseOrganization(flag === -1 ? 'Real estate' : (process.argv[flag + 1] ?? ''))
+
+const sql = connect({ max: 1 })
+await sql.begin(async (tx) => {
+  await tx`insert into portfolio.amenities ${tx(amenities.map(([code, name]) => ({ code, name })))} on conflict do nothing`
+  await tx`insert into core.organizations ${tx(organization)} on conflict do nothing`
+  // An explicit id leaves the identity sequence behind, so the next organization would take id 1 again.
+  await tx`select setval(pg_get_serial_sequence('core.organizations', 'id'), (select max(id) from core.organizations))`
+})
+await sql.end()
+console.log(`seeded the base data of ${organization.name}`)

package/dist/templates/real-estate/seed/builders/allocation.ts

@@ -0,0 +1,47 @@
+import { DAY, addMonths, firstPeriod, monthOf, windowEnd, windowStart } from '../calendar'
+import { int, pick, rngAt, weighted } from '../rng'
+
+// What the ids of everything under a property depend on: world.ts counts units, leases and tenants with these before
+// any row is built, so they take only the organization's seed and an ordinal.
+
+const YEAR = 365 * DAY
+
+export const propertyShapeAt = (seed: number, ordinal: number) => {
+  const rand = rngAt(seed + 1, ordinal)
+  const kind = weighted(rand, [['single_family', 45], ['apartment_building', 40], ['mixed_use', 15]] as const)
+  const units = kind === 'single_family' ? 1 : kind === 'mixed_use' ? int(rand, 2, 12) : int(rand, 6, 40)
+  return { kind, units }
+}
+
+// Most of the portfolio was under management before the window; about one property in eight joined during it.
+export const propertyAcquiredAt = (seed: number, ordinal: number) => {
+  const rand = rngAt(seed + 2, ordinal)
+  if (rand() < 0.88) return Math.floor(windowStart - rand() * 8 * YEAR)
+  return Math.floor(windowStart + rand() * (windowEnd - windowStart - 120 * DAY))
+}
+
+export type Tenancy = { start: number; end: number | null; term: 'fixed' | 'indefinite'; gapAfter: number }
+
+// The leases of one unit, oldest first, as months: each starts on a first and ends on a last day of a month, and the
+// next starts after a few empty months at most (the longer gaps are renovations). Only leases that reach into the
+// window are kept. An indefinite lease that runs past the window has no end date yet; a fixed one always has one.
+// `unit` is the organization-wide unit ordinal.
+export const tenanciesOf = (seed: number, unit: number, availableFrom: number) => {
+  const rand = rngAt(seed + 6, unit)
+  const tenancies: Tenancy[] = []
+  let start = availableFrom < windowStart ? addMonths(firstPeriod, -int(rand, 1, 96)) : addMonths(monthOf(availableFrom), int(rand, 1, 3))
+  while (start <= windowEnd) {
+    const term = rand() < 0.35 ? 'fixed' : 'indefinite'
+    const months = term === 'fixed' ? pick(rand, [12, 24]) : weighted(rand, [[int(rand, 12, 36), 35], [int(rand, 37, 96), 45], [int(rand, 97, 240), 20]] as const)
+    const next = addMonths(start, months)
+    const lastDay = next - DAY
+    const end = term === 'fixed' || lastDay <= windowEnd ? lastDay : null
+    const gapAfter = weighted(rand, [[0, 55], [1, 25], [2, 12], [int(rand, 3, 5), 8]] as const)
+    if (lastDay >= windowStart) tenancies.push({ start, end, term, gapAfter })
+    start = addMonths(next, gapAfter)
+  }
+  return tenancies
+}
+
+export const coSigned = (seed: number, lease: number) => rngAt(seed + 7, lease)() < 0.3
+

package/dist/templates/real-estate/seed/builders/ledger.ts

@@ -0,0 +1,52 @@
+import { DAY, addMonths, firstPeriod, lastPeriod, monthOf, windowEnd } from '../calendar'
+import { int, pick, rngAt, weighted } from '../rng'
+import type { Org } from '../world'
+import { rentAt, type SeededLease } from './tenancy'
+
+const monthNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
+
+type Payment = { paidOn: number; amountCents: number; method: 'direct_debit' | 'bank_transfer' | 'ideal' }
+
+// How one charge of `amount` due on `due` gets paid, by the lease's kind of payer. Payments after the window's end
+// have not happened yet. The parts of a charge never add up to more than the charge.
+const paymentsFor = (payer: SeededLease['payer'], due: number, amount: number, stopped: boolean, rand: () => number): Payment[] => {
+  const pay = (days: number, cents: number, method: Payment['method']) => ({ paidOn: due + days * DAY, amountCents: cents, method })
+  const transfer = () => pick(rand, ['bank_transfer', 'bank_transfer', 'ideal'] as const)
+  if (stopped) return []
+  if (payer === 'punctual') return [pay(int(rand, 0, 3), amount, rand() < 0.8 ? 'direct_debit' : 'bank_transfer')]
+  if (payer === 'late' || payer === 'defaulter') return [pay(int(rand, 3, 28), amount, transfer())]
+  const kind = weighted(rand, [['late', 60], ['split', 32], ['short', 8]] as const)
+  if (kind === 'late') return [pay(int(rand, 10, 60), amount, transfer())]
+  const part = Math.round(amount * (0.3 + rand() * 0.5))
+  if (kind === 'split') return [pay(int(rand, 5, 30), part, transfer()), pay(int(rand, 31, 90), amount - part, transfer())]
+  return [pay(int(rand, 10, 60), part, transfer())]
+}
+
+/**
+ * The monthly charges of a lease inside the window, each with the payments made on it by the window's end. A
+ * defaulter stops paying for the last two to seven months of the lease (or of the window, while it runs).
+ */
+export const ledgerOf = (org: Org, lease: SeededLease) => {
+  const rand = rngAt(org.seed + 12, lease.ordinal)
+  const { start, end } = lease.tenancy
+  const from = Math.max(firstPeriod, start)
+  const to = end === null ? lastPeriod : Math.min(lastPeriod, monthOf(end))
+  const stopFrom = lease.payer === 'defaulter' ? addMonths(to, -int(rand, 1, 6)) : Infinity
+  const charges = []
+  for (let period = from; period <= to; period = addMonths(period, 1)) {
+    const date = new Date(period)
+    const amountCents = rentAt(lease.startCents, start, period) + lease.serviceCents
+    const payments = paymentsFor(lease.payer, period, amountCents, period >= stopFrom, rand).filter((payment) => payment.paidOn <= windowEnd)
+    charges.push({
+      period,
+      dueOn: period,
+      description: `Rent ${monthNames[date.getUTCMonth()]} ${date.getUTCFullYear()}`,
+      amountCents,
+      paidCents: payments.reduce((sum, payment) => sum + payment.amountCents, 0),
+      payments,
+      // The monthly run bills a week ahead.
+      createdAt: Math.min(period - 7 * DAY + 6 * 3_600_000, windowEnd),
+    })
+  }
+  return charges
+}

package/dist/templates/real-estate/seed/builders/property.ts

@@ -0,0 +1,98 @@
+import { DAY, windowStart } from '../calendar'
+import { buildingNames, buildingPrefixes, firstNames, ownerCompanyWords, streets, surnames } from '../data/names'
+import { iban } from '../iban'
+import { int, pick, rngAt, weighted } from '../rng'
+import type { Org } from '../world'
+import { propertyAcquiredAt, propertyShapeAt } from './allocation'
+
+const YEAR = 365 * DAY
+const letters = 'ABCDEFGHJKLMNPRTVWXZ'
+
+export const ownerAt = (org: Org, ordinal: number) => {
+  const rand = rngAt(org.seed + 3, ordinal)
+  const kind = weighted(rand, [['private', 55], ['company', 25], ['pension_fund', 8], ['housing_association', 12]] as const)
+  const surname = pick(rand, surnames)
+  const name =
+    kind === 'private' ? `${pick(rand, firstNames)} ${surname}`
+    : kind === 'company' ? `${surname.replace(/^(van|de|der|den|el)\s+/i, '').replace(/^\w/, (c) => c.toUpperCase())} ${pick(rand, ownerCompanyWords)} B.V.`
+    : kind === 'pension_fund' ? `Stichting Pensioenfonds ${pick(rand, buildingNames)}`
+    : `Woonstichting ${pick(rand, buildingNames)}`
+  const domain = kind === 'private' ? pick(rand, ['gmail.com', 'outlook.com', 'ziggo.nl', 'kpnmail.nl']) : `${name.toLowerCase().replace(/ b\.v\.$/, '').replace(/[^a-z]+/g, '')}.nl`
+  const fee = kind === 'private' ? int(rand, 700, 900) : kind === 'company' ? int(rand, 500, 650) : int(rand, 350, 500)
+  return {
+    id: org.ownerFirstId + ordinal,
+    name,
+    kind,
+    email: kind === 'private' ? `${name.split(' ')[0]!.toLowerCase()}.${surname.toLowerCase().replace(/[^a-z]+/g, '')}@${domain}` : `beheer@${domain}`,
+    phone: rand() < 0.8 ? `+31 ${int(rand, 10, 79)} ${int(rand, 1_000_000, 9_999_999)}` : null,
+    iban: iban(rand),
+    feePercent: fee / 100,
+    createdAt: Math.floor(windowStart - int(rand, 1, 9) * YEAR),
+  }
+}
+
+const builtYear = (rand: () => number) =>
+  weighted(rand, [[int(rand, 1890, 1940), 25], [int(rand, 1946, 1979), 30], [int(rand, 1980, 2005), 30], [int(rand, 2006, 2024), 15]] as const)
+
+export const propertyAt = (org: Org, ordinal: number) => {
+  const { kind, units } = propertyShapeAt(org.seed, ordinal)
+  const rand = rngAt(org.seed + 4, ordinal)
+  const [city, lat, lng, postalFrom, postalTo, rentPerM2] = weighted(rand, org.cities.map((entry, index) => [entry, index === 0 ? 40 : 12] as const))
+  const street = pick(rand, streets)
+  const number = int(rand, 1, 240)
+  const houseNumber = kind === 'single_family' && rand() < 0.1 ? `${number}${pick(rand, ['a', 'b'])}` : String(number)
+  const building = `${pick(rand, buildingPrefixes)} ${pick(rand, buildingNames)}`
+  return {
+    id: org.propertyFirstId + ordinal,
+    ownerId: org.ownerFirstId + Math.floor(rand() ** 1.7 * org.ownerCount),
+    kind,
+    units,
+    name: kind === 'single_family' ? `${street} ${houseNumber}` : building,
+    shortName: kind === 'single_family' ? `${street} ${houseNumber}` : building.split(' ').slice(1).join(' '),
+    street,
+    houseNumber,
+    postalCode: `${int(rand, postalFrom, postalTo)} ${pick(rand, [...letters])}${pick(rand, [...letters])}`,
+    city,
+    latitude: (lat + (rand() - 0.5) * 0.06).toFixed(6),
+    longitude: (lng + (rand() - 0.5) * 0.09).toFixed(6),
+    rentPerM2,
+    builtYear: builtYear(rand),
+    createdAt: propertyAcquiredAt(org.seed, ordinal),
+  }
+}
+
+export type SeededProperty = ReturnType<typeof propertyAt>
+
+const energyLabels = ['A++++', 'A+++', 'A++', 'A+', 'A', 'B', 'C', 'D', 'E', 'F', 'G'] as const
+
+// Newer buildings and renovated older ones carry better labels.
+const energyLabel = (builtYear: number, rand: () => number) => {
+  const base = builtYear >= 2015 ? 2 : builtYear >= 2000 ? 4 : builtYear >= 1980 ? 6 : 7
+  return energyLabels[Math.max(0, Math.min(energyLabels.length - 1, base + int(rand, -2, 2)))]!
+}
+
+// The unit's slot inside its property; `unit` is the organization-wide unit ordinal.
+export const unitAt = (org: Org, property: SeededProperty, unit: number) => {
+  const slot = unit - org.unitStarts[property.id - org.propertyFirstId]!
+  const rand = rngAt(org.seed + 5, unit)
+  const perFloor = property.kind === 'mixed_use' ? 3 : 4
+  // Mixed-use blocks have shops on the ground floor, so their homes start on the first.
+  const floor = property.kind === 'single_family' ? 0 : Math.floor(slot / perFloor) + (property.kind === 'mixed_use' ? 1 : 0)
+  const area = property.kind === 'single_family' ? int(rand, 85, 165) : int(rand, 38, 115)
+  const bedrooms = area < 45 ? int(rand, 0, 1) : area < 70 ? 2 : area < 100 ? 3 : 4
+  const marketFactor = 0.9 + rand() * 0.25
+  return {
+    id: org.unitFirstId + unit,
+    label: property.kind === 'single_family' ? property.shortName : `${property.shortName} ${floor}.${String((slot % perFloor) + 1).padStart(2, '0')}`,
+    floor,
+    bedrooms,
+    area,
+    energyLabel: energyLabel(property.builtYear, rand),
+    // 2026 market rent, in whole euros.
+    baseRentCents: Math.round(area * property.rentPerM2 * marketFactor * (property.kind === 'single_family' ? 0.92 : 1)) * 100,
+    topFloor: property.kind !== 'single_family' && slot >= property.units - perFloor,
+    createdAt: property.createdAt,
+  }
+}
+
+export type SeededUnit = ReturnType<typeof unitAt>

package/dist/templates/real-estate/seed/builders/tenancy.ts

@@ -0,0 +1,99 @@
+import { DAY, addMonths, lastPeriod, monthOf, windowEnd } from '../calendar'
+import { firstNames, surnames } from '../data/names'
+import { slugify } from '../format'
+import { iban } from '../iban'
+import { int, pick, rngAt, weighted } from '../rng'
+import type { Org } from '../world'
+import type { Tenancy } from './allocation'
+import type { SeededProperty, SeededUnit } from './property'
+
+const YEAR = 365 * DAY
+
+/** Let when a lease covers the window's last day, else vacant, or under renovation in a long gap. */
+export const unitStatus = (tenancies: Tenancy[]) => {
+  const today = Math.floor(windowEnd / DAY) * DAY
+  if (tenancies.some((tenancy) => tenancy.start <= today && (tenancy.end === null || tenancy.end >= today))) return 'let'
+  const before = tenancies.filter((tenancy) => tenancy.start <= today).at(-1)
+  return before && before.gapAfter >= 3 ? 'renovation' : 'vacant'
+}
+
+// The yearly rent increase on 1 July, in the range Dutch free-sector leases allowed.
+const increases: Record<number, number> = { 2016: 0.025, 2017: 0.025, 2018: 0.03, 2019: 0.03, 2020: 0.026, 2021: 0, 2022: 0.033, 2023: 0.055, 2024: 0.055, 2025: 0.041, 2026: 0.044 }
+
+/** The rent in cents a lease starting at `startCents` charges for `period` (a month), after every July increase since. */
+export const rentAt = (startCents: number, start: number, period: number) => {
+  let rent = startCents
+  for (let year = new Date(start).getUTCFullYear(); year <= new Date(period).getUTCFullYear(); year++) {
+    const july = Date.UTC(year, 6, 1)
+    if (july > start && july <= period) rent = Math.round(rent * (1 + (increases[year] ?? 0.025)))
+  }
+  return rent
+}
+
+// `lease` is the organization-wide lease ordinal, `index` the lease's position among its unit's leases.
+export const leaseAt = (org: Org, property: SeededProperty, unit: SeededUnit, unitOrdinal: number, index: number, tenancy: Tenancy) => {
+  const lease = org.leaseStarts[unitOrdinal]! + index
+  const rand = rngAt(org.seed + 8, lease)
+  // New leases follow the market: the 2026 rent, about 3.5% less for every year before.
+  const startCents = Math.round((unit.baseRentCents * 0.965 ** ((lastPeriod - tenancy.start) / YEAR)) / 100) * 100
+  const lastMonth = tenancy.end === null ? lastPeriod : Math.min(lastPeriod, monthOf(tenancy.end))
+  const serviceCents = property.kind === 'single_family' ? 0 : int(rand, 9, 24) * 500
+  const signedAt = tenancy.start - int(rand, 14, 50) * DAY - int(rand, 9, 17) * 3_600_000
+  const notice = tenancy.term === 'indefinite' && tenancy.end !== null ? addMonths(monthOf(tenancy.end), -int(rand, 1, 3)) + int(rand, 0, 20) * DAY : null
+  return {
+    id: org.leaseFirstId + lease,
+    ordinal: lease,
+    number: `HC-${new Date(tenancy.start).getUTCFullYear()}-${String(lease + 1).padStart(6, '0')}`,
+    unitId: unit.id,
+    tenancy,
+    startCents,
+    rentCents: rentAt(startCents, tenancy.start, lastMonth),
+    serviceCents,
+    notice,
+    // Late payers are few: the arrears view should have something to show, not everything.
+    payer: weighted(rand, [['punctual', 74], ['late', 17], ['chronic', 6], ['defaulter', 3]] as const),
+    createdAt: signedAt,
+    updatedAt: notice ?? signedAt,
+  }
+}
+
+export type SeededLease = ReturnType<typeof leaseAt>
+
+const providers = ['gmail.com', 'outlook.com', 'hotmail.com', 'ziggo.nl', 'kpnmail.nl', 'icloud.com', 'live.nl']
+
+// The tenants of a lease: the primary tenant first, then a co-signer when there is one.
+export const tenantsOf = (org: Org, lease: SeededLease) => {
+  const first = org.tenantStarts[lease.ordinal]!
+  const count = org.tenantStarts[lease.ordinal + 1]! - first
+  return Array.from({ length: count }, (_, slot) => {
+    const rand = rngAt(org.seed + 9, first + slot)
+    const firstName = pick(rand, firstNames)
+    const lastName = pick(rand, surnames)
+    const age = weighted(rand, [[int(rand, 20, 29), 40], [int(rand, 30, 44), 35], [int(rand, 45, 64), 18], [int(rand, 65, 80), 7]] as const)
+    return {
+      id: org.tenantFirstId + first + slot,
+      role: slot === 0 ? 'primary' : 'co_signer',
+      firstName,
+      lastName,
+      email: `${slugify(firstName)}.${slugify(lastName)}${rand() < 0.4 ? int(rand, 1, 99) : ''}@${pick(rand, providers)}`,
+      phone: rand() < 0.9 ? `+31 6 ${int(rand, 10_000_000, 99_999_999)}` : null,
+      dateOfBirth: lease.tenancy.start - age * YEAR - int(rand, 0, 364) * DAY,
+      iban: iban(rand),
+      // Landlords ask for an income of about four times the rent; a co-signer adds to it.
+      incomeCents: Math.round((lease.startCents * (slot === 0 ? 3 + rand() * 2.5 : 1 + rand() * 2)) / 100) * 100,
+      createdAt: lease.createdAt,
+    }
+  })
+}
+
+/** The deposit of a lease: two months of its first rent, returned (sometimes in part) after it ends. */
+export const depositFor = (org: Org, lease: SeededLease) => {
+  const rand = rngAt(org.seed + 11, lease.ordinal)
+  const amountCents = lease.startCents * 2
+  const receivedOn = lease.createdAt + int(rand, 1, 7) * DAY
+  const returnedOn = lease.tenancy.end === null ? null : lease.tenancy.end + int(rand, 14, 42) * DAY
+  if (returnedOn === null || returnedOn > windowEnd) return { amountCents, receivedOn, status: 'held', returnedCents: 0, returnedOn: null }
+  const status = weighted(rand, [['returned', 85], ['partially_returned', 12], ['withheld', 3]] as const)
+  const returnedCents = status === 'returned' ? amountCents : status === 'withheld' ? 0 : Math.round((amountCents * (0.3 + rand() * 0.6)) / 100) * 100
+  return { amountCents, receivedOn, status, returnedCents, returnedOn }
+}