npm - @cowliss/cli - Versions diffs - 0.10.0 → 0.12.0 - Mend

@cowliss/cli 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/{examples → blueprints}/abandoned-checkout/journeys/abandoned-checkout.ts RENAMED Viewed

@@ -11,7 +11,7 @@ import { defineJourney } from "@cowliss/cli/journeys";
  * `enrollment: { cooldown: "30d" }` to reach a repeat abandoner again, a
  * month after their last reminder.
  *
- * Example: add it with `cow add example abandoned-checkout`; rename the
+ * Blueprint: add it with `cow add blueprint abandoned-checkout`; rename the
  * events and the email to your domain's vocabulary.
  */
 export default defineJourney({

package/{examples → blueprints}/activity-decay/journeys/activity-decay.ts RENAMED Viewed

@@ -22,7 +22,7 @@ import { defineJourney } from "@cowliss/cli/journeys";
  * trait write below from flipping a segment whose entry event restarts this
  * journey, forever.
  *
- * Example: add it with `cow add example activity-decay`; rename the trait to
+ * Blueprint: add it with `cow add blueprint activity-decay`; rename the trait to
  * your domain's vocabulary, or narrow the pattern (`checkout.*`, or a list)
  * if only some events should count as activity.
  */

package/blueprints/ecommerce/emails/_shell.tsx ADDED Viewed

@@ -0,0 +1,133 @@
+import {
+  Body,
+  Button,
+  Container,
+  Head,
+  Heading,
+  Hr,
+  Html,
+  Preview,
+  Text,
+} from "@react-email/components";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+/**
+ * The chrome all nine mails in this blueprint share: one look for the
+ * programme rather than nine 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 three constants below are the first thing to change. The postal
+ * address is not decoration: 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 STORE_NAME = "Acme";
+export const STORE_URL = "https://example.com";
+export const STORE_ADDRESS = "Acme, 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 StoreEmail(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}>{STORE_ADDRESS}</Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+/** The one action a mail asks for. Every mail here has exactly 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,";

package/blueprints/ecommerce/emails/abandoned-checkout-last-call.tsx ADDED Viewed

@@ -0,0 +1,46 @@
+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, greeting, STORE_URL, StoreEmail, textStyle } from "./_shell";
+/**
+ * The second and last cart reminder, a day after the first. It says this
+ * is the last one, and that is the only new thing it has to say. A third
+ * reminder is how a store gets marked as spam.
+ */
+export const props = z.object({
+  checkoutUrl: z.url().optional(),
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = (p) =>
+  p.firstName
+    ? `${p.firstName}, last call on your cart`
+    : "Last call on your cart";
+export const sendClass: SendClass = "marketing";
+export const tags = ["shop", "checkout"];
+export default function AbandonedCheckoutLastCall(
+  p: z.infer<typeof props>,
+): ReactElement {
+  return (
+    <StoreEmail
+      preview="The last one about this cart."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        This is the last reminder about your cart. Stock moves, so what is in it
+        may not be there much longer.
+      </Text>
+      <Text style={textStyle}>
+        If you have changed your mind, nothing else about this cart will reach
+        you.
+      </Text>
+      <Cta href={p.checkoutUrl ?? STORE_URL}>Finish checkout</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/abandoned-checkout.tsx ADDED Viewed

@@ -0,0 +1,46 @@
+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, greeting, STORE_URL, StoreEmail, textStyle } from "./_shell";
+/**
+ * The first cart reminder, 24 hours after a checkout that went nowhere.
+ * No discount: most abandoned carts are a distraction, not a price
+ * objection, and a store that pays people to leave gets more of it.
+ *
+ * `checkoutUrl` belongs to your store, so the journey reads it off the
+ * `checkout.started` event and the button falls back to the shop when the
+ * event did not carry one.
+ */
+export const props = z.object({
+  checkoutUrl: z.url().optional(),
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = (p) =>
+  p.firstName
+    ? `${p.firstName}, your cart is still here`
+    : "Your cart is still here";
+export const sendClass: SendClass = "marketing";
+export const tags = ["shop", "checkout"];
+export default function AbandonedCheckout(
+  p: z.infer<typeof props>,
+): ReactElement {
+  return (
+    <StoreEmail
+      preview="Your cart is still here."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        You started checking out and did not finish. Your cart is saved, so
+        picking it up again takes a moment.
+      </Text>
+      <Cta href={p.checkoutUrl ?? STORE_URL}>Finish checkout</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/order-thanks.tsx ADDED Viewed

@@ -0,0 +1,44 @@
+import type { SendClass, Subject } from "@cowliss/cli/emails";
+import { Text } from "@react-email/components";
+import type { ReactElement } from "react";
+import { z } from "zod";
+import { greeting, STORE_NAME, StoreEmail, textStyle } from "./_shell";
+/**
+ * The thank-you for a first order. It is not a receipt: your shop already
+ * sent one, with the numbers on it. This is the note that says a person
+ * saw the order, so it carries no total, no tracking link and nothing to
+ * buy.
+ *
+ * Transactional, and it has no call to action at all. That is on purpose:
+ * a button here would make it a marketing mail wearing a thank-you.
+ */
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = () =>
+  `Thanks for your first order`;
+export const sendClass: SendClass = "transactional";
+export const tags = ["shop", "orders"];
+export default function OrderThanks(p: z.infer<typeof props>): ReactElement {
+  return (
+    <StoreEmail
+      preview="Your first order is on its way."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your first order from {STORE_NAME} is packed and on its way. Your
+        receipt and tracking are in a separate mail.
+      </Text>
+      <Text style={textStyle}>
+        If anything about it is wrong, reply to this message and a person reads
+        it.
+      </Text>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/replenishment.tsx ADDED Viewed

@@ -0,0 +1,40 @@
+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, greeting, STORE_URL, StoreEmail, textStyle } from "./_shell";
+/**
+ * The reorder nudge, sent when a regular customer's usual cycle has gone
+ * by without an order. Its whole argument is timing, so it makes no offer
+ * and asks for nothing except a reorder.
+ */
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = () => "Running low?";
+export const sendClass: SendClass = "marketing";
+export const tags = ["shop", "retention"];
+export default function Replenishment(p: z.infer<typeof props>): ReactElement {
+  return (
+    <StoreEmail
+      preview="Reorder in a couple of taps."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        It has been about six weeks since your last order, which is usually when
+        people come back for more.
+      </Text>
+      <Text style={textStyle}>
+        Your last order is saved, so reordering the same thing takes a couple of
+        taps.
+      </Text>
+      <Cta href={`${STORE_URL}/orders`}>Reorder</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/review-request.tsx ADDED Viewed

@@ -0,0 +1,44 @@
+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, greeting, STORE_URL, StoreEmail, textStyle } from "./_shell";
+/**
+ * Asked three days after the order was delivered, so there is something to
+ * answer. One question, one link, and an honest way out for someone whose
+ * order went wrong.
+ *
+ * Transactional, and it stays that way only as long as it is about their
+ * order. Add a discount for leaving a review and it has become marketing:
+ * move it to a journey with a marketing purpose instead.
+ */
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = () => "How is your order?";
+export const sendClass: SendClass = "transactional";
+export const tags = ["shop", "orders"];
+export default function ReviewRequest(p: z.infer<typeof props>): ReactElement {
+  return (
+    <StoreEmail
+      preview="Two minutes, if you have them."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Your order arrived a few days ago. If you have two minutes, tell us how
+        it is going. Other people read these before they buy.
+      </Text>
+      <Text style={textStyle}>
+        If it did not go well, reply to this message instead and we will sort it
+        out.
+      </Text>
+      <Cta href={`${STORE_URL}/reviews`}>Write a review</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/vip-thanks.tsx ADDED Viewed

@@ -0,0 +1,51 @@
+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,
+  greeting,
+  STORE_NAME,
+  STORE_URL,
+  StoreEmail,
+  textStyle,
+} from "./_shell";
+/**
+ * Sent once a customer crosses the lifetime-value threshold. A thank-you
+ * and one perk, and the perk is free shipping because it is worth
+ * something every time they order and costs nothing to explain.
+ *
+ * No tier name and no list of benefits: this is a note about them, not an
+ * announcement about a programme.
+ */
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = () =>
+  "Free shipping, from now on";
+export const sendClass: SendClass = "marketing";
+export const tags = ["shop", "value"];
+export default function VipThanks(p: z.infer<typeof props>): ReactElement {
+  return (
+    <StoreEmail
+      preview="Free shipping on everything you order."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        You are one of the handful of people who keep {STORE_NAME} going, and we
+        noticed.
+      </Text>
+      <Text style={textStyle}>
+        From now on your orders ship free, with nothing to enter and no minimum.
+        It is already on your account.
+      </Text>
+      <Cta href={STORE_URL}>Browse the shop</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/welcome.tsx ADDED Viewed

@@ -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,
+  greeting,
+  STORE_NAME,
+  STORE_URL,
+  StoreEmail,
+  textStyle,
+} from "./_shell";
+/**
+ * The welcome, sent to someone who has looked at a product and not
+ * ordered. It sells nothing in particular, because you do not yet know
+ * what they want: it says who you are and gets them back to the shop.
+ */
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = (p) =>
+  p.firstName ? `Welcome, ${p.firstName}` : `Welcome to ${STORE_NAME}`;
+export const sendClass: SendClass = "marketing";
+export const tags = ["shop", "lifecycle"];
+export default function Welcome(p: z.infer<typeof props>): ReactElement {
+  return (
+    <StoreEmail
+      preview="Everything we make, in one place."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        Thanks for stopping by {STORE_NAME}. Everything we sell is made in small
+        batches, and we only list what we would keep for ourselves.
+      </Text>
+      <Text style={textStyle}>
+        Orders placed before noon go out the same day, and anything that is not
+        right comes back to us free for 30 days.
+      </Text>
+      <Cta href={STORE_URL}>Browse the shop</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/winback-offer.tsx ADDED Viewed

@@ -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, greeting, STORE_URL, StoreEmail, textStyle } from "./_shell";
+/**
+ * The second and last win-back, two weeks after the reminder went
+ * unanswered. This is where the discount goes, and the code is written out
+ * here because it is one code for one campaign: change it, and the 10%
+ * below, when you change the offer.
+ */
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = () => "10% off, if you want it";
+export const sendClass: SendClass = "marketing";
+export const tags = ["shop", "retention"];
+export default function WinbackOffer(p: z.infer<typeof props>): ReactElement {
+  return (
+    <StoreEmail
+      preview="COMEBACK10, for the next 30 days."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        We would rather have you back than be right about the price, so here is
+        10% off your next order with the code COMEBACK10. It works for the next
+        30 days.
+      </Text>
+      <Text style={textStyle}>
+        This is the last mail we will send about it either way.
+      </Text>
+      <Cta href={STORE_URL}>Use the code</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/emails/winback-reminder.tsx ADDED Viewed

@@ -0,0 +1,45 @@
+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,
+  greeting,
+  STORE_NAME,
+  STORE_URL,
+  StoreEmail,
+  textStyle,
+} from "./_shell";
+/**
+ * The first win-back, sent when a customer becomes lapsed. No discount
+ * and no urgency: they already know the shop, so the job is to remind
+ * them it is still here and worth a look.
+ */
+export const props = z.object({
+  firstName: z.string().optional(),
+});
+export const subject: Subject<typeof props> = () => "It has been a while";
+export const sendClass: SendClass = "marketing";
+export const tags = ["shop", "retention"];
+export default function WinbackReminder(
+  p: z.infer<typeof props>,
+): ReactElement {
+  return (
+    <StoreEmail
+      preview="New things since you were last here."
+      heading={greeting(p.firstName)}
+    >
+      <Text style={textStyle}>
+        It has been a few months since your last order. Plenty has changed at
+        {` ${STORE_NAME}`} since then, and your details are where you left them.
+      </Text>
+      <Cta href={STORE_URL}>See what is new</Cta>
+    </StoreEmail>
+  );
+}

package/blueprints/ecommerce/journeys/_helpers.ts ADDED Viewed

@@ -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 when the
+ * win-back mail goes out is one edit in `winback.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/ecommerce/journeys/abandoned-checkout.ts ADDED Viewed

@@ -0,0 +1,44 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+/**
+ * Abandoned checkout, in two touches. `checkout.started` opens a 24-hour
+ * window; an `order.placed` inside it closes the journey quietly and marks
+ * the cart recovered, a trait your other journeys and segments can read.
+ * Silence spends one reminder, waits another 24 hours, and spends a last
+ * one.
+ *
+ * Two literals to argue with: the first `24h` is how long you leave someone
+ * alone before reminding them, the second is the gap before the last call.
+ * Shorten the first if your basket is cheap and impulse-bought.
+ *
+ * `marketing` with a 30-day cooldown, so a shopper who abandons a cart
+ * every week is reminded once a month rather than every week.
+ */
+export default defineJourney({
+  trigger: { event: "checkout.started" },
+  purpose: "marketing",
+  enrollment: { cooldown: "30d" },
+  from: "Acme <checkout@example.com>",
+  description: "Reminds someone who left items in their cart, twice at most.",
+  tags: ["shop", "checkout"],
+  run: async (event, api) => {
+    if (await api.waitForEvent("order.placed", { timeout: "24h" })) {
+      await api.traits.set("cartRecovered", true);
+      return;
+    }
+    // The checkout link belongs to your store, so the trigger event carries
+    // it; the mail drops its button when the property is missing.
+    const me = await api.profile.get();
+    const props = {
+      checkoutUrl: str(event.properties.checkoutUrl),
+      firstName: str(me.traits.firstName),
+    };
+    await api.send.email({ template: "abandoned-checkout", props });
+    if (await api.waitForEvent("order.placed", { timeout: "24h" })) {
+      await api.traits.set("cartRecovered", true);
+      return;
+    }
+    await api.send.email({ template: "abandoned-checkout-last-call", props });
+  },
+});

package/blueprints/ecommerce/journeys/first-order-thanks.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { defineJourney } from "@cowliss/cli/journeys";
+import { str } from "./_helpers";
+/**
+ * The first order, thanked, and the review asked for once it arrives.
+ *
+ * It enrolls from `segments/first-time-buyers.ts` rather than from
+ * `order.placed`, so "their first order" is the audience's job and this
+ * file has no counting to do. Every later order leaves them out of that
+ * audience, which is what makes the thank-you the first one only.
+ *
+ * `transactional`, the only one of the six that is: both mails are about
+ * one order this person chose to place, which is why neither is gated on
+ * marketing consent and why the journey takes no cooldown. That is also
+ * the line to watch. Put a discount code in the review request and it
+ * stops being about their order: move it to a marketing journey of its
+ * own rather than sending a promotion under this purpose.
+ *
+ * The review request waits for delivery and then sleeps 3 days, because
+ * the honest answer to "how is it?" needs the thing in their hands for a
+ * few days. Nothing is sent if the delivery event never arrives.
+ */
+export default defineJourney({
+  trigger: { segment: "first-time-buyers" },
+  purpose: "transactional",
+  from: "Acme <orders@example.com>",
+  description:
+    "Thanks a first-time customer, then asks how the order went once it arrives.",
+  tags: ["shop", "orders"],
+  run: async (_event, api) => {
+    const me = await api.profile.get();
+    const props = { firstName: str(me.traits.firstName) };
+    await api.send.email({ template: "order-thanks", props });
+    if (!(await api.waitForEvent("order.delivered", { timeout: "30d" }))) {
+      return;
+    }
+    await api.sleep("3d");
+    await api.send.email({ template: "review-request", props });
+  },
+});