feat(onboarding): add mini app household join flow

packages/application/src/household-onboarding-service.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, test } from 'bun:test'
+
+import type {
+  FinanceMemberRecord,
+  HouseholdConfigurationRepository,
+  HouseholdJoinTokenRecord,
+  HouseholdPendingMemberRecord,
+  HouseholdTelegramChatRecord,
+  HouseholdTopicBindingRecord
+} from '@household/ports'
+
+import { createHouseholdOnboardingService } from './household-onboarding-service'
+
+function createRepositoryStub() {
+  const household: HouseholdTelegramChatRecord = {
+    householdId: 'household-1',
+    householdName: 'Kojori House',
+    telegramChatId: '-100123',
+    telegramChatType: 'supergroup',
+    title: 'Kojori House'
+  }
+  let joinToken: HouseholdJoinTokenRecord | null = null
+  const pendingMembers = new Map<string, HouseholdPendingMemberRecord>()
+
+  const repository: HouseholdConfigurationRepository = {
+    async registerTelegramHouseholdChat() {
+      return {
+        status: 'existing',
+        household
+      }
+    },
+    async getTelegramHouseholdChat() {
+      return household
+    },
+    async bindHouseholdTopic(input) {
+      const binding: HouseholdTopicBindingRecord = {
+        householdId: input.householdId,
+        role: input.role,
+        telegramThreadId: input.telegramThreadId,
+        topicName: input.topicName?.trim() || null
+      }
+      return binding
+    },
+    async getHouseholdTopicBinding() {
+      return null
+    },
+    async findHouseholdTopicByTelegramContext() {
+      return null
+    },
+    async listHouseholdTopicBindings() {
+      return []
+    },
+    async upsertHouseholdJoinToken(input) {
+      joinToken = {
+        householdId: household.householdId,
+        householdName: household.householdName,
+        token: input.token,
+        createdByTelegramUserId: input.createdByTelegramUserId ?? null
+      }
+      return joinToken
+    },
+    async getHouseholdJoinToken() {
+      return joinToken
+    },
+    async getHouseholdByJoinToken(token) {
+      return joinToken?.token === token ? household : null
+    },
+    async upsertPendingHouseholdMember(input) {
+      const record: HouseholdPendingMemberRecord = {
+        householdId: household.householdId,
+        householdName: household.householdName,
+        telegramUserId: input.telegramUserId,
+        displayName: input.displayName,
+        username: input.username?.trim() || null,
+        languageCode: input.languageCode?.trim() || null
+      }
+      pendingMembers.set(input.telegramUserId, record)
+      return record
+    },
+    async getPendingHouseholdMember(_householdId, telegramUserId) {
+      return pendingMembers.get(telegramUserId) ?? null
+    },
+    async findPendingHouseholdMemberByTelegramUserId(telegramUserId) {
+      return pendingMembers.get(telegramUserId) ?? null
+    }
+  }
+
+  return {
+    repository
+  }
+}
+
+describe('createHouseholdOnboardingService', () => {
+  test('creates and reuses a stable join token for a household', async () => {
+    const { repository } = createRepositoryStub()
+    const service = createHouseholdOnboardingService({
+      repository,
+      tokenFactory: () => 'join-token'
+    })
+
+    const created = await service.ensureHouseholdJoinToken({
+      householdId: 'household-1',
+      actorTelegramUserId: '1'
+    })
+    const reused = await service.ensureHouseholdJoinToken({
+      householdId: 'household-1'
+    })
+
+    expect(created.token).toBe('join-token')
+    expect(reused.token).toBe('join-token')
+  })
+
+  test('reports join_required for a valid token and non-member', async () => {
+    const { repository } = createRepositoryStub()
+    const service = createHouseholdOnboardingService({
+      repository,
+      tokenFactory: () => 'join-token'
+    })
+    await service.ensureHouseholdJoinToken({
+      householdId: 'household-1'
+    })
+
+    const access = await service.getMiniAppAccess({
+      identity: {
+        telegramUserId: '42',
+        displayName: 'Stan'
+      },
+      joinToken: 'join-token'
+    })
+
+    expect(access).toEqual({
+      status: 'join_required',
+      household: {
+        id: 'household-1',
+        name: 'Kojori House'
+      }
+    })
+  })
+
+  test('creates a pending join request', async () => {
+    const { repository } = createRepositoryStub()
+    const service = createHouseholdOnboardingService({
+      repository,
+      tokenFactory: () => 'join-token'
+    })
+    await service.ensureHouseholdJoinToken({
+      householdId: 'household-1'
+    })
+
+    const result = await service.joinHousehold({
+      identity: {
+        telegramUserId: '42',
+        displayName: 'Stan',
+        username: 'stan'
+      },
+      joinToken: 'join-token'
+    })
+
+    expect(result).toEqual({
+      status: 'pending',
+      household: {
+        id: 'household-1',
+        name: 'Kojori House'
+      }
+    })
+
+    const access = await service.getMiniAppAccess({
+      identity: {
+        telegramUserId: '42',
+        displayName: 'Stan'
+      }
+    })
+
+    expect(access).toEqual({
+      status: 'pending',
+      household: {
+        id: 'household-1',
+        name: 'Kojori House'
+      }
+    })
+  })
+
+  test('returns active when the user is already a finance member', async () => {
+    const { repository } = createRepositoryStub()
+    const member: FinanceMemberRecord = {
+      id: 'member-1',
+      telegramUserId: '42',
+      displayName: 'Stan',
+      isAdmin: true
+    }
+    const service = createHouseholdOnboardingService({
+      repository,
+      getMemberByTelegramUserId: async () => member
+    })
+
+    const access = await service.getMiniAppAccess({
+      identity: {
+        telegramUserId: '42',
+        displayName: 'Stan'
+      },
+      joinToken: 'anything'
+    })
+
+    expect(access).toEqual({
+      status: 'active',
+      member: {
+        id: 'member-1',
+        displayName: 'Stan',
+        isAdmin: true
+      }
+    })
+  })
+})

packages/application/src/household-onboarding-service.ts

@@ -0,0 +1,228 @@
+import { randomBytes } from 'node:crypto'
+
+import type { FinanceMemberRecord, HouseholdConfigurationRepository } from '@household/ports'
+
+export interface HouseholdOnboardingIdentity {
+  telegramUserId: string
+  displayName: string
+  username?: string | null
+  languageCode?: string | null
+}
+
+export type HouseholdMiniAppAccess =
+  | {
+      status: 'active'
+      member: {
+        id: string
+        displayName: string
+        isAdmin: boolean
+      }
+    }
+  | {
+      status: 'pending'
+      household: {
+        id: string
+        name: string
+      }
+    }
+  | {
+      status: 'join_required'
+      household: {
+        id: string
+        name: string
+      }
+    }
+  | {
+      status: 'open_from_group'
+    }
+
+export interface HouseholdOnboardingService {
+  ensureHouseholdJoinToken(input: { householdId: string; actorTelegramUserId?: string }): Promise<{
+    householdId: string
+    householdName: string
+    token: string
+  }>
+  getMiniAppAccess(input: {
+    identity: HouseholdOnboardingIdentity
+    joinToken?: string
+  }): Promise<HouseholdMiniAppAccess>
+  joinHousehold(input: { identity: HouseholdOnboardingIdentity; joinToken: string }): Promise<
+    | {
+        status: 'pending'
+        household: {
+          id: string
+          name: string
+        }
+      }
+    | {
+        status: 'active'
+        member: {
+          id: string
+          displayName: string
+          isAdmin: boolean
+        }
+      }
+    | {
+        status: 'invalid_token'
+      }
+  >
+}
+
+function toMember(member: FinanceMemberRecord): {
+  id: string
+  displayName: string
+  isAdmin: boolean
+} {
+  return {
+    id: member.id,
+    displayName: member.displayName,
+    isAdmin: member.isAdmin
+  }
+}
+
+function generateJoinToken(): string {
+  return randomBytes(24).toString('base64url')
+}
+
+export function createHouseholdOnboardingService(options: {
+  repository: HouseholdConfigurationRepository
+  getMemberByTelegramUserId?: (telegramUserId: string) => Promise<FinanceMemberRecord | null>
+  tokenFactory?: () => string
+}): HouseholdOnboardingService {
+  const createToken = options.tokenFactory ?? generateJoinToken
+
+  return {
+    async ensureHouseholdJoinToken(input) {
+      const existing = await options.repository.getHouseholdJoinToken(input.householdId)
+      if (existing) {
+        return {
+          householdId: existing.householdId,
+          householdName: existing.householdName,
+          token: existing.token
+        }
+      }
+
+      const token = createToken()
+      const created = await options.repository.upsertHouseholdJoinToken({
+        householdId: input.householdId,
+        token,
+        ...(input.actorTelegramUserId
+          ? {
+              createdByTelegramUserId: input.actorTelegramUserId
+            }
+          : {})
+      })
+
+      return {
+        householdId: created.householdId,
+        householdName: created.householdName,
+        token: created.token
+      }
+    },
+
+    async getMiniAppAccess(input) {
+      const activeMember = options.getMemberByTelegramUserId
+        ? await options.getMemberByTelegramUserId(input.identity.telegramUserId)
+        : null
+
+      if (activeMember) {
+        return {
+          status: 'active',
+          member: toMember(activeMember)
+        }
+      }
+
+      const existingPending = await options.repository.findPendingHouseholdMemberByTelegramUserId(
+        input.identity.telegramUserId
+      )
+      if (existingPending) {
+        return {
+          status: 'pending',
+          household: {
+            id: existingPending.householdId,
+            name: existingPending.householdName
+          }
+        }
+      }
+
+      if (!input.joinToken) {
+        return {
+          status: 'open_from_group'
+        }
+      }
+
+      const household = await options.repository.getHouseholdByJoinToken(input.joinToken)
+      if (!household) {
+        return {
+          status: 'open_from_group'
+        }
+      }
+
+      const pending = await options.repository.getPendingHouseholdMember(
+        household.householdId,
+        input.identity.telegramUserId
+      )
+      if (pending) {
+        return {
+          status: 'pending',
+          household: {
+            id: pending.householdId,
+            name: pending.householdName
+          }
+        }
+      }
+
+      return {
+        status: 'join_required',
+        household: {
+          id: household.householdId,
+          name: household.householdName
+        }
+      }
+    },
+
+    async joinHousehold(input) {
+      const household = await options.repository.getHouseholdByJoinToken(input.joinToken)
+      if (!household) {
+        return {
+          status: 'invalid_token'
+        }
+      }
+
+      const activeMember = options.getMemberByTelegramUserId
+        ? await options.getMemberByTelegramUserId(input.identity.telegramUserId)
+        : null
+
+      if (activeMember) {
+        return {
+          status: 'active',
+          member: toMember(activeMember)
+        }
+      }
+
+      const pending = await options.repository.upsertPendingHouseholdMember({
+        householdId: household.householdId,
+        telegramUserId: input.identity.telegramUserId,
+        displayName: input.identity.displayName,
+        ...(input.identity.username
+          ? {
+              username: input.identity.username
+            }
+          : {}),
+        ...(input.identity.languageCode
+          ? {
+              languageCode: input.identity.languageCode
+            }
+          : {})
+      })
+
+      return {
+        status: 'pending',
+        household: {
+          id: pending.householdId,
+          name: pending.householdName
+        }
+      }
+    }
+  }
+}

packages/application/src/household-setup-service.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, test } from 'bun:test'
 
 import type {
   HouseholdConfigurationRepository,
+  HouseholdJoinTokenRecord,
+  HouseholdPendingMemberRecord,
   HouseholdTelegramChatRecord,
   HouseholdTopicBindingRecord
 } from '@household/ports'
@@ -11,6 +13,8 @@ import { createHouseholdSetupService } from './household-setup-service'
 function createRepositoryStub() {
   const households = new Map<string, HouseholdTelegramChatRecord>()
   const bindings = new Map<string, HouseholdTopicBindingRecord[]>()
+  const joinTokens = new Map<string, HouseholdJoinTokenRecord>()
+  const pendingMembers = new Map<string, HouseholdPendingMemberRecord>()
 
   const repository: HouseholdConfigurationRepository = {
     async registerTelegramHouseholdChat(input) {
@@ -79,6 +83,71 @@ function createRepositoryStub() {
 
     async listHouseholdTopicBindings(householdId) {
       return bindings.get(householdId) ?? []
+    },
+
+    async upsertHouseholdJoinToken(input) {
+      const household = [...households.values()].find(
+        (entry) => entry.householdId === input.householdId
+      )
+      if (!household) {
+        throw new Error('Missing household')
+      }
+
+      const record: HouseholdJoinTokenRecord = {
+        householdId: household.householdId,
+        householdName: household.householdName,
+        token: input.token,
+        createdByTelegramUserId: input.createdByTelegramUserId ?? null
+      }
+      joinTokens.set(household.householdId, record)
+      return record
+    },
+
+    async getHouseholdJoinToken(householdId) {
+      return joinTokens.get(householdId) ?? null
+    },
+
+    async getHouseholdByJoinToken(token) {
+      const record = [...joinTokens.values()].find((entry) => entry.token === token)
+      if (!record) {
+        return null
+      }
+
+      return (
+        [...households.values()].find((entry) => entry.householdId === record.householdId) ?? null
+      )
+    },
+
+    async upsertPendingHouseholdMember(input) {
+      const household = [...households.values()].find(
+        (entry) => entry.householdId === input.householdId
+      )
+      if (!household) {
+        throw new Error('Missing household')
+      }
+
+      const key = `${input.householdId}:${input.telegramUserId}`
+      const record: HouseholdPendingMemberRecord = {
+        householdId: household.householdId,
+        householdName: household.householdName,
+        telegramUserId: input.telegramUserId,
+        displayName: input.displayName,
+        username: input.username?.trim() || null,
+        languageCode: input.languageCode?.trim() || null
+      }
+      pendingMembers.set(key, record)
+      return record
+    },
+
+    async getPendingHouseholdMember(householdId, telegramUserId) {
+      return pendingMembers.get(`${householdId}:${telegramUserId}`) ?? null
+    },
+
+    async findPendingHouseholdMemberByTelegramUserId(telegramUserId) {
+      return (
+        [...pendingMembers.values()].find((entry) => entry.telegramUserId === telegramUserId) ??
+        null
+      )
     }
   }
 

packages/application/src/index.ts

@@ -6,6 +6,12 @@ export {
 } from './anonymous-feedback-service'
 export { createFinanceCommandService, type FinanceCommandService } from './finance-command-service'
 export { createHouseholdSetupService, type HouseholdSetupService } from './household-setup-service'
+export {
+  createHouseholdOnboardingService,
+  type HouseholdMiniAppAccess,
+  type HouseholdOnboardingIdentity,
+  type HouseholdOnboardingService
+} from './household-onboarding-service'
 export {
   createReminderJobService,
   type ReminderJobResult,