@cowliss/cli 0.9.0 → 0.11.0

package/blueprints/saas-trial/emails/trial-converted.tsx

@@ -0,0 +1,57 @@
+import type { SendClass } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import {
+  APP_URL,
+  Cta,
+  greeting,
+  PRODUCT_NAME,
+  ProductEmail,
+  textStyle,
+} from "./_shell";
+
+/**
+ * They subscribed. Sent the moment it happens rather than when the trial
+ * would have ended.
+ *
+ * It is not a receipt: your billing provider already sent one with the
+ * numbers on it. This is the note that says the trial is over and nothing
+ * is about to switch off, which is the thing somebody who just paid
+ * actually wants confirmed.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject = `You are in`;
+
+export const sendClass: SendClass = "transactional";
+
+export const tags = ["saas", "revenue"];
+
+export default function TrialConverted(p: z.infer<typeof props>): ReactElement {
+  return (
+    <ProductEmail
+      preview="Nothing switches off now."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your subscription is active, so the trial countdown is gone and nothing
+        switches off. Everything you built during the trial carries over as it
+        is.
+      </Text>
+      <Text style={textStyle}>
+        Your receipt and invoices come from our billing provider in a separate
+        mail. Seats, plan, and cancellation all live on the billing page, and
+        you can change any of them yourself.
+      </Text>
+      <Text style={textStyle}>
+        Thanks for picking {PRODUCT_NAME}. If something is not working the way
+        you expected, reply to this message.
+      </Text>
+      <Cta href={APP_URL}>Open your workspace</Cta>
+    </ProductEmail>
+  );
+}

package/blueprints/saas-trial/emails/trial-ended.tsx

@@ -0,0 +1,52 @@
+import type { SendClass } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { APP_URL, Cta, greeting, ProductEmail, textStyle } from "./_shell";
+
+/**
+ * The trial ran out and nobody subscribed. One mail, no chasing.
+ *
+ * Its whole job is to remove the worry that the work is gone, because the
+ * worry is what makes people avoid the mail rather than read it. Saying
+ * how long the data is kept, in plain days, is the useful part.
+ *
+ * Transactional, because losing access to your own work is a fact you are
+ * owed regardless of what you ticked. It stays transactional only as long
+ * as it carries no offer: a discount here makes it a win-back campaign,
+ * and a win-back campaign belongs in a journey with a marketing purpose.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject = "Your trial has ended";
+
+export const sendClass: SendClass = "transactional";
+
+export const tags = ["saas", "trial"];
+
+export default function TrialEnded(p: z.infer<typeof props>): ReactElement {
+  return (
+    <ProductEmail
+      preview="Your projects are kept for 60 days."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your trial ended today. Nothing has been deleted: your account still
+        opens, your projects are still there to read, and you can export them
+        whenever you like.
+      </Text>
+      <Text style={textStyle}>
+        We keep everything for 60 days. Subscribe inside that window and you
+        pick up exactly where you left off, with nothing to set up again.
+      </Text>
+      <Text style={textStyle}>
+        This is the last mail about the trial. If it was not the right fit, we
+        would still like to know why — reply and tell us.
+      </Text>
+      <Cta href={`${APP_URL}/billing`}>Choose a plan</Cta>
+    </ProductEmail>
+  );
+}

package/blueprints/saas-trial/emails/trial-ending-activated.tsx

@@ -0,0 +1,53 @@
+import type { SendClass } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { APP_URL, Cta, greeting, ProductEmail, textStyle } from "./_shell";
+
+/**
+ * Three days left, to somebody who has work in the product. They are
+ * deciding what happens to it, so the mail answers that and nothing else:
+ * the date, what stays, what stops.
+ *
+ * Transactional, and the one mail here that most deserves to be. Their
+ * access is about to change and the work is theirs; that is not something
+ * an unsubscribe should be able to stop. It keeps that standing by
+ * carrying no discount and no pitch — see the journey's comment for why
+ * adding one would be a bigger change than it looks.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject = "Three days left on your trial";
+
+export const sendClass: SendClass = "transactional";
+
+export const tags = ["saas", "trial"];
+
+export default function TrialEndingActivated(
+  p: z.infer<typeof props>,
+): ReactElement {
+  return (
+    <ProductEmail
+      preview="What happens to your projects on Friday."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your trial ends in three days. Here is what that means for the work you
+        have in it.
+      </Text>
+      <Text style={textStyle}>
+        Your projects stay exactly as they are. You keep read access to all of
+        them, and you can export everything at any time. What stops is editing,
+        sharing, and anything running on a schedule.
+      </Text>
+      <Text style={textStyle}>
+        Subscribing before Friday means nothing changes at all, and no gap to
+        explain to whoever you brought in.
+      </Text>
+      <Cta href={`${APP_URL}/billing`}>Choose a plan</Cta>
+    </ProductEmail>
+  );
+}

package/blueprints/saas-trial/emails/trial-ending-unactivated.tsx

@@ -0,0 +1,54 @@
+import type { SendClass } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { APP_URL, Cta, greeting, ProductEmail, textStyle } from "./_shell";
+
+/**
+ * Three days left, to somebody who never set anything up. There is no work
+ * to protect, so there is nothing to warn them about: this is an ask, and
+ * an ask is marketing.
+ *
+ * It is the pair to `trial-ending-activated.tsx`, which is transactional.
+ * Same journey, same day, different `sendClass`, because the difference is
+ * not the timing — it is that one mail is owed and the other is wanted.
+ * The journey's comment has the whole rule.
+ *
+ * What it offers is time, not a discount. Somebody who never opened the
+ * product has not priced it yet.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject = "Want another two weeks?";
+
+export const sendClass: SendClass = "marketing";
+
+export const tags = ["saas", "trial"];
+
+export default function TrialEndingUnactivated(
+  p: z.infer<typeof props>,
+): ReactElement {
+  return (
+    <ProductEmail
+      preview="Your trial ends Friday. We can move it."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your trial ends in three days and you have not had a chance to use it,
+        so ending it would not tell either of us much.
+      </Text>
+      <Text style={textStyle}>
+        Reply with the word "extend" and we will give you another two weeks,
+        starting whenever you are ready rather than today. No card, no call.
+      </Text>
+      <Text style={textStyle}>
+        Or open it now: the sample project takes about ten minutes and is enough
+        to tell whether this is worth your time.
+      </Text>
+      <Cta href={`${APP_URL}/projects/new?sample=1`}>Open a sample project</Cta>
+    </ProductEmail>
+  );
+}

package/blueprints/saas-trial/emails/trial-welcome.tsx

@@ -0,0 +1,57 @@
+import type { SendClass } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import {
+  APP_URL,
+  Cta,
+  greeting,
+  PRODUCT_NAME,
+  ProductEmail,
+  stepStyle,
+  textStyle,
+} from "./_shell";
+
+/**
+ * The mail that opens the trial. It names one thing to do, in three steps
+ * somebody can finish before their coffee goes cold, and links nothing
+ * else. A tour of every feature on day one is a tour nobody takes.
+ *
+ * The subject is a plain string rather than a function, because it does
+ * not depend on the props. `apps/platform-workspace` writes its constant
+ * subjects this way and it is one less indirection to read past.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject = `Your ${PRODUCT_NAME} trial starts now`;
+
+export const sendClass: SendClass = "transactional";
+
+export const tags = ["saas", "trial"];
+
+export default function TrialWelcome(p: z.infer<typeof props>): ReactElement {
+  return (
+    <ProductEmail
+      preview="Your first project is about ten minutes away."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your 14-day trial of {PRODUCT_NAME} is open. Everything is unlocked,
+        there is no card on file, and nothing switches off without warning.
+      </Text>
+      <Text style={textStyle}>
+        The fastest way to see whether this is for you is to create one project
+        with real work in it. That takes about ten minutes:
+      </Text>
+      <Text style={stepStyle}>1. Create a project and give it a name.</Text>
+      <Text style={stepStyle}>
+        2. Import or paste in something you already have.
+      </Text>
+      <Text style={stepStyle}>3. Open it and change one thing.</Text>
+      <Cta href={`${APP_URL}/projects/new`}>Create your first project</Cta>
+    </ProductEmail>
+  );
+}

package/blueprints/saas-trial/journeys/_helpers.ts

@@ -0,0 +1,14 @@
+/**
+ * The one thing all six journeys share. An `_`-prefixed file under
+ * `journeys/` is a module, not a journey: `cow build` skips it in
+ * discovery and bundles it into whichever journey imports it.
+ *
+ * Deliberately nothing else lives here, not even the from-address.
+ * Addresses, waits and trial lengths stay written out in the journey that
+ * uses them, so moving the activation nudge from day 2 to day 4 is one
+ * edit in `activation-nudge.ts` and not a hunt through a shared config.
+ */
+
+/** A trait, which is `unknown` on the way out of a profile, as a string. */
+export const str = (value: unknown): string | undefined =>
+  typeof value === "string" ? value : undefined;

package/blueprints/saas-trial/journeys/activated.ts

@@ -0,0 +1,42 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * The activation mail: their first project exists, so this is the moment
+ * they have seen the product work and the moment to say what comes next.
+ *
+ * `activated` is one trait doing two jobs. It guards this journey, which
+ * triggers on every `project.created` and must only mail the first one;
+ * and it is how `trial-ending.ts` knows which of its two mails to send
+ * three days before the trial runs out. Delete this journey and that split
+ * quietly collapses into its unactivated branch, so change the two files
+ * together.
+ *
+ * Setting it after the send rather than before is deliberate: a send that
+ * fails leaves the trait unset, and the next project mails them instead of
+ * skipping them forever.
+ *
+ * `transactional`: this is about something they did in their own account,
+ * five minutes ago, and it carries no offer. `apps/platform-workspace`
+ * sends its own activation mail under the same purpose for the same
+ * reason.
+ */
+export default defineJourney({
+  trigger: { event: "project.created" },
+  purpose: "transactional",
+  from: "Acme <hello@example.com>",
+  description:
+    "Congratulates someone on their first project and says what is next.",
+  tags: ["saas", "activation"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    if (me.traits.activated === true) {
+      return;
+    }
+    await api.send.email({
+      template: "activated",
+      props: { firstName: str(me.traits.firstName) },
+    });
+    await api.traits.set("activated", true);
+  },
+});

package/blueprints/saas-trial/journeys/activation-nudge.ts

@@ -0,0 +1,44 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * Two touches for a trial that has not started, stopping the moment it
+ * does:
+ *
+ *   day 2  activation-nudge  the ten-minute version of the first project
+ *   day 5  activation-help   no instructions, just "what got in the way?"
+ *
+ * Two literals to argue with: leave the first at a couple of days if
+ * people evaluate your product in one sitting, and stretch both if they
+ * need a colleague's approval before they can try anything.
+ *
+ * It enrolls from `segments/unactivated.ts`, so the milestone is defined
+ * in one file and this journey only decides what to do about it. Each wait
+ * is on `project.created`, and activating at any point ends the sequence:
+ * somebody who creates their first project on day 4 gets the walkthrough
+ * and not the "what got in the way" mail.
+ *
+ * `marketing`: a nudge is a mail nobody asked for, so it is gated on
+ * consent and counts against the frequency cap. No cooldown, which means
+ * once ever — and nobody re-enters `unactivated` anyway, because the
+ * milestone cannot be un-reached.
+ */
+export default defineJourney({
+  trigger: { segment: "unactivated" },
+  purpose: "marketing",
+  from: "Acme <hello@example.com>",
+  description: "Helps a trial that has not created its first project yet.",
+  tags: ["saas", "activation"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    const props = { firstName: str(me.traits.firstName) };
+    if (await api.waitForEvent("project.created", { timeout: "2d" })) {
+      return;
+    }
+    await api.send.email({ template: "activation-nudge", props });
+    if (await api.waitForEvent("project.created", { timeout: "3d" })) {
+      return;
+    }
+    await api.send.email({ template: "activation-help", props });
+  },
+});

package/blueprints/saas-trial/journeys/invite-your-team.ts

@@ -0,0 +1,42 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * One person is evaluating a product their team will use. Asking them to
+ * bring a colleague in is the highest-value mail in this blueprint, and
+ * the easiest one to send at the wrong moment.
+ *
+ * So it enrolls from `segments/activated-users.ts` rather than from the
+ * trial: there is no point asking someone to show their team a workspace
+ * that is still empty. Then it waits three days on `invite.sent` and says
+ * nothing at all if one arrives, because somebody who has already invited
+ * their team does not need to be asked to.
+ *
+ * The three days are the literal to argue with. Shorten it if your product
+ * is single-sitting; lengthen it if setting up a shared workspace is a
+ * week's work.
+ *
+ * `marketing` with no cooldown, so one person is asked once, ever. A
+ * cooldown is the knob for asking again, and it would do nothing here:
+ * activating is permanent, so nobody re-enters the audience to be asked a
+ * second time. Widen the audience to one people leave and return to (add
+ * a `notPerformed invite.sent withinDays` predicate, say) and the cooldown
+ * becomes the thing standing between a year and a fortnight.
+ */
+export default defineJourney({
+  trigger: { segment: "activated-users" },
+  purpose: "marketing",
+  from: "Acme <hello@example.com>",
+  description: "Asks someone working alone to bring their team in.",
+  tags: ["saas", "expansion"],
+  run: async (_event, api) => {
+    if (await api.waitForEvent("invite.sent", { timeout: "3d" })) {
+      return;
+    }
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "invite-your-team",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/saas-trial/journeys/trial-ended.ts

@@ -0,0 +1,39 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * How a trial finishes, both ways. It starts with the trial and waits the
+ * whole 14 days for `subscription.created`:
+ *
+ *   it arrives  trial-converted  sent the day they subscribe, not day 14
+ *   it does not trial-ended      sent when the trial runs out
+ *
+ * The converted mail going out early is the point. Subscribing ends the
+ * trial, so that is when there is something to say, and waiting until
+ * Friday to acknowledge a payment made on Tuesday reads as a program that
+ * is not paying attention.
+ *
+ * `transactional`, both endings: whether someone still has an account on
+ * Monday is a fact about their access, not a campaign, and neither mail
+ * carries an offer. That is the line. Put a "come back for 30% off" in
+ * `trial-ended.tsx` and it has become marketing — move it to a journey
+ * with a marketing purpose rather than changing its `sendClass` here,
+ * because the purpose is what the consent gate reads.
+ */
+export default defineJourney({
+  trigger: { event: "trial.started" },
+  purpose: "transactional",
+  from: "Acme <hello@example.com>",
+  description:
+    "Closes a trial, either with a welcome or with what happens now.",
+  tags: ["saas", "trial"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    const props = { firstName: str(me.traits.firstName) };
+    if (await api.waitForEvent("subscription.created", { timeout: "14d" })) {
+      await api.send.email({ template: "trial-converted", props });
+      return;
+    }
+    await api.send.email({ template: "trial-ended", props });
+  },
+});

package/blueprints/saas-trial/journeys/trial-ending.ts

@@ -0,0 +1,58 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * Three days before the end of a 14-day trial, split on whether they ever
+ * got the product working. The two literals are the 11 days below and the
+ * 14 in `trial-ended.ts`: they are one trial length between them, so if
+ * yours is 30 days, make them 27 and 30.
+ *
+ * The wait does two jobs. It is the eleven days, and it is the exit: a
+ * `subscription.created` inside the window means they already bought, and
+ * `trial-ended.ts` welcomes them. Waiting rather than sleeping is what
+ * stops this journey mailing a paying customer about an expiry.
+ *
+ * The profile is read AFTER the wait, not before. `activated.ts` sets the
+ * trait the moment their first project lands, which can be day 9, and a
+ * read at enrollment would have missed it. (`apps/platform-workspace`
+ * reads first in `platform-dormant.ts`, for the opposite reason: the
+ * event it waits on can no longer fire for the profiles it wants to skip.)
+ *
+ * This is the journey worth reading twice, because it sends one mail of
+ * each class:
+ *
+ *   activated    trial-ending-activated     transactional
+ *   not yet      trial-ending-unactivated   marketing
+ *
+ * A template's `sendClass` decides which gates run for THAT mail: a
+ * transactional one skips consent and the frequency cap, a marketing one
+ * does not. A journey's `purpose` is the consent category the marketing
+ * gate then asks about. So the purpose here is `marketing` — the stricter
+ * of the two — and the transactional mail is unaffected by it. Declaring
+ * `transactional` instead would let the marketing mail through the
+ * marketing gate untested, which is the one mistake this file exists to
+ * prevent.
+ *
+ * Somebody whose trial is ending and who never got started is the reason
+ * for the split: telling them their trial expires on Friday is a fact they
+ * are owed, and asking them to try again is an ask they can decline.
+ */
+export default defineJourney({
+  trigger: { segment: "trialing" },
+  purpose: "marketing",
+  from: "Acme <hello@example.com>",
+  description: "Gives three days' notice before a trial ends.",
+  tags: ["saas", "trial"],
+  run: async (_event, api) => {
+    if (await api.waitForEvent("subscription.created", { timeout: "11d" })) {
+      return;
+    }
+    const me = await api.profile.get();
+    const props = { firstName: str(me.traits.firstName) };
+    if (me.traits.activated === true) {
+      await api.send.email({ template: "trial-ending-activated", props });
+      return;
+    }
+    await api.send.email({ template: "trial-ending-unactivated", props });
+  },
+});

package/blueprints/saas-trial/journeys/trial-welcome.ts

@@ -0,0 +1,35 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * The first mail of the trial, sent on `trial.started`. One job: get them
+ * to the thing the product is for, which here is their first project.
+ *
+ * Four journeys start within a second of each other at the top of a trial
+ * — this one, `activation-nudge`, `trial-ending` and `trial-ended` — and
+ * this is the only one that sends anything today. The other three are
+ * waiting to see what happens.
+ *
+ * `transactional`: somebody asked for a trial and this is the mail that
+ * opens it, the same way a receipt follows an order. It is not gated on
+ * marketing consent and takes no cooldown, because a second trial is a
+ * second trial.
+ *
+ * That is also the line to watch. Put a case study or a pricing pitch in
+ * here and it stops being the mail they asked for; those belong in
+ * `activation-nudge`, which is gated on consent.
+ */
+export default defineJourney({
+  trigger: { event: "trial.started" },
+  purpose: "transactional",
+  from: "Acme <hello@example.com>",
+  description: "Opens a trial with the one thing to do first.",
+  tags: ["saas", "trial"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "trial-welcome",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/saas-trial/scenarios/activated.first-project.json

@@ -0,0 +1,14 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": { "email": "ada@example.com", "firstName": "Ada" }
+  },
+  "events": [],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": { "template": "activated", "props": { "firstName": "Ada" } }
+    },
+    { "activity": "setTrait", "input": { "key": "activated", "value": true } }
+  ]
+}

package/blueprints/saas-trial/scenarios/activated.second-project.json

@@ -0,0 +1,12 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada",
+      "activated": true
+    }
+  },
+  "events": [],
+  "expect": []
+}

package/blueprints/saas-trial/scenarios/activation-nudge.activated-late.json

@@ -0,0 +1,16 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": { "email": "ada@example.com", "firstName": "Ada" }
+  },
+  "events": [{ "at": "4d", "event": "project.created" }],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "activation-nudge",
+        "props": { "firstName": "Ada" }
+      }
+    }
+  ]
+}

package/blueprints/saas-trial/scenarios/activation-nudge.activated.json

@@ -0,0 +1,8 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": { "email": "ada@example.com", "firstName": "Ada" }
+  },
+  "events": [{ "at": "1d", "event": "project.created" }],
+  "expect": []
+}

package/blueprints/saas-trial/scenarios/activation-nudge.stalled.json

@@ -0,0 +1,23 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": { "email": "ada@example.com", "firstName": "Ada" }
+  },
+  "events": [],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "activation-nudge",
+        "props": { "firstName": "Ada" }
+      }
+    },
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "activation-help",
+        "props": { "firstName": "Ada" }
+      }
+    }
+  ]
+}

package/blueprints/saas-trial/scenarios/invite-your-team.alone.json

@@ -0,0 +1,16 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": { "email": "ada@example.com", "firstName": "Ada" }
+  },
+  "events": [],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "invite-your-team",
+        "props": { "firstName": "Ada" }
+      }
+    }
+  ]
+}

package/blueprints/saas-trial/scenarios/invite-your-team.invited.json

@@ -0,0 +1,8 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": { "email": "ada@example.com", "firstName": "Ada" }
+  },
+  "events": [{ "at": "1d", "event": "invite.sent" }],
+  "expect": []
+}