@tellescope/sdk 1.256.2 → 1.256.3

package/src/tests/api_tests/stripe_webhook_triggers.test.ts

@@ -0,0 +1,676 @@
+require('source-map-support').install();
+
+import { Session } from "../../sdk"
+import { assert, log_header, wait } from "@tellescope/testing"
+import { setup_tests } from "../setup"
+import {
+  cleanup_stripe_test_integrations,
+  invoice_payment_failed_event,
+  item_with_expanded_price_product,
+  item_with_plan_product,
+  item_with_price_product,
+  line_with_expanded_price_product,
+  line_with_plan_product,
+  line_with_price_product,
+  PAUSE_COLLECTION,
+  post_stripe_webhook,
+  setup_stripe_test_integration,
+  sign_stripe_payload,
+  subscription_deleted_event,
+  subscription_paused_event,
+  subscription_resumed_event,
+  subscription_updated_event,
+} from "../stripe_webhook_helpers"
+
+const host = process.env.API_URL || "http://localhost:8080"
+
+/**
+ * End-to-end coverage of the custom Stripe webhook -> automation trigger path, driven by synthetic
+ * but genuinely-signed payloads (see ../stripe_webhook_helpers).
+ *
+ * Fixture rules, all forced by handle_actions_for_triggers:
+ *  - 'Add Tags' is the action because it applies inline via $addToSet, with no worker involved.
+ *  - Every webhook POST gets its own enduser: triggers throttle per (trigger, enduser) for 60s, and
+ *    neither handle_payment_failed nor handle_subscription_ended opts out.
+ *  - No journeyId (the handler skips the action entirely for journey-scoped triggers), no
+ *    oncePerEnduser, no enduserCondition, no weeklyAvailabilities.
+ *  - Tags are run-unique, so a stale tag can't satisfy an assertion and 'Add Tags' can't no-op.
+ */
+export const stripe_webhook_triggers_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Stripe Webhook Triggers")
+
+  const RUN = `${Date.now()}`
+  const tag = (name: string) => `stripe-wh-${name}-${RUN}`
+
+  const createdEnduserIds: string[] = []
+  const createdTriggerIds: string[] = []
+  const createdProductIds: string[] = []
+
+  const { stripePublicKey, webhooksSecret, cleanup } = await setup_stripe_test_integration(sdk)
+
+  // Each enduser is matched by the handler on stripeCustomerId, so it must be unique per case.
+  const new_enduser = async (label: string) => {
+    const stripeCustomerId = `cus_test_${label}_${RUN}`
+    const enduser = await sdk.api.endusers.createOne({
+      fname: 'Stripe',
+      lname: `Webhook ${label}`,
+      email: `stripe-webhook-${label}-${RUN}@tellescope.com`,
+      // settable by a staff session, but declared readonly in the client types
+      stripeCustomerId,
+    } as any)
+    createdEnduserIds.push(enduser.id)
+
+    return { id: enduser.id, stripeCustomerId }
+  }
+
+  // `event` is loosely typed so this helper can build both trigger types, including
+  // configurations that only became valid once productIds was added to Subscription Payment Failed.
+  const new_trigger = async ({ title, event, tags } : { title: string, event: any, tags: string[] }) => {
+    const trigger = await sdk.api.automation_triggers.createOne({
+      title,
+      status: 'Active',
+      event,
+      action: { type: 'Add Tags', info: { tags } },
+    })
+    createdTriggerIds.push(trigger.id)
+
+    return trigger
+  }
+
+  // stripeSubscriptionId is the field the backend matches on, and it holds a Stripe *product* id
+  const new_product = async (label: string, stripeProductId: string) => {
+    const product = await sdk.api.products.createOne({
+      title: `Stripe Webhook Test ${label} ${RUN}`, // products.title is unique
+      cost: { amount: 1999, currency: 'USD' },
+      processor: 'Stripe',
+      stripeSubscriptionId: stripeProductId,
+    })
+    createdProductIds.push(product.id)
+
+    return product
+  }
+
+  const poll_for_tag = async (enduserId: string, expected: string, iterations = 20) => {
+    for (let i = 0; i < iterations; i++) {
+      await wait(undefined, 500)
+      const enduser = await sdk.api.endusers.getOne(enduserId)
+      if (enduser.tags?.includes(expected)) return true
+    }
+    return false
+  }
+
+  const expect_fired = async (enduserId: string, expected: string, title: string) => {
+    assert(await poll_for_tag(enduserId, expected), `expected tag ${expected} to be added by the trigger`, title)
+  }
+
+  // Nothing to poll for when asserting absence, so wait out the trigger handling like the
+  // other webhook trigger tests do
+  const expect_not_fired = async (enduserId: string, expected: string, title: string) => {
+    await wait(undefined, 2500)
+    const enduser = await sdk.api.endusers.getOne(enduserId)
+    assert(!enduser.tags?.includes(expected), `expected the trigger NOT to fire, but tag ${expected} was added`, title)
+  }
+
+  try {
+    /* ===================== invoice.payment_failed ===================== */
+
+    // B1: a valid-format signature over different bytes must be rejected. This is what proves the
+    // rest of the suite is going through real signature verification rather than around it.
+    const B1_TAG = tag('b1-bad-signature')
+    const b1Enduser = await new_enduser('b1')
+    await new_trigger({
+      title: `Stripe payment failed (bad signature) ${RUN}`,
+      event: { type: 'Subscription Payment Failed', info: {} },
+      tags: [B1_TAG],
+    })
+    const b1Event = invoice_payment_failed_event({ stripeCustomerId: b1Enduser.stripeCustomerId })
+    const b1Res = await post_stripe_webhook({
+      stripePublicKey,
+      secret: webhooksSecret,
+      event: b1Event,
+      signature: sign_stripe_payload('{"tampered":true}', webhooksSecret),
+    })
+    assert(b1Res.status === 400, `expected 400 for a mismatched signature, got ${b1Res.status}`, 'invalid signature rejected')
+    await expect_not_fired(b1Enduser.id, B1_TAG, 'invalid signature does not fire triggers')
+
+    // B2: unknown public key in the URL -> no integration -> 404
+    const b2Res = await post_stripe_webhook({
+      stripePublicKey: `pk_test_missing_${RUN}`,
+      secret: webhooksSecret,
+      event: invoice_payment_failed_event({ stripeCustomerId: `cus_test_missing_${RUN}` }),
+    })
+    assert(b2Res.status === 404, `expected 404 for an unknown public key, got ${b2Res.status}`, 'unknown integration rejected')
+
+    // B3: a signed event for a customer no enduser claims is accepted but fires nothing
+    const B3_TAG = tag('b3-unknown-customer')
+    const b3Enduser = await new_enduser('b3')
+    await new_trigger({
+      title: `Stripe payment failed (unknown customer) ${RUN}`,
+      event: { type: 'Subscription Payment Failed', info: {} },
+      tags: [B3_TAG],
+    })
+    const b3Res = await post_stripe_webhook({
+      stripePublicKey,
+      secret: webhooksSecret,
+      event: invoice_payment_failed_event({ stripeCustomerId: `cus_test_nobody_${RUN}` }),
+    })
+    assert(b3Res.status === 200, `expected 200 for an unmatched customer, got ${b3Res.status}`, 'unmatched customer accepted')
+    await expect_not_fired(b3Enduser.id, B3_TAG, 'unmatched customer does not fire triggers')
+
+    // B4: the baseline behavior the productIds feature must preserve — a Subscription Payment Failed
+    // trigger with no product scoping fires for any failed invoice.
+    const B4_TAG = tag('b4-unscoped')
+    const b4Enduser = await new_enduser('b4')
+    await new_trigger({
+      title: `Stripe payment failed (unscoped) ${RUN}`,
+      event: { type: 'Subscription Payment Failed', info: {} },
+      tags: [B4_TAG],
+    })
+    const b4Res = await post_stripe_webhook({
+      stripePublicKey,
+      secret: webhooksSecret,
+      event: invoice_payment_failed_event({
+        stripeCustomerId: b4Enduser.stripeCustomerId,
+        lines: [line_with_price_product(`prod_test_b4_${RUN}`)],
+      }),
+    })
+    assert(b4Res.status === 200, `expected 200, got ${b4Res.status} (${b4Res.data})`, 'payment failed webhook accepted')
+    await expect_fired(b4Enduser.id, B4_TAG, 'unscoped Subscription Payment Failed trigger fires')
+
+    /* ===================== customer.subscription.deleted ===================== */
+
+    // Products A and B exist to distinguish "the subscription's product" from "some other product".
+    const stripeProductA = `prod_test_a_${RUN}`
+    const stripeProductB = `prod_test_b_${RUN}`
+    const productA = await new_product('A', stripeProductA)
+    const productB = await new_product('B', stripeProductB)
+
+    // B5: unscoped Subscription Ended fires
+    const B5_TAG = tag('b5-ended-unscoped')
+    const b5Enduser = await new_enduser('b5')
+    await new_trigger({
+      title: `Stripe subscription ended (unscoped) ${RUN}`,
+      event: { type: 'Subscription Ended', info: {} },
+      tags: [B5_TAG],
+    })
+    const b5Res = await post_stripe_webhook({
+      stripePublicKey,
+      secret: webhooksSecret,
+      event: subscription_deleted_event({
+        stripeCustomerId: b5Enduser.stripeCustomerId,
+        stripeProductIds: [stripeProductA],
+      }),
+    })
+    assert(b5Res.status === 200, `expected 200, got ${b5Res.status} (${b5Res.data})`, 'subscription deleted webhook accepted')
+    await expect_fired(b5Enduser.id, B5_TAG, 'unscoped Subscription Ended trigger fires')
+
+    // B6: an explicitly empty productIds list means "all products"
+    const B6_TAG = tag('b6-ended-empty-list')
+    const b6Enduser = await new_enduser('b6')
+    await new_trigger({
+      title: `Stripe subscription ended (empty productIds) ${RUN}`,
+      event: { type: 'Subscription Ended', info: { productIds: [] } },
+      tags: [B6_TAG],
+    })
+    await post_stripe_webhook({
+      stripePublicKey,
+      secret: webhooksSecret,
+      event: subscription_deleted_event({
+        stripeCustomerId: b6Enduser.stripeCustomerId,
+        stripeProductIds: [stripeProductA],
+      }),
+    })
+    await expect_fired(b6Enduser.id, B6_TAG, 'Subscription Ended trigger with empty productIds fires')
+
+    // B7/B8 pin the existing product-matching semantics end-to-end, so any refactor of the
+    // productIds query clause is provably behavior-preserving.
+
+    // B7: productIds matching the subscription's product fires
+    const B7_TAG = tag('b7-ended-matching')
+    const b7Enduser = await new_enduser('b7')
+    await new_trigger({
+      title: `Stripe subscription ended (matching product) ${RUN}`,
+      event: { type: 'Subscription Ended', info: { productIds: [productA.id] } },
+      tags: [B7_TAG],
+    })
+    await post_stripe_webhook({
+      stripePublicKey,
+      secret: webhooksSecret,
+      event: subscription_deleted_event({
+        stripeCustomerId: b7Enduser.stripeCustomerId,
+        stripeProductIds: [stripeProductA],
+      }),
+    })
+    await expect_fired(b7Enduser.id, B7_TAG, 'Subscription Ended trigger scoped to the matching product fires')
+
+    // B8: productIds naming a different product does not fire
+    const B8_TAG = tag('b8-ended-nonmatching')
+    const b8Enduser = await new_enduser('b8')
+    await new_trigger({
+      title: `Stripe subscription ended (other product) ${RUN}`,
+      event: { type: 'Subscription Ended', info: { productIds: [productB.id] } },
+      tags: [B8_TAG],
+    })
+    await post_stripe_webhook({
+      stripePublicKey,
+      secret: webhooksSecret,
+      event: subscription_deleted_event({
+        stripeCustomerId: b8Enduser.stripeCustomerId,
+        stripeProductIds: [stripeProductA],
+      }),
+    })
+    await expect_not_fired(b8Enduser.id, B8_TAG, 'Subscription Ended trigger scoped to another product does not fire')
+
+    /* ============ invoice.payment_failed, scoped to products ============ */
+
+    // Shared shape for the cases below: a trigger scoped to productA, and an invoice whose line
+    // items are varied per case to cover how Stripe can reference a product.
+    const run_scoped_payment_failed_case = async ({ label, productIds, lines, shouldFire, title } : {
+      label: string,
+      productIds: string[],
+      lines: object[],
+      shouldFire: boolean,
+      title: string,
+    }) => {
+      const caseTag = tag(label)
+      const enduser = await new_enduser(label)
+      await new_trigger({
+        title: `Stripe payment failed (${label}) ${RUN}`,
+        event: { type: 'Subscription Payment Failed', info: { productIds } },
+        tags: [caseTag],
+      })
+
+      const res = await post_stripe_webhook({
+        stripePublicKey,
+        secret: webhooksSecret,
+        event: invoice_payment_failed_event({ stripeCustomerId: enduser.stripeCustomerId, lines }),
+      })
+      assert(res.status === 200, `expected 200, got ${res.status} (${res.data})`, `${label} webhook accepted`)
+
+      if (shouldFire) await expect_fired(enduser.id, caseTag, title)
+      else await expect_not_fired(enduser.id, caseTag, title)
+    }
+
+    // F1: the feature — a trigger scoped to the product that actually failed fires
+    await run_scoped_payment_failed_case({
+      label: 'f1-matching',
+      productIds: [productA.id],
+      lines: [line_with_price_product(stripeProductA)],
+      shouldFire: true,
+      title: 'Subscription Payment Failed scoped to the failed product fires',
+    })
+
+    // F2: the point of the feature — a trigger scoped to a different product stays quiet
+    await run_scoped_payment_failed_case({
+      label: 'f2-nonmatching',
+      productIds: [productB.id],
+      lines: [line_with_price_product(stripeProductA)],
+      shouldFire: false,
+      title: 'Subscription Payment Failed scoped to another product does not fire',
+    })
+
+    // F3: "leave blank for all" — an empty list is not a filter
+    await run_scoped_payment_failed_case({
+      label: 'f3-empty-list',
+      productIds: [],
+      lines: [line_with_price_product(stripeProductA)],
+      shouldFire: true,
+      title: 'Subscription Payment Failed with empty productIds fires',
+    })
+
+    // F4: price.product may arrive expanded as an object rather than a bare id
+    await run_scoped_payment_failed_case({
+      label: 'f4-expanded-product',
+      productIds: [productA.id],
+      lines: [line_with_expanded_price_product(stripeProductA)],
+      shouldFire: true,
+      title: 'expanded price.product object resolves to the product',
+    })
+
+    // F5: subscription/proration lines can carry plan.product with no price
+    await run_scoped_payment_failed_case({
+      label: 'f5-plan-product',
+      productIds: [productA.id],
+      lines: [line_with_plan_product(stripeProductA)],
+      shouldFire: true,
+      title: 'plan.product fallback resolves to the product',
+    })
+
+    // F6: one matching line among several is enough
+    await run_scoped_payment_failed_case({
+      label: 'f6-multi-line',
+      productIds: [productA.id],
+      lines: [line_with_price_product(stripeProductB), line_with_price_product(stripeProductA)],
+      shouldFire: true,
+      title: 'a matching line among several fires the scoped trigger',
+    })
+
+    /* ===================== validator ===================== */
+
+    // F7: productIds must round-trip, and an omitted info must stay valid — it was accepted before
+    // productIds existed, so requiring it would break existing API clients.
+    const f7Scoped = await new_trigger({
+      title: `Stripe payment failed (validator round-trip) ${RUN}`,
+      event: { type: 'Subscription Payment Failed', info: { productIds: [productA.id] } },
+      tags: [tag('f7')],
+    })
+    const f7Fetched = await sdk.api.automation_triggers.getOne(f7Scoped.id)
+    assert(
+      JSON.stringify((f7Fetched.event as any).info?.productIds) === JSON.stringify([productA.id]),
+      `expected productIds to round-trip, got ${JSON.stringify(f7Fetched.event)}`,
+      'productIds round-trips through the validator',
+    )
+
+    await new_trigger({
+      title: `Stripe payment failed (empty info) ${RUN}`,
+      event: { type: 'Subscription Payment Failed', info: {} },
+      tags: [tag('f7-empty-info')],
+    })
+    assert(true, '', 'empty info accepted')
+
+    await new_trigger({
+      title: `Stripe payment failed (no info) ${RUN}`,
+      event: { type: 'Subscription Payment Failed' },
+      tags: [tag('f7-no-info')],
+    })
+    assert(true, '', 'omitted info still accepted')
+
+    let rejectedInvalidProductId = false
+    try {
+      await new_trigger({
+        title: `Stripe payment failed (invalid productId) ${RUN}`,
+        event: { type: 'Subscription Payment Failed', info: { productIds: ['not-a-mongo-id'] } },
+        tags: [tag('f7-invalid')],
+      })
+    } catch(e) {
+      rejectedInvalidProductId = true
+    }
+    assert(rejectedInvalidProductId, 'expected a non-ObjectId productId to be rejected', 'invalid productId rejected')
+
+    /* ============ subscription paused / resumed ============ */
+
+    // Every case below is one webhook POST against a trigger of one of the two new types. `event` is
+    // built by the caller so a case can vary the pause mechanism (pause_collection transition on
+    // customer.subscription.updated, vs the dedicated paused/resumed events) independently of the
+    // product scoping.
+    const run_pause_case = async ({ label, type, productIds, event: buildEvent, shouldFire, title } : {
+      label: string,
+      type: 'Subscription Paused' | 'Subscription Resumed',
+      productIds?: string[],
+      event: (stripeCustomerId: string) => object,
+      shouldFire: boolean,
+      title: string,
+    }) => {
+      const caseTag = tag(label)
+      const enduser = await new_enduser(label)
+      await new_trigger({
+        title: `Stripe ${type} (${label}) ${RUN}`,
+        event: { type, ...productIds !== undefined ? { info: { productIds } } : {} },
+        tags: [caseTag],
+      })
+
+      const res = await post_stripe_webhook({
+        stripePublicKey,
+        secret: webhooksSecret,
+        event: buildEvent(enduser.stripeCustomerId),
+      })
+      assert(res.status === 200, `expected 200, got ${res.status} (${res.data})`, `${label} webhook accepted`)
+
+      if (shouldFire) await expect_fired(enduser.id, caseTag, title)
+      else await expect_not_fired(enduser.id, caseTag, title)
+    }
+
+    // P1: the core pause path — pause_collection goes null -> set on customer.subscription.updated.
+    // This is how a pause from the billing portal or dashboard actually arrives; there is no
+    // dedicated event for it.
+    await run_pause_case({
+      label: 'p1-pause-collection-set',
+      type: 'Subscription Paused',
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        previousAttributes: { pause_collection: null },
+        pauseCollection: PAUSE_COLLECTION,
+      }),
+      shouldFire: true,
+      title: 'pause_collection null -> set fires Subscription Paused',
+    })
+
+    // P2: the mirror — pause_collection cleared is a resume
+    await run_pause_case({
+      label: 'p2-pause-collection-cleared',
+      type: 'Subscription Resumed',
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        previousAttributes: { pause_collection: PAUSE_COLLECTION },
+        pauseCollection: null,
+      }),
+      shouldFire: true,
+      title: 'pause_collection set -> null fires Subscription Resumed',
+    })
+
+    // P3: a pause that is only *modified* (behavior or resumes_at changed) is neither a pause nor a
+    // resume — firing here would re-trigger every time a customer adjusts an existing pause
+    await run_pause_case({
+      label: 'p3-pause-modified',
+      type: 'Subscription Paused',
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        previousAttributes: { pause_collection: { behavior: 'void', resumes_at: null } },
+        pauseCollection: { behavior: 'keep_as_draft', resumes_at: null },
+      }),
+      shouldFire: false,
+      title: 'a modified pause_collection fires neither trigger',
+    })
+
+    // P4: the volume guard. customer.subscription.updated fires on every renewal, price change and
+    // cancel_at_period_end toggle; with no pause_collection key in previous_attributes the handler
+    // must do nothing (and, in the API, must not even reach the enduser lookup).
+    await run_pause_case({
+      label: 'p4-unrelated-update',
+      type: 'Subscription Paused',
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        previousAttributes: { items: { object: 'list', data: [] } },
+      }),
+      shouldFire: false,
+      title: 'an unrelated subscription update fires neither trigger',
+    })
+
+    // P4b: the idempotency case. previous_attributes carries only what changed, so an unrelated
+    // update to an already-paused subscription has no pause_collection key even though
+    // pause_collection is currently set. Firing here would re-trigger on every renewal, quantity
+    // change and coupon edit for the whole duration of a pause — which is what would happen if the
+    // gate were ever "simplified" to read current state instead of the transition.
+    await run_pause_case({
+      label: 'p4b-update-while-paused',
+      type: 'Subscription Paused',
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        previousAttributes: { quantity: 1 },
+        pauseCollection: PAUSE_COLLECTION,
+      }),
+      shouldFire: false,
+      title: 'an unrelated update while already paused does not re-fire Subscription Paused',
+    })
+
+    // P5/P6: the dedicated events, which Stripe emits for status='paused' transitions only
+    await run_pause_case({
+      label: 'p5-dedicated-paused',
+      type: 'Subscription Paused',
+      event: stripeCustomerId => subscription_paused_event({ stripeCustomerId }),
+      shouldFire: true,
+      title: 'customer.subscription.paused fires Subscription Paused',
+    })
+    await run_pause_case({
+      label: 'p6-dedicated-resumed',
+      type: 'Subscription Resumed',
+      event: stripeCustomerId => subscription_resumed_event({ stripeCustomerId }),
+      shouldFire: true,
+      title: 'customer.subscription.resumed fires Subscription Resumed',
+    })
+
+    // P7: a Paused trigger must not fire on a resume, and vice versa — the two are separate types
+    await run_pause_case({
+      label: 'p7-wrong-direction',
+      type: 'Subscription Paused',
+      event: stripeCustomerId => subscription_resumed_event({ stripeCustomerId }),
+      shouldFire: false,
+      title: 'a resume does not fire a Subscription Paused trigger',
+    })
+
+    // P8: the dedupe guard — the .updated that accompanies a status='paused' transition must not
+    // fire on top of the dedicated event. Stripe isn't expected to send this combination at all;
+    // the case pins the guard so a future refactor can't quietly drop it.
+    await run_pause_case({
+      label: 'p8-paused-status-suppressed',
+      type: 'Subscription Paused',
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        previousAttributes: { pause_collection: null, status: 'trialing' },
+        pauseCollection: PAUSE_COLLECTION,
+        status: 'paused',
+      }),
+      shouldFire: false,
+      title: 'a pause_collection change coinciding with status=paused is suppressed',
+    })
+
+    /* ---- product scoping, over the pause_collection path ---- */
+
+    // P9-P12: the same matrix the payment-failed cases cover, applied to the new triggers
+    await run_pause_case({
+      label: 'p9-scoped-matching',
+      type: 'Subscription Paused',
+      productIds: [productA.id],
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        items: [item_with_price_product(stripeProductA)],
+        previousAttributes: { pause_collection: null },
+        pauseCollection: PAUSE_COLLECTION,
+      }),
+      shouldFire: true,
+      title: 'Subscription Paused scoped to the paused product fires',
+    })
+
+    await run_pause_case({
+      label: 'p10-scoped-nonmatching',
+      type: 'Subscription Paused',
+      productIds: [productB.id],
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        items: [item_with_price_product(stripeProductA)],
+        previousAttributes: { pause_collection: null },
+        pauseCollection: PAUSE_COLLECTION,
+      }),
+      shouldFire: false,
+      title: 'Subscription Paused scoped to another product does not fire',
+    })
+
+    await run_pause_case({
+      label: 'p11-empty-list',
+      type: 'Subscription Paused',
+      productIds: [],
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        items: [item_with_price_product(stripeProductA)],
+        previousAttributes: { pause_collection: null },
+        pauseCollection: PAUSE_COLLECTION,
+      }),
+      shouldFire: true,
+      title: 'Subscription Paused with empty productIds fires',
+    })
+
+    // plan.product and expanded price.product objects both have to resolve, same as the invoice path
+    await run_pause_case({
+      label: 'p12-plan-product',
+      type: 'Subscription Resumed',
+      productIds: [productA.id],
+      event: stripeCustomerId => subscription_updated_event({
+        stripeCustomerId,
+        items: [item_with_plan_product(stripeProductA)],
+        previousAttributes: { pause_collection: PAUSE_COLLECTION },
+        pauseCollection: null,
+      }),
+      shouldFire: true,
+      title: 'plan.product resolves for a scoped Subscription Resumed trigger',
+    })
+
+    await run_pause_case({
+      label: 'p13-expanded-product',
+      type: 'Subscription Resumed',
+      productIds: [productA.id],
+      event: stripeCustomerId => subscription_resumed_event({
+        stripeCustomerId,
+        items: [item_with_expanded_price_product(stripeProductA)],
+      }),
+      shouldFire: true,
+      title: 'expanded price.product resolves on the dedicated resumed event',
+    })
+
+    /* ---- validator ---- */
+
+    // P14: same round-trip guarantees as F7, for both new types
+    const p14Scoped = await new_trigger({
+      title: `Stripe subscription paused (validator round-trip) ${RUN}`,
+      event: { type: 'Subscription Paused', info: { productIds: [productA.id] } },
+      tags: [tag('p14')],
+    })
+    const p14Fetched = await sdk.api.automation_triggers.getOne(p14Scoped.id)
+    assert(
+      JSON.stringify((p14Fetched.event as any).info?.productIds) === JSON.stringify([productA.id]),
+      `expected productIds to round-trip, got ${JSON.stringify(p14Fetched.event)}`,
+      'Subscription Paused productIds round-trips through the validator',
+    )
+
+    await new_trigger({
+      title: `Stripe subscription resumed (no info) ${RUN}`,
+      event: { type: 'Subscription Resumed' },
+      tags: [tag('p14-no-info')],
+    })
+    assert(true, '', 'Subscription Resumed with omitted info accepted')
+
+    let rejectedInvalidPausedProductId = false
+    try {
+      await new_trigger({
+        title: `Stripe subscription paused (invalid productId) ${RUN}`,
+        event: { type: 'Subscription Paused', info: { productIds: ['not-a-mongo-id'] } },
+        tags: [tag('p14-invalid')],
+      })
+    } catch(e) {
+      rejectedInvalidPausedProductId = true
+    }
+    assert(rejectedInvalidPausedProductId, 'expected a non-ObjectId productId to be rejected', 'invalid Subscription Paused productId rejected')
+
+    console.log("All Stripe webhook trigger tests passed!")
+  } finally {
+    // Best-effort only: the harness exits the process on the first failed assertion, which skips
+    // this block. setup_stripe_test_integration clears integration residue on the next run.
+    await cleanup().catch(console.error)
+    await Promise.all([
+      ...createdTriggerIds.map(id => sdk.api.automation_triggers.deleteOne(id).catch(console.error)),
+      ...createdProductIds.map(id => sdk.api.products.deleteOne(id).catch(console.error)),
+      ...createdEnduserIds.map(id => sdk.api.endusers.deleteOne(id).catch(console.error)),
+    ])
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`Using API URL: ${host}`)
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await stripe_webhook_triggers_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+    .then(() => {
+      console.log("Stripe webhook triggers test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("Stripe webhook triggers test suite failed:", error)
+      process.exit(1)
+    })
+}