@stamhoofd/models 2.120.6 → 2.122.0

package/package.json

@@ -1,37 +1,65 @@
 {
     "name": "@stamhoofd/models",
-    "version": "2.120.6",
+    "version": "2.122.0",
     "type": "module",
-    "types": "./dist/index.d.ts",
     "main": "./dist/index.js",
-    "license": "UNLICENCED",
+    "types": "./dist/index.d.ts",
     "sideEffects": [
         "./src/models/_relations.ts",
         "./dist/models/_relations.js"
     ],
+    "exports": {
+        ".": "./dist/index.js",
+        "./*.ts": "./dist/*.js",
+        "./*.js": "./dist/*.js"
+    },
+    "imports": {
+        "#*": "./src/*.ts",
+        "#*.ts": "./src/*.ts"
+    },
     "files": [
         "dist",
         "src"
     ],
     "scripts": {
         "build": "tsc --build tsconfig.build.json && mkdir -p ./dist/migrations && rsync --delete --exclude='*.ts' --exclude='*.js' --exclude='*.map' -r --checksum ./src/migrations/ ./dist/migrations/ && rsync -r --checksum ./src/assets/ ./dist/assets/",
+        "lint": "eslint",
         "test": "vitest",
-        "lint": "eslint"
-    },
-    "peerDependencies": {
-        "@simonbackx/simple-database": "1.36.12",
-        "@stamhoofd/email": "*",
-        "@stamhoofd/queues": "*"
+        "test:coverage": "vitest --coverage"
     },
     "dependencies": {
-        "@aws-sdk/client-s3": "^3.839.0",
-        "base-x": "^3.0.11"
+        "@aws-sdk/client-s3": "3.1068.0",
+        "@aws-sdk/client-sesv2": "3.1068.0",
+        "@bwip-js/node": "4.11.1",
+        "@mollie/api-client": "4.5.0",
+        "@simonbackx/simple-encoding": "2.26.10",
+        "@simonbackx/simple-endpoints": "1.21.1",
+        "@simonbackx/simple-errors": "1.5.0",
+        "argon2": "0.44.0",
+        "base-x": "3.0.11",
+        "handlebars": "4.7.9",
+        "sharp": "0.35.1"
     },
     "devDependencies": {
-        "@simonbackx/simple-database": "1.36.12"
+        "@simonbackx/simple-database": "1.37.1",
+        "@stamhoofd/test-utils": "2.122.0",
+        "@types/luxon": "3.7.1",
+        "@types/uuid": "8.3.4",
+        "vitest": "4.1.8"
+    },
+    "peerDependencies": {
+        "@simonbackx/simple-database": "1.37.1",
+        "@stamhoofd/backend-i18n": "*",
+        "@stamhoofd/email": "*",
+        "@stamhoofd/queues": "*",
+        "@stamhoofd/sql": "*",
+        "@stamhoofd/structures": "*",
+        "@stamhoofd/types": "*",
+        "@stamhoofd/utility": "*"
     },
+    "license": "UNLICENCED",
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "0f41cc566739b9793910b67286a66be5745a163e"
+    "gitHead": "3c022b7d7801fb105acfaa401432a8d029abda61"
 }

package/src/factories/GroupFactory.ts

@@ -1,5 +1,5 @@
 import { Factory } from '@simonbackx/simple-database';
-import type { BundleDiscount, GroupPriceDiscount, GroupType} from '@stamhoofd/structures';
+import type { BundleDiscount, GroupPriceDiscount, GroupType } from '@stamhoofd/structures';
 import { BundleDiscountGroupPriceSettings, GroupPrice, GroupSettings, ReduceablePrice, TranslatedString } from '@stamhoofd/structures';
 
 import { SimpleError } from '@simonbackx/simple-errors';
@@ -42,15 +42,14 @@ export class GroupFactory extends Factory<Options, Group> {
                 });
             }
             group.periodId = this.options.period.id;
-        }
-        else {
+        } else {
             group.periodId = organization.periodId;
         }
 
         group.waitingListId = this.options.waitingListId ?? null;
 
         group.settings = GroupSettings.create({
-            name: this.options.name ?? new TranslatedString('Group name'),
+            name: this.options.name ?? new TranslatedString('Group ' + this.randomString(5)),
             startDate: new Date(new Date().getTime() - 10 * 1000),
             endDate: new Date(new Date().getTime() + 10 * 1000),
             registrationStartDate: new Date(new Date().getTime() - 10 * 1000),
@@ -80,8 +79,7 @@ export class GroupFactory extends Factory<Options, Group> {
                 for (const discount of this.options.bundleDiscounts) {
                     map.set(discount, null);
                 }
-            }
-            else {
+            } else {
                 map = this.options.bundleDiscounts;
             }
 

package/src/factories/OrganizationFactory.ts

@@ -1,5 +1,5 @@
 import { Factory } from '@simonbackx/simple-database';
-import type { PermissionRoleDetailed } from '@stamhoofd/structures';
+import type { PermissionRoleDetailed, STPackageBundle, STPackageType } from '@stamhoofd/structures';
 import { Address, OrganizationMetaData, OrganizationType } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
 
@@ -7,6 +7,7 @@ import { Organization } from '../models/Organization.js';
 import type { RegistrationPeriod } from '../models/RegistrationPeriod.js';
 import { RegistrationPeriodFactory } from './RegistrationPeriodFactory.js';
 import { Country } from '@stamhoofd/types/Country';
+import { STPackageFactory } from './STPackageFactory.js';
 
 class Options {
     uri?: string;
@@ -17,12 +18,13 @@ class Options {
     roles?: PermissionRoleDetailed[];
     period?: RegistrationPeriod;
     tags?: string[];
+    packages?: STPackageBundle[];
 }
 
 export class OrganizationFactory extends Factory<Options, Organization> {
     async create(): Promise<Organization> {
         const organization = new Organization();
-        organization.name = this.options.name ?? 'Organization ' + (new Date().getTime() + Math.floor(Math.random() * 999999));
+        organization.name = this.options.name ?? 'Organization ' + (new Date().getTime() + '-' + Math.floor(Math.random() * 999999) + '-' + Math.floor(Math.random() * 999999));
         organization.website = 'https://domain.com';
         organization.registerDomain = this.options.domain ?? null;
         organization.uri = this.options.uri ?? Formatter.slug(organization.name);
@@ -45,8 +47,7 @@ export class OrganizationFactory extends Factory<Options, Organization> {
 
         if (this.options.period) {
             period = this.options.period;
-        }
-        else {
+        } else {
             period = await new RegistrationPeriodFactory({}).create();
         }
 
@@ -68,6 +69,13 @@ export class OrganizationFactory extends Factory<Options, Organization> {
             await period.save();
         }
 
+        for (const bundle of this.options.packages ?? []) {
+            await new STPackageFactory({
+                organization,
+                bundle,
+            }).create();
+        }
+
         return organization;
     }
 }

package/src/factories/RegistrationInvitationFactory.ts

@@ -0,0 +1,24 @@
+import { Factory } from '@simonbackx/simple-database';
+
+import type { Group } from '../models/Group.js';
+import type { Member } from '../models/Member.js';
+import type { Organization } from '../models/Organization.js';
+import { RegistrationInvitation } from '../models/RegistrationInvitation.js';
+
+class Options {
+    group: Group;
+    member: Member;
+    organization: Organization
+}
+
+export class RegistrationInvitationFactory extends Factory<Options, RegistrationInvitation> {
+    async create(): Promise<RegistrationInvitation> {
+        const invitation = new RegistrationInvitation();
+        invitation.groupId = this.options.group.id;
+        invitation.memberId = this.options.member.id;
+        invitation.organizationId = this.options.organization.id;
+        await invitation.save();
+
+        return invitation;
+    }
+}

package/src/factories/STPackageFactory.ts

@@ -24,8 +24,7 @@ export class STPackageFactory extends Factory<Options, STPackage> {
 
         if (this.options.removeAt) {
             pack.validAt = new Date(this.options.removeAt.getTime() - 365 * 1000 * 60 * 60 * 24);
-        }
-        else {
+        } else {
             pack.validAt = this.options.validAt !== undefined ? this.options.validAt : new Date();
         }
 
@@ -38,6 +37,7 @@ export class STPackageFactory extends Factory<Options, STPackage> {
         }
 
         await pack.save();
+
         return pack;
     }
 }

package/src/factories/UserFactory.ts

@@ -1,5 +1,5 @@
 import { Factory } from '@simonbackx/simple-database';
-import type { Permissions} from '@stamhoofd/structures';
+import type { Permissions } from '@stamhoofd/structures';
 import { NewUser, UserPermissions } from '@stamhoofd/structures';
 
 import type { Organization } from '../models/Organization.js';
@@ -22,13 +22,12 @@ class Options {
 
 export class UserFactory extends Factory<Options, User> {
     async create(): Promise<User> {
-        let organization: Organization | null = null;
+        let organization: Organization | null;
 
         if (!this.options.organization && STAMHOOFD.userMode !== 'platform' && !this.options.globalPermissions) {
             const organizationFactory = new OrganizationFactory({});
             organization = await organizationFactory.create();
-        }
-        else {
+        } else {
             organization = this.options.organization ?? null;
         }
 
@@ -40,7 +39,7 @@ export class UserFactory extends Factory<Options, User> {
             organizationId: organization?.id ?? null,
             password,
         }), {
-            allowPlatform: !!this.options.globalPermissions
+            allowPlatform: !!this.options.globalPermissions,
         });
         if (!user) {
             throw new Error('Unexpected failure when creating user in factory');

package/src/factories/index.ts

@@ -24,3 +24,4 @@ export * from './RecordCategoryFactory.js';
 export * from './RecordAnswerFactory.js';
 export * from './DocumentTemplateFactory.js';
 export * from './STPackageFactory.js';
+export * from './RegistrationInvitationFactory.js';

package/src/helpers/EmailBuilder.ts

@@ -1,7 +1,7 @@
 import type { EmailBuilder, EmailInterfaceRecipient } from '@stamhoofd/email';
 import { Email, EmailAddress } from '@stamhoofd/email';
-import type { EmailRecipient as EmailRecipientStruct, EmailTemplateType, OrganizationEmail, Platform as PlatformStruct, Recipient} from '@stamhoofd/structures';
-import { BalanceItem as BalanceItemStruct, ReceivableBalanceType, replaceEmailHtml, replaceEmailText, Replacement } from '@stamhoofd/structures';
+import type { EmailRecipient as EmailRecipientStruct, EmailTemplateType, OrganizationEmail, Platform as PlatformStruct, Recipient } from '@stamhoofd/structures';
+import { BalanceItem as BalanceItemStruct, getAppHost, ReceivableBalanceType, replaceEmailHtml, replaceEmailText, Replacement } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
 
 import { SimpleError } from '@simonbackx/simple-errors';
@@ -13,7 +13,7 @@ import type { Group } from '../models/Group.js';
 import type { Organization } from '../models/Organization.js';
 import { Platform } from '../models/Platform.js';
 import { User } from '../models/User.js';
-import type {Webshop} from '../models/Webshop.js';
+import type { Webshop } from '../models/Webshop.js';
 
 export type EmailTemplateOptions = {
     type: EmailTemplateType;
@@ -314,8 +314,7 @@ export async function getEmailBuilder(organization: Organization | null, email:
                 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
             };
             cleaned.push(recipient);
-        }
-        catch (e) {
+        } catch (e) {
             console.error(e);
         }
     }
@@ -499,14 +498,14 @@ export function stripSensitiveRecipientReplacements(recipient: Recipient | Email
     }
 
     // Add dummy unsubscribeUrl
-    const dummyUnsubscribeUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? organization.getHost() : STAMHOOFD.domains.dashboard) + '/unsubscribe?token=example';
+    const dummyUnsubscribeUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? getAppHost('registration', organization, false) : STAMHOOFD.domains.dashboard) + '/unsubscribe?token=example';
     recipient.replacements.push(Replacement.create({
         token: 'unsubscribeUrl',
         value: dummyUnsubscribeUrl,
     }));
 
     // dummy signInUrl
-    const dummySignInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? organization.getHost() : STAMHOOFD.domains.dashboard) + '/login';
+    const dummySignInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? getAppHost('registration', organization, false) : STAMHOOFD.domains.dashboard) + '/login';
     recipient.replacements.push(Replacement.create({
         token: 'signInUrl',
         value: dummySignInUrl,
@@ -536,7 +535,7 @@ export function stripRecipientReplacementsForWebDisplay(recipient: Recipient | E
     recipient.replacements = recipient.replacements.filter(r => r.token !== 'unsubscribeUrl' && r.token !== 'loginDetails' && r.token !== 'greeting');
 
     // Add dummy unsubscribeUrl
-    const dummyUnsubscribeUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? organization.getHost() : STAMHOOFD.domains.dashboard);
+    const dummyUnsubscribeUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? getAppHost('registration', organization, false) : STAMHOOFD.domains.dashboard);
     recipient.replacements.push(Replacement.create({
         token: 'unsubscribeUrl',
         value: dummyUnsubscribeUrl,
@@ -575,7 +574,7 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
     }
 
     if (!recipient.email && !recipient.userId) {
-        const signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? organization.getHost() : STAMHOOFD.domains.dashboard) + '/login';
+        const signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? getAppHost('registration', organization, false) : STAMHOOFD.domains.dashboard) + '/login';
         recipient.replacements.push(Replacement.create({
             token: 'signInUrl',
             value: signInUrl,
@@ -587,8 +586,7 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
                 value: '',
             }));
         }
-    }
-    else {
+    } else {
         // Default signInUrl
         recipientUser = recipient.userId ? await User.select().where('id', recipient.userId).first(false) : await User.getForAuthentication(organization?.id ?? null, recipient.email!, { allowWithoutAccount: true });
         if (STAMHOOFD.userMode !== 'platform' && recipientUser && recipientUser.organizationId && recipientUser.organizationId !== (organization?.id ?? null)) {
@@ -600,14 +598,12 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
         if (!recipientUser || !recipientUser.hasAccount()) {
             // We can create a special token
             if (recipientUser) {
-                signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? organization.getHost() : STAMHOOFD.domains.dashboard) + '/account-aanmaken?email=' + encodeURIComponent(recipientUser?.email);
-            }
-            else {
-                signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? organization.getHost() : STAMHOOFD.domains.dashboard) + '/account-aanmaken';
+                signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? getAppHost('registration', organization, false) : STAMHOOFD.domains.dashboard) + '/account-aanmaken?email=' + encodeURIComponent(recipientUser?.email);
+            } else {
+                signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? getAppHost('registration', organization, false) : STAMHOOFD.domains.dashboard) + '/account-aanmaken';
             }
-        }
-        else {
-            signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? organization.getHost() : STAMHOOFD.domains.dashboard) + '/login?email=' + encodeURIComponent(recipientUser.email);
+        } else {
+            signInUrl = 'https://' + (organization && STAMHOOFD.userMode === 'organization' ? getAppHost('registration', organization, false) : STAMHOOFD.domains.dashboard) + '/login?email=' + encodeURIComponent(recipientUser.email);
         }
 
         recipient.replacements.push(Replacement.create({
@@ -638,8 +634,7 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
                             }),
                         );
                     }
-                }
-                else {
+                } else {
                     console.log('No member found for user', recipientUser.id);
                 }
             }
@@ -653,8 +648,7 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
                         : `<p class="description"><em>${$t('%1EB', { email: emailEscaped })}${suffix}</em></p>`,
                 }),
             );
-        }
-        else {
+        } else {
             if (recipient.email) {
                 const emailEscaped = `<strong>${Formatter.escapeHtml(recipient.email)}</strong>`;
                 console.log('No user found for email', recipient.email);
@@ -665,8 +659,7 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
                         html: `<p class="description"><em>${$t('%1EB', { email: emailEscaped })}</em></p>`,
                     }),
                 );
-            }
-            else {
+            } else {
                 recipient.replacements.push(
                     Replacement.create({
                         token: 'loginDetails',
@@ -702,8 +695,7 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
                     html: BalanceItemStruct.getDetailsHTMLTable(balanceItems),
                 }),
             );
-        }
-        else {
+        } else {
             recipient.replacements.push(
                 Replacement.create({
                     token: 'outstandingBalance',
@@ -739,8 +731,7 @@ export async function fillRecipientReplacements(recipient: Recipient | EmailReci
 
     if (recipient instanceof EmailRecipient) {
         recipient.replacements.push(...recipient.getRecipient().getDefaultReplacements());
-    }
-    else {
+    } else {
         recipient.replacements.push(...recipient.getDefaultReplacements());
     }
 

package/src/helpers/Handlebars.ts

@@ -50,7 +50,12 @@ class AsyncResolver {
 
 Handlebars.registerHelper('eq', (a, b) => a == b);
 Handlebars.registerHelper('neq', (a, b) => a !== b);
-Handlebars.registerHelper('formatPrice', a => typeof a === 'number' ? Formatter.price(a) : a);
+Handlebars.registerHelper('formatPrice', (a, options) => {
+    if (typeof a !== 'number') return a;
+    // round=true rounds to nearest cent (100 units = 1 cent, where 10000 units = €1)
+    const value = options?.hash?.round ? Math.round(a / 100) * 100 : a;
+    return Formatter.price(value);
+});
 Handlebars.registerHelper('formatDate', (a, options) => {
     if (!(a instanceof Date)) {
         return '';
@@ -103,6 +108,10 @@ Handlebars.registerHelper('coalesce', (...args) => {
     return args.find(a => a !== null && a !== undefined) ?? null;
 });
 
+Handlebars.registerHelper('$t', (t: string) => {
+    return $t(t);
+});
+
 Handlebars.registerHelper('days', (a, b) => {
     if (!(a instanceof Date) || !(b instanceof Date)) {
         return 0;

package/src/helpers/InvoiceCounter.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect } from 'vitest';
+import { InvoiceCounter } from './InvoiceCounter.js';
+import { OrganizationInvoiceSettings } from '@stamhoofd/structures/OrganizationInvoiceSettings.js';
+import { Invoice } from '../models/Invoice.js';
+import { OrganizationFactory } from '../factories/OrganizationFactory.js';
+
+// Minimal settings factory
+function makeSettings(overrides: Partial<OrganizationInvoiceSettings> = {}): OrganizationInvoiceSettings {
+    return OrganizationInvoiceSettings.create({
+        resetMonth: null,
+        prefixYear: false,
+        ...overrides,
+    })
+}
+
+// ─────────────────────────────────────────────
+// parseNumber
+// ─────────────────────────────────────────────
+describe('InvoiceCounter.parseNumber', () => {
+    describe('without year prefix', () => {
+        const settings = makeSettings({ prefixYear: false });
+
+        it('parses ABC-123 → 123', () => {
+            expect(InvoiceCounter.parseNumber(settings, 'ABC-123')).toBe(123);
+        });
+
+        it('parses XXX0001 → 1', () => {
+            expect(InvoiceCounter.parseNumber(settings, 'XXX0001')).toBe(1);
+        });
+
+        it('parses 05STA0001 → 1', () => {
+            expect(InvoiceCounter.parseNumber(settings, '05STA0001')).toBe(1);
+        });
+
+        it('parses 1234-0011 → 11', () => {
+            expect(InvoiceCounter.parseNumber(settings, '1234-0011')).toBe(11);
+        });
+    });
+
+    describe('with year prefix (prefixYear: true)', () => {
+        const settings = makeSettings({ prefixYear: true });
+
+        it('parses 2012001584 → 1584', () => {
+            expect(InvoiceCounter.parseNumber(settings, '2012001584')).toBe(1584);
+        });
+
+        it('parses XXX-2012001584 → 1584', () => {
+            expect(InvoiceCounter.parseNumber(settings, 'XXX-2012001584')).toBe(1584);
+        });
+    });
+});
+
+describe('InvoiceCounter.formatNumber', () => {
+    const date2025 = new Date('2025-06-15T12:00:00Z');
+
+    it('formats 123 with fixed prefix ABC → "ABC000123"', () => {
+        const settings = makeSettings({ fixedPrefix: 'ABC' });
+        expect(InvoiceCounter.formatNumber(settings, 123, date2025)).toBe('ABC000123');
+    });
+
+    it('formats 123 with fixed prefix ABC1 → "ABC1-000123"', () => {
+        const settings = makeSettings({ fixedPrefix: 'ABC1' });
+        expect(InvoiceCounter.formatNumber(settings, 123, date2025)).toBe('ABC1-000123');
+    });
+
+    it('formats 1 with year prefix → "2025000001"', () => {
+        const settings = makeSettings({ prefixYear: true });
+        expect(InvoiceCounter.formatNumber(settings, 1, date2025)).toBe('2025000001');
+    });
+
+    it('formats 11 with fixed prefix "111-" and no duplicate dash → "111-000011"', () => {
+        const settings = makeSettings({ fixedPrefix: '111-' });
+        expect(InvoiceCounter.formatNumber(settings, 11, date2025)).toBe('111-000011');
+    });
+
+    it('formats 11 with fixed prefix "test-" and no duplicate dash → "test-000011"', () => {
+        const settings = makeSettings({ fixedPrefix: 'test-' });
+        expect(InvoiceCounter.formatNumber(settings, 11, date2025)).toBe('test-000011');
+    });
+
+    it('formats 54 with year prefix + fixed prefix → "ABC202500054"', () => {
+        // year is prepended first, then fixedPrefix wraps around
+        const settings = makeSettings({ prefixYear: true, fixedPrefix: 'ABC' });
+        expect(InvoiceCounter.formatNumber(settings, 54, date2025)).toBe('ABC2025000054');
+    });
+});
+
+describe('InvoiceCounter.shouldStartNewSeries', () => {
+    it('returns false when resetMonth is null', () => {
+        const settings = makeSettings({ resetMonth: null });
+        const last = new Date('2024-12-01');
+        const now = new Date('2025-06-01');
+        expect(InvoiceCounter.shouldStartNewSeries(settings, last, now)).toBe(false);
+    });
+
+    it('returns true when crossing the reset month boundary', () => {
+        // reset on January (month 1)
+        const settings = makeSettings({ resetMonth: 1 });
+        const last = new Date('2024-06-15');
+        const now = new Date('2025-01-02');
+        expect(InvoiceCounter.shouldStartNewSeries(settings, last, now)).toBe(true);
+    });
+
+    it('returns false when still within the same series period', () => {
+        const settings = makeSettings({ resetMonth: 1 });
+        const last = new Date('2025-01-05');
+        const now = new Date('2025-06-01');
+        expect(InvoiceCounter.shouldStartNewSeries(settings, last, now)).toBe(false);
+    });
+});
+
+describe('InvoiceCounter.assignNextNumber', () => {
+    beforeEach(() => {
+        InvoiceCounter.clearAll();
+        vitest.useFakeTimers({ toFake: ['Date'] });
+    });
+
+    afterEach(() => {
+        vitest.useRealTimers();
+    });
+
+    it('assigns 000001 to the first invoice for an org (no cache, no DB)', async () => {
+        const org = await new OrganizationFactory({}).create();
+        const settings = makeSettings({});
+
+        const invoice = new Invoice();
+        invoice.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice, settings);
+
+        expect(invoice.number).toBe('000001');
+        expect(invoice.invoicedAt).not.toBeNull();
+    });
+
+    it('increments from cache when called twice without a reset boundary', async () => {
+        const org = await new OrganizationFactory({}).create();
+        const settings = makeSettings({});
+
+        const invoice1 = new Invoice();
+        invoice1.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice1, settings);
+        expect(invoice1.number).toBe('000001');
+
+        const invoice2 = new Invoice();
+        invoice2.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice2, settings);
+        expect(invoice2.number).toBe('000002');
+    });
+
+    it('continues from DB when cache is absent but a numbered invoice exists', async () => {
+        const org = await new OrganizationFactory({}).create();
+        const settings = makeSettings({});
+
+        const existing = new Invoice();
+        existing.organizationId = org.id;
+        existing.number = '000042';
+        existing.invoicedAt = new Date();
+        await existing.save();
+
+        InvoiceCounter.clearAll();
+
+        const invoice = new Invoice();
+        invoice.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice, settings);
+
+        expect(invoice.number).toBe('000043');
+    });
+
+    it('starts a new series when the reset boundary is crossed (cache hit)', async () => {
+        const org = await new OrganizationFactory({}).create();
+        const settings = makeSettings({ resetMonth: 1, prefixYear: true });
+
+        vitest.setSystemTime(new Date('2024-06-15T12:00:00Z'));
+        const invoice1 = new Invoice();
+        invoice1.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice1, settings);
+        expect(invoice1.number).toBe('2024000001');
+
+        // Advance past the January 2025 reset boundary
+        vitest.setSystemTime(new Date('2025-02-01T12:00:00Z'));
+        const invoice2 = new Invoice();
+        invoice2.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice2, settings);
+
+        expect(invoice2.number).toBe('2025000001');
+    });
+
+    it('falls back to 1 when the DB invoice number cannot be parsed', async () => {
+        const org = await new OrganizationFactory({}).create();
+        const settings = makeSettings({});
+
+        const existing = new Invoice();
+        existing.organizationId = org.id;
+        existing.number = 'INVALID';
+        existing.invoicedAt = new Date();
+        await existing.save();
+
+        const invoice = new Invoice();
+        invoice.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice, settings);
+
+        expect(invoice.number).toBe('000001');
+    });
+
+    it('reads from DB after resetNumbers clears the cache', async () => {
+        const org = await new OrganizationFactory({}).create();
+        const settings = makeSettings({});
+
+        const invoice1 = new Invoice();
+        invoice1.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice1, settings);
+        expect(invoice1.number).toBe('000001');
+
+        await InvoiceCounter.resetNumbers(org.id);
+
+        const invoice2 = new Invoice();
+        invoice2.organizationId = org.id;
+        await InvoiceCounter.assignNextNumber(invoice2, settings);
+        expect(invoice2.number).toBe('000002');
+    });
+});