@cowliss/cli 0.10.0 → 0.11.0

package/blueprints/ecommerce/journeys/replenishment.ts

@@ -0,0 +1,39 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * The reorder nudge, timed off the last order. It enrolls a customer once
+ * they have ordered twice (`segments/repeat-buyers.ts`), because two orders
+ * are what tells you they buy this again at all, and then re-arms itself
+ * for as long as they keep buying.
+ *
+ * 45 days is the consumable cycle: long enough that the mail lands when
+ * they are running low rather than while the last one is still full. Set
+ * it to whatever your product actually lasts.
+ *
+ * `api.restart()` rather than a loop. Restarting starts the wait again
+ * with an empty journal; looping would journal one entry per order and
+ * your best customer is then the one whose execution hits the call cap.
+ *
+ * `marketing` with no cooldown: the restart is what makes it recur, and it
+ * only ever recurs off an order the customer placed.
+ */
+export default defineJourney({
+  trigger: { segment: "repeat-buyers" },
+  purpose: "marketing",
+  from: "Acme <hello@example.com>",
+  description: "Reminds a regular customer to reorder before they run out.",
+  tags: ["shop", "retention"],
+  run: async (_event, api) => {
+    if (await api.waitForEvent("order.placed", { timeout: "45d" })) {
+      // They reordered on their own. Start the clock again from this order,
+      // with a fresh journal.
+      await api.restart();
+    }
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "replenishment",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/ecommerce/journeys/vip.ts

@@ -0,0 +1,29 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * A customer crosses the lifetime-value threshold and hears about it: one
+ * thank-you carrying one perk.
+ *
+ * It enrolls from `segments/vip-customers.ts`, where the threshold is; the
+ * perk itself is in the mail. Give it something that costs you a little
+ * and reads as recognition, and keep it to one: a list of benefits reads
+ * as a tier announcement, and nobody thanked you for a tier.
+ *
+ * `marketing` with no cooldown, so crossing the threshold is worth one
+ * mail, once.
+ */
+export default defineJourney({
+  trigger: { segment: "vip-customers" },
+  purpose: "marketing",
+  from: "Acme <hello@example.com>",
+  description: "Thanks a customer who has spent past the VIP threshold.",
+  tags: ["shop", "value"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "vip-thanks",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/ecommerce/journeys/welcome.ts

@@ -0,0 +1,42 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * Welcome: someone with an address who has looked at a product and has
+ * never ordered. One mail, sent once.
+ *
+ * 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.
+ *
+ * A product view rather than the signup alone. An address by itself only
+ * says a form was filled in, and the mail reads better sent to someone who
+ * has seen what you sell. Drop that predicate and the welcome goes out on
+ * the identify call instead.
+ *
+ * `marketing` with no `enrollment`, so one person is welcomed once, ever,
+ * however many times they leave and re-enter the audience.
+ */
+export default defineJourney({
+  trigger: {
+    segment: {
+      match: "all",
+      predicates: [
+        { kind: "trait", name: "email", op: "exists" },
+        { kind: "event", name: "product.viewed", op: "performed", atLeast: 1 },
+        { kind: "event", name: "order.placed", op: "notPerformed" },
+      ],
+    },
+  },
+  purpose: "marketing",
+  from: "Acme <hello@example.com>",
+  description: "Introduces the store to a shopper who has not ordered yet.",
+  tags: ["shop", "lifecycle"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    await api.send.email({
+      template: "welcome",
+      props: { firstName: str(me.traits.firstName) },
+    });
+  },
+});

package/blueprints/ecommerce/journeys/winback.ts

@@ -0,0 +1,35 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+
+/**
+ * Win-back, in two touches, stopping the moment an order arrives.
+ *
+ * It enrolls from `segments/lapsed.ts`, so the definition of lapsed lives
+ * in one file and this journey only decides what to do about it. Change
+ * the 120 days there, not here.
+ *
+ * The reminder goes first and carries no discount: plenty of people come
+ * back for the reminder alone, and a store that opens with money off
+ * teaches its customers to wait for it. The offer is the second touch, 14
+ * days later, and only for someone who ignored the first.
+ *
+ * `marketing` with a 180-day cooldown, so a customer who lapses again next
+ * year is won back again, and one who lapses twice in a season is not.
+ */
+export default defineJourney({
+  trigger: { segment: "lapsed" },
+  purpose: "marketing",
+  enrollment: { cooldown: "180d" },
+  from: "Acme <hello@example.com>",
+  description: "Invites a customer back who has not ordered in months.",
+  tags: ["shop", "retention"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    const props = { firstName: str(me.traits.firstName) };
+    await api.send.email({ template: "winback-reminder", props });
+    if (await api.waitForEvent("order.placed", { timeout: "14d" })) {
+      return;
+    }
+    await api.send.email({ template: "winback-offer", props });
+  },
+});

package/blueprints/ecommerce/scenarios/abandoned-checkout.last-call.json

@@ -0,0 +1,30 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "abandoned-checkout",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    },
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "abandoned-checkout-last-call",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    }
+  ]
+}

package/blueprints/ecommerce/scenarios/abandoned-checkout.recovered.json

@@ -0,0 +1,24 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [
+    {
+      "at": "1h",
+      "event": "order.placed"
+    }
+  ],
+  "expect": [
+    {
+      "activity": "setTrait",
+      "input": {
+        "key": "cartRecovered",
+        "value": true
+      }
+    }
+  ]
+}

package/blueprints/ecommerce/scenarios/abandoned-checkout.reminded.json

@@ -0,0 +1,33 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [
+    {
+      "at": "30h",
+      "event": "order.placed"
+    }
+  ],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "abandoned-checkout",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    },
+    {
+      "activity": "setTrait",
+      "input": {
+        "key": "cartRecovered",
+        "value": true
+      }
+    }
+  ]
+}

package/blueprints/ecommerce/scenarios/first-order-thanks.delivered.json

@@ -0,0 +1,35 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [
+    {
+      "at": "2d",
+      "event": "order.delivered"
+    }
+  ],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "order-thanks",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    },
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "review-request",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    }
+  ]
+}

package/blueprints/ecommerce/scenarios/first-order-thanks.never-delivered.json

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

package/blueprints/ecommerce/scenarios/replenishment.due.json

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

package/blueprints/ecommerce/scenarios/replenishment.reordered.json

@@ -0,0 +1,20 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [
+    {
+      "at": "20d",
+      "event": "order.placed"
+    }
+  ],
+  "expect": [
+    {
+      "activity": "restart"
+    }
+  ]
+}

package/blueprints/ecommerce/scenarios/vip.crossed.json

@@ -0,0 +1,22 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada",
+      "lifetimeValue": 780
+    }
+  },
+  "events": [],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "vip-thanks",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    }
+  ]
+}

package/blueprints/ecommerce/scenarios/welcome.new-shopper.json

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

package/blueprints/ecommerce/scenarios/winback.returned.json

@@ -0,0 +1,26 @@
+{
+  "user": {
+    "id": "usr_1",
+    "traits": {
+      "email": "ada@example.com",
+      "firstName": "Ada"
+    }
+  },
+  "events": [
+    {
+      "at": "3d",
+      "event": "order.placed"
+    }
+  ],
+  "expect": [
+    {
+      "activity": "sendEmail",
+      "input": {
+        "template": "winback-reminder",
+        "props": {
+          "firstName": "Ada"
+        }
+      }
+    }
+  ]
+}

package/blueprints/ecommerce/scenarios/winback.still-gone.json

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

package/blueprints/ecommerce/segments/first-time-buyers.ts

@@ -0,0 +1,24 @@
+import { defineSegment } from "@cowliss/cli/segments";
+
+/**
+ * Bought exactly once: one `order.placed` and no second one. "Exactly one"
+ * is two predicates, because a predicate counts upwards — performed at
+ * least once, and NOT performed at least twice.
+ *
+ * A file rather than a trigger's inline definition (ADR 0023) because the
+ * dashboard reads it too: this is the audience you slice your users by
+ * while the journeys that enroll from it run.
+ *
+ * `order.placed` is the name most stores already send. If yours sends
+ * `purchase` or `Order Completed`, change the two names here and in the
+ * other segment files rather than renaming events in your own app.
+ */
+export default defineSegment({
+  description: "Placed one order and has not ordered again.",
+  tags: ["shop", "lifecycle"],
+  match: "all",
+  predicates: [
+    { kind: "event", name: "order.placed", op: "performed", atLeast: 1 },
+    { kind: "event", name: "order.placed", op: "notPerformed", atLeast: 2 },
+  ],
+});

package/blueprints/ecommerce/segments/lapsed.ts

@@ -0,0 +1,27 @@
+import { defineSegment } from "@cowliss/cli/segments";
+
+/**
+ * Bought before, and nothing in 120 days. Both predicates are needed: the
+ * first keeps out everyone who never bought at all (they belong to the
+ * welcome journey), and the second is the silence that makes a customer
+ * lapsed.
+ *
+ * 120 days is the number to argue with. It should be longer than the time
+ * your customers normally leave between orders, or the win-back journey
+ * chases people who are simply between purchases.
+ */
+export default defineSegment({
+  description: "Ordered at some point, and nothing in the last 120 days.",
+  tags: ["shop", "lifecycle"],
+  match: "all",
+  predicates: [
+    { kind: "event", name: "order.placed", op: "performed", atLeast: 1 },
+    {
+      kind: "event",
+      name: "order.placed",
+      op: "notPerformed",
+      atLeast: 1,
+      withinDays: 120,
+    },
+  ],
+});

package/blueprints/ecommerce/segments/repeat-buyers.ts

@@ -0,0 +1,18 @@
+import { defineSegment } from "@cowliss/cli/segments";
+
+/**
+ * Ordered twice or more. The second order is where a shopper becomes a
+ * customer, which is why it is the threshold: raise the 2 if your store
+ * sells something people buy in threes before they settle into a habit.
+ *
+ * The replenishment journey enrolls from this one, and the dashboard
+ * counts it beside the other three.
+ */
+export default defineSegment({
+  description: "Placed at least two orders.",
+  tags: ["shop", "lifecycle"],
+  match: "all",
+  predicates: [
+    { kind: "event", name: "order.placed", op: "performed", atLeast: 2 },
+  ],
+});

package/blueprints/ecommerce/segments/vip-customers.ts

@@ -0,0 +1,20 @@
+import { defineSegment } from "@cowliss/cli/segments";
+
+/**
+ * Spent 500 or more, all time. A trait rather than a count of events:
+ * lifetime value is a number your store already knows, so send it on
+ * identify as `lifetimeValue` and this segment follows it.
+ *
+ * The threshold is the literal below. Pick one only a small share of your
+ * customers reach, because the VIP journey promises them attention.
+ *
+ * Named `vip-customers` and not `vip`: a segment name and a journey key
+ * share one namespace per organization, and the journey that enrolls from
+ * this is called `vip`.
+ */
+export default defineSegment({
+  description: "Lifetime spend of 500 or more.",
+  tags: ["shop", "value"],
+  match: "all",
+  predicates: [{ kind: "trait", name: "lifetimeValue", op: "gte", value: 500 }],
+});

package/blueprints/mobile-game/emails/_shell.tsx

@@ -0,0 +1,138 @@
+import {
+  Body,
+  Button,
+  Container,
+  Head,
+  Heading,
+  Hr,
+  Html,
+  Preview,
+  Text,
+} from "@react-email/components";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+
+/**
+ * The chrome all seven mails in this blueprint share: one look for the
+ * programme rather than seven copies of the same inline styles. An
+ * `_`-prefixed file under `emails/` is a shared module, not a template:
+ * `cow build` skips it in discovery and bundles it into whichever template
+ * imports it.
+ *
+ * Inline styles only, no Tailwind and no stylesheet, because email clients
+ * strip both.
+ *
+ * The four constants below are the first thing to change. `GAME_LINK` is
+ * the one that matters most: every mail here sends the player back into
+ * the game, so make it a link your app opens directly (a universal link on
+ * iOS, an App Link on Android) rather than a store page a player who
+ * already installed the game has to walk through. The postal address is
+ * not decoration either: a marketing mail is required to carry one in most
+ * of the world, and Cowliss does not know yours. The unsubscribe link is
+ * the one thing you do not add here — the send path appends it to every
+ * marketing mail, and one that is already in the body is left alone.
+ */
+
+export const GAME_NAME = "Acme Quest";
+export const GAME_URL = "https://example.com";
+export const GAME_LINK = "https://example.com/play";
+export const STUDIO_ADDRESS = "Acme Games, 1 Example Street, Springfield";
+
+export const bodyStyle: CSSProperties = {
+  backgroundColor: "#f4f4f5",
+  fontFamily:
+    "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
+  margin: "0",
+  padding: "32px 0",
+};
+
+export const containerStyle: CSSProperties = {
+  margin: "0 auto",
+  padding: "40px 36px",
+  maxWidth: "560px",
+  backgroundColor: "#ffffff",
+  borderRadius: "14px",
+  border: "1px solid #e4e4e7",
+};
+
+export const headingStyle: CSSProperties = {
+  fontSize: "24px",
+  lineHeight: "1.25",
+  fontWeight: 700,
+  letterSpacing: "-0.02em",
+  color: "#09090b",
+  margin: "0 0 18px",
+};
+
+export const textStyle: CSSProperties = {
+  fontSize: "16px",
+  lineHeight: "1.7",
+  color: "#27272a",
+  margin: "0 0 16px",
+};
+
+export const buttonStyle: CSSProperties = {
+  display: "inline-block",
+  marginTop: "8px",
+  marginBottom: "16px",
+  padding: "14px 26px",
+  borderRadius: "10px",
+  backgroundColor: "#09090b",
+  color: "#ffffff",
+  fontSize: "15px",
+  fontWeight: 600,
+  lineHeight: 1,
+  textDecoration: "none",
+};
+
+const hrStyle: CSSProperties = {
+  borderColor: "#e4e4e7",
+  borderStyle: "solid",
+  borderWidth: "1px 0 0 0",
+  margin: "24px 0",
+};
+
+const footerStyle: CSSProperties = {
+  fontSize: "13px",
+  lineHeight: "1.6",
+  color: "#52525b",
+  margin: "0",
+};
+
+export function GameEmail(props: {
+  preview: string;
+  heading: string;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <Html dir="ltr" lang="en">
+      <Head>
+        <meta content="text/html; charset=UTF-8" httpEquiv="Content-Type" />
+        <meta name="x-apple-disable-message-reformatting" />
+        <meta name="color-scheme" content="light" />
+        <meta name="supported-color-schemes" content="light" />
+      </Head>
+      <Preview>{props.preview}</Preview>
+      <Body style={bodyStyle}>
+        <Container style={containerStyle}>
+          <Heading style={headingStyle}>{props.heading}</Heading>
+          {props.children}
+          <Hr style={hrStyle} />
+          <Text style={footerStyle}>{STUDIO_ADDRESS}</Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+/** The one action a mail asks for. Every mail here has at most one. */
+export function Cta(props: { href: string; children: string }): ReactElement {
+  return (
+    <Button style={buttonStyle} href={props.href}>
+      {props.children}
+    </Button>
+  );
+}
+
+/** "Hi Ada," when the journey passed a first name, "Hi," when it did not. */
+export const greeting = (firstName?: string): string =>
+  firstName ? `Hi ${firstName},` : "Hi,";