mailery 0.8.1 → 0.10.0

package/dist/{null-CwXmiVLe.d.cts → null-CU_EApC6.d.cts}

@@ -113,6 +113,21 @@ type Predicate = {
     };
 } | {
     fieldExists: string;
+}
+/**
+ * Tests a property of the event that STARTED this run, so the answer is
+ * per-run rather than per-contact. Use when the gate depends on what the run
+ * is about (which account, plan, order) instead of a durable trait of the
+ * person: a contact-level tag is shared by every concurrent run and the last
+ * writer wins, which silently changes branching in runs already in flight.
+ */
+ | {
+    triggerPropertyEquals: {
+        key: string;
+        value: string | number | boolean | null;
+    };
+} | {
+    triggerPropertyTruthy: string;
 } | {
     hasFiredEvent: string;
     sinceFlowStart?: boolean;
@@ -378,6 +393,13 @@ interface Queues {
 type QueueDriverConfig = {
     driver: 'bull';
     redis: RedisOptions | IORedis;
+    /**
+     * Redis key prefix for all queue keys (BullMQ default: 'bull').
+     * Namespaces multiple mailery instances on one Redis cluster — e.g.
+     * 'mailery-dev' / 'mailery-prod' to isolate environments. Must not
+     * contain ':' (BullMQ uses it as the key separator).
+     */
+    prefix?: string;
 } | {
     driver: 'agenda';
     db?: Db;
@@ -1382,6 +1404,7 @@ declare class Mailer {
      *   MAILER_MONGODB_URI                — Mongo connection string (required)
      *   MAILER_MONGODB_DB                 — database name (optional; defaults to the URI default)
      *   MAILER_REDIS_URL                  — Redis connection URL (required)
+     *   MAILER_QUEUE_PREFIX               — Redis key prefix to namespace this instance (optional)
      *   MAILER_PUBLIC_URL                 — base for tracking/unsub URLs (required)
      *   MAILER_UNSUBSCRIBE_SECRET         — HMAC key (required)
      *   MAILER_SENDER_ADDRESS             — postal address for CAN-SPAM (optional)
@@ -1419,6 +1442,7 @@ declare class Mailer {
      */
     abortFlow(flowSlug: string, externalId: string, opts?: {
         reason?: string;
+        matchTriggerProperties?: Record<string, unknown>;
     }): Promise<{
         abortedRuns: number;
         cancelledSends: number;

package/dist/{null-CwXmiVLe.d.ts → null-CU_EApC6.d.ts}

@@ -113,6 +113,21 @@ type Predicate = {
     };
 } | {
     fieldExists: string;
+}
+/**
+ * Tests a property of the event that STARTED this run, so the answer is
+ * per-run rather than per-contact. Use when the gate depends on what the run
+ * is about (which account, plan, order) instead of a durable trait of the
+ * person: a contact-level tag is shared by every concurrent run and the last
+ * writer wins, which silently changes branching in runs already in flight.
+ */
+ | {
+    triggerPropertyEquals: {
+        key: string;
+        value: string | number | boolean | null;
+    };
+} | {
+    triggerPropertyTruthy: string;
 } | {
     hasFiredEvent: string;
     sinceFlowStart?: boolean;
@@ -378,6 +393,13 @@ interface Queues {
 type QueueDriverConfig = {
     driver: 'bull';
     redis: RedisOptions | IORedis;
+    /**
+     * Redis key prefix for all queue keys (BullMQ default: 'bull').
+     * Namespaces multiple mailery instances on one Redis cluster — e.g.
+     * 'mailery-dev' / 'mailery-prod' to isolate environments. Must not
+     * contain ':' (BullMQ uses it as the key separator).
+     */
+    prefix?: string;
 } | {
     driver: 'agenda';
     db?: Db;
@@ -1382,6 +1404,7 @@ declare class Mailer {
      *   MAILER_MONGODB_URI                — Mongo connection string (required)
      *   MAILER_MONGODB_DB                 — database name (optional; defaults to the URI default)
      *   MAILER_REDIS_URL                  — Redis connection URL (required)
+     *   MAILER_QUEUE_PREFIX               — Redis key prefix to namespace this instance (optional)
      *   MAILER_PUBLIC_URL                 — base for tracking/unsub URLs (required)
      *   MAILER_UNSUBSCRIBE_SECRET         — HMAC key (required)
      *   MAILER_SENDER_ADDRESS             — postal address for CAN-SPAM (optional)
@@ -1419,6 +1442,7 @@ declare class Mailer {
      */
     abortFlow(flowSlug: string, externalId: string, opts?: {
         reason?: string;
+        matchTriggerProperties?: Record<string, unknown>;
     }): Promise<{
         abortedRuns: number;
         cancelledSends: number;

package/dist/testing.cjs

@@ -14208,7 +14208,25 @@ var tagInputSchema = zod.z.object({
 var abortFlowInputSchema = zod.z.object({
   flowSlug: slugSchema,
   externalId: externalIdSchema,
-  reason: zod.z.string().min(1).max(200).optional()
+  reason: zod.z.string().min(1).max(200).optional(),
+  /**
+   * Restrict the abort to runs whose trigger event carried these properties —
+   * e.g. `{ accountId }` to cancel one account's series while the same
+   * contact's other accounts keep running. Omit to abort every active run for
+   * the contact on this flow.
+   *
+   * Keys and values are both constrained because these go straight into a
+   * Mongo query. Values are primitives only: an object value like
+   * `{ $ne: null }` would reach the query as an OPERATOR and match every
+   * scoped run, turning a one-account abort into abort-everything. Hosts
+   * typically pass an id from a request body, so treat it as untrusted. The
+   * key regex likewise blocks `$`-prefixed keys and dots (a dot would silently
+   * extend the path and change match semantics).
+   */
+  matchTriggerProperties: zod.z.record(
+    zod.z.string().regex(/^[A-Za-z0-9_]+$/),
+    zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.null()])
+  ).optional()
 });
 var abortAllFlowsInputSchema = abortFlowInputSchema.omit({ flowSlug: true });
 var sendOneOffInputSchema = zod.z.object({
@@ -14277,6 +14295,13 @@ var predicateSchema = zod.z.lazy(
     zod.z.object({ notHasTag: zod.z.string() }),
     zod.z.object({ fieldEquals: zod.z.object({ field: zod.z.string(), value: zod.z.unknown() }) }),
     zod.z.object({ fieldExists: zod.z.string() }),
+    zod.z.object({
+      triggerPropertyEquals: zod.z.object({
+        key: zod.z.string().min(1),
+        value: zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.null()])
+      })
+    }),
+    zod.z.object({ triggerPropertyTruthy: zod.z.string().min(1) }),
     zod.z.object({
       hasFiredEvent: zod.z.string(),
       sinceFlowStart: zod.z.boolean().optional(),
@@ -14636,7 +14661,7 @@ var BullDriver = class _BullDriver {
   bullQueues;
   workers = null;
   bull;
-  static async create(redisConfig) {
+  static async create(redisConfig, prefix) {
     let bull;
     try {
       bull = await import('bullmq');
@@ -14645,14 +14670,22 @@ var BullDriver = class _BullDriver {
         "mailery: queue driver 'bull' requires the 'bullmq' peer dependency. Run `npm install bullmq ioredis`."
       );
     }
+    if (prefix?.includes(":")) {
+      throw new Error(
+        `mailery: queue prefix "${prefix}" must not contain ':' \u2014 BullMQ uses it as the Redis key separator.`
+      );
+    }
     const redis = isRedisLike(redisConfig) ? redisConfig : connect(redisConfig);
-    return new _BullDriver(bull, redis);
+    return new _BullDriver(bull, redis, prefix);
   }
-  constructor(bull, redis) {
+  prefix;
+  constructor(bull, redis, prefix) {
     this.bull = bull;
     this.redis = redis;
+    this.prefix = prefix;
     const opts = {
       connection: redis,
+      prefix,
       defaultJobOptions: {
         removeOnComplete: { age: 24 * 3600, count: 1e3 },
         removeOnFail: { age: 7 * 24 * 3600 }
@@ -14684,7 +14717,7 @@ var BullDriver = class _BullDriver {
   }
   async startWorkers(opts) {
     if (this.workers) return;
-    const base = { connection: this.redis };
+    const base = { connection: this.redis, prefix: this.prefix };
     const { Worker } = this.bull;
     const tick = new Worker(
       QUEUE_NAMES.tick,
@@ -14936,7 +14969,7 @@ var NoopDriver = class {
 async function createQueueDriver(config, fallbackDb) {
   switch (config.driver) {
     case "bull":
-      return BullDriver.create(config.redis);
+      return BullDriver.create(config.redis, config.prefix);
     case "agenda":
       return AgendaDriver.create({
         db: config.db ?? fallbackDb,
@@ -15359,6 +15392,12 @@ async function evaluatePredicate(predicate, ctx) {
   if ("fieldExists" in p) {
     return ctx.contact.fields[p.fieldExists] !== void 0;
   }
+  if ("triggerPropertyEquals" in p) {
+    return (ctx.run.triggerEvent?.properties ?? {})[p.triggerPropertyEquals.key] === p.triggerPropertyEquals.value;
+  }
+  if ("triggerPropertyTruthy" in p) {
+    return Boolean((ctx.run.triggerEvent?.properties ?? {})[p.triggerPropertyTruthy]);
+  }
   if ("subscriptionStatus" in p) {
     const sub = await ctx.collections.subscriptions.findOne({ externalId: ctx.contact.externalId });
     return sub?.status === p.subscriptionStatus;
@@ -16105,7 +16144,14 @@ async function handleFireEvent(run, step2, ctx) {
     await ctx.collections.events.insertOne({
       externalId: run.externalId,
       name: step2.eventName,
-      properties: step2.properties ?? {},
+      // Inherit the triggering event's properties so a handoff carries the
+      // context that identifies what the run is ABOUT (which account, order,
+      // subscription, ...). A step's `properties` are static — authored once in
+      // the flow definition — so without this a fired event can only ever say
+      // "this contact", losing the scope the originating event supplied, and
+      // the receiving flow has nothing to resolve variables against. Explicit
+      // step.properties win on conflict.
+      properties: { ...run.triggerEvent?.properties ?? {}, ...step2.properties ?? {} },
       dedupeKey,
       occurredAt: /* @__PURE__ */ new Date(),
       createdAt: /* @__PURE__ */ new Date()
@@ -17364,6 +17410,7 @@ var Mailer = class _Mailer {
    *   MAILER_MONGODB_URI                — Mongo connection string (required)
    *   MAILER_MONGODB_DB                 — database name (optional; defaults to the URI default)
    *   MAILER_REDIS_URL                  — Redis connection URL (required)
+   *   MAILER_QUEUE_PREFIX               — Redis key prefix to namespace this instance (optional)
    *   MAILER_PUBLIC_URL                 — base for tracking/unsub URLs (required)
    *   MAILER_UNSUBSCRIBE_SECRET         — HMAC key (required)
    *   MAILER_SENDER_ADDRESS             — postal address for CAN-SPAM (optional)
@@ -17412,7 +17459,11 @@ var Mailer = class _Mailer {
     }
     const defaultProvider = env.MAILER_DEFAULT_PROVIDER ?? Object.keys(providers)[0];
     const driverEnv = env.MAILER_QUEUE_DRIVER ?? "bull";
-    const queue = driverEnv === "agenda" ? { driver: "agenda" } : driverEnv === "noop" ? { driver: "noop" } : { driver: "bull", redis: { url: required("MAILER_REDIS_URL") } };
+    const queue = driverEnv === "agenda" ? { driver: "agenda" } : driverEnv === "noop" ? { driver: "noop" } : {
+      driver: "bull",
+      redis: { url: required("MAILER_REDIS_URL") },
+      prefix: env.MAILER_QUEUE_PREFIX
+    };
     return _Mailer.init({
       db,
       adapter,
@@ -17663,14 +17714,25 @@ var Mailer = class _Mailer {
    * same handler that processes the business event ("user upgraded").
    */
   async abortFlow(flowSlug, externalId, opts = {}) {
-    const parsed = abortFlowInputSchema.parse({ flowSlug, externalId, reason: opts.reason });
+    const parsed = abortFlowInputSchema.parse({
+      flowSlug,
+      externalId,
+      reason: opts.reason,
+      matchTriggerProperties: opts.matchTriggerProperties
+    });
     const flow = await this.collections.flows.findOne(
       { slug: parsed.flowSlug },
       { projection: { _id: 1 } }
     );
     if (!flow) throw new Error(`abortFlow: unknown flow slug "${parsed.flowSlug}"`);
+    const triggerMatch = Object.fromEntries(
+      Object.entries(parsed.matchTriggerProperties ?? {}).map(([k, v]) => [
+        `triggerEvent.properties.${k}`,
+        v
+      ])
+    );
     const result = await this.abortActiveRuns(
-      { externalId: parsed.externalId, flowId: flow._id },
+      { externalId: parsed.externalId, flowId: flow._id, ...triggerMatch },
       parsed.reason ? `aborted_by_host:${parsed.reason}` : "aborted_by_host"
     );
     if (result.abortedRuns > 0 || result.cancelledSends > 0) {
@@ -17678,7 +17740,9 @@ var Mailer = class _Mailer {
         actor: "host",
         action: "flow.abort",
         resource: { collection: "mailer_flow_runs", slug: parsed.flowSlug },
-        diffSummary: `abortFlow slug=${parsed.flowSlug} externalId=${parsed.externalId} runs=${result.abortedRuns} sends=${result.cancelledSends}${parsed.reason ? ` reason=${parsed.reason}` : ""}`
+        // Record the scope: without it a one-account abort and an abort-every-
+        // run-for-this-contact are indistinguishable in the audit trail.
+        diffSummary: `abortFlow slug=${parsed.flowSlug} externalId=${parsed.externalId} scope=${parsed.matchTriggerProperties ? JSON.stringify(parsed.matchTriggerProperties) : "all"} runs=${result.abortedRuns} sends=${result.cancelledSends}${parsed.reason ? ` reason=${parsed.reason}` : ""}`
       });
     }
     return result;