/**
 * Billing computation pipeline.
 *
 * Public entry points:
 *   - computeInvoiceDraft({ zitadelOrgId, year, month, locale? })
 *     Builds an in-memory InvoiceDraft from the live signals
 *     (LiteLLM spend, Threema relay usage, tenant skill events,
 *     lifecycle, suspension). Does NOT persist or render the PDF.
 *
 *   - generateInvoice({ zitadelOrgId, year, month, locale?, dryRun? })
 *     Calls computeInvoiceDraft, renders the PDF, persists the
 *     invoice transactionally. Returns the persisted Invoice
 *     (or the draft if dryRun=true).
 *
 * Design choices:
 *
 * - All compute is over UTC calendar days. "Active during day D"
 *   means the tenant existed and was not fully suspended at some
 *   moment in [D 00:00 UTC, D+1 00:00 UTC). This matches the
 *   skill billing rule ("same-day toggle = 1 day") for monthly
 *   fee proration too.
 *
 * - Computation is independent of persistence. Callers can preview
 *   without committing (the admin generate form does this on first
 *   click), and the same compute path is reused when committing.
 *
 * - The compute path collects warnings rather than throwing on
 *   recoverable issues (missing LiteLLM team for a tenant, etc.).
 *   The UI surfaces these to the admin before they confirm.
 */

import type {
  Invoice,
  InvoiceBillingSnapshot,
  InvoiceDraft,
  InvoiceLine,
  InvoiceLineKind,
  InvoicePaymentMethod,
  PiecedTenant,
  PlatformPricing,
  SkillPricing,
  TenantBillingLifecycle,
  TenantSkillEvent,
  TenantSuspensionEvent,
} from "@/types";
import {
  createInvoice,
  getInvoiceById,
  getOrgBilling,
  getOrgBillingConfig,
  getPlatformPricing,
  getTenantBillingLifecycle,
  listSkillEventsForTenant,
  listSkillPricing,
  listSuspensionEventsForTenant,
  tenantHasSetupFeeBilled,
  tenantSkillHasBeenBilled,
  updateInvoicePdf,
} from "./db";
import { listTenants } from "./k8s";
import { getTeamSpendLogsV2 } from "./litellm";
import { getUsage as getThreemaUsage } from "./threema-relay";
import { renderInvoicePdf } from "./billing-pdf";
import { sendInvoiceIssuedEmail } from "./email";
import { formatLineDescription } from "./billing-i18n";

// ---------------------------------------------------------------------------
// Period helpers
// ---------------------------------------------------------------------------

/**
 * Returns the [periodStart, periodEnd] inclusive calendar dates for
 * the given month, plus the count of days in the month.
 *
 * Dates returned as ISO `YYYY-MM-DD` strings (no time). Convertible
 * to UTC midnight via `new Date(`${date}T00:00:00Z`)`.
 */
export function monthBounds(year: number, month: number): {
  periodStart: string;
  periodEnd: string;
  daysInMonth: number;
} {
  if (month < 1 || month > 12) throw new Error(`Invalid month: ${month}`);
  const start = new Date(Date.UTC(year, month - 1, 1));
  // Day 0 of next month = last day of this month
  const end = new Date(Date.UTC(year, month, 0));
  return {
    periodStart: start.toISOString().split("T")[0],
    periodEnd: end.toISOString().split("T")[0],
    daysInMonth: end.getUTCDate(),
  };
}

function isoDate(d: Date): string {
  return d.toISOString().split("T")[0];
}

function dueDate(periodEnd: string, netDays: number = 30): string {
  // due_at = period_end + netDays
  const d = new Date(`${periodEnd}T00:00:00Z`);
  d.setUTCDate(d.getUTCDate() + netDays);
  return isoDate(d);
}

// ---------------------------------------------------------------------------
// Day-set computation (calendar-day model, UTC)
// ---------------------------------------------------------------------------

/**
 * Iterates UTC calendar days in [periodStart, periodEnd] inclusive.
 * Yields { date: 'YYYY-MM-DD', dayStartMs, dayEndMs } where dayEnd
 * is exclusive (next-day-midnight UTC).
 */
function* iterDays(periodStart: string, periodEnd: string) {
  const start = new Date(`${periodStart}T00:00:00Z`).getTime();
  const end = new Date(`${periodEnd}T00:00:00Z`).getTime();
  for (let t = start; t <= end; t += 86_400_000) {
    yield {
      date: isoDate(new Date(t)),
      dayStartMs: t,
      dayEndMs: t + 86_400_000,
    };
  }
}

/**
 * Was the tenant "running" (created, not deleted, not suspended) at
 * any moment in the half-open interval [dayStartMs, dayEndMs)?
 *
 * Inputs: tenant lifecycle and the timeline of suspension events
 * sorted ascending by occurredAt.
 *
 * The state-at-day-start is reconstructed from suspension events
 * BEFORE the day. If the count of suspension events before the day
 * is odd, the tenant was suspended at day start (because we record
 * suspend then resume, so an odd prefix-count means the last
 * recorded transition is "suspended"). This is robust as long as
 * events are correctly ordered.
 *
 * Actually we use the actual event kinds from the events list,
 * not the parity heuristic — the heuristic is documentation for
 * intuition.
 */
function activeDuringDay(
  lifecycle: TenantBillingLifecycle,
  suspensionEvents: TenantSuspensionEvent[],
  dayStartMs: number,
  dayEndMs: number
): boolean {
  // Lifecycle gate: tenant must have existed during some part of the day.
  const createdMs = new Date(lifecycle.createdAt).getTime();
  const deletedMs = lifecycle.deletedAt
    ? new Date(lifecycle.deletedAt).getTime()
    : Infinity;
  if (createdMs >= dayEndMs) return false;
  if (deletedMs <= dayStartMs) return false;
  // Effective existence window within this day
  const existsFrom = Math.max(createdMs, dayStartMs);
  const existsTo = Math.min(deletedMs, dayEndMs);
  if (existsFrom >= existsTo) return false;

  // Determine suspended state at existsFrom by replaying events.
  // Initial state at lifecycle.createdAt is 'running' (we don't
  // record an explicit 'created → running' event; this is the
  // implicit baseline).
  let suspended = false;
  for (const e of suspensionEvents) {
    const ts = new Date(e.occurredAt).getTime();
    if (ts > existsFrom) break;
    suspended = e.eventKind === "suspended";
  }

  // Walk events from existsFrom to existsTo. If at any moment the
  // tenant is running, the day counts.
  if (!suspended) return true;
  for (const e of suspensionEvents) {
    const ts = new Date(e.occurredAt).getTime();
    if (ts <= existsFrom) continue;
    if (ts >= existsTo) break;
    if (e.eventKind === "resumed") return true;
  }
  return false;
}

/**
 * Was the skill 'enabled' at any moment in the day?
 *
 * Same shape as activeDuringDay but driven by skill events instead
 * of suspension events.
 *
 * Important: callers must include events from before periodStart in
 * `prevState` (state at day start), since a skill enabled three
 * months ago and never disabled has no events in the billing
 * window but is still enabled.
 */
function skillActiveDuringDay(
  events: TenantSkillEvent[],
  initiallyEnabled: boolean,
  dayStartMs: number,
  dayEndMs: number
): boolean {
  let enabled = initiallyEnabled;
  // First, replay events that occurred AT OR BEFORE dayStartMs to
  // get the state at day start.
  for (const e of events) {
    const ts = new Date(e.occurredAt).getTime();
    if (ts > dayStartMs) break;
    enabled = e.eventKind === "enabled";
  }
  if (enabled) return true;
  // Walk events in [dayStart, dayEnd). If any 'enabled' event
  // appears, the day counts.
  for (const e of events) {
    const ts = new Date(e.occurredAt).getTime();
    if (ts <= dayStartMs) continue;
    if (ts >= dayEndMs) break;
    if (e.eventKind === "enabled") return true;
  }
  return false;
}

// ---------------------------------------------------------------------------
// Rounding
// ---------------------------------------------------------------------------

/** Round to 2dp, half-up. */
function round2(n: number): number {
  return Math.round(n * 100) / 100;
}

// ---------------------------------------------------------------------------
// VAT logic
// ---------------------------------------------------------------------------

const EU_COUNTRIES = new Set([
  "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR",
  "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL",
  "PL", "PT", "RO", "SK", "SI", "ES", "SE",
]);

/**
 * Determine VAT rate from billing address and the platform default.
 * See README for the legal interpretation; this implements the
 * defaults you confirmed:
 *
 *   - CH or LI:        platform_pricing.vat_rate_chli (default 8.10)
 *   - EU + VAT number: 0% (reverse charge — B2B)
 *   - EU without VAT:  CH MWST (B2C consumer, we charge our rate)
 *   - other:           0% (export of services)
 */
function vatRateForAddress(
  snapshot: InvoiceBillingSnapshot,
  platformPricing: PlatformPricing
): { rate: number; note: string | null } {
  const country = snapshot.country?.toUpperCase().trim() ?? "";
  if (country === "CH" || country === "LI") {
    return { rate: platformPricing.vatRateChli, note: null };
  }
  if (EU_COUNTRIES.has(country)) {
    if (snapshot.vatNumber && snapshot.vatNumber.trim().length > 0) {
      return {
        rate: 0,
        note:
          "Steuerschuldnerschaft des Leistungsempfängers / Reverse charge — VAT to be accounted for by the recipient.",
      };
    }
    return { rate: platformPricing.vatRateChli, note: null };
  }
  return { rate: 0, note: "Export of services — VAT not applicable." };
}

// ---------------------------------------------------------------------------
// Locale default
// ---------------------------------------------------------------------------

/**
 * Pick a default invoice locale from the billing country. Admins
 * can override at generation time. We default to German for
 * CH/LI/AT/DE; French for FR/BE/LU; Italian for IT; English
 * otherwise.
 */
export function defaultLocaleForCountry(country: string): string {
  const c = (country || "").toUpperCase().trim();
  if (["CH", "LI", "AT", "DE"].includes(c)) return "de";
  if (["FR", "BE", "LU"].includes(c)) return "fr";
  if (c === "IT") return "it";
  return "en";
}

// ---------------------------------------------------------------------------
// Tenant signal collectors
// ---------------------------------------------------------------------------

/**
 * Sum AI usage spend for a tenant over the billing period via
 * LiteLLM. Returns the CHF total (already in CHF — LiteLLM stores
 * costs after the platform's USD→CHF conversion) and the request
 * count for the metadata.
 *
 * Tolerates missing litellmTeamId on the tenant: such tenants are
 * skipped and the warning is surfaced upstream.
 */
async function collectAiUsage(
  tenant: PiecedTenant,
  periodStart: string,
  periodEnd: string
): Promise<{ spendChf: number; requestCount: number } | null> {
  const teamId = tenant.status?.litellmTeamId;
  if (!teamId) return null;
  const keyAlias = tenant.metadata.name;
  let spendChf = 0;
  let requestCount = 0;
  let page = 1;
  // 50-page cap matches the existing usage route's defensive cap.
  while (page <= 50) {
    const result = await getTeamSpendLogsV2(
      teamId,
      periodStart,
      periodEnd,
      page,
      100,
      keyAlias
    );
    const rows: any[] = result.data ?? [];
    for (const r of rows) {
      spendChf += Number(r.spend ?? 0);
      requestCount += 1;
    }
    if (page >= (result.total_pages || 1)) break;
    page++;
  }
  return { spendChf: round2(spendChf), requestCount };
}

/**
 * Sum Threema messages (in + out) for the tenant over the period.
 * Returns null if the relay refuses or the tenant has no Threema
 * package — billing is skipped silently in that case.
 */
async function collectThreemaUsage(
  tenant: PiecedTenant,
  periodStart: string,
  periodEnd: string
): Promise<{ inCount: number; outCount: number } | null> {
  const packages = tenant.spec.packages ?? [];
  if (!packages.includes("threema")) return null;
  // threema-relay.getUsage takes Date params, not strings, and
  // returns a discriminated RelayResult<UsageBreakdown> — the
  // `ok` discriminant must be checked before reading the totals.
  // Period end is exclusive in the relay's API; pass the next-day
  // midnight UTC to capture the full last day of the period.
  const from = new Date(`${periodStart}T00:00:00Z`);
  const to = new Date(`${periodEnd}T00:00:00Z`);
  to.setUTCDate(to.getUTCDate() + 1);
  const result = await getThreemaUsage(tenant.metadata.name, from, to).catch(
    () => null
  );
  if (!result || !result.ok) return null;
  return {
    inCount: Number(result.totals?.in ?? 0),
    outCount: Number(result.totals?.out ?? 0),
  };
}

// ---------------------------------------------------------------------------
// Per-tenant line builders
// ---------------------------------------------------------------------------

async function buildTenantLines(opts: {
  tenant: PiecedTenant;
  periodStart: string;
  periodEnd: string;
  daysInMonth: number;
  platformPricing: PlatformPricing;
  skillPricing: SkillPricing[];
  locale: string;
  warnings: string[];
  displayOrderOffset: number;
}): Promise<Omit<InvoiceLine, "id" | "invoiceId">[]> {
  const {
    tenant,
    periodStart,
    periodEnd,
    daysInMonth,
    platformPricing,
    skillPricing,
    locale,
    warnings,
  } = opts;
  let displayOrder = opts.displayOrderOffset;
  const tenantName = tenant.metadata.name;
  const lines: Omit<InvoiceLine, "id" | "invoiceId">[] = [];

  // Lifecycle & suspension events — required for monthly proration.
  const lifecycle = await getTenantBillingLifecycle(tenantName);
  if (!lifecycle) {
    warnings.push(
      `Tenant "${tenantName}" has no billing lifecycle row — run the Phase 1 backfill.`
    );
    return lines;
  }

  // Period interval in millis (extended by one day on each side as
  // buffer for events that occur at month boundaries).
  const periodStartMs = new Date(`${periodStart}T00:00:00Z`).getTime();
  const periodEndMs = new Date(`${periodEnd}T00:00:00Z`).getTime() + 86_400_000;

  const suspensionEvents = await listSuspensionEventsForTenant(
    tenantName,
    new Date(periodStartMs - 365 * 86_400_000), // look back a year for state-at-start
    new Date(periodEndMs)
  );

  // --- tenant_monthly (prorated, suspended days excluded) -------------------
  if (platformPricing.tenantMonthlyFeeChf > 0) {
    let billableDays = 0;
    let suspendedDays = 0;
    for (const day of iterDays(periodStart, periodEnd)) {
      if (activeDuringDay(lifecycle, suspensionEvents, day.dayStartMs, day.dayEndMs)) {
        billableDays++;
      } else {
        // Distinguish "not yet existed / deleted" from "suspended"
        // for the metadata audit trail. Cheap re-check.
        const createdMs = new Date(lifecycle.createdAt).getTime();
        const deletedMs = lifecycle.deletedAt
          ? new Date(lifecycle.deletedAt).getTime()
          : Infinity;
        if (createdMs < day.dayEndMs && deletedMs > day.dayStartMs) {
          suspendedDays++;
        }
      }
    }
    if (billableDays > 0) {
      const unit = platformPricing.tenantMonthlyFeeChf / daysInMonth;
      const amount = round2(unit * billableDays);
      const metadata = {
        billable_days: billableDays,
        suspended_days: suspendedDays,
        days_in_month: daysInMonth,
      };
      lines.push({
        tenantName,
        kind: "tenant_monthly",
        description: formatLineDescription(
          { kind: "tenant_monthly", tenantName, metadata },
          locale
        ),
        quantity: billableDays,
        unitLabel: "days",
        unitPriceChf: round2(unit * 1e5) / 1e5,
        amountChf: amount,
        metadata,
        displayOrder: displayOrder++,
      });
    }
  }

  // --- tenant_setup (first invoice only) -----------------------------------
  if (platformPricing.tenantSetupFeeChf > 0) {
    const alreadyBilled = await tenantHasSetupFeeBilled(tenantName);
    if (!alreadyBilled) {
      lines.push({
        tenantName,
        kind: "tenant_setup",
        description: formatLineDescription(
          { kind: "tenant_setup", tenantName, metadata: null },
          locale
        ),
        quantity: 1,
        unitLabel: null,
        unitPriceChf: platformPricing.tenantSetupFeeChf,
        amountChf: round2(platformPricing.tenantSetupFeeChf),
        metadata: null,
        displayOrder: displayOrder++,
      });
    }
  }

  // --- ai_usage --------------------------------------------------------------
  const aiUsage = await collectAiUsage(tenant, periodStart, periodEnd).catch(
    (e) => {
      warnings.push(
        `AI usage fetch failed for ${tenantName}: ${e instanceof Error ? e.message : String(e)}`
      );
      return null;
    }
  );
  if (aiUsage === null && tenant.status?.litellmTeamId) {
    // teamId exists but fetch returned null — already warned above
  } else if (aiUsage === null) {
    warnings.push(
      `Tenant ${tenantName} has no LiteLLM team yet — AI usage skipped.`
    );
  } else if (aiUsage.spendChf > 0) {
    const aiMetadata = {
      litellm_key_alias: tenantName,
      spend_chf: aiUsage.spendChf,
      requests: aiUsage.requestCount,
    };
    lines.push({
      tenantName,
      kind: "ai_usage",
      description: formatLineDescription(
        { kind: "ai_usage", tenantName, metadata: aiMetadata },
        locale
      ),
      quantity: 1,
      unitLabel: null,
      unitPriceChf: aiUsage.spendChf,
      amountChf: aiUsage.spendChf,
      metadata: aiMetadata,
      displayOrder: displayOrder++,
    });
  }

  // --- threema_messages -----------------------------------------------------
  if (platformPricing.threemaMessageChf > 0) {
    const threema = await collectThreemaUsage(tenant, periodStart, periodEnd);
    if (threema && (threema.inCount + threema.outCount) > 0) {
      const total = threema.inCount + threema.outCount;
      const threemaMetadata = {
        in_count: threema.inCount,
        out_count: threema.outCount,
        total_count: total,
      };
      lines.push({
        tenantName,
        kind: "threema_messages",
        description: formatLineDescription(
          { kind: "threema_messages", tenantName, metadata: threemaMetadata },
          locale
        ),
        quantity: total,
        unitLabel: "msgs",
        unitPriceChf: platformPricing.threemaMessageChf,
        amountChf: round2(total * platformPricing.threemaMessageChf),
        metadata: threemaMetadata,
        displayOrder: displayOrder++,
      });
    }
  }

  // --- skill_usage ----------------------------------------------------------
  // For each priced skill, count distinct UTC days the skill was
  // enabled during the period.
  if (skillPricing.length > 0) {
    // Fetch all skill events for the tenant within the period plus
    // a long lookback so we can determine state-at-period-start.
    // The state-at-day-start logic in skillActiveDuringDay walks
    // these events forward.
    const allEvents = await listSkillEventsForTenant(
      tenantName,
      new Date(0),
      new Date(periodEndMs)
    );
    for (const sp of skillPricing) {
      const skillEvents = allEvents.filter((e) => e.skillId === sp.skillId);
      // Skip cheaply if no events ever existed for this skill on
      // this tenant.
      if (skillEvents.length === 0) continue;
      // Initial state assumption: false. The very first event is
      // always 'enabled' (we only record toggles, and the implicit
      // pre-toggle state for a never-seen skill is 'disabled').
      let billableDays = 0;
      for (const day of iterDays(periodStart, periodEnd)) {
        if (skillActiveDuringDay(skillEvents, false, day.dayStartMs, day.dayEndMs)) {
          billableDays++;
        }
      }
      if (billableDays > 0) {
        // Setup fee fires once per (tenant, skill) — before the
        // usage line so it appears above it on the PDF.
        if (sp.setupFeeChf > 0) {
          const alreadyBilled = await tenantSkillHasBeenBilled(
            tenantName,
            sp.skillId
          );
          if (!alreadyBilled) {
            const setupMetadata = { skill_id: sp.skillId };
            lines.push({
              tenantName,
              kind: "skill_setup",
              description: formatLineDescription(
                { kind: "skill_setup", tenantName, metadata: setupMetadata },
                locale
              ),
              quantity: 1,
              unitLabel: null,
              unitPriceChf: sp.setupFeeChf,
              amountChf: round2(sp.setupFeeChf),
              metadata: setupMetadata,
              displayOrder: displayOrder++,
            });
          }
        }
        const skillMetadata = {
          skill_id: sp.skillId,
          billable_days: billableDays,
          event_count: skillEvents.length,
        };
        lines.push({
          tenantName,
          kind: "skill_usage",
          description: formatLineDescription(
            { kind: "skill_usage", tenantName, metadata: skillMetadata },
            locale
          ),
          quantity: billableDays,
          unitLabel: "days",
          unitPriceChf: sp.dailyPriceChf,
          amountChf: round2(billableDays * sp.dailyPriceChf),
          metadata: skillMetadata,
          displayOrder: displayOrder++,
        });
      }
    }
  }

  return lines;
}

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

export async function computeInvoiceDraft(opts: {
  zitadelOrgId: string;
  year: number;
  month: number;
  locale?: string;
  paymentMethod?: InvoicePaymentMethod;
}): Promise<InvoiceDraft> {
  const { zitadelOrgId, year, month } = opts;
  const { periodStart, periodEnd, daysInMonth } = monthBounds(year, month);
  const warnings: string[] = [];

  // 1. Billing address. Required — without it we can't produce a
  //    valid invoice.
  const orgBilling = await getOrgBilling(zitadelOrgId);
  if (!orgBilling) {
    throw new Error(
      `Org ${zitadelOrgId} has no billing address on file. ` +
        `The customer must complete /settings/billing before an invoice can be issued.`
    );
  }
  const snapshot: InvoiceBillingSnapshot = {
    companyName: orgBilling.companyName,
    streetAddress: orgBilling.streetAddress,
    postalCode: orgBilling.postalCode,
    city: orgBilling.city,
    country: orgBilling.country,
    vatNumber: orgBilling.vatNumber ?? null,
    billingEmail: orgBilling.billingEmail,
    notes: orgBilling.notes ?? null,
  };

  // 2. Platform pricing + skill prices.
  const platformPricing = await getPlatformPricing();
  const skillPricing = await listSkillPricing();

  // 3. Find all tenants for this org. We list from K8s (source of
  //    truth) and filter by the zitadel-org-id label.
  const allTenants = await listTenants();
  const orgTenants = allTenants.filter(
    (t) => t.metadata.labels?.["pieced.ch/zitadel-org-id"] === zitadelOrgId
  );
  if (orgTenants.length === 0) {
    warnings.push(`No tenants found for org ${zitadelOrgId}.`);
  }

  // 4. Build lines, grouped per tenant (display order preserved).
  // Locale must be resolved before line construction since the
  // descriptions are localized at compute time.
  const locale = opts.locale ?? defaultLocaleForCountry(snapshot.country);
  const lines: Omit<InvoiceLine, "id" | "invoiceId">[] = [];
  let nextDisplayOrder = 0;
  // Sort tenants by name for stable line ordering across regenerations.
  orgTenants.sort((a, b) => a.metadata.name.localeCompare(b.metadata.name));
  for (const tenant of orgTenants) {
    const tenantLines = await buildTenantLines({
      tenant,
      periodStart,
      periodEnd,
      daysInMonth,
      platformPricing,
      skillPricing,
      locale,
      warnings,
      displayOrderOffset: nextDisplayOrder,
    });
    lines.push(...tenantLines);
    nextDisplayOrder += tenantLines.length;
  }

  // 5. Subtotal & VAT.
  const subtotal = round2(lines.reduce((acc, l) => acc + l.amountChf, 0));
  const vat = vatRateForAddress(snapshot, platformPricing);
  const vatAmount = round2((subtotal * vat.rate) / 100);
  const total = round2(subtotal + vatAmount);
  if (vat.note) warnings.push(vat.note);

  // 6. Payment method: prefer pay-by-invoice if the admin enabled
  //    it for the org, otherwise default to invoice. Card payment
  //    is wired in Phase 4 — for Phase 2 every invoice is 'invoice'.
  const orgConfig = await getOrgBillingConfig(zitadelOrgId);
  const paymentMethod: InvoicePaymentMethod =
    opts.paymentMethod ?? (orgConfig.payByInvoice ? "invoice" : "invoice");

  return {
    zitadelOrgId,
    periodStart,
    periodEnd,
    dueAt: dueDate(periodEnd, 30),
    locale,
    paymentMethod,
    billingSnapshot: snapshot,
    lines,
    subtotalChf: subtotal,
    vatRate: vat.rate,
    vatAmountChf: vatAmount,
    totalChf: total,
    warnings,
  };
}

/**
 * Compute + render + persist in one step. If dryRun is true, the
 * draft is returned without persisting and no PDF is rendered (the
 * preview UI hits this).
 */
export async function generateInvoice(opts: {
  zitadelOrgId: string;
  year: number;
  month: number;
  locale?: string;
  dryRun?: boolean;
}): Promise<{ draft: InvoiceDraft; invoice: Invoice | null }> {
  const draft = await computeInvoiceDraft(opts);
  if (opts.dryRun) {
    return { draft, invoice: null };
  }
  // Render the PDF first — if it fails, we never touch the DB.
  // The PDF render needs the invoice number, which is allocated
  // inside createInvoice's transaction. To keep the PDF rendering
  // outside the DB transaction (it can be slow), we render with a
  // placeholder number, allocate the real number inside the tx,
  // then re-render? No — instead we generate a temporary draft
  // number for the PDF and accept that the displayed number on
  // the PDF matches what we'll persist (because the allocator is
  // serialized).
  //
  // Practical approach: render the PDF inside createInvoice's tx,
  // immediately after allocation. This is fine because react-pdf
  // is reasonably fast (~50–200 ms for a typical invoice) and
  // happens once per invoice.
  //
  // To avoid restructuring createInvoice, we do this in two
  // passes: (1) reserve a number via createInvoice with a
  // placeholder PDF; (2) render with the real number; (3) UPDATE
  // pdf_data. The trade-off is two write trips but keeps the code
  // shape simple. We accept it.
  //
  // Reasoning behind two-pass: if PDF render is moved inside the
  // tx and fails (font missing, etc.), the allocated counter rolls
  // back — good. But it also means the connection is held during
  // render. At v1 scale that's fine; the choice is reversible.

  // Pass 1: allocate number + persist with empty PDF.
  const placeholder = await createInvoice(draft, null, null);
  try {
    const pdfBuffer = await renderInvoicePdf(
      placeholder,
      draft.lines.map((l, i) => ({
        ...l,
        id: `tmp-${i}`,
        invoiceId: placeholder.id,
      }))
    );
    const filename = `${placeholder.invoiceNumber}.pdf`;
    // Pass 2: store the PDF bytes.
    await updateInvoicePdf(placeholder.id, pdfBuffer, filename);
    const finalInvoice = await getInvoiceById(placeholder.id);

    // Phase 3: best-effort notification to the billing contact.
    // We send AFTER the PDF is fully persisted (so the deep link
    // in the email immediately resolves to a downloadable PDF) but
    // BEFORE returning, since the cron caller doesn't otherwise
    // know to trigger this. Failure is logged, never thrown — a
    // mail-server hiccup must not roll back an issued invoice.
    // The recipient is the billing email captured in the invoice
    // snapshot (immutable; reflects who was on file at issue time).
    try {
      const settled = finalInvoice ?? placeholder;
      const snapshot = settled.billingSnapshot;
      if (snapshot.billingEmail) {
        const supportedLocales: Array<"en" | "de" | "fr" | "it"> = [
          "en", "de", "fr", "it",
        ];
        const locale = supportedLocales.includes(settled.locale as any)
          ? (settled.locale as "en" | "de" | "fr" | "it")
          : "de";
        await sendInvoiceIssuedEmail({
          to: snapshot.billingEmail,
          contactName: snapshot.companyName, // no separate contact-name field
          companyName: snapshot.companyName,
          invoiceNumber: settled.invoiceNumber,
          totalChf: settled.totalChf,
          currency: "CHF",
          dueAt: settled.dueAt,
          lineCount: draft.lines.length,
          periodStart: settled.periodStart,
          periodEnd: settled.periodEnd,
          locale,
        });
      } else {
        console.warn(
          `Invoice ${settled.invoiceNumber} issued but billing snapshot has no email — notification skipped.`
        );
      }
    } catch (e) {
      console.error(
        `Invoice ${placeholder.invoiceNumber} issued; notification email failed:`,
        e
      );
    }

    return { draft, invoice: finalInvoice ?? placeholder };
  } catch (e) {
    // Render failed — leave the persisted row in place so admin can
    // inspect it, but surface the error.
    throw new Error(
      `Invoice ${placeholder.invoiceNumber} persisted but PDF rendering failed: ${
        e instanceof Error ? e.message : String(e)
      }. Use the admin "delete invoice" tool to clean up if needed.`
    );
  }
}