feat: add support for disputes (#67)

Author: kevcodez

README.md

@@ -35,7 +35,11 @@ This server synchronizes your Stripe account to a Postgres database. It can be a
 - [x] `charge.refunded` 🟢
 - [x] `charge.succeeded` 🟢
 - [x] `charge.updated` 🟢
-- [ ] `charge.dispute.created`
+- [x] `charge.dispute.closed` 🟢
+- [x] `charge.dispute.created` 🟢
+- [x] `charge.dispute.funds_reinstated` 🟢
+- [x] `charge.dispute.funds_withdrawn` 🟢
+- [x] `charge.dispute.updated` 🟢
 - [ ] `checkout.session.async_payment_failed`
 - [ ] `checkout.session.async_payment_succeeded`
 - [ ] `checkout.session.completed`

db/migrations/0020_disputes_payment_intent_created_idx.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "stripe"."disputes" ADD COLUMN IF NOT EXISTS payment_intent TEXT;
+
+CREATE INDEX IF NOT EXISTS stripe_dispute_created_idx ON "stripe"."disputes" USING btree (created);

src/lib/disputes.ts

@@ -0,0 +1,43 @@
+import Stripe from 'stripe'
+import { query } from '../utils/PostgresConnection'
+import { pg as sql } from 'yesql'
+import { getConfig } from '../utils/config'
+import { stripe } from '../utils/StripeClientManager'
+import { cleanseArrayField, constructUpsertSql } from '../utils/helpers'
+import { upsertCharge } from './charges'
+import { disputeSchema } from '../schemas/dispute'
+
+const config = getConfig()
+
+export const upsertDispute = async (charge: Stripe.Dispute): Promise<Stripe.Dispute[]> => {
+  // Backfill charge if it doesn't already exist
+  const chargeId = charge?.charge?.toString()
+  if (chargeId && !(await verifyChargeExists(chargeId))) {
+    await fetchAndInsertCharge(chargeId)
+  }
+
+  // Create the SQL
+  const upsertString = constructUpsertSql(config.SCHEMA || 'stripe', 'disputes', disputeSchema)
+
+  // Inject the values
+  const cleansed = cleanseArrayField(charge)
+  const prepared = sql(upsertString)(cleansed)
+
+  // Run it
+  const { rows } = await query(prepared.text, prepared.values)
+  return rows
+}
+
+export const verifyChargeExists = async (id: string): Promise<boolean> => {
+  const prepared = sql(`
+    select id from "${config.SCHEMA}"."charges" 
+    where id = :id;
+    `)({ id })
+  const { rows } = await query(prepared.text, prepared.values)
+  return rows.length > 0
+}
+
+export const fetchAndInsertCharge = async (id: string): Promise<Stripe.Charge[]> => {
+  const charge = await stripe.charges.retrieve(id)
+  return upsertCharge(charge)
+}

src/lib/sync.ts

@@ -7,6 +7,7 @@ import { stripe } from '../utils/StripeClientManager'
 import Stripe from 'stripe'
 import { upsertSetupIntent } from './setup_intents'
 import { upsertPaymentMethod } from './payment_methods'
+import { upsertDispute } from './disputes'
 
 interface Sync {
   synced: number
@@ -20,6 +21,7 @@ interface SyncBackfill {
   invoices?: Sync
   setupIntents?: Sync
   paymentMethods?: Sync
+  disputes?: Sync
 }
 
 export interface SyncBackfillParams {
@@ -36,10 +38,11 @@ type SyncObject =
   | 'subscription'
   | 'setup_intent'
   | 'payment_method'
+  | 'dispute'
 
 export async function syncBackfill(params?: SyncBackfillParams): Promise<SyncBackfill> {
   const { created, object } = params ?? {}
-  let products, prices, customers, subscriptions, invoices, setupIntents, paymentMethods
+  let products, prices, customers, subscriptions, invoices, setupIntents, paymentMethods, disputes
 
   switch (object) {
     case 'all':
@@ -72,6 +75,9 @@ export async function syncBackfill(params?: SyncBackfillParams): Promise<SyncBac
     case 'payment_method':
       paymentMethods = await syncPaymentMethods(created)
       break
+    case 'dispute':
+      disputes = await syncDisputes(created)
+      break
     default:
       break
   }
@@ -84,6 +90,7 @@ export async function syncBackfill(params?: SyncBackfillParams): Promise<SyncBac
     invoices,
     setupIntents,
     paymentMethods,
+    disputes,
   }
 }
 
@@ -213,3 +220,16 @@ export async function syncPaymentMethods(created?: Stripe.RangeQueryParam): Prom
 
   return { synced }
 }
+
+export async function syncDisputes(created?: Stripe.RangeQueryParam): Promise<Sync> {
+  const params: Stripe.DisputeListParams = { limit: 100 }
+  if (created) params.created = created
+
+  let synced = 0
+  for await (const dispute of stripe.disputes.list(params)) {
+    await upsertDispute(dispute)
+    synced++
+  }
+
+  return { synced }
+}

src/routes/webhooks.ts

@@ -10,6 +10,7 @@ import { upsertCharge } from '../lib/charges'
 import Stripe from 'stripe'
 import { upsertSetupIntent } from '../lib/setup_intents'
 import { upsertPaymentMethod } from '../lib/payment_methods'
+import { upsertDispute } from '../lib/disputes'
 
 const config = getConfig()
 
@@ -103,6 +104,17 @@ export default async function routes(fastify: FastifyInstance) {
           await upsertPaymentMethod(paymentMethod)
           break
         }
+        case 'charge.dispute.closed':
+        case 'charge.dispute.created':
+        case 'charge.dispute.funds_reinstated':
+        case 'charge.dispute.funds_withdrawn':
+        case 'charge.dispute.updated':
+        case 'charge.dispute.closed': {
+          const dispute = event.data.object as Stripe.Dispute
+
+          await upsertDispute(dispute)
+          break
+        }
 
         default:
           throw new Error('Unhandled webhook event')

src/schemas/dispute.ts

@@ -0,0 +1,24 @@
+import { JsonSchema } from '../types/types'
+
+export const disputeSchema: JsonSchema = {
+  $id: 'disputeSchema',
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    object: { type: 'string' },
+    amount: { type: 'integer' },
+    charge: { type: 'string' },
+    created: { type: 'integer' },
+    currency: { type: 'string' },
+    balance_transactions: { type: 'object' },
+    evidence: { type: 'object' },
+    evidence_details: { type: 'object' },
+    is_charge_refundable: { type: 'boolean' },
+    livemode: { type: 'boolean' },
+    metadata: { type: 'object' },
+    payment_intent: { type: 'string' },
+    reason: { type: 'string' },
+    status: { type: 'string' },
+  },
+  required: ['id'],
+} as const

test/helpers/stripe.ts

@@ -435,4 +435,104 @@ export default {
       })
     ),
   },
+  charges: {
+    retrieve: jest.fn((id) =>
+      Promise.resolve({
+        id,
+        object: 'charge',
+        amount: 3000,
+        amount_captured: 3000,
+        amount_refunded: 0,
+        application: null,
+        application_fee: null,
+        application_fee_amount: null,
+        balance_transaction: 'txn_3KtQThJDPojXS6LN0ClROjTy',
+        billing_details: {
+          address: {
+            city: null,
+            country: 'AU',
+            line1: null,
+            line2: null,
+            postal_code: null,
+            state: null,
+          },
+          email: null,
+          name: null,
+          phone: null,
+        },
+        calculated_statement_descriptor: 'SUPABASE',
+        captured: true,
+        created: 1651125926,
+        currency: 'usd',
+        customer: 'cus_J7Mkgr8mvbl1eK',
+        description: 'Subscription update',
+        destination: null,
+        dispute: null,
+        disputed: false,
+        failure_balance_transaction: null,
+        failure_code: null,
+        failure_message: null,
+        fraud_details: {},
+        invoice: 'in_1KJdKkJDPojXS6LNSwSWkZSN',
+        livemode: false,
+        metadata: {},
+        on_behalf_of: null,
+        order: null,
+        outcome: {
+          network_status: 'approved_by_network',
+          reason: null,
+          risk_level: 'normal',
+          risk_score: 55,
+          seller_message: 'Payment complete.',
+          type: 'authorized',
+        },
+        paid: true,
+        payment_intent: 'pi_3KtQThJDPojXS6LN0H9EfsjV',
+        payment_method: 'pm_1KtQTCJDPojXS6LNmYLNUmTc',
+        payment_method_details: {
+          card: {
+            brand: 'visa',
+            checks: {
+              address_line1_check: null,
+              address_postal_code_check: null,
+              cvc_check: 'pass',
+            },
+            country: 'US',
+            exp_month: 4,
+            exp_year: 2024,
+            fingerprint: 'oPS2CZBviZaiMQyc',
+            funding: 'credit',
+            installments: null,
+            last4: '4242',
+            mandate: null,
+            network: 'visa',
+            three_d_secure: null,
+            wallet: null,
+          },
+          type: 'card',
+        },
+        receipt_email: null,
+        receipt_number: null,
+        receipt_url:
+          'https://pay.stripe.com/receipts/acct_1GThseJDPojXS6LN/ch_3KtQThJDPojXS6LN0YmgbxGj/rcpt_LabhDLLWN1rPswDktT0KujMSqYV8ROm',
+        refunded: false,
+        refunds: {
+          object: 'list',
+          data: [],
+          has_more: false,
+          total_count: 0,
+          url: '/v1/charges/ch_3KtQThJDPojXS6LN0YmgbxGj/refunds',
+        },
+        review: null,
+        shipping: null,
+        source: null,
+        source_transfer: null,
+        statement_descriptor: null,
+        statement_descriptor_suffix: null,
+        status: 'succeeded',
+        transfer_data: null,
+        transfer_group: null,
+      })
+    ),
+  },
 }

test/stripe/charge_dispute_closed.json

@@ -0,0 +1,65 @@
+{
+  "id": "evt_3KtQThJDPojXS6LN0E06aNxq",
+  "object": "event",
+  "api_version": "2020-03-02",
+  "created": 1619701111,
+  "data": {
+    "object": {
+      "id": "dp_1MLuxQJDPojXS6LNrukJCBBG",
+      "object": "dispute",
+      "amount": 1000,
+      "balance_transactions": [],
+      "charge": "ch_1IqtGAJDPojXS6LNstgEfUji",
+      "created": 1672692608,
+      "currency": "usd",
+      "evidence": {
+        "access_activity_log": null,
+        "billing_address": null,
+        "cancellation_policy": null,
+        "cancellation_policy_disclosure": null,
+        "cancellation_rebuttal": null,
+        "customer_communication": null,
+        "customer_email_address": null,
+        "customer_name": null,
+        "customer_purchase_ip": null,
+        "customer_signature": null,
+        "duplicate_charge_documentation": null,
+        "duplicate_charge_explanation": null,
+        "duplicate_charge_id": null,
+        "product_description": null,
+        "receipt": null,
+        "refund_policy": null,
+        "refund_policy_disclosure": null,
+        "refund_refusal_explanation": null,
+        "service_date": null,
+        "service_documentation": null,
+        "shipping_address": null,
+        "shipping_carrier": null,
+        "shipping_date": null,
+        "shipping_documentation": null,
+        "shipping_tracking_number": null,
+        "uncategorized_file": null,
+        "uncategorized_text": null
+      },
+      "evidence_details": {
+        "due_by": 1674345599,
+        "has_evidence": false,
+        "past_due": false,
+        "submission_count": 0
+      },
+      "is_charge_refundable": true,
+      "livemode": false,
+      "metadata": {},
+      "payment_intent": "pi_1IqtG9JDPojXS6LNOGnYrIqq",
+      "reason": "general",
+      "status": "warning_needs_response"
+    }
+  },
+  "livemode": false,
+  "pending_webhooks": 4,
+  "request": {
+    "id": "req_QyDCzn33ls4m1t",
+    "idempotency_key": null
+  },
+  "type": "charge.dispute.closed"
+}