Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

13.6 KB
Raw Blame
import { getRecommendedPlan } from '@openpanel/payments';
import { stripTrailingSlash } from '@openpanel/shared';
import { format } from 'date-fns';
import type { Logger } from '../../logger';
import type { ServiceDeps, Services } from '../../services';
import { hashClientSecret, newClientSecret } from '../../shared/client-secret';
import {
  getReferrerWithQuery,
  parseReferrer,
} from '../../shared/parse-referrer';
import { getId } from '../../slug-id';
import {
  runSequence,
  type SequenceStep,
  type SequenceSubject,
  step,
} from '../email/src/sequence';
import {
  getOrganizationById,
  getOrganizationEventsCount,
} from '../organization/organization.service';
import {
  getOrganizationContact,
  ORGANIZATION_ADMINS_INCLUDE,
  type OrganizationContact,
  type OrganizationWithAdmins,
} from '../organization/src/contact';
import { getUserById } from '../user/user.service';
import type {
  IOnboardingProject,
  IOrganizationAttribution,
  IOrganizationAttributionStored,
} from './onboarding.constants';

const TRIAL_DURATION_IN_DAYS = 30;
// Generous trial allowance so trialing orgs never get flagged as
// "limit exceeded" (the limit defaults to 0, which trips on the first event).
const TRIAL_EVENTS_LIMIT = 10_000_000;

export async function canSkipOnboarding(
  deps: ServiceDeps,
  userId: string | null | undefined
): Promise<{ canSkip: boolean }> {
  if (!userId) {
    return { canSkip: false };
  }

  const members = await deps.db.member.count({ where: { userId } });
  return { canSkip: members > 0 };
}

export function toStoredAttribution(
  attribution: IOrganizationAttribution | undefined
): IOrganizationAttributionStored | undefined {
  if (!attribution) {
    return undefined;
  }
  const hasAnyValue = Object.values(attribution).some(Boolean);
  if (!hasAnyValue) {
    return undefined;
  }

  const fromReferrer = parseReferrer(attribution.referrer);
  const fromUtm = getReferrerWithQuery(
    attribution.utmSource ? { utm_source: attribution.utmSource } : undefined
  );
  const resolved = fromReferrer.name ? fromReferrer : fromUtm;

  return {
    referrer: attribution.referrer || null,
    referrerName: resolved?.name || null,
    referrerType: resolved?.type || null,
    landingPage: attribution.landingPage || null,
    utmSource: attribution.utmSource || null,
    utmMedium: attribution.utmMedium || null,
    utmCampaign: attribution.utmCampaign || null,
    utmContent: attribution.utmContent || null,
    utmTerm: attribution.utmTerm || null,
    firstSeenAt: attribution.firstSeenAt || null,
  };
}

async function createOrGetOnboardingOrganization(
  deps: ServiceDeps,
  input: IOnboardingProject,
  userId: string
) {
  if (input.organizationId) {
    return await getOrganizationById(deps, input.organizationId);
  }

  if (!input.organization) {
    return null;
  }

  const db = deps.db;
  const organizationId = await getId(deps, 'organization', input.organization);

  // Create the organization and its owner atomically. The `delete` cron
  // treats an organization with no admin member as ownerless and removes it,
  // so an organization must never exist without one.
  const [organization] = await db.$transaction([
    db.organization.create({
      data: {
        id: organizationId,
        name: input.organization,
        createdByUserId: userId,
        subscriptionEndsAt: new Date(
          Date.now() + TRIAL_DURATION_IN_DAYS * 24 * 60 * 60 * 1000
        ),
        subscriptionStatus: 'trialing',
        subscriptionPeriodEventsLimit: TRIAL_EVENTS_LIMIT,
        timezone: input.timezone,
        attribution: toStoredAttribution(input.attribution),
        onboarding: '',
        // Equal to the id so it is unique; see code migration 26.
        slug: organizationId,
      },
    }),
    db.member.create({
      data: {
        email: (await getUserById(deps, userId)).email,
        organizationId,
        role: 'owner',
        userId,
      },
    }),
  ]);

  return organization;
}

export interface CreateOnboardingProjectResult {
  id: string;
  name: string;
  organizationId: string;
  projectId: string | null;
  type: string;
  secret: string;
  /** Token for the read-only MCP client created alongside; only ever returned here. */
  mcpToken: string;
}

const toMcpToken = (clientId: string, secret: string) =>
  Buffer.from(`${clientId}:${secret}`).toString('base64');

export async function createOnboardingProject(
  deps: ServiceDeps,
  input: IOnboardingProject,
  userId: string
): Promise<CreateOnboardingProjectResult> {
  const types: ('website' | 'app' | 'backend')[] = [];
  if (input.website) {
    types.push('website');
  }
  if (input.app) {
    types.push('app');
  }
  if (input.backend) {
    types.push('backend');
  }

  const organization = await createOrGetOnboardingOrganization(
    deps,
    input,
    userId
  );
  // Only the no-org-identified branch of createOrGetOnboardingOrganization
  // can produce this: the organizationId branch throws (findUniqueOrThrow)
  // rather than returning falsy, so `organization` is always non-null there.
  if (!organization) {
    throw new Error('Organization name or id is required');
  }

  const cors = [...input.cors];
  if (cors.length === 0 && input.website) {
    cors.push('*');
  }

  const db = deps.db;

  const projectId = await getId(deps, 'project', input.project);
  const secret = newClientSecret();
  // MCP only accepts read and root clients, so the write client's token
  // would never work. A read client scoped to this project is created up
  // front; the dashboard shows its token once and never its id or secret.
  const mcpSecret = newClientSecret();
  const [hashedSecret, hashedMcpSecret] = await Promise.all([
    hashClientSecret(secret),
    hashClientSecret(mcpSecret),
  ]);

  // One transaction: a project without its clients would leave the user
  // with an error and no credentials to retry with.
  const { client, mcpClient } = await db.$transaction(async (tx) => {
    const project = await tx.project.create({
      data: {
        id: projectId,
        name: input.project,
        organizationId: organization.id,
        types,
        domain: input.domain ? stripTrailingSlash(input.domain) : null,
        cors: cors.map((c) => stripTrailingSlash(c)),
      },
    });
    const createdClient = await tx.client.create({
      data: {
        name: `${project.name} Client`,
        organizationId: organization.id,
        projectId: project.id,
        type: 'write',
        secret: hashedSecret,
      },
    });
    const createdMcpClient = await tx.client.create({
      data: {
        name: `${project.name} MCP client`,
        organizationId: organization.id,
        projectId: project.id,
        type: 'read',
        secret: hashedMcpSecret,
      },
    });
    return { client: createdClient, mcpClient: createdMcpClient };
  });

  return { ...client, secret, mcpToken: toMcpToken(mcpClient.id, mcpSecret) };
}

// The onboarding email drip cron. The `organization.onboarding` column
// stores the last sent step, and step names are equal to template names for
// historical reasons: in-flight orgs already hold those values. Renaming one
// strands every org sitting on it (the runner completes them rather than
// replaying the sequence, but they still stop early).
//
// Stops at day 26 — what happens after the trial expires belongs to the
// wind-down cron, anchored on expiry rather than signup.

interface OnboardingUsage {
  eventsCount: number;
  hasData: boolean;
}

interface OnboardingCronOrg extends OrganizationWithAdmins {
  id: string;
  createdAt: Date;
  onboarding: string | null;
  subscriptionStatus: string | null;
  subscriptionEndsAt: Date | null;
  projects: { id: string }[];
}

interface OnboardingContext {
  org: OnboardingCronOrg;
  user: OrganizationContact;
  dashboardUrl: string;
  // Lazy + memoized: only emails past the day gate pay for the ClickHouse count.
  getUsage: () => Promise<OnboardingUsage>;
}

function createUsageGetter(deps: ServiceDeps, org: OnboardingCronOrg) {
  let promise: Promise<OnboardingUsage> | null = null;
  return () => {
    promise ??= getOrganizationEventsCount(
      deps,
      org.projects.map((project) => project.id)
    ).then((eventsCount) => ({
      eventsCount,
      hasData: eventsCount > 0,
    }));
    return promise;
  };
}

// Split by sync/async so a call site's own code (awaited or not) is the
// type-level signal of which is which, instead of one object where only
// `recommendedPlan` happens to return a Promise.
const syncGetters = {
  firstName: (ctx: OnboardingContext) => ctx.user.firstName || undefined,
  dashboardUrl: (ctx: OnboardingContext) => {
    return `${ctx.dashboardUrl}/${ctx.org.id}`;
  },
  billingUrl: (ctx: OnboardingContext) => {
    return `${ctx.dashboardUrl}/${ctx.org.id}/billing`;
  },
  trialEndDate: (ctx: OnboardingContext) => {
    return ctx.org.subscriptionEndsAt
      ? format(ctx.org.subscriptionEndsAt, 'MMMM d')
      : undefined;
  },
} as const;

const asyncGetters = {
  recommendedPlan: async (ctx: OnboardingContext) => {
    const { eventsCount } = await ctx.getUsage();
    return getRecommendedPlan(
      eventsCount,
      (plan: { formattedEvents: string; formattedPrice: string }) =>
        `${plan.formattedEvents} events per month for ${plan.formattedPrice}`
    );
  },
} as const;

const ONBOARDING_EMAILS: SequenceStep<OnboardingContext>[] = [
  step<OnboardingContext, 'onboarding-welcome'>({
    day: 0,
    step: 'onboarding-welcome',
    template: 'onboarding-welcome',
    data: async (ctx) => ({
      firstName: syncGetters.firstName(ctx),
      dashboardUrl: syncGetters.dashboardUrl(ctx),
      hasData: (await ctx.getUsage()).hasData,
    }),
  }),
  step<OnboardingContext, 'onboarding-what-to-track'>({
    day: 2,
    step: 'onboarding-what-to-track',
    template: 'onboarding-what-to-track',
    data: async (ctx) => {
      const usage = await ctx.getUsage();
      return {
        firstName: syncGetters.firstName(ctx),
        hasData: usage.hasData,
        eventsCount: usage.eventsCount,
      };
    },
  }),
  step<OnboardingContext, 'onboarding-dashboards'>({
    day: 6,
    step: 'onboarding-dashboards',
    template: 'onboarding-dashboards',
    data: async (ctx) => {
      const usage = await ctx.getUsage();
      return {
        firstName: syncGetters.firstName(ctx),
        dashboardUrl: syncGetters.dashboardUrl(ctx),
        hasData: usage.hasData,
        eventsCount: usage.eventsCount,
      };
    },
  }),
  step<OnboardingContext, 'onboarding-feature-request'>({
    day: 14,
    step: 'onboarding-feature-request',
    template: 'onboarding-feature-request',
    data: async (ctx) => ({
      firstName: syncGetters.firstName(ctx),
      hasData: (await ctx.getUsage()).hasData,
    }),
  }),
  step<OnboardingContext, 'onboarding-trial-ending'>({
    day: 26,
    step: 'onboarding-trial-ending',
    template: 'onboarding-trial-ending',
    shouldSend: async ({ org }) => {
      if (org.subscriptionStatus === 'active') {
        return 'complete';
      }
      return true;
    },
    data: async (ctx) => {
      const usage = await ctx.getUsage();
      return {
        firstName: syncGetters.firstName(ctx),
        billingUrl: syncGetters.billingUrl(ctx),
        recommendedPlan: await asyncGetters.recommendedPlan(ctx),
        trialEndDate: syncGetters.trialEndDate(ctx),
        hasData: usage.hasData,
        eventsCount: usage.eventsCount,
      };
    },
  }),
];

export type OnboardingCronLogger = Pick<Logger, 'info' | 'warn' | 'error'>;

export interface OnboardingCronSummary {
  totalOrgs: number;
  emailsSent: number;
  orgsCompleted: number;
  orgsSkipped: number;
}

export async function runOnboardingCron(
  deps: ServiceDeps,
  logger: OnboardingCronLogger
): Promise<OnboardingCronSummary | null> {
  if (deps.config.selfHosted) {
    return null;
  }

  logger.info('Starting onboarding email job');

  const db = deps.db;
  const orgs: OnboardingCronOrg[] = await db.organization.findMany({
    where: {
      OR: [{ onboarding: null }, { onboarding: { notIn: ['completed'] } }],
      deleteAt: null,
    },
    include: {
      ...ORGANIZATION_ADMINS_INCLUDE,
      projects: { select: { id: true } },
    },
  });

  logger.info(`Found ${orgs.length} organizations in onboarding`);

  const subjects: SequenceSubject<OnboardingContext>[] = orgs.flatMap((org) => {
    const user = getOrganizationContact(org);
    if (!user) {
      return [];
    }
    return {
      id: org.id,
      email: user.email,
      anchor: org.createdAt,
      pointer: org.onboarding,
      ctx: {
        org,
        user,
        dashboardUrl: deps.config.dashboardUrl,
        getUsage: createUsageGetter(deps, org),
      },
    };
  });

  const result = await runSequence({
    name: 'onboarding',
    steps: ONBOARDING_EMAILS,
    subjects,
    logger,
    onAdvance: async (subject, stepName) => {
      await db.organization.update({
        where: { id: subject.id },
        data: { onboarding: stepName },
      });
    },
    onComplete: async (subject) => {
      await db.organization.update({
        where: { id: subject.id },
        data: { onboarding: 'completed' },
      });
    },
  });

  const summary: OnboardingCronSummary = {
    totalOrgs: orgs.length,
    emailsSent: result.emailsSent,
    orgsCompleted: result.completed,
    orgsSkipped:
      result.deferred + result.stepsSkipped + orgs.length - subjects.length,
  };

  logger.info({ ...summary }, 'Completed onboarding email job');

  return summary;
}

/** Closes over `deps.logger`, so `ctx.services.onboarding.runOnboardingCron()` takes no arguments. */
export function createOnboardingService(
  deps: ServiceDeps,
  _services: () => Services
) {
  return {
    runOnboardingCron: (): Promise<OnboardingCronSummary | null> =>
      runOnboardingCron(deps, deps.logger),
  };
}