Add Community Subscription Billing to Community Portal

[noce-nick]

Summary

Add subscription billing functionality to OCOM, allowing community owners to select a subscription plan, configure or update a payment instrument, process recurring subscription charges, and view billing history.

This task may be developed in parallel with the Cellix payment infrastructure task. Application functionality should be implemented independently where possible, with payment operations wired through @ocom/service-payment once available.

Subscription Plans

Initially support two subscription tiers:

Plan	Price
Pro	$10/member/month
Enterprise	$20/member/month

Pro should be the default subscription tier.

Community Configuration

Add a CommunityConfig collection containing effective-dated configuration for each subscription tier.

Proposed shape:

CommunityConfig {
  _id: ObjectId;
  subscriptionTier: "pro" | "enterprise";

  subscription: {
    pricePerMember: number; // cents
    currency: string;       // USD
  };

  limits: {
    maxMembers: number;
    maxAdmins: number;
  };

  effectiveDate: Date;
}

Initial limits should be configured as:

• Pro: 50 members / 2 admins
• Enterprise: 200 members / 10 admins

The limits are included in the configuration model for future use but do not need to be enforced as part of this task.

Configuration records should be added rather than modified. At runtime, resolve the applicable configuration by finding the record matching the Community's selected subscriptionTier with the latest effectiveDate that has taken effect.

Community Finance

Extend the Community schema with a root-level finance structure:

finance: {
  subscriptionTier: "pro" | "enterprise";
  paymentInstrumentId?: string;
  transactions: CommunityTransaction[];
}

subscriptionTier should be a stable application-defined enum rather than a reference to a specific CommunityConfig record.

Community Transactions

Store billing transactions as subdocuments within finance.transactions.

CommunityTransaction {
  _id: ObjectId;
  amount: number;

  transactionReference: {
    vendor?: string;
    isSuccess?: boolean;
    lastRequestedAt?: Date;
    referenceId?: string;
    transactionId?: string;
    reconciliationId?: string;
    completedAt?: Date;
    errorOccurredAt?: Date;
    errorCode?: string;
    errorMessage?: string;
  };
}

transactionReference should capture the normalized transaction information returned through @ocom/service-payment so OCOM can retain billing history and reconcile payment activity without coupling the Community model to a specific vendor.

Subscription Billing

Community owners must be able to:

• Select a subscription tier during or immediately following community onboarding.
• Configure a payment instrument for the community.
• Update the community's payment instrument.
• View previous billing transactions from the community admin side.
• Process recurring subscription charges through @ocom/service-payment.

The subscription amount should be dynamically calculated using the currently applicable CommunityConfig:

current member count × price per member

OCOM owns this calculation and supplies the resulting amount to the payment service.

Payment operations should use @ocom/service-payment, initially backed by @cellix/service-payment-mock.

UI / API

Add the necessary Community Portal admin-side functionality for a community owner to:

• View their current subscription tier and pricing.
• Select/change their subscription tier.
• Configure or update their payment instrument.
• View billing history.

Add the required GraphQL queries/mutations and application services to support these workflows.

Testing

Add/update tests covering:

• Subscription tier selection and changes.
• Resolution of the latest effective CommunityConfig.
• Dynamic subscription amount calculation.
• Payment instrument setup and updates.
• Subscription payment processing.
• CommunityTransaction persistence.
• Billing history retrieval.
• Relevant authorization and invalid-operation scenarios.

Update the OCOM verification suites where applicable.

Out of Scope

• Enforcement of member or admin limits from CommunityConfig.
• Property limits or property-based pricing.
• Additional charges for extra administrators.
• Tech Admin management of subscription configurations.
• Real payment vendor integration.
• Proration or other advanced subscription billing behavior.

Follow-up tasks can use the same CommunityConfig model to enforce membership limits and other subscription-tier behavior.