From 35197c465b72f4c4b325961082ac494a2ee975bd Mon Sep 17 00:00:00 2001
From: Jennie Robinson Faber <jennie@jenniefaber.com>
Date: Sat, 18 Apr 2026 17:16:09 +0100
Subject: [PATCH] feat(schemas): accept cadence field on subscription +
 contribution updates

---
 server/utils/schemas.js                    |  6 +-
 tests/server/api/validation-phase3.test.js | 65 ++++++++++++++++++++++
 2 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/server/utils/schemas.js b/server/utils/schemas.js
index 6e1abc4..dd5de22 100644
--- a/server/utils/schemas.js
+++ b/server/utils/schemas.js
@@ -75,7 +75,8 @@ export const helcimSubscriptionSchema = z.object({
   customerId: z.union([z.string().min(1), z.number()]),
   contributionTier: z.enum(['0', '5', '15', '30', '50']),
   customerCode: z.union([z.string().min(1).max(200), z.number()]).transform(String),
-  cardToken: z.string().max(500).optional().nullable()
+  cardToken: z.string().max(500).optional().nullable(),
+  cadence: z.enum(['monthly', 'annual']).default('monthly')
 })
 
 export const helcimUpdateBillingSchema = z.object({
@@ -135,7 +136,8 @@ export const eventPaymentSchema = z.object({
 // --- Member schemas ---
 
 export const updateContributionSchema = z.object({
-  contributionTier: z.enum(['0', '5', '15', '30', '50'])
+  contributionTier: z.enum(['0', '5', '15', '30', '50']),
+  cadence: z.enum(['monthly', 'annual']).default('monthly')
 })
 
 export const updateCircleSchema = z.object({
diff --git a/tests/server/api/validation-phase3.test.js b/tests/server/api/validation-phase3.test.js
index fd63e78..ed12cd4 100644
--- a/tests/server/api/validation-phase3.test.js
+++ b/tests/server/api/validation-phase3.test.js
@@ -160,6 +160,48 @@ describe('helcimSubscriptionSchema', () => {
     })
     expect(result.success).toBe(false)
   })
+
+  it('accepts cadence: monthly', () => {
+    const result = helcimSubscriptionSchema.safeParse({
+      customerId: '12345',
+      contributionTier: '15',
+      customerCode: 'CST123',
+      cadence: 'monthly'
+    })
+    expect(result.success).toBe(true)
+    expect(result.data.cadence).toBe('monthly')
+  })
+
+  it('accepts cadence: annual', () => {
+    const result = helcimSubscriptionSchema.safeParse({
+      customerId: '12345',
+      contributionTier: '15',
+      customerCode: 'CST123',
+      cadence: 'annual'
+    })
+    expect(result.success).toBe(true)
+    expect(result.data.cadence).toBe('annual')
+  })
+
+  it('rejects cadence: weekly', () => {
+    const result = helcimSubscriptionSchema.safeParse({
+      customerId: '12345',
+      contributionTier: '15',
+      customerCode: 'CST123',
+      cadence: 'weekly'
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('defaults cadence to monthly when omitted', () => {
+    const result = helcimSubscriptionSchema.safeParse({
+      customerId: '12345',
+      contributionTier: '15',
+      customerCode: 'CST123'
+    })
+    expect(result.success).toBe(true)
+    expect(result.data.cadence).toBe('monthly')
+  })
 })
 
 describe('helcimUpdateBillingSchema', () => {
@@ -310,6 +352,29 @@ describe('updateContributionSchema', () => {
     expect(result.success).toBe(true)
     expect(result.data).not.toHaveProperty('role')
   })
+
+  it('accepts cadence: monthly', () => {
+    const result = updateContributionSchema.safeParse({ contributionTier: '15', cadence: 'monthly' })
+    expect(result.success).toBe(true)
+    expect(result.data.cadence).toBe('monthly')
+  })
+
+  it('accepts cadence: annual', () => {
+    const result = updateContributionSchema.safeParse({ contributionTier: '15', cadence: 'annual' })
+    expect(result.success).toBe(true)
+    expect(result.data.cadence).toBe('annual')
+  })
+
+  it('rejects cadence: weekly', () => {
+    const result = updateContributionSchema.safeParse({ contributionTier: '15', cadence: 'weekly' })
+    expect(result.success).toBe(false)
+  })
+
+  it('defaults cadence to monthly when omitted', () => {
+    const result = updateContributionSchema.safeParse({ contributionTier: '15' })
+    expect(result.success).toBe(true)
+    expect(result.data.cadence).toBe('monthly')
+  })
 })
 
 // --- Series schemas ---