@vouchington/memberships 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @vouchington/memberships
+
+Dependency-free, schema-less primitives for membership lifecycles, SKU grouping, benefit catalogs,
+and payment-provider adapters.
+
+```ts
+import {
+  buildMembershipBenefitCatalog,
+  transitionMembershipLifecycle,
+} from '@vouchington/memberships'
+
+const catalog = buildMembershipBenefitCatalog(
+  {
+    version: 1,
+    plans: ['basic', 'premium'] as const,
+    groups: [
+      {
+        id: 'usage',
+        benefits: [
+          {
+            id: 'requests',
+            placements: ['comparison'] as const,
+            values: { basic: 10, premium: 100 },
+          },
+        ],
+      },
+    ],
+  },
+  new Set(['requests'] as const),
+)
+```
+
+The package fixes only the lifecycle vocabulary: `active`, `past_due`, `paused`, `cancelled`, and
+`expired`. It does not define database tables, products, entitlements, authorization, payment
+processors, hosted portals, or refund persistence. Applications own their plans, IDs, money policy,
+provider-specific adapters, webhook authentication, and access enforcement.
+
+Provider capabilities are structural interfaces. An application supplies its own adapter context and
+request/result types for subscription creation, updates, cancellation, webhook normalization,
+refundable-payment lookup, and refunds.

package/dist/catalog.d.mts

@@ -0,0 +1,23 @@
+export type MembershipBenefitCatalogInput = {
+    version: number;
+    plans: readonly PropertyKey[];
+    groups: readonly {
+        id: PropertyKey;
+        benefits: readonly {
+            id: PropertyKey;
+            placements: readonly PropertyKey[];
+            values: object;
+        }[];
+    }[];
+};
+type CatalogBenefit<Catalog extends MembershipBenefitCatalogInput> = Catalog['groups'][number]['benefits'][number];
+type CatalogBenefitId<Catalog extends MembershipBenefitCatalogInput> = CatalogBenefit<Catalog>['id'];
+type CatalogBenefitForId<Catalog extends MembershipBenefitCatalogInput, BenefitId extends CatalogBenefitId<Catalog>> = Extract<CatalogBenefit<Catalog>, {
+    id: BenefitId;
+}>;
+type CatalogBenefitValue<Catalog extends MembershipBenefitCatalogInput, BenefitId extends CatalogBenefitId<Catalog>, Plan extends Catalog['plans'][number]> = CatalogBenefitForId<Catalog, BenefitId> extends {
+    values: infer Values;
+} ? Values extends Record<PropertyKey, unknown> ? Values[Plan & keyof Values] : never : never;
+export declare function buildMembershipBenefitCatalog<const Catalog extends MembershipBenefitCatalogInput>(catalog: Catalog, enforcedBenefitIds: ReadonlySet<CatalogBenefitId<Catalog>>): Catalog;
+export declare function resolveMembershipBenefit<const Catalog extends MembershipBenefitCatalogInput, BenefitId extends CatalogBenefitId<Catalog>, Plan extends Catalog['plans'][number]>(catalog: Catalog, benefitId: BenefitId, plan: Plan): CatalogBenefitValue<Catalog, BenefitId, Plan> | undefined;
+export {};

package/dist/catalog.mjs

@@ -0,0 +1,34 @@
+export function buildMembershipBenefitCatalog(catalog, enforcedBenefitIds) {
+    const groupIds = new Set();
+    const ids = new Set();
+    for (const group of catalog.groups) {
+        if (groupIds.has(group.id))
+            throw new Error(`Duplicate membership benefit group: ${String(group.id)}`);
+        groupIds.add(group.id);
+        for (const benefit of group.benefits) {
+            if (!enforcedBenefitIds.has(benefit.id)) {
+                throw new Error(`Membership benefit is not enforced: ${String(benefit.id)}`);
+            }
+            if (ids.has(benefit.id))
+                throw new Error(`Duplicate membership benefit: ${String(benefit.id)}`);
+            ids.add(benefit.id);
+            for (const plan of catalog.plans) {
+                if (!Object.hasOwn(benefit.values, plan)) {
+                    throw new Error(`Membership benefit is missing a value for plan: ${String(plan)}`);
+                }
+            }
+        }
+    }
+    return catalog;
+}
+export function resolveMembershipBenefit(catalog, benefitId, plan) {
+    for (const group of catalog.groups) {
+        const benefit = group.benefits.find((item) => item.id === benefitId);
+        if (!benefit)
+            continue;
+        if (!Object.hasOwn(benefit.values, plan))
+            return undefined;
+        return benefit.values[plan];
+    }
+    return undefined;
+}

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+export { buildMembershipBenefitCatalog, resolveMembershipBenefit } from './catalog.mts';
+export { classifyMembershipChange, isTerminalMembershipStatus, transitionMembershipLifecycle, } from './lifecycle.mts';
+export { groupMembershipSkusByPlan } from './sku.mts';
+export type { CancelSubscriptionCapability, CreateSubscriptionCapability, ListRefundablePaymentsCapability, MembershipMoney, MembershipProviderOperation, NormalizedMembershipWebhook, NormalizedRefundWebhook, NormalizedSubscriptionWebhook, NormalizeWebhookCapability, RefundablePayment, RefundPaymentCapability, UpdateSubscriptionCapability, } from './provider.mts';
+export type { MembershipBenefitCatalogInput } from './catalog.mts';
+export type { MembershipChangeType, MembershipLifecycleFields, MembershipLifecycleUpdate, MembershipStatus, } from './types.mts';

package/dist/index.mjs

@@ -0,0 +1,3 @@
+export { buildMembershipBenefitCatalog, resolveMembershipBenefit } from './catalog.mjs';
+export { classifyMembershipChange, isTerminalMembershipStatus, transitionMembershipLifecycle, } from './lifecycle.mjs';
+export { groupMembershipSkusByPlan } from './sku.mjs';

package/dist/lifecycle.d.mts

@@ -0,0 +1,12 @@
+import type { MembershipChangeType, MembershipLifecycleFields, MembershipLifecycleUpdate, MembershipStatus } from './types.mts';
+export declare function isTerminalMembershipStatus(status: MembershipStatus): boolean;
+export declare function transitionMembershipLifecycle(current: MembershipLifecycleFields, update: MembershipLifecycleUpdate, at: Date): MembershipLifecycleFields;
+export declare function classifyMembershipChange<Plan, Sku>(options: {
+    previousStatus: MembershipStatus;
+    nextStatus: MembershipStatus;
+    previousPlan: Plan;
+    nextPlan: Plan;
+    previousSku: Sku;
+    nextSku: Sku;
+    comparePlans: (left: Plan, right: Plan) => number;
+}): MembershipChangeType | null;

package/dist/lifecycle.mjs

@@ -0,0 +1,56 @@
+export function isTerminalMembershipStatus(status) {
+    return status === 'cancelled' || status === 'expired';
+}
+export function transitionMembershipLifecycle(current, update, at) {
+    const status = update.status ?? current.status;
+    if (current.status === 'expired' && status !== 'expired') {
+        throw new Error('An expired membership cannot transition to another status');
+    }
+    const timestamp = status === 'active'
+        ? null
+        : current.status === status
+            ? (timestampForStatus(current, status) ?? at)
+            : at;
+    return {
+        status,
+        cancelledAt: status === 'cancelled' ? timestamp : null,
+        expiredAt: status === 'expired' ? timestamp : null,
+        pastDueAt: status === 'past_due' ? timestamp : null,
+        pausedAt: status === 'paused' ? timestamp : null,
+        cancelAtPeriodEnd: isTerminalMembershipStatus(status)
+            ? false
+            : (update.cancelAtPeriodEnd ?? current.cancelAtPeriodEnd),
+    };
+}
+export function classifyMembershipChange(options) {
+    const { previousStatus, nextStatus, previousPlan, nextPlan, previousSku, nextSku, comparePlans } = options;
+    if (previousPlan !== nextPlan) {
+        const comparison = comparePlans(nextPlan, previousPlan);
+        if (comparison !== 0)
+            return comparison > 0 ? 'upgrade' : 'downgrade';
+    }
+    if (previousStatus !== nextStatus)
+        return classifyStatusChange(previousStatus, nextStatus);
+    return previousSku !== nextSku ? 'sku_migration' : null;
+}
+function timestampForStatus(current, status) {
+    switch (status) {
+        case 'cancelled':
+            return current.cancelledAt;
+        case 'expired':
+            return current.expiredAt;
+        case 'past_due':
+            return current.pastDueAt;
+        case 'paused':
+            return current.pausedAt;
+    }
+}
+function classifyStatusChange(previous, next) {
+    if (next === 'cancelled')
+        return 'cancellation';
+    if (next === 'paused')
+        return 'pause';
+    if ((previous === 'cancelled' || previous === 'paused') && next === 'active')
+        return 'reactivation';
+    return next === 'expired' ? 'expiration' : 'renewal';
+}

package/dist/provider.d.mts

@@ -0,0 +1,53 @@
+import type { MembershipStatus } from './types.mts';
+export type MembershipMoney = {
+    amountMinorUnits: number;
+    currency: string;
+};
+/** Caller-generated key used by provider adapters to make mutations replay-safe. */
+export type MembershipProviderOperation = {
+    idempotencyKey: string;
+};
+export type NormalizedSubscriptionWebhook<SubscriptionId = string, CustomerId = string, SkuId = string> = {
+    kind: 'subscription';
+    eventId: string;
+    occurredAt: Date;
+    subscriptionId: SubscriptionId;
+    customerId: CustomerId | null;
+    skuId: SkuId | null;
+    status: MembershipStatus;
+    periodEndAt: Date | null;
+    cancelAtPeriodEnd: boolean;
+};
+export type NormalizedRefundWebhook<PaymentId = string> = {
+    kind: 'refund';
+    eventId: string;
+    occurredAt: Date;
+    paymentId: PaymentId;
+    amount: MembershipMoney;
+};
+export type NormalizedMembershipWebhook<SubscriptionId = string, CustomerId = string, SkuId = string, PaymentId = string> = NormalizedSubscriptionWebhook<SubscriptionId, CustomerId, SkuId> | NormalizedRefundWebhook<PaymentId>;
+export type RefundablePayment<PaymentId = string> = {
+    paymentId: PaymentId;
+    amount: MembershipMoney;
+    refundedAmount: MembershipMoney;
+    createdAt: Date;
+    description: string | null;
+};
+export type CreateSubscriptionCapability<Context, Request, Result> = {
+    createSubscription(context: Context, request: Request, operation: MembershipProviderOperation): Promise<Result>;
+};
+export type UpdateSubscriptionCapability<Context, Request, Result> = {
+    updateSubscription(context: Context, request: Request, operation: MembershipProviderOperation): Promise<Result>;
+};
+export type CancelSubscriptionCapability<Context, Request, Result> = {
+    cancelSubscription(context: Context, request: Request, operation: MembershipProviderOperation): Promise<Result>;
+};
+export type NormalizeWebhookCapability<Context, Request, SubscriptionId = string, CustomerId = string, SkuId = string, PaymentId = string> = {
+    normalizeWebhook(context: Context, request: Request): Promise<NormalizedMembershipWebhook<SubscriptionId, CustomerId, SkuId, PaymentId>>;
+};
+export type ListRefundablePaymentsCapability<Context, Request, PaymentId = string> = {
+    listRefundablePayments(context: Context, request: Request): Promise<RefundablePayment<PaymentId>[]>;
+};
+export type RefundPaymentCapability<Context, Request, Result> = {
+    refundPayment(context: Context, request: Request, operation: MembershipProviderOperation): Promise<Result>;
+};

package/dist/provider.mjs

@@ -0,0 +1 @@
+export {};

package/dist/sku.d.mts

@@ -0,0 +1,3 @@
+export declare function groupMembershipSkusByPlan<Plan extends PropertyKey, Sku extends {
+    plan: Plan;
+}>(skus: readonly Sku[]): Map<Plan, Sku[]>;

package/dist/sku.mjs

@@ -0,0 +1,11 @@
+export function groupMembershipSkusByPlan(skus) {
+    const grouped = new Map();
+    for (const sku of skus) {
+        const entries = grouped.get(sku.plan);
+        if (entries)
+            entries.push(sku);
+        else
+            grouped.set(sku.plan, [sku]);
+    }
+    return grouped;
+}

package/dist/types.d.mts

@@ -0,0 +1,14 @@
+export type MembershipStatus = 'active' | 'past_due' | 'paused' | 'cancelled' | 'expired';
+export type MembershipLifecycleFields = {
+    status: MembershipStatus;
+    cancelledAt: Date | null;
+    expiredAt: Date | null;
+    pastDueAt: Date | null;
+    pausedAt: Date | null;
+    cancelAtPeriodEnd: boolean;
+};
+export type MembershipLifecycleUpdate = {
+    status?: MembershipStatus;
+    cancelAtPeriodEnd?: boolean;
+};
+export type MembershipChangeType = 'upgrade' | 'downgrade' | 'renewal' | 'cancellation' | 'reactivation' | 'pause' | 'sku_migration' | 'expiration';

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vouchington/memberships",
+  "version": "0.0.0",
+  "description": "Schema-less membership lifecycle, catalog, SKU, and provider primitives.",
+  "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/memberships#readme",
+  "bugs": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/memberships"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}