@meith/plugin-dues 0.1.0

package/src/plans.ts

@@ -0,0 +1,183 @@
+import type { PluginData } from '@meith/plugin-kit'
+
+import type { DuesConfig } from './config'
+import { isCurrencyCode, isValidMinorAmount } from './money'
+import { addDays, parsePeriod, periodCeilingDays, type Period } from './period'
+import {
+  countPlans,
+  insertPlan,
+  listPlans,
+  type NewPlan,
+  type PlanMode,
+  type PlanRow,
+} from './store'
+
+export const GRANT_WINDOW_DAYS = 700
+export const TOP_UP_WHEN_WITHIN_DAYS = 90
+export const LIFETIME_END = new Date('9999-12-31T00:00:00Z')
+
+export const MAX_PLAN_DAYS = 2 * 366
+
+const PLAN_KEY = /^[a-z][a-z0-9-]{0,39}$/
+
+export function clampGrantUntil(graceUntil: Date, now: Date): Date {
+  const ceiling = addDays(now, GRANT_WINDOW_DAYS)
+  return graceUntil > ceiling ? ceiling : graceUntil
+}
+
+export function isLifetime(periodEnd: Date): boolean {
+  return periodEnd >= LIFETIME_END
+}
+
+export async function loadPlans(
+  data: PluginData,
+  config: DuesConfig,
+): Promise<readonly PlanRow[]> {
+  if ((await countPlans(data)) === 0 && config.seedPlans.length > 0) {
+    for (const seed of config.seedPlans) {
+      await insertPlan(data, {
+        planKey: seed.key,
+        name: seed.name,
+        description: seed.description,
+        groupKey: seed.group,
+        priceMinor: seed.price,
+        currency: config.currency,
+        mode: seed.billing.mode,
+        periodSpec: seed.billing.mode === 'fixed' ? seed.billing.period : null,
+        billingInterval: seed.billing.mode === 'auto' ? seed.billing.interval : null,
+        stripePriceId: seed.billing.mode === 'auto' ? seed.billing.stripePriceId : null,
+        stripeProductId: null,
+        giftable: seed.giftable,
+        hidden: seed.hidden,
+      })
+    }
+  }
+  return listPlans(data)
+}
+
+export async function shopPlans(
+  data: PluginData,
+  config: DuesConfig,
+): Promise<readonly PlanRow[]> {
+  return (await loadPlans(data, config)).filter((plan) => !plan.hidden && !plan.archived)
+}
+
+export async function anyPlanByKey(
+  data: PluginData,
+  config: DuesConfig,
+  key: string,
+): Promise<PlanRow | null> {
+  return (await loadPlans(data, config)).find((plan) => plan.key === key) ?? null
+}
+
+export async function sellablePlanByKey(
+  data: PluginData,
+  config: DuesConfig,
+  key: string,
+): Promise<PlanRow | null> {
+  const plan = await anyPlanByKey(data, config, key)
+  return plan === null || plan.archived ? null : plan
+}
+
+export function planPeriod(plan: PlanRow): Period | null {
+  return plan.periodSpec === null ? null : parsePeriod(plan.periodSpec)
+}
+
+export function describeBilling(plan: PlanRow): string {
+  if (plan.mode === 'auto') return `every ${plan.billingInterval ?? 'month'}`
+  if (plan.mode === 'lifetime') return 'once, for good'
+  const period = planPeriod(plan)
+  if (period === null) return plan.periodSpec ?? ''
+  const parts: string[] = []
+  const piece = (count: number, word: string) => {
+    if (count > 0) parts.push(`${count} ${word}${count === 1 ? '' : 's'}`)
+  }
+  piece(period.years, 'year')
+  piece(period.months, 'month')
+  piece(period.weeks, 'week')
+  piece(period.days, 'day')
+  return parts.join(', ')
+}
+
+export interface PlanFormInput {
+  readonly key?: string | undefined
+  readonly name?: string | undefined
+  readonly description?: string | undefined
+  readonly group?: string | undefined
+  readonly price?: string | undefined
+  readonly currency?: string | undefined
+  readonly mode?: string | undefined
+  readonly length?: string | undefined
+  readonly unit?: string | undefined
+  readonly interval?: string | undefined
+  readonly stripe_price?: string | undefined
+  readonly giftable?: string | undefined
+  readonly hidden?: string | undefined
+}
+
+export type PlanParse =
+  | { readonly ok: true; readonly plan: Omit<NewPlan, 'stripePriceId' | 'stripeProductId'> }
+  | { readonly ok: false; readonly error: string }
+
+function bad(error: string): PlanParse {
+  return { ok: false, error }
+}
+
+export function parsePlanForm(form: PlanFormInput, graceDays: number): PlanParse {
+  const key = (form.key ?? '').trim().toLowerCase()
+  if (!PLAN_KEY.test(key)) return bad('bad-key')
+
+  const name = (form.name ?? '').trim()
+  if (name === '') return bad('bad-name')
+
+  const group = (form.group ?? '').trim().toLowerCase()
+  if (!PLAN_KEY.test(group)) return bad('bad-group')
+
+  const price = Number(form.price ?? '')
+  if (!isValidMinorAmount(price)) return bad('bad-price')
+
+  const currency = (form.currency ?? '').trim().toLowerCase()
+  if (!isCurrencyCode(currency)) return bad('bad-currency')
+
+  const mode = form.mode as PlanMode
+  if (mode !== 'auto' && mode !== 'fixed' && mode !== 'lifetime') return bad('bad-mode')
+
+  let periodSpec: string | null = null
+  let billingInterval: 'month' | 'year' | null = null
+
+  if (mode === 'fixed') {
+    const length = Number(form.length ?? '')
+    const unit = form.unit ?? ''
+    const letter =
+      unit === 'days' ? 'D' : unit === 'weeks' ? 'W' : unit === 'months' ? 'M' : unit === 'years' ? 'Y' : null
+    if (letter === null || !Number.isInteger(length) || length < 1) return bad('bad-length')
+
+    periodSpec = `P${length}${letter}`
+    const parsed = parsePeriod(periodSpec)
+    if (parsed === null) return bad('bad-length')
+    if (periodCeilingDays(parsed) + graceDays > MAX_PLAN_DAYS) return bad('too-long')
+  }
+
+  if (mode === 'auto') {
+    if (form.interval !== 'month' && form.interval !== 'year') return bad('bad-interval')
+    billingInterval = form.interval
+    if (form.giftable === 'on') return bad('auto-gift')
+  }
+
+  return {
+    ok: true,
+    plan: {
+      planKey: key,
+      name,
+      description: (form.description ?? '').trim() || null,
+      groupKey: group,
+      priceMinor: price,
+      currency,
+      mode,
+      periodSpec,
+      billingInterval,
+      giftable: mode === 'auto' ? false : form.giftable === 'on',
+      hidden: form.hidden === 'on',
+    },
+  }
+}

package/src/schema.ts

@@ -0,0 +1,153 @@
+import type { PluginMigration } from '@meith/plugin-kit'
+
+export const DUES_MIGRATIONS: readonly PluginMigration[] = [
+  {
+    id: '0001_customers_orders',
+    statements: [
+      `create table if not exists plugin_dues_customer (
+         user_id            integer     not null,
+         stripe_customer_id text        not null,
+         created_at         timestamptz not null default now(),
+         primary key (user_id)
+       )`,
+      `create unique index if not exists plugin_dues_customer_stripe_key
+         on plugin_dues_customer (stripe_customer_id)`,
+      `create table if not exists plugin_dues_order (
+         id                       bigint generated by default as identity primary key,
+         buyer_user_id            integer     not null,
+         recipient_user_id        integer     not null,
+         plan_key                 text        not null,
+         plan_name                text        not null,
+         group_key                text        not null,
+         amount_minor             integer     not null,
+         currency                 text        not null,
+         billing_mode             text        not null,
+         period_spec              text,
+         status                   text        not null default 'created',
+         needs_attention          text,
+         idempotency_key          text        not null,
+         stripe_session_id        text,
+         stripe_subscription_id   text,
+         stripe_payment_intent_id text,
+         checkout_url             text,
+         created_at               timestamptz not null default now(),
+         settled_at               timestamptz
+       )`,
+      `create unique index if not exists plugin_dues_order_idem_key
+         on plugin_dues_order (idempotency_key)`,
+      `create unique index if not exists plugin_dues_order_session_key
+         on plugin_dues_order (stripe_session_id)
+         where stripe_session_id is not null`,
+      `create index if not exists plugin_dues_order_pending_idx
+         on plugin_dues_order (created_at)
+         where status in ('created', 'pending')`,
+      `create index if not exists plugin_dues_order_buyer_idx
+         on plugin_dues_order (buyer_user_id)`,
+    ],
+  },
+  {
+    id: '0002_memberships_events_ledger',
+    statements: [
+      `create table if not exists plugin_dues_membership (
+         id                     bigint generated by default as identity primary key,
+         user_id                integer     not null,
+         group_key              text        not null,
+         plan_key               text        not null,
+         status                 text        not null,
+         renewal_mode           text        not null,
+         current_period_end     timestamptz not null,
+         grace_until            timestamptz not null,
+         needs_attention        text,
+         stripe_subscription_id text,
+         last_order_id          bigint,
+         created_at             timestamptz not null default now(),
+         updated_at             timestamptz not null default now()
+       )`,
+      `create unique index if not exists plugin_dues_membership_live_key
+         on plugin_dues_membership (user_id, group_key)
+         where status in ('active', 'grace', 'closing')`,
+      `create index if not exists plugin_dues_membership_subscription_idx
+         on plugin_dues_membership (stripe_subscription_id)
+         where stripe_subscription_id is not null`,
+      `create index if not exists plugin_dues_membership_due_idx
+         on plugin_dues_membership (grace_until)
+         where status in ('active', 'grace', 'closing')`,
+      `create table if not exists plugin_dues_event (
+         id              bigint generated by default as identity primary key,
+         stripe_event_id text        not null,
+         type            text        not null,
+         payload         jsonb       not null,
+         received_at     timestamptz not null default now(),
+         processed_at    timestamptz,
+         outcome         text
+       )`,
+      `create unique index if not exists plugin_dues_event_stripe_key
+         on plugin_dues_event (stripe_event_id)`,
+      `create index if not exists plugin_dues_event_unprocessed_idx
+         on plugin_dues_event (received_at)
+         where processed_at is null`,
+      `create table if not exists plugin_dues_ledger (
+         id            bigint generated by default as identity primary key,
+         occurred_at   timestamptz not null default now(),
+         kind          text        not null,
+         user_id       integer     not null,
+         membership_id bigint,
+         order_id      bigint,
+         amount_minor  integer     not null,
+         currency      text        not null,
+         stripe_ref    text,
+         note          text
+       )`,
+      `create index if not exists plugin_dues_ledger_time_idx
+         on plugin_dues_ledger (occurred_at)`,
+    ],
+  },
+  {
+    id: '0003_discount_codes',
+    statements: [
+      `create table if not exists plugin_dues_code (
+         id                 bigint generated by default as identity primary key,
+         code               text        not null,
+         percent_off        integer     not null,
+         plan_key           text,
+         max_redemptions    integer,
+         redeemed_count     integer     not null default 0,
+         expires_at         timestamptz,
+         disabled           boolean     not null default false,
+         created_by_user_id integer     not null,
+         stripe_coupon_id   text,
+         created_at         timestamptz not null default now()
+       )`,
+      `create unique index if not exists plugin_dues_code_key
+         on plugin_dues_code (lower(code))`,
+      `alter table plugin_dues_order add column if not exists code_id bigint`,
+      `alter table plugin_dues_order add column if not exists discount_minor integer not null default 0`,
+    ],
+  },
+  {
+    id: '0004_plans',
+    statements: [
+      `create table if not exists plugin_dues_plan (
+         id                bigint generated by default as identity primary key,
+         plan_key          text        not null,
+         name              text        not null,
+         description       text,
+         group_key         text        not null,
+         price_minor       integer     not null,
+         currency          text        not null,
+         mode              text        not null,
+         period_spec       text,
+         billing_interval  text,
+         stripe_price_id   text,
+         stripe_product_id text,
+         giftable          boolean     not null default true,
+         hidden            boolean     not null default false,
+         archived          boolean     not null default false,
+         created_at        timestamptz not null default now(),
+         updated_at        timestamptz not null default now()
+       )`,
+      `create unique index if not exists plugin_dues_plan_key
+         on plugin_dues_plan (plan_key)`,
+    ],
+  },
+]