:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(workflows): hold capped messages until a frequency cap slot frees (#127579)
Harley Alexander7a1cda6cde18
diff --git a/nodejs/src/cdp/services/hogflows/actions/hog_function.test.ts b/nodejs/src/cdp/services/hogflows/actions/hog_function.test.tsindex fe46d37dc7a5..bdb88d9c8caf 100644--- a/nodejs/src/cdp/services/hogflows/actions/hog_function.test.ts+++ b/nodejs/src/cdp/services/hogflows/actions/hog_function.test.ts@@ -1,6 +1,6 @@import { mockFetch } from '~/tests/helpers/mocks/request.mock'-import { DateTime } from 'luxon'+import { DateTime, Settings } from 'luxon'import { register } from 'prom-client'import { FixtureHogFlowBuilder } from '~/cdp/_tests/builders/hogflow.builder'@@ -129,7 +129,7 @@ describe('HogFunctionHandler', () => {)mockRecipientPreferencesService = {shouldSkipAction: jest.fn().mockResolvedValue(null),- isFrequencyCapped: jest.fn().mockResolvedValue(false),+ checkFrequencyCap: jest.fn().mockResolvedValue({ capped: false }),} as anymockEmailValidationService = {getSkipReason: jest.fn().mockResolvedValue(null),@@ -496,7 +496,11 @@ describe('HogFunctionHandler', () => {])('should skip the send and emit message_frequency_capped when the recipient reached the frequency cap for %s',async (_label, parentRunId) => {- ;(mockRecipientPreferencesService.isFrequencyCapped as jest.Mock).mockResolvedValueOnce(true)+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({+ capped: true,+ nextSlotAt: Date.now() + 60 * 60 * 1000,+ holdHours: null,+ })invocation.parentRunId = parentRunIdconst invocationResult = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {@@ -524,6 +528,102 @@ describe('HogFunctionHandler', () => {})+ const hour = 60 * 60 * 1000++ it.each([+ ['another send took the freed slot', 1 * hour, { capped: true, nextSlotAt: 1_800_000_000_000 + 3 * hour }, 1],+ // A worker backlog can wake the send after the hold ended. It must not claim a slot that freed late.+ ['the send wakes after the hold ended', 3 * hour, { capped: false }, 0],+ ])(+ 'should hold a capped send until the next slot, then skip it when %s',+ async (_label, wakeAfter, wakeCheck, checks) => {+ const start = 1_800_000_000_000+ const originalNow = Settings.now+ jest.spyOn(Math, 'random').mockReturnValue(0)+ const checkFrequencyCap = mockRecipientPreferencesService.checkFrequencyCap as jest.Mock+ try {+ Settings.now = () => start+ checkFrequencyCap.mockResolvedValueOnce({ capped: true, nextSlotAt: start + hour, holdHours: 2 })+ const held = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {+ queue: 'hog',+ queuePriority: 0,+ })++ const heldResult = await hogFunctionHandler.execute({ invocation, action, result: held })++ expect(heldResult).toEqual({ scheduledAt: DateTime.fromMillis(start + hour) })+ expect(held.invocation.state.currentAction?.frequencyCapHoldDeadlineAt).toBe(+ DateTime.fromMillis(start + 2 * hour).toISO()+ )+ expect(held.logs[0].message).toContain('Holding send until')+ expect(held.metrics).toMatchObject([{ metric_name: 'message_frequency_cap_held', count: 1 }])++ Settings.now = () => start + wakeAfter+ checkFrequencyCap.mockClear()+ checkFrequencyCap.mockResolvedValueOnce({ ...wakeCheck, holdHours: 2 })+ const woken = createInvocationResult<CyclotronJobInvocationHogFlow>(held.invocation, {+ queue: 'hog',+ queuePriority: 0,+ })++ const wokenResult = await hogFunctionHandler.execute({+ invocation: held.invocation,+ action,+ result: woken,+ })++ expect(wokenResult.nextAction?.id).toBe('exit')+ expect(woken.logs[0].message).toContain('no slot opened before the hold ended')+ expect(woken.metrics).toMatchObject([{ metric_name: 'message_frequency_capped', count: 1 }])+ expect(checkFrequencyCap).toHaveBeenCalledTimes(checks)+ expect(mockFetch).not.toHaveBeenCalled()+ } finally {+ Settings.now = originalNow+ }+ }+ )++ it('should skip at once when the next slot frees after the hold would end', async () => {+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({+ capped: true,+ nextSlotAt: Date.now() + 3 * hour,+ holdHours: 2,+ })+ const invocationResult = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {+ queue: 'hog',+ queuePriority: 0,+ })++ const handlerResult = await hogFunctionHandler.execute({ invocation, action, result: invocationResult })++ expect(handlerResult.nextAction?.id).toBe('exit')+ expect(invocationResult.metrics).toMatchObject([{ metric_name: 'message_frequency_capped', count: 1 }])+ })++ it('should skip, not hold, a capped send that resumes on the email queue', async () => {+ // A hold here would drop the pending send that the email queue continuation carries.+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({+ capped: true,+ nextSlotAt: Date.now() + hour,+ holdHours: 2,+ })+ invocation.state.currentAction!.hogFunctionState = {+ globals: { ...createExampleHogFlowInvocation(invocation.hogFlow).state.event, inputs: {} } as any,+ timings: [],+ attempts: 0,+ } as any+ const invocationResult = createInvocationResult<CyclotronJobInvocationHogFlow>(invocation, {+ queue: 'email',+ queuePriority: 0,+ })++ const handlerResult = await hogFunctionHandler.execute({ invocation, action, result: invocationResult })++ expect(handlerResult.nextAction?.id).toBe('exit')+ expect(invocationResult.metrics).toMatchObject([{ metric_name: 'message_frequency_capped', count: 1 }])+ expect(invocationResult.invocation.state.currentAction?.frequencyCapHoldDeadlineAt).toBeUndefined()+ })+it.each([['a workflow run', undefined],['a broadcast run', 'broadcast-run-id'],@@ -576,7 +676,11 @@ describe('HogFunctionHandler', () => {)}const skipFrequencyCapped = (): void => {- ;(mockRecipientPreferencesService.isFrequencyCapped as jest.Mock).mockResolvedValueOnce(true)+ ;(mockRecipientPreferencesService.checkFrequencyCap as jest.Mock).mockResolvedValueOnce({+ capped: true,+ nextSlotAt: Date.now() + 60 * 60 * 1000,+ holdHours: null,+ })}it.each([diff --git a/nodejs/src/cdp/services/hogflows/actions/hog_function.ts b/nodejs/src/cdp/services/hogflows/actions/hog_function.tsindex 4386e42b93c0..7aa0700925e2 100644--- a/nodejs/src/cdp/services/hogflows/actions/hog_function.ts+++ b/nodejs/src/cdp/services/hogflows/actions/hog_function.ts@@ -20,7 +20,7 @@ import {import { HogExecutorExecuteAsyncOptions } from '../../hog-executor-async.service'import { EmailSkipReason, EmailStatusService } from '../../messaging/email-status.service'import { EmailValidationService } from '../../messaging/email-validation.service'-import { RecipientPreferencesService } from '../../messaging/recipient-preferences.service'+import { FrequencyCapCheck, RecipientPreferencesService } from '../../messaging/recipient-preferences.service'import { CdpUsageReporterService } from '../../usage/cdp-usage-reporter.service'import { trackHogFlowBillableInvocation } from '../billing-utils'import { HogFlowFunctionsService } from '../hogflow-functions.service'@@ -185,7 +185,10 @@ export class HogFunctionHandler implements ActionHandler {// Inputs are rendered once, on fresh entry into the action (continuations reuse the// rendered state in hogFunctionState) - so this also fires at most once per step per run- if (!invocation.state.currentAction?.hogFunctionState) {+ if (+ !invocation.state.currentAction?.hogFunctionState &&+ !invocation.state.currentAction?.frequencyCapHoldDeadlineAt+ ) {observeMissingVariableReferences(invocation, action, result)}@@ -214,6 +217,12 @@ export class HogFunctionHandler implements ActionHandler {result.metrics = [...result.metrics, ...functionResult.metrics]result.messageAssets = [...result.messageAssets, ...functionResult.messageAssets]+ if (functionResult.frequencyCapHold) {+ result.invocation.state.currentAction!.frequencyCapHoldDeadlineAt =+ functionResult.frequencyCapHold.deadlineAt+ return { scheduledAt: functionResult.frequencyCapHold.until }+ }+if (!functionResult.finished) {// Set the state of the function result on the substate of the flow for the next executionresult.invocation.state.currentAction!.hogFunctionState = {@@ -431,7 +440,12 @@ export class HogFunctionHandler implements ActionHandler {invocation: CyclotronJobInvocationHogFlow,action: Action,hogExecutorOptions?: HogExecutorExecuteAsyncOptions- ): Promise<CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> & { skipped?: boolean }> {+ ): Promise<+ CyclotronJobInvocationResult<CyclotronJobInvocationHogFunction> & {+ skipped?: boolean+ frequencyCapHold?: FrequencyCapHold+ }+ > {const hogFunction = await instrumentFn({ key: 'hogFlow.action.hogFunction.buildHogFunction', sendException: false },() => this.hogFlowFunctionsService.buildHogFunction(invocation.hogFlow, action.config, action.name)@@ -537,10 +551,46 @@ export class HogFunctionHandler implements ActionHandler {// This check runs last because it also records the send against the cap. If it ran before the// opt-out, suppression or bounce checks, a send that one of them skips would still use a slot.- if (- !hogExecutorOptions?.isTest &&- (await this.recipientPreferencesService.isFrequencyCapped(hogFunctionInvocation, action))- ) {+ // A held send that wakes after its hold ended is skipped before the check, so it never claims a slot late.+ const holdExpired = frequencyCapHoldExpired(invocation)+ const frequencyCap =+ hogExecutorOptions?.isTest || holdExpired+ ? ({ capped: false } as const)+ : await this.recipientPreferencesService.checkFrequencyCap(hogFunctionInvocation, action)+ if (holdExpired || frequencyCap.capped) {+ const hold = frequencyCap.capped ? frequencyCapHold(invocation, frequencyCap) : null+ if (hold) {+ return {+ finished: false,+ invocation: hogFunctionInvocation,+ frequencyCapHold: hold,+ logs: [+ {+ level: 'info',+ timestamp: DateTime.now(),+ // Worded apart from the skip line, which the metrics drill-down finds by 'reached the frequency cap'.+ message: `Holding send until ${hold.until.toUTC().toISO()}: the recipient is at the frequency cap.`,+ },+ ],+ // Counted once per held send, not on every wake that finds the cap still full.+ metrics: hold.firstHold+ ? [+ {+ team_id: hogFunctionInvocation.teamId,+ app_source_id: hogFunctionInvocation.parentRunId ?? hogFunctionInvocation.functionId,+ instance_id: action.id,+ metric_kind: 'other',+ metric_name: 'message_frequency_cap_held',+ count: 1,+ },+ ]+ : [],+ capturedPostHogEvents: [],+ warehouseWebhookPayloads: [],+ messageAssets: [],+ conversionWatchers: [],+ }+ }this.recordSkippedEmail(hogFunctionInvocation, action, 'frequency_capped', hogExecutorOptions)return {finished: true,@@ -550,7 +600,9 @@ export class HogFunctionHandler implements ActionHandler {{level: 'info',timestamp: DateTime.now(),- message: 'Skipping send: recipient reached the frequency cap.',+ message: invocation.state.currentAction?.frequencyCapHoldDeadlineAt+ ? 'Skipping send: recipient reached the frequency cap, and no slot opened before the hold ended.'+ : 'Skipping send: recipient reached the frequency cap.',},],metrics: [@@ -575,3 +627,37 @@ export class HogFunctionHandler implements ActionHandler {)}}++type FrequencyCapHold = { until: DateTime; deadlineAt: string; firstHold: boolean }++// Up to a minute of spread, so held sends for one person that wait on the same slot don't all wake at once.+const FREQUENCY_CAP_HOLD_JITTER_MS = 60_000+function frequencyCapHoldExpired(invocation: CyclotronJobInvocationHogFlow): boolean {+ const deadlineAt = invocation.state.currentAction?.frequencyCapHoldDeadlineAt+ return !!deadlineAt && DateTime.now() >= DateTime.fromISO(deadlineAt)+}++/** When the team holds capped messages and the hold has not ended, returns when to check the cap again. */+function frequencyCapHold(+ invocation: CyclotronJobInvocationHogFlow,+ cap: Extract<FrequencyCapCheck, { capped: true }>+): FrequencyCapHold | null {+ // A continuation on the email queue carries a pending send that a hold would drop, so it skips as before.+ if (!cap.holdHours || invocation.state.currentAction?.hogFunctionState) {+ return null+ }+ const now = DateTime.now()+ const startedDeadline = invocation.state.currentAction?.frequencyCapHoldDeadlineAt+ const deadline = startedDeadline ? DateTime.fromISO(startedDeadline) : now.plus({ hours: cap.holdHours })+ // No slot frees before the hold ends, so waiting cannot help.+ if (cap.nextSlotAt >= deadline.toMillis()) {+ return null+ }+ // Wake after the slot frees but before the deadline, which the next wake enforces strictly.+ const jitterMs = Math.min(+ Math.floor(Math.random() * FREQUENCY_CAP_HOLD_JITTER_MS),+ Math.floor((deadline.toMillis() - cap.nextSlotAt) / 2)+ )+ const until = DateTime.max(now, DateTime.fromMillis(cap.nextSlotAt + jitterMs))+ return { until, deadlineAt: deadline.toISO()!, firstHold: !startedDeadline }+}diff --git a/nodejs/src/cdp/services/managers/team-workflows-config.service.ts b/nodejs/src/cdp/services/managers/team-workflows-config.service.tsindex c32434562bde..59e5ddb039ba 100644--- a/nodejs/src/cdp/services/managers/team-workflows-config.service.ts+++ b/nodejs/src/cdp/services/managers/team-workflows-config.service.ts@@ -23,9 +23,11 @@ export type TeamWorkflowsConfig = {/** Max marketing messages one person gets per window. Null on either field means no cap. */marketing_frequency_cap_max_messages: number | nullmarketing_frequency_cap_window_days: number | null+ /** Hours a capped marketing message waits for a free slot. Null skips it at once. */+ marketing_frequency_cap_hold_hours: number | null}-export type FrequencyCap = { max_messages: number | null; window_days: number | null }+export type FrequencyCap = { max_messages: number | null; window_days: number | null; hold_hours: number | null }const DEFAULT_CONFIG: TeamWorkflowsConfig = {capture_workflows_engagement_events: false,@@ -35,6 +37,7 @@ const DEFAULT_CONFIG: TeamWorkflowsConfig = {email_sending_tier: 0,marketing_frequency_cap_max_messages: null,marketing_frequency_cap_window_days: null,+ marketing_frequency_cap_hold_hours: null,}/**@@ -119,6 +122,7 @@ export class TeamWorkflowsConfigService {return {max_messages: config.marketing_frequency_cap_max_messages,window_days: config.marketing_frequency_cap_window_days,+ hold_hours: config.marketing_frequency_cap_hold_hours,}}@@ -132,6 +136,7 @@ export class TeamWorkflowsConfigService {email_sending_tier: numbermarketing_frequency_cap_max_messages: number | nullmarketing_frequency_cap_window_days: number | null+ marketing_frequency_cap_hold_hours: number | null}>(PostgresUse.COMMON_READ,// Only DISABLED blocks: ENABLED and REINSTATED both permit sending, and '' means the@@ -139,7 +144,8 @@ export class TeamWorkflowsConfigService {`SELECT team_id, capture_workflows_engagement_events, email_tracking_consent_mode,email_sending_suspended_at IS NOT NULL AS email_sending_suspended,ses_tenant_sending_status = 'DISABLED' AS ses_tenant_provider_suspended,- email_sending_tier, marketing_frequency_cap_max_messages, marketing_frequency_cap_window_days+ email_sending_tier, marketing_frequency_cap_max_messages, marketing_frequency_cap_window_days,+ marketing_frequency_cap_hold_hoursFROM workflows_teamworkflowsconfigWHERE team_id = ANY($1)`,[validTeamIds(teamIds)],@@ -159,6 +165,7 @@ export class TeamWorkflowsConfigService {email_sending_tier: row.email_sending_tier ?? 0,marketing_frequency_cap_max_messages: row.marketing_frequency_cap_max_messages,marketing_frequency_cap_window_days: row.marketing_frequency_cap_window_days,+ marketing_frequency_cap_hold_hours: row.marketing_frequency_cap_hold_hours,}}return configsdiff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.tsindex 84217d319ede..ac4a0ca18511 100644--- a/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts+++ b/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts@@ -13,10 +13,10 @@ import { createTestTeamFixture } from '~/tests/helpers/sql'import { Hub, Team } from '~/types'import { RecipientsManagerService } from '../managers/recipients-manager.service'-import { TeamWorkflowsConfigService } from '../managers/team-workflows-config.service'+import { FrequencyCap, TeamWorkflowsConfigService } from '../managers/team-workflows-config.service'import { EmailSuppressionService, emailSuppressionConfigFromEnv } from './email-suppression.service'import { createFrequencyCapValkeyPool } from './frequency-cap-valkey-pool'-import { RecipientPreferencesService } from './recipient-preferences.service'+import { FrequencyCapCheck, RecipientPreferencesService } from './recipient-preferences.service'import { RecipientTokensService } from './recipient-tokens.service'const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')@@ -658,9 +658,9 @@ describe('RecipientPreferencesService', () => {})})- describe('isFrequencyCapped', () => {+ describe('checkFrequencyCap', () => {let valkey: RedisV2- let frequencyCap: { max_messages: number | null; window_days: number | null }+ let frequencyCap: FrequencyCaplet teamWorkflowsConfig: TeamWorkflowsConfigServicelet cappedService: RecipientPreferencesServicelet persons: { getCyclotronPerson: jest.Mock }@@ -691,7 +691,7 @@ describe('RecipientPreferencesService', () => {beforeEach(async () => {await deleteKeysWithPrefix(valkey, `@posthog/workflows-frequency-cap/${team.id}/`)- frequencyCap = { max_messages: 2, window_days: 7 }+ frequencyCap = { max_messages: 2, window_days: 7, hold_hours: null }teamWorkflowsConfig = new TeamWorkflowsConfigService(hub.postgres, hub.pubSub)jest.spyOn(teamWorkflowsConfig, 'getFrequencyCap').mockImplementation(() => Promise.resolve(frequencyCap))persons = { getCyclotronPerson: jest.fn().mockResolvedValue(null) }@@ -702,10 +702,11 @@ describe('RecipientPreferencesService', () => {})})- const sendAt = async (action: HogFlowAction, at: number): Promise<boolean> => {+ const checkAt = async (action: HogFlowAction, at: number): Promise<FrequencyCapCheck> => {jest.spyOn(Date, 'now').mockReturnValue(at)- return cappedService.isFrequencyCapped(createFunctionStepInvocation(action as any), action)+ return cappedService.checkFrequencyCap(createFunctionStepInvocation(action as any), action)}+ const sendAt = async (action: HogFlowAction, at: number): Promise<boolean> => (await checkAt(action, at)).cappedit('caps marketing sends past the limit until the window moves past the oldest send', async () => {const day = 24 * 60 * 60 * 1000@@ -713,33 +714,42 @@ describe('RecipientPreferencesService', () => {expect(await sendAt(emailAction(), start)).toBe(false)expect(await sendAt(emailAction(), start + day)).toBe(false)- expect(await sendAt(emailAction(), start + 2 * day)).toBe(true)+ expect(await checkAt(emailAction(), start + 2 * day)).toEqual({+ capped: true,+ nextSlotAt: start + 7 * day,+ holdHours: null,+ })expect(await sendAt(emailAction(), start + 7 * day + 1)).toBe(false)})it('lets a re-entered step visit keep its slot from the send time and counts a later visit', async () => {- frequencyCap = { max_messages: 1, window_days: 1 }+ frequencyCap = { max_messages: 1, window_days: 1, hold_hours: 12 }const hour = 60 * 60 * 1000const start = 1_800_000_000_000const action = emailAction()const invocation = createFunctionStepInvocation(action)invocation.state.actionId = action.idinvocation.state.actionStepCount = 1- const checkAt = async (at: number): Promise<boolean> => {+ const visitAt = async (at: number): Promise<FrequencyCapCheck> => {jest.spyOn(Date, 'now').mockReturnValue(at)- return cappedService.isFrequencyCapped(invocation, action)+ return cappedService.checkFrequencyCap(invocation, action)}// The email queue runs the step a second time after the hog queue routed it there and paced it.- expect(await checkAt(start)).toBe(false)- expect(await checkAt(start + 23 * hour)).toBe(false)+ expect(await visitAt(start)).toEqual({ capped: false })+ expect(await visitAt(start + 23 * hour)).toEqual({ capped: false })+ // The slot frees a day after the second run moved it, not a day after the first check.invocation.state.actionStepCount = 3- expect(await checkAt(start + 25 * hour)).toBe(true)+ expect(await visitAt(start + 25 * hour)).toEqual({+ capped: true,+ nextSlotAt: start + 47 * hour,+ holdHours: 12,+ })})it('counts a push to a named person against that person, not the run person', async () => {- frequencyCap = { max_messages: 1, window_days: 7 }+ frequencyCap = { max_messages: 1, window_days: 7, hold_hours: null }persons.getCyclotronPerson.mockResolvedValue({ id: 'named-person-id' })const pushToNamed: Extract<HogFlowAction, { type: 'function_push' }> = {id: 'push',@@ -770,9 +780,17 @@ describe('RecipientPreferencesService', () => {})it.each([- ['transactional sends', emailAction('transactional'), { max_messages: 0, window_days: 7 }],- ['marketing sends that skip the cap', emailAction('marketing', true), { max_messages: 1, window_days: 7 }],- ['teams with no cap', emailAction(), { max_messages: null, window_days: null }],+ [+ 'transactional sends',+ emailAction('transactional'),+ { max_messages: 0, window_days: 7, hold_hours: null },+ ],+ [+ 'marketing sends that skip the cap',+ emailAction('marketing', true),+ { max_messages: 1, window_days: 7, hold_hours: null },+ ],+ ['teams with no cap', emailAction(), { max_messages: null, window_days: null, hold_hours: null }],])('never caps %s', async (_, action, cap) => {frequencyCap = capfor (let i = 0; i < 3; i++) {diff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.tsindex b9963c487801..6bf19cb6b079 100644--- a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts+++ b/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts@@ -23,14 +23,28 @@ export type RecipientSkipReason = 'suppressed' | 'opted_out'// is keyed on the step visit. The email queue and send retries run the same step visit again, so a// visit that already holds a slot passes. That run also moves the slot score to now, because the email// queue can delay the actual send by hours and the window must start when the email goes out.+// A capped call returns the time in ms when the next slot frees up: the oldest slot that must leave+// the window before the count drops below the cap. An allowed call returns 0.const FREQUENCY_CAP_SCRIPT = `redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', tonumber(ARGV[1]) - tonumber(ARGV[2]))-if not redis.call('ZSCORE', KEYS[1], ARGV[4]) and redis.call('ZCARD', KEYS[1]) >= tonumber(ARGV[3]) then return 1 end+if not redis.call('ZSCORE', KEYS[1], ARGV[4]) then+ local count = redis.call('ZCARD', KEYS[1])+ if count >= tonumber(ARGV[3]) then+ local freeing = redis.call('ZRANGE', KEYS[1], count - tonumber(ARGV[3]), count - tonumber(ARGV[3]), 'WITHSCORES')+ return tonumber(freeing[2]) + tonumber(ARGV[2])+ end+endredis.call('ZADD', KEYS[1], ARGV[1], ARGV[4])redis.call('PEXPIRE', KEYS[1], ARGV[2])return 0`+export type FrequencyCapCheck =+ | { capped: false }+ // nextSlotAt is when the person can get a marketing message again, in ms. holdHours is how long the+ // team lets a capped message wait for that slot; null means skip it.+ | { capped: true; nextSlotAt: number; holdHours: number | null }+export class RecipientPreferencesService {constructor(private recipientsManager: RecipientsManagerService,@@ -42,11 +56,11 @@ export class RecipientPreferencesService {}) {}- /** Returns true when the person is at the cap. Otherwise records this send against the cap and returns false. */- public async isFrequencyCapped(+ /** Reports whether the person is at the cap. When they are not, records this send against the cap. */+ public async checkFrequencyCap(invocation: CyclotronJobInvocationHogFunction,action: HogFlowAction- ): Promise<boolean> {+ ): Promise<FrequencyCapCheck> {const messageAction = this.asMessageAction(action)if (!this.frequencyCap ||@@ -54,20 +68,19 @@ export class RecipientPreferencesService {messageAction.config.message_category_type === 'transactional' ||(messageAction.type === 'function_email' && messageAction.config.skip_frequency_cap === true)) {- return false+ return { capped: false }}try {- const { max_messages, window_days } = await this.frequencyCap.teamWorkflowsConfig.getFrequencyCap(- invocation.teamId- )+ const { max_messages, window_days, hold_hours } =+ await this.frequencyCap.teamWorkflowsConfig.getFrequencyCap(invocation.teamId)if (!max_messages || !window_days) {- return false+ return { capped: false }}const personId = await this.cappedPersonId(invocation, messageAction, this.frequencyCap.persons)if (!personId) {- return false+ return { capped: false }}- const capped = await this.frequencyCap.valkey.useClient(+ const nextSlotAt = await this.frequencyCap.valkey.useClient({ name: 'workflows-frequency-cap', failOpen: true },(client) =>client.eval(@@ -80,12 +93,12 @@ export class RecipientPreferencesService {workflowStepDispatchKeyFromInvocation(invocation) ?? `${invocation.id}:${action.id}`) as Promise<number>)- return capped === 1+ return nextSlotAt ? { capped: true, nextSlotAt, holdHours: hold_hours } : { capped: false }} catch (error) {// Fail open: a config or Valkey pool error must never block a send. failOpen above only// covers errors inside the Valkey callback.logger.error(`Failed to check the frequency cap for team ${invocation.teamId}:`, error)- return false+ return { capped: false }}}diff --git a/nodejs/src/cdp/types.ts b/nodejs/src/cdp/types.tsindex ef962fa084c5..2bb28279f5e4 100644--- a/nodejs/src/cdp/types.ts+++ b/nodejs/src/cdp/types.ts@@ -262,6 +262,7 @@ export type MinimalAppMetric = {| 'email_bounced_undetermined'| 'email_bounce_prevented'| 'message_frequency_capped'+ | 'message_frequency_cap_held'| 'email_suppressed'| 'email_missing_recipient'| 'email_suspended'@@ -560,6 +561,9 @@ export type HogFlowInvocationContext = {parkedAt?: string}resumeResult?: { key: string; status: WorkflowStepResumeStatus; result?: Record<string, unknown> }+ // Set when a message step first finds the person at the frequency cap and the team holds capped+ // messages. The step re-checks the cap on each wake and skips the send once this ISO time passes.+ frequencyCapHoldDeadlineAt?: string}// Set by the subscription matcher consumer when an incoming event matched the// workflow's event-based conversion goals. shouldExitEarly reads and clears it.