@open-mercato/onboarding 0.4.2-canary-c02407ff85

package/dist/modules/onboarding/migrations/Migration20260112142945.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/onboarding/migrations/Migration20260112142945.ts"],
+  "sourcesContent": ["import { Migration } from '@mikro-orm/migrations';\n\nexport class Migration20260112142945 extends Migration {\n\n  override async up(): Promise<void> {\n    this.addSql(`create table \"onboarding_requests\" (\"id\" uuid not null default gen_random_uuid(), \"email\" text not null, \"token_hash\" text not null, \"status\" text not null default 'pending', \"first_name\" text not null, \"last_name\" text not null, \"organization_name\" text not null, \"locale\" text null, \"terms_accepted\" boolean not null default false, \"password_hash\" text null, \"expires_at\" timestamptz not null, \"completed_at\" timestamptz null, \"tenant_id\" uuid null, \"organization_id\" uuid null, \"user_id\" uuid null, \"last_email_sent_at\" timestamptz null, \"created_at\" timestamptz not null, \"updated_at\" timestamptz null, \"deleted_at\" timestamptz null, constraint \"onboarding_requests_pkey\" primary key (\"id\"));`);\n    this.addSql(`alter table \"onboarding_requests\" add constraint \"onboarding_requests_token_hash_unique\" unique (\"token_hash\");`);\n    this.addSql(`alter table \"onboarding_requests\" add constraint \"onboarding_requests_email_unique\" unique (\"email\");`);\n  }\n\n}\n"],
+  "mappings": "AAAA,SAAS,iBAAiB;AAEnB,MAAM,gCAAgC,UAAU;AAAA,EAErD,MAAe,KAAoB;AACjC,SAAK,OAAO,0rBAA0rB;AACtsB,SAAK,OAAO,iHAAiH;AAC7H,SAAK,OAAO,uGAAuG;AAAA,EACrH;AAEF;",
+  "names": []
+}

package/generated/entities/onboarding_request/index.ts

@@ -0,0 +1,19 @@
+export const id = 'id'
+export const email = 'email'
+export const token_hash = 'token_hash'
+export const status = 'status'
+export const first_name = 'first_name'
+export const last_name = 'last_name'
+export const organization_name = 'organization_name'
+export const locale = 'locale'
+export const terms_accepted = 'terms_accepted'
+export const password_hash = 'password_hash'
+export const expires_at = 'expires_at'
+export const completed_at = 'completed_at'
+export const tenant_id = 'tenant_id'
+export const organization_id = 'organization_id'
+export const user_id = 'user_id'
+export const last_email_sent_at = 'last_email_sent_at'
+export const created_at = 'created_at'
+export const updated_at = 'updated_at'
+export const deleted_at = 'deleted_at'

package/generated/entities.ids.generated.ts

@@ -0,0 +1,11 @@
+// AUTO-GENERATED by mercato generate entity-ids
+export const M = {
+  "onboarding": "onboarding"
+} as const
+export const E = {
+  "onboarding": {
+    "onboarding_request": "onboarding:onboarding_request"
+  }
+} as const
+export type KnownModuleId = keyof typeof M
+export type KnownEntities = typeof E

package/generated/entity-fields-registry.ts

@@ -0,0 +1,11 @@
+// AUTO-GENERATED by mercato generate entity-ids
+// Static registry for entity fields - eliminates dynamic imports for Turbopack compatibility
+import * as onboarding_request from './entities/onboarding_request/index'
+
+export const entityFieldsRegistry: Record<string, Record<string, string>> = {
+  onboarding_request
+}
+
+export function getEntityFields(slug: string): Record<string, string> | undefined {
+  return entityFieldsRegistry[slug]
+}

package/jest.config.cjs

@@ -0,0 +1,19 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          jsx: 'react-jsx',
+        },
+      },
+    ],
+  },
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@open-mercato/onboarding",
+  "version": "0.4.2-canary-c02407ff85",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.tsx": {
+      "types": "./src/*.tsx",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./src/*.json",
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*.json": "./src/*/*.json",
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*.json": "./src/*/*/*.json",
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*/*.json": "./src/*/*/*/*/*.json",
+    "./*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*/*.json": "./src/*/*/*/*/*/*.json",
+    "./*/*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*/*.js"
+    }
+  },
+  "dependencies": {
+    "@open-mercato/shared": "0.4.2-canary-c02407ff85"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "stableVersion": "0.4.1"
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// Barrel for @open-mercato/onboarding
+export {}

package/src/modules/onboarding/acl.ts

@@ -0,0 +1,7 @@
+export const features = [
+  { id: 'onboarding.access', title: 'Access onboarding flow', module: 'onboarding' },
+  { id: 'onboarding.submit', title: 'Submit onboarding request', module: 'onboarding' },
+  { id: 'onboarding.verify', title: 'Verify onboarding request', module: 'onboarding' },
+]
+
+export default features

package/src/modules/onboarding/api/get/onboarding/verify.ts

@@ -0,0 +1,224 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { onboardingVerifySchema } from '@open-mercato/onboarding/modules/onboarding/data/validators'
+import { OnboardingService } from '@open-mercato/onboarding/modules/onboarding/lib/service'
+import { setupInitialTenant } from '@open-mercato/core/modules/auth/lib/setup-app'
+import {
+  seedCustomerDictionaries,
+  seedCustomerExamples,
+  seedCurrencyDictionary,
+} from '@open-mercato/core/modules/customers/cli'
+import { seedDashboardDefaultsForTenant } from '@open-mercato/core/modules/dashboards/cli'
+import { AuthService } from '@open-mercato/core/modules/auth/services/authService'
+import { signJwt } from '@open-mercato/shared/lib/auth/jwt'
+import { reindexEntity } from '@open-mercato/core/modules/query_index/lib/reindexer'
+import { purgeIndexScope } from '@open-mercato/core/modules/query_index/lib/purge'
+import { refreshCoverageSnapshot } from '@open-mercato/core/modules/query_index/lib/coverage'
+import { flattenSystemEntityIds } from '@open-mercato/shared/lib/entities/system-entities'
+import { getEntityIds } from '@open-mercato/shared/lib/encryption/entityIds'
+import type { VectorIndexService } from '@open-mercato/search/vector'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+
+export const metadata = {
+  GET: {
+    requireAuth: false,
+  },
+}
+
+function redirectWithStatus(baseUrl: string, status: string) {
+  return NextResponse.redirect(`${baseUrl}/onboarding?status=${encodeURIComponent(status)}`)
+}
+
+export async function GET(req: Request) {
+  const url = new URL(req.url)
+  const baseUrl = process.env.APP_URL || `${url.protocol}//${url.host}`
+  const token = url.searchParams.get('token') ?? ''
+  const parsed = onboardingVerifySchema.safeParse({ token })
+  if (!parsed.success) {
+    return redirectWithStatus(baseUrl, 'invalid')
+  }
+
+  const container = await createRequestContainer()
+  const em = (container.resolve('em') as EntityManager)
+  const service = new OnboardingService(em)
+  const request = await service.findPendingByToken(parsed.data.token)
+  if (!request) {
+    return redirectWithStatus(baseUrl, 'invalid')
+  }
+  if (!request.passwordHash) {
+    console.error('[onboarding.verify] missing password hash for request', request.id)
+    return redirectWithStatus(baseUrl, 'error')
+  }
+
+  let tenantId: string | null = null
+  let organizationId: string | null = null
+  let userId: string | null = null
+
+  try {
+    const setupResult = await setupInitialTenant(em, {
+      orgName: request.organizationName,
+      includeDerivedUsers: false,
+      failIfUserExists: true,
+      primaryUserRoles: ['admin'],
+      includeSuperadminRole: false,
+      primaryUser: {
+        email: request.email,
+        firstName: request.firstName,
+        lastName: request.lastName,
+        displayName: `${request.firstName} ${request.lastName}`.trim(),
+        hashedPassword: request.passwordHash,
+        confirm: true,
+      },
+    })
+
+    tenantId = String(setupResult.tenantId)
+    organizationId = String(setupResult.organizationId)
+
+    const mainUserSnapshot = setupResult.users.find((entry) => entry.user.email === request.email)
+    if (!mainUserSnapshot) throw new Error('USER_NOT_CREATED')
+    const user = mainUserSnapshot.user
+    const resolvedUserId = String(user.id)
+    userId = resolvedUserId
+
+    await seedCustomerDictionaries(em, { tenantId, organizationId })
+    await seedCurrencyDictionary(em, { tenantId, organizationId })
+    await seedCustomerExamples(em, container, { tenantId, organizationId })
+    await seedDashboardDefaultsForTenant(em, { tenantId, organizationId, logger: () => {} })
+
+    if (tenantId) {
+      let vectorService: VectorIndexService | null = null
+      try {
+        vectorService = container.resolve<VectorIndexService>('vectorIndexService')
+      } catch {
+        vectorService = null
+      }
+      const coverageRefreshKeys = new Set<string>()
+      try {
+        const allEntities = getEntityIds()
+        const entityIds = flattenSystemEntityIds(allEntities)
+        for (const entityType of entityIds) {
+          try {
+            await purgeIndexScope(em, { entityType, tenantId })
+          } catch (error) {
+            console.error('[onboarding.verify] failed to purge query index scope', { entityType, tenantId, error })
+          }
+          try {
+            await reindexEntity(em, {
+              entityType,
+              tenantId,
+              force: true,
+              emitVectorizeEvents: false,
+              vectorService: null,
+            })
+          } catch (error) {
+            console.error('[onboarding.verify] failed to reindex entity', { entityType, tenantId, error })
+          }
+          coverageRefreshKeys.add(`${entityType}|${tenantId}|__null__`)
+          if (organizationId) coverageRefreshKeys.add(`${entityType}|${tenantId}|${organizationId}`)
+        }
+      } catch (error) {
+        console.error('[onboarding.verify] failed to rebuild query indexes', { tenantId, error })
+      }
+
+      if (vectorService) {
+        try {
+          await vectorService.reindexAll({ tenantId, organizationId, purgeFirst: true })
+        } catch (error) {
+          console.error('[onboarding.verify] failed to rebuild vector indexes', { tenantId, organizationId, error })
+        }
+      }
+
+      if (coverageRefreshKeys.size) {
+        for (const entry of coverageRefreshKeys) {
+          const [entityType, tenantKey, orgKey] = entry.split('|')
+          const orgScope = orgKey === '__null__' ? null : orgKey
+          try {
+            await refreshCoverageSnapshot(
+              em,
+              {
+                entityType,
+                tenantId: tenantKey,
+                organizationId: orgScope,
+                withDeleted: false,
+              },
+            )
+          } catch (error) {
+            console.error('[onboarding.verify] failed to refresh coverage snapshot', {
+              entityType,
+              tenantId: tenantKey,
+              organizationId: orgScope,
+              error,
+            })
+          }
+        }
+      }
+    }
+
+    const authService = (container.resolve('authService') as AuthService)
+    await authService.updateLastLoginAt(user)
+    const roles = await authService.getUserRoles(user, tenantId)
+    const jwt = signJwt({
+      sub: String(user.id),
+      tenantId,
+      orgId: organizationId,
+      email: user.email,
+      roles,
+    })
+    const response = NextResponse.redirect(`${baseUrl}/backend`)
+    response.cookies.set('auth_token', jwt, {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: process.env.NODE_ENV === 'production',
+      path: '/',
+      maxAge: 60 * 60 * 8,
+    })
+
+    const rememberDays = Number(process.env.REMEMBER_ME_DAYS || '30')
+    const expiresAt = new Date(Date.now() + rememberDays * 24 * 60 * 60 * 1000)
+    const session = await authService.createSession(user, expiresAt)
+    response.cookies.set('session_token', session.token, {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: process.env.NODE_ENV === 'production',
+      path: '/',
+      expires: expiresAt,
+    })
+
+    await service.markCompleted(request, { tenantId, organizationId, userId: resolvedUserId })
+    return response
+  } catch (error) {
+    if (error instanceof Error && error.message === 'USER_EXISTS') {
+      return redirectWithStatus(baseUrl, 'already_exists')
+    }
+    console.error('[onboarding.verify] failed', error)
+    return redirectWithStatus(baseUrl, 'error')
+  }
+}
+
+export default GET
+
+const onboardingTag = 'Onboarding'
+
+const onboardingVerifyQuerySchema = z.object({
+  token: onboardingVerifySchema.shape.token,
+})
+
+const onboardingVerifyDoc: OpenApiMethodDoc = {
+  summary: 'Verify onboarding token',
+  description: 'Validates the onboarding token, provisions the tenant, seeds demo data, and redirects the user to the dashboard.',
+  tags: [onboardingTag],
+  query: onboardingVerifyQuerySchema,
+  responses: [
+    { status: 302, description: 'Redirect to onboarding UI or dashboard' },
+  ],
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: onboardingTag,
+  summary: 'Onboarding verification redirect',
+  methods: {
+    GET: onboardingVerifyDoc,
+  },
+}

package/src/modules/onboarding/api/post/onboarding.ts

@@ -0,0 +1,210 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { loadDictionary } from '@open-mercato/shared/lib/i18n/server'
+import { defaultLocale, locales, type Locale } from '@open-mercato/shared/lib/i18n/config'
+import { createFallbackTranslator } from '@open-mercato/shared/lib/i18n/translate'
+import { sendEmail } from '@open-mercato/shared/lib/email/send'
+import { onboardingStartSchema } from '@open-mercato/onboarding/modules/onboarding/data/validators'
+import { OnboardingService } from '@open-mercato/onboarding/modules/onboarding/lib/service'
+import VerificationEmail from '@open-mercato/onboarding/modules/onboarding/emails/VerificationEmail'
+import AdminNotificationEmail from '@open-mercato/onboarding/modules/onboarding/emails/AdminNotificationEmail'
+import { User } from '@open-mercato/core/modules/auth/data/entities'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+
+export const metadata = {
+  POST: {
+    requireAuth: false,
+  },
+}
+
+export async function POST(req: Request) {
+  if (process.env.SELF_SERVICE_ONBOARDING_ENABLED !== 'true') {
+    return NextResponse.json({ ok: false, error: 'Self-service onboarding is disabled.' }, { status: 404 })
+  }
+  let payload: unknown
+  try {
+    payload = await req.json()
+  } catch {
+    return NextResponse.json({ ok: false, error: 'Invalid payload' }, { status: 400 })
+  }
+
+  const rawLocale =
+    payload && typeof payload === 'object' && 'locale' in payload && typeof (payload as any).locale === 'string'
+      ? (payload as any).locale as string
+      : null
+  const locale: Locale = rawLocale && locales.includes(rawLocale as Locale)
+    ? (rawLocale as Locale)
+    : defaultLocale
+  const dict = await loadDictionary(locale)
+  const translate = createFallbackTranslator(dict)
+
+  const parsed = onboardingStartSchema.safeParse(payload)
+  if (!parsed.success) {
+    const fieldErrors: Record<string, string> = {}
+    for (const issue of parsed.error.issues) {
+      const path = issue.path[0]
+      if (!path) continue
+      switch (path) {
+        case 'email':
+          fieldErrors.email = translate('onboarding.errors.emailInvalid', 'Enter a valid work email.')
+          break
+        case 'firstName':
+          fieldErrors.firstName = translate('onboarding.errors.firstNameRequired', 'First name is required.')
+          break
+        case 'lastName':
+          fieldErrors.lastName = translate('onboarding.errors.lastNameRequired', 'Last name is required.')
+          break
+        case 'organizationName':
+          fieldErrors.organizationName = translate('onboarding.errors.organizationNameRequired', 'Organization name is required.')
+          break
+        case 'password':
+          fieldErrors.password = translate('onboarding.errors.passwordRequired', 'Password must be at least 6 characters.')
+          break
+        case 'confirmPassword':
+          fieldErrors.confirmPassword = translate('onboarding.errors.passwordMismatch', 'Passwords must match.')
+          break
+        case 'termsAccepted':
+          fieldErrors.termsAccepted = translate('onboarding.form.termsRequired', 'Please accept the terms to continue.')
+          break
+        default:
+          break
+      }
+    }
+    return NextResponse.json({
+      ok: false,
+      error: translate('onboarding.form.genericError', 'Please check the form and try again.'),
+      fieldErrors,
+    }, { status: 400 })
+  }
+
+  try {
+    const container = await createRequestContainer()
+    const em = (container.resolve('em') as EntityManager)
+
+    const existingUser = await em.findOne(User, { email: parsed.data.email })
+    if (existingUser) {
+      const message = translate('onboarding.errors.emailExists', 'We already have an account with this email. Try signing in or resetting your password.')
+      return NextResponse.json({
+        ok: false,
+        error: message,
+        fieldErrors: { email: message },
+      }, { status: 409 })
+    }
+
+    const service = new OnboardingService(em)
+    let request, token
+    try {
+      const result = await service.createOrUpdateRequest(parsed.data)
+      request = result.request
+      token = result.token
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith('PENDING_REQUEST:')) {
+        const minutes = Number(err.message.split(':')[1] || '10')
+        const message = translate('onboarding.errors.pendingRequest', 'We already have a pending verification. Please try again in about {minutes} minutes or contact the administrator.', { minutes })
+        return NextResponse.json({
+          ok: false,
+          error: message,
+          fieldErrors: { email: message },
+        }, { status: 409 })
+      }
+      throw err
+    }
+
+    const url = new URL(req.url)
+    const baseUrl = process.env.APP_URL || `${url.protocol}//${url.host}`
+    const verifyUrl = `${baseUrl}/api/onboarding/onboarding/verify?token=${token}`
+
+    const firstName = request.firstName || parsed.data.firstName
+    const subject = translate('onboarding.email.subject', 'Confirm your email to finish onboarding')
+    const emailCopy = {
+      preview: translate('onboarding.email.preview', 'Confirm your email to activate your Open Mercato workspace'),
+      heading: translate('onboarding.email.heading', 'Welcome to Open Mercato'),
+      greeting: translate('onboarding.email.greeting', 'Hi {firstName},', { firstName }),
+      body: translate(
+        'onboarding.email.body',
+        'We just need to confirm your email address to finish setting up the organization {organizationName}.',
+        { organizationName: request.organizationName },
+      ),
+      cta: translate('onboarding.email.cta', 'Confirm email & activate workspace'),
+      expiry: translate(
+        'onboarding.email.expiry',
+        "The link will expire in 24 hours. If you didn't request this, you can safely ignore this message.",
+      ),
+      footer: translate('onboarding.email.footer', 'Open Mercato · Tenant onboarding service'),
+    }
+    const emailReact = VerificationEmail({ verifyUrl, copy: emailCopy })
+    await sendEmail({ to: request.email, subject, react: emailReact })
+
+    const adminEmail = process.env.ADMIN_EMAIL || 'piotr@catchthetornado.com'
+    const adminSubject = translate('onboarding.email.adminSubject', 'New self-service onboarding request')
+    const adminCopy = {
+      preview: translate('onboarding.email.adminPreview', 'New onboarding request submitted'),
+      heading: translate('onboarding.email.adminHeading', 'New onboarding request'),
+      body: translate('onboarding.email.adminBody', '{firstName} {lastName} ({email}) submitted an onboarding request for {organizationName}.', {
+        firstName: request.firstName,
+        lastName: request.lastName,
+        email: request.email,
+        organizationName: request.organizationName,
+      }),
+      footer: translate('onboarding.email.adminFooter', 'You can review the tenant after verification is complete.'),
+    }
+    await sendEmail({
+      to: adminEmail,
+      subject: adminSubject,
+      react: AdminNotificationEmail({ copy: adminCopy }),
+    })
+
+    return NextResponse.json({ ok: true, email: request.email })
+  } catch (error) {
+    console.error('[onboarding.start] failed', error)
+    return NextResponse.json({
+      ok: false,
+      error: translate('onboarding.form.genericError', 'Something went wrong. Please try again later.'),
+    }, { status: 500 })
+  }
+}
+
+export default POST
+
+const onboardingTag = 'Onboarding'
+
+const onboardingSuccessSchema = z.object({
+  ok: z.literal(true),
+  email: z.string().email(),
+})
+
+const onboardingErrorSchema = z.object({
+  ok: z.literal(false),
+  error: z.string(),
+  fieldErrors: z.record(z.string(), z.string()).optional(),
+})
+
+const onboardingPostDoc: OpenApiMethodDoc = {
+  summary: 'Submit onboarding request',
+  description: 'Accepts a self-service onboarding form submission and triggers email verification.',
+  tags: [onboardingTag],
+  requestBody: {
+    contentType: 'application/json',
+    schema: onboardingStartSchema,
+    description: 'Onboarding form payload with contact and organization information.',
+  },
+  responses: [
+    { status: 200, description: 'Onboarding request accepted.', schema: onboardingSuccessSchema },
+  ],
+  errors: [
+    { status: 400, description: 'Validation failed', schema: onboardingErrorSchema },
+    { status: 404, description: 'Self-service onboarding disabled', schema: onboardingErrorSchema },
+    { status: 409, description: 'Existing account or pending request', schema: onboardingErrorSchema },
+    { status: 500, description: 'Unexpected server error', schema: onboardingErrorSchema },
+  ],
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: onboardingTag,
+  summary: 'Self-service onboarding submission',
+  methods: {
+    POST: onboardingPostDoc,
+  },
+}

package/src/modules/onboarding/data/entities.ts

@@ -0,0 +1,67 @@
+import { Entity, PrimaryKey, Property, Unique } from '@mikro-orm/core'
+
+type OnboardingStatus = 'pending' | 'completed' | 'expired'
+
+@Entity({ tableName: 'onboarding_requests' })
+@Unique({ properties: ['email'] })
+@Unique({ properties: ['tokenHash'] })
+export class OnboardingRequest {
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ type: 'text' })
+  email!: string
+
+  @Property({ name: 'token_hash', type: 'text' })
+  tokenHash!: string
+
+  @Property({ type: 'text', default: 'pending' })
+  status: OnboardingStatus = 'pending'
+
+  @Property({ name: 'first_name', type: 'text' })
+  firstName!: string
+
+  @Property({ name: 'last_name', type: 'text' })
+  lastName!: string
+
+  @Property({ name: 'organization_name', type: 'text' })
+  organizationName!: string
+
+  @Property({ type: 'text', nullable: true })
+  locale?: string | null
+
+  @Property({ name: 'terms_accepted', type: 'boolean', default: false })
+  termsAccepted: boolean = false
+
+  @Property({ name: 'password_hash', type: 'text', nullable: true })
+  passwordHash?: string | null
+
+  @Property({ name: 'expires_at', type: Date })
+  expiresAt!: Date
+
+  @Property({ name: 'completed_at', type: Date, nullable: true })
+  completedAt?: Date | null
+
+  @Property({ name: 'tenant_id', type: 'uuid', nullable: true })
+  tenantId?: string | null
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'user_id', type: 'uuid', nullable: true })
+  userId?: string | null
+
+  @Property({ name: 'last_email_sent_at', type: Date, nullable: true })
+  lastEmailSentAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date(), nullable: true })
+  updatedAt?: Date
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+export type { OnboardingStatus }