`@withpotter/subscriptions` — module reference

HTTP routes this module mounts, plus its internal use-cases, entities, and repositories. The exhaustive request/response contract is the engine’s OpenAPI document at /docs; the layered structure below follows the package internal architecture.

HTTP routes

MerchantSubscriptionsController `/merchant-subscriptions`

Method	Path	Auth	Description
`GET`	`/merchant-subscriptions/plans`	—	List plans
`GET`	`/merchant-subscriptions/plans/:id`	—	Get plan
`GET`	`/merchant-subscriptions/plans/active`	—	Get active plans
`GET`	`/merchant-subscriptions/subscriptions`	—	List subscriptions
`GET`	`/merchant-subscriptions/subscriptions/:id`	—	Get subscription
`GET`	`/merchant-subscriptions/subscriptions/attention`	—	Get needing attention
`GET`	`/merchant-subscriptions/subscriptions/customer/:customerId`	—	Get by customer
`GET`	`/merchant-subscriptions/subscriptions/stats`	—	Get stats
`POST`	`/merchant-subscriptions/plans`	Yes	Create new plan
`POST`	`/merchant-subscriptions/plans/:id/activate`	Yes	Activate plan
`POST`	`/merchant-subscriptions/plans/:id/deactivate`	Yes	Deactivate plan
`POST`	`/merchant-subscriptions/subscriptions`	—	Create new subscription
`POST`	`/merchant-subscriptions/subscriptions/:id/cancel`	—	Cancel subscription
`POST`	`/merchant-subscriptions/subscriptions/:id/pause`	—	Pause renewal
`POST`	`/merchant-subscriptions/subscriptions/:id/resume`	—	Resume renewal
`PUT`	`/merchant-subscriptions/plans/:id`	Yes	Update plan
`DELETE`	`/merchant-subscriptions/plans/:id`	Yes	Archive plan

Internals

Use-cases

Application operations. Each is a single-purpose class with one execute() method.

Use-case	Signature
`ActivatePlanUseCase`	`execute(tenantId: string, planId: string)`
`ArchivePlanUseCase`	`execute(tenantId: string, planId: string)`
`CancelSubscriptionUseCase`	`execute(tenantId: string, subscriptionId: string)`
`CreatePlanUseCase`	`execute(tenantId: string, dto: CreatePlanDto)`
`CreateSubscriptionUseCase`	`execute(tenantId: string, dto: CreateSubscriptionDto)`
`DeactivatePlanUseCase`	`execute(tenantId: string, planId: string)`
`GetActivePlansUseCase`	`execute(tenantId: string)`
`GetCustomerSubscriptionsUseCase`	`execute(tenantId: string, customerId: string)`
`GetPlanUseCase`	`execute(tenantId: string, planId: string)`
`GetSubscriptionsNeedingAttentionUseCase`	`execute(tenantId: string)`
`GetSubscriptionStatsUseCase`	`execute(tenantId: string)`
`GetSubscriptionUseCase`	`execute(tenantId: string, subscriptionId: string)`
`ListPlansUseCase`	`execute(tenantId: string, query: ListPlansQueryDto)`
`ListSubscriptionsUseCase`	`execute(tenantId: string, query: ListSubscriptionsQueryDto)`
`PauseSubscriptionRenewalUseCase`	`execute(tenantId: string, subscriptionId: string)`
`ResumeSubscriptionRenewalUseCase`	`execute(tenantId: string, subscriptionId: string)`
`UpdatePlanUseCase`	`execute(tenantId: string, planId: string, dto: UpdatePlanDto)`

Entities

Sequelize models owned by this module.

`CustomerSubscription` — table `customer_subscriptions`

Field	Type
`id`	`string`
`tenantId`	`string`
`tenant`	`Tenant`
`planId`	`string`
`plan`	`MerchantPlan`
`customerId`	`string`
`customer`	`Member`
`customerEmail`	`string`
`paystackSubscriptionCode`	`string \| null`
`paystackPlanCode`	`string \| null`
`paystackEmailToken`	`string \| null`
`authorizationCode`	`string \| null`
`status`	`CustomerSubscriptionStatus`
`amount`	`number`
`currency`	`string`
`currentPeriodStart`	`Date \| null`
`currentPeriodEnd`	`Date \| null`
`nextPaymentDate`	`Date \| null`
`cancelledAt`	`Date \| null`
`paymentsCount`	`number`
`metadata`	`Record<string, unknown>`
`createdAt`	`Date`
`updatedAt`	`Date`

`CustomerSubscriptionLineItem` — table `customer_subscription_line_items`

Field	Type
`id`	`string`
`customerSubscriptionId`	`string`
`customerSubscription`	`CustomerSubscription`
`contentId`	`string \| null`
`content`	`Content`
`title`	`string`
`variant`	`{ id: string`
`quantity`	`number`
`unitPriceSnapshot`	`number`
`currency`	`string`
`createdAt`	`Date`
`updatedAt`	`Date`

Repositories

Data-access classes wrapping the entities.

`CustomerSubscriptionLineItemRepository`

bulkCreate · listForSubscription

`CustomerSubscriptionRepository`

create · findById · findByPaystackSubscriptionCode · findByCustomerAndPlan · findActiveByCustomer · listByTenant · listByPlan · getStats · update · updateByPaystackCode · incrementPaymentsCount · cancel · getSubscriptionsNeedingAttention

Generated from the module’s source. Routes are relative to the engine root (default http://localhost:3001). For full request/response schemas use the live OpenAPI document.

shipping team

@withpotter/subscriptions — module reference