@cowliss/cli 0.9.0 → 0.11.0

package/blueprints/mobile-game/emails/day-two-return.tsx

@@ -0,0 +1,41 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { Cta, GAME_LINK, GameEmail, greeting, textStyle } from "./_shell";
+
+/**
+ * Sent a day and a half after the tutorial, to a player who has not come
+ * back. It names one concrete thing waiting for them rather than asking
+ * them to come back in general: the second line is the one to rewrite for
+ * your own game, and it should name something that is true.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject: Subject<typeof props> = () => "Your next run is ready";
+
+export const sendClass: SendClass = "marketing";
+
+export const tags = ["game", "retention"];
+
+export default function DayTwoReturn(p: z.infer<typeof props>): ReactElement {
+  return (
+    <GameEmail
+      preview="Your camp is where you left it."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        You made it through the tutorial, which is the slowest part. What comes
+        next is the part people stay for.
+      </Text>
+      <Text style={textStyle}>
+        Your camp is where you left it, and the first daily reward is still
+        waiting to be collected.
+      </Text>
+      <Cta href={GAME_LINK}>Open the game</Cta>
+    </GameEmail>
+  );
+}

package/blueprints/mobile-game/emails/lapsed-offer.tsx

@@ -0,0 +1,41 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { Cta, GAME_LINK, GameEmail, greeting, textStyle } from "./_shell";
+
+/**
+ * The second and last return mail, a week after the reminder went
+ * unanswered. This is where the offer goes, and it is written out here
+ * because it is one offer for one campaign: change the week and the
+ * doubling together when you change it.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject: Subject<typeof props> = () =>
+  "A week of double coins, if you want it";
+
+export const sendClass: SendClass = "marketing";
+
+export const tags = ["game", "lifecycle"];
+
+export default function LapsedOffer(p: z.infer<typeof props>): ReactElement {
+  return (
+    <GameEmail
+      preview="Double coins for seven days, from your next run."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Every coin you earn is worth double for seven days, counting from the
+        next time you open the game. There is nothing to enter.
+      </Text>
+      <Text style={textStyle}>
+        This is the last mail we will send about it either way.
+      </Text>
+      <Cta href={GAME_LINK}>Claim double coins</Cta>
+    </GameEmail>
+  );
+}

package/blueprints/mobile-game/emails/lapsed-reminder.tsx

@@ -0,0 +1,48 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import {
+  Cta,
+  GAME_LINK,
+  GAME_NAME,
+  GameEmail,
+  greeting,
+  textStyle,
+} from "./_shell";
+
+/**
+ * The first return mail, sent when a player has not opened the game in a
+ * month. No currency and no countdown: they already know the game, so the
+ * job is to say it is still here, their save survived, and something has
+ * changed since they left.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject: Subject<typeof props> = () => "Your save is still here";
+
+export const sendClass: SendClass = "marketing";
+
+export const tags = ["game", "lifecycle"];
+
+export default function LapsedReminder(p: z.infer<typeof props>): ReactElement {
+  return (
+    <GameEmail
+      preview="Three new chapters since your last run."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        It has been about a month since you last played {GAME_NAME}. Your save
+        is untouched, with everything you had built on it.
+      </Text>
+      <Text style={textStyle}>
+        Three chapters have shipped since then, and the one you were on now ends
+        somewhere different.
+      </Text>
+      <Cta href={GAME_LINK}>Open the game</Cta>
+    </GameEmail>
+  );
+}

package/blueprints/mobile-game/emails/purchase-receipt.tsx

@@ -0,0 +1,47 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { GAME_NAME, GameEmail, greeting, textStyle } from "./_shell";
+
+/**
+ * The one transactional mail in this blueprint. It is not the payment
+ * receipt — the app store sends that, with the money on it — it is the
+ * game confirming that what was paid for reached the account, which is the
+ * part the store cannot say and the part a player writes to support about.
+ *
+ * No call to action at all, on purpose: a button here would make it a
+ * marketing mail wearing a receipt, and a receipt is the one mail that
+ * reaches a player who has refused marketing.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject: Subject<typeof props> = () =>
+  "Your purchase is on your account";
+
+export const sendClass: SendClass = "transactional";
+
+export const tags = ["game", "revenue"];
+
+export default function PurchaseReceipt(
+  p: z.infer<typeof props>,
+): ReactElement {
+  return (
+    <GameEmail
+      preview="Everything it includes is already there."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your first purchase in {GAME_NAME} went through, and everything it
+        includes is already on your account. The payment receipt comes from the
+        app store rather than from us.
+      </Text>
+      <Text style={textStyle}>
+        If something is missing, reply to this message and a person reads it.
+      </Text>
+    </GameEmail>
+  );
+}

package/blueprints/mobile-game/emails/spender-thanks.tsx

@@ -0,0 +1,53 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import {
+  Cta,
+  GAME_LINK,
+  GAME_NAME,
+  GameEmail,
+  greeting,
+  textStyle,
+} from "./_shell";
+
+/**
+ * Sent once a player crosses the lifetime-spend threshold. A thank-you and
+ * one perk, and the perk is a standing bonus because it is worth something
+ * every time they buy and takes one line to explain.
+ *
+ * No tier name and no list of benefits: this is a note about them, not the
+ * launch of a loyalty programme. Change the 10% here and the threshold in
+ * `journeys/spender-care.ts` together.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject: Subject<typeof props> = () =>
+  "10% extra on everything you buy";
+
+export const sendClass: SendClass = "marketing";
+
+export const tags = ["game", "revenue"];
+
+export default function SpenderThanks(p: z.infer<typeof props>): ReactElement {
+  return (
+    <GameEmail
+      preview="A standing bonus on every purchase."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        You are one of the handful of players who keep {GAME_NAME} running, and
+        we noticed.
+      </Text>
+      <Text style={textStyle}>
+        From now on every purchase you make includes 10% extra of whatever is in
+        it. There is nothing to enter and no expiry; it is already on your
+        account.
+      </Text>
+      <Cta href={GAME_LINK}>Open the game</Cta>
+    </GameEmail>
+  );
+}

package/blueprints/mobile-game/emails/stuck-hint.tsx

@@ -0,0 +1,48 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { Cta, GAME_LINK, GameEmail, greeting, textStyle } from "./_shell";
+
+/**
+ * Sent after three failures in a row. It leads with the hint and mentions
+ * the offer once, in that order: a mail that sells a second life to
+ * somebody who is losing reads as a toll booth, and the same mail that
+ * helps first reads as help.
+ *
+ * `level` comes off the `level.failed` event your game sends. The subject
+ * and the first line both work without it, because a game that sends no
+ * level number should still get a usable mail.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+  level: z.string().optional(),
+});
+
+export const subject: Subject<typeof props> = (p) =>
+  p.level ? `A hint for level ${p.level}` : "A hint for that level";
+
+export const sendClass: SendClass = "marketing";
+
+export const tags = ["game", "help"];
+
+export default function StuckHint(p: z.infer<typeof props>): ReactElement {
+  return (
+    <GameEmail
+      preview="Most people clear it on the next try."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        {p.level
+          ? `Level ${p.level} catches most people a few times. Two things help: upgrade your boots before you start, and keep the shield for the last stretch rather than opening with it.`
+          : "That level catches most people a few times. Two things help: upgrade your boots before you start, and keep the shield for the last stretch rather than opening with it."}
+      </Text>
+      <Text style={textStyle}>
+        If it still will not go, the starter pack gives you a second life on
+        every run for a week.
+      </Text>
+      <Cta href={GAME_LINK}>Try the level again</Cta>
+    </GameEmail>
+  );
+}

package/blueprints/mobile-game/emails/tutorial-nudge.tsx

@@ -0,0 +1,48 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import {
+  Cta,
+  GAME_LINK,
+  GAME_NAME,
+  GameEmail,
+  greeting,
+  textStyle,
+} from "./_shell";
+
+/**
+ * Sent a day after someone played and stopped partway through the
+ * tutorial. It says how long finishing takes and what opens up after it,
+ * because "come back" is not a reason and "two minutes" is.
+ */
+
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+
+export const subject: Subject<typeof props> = () =>
+  "Two minutes left in the tutorial";
+
+export const sendClass: SendClass = "marketing";
+
+export const tags = ["game", "onboarding"];
+
+export default function TutorialNudge(p: z.infer<typeof props>): ReactElement {
+  return (
+    <GameEmail
+      preview="Your progress is saved where you stopped."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        You started {GAME_NAME} and stopped partway through the tutorial. There
+        are about two minutes left in it, and the map, the workshop and
+        everything else open up at the end.
+      </Text>
+      <Text style={textStyle}>
+        Your progress is saved, so you start where you stopped.
+      </Text>
+      <Cta href={GAME_LINK}>Finish the tutorial</Cta>
+    </GameEmail>
+  );
+}

package/blueprints/mobile-game/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. Addresses, waits and thresholds
+ * stay written out in the journey that uses them, so changing how long a
+ * player has to come back before the return mail goes out is one edit in
+ * `lapsed-player.ts` and not a hunt through a shared config.
+ */
+
+/** A trait or event property, which arrives as `unknown`, as a string. */
+export const str = (value: unknown): string | undefined =>
+  typeof value === "string" ? value : undefined;

package/blueprints/mobile-game/journeys/day-two-return.ts

@@ -0,0 +1,40 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * Day two: they finished the tutorial and have not opened the game since.
+ * The single biggest drop in a mobile game is between the first session
+ * and the second, and this is the mail that sits in it.
+ *
+ * `tutorial.completed` is the trigger rather than `session.started`,
+ * because a session ends where the player stops and nothing says when that
+ * was; finishing the tutorial is the one moment the game knows the first
+ * session went well.
+ *
+ * 36 hours, not 24: someone who plays after work is not gone at the same
+ * hour the next day, and a mail that arrives while they are still playing
+ * is worse than no mail.
+ *
+ * `marketing` with no `enrollment`. The tutorial is finished once, so this
+ * journey runs once even without the rule, and the rule is what keeps it
+ * that way if you ever point the trigger at something repeatable.
+ */
+export default defineJourney({
+  trigger: { event: "tutorial.completed" },
+  purpose: "marketing",
+  from: "Acme Quest <play@example.com>",
+  description: "Invites a new player back for a second session.",
+  tags: ["game", "retention"],
+  run: async (_event, api) => {
+    if (await api.waitForEvent("session.started", { timeout: "36h" })) {
+      // They came back by themselves, which is the outcome this mail was
+      // for. Sending it now would be telling them to do what they did.
+      return;
+    }
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "day-two-return",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/mobile-game/journeys/first-purchase.ts

@@ -0,0 +1,34 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * The first purchase, confirmed. It enrolls from
+ * `segments/paying-players.ts` rather than from `purchase.completed`, so
+ * "has paid at all" is the audience's job and this file has no counting to
+ * do: a player crosses that line once, which is what makes this the first
+ * purchase and not every purchase.
+ *
+ * `transactional`, the only one of the six that is. The player paid for
+ * something and this says it arrived, which is why it is not gated on
+ * marketing consent and why the journey takes no cooldown.
+ *
+ * That is also the line to watch, and in a game it is thin. One mail about
+ * what they bought is transactional. The same mail with a second offer
+ * under it is marketing wearing a receipt: the follow-on belongs in
+ * `spender-care.ts`, which is marketing and says so.
+ */
+export default defineJourney({
+  trigger: { segment: "paying-players" },
+  purpose: "transactional",
+  from: "Acme Quest <receipts@example.com>",
+  description:
+    "Confirms a player's first in-app purchase reached their account.",
+  tags: ["game", "revenue"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "purchase-receipt",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/mobile-game/journeys/lapsed-player.ts

@@ -0,0 +1,39 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * The return sequence, in two touches, stopping the moment they play.
+ *
+ * It enrolls from `segments/lapsed-players.ts`, so what counts as lapsed
+ * lives in one file and this journey only decides what to do about it.
+ * Change the 30 days there, not here.
+ *
+ * The reminder goes first and carries nothing: a good number of people
+ * come back for the reminder alone, and a game that opens with free
+ * currency teaches its players to stop playing and wait for it. The offer
+ * is the second touch, a week later, and only for someone who ignored the
+ * first — the `waitForEvent` is what draws that line, and it ends the
+ * journey on the session rather than after it.
+ *
+ * `marketing` with a 180-day cooldown, so a player who drifts away again
+ * next year is invited back again, and one who drifts twice in a season is
+ * not.
+ */
+export default defineJourney({
+  trigger: { segment: "lapsed-players" },
+  purpose: "marketing",
+  enrollment: { cooldown: "180d" },
+  from: "Acme Quest <play@example.com>",
+  description: "Invites a player back who has not opened the game in a month.",
+  tags: ["game", "lifecycle"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    const props = { firstName: str(me.traits.firstName) };
+    await api.send.email({ template: "lapsed-reminder", props });
+    if (await api.waitForEvent("session.started", { timeout: "7d" })) {
+      // They played. The offer was for the people who did not.
+      return;
+    }
+    await api.send.email({ template: "lapsed-offer", props });
+  },
+});

package/blueprints/mobile-game/journeys/onboarding.ts

@@ -0,0 +1,35 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * Onboarding: they played, they did not finish the tutorial. One nudge,
+ * sent once.
+ *
+ * The wait is the whole journey. Enrolling gives the player a day to
+ * finish on their own, and `waitForEvent` is how you spend that day: it
+ * resolves the moment `tutorial.completed` arrives and returns `null` when
+ * the 24 hours are up, so the nudge is only ever sent to someone who is
+ * still stuck. A `sleep("24h")` followed by a check would mail the player
+ * who finished twenty minutes in.
+ *
+ * `marketing` with no `enrollment`, so one player is nudged once, ever,
+ * however many times they re-enter `new-players`.
+ */
+export default defineJourney({
+  trigger: { segment: "new-players" },
+  purpose: "marketing",
+  from: "Acme Quest <play@example.com>",
+  description: "Nudges a new player who stopped partway through the tutorial.",
+  tags: ["game", "onboarding"],
+  run: async (_event, api) => {
+    if (await api.waitForEvent("tutorial.completed", { timeout: "24h" })) {
+      // They finished on their own. Nothing to say.
+      return;
+    }
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "tutorial-nudge",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/mobile-game/journeys/spender-care.ts

@@ -0,0 +1,41 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * A player crosses the lifetime-spend threshold and hears about it: one
+ * thank-you carrying one perk.
+ *
+ * The trigger is a segment written out here rather than in `segments/`,
+ * because no other journey wants this audience (ADR 0023). The four in
+ * `segments/` are shared; this one is the journey's own.
+ *
+ * 50 is the threshold, and it is a number your game tells Cowliss: send
+ * the running total on identify as `lifetimeSpend` and this trigger
+ * follows it. Pick a figure only a small share of your players reach,
+ * because the mail below promises them attention.
+ *
+ * `marketing` with no `enrollment`, so crossing the threshold is worth one
+ * mail, once. This is also where the follow-on to a purchase lives: it is
+ * an offer, it is not owed to anybody, and it is gated on consent.
+ */
+export default defineJourney({
+  trigger: {
+    segment: {
+      match: "all",
+      predicates: [
+        { kind: "trait", name: "lifetimeSpend", op: "gte", value: 50 },
+      ],
+    },
+  },
+  purpose: "marketing",
+  from: "Acme Quest <play@example.com>",
+  description: "Thanks a player who has spent past the threshold, with a perk.",
+  tags: ["game", "revenue"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "spender-thanks",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/mobile-game/journeys/stuck.ts

@@ -0,0 +1,58 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * Stuck: three failures in a row, no clear in between. A player who keeps
+ * losing is one session away from deleting the game, and a hint that
+ * arrives while they are still on that level is the one piece of mail a
+ * game can send that reads as help rather than marketing.
+ *
+ * The wait takes a list, which is a disjunction: it resolves on whichever
+ * of the two arrives first, and the resolved event's `name` says which.
+ * That is how "failed again" is told apart from "cleared it" without two
+ * waits racing each other.
+ *
+ * It counts failures rather than comparing `properties.level` across them.
+ * Three failures inside two hours is one session going badly whichever
+ * levels they were, and a branch on an event property is one `cow test`
+ * cannot script, because a scenario names an event and not its properties.
+ *
+ * Two literals: the two-hour window between failures (long enough to
+ * survive a trip through a lobby screen, short enough that yesterday's
+ * failure does not count) and the three failures themselves, which is the
+ * second `waitForEvent` plus the trigger.
+ *
+ * `marketing` with a 7-day cooldown, so a player who struggles all week
+ * hears from you once rather than every evening.
+ */
+export default defineJourney({
+  trigger: { event: "level.failed" },
+  purpose: "marketing",
+  enrollment: { cooldown: "7d" },
+  from: "Acme Quest <play@example.com>",
+  description: "Sends a hint to a player who keeps failing the same run.",
+  tags: ["game", "help"],
+  run: async (event, api) => {
+    // The level belongs to your game, so the trigger event carries it; the
+    // mail drops the number when the event did not name one.
+    const level = str(event.properties.level);
+    const second = await api.waitForEvent(["level.failed", "level.completed"], {
+      timeout: "2h",
+    });
+    if (second?.name !== "level.failed") {
+      // They cleared it, or they stopped playing. Either way, no hint.
+      return;
+    }
+    const third = await api.waitForEvent(["level.failed", "level.completed"], {
+      timeout: "2h",
+    });
+    if (third?.name !== "level.failed") {
+      return;
+    }
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "stuck-hint",
+      props: { firstName: str(me.traits.firstName), level },
+    });
+  },
+});

package/blueprints/mobile-game/scenarios/day-two-return.came-back.json

@@ -0,0 +1,16 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [
+    {
+      "at": "12h",
+      "event": "session.started"
+    }
+  ],
+  "expect": []
+}

package/blueprints/mobile-game/scenarios/day-two-return.no-show.json

@@ -0,0 +1,21 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "day-two-return",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    }
+  ]
+}

package/blueprints/mobile-game/scenarios/first-purchase.paid.json

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