Turn confirmed usage into invoice drafts

// Hosted Widget server. Configure these values with your treasurer before enabling writes.
const MANDATE_ID = 'YOUR_MANDATE_ID';
const CURRENCY = 'EUR'; // The mandate's actual currency; this never converts amounts.
const ALLOW_DRAFTS = false;
const CUSTOMERS = [
    {
        key: 'test-customer',
        name: 'Example customer',
        account: 0,
        address: { country: 'DE', zip: '10115', city: 'Berlin', addressLine: 'Example street 1' },
    },
];
const SERVICES = [
    {
        key: 'equipment-session',
        name: 'Equipment use',
        unit: 'session',
        unitAmount: 1500,
        account: 0,
        costCenter1: null as number | null,
        costCenter2: null as number | null,
        taxCode: null as string | null,
    },
];
type Input = {
    reference: string;
    customer: string;
    service: string;
    quantity: number;
    receiptDate: string;
    dueDate: string;
};
type Job = {
    schema: 1;
    reference: string;
    input: Input;
    payload: any;
    currency: string;
    state: 'reserved' | 'created' | 'verified';
    receiptId: string | null;
    createdAt: string;
    updatedAt: string;
};

function id(value: unknown) {
    const result = String(value);
    if (!/^[a-f0-9]{24}$/i.test(result)) throw new Error('Configure a valid full mandate or receipt ID.');
    return result;
}
function reference(value: unknown) {
    if (typeof value !== 'string' || !/^[A-Z0-9][A-Z0-9_-]{2,59}$/.test(value))
        throw new Error(
            'Use a stable 3–60 character usage reference: capital letters, numbers, underscores or hyphens.',
        );
    return value;
}
function day(value: unknown) {
    if (
        typeof value !== 'string' ||
        !/^20\d\d-\d{2}-\d{2}$/.test(value) ||
        !Number.isFinite(Date.parse(`${value}T00:00:00Z`)) ||
        new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value
    )
        throw new Error('Use a real calendar date from 2000 to 2099.');
    return value;
}
function key(ref: string): [string, string, string] {
    return ['usage-invoice-drafts', id(MANDATE_ID), reference(ref)];
}
function prepare(raw: unknown) {
    if (!raw || typeof raw !== 'object') throw new Error('Enter a usage record.');
    const value = raw as Record<string, unknown>;
    const customer = CUSTOMERS.find((item) => item.key === value.customer);
    const service = SERVICES.find((item) => item.key === value.service);
    if (!customer || !service) throw new Error('Choose a configured customer and service.');
    if (
        !Number.isSafeInteger(customer.account) ||
        customer.account <= 0 ||
        !Number.isSafeInteger(service.account) ||
        service.account <= 0
    )
        throw new Error('Configure the debtor account and revenue account before previewing.');
    if (!Number.isSafeInteger(service.unitAmount) || service.unitAmount <= 0)
        throw new Error('Configure an integer minor-unit price greater than zero.');
    const quantity = Number(value.quantity);
    if (
        typeof value.quantity !== 'number' ||
        !Number.isSafeInteger(quantity) ||
        quantity < 1 ||
        quantity > 10000
    )
        throw new Error('Quantity must be a whole number from 1 to 10,000.');
    const input: Input = {
        reference: reference(value.reference),
        customer: customer.key,
        service: service.key,
        quantity,
        receiptDate: day(value.receiptDate),
        dueDate: day(value.dueDate),
    };
    if (input.dueDate < input.receiptDate) throw new Error('Due date must not precede the invoice date.');
    const total = quantity * service.unitAmount;
    if (!Number.isSafeInteger(total) || total > 100000000)
        throw new Error('Split this usage record into smaller reviewed jobs.');
    if (!/^[A-Z]{3}$/.test(CURRENCY)) throw new Error('Configure the mandate currency.');
    const payload = {
        mandateId: id(MANDATE_ID),
        account: customer.account,
        accountName: customer.name,
        address: customer.address,
        deliveryDateType: null,
        title: `Usage ${input.reference}`,
        intro: '',
        note: `Developer usage reference: ${input.reference}`,
        receiptDate: `${input.receiptDate}T00:00:00.000Z`,
        dueDate: `${input.dueDate}T00:00:00.000Z`,
        positions: [
            {
                unitAmount: service.unitAmount,
                quantity,
                discount: 0,
                description: service.name,
                unit: service.unit,
                account: service.account,
                costCenter1: service.costCenter1,
                costCenter2: service.costCenter2,
                taxCode: service.taxCode,
            },
        ],
        isNet: false,
        draft: true,
        sendMethod: 'none' as const,
        email: '',
        doNotSendReceipt: true,
        useDepositReceipts: false,
        paymentMethod: null,
        queueReceiptDocument: false,
    };
    return {
        input,
        payload,
        reviewToken: JSON.stringify(payload),
        total,
        currency: CURRENCY,
        customer: customer.name,
        service: service.name,
    };
}
function checkedJob(value: unknown, ref: string): Job {
    const job = value as Job;
    if (
        !job ||
        job.schema !== 1 ||
        job.reference !== ref ||
        !job.payload ||
        !['reserved', 'created', 'verified'].includes(job.state) ||
        job.payload.mandateId !== MANDATE_ID ||
        job.payload.note !== `Developer usage reference: ${ref}` ||
        job.payload.draft !== true ||
        job.payload.doNotSendReceipt !== true ||
        job.payload.sendMethod !== 'none'
    )
        throw new Error('Unsupported stored job. Preserve it for review; no invoice was created.');
    return job;
}
function dateIso(value: unknown) {
    return value instanceof Date ? value.toISOString() : value;
}
function verifyReceipt(receipt: any, job: Job) {
    const expected = job.payload;
    const actual = receipt?.positions?.[0];
    const position = expected.positions[0];
    if (
        !receipt ||
        receipt.type !== 'invoice' ||
        receipt.draft !== true ||
        String(receipt.mandate) !== MANDATE_ID ||
        receipt.account !== expected.account ||
        receipt.accountName !== expected.accountName ||
        receipt.title !== expected.title ||
        receipt.note !== expected.note ||
        receipt.sendMethod !== 'none' ||
        receipt.doNotSendReceipt !== true ||
        receipt.isNet !== false ||
        receipt.canceledAt ||
        receipt.archivedAt ||
        receipt.payments?.length ||
        dateIso(receipt.receiptDate) !== expected.receiptDate ||
        dateIso(receipt.dueDate) !== expected.dueDate ||
        !Array.isArray(receipt.positions) ||
        receipt.positions.length !== 1 ||
        [
            'unitAmount',
            'quantity',
            'discount',
            'description',
            'unit',
            'account',
            'costCenter1',
            'costCenter2',
            'taxCode',
        ].some((field) => actual?.[field] !== position[field]) ||
        ['country', 'zip', 'city', 'addressLine'].some(
            (field) => receipt.address?.[field] !== expected.address[field],
        ) ||
        receipt.totalGrossAmount !== position.unitAmount * position.quantity
    )
        throw new Error(
            'The receipt does not match the reserved draft. Inspect it in campai; no create was repeated.',
        );
}
export async function loadDesk() {
    const jobs: Job[] = [];
    for await (const entry of storage.list<Job>(
        { prefix: ['usage-invoice-drafts', id(MANDATE_ID)] },
        { limit: 101 },
    )) {
        const ref = reference(entry.key[2]);
        jobs.push(checkedJob(entry.value, ref));
    }
    if (jobs.length > 100)
        throw new Error('This small desk lists at most 100 jobs. Add pagination before continuing.');
    return {
        enabled: ALLOW_DRAFTS,
        currency: CURRENCY,
        customers: CUSTOMERS.map(({ key, name }) => ({ key, name })),
        services: SERVICES.map(({ key, name, unitAmount, unit }) => ({ key, name, unitAmount, unit })),
        jobs: jobs.sort((a, b) => b.createdAt.localeCompare(a.createdAt)),
    };
}
export async function previewUsage(raw: unknown) {
    return prepare(raw);
}
export async function createDraft(raw: unknown) {
    if (!ALLOW_DRAFTS) throw new Error('Draft creation is disabled in the server configuration.');
    if (!raw || typeof raw !== 'object') throw new Error('Preview the usage record first.');
    const request = raw as Record<string, unknown>;
    const prepared = prepare(request.input);
    if (request.reviewToken !== prepared.reviewToken)
        throw new Error('The configured invoice changed. Preview and review it again.');
    if ((await loadDesk()).jobs.length >= 100)
        throw new Error('Add pagination and a retention workflow before creating more jobs in this example.');
    const jobKey = key(prepared.input.reference);
    const existing = await storage.get<Job>(jobKey);
    if (existing.versionstamp !== null)
        throw new Error(
            'This usage reference is already reserved. Review its saved outcome; do not create again.',
        );
    const now = new Date().toISOString();
    const job: Job = {
        schema: 1,
        reference: prepared.input.reference,
        input: prepared.input,
        payload: prepared.payload,
        currency: CURRENCY,
        state: 'reserved',
        receiptId: null,
        createdAt: now,
        updatedAt: now,
    };
    // Reserve durably before the API request. A failed/uncertain reservation never sends a request.
    const reservation = await storage.atomic().check(existing).set(jobKey, job).commit();
    if (!reservation.ok) throw new Error('Another request reserved this usage reference. Reload the desk.');
    let receiptId: string;
    try {
        const created = await api.finance.receipts.createInvoiceReceipt(prepared.payload);
        receiptId = id(created._id);
    } catch {
        // Even a rejected response stays reserved: no automated retries after a possibly successful write.
        throw new Error(
            'Creation was not confirmed. The reference stays reserved. Reload, inspect campai, and reconcile any matching draft.',
        );
    }
    job.receiptId = receiptId;
    job.state = 'created';
    job.updatedAt = new Date().toISOString();
    try {
        const saved = await storage
            .atomic()
            .check({ key: jobKey, versionstamp: reservation.versionstamp })
            .set(jobKey, job)
            .commit();
        if (!saved.ok) throw new Error('Job changed.');
    } catch {
        throw new Error(
            `Draft ${receiptId} was created, but saving its ID was not confirmed. Record this ID and reconcile the reserved job. Do not create again.`,
        );
    }
    return reconcileDraft({ reference: job.reference, receiptId });
}
export async function reconcileDraft(raw: unknown) {
    if (!raw || typeof raw !== 'object') throw new Error('Choose a saved job and its receipt ID.');
    const value = raw as Record<string, unknown>;
    const ref = reference(value.reference);
    const receiptId = id(value.receiptId);
    const entry = await storage.get<Job>(key(ref));
    if (entry.versionstamp === null) throw new Error('No reserved job exists for this usage reference.');
    const job = checkedJob(entry.value, ref);
    if (job.receiptId && job.receiptId !== receiptId)
        throw new Error('Use the receipt ID already recorded for this job.');
    if (job.state === 'reserved' && Date.now() - Date.parse(job.createdAt) < 120000)
        throw new Error('Creation may still be running. Wait two minutes before reconciling a reserved job.');
    const receipt = await api.finance.receipts.getReceipt({ mandateId: id(MANDATE_ID), receiptId });
    verifyReceipt(receipt, job);
    job.state = 'verified';
    job.receiptId = receiptId;
    job.updatedAt = new Date().toISOString();
    const saved = await storage.atomic().check(entry).set(entry.key, job).commit();
    if (!saved.ok)
        throw new Error(
            'The saved job changed during verification. Reload and reconcile again; no invoice was created.',
        );
    return { reference: ref, receiptId, state: 'verified' as const };
}