@stamhoofd/backend 2.127.1 → 2.129.1

package/src/helpers/MemberMerger.ts

@@ -4,6 +4,7 @@ import {
     Member,
     MemberPlatformMembership,
     MemberResponsibilityRecord,
+    MemberUser,
     MergedMember,
     Registration,
     User,
@@ -70,6 +71,7 @@ export async function mergeTwoMembers(base: Member, other: Member, options?: { u
     if (other.existsInDatabase) {
         await mergeRegistrations(base, other);
         await mergeUsers(base, other);
+        // await mergeUserMembers(base, other);
         await mergeResponsibilities(base, other);
         await mergeBalanceItems(base, other);
         await mergeDocuments(base, other);
@@ -114,6 +116,20 @@ async function mergeUsers(base: Member, other: Member) {
     await mergeModels(base, other, User);
 }
 
+async function mergeUserMembers(base: Member, other: Member) {
+    const baseId = base.id;
+    const otherModels = await MemberUser.select().where('membersId', other.id).fetch();
+
+    for (const otherModel of otherModels) {
+        otherModel.membersId = baseId;
+
+        await otherModel.save({
+            skipMarkSaved: true,
+            skipSendEvents: true,
+        });
+    }
+}
+
 async function mergeResponsibilities(base: Member, other: Member) {
     async function getResponsibilities(memberId: string) {
         const rows = await SQL.select()

package/src/helpers/MemberUserSyncer.test.ts

@@ -1,5 +1,6 @@
 import { Database } from '@simonbackx/simple-database';
-import { Member, MemberFactory, MemberResponsibilityRecordFactory, User, UserFactory } from '@stamhoofd/models';
+import { Member, MemberFactory, MemberResponsibilityRecordFactory, MemberUser, User, UserFactory } from '@stamhoofd/models';
+import { SQL } from '@stamhoofd/sql';
 import { BooleanStatus, MemberDetails, Parent, UserPermissions } from '@stamhoofd/structures';
 import { TestUtils } from '@stamhoofd/test-utils';
 import { MemberUserSyncer } from './MemberUserSyncer.js';
@@ -1027,6 +1028,68 @@ describe('Helpers.MemberUserSyncer', () => {
         });
     });
 
+    describe('removeDuplicates', () => {
+        const link = async (memberId: string, userId: string) => {
+            await SQL.insert(MemberUser.table)
+                .columns('membersId', 'usersId')
+                .values([memberId, userId])
+                .insert();
+        };
+
+        const countLinks = async (memberId: string, userId: string) => {
+            const rows = await SQL.select()
+                .from(SQL.table(MemberUser.table))
+                .where(SQL.column('membersId'), memberId)
+                .where(SQL.column('usersId'), userId)
+                .fetch();
+            return rows.length;
+        };
+
+        test('Duplicate links for a single member are collapsed to one', async () => {
+            const member = await new MemberFactory({}).create();
+            const otherMember = await new MemberFactory({}).create();
+            const userA = await new UserFactory({ email: 'a@example.com' }).create();
+            const userB = await new UserFactory({ email: 'b@example.com' }).create();
+
+            // 3 duplicate links for (member, userA)
+            await link(member.id, userA.id);
+            await link(member.id, userA.id);
+            await link(member.id, userA.id);
+
+            // A single link for (member, userB) should be kept untouched
+            await link(member.id, userB.id);
+
+            // Duplicates for another member should not be affected when scoping to member
+            await link(otherMember.id, userA.id);
+            await link(otherMember.id, userA.id);
+
+            await MemberUserSyncer.removeDuplicates(member.id);
+
+            expect(await countLinks(member.id, userA.id)).toBe(1);
+            expect(await countLinks(member.id, userB.id)).toBe(1);
+
+            // Untouched: scoped to member only
+            expect(await countLinks(otherMember.id, userA.id)).toBe(2);
+        });
+
+        test('Duplicate links across all members are collapsed when memberId is null', async () => {
+            const member1 = await new MemberFactory({}).create();
+            const member2 = await new MemberFactory({}).create();
+            const userA = await new UserFactory({ email: 'a@example.com' }).create();
+
+            await link(member1.id, userA.id);
+            await link(member1.id, userA.id);
+            await link(member2.id, userA.id);
+            await link(member2.id, userA.id);
+            await link(member2.id, userA.id);
+
+            await MemberUserSyncer.removeDuplicates(null);
+
+            expect(await countLinks(member1.id, userA.id)).toBe(1);
+            expect(await countLinks(member2.id, userA.id)).toBe(1);
+        });
+    });
+
     describe('Members with the same email addresses', () => {
         test('The most recent member is linked to a user if both do not have responsibilities', async () => {
             const member1 = await new MemberFactory({

package/src/helpers/MemberUserSyncer.ts

@@ -1,30 +1,55 @@
 import type { MemberWithUsers } from '@stamhoofd/models';
-import { CachedBalance, Member, MemberResponsibilityRecord, Organization, Platform, User } from '@stamhoofd/models';
+import { CachedBalance, Member, MemberResponsibilityRecord, MemberUser, Organization, Platform, User } from '@stamhoofd/models';
 import { QueueHandler } from '@stamhoofd/queues';
-import { SQL } from '@stamhoofd/sql';
+import { SQL, SQLAlias, SQLCount, SQLSelectAs } from '@stamhoofd/sql';
 import type { MemberDetails, PermissionRole } from '@stamhoofd/structures';
 import { AuditLogSource, Permissions, ReceivableBalanceType, UserPermissions } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
-import basex from 'base-x';
-import crypto from 'crypto';
 import { AuditLogService } from '../services/AuditLogService.js';
 
-const ALPHABET = '123456789ABCDEFGHJKMNPQRSTUVWXYZ'; // Note: we removed 0, O, I and l to make it easier for humans
-const customBase = basex(ALPHABET);
+export class MemberUserSyncerStatic {
+    /**
+     * Delete duplicate member <-> user links (the same user linked to the same member more than once),
+     * keeping the row with the lowest id for each (membersId, usersId) pair.
+     *
+     * Runs as a single atomic statement, either scoped to one member or across all members (memberId = null).
+     */
+    async removeDuplicates(memberId: string | null) {
+        // Find only the (membersId, usersId) pairs that actually have duplicates, together with the
+        // lowest id we want to keep. HAVING COUNT(*) > 1 keeps this derived table tiny (duplicates are
+        // rare), so we only materialize + join the handful of affected groups instead of the whole table.
+        // It has to be a derived table so MySQL materializes it up front: a plain self-join against the
+        // delete target does not reliably delete rows (and is forbidden as a subquery on the same table).
+        const duplicateGroups = SQL.select(
+            SQL.column('membersId'),
+            SQL.column('usersId'),
+            new SQLSelectAs(SQL.min(SQL.column('id')), new SQLAlias('keepId')),
+        )
+            .from(SQL.table(MemberUser.table))
+            .groupBy(SQL.column('membersId'), SQL.column('usersId'))
+            .having(SQL.where(new SQLCount(), '>', 1));
+
+        if (memberId !== null) {
+            duplicateGroups.where(SQL.column('membersId'), memberId);
+        }
 
-async function randomBytes(size: number): Promise<Buffer> {
-    return new Promise((resolve, reject) => {
-        crypto.randomBytes(size, (err: Error | null, buf: Buffer) => {
-            if (err) {
-                reject(err);
-                return;
-            }
-            resolve(buf);
-        });
-    });
-}
+        // Delete the duplicate rows: every row in an affected group whose id is higher than the one we keep.
+        const query = SQL.delete()
+            .from(SQL.table(MemberUser.table, 'duplicate'))
+            .join(
+                SQL.join(duplicateGroups.as('duplicate_group'))
+                    .where(SQL.column('duplicate_group', 'membersId'), SQL.column('duplicate', 'membersId'))
+                    .where(SQL.column('duplicate_group', 'usersId'), SQL.column('duplicate', 'usersId'))
+                    .where(SQL.column('duplicate', 'id'), '>', SQL.column('duplicate_group', 'keepId')),
+            );
+
+        if (memberId !== null) {
+            query.where(SQL.column('duplicate', 'membersId'), memberId);
+        }
+
+        await query.delete();
+    }
 
-export class MemberUserSyncerStatic {
     /**
      * Call when:
      * - responsibilities have changed
@@ -40,6 +65,22 @@ export class MemberUserSyncerStatic {
                     throw new Error('Failed to load users for member ' + member.id);
                 }
 
+                // Check duplicate users
+                // Cleanup legacy bugs, but also cleans up merges
+                let removeDuplicates = false;
+                for (const user of member.users) {
+                    const o = member.users.filter(u => u.id === user.id);
+                    if (o.length > 1) {
+                        removeDuplicates = true;
+                        break;
+                    }
+                }
+
+                if (removeDuplicates) {
+                    await this.removeDuplicates(member.id);
+                    await Member.users.load(member);
+                }
+
                 const { userEmails, parentEmails, unverifiedEmails, allEmails } = this.getMemberAccessEmails(member.details);
 
                 // Make sure all these users have access to the member
@@ -97,12 +138,10 @@ export class MemberUserSyncerStatic {
                 }
 
                 // Generate security code (only for userMode platform)
-                if (STAMHOOFD.userMode !== 'organization' && member.details.securityCode === null) {
+                if (member.details.securityCode === null) {
                     console.log('Generating security code for member ' + member.id);
 
-                    const length = 16;
-                    const code = customBase.encode(await randomBytes(100)).toUpperCase().substring(0, length);
-                    member.details.securityCode = code;
+                    member.details.securityCode = await Member.generateSecurityCode();
                     await member.save();
                 }
             });

package/src/helpers/StripeInvoicer.ts

@@ -347,7 +347,7 @@ export class StripeInvoicer {
                 break;
             }
             const nextMonth = new Date(currentMonth.getFullYear(), currentMonth.getMonth() + 1, 1);
-            const { end: endNext } = StripeInvoicer.getMonthUnixStartEnd(currentMonth);
+            const { end: endNext } = StripeInvoicer.getMonthUnixStartEnd(nextMonth);
             const isLastMonth = endNext >= stopAt.getTime() / 1000;
             await this.generateInvoices(sellingOrganization, currentMonth, { ...options, force: (isLastMonth && !!options?.forceLast) || !!options?.force });
             currentMonth = nextMonth;

package/src/migrations/1783097842-default-member-security-code-email-template.sql

@@ -0,0 +1,3 @@
+INSERT INTO `email_templates` (`id`, `subject`, `groupId`, `webshopId`, `organizationId`, `type`, `text`, `html`, `json`, `updatedAt`, `createdAt`) VALUES
+('7c9e6a41-2b8d-4f3a-9e21-5a1c3b4d5e6f', 'Beveiligingscode voor {{firstNameMember}}', NULL, NULL, NULL, 'MemberSecurityCode', '{{greeting}}\n\nJij of een gezinslid ({{requesterEmail}}) vroeg de beveiligingscode op van {{firstNameMember}} bij {{organizationName}}. Met deze code kan je toegang krijgen tot dit lid:\n\n{{securityCode}}Heb je dit niet aangevraagd? Dan kan je deze e-mail veilig negeren.\n\nMet vriendelijke groeten,\n{{organizationName}}\n\nIk wil deze mails niet meer ontvangen ({{unsubscribeUrl}})', '<!DOCTYPE html>\n<html>\n\n<head>\n<meta charset=\"utf-8\" />\n<meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\" />\n<meta name=\"viewport\" content=\"width=device-width,initial-scale=1.0\" />\n<title>Beveiligingscode voor {{firstNameMember}}</title>\n<style type=\"text/css\">body {\n  color: #000716;\n  color: var(--color-dark, #000716);\n  font-family: -apple-system-body, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif, \"Apple Color Emoji\", \"Segoe UI Emoji\", \"Segoe UI Symbol\";\n  font-size: 12pt;\n  line-height: 1.4;\n}\n\np {\n  margin: 0;\n  padding: 0;\n  line-height: 1.4;\n}\n\np.description {\n  color: var(--color-gray-4, #5e5e5e);\n  font-size: 10pt;\n}\np.description a, p.description a:link, p.description a:visited, p.description a:active, p.description a:hover {\n  text-decoration: underline;\n  color: var(--color-gray-4, #5e5e5e);\n}\n\nstrong {\n  font-weight: bold;\n}\n\nem {\n  font-style: italic;\n}\n\nh1 {\n  font-size: 30px;\n  font-weight: bold;\n  line-height: 1.2;\n}\n@media (max-width: 350px) {\n  h1 {\n    font-size: 24px;\n  }\n}\nh1 {\n  margin: 0;\n  padding: 0;\n}\n\nh2 {\n  font-size: 20px;\n  line-height: 1.2;\n  font-weight: bold;\n  margin: 0;\n  padding: 0;\n}\n\nh3 {\n  font-size: 16px;\n  line-height: 1.2;\n  font-weight: bold;\n  margin: 0;\n  padding: 0;\n}\n\nh4 {\n  line-height: 1.2;\n  font-weight: 500;\n  margin: 0;\n  padding: 0;\n}\n\nol, ul {\n  list-style-position: outside;\n  padding-left: 30px;\n}\n\nhr {\n  height: 1px;\n  background: var(--color-border, var(--color-gray-2, #dcdcdc));\n  border-radius: 1px;\n  padding: 0;\n  margin: 20px 0;\n  outline: none;\n  border: 0;\n}\n\n.button {\n  touch-action: inherit;\n  user-select: auto;\n  cursor: pointer;\n  display: inline-block !important;\n  line-height: 42px;\n  font-size: 16px;\n  font-weight: bold;\n  text-box-trim: none;\n}\n.button:active {\n  transform: none;\n}\n\nimg {\n  max-width: 100%;\n  height: auto;\n}\n\na, a:link, a:visited, a:active, a:hover {\n  text-decoration: underline;\n  color: blue;\n}\n\n.email-data-table {\n  width: 100%;\n  border-collapse: collapse;\n}\n.email-data-table th, .email-data-table td {\n  text-align: left;\n  padding: 10px 10px 10px 0;\n  border-bottom: 1px solid var(--color-border, var(--color-gray-2, #dcdcdc));\n  vertical-align: middle;\n}\n.email-data-table th:last-child, .email-data-table td:last-child {\n  text-align: right;\n  padding-right: 0;\n}\n.email-data-table td.price {\n  white-space: nowrap;\n}\n.email-data-table thead {\n  font-weight: bold;\n}\n.email-data-table thead th {\n  font-size: 10pt;\n}\n.email-data-table h4 ~ p {\n  padding-top: 3px;\n  opacity: 0.8;\n  font-size: 11pt;\n}\n\n.style-inline-code {\n  font-family: monospace;\n  white-space: pre-wrap;\n  display: inline-block;\n  letter-spacing: 1%;\n}\n\n.style-code-large {\n  font-family: monospace;\n  white-space: pre-wrap;\n  font-size: 16pt;\n  letter-spacing: 2px;\n  background: #f2f2f2;\n  padding: 6px 10px;\n  border-radius: 6px;\n  display: inline-block;\n}\n\n.email-style-description-small {\n  font-size: 14px;\n  line-height: 1.5;\n  font-weight: normal;\n  color: var(--color-gray-4, #5e5e5e);\n  font-variation-settings: \"opsz\" 19;\n}\n\n.email-style-title-list {\n  font-size: 16px;\n  line-height: 1.3;\n  font-weight: 500;\n}\n.email-style-title-list + p {\n  padding-top: 3px;\n}\n\n.email-style-title-prefix-list {\n  font-size: 11px;\n  line-height: 1.5;\n  font-weight: bold;\n  color: {{primaryColor}};\n  text-transform: uppercase;\n  margin-bottom: 3px;\n}\n.email-style-title-prefix-list.error {\n  color: #f0153d;\n}\n\n.email-style-price-base, .email-style-discount-price, .email-style-discount-old-price, .email-style-price {\n  font-size: 15px;\n  line-height: 1.4;\n  font-weight: 500;\n  font-variant-numeric: tabular-nums;\n}\n.email-style-price-base.disabled, .disabled.email-style-discount-price, .disabled.email-style-discount-old-price, .disabled.email-style-price {\n  opacity: 0.6;\n}\n.email-style-price-base.negative, .negative.email-style-discount-price, .negative.email-style-discount-old-price, .negative.email-style-price {\n  color: #f0153d;\n}\n\n.email-style-price {\n  font-weight: bold;\n  color: {{primaryColor}};\n}\n\n.email-style-discount-old-price {\n  text-decoration: line-through;\n  color: var(--color-gray-4, #5e5e5e);\n}\n\n.email-style-discount-price {\n  font-weight: bold;\n  color: #ff4747;\n  margin-left: 5px;\n}\n\n.pre-wrap {\n  white-space: pre-wrap;\n} hr {height: 2px;background: #e7e7e7; border-radius: 1px; padding: 0; margin: 20px 0; outline: none; border: 0;} .button.primary { margin: 0; text-decoration: none; font-size: 16px; font-weight: bold; color: {{primaryColorContrast}}; padding: 0 27px; line-height: 42px; background: {{primaryColor}}; text-align: center; border-radius: 7px; touch-action: manipulation; display: inline-block; transition: 0.2s transform, 0.2s opacity; } .button.primary:active { transform: scale(0.95, 0.95); }  .inline-link, .inline-link:link, .inline-link:visited, .inline-link:active, .inline-link:hover { margin: 0; text-decoration: underline; font-size: inherit; font-weight: inherit; color: inherit; touch-action: manipulation; } .inline-link:active { opacity: 0.5; }  .description { color: #5e5e5e; } </style>\n</head>\n\n<body>\n<p style=\"margin: 0; padding: 0; line-height: 1.4;\">{{greeting}}</p><p style=\"margin: 0; padding: 0; line-height: 1.4;\"><br></p><p style=\"margin: 0; padding: 0; line-height: 1.4;\">Jij of een gezinslid ({{requesterEmail}}) vroeg de beveiligingscode op van {{firstNameMember}} bij {{organizationName}}. Met deze code kan je toegang krijgen tot dit lid:</p><p style=\"margin: 0; padding: 0; line-height: 1.4;\"><br></p><div data-type=\"smartVariableBlock\" data-id=\"securityCode\">{{securityCode}}</div><p class=\"description\" style=\"color: #5e5e5e;\">Heb je dit niet aangevraagd? Dan kan je deze e-mail veilig negeren.</p><p style=\"margin: 0; padding: 0; line-height: 1.4;\"><br></p><p style=\"margin: 0; padding: 0; line-height: 1.4;\">Met vriendelijke groeten,</p><p style=\"margin: 0; padding: 0; line-height: 1.4;\">{{organizationName}}</p><p style=\"margin: 0; padding: 0; line-height: 1.4;\"><br></p><hr style=\"height: 2px;background: #e7e7e7; border-radius: 1px; padding: 0; margin: 20px 0; outline: none; border: 0;\"><p style=\"margin: 0; padding: 0; line-height: 1.4;\"><a class=\"inline-link\" href=\"{{unsubscribeUrl}}\" target=\"\" style=\"margin: 0; text-decoration: underline; font-size: inherit; font-weight: inherit; color: inherit; touch-action: manipulation;\">Ik wil deze mails niet meer ontvangen</a></p><p style=\"margin: 0; padding: 0; line-height: 1.4;\"><br></p>\n</body>\n\n</html>', '{\"value\": {\"type\": \"doc\", \"content\": [{\"type\": \"paragraph\", \"content\": [{\"type\": \"smartVariable\", \"attrs\": {\"id\": \"greeting\"}}]}, {\"type\": \"paragraph\"}, {\"type\": \"paragraph\", \"content\": [{\"text\": \"Jij of een gezinslid (\", \"type\": \"text\"}, {\"type\": \"smartVariable\", \"attrs\": {\"id\": \"requesterEmail\"}}, {\"text\": \") vroeg de beveiligingscode op van \", \"type\": \"text\"}, {\"type\": \"smartVariable\", \"attrs\": {\"id\": \"firstNameMember\"}}, {\"text\": \" bij \", \"type\": \"text\"}, {\"type\": \"smartVariable\", \"attrs\": {\"id\": \"organizationName\"}}, {\"text\": \". Met deze code kan je toegang krijgen tot dit lid:\", \"type\": \"text\"}]}, {\"type\": \"paragraph\"}, {\"type\": \"smartVariableBlock\", \"attrs\": {\"id\": \"securityCode\"}}, {\"type\": \"descriptiveText\", \"content\": [{\"text\": \"Heb je dit niet aangevraagd? Dan kan je deze e-mail veilig negeren.\", \"type\": \"text\"}]}, {\"type\": \"paragraph\"}, {\"type\": \"paragraph\", \"content\": [{\"text\": \"Met vriendelijke groeten,\", \"type\": \"text\"}]}, {\"type\": \"paragraph\", \"content\": [{\"type\": \"smartVariable\", \"attrs\": {\"id\": \"organizationName\"}}]}, {\"type\": \"paragraph\"}, {\"type\": \"horizontalRule\"}, {\"type\": \"paragraph\", \"content\": [{\"type\": \"smartButtonInline\", \"attrs\": {\"id\": \"unsubscribeUrl\"}, \"content\": [{\"text\": \"Ik wil deze mails niet meer ontvangen\", \"type\": \"text\"}]}]}, {\"type\": \"paragraph\"}]}, \"version\": 401}', '2026-07-03 15:41:24', '2026-07-03 15:41:24')
+ON DUPLICATE KEY UPDATE id=id;

package/src/{migrations/1761665607-sync-member-users.ts → seeds/1783100286-sync-member-users-security-codes.ts}

@@ -6,20 +6,15 @@ import { MemberUserSyncer } from '../helpers/MemberUserSyncer.js';
 import { allSettledButThrowFirst, SeedTools } from '../helpers/SeedTools.js';
 
 export default new Migration(async () => {
-    if (STAMHOOFD.environment == 'test') {
+    if (STAMHOOFD.environment === 'test') {
         console.log('skipped in tests');
         return;
     }
 
-    if (STAMHOOFD.platformName.toLowerCase() !== 'stamhoofd') {
-        console.log('skipped for platform (only runs for Stamhoofd): ' + STAMHOOFD.platformName);
-        return;
-    }
-
     const result = await logger.setContext({ tags: ['silent-seed', 'seed'] }, async () => {
         return await SeedTools.loopBatched({
             query: Member.select('id'),
-            batchSize: 500,
+            batchSize: 50,
             batchAction: async (rawMembers) => {
                 const membersWithRegistrations = await Member.getBlobByIds(...rawMembers.map(m => m.id));
 

package/src/services/SMSService.test.ts

@@ -0,0 +1,48 @@
+import { STExpect, TestUtils } from '@stamhoofd/test-utils';
+import { initSMSApi } from '../../tests/init/index.js';
+import { SMSService } from './SMSService.js';
+
+describe('SMSService', () => {
+    describe('configuration', () => {
+        test('is configured when GATEWAYAPI_TOKEN is set', () => {
+            // The test environment configures GATEWAYAPI_TOKEN by default
+            expect(SMSService.isConfigured).toBe(true);
+        });
+
+        test('is not configured when GATEWAYAPI_TOKEN is missing', () => {
+            TestUtils.setEnvironment('GATEWAYAPI_TOKEN', undefined);
+            expect(SMSService.isConfigured).toBe(false);
+        });
+    });
+
+    describe('phone number formatting', () => {
+        test('converts to E.164 and msisdn', () => {
+            expect(SMSService.toE164('+32 470 12 34 56')).toBe('+32470123456');
+            expect(SMSService.toMsisdn('+32 470 12 34 56')).toBe(32470123456);
+        });
+
+        test('throws for invalid phone numbers', () => {
+            expect(() => SMSService.toE164('not-a-number')).toThrow(STExpect.errorWithCode('invalid_phone'));
+        });
+    });
+
+    describe('sending', () => {
+        test('sends via GatewayAPI', async () => {
+            const mocker = initSMSApi();
+
+            await SMSService.send({ to: '+32 470 12 34 56', message: 'Your code is 1234' });
+
+            expect(mocker.sentMessages.length).toBe(1);
+            expect(mocker.lastMessage!.recipient).toBe(32470123456);
+            expect(mocker.lastMessage!.message).toBe('Your code is 1234');
+        });
+
+        test('throws sms_not_configured when GATEWAYAPI_TOKEN is missing', async () => {
+            TestUtils.setEnvironment('GATEWAYAPI_TOKEN', undefined);
+
+            await expect(SMSService.send({ to: '+32470123456', message: 'hi' }))
+                .rejects
+                .toThrow(STExpect.errorWithCode('sms_not_configured'));
+        });
+    });
+});

package/src/services/SMSService.ts

@@ -0,0 +1,101 @@
+import { SimpleError } from '@simonbackx/simple-errors';
+import { Platform } from '@stamhoofd/models';
+import { Country } from '@stamhoofd/types/Country';
+import type { CountryCode } from 'libphonenumber-js';
+import { parsePhoneNumber } from 'libphonenumber-js/max';
+
+const GATEWAY_API_URL = 'https://messaging.gatewayapi.eu/mobile/single';
+
+export type SMSMessage = {
+    /**
+     * Phone number, either in international format (e.g. +32 470 12 34 56) or national format (e.g. 0470 12 34 56).
+     */
+    to: string;
+    message: string;
+    /**
+     * Default country used to parse national phone numbers (numbers without a country code).
+     */
+    defaultCountry?: Country;
+};
+
+export class SMSService {
+    static get isConfigured(): boolean {
+        return !!STAMHOOFD.GATEWAYAPI_TOKEN;
+    }
+
+    /**
+     * Convert a phone number to E.164 format (e.g. +32 470 12 34 56 -> +32470123456).
+     */
+    static toE164(phone: string, defaultCountry: Country = Country.Belgium): string {
+        try {
+            const parsed = parsePhoneNumber(phone, defaultCountry as unknown as CountryCode);
+            if (parsed && parsed.isValid()) {
+                return parsed.number;
+            }
+        } catch (e) {
+            // handled below
+        }
+
+        throw new SimpleError({
+            code: 'invalid_phone',
+            message: 'Invalid phone number for SMS: ' + phone,
+            human: $t(`%ZbO`),
+        });
+    }
+
+    /**
+     * Convert a phone number to the msisdn format expected by GatewayAPI: the full international
+     * number without a leading '+' or '00' (e.g. +32 470 12 34 56 -> 32470123456).
+     */
+    static toMsisdn(phone: string, defaultCountry: Country = Country.Belgium): number {
+        return parseInt(this.toE164(phone, defaultCountry).substring(1), 10);
+    }
+
+    static async send(sms: SMSMessage): Promise<void> {
+        const token = STAMHOOFD.GATEWAYAPI_TOKEN;
+        if (!token) {
+            throw new SimpleError({
+                code: 'sms_not_configured',
+                message: 'SMS gateway is not configured',
+                human: $t(`%ZbC`),
+            });
+        }
+
+        const msisdn = this.toMsisdn(sms.to, sms.defaultCountry ?? Country.Belgium);
+
+        let response: Response;
+        try {
+            response = await fetch(GATEWAY_API_URL, {
+                method: 'POST',
+                headers: {
+                    'Authorization': 'Token ' + token,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    sender: (await Platform.getShared()).config.name,
+                    message: sms.message,
+                    recipient: msisdn,
+                    priority: 'urgent',
+                    expiration: 'PT10M',
+                }),
+                signal: AbortSignal.timeout(10000),
+            });
+        } catch (error) {
+            throw new SimpleError({
+                code: 'sms_unreachable',
+                message: 'Network issue when sending SMS: ' + (error instanceof Error ? error.message : String(error)),
+                human: $t(`%Zb8`),
+            });
+        }
+
+        if (!response.ok) {
+            const body = await response.text();
+            console.error('Failed to send SMS via GatewayAPI', response.status, body);
+            throw new SimpleError({
+                code: 'sms_failed',
+                message: 'Failed to send SMS via GatewayAPI: ' + response.status + ' ' + body,
+                human: $t(`%Zb8`),
+            });
+        }
+    }
+}

package/tests/helpers/SMSMocker.ts

@@ -0,0 +1,61 @@
+import nock from 'nock';
+import { resetNock } from './resetNock.js';
+
+export type SentSMS = {
+    sender: string;
+    message: string;
+    recipient: number;
+};
+
+/**
+ * Mocks the GatewayAPI SMS HTTP endpoint (https://messaging.gatewayapi.eu/rest/mtsms).
+ *
+ * This only intercepts the outgoing HTTP request, so all of the real SMSService code (payload
+ * building, authentication, phone number normalization, error handling) runs during the test.
+ */
+export class SMSMocker {
+    sentMessages: SentSMS[] = [];
+
+    #forceFailure = false;
+
+    reset() {
+        this.sentMessages = [];
+        this.#forceFailure = false;
+    }
+
+    /**
+     * Make the next requests fail (server returns a 500).
+     */
+    forceFailure() {
+        this.#forceFailure = true;
+    }
+
+    start() {
+        nock('https://messaging.gatewayapi.eu')
+            .persist()
+            .post('/mobile/single')
+            .reply((uri: string, requestBody: nock.Body) => {
+                if (this.#forceFailure) {
+                    return [500, { code: '0x0002', message: 'Forced failure' }];
+                }
+
+                const body = (typeof requestBody === 'string' ? JSON.parse(requestBody) : requestBody) as SentSMS;
+                this.sentMessages.push({
+                    sender: body.sender,
+                    message: body.message,
+                    recipient: body.recipient,
+                });
+
+                return [200, { ids: [this.sentMessages.length] }];
+            });
+    }
+
+    stop() {
+        this.reset();
+        resetNock();
+    }
+
+    get lastMessage(): SentSMS | undefined {
+        return this.sentMessages[this.sentMessages.length - 1];
+    }
+}

package/tests/init/index.ts

@@ -5,3 +5,4 @@ export * from './initBundleDiscount.js';
 export * from './initStripe.js';
 export * from './initPermissionRole.js';
 export * from './initUitpasApi.js';
+export * from './initSMSApi.js';

package/tests/init/initSMSApi.ts

@@ -0,0 +1,14 @@
+import { TestUtils } from '@stamhoofd/test-utils';
+import { SMSMocker } from '../helpers/SMSMocker.js';
+
+export function initSMSApi(): SMSMocker {
+    const mocker = new SMSMocker();
+
+    mocker.start();
+
+    TestUtils.scheduleAfterThisTest(() => {
+        mocker.stop();
+    });
+
+    return mocker;
+}