feat: updates subscription billing cycle on invoice.issued event (#22)

Orb currently has no webhook whenever a billing cycle is reset, so subscription billing cycle information may be outdated.
As a workaround we check whether an issued invoice contains a plan line item. A plan line item bein present means that there
was a billing cycle reset and you can find the billing cycle's start and end date in the line item.

Author: ecktoteckto

apps/node-fastify/.env.sample

@@ -16,3 +16,5 @@ ORB_API_KEY=test_
 # Optional
 PORT=8080
 
+# Optional, whether to verify the Orb webhook signature
+VERIFY_WEBHOOK_SIGNATURE=true

apps/node-fastify/src/app.ts

@@ -42,6 +42,7 @@ export async function createApp(opts: FastifyServerOptions = {}): Promise<Fastif
     orbWebhookSecret: config.ORB_WEBHOOK_SECRET,
     databaseSchema: config.DATABASE_SCHEMA,
     orbApiKey: config.ORB_API_KEY,
+    verifyWebhookSignature: config.VERIFY_WEBHOOK_SIGNATURE,
   });
 
   app.decorate('orbSync', orbSync);

apps/node-fastify/src/utils/config.ts

@@ -19,6 +19,9 @@ type configType = {
 
   /** Access the Orb API */
   ORB_API_KEY?: string;
+
+  /** Whether to verify the Orb webhook signature */
+  VERIFY_WEBHOOK_SIGNATURE: boolean;
 };
 
 function getConfigFromEnv(key: string, defaultValue?: string): string {
@@ -40,6 +43,7 @@ export function getConfig(): configType {
     DATABASE_URL: getConfigFromEnv('DATABASE_URL'),
     ORB_WEBHOOK_SECRET: getConfigFromEnv('ORB_WEBHOOK_SECRET'),
     PORT: Number(getConfigFromEnv('PORT', '8080')),
+    VERIFY_WEBHOOK_SIGNATURE: getConfigFromEnv('VERIFY_WEBHOOK_SIGNATURE', 'true') === 'true',
   };
 
   assert(!Number.isNaN(config.PORT), 'PORT must be a number');

packages/orb-sync-lib/src/database/postgres.ts

@@ -76,6 +76,39 @@ export class PostgresClient {
       ;`;
   };
 
+  /**
+   * Updates a subscription's billing cycle dates, provided that the current end date is in the past (i.e. the subscription
+   * data in the database being stale).
+   */
+  async updateSubscriptionBillingCycle({
+    subscriptionId,
+    billingCycleStart,
+    billingCycleEnd,
+  }: {
+    subscriptionId: string;
+    billingCycleStart: string;
+    billingCycleEnd: string;
+  }) {
+    const updateSql = `
+      update "${this.config.schema}"."subscriptions"
+      set (current_billing_period_start_date, current_billing_period_end_date) =
+      (:current_billing_period_start_date, :current_billing_period_end_date)
+      where id = :id and current_billing_period_end_date < :now`;
+
+    const prepared = sql(updateSql, {
+      useNullForMissing: true,
+    })({
+      id: subscriptionId,
+      current_billing_period_start_date: billingCycleStart,
+      current_billing_period_end_date: billingCycleEnd,
+      now: new Date().toISOString(),
+    });
+
+    const result = await this.pool.query(prepared.text, prepared.values);
+
+    return result.rows;
+  }
+
   private cleanseArrayField(
     obj: {
       [Key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any

packages/orb-sync-lib/src/invoice-utils.ts

@@ -0,0 +1,32 @@
+import { Invoice } from 'orb-billing/resources';
+
+const PLAN_LINE_ITEM_NAME_ENDS_IN = 'Plan';
+
+/**
+ * Returns the billing cycle the given invoice's plan line item applies to.
+ * If no plan line item is present, null is returned.
+ */
+export function getBillingCycleFromInvoice(invoice: Invoice): { start: string; end: string } | null {
+  const planLineItem = findPlanLineItem(invoice.line_items);
+
+  // No plan line item found.
+  // Is the case for e.g. invoices that include usage line items for the past billing cycle only or
+  // invoices that include a fixed price line item other than the plan line item only
+  if (!planLineItem) {
+    return null;
+  }
+
+  return {
+    start: planLineItem.start_date,
+    end: planLineItem.end_date,
+  };
+}
+
+function findPlanLineItem(lineItems: Invoice.LineItem[]): Invoice.LineItem | undefined {
+  return lineItems.find(
+    (item) =>
+      item.price?.price_type === 'fixed_price' &&
+      item.price.billable_metric === null &&
+      item.name.endsWith(PLAN_LINE_ITEM_NAME_ENDS_IN)
+  );
+}

packages/orb-sync-lib/src/orb-sync.ts

@@ -14,10 +14,16 @@ import type {
 } from './types';
 import { PostgresClient } from './database/postgres';
 import { fetchAndSyncCustomer, fetchAndSyncCustomers, syncCustomers } from './sync/customers';
-import { fetchAndSyncSubscription, fetchAndSyncSubscriptions, syncSubscriptions } from './sync/subscriptions';
+import {
+  fetchAndSyncSubscription,
+  fetchAndSyncSubscriptions,
+  syncSubscriptions,
+  updateBillingCycle,
+} from './sync/subscriptions';
 import { fetchAndSyncInvoice, fetchAndSyncInvoices, syncInvoices } from './sync/invoices';
 import { fetchAndSyncCreditNote, fetchAndSyncCreditNotes, syncCreditNotes } from './sync/credit_notes';
 import { fetchAndSyncPlan, fetchAndSyncPlans } from './sync/plans';
+import { getBillingCycleFromInvoice } from './invoice-utils';
 
 export type OrbSyncConfig = {
   databaseUrl: string;
@@ -54,7 +60,7 @@ export class OrbSync {
       | CustomersFetchParams
       | CreditNotesFetchParams
       | SubscriptionsFetchParams
-      | PlansFetchParams,
+      | PlansFetchParams
   ): Promise<number> {
     switch (entity) {
       case 'invoices': {
@@ -112,8 +118,24 @@ export class OrbSync {
         // We don't want to override invoice data with a minified version.
         break;
       }
+
+      case 'invoice.issued': {
+        const invoice = (parsedData as InvoiceWebhook).invoice;
+        await syncInvoices(this.postgresClient, [invoice]);
+
+        const billingCycle = getBillingCycleFromInvoice(invoice);
+        if (billingCycle && invoice.subscription) {
+          await updateBillingCycle(this.postgresClient, {
+            subscriptionId: invoice.subscription.id,
+            billingCycleStart: billingCycle.start,
+            billingCycleEnd: billingCycle.end,
+          });
+        }
+
+        break;
+      }
+
       case 'invoice.edited':
-      case 'invoice.issued':
       case 'invoice.manually_marked_as_void':
       case 'invoice.payment_failed':
       case 'invoice.issue_failed':

packages/orb-sync-lib/src/sync/subscriptions.ts

@@ -58,3 +58,28 @@ export async function fetchAndSyncSubscription(postgresClient: PostgresClient, o
 
   await syncSubscriptions(postgresClient, [subscription]);
 }
+
+export async function updateBillingCycle(
+  postgresClient: PostgresClient,
+  {
+    subscriptionId,
+    billingCycleStart,
+    billingCycleEnd,
+  }: {
+    subscriptionId: string;
+    billingCycleStart: string;
+    billingCycleEnd: string;
+  }
+) {
+  const isBillingCycleStartInThePast = new Date(billingCycleStart) < new Date();
+  const isBillingCycleEndInTheFuture = new Date(billingCycleEnd) > new Date();
+
+  if (!isBillingCycleStartInThePast || !isBillingCycleEndInTheFuture) {
+    console.info(
+      `Billing cycle of subscription ${subscriptionId} is not being updated. start (${billingCycleStart}) / end (${billingCycleEnd}) not suitable`
+    );
+    return;
+  }
+
+  return postgresClient.updateSubscriptionBillingCycle({ subscriptionId, billingCycleStart, billingCycleEnd });
+}