@startsimpli/billing 0.4.10 → 0.4.14

package/src/mock/__tests__/mock-backend.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Mock billing backend (parallel to @startsimpli/auth's createMockAuthBackend):
+ * a backend-agnostic BillingBackend impl seeded with demo accounts. Used by
+ * apps without a live Stripe/Apple/Google integration (e.g. the MCR demo).
+ */
+import { describe, it, expect } from 'vitest';
+import { createMockBillingBackend } from '../mock-backend';
+import type { SubscriptionInfo, PaymentMethod, Invoice, PayoutRequest } from '../../types';
+
+const offer = {
+  id: 'pro',
+  name: 'MCR Pro',
+  slug: 'pro',
+  unitPrice: '10.00',
+  currency: 'USD',
+  pricingModel: 'flat' as const,
+  intervalUnit: 'month' as const,
+  intervalCount: 1,
+  intervalDisplay: 'monthly',
+  isRecurring: true,
+  isFree: false,
+  features: [],
+  isActive: true,
+  isFeatured: true,
+  trialDays: 0,
+  sortOrder: 1,
+  ctaText: 'Subscribe',
+};
+
+const sub: SubscriptionInfo = {
+  id: 'sub_1',
+  offer,
+  status: 'active',
+  currentPeriodStart: '2026-05-01T00:00:00Z',
+  currentPeriodEnd: '2026-06-01T00:00:00Z',
+  cancelAtPeriodEnd: false,
+  trialEnd: null,
+};
+
+const pm: PaymentMethod = { brand: 'visa', last4: '4242' };
+
+const invoice: Invoice = {
+  id: 'inv_1',
+  date: '2026-05-01T00:00:00Z',
+  amount: '10.00',
+  currency: 'USD',
+  status: 'paid',
+  description: 'MCR Pro — May 2026',
+};
+
+const payout: PayoutRequest = {
+  id: 'po_1',
+  requestedAt: '2026-04-15T00:00:00Z',
+  paidAt: '2026-04-18T00:00:00Z',
+  amount: '5000.00',
+  currency: 'USD',
+  status: 'paid',
+};
+
+const seedAccount = {
+  id: 'amr',
+  subscription: sub,
+  paymentMethod: pm,
+  invoices: [invoice],
+  payouts: [payout],
+};
+
+describe('createMockBillingBackend', () => {
+  it('returns the seeded subscription for a known account', async () => {
+    const b = createMockBillingBackend({ accounts: [seedAccount] });
+    const s = await b.getSubscription('amr');
+    expect(s?.status).toBe('active');
+    expect(s?.offer.unitPrice).toBe('10.00');
+  });
+
+  it('returns null for an unknown account', async () => {
+    const b = createMockBillingBackend({ accounts: [seedAccount] });
+    expect(await b.getSubscription('ghost')).toBeNull();
+  });
+
+  it('returns the seeded payment method', async () => {
+    const b = createMockBillingBackend({ accounts: [seedAccount] });
+    expect(await b.getPaymentMethod('amr')).toEqual(pm);
+  });
+
+  it('returns the seeded invoices', async () => {
+    const b = createMockBillingBackend({ accounts: [seedAccount] });
+    const invoices = await b.listInvoices('amr');
+    expect(invoices).toHaveLength(1);
+    expect(invoices[0].status).toBe('paid');
+  });
+
+  it('returns the seeded payouts', async () => {
+    const b = createMockBillingBackend({ accounts: [seedAccount] });
+    expect((await b.listPayouts('amr'))).toHaveLength(1);
+  });
+
+  it('requestPayout appends a new "requested" payout and listPayouts shows it', async () => {
+    const b = createMockBillingBackend({ accounts: [seedAccount] });
+    const before = (await b.listPayouts('amr')).length;
+    const created = await b.requestPayout('amr', '1234.56', 'USD');
+    expect(created.status).toBe('requested');
+    expect(created.amount).toBe('1234.56');
+    expect(created.paidAt).toBeNull();
+    const after = await b.listPayouts('amr');
+    expect(after).toHaveLength(before + 1);
+    expect(after.find((p) => p.id === created.id)).toBeTruthy();
+  });
+
+  it('requestPayout for an unknown account throws', async () => {
+    const b = createMockBillingBackend({ accounts: [seedAccount] });
+    await expect(b.requestPayout('ghost', '10', 'USD')).rejects.toThrow(/no account/i);
+  });
+
+  it('lists empty arrays for accounts with no seeded data', async () => {
+    const b = createMockBillingBackend({ accounts: [{ id: 'fresh', subscription: null }] });
+    expect(await b.getSubscription('fresh')).toBeNull();
+    expect(await b.getPaymentMethod('fresh')).toBeNull();
+    expect(await b.listInvoices('fresh')).toEqual([]);
+    expect(await b.listPayouts('fresh')).toEqual([]);
+  });
+
+  it('upsertAccount adds an account at runtime', async () => {
+    const b = createMockBillingBackend({ accounts: [] });
+    b.upsertAccount({ id: 'late', subscription: sub });
+    expect((await b.getSubscription('late'))?.status).toBe('active');
+  });
+});

package/src/mock/backend.ts

@@ -0,0 +1,25 @@
+/**
+ * Backend-agnostic billing contract.
+ *
+ * The Stripe/Apple/Google adapters that ship with this package are web-bound;
+ * a BillingBackend lets apps (incl. backendless demos, React Native apps,
+ * Storybooks) drive Plan/Subscription/Invoice/Payout state without those.
+ * Mirrors the AuthBackend pattern in @startsimpli/auth.
+ *
+ * The method set is exactly what a "billing surface" needs — nothing here is
+ * Stripe-specific.
+ */
+import type { Invoice, PaymentMethod, PayoutRequest, SubscriptionInfo } from '../types';
+
+export interface BillingBackend {
+  /** Current subscription for the account, or null if none. */
+  getSubscription(accountId: string): Promise<SubscriptionInfo | null>;
+  /** Payment method on file, or null. */
+  getPaymentMethod(accountId: string): Promise<PaymentMethod | null>;
+  /** Invoices in reverse chronological order. */
+  listInvoices(accountId: string): Promise<Invoice[]>;
+  /** Past payout requests (most recent first). */
+  listPayouts(accountId: string): Promise<PayoutRequest[]>;
+  /** Open a new payout. Implementations may queue, settle async, etc. */
+  requestPayout(accountId: string, amount: string, currency: string): Promise<PayoutRequest>;
+}

package/src/mock/index.ts

@@ -0,0 +1,7 @@
+export type { BillingBackend } from './backend';
+export {
+  createMockBillingBackend,
+  type MockBillingBackend,
+  type MockBillingBackendOptions,
+  type MockBillingAccount,
+} from './mock-backend';

package/src/mock/mock-backend.ts

@@ -0,0 +1,103 @@
+/**
+ * In-memory BillingBackend for backendless apps (demos, offline-first,
+ * Storybook). Implements the full BillingBackend contract plus mock-only
+ * helpers (upsertAccount, addInvoice). No network, no Stripe.
+ */
+import type {
+  Invoice,
+  PaymentMethod,
+  PayoutRequest,
+  SubscriptionInfo,
+} from '../types';
+import type { BillingBackend } from './backend';
+
+export interface MockBillingAccount {
+  id: string;
+  subscription: SubscriptionInfo | null;
+  paymentMethod?: PaymentMethod;
+  invoices?: Invoice[];
+  payouts?: PayoutRequest[];
+}
+
+export interface MockBillingBackendOptions {
+  accounts: MockBillingAccount[];
+  /** Injectable clock (tests). Default Date.now. */
+  now?: () => number;
+}
+
+export interface MockBillingBackend extends BillingBackend {
+  /** Add or replace an account at runtime. */
+  upsertAccount(account: MockBillingAccount): void;
+  /** Append an invoice to an account's history. */
+  addInvoice(accountId: string, invoice: Invoice): void;
+}
+
+let _seq = 0;
+function genId(prefix: string): string {
+  _seq += 1;
+  return `${prefix}_${Date.now().toString(36)}_${_seq}`;
+}
+
+export function createMockBillingBackend(
+  options: MockBillingBackendOptions
+): MockBillingBackend {
+  const now = options.now ?? (() => Date.now());
+
+  interface Record_ {
+    subscription: SubscriptionInfo | null;
+    paymentMethod: PaymentMethod | null;
+    invoices: Invoice[];
+    payouts: PayoutRequest[];
+  }
+  const accounts = new Map<string, Record_>();
+  const seed = (a: MockBillingAccount) => {
+    accounts.set(a.id, {
+      subscription: a.subscription,
+      paymentMethod: a.paymentMethod ?? null,
+      invoices: [...(a.invoices ?? [])],
+      payouts: [...(a.payouts ?? [])],
+    });
+  };
+  options.accounts.forEach(seed);
+
+  function require_(id: string): Record_ {
+    const a = accounts.get(id);
+    if (!a) throw new Error(`No account: ${id}`);
+    return a;
+  }
+
+  return {
+    async getSubscription(id) {
+      return accounts.get(id)?.subscription ?? null;
+    },
+    async getPaymentMethod(id) {
+      return accounts.get(id)?.paymentMethod ?? null;
+    },
+    async listInvoices(id) {
+      return accounts.get(id)?.invoices ?? [];
+    },
+    async listPayouts(id) {
+      return accounts.get(id)?.payouts ?? [];
+    },
+    async requestPayout(id, amount, currency) {
+      const account = require_(id);
+      const payout: PayoutRequest = {
+        id: genId('po'),
+        requestedAt: new Date(now()).toISOString(),
+        paidAt: null,
+        amount,
+        currency,
+        status: 'requested',
+      };
+      account.payouts = [payout, ...account.payouts];
+      return payout;
+    },
+    upsertAccount(account) {
+      seed(account);
+    },
+    addInvoice(id, invoice) {
+      const account = require_(id);
+      account.invoices = [invoice, ...account.invoices];
+    },
+  };
+}

package/src/types/index.ts

@@ -34,6 +34,12 @@ export interface OfferFeature {
   tooltip?: string | null;
 }
 
+/** Per-product usage payload from GET /api/v1/billing/usage/<product>/.
+ * Keys match OfferFeature.key; limit -1 == unlimited; null limit == hide bar.
+ * Empty {} is a valid response (no adapter / no sub / errors) — UI must
+ * tolerate it. startsim-h14. */
+export type UsageMap = Record<string, { used: number; limit: number | null }>;
+
 export interface BillingProduct {
   id: string;
   slug: string;
@@ -59,11 +65,17 @@ export interface PortalResult {
 export interface SubscriptionInfo {
   id: string;
   offer: ProductOffer;
-  status: "active" | "trialing" | "past_due" | "cancelled" | "incomplete" | "incomplete_expired" | "unpaid";
+  status: "active" | "trialing" | "past_due" | "cancelled" | "incomplete" | "incomplete_expired" | "unpaid" | "trial_expired";
   currentPeriodStart: string | null;
   currentPeriodEnd: string | null;
   cancelAtPeriodEnd: boolean;
   trialEnd: string | null;
+  /** True when the viewing user is the OWNER of the team the subscription
+   * belongs to. Drives the UI's read-only billing view for non-owner
+   * team members ('Owner manages billing'). startsim-wo9. */
+  viewerIsOwner?: boolean;
+  /** Email of the team owner so non-owners can be told who to ask. */
+  ownerEmail?: string | null;
 }
 
 export interface PaymentMethod {
@@ -87,6 +99,37 @@ export interface CachedSubscriptionState {
   paymentMethod: PaymentMethod | null;
 }
 
+export type InvoiceStatus = 'paid' | 'open' | 'past_due' | 'void';
+
+export interface Invoice {
+  id: string;
+  /** ISO timestamp of when the invoice was issued. */
+  date: string;
+  /** Decimal as a string (mirrors DRF's Money serialization). */
+  amount: string;
+  currency: string;
+  status: InvoiceStatus;
+  description: string;
+  /** Optional link to a hosted receipt / PDF. */
+  receiptUrl?: string;
+}
+
+export type PayoutStatus = 'requested' | 'processing' | 'paid' | 'failed';
+
+/** A request to disburse funds to the account holder (e.g. an artist's
+ *  collected royalties). Generic enough for any payout flow. */
+export interface PayoutRequest {
+  id: string;
+  /** ISO timestamp of when the payout was requested. */
+  requestedAt: string;
+  /** ISO timestamp of when the payout cleared, or null while pending. */
+  paidAt: string | null;
+  /** Decimal as a string. */
+  amount: string;
+  currency: string;
+  status: PayoutStatus;
+}
+
 export interface BillingConfig {
   /**
    * Base path for billing API calls.

package/src/utils/api.ts

@@ -10,6 +10,7 @@ import type {
   FreeSubscriptionResult,
   PortalResult,
   SubscriptionInfo,
+  UsageMap,
 } from "../types";
 
 export class BillingApiClient {
@@ -118,6 +119,21 @@ export class BillingApiClient {
     return resp.json();
   }
 
+  /** Per-product usage map for the current user/team — {feature_key:
+   * {used, limit}}. Graceful: 200 {} when no adapter / no sub / errors.
+   * startsim-h14 — feeds CurrentPlanCard progress bars.
+   */
+  async getUsage(slug: string): Promise<UsageMap> {
+    const url = `${this.config.apiBaseUrl}/billing/usage/${slug}/`;
+    const resp = await this.fetcher(url, { headers: this.headers });
+    if (!resp.ok) {
+      // Treat any non-2xx as "no data" — usage failures must not block the
+      // page. UI hides the bars when the map is empty.
+      return {};
+    }
+    return (await resp.json()) as UsageMap;
+  }
+
   /** Get current user's subscription. */
   async getSubscription(): Promise<SubscriptionInfo | null> {
     const url = `${this.config.apiBaseUrl}/billing/subscription/current/`;