Skip to content

: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.

21.4 KB
Raw Blame
import { z } from 'zod'

import { CyclotronInputMappingSchema, CyclotronInputSchema, CyclotronJobInputSchemaTypeSchema } from './cyclotron'

export const HogFlowEmailSendingRateLimitSchema = z.object({
    count: z.number().int().positive(),
    period: z.enum(['minute', 'hour']),
})

export type HogFlowEmailSendingRateLimit = z.infer<typeof HogFlowEmailSendingRateLimitSchema>

const HogFlowOutputVariableSchema = z.object({
    key: z.string(),
    result_path: z.string().optional().nullable(), // The path within the action result to store, e.g. 'response.user.id'
    spread: z.boolean().optional().nullable(), // When true, spread object result into multiple variables as {key}_{property}
    label: z.string().optional().nullable(), // Display label for the auto-created workflow variable
})

// Rows written before the API coerced bare key strings — normalize at read so one legacy value
// can't make the whole flow row unparseable. The annotated return type keeps the union's output
// type identical to the object schema's, so downstream field access still narrows.
const legacyStringOutputVariable = z.string().transform((key): z.infer<typeof HogFlowOutputVariableSchema> => ({ key }))

const _commonActionFields = {
    id: z.string(),
    name: z.string(),
    description: z.string(),
    on_error: z.enum(['continue', 'abort']).optional(),
    created_at: z.number(),
    updated_at: z.number(),
    filters: z.any(), // TODO: Correct to the right type
    output_variable: z // The Hogflow-level variable to store the output of this action into
        .union([
            HogFlowOutputVariableSchema,
            z.array(z.union([HogFlowOutputVariableSchema, legacyStringOutputVariable])),
            legacyStringOutputVariable,
        ])
        .optional()
        .nullable(),
}

const HogFlowTriggerSchema = z.discriminatedUnion('type', [
    z.object({
        type: z.literal('event'),
        filters: z.object({
            events: z.array(z.any()).optional(),
            properties: z.array(z.any()).optional(),
            actions: z.array(z.any()).optional(),
        }),
    }),
    z.object({
        type: z.literal('webhook'),
        template_uuid: z.string().optional(), // May be used later to specify a specific template version
        template_id: z.string(),
        inputs: z.record(z.string(), CyclotronInputSchema),
    }),
    z.object({
        type: z.literal('manual'),
        template_uuid: z.string().optional(), // May be used later to specify a specific template version
        template_id: z.string(),
        inputs: z.record(z.string(), CyclotronInputSchema),
    }),
    z.object({
        type: z.literal('tracking_pixel'),
        template_uuid: z.string().optional(), // May be used later to specify a specific template version
        template_id: z.string(),
        inputs: z.record(z.string(), CyclotronInputSchema),
    }),
    z.object({
        type: z.literal('schedule'),
    }),
    // A transactional email: Django's send endpoint runs the workflow once per call.
    z.object({
        type: z.literal('api'),
    }),
    z.object({
        type: z.literal('cohort'),
        cohort_id: z.number(),
        transition: z.enum(['entered', 'left']),
    }),
    z.object({
        type: z.literal('batch'),
        filters: z.object({
            // 'accounts' fans out one run per customer analytics account instead of per person
            audience_type: z.enum(['persons', 'accounts']).optional(),
            properties: z.array(z.any()),
            filter_test_accounts: z.boolean().optional(),
            tag_names: z.array(z.string()).optional(),
            assignment_status: z.enum(['all', 'assigned', 'unassigned']).optional(),
            assigned_to_user_ids: z.array(z.number()).optional(),
            all_roles_unassigned: z.boolean().optional(),
        }),
    }),
    z.object({
        type: z.literal('data-warehouse-table'),
        // Dot-notated table name, matching the format produced by the Python CDPProducer
        // (see get_data_warehouse_table_name) so producer gating and trigger config use identical strings.
        table_name: z.string(),
        filters: z.object({
            // Row-property filters only - warehouse-triggered workflows are person-less ("row-scoped")
            properties: z.array(z.any()).optional(),
        }),
        // Optional row column used as the masking / dedup key in place of distinct_id
        key_property: z.string().optional(),
    }),
    z.object({
        type: z.literal('internal-event'),
        filters: z.object({
            source: z.literal('internal-events'),
            events: z.array(z.any()).min(1),
            properties: z.array(z.any()).optional(),
        }),
    }),
    z.object({
        type: z.literal('data-warehouse-view'),
        // The materialized view's own name, which is also the name it is queryable by in HogQL.
        table_name: z.string(),
        filters: z.object({
            // Row-property filters only - warehouse-triggered workflows are person-less ("row-scoped")
            properties: z.array(z.any()).optional(),
        }),
        // Optional row column used as the masking / dedup key in place of distinct_id
        key_property: z.string().optional(),
    }),
])

export const HogFlowActionSchema = z.discriminatedUnion('type', [
    // Trigger
    z.object({
        ..._commonActionFields,
        type: z.literal('trigger'),
        config: HogFlowTriggerSchema,
        // A trigger's event filters are stored on the top-level Hogflow object
    }),
    // Branching
    z.object({
        ..._commonActionFields,
        type: z.literal('conditional_branch'),
        config: z.object({
            conditions: z.array(
                z.object({
                    filters: z.any(), // type this stronger
                    name: z.string().optional(), // Custom name for the condition
                })
            ),
        }),
    }),
    z.object({
        ..._commonActionFields,
        type: z.literal('random_cohort_branch'),
        config: z.object({
            cohorts: z.array(
                z.object({
                    percentage: z.number(),
                    name: z.string().optional(), // Custom name for the cohort
                })
            ),
        }),
    }),

    // Time based
    z.object({
        ..._commonActionFields,
        type: z.literal('delay'),
        // Two ways to say when to continue, exactly one of which is set. `delay_duration` waits a fixed
        // span from when the step starts. `delay_until` waits for an instant carried by the person or the
        // event, which a fixed duration cannot express (e.g. a per-person trial expiry).
        config: z.object({
            delay_duration: z.string().optional(),
            delay_until: z
                .object({
                    // HogQL evaluating to a datetime: an ISO string, a HogDateTime, or unix seconds.
                    expression: z.string(),
                    // Signed offset applied to that instant, e.g. '-1d' for "one day before". Kept separate
                    // from the expression so the builder can offer a property picker instead of arithmetic.
                    offset: z.string().optional(),
                    // Which zone a date with no offset of its own is read in, the same three fields
                    // wait_until_time_window uses. A stored '2026-03-01' means midnight where the customer
                    // lives, not midnight UTC.
                    timezone: z.string().nullish(),
                    use_person_timezone: z.boolean().optional(),
                    fallback_timezone: z.string().nullish(),
                    bytecode: z.any().optional(),
                    bytecode_error: z.string().optional(),
                })
                .optional(),
            // How long past the step's start the wait may run, so a far-future or malformed instant cannot
            // park a run indefinitely. Applies to delay_until only.
            max_delay_duration: z.string().optional(),
        }),
    }),
    z.object({
        ..._commonActionFields,
        type: z.literal('wait_until_condition'),
        config: z.object({
            condition: z.object({
                filters: z.any(), // type this stronger
                name: z.string().optional(), // Custom name for the condition
            }),
            events: z
                .array(
                    z.object({
                        filters: z.any(),
                        name: z.string().optional(),
                    })
                )
                .optional(),
            max_wait_duration: z.string(),
        }),
    }),

    z.object({
        ..._commonActionFields,
        type: z.literal('wait_until_time_window'),
        config: z.object({
            timezone: z.string().nullable(),
            // When true, use the person's $geoip_time_zone property for timezone
            use_person_timezone: z.boolean().optional(),
            // Fallback timezone when use_person_timezone is true but person has no timezone set
            fallback_timezone: z.string().nullable().optional(),
            // Date can be special values "weekday", "weekend" or a list of days of the week e.g. 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'
            day: z.union([
                z.literal('any'),
                z.literal('weekday'),
                z.literal('weekend'),
                z.array(z.enum(['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'])),
            ]),
            // time can be "any", or a time range [start, end]
            time: z.union([
                z.literal('any'),
                z.tuple([z.string(), z.string()]), // e.g. ['10:00', '11:00']
            ]),
        }),
    }),

    // Native messages
    z.object({
        ..._commonActionFields,
        type: z.literal('function_email'),
        config: z.object({
            message_category_id: z.string().optional(),
            message_category_type: z.enum(['marketing', 'transactional']).optional(),
            // When false, no open pixel is injected, links are not rewritten, and the send uses the
            // untracked SES configuration set. Absent/true means tracked (existing behavior).
            tracking_enabled: z.boolean().optional(),
            // Set from a transactional template marked sensitive: the stored asset keeps a placeholder instead
            // of the body, events keep no subject, clicked links keep only their origin, and the run
            // snapshot keeps no variables.
            sensitive: z.boolean().optional(),
            // When true, links get utm_source, utm_medium and utm_campaign tags they don't already carry.
            utm_tags_enabled: z.boolean().optional(),
            // When true, a marketing send ignores the team's frequency cap and takes no slot under it. Opt-outs
            // and unsubscribe headers still apply. For product email that is marketing in form but must not
            // crowd out, or be crowded out by, other marketing email.
            skip_frequency_cap: z.boolean().optional(),
            // Liquid templates that replace the default tag values. An empty value keeps the default.
            utm_params: z
                .object({
                    utm_source: z.string().optional(),
                    utm_medium: z.string().optional(),
                    utm_campaign: z.string().optional(),
                    utm_content: z.string().optional(),
                })
                .optional(),
            template_uuid: z.string().optional(), // May be used later to specify a specific template version
            template_id: z.literal('template-email'),
            inputs: z.record(z.string(), CyclotronInputSchema),
            mappings: z.array(CyclotronInputMappingSchema).optional(),
        }),
    }),

    // CDP functions
    z.object({
        ..._commonActionFields,
        type: z.literal('function'),
        config: z.object({
            template_uuid: z.string().optional(), // May be used later to specify a specific template version
            template_id: z.string(),
            inputs: z.record(z.string(), CyclotronInputSchema),
            mappings: z.array(CyclotronInputMappingSchema).optional(),
        }),
    }),
    z.object({
        ..._commonActionFields,
        type: z.literal('function_sms'),
        config: z.object({
            message_category_id: z.string().optional(),
            message_category_type: z.enum(['marketing', 'transactional']).optional(),
            template_uuid: z.string().optional(),
            template_id: z.literal('template-twilio'),
            inputs: z.record(z.string(), CyclotronInputSchema),
            mappings: z.array(CyclotronInputMappingSchema).optional(),
        }),
    }),
    z.object({
        ..._commonActionFields,
        type: z.literal('function_push'),
        config: z.object({
            message_category_id: z.string().optional(),
            message_category_type: z.enum(['marketing', 'transactional']).optional(),
            template_uuid: z.string().optional(),
            template_id: z.literal('template-native-push'),
            // When true, the stored asset keeps a placeholder instead of the notification's content, and the
            // run snapshot keeps no variables.
            sensitive: z.boolean().optional(),
            inputs: z.record(z.string(), CyclotronInputSchema),
            mappings: z.array(CyclotronInputMappingSchema).optional(),
        }),
    }),
    // Exit
    z.object({
        ..._commonActionFields,
        type: z.literal('exit'),
        config: z.object({
            reason: z.string().optional(),
        }),
    }),
])

const HogFlowEdgeSchema = z.object({
    from: z.string(),
    to: z.string(),
    type: z.enum(['continue', 'branch']),
    index: z.number().optional(),
})

// Optional masking config for the trigger, allows HogFlows to be rate limited per distinct ID or other property
const HogFlowTriggerMaskingSchema = z.object({
    ttl: z.number().nullable(),
    hash: z.string(),
    bytecode: z.array(z.union([z.string(), z.number()])),
    threshold: z.number().nullable(),
})

export const HogFlowSchema = z.object({
    id: z.string(),
    team_id: z.number(),
    version: z.number(),
    name: z.string(),
    status: z.enum(['active', 'draft', 'archived']),
    trigger: HogFlowTriggerSchema,
    trigger_masking: HogFlowTriggerMaskingSchema.optional().nullable(),
    conversion: z
        .object({
            // Preferred form, matching how delay steps express a duration: `7d`, `12h`, `90d`.
            window: z.string().nullable().optional(),
            filters: z.any(),
            bytecode: z.array(z.union([z.string(), z.number()])),
            events: z
                .array(
                    z.object({
                        filters: z.any(),
                        name: z.string().optional(),
                    })
                )
                .optional(),
        })
        .optional(),
    exit_condition: z.enum([
        'exit_on_conversion',
        'exit_on_trigger_not_matched',
        'exit_on_trigger_not_matched_or_conversion',
        'exit_only_at_end',
    ]),
    // User-configured email pacing for deliverability. The email worker holds this flow's sends
    // under the limit by rescheduling over-limit sends, never dropping them.
    email_sending_rate_limit: HogFlowEmailSendingRateLimitSchema.optional().nullable(),
    // Set when PostHog paused this flow's email automatically because its spam complaint or hard
    // bounce rate breached a threshold. Non-null means the email service skips every send for this
    // flow, including test sends. Same value shapes as `updated_at`: pg returns a Date, fixtures
    // use epoch millis or an ISO string.
    email_sending_paused_at: z.union([z.number(), z.string(), z.date()]).optional().nullable(),
    email_sending_paused_reason: z.string().optional().nullable(),
    // "auto" (deliverability detector) or "staff". Staff pauses are not customer-resumable, so the
    // skip log tells the customer to contact support instead of pointing at the resume button.
    email_sending_paused_by: z.string().optional().nullable(),
    actions: z.array(HogFlowActionSchema),
    // Secret function inputs, split out of `actions` and stored Fernet-encrypted at rest, keyed by
    // action id then input key. Decrypted by the manager and merged back into `action.config.inputs`
    // before execution; never present on the plaintext `actions` blob.
    encrypted_inputs: z.record(z.string(), z.record(z.string(), CyclotronInputSchema)).optional().nullable(),
    abort_action: z.string().optional(),
    edges: z.array(HogFlowEdgeSchema),
    variables: z.array(CyclotronJobInputSchemaTypeSchema).optional().nullable(),
    billable_action_types: z.array(z.string()).optional().nullable(),
    // Skip-forward map for deleted steps ({deleted_action_id: surviving_action_id}), maintained by
    // the API on live graph edits. Values always reference actions present in this flow's `actions`.
    action_redirects: z.record(z.string(), z.string()).optional().nullable(),
    // Selected by the worker (HOG_FLOW_FIELDS); pg returns timestamptz as a Date, fixtures use
    // epoch millis. Used to distinguish live edits from malformed-from-birth graphs.
    updated_at: z.union([z.number(), z.string(), z.date()]).optional(),
})

export type RowScopedTrigger = Extract<
    HogFlow['trigger'],
    { type: 'data-warehouse-table' | 'data-warehouse-view' | 'internal-event' }
>

/**
 * A row-scoped trigger produces one run per delivery (a warehouse row, a Slack message, a GitHub
 * event), with the delivery's own properties under `event.properties` and no person attached.
 * Keep in sync with the backend's ROW_SCOPED_TRIGGER_TYPES.
 */
export function isRowScopedTrigger(trigger: HogFlow['trigger']): trigger is RowScopedTrigger {
    return (
        trigger?.type === 'data-warehouse-table' ||
        trigger?.type === 'data-warehouse-view' ||
        trigger?.type === 'internal-event'
    )
}

// The internal event a Slack-connected workflow's trigger fires on. Shared by the internal-events
// consumer's eligibility check and the test-run trigger handler so both match the same events.
// The Python producer keeps its own copy in products/slack_app/backend/slack_workflow_events.py.
export const SLACK_MESSAGE_RECEIVED_EVENT = '$slack_message_received'

// The same, for a GitHub delivery. The Python producer keeps its own copy in
// products/workflows/backend/github_workflow_events.py.
export const GITHUB_EVENT_RECEIVED_EVENT = '$github_event_received'

// The event ids an internal-event trigger's filters name, or null when the filters are not the
// shape the internal-events consumer accepts (wrong source, no events, or action/warehouse
// filters, which that stream cannot evaluate). Shared by the consumer's eligibility check and
// the test-run trigger handler so both accept the same filters.
export function getInternalEventFilterEventIds(filters: unknown): string[] | null {
    if (!filters || typeof filters !== 'object') {
        return null
    }

    const { source, events, actions, data_warehouse } = filters as {
        source?: unknown
        events?: unknown
        actions?: unknown
        data_warehouse?: unknown
    }
    const hasUnsupportedFilters =
        (actions !== undefined && (!Array.isArray(actions) || actions.length > 0)) ||
        (data_warehouse !== undefined && (!Array.isArray(data_warehouse) || data_warehouse.length > 0))
    if (source !== 'internal-events' || !Array.isArray(events) || !events.length || hasUnsupportedFilters) {
        return null
    }

    const eventIds = events.map((event) => (event && typeof event === 'object' ? (event as { id?: unknown }).id : null))
    return eventIds.every((eventId): eventId is string => typeof eventId === 'string' && eventId.trim().length > 0)
        ? eventIds
        : null
}

export function hasMatchingInternalEventFilter(filters: unknown, eventName: string): boolean {
    return getInternalEventFilterEventIds(filters)?.includes(eventName) ?? false
}

// Synthetic event name stamped on the row built for a warehouse-row trigger from a synced source
// table. Shared by the warehouse-events consumer's eligibility check and the test-run trigger
// handler so both match the same rows.
export const WAREHOUSE_SOURCE_ROW_EVENT = '$warehouse_source_row'

// The same, for a row a materialized view run added or updated.
export const WAREHOUSE_VIEW_ROW_EVENT = '$warehouse_view_row'

// Property on the synthetic row event holding the dot-notated source table name, read against a
// row-scoped trigger's own `table_name` to confirm a row actually came from that table.
export const DWH_SOURCE_TABLE_PROPERTY = '$source_table'

// The row-scoped trigger type a synthetic warehouse event's name matches, or null for anything
// else. Explicit rather than defaulting to one type, so a caller that can receive an arbitrary
// event - like a workflow test run - does not treat an unrelated event as a warehouse row by
// elimination.
export function rowScopedTriggerTypeForEvent(eventName: string | undefined): RowScopedTrigger['type'] | null {
    if (eventName === WAREHOUSE_VIEW_ROW_EVENT) {
        return 'data-warehouse-view'
    }
    if (eventName === WAREHOUSE_SOURCE_ROW_EVENT) {
        return 'data-warehouse-table'
    }
    return null
}

// NOTE: these are purposefully exported as interfaces to support kea typegen
export interface HogFlow extends z.infer<typeof HogFlowSchema> {}
export type HogFlowAction = z.infer<typeof HogFlowActionSchema> & Record<string, unknown>
export interface HogFlowEdge extends z.infer<typeof HogFlowEdgeSchema> {}