@frigear-nu/subscriptions 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @frigear-nu/subscriptions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Recurring Stripe subscriptions for the frigear ecosystem: host-defined plans, checkout, upgrade/downgrade, billing
+portal, entitlements and opt-in account pages. Built on [`@frigear-nu/stripe`](../stripe) (customer link + verified
+webhook) and [`@frigear-nu/users`](../users). One-off payments are out of scope.
+
+## Features
+
+- 📋 Plans declared in config; live prices resolved from Stripe and cached in NuxtHub KV (~5 minutes).
+- 🔁 Checkout for new subscribers; immediate upgrade (prorated) or deferred downgrade, decided by plan `rank`.
+- 🧾 Stripe billing portal sessions.
+- 🪝 Policy hooks (`subscriptions:checkout:before`, `subscriptions:plans:filter`) for seasons, discounts, trials, ...
+- 🔐 Entitlement utils (`hasActiveSubscription`, `getUserSubscription`) and a `subscription` route middleware.
+- 🧩 `usePlans` / `useSubscription` composables, `SubscriptionPlans` / `SubscriptionStatus` components with slots and
+  optional i18n, and opt-in membership/success/cancel pages (built with [`@nuxt/ui`](https://ui.nuxt.com)).
+- 🗂️ Contributes a "Subscription" item to `@frigear-nu/menu` (when installed).
+
+## Quick Setup
+
+```bash
+npx nuxt module add @frigear-nu/subscriptions
+```
+
+Requires `@nuxthub/core` with `hub.kv: true` (the build fails otherwise), `@frigear-nu/users` and `@frigear-nu/stripe`
+(set up its environment variables as described in its README).
+
+## Configuration
+
+```ts
+export default defineNuxtConfig({
+  modules: [
+    '@nuxthub/core',
+    '@frigear-nu/users',
+    '@frigear-nu/menu', // optional
+    '@frigear-nu/stripe',
+    '@frigear-nu/subscriptions',
+  ],
+  hub: { db: { dialect: 'sqlite', driver: 'libsql' }, kv: true },
+  subscriptions: {
+    plans: {
+      member: { label: 'Member', rank: 1, prices: ['price_123', { lookupKey: 'member_yearly' }] },
+      patron: { label: 'Patron', description: 'Supporters', rank: 2, prices: [{ lookupKey: 'patron_yearly' }] },
+    },
+    settings: {
+      pages: {
+        membership: true, // or a custom path, default '/account/membership'
+        success: true, // default '/account/membership/success'
+        cancel: true, // default '/account/membership/cancel'
+      },
+      allowChangeInPortal: false, // default; a hint exposed in public runtime config, not enforced
+    },
+  },
+})
+```
+
+- `plans` (default `{}`): keyed by plan key. `prices` are Stripe price ids or `{ lookupKey }`; `rank` decides upgrade vs.
+  downgrade (never the price amount); `label` defaults to the key. Leave `plans` empty for "any active subscription"
+  (checkout then requires a `priceId`).
+- Pages are off unless enabled; `true` uses the default path, a string overrides it.
+
+## Database
+
+Registers a `subscriptions` table (one row per Stripe subscription: `id`, `userId`, `planKey`, `priceId`, `status`,
+`cancelAtPeriodEnd`, period dates, `endedAt`, `rawItems`, timestamps). Rows are never deleted; prices outside the config are
+stored with `planKey = null`. There is no foreign key to `users`.
+
+**Host apps must generate and commit their own migration** (the `subscriptions` table plus `users.stripe_customer_id`
+from `@frigear-nu/stripe`), using the app's complete module configuration. See `AGENTS.md` and the Module Kit docs.
+
+## Webhook events
+
+Subscribe the Stripe webhook endpoint (see `@frigear-nu/stripe`) to `customer.subscription.created`, `.updated`,
+`.deleted`, `.paused` and `.resumed`. Each event is an idempotent upsert by subscription id; events for customers without
+a local user are logged and ignored.
+
+## API routes
+
+- `GET /api/subscriptions/plans` - public; `{ plans }` with live prices, after the `subscriptions:plans:filter` hook.
+- `GET /api/subscriptions/me` - `{ subscriptions, activePlan }` (401 when signed out).
+- `POST /api/subscriptions/checkout` - body `{ planKey?, priceId?, successUrl?, cancelUrl? }` (one of `planKey`/`priceId`
+  required; a multi-price plan needs `priceId`). Returns `{ url }` (new Checkout Session) or
+  `{ updated: true, kind: 'upgrade' | 'downgrade' }`. A higher rank upgrades immediately (`always_invoice` proration);
+  a lower or equal rank (including monthly to yearly of one plan) is scheduled for period end. `400` for unknown or hidden
+  plans/prices and URLs outside the request origin, `409` when already on that price.
+- `POST /api/subscriptions/portal` - body `{ returnUrl? }`; returns `{ url }` of a billing portal session.
+
+## Policy hooks
+
+```ts
+// server/plugins/subscription-policy.ts
+export default defineNitroPlugin((nitro) => {
+  // ctx: { event, userId, planKey, priceId, kind: 'checkout' | 'upgrade' | 'downgrade', params }
+  // Throw to deny. `params` (Stripe Checkout Session params) only applies when `kind === 'checkout'`.
+  nitro.hooks.hook('subscriptions:checkout:before', (ctx) => {
+    if (ctx.kind === 'checkout') ctx.params.subscription_data = { ...ctx.params.subscription_data, trial_period_days: 7 }
+  })
+
+  // ctx: { event (undefined outside a request), plans }. Change `ctx.plans` to hide or reorder plans.
+  nitro.hooks.hook('subscriptions:plans:filter', (ctx) => {
+    ctx.plans = ctx.plans.filter(plan => plan.key !== 'secret')
+  })
+})
+```
+
+## Entitlements and middleware
+
+```ts
+// server (auto-imported, or from '@frigear-nu/subscriptions/utils')
+const subscription = await getUserSubscription(userId)
+const ok = await hasActiveSubscription(userId, { plans: ['member'], statuses: ['active', 'trialing'] }) // statuses default
+```
+
+```ts
+// page
+definePageMeta({ middleware: 'subscription', subscription: { plans: ['member'], redirectTo: '/join' } })
+```
+
+Redirects to `redirectTo` (else the membership page) with `?redirect=<route>`; a no-op when neither exists.
+
+## Composables and components
+
+- `usePlans()` - `{ plans, status, error, refresh }`.
+- `useSubscription()` - `{ subscription, plan, status, isActive, cancelsAt, has(plan), pending, error, refresh, subscribe(planKeyOrPriceId, { successUrl?, cancelUrl? }), openPortal(returnUrl?) }`.
+- `<SubscriptionPlans>` - props `locale`, `currency`, `interval`, `plans`, `confirmChange`; slots `loading`,
+  `empty`, `header`, `badge`, `price`, `features`, `action`, `confirm`, `confirm-actions`.
+- `<SubscriptionStatus>` - props `locale`; slots `header`, `loading`, `empty`, `plan`, `badge`, `dates`, `actions`.
+
+Text uses `useModuleT('subscriptions…')`: `subscriptions.<group>.<key>` from `@nuxtjs/i18n` when defined, else English defaults. Plan names come from `subscriptions.catalog.<planKey>.label` / `.description`, falling back to the plan config.

package/dist/module.d.mts

@@ -0,0 +1,155 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import Stripe from 'stripe';
+import { H3Event } from 'h3';
+
+/** A price of a plan: either a Stripe price id, or a lookup key resolved through Stripe. */
+type PlanPriceRef = string | {
+    lookupKey: string;
+};
+type PlanConfig = {
+    /** Stripe prices belonging to this plan (e.g. monthly + yearly). */
+    prices: PlanPriceRef[];
+    /** Display label. Plain text, used as the fallback. The UI prefers `subscriptions.catalog.<planKey>.label` from i18n when defined. */
+    label?: string;
+    description?: string;
+    /** Drives upgrade vs. downgrade: a higher rank is a higher tier. */
+    rank: number;
+};
+type ModuleOptions = {
+    /** Plans keyed by plan key. Leave empty to use the module as "any active subscription". */
+    plans?: Record<string, PlanConfig>;
+    settings?: {
+        pages?: {
+            /** Default `/account/membership`. */
+            membership?: string | boolean;
+            /** Default `/account/membership/success`. */
+            success?: string | boolean;
+            /** Default `/account/membership/cancel`. */
+            cancel?: string | boolean;
+        };
+        /** Hint for the UI: let customers change plan in the Stripe billing portal instead of in-app. */
+        allowChangeInPortal?: boolean;
+    };
+};
+type PublicPlan = {
+    key: string;
+    label: string;
+    description?: string;
+    rank: number;
+};
+/** Exposed as `useRuntimeConfig().public.subscriptions`. */
+type PublicModuleOptions = {
+    pages: {
+        membership?: string;
+        success?: string;
+        cancel?: string;
+    };
+    plans: PublicPlan[];
+    allowChangeInPortal: boolean;
+};
+/** Private server runtime config (`useRuntimeConfig().subscriptions`). */
+type SubscriptionsRuntimeConfig = {
+    plans: Record<string, {
+        prices: PlanPriceRef[];
+        label?: string;
+        description?: string;
+        rank: number;
+    }>;
+};
+type PlanPrice = {
+    id: string;
+    amount: number | null;
+    currency: string;
+    interval: 'day' | 'week' | 'month' | 'year';
+    intervalCount: number;
+    trialPeriodDays: number | null;
+    lookupKey: string | null;
+};
+type ResolvedPlan = PublicPlan & {
+    prices: PlanPrice[];
+};
+type PlansResponse = {
+    plans: ResolvedPlan[];
+};
+type SubscriptionDto = {
+    id: string;
+    planKey: string | null;
+    priceId: string;
+    status: string;
+    cancelAtPeriodEnd: boolean;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    endedAt: string | null;
+};
+type MeResponse = {
+    subscriptions: SubscriptionDto[];
+    activePlan: string | null;
+};
+type CheckoutBody = {
+    planKey?: string;
+    priceId?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+};
+type CheckoutResponse = {
+    url: string;
+} | {
+    updated: true;
+    kind: 'upgrade' | 'downgrade';
+};
+type PortalBody = {
+    returnUrl?: string;
+};
+/** Fired before a checkout / plan change. Throw (e.g. `createError`) to deny; mutate `params` to adjust. */
+type CheckoutBeforeContext = {
+    event: H3Event;
+    userId: number;
+    /** The plan the user is moving to, or `null` when the price isn't part of a configured plan. */
+    planKey: string | null;
+    priceId: string;
+    /** `checkout` = new subscription, otherwise a change of an existing one. */
+    kind: 'checkout' | 'upgrade' | 'downgrade';
+    /**
+     * Parameters for `stripe.checkout.sessions.create` (only used when `kind === 'checkout'`). Adjust
+     * them in place to add promo codes, tax, trials, metadata, ...
+     */
+    params: Stripe.Checkout.SessionCreateParams;
+};
+type PlansFilterContext = {
+    /** The request, or `undefined` when computed outside a request. */
+    event: H3Event | undefined;
+    /** The plans about to be returned. Mutate or reassign `plans` to hide / reorder them. */
+    plans: ResolvedPlan[];
+};
+
+declare module '@nuxt/schema' {
+    interface NuxtConfig {
+        subscriptions?: ModuleOptions;
+    }
+    interface RuntimeConfig {
+        subscriptions: SubscriptionsRuntimeConfig;
+    }
+    interface PublicRuntimeConfig {
+        subscriptions: PublicModuleOptions;
+    }
+}
+declare module '#app' {
+    interface PageMeta {
+        subscription?: {
+            plans?: string[];
+            redirectTo?: string;
+        };
+    }
+}
+declare module 'nitropack' {
+    interface NitroRuntimeHooks {
+        /** Policy hook: throw to deny a checkout / plan change, or adjust `ctx.params`. */
+        'subscriptions:checkout:before': (ctx: CheckoutBeforeContext) => void | Promise<void>;
+        /** Policy hook: hide or reorder plans by changing `ctx.plans` in place. */
+        'subscriptions:plans:filter': (ctx: PlansFilterContext) => void | Promise<void>;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { CheckoutBeforeContext, CheckoutBody, CheckoutResponse, MeResponse, ModuleOptions, PlanConfig, PlanPrice, PlanPriceRef, PlansFilterContext, PlansResponse, PortalBody, PublicModuleOptions, PublicPlan, ResolvedPlan, SubscriptionDto, SubscriptionsRuntimeConfig };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/subscriptions",
+  "configKey": "subscriptions",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,120 @@
+import { defineNuxtModule, createResolver, hasNuxtModule, addServerHandler, addServerImportsDir, addImports, addComponentsDir, addRouteMiddleware, extendPages } from '@nuxt/kit';
+import { registerModule, registerLocales, registerDatabaseTable, moduleApiUrl, defineModulePage } from '@frigear-nu/module-kit/utils';
+import { registerStripeEventHandler } from '@frigear-nu/stripe/utils';
+
+const MODULE_NAME = "@frigear-nu/subscriptions";
+function resolvePagePath(setting, defaultPath) {
+  if (typeof setting === "string") return setting;
+  if (setting === true) return defaultPath;
+  return void 0;
+}
+const module$1 = defineNuxtModule({
+  meta: { name: MODULE_NAME, configKey: "subscriptions" },
+  defaults: {
+    plans: {},
+    settings: { pages: {}, allowChangeInPortal: false }
+  },
+  moduleDependencies: {
+    "@nuxthub/core": {
+      version: ">=0.10",
+      defaults: { kv: true }
+    },
+    "@frigear-nu/module-kit": { version: ">=0.0.1" },
+    "@frigear-nu/users": { version: ">=0.0.1" },
+    "@frigear-nu/stripe": { version: ">=0.0.1" },
+    "@frigear-nu/menu": { version: ">=0.0.1", optional: true }
+  },
+  async setup(options, nuxt) {
+    registerModule(MODULE_NAME, nuxt);
+    const resolver = createResolver(import.meta.url);
+    registerLocales(nuxt, resolver.resolve("./runtime/i18n/lang"));
+    const settings = options.settings ?? {};
+    const plans = options.plans ?? {};
+    const withMenus = hasNuxtModule("@frigear-nu/menu");
+    if (!nuxt.options.hub?.kv) {
+      throw new Error("[@frigear-nu/subscriptions] NuxtHub KV is required (plans cache). Set `hub: { kv: true }` in your Nuxt config.");
+    }
+    const membershipPath = resolvePagePath(settings.pages?.membership, "/account/membership");
+    const successPath = resolvePagePath(settings.pages?.success, "/account/membership/success");
+    const cancelPath = resolvePagePath(settings.pages?.cancel, "/account/membership/cancel");
+    const planEntries = Object.entries(plans);
+    nuxt.options.runtimeConfig.subscriptions = {
+      plans: Object.fromEntries(planEntries.map(([key, plan]) => [key, {
+        prices: plan.prices,
+        label: plan.label,
+        description: plan.description,
+        rank: plan.rank
+      }]))
+    };
+    nuxt.options.runtimeConfig.public.subscriptions = {
+      pages: { membership: membershipPath, success: successPath, cancel: cancelPath },
+      plans: planEntries.map(([key, plan]) => ({ key, label: plan.label ?? key, description: plan.description, rank: plan.rank })).sort((a, b) => a.rank - b.rank),
+      allowChangeInPortal: settings.allowChangeInPortal === true
+    };
+    await registerDatabaseTable(nuxt, {
+      name: "subscriptions",
+      resolver,
+      schema: (dialect) => `./runtime/server/db/schema.${dialect}`
+    });
+    registerStripeEventHandler(nuxt, {
+      events: [
+        "customer.subscription.created",
+        "customer.subscription.updated",
+        "customer.subscription.deleted",
+        "customer.subscription.paused",
+        "customer.subscription.resumed"
+      ],
+      handler: resolver.resolve("./runtime/server/stripe/subscription-events")
+    });
+    addServerHandler({
+      route: moduleApiUrl("subscriptions", "plans"),
+      method: "get",
+      handler: resolver.resolve("./runtime/server/routes/subscriptions/plans.get")
+    });
+    addServerHandler({
+      route: moduleApiUrl("subscriptions", "me"),
+      method: "get",
+      handler: resolver.resolve("./runtime/server/routes/subscriptions/me.get")
+    });
+    addServerHandler({
+      route: moduleApiUrl("subscriptions", "checkout"),
+      method: "post",
+      handler: resolver.resolve("./runtime/server/routes/subscriptions/checkout.post")
+    });
+    addServerHandler({
+      route: moduleApiUrl("subscriptions", "portal"),
+      method: "post",
+      handler: resolver.resolve("./runtime/server/routes/subscriptions/portal.post")
+    });
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addImports([
+      { name: "usePlans", from: resolver.resolve("./runtime/app/composables/usePlans") },
+      { name: "useSubscription", from: resolver.resolve("./runtime/app/composables/useSubscription") }
+    ]);
+    addComponentsDir({ path: resolver.resolve("./runtime/app/components") });
+    addRouteMiddleware({
+      name: "subscription",
+      path: resolver.resolve("./runtime/app/middleware/subscription")
+    });
+    if (membershipPath || successPath || cancelPath) {
+      extendPages((pages) => {
+        const existingPaths = new Set(pages.map((page) => page.path));
+        if (membershipPath && !existingPaths.has(membershipPath)) {
+          pages.push(defineModulePage(MODULE_NAME, { name: "subscriptions-membership", path: membershipPath, file: resolver.resolve("./runtime/app/pages/membership.vue") }));
+        }
+        if (successPath && !existingPaths.has(successPath)) {
+          pages.push(defineModulePage(MODULE_NAME, { name: "subscriptions-success", path: successPath, file: resolver.resolve("./runtime/app/pages/success.vue") }));
+        }
+        if (cancelPath && !existingPaths.has(cancelPath)) {
+          pages.push(defineModulePage(MODULE_NAME, { name: "subscriptions-cancel", path: cancelPath, file: resolver.resolve("./runtime/app/pages/cancel.vue") }));
+        }
+      });
+    }
+    if (withMenus) {
+      const { registerMenuSource } = await import('@frigear-nu/menu/utils');
+      registerMenuSource(nuxt, { file: resolver.resolve("./runtime/menus"), menu: "dashboard.account" });
+    }
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/components/SubscriptionPlans.d.vue.ts

@@ -0,0 +1,71 @@
+import type { SubscriptionPlan, SubscriptionPlanPrice } from '../composables/usePlans.js';
+type __VLS_Props = {
+    locale?: string;
+    /** Override the price currency formatting currency (defaults to the price's own currency). */
+    currency?: string;
+    interval?: SubscriptionPlanPrice['interval'];
+    /** Only show these plan keys. */
+    plans?: string[];
+    /** Ask for confirmation (modal) before changing an existing subscription. */
+    confirmChange?: boolean;
+};
+declare function formatPrice(price: SubscriptionPlanPrice): string;
+declare function intervalLabel(price: SubscriptionPlanPrice): any;
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_17: {
+    plan: any;
+    state: "upgrade" | "downgrade" | "subscribe" | "current";
+}, __VLS_19: {
+    plan: any;
+    state: "upgrade" | "downgrade" | "subscribe" | "current";
+}, __VLS_27: {
+    plan: any;
+    price: SubscriptionPlanPrice | undefined;
+    formatPrice: typeof formatPrice;
+    intervalLabel: typeof intervalLabel;
+}, __VLS_29: {
+    plan: any;
+}, __VLS_32: {
+    plan: any;
+    state: "upgrade" | "downgrade" | "subscribe" | "current";
+    pending: any;
+    select: () => void;
+}, __VLS_48: {
+    plan: any;
+    price: any;
+}, __VLS_51: {
+    plan: any;
+    price: any;
+    confirm: () => any;
+};
+type __VLS_Slots = {} & {
+    loading?: (props: typeof __VLS_1) => any;
+} & {
+    empty?: (props: typeof __VLS_3) => any;
+} & {
+    header?: (props: typeof __VLS_17) => any;
+} & {
+    badge?: (props: typeof __VLS_19) => any;
+} & {
+    price?: (props: typeof __VLS_27) => any;
+} & {
+    features?: (props: typeof __VLS_29) => any;
+} & {
+    action?: (props: typeof __VLS_32) => any;
+} & {
+    confirm?: (props: typeof __VLS_48) => any;
+} & {
+    'confirm-actions'?: (props: typeof __VLS_51) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (plan: SubscriptionPlan, price: SubscriptionPlanPrice) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onSelect?: ((plan: SubscriptionPlan, price: SubscriptionPlanPrice) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};