: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): add a step-by-step wizard for transactional emails (#124088)
Meikel Ratz9e44f258d290
diff --git a/frontend/src/products.tsx b/frontend/src/products.tsxindex da0cac69bca6..1eac64193f2e 100644--- a/frontend/src/products.tsx+++ b/frontend/src/products.tsx@@ -393,6 +393,7 @@ export const productRoutes: Record<string, [string, string]> = {'/transactional/suppression': ['Transactional', 'transactional'],'/transactional/reputation': ['Transactional', 'transactional'],'/transactional/settings': ['Transactional', 'transactional'],+ '/transactional/new': ['Transactional', 'transactional'],'/transactional/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],'/broadcasts/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],'/broadcasts/new': ['Broadcast', 'broadcast'],@@ -2031,6 +2032,7 @@ export const productUrls = {broadcast: (id: string): string => `/broadcasts/${id}`,broadcastNew: (): string => '/broadcasts/new',transactional: (tab?: MessagingNavTabKey): string => `/transactional${tab ? `/${tab}` : ''}`,+ transactionalNew: (): string => '/transactional/new',transactionalTemplate: (id: string): string => `/transactional/library/templates/${id}`,broadcastsTemplate: (id: string): string => `/broadcasts/library/templates/${id}`,}diff --git a/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsx b/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsxindex 0cd075d75986..7d7bc1782788 100644--- a/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsx+++ b/frontend/src/scenes/hog-functions/email-templater/EmailSenderForm.tsx@@ -34,7 +34,8 @@ export function EmailSenderForm({senders: EmailSender[]onChangeFrom: (from: EmailTemplateFrom) => voidonChangeReplyTo: (replyTo: string) => void- onDone: () => void+ /** Shows a Done button, for when the form sits in a dropdown. */+ onDone?: () => void}): JSX.Element {const sender = senders.find((candidate) => candidate.id === from.integrationId)const domain = senderDomain(sender)@@ -106,11 +107,13 @@ export function EmailSenderForm({data-attr="transactional-email-reply-to"/></LemonField.Pure>- <div className="flex justify-end">- <LemonButton type="primary" size="small" onClick={onDone}>- Done- </LemonButton>- </div>+ {onDone ? (+ <div className="flex justify-end">+ <LemonButton type="primary" size="small" onClick={onDone}>+ Done+ </LemonButton>+ </div>+ ) : null}</div>)}diff --git a/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsx b/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsxindex e990f2d12462..870dac0a65a8 100644--- a/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsx+++ b/frontend/src/scenes/hog-functions/email-templater/EmailTemplater.tsx@@ -144,6 +144,9 @@ function DestinationEmailTemplaterForm({fieldsHidden?: boolean}): JSX.Element {const { logicProps, mergeTags, activeContentTab, emailTemplate } = useValues(emailTemplaterLogic)+ // The editor rebuilds itself when its options change, so it keeps the tags it started with.+ // Later changes reach it through setMergeTags in the logic.+ const [initialMergeTags] = useState(mergeTags)const { setEmailEditorRef, onEmailEditorReady } = useActions(emailTemplaterLogic)return (@@ -202,7 +205,7 @@ function DestinationEmailTemplaterForm({onReady={() => onEmailEditorReady()}minHeight={20}options={{- mergeTags,+ mergeTags: initialMergeTags,displayMode: 'email',appearance: {actionBar: {@@ -547,6 +550,9 @@ function NativeEmailTemplaterForm({visibleFields,emailTemplate,} = useValues(emailTemplaterLogic)+ // The editor rebuilds itself when its options change, so it keeps the tags it started with.+ // Later changes reach it through setMergeTags in the logic.+ const [initialMergeTags] = useState(mergeTags)const { setEmailEditorRef, onEmailEditorReady, setActiveContentTab, hideAdvancedField, revealAdvancedField } =useActions(emailTemplaterLogic)// With the AI panel integration on, chat sits beside the editor and width is scarce, so the@@ -726,7 +732,7 @@ function NativeEmailTemplaterForm({onReady={() => onEmailEditorReady()}minHeight={20}options={{- mergeTags,+ mergeTags: initialMergeTags,displayMode: 'email',appearance: {actionBar: {diff --git a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.ts b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.tsindex c4af268fa340..36b88fe6d841 100644--- a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.ts+++ b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.test.ts@@ -156,6 +156,47 @@ describe('emailTemplaterLogic', () => {})})+ describe('merge tags', () => {+ beforeEach(() => {+ useMocks({ get: { '/api/projects/:team_id/property_definitions/': { results: [{ name: 'email' }] } } })+ })++ it.each([+ { type: 'native_email_template', variables: undefined, expected: ['email'] },+ {+ type: 'native_email_transactional_template',+ variables: { variables: { first_name: '', reset_link: '' } },+ expected: ['variables.first_name', 'variables.reset_link'],+ },+ ] as const)('$type offers $expected', async ({ type, variables, expected }) => {+ logic = emailTemplaterLogic(makeProps({ type, variables }))+ logic.mount()+ await expectLogic(logic).toFinishAllListeners()++ const offered = Object.keys(logic.values.mergeTags).filter((key) => !key.startsWith('unsubscribe'))+ expect(offered).toEqual(expected)+ })++ it('pushes a newly added variable into the open editor', async () => {+ const setMergeTags = jest.fn()+ const props = makeProps({ type: 'native_email_transactional_template', variables: { variables: {} } })+ logic = emailTemplaterLogic(props)+ logic.mount()+ logic.actions.setEmailEditorRef({+ editor: { setMergeTags, addEventListener: jest.fn(), loadDesign: jest.fn() },+ } as any)+ logic.actions.onEmailEditorReady()++ emailTemplaterLogic({ ...props, variables: { variables: { code: '' } } })++ expect(setMergeTags).toHaveBeenLastCalledWith(+ expect.objectContaining({+ 'variables.code': expect.objectContaining({ value: '{{ variables.code }}' }),+ })+ )+ })+ })+describe('modal content tab default', () => {it.each([{diff --git a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsx b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsxindex 7c31f17bcdbb..16467bceb6b9 100644--- a/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsx+++ b/frontend/src/scenes/hog-functions/email-templater/emailTemplaterLogic.tsx@@ -188,6 +188,46 @@ export function buildPersonPropertyMergeValue(name: string): string {return `{{person.properties['${escaped}']}}`}+/** The merge tags the visual editor offers. A transactional email gets its own variables instead of person properties. */+export function buildMergeTags(+ personPropertyDefinitions: PropertyDefinition[],+ type: EmailTemplaterType,+ variables: Record<string, any> | undefined+): UnlayerMergeTags {+ const tags: UnlayerMergeTags = {+ unsubscribe_url: {+ name: 'Unsubscribe URL',+ value: '{{unsubscribe_url}}',+ sample: 'https://example.com/unsubscribe/12345',+ },+ unsubscribe_url_one_click: {+ name: 'One-Click Unsubscribe URL',+ value: '{{unsubscribe_url_one_click}}',+ sample: 'https://example.com/unsubscribe/12345?one_click_unsubscribe=1',+ },+ }++ // A transactional email can't read person properties. It reads what the API call passes in+ // `message_data`, which the caller lists under `variables.variables`.+ if (type === 'native_email_transactional_template') {+ Object.keys(variables?.variables ?? {}).forEach((name) => {+ tags[`variables.${name}`] = { name, value: `{{ variables.${name} }}`, sample: name }+ })+ return tags+ }++ // Add person properties as merge tags+ personPropertyDefinitions.forEach((property: PropertyDefinition) => {+ tags[property.name] = {+ name: property.name,+ value: buildPersonPropertyMergeValue(property.name),+ sample: property.example || `Sample ${property.name}`,+ }+ })++ return tags+}+export interface EmailTemplaterLogicProps {value: EmailTemplate | nullonChange: (value: EmailTemplate) => void@@ -393,7 +433,11 @@ export interface emailTemplaterLogicActions {export interface emailTemplaterLogicMeta {__keaTypeGenInternalSelectorTypes: {logicProps: (arg: any) => EmailTemplaterLogicProps- mergeTags: (personPropertyDefinitions: PropertyDefinition[]) => UnlayerMergeTags+ mergeTags: (+ personPropertyDefinitions: PropertyDefinition[],+ arg: EmailTemplaterType,+ arg2: Record<string, any> | undefined+ ) => UnlayerMergeTagsunlayerEditorProjectId: (preflight: PreflightStatus | null) => 275430 | undefinedemailMediaLibraryEnabled: (arg: EmailTemplaterType, unlayerEditorProjectId: 275430 | undefined) => booleanunlayerEditorUser: (@@ -533,32 +577,16 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([selectors({logicProps: [() => [(_, props) => props], (props: EmailTemplaterLogicProps) => props],mergeTags: [- (s) => [s.personPropertyDefinitions],- (personPropertyDefinitions: PropertyDefinition[]): UnlayerMergeTags => {- const tags: UnlayerMergeTags = {- unsubscribe_url: {- name: 'Unsubscribe URL',- value: '{{unsubscribe_url}}',- sample: 'https://example.com/unsubscribe/12345',- },- unsubscribe_url_one_click: {- name: 'One-Click Unsubscribe URL',- value: '{{unsubscribe_url_one_click}}',- sample: 'https://example.com/unsubscribe/12345?one_click_unsubscribe=1',- },- }-- // Add person properties as merge tags- personPropertyDefinitions.forEach((property: PropertyDefinition) => {- tags[property.name] = {- name: property.name,- value: buildPersonPropertyMergeValue(property.name),- sample: property.example || `Sample ${property.name}`,- }- })-- return tags- },+ (s) => [+ s.personPropertyDefinitions,+ (_, props: EmailTemplaterLogicProps) => props.type,+ (_, props: EmailTemplaterLogicProps) => props.variables,+ ],+ (+ personPropertyDefinitions: PropertyDefinition[],+ type: EmailTemplaterType,+ variables: Record<string, any> | undefined+ ): UnlayerMergeTags => buildMergeTags(personPropertyDefinitions, type, variables),],unlayerEditorProjectId: [(s) => [s.preflight],@@ -649,6 +677,14 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([})),listeners(({ props, values, actions, cache }) => ({+ // Person properties load after the editor starts, and the editor only reads its options once.+ loadPersonPropertyDefinitionsSuccess: () => {+ const mergeTags = buildMergeTags(values.personPropertyDefinitions, props.type, props.variables)+ if (values.isEmailEditorReady && !objectsEqual(mergeTags, cache.lastMergeTags)) {+ cache.lastMergeTags = mergeTags+ values.emailEditorRef?.editor?.setMergeTags?.(mergeTags)+ }+ },onEmailEditorReady: () => {const editor = values.emailEditorRef?.editorif (editor && values.emailMediaLibraryEnabled) {@@ -662,6 +698,9 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([// Both layouts rebaseline on load: the modal submit compares its export against the// baseline to tell a no-op save from a real edit.values.emailEditorRef?.editor?.addEventListener('design:loaded', () => actions.designLoaded())+ // The editor read its merge tags when it started, so any added since then are pushed in.+ cache.lastMergeTags = buildMergeTags(values.personPropertyDefinitions, props.type, props.variables)+ values.emailEditorRef?.editor?.setMergeTags?.(cache.lastMergeTags)if (props.value?.design) {cache.lastEditorDesign = props.value.designvalues.emailEditorRef?.editor?.loadDesign(props.value.design)@@ -916,6 +955,13 @@ export const emailTemplaterLogic = kea<emailTemplaterLogicType>([})),propsChanged(({ actions, props, values, cache }, oldProps) => {+ // A transactional email's merge tags follow the variables it uses, so the open editor gets new ones.+ // Built from the new props here: a selector would still return its cached value until the store changes.+ const mergeTags = buildMergeTags(values.personPropertyDefinitions, props.type, props.variables)+ if (values.isEmailEditorReady && !objectsEqual(mergeTags, cache.lastMergeTags)) {+ cache.lastMergeTags = mergeTags+ values.emailEditorRef?.editor?.setMergeTags?.(mergeTags)+ }if (props.value && !objectsEqual(props.value, oldProps.value)) {actions.resetEmailTemplate(props.value)autoRevealAdvancedFields(actions, props)diff --git a/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx b/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsxindex 6b03be375af9..3c6d83aefaa6 100644--- a/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx+++ b/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx@@ -30,6 +30,7 @@ import { SceneContent } from '~/layout/scenes/components/SceneContent'import { SceneTitleSection } from '~/layout/scenes/components/SceneTitleSection'import { ProductKey } from '~/queries/schema/schema-general'+import { transactionalEditorGlobals, variablesInEmail } from '../Transactional/wizard/emailVariables'import { WorkflowInvocations } from '../Workflows/WorkflowInvocations'import { workflowLogic } from '../Workflows/workflowLogic'import { WorkflowMetrics } from '../Workflows/WorkflowMetrics'@@ -90,7 +91,6 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.ElemisSavingDraft,isDiscardingDraft,isSavingSensitive,- createAsTransactional,} = useValues(logic)const transactionalEmailsEnabled = useFeatureFlag('WORKFLOWS_TRANSACTIONAL_EMAIL_API')const todayRailNav = useFeatureFlag('TODAY_RAIL_NAV')@@ -138,10 +138,15 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.ElemonChange={(value) => setTemplateValue('content.email', value)}onChangeTemplating={(templating) => setTemplateValue('content.email.templating', templating)}type={- template?.transactional_hog_flow_id || createAsTransactional+ template?.transactional_hog_flow_id? 'native_email_transactional_template': 'native_email_template'}+ variables={+ template?.transactional_hog_flow_id+ ? transactionalEditorGlobals(variablesInEmail(template.content.email))+ : undefined+ }layout="inline"/>)}@@ -261,12 +266,6 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem</Tooltip>)}</>- ) : createAsTransactional ? (- <Tooltip title="Saving creates the email and makes it transactional, so you can send it from your code.">- <LemonTag type="success" className="ml-1">- Transactional- </LemonTag>- </Tooltip>) : undefined}actions={diff --git a/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx b/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsxindex 587b873a72a7..778b66644edb 100644--- a/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx+++ b/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx@@ -6,15 +6,25 @@ import { CodeSnippet, Language } from 'lib/components/CodeSnippet'import { teamLogic } from 'scenes/teamLogic'import { urls } from 'scenes/urls'-export function TransactionalEmailApiExample({ templateId }: { templateId: string }): JSX.Element {+export function TransactionalEmailApiExample({+ templateId,+ variables,+}: {+ templateId: string+ /** The email's `{{ variables.* }}` names. The snippet shows a sample when the email uses none. */+ variables?: string[]+}): JSX.Element {const { currentTeamIdStrict } = useValues(teamLogic)+ const messageData = variables?.length+ ? `{ ${variables.map((name) => `"${name}": "..."`).join(', ')} }`+ : '{ "first_name": "Jane", "reset_link": "https://example.com/reset" }'const snippet = `curl -X POST ${window.location.origin}/api/projects/${currentTeamIdStrict}/messaging_templates/${templateId}/send/ \\-H "Authorization: Bearer $POSTHOG_PROJECT_SECRET_API_KEY" \\-H "Content-Type: application/json" \\-d '{"to": "[email protected]","identifiers": { "distinct_id": "jane-distinct-id" },- "message_data": { "first_name": "Jane", "reset_link": "https://example.com/reset" }+ "message_data": ${messageData}}'`return (diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.tsindex ae2e0a4c6a97..979b3d0caab5 100644--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts@@ -3,7 +3,6 @@ import { expectLogic } from 'kea-test-utils'import { FEATURE_FLAGS } from 'lib/constants'import { featureFlagLogic } from 'lib/logic/featureFlagLogic'-import { removeProjectIdIfPresent } from 'lib/utils/kea-router'import { useMocks } from '~/mocks/jest'import { initKeaTests } from '~/test/init'@@ -11,7 +10,6 @@ import type { ResourceEditedEvent } from '~/types'import { resourceEditedLogic } from 'products/notifications/frontend/resourceEditedLogic'-import { NEW_TEMPLATE } from './constants'import { messageTemplateLogic } from './messageTemplateLogic'jest.mock('lib/lemon-ui/LemonToast', () => ({@@ -465,28 +463,5 @@ describe('messageTemplateLogic', () => {expect(logic.values.template.name).toEqual('Renamed while converting')}})-- test.each([- ['from the Transactional section converts it and opens it', { transactional: 'true' }, 1, '/created-id'],- ['as a plain template leaves it alone', {}, 0, '/workflows/library'],- ])('first save of a new template started %s', async (_name, search, expectedConversions, expectedPath) => {- const makeTransactional = jest.fn(() => [200, { id: 'created-id', transactional_hog_flow_id: 'flow-id' }])- useMocks({- post: {- '/api/projects/:team_id/messaging_templates/': { ...NEW_TEMPLATE, id: 'created-id' },- '/api/projects/:team_id/messaging_templates/:id/make_transactional/': makeTransactional,- },- })- router.actions.push('/workflows/library/templates/new', search)- logic = messageTemplateLogic({ id: 'new' })- logic.mount()-- await expectLogic(logic, () => {- logic.actions.saveTemplate(logic.values.template)- }).toFinishAllListeners()-- expect(makeTransactional).toHaveBeenCalledTimes(expectedConversions)- expect(removeProjectIdIfPresent(router.values.location.pathname)).toMatch(new RegExp(`${expectedPath}$`))- })})})diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.tsindex 089fde78f8ba..2ae498c2cacb 100644--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts@@ -34,7 +34,7 @@ import type { HogFunctionType, ResourceEditedEvent, UserBasicType } from '../../import type { IntegrationType } from '../../../../frontend/src/types'import { workflowLogic } from '../Workflows/workflowLogic'import { NEW_TEMPLATE } from './constants'-import { TRANSACTIONAL_PARAM, newTemplateAgentLogic } from './newTemplateAgentLogic'+import { newTemplateAgentLogic } from './newTemplateAgentLogic'import { TemplateSection, templateLibraryUrl, templateSectionFor, templateUrlInSection } from './templateSection'import { MessageTemplate } from './types'@@ -63,7 +63,6 @@ export interface messageTemplateLogicValues {integrations: IntegrationType[] | null // integrationsLogicaiComposerAvailable: boolean // newTemplateAgentLogiccurrentTeamIdStrict: number | string // teamLogic- createAsTransactional: booleandeferredExternalEdit: ResourceEditedEvent | nulldraftOutOfDate: booleandraftsEnabled: boolean@@ -447,9 +446,8 @@ export interface messageTemplateLogicMeta {key: string__keaTypeGenInternalSelectorTypes: {logicProps: (arg: MessageTemplateLogicProps) => MessageTemplateLogicProps- createAsTransactional: (searchParams: Record<string, any>, arg: MessageTemplateLogicProps) => booleantransactionalHogFlowId: (originalTemplate: MessageTemplate) => string | null- isTransactional: (transactionalHogFlowId: string | null, createAsTransactional: boolean) => boolean+ isTransactional: (transactionalHogFlowId: string | null) => booleansection: (location: { hash: string; pathname: string; search: string }) => TemplateSectionlistUrl: (isTransactional: boolean, section: TemplateSection) => stringdraftsEnabled: (transactionalHogFlowId: string | null) => boolean@@ -657,21 +655,14 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([],}),selectors({- // A new template started from the Transactional section. Its first save also makes it transactional.- createAsTransactional: [- () => [router.selectors.searchParams, (_, props: MessageTemplateLogicProps) => props],- (searchParams: Record<string, any>, props: MessageTemplateLogicProps): boolean =>- props.id === 'new' && !props.messageId && searchParams[TRANSACTIONAL_PARAM] === 'true',- ],// The saved state decides it: an unsaved template can't be transactional yet.transactionalHogFlowId: [(s) => [s.originalTemplate],(originalTemplate: MessageTemplate): string | null => originalTemplate.transactional_hog_flow_id ?? null,],isTransactional: [- (s) => [s.transactionalHogFlowId, s.createAsTransactional],- (transactionalHogFlowId: string | null, createAsTransactional: boolean): boolean =>- !!transactionalHogFlowId || createAsTransactional,+ (s) => [s.transactionalHogFlowId],+ (transactionalHogFlowId: string | null): boolean => !!transactionalHogFlowId,],// The nav section the page was opened under. Links from the page stay in it.section: [@@ -1013,21 +1004,6 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([lemonToast.error('Failed to save template. Please try again.')},saveTemplateSuccess: async ({ template }) => {- if (values.createAsTransactional && template.id) {- actions.resetTemplate(template)- actions.setOriginalTemplate(template)- try {- await messagingTemplatesMakeTransactionalCreate(String(values.currentTeamIdStrict), template.id, {})- lemonToast.success('Transactional email created. Send it from the API tab.')- } catch (error: any) {- // The template exists either way. Its API tab offers "Make transactional" to try again.- lemonToast.error(- `Template created. Couldn't make it transactional: ${error?.detail ?? 'unknown error'}. Try again from the API tab.`- )- }- router.actions.replace(urls.transactionalTemplate(template.id))- return- }lemonToast.success(props.id === 'new' ? 'Template created' : values.draftsEnabled ? 'Published' : 'Template saved')diff --git a/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.ts b/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.tsindex ca77e00bdbbf..372a617cc524 100644--- a/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.ts+++ b/products/workflows/frontend/TemplateLibrary/newTemplateAgentLogic.ts@@ -92,9 +92,6 @@ export interface newTemplateAgentLogicActions {startNewTemplate: () => {value: true}- startNewTransactionalEmail: () => {- value: true- }}// Generated by kea-typegen. Update if you're an agent, ignore if you're human.@@ -122,9 +119,6 @@ export type newTemplateAgentLogicType = MakeLogicType<newTemplateAgentLogicMeta>-// pinned: URL search param - the new-template editor reads it to make the template transactional on its first save-export const TRANSACTIONAL_PARAM = 'transactional'-/** Entry, mode and picked starting point for the AI-first "New template" page. */export const newTemplateAgentLogic = kea<newTemplateAgentLogicType>([path(['products', 'workflows', 'frontend', 'library', 'newTemplateAgentLogic']),@@ -141,7 +135,6 @@ export const newTemplateAgentLogic = kea<newTemplateAgentLogicType>([})),actions({startNewTemplate: true,- startNewTransactionalEmail: true,openEditorFromAiComposer: true,setPickedTemplate: (template: MessageTemplate | null) => ({ template }),}),@@ -194,10 +187,6 @@ export const newTemplateAgentLogic = kea<newTemplateAgentLogicType>([values.aiFirstNewEnabled ? { [EDITOR_MODE_PARAM]: AI_COMPOSER_MODE_VALUE } : {})},- // Skips the AI composer, which writes a plain template.- startNewTransactionalEmail: () => {- router.actions.push(urls.workflowsLibraryTemplateNew(), { [TRANSACTIONAL_PARAM]: 'true' })- },// The editor URL keeps the composer from rendering again, and the editor opens its picker for it.openEditorFromAiComposer: () => {router.actions.push(urls.workflowsLibraryTemplateNew(), { [EDITOR_MODE_PARAM]: EDITOR_MODE_VALUE })diff --git a/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsx b/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsxindex 79cc6f0be270..45e2b3dbe671 100644--- a/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsx+++ b/products/workflows/frontend/Transactional/TransactionalEmailsTable.tsx@@ -1,4 +1,5 @@-import { useActions, useMountedLogic, useValues } from 'kea'+import { useMountedLogic, useValues } from 'kea'+import { router } from 'kea-router'import { IconLock } from '@posthog/icons'import { LemonTag, Link } from '@posthog/lemon-ui'@@ -14,13 +15,11 @@ import { urls } from 'scenes/urls'import { AccessControlLevel, AccessControlResourceType } from '~/types'import { messageTemplatesLogic } from '../TemplateLibrary/messageTemplatesLogic'-import { newTemplateAgentLogic } from '../TemplateLibrary/newTemplateAgentLogic'import { MessageTemplate } from '../TemplateLibrary/types'export function TransactionalEmailsTable(): JSX.Element {useMountedLogic(messageTemplatesLogic)const { transactionalTemplates, templatesLoading } = useValues(messageTemplatesLogic)- const { startNewTransactionalEmail } = useActions(newTemplateAgentLogic)if (!templatesLoading && transactionalTemplates.length === 0) {return (@@ -28,7 +27,7 @@ export function TransactionalEmailsTable(): JSX.Element {thingName="transactional email"description="Send emails from your code with one API call. Use them for emails a person triggers, like password resets, receipts and sign-in codes. This tab shows how many were sent, delivered and failed in the last 7 days."docsURL="https://posthog.com/docs/workflows"- action={startNewTransactionalEmail}+ action={() => router.actions.push(urls.transactionalNew())}disabledReason={getAccessControlDisabledReason(AccessControlResourceType.Workflow, AccessControlLevel.Editor) ??undefineddiff --git a/products/workflows/frontend/Transactional/TransactionalScene.tsx b/products/workflows/frontend/Transactional/TransactionalScene.tsxindex 721fe5597b3e..1ff7688fefdb 100644--- a/products/workflows/frontend/Transactional/TransactionalScene.tsx+++ b/products/workflows/frontend/Transactional/TransactionalScene.tsx@@ -1,4 +1,4 @@-import { useActions, useValues } from 'kea'+import { useValues } from 'kea'import { router } from 'kea-router'import { LemonButton } from '@posthog/lemon-ui'@@ -25,8 +25,8 @@ import {MessagingNavTabKey,isMessagingSetupTab,} from '../messagingTabs'-import { newTemplateAgentLogic } from '../TemplateLibrary/newTemplateAgentLogic'import { TransactionalEmailsTable } from './TransactionalEmailsTable'+import { TransactionalEmailWizard } from './wizard/TransactionalEmailWizard'export const scene: SceneExport = {component: TransactionalScene,@@ -35,19 +35,24 @@ export const scene: SceneExport = {export function TransactionalScene(): JSX.Element {const { location } = useValues(router)- const { startNewTransactionalEmail } = useActions(newTemplateAgentLogic)const showTransactional = useFeatureFlag('WORKFLOWS_TRANSACTIONAL_EMAIL_API')const todayRailNav = useFeatureFlag('TODAY_RAIL_NAV')// The tab routes are literal paths, so the tab is the last path segment rather than a route param.- const lastSegment = location.pathname.split('/').pop() as MessagingNavTabKey- const currentTab: MessagingNavTabKey | 'transactional' = MESSAGING_NAV_TAB_KEYS.includes(lastSegment)- ? lastSegment+ const lastSegment = location.pathname.split('/').pop() ?? ''+ const currentTab: MessagingNavTabKey | 'transactional' = MESSAGING_NAV_TAB_KEYS.includes(+ lastSegment as MessagingNavTabKey+ )+ ? (lastSegment as MessagingNavTabKey): 'transactional'if (!showTransactional) {return <NotFound object="page" />}+ if (lastSegment === 'new') {+ return <TransactionalEmailWizard />+ }+return (<SceneContent><SceneTitleSection@@ -63,7 +68,7 @@ export function TransactionalScene(): JSX.Element {{todayRailNav ? (<Buttondata-attr="new-transactional-email"- onClick={startNewTransactionalEmail}+ onClick={() => router.actions.push(urls.transactionalNew())}variant="primary">New transactional email@@ -71,7 +76,7 @@ export function TransactionalScene(): JSX.Element {) : (<LemonButtondata-attr="new-transactional-email"- onClick={startNewTransactionalEmail}+ to={urls.transactionalNew()}type="primary"size="small">diff --git a/products/workflows/frontend/Transactional/wizard/TransactionalEmailWizard.tsx b/products/workflows/frontend/Transactional/wizard/TransactionalEmailWizard.tsxnew file mode 100644index 000000000000..ed345b2f73b3--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/TransactionalEmailWizard.tsx@@ -0,0 +1,98 @@+import { useActions, useMountedLogic, useValues } from 'kea'++import { LemonButton } from '@posthog/lemon-ui'++import { GuidedWizardStep, GuidedWizardStepper } from 'lib/components/GuidedWizard/GuidedWizardStepper'+import { urls } from 'scenes/urls'++import { SceneContent } from '~/layout/scenes/components/SceneContent'+import { SceneTitleSection } from '~/layout/scenes/components/SceneTitleSection'++import { ContentStep } from './steps/ContentStep'+import { NameStep } from './steps/NameStep'+import { SenderStep } from './steps/SenderStep'+import { SendStep } from './steps/SendStep'+import { TransactionalEmailWizardStep, transactionalEmailWizardLogic } from './transactionalEmailWizardLogic'++const STEPS: GuidedWizardStep<TransactionalEmailWizardStep>[] = [+ { step: 'name', label: 'Name', dataAttr: 'transactional-email-wizard-step-name' },+ { step: 'sender', label: 'Sender', dataAttr: 'transactional-email-wizard-step-sender' },+ { step: 'content', label: 'Content', dataAttr: 'transactional-email-wizard-step-content' },+ { step: 'send', label: 'Send from your code', dataAttr: 'transactional-email-wizard-step-send' },+]++const STEP_CONTENT: Record<TransactionalEmailWizardStep, () => JSX.Element> = {+ name: NameStep,+ sender: SenderStep,+ content: ContentStep,+ send: SendStep,+}++export function TransactionalEmailWizard(): JSX.Element {+ useMountedLogic(transactionalEmailWizardLogic)+ const { currentStep, currentStepErrors, isCreating } = useValues(transactionalEmailWizardLogic)+ const { setStep, nextStep, previousStep, createTransactionalEmail } = useActions(transactionalEmailWizardLogic)+ const StepContent = STEP_CONTENT[currentStep]+ const isFirstStep = currentStep === STEPS[0].step+ const isLastStep = currentStep === STEPS[STEPS.length - 1].step++ return (+ <SceneContent data-attr="transactional-email-wizard">+ <SceneTitleSection+ name="New transactional email"+ description="Write the email once, then send it from your code with one API call"+ resourceType={{ type: 'transactional' }}+ actions={+ <LemonButton type="secondary" size="small" to={urls.transactional()}>+ Cancel+ </LemonButton>+ }+ />+ <GuidedWizardStepper+ steps={STEPS}+ currentStep={currentStep}+ // The draft is already on its way, so edits made now would be lost.+ onStepClick={isCreating ? undefined : setStep}+ className="flex-wrap"+ aria-label="Transactional email wizard progress"+ />+ {/* The editor stays mounted, so an edit still saving when you leave Content isn't lost. */}+ <div hidden={currentStep !== 'content'}>+ <ContentStep />+ </div>+ {currentStep !== 'content' ? <StepContent /> : null}+ <div className="flex justify-between gap-2 border-t pt-3">+ {isFirstStep ? (+ <span />+ ) : (+ <LemonButton+ type="secondary"+ onClick={previousStep}+ disabledReason={isCreating ? 'Creating the email' : undefined}+ >+ Back+ </LemonButton>+ )}+ {isLastStep ? (+ <LemonButton+ type="primary"+ onClick={createTransactionalEmail}+ loading={isCreating}+ data-attr="transactional-email-wizard-create"+ >+ Create transactional email+ </LemonButton>+ ) : (+ <LemonButton+ type="primary"+ onClick={nextStep}+ disabledReason={currentStepErrors[0]}+ data-attr="transactional-email-wizard-next"+ >+ Next+ </LemonButton>+ )}+ </div>+ </SceneContent>+ )+}diff --git a/products/workflows/frontend/Transactional/wizard/emailVariables.test.ts b/products/workflows/frontend/Transactional/wizard/emailVariables.test.tsnew file mode 100644index 000000000000..8f4f7a49cd53--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/emailVariables.test.ts@@ -0,0 +1,41 @@+import { variablesInEmail } from './emailVariables'++describe('variablesInEmail', () => {+ test.each([+ [+ 'finds a variable in the body',+ { subject: 'Hi', html: '<a href="{{ variables.reset_link }}">Reset</a>' },+ ['reset_link'],+ ],+ [+ 'keeps first-seen order across subject and body, without duplicates',+ { subject: 'Hi {{ variables.first_name }}', html: '{{variables.code}} {{ variables.first_name }}' },+ ['first_name', 'code'],+ ],+ ['reads past a Liquid filter', { subject: '{{ variables.name | default: "there" }}', html: '' }, ['name']],+ ['ignores person properties', { subject: '{{ person.properties.email }}', html: '' }, []],+ [+ 'finds a variable in a control tag',+ { subject: '', html: '{% if variables.show_receipt %}Hi{% endif %}' },+ ['show_receipt'],+ ],+ [+ 'finds a variable used as a filter argument',+ { subject: '{{ variables.name | default: variables.fallback_name }}', html: '' },+ ['name', 'fallback_name'],+ ],+ ['ignores the word outside Liquid', { subject: 'See variables.example in the docs', html: '' }, []],+ [+ 'finds a variable in the sender name and reply-to',+ {+ subject: '',+ html: '',+ from: { name: '{{ variables.sender_name }}' },+ replyTo: '{{ variables.reply_to }}',+ },+ ['sender_name', 'reply_to'],+ ],+ ])('%s', (_, email, expected) => {+ expect(variablesInEmail({ text: '', from: '', ...email })).toEqual(expected)+ })+})diff --git a/products/workflows/frontend/Transactional/wizard/emailVariables.ts b/products/workflows/frontend/Transactional/wizard/emailVariables.tsnew file mode 100644index 000000000000..deb838df07c9--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/emailVariables.ts@@ -0,0 +1,35 @@+import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'++// Any Liquid output `{{ … }}` or tag `{% … %}`. Variables can sit anywhere inside one, such as+// `{% if variables.show_receipt %}` or `{{ variables.name | default: variables.fallback_name }}`.+const LIQUID_EXPRESSION = /\{\{[\s\S]*?\}\}|\{%[\s\S]*?%\}/g+const VARIABLE_REFERENCE = /\bvariables\.([A-Za-z_][A-Za-z0-9_]*)/g++/** The `message_data` keys an email reads, in the order they first appear in its sender, subject, preheader and body. */+export function variablesInEmail(+ email: Pick<EmailTemplate, 'subject' | 'html' | 'text' | 'preheader' | 'from' | 'replyTo'>+): string[] {+ const from = typeof email.from === 'object' && email.from ? email.from : {}+ const source = [from.name, from.email, email.replyTo, email.subject, email.preheader, email.html, email.text]+ .filter(Boolean)+ .join('\n')+ const expressions = source.match(LIQUID_EXPRESSION) ?? []+ return [+ ...new Set(+ expressions.flatMap((expression) => [...expression.matchAll(VARIABLE_REFERENCE)].map((match) => match[1]))+ ),+ ]+}++/** Editor globals for a transactional email: its variables feed the merge tags and Liquid autocomplete. */+export function transactionalEditorGlobals(names: string[]): { variables: Record<string, string> } {+ return { variables: Object.fromEntries(names.map((name) => [name, ''])) }+}++/** A name a person typed, made safe to use after `variables.`. */+export function cleanVariableName(name: string): string {+ return name+ .trim()+ .replace(/[^A-Za-z0-9_]/g, '_')+ .replace(/^(\d)/, '_$1')+}diff --git a/products/workflows/frontend/Transactional/wizard/steps/ContentStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/ContentStep.tsxnew file mode 100644index 000000000000..37d5ac0909bb--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/steps/ContentStep.tsx@@ -0,0 +1,82 @@+import { useActions, useValues } from 'kea'+import { useState } from 'react'++import { IconPlus } from '@posthog/icons'+import { LemonButton, LemonInput, LemonTag } from '@posthog/lemon-ui'++import { EmailTemplater } from 'scenes/hog-functions/email-templater/EmailTemplater'++import { cleanVariableName } from '../emailVariables'+import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'++export function ContentStep(): JSX.Element {+ const { draft, variables, panelVariables, editorGlobals } = useValues(transactionalEmailWizardLogic)+ const { updateDraft, addVariable } = useActions(transactionalEmailWizardLogic)+ const [newVariable, setNewVariable] = useState('')+ const newVariableName = cleanVariableName(newVariable)+ const submitNewVariable = (): void => {+ if (newVariableName) {+ addVariable(newVariableName)+ setNewVariable('')+ }+ }++ return (+ <div className="flex flex-col @min-[64rem]/main-content:flex-row gap-4 min-h-[36rem]">+ <div className="flex flex-col flex-1 min-w-0">+ <EmailTemplater+ value={draft.email}+ onChange={(email) => updateDraft({ email })}+ type="native_email_transactional_template"+ variables={editorGlobals}+ layout="inline"+ />+ </div>+ <div+ className="flex flex-col gap-2 @min-[64rem]/main-content:w-64 shrink-0 border rounded p-3 self-start"+ data-attr="transactional-email-wizard-variables"+ >+ <div className="font-semibold">Variables your code sends</div>+ <p className="text-secondary text-sm m-0">+ Your code passes these in <code>message_data</code> with each send. Person properties aren't+ available.+ </p>+ {panelVariables.length ? (+ <ul className="flex flex-col gap-1 m-0 p-0 list-none">+ {panelVariables.map((name) => (+ <li key={name} className="flex items-center justify-between gap-2">+ <code className="truncate">{name}</code>+ {variables.includes(name) ? null : <LemonTag size="small">Not used yet</LemonTag>}+ </li>+ ))}+ </ul>+ ) : null}+ <div className="flex gap-1">+ <LemonInput+ size="small"+ className="flex-1 min-w-0"+ placeholder="Variable name, like first_name"+ value={newVariable}+ onChange={setNewVariable}+ onPressEnter={submitNewVariable}+ data-attr="transactional-email-wizard-new-variable"+ />+ <LemonButton+ size="small"+ type="secondary"+ icon={<IconPlus />}+ disabledReason={!newVariableName ? 'Type a variable name first' : undefined}+ onClick={submitNewVariable}+ data-attr="transactional-email-wizard-add-variable"+ >+ Add+ </LemonButton>+ </div>+ <p className="text-secondary text-sm m-0">+ Insert one in the body from <b>Merge tags</b> in a text block's toolbar. In the subject, type it as{' '}+ <code>{'{{ variables.first_name }}'}</code>.+ </p>+ </div>+ </div>+ )+}diff --git a/products/workflows/frontend/Transactional/wizard/steps/NameStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/NameStep.tsxnew file mode 100644index 000000000000..e69f17f82d32--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/steps/NameStep.tsx@@ -0,0 +1,50 @@+import { useActions, useValues } from 'kea'++import { LemonInput, LemonSwitch } from '@posthog/lemon-ui'++import { LemonField } from 'lib/lemon-ui/LemonField'+import { LemonTextArea } from 'lib/lemon-ui/LemonTextArea'++import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'++export function NameStep(): JSX.Element {+ const { draft } = useValues(transactionalEmailWizardLogic)+ const { updateDraft } = useActions(transactionalEmailWizardLogic)++ return (+ <div className="flex flex-col gap-4 max-w-160">+ <LemonField.Pure label="Name" help="Only your team sees this.">+ <LemonInput+ autoFocus+ value={draft.name}+ placeholder="Password reset"+ onChange={(name) => updateDraft({ name })}+ data-attr="transactional-email-wizard-name"+ />+ </LemonField.Pure>+ <LemonField.Pure label="Description" showOptional>+ <LemonTextArea+ value={draft.description}+ placeholder="Sent when someone asks to reset their password"+ onChange={(description) => updateDraft({ description })}+ data-attr="transactional-email-wizard-description"+ />+ </LemonField.Pure>+ <LemonSwitch+ bordered+ checked={draft.sensitive}+ onChange={(sensitive) => updateDraft({ sensitive })}+ label={+ <div>+ <div className="font-semibold">Protect sensitive data</div>+ <div className="text-secondary text-sm font-normal">+ For emails with login codes or reset links. PostHog keeps no copy of what each email+ contained, and clicked links keep only the site address.+ </div>+ </div>+ }+ data-attr="transactional-email-wizard-sensitive"+ />+ </div>+ )+}diff --git a/products/workflows/frontend/Transactional/wizard/steps/SendStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/SendStep.tsxnew file mode 100644index 000000000000..3e933c5b91eb--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/steps/SendStep.tsx@@ -0,0 +1,43 @@+import { useValues } from 'kea'++import { LemonTag } from '@posthog/lemon-ui'++import { senderFrom } from 'scenes/hog-functions/email-templater/emailSenderFields'++import { TransactionalEmailApiExample } from '../../../TemplateLibrary/TransactionalEmailApiExample'+import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'++export function SendStep(): JSX.Element {+ const { draft, senders, variables } = useValues(transactionalEmailWizardLogic)+ const from = senderFrom(draft.email)+ const sender = senders.find((candidate) => candidate.id === from.integrationId)++ return (+ <div className="flex flex-col gap-4 max-w-200">+ <dl className="grid grid-cols-[8rem_minmax(0,1fr)] gap-x-4 gap-y-1 m-0 border rounded p-3">+ <dt className="text-secondary">Name</dt>+ <dd className="m-0 flex gap-2 items-center flex-wrap">+ {draft.name}+ {draft.sensitive ? <LemonTag type="highlight">Sensitive</LemonTag> : null}+ </dd>+ <dt className="text-secondary">From</dt>+ <dd className="m-0 truncate">{from.email || sender?.config?.email}</dd>+ <dt className="text-secondary">Subject</dt>+ <dd className="m-0 truncate">{draft.email.subject}</dd>+ <dt className="text-secondary">Variables</dt>+ <dd className="m-0 flex gap-1 flex-wrap">+ {variables.length ? variables.map((name) => <code key={name}>{name}</code>) : 'None'}+ </dd>+ </dl>+ <TransactionalEmailApiExample templateId="TEMPLATE_ID" variables={variables} />+ <ul className="list-disc pl-6 m-0 flex flex-col gap-1 text-secondary">+ <li>+ <code>TEMPLATE_ID</code> is filled in on the email's page once you create it.+ </li>+ <li>Transactional emails ignore marketing opt-outs, so don't use them for marketing.</li>+ <li>Later edits save as a draft until you publish them.</li>+ <li>An email created here stays transactional.</li>+ </ul>+ </div>+ )+}diff --git a/products/workflows/frontend/Transactional/wizard/steps/SenderStep.tsx b/products/workflows/frontend/Transactional/wizard/steps/SenderStep.tsxnew file mode 100644index 000000000000..754b1ce91778--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/steps/SenderStep.tsx@@ -0,0 +1,63 @@+import { useActions, useValues } from 'kea'++import { LemonButton } from '@posthog/lemon-ui'++import { ProductIntroduction } from 'lib/components/ProductIntroduction/ProductIntroduction'+import { integrationsLogic } from 'lib/integrations/integrationsLogic'+import { Spinner } from 'lib/lemon-ui/Spinner'+import { senderFrom } from 'scenes/hog-functions/email-templater/emailSenderFields'+import { EmailSenderForm } from 'scenes/hog-functions/email-templater/EmailSenderForm'+import { urls } from 'scenes/urls'++import { transactionalEmailWizardLogic } from '../transactionalEmailWizardLogic'++export function SenderStep(): JSX.Element {+ const { draft, senders } = useValues(transactionalEmailWizardLogic)+ const { updateEmail } = useActions(transactionalEmailWizardLogic)+ const { integrations, integrationsLoading } = useValues(integrationsLogic)+ const { loadIntegrations } = useActions(integrationsLogic)++ // A failed load clears the loading flag, and falls through to the retry below.+ if (integrations === null && integrationsLoading) {+ return <Spinner className="text-lg" />+ }++ if (senders.length === 0) {+ return (+ <ProductIntroduction+ titleOverride="Set up a sending domain first"+ thingName="email sender"+ description="Transactional emails send from a verified domain. Verify one in a new tab, then check again here to finish this email."+ isEmpty+ actionElementOverride={+ <div className="flex gap-2 flex-wrap">+ <LemonButton type="primary" to={urls.transactional('channels')} targetBlank>+ Set up a sending domain+ </LemonButton>+ {/* Domain setup opens in a new tab, so this picks up the sender without losing the email. */}+ <LemonButton+ type="secondary"+ onClick={loadIntegrations}+ loading={integrationsLoading}+ data-attr="transactional-email-wizard-check-senders"+ >+ Check again+ </LemonButton>+ </div>+ }+ />+ )+ }++ return (+ <div className="max-w-160 [&>div]:w-full [&>div]:p-0">+ <EmailSenderForm+ from={senderFrom(draft.email)}+ replyTo={draft.email.replyTo}+ senders={senders}+ onChangeFrom={(from) => updateEmail({ from })}+ onChangeReplyTo={(replyTo) => updateEmail({ replyTo })}+ />+ </div>+ )+}diff --git a/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.test.ts b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.test.tsnew file mode 100644index 000000000000..cf5d3bf9e3e1--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.test.ts@@ -0,0 +1,69 @@+import { router } from 'kea-router'+import { expectLogic } from 'kea-test-utils'++import { removeProjectIdIfPresent } from 'lib/utils/kea-router'++import { useMocks } from '~/mocks/jest'+import { initKeaTests } from '~/test/init'++import { transactionalEmailWizardLogic } from './transactionalEmailWizardLogic'++jest.mock('lib/lemon-ui/LemonToast', () => ({ lemonToast: { success: jest.fn(), error: jest.fn() } }))++describe('transactionalEmailWizardLogic', () => {+ let logic: ReturnType<typeof transactionalEmailWizardLogic.build>+ let createTemplate: jest.Mock+ let makeTransactional: jest.Mock++ beforeEach(() => {+ createTemplate = jest.fn(() => [201, { id: 'created-id' }])+ makeTransactional = jest.fn(() => [200, { id: 'created-id', transactional_hog_flow_id: 'flow-id' }])+ useMocks({+ get: {+ '/api/environments/:team_id/integrations/': {+ results: [+ {+ id: 7,+ kind: 'email',+ config: { email: '[email protected]', domain: 'example.com', verified: true },+ },+ ],+ },+ },+ post: {+ '/api/projects/:team_id/messaging_templates/': createTemplate,+ '/api/projects/:team_id/messaging_templates/:id/make_transactional/': makeTransactional,+ },+ })+ initKeaTests()+ router.actions.push('/transactional/new')+ logic = transactionalEmailWizardLogic()+ logic.mount()+ })++ afterEach(() => {+ logic.unmount()+ })++ test.each([+ ['an email missing its sender is not created', {}, 0, 'sender', '/transactional/new'],+ [+ 'a complete email is created, made transactional, and opened in its section',+ { from: { integrationId: 7 }, subject: 'Reset your password' },+ 1,+ 'name',+ '/transactional/library/templates/created-id',+ ],+ ])('%s', async (_, emailPatch, expectedCalls, expectedStep, expectedPath) => {+ await expectLogic(logic).toFinishAllListeners()+ logic.actions.updateDraft({ name: 'Password reset' })+ logic.actions.updateEmail(emailPatch)++ await expectLogic(logic, () => logic.actions.createTransactionalEmail()).toFinishAllListeners()++ expect(createTemplate).toHaveBeenCalledTimes(expectedCalls)+ expect(makeTransactional).toHaveBeenCalledTimes(expectedCalls)+ expect(removeProjectIdIfPresent(router.values.location.pathname)).toEqual(expectedPath)+ expect(logic.values.currentStep).toEqual(expectedStep)+ })+})diff --git a/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.ts b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.tsnew file mode 100644index 000000000000..d222c9e89dd9--- /dev/null+++ b/products/workflows/frontend/Transactional/wizard/transactionalEmailWizardLogic.ts@@ -0,0 +1,299 @@+import { MakeLogicType, actions, afterMount, connect, kea, listeners, path, reducers, selectors } from 'kea'+import { beforeUnload, router } from 'kea-router'+import posthog from 'posthog-js'++import { integrationsLogic } from 'lib/integrations/integrationsLogic'+import { lemonToast } from 'lib/lemon-ui/LemonToast'+import { senderAddressError, senderFrom } from 'scenes/hog-functions/email-templater/emailSenderFields'+import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'+import { teamLogic } from 'scenes/teamLogic'+import { urls } from 'scenes/urls'++import type { IntegrationType } from '~/types'++import {+ messagingTemplatesCreate,+ messagingTemplatesMakeTransactionalCreate,+} from 'products/messaging/frontend/generated/api'+import type { MessageTemplateContentApi } from 'products/messaging/frontend/generated/api.schemas'++import { NEW_TEMPLATE } from '../../TemplateLibrary/constants'+import { cleanVariableName, transactionalEditorGlobals, variablesInEmail } from './emailVariables'++export type TransactionalEmailWizardStep = 'name' | 'sender' | 'content' | 'send'++export const TRANSACTIONAL_EMAIL_WIZARD_STEPS: TransactionalEmailWizardStep[] = ['name', 'sender', 'content', 'send']++export interface TransactionalEmailDraft {+ name: string+ description: string+ sensitive: boolean+ email: EmailTemplate+}++const EMPTY_DRAFT: TransactionalEmailDraft = {+ name: '',+ description: '',+ sensitive: false,+ // The editor's starter design, with no subject, so nothing sends as "Hello from PostHog" by accident.+ email: { ...NEW_TEMPLATE.content.email, subject: '' },+}++/** What still blocks each step, so Next and the stepper can say why. */+export function wizardStepErrors(+ draft: TransactionalEmailDraft,+ senders: IntegrationType[]+): Record<TransactionalEmailWizardStep, string[]> {+ const from = senderFrom(draft.email)+ const sender = senders.find((candidate) => candidate.id === from.integrationId)+ const addressError = senderAddressError(from.email, sender)+ return {+ name: draft.name.trim() ? [] : ['Give the email a name'],+ sender: !sender ? ['Choose who the email comes from'] : addressError ? [addressError] : [],+ content: [+ ...(draft.email.subject.trim() ? [] : ['Add a subject']),+ ...(draft.email.html || draft.email.text ? [] : ['Add a body']),+ ],+ send: [],+ }+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface transactionalEmailWizardLogicValues {+ integrations: IntegrationType[] | null // integrationsLogic+ currentTeamIdStrict: number | string // teamLogic+ addedVariables: string[]+ created: boolean+ currentStep: TransactionalEmailWizardStep+ currentStepErrors: string[]+ draft: TransactionalEmailDraft+ editorGlobals: {+ variables: Record<string, string>+ }+ hasChanges: boolean+ isCreating: boolean+ panelVariables: string[]+ senders: IntegrationType[]+ stepErrors: Record<TransactionalEmailWizardStep, string[]>+ variables: string[]+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface transactionalEmailWizardLogicActions {+ addVariable: (name: string) => {+ name: string+ }+ createTransactionalEmail: () => {+ value: true+ }+ createTransactionalEmailFinished: (created: boolean) => {+ created: boolean+ }+ nextStep: () => {+ value: true+ }+ previousStep: () => {+ value: true+ }+ resetWizard: () => {+ value: true+ }+ setStep: (step: TransactionalEmailWizardStep) => {+ step: TransactionalEmailWizardStep+ }+ updateDraft: (patch: Partial<TransactionalEmailDraft>) => {+ patch: Partial<TransactionalEmailDraft>+ }+ updateEmail: (patch: Partial<EmailTemplate>) => {+ patch: Partial<EmailTemplate>+ }+}++// Generated by kea-typegen. Update if you're an agent, ignore if you're human.+export interface transactionalEmailWizardLogicMeta {+ __keaTypeGenInternalSelectorTypes: {+ senders: (integrations: IntegrationType[] | null) => IntegrationType[]+ stepErrors: (+ draft: TransactionalEmailDraft,+ senders: IntegrationType[]+ ) => Record<TransactionalEmailWizardStep, string[]>+ currentStepErrors: (+ stepErrors: Record<TransactionalEmailWizardStep, string[]>,+ currentStep: TransactionalEmailWizardStep+ ) => string[]+ variables: (draft: TransactionalEmailDraft) => string[]+ panelVariables: (variables: string[], addedVariables: string[]) => string[]+ editorGlobals: (panelVariables: string[]) => {+ variables: Record<string, string>+ }+ hasChanges: (draft: TransactionalEmailDraft) => boolean+ }+}++export type transactionalEmailWizardLogicType = MakeLogicType<+ transactionalEmailWizardLogicValues,+ transactionalEmailWizardLogicActions,+ Record<string, any>,+ transactionalEmailWizardLogicMeta+>++export const transactionalEmailWizardLogic = kea<transactionalEmailWizardLogicType>([+ path(['products', 'workflows', 'frontend', 'Transactional', 'wizard', 'transactionalEmailWizardLogic']),+ connect(() => ({+ values: [teamLogic, ['currentTeamIdStrict'], integrationsLogic, ['integrations']],+ })),+ actions({+ setStep: (step: TransactionalEmailWizardStep) => ({ step }),+ nextStep: true,+ previousStep: true,+ updateDraft: (patch: Partial<TransactionalEmailDraft>) => ({ patch }),+ updateEmail: (patch: Partial<EmailTemplate>) => ({ patch }),+ addVariable: (name: string) => ({ name }),+ resetWizard: true,+ createTransactionalEmail: true,+ createTransactionalEmailFinished: (created: boolean) => ({ created }),+ }),+ reducers({+ currentStep: [+ 'name' as TransactionalEmailWizardStep,+ {+ setStep: (_, { step }) => step,+ nextStep: (state) =>+ TRANSACTIONAL_EMAIL_WIZARD_STEPS[+ Math.min(+ TRANSACTIONAL_EMAIL_WIZARD_STEPS.indexOf(state) + 1,+ TRANSACTIONAL_EMAIL_WIZARD_STEPS.length - 1+ )+ ],+ previousStep: (state) =>+ TRANSACTIONAL_EMAIL_WIZARD_STEPS[Math.max(TRANSACTIONAL_EMAIL_WIZARD_STEPS.indexOf(state) - 1, 0)],+ resetWizard: () => 'name',+ },+ ],+ draft: [+ EMPTY_DRAFT,+ {+ updateDraft: (state, { patch }) => ({ ...state, ...patch }),+ updateEmail: (state, { patch }) => ({ ...state, email: { ...state.email, ...patch } }),+ resetWizard: () => EMPTY_DRAFT,+ },+ ],+ // Variables added in the panel before the email uses them, so they can be inserted from the editor.+ addedVariables: [+ [] as string[],+ {+ addVariable: (state, { name }) => {+ const cleaned = cleanVariableName(name)+ return cleaned && !state.includes(cleaned) ? [...state, cleaned] : state+ },+ resetWizard: () => [],+ },+ ],+ isCreating: [+ false,+ {+ createTransactionalEmail: () => true,+ createTransactionalEmailFinished: () => false,+ },+ ],+ // Set once the template exists, so leaving the page no longer asks to discard it.+ created: [+ false,+ {+ createTransactionalEmailFinished: (_, { created }) => created,+ resetWizard: () => false,+ },+ ],+ }),+ selectors({+ senders: [+ (s) => [s.integrations],+ (integrations: IntegrationType[] | null): IntegrationType[] =>+ // make_transactional only accepts a verified sender.+ (integrations ?? []).filter(+ (integration) => integration.kind === 'email' && integration.config?.verified === true+ ),+ ],+ stepErrors: [+ (s) => [s.draft, s.senders],+ (+ draft: TransactionalEmailDraft,+ senders: IntegrationType[]+ ): Record<TransactionalEmailWizardStep, string[]> => wizardStepErrors(draft, senders),+ ],+ currentStepErrors: [+ (s) => [s.stepErrors, s.currentStep],+ (stepErrors: Record<TransactionalEmailWizardStep, string[]>, currentStep: TransactionalEmailWizardStep) =>+ stepErrors[currentStep],+ ],+ variables: [(s) => [s.draft], (draft: TransactionalEmailDraft): string[] => variablesInEmail(draft.email)],+ // Everything the editor offers as a merge tag: what the email uses, plus what was added and not used yet.+ panelVariables: [+ (s) => [s.variables, s.addedVariables],+ (variables: string[], addedVariables: string[]): string[] => [+ ...variables,+ ...addedVariables.filter((name) => !variables.includes(name)),+ ],+ ],+ editorGlobals: [+ (s) => [s.panelVariables],+ (panelVariables: string[]): { variables: Record<string, string> } =>+ transactionalEditorGlobals(panelVariables),+ ],+ hasChanges: [(s) => [s.draft], (draft: TransactionalEmailDraft): boolean => draft !== EMPTY_DRAFT],+ }),+ listeners(({ actions, values }) => ({+ createTransactionalEmail: async () => {+ const firstInvalidStep = TRANSACTIONAL_EMAIL_WIZARD_STEPS.find((step) => values.stepErrors[step].length > 0)+ if (firstInvalidStep) {+ actions.setStep(firstInvalidStep)+ actions.createTransactionalEmailFinished(false)+ return+ }+ const { name, description, sensitive, email } = values.draft+ const teamId = String(values.currentTeamIdStrict)+ let templateId: string+ try {+ const template = await messagingTemplatesCreate(teamId, {+ name: name.trim(),+ description,+ sensitive,+ content: { templating: 'liquid', email } as unknown as MessageTemplateContentApi,+ })+ templateId = template.id+ } catch (error: any) {+ lemonToast.error(`Couldn't create the email: ${error?.detail ?? 'unknown error'}. Try again.`)+ actions.createTransactionalEmailFinished(false)+ return+ }+ try {+ await messagingTemplatesMakeTransactionalCreate(teamId, templateId, {})+ posthog.capture('transactional email created', { variable_count: values.variables.length, sensitive })+ lemonToast.success('Transactional email created')+ } catch (error: any) {+ // The template exists either way. Its API tab offers "Make transactional" to try again.+ posthog.capture('transactional email creation failed', { step: 'make_transactional' })+ lemonToast.error(+ `Email saved, but it couldn't be made transactional: ${error?.detail ?? 'unknown error'}. Try again from its API tab.`+ )+ }+ actions.createTransactionalEmailFinished(true)+ router.actions.replace(urls.transactionalTemplate(templateId))+ },+ setStep: ({ step }) => {+ posthog.capture('transactional email wizard step viewed', { step })+ },+ nextStep: () => {+ posthog.capture('transactional email wizard step viewed', { step: values.currentStep })+ },+ })),+ afterMount(({ actions }) => {+ // Each visit to /transactional/new starts a new email.+ actions.resetWizard()+ posthog.capture('transactional email wizard step viewed', { step: 'name' })+ }),+ beforeUnload(({ values }) => ({+ enabled: () => values.hasChanges && !values.created,+ message: 'Leave this email?\nNothing is saved until you create it.',+ })),+])diff --git a/products/workflows/manifest.tsx b/products/workflows/manifest.tsxindex 64bf7e640554..79daab2e242a 100644--- a/products/workflows/manifest.tsx+++ b/products/workflows/manifest.tsx@@ -86,6 +86,7 @@ export const manifest: ProductManifest = {'/transactional/suppression': ['Transactional', 'transactional'],'/transactional/reputation': ['Transactional', 'transactional'],'/transactional/settings': ['Transactional', 'transactional'],+ '/transactional/new': ['Transactional', 'transactional'],// A template opened from a section's Templates tab stays in that section.'/transactional/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],'/broadcasts/library/templates/:id': ['WorkflowsLibraryTemplate', 'workflowsLibraryTemplate'],@@ -107,6 +108,7 @@ export const manifest: ProductManifest = {broadcast: (id: string): string => `/broadcasts/${id}`,broadcastNew: (): string => '/broadcasts/new',transactional: (tab?: MessagingNavTabKey): string => `/transactional${tab ? `/${tab}` : ''}`,+ transactionalNew: (): string => '/transactional/new',transactionalTemplate: (id: string): string => `/transactional/library/templates/${id}`,broadcastsTemplate: (id: string): string => `/broadcasts/library/templates/${id}`,},diff --git a/services/mcp/src/tools/links/app-url-manifest.json b/services/mcp/src/tools/links/app-url-manifest.jsonindex e655f0928e70..ba17aee7f682 100644--- a/services/mcp/src/tools/links/app-url-manifest.json+++ b/services/mcp/src/tools/links/app-url-manifest.json@@ -1849,6 +1849,11 @@"params": [],"scope": "project"},+ "transactionalNew": {+ "template": "/transactional/new",+ "params": [],+ "scope": "project"+ },"transactionalTemplate": {"template": "/transactional/library/templates/{id}","params": ["id"],diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.jsonindex d05a4e0eba6c..d0a1b79d8947 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/generate-app-url.json@@ -13,7 +13,7 @@"type": "object"},"url": {- "description": "A path template copied verbatim from the catalog below (e.g. `/persons/{uuid}`). Its `{placeholders}` are filled from `params`. These slugs come from PostHog's canonical route table, so they are always correct — never pass a path that is not in this list.\n\n/account-connected/{kind}\n/account/credential-review\n/account/social-connected\n/activity-logs\n/activity/{tab}\n/agentic/account-mismatch\n/agentic/authorize\n/ai\n/ai-enrichment\n/ai-evals/evaluations\n/ai-evals/evaluations/offline/datasets/{id}\n/ai-evals/evaluations/offline/experiments\n/ai-evals/evaluations/offline/experiments/{experimentId}\n/ai-evals/evaluations/offline/experiments?tab=datasets\n/ai-evals/evaluations/scorers\n/ai-evals/evaluations/scorers/{scorerId}\n/ai-evals/evaluations/scorers/{scorerId}/offline\n/ai-evals/evaluations/templates\n/ai-evals/evaluations/{id}\n/ai-evals/taggers\n/ai-evals/taggers/{id}\n/ai-observability/clusters\n/ai-observability/clusters/{runId}/{clusterId}\n/ai-observability/dashboard\n/ai-observability/errors\n/ai-observability/generations\n/ai-observability/playground\n/ai-observability/reviews\n/ai-observability/self-driving\n/ai-observability/sentiment\n/ai-observability/sessions\n/ai-observability/sessions/{id}\n/ai-observability/tools\n/ai-observability/traces\n/ai-observability/traces/{id}\n/ai-observability/users\n/ai/history\n/alerts\n/analytics\n/analytics/all\n/analytics/mine\n/analytics/product-analytics\n/analytics/spaces\n/application-observability\n/approvals/{id}\n/autoresearch\n/autoresearch/new\n/autoresearch/{id}\n/bi\n/bi/new\n/bi/{insightShortId}\n/billing/authorization_status\n/broadcasts\n/broadcasts/library/templates/{id}\n/broadcasts/new\n/broadcasts/{id}\n/business-knowledge\n/business-knowledge/playground\n/business-knowledge/settings\n/business-knowledge/{id}\n/canvas\n/canvases\n/canvases/new\n/canvases/{id}\n/cli/authorize\n/cli/live\n/code-review\n/code/canvas/{channelId}/{dashboardId}\n/code/channel/{channelId}\n/code/loop/{loopId}\n/code/task/{taskId}\n/cohorts\n/cohorts/{id}\n/cohorts/{id}/calculation-history\n/connect/vercel/link\n/coupons/{campaign}\n/create-organization\n/cross-project-dashboards\n/cross-project-dashboards/{id}\n/customer_analytics\n/customer_analytics/accounts\n/customer_analytics/accounts/by-external-id/{externalId}\n/customer_analytics/accounts/{accountId}\n/customer_analytics/announcements\n/customer_analytics/configuration\n/customer_analytics/dashboard\n/customer_analytics/feature-requests\n/customer_analytics/feed\n/customer_analytics/journeys\n/customer_analytics/journeys/new\n/customer_analytics/journeys/templates\n/customer_analytics/journeys/{id}/edit\n/customer_analytics/notes\n/customer_analytics/tasks\n/dashboard\n/dashboard/templates/{templateId}/copy-to-project\n/dashboard/{id}\n/dashboard/{id}/sharing\n/dashboard/{id}/subscriptions\n/dashboard/{id}/subscriptions/{subscriptionId}\n/dashboard/{id}/tiles/{tileId}\n/data-catalog\n/data-catalog/metrics/{name}\n/data-catalog/new-metric\n/data-management/actions\n/data-management/actions/new\n/data-management/actions/new/\n/data-management/actions/{id}\n/data-management/annotations\n/data-management/annotations/{id}\n/data-management/core-events\n/data-management/database\n/data-management/destinations\n/data-management/event-filtering\n/data-management/events\n/data-management/events/{id}\n/data-management/events/{id}/edit\n/data-management/history\n/data-management/ingestion-warnings\n/data-management/ingestion-warnings-v2\n/data-management/managed-viewsets\n/data-management/materialized-columns\n/data-management/properties\n/data-management/properties/{id}\n/data-management/properties/{id}/edit\n/data-management/revenue\n/data-management/schema\n/data-management/sources\n/data-management/sources/{id}/schemas\n/data-management/sources/{sourceId}/schemas/{schemaId}\n/data-management/transformations\n/data-management/variables\n/data-management/variables/{id}\n/data-management/variables/{id}/edit\n/data-management/warehouse-destinations\n/data-management/warehouse-properties\n/data-ops\n/data-warehouse/connect\n/data-warehouse/new-source\n/debug\n/debug/hog\n/debug/precompute\n/early_access_features\n/early_access_features/{id}\n/embedded/{token}\n/endpoints\n/endpoints/{name}\n/engineering-analytics/authors\n/engineering-analytics/authors/{handle}\n/engineering-analytics/deploys\n/engineering-analytics/overview\n/engineering-analytics/pull-requests\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/runs/{runId}\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/workflows/{workflowName}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}/ci-explorer\n/engineering-analytics/teams\n/engineering-analytics/teams/{ownerTeam}\n/engineering-analytics/tests\n/engineering-analytics/workflows\n/error-tracking\n/error-tracking/alerts/new/{templateId}\n/error-tracking/alerts/{id}\n/error-tracking/fingerprint/{fingerprint}\n/error-tracking/{id}\n/etl\n/events/{id}/{timestamp}\n/experiments\n/experiments/shared-metrics\n/experiments/shared-metrics/{id}\n/experiments/staff\n/experiments/{id}\n/exports\n/feature-flags\n/feature-flags/new\n/feature-flags/staff\n/feature-flags/staff/cohorts\n/feature-flags/templates\n/feature-flags/{id}\n/files\n/functions/new/{templateId}\n/functions/{id}\n/games/368hedgehogs\n/games/flappyhog\n/games/shipit\n/groups/{groupTypeIndex}\n/groups/{groupTypeIndex}/new\n/groups/{groupTypeIndex}/{groupKey}\n/health\n/health/alerts\n/health/pipeline-status\n/health/sdk-health\n/health/{category}\n/heatmaps\n/heatmaps/new\n/heatmaps/recording\n/heatmaps/{id}\n/home\n/identity-matching\n/inbox\n/inbox/reports/triage\n/inbox/scout-trials\n/inbox/scouts/findings\n/inbox/scouts/runs\n/inbox/scouts/scratchpad\n/inbox/scouts/{skillName}\n/inbox/{tab}/{reportId}\n/insights\n/insights/new\n/insights/quick-start\n/insights/{id}\n/insights/{id}/edit\n/insights/{id}/sharing\n/insights/{id}/subscriptions\n/insights/{id}/subscriptions/{subscriptionId}\n/insights/{insightShortId}/alerts\n/instance/async_migrations\n/instance/async_migrations/future\n/instance/async_migrations/settings\n/instance/dead_letter_queue\n/instance/kafka_inspector\n/instance/metrics\n/instance/settings\n/instance/staff_users\n/instance/status\n/integrations/stripe/confirm-install\n/integrations/vercel/link-error\n/integrations/{kind}/callback\n/integrations/{slug}\n/legal\n/legal/new/{type}\n/login\n/login/2fa\n/login/2fa_setup\n/logs\n/logs/alerts/{alertId}/notifications/{hogFunctionId}\n/logs/alerts/{id}\n/logs/drop-rules/new\n/logs/drop-rules/{id}\n/logs/retention-rules/new\n/logs/retention-rules/{id}\n/managed_migrations\n/managed_migrations/new\n/marketing\n/mcp-analytics\n/mcp-analytics/activity\n/mcp-analytics/dashboard\n/mcp-analytics/intent-clustering\n/mcp-analytics/missing-capabilities\n/mcp-analytics/notifications\n/mcp-analytics/sessions\n/mcp-analytics/tool-quality\n/mcp-analytics/tool-quality/{toolName}\n/mcp-registry\n/mcp-servers\n/mcp-servers/agent/{id}\n/mcp-servers/member/{id}\n/mcp-servers/server/{id}\n/mcp-servers/{tab}\n/metrics\n/metrics/dashboard-review\n/models\n/models/{id}\n/move-to-cloud\n/my-tickets\n/notebooks\n/notebooks/widgets/{widgetId}\n/notebooks/{shortId}\n/oauth/authorize\n/onboarding\n/onboarding/simple\n/organization-deactivated\n/organization-pending-deletion\n/organization/billing\n/organization/billing/overview\n/organization/billing/real-time-usage\n/organization/confirm-creation\n/organization/create-project\n/organization/legal\n/organization/startups\n/person/{id}\n/persons\n/persons/{uuid}\n/pipeline/batch-exports/new/{service}\n/pipeline/batch-exports/{id}\n/pipeline/new/\n/pipeline/plugins/{id}\n/platform-alerts\n/platform-alerts/{id}\n/preflight\n/product_tours\n/product_tours/{id}\n/project-pending-deletion\n/prompt-management/prompts\n/prompt-management/prompts/{name}\n/pulse\n/replay-vision\n/replay-vision/new/goal\n/replay-vision/observations/{observationId}\n/replay-vision/{id}/budget\n/replay-vision/{id}/configure\n/replay-vision/{id}/details\n/replay-vision/{id}/goal\n/replay-vision/{id}/overview\n/replay-vision/{id}/triggers\n/replay/file-playback\n/replay/home\n/replay/kiosk\n/replay/playlists/{id}\n/replay/settings\n/replay/{id}\n/reset\n/reset/{userUuid}/{token}\n/reset_2fa/{userUuid}/{token}\n/resource-transfer/{resourceKind}/{resourceId}\n/sessions/{id}\n/settings/environment-approvals\n/settings/organization-authentication/{feature}/{configId}\n/settings/project\n/settings/user-feature-previews\n/shared/{token}\n/shared_dashboard/{shareToken}\n/signup\n/signup/{id}\n/site/{url}\n/skills\n/skills/community\n/skills/{categoryTab}\n/skills/{name}\n/slack-task-context\n/spaces\n/spaces/new\n/spaces/{id}\n/spaces/{id}/canvases\n/spaces/{id}/new\n/spaces/{id}/settings\n/sql\n/stamphog\n/stamphog/digests\n/stamphog/install/callback\n/stamphog/runs\n/startups\n/streamlit-apps\n/streamlit-apps/new\n/streamlit-apps/{id}\n/streamlit-apps/{id}/edit\n/subscriptions\n/subscriptions/new\n/subscriptions/{id}\n/subscriptions/{id}/edit\n/support\n/support/settings\n/support/tickets\n/support/tickets/{ticketId}\n/surveys\n/surveys/form/new\n/surveys/guided/new\n/surveys/{id}\n/tasks\n/tasks/new\n/tasks/{taskId}\n/terminal\n/themes/custom-css\n/toolbar\n/tools\n/tracing\n/tracing/retention-rules/new\n/tracing/retention-rules/{id}\n/transactional\n/transactional/library/templates/{id}\n/unsubscribe\n/uptime-monitoring\n/verify_email\n/visual-review\n/visual-review/repos/{repoOwner}/{repoName}/flakiness\n/visual-review/repos/{repoOwner}/{repoName}/runs\n/visual-review/repos/{repoOwner}/{repoName}/runs/{runId}\n/visual-review/repos/{repoOwner}/{repoName}/snapshots\n/visual-review/repos/{repoOwner}/{repoName}/{runType}/snapshots/{identifier}\n/visual-review/runs/{runId}\n/visual-review/settings\n/web\n/web-scripts\n/web-scripts/new\n/web/agents\n/web/bots\n/web/content-autopilot\n/web/health\n/web/live\n/web/marketing\n/web/page-performance\n/web/page-reports\n/web/recap\n/web/session-attribution-explorer\n/web/web-vitals\n/welcome\n/wizard/runs\n/workflows\n/workflows/channels/email/{id}\n/workflows/library/messages/{id}\n/workflows/library/templates/new\n/workflows/library/templates/{id}\n/workflows/new/workflow\n/workflows/{id}/{tab}",+ "description": "A path template copied verbatim from the catalog below (e.g. `/persons/{uuid}`). Its `{placeholders}` are filled from `params`. These slugs come from PostHog's canonical route table, so they are always correct — never pass a path that is not in this list.\n\n/account-connected/{kind}\n/account/credential-review\n/account/social-connected\n/activity-logs\n/activity/{tab}\n/agentic/account-mismatch\n/agentic/authorize\n/ai\n/ai-enrichment\n/ai-evals/evaluations\n/ai-evals/evaluations/offline/datasets/{id}\n/ai-evals/evaluations/offline/experiments\n/ai-evals/evaluations/offline/experiments/{experimentId}\n/ai-evals/evaluations/offline/experiments?tab=datasets\n/ai-evals/evaluations/scorers\n/ai-evals/evaluations/scorers/{scorerId}\n/ai-evals/evaluations/scorers/{scorerId}/offline\n/ai-evals/evaluations/templates\n/ai-evals/evaluations/{id}\n/ai-evals/taggers\n/ai-evals/taggers/{id}\n/ai-observability/clusters\n/ai-observability/clusters/{runId}/{clusterId}\n/ai-observability/dashboard\n/ai-observability/errors\n/ai-observability/generations\n/ai-observability/playground\n/ai-observability/reviews\n/ai-observability/self-driving\n/ai-observability/sentiment\n/ai-observability/sessions\n/ai-observability/sessions/{id}\n/ai-observability/tools\n/ai-observability/traces\n/ai-observability/traces/{id}\n/ai-observability/users\n/ai/history\n/alerts\n/analytics\n/analytics/all\n/analytics/mine\n/analytics/product-analytics\n/analytics/spaces\n/application-observability\n/approvals/{id}\n/autoresearch\n/autoresearch/new\n/autoresearch/{id}\n/bi\n/bi/new\n/bi/{insightShortId}\n/billing/authorization_status\n/broadcasts\n/broadcasts/library/templates/{id}\n/broadcasts/new\n/broadcasts/{id}\n/business-knowledge\n/business-knowledge/playground\n/business-knowledge/settings\n/business-knowledge/{id}\n/canvas\n/canvases\n/canvases/new\n/canvases/{id}\n/cli/authorize\n/cli/live\n/code-review\n/code/canvas/{channelId}/{dashboardId}\n/code/channel/{channelId}\n/code/loop/{loopId}\n/code/task/{taskId}\n/cohorts\n/cohorts/{id}\n/cohorts/{id}/calculation-history\n/connect/vercel/link\n/coupons/{campaign}\n/create-organization\n/cross-project-dashboards\n/cross-project-dashboards/{id}\n/customer_analytics\n/customer_analytics/accounts\n/customer_analytics/accounts/by-external-id/{externalId}\n/customer_analytics/accounts/{accountId}\n/customer_analytics/announcements\n/customer_analytics/configuration\n/customer_analytics/dashboard\n/customer_analytics/feature-requests\n/customer_analytics/feed\n/customer_analytics/journeys\n/customer_analytics/journeys/new\n/customer_analytics/journeys/templates\n/customer_analytics/journeys/{id}/edit\n/customer_analytics/notes\n/customer_analytics/tasks\n/dashboard\n/dashboard/templates/{templateId}/copy-to-project\n/dashboard/{id}\n/dashboard/{id}/sharing\n/dashboard/{id}/subscriptions\n/dashboard/{id}/subscriptions/{subscriptionId}\n/dashboard/{id}/tiles/{tileId}\n/data-catalog\n/data-catalog/metrics/{name}\n/data-catalog/new-metric\n/data-management/actions\n/data-management/actions/new\n/data-management/actions/new/\n/data-management/actions/{id}\n/data-management/annotations\n/data-management/annotations/{id}\n/data-management/core-events\n/data-management/database\n/data-management/destinations\n/data-management/event-filtering\n/data-management/events\n/data-management/events/{id}\n/data-management/events/{id}/edit\n/data-management/history\n/data-management/ingestion-warnings\n/data-management/ingestion-warnings-v2\n/data-management/managed-viewsets\n/data-management/materialized-columns\n/data-management/properties\n/data-management/properties/{id}\n/data-management/properties/{id}/edit\n/data-management/revenue\n/data-management/schema\n/data-management/sources\n/data-management/sources/{id}/schemas\n/data-management/sources/{sourceId}/schemas/{schemaId}\n/data-management/transformations\n/data-management/variables\n/data-management/variables/{id}\n/data-management/variables/{id}/edit\n/data-management/warehouse-destinations\n/data-management/warehouse-properties\n/data-ops\n/data-warehouse/connect\n/data-warehouse/new-source\n/debug\n/debug/hog\n/debug/precompute\n/early_access_features\n/early_access_features/{id}\n/embedded/{token}\n/endpoints\n/endpoints/{name}\n/engineering-analytics/authors\n/engineering-analytics/authors/{handle}\n/engineering-analytics/deploys\n/engineering-analytics/overview\n/engineering-analytics/pull-requests\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/runs/{runId}\n/engineering-analytics/repos/{repoOwner}/{repoName}/actions/workflows/{workflowName}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}\n/engineering-analytics/repos/{repoOwner}/{repoName}/pull-requests/{number}/ci-explorer\n/engineering-analytics/teams\n/engineering-analytics/teams/{ownerTeam}\n/engineering-analytics/tests\n/engineering-analytics/workflows\n/error-tracking\n/error-tracking/alerts/new/{templateId}\n/error-tracking/alerts/{id}\n/error-tracking/fingerprint/{fingerprint}\n/error-tracking/{id}\n/etl\n/events/{id}/{timestamp}\n/experiments\n/experiments/shared-metrics\n/experiments/shared-metrics/{id}\n/experiments/staff\n/experiments/{id}\n/exports\n/feature-flags\n/feature-flags/new\n/feature-flags/staff\n/feature-flags/staff/cohorts\n/feature-flags/templates\n/feature-flags/{id}\n/files\n/functions/new/{templateId}\n/functions/{id}\n/games/368hedgehogs\n/games/flappyhog\n/games/shipit\n/groups/{groupTypeIndex}\n/groups/{groupTypeIndex}/new\n/groups/{groupTypeIndex}/{groupKey}\n/health\n/health/alerts\n/health/pipeline-status\n/health/sdk-health\n/health/{category}\n/heatmaps\n/heatmaps/new\n/heatmaps/recording\n/heatmaps/{id}\n/home\n/identity-matching\n/inbox\n/inbox/reports/triage\n/inbox/scout-trials\n/inbox/scouts/findings\n/inbox/scouts/runs\n/inbox/scouts/scratchpad\n/inbox/scouts/{skillName}\n/inbox/{tab}/{reportId}\n/insights\n/insights/new\n/insights/quick-start\n/insights/{id}\n/insights/{id}/edit\n/insights/{id}/sharing\n/insights/{id}/subscriptions\n/insights/{id}/subscriptions/{subscriptionId}\n/insights/{insightShortId}/alerts\n/instance/async_migrations\n/instance/async_migrations/future\n/instance/async_migrations/settings\n/instance/dead_letter_queue\n/instance/kafka_inspector\n/instance/metrics\n/instance/settings\n/instance/staff_users\n/instance/status\n/integrations/stripe/confirm-install\n/integrations/vercel/link-error\n/integrations/{kind}/callback\n/integrations/{slug}\n/legal\n/legal/new/{type}\n/login\n/login/2fa\n/login/2fa_setup\n/logs\n/logs/alerts/{alertId}/notifications/{hogFunctionId}\n/logs/alerts/{id}\n/logs/drop-rules/new\n/logs/drop-rules/{id}\n/logs/retention-rules/new\n/logs/retention-rules/{id}\n/managed_migrations\n/managed_migrations/new\n/marketing\n/mcp-analytics\n/mcp-analytics/activity\n/mcp-analytics/dashboard\n/mcp-analytics/intent-clustering\n/mcp-analytics/missing-capabilities\n/mcp-analytics/notifications\n/mcp-analytics/sessions\n/mcp-analytics/tool-quality\n/mcp-analytics/tool-quality/{toolName}\n/mcp-registry\n/mcp-servers\n/mcp-servers/agent/{id}\n/mcp-servers/member/{id}\n/mcp-servers/server/{id}\n/mcp-servers/{tab}\n/metrics\n/metrics/dashboard-review\n/models\n/models/{id}\n/move-to-cloud\n/my-tickets\n/notebooks\n/notebooks/widgets/{widgetId}\n/notebooks/{shortId}\n/oauth/authorize\n/onboarding\n/onboarding/simple\n/organization-deactivated\n/organization-pending-deletion\n/organization/billing\n/organization/billing/overview\n/organization/billing/real-time-usage\n/organization/confirm-creation\n/organization/create-project\n/organization/legal\n/organization/startups\n/person/{id}\n/persons\n/persons/{uuid}\n/pipeline/batch-exports/new/{service}\n/pipeline/batch-exports/{id}\n/pipeline/new/\n/pipeline/plugins/{id}\n/platform-alerts\n/platform-alerts/{id}\n/preflight\n/product_tours\n/product_tours/{id}\n/project-pending-deletion\n/prompt-management/prompts\n/prompt-management/prompts/{name}\n/pulse\n/replay-vision\n/replay-vision/new/goal\n/replay-vision/observations/{observationId}\n/replay-vision/{id}/budget\n/replay-vision/{id}/configure\n/replay-vision/{id}/details\n/replay-vision/{id}/goal\n/replay-vision/{id}/overview\n/replay-vision/{id}/triggers\n/replay/file-playback\n/replay/home\n/replay/kiosk\n/replay/playlists/{id}\n/replay/settings\n/replay/{id}\n/reset\n/reset/{userUuid}/{token}\n/reset_2fa/{userUuid}/{token}\n/resource-transfer/{resourceKind}/{resourceId}\n/sessions/{id}\n/settings/environment-approvals\n/settings/organization-authentication/{feature}/{configId}\n/settings/project\n/settings/user-feature-previews\n/shared/{token}\n/shared_dashboard/{shareToken}\n/signup\n/signup/{id}\n/site/{url}\n/skills\n/skills/community\n/skills/{categoryTab}\n/skills/{name}\n/slack-task-context\n/spaces\n/spaces/new\n/spaces/{id}\n/spaces/{id}/canvases\n/spaces/{id}/new\n/spaces/{id}/settings\n/sql\n/stamphog\n/stamphog/digests\n/stamphog/install/callback\n/stamphog/runs\n/startups\n/streamlit-apps\n/streamlit-apps/new\n/streamlit-apps/{id}\n/streamlit-apps/{id}/edit\n/subscriptions\n/subscriptions/new\n/subscriptions/{id}\n/subscriptions/{id}/edit\n/support\n/support/settings\n/support/tickets\n/support/tickets/{ticketId}\n/surveys\n/surveys/form/new\n/surveys/guided/new\n/surveys/{id}\n/tasks\n/tasks/new\n/tasks/{taskId}\n/terminal\n/themes/custom-css\n/toolbar\n/tools\n/tracing\n/tracing/retention-rules/new\n/tracing/retention-rules/{id}\n/transactional\n/transactional/library/templates/{id}\n/transactional/new\n/unsubscribe\n/uptime-monitoring\n/verify_email\n/visual-review\n/visual-review/repos/{repoOwner}/{repoName}/flakiness\n/visual-review/repos/{repoOwner}/{repoName}/runs\n/visual-review/repos/{repoOwner}/{repoName}/runs/{runId}\n/visual-review/repos/{repoOwner}/{repoName}/snapshots\n/visual-review/repos/{repoOwner}/{repoName}/{runType}/snapshots/{identifier}\n/visual-review/runs/{runId}\n/visual-review/settings\n/web\n/web-scripts\n/web-scripts/new\n/web/agents\n/web/bots\n/web/content-autopilot\n/web/health\n/web/live\n/web/marketing\n/web/page-performance\n/web/page-reports\n/web/recap\n/web/session-attribution-explorer\n/web/web-vitals\n/welcome\n/wizard/runs\n/workflows\n/workflows/channels/email/{id}\n/workflows/library/messages/{id}\n/workflows/library/templates/new\n/workflows/library/templates/{id}\n/workflows/new/workflow\n/workflows/{id}/{tab}","type": "string"}},