adonia 0.1.0

package/registry/subscription/service.ts

@@ -0,0 +1,140 @@
+/**
+ * SubscriptionService
+ *
+ * Generic subscription state + Creem webhook sync.
+ * Every webhook handler upserts (idempotent, order-independent).
+ * Plan default comes from CreemService.defaultPlan.
+ */
+import ApiService from '#modules/api/service'
+import type { CreemService } from '#modules/creem/service'
+import type {
+  Subscription,
+  SubscriptionConfig,
+  SubscriptionSnapshot,
+  SubscriptionStore,
+} from '#modules/subscription/contracts/index'
+import { defaultSubscriptionOptions } from '#modules/subscription/options'
+import '#modules/subscription/events'
+
+export class SubscriptionService extends ApiService {
+  namespace = 'subscription'
+
+  private activeStatuses: string[]
+
+  constructor(
+    private subscriptions: SubscriptionStore,
+    private creem: CreemService,
+    config: SubscriptionConfig = {}
+  ) {
+    super()
+    this.activeStatuses = config.activeStatuses ?? defaultSubscriptionOptions.activeStatuses
+  }
+
+  /**
+   * Returns the user's current subscription record, or null if none exists.
+   */
+  async getSubscription(userId: number): Promise<Subscription | null> {
+    return this.subscriptions.findCurrentByUserId(userId)
+  }
+
+  /**
+   * Resolves the plan key via Creem product→plan map when the subscription
+   * is active; otherwise returns CreemService.defaultPlan.
+   */
+  async getUserPlan(userId: number): Promise<string> {
+    const sub = await this.getSubscription(userId)
+    if (!sub || !this.activeStatuses.includes(sub.status)) {
+      return this.creem.defaultPlan
+    }
+    return this.creem.resolveProductPlan(sub.creemProductId)
+  }
+
+  /**
+   * Billing period start. Without a subscription, uses start of the current UTC month.
+   */
+  async getCurrentPeriodStart(userId: number): Promise<Date> {
+    const sub = await this.getSubscription(userId)
+    if (sub?.currentPeriodStart) {
+      return sub.currentPeriodStart
+    }
+    const now = new Date()
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1))
+  }
+
+  /**
+   * True when the user has a subscription in an active status.
+   */
+  async isActive(userId: number): Promise<boolean> {
+    const sub = await this.subscriptions.findActiveByUserId(userId, this.activeStatuses)
+    return sub !== null
+  }
+
+  /**
+   * Processes a Creem webhook. SDK verifies signature; every handler upserts.
+   */
+  async syncFromWebhook(rawBody: string, signature: string): Promise<void> {
+    await this.creem.handleWebhookEvents(rawBody, signature, {
+      onGrantAccess: async (context) => {
+        const snapshot = this.toSnapshot(context)
+        if (!snapshot) return
+        await this.subscriptions.upsert(snapshot)
+        this.emitSafe('Subscription:Activated', { userId: snapshot.userId })
+      },
+
+      onRevokeAccess: async (context) => {
+        const snapshot = this.toSnapshot(context)
+        if (!snapshot) return
+        await this.subscriptions.upsert(snapshot)
+        this.emitSafe('Subscription:Revoked', { userId: snapshot.userId })
+      },
+
+      onSubscriptionCanceled: async (data) => {
+        const snapshot = this.toSnapshot(data)
+        if (!snapshot) return
+        await this.subscriptions.upsert(snapshot)
+        this.emitSafe('Subscription:Canceled', { userId: snapshot.userId })
+      },
+
+      onSubscriptionScheduledCancel: async (data) => {
+        const snapshot = this.toSnapshot(data)
+        if (!snapshot) return
+        await this.subscriptions.upsert(snapshot)
+        this.emitSafe('Subscription:ScheduledCancel', { userId: snapshot.userId })
+      },
+
+      onSubscriptionUpdate: async (data) => {
+        const snapshot = this.toSnapshot(data)
+        if (!snapshot) return
+        await this.subscriptions.upsert(snapshot)
+        this.emitSafe('Subscription:Updated', { userId: snapshot.userId })
+      },
+
+      onRefundCreated: async (data) => {
+        this.emitSafe('Subscription:RefundCreated', { refundId: String(data?.id ?? '') })
+      },
+    })
+  }
+
+  /**
+   * Maps a Creem webhook payload into a store snapshot.
+   * Requires metadata.userId (set at checkout).
+   */
+  private toSnapshot(payload: any): SubscriptionSnapshot | null {
+    const userId = Number(payload?.metadata?.userId)
+    if (!userId || Number.isNaN(userId)) {
+      return null
+    }
+
+    return {
+      id: String(payload.id),
+      userId,
+      customerId: String(payload.customer.id),
+      productId: String(payload.product.id),
+      productName: String(payload.product.name),
+      status: String(payload.status),
+      currentPeriodStart: new Date(payload.currentPeriodStartDate),
+      currentPeriodEnd: new Date(payload.currentPeriodEndDate),
+      canceledAt: payload.canceledAt ? new Date(payload.canceledAt) : null,
+    }
+  }
+}

package/registry/subscription/stubs/adapters/lucid_subscription_store.ts

@@ -0,0 +1,69 @@
+/**
+ * Lucid SubscriptionStore. Copied to app/adapters/lucid_subscription_store.ts.
+ * Expects a Subscription model at #models/subscription.
+ */
+import { DateTime } from 'luxon'
+import SubscriptionModel from '#models/subscription'
+import type {
+  Subscription,
+  SubscriptionSnapshot,
+  SubscriptionStore,
+} from '#modules/subscription/contracts/index'
+
+function toSubscription(row: InstanceType<typeof SubscriptionModel>): Subscription {
+  return {
+    id: row.id,
+    userId: row.userId,
+    creemCustomerId: row.creemCustomerId,
+    creemSubscriptionId: row.creemSubscriptionId,
+    creemProductId: row.creemProductId,
+    plan: row.plan,
+    status: row.status,
+    currentPeriodStart: row.currentPeriodStart?.toJSDate() ?? null,
+    currentPeriodEnd: row.currentPeriodEnd?.toJSDate() ?? null,
+    canceledAt: row.canceledAt?.toJSDate() ?? null,
+  }
+}
+
+function period(date: Date) {
+  return DateTime.fromJSDate(date)
+}
+
+export class LucidSubscriptionStore implements SubscriptionStore {
+  async findCurrentByUserId(userId: number): Promise<Subscription | null> {
+    const row = await SubscriptionModel.query()
+      .where('userId', userId)
+      .orderBy('currentPeriodEnd', 'desc')
+      .first()
+    return row ? toSubscription(row) : null
+  }
+
+  async findActiveByUserId(
+    userId: number,
+    activeStatuses: string[]
+  ): Promise<Subscription | null> {
+    const row = await SubscriptionModel.query()
+      .where('userId', userId)
+      .whereIn('status', activeStatuses)
+      .orderBy('currentPeriodEnd', 'desc')
+      .first()
+    return row ? toSubscription(row) : null
+  }
+
+  async upsert(snapshot: SubscriptionSnapshot): Promise<void> {
+    await SubscriptionModel.updateOrCreate(
+      { userId: snapshot.userId, creemSubscriptionId: snapshot.id },
+      {
+        userId: snapshot.userId,
+        creemCustomerId: snapshot.customerId,
+        creemSubscriptionId: snapshot.id,
+        creemProductId: snapshot.productId,
+        plan: snapshot.productName,
+        status: snapshot.status,
+        currentPeriodStart: period(snapshot.currentPeriodStart),
+        currentPeriodEnd: period(snapshot.currentPeriodEnd),
+        canceledAt: snapshot.canceledAt ? period(snapshot.canceledAt) : null,
+      }
+    )
+  }
+}

package/registry/subscription/stubs/adapters/subscription.ts

@@ -0,0 +1,21 @@
+/**
+ * Host Lucid factory for subscriptions. Copied to app/adapters/subscription.ts.
+ * Import as `#adapters/subscription`.
+ */
+import { SubscriptionService } from '#modules/subscription/service'
+import { LucidSubscriptionStore } from './lucid_subscription_store.ts'
+import type { CreemService } from '#modules/creem/service'
+import type {
+  SubscriptionConfig,
+  SubscriptionStore,
+} from '#modules/subscription/contracts/index'
+
+export { LucidSubscriptionStore } from './lucid_subscription_store.ts'
+
+export function createSubscriptionService(
+  creem: CreemService,
+  store: SubscriptionStore = new LucidSubscriptionStore(),
+  config: SubscriptionConfig = {}
+) {
+  return new SubscriptionService(store, creem, config)
+}

package/registry/subscription/stubs/migrations/create_subscriptions_table.ts

@@ -0,0 +1,26 @@
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'subscriptions'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.increments('id').primary().notNullable()
+      table.integer('user_id').references('id').inTable('users').onDelete('CASCADE')
+      table.string('creem_customer_id').notNullable()
+      table.string('creem_subscription_id').unique()
+      table.string('creem_product_id').notNullable()
+      table.string('plan').notNullable()
+      table.string('status').notNullable()
+      table.timestamp('current_period_start')
+      table.timestamp('current_period_end')
+      table.timestamp('canceled_at')
+      table.timestamp('created_at')
+      table.timestamp('updated_at')
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}

package/registry/subscription/stubs/migrations/subscriptions_user_creem_unique.ts

@@ -0,0 +1,19 @@
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'subscriptions'
+
+  async up() {
+    this.schema.alterTable(this.tableName, (table) => {
+      table.dropUnique(['creem_subscription_id'])
+      table.unique(['user_id', 'creem_subscription_id'])
+    })
+  }
+
+  async down() {
+    this.schema.alterTable(this.tableName, (table) => {
+      table.dropUnique(['user_id', 'creem_subscription_id'])
+      table.unique(['creem_subscription_id'])
+    })
+  }
+}

package/registry/subscription/stubs/models/subscription.ts

@@ -0,0 +1,45 @@
+import { DateTime } from 'luxon'
+import { BaseModel, belongsTo, column } from '@adonisjs/lucid/orm'
+import type { BelongsTo } from '@adonisjs/lucid/types/relations'
+import User from '#models/user'
+
+export default class Subscription extends BaseModel {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare userId: number
+
+  @column()
+  declare creemCustomerId: string
+
+  @column()
+  declare creemSubscriptionId: string | null
+
+  @column()
+  declare creemProductId: string
+
+  @column()
+  declare plan: string
+
+  @column()
+  declare status: string
+
+  @column.dateTime()
+  declare currentPeriodStart: DateTime | null
+
+  @column.dateTime()
+  declare currentPeriodEnd: DateTime | null
+
+  @column.dateTime()
+  declare canceledAt: DateTime | null
+
+  @column.dateTime({ autoCreate: true })
+  declare createdAt: DateTime
+
+  @column.dateTime({ autoCreate: true, autoUpdate: true })
+  declare updatedAt: DateTime
+
+  @belongsTo(() => User)
+  declare user: BelongsTo<typeof User>
+}

package/registry/subscription/tests/billing_service.spec.ts

@@ -0,0 +1,189 @@
+import { test } from '@japa/runner'
+import assert from 'node:assert/strict'
+import { CreemService } from '#modules/creem/service'
+import { SubscriptionService } from '#modules/subscription/service'
+import { FakeCreemClient, makeNormalizedSub } from '#modules/creem/tests/fakes/fake_creem_client'
+import { MemorySubscriptionStore } from '#modules/subscription/tests/fakes/memory_subscription_store'
+
+function makeBilling(productPlans: Record<string, string> = { prod_pro: 'pro' }) {
+  const client = new FakeCreemClient()
+  const creem = new CreemService(client, {
+    successUrl: 'https://app.test/success',
+    productPlans,
+    defaultPlan: 'starter',
+  })
+  const store = new MemorySubscriptionStore()
+  const subscriptions = new SubscriptionService(store, creem)
+  const emissions: Array<{ event: string; payload: any }> = []
+  ;(creem as any).emitSafe = async () => {}
+  ;(subscriptions as any).emitSafe = async (event: string, payload: any) => {
+    emissions.push({ event, payload })
+  }
+  return { client, creem, store, subscriptions, emissions }
+}
+
+test.group('CreemService - resolveProductPlan', () => {
+  test('maps known products and falls back to defaultPlan', async () => {
+    const { creem } = makeBilling({ prod_pro: 'pro' })
+    assert.equal(creem.resolveProductPlan('prod_pro'), 'pro')
+    assert.equal(creem.resolveProductPlan('prod_unknown'), 'starter')
+    assert.equal(creem.defaultPlan, 'starter')
+  })
+})
+
+test.group('SubscriptionService - getUserPlan', () => {
+  test('no subscription returns defaultPlan', async () => {
+    const { subscriptions } = makeBilling()
+    assert.equal(await subscriptions.getUserPlan(1), 'starter')
+  })
+
+  test('inactive subscription returns defaultPlan', async () => {
+    const { subscriptions, store } = makeBilling()
+    await store.upsert({
+      id: 'sub_1',
+      userId: 1,
+      customerId: 'c',
+      productId: 'prod_pro',
+      productName: 'Pro',
+      status: 'canceled',
+      currentPeriodStart: new Date('2024-01-01'),
+      currentPeriodEnd: new Date('2024-02-01'),
+      canceledAt: new Date('2024-01-15'),
+    })
+    assert.equal(await subscriptions.getUserPlan(1), 'starter')
+  })
+
+  test('active mapped product returns plan', async () => {
+    const { subscriptions, store } = makeBilling()
+    await store.upsert({
+      id: 'sub_1',
+      userId: 1,
+      customerId: 'c',
+      productId: 'prod_pro',
+      productName: 'Pro',
+      status: 'active',
+      currentPeriodStart: new Date('2024-01-01'),
+      currentPeriodEnd: new Date('2024-02-01'),
+      canceledAt: null,
+    })
+    assert.equal(await subscriptions.getUserPlan(1), 'pro')
+  })
+
+  test('active unmapped product returns defaultPlan', async () => {
+    const { subscriptions, store } = makeBilling()
+    await store.upsert({
+      id: 'sub_1',
+      userId: 1,
+      customerId: 'c',
+      productId: 'prod_unknown',
+      productName: 'X',
+      status: 'active',
+      currentPeriodStart: new Date('2024-01-01'),
+      currentPeriodEnd: new Date('2024-02-01'),
+      canceledAt: null,
+    })
+    assert.equal(await subscriptions.getUserPlan(1), 'starter')
+  })
+})
+
+test.group('SubscriptionService - syncFromWebhook', () => {
+  test('payload without metadata.userId is ignored', async () => {
+    const { client, subscriptions, store, emissions } = makeBilling()
+    client.nextHandler = {
+      name: 'onGrantAccess',
+      payload: makeNormalizedSub({ metadata: {} }),
+    }
+    await subscriptions.syncFromWebhook('body', 'sig')
+    assert.equal(store.rows.length, 0)
+    assert.equal(emissions.length, 0)
+  })
+
+  test('grant upserts and emits Activated', async () => {
+    const { client, subscriptions, store, emissions } = makeBilling()
+    client.nextHandler = {
+      name: 'onGrantAccess',
+      payload: makeNormalizedSub({ status: 'active' }),
+    }
+    await subscriptions.syncFromWebhook('body', 'sig')
+    assert.equal(store.rows.length, 1)
+    assert.equal(emissions[0]?.event, 'Subscription:Activated')
+  })
+
+  test('revoke, cancel, scheduled cancel, and update each upsert and emit', async () => {
+    const cases = [
+      ['onRevokeAccess', 'Subscription:Revoked'],
+      ['onSubscriptionCanceled', 'Subscription:Canceled'],
+      ['onSubscriptionScheduledCancel', 'Subscription:ScheduledCancel'],
+      ['onSubscriptionUpdate', 'Subscription:Updated'],
+    ] as const
+
+    for (const [handler, event] of cases) {
+      const { client, subscriptions, store, emissions } = makeBilling()
+      client.nextHandler = {
+        name: handler,
+        payload: makeNormalizedSub({ status: 'canceled', id: `sub_${handler}` }),
+      }
+      await subscriptions.syncFromWebhook('body', 'sig')
+      assert.equal(store.rows.length, 1, handler)
+      assert.equal(emissions[0]?.event, event, handler)
+    }
+  })
+
+  test('delivering the same webhook twice produces one row', async () => {
+    const { client, subscriptions, store } = makeBilling()
+    const payload = makeNormalizedSub()
+    client.nextHandler = { name: 'onGrantAccess', payload }
+    await subscriptions.syncFromWebhook('body', 'sig')
+    await subscriptions.syncFromWebhook('body', 'sig')
+    assert.equal(store.rows.length, 1)
+  })
+
+  test('update before grant_access produces one row in the updated state', async () => {
+    const { client, subscriptions, store } = makeBilling()
+    client.nextHandler = {
+      name: 'onSubscriptionUpdate',
+      payload: makeNormalizedSub({ status: 'active', product: { id: 'prod_pro', name: 'Pro' } }),
+    }
+    await subscriptions.syncFromWebhook('body', 'sig')
+    client.nextHandler = {
+      name: 'onGrantAccess',
+      payload: makeNormalizedSub({
+        status: 'trialing',
+        product: { id: 'prod_pro', name: 'Pro Trial' },
+      }),
+    }
+    await subscriptions.syncFromWebhook('body', 'sig')
+    assert.equal(store.rows.length, 1)
+    assert.equal(store.rows[0].status, 'trialing')
+    assert.equal(store.rows[0].plan, 'Pro Trial')
+  })
+
+  test('canceled older row plus newer active resolves to active plan', async () => {
+    const { subscriptions, store } = makeBilling()
+    await store.upsert({
+      id: 'sub_old',
+      userId: 1,
+      customerId: 'c',
+      productId: 'prod_pro',
+      productName: 'Pro',
+      status: 'canceled',
+      currentPeriodStart: new Date('2023-01-01'),
+      currentPeriodEnd: new Date('2023-02-01'),
+      canceledAt: new Date('2023-01-15'),
+    })
+    await store.upsert({
+      id: 'sub_new',
+      userId: 1,
+      customerId: 'c',
+      productId: 'prod_pro',
+      productName: 'Pro',
+      status: 'active',
+      currentPeriodStart: new Date('2024-01-01'),
+      currentPeriodEnd: new Date('2024-02-01'),
+      canceledAt: null,
+    })
+    assert.equal(await subscriptions.getUserPlan(1), 'pro')
+    const current = await subscriptions.getSubscription(1)
+    assert.equal(current?.creemSubscriptionId, 'sub_new')
+  })
+})

package/registry/subscription/tests/fakes/memory_subscription_store.ts

@@ -0,0 +1,63 @@
+import type {
+  Subscription,
+  SubscriptionSnapshot,
+  SubscriptionStore,
+} from '#modules/subscription/contracts/index'
+
+/**
+ * In-memory SubscriptionStore. upsert keys on (userId, creemSubscriptionId).
+ */
+export class MemorySubscriptionStore implements SubscriptionStore {
+  rows: Subscription[] = []
+  upserts: SubscriptionSnapshot[] = []
+  nextId = 1
+
+  async findCurrentByUserId(userId: number): Promise<Subscription | null> {
+    const matches = this.rows
+      .filter((row) => row.userId === userId)
+      .sort((a, b) => {
+        const aEnd = a.currentPeriodEnd?.getTime() ?? 0
+        const bEnd = b.currentPeriodEnd?.getTime() ?? 0
+        return bEnd - aEnd
+      })
+    return matches[0] ?? null
+  }
+
+  async findActiveByUserId(
+    userId: number,
+    activeStatuses: string[]
+  ): Promise<Subscription | null> {
+    const matches = this.rows
+      .filter((row) => row.userId === userId && activeStatuses.includes(row.status))
+      .sort((a, b) => {
+        const aEnd = a.currentPeriodEnd?.getTime() ?? 0
+        const bEnd = b.currentPeriodEnd?.getTime() ?? 0
+        return bEnd - aEnd
+      })
+    return matches[0] ?? null
+  }
+
+  async upsert(snapshot: SubscriptionSnapshot): Promise<void> {
+    this.upserts.push(snapshot)
+    const index = this.rows.findIndex(
+      (row) => row.userId === snapshot.userId && row.creemSubscriptionId === snapshot.id
+    )
+    const next: Subscription = {
+      id: index >= 0 ? this.rows[index].id : this.nextId++,
+      userId: snapshot.userId,
+      creemCustomerId: snapshot.customerId,
+      creemSubscriptionId: snapshot.id,
+      creemProductId: snapshot.productId,
+      plan: snapshot.productName,
+      status: snapshot.status,
+      currentPeriodStart: snapshot.currentPeriodStart,
+      currentPeriodEnd: snapshot.currentPeriodEnd,
+      canceledAt: snapshot.canceledAt,
+    }
+    if (index >= 0) {
+      this.rows[index] = next
+    } else {
+      this.rows.push(next)
+    }
+  }
+}

package/registry/types/api.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared API response envelope types for the starter core.
+ * Runtime helpers live in modules/api/envelope.ts.
+ *
+ * Controllers (and hosts) build these envelopes. Domain services return DTOs.
+ */
+
+export interface PaginationMeta {
+  total: number
+  page: number
+  pageSize: number
+  totalPages: number
+}
+
+export interface ApiResponse<T> {
+  data: T
+  message: string | null
+  success: boolean
+  meta?: PaginationMeta
+}
+
+export type ApiErrorBody = {
+  success: false
+  message: string
+  status?: number
+  errors?: unknown
+}
+
+export type ApiResult<T> =
+  | { success: true; data: T; message: string | null; meta?: PaginationMeta }
+  | ApiErrorBody
+
+/**
+ * Paginated success envelope — same shape as ApiResponse with required meta.
+ */
+export type PaginatedResponse<T> = ApiResponse<T[]> & { meta: PaginationMeta }
+
+export interface PaginationParams {
+  page?: number
+  pageSize?: number
+}

package/registry/types/constants.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared shape for exception and success response code constants.
+ */
+export type StatusCodeEntry = {
+  status: number
+  code: string
+}

package/registry/types/index.ts

@@ -0,0 +1,6 @@
+import * as ModelsTypes from './models.ts'
+import * as ApiTypes from './api.ts'
+import type { StatusCodeEntry } from './constants.ts'
+
+export type { StatusCodeEntry }
+export { ModelsTypes, ApiTypes }

package/registry/types/models.ts

@@ -0,0 +1,32 @@
+import { DateTime } from 'luxon'
+
+export type ModuleActionConfig = {
+  description: string
+  /** Event names enabled for emitSafe. Filled from each module's events list. */
+  emits: string[]
+}
+
+export type NameSpace = null | string
+
+export type ModularModel<T> = {
+  nameSpace: NameSpace
+} & T
+
+export interface IUserModel {
+  id: number
+  authMethod: 'github' | 'google' | 'email'
+  email: string
+  pendingEmail: string | null
+  firstName: string
+  lastName: string
+  avatarKey: string | null
+  password: string | null
+  emailVerificationToken: string | null
+  createdAt: DateTime
+  updatedAt: DateTime | null
+  emailVerifiedAt: DateTime | null
+  verifyEmail(): void
+  generateVerificationToken(): void
+  get name(): string
+  get avatar(): string
+}