adonia 0.1.0

package/registry/creem/tests/fakes/fake_creem_client.ts

@@ -0,0 +1,68 @@
+import type {
+  CreemClient,
+  CreemInvoice,
+  CreemWebhookHandlers,
+} from '#modules/creem/contracts/index'
+
+type CheckoutInput = {
+  successUrl: string
+  productId: string
+  customerEmail: string
+  userId: number
+}
+
+/**
+ * Fake CreemClient. handleWebhookEvents invokes a named handler with canned data.
+ */
+export class FakeCreemClient implements CreemClient {
+  checkouts: CheckoutInput[] = []
+  portalCalls: string[] = []
+  listCalls: Array<{ customerId: string; limit: number }> = []
+  checkoutUrl: string | null = 'https://pay.creem.io/checkout/1'
+  portalUrl = 'https://portal.creem.io/1'
+  invoices: CreemInvoice[] = []
+
+  /** When set, handleWebhookEvents calls this handler name with handlerPayload. */
+  nextHandler: { name: string; payload: any } | null = null
+
+  async createCheckout(input: CheckoutInput) {
+    this.checkouts.push(input)
+    return { checkoutUrl: this.checkoutUrl }
+  }
+
+  async createPortalLink(customerId: string) {
+    this.portalCalls.push(customerId)
+    return { portalUrl: this.portalUrl }
+  }
+
+  async listTransactions(customerId: string, limit: number) {
+    this.listCalls.push({ customerId, limit })
+    return { items: this.invoices }
+  }
+
+  async handleWebhookEvents(
+    _rawBody: string,
+    _signature: string,
+    handlers: CreemWebhookHandlers
+  ) {
+    if (!this.nextHandler) return
+    const fn = handlers[this.nextHandler.name]
+    if (fn) {
+      await fn(this.nextHandler.payload)
+    }
+  }
+}
+
+export function makeNormalizedSub(overrides: Record<string, any> = {}) {
+  return {
+    id: 'sub_123',
+    status: 'active',
+    metadata: { userId: '1' },
+    customer: { id: 'cust_123' },
+    product: { id: 'prod_123', name: 'Pro' },
+    currentPeriodStartDate: '2024-01-01T00:00:00.000Z',
+    currentPeriodEndDate: '2024-02-01T00:00:00.000Z',
+    canceledAt: null,
+    ...overrides,
+  }
+}

package/registry/notification/contracts/app_notification_store.ts

@@ -0,0 +1,8 @@
+import type { AppNotificationData } from './types.ts'
+
+/**
+ * Persist in-app notifications. Host wires Lucid / Drizzle / etc.
+ */
+export interface AppNotificationStore {
+  create(data: AppNotificationData): Promise<void>
+}

package/registry/notification/contracts/index.ts

@@ -0,0 +1,9 @@
+export type {
+  NotificationChannel,
+  AppNotificationData,
+  NotificationDefinition,
+  NotificationRegistry,
+} from './types.ts'
+
+export type { MailTransport } from './mail_transport.ts'
+export type { AppNotificationStore } from './app_notification_store.ts'

package/registry/notification/contracts/mail_transport.ts

@@ -0,0 +1,7 @@
+/**
+ * Outbound email. Host wires Adonis Mail, Resend, SES, etc.
+ * Message type is opaque so this contract stays mailer-agnostic.
+ */
+export interface MailTransport {
+  sendLater(message: unknown): Promise<void>
+}

package/registry/notification/contracts/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Notification channel + registry types.
+ * Concrete notification types and mail classes stay host-owned.
+ */
+
+export type NotificationChannel = 'email' | 'app'
+
+/**
+ * Payload written to the in-app notifications store.
+ */
+export type AppNotificationData = {
+  userId: number
+  type: string
+  title: string
+  body: string
+  data?: Record<string, any>
+}
+
+/**
+ * Per-type handlers. Email returns an opaque message for MailTransport;
+ * app returns the row shape for AppNotificationStore.
+ */
+export type NotificationDefinition = {
+  email?: (payload: Record<string, any>) => unknown
+  app?: (payload: Record<string, any>) => AppNotificationData
+}
+
+/**
+ * Host-supplied map of notification type → channel handlers.
+ * Keys are free-form strings (e.g. 'verify_email', 'welcome').
+ */
+export type NotificationRegistry = Record<string, NotificationDefinition>

package/registry/notification/module.json

@@ -0,0 +1,23 @@
+{
+  "name": "notification",
+  "description": "Multi-channel notification dispatcher with host-supplied registry",
+  "files": [
+    "service.ts",
+    "options.ts",
+    "contracts/**",
+    "module.json"
+  ],
+  "stubs": [
+    "stubs/models/app_notification.ts",
+    "stubs/migrations/*.ts",
+    "stubs/adapters/**/*"
+  ],
+  "dependencies": {},
+  "registryDependencies": ["api"],
+  "peerModels": ["#models/app_notification"],
+  "configKeys": [],
+  "env": [],
+  "events": [],
+  "hostFacingExceptions": [],
+  "hostTests": []
+}

package/registry/notification/options.ts

@@ -0,0 +1,11 @@
+import type { NotificationChannel } from '#modules/notification/contracts/index'
+
+/**
+ * Constructor options for NotificationService.
+ */
+export type NotificationServiceOptions = {
+  /** Called when a channel has no handler for the given type. Default: no-op. */
+  onWarn?: (message: string) => void
+  /** Called when a channel handler throws. Default: no-op. */
+  onError?: (channel: NotificationChannel, type: string, error: unknown) => void
+}

package/registry/notification/service.ts

@@ -0,0 +1,103 @@
+/**
+ * NotificationService
+ *
+ * Channel-agnostic dispatcher. Resolves handlers from a host-supplied registry
+ * and fans out to email / in-app transports.
+ *
+ * Infrastructure (not a domain service) — intentionally does not extend
+ * ApiService. Does not own notification types, mail templates, or preferences.
+ */
+import type {
+  AppNotificationStore,
+  MailTransport,
+  NotificationChannel,
+  NotificationRegistry,
+} from '#modules/notification/contracts/index'
+import type { NotificationServiceOptions } from '#modules/notification/options'
+
+export type ChannelSendStatus = 'sent' | 'skipped' | 'failed'
+export type { NotificationServiceOptions } from '#modules/notification/options'
+
+export class NotificationService<R extends NotificationRegistry = NotificationRegistry> {
+  private readonly onWarn: (message: string) => void
+  private readonly onError: (
+    channel: NotificationChannel,
+    type: string,
+    error: unknown
+  ) => void
+
+  constructor(
+    private registry: R,
+    private mail: MailTransport,
+    private appNotifications: AppNotificationStore,
+    options: NotificationServiceOptions = {}
+  ) {
+    this.onWarn = options.onWarn ?? (() => {})
+    this.onError = options.onError ?? (() => {})
+  }
+
+  /**
+   * Dispatch to the requested channels in parallel.
+   * Channel failures are isolated and reported via onError + the return map.
+   */
+  async send<K extends keyof R & string>(
+    type: K,
+    channels: NotificationChannel[],
+    payload: Record<string, any>
+  ): Promise<Record<NotificationChannel, ChannelSendStatus>> {
+    const status: Record<NotificationChannel, ChannelSendStatus> = {
+      email: 'skipped',
+      app: 'skipped',
+    }
+
+    await Promise.all(
+      [...new Set(channels)].map(async (channel) => {
+        try {
+          status[channel] = await this.dispatch(channel, type, payload)
+        } catch (error) {
+          this.onError(channel, type, error)
+          status[channel] = 'failed'
+        }
+      })
+    )
+
+    return status
+  }
+
+  private async dispatch(
+    channel: NotificationChannel,
+    type: string,
+    payload: Record<string, any>
+  ): Promise<'sent' | 'skipped'> {
+    if (channel === 'email') {
+      return this.sendEmail(type, payload)
+    }
+    return this.sendApp(type, payload)
+  }
+
+  private async sendEmail(
+    type: string,
+    payload: Record<string, any>
+  ): Promise<'sent' | 'skipped'> {
+    const definition = this.registry[type]
+    if (!definition?.email) {
+      this.onWarn(`No email handler for notification type: ${type}`)
+      return 'skipped'
+    }
+    await this.mail.sendLater(definition.email(payload))
+    return 'sent'
+  }
+
+  private async sendApp(
+    type: string,
+    payload: Record<string, any>
+  ): Promise<'sent' | 'skipped'> {
+    const definition = this.registry[type]
+    if (!definition?.app) {
+      this.onWarn(`No app handler for notification type: ${type}`)
+      return 'skipped'
+    }
+    await this.appNotifications.create(definition.app(payload))
+    return 'sent'
+  }
+}

package/registry/notification/stubs/adapters/adonis_mail_transport.ts

@@ -0,0 +1,15 @@
+/**
+ * Adonis Mail transport. Copied to app/adapters/adonis_mail_transport.ts.
+ * Requires `@adonisjs/mail` (`node ace add @adonisjs/mail`).
+ *
+ * Registry email builders must return whatever `mail.sendLater` accepts
+ * (a BaseMail instance or a message callback).
+ */
+import mail from '@adonisjs/mail/services/main'
+import type { MailTransport } from '#modules/notification/contracts/index'
+
+export class AdonisMailTransport implements MailTransport {
+  async sendLater(message: unknown): Promise<void> {
+    await mail.sendLater(message as Parameters<typeof mail.sendLater>[0])
+  }
+}

package/registry/notification/stubs/adapters/lucid_app_notification_store.ts

@@ -0,0 +1,21 @@
+/**
+ * Lucid AppNotificationStore. Copied to app/adapters/lucid_app_notification_store.ts.
+ * Expects a model at #models/app_notification with userId, type, title, body, data.
+ */
+import AppNotificationModel from '#models/app_notification'
+import type {
+  AppNotificationData,
+  AppNotificationStore,
+} from '#modules/notification/contracts/index'
+
+export class LucidAppNotificationStore implements AppNotificationStore {
+  async create(data: AppNotificationData): Promise<void> {
+    await AppNotificationModel.create({
+      userId: data.userId,
+      type: data.type,
+      title: data.title,
+      body: data.body,
+      data: data.data ?? null,
+    })
+  }
+}

package/registry/notification/stubs/adapters/notification.ts

@@ -0,0 +1,36 @@
+/**
+ * Host factory for notification. Copied to app/adapters/notification.ts.
+ * Import as `#adapters/notification`.
+ *
+ * Defaults to Adonis Mail + Lucid in-app store. Requires
+ * `node ace add @adonisjs/mail` (and Lucid for the app channel).
+ */
+import { NotificationService } from '#modules/notification/service'
+import type { NotificationServiceOptions } from '#modules/notification/options'
+import { AdonisMailTransport } from './adonis_mail_transport.ts'
+import { LucidAppNotificationStore } from './lucid_app_notification_store.ts'
+import type {
+  AppNotificationStore,
+  MailTransport,
+  NotificationRegistry,
+} from '#modules/notification/contracts/index'
+
+export { AdonisMailTransport } from './adonis_mail_transport.ts'
+export { LucidAppNotificationStore } from './lucid_app_notification_store.ts'
+
+export type CreateNotificationServiceOptions = NotificationServiceOptions & {
+  mail?: MailTransport
+  appNotifications?: AppNotificationStore
+}
+
+export function createNotificationService<R extends NotificationRegistry>(
+  registry: R,
+  options: CreateNotificationServiceOptions = {}
+) {
+  return new NotificationService(
+    registry,
+    options.mail ?? new AdonisMailTransport(),
+    options.appNotifications ?? new LucidAppNotificationStore(),
+    { onWarn: options.onWarn, onError: options.onError }
+  )
+}

package/registry/notification/stubs/migrations/create_notifications_table.ts

@@ -0,0 +1,23 @@
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'notifications'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.string('id').primary().unique().notNullable()
+      table.integer('user_id').references('id').inTable('users').onDelete('CASCADE').notNullable()
+      table.string('type').notNullable()
+      table.string('title').notNullable()
+      table.text('body').notNullable()
+      table.json('data').nullable()
+      table.timestamp('read_at').nullable()
+      table.timestamp('created_at')
+      table.timestamp('updated_at')
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}

package/registry/notification/stubs/models/app_notification.ts

@@ -0,0 +1,45 @@
+import { DateTime } from 'luxon'
+import { BaseModel, beforeCreate, belongsTo, column } from '@adonisjs/lucid/orm'
+import type { BelongsTo } from '@adonisjs/lucid/types/relations'
+import { randomUUID } from 'node:crypto'
+import User from '#models/user'
+
+export default class AppNotification extends BaseModel {
+  static selfAssignPrimaryKey = true
+  static table = 'notifications'
+
+  @column({ isPrimary: true })
+  declare id: string
+
+  @column()
+  declare userId: number
+
+  @column()
+  declare type: string
+
+  @column()
+  declare title: string
+
+  @column()
+  declare body: string
+
+  @column()
+  declare data: Record<string, any> | null
+
+  @column.dateTime()
+  declare readAt: DateTime | null
+
+  @column.dateTime({ autoCreate: true })
+  declare createdAt: DateTime
+
+  @column.dateTime({ autoCreate: true, autoUpdate: true })
+  declare updatedAt: DateTime
+
+  @beforeCreate()
+  static assignUuid(model: AppNotification) {
+    model.id = randomUUID()
+  }
+
+  @belongsTo(() => User)
+  declare user: BelongsTo<typeof User>
+}

package/registry/notification/tests/fakes/memory_app_notification_store.ts

@@ -0,0 +1,19 @@
+import type {
+  AppNotificationData,
+  AppNotificationStore,
+} from '#modules/notification/contracts/index'
+
+/**
+ * In-memory AppNotificationStore.
+ */
+export class MemoryAppNotificationStore implements AppNotificationStore {
+  rows: AppNotificationData[] = []
+  throwOnCreate = false
+
+  async create(data: AppNotificationData): Promise<void> {
+    if (this.throwOnCreate) {
+      throw new Error('app notification failure')
+    }
+    this.rows.push({ ...data })
+  }
+}

package/registry/notification/tests/fakes/memory_mail_transport.ts

@@ -0,0 +1,16 @@
+import type { MailTransport } from '#modules/notification/contracts/index'
+
+/**
+ * In-memory MailTransport. Optionally throws to simulate mailer outages.
+ */
+export class MemoryMailTransport implements MailTransport {
+  messages: unknown[] = []
+  throwOnSend = false
+
+  async sendLater(message: unknown): Promise<void> {
+    if (this.throwOnSend) {
+      throw new Error('SMTP failure')
+    }
+    this.messages.push(message)
+  }
+}

package/registry/notification/tests/notification_service.spec.ts

@@ -0,0 +1,63 @@
+import { test } from '@japa/runner'
+import assert from 'node:assert/strict'
+import { NotificationService } from '#modules/notification/service'
+import { MemoryMailTransport } from '#modules/notification/tests/fakes/memory_mail_transport'
+import { MemoryAppNotificationStore } from '#modules/notification/tests/fakes/memory_app_notification_store'
+import type { NotificationRegistry } from '#modules/notification/contracts/index'
+
+const registry = {
+  welcome: {
+    email: (p: Record<string, any>) => ({ to: p.email, template: 'welcome' }),
+  },
+  new_submission: {
+    email: (p: Record<string, any>) => ({ to: p.email }),
+    app: (p: Record<string, any>) => ({
+      userId: p.userId,
+      type: 'new_submission',
+      title: 'New',
+      body: 'Body',
+    }),
+  },
+} as const satisfies NotificationRegistry
+
+test.group('NotificationService', () => {
+  test('send typo is a compile-time error when using a typed registry', async () => {
+    const mail = new MemoryMailTransport()
+    const app = new MemoryAppNotificationStore()
+    const service = new NotificationService(registry, mail, app)
+
+    // @ts-expect-error typo is not a registry key
+    await service.send('typo', ['email'], {})
+
+    const status = await service.send('welcome', ['email'], { email: 'a@test.com' })
+    assert.equal(status.email, 'sent')
+    assert.equal(status.app, 'skipped')
+  })
+
+  test('throwing MailTransport calls onError and returns email failed', async () => {
+    const mail = new MemoryMailTransport()
+    mail.throwOnSend = true
+    const errors: Array<{ channel: string; type: string }> = []
+    const service = new NotificationService(registry, mail, new MemoryAppNotificationStore(), {
+      onError: (channel, type) => errors.push({ channel, type }),
+    })
+
+    const status = await service.send('welcome', ['email'], { email: 'a@test.com' })
+    assert.equal(status.email, 'failed')
+    assert.deepEqual(errors, [{ channel: 'email', type: 'welcome' }])
+  })
+
+  test('dispatches to both channels', async () => {
+    const mail = new MemoryMailTransport()
+    const app = new MemoryAppNotificationStore()
+    const service = new NotificationService(registry, mail, app)
+    const status = await service.send('new_submission', ['email', 'app'], {
+      email: 'a@test.com',
+      userId: 1,
+    })
+    assert.equal(status.email, 'sent')
+    assert.equal(status.app, 'sent')
+    assert.equal(mail.messages.length, 1)
+    assert.equal(app.rows.length, 1)
+  })
+})

package/registry/registry.json

@@ -0,0 +1,4 @@
+{
+  "core": ["api", "types", "constants", "contracts"],
+  "modules": ["auth", "account", "notification", "creem", "subscription"]
+}

package/registry/subscription/contracts/index.ts

@@ -0,0 +1,9 @@
+export type {
+  Subscription,
+  SubscriptionSnapshot,
+  SubscriptionConfig,
+} from './types.ts'
+
+export { DEFAULT_ACTIVE_STATUSES } from '../options.ts'
+
+export type { SubscriptionStore } from './subscription_store.ts'

package/registry/subscription/contracts/subscription_store.ts

@@ -0,0 +1,15 @@
+import type { Subscription, SubscriptionSnapshot } from './types.ts'
+
+/**
+ * Host persistence for subscriptions. Lucid / Drizzle / etc. stay in adapters.
+ */
+export interface SubscriptionStore {
+  /**
+   * Current subscription for the user: the row with the latest currentPeriodEnd.
+   */
+  findCurrentByUserId(userId: number): Promise<Subscription | null>
+
+  findActiveByUserId(userId: number, activeStatuses: string[]): Promise<Subscription | null>
+
+  upsert(snapshot: SubscriptionSnapshot): Promise<void>
+}

package/registry/subscription/contracts/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Portable subscription DTO + webhook snapshot.
+ * Host adapters map persistence models ↔ these shapes.
+ */
+
+export type Subscription = {
+  id: string | number
+  userId: number
+  creemCustomerId: string
+  creemSubscriptionId: string | null
+  creemProductId: string
+  /** Product display name as stored from Creem (informational). */
+  plan: string
+  status: string
+  currentPeriodStart: Date | null
+  currentPeriodEnd: Date | null
+  canceledAt: Date | null
+}
+
+/**
+ * Normalized Creem subscription payload used for upsert.
+ * Mapped from webhook context inside the service — store never sees creem_io types.
+ */
+export type SubscriptionSnapshot = {
+  id: string
+  userId: number
+  customerId: string
+  productId: string
+  productName: string
+  status: string
+  currentPeriodStart: Date
+  currentPeriodEnd: Date
+  canceledAt: Date | null
+}
+
+export type SubscriptionConfig = {
+  /** Statuses treated as entitled. Defaults from options.ts. */
+  activeStatuses?: string[]
+}

package/registry/subscription/events.ts

@@ -0,0 +1,13 @@
+/**
+ * Subscription module events. Import this file so the EventsList augmentation loads.
+ */
+declare module '@adonisjs/core/types' {
+  interface EventsList {
+    'Subscription:Activated': { userId: number }
+    'Subscription:Revoked': { userId: number }
+    'Subscription:Canceled': { userId: number }
+    'Subscription:ScheduledCancel': { userId: number }
+    'Subscription:Updated': { userId: number }
+    'Subscription:RefundCreated': { refundId: string }
+  }
+}

package/registry/subscription/module.json

@@ -0,0 +1,31 @@
+{
+  "name": "subscription",
+  "description": "Subscription state synced from Creem webhooks",
+  "files": [
+    "service.ts",
+    "events.ts",
+    "options.ts",
+    "contracts/**",
+    "module.json"
+  ],
+  "stubs": [
+    "stubs/models/subscription.ts",
+    "stubs/migrations/*.ts",
+    "stubs/adapters/**/*"
+  ],
+  "dependencies": {},
+  "registryDependencies": ["api", "creem"],
+  "peerModels": ["#models/subscription"],
+  "configKeys": ["modules.subscription"],
+  "env": [],
+  "events": [
+    "Subscription:Activated",
+    "Subscription:Revoked",
+    "Subscription:Canceled",
+    "Subscription:ScheduledCancel",
+    "Subscription:Updated",
+    "Subscription:RefundCreated"
+  ],
+  "hostFacingExceptions": [],
+  "hostTests": ["tests/integration/lucid_adapters.spec.ts"]
+}

package/registry/subscription/options.ts

@@ -0,0 +1,14 @@
+/**
+ * Host-editable defaults for SubscriptionService.
+ */
+export type SubscriptionOptions = {
+  /** Statuses treated as entitled. */
+  activeStatuses: string[]
+}
+
+export const defaultSubscriptionOptions: SubscriptionOptions = {
+  activeStatuses: ['active', 'trialing', 'scheduled_cancel'],
+}
+
+/** @deprecated Prefer defaultSubscriptionOptions.activeStatuses */
+export const DEFAULT_ACTIVE_STATUSES = defaultSubscriptionOptions.activeStatuses