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.

15.4 KB
Raw Blame
import { MakeLogicType, actions, connect, kea, listeners, path, reducers, selectors } from 'kea'
import { loaders } from 'kea-loaders'
import { subscriptions } from 'kea-subscriptions'
import posthog from 'posthog-js'

import api from 'lib/api'
import { userLogic } from 'scenes/userLogic'

import type { UserType } from '../../types'

export interface WelcomeInviter {
    name: string
    email: string
}

export type WelcomeLastActive = 'today' | 'this_week' | 'inactive' | 'never'

export interface WelcomeTeamMember {
    name: string
    email: string
    avatar: string | null
    role: string
    last_active: WelcomeLastActive
}

export interface WelcomeRecentActivity {
    type: string
    actor_name: string
    entity_name: string
    entity_url: string | null
    timestamp: string
}

export interface WelcomePopularDashboard {
    id: number
    name: string
    description: string
    team_id: number
    url: string
}

export interface WelcomeSuggestedStep {
    label: string
    href: string
    reason: string
    docs_href?: string
    product_key?: string
}

export interface WelcomePayload {
    organization_name: string
    inviter: WelcomeInviter | null
    team_members: WelcomeTeamMember[]
    recent_activity: WelcomeRecentActivity[]
    popular_dashboards: WelcomePopularDashboard[]
    products_in_use: string[]
    suggested_next_steps: WelcomeSuggestedStep[]
    is_organization_first_user: boolean
}

const EMPTY_PAYLOAD: WelcomePayload = {
    organization_name: '',
    inviter: null,
    team_members: [],
    recent_activity: [],
    popular_dashboards: [],
    products_in_use: [],
    suggested_next_steps: [],
    is_organization_first_user: false,
}

export type WelcomeCardKind = 'members' | 'activity' | 'dashboards' | 'products' | 'next_steps'

/** Which control closed the dialog. Reported as the `source` property of `welcome_screen_closed`,
 * which is how we tell a deliberate "Start exploring" from an escape through the X. */
export type WelcomeCloseSource = 'start_exploring' | 'modal_close' | 'ask_max_card'

const WEEK_MS = 7 * 24 * 60 * 60 * 1000
const WELCOME_WINDOW_WEEKS = 2

function weeksSince(start: number, at: number): number {
    return Math.floor((at - start) / WEEK_MS)
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface welcomeDialogLogicValues {
    isProvisionedUser: boolean // userLogic
    user: UserType | null // userLogic
    closedAt: Record<string, number>
    dismissedMemberships: Record<string, boolean>
    hasLoadedOnce: boolean
    interactedCards: Record<WelcomeCardKind, boolean>
    inviter: WelcomeInviter | null
    membershipKey: string | null
    organizationName: string
    popularDashboards: WelcomePopularDashboard[]
    productsInUse: string[]
    recentActivity: WelcomeRecentActivity[]
    shouldShowDialog: boolean
    shownAt: number | null
    suggestedNextSteps: WelcomeSuggestedStep[]
    teamMembers: WelcomeTeamMember[]
    welcomeData: WelcomePayload
    welcomeDataError: boolean
    welcomeDataLoading: boolean
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface welcomeDialogLogicActions {
    closeDialog: (source: WelcomeCloseSource) => {
        source: WelcomeCloseSource
    }
    dismissWelcome: () => {
        value: true
    }
    loadWelcomeData: () => any
    loadWelcomeDataFailure: (
        error: string,
        errorObject?: any
    ) => {
        error: string
        errorObject?: any
    }
    loadWelcomeDataSuccess: (
        welcomeData: WelcomePayload,
        payload?: any
    ) => {
        welcomeData: WelcomePayload
        payload?: any
    }
    markCardInteracted: (card: WelcomeCardKind) => {
        card: WelcomeCardKind
    }
    markClosed: (
        membershipKey: string,
        closedAt: number
    ) => {
        closedAt: number
        membershipKey: string
    }
    markDismissed: (membershipKey: string) => {
        membershipKey: string
    }
    markShown: () => {
        value: true
    }
    resetForOrgChange: () => {
        value: true
    }
    setWelcomeDataError: (error: boolean) => {
        error: boolean
    }
    trackCardClick: (
        card: WelcomeCardKind,
        targetHref: string
    ) => {
        card: WelcomeCardKind
        targetHref: string
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface welcomeDialogLogicMeta {
    __keaTypeGenInternalSelectorTypes: {
        inviter: (welcomeData: WelcomePayload) => WelcomeInviter | null
        teamMembers: (welcomeData: WelcomePayload) => WelcomeTeamMember[]
        recentActivity: (welcomeData: WelcomePayload) => WelcomeRecentActivity[]
        popularDashboards: (welcomeData: WelcomePayload) => WelcomePopularDashboard[]
        productsInUse: (welcomeData: WelcomePayload) => string[]
        suggestedNextSteps: (welcomeData: WelcomePayload) => WelcomeSuggestedStep[]
        organizationName: (welcomeData: WelcomePayload, user: UserType | null) => string
        membershipKey: (user: UserType | null) => string | null
        shouldShowDialog: (
            user: UserType | null,
            isProvisionedUser: boolean,
            membershipKey: string | null,
            dismissedMemberships: Record<string, boolean>,
            closedAt: Record<string, number>
        ) => boolean
    }
}

export type welcomeDialogLogicType = MakeLogicType<
    welcomeDialogLogicValues,
    welcomeDialogLogicActions,
    Record<string, any>,
    welcomeDialogLogicMeta
>

export const welcomeDialogLogic = kea<welcomeDialogLogicType>([
    path(['scenes', 'welcome', 'welcomeDialogLogic']),

    connect(() => ({
        values: [userLogic, ['user', 'isProvisionedUser']],
    })),

    actions({
        dismissWelcome: true,
        closeDialog: (source: WelcomeCloseSource) => ({ source }),
        resetForOrgChange: true,
        trackCardClick: (card: WelcomeCardKind, targetHref: string) => ({ card, targetHref }),
        markCardInteracted: (card: WelcomeCardKind) => ({ card }),
        markShown: true,
        setWelcomeDataError: (error: boolean) => ({ error }),
        markDismissed: (membershipKey: string) => ({ membershipKey }),
        markClosed: (membershipKey: string, closedAt: number) => ({ membershipKey, closedAt }),
    }),

    reducers({
        shownAt: [
            null as number | null,
            {
                markShown: () => Date.now(),
                resetForOrgChange: () => null,
            },
        ],
        interactedCards: [
            {} as Record<WelcomeCardKind, boolean>,
            {
                markCardInteracted: (state, { card }) => ({ ...state, [card]: true }),
                resetForOrgChange: () => ({}) as Record<WelcomeCardKind, boolean>,
            },
        ],
        // Both persisted maps are keyed by `membershipKey`, so a contractor/agency who works across
        // multiple orgs gets a fresh welcome in each org. "Don't show again" hides the dialog for good.
        dismissedMemberships: [
            {} as Record<string, boolean>,
            { persist: true },
            {
                markDismissed: (state, { membershipKey }) => ({ ...state, [membershipKey]: true }),
            },
        ],
        closedAt: [
            {} as Record<string, number>,
            { persist: true },
            {
                markClosed: (state, { membershipKey, closedAt }) => ({ ...state, [membershipKey]: closedAt }),
            },
        ],
        hasLoadedOnce: [
            false,
            {
                loadWelcomeDataSuccess: () => true,
                resetForOrgChange: () => false,
            },
        ],
        welcomeDataError: [
            false,
            {
                setWelcomeDataError: (_, { error }) => error,
                loadWelcomeData: () => false,
                resetForOrgChange: () => false,
            },
        ],
    }),

    loaders(({ actions }) => ({
        welcomeData: [
            EMPTY_PAYLOAD,
            {
                loadWelcomeData: async () => {
                    try {
                        // nosemgrep: prefer-codegen-api -- Legacy raw API call with a hand-written URL and an unchecked response type. Use welcomeCurrentRetrieve() from 'products/platform_features/frontend/generated/api' instead.
                        return await api.get<WelcomePayload>('api/organizations/@current/welcome/current/')
                    } catch (error) {
                        const status =
                            typeof error === 'object' && error !== null && 'status' in error
                                ? (error as { status?: unknown }).status
                                : undefined
                        console.warn('Failed to load welcome data', error)
                        actions.setWelcomeDataError(true)
                        // Surface in PostHog so fleet-level error rate is observable; console.warn
                        // alone is invisible at scale.
                        posthog.capture('welcome_screen_load_failed', { status })
                        return EMPTY_PAYLOAD
                    }
                },
            },
        ],
    })),

    selectors({
        inviter: [(s) => [s.welcomeData], (data: WelcomePayload): WelcomeInviter | null => data.inviter],
        teamMembers: [(s) => [s.welcomeData], (data: WelcomePayload): WelcomeTeamMember[] => data.team_members],
        recentActivity: [
            (s) => [s.welcomeData],
            (data: WelcomePayload): WelcomeRecentActivity[] => data.recent_activity,
        ],
        popularDashboards: [
            (s) => [s.welcomeData],
            (data: WelcomePayload): WelcomePopularDashboard[] => data.popular_dashboards,
        ],
        productsInUse: [(s) => [s.welcomeData], (data: WelcomePayload): string[] => data.products_in_use],
        suggestedNextSteps: [
            (s) => [s.welcomeData],
            (data: WelcomePayload): WelcomeSuggestedStep[] => data.suggested_next_steps,
        ],
        organizationName: [
            (s) => [s.welcomeData, s.user],
            (data: WelcomePayload, user: null | import('../../types').UserType): string => {
                const userOrgName = user?.organization?.name
                // After an org switch the cached payload still names the previous org until the
                // refetch lands. Prefer the user's current org so the title never lags behind.
                if (userOrgName && data.organization_name && data.organization_name !== userOrgName) {
                    return userOrgName
                }
                return data.organization_name || userOrgName || ''
            },
        ],
        membershipKey: [
            (s) => [s.user],
            (user: UserType | null): string | null =>
                user?.uuid && user.organization?.id ? `${user.uuid}:${user.organization.id}` : null,
        ],
        shouldShowDialog: [
            (s) => [s.user, s.isProvisionedUser, s.membershipKey, s.dismissedMemberships, s.closedAt],
            (
                user: UserType | null,
                isProvisionedUser: boolean,
                membershipKey: string | null,
                dismissedMemberships: Record<string, boolean>,
                closedAt: Record<string, number>
            ): boolean => {
                // Open for invitees (not the org creator) and for partner-provisioned accounts (which have
                // no inviter, so they'd otherwise never see it).
                if (!user || !membershipKey || (user.is_organization_first_user !== false && !isProvisionedUser)) {
                    return false
                }
                const joinedAt = Date.parse(user.organization?.membership_joined_at ?? '')
                if (Number.isNaN(joinedAt) || dismissedMemberships[membershipKey]) {
                    return false
                }
                const currentWeek = weeksSince(joinedAt, Date.now())
                if (currentWeek >= WELCOME_WINDOW_WEEKS) {
                    return false
                }
                const lastClosedAt = closedAt[membershipKey]
                return lastClosedAt === undefined || weeksSince(joinedAt, lastClosedAt) < currentWeek
            },
        ],
    }),

    listeners(({ actions, values }) => ({
        resetForOrgChange: () => {
            // The cached payload belongs to the previous org. Refetch so the members, dashboards,
            // activity, and org name all reflect the org the user just switched to. The automatic
            // refetch only fires when `shouldShowDialog` flips, which it does not when the dialog
            // was eligible in both orgs.
            actions.loadWelcomeData()
        },
        loadWelcomeDataSuccess: ({ welcomeData }) => {
            if (!values.shouldShowDialog || values.welcomeDataError) {
                return
            }
            if (!welcomeData.organization_name) {
                // Empty payload = backend error that was caught and returned EMPTY_PAYLOAD.
                return
            }
            actions.markShown()
            posthog.capture('welcome_screen_shown', {
                org_id: values.user?.organization?.id,
                num_team_members: welcomeData.team_members.length,
                products_in_use: welcomeData.products_in_use,
                had_recent_activity: welcomeData.recent_activity.length > 0,
                from_invite_type: welcomeData.inviter ? 'invite' : 'unknown',
            })
        },
        closeDialog: ({ source }) => {
            if (values.membershipKey) {
                actions.markClosed(values.membershipKey, Date.now())
            }
            posthog.capture('welcome_screen_closed', {
                source,
                time_on_screen_ms: values.shownAt ? Date.now() - values.shownAt : null,
                cards_interacted_with: Object.keys(values.interactedCards).length,
            })
        },
        dismissWelcome: () => {
            const interactedCount = Object.keys(values.interactedCards).length
            const timeOnScreen = values.shownAt ? Date.now() - values.shownAt : null
            if (values.membershipKey) {
                actions.markDismissed(values.membershipKey)
            }
            posthog.capture('welcome_screen_dismissed', {
                time_on_screen_ms: timeOnScreen,
                cards_interacted_with: interactedCount,
            })
        },
        trackCardClick: ({ card, targetHref }) => {
            actions.markCardInteracted(card)
            // Clicking an in-app card link counts as engagement, so it hides the dialog like a close.
            if (values.membershipKey) {
                actions.markClosed(values.membershipKey, Date.now())
            }
            posthog.capture('welcome_screen_card_clicked', {
                card,
                target_href: targetHref,
            })
        },
    })),

    // Re-evaluate on user changes. Triggers the initial fetch once the user loads, and re-fetches
    // when the user switches current organization so we don't render stale data across orgs.
    subscriptions(({ actions, values }) => ({
        user: (nextUser, previousUser) => {
            const prevOrgId = previousUser?.organization?.id
            const nextOrgId = nextUser?.organization?.id
            if (prevOrgId && nextOrgId && prevOrgId !== nextOrgId) {
                actions.resetForOrgChange()
            }
        },
        shouldShowDialog: (shouldShow: boolean) => {
            if (shouldShow && !values.hasLoadedOnce && !values.welcomeDataLoading) {
                actions.loadWelcomeData()
            }
        },
    })),
])