feat: add renewal invoice sweep (#20)

Refs #9

## Summary
- add a worker-side renewal invoice sweep that creates one invoice 72 hours before subscription expiry
- expire elapsed pending invoices automatically and email users when an automatic renewal invoice is created
- stop auto-recreating invoices for the same paid cycle once any invoice already exists for that cycle
- document the current renewal-invoice and pending-invoice expiry behavior

## Testing
- built `infra/docker/web.Dockerfile`
- ran `pnpm --filter @nproxy/db test` inside the built container
- verified `@nproxy/db build` and `@nproxy/web build` during the image build
- built `infra/docker/worker.Dockerfile`

Co-authored-by: sirily <sirily@git.shararam.party>
Reviewed-on: #20

packages/db/src/billing-store.test.ts

@@ -3,6 +3,142 @@ import assert from "node:assert/strict";
 import { Prisma } from "@prisma/client";
 import { BillingError, createPrismaBillingStore } from "./billing-store.js";
 
+test("createUpcomingRenewalInvoices creates one invoice for subscriptions entering the 72h renewal window", async () => {
+  const database = createRenewalBillingDatabase({
+    subscriptions: [
+      createRenewalSubscriptionFixture({
+        id: "subscription_1",
+        currentPeriodStart: new Date("2026-03-01T12:00:00.000Z"),
+        currentPeriodEnd: new Date("2026-03-12T11:00:00.000Z"),
+      }),
+    ],
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const notifications = await store.createUpcomingRenewalInvoices({
+    paymentProvider: "nowpayments",
+    paymentProviderAdapter: {
+      createInvoice: async () => ({
+        providerInvoiceId: "provider_invoice_renewal_1",
+        paymentAddress: "wallet_renewal_1",
+        amountCrypto: 29,
+        amountUsd: 29,
+        currency: "USDT",
+        expiresAt: new Date("2026-03-10T13:00:00.000Z"),
+      }),
+      getInvoiceStatus: async (providerInvoiceId) => ({
+        providerInvoiceId,
+        status: "pending",
+      }),
+    },
+    renewalLeadTimeHours: 72,
+    now: new Date("2026-03-09T12:00:00.000Z"),
+  });
+
+  assert.equal(notifications.length, 1);
+  assert.equal(notifications[0]?.email, "user_subscription_1@example.com");
+  assert.equal(notifications[0]?.subscriptionId, "subscription_1");
+  assert.equal(database.calls.paymentInvoiceCreate.length, 1);
+});
+
+test("createUpcomingRenewalInvoices does not auto-create another invoice after one already exists in the current cycle", async () => {
+  const currentPeriodStart = new Date("2026-03-01T12:00:00.000Z");
+  const database = createRenewalBillingDatabase({
+    subscriptions: [
+      createRenewalSubscriptionFixture({
+        id: "subscription_1",
+        currentPeriodStart,
+        currentPeriodEnd: new Date("2026-03-12T11:00:00.000Z"),
+      }),
+    ],
+    existingInvoicesBySubscriptionId: {
+      subscription_1: [
+        createInvoiceFixture({
+          id: "invoice_existing",
+          status: "expired",
+          createdAt: new Date("2026-03-09T09:00:00.000Z"),
+          paidAt: null,
+          subscription: createSubscriptionFixture({
+            id: "subscription_1",
+            currentPeriodStart,
+            currentPeriodEnd: new Date("2026-03-12T11:00:00.000Z"),
+            status: "active",
+          }),
+        }),
+      ],
+    },
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const notifications = await store.createUpcomingRenewalInvoices({
+    paymentProvider: "nowpayments",
+    paymentProviderAdapter: {
+      createInvoice: async () => {
+        throw new Error("createInvoice should not be called");
+      },
+      getInvoiceStatus: async (providerInvoiceId) => ({
+        providerInvoiceId,
+        status: "pending",
+      }),
+    },
+    renewalLeadTimeHours: 72,
+    now: new Date("2026-03-09T12:00:00.000Z"),
+  });
+
+  assert.equal(notifications.length, 0);
+  assert.equal(database.calls.paymentInvoiceCreate.length, 0);
+});
+
+test("createUpcomingRenewalInvoices acquires a subscription billing lock before creating an invoice", async () => {
+  const database = createRenewalBillingDatabase({
+    subscriptions: [
+      createRenewalSubscriptionFixture({
+        id: "subscription_1",
+        currentPeriodStart: new Date("2026-03-01T12:00:00.000Z"),
+        currentPeriodEnd: new Date("2026-03-12T11:00:00.000Z"),
+      }),
+    ],
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const notifications = await store.createUpcomingRenewalInvoices({
+    paymentProvider: "nowpayments",
+    paymentProviderAdapter: {
+      createInvoice: async () => ({
+        providerInvoiceId: "provider_invoice_renewal_1",
+        paymentAddress: "wallet_renewal_1",
+        amountCrypto: 29,
+        amountUsd: 29,
+        currency: "USDT",
+        expiresAt: new Date("2026-03-10T13:00:00.000Z"),
+      }),
+      getInvoiceStatus: async (providerInvoiceId) => ({
+        providerInvoiceId,
+        status: "pending",
+      }),
+    },
+    renewalLeadTimeHours: 72,
+    now: new Date("2026-03-09T12:00:00.000Z"),
+  });
+
+  assert.equal(notifications.length, 1);
+  assert.equal(database.calls.paymentInvoiceCreate.length, 1);
+  assert.deepEqual(database.calls.subscriptionBillingLocks, ["subscription_1"]);
+});
+
+test("expireElapsedPendingInvoices marks pending invoices expired", async () => {
+  const database = createRenewalBillingDatabase({
+    subscriptions: [],
+    expirePendingCount: 2,
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const result = await store.expireElapsedPendingInvoices(new Date("2026-03-10T12:00:00.000Z"));
+
+  assert.equal(result.expiredCount, 2);
+  assert.equal(database.calls.paymentInvoiceExpireUpdateMany.length, 1);
+});
+
 test("markInvoicePaid activates a pending invoice once and writes an admin audit log", async () => {
   const invoice = createInvoiceFixture({
     status: "pending",
@@ -149,6 +285,118 @@ test("markInvoicePaid treats a concurrent pending->paid race as a replay without
   assert.equal(database.calls.adminAuditCreate[0]?.metadata?.replayed, true);
 });
 
+test("reconcilePendingInvoice marks a pending invoice paid using provider paidAt", async () => {
+  const providerPaidAt = new Date("2026-03-10T12:34:56.000Z");
+  const database = createBillingDatabase({
+    invoice: createInvoiceFixture({
+      status: "pending",
+      paidAt: null,
+      subscription: createSubscriptionFixture(),
+    }),
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const result = await store.reconcilePendingInvoice({
+    invoiceId: "invoice_1",
+    providerStatus: "paid",
+    paidAt: providerPaidAt,
+    actor: {
+      type: "system",
+      ref: "invoice_reconciliation",
+    },
+  });
+
+  assert.equal(result.outcome, "marked_paid");
+  assert.equal(result.invoice.paidAt?.toISOString(), providerPaidAt.toISOString());
+  assert.equal(database.calls.paymentInvoiceUpdateMany.length, 1);
+  assert.equal(
+    (
+      database.calls.paymentInvoiceUpdateMany[0] as {
+        data: { paidAt: Date };
+      }
+    ).data.paidAt.toISOString(),
+    providerPaidAt.toISOString(),
+  );
+  assert.equal(
+    (
+      database.calls.subscriptionUpdate[0] as {
+        data: { currentPeriodStart: Date };
+      }
+    ).data.currentPeriodStart.toISOString(),
+    providerPaidAt.toISOString(),
+  );
+});
+
+test("reconcilePendingInvoice marks a pending invoice expired", async () => {
+  const database = createBillingDatabase({
+    invoice: createInvoiceFixture({
+      status: "pending",
+      paidAt: null,
+      subscription: createSubscriptionFixture(),
+    }),
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const result = await store.reconcilePendingInvoice({
+    invoiceId: "invoice_1",
+    providerStatus: "expired",
+  });
+
+  assert.equal(result.outcome, "marked_expired");
+  assert.equal(result.invoice.status, "expired");
+  assert.equal(database.calls.paymentInvoiceTerminalUpdateMany.length, 1);
+  assert.equal(database.calls.subscriptionUpdate.length, 0);
+  assert.equal(database.calls.usageLedgerCreate.length, 0);
+});
+
+test("reconcilePendingInvoice does not override an already paid invoice with expired status", async () => {
+  const paidAt = new Date("2026-03-10T12:00:00.000Z");
+  const database = createBillingDatabase({
+    invoice: createInvoiceFixture({
+      status: "paid",
+      paidAt,
+      subscription: createSubscriptionFixture(),
+    }),
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const result = await store.reconcilePendingInvoice({
+    invoiceId: "invoice_1",
+    providerStatus: "expired",
+  });
+
+  assert.equal(result.outcome, "ignored_terminal_state");
+  assert.equal(result.invoice.status, "paid");
+  assert.equal(database.calls.paymentInvoiceTerminalUpdateMany.length, 0);
+});
+
+test("reconcilePendingInvoice accepts provider paid for a locally expired invoice", async () => {
+  const providerPaidAt = new Date("2026-03-10T12:34:56.000Z");
+  const database = createBillingDatabase({
+    invoice: createInvoiceFixture({
+      status: "expired",
+      paidAt: null,
+      subscription: createSubscriptionFixture(),
+    }),
+  });
+  const store = createPrismaBillingStore(database.client);
+
+  const result = await store.reconcilePendingInvoice({
+    invoiceId: "invoice_1",
+    providerStatus: "paid",
+    paidAt: providerPaidAt,
+    actor: {
+      type: "system",
+      ref: "invoice_reconciliation",
+    },
+  });
+
+  assert.equal(result.outcome, "marked_paid");
+  assert.equal(result.invoice.status, "paid");
+  assert.equal(result.invoice.paidAt?.toISOString(), providerPaidAt.toISOString());
+  assert.equal(database.calls.paymentInvoiceUpdateMany.length, 1);
+});
+
 function createBillingDatabase(input: {
   invoice: ReturnType<typeof createInvoiceFixture>;
   updateManyCount?: number;
@@ -156,6 +404,7 @@ function createBillingDatabase(input: {
 }) {
   const calls = {
     paymentInvoiceUpdateMany: [] as Array<Record<string, unknown>>,
+    paymentInvoiceTerminalUpdateMany: [] as Array<Record<string, unknown>>,
     subscriptionUpdate: [] as Array<Record<string, unknown>>,
     usageLedgerCreate: [] as Array<Record<string, unknown>>,
     adminAuditCreate: [] as Array<Record<string, any>>,
@@ -183,14 +432,18 @@ function createBillingDatabase(input: {
         where,
         data,
       }: {
-        where: { id: string; status: "pending" };
+        where: { id: string; status: "pending" | { in: Array<"pending" | "expired" | "canceled"> } };
         data: { status: "paid"; paidAt: Date };
       }) => {
         calls.paymentInvoiceUpdateMany.push({ where, data });
 
+        const allowedStatuses =
+          (typeof where.status === "string" ? [where.status] : where.status.in) as Array<
+            "pending" | "expired" | "canceled" | "paid"
+          >;
         const count =
           input.updateManyCount ??
-          (currentInvoice.id === where.id && currentInvoice.status === where.status ? 1 : 0);
+          (currentInvoice.id === where.id && allowedStatuses.includes(currentInvoice.status) ? 1 : 0);
 
         if (count > 0) {
           currentInvoice = {
@@ -224,6 +477,29 @@ function createBillingDatabase(input: {
   };
 
   const client = {
+    paymentInvoice: {
+      findUnique: async () => currentInvoice,
+      updateMany: async ({
+        where,
+        data,
+      }: {
+        where: { id: string; status: "pending" };
+        data: { status: "expired" | "canceled" };
+      }) => {
+        calls.paymentInvoiceTerminalUpdateMany.push({ where, data });
+
+        const count = currentInvoice.id === where.id && currentInvoice.status === where.status ? 1 : 0;
+
+        if (count > 0) {
+          currentInvoice = {
+            ...currentInvoice,
+            status: data.status,
+          };
+        }
+
+        return { count };
+      },
+    },
     $transaction: async <T>(callback: (tx: typeof transaction) => Promise<T>) => callback(transaction),
   } as unknown as Parameters<typeof createPrismaBillingStore>[0];
 
@@ -234,12 +510,14 @@ function createBillingDatabase(input: {
 }
 
 function createInvoiceFixture(input: {
+  id?: string;
   status: "pending" | "paid" | "expired" | "canceled";
   paidAt: Date | null;
+  createdAt?: Date;
   subscription: ReturnType<typeof createSubscriptionFixture> | null;
 }) {
   return {
-    id: "invoice_1",
+    id: input.id ?? "invoice_1",
     userId: "user_1",
     subscriptionId: input.subscription?.id ?? null,
     provider: "nowpayments",
@@ -251,22 +529,30 @@ function createInvoiceFixture(input: {
     paymentAddress: "wallet_1",
     expiresAt: new Date("2026-03-11T12:00:00.000Z"),
     paidAt: input.paidAt,
-    createdAt: new Date("2026-03-10T11:00:00.000Z"),
-    updatedAt: new Date("2026-03-10T11:00:00.000Z"),
+    createdAt: input.createdAt ?? new Date("2026-03-10T11:00:00.000Z"),
+    updatedAt: input.createdAt ?? new Date("2026-03-10T11:00:00.000Z"),
     subscription: input.subscription,
   };
 }
 
-function createSubscriptionFixture() {
+function createSubscriptionFixture(
+  overrides?: Partial<{
+    id: string;
+    status: "pending_activation" | "active" | "expired";
+    currentPeriodStart: Date | null;
+    currentPeriodEnd: Date | null;
+    activatedAt: Date | null;
+  }>,
+) {
   return {
-    id: "subscription_1",
+    id: overrides?.id ?? "subscription_1",
     userId: "user_1",
     planId: "plan_1",
-    status: "pending_activation" as const,
+    status: overrides?.status ?? ("pending_activation" as const),
     renewsManually: true,
-    activatedAt: null,
-    currentPeriodStart: null,
-    currentPeriodEnd: null,
+    activatedAt: overrides?.activatedAt ?? null,
+    currentPeriodStart: overrides?.currentPeriodStart ?? null,
+    currentPeriodEnd: overrides?.currentPeriodEnd ?? null,
     canceledAt: null,
     createdAt: new Date("2026-03-10T11:00:00.000Z"),
     updatedAt: new Date("2026-03-10T11:00:00.000Z"),
@@ -283,3 +569,118 @@ function createSubscriptionFixture() {
     },
   };
 }
+
+function createRenewalBillingDatabase(input: {
+  subscriptions: Array<ReturnType<typeof createRenewalSubscriptionFixture>>;
+  existingInvoicesBySubscriptionId?: Record<string, ReturnType<typeof createInvoiceFixture>[]>;
+  expirePendingCount?: number;
+}) {
+  const calls = {
+    paymentInvoiceCreate: [] as Array<Record<string, unknown>>,
+    paymentInvoiceFindFirst: [] as Array<Record<string, unknown>>,
+    paymentInvoiceExpireUpdateMany: [] as Array<Record<string, unknown>>,
+    subscriptionBillingLocks: [] as string[],
+  };
+
+  const transaction = {
+    $queryRaw: async (strings: TemplateStringsArray, subscriptionId: string) => {
+      if (strings[0]?.includes('FROM "Subscription"')) {
+        calls.subscriptionBillingLocks.push(subscriptionId);
+      }
+
+      return [];
+    },
+    subscription: {
+      findMany: async () => input.subscriptions,
+    },
+    paymentInvoice: {
+      findFirst: async ({
+        where,
+      }: {
+        where: {
+          subscriptionId: string;
+          createdAt: { gte: Date };
+        };
+      }) => {
+        calls.paymentInvoiceFindFirst.push({ where });
+        const invoices = input.existingInvoicesBySubscriptionId?.[where.subscriptionId] ?? [];
+        return (
+          invoices
+            .filter((invoice) => invoice.createdAt >= where.createdAt.gte)
+            .sort((left, right) => right.createdAt.getTime() - left.createdAt.getTime())[0] ?? null
+        );
+      },
+      create: async ({ data }: { data: Record<string, unknown> }) => {
+        calls.paymentInvoiceCreate.push({ data });
+        return {
+          id: "invoice_created_1",
+          subscriptionId: data.subscriptionId as string,
+          provider: data.provider as string,
+          providerInvoiceId: data.providerInvoiceId as string,
+          status: "pending" as const,
+          currency: data.currency as string,
+          amountCrypto: new Prisma.Decimal(String(data.amountCrypto)),
+          amountUsd: new Prisma.Decimal(String(data.amountUsd)),
+          paymentAddress: data.paymentAddress as string,
+          expiresAt: data.expiresAt as Date,
+          paidAt: null,
+          createdAt: new Date("2026-03-09T12:00:00.000Z"),
+          updatedAt: new Date("2026-03-09T12:00:00.000Z"),
+        };
+      },
+      updateMany: async ({
+        where,
+        data,
+      }: {
+        where: { status: "pending"; expiresAt: { lte: Date } };
+        data: { status: "expired" };
+      }) => {
+        calls.paymentInvoiceExpireUpdateMany.push({ where, data });
+        return { count: input.expirePendingCount ?? 0 };
+      },
+    },
+  };
+
+  const client = {
+    subscription: transaction.subscription,
+    paymentInvoice: transaction.paymentInvoice,
+    $transaction: async <T>(callback: (tx: typeof transaction) => Promise<T>) => callback(transaction),
+  } as unknown as Parameters<typeof createPrismaBillingStore>[0];
+
+  return {
+    client,
+    calls,
+  };
+}
+
+function createRenewalSubscriptionFixture(input: {
+  id: string;
+  currentPeriodStart: Date;
+  currentPeriodEnd: Date;
+}) {
+  return {
+    id: input.id,
+    userId: `user_${input.id}`,
+    planId: "plan_1",
+    status: "active" as const,
+    renewsManually: true,
+    activatedAt: input.currentPeriodStart,
+    currentPeriodStart: input.currentPeriodStart,
+    currentPeriodEnd: input.currentPeriodEnd,
+    canceledAt: null,
+    createdAt: input.currentPeriodStart,
+    updatedAt: input.currentPeriodStart,
+    user: {
+      id: `user_${input.id}`,
+      email: `user_${input.id}@example.com`,
+    },
+    plan: {
+      id: "plan_1",
+      code: "monthly",
+      displayName: "Monthly",
+      monthlyRequestLimit: 100,
+      monthlyPriceUsd: new Prisma.Decimal("29"),
+      billingCurrency: "USDT",
+    },
+  };
+}

packages/db/src/billing-store.ts

@@ -1,4 +1,4 @@
-import type { PaymentProviderAdapter } from "@nproxy/providers";
+import type { PaymentProviderAdapter, ProviderInvoiceStatus } from "@nproxy/providers";
 import {
   Prisma,
   type AdminActorType,
@@ -48,6 +48,38 @@ export interface BillingActorMetadata {
   ref?: string;
 }
 
+export interface ExpirePendingInvoicesResult {
+  expiredCount: number;
+}
+
+export interface RenewalInvoiceNotification {
+  userId: string;
+  email: string;
+  subscriptionId: string;
+  subscriptionCurrentPeriodEnd: Date;
+  invoice: BillingInvoiceRecord;
+}
+
+export interface PendingInvoiceReconciliationRecord extends BillingInvoiceRecord {
+  userId: string;
+  providerInvoiceId: string;
+}
+
+export type InvoiceReconciliationOutcome =
+  | "noop_pending"
+  | "marked_paid"
+  | "marked_expired"
+  | "marked_canceled"
+  | "already_paid"
+  | "already_expired"
+  | "already_canceled"
+  | "ignored_terminal_state";
+
+export interface InvoiceReconciliationResult {
+  outcome: InvoiceReconciliationOutcome;
+  invoice: BillingInvoiceRecord;
+}
+
 export class BillingError extends Error {
   constructor(
     readonly code: "invoice_not_found" | "invoice_transition_not_allowed",
@@ -58,7 +90,7 @@ export class BillingError extends Error {
 }
 
 export function createPrismaBillingStore(database: PrismaClient = defaultPrisma) {
-  return {
+  const store = {
     async listUserInvoices(userId: string): Promise<BillingInvoiceRecord[]> {
       const invoices = await database.paymentInvoice.findMany({
         where: { userId },
@@ -92,180 +124,475 @@ export function createPrismaBillingStore(database: PrismaClient = defaultPrisma)
       paymentProvider: string;
       paymentProviderAdapter: PaymentProviderAdapter;
     }): Promise<BillingInvoiceRecord> {
-      const subscription = await database.subscription.findFirst({
-        where: { userId: input.userId },
-        include: { plan: true },
-        orderBy: [{ currentPeriodEnd: "desc" }, { createdAt: "desc" }],
-      });
+      return database.$transaction(async (transaction) => {
+        const subscription = await transaction.subscription.findFirst({
+          where: { userId: input.userId },
+          include: { plan: true },
+          orderBy: [{ currentPeriodEnd: "desc" }, { createdAt: "desc" }],
+        });
 
-      if (!subscription) {
-        throw new Error("Subscription not found.");
-      }
+        if (!subscription) {
+          throw new Error("Subscription not found.");
+        }
 
-      const existingPending = await database.paymentInvoice.findFirst({
-        where: {
+        await lockSubscriptionForBilling(transaction, subscription.id);
+
+        const existingPending = await transaction.paymentInvoice.findFirst({
+          where: {
+            userId: input.userId,
+            subscriptionId: subscription.id,
+            status: "pending",
+            expiresAt: {
+              gt: new Date(),
+            },
+          },
+          orderBy: { createdAt: "desc" },
+        });
+
+        if (existingPending) {
+          return mapInvoice(existingPending);
+        }
+
+        const amountUsd = subscription.plan.monthlyPriceUsd.toNumber();
+        const currency = subscription.plan.billingCurrency;
+        const amountCrypto = amountUsd;
+        const providerInvoice = await input.paymentProviderAdapter.createInvoice({
           userId: input.userId,
-          subscriptionId: subscription.id,
+          planCode: subscription.plan.code,
+          amountUsd,
+          amountCrypto,
+          currency,
+        });
+
+        const invoice = await transaction.paymentInvoice.create({
+          data: {
+            userId: input.userId,
+            subscriptionId: subscription.id,
+            provider: input.paymentProvider,
+            providerInvoiceId: providerInvoice.providerInvoiceId,
+            status: "pending",
+            currency: providerInvoice.currency,
+            amountCrypto: new Prisma.Decimal(providerInvoice.amountCrypto),
+            amountUsd: new Prisma.Decimal(providerInvoice.amountUsd),
+            paymentAddress: providerInvoice.paymentAddress,
+            expiresAt: providerInvoice.expiresAt,
+          },
+        });
+
+        return mapInvoice(invoice);
+      });
+    },
+
+    async expireElapsedPendingInvoices(
+      now: Date = new Date(),
+    ): Promise<ExpirePendingInvoicesResult> {
+      const result = await database.paymentInvoice.updateMany({
+        where: {
           status: "pending",
           expiresAt: {
-            gt: new Date(),
+            lte: now,
           },
         },
-        orderBy: { createdAt: "desc" },
-      });
-
-      if (existingPending) {
-        return mapInvoice(existingPending);
-      }
-
-      const amountUsd = subscription.plan.monthlyPriceUsd.toNumber();
-      const currency = subscription.plan.billingCurrency;
-      const amountCrypto = amountUsd;
-      const providerInvoice = await input.paymentProviderAdapter.createInvoice({
-        userId: input.userId,
-        planCode: subscription.plan.code,
-        amountUsd,
-        amountCrypto,
-        currency,
-      });
-
-      const invoice = await database.paymentInvoice.create({
         data: {
-          userId: input.userId,
-          subscriptionId: subscription.id,
-          provider: input.paymentProvider,
-          providerInvoiceId: providerInvoice.providerInvoiceId,
-          status: "pending",
-          currency: providerInvoice.currency,
-          amountCrypto: new Prisma.Decimal(providerInvoice.amountCrypto),
-          amountUsd: new Prisma.Decimal(providerInvoice.amountUsd),
-          paymentAddress: providerInvoice.paymentAddress,
-          expiresAt: providerInvoice.expiresAt,
+          status: "expired",
         },
       });
 
-      return mapInvoice(invoice);
+      return {
+        expiredCount: result.count,
+      };
+    },
+
+    async createUpcomingRenewalInvoices(input: {
+      paymentProvider: string;
+      paymentProviderAdapter: PaymentProviderAdapter;
+      renewalLeadTimeHours: number;
+      now?: Date;
+    }): Promise<RenewalInvoiceNotification[]> {
+      const now = input.now ?? new Date();
+      const renewalWindowEnd = addHours(now, input.renewalLeadTimeHours);
+      const subscriptions = await database.subscription.findMany({
+        where: {
+          status: "active",
+          renewsManually: true,
+          currentPeriodEnd: {
+            gt: now,
+            lte: renewalWindowEnd,
+          },
+        },
+        include: {
+          user: true,
+          plan: true,
+        },
+        orderBy: {
+          currentPeriodEnd: "asc",
+        },
+      });
+
+      const notifications: RenewalInvoiceNotification[] = [];
+
+      for (const subscription of subscriptions) {
+        if (!subscription.currentPeriodEnd) {
+          continue;
+        }
+
+        const cycleStart =
+          subscription.currentPeriodStart ?? subscription.activatedAt ?? subscription.createdAt;
+        const subscriptionCurrentPeriodEnd = subscription.currentPeriodEnd;
+        const notification = await database.$transaction(async (transaction) => {
+          await lockSubscriptionForBilling(transaction, subscription.id);
+
+          const existingCycleInvoice = await transaction.paymentInvoice.findFirst({
+            where: {
+              subscriptionId: subscription.id,
+              createdAt: {
+                gte: cycleStart,
+              },
+            },
+            orderBy: {
+              createdAt: "desc",
+            },
+          });
+
+          if (existingCycleInvoice) {
+            return null;
+          }
+
+          const amountUsd = subscription.plan.monthlyPriceUsd.toNumber();
+          const currency = subscription.plan.billingCurrency;
+          const amountCrypto = amountUsd;
+          const providerInvoice = await input.paymentProviderAdapter.createInvoice({
+            userId: subscription.userId,
+            planCode: subscription.plan.code,
+            amountUsd,
+            amountCrypto,
+            currency,
+          });
+
+          const invoice = await transaction.paymentInvoice.create({
+            data: {
+              userId: subscription.userId,
+              subscriptionId: subscription.id,
+              provider: input.paymentProvider,
+              providerInvoiceId: providerInvoice.providerInvoiceId,
+              status: "pending",
+              currency: providerInvoice.currency,
+              amountCrypto: new Prisma.Decimal(providerInvoice.amountCrypto),
+              amountUsd: new Prisma.Decimal(providerInvoice.amountUsd),
+              paymentAddress: providerInvoice.paymentAddress,
+              expiresAt: providerInvoice.expiresAt,
+            },
+          });
+
+          return {
+            userId: subscription.userId,
+            email: subscription.user.email,
+            subscriptionId: subscription.id,
+            subscriptionCurrentPeriodEnd,
+            invoice: mapInvoice(invoice),
+          } satisfies RenewalInvoiceNotification;
+        });
+
+        if (notification) {
+          notifications.push(notification);
+        }
+      }
+
+      return notifications;
     },
 
     async markInvoicePaid(input: {
       invoiceId: string;
       actor?: BillingActorMetadata;
+      paidAt?: Date;
     }): Promise<BillingInvoiceRecord> {
-      return database.$transaction(async (transaction) => {
-        const invoice = await transaction.paymentInvoice.findUnique({
-          where: { id: input.invoiceId },
-          include: {
-            subscription: {
-              include: {
-                plan: true,
-              },
-            },
+      const result = await markInvoicePaidInternal(database, input);
+      return result.invoice;
+    },
+
+    async listPendingInvoicesForReconciliation(
+      limit: number = 100,
+    ): Promise<PendingInvoiceReconciliationRecord[]> {
+      const invoices = await database.paymentInvoice.findMany({
+        where: {
+          status: "pending",
+          providerInvoiceId: {
+            not: null,
           },
-        });
-
-        if (!invoice) {
-          throw new BillingError("invoice_not_found", "Invoice not found.");
-        }
-
-        if (invoice.status === "canceled" || invoice.status === "expired") {
-          throw new BillingError(
-            "invoice_transition_not_allowed",
-            `Invoice in status "${invoice.status}" cannot be marked paid.`,
-          );
-        }
-
-        if (invoice.status === "paid") {
-          await writeInvoicePaidAuditLog(transaction, invoice, input.actor, true);
-          return mapInvoice(invoice);
-        }
-
-        const paidAt = invoice.paidAt ?? new Date();
-        const transitionResult = await transaction.paymentInvoice.updateMany({
-          where: {
-            id: invoice.id,
-            status: "pending",
-          },
-          data: {
-            status: "paid",
-            paidAt,
-          },
-        });
-
-        if (transitionResult.count === 0) {
-          const currentInvoice = await transaction.paymentInvoice.findUnique({
-            where: { id: input.invoiceId },
-            include: {
-              subscription: {
-                include: {
-                  plan: true,
-                },
-              },
-            },
-          });
-
-          if (!currentInvoice) {
-            throw new BillingError("invoice_not_found", "Invoice not found.");
-          }
-
-          if (currentInvoice.status === "paid") {
-            await writeInvoicePaidAuditLog(transaction, currentInvoice, input.actor, true);
-            return mapInvoice(currentInvoice);
-          }
-
-          throw new BillingError(
-            "invoice_transition_not_allowed",
-            `Invoice in status "${currentInvoice.status}" cannot be marked paid.`,
-          );
-        }
-
-        const updatedInvoice = await transaction.paymentInvoice.findUnique({
-          where: { id: invoice.id },
-          include: {
-            subscription: {
-              include: {
-                plan: true,
-              },
-            },
-          },
-        });
-
-        if (!updatedInvoice) {
-          throw new BillingError("invoice_not_found", "Invoice not found.");
-        }
-
-        if (invoice.subscription) {
-          const periodStart = paidAt;
-          const periodEnd = addDays(periodStart, 30);
-
-          await transaction.subscription.update({
-            where: { id: invoice.subscription.id },
-            data: {
-              status: "active",
-              activatedAt: invoice.subscription.activatedAt ?? paidAt,
-              currentPeriodStart: periodStart,
-              currentPeriodEnd: periodEnd,
-              canceledAt: null,
-            },
-          });
-
-          await transaction.usageLedgerEntry.create({
-            data: {
-              userId: invoice.userId,
-              entryType: "cycle_reset",
-              deltaRequests: 0,
-              cycleStartedAt: periodStart,
-              cycleEndsAt: periodEnd,
-              note: `Cycle activated from invoice ${invoice.id}.`,
-            },
-          });
-        }
-
-        await writeInvoicePaidAuditLog(transaction, updatedInvoice, input.actor, false);
-
-        return mapInvoice(updatedInvoice);
+        },
+        orderBy: {
+          createdAt: "asc",
+        },
+        take: limit,
       });
+
+      return invoices
+        .filter(
+          (invoice): invoice is typeof invoice & { providerInvoiceId: string } =>
+            invoice.providerInvoiceId !== null,
+        )
+        .map((invoice) => ({
+          userId: invoice.userId,
+          providerInvoiceId: invoice.providerInvoiceId,
+          ...mapInvoice(invoice),
+        }));
+    },
+
+    async reconcilePendingInvoice(input: {
+      invoiceId: string;
+      providerStatus: ProviderInvoiceStatus;
+      paidAt?: Date;
+      actor?: BillingActorMetadata;
+    }): Promise<InvoiceReconciliationResult> {
+      const currentInvoice = await database.paymentInvoice.findUnique({
+        where: { id: input.invoiceId },
+      });
+
+      if (!currentInvoice) {
+        throw new BillingError("invoice_not_found", "Invoice not found.");
+      }
+
+      if (input.providerStatus === "pending") {
+        return {
+          outcome: "noop_pending",
+          invoice: mapInvoice(currentInvoice),
+        };
+      }
+
+      if (input.providerStatus === "paid") {
+        try {
+          const result = await markInvoicePaidInternal(database, {
+            invoiceId: input.invoiceId,
+            ...(input.actor ? { actor: input.actor } : {}),
+            ...(input.paidAt ? { paidAt: input.paidAt } : {}),
+            allowedSourceStatuses: ["pending", "expired", "canceled"],
+          });
+
+          return {
+            outcome: result.replayed ? "already_paid" : "marked_paid",
+            invoice: result.invoice,
+          };
+        } catch (error) {
+          if (
+            error instanceof BillingError &&
+            error.code === "invoice_transition_not_allowed"
+          ) {
+            const terminalInvoice = await database.paymentInvoice.findUnique({
+              where: { id: input.invoiceId },
+            });
+
+            if (terminalInvoice) {
+              return {
+                outcome: "ignored_terminal_state",
+                invoice: mapInvoice(terminalInvoice),
+              };
+            }
+          }
+
+          throw error;
+        }
+      }
+
+      const targetStatus = input.providerStatus;
+
+      if (currentInvoice.status === "paid") {
+        return {
+          outcome: "ignored_terminal_state",
+          invoice: mapInvoice(currentInvoice),
+        };
+      }
+
+      if (currentInvoice.status === targetStatus) {
+        return {
+          outcome: targetStatus === "expired" ? "already_expired" : "already_canceled",
+          invoice: mapInvoice(currentInvoice),
+        };
+      }
+
+      if (currentInvoice.status !== "pending") {
+        return {
+          outcome: "ignored_terminal_state",
+          invoice: mapInvoice(currentInvoice),
+        };
+      }
+
+      const transitionResult = await database.paymentInvoice.updateMany({
+        where: {
+          id: input.invoiceId,
+          status: "pending",
+        },
+        data: {
+          status: targetStatus,
+        },
+      });
+
+      const updatedInvoice = await database.paymentInvoice.findUnique({
+        where: { id: input.invoiceId },
+      });
+
+      if (!updatedInvoice) {
+        throw new BillingError("invoice_not_found", "Invoice not found.");
+      }
+
+      if (transitionResult.count > 0) {
+        return {
+          outcome: targetStatus === "expired" ? "marked_expired" : "marked_canceled",
+          invoice: mapInvoice(updatedInvoice),
+        };
+      }
+
+      if (updatedInvoice.status === targetStatus) {
+        return {
+          outcome: targetStatus === "expired" ? "already_expired" : "already_canceled",
+          invoice: mapInvoice(updatedInvoice),
+        };
+      }
+
+      return {
+        outcome: "ignored_terminal_state",
+        invoice: mapInvoice(updatedInvoice),
+      };
     },
   };
+
+  return store;
+}
+
+async function markInvoicePaidInternal(
+  database: PrismaClient,
+  input: {
+    invoiceId: string;
+    actor?: BillingActorMetadata;
+    paidAt?: Date;
+    allowedSourceStatuses?: PaymentInvoiceStatus[];
+  },
+): Promise<{ invoice: BillingInvoiceRecord; replayed: boolean }> {
+  return database.$transaction(async (transaction) => {
+    const invoice = await transaction.paymentInvoice.findUnique({
+      where: { id: input.invoiceId },
+      include: {
+        subscription: {
+          include: {
+            plan: true,
+          },
+        },
+      },
+    });
+
+    if (!invoice) {
+      throw new BillingError("invoice_not_found", "Invoice not found.");
+    }
+
+    if (invoice.status === "paid") {
+      await writeInvoicePaidAuditLog(transaction, invoice, input.actor, true);
+      return {
+        invoice: mapInvoice(invoice),
+        replayed: true,
+      };
+    }
+
+    const allowedSourceStatuses = input.allowedSourceStatuses ?? ["pending"];
+
+    if (!allowedSourceStatuses.includes(invoice.status)) {
+      throw new BillingError(
+        "invoice_transition_not_allowed",
+        `Invoice in status "${invoice.status}" cannot be marked paid.`,
+      );
+    }
+
+    const paidAt = invoice.paidAt ?? input.paidAt ?? new Date();
+    const transitionResult = await transaction.paymentInvoice.updateMany({
+      where: {
+        id: invoice.id,
+        status: {
+          in: allowedSourceStatuses,
+        },
+      },
+      data: {
+        status: "paid",
+        paidAt,
+      },
+    });
+
+    if (transitionResult.count === 0) {
+      const currentInvoice = await transaction.paymentInvoice.findUnique({
+        where: { id: input.invoiceId },
+        include: {
+          subscription: {
+            include: {
+              plan: true,
+            },
+          },
+        },
+      });
+
+      if (!currentInvoice) {
+        throw new BillingError("invoice_not_found", "Invoice not found.");
+      }
+
+      if (currentInvoice.status === "paid") {
+        await writeInvoicePaidAuditLog(transaction, currentInvoice, input.actor, true);
+        return {
+          invoice: mapInvoice(currentInvoice),
+          replayed: true,
+        };
+      }
+
+      throw new BillingError(
+        "invoice_transition_not_allowed",
+        `Invoice in status "${currentInvoice.status}" cannot be marked paid.`,
+      );
+    }
+
+    const updatedInvoice = await transaction.paymentInvoice.findUnique({
+      where: { id: invoice.id },
+      include: {
+        subscription: {
+          include: {
+            plan: true,
+          },
+        },
+      },
+    });
+
+    if (!updatedInvoice) {
+      throw new BillingError("invoice_not_found", "Invoice not found.");
+    }
+
+    if (invoice.subscription) {
+      const periodStart = paidAt;
+      const periodEnd = addDays(periodStart, 30);
+
+      await transaction.subscription.update({
+        where: { id: invoice.subscription.id },
+        data: {
+          status: "active",
+          activatedAt: invoice.subscription.activatedAt ?? paidAt,
+          currentPeriodStart: periodStart,
+          currentPeriodEnd: periodEnd,
+          canceledAt: null,
+        },
+      });
+
+      await transaction.usageLedgerEntry.create({
+        data: {
+          userId: invoice.userId,
+          entryType: "cycle_reset",
+          deltaRequests: 0,
+          cycleStartedAt: periodStart,
+          cycleEndsAt: periodEnd,
+          note: `Cycle activated from invoice ${invoice.id}.`,
+        },
+      });
+    }
+
+    await writeInvoicePaidAuditLog(transaction, updatedInvoice, input.actor, false);
+
+    return {
+      invoice: mapInvoice(updatedInvoice),
+      replayed: false,
+    };
+  });
 }
 
 async function writeInvoicePaidAuditLog(
@@ -376,3 +703,14 @@ function mapSubscription(subscription: {
 function addDays(value: Date, days: number): Date {
   return new Date(value.getTime() + days * 24 * 60 * 60 * 1000);
 }
+
+function addHours(value: Date, hours: number): Date {
+  return new Date(value.getTime() + hours * 60 * 60 * 1000);
+}
+
+async function lockSubscriptionForBilling(
+  database: Pick<Prisma.TransactionClient, "$queryRaw">,
+  subscriptionId: string,
+): Promise<void> {
+  await database.$queryRaw`SELECT 1 FROM "Subscription" WHERE id = ${subscriptionId} FOR UPDATE`;
+}