`@withpotter/membership` — 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

Memberships `/memberships`

Method	Path	Auth	Description
`GET`	`/memberships/member/:memberId`	Yes	Get active subscription for a member
`GET`	`/memberships/stats`	Yes	Get membership statistics
`GET`	`/memberships/subscriptions`	Yes	Get all subscriptions
`GET`	`/memberships/subscriptions/:id`	Yes	Get a subscription by ID
`GET`	`/memberships/tiers`	—	Get all membership tiers
`GET`	`/memberships/tiers/:id`	—	Get a membership tier by ID
`POST`	`/memberships/subscriptions`	Yes	Create a new subscription
`POST`	`/memberships/subscriptions/:id/cancel`	Yes	Cancel a subscription
`POST`	`/memberships/tiers`	Yes	Create a new membership tier
`PUT`	`/memberships/subscriptions/:id`	Yes	Update a subscription
`PUT`	`/memberships/tiers/:id`	Yes	Update a membership tier
`DELETE`	`/memberships/tiers/:id`	Yes	Delete a membership tier

Internals

Use-cases

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

Use-case	Signature
`CancelSubscriptionUseCase`	`execute(tenantId: string, subscriptionId: string, reason?: string)`
`CreateMembershipTierUseCase`	`execute(tenantId: string, dto: CreateMembershipTierDto)`
`CreateSubscriptionUseCase`	`execute(tenantId: string, dto: CreateSubscriptionDto)`
`DeleteMembershipTierUseCase`	`execute(tenantId: string, tierId: string)`
`GetMembershipStatsUseCase`	`execute(tenantId: string)`
`GetMembershipTierUseCase`	`execute(tenantId: string, tierId: string)`
`GetMemberSubscriptionUseCase`	`execute(tenantId: string, memberId: string)`
`GetSubscriptionUseCase`	`execute(tenantId: string, subscriptionId: string)`
`ListMembershipTiersUseCase`	`execute(tenantId: string, includeInactive?: boolean)`
`ListSubscriptionsUseCase`	`execute(tenantId: string, query: ListSubscriptionsQuery)`
`UpdateMembershipTierUseCase`	`execute(tenantId: string, tierId: string, dto: UpdateMembershipTierDto)`
`UpdateSubscriptionUseCase`	`execute(tenantId: string, subscriptionId: string, dto: UpdateSubscriptionDto)`

Entities

Sequelize models owned by this module.

`MembershipTier` — table `membership_tiers`

Field	Type
`id`	`string`
`tenantId`	`string`
`tenant`	`Tenant`
`name`	`string`
`slug`	`string`
`description`	`string \| null`
`icon`	`string \| null`
`color`	`string \| null`
`monthlyPrice`	`number`
`yearlyPrice`	`number \| null`
`currency`	`string`
`benefits`	`MembershipBenefit[]`
`discountPercentage`	`number \| null`
`freeServicesPerMonth`	`number \| null`
`priorityBooking`	`boolean`
`vipAccess`	`boolean`
`customBenefits`	`Record<string, unknown> \| null`
`linkedPlanId`	`string \| null`
`linkedPlan`	`MerchantPlan`
`status`	`MembershipTierStatus`
`sortOrder`	`number`
`featured`	`boolean`
`createdAt`	`Date`
`updatedAt`	`Date`
`id`	`string`
`tenantId`	`string`
`memberId`	`string`
`tierId`	`string`
`tier`	`MembershipTier`
`billingInterval`	`BillingInterval`
`price`	`number`
`currency`	`string`
`status`	`SubscriptionStatus`
`startDate`	`Date`
`endDate`	`Date \| null`
`nextBillingDate`	`Date \| null`
`cancelledAt`	`Date \| null`
`cancellationReason`	`string \| null`
`paymentProvider`	`string \| null`
`externalSubscriptionId`	`string \| null`
`freeServicesUsed`	`number`
`usageResetDate`	`Date \| null`
`createdAt`	`Date`
`updatedAt`	`Date`

Repositories

Data-access classes wrapping the entities.

`MembershipRepository`

createTier · findTierById · findTierBySlug · findAllTiers · updateTier · deleteTier · createSubscription · findSubscriptionById · findSubscriptionsByMember · findActiveSubscription · findAllSubscriptions · updateSubscription · cancelSubscription · renewSubscription · countActiveSubscriptionsForTier · findSubscriptionByExternalId · findTierByLinkedPlanId · getStats · getSubscriberCountByTier

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.

members onboarding

@withpotter/membership — module reference