feat(billing): add refundCharge service with deterministic idempotency key

Promote billing.refund.service.js from trawl to devkit (Task 3a of billing-residual-cleanup plan).
Wraps stripe.refunds.create with a deterministic idempotency key (refund_{chargeId}_{amount|full})
so retries on network failures never create duplicate refunds. Ledger debit happens via
the charge.refunded webhook (single source of truth) — this service only initiates the
Stripe refund. Full + partial refund, reason passthrough, empty chargeId and non-positive
amount guards all covered by 6 unit test cases.

Author: PierreBrisorgueil

modules/billing/services/billing.refund.service.js

@@ -0,0 +1,49 @@
+/**
+ * Module dependencies
+ */
+import getStripe from '../lib/stripe.js';
+
+/**
+ * @function refundCharge
+ * @description Initiate a Stripe refund for a given charge.
+ *              Wraps stripe.refunds.create with a deterministic idempotency key so
+ *              retries on network failures never create duplicate refunds.
+ *              The actual ledger debit happens via the `charge.refunded` webhook
+ *              (single source of truth) — this service ONLY initiates the Stripe refund.
+ *
+ * @param {string} stripeChargeId - Stripe charge ID (ch_xxx). Must be non-empty.
+ * @param {number|undefined} [amountCents] - Amount to refund in cents. Omit for full refund. Must be > 0 if provided.
+ * @param {Object} [options={}] - Optional Stripe refund options.
+ * @param {string} [options.reason] - Optional Stripe refund reason.
+ * @returns {Promise<Object>} The Stripe refund object.
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js service, not Qwik
+const refundCharge = async (stripeChargeId, amountCents, { reason } = {}) => {
+  if (typeof stripeChargeId !== 'string' || stripeChargeId.trim() === '') {
+    throw new Error('invalid argument: stripeChargeId must be a non-empty string');
+  }
+  if (amountCents !== undefined) {
+    if (!Number.isInteger(amountCents) || amountCents <= 0) {
+      throw new Error('invalid argument: amountCents must be a positive integer');
+    }
+  }
+
+  const stripe = getStripe();
+  if (!stripe) throw new Error('Stripe is not configured');
+
+  const idempotencyKey = `refund_${stripeChargeId}_${amountCents ?? 'full'}`;
+
+  const params = {
+    charge: stripeChargeId,
+    reason: reason || 'requested_by_customer',
+  };
+  if (amountCents !== undefined) {
+    params.amount = amountCents;
+  }
+
+  return stripe.refunds.create(params, { idempotencyKey });
+};
+
+export default {
+  refundCharge,
+};

modules/billing/tests/billing.refund.service.refundCharge.unit.tests.js

@@ -0,0 +1,61 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+
+describe('billing.refund.service — refundCharge:', () => {
+  let RefundService;
+  let mockStripe;
+  let mockRefundsCreate;
+
+  beforeEach(async () => {
+    jest.resetModules();
+    mockRefundsCreate = jest.fn().mockResolvedValue({ id: 're_test_123', status: 'succeeded' });
+    mockStripe = { refunds: { create: mockRefundsCreate } };
+    jest.unstable_mockModule('../lib/stripe.js', () => ({
+      default: jest.fn().mockReturnValue(mockStripe),
+    }));
+    ({ default: RefundService } = await import('../services/billing.refund.service.js'));
+  });
+
+  test('initiates a full refund when amountCents omitted', async () => {
+    const result = await RefundService.refundCharge('ch_test_123');
+    expect(mockRefundsCreate).toHaveBeenCalledTimes(1);
+    const callArgs = mockRefundsCreate.mock.calls[0][0];
+    expect(callArgs.charge).toBe('ch_test_123');
+    expect(callArgs.amount).toBeUndefined();
+    expect(result.id).toBe('re_test_123');
+  });
+
+  test('uses partial amount when amountCents provided', async () => {
+    await RefundService.refundCharge('ch_test_456', 5000);
+    expect(mockRefundsCreate).toHaveBeenCalledWith(expect.objectContaining({
+      charge: 'ch_test_456',
+      amount: 5000,
+    }), expect.any(Object));
+  });
+
+  test('passes deterministic idempotency key derived from charge+amount', async () => {
+    await RefundService.refundCharge('ch_idem_test', 1000);
+    const idemArg = mockRefundsCreate.mock.calls[0][1];
+    expect(idemArg).toBeDefined();
+    expect(idemArg.idempotencyKey).toBeDefined();
+    // Same charge+amount → same key (deterministic)
+    await RefundService.refundCharge('ch_idem_test', 1000);
+    const idemArg2 = mockRefundsCreate.mock.calls[1][1];
+    expect(idemArg2.idempotencyKey).toBe(idemArg.idempotencyKey);
+  });
+
+  test('passes reason when provided', async () => {
+    await RefundService.refundCharge('ch_test', undefined, { reason: 'requested_by_customer' });
+    expect(mockRefundsCreate).toHaveBeenCalledWith(expect.objectContaining({
+      reason: 'requested_by_customer',
+    }), expect.any(Object));
+  });
+
+  test('throws when stripeChargeId is empty', async () => {
+    await expect(RefundService.refundCharge('')).rejects.toThrow();
+  });
+
+  test('throws when amountCents is 0 or negative', async () => {
+    await expect(RefundService.refundCharge('ch_x', 0)).rejects.toThrow();
+    await expect(RefundService.refundCharge('ch_x', -100)).rejects.toThrow();
+  });
+});