feat: sync payment reviews (#146)

kevcodez · web-flow · commit 04b8e1b20e50 · 2025-06-02T12:41:09.000+08:00
Backfill not supported as only open reviews can be fetched but not historical ones
diff --git a/README.md b/README.md
@@ -102,6 +102,8 @@ This server synchronizes your Stripe account to a Postgres database. It can be a
 - [x] `product.updated` 🟢
 - [x] `radar.early_fraud_warning.created` 🟢
 - [x] `radar.early_fraud_warning.updated` 🟢
+- [x] `review.opened` 🟢
+- [x] `review.closed` 🟢
 - [x] `setup_intent.canceled` 🟢
 - [x] `setup_intent.created` 🟢
 - [x] `setup_intent.requires_action` 🟢
diff --git a/packages/fastify-app/src/test/helpers/mockStripe.ts b/packages/fastify-app/src/test/helpers/mockStripe.ts
@@ -532,6 +532,59 @@ export const mockStripe = {
       })
     ),
   },
+  paymentIntents: {
+    retrieve: vitest.fn((id) =>
+      Promise.resolve({
+        id,
+        object: 'payment_intent',
+        amount: 1000,
+        amount_capturable: 0,
+        amount_details: {
+          tip: {},
+        },
+        amount_received: 0,
+        application: null,
+        application_fee_amount: null,
+        automatic_payment_methods: null,
+        canceled_at: null,
+        cancellation_reason: null,
+        capture_method: 'automatic',
+        client_secret: 'pi_abc_secret_abc',
+        confirmation_method: 'automatic',
+        created: 1620984482,
+        currency: 'usd',
+        customer: null,
+        description: 'Created by stripe.com/docs demo',
+        invoice: null,
+        last_payment_error: null,
+        latest_charge: null,
+        livemode: false,
+        metadata: {},
+        next_action: null,
+        on_behalf_of: null,
+        payment_method: null,
+        payment_method_options: {
+          card: {
+            installments: null,
+            mandate_options: null,
+            network: null,
+            request_three_d_secure: 'automatic',
+          },
+        },
+        payment_method_types: ['card'],
+        processing: null,
+        receipt_email: null,
+        review: null,
+        setup_future_usage: null,
+        shipping: null,
+        statement_descriptor: null,
+        statement_descriptor_suffix: null,
+        status: 'requires_payment_method',
+        transfer_data: null,
+        transfer_group: null,
+      })
+    ),
+  },
   products: {
     retrieve: vitest.fn((id) =>
       Promise.resolve({
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_amount_capturable_updated.json b/packages/fastify-app/src/test/stripe/payment_intent_amount_capturable_updated.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_canceled.json b/packages/fastify-app/src/test/stripe/payment_intent_canceled.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_created.json b/packages/fastify-app/src/test/stripe/payment_intent_created.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_partially_funded.json b/packages/fastify-app/src/test/stripe/payment_intent_partially_funded.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_payment_failed.json b/packages/fastify-app/src/test/stripe/payment_intent_payment_failed.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_processing.json b/packages/fastify-app/src/test/stripe/payment_intent_processing.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_requires_action.json b/packages/fastify-app/src/test/stripe/payment_intent_requires_action.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/payment_intent_succeeded.json b/packages/fastify-app/src/test/stripe/payment_intent_succeeded.json
@@ -19,7 +19,7 @@
       "canceled_at": null,
       "cancellation_reason": null,
       "capture_method": "automatic",
-      "client_secret": "pi_1IqxJOJDPojXS6LN9uOebAea_secret_xAFUlXdrX2V3jcTfidX8eP14p",
+      "client_secret": "pi_abc_secret_abc",
       "confirmation_method": "automatic",
       "created": 1620984482,
       "currency": "usd",
diff --git a/packages/fastify-app/src/test/stripe/review_closed.json b/packages/fastify-app/src/test/stripe/review_closed.json
@@ -0,0 +1,31 @@
+{
+  "id": "evt_1KJrGtJDPojXS6LN15fcthM3",
+  "object": "event",
+  "api_version": "2020-03-02",
+  "created": 1642649111,
+  "data": {
+    "object": {
+      "id": "prv_1NVyFt2eZvKYlo2CjubqF1xm",
+      "object": "review",
+      "billing_zip": null,
+      "charge": null,
+      "closed_reason": null,
+      "created": 1689864901,
+      "ip_address": null,
+      "ip_address_location": null,
+      "livemode": false,
+      "open": true,
+      "opened_reason": "rule",
+      "payment_intent": "pi_3NVy8c2eZvKYlo2C055h7pkd",
+      "reason": "rule",
+      "session": null
+    }
+  },
+  "livemode": false,
+  "pending_webhooks": 3,
+  "request": {
+    "id": null,
+    "idempotency_key": null
+  },
+  "type": "review.closed"
+}
diff --git a/packages/fastify-app/src/test/stripe/review_opened.json b/packages/fastify-app/src/test/stripe/review_opened.json
@@ -0,0 +1,31 @@
+{
+  "id": "evt_1KJrGtJDPojXS6LN15fcthM3",
+  "object": "event",
+  "api_version": "2020-03-02",
+  "created": 1642649111,
+  "data": {
+    "object": {
+      "id": "prv_1NVyFt2eZvKYlo2CjubqF1xm",
+      "object": "review",
+      "billing_zip": null,
+      "charge": null,
+      "closed_reason": null,
+      "created": 1689864901,
+      "ip_address": null,
+      "ip_address_location": null,
+      "livemode": false,
+      "open": true,
+      "opened_reason": "rule",
+      "payment_intent": "pi_3NVy8c2eZvKYlo2C055h7pkd",
+      "reason": "rule",
+      "session": null
+    }
+  },
+  "livemode": false,
+  "pending_webhooks": 3,
+  "request": {
+    "id": null,
+    "idempotency_key": null
+  },
+  "type": "review.opened"
+}
diff --git a/packages/fastify-app/src/test/webhooks.test.ts b/packages/fastify-app/src/test/webhooks.test.ts
@@ -98,6 +98,8 @@ describe('POST /webhooks', () => {
     'credit_note_voided',
     'early_fraud_warning_created',
     'early_fraud_warning_updated',
+    'review_closed',
+    'review_opened',
   ])('process event %s', async (jsonFile) => {
     const eventBody = await import(`./stripe/${jsonFile}`).then(({ default: myData }) => myData)
     const signature = createHmac('sha256', stripeWebhookSecret)
diff --git a/packages/sync-engine/db/migrations/0029_reviews.sql b/packages/sync-engine/db/migrations/0029_reviews.sql
@@ -0,0 +1,28 @@
+create table
+    if not exists "stripe"."reviews" (
+        "id" text primary key,
+        object text,
+        billing_zip text,
+        charge text,
+        created integer,
+        closed_reason text,
+        livemode boolean,
+        ip_address text,
+        ip_address_location jsonb,
+        open boolean,
+        opened_reason text,
+        payment_intent text,
+        reason text,
+        session text,
+        updated_at timestamptz default timezone('utc'::text, now()) not null
+    );
+
+create index stripe_reviews_charge_idx on "stripe"."reviews" using btree (charge);
+
+create index stripe_reviews_payment_intent_idx on "stripe"."reviews" using btree (payment_intent);
+
+create trigger handle_updated_at
+    before update
+    on stripe.reviews
+    for each row
+    execute procedure set_updated_at();
diff --git a/packages/sync-engine/src/schemas/review.ts b/packages/sync-engine/src/schemas/review.ts
@@ -0,0 +1,20 @@
+import type { EntitySchema } from './types'
+
+export const reviewSchema: EntitySchema = {
+  properties: [
+    'id',
+    'object',
+    'billing_zip',
+    'created',
+    'charge',
+    'closed_reason',
+    'livemode',
+    'ip_address',
+    'ip_address_location',
+    'open',
+    'opened_reason',
+    'payment_intent',
+    'reason',
+    'session',
+  ],
+} as const
diff --git a/packages/sync-engine/src/stripeSync.ts b/packages/sync-engine/src/stripeSync.ts
@@ -18,6 +18,7 @@ import { subscriptionScheduleSchema } from './schemas/subscription_schedules'
 import { subscriptionSchema } from './schemas/subscription'
 import { StripeSyncConfig, Sync, SyncBackfill, SyncBackfillParams } from './types'
 import { earlyFraudWarningSchema } from './schemas/early_fraud_warning'
+import { reviewSchema } from './schemas/review'
 
 function getUniqueIds<T>(entries: T[], key: string): string[] {
   const set = new Set(
@@ -383,6 +384,21 @@ export class StripeSync {
         break
       }
 
+      case 'review.closed':
+      case 'review.opened': {
+        const review = await this.fetchOrUseWebhookData(event.data.object as Stripe.Review, (id) =>
+          this.stripe.reviews.retrieve(id)
+        )
+
+        this.config.logger?.info(
+          `Received webhook ${event.id}: ${event.type} for review ${review.id}`
+        )
+
+        await this.upsertReviews([review])
+
+        break
+      }
+
       default:
         throw new Error('Unhandled webhook event')
     }
@@ -440,6 +456,8 @@ export class StripeSync {
       return this.stripe.radar.earlyFraudWarnings
         .retrieve(stripeId)
         .then((it) => this.upsertEarlyFraudWarning([it]))
+    } else if (stripeId.startsWith('prv_')) {
+      return this.stripe.reviews.retrieve(stripeId).then((it) => this.upsertReviews([it]))
     }
   }
 
@@ -831,7 +849,7 @@ export class StripeSync {
     return this.postgresClient.upsertMany(creditNotes, 'credit_notes', creditNoteSchema)
   }
 
-  private async upsertEarlyFraudWarning(
+  async upsertEarlyFraudWarning(
     earlyFraudWarnings: Stripe.Radar.EarlyFraudWarning[],
     backfillRelatedEntities?: boolean
   ): Promise<Stripe.Radar.EarlyFraudWarning[]> {
@@ -849,6 +867,20 @@ export class StripeSync {
     )
   }
 
+  async upsertReviews(
+    reviews: Stripe.Review[],
+    backfillRelatedEntities?: boolean
+  ): Promise<Stripe.Review[]> {
+    if (backfillRelatedEntities ?? this.config.backfillRelatedEntities) {
+      await Promise.all([
+        this.backfillPaymentIntents(getUniqueIds(reviews, 'payment_intent')),
+        this.backfillCharges(getUniqueIds(reviews, 'charge')),
+      ])
+    }
+
+    return this.postgresClient.upsertMany(reviews, 'reviews', reviewSchema)
+  }
+
   async upsertCustomers(
     customers: (Stripe.Customer | Stripe.DeletedCustomer)[]
   ): Promise<(Stripe.Customer | Stripe.DeletedCustomer)[]> {
