feat: Free trial mutations

[jmtaber129]

Description

Fixes #9133

Spec 🔒

Introduces two mutations, startTrial and endTrial, which set/reset a trialStartDate field on any object with a tier field (Organization, Team, OrganizationUser, and User) to activate a free trial for a particular org without overwriting tier information.

Frontend/GQL:
In the GQL layer, the trialStartDate field is used to override the tier field, such that any checks in the frontend for whether a user has access to a feature based on tier will treat the object as being on the Team plan. We also introduce an isTrial field that indicates that the tier is set via free trial, so that billing-related components (e.g. billing panel, component displaying tier, etc.), can show that a free trial is active.

Server:
In server-side mutations + resolvers, anywhere that we check whether tier is starter, we also check if trialStartDate is non-null.

Mutations:

mutation {
  startTrial(orgId:"nWW2freL5K") {
    ... on StartTrialSuccess {
      organization {
        trialStartDate
      }
    }
  }
}
mutation {
  endTrial(orgId:"nWW2freL5K") {
    ... on EndTrialSuccess {
      organization {
        trialStartDate
      }
    }
  }
}

Demo

https://www.loom.com/share/e78ac40536d04d8fadd8e92ab97be813?sid=04b7efa6-3a0f-4f76-86f8-865dca95cffd

Testing scenarios

• Smoke test feature access + billing-/plan-related pages for each of these scenarios:
  • Starter plan, never had a trial
  • Trial activated on starter plan
  • Trial ended on starter plan
  • Org upgrade during active trial, then later downgrades
• Error cases for mutations:
  • Start trial on paid org
  • Start trial on org with active trial
  • End trial on org without active trial

Final checklist

• I checked the code review guidelines
• I have added Metrics Representative as reviewer(s) if my PR invovles metrics/data/analytics related changes
• I have performed a self-review of my code, the same way I'd do it for any other team member
• I have tested all cases I listed in the testing scenarios and I haven't found any issues or regressions
• Whenever I took a non-obvious choice I added a comment explaining why I did it this way
• I added the label One Review Required if the PR introduces only minor changes, does not contain any architectural changes or does not introduce any new patterns and I think one review is sufficient'
• PR title is human readable and could be used in changelog

[BartoszJarocki]

@jmtaber129 I'd love to clarify a couple of things.

First, do you see any issues with setting tier to team when startTrial mutation runs? alongside updating tier we'd set the information about the trial (start date, whatever else is needed). this way, we wouldn't need to change any business logic related to tier handling, except for showing the information about trial and possibly upgrading. Any thoughts?

Another clarifying question, why do we set the trialStartDate in a few places like Org, OrgUser, Team? why not just one place?

[jmtaber129]

@BartoszJarocki

do you see any issues with setting tier to team when startTrial mutation runs

Nothing specific, but because tier is currently tightly coupled with billing, I'm wary about changing that state for a new experimental feature like this one - when starting+ending trials, we'd need to correctly update the tier according to billing. By keeping tier as-is and adding trialStartDate, we can leave billing state untouched, and then use existing state + new state to determine what "feature tier" an org is on.

Effectively, I'm optimizing for "what's easiest to reverse and least likely to cause problems", rather than "what is the ideal long-term state", since this is experimental.

why do we set the trialStartDate in a few places like Org, OrgUser, Team? why not just one place?

This is the same as what we do with tier today, so I'm using the same pattern for consistency. Instead of storing tier just on the Org, we denormalize it onto several different objects that inherit in some way from Org, so we don't need to do a DB lookup of Org when we check the tier of an OrgUser or Team. The trialStartDate on the Org is still the source of truth.

[tianrunhe]

I did a quick test locally and it worked fine. I think the bot added me because of the migration script, which I reviewed and it LGTM.
Asked a relevant question on Slack here. We might also want to programmatically add/remove feature flags from the startTrial and endTrial mutations but they are definitely worth a separate PR.
Signing off as-is from data perspective! Great work, looking forward to seeing it in action soon!

[BartoszJarocki]

@BartoszJarocki

do you see any issues with setting tier to team when startTrial mutation runs

Nothing specific, but because tier is currently tightly coupled with billing, I'm wary about changing that state for a new experimental feature like this one - when starting+ending trials, we'd need to correctly update the tier according to billing. By keeping tier as-is and adding trialStartDate, we can leave billing state untouched, and then use existing state + new state to determine what "feature tier" an org is on.

Effectively, I'm optimizing for "what's easiest to reverse and least likely to cause problems", rather than "what is the ideal long-term state", since this is experimental.

why do we set the trialStartDate in a few places like Org, OrgUser, Team? why not just one place?

This is the same as what we do with tier today, so I'm using the same pattern for consistency. Instead of storing tier just on the Org, we denormalize it onto several different objects that inherit in some way from Org, so we don't need to do a DB lookup of Org when we check the tier of an OrgUser or Team. The trialStartDate on the Org is still the source of truth.

got it, makes sense!

[Dschoordsch]

Only did a smoke test

[Dschoordsch]

+1 it's not obvious that setUserTierForOrgId and setTierForOrgUsers can run in parallel as one writes OrganizationUser and the other one reads it. A comment on top of setUserTierForUserIds that it does not read the tier from OrganizationUser for this very reason would be nice.

[jmtaber129]

Added a comment.

[Dschoordsch]

@tianrunhe should we have some analytics events in starttrial and endtrial or is this irrelevant because we're reading the data from the db anyways?

[tianrunhe]

@tianrunhe should we have some analytics events in starttrial and endtrial or is this irrelevant because we're reading the data from the db anyways?

I think at this time, the intention is to ask our sales to run these mutations internally. Since it's not public (I think?), I have no tension adding metrics atm.

[Dschoordsch]

Could you please check what's wrong with the test for draftEnterpriseInvoice? It passes locally for me, so it might be a CI setup issue. Querying the error field in the test might give more insights.

It would be nice if the trial would show up on the OrgPlansAndBillingHeading similar to the team settings, so it would say something along the lines of: "You are on a Free Trial for the Team Tier".