feat(bot): add household admin approval flow

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

@@ -0,0 +1,180 @@
+import { describe, expect, test } from 'bun:test'
+
+import type {
+  HouseholdConfigurationRepository,
+  HouseholdJoinTokenRecord,
+  HouseholdMemberRecord,
+  HouseholdPendingMemberRecord,
+  HouseholdTelegramChatRecord,
+  HouseholdTopicBindingRecord
+} from '@household/ports'
+
+import { createHouseholdAdminService } from './household-admin-service'
+
+function createRepositoryStub() {
+  const household: HouseholdTelegramChatRecord = {
+    householdId: 'household-1',
+    householdName: 'Kojori House',
+    telegramChatId: '-100123',
+    telegramChatType: 'supergroup',
+    title: 'Kojori House'
+  }
+  const members = new Map<string, HouseholdMemberRecord>()
+  const pendingMembers = new Map<string, HouseholdPendingMemberRecord>()
+
+  members.set('1', {
+    householdId: household.householdId,
+    telegramUserId: '1',
+    displayName: 'Stan',
+    isAdmin: true
+  })
+  pendingMembers.set('2', {
+    householdId: household.householdId,
+    householdName: household.householdName,
+    telegramUserId: '2',
+    displayName: 'Alice',
+    username: 'alice',
+    languageCode: 'en'
+  })
+
+  const repository: HouseholdConfigurationRepository = {
+    registerTelegramHouseholdChat: async () => ({
+      status: 'existing',
+      household
+    }),
+    getTelegramHouseholdChat: async () => household,
+    bindHouseholdTopic: async (input) =>
+      ({
+        householdId: input.householdId,
+        role: input.role,
+        telegramThreadId: input.telegramThreadId,
+        topicName: input.topicName?.trim() || null
+      }) satisfies HouseholdTopicBindingRecord,
+    getHouseholdTopicBinding: async () => null,
+    findHouseholdTopicByTelegramContext: async () => null,
+    listHouseholdTopicBindings: async () => [],
+    upsertHouseholdJoinToken: async (input) =>
+      ({
+        householdId: household.householdId,
+        householdName: household.householdName,
+        token: input.token,
+        createdByTelegramUserId: input.createdByTelegramUserId ?? null
+      }) satisfies HouseholdJoinTokenRecord,
+    getHouseholdJoinToken: async () => null,
+    getHouseholdByJoinToken: async () => household,
+    upsertPendingHouseholdMember: async (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
+    },
+    getPendingHouseholdMember: async (_householdId, telegramUserId) =>
+      pendingMembers.get(telegramUserId) ?? null,
+    findPendingHouseholdMemberByTelegramUserId: async (telegramUserId) =>
+      pendingMembers.get(telegramUserId) ?? null,
+    ensureHouseholdMember: async (input) => {
+      const record: HouseholdMemberRecord = {
+        householdId: input.householdId,
+        telegramUserId: input.telegramUserId,
+        displayName: input.displayName,
+        isAdmin: input.isAdmin === true
+      }
+      members.set(input.telegramUserId, record)
+      return record
+    },
+    getHouseholdMember: async (_householdId, telegramUserId) => members.get(telegramUserId) ?? null,
+    listPendingHouseholdMembers: async () => [...pendingMembers.values()],
+    approvePendingHouseholdMember: async (input) => {
+      const pending = pendingMembers.get(input.telegramUserId)
+      if (!pending) {
+        return null
+      }
+
+      pendingMembers.delete(input.telegramUserId)
+
+      const member: HouseholdMemberRecord = {
+        householdId: pending.householdId,
+        telegramUserId: pending.telegramUserId,
+        displayName: pending.displayName,
+        isAdmin: input.isAdmin === true
+      }
+      members.set(member.telegramUserId, member)
+      return member
+    }
+  }
+
+  return {
+    repository
+  }
+}
+
+describe('createHouseholdAdminService', () => {
+  test('lists pending members for a household admin', async () => {
+    const { repository } = createRepositoryStub()
+    const service = createHouseholdAdminService(repository)
+
+    const result = await service.listPendingMembers({
+      actorTelegramUserId: '1',
+      telegramChatId: '-100123'
+    })
+
+    expect(result.status).toBe('ok')
+    if (result.status !== 'ok') {
+      return
+    }
+
+    expect(result.members).toEqual([
+      {
+        householdId: 'household-1',
+        householdName: 'Kojori House',
+        telegramUserId: '2',
+        displayName: 'Alice',
+        username: 'alice',
+        languageCode: 'en'
+      }
+    ])
+  })
+
+  test('rejects pending list for a non-admin member', async () => {
+    const { repository } = createRepositoryStub()
+    const service = createHouseholdAdminService(repository)
+
+    const result = await service.listPendingMembers({
+      actorTelegramUserId: '2',
+      telegramChatId: '-100123'
+    })
+
+    expect(result).toEqual({
+      status: 'rejected',
+      reason: 'not_admin'
+    })
+  })
+
+  test('approves a pending member into active members', async () => {
+    const { repository } = createRepositoryStub()
+    const service = createHouseholdAdminService(repository)
+
+    const result = await service.approvePendingMember({
+      actorTelegramUserId: '1',
+      telegramChatId: '-100123',
+      pendingTelegramUserId: '2'
+    })
+
+    expect(result).toEqual({
+      status: 'approved',
+      householdName: 'Kojori House',
+      member: {
+        householdId: 'household-1',
+        telegramUserId: '2',
+        displayName: 'Alice',
+        isAdmin: false
+      }
+    })
+  })
+})

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

@@ -0,0 +1,109 @@
+import type {
+  HouseholdConfigurationRepository,
+  HouseholdMemberRecord,
+  HouseholdPendingMemberRecord
+} from '@household/ports'
+
+export interface HouseholdAdminService {
+  listPendingMembers(input: { actorTelegramUserId: string; telegramChatId: string }): Promise<
+    | {
+        status: 'ok'
+        householdName: string
+        members: readonly HouseholdPendingMemberRecord[]
+      }
+    | {
+        status: 'rejected'
+        reason: 'household_not_found' | 'not_admin'
+      }
+  >
+  approvePendingMember(input: {
+    actorTelegramUserId: string
+    telegramChatId: string
+    pendingTelegramUserId: string
+  }): Promise<
+    | {
+        status: 'approved'
+        householdName: string
+        member: HouseholdMemberRecord
+      }
+    | {
+        status: 'rejected'
+        reason: 'household_not_found' | 'not_admin' | 'pending_not_found'
+      }
+  >
+}
+
+export function createHouseholdAdminService(
+  repository: HouseholdConfigurationRepository
+): HouseholdAdminService {
+  async function resolveAuthorizedHousehold(input: {
+    actorTelegramUserId: string
+    telegramChatId: string
+  }) {
+    const household = await repository.getTelegramHouseholdChat(input.telegramChatId)
+    if (!household) {
+      return {
+        status: 'rejected' as const,
+        reason: 'household_not_found' as const
+      }
+    }
+
+    const actor = await repository.getHouseholdMember(
+      household.householdId,
+      input.actorTelegramUserId
+    )
+    if (!actor?.isAdmin) {
+      return {
+        status: 'rejected' as const,
+        reason: 'not_admin' as const
+      }
+    }
+
+    return {
+      status: 'ok' as const,
+      household
+    }
+  }
+
+  return {
+    async listPendingMembers(input) {
+      const access = await resolveAuthorizedHousehold(input)
+      if (access.status === 'rejected') {
+        return access
+      }
+
+      const members = await repository.listPendingHouseholdMembers(access.household.householdId)
+
+      return {
+        status: 'ok',
+        householdName: access.household.householdName,
+        members
+      }
+    },
+
+    async approvePendingMember(input) {
+      const access = await resolveAuthorizedHousehold(input)
+      if (access.status === 'rejected') {
+        return access
+      }
+
+      const member = await repository.approvePendingHouseholdMember({
+        householdId: access.household.householdId,
+        telegramUserId: input.pendingTelegramUserId
+      })
+
+      if (!member) {
+        return {
+          status: 'rejected',
+          reason: 'pending_not_found'
+        }
+      }
+
+      return {
+        status: 'approved',
+        householdName: access.household.householdName,
+        member
+      }
+    }
+  }
+}

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

@@ -82,6 +82,35 @@ function createRepositoryStub() {
     },
     async findPendingHouseholdMemberByTelegramUserId(telegramUserId) {
       return pendingMembers.get(telegramUserId) ?? null
+    },
+    async ensureHouseholdMember(input) {
+      return {
+        householdId: input.householdId,
+        telegramUserId: input.telegramUserId,
+        displayName: input.displayName,
+        isAdmin: input.isAdmin === true
+      }
+    },
+    async getHouseholdMember() {
+      return null
+    },
+    async listPendingHouseholdMembers() {
+      return [...pendingMembers.values()]
+    },
+    async approvePendingHouseholdMember(input) {
+      const pending = pendingMembers.get(input.telegramUserId)
+      if (!pending) {
+        return null
+      }
+
+      pendingMembers.delete(input.telegramUserId)
+
+      return {
+        householdId: pending.householdId,
+        telegramUserId: pending.telegramUserId,
+        displayName: pending.displayName,
+        isAdmin: input.isAdmin === true
+      }
     }
   }
 

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

@@ -3,6 +3,7 @@ import { describe, expect, test } from 'bun:test'
 import type {
   HouseholdConfigurationRepository,
   HouseholdJoinTokenRecord,
+  HouseholdMemberRecord,
   HouseholdPendingMemberRecord,
   HouseholdTelegramChatRecord,
   HouseholdTopicBindingRecord
@@ -15,6 +16,7 @@ function createRepositoryStub() {
   const bindings = new Map<string, HouseholdTopicBindingRecord[]>()
   const joinTokens = new Map<string, HouseholdJoinTokenRecord>()
   const pendingMembers = new Map<string, HouseholdPendingMemberRecord>()
+  const members = new Map<string, HouseholdMemberRecord>()
 
   const repository: HouseholdConfigurationRepository = {
     async registerTelegramHouseholdChat(input) {
@@ -148,6 +150,46 @@ function createRepositoryStub() {
         [...pendingMembers.values()].find((entry) => entry.telegramUserId === telegramUserId) ??
         null
       )
+    },
+
+    async ensureHouseholdMember(input) {
+      const key = `${input.householdId}:${input.telegramUserId}`
+      const existing = members.get(key)
+      const next: HouseholdMemberRecord = {
+        householdId: input.householdId,
+        telegramUserId: input.telegramUserId,
+        displayName: input.displayName,
+        isAdmin: input.isAdmin === true || existing?.isAdmin === true
+      }
+      members.set(key, next)
+      return next
+    },
+
+    async getHouseholdMember(householdId, telegramUserId) {
+      return members.get(`${householdId}:${telegramUserId}`) ?? null
+    },
+
+    async listPendingHouseholdMembers(householdId) {
+      return [...pendingMembers.values()].filter((entry) => entry.householdId === householdId)
+    },
+
+    async approvePendingHouseholdMember(input) {
+      const key = `${input.householdId}:${input.telegramUserId}`
+      const pending = pendingMembers.get(key)
+      if (!pending) {
+        return null
+      }
+
+      pendingMembers.delete(key)
+
+      const member: HouseholdMemberRecord = {
+        householdId: pending.householdId,
+        telegramUserId: pending.telegramUserId,
+        displayName: pending.displayName,
+        isAdmin: input.isAdmin === true
+      }
+      members.set(key, member)
+      return member
     }
   }
 
@@ -163,6 +205,8 @@ describe('createHouseholdSetupService', () => {
 
     const result = await service.setupGroupChat({
       actorIsAdmin: true,
+      actorTelegramUserId: '42',
+      actorDisplayName: 'Stan',
       telegramChatId: '-100123',
       telegramChatType: 'supergroup',
       title: 'Kojori House'
@@ -174,6 +218,13 @@ describe('createHouseholdSetupService', () => {
     }
     expect(result.household.householdName).toBe('Kojori House')
     expect(result.household.telegramChatId).toBe('-100123')
+    const admin = await repository.getHouseholdMember(result.household.householdId, '42')
+    expect(admin).toEqual({
+      householdId: result.household.householdId,
+      telegramUserId: '42',
+      displayName: 'Stan',
+      isAdmin: true
+    })
   })
 
   test('rejects setup when the actor is not a group admin', async () => {

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

@@ -8,6 +8,8 @@ import type {
 export interface HouseholdSetupService {
   setupGroupChat(input: {
     actorIsAdmin: boolean
+    actorTelegramUserId?: string
+    actorDisplayName?: string
     telegramChatId: string
     telegramChatType: string
     title?: string
@@ -83,6 +85,15 @@ export function createHouseholdSetupService(
           : {})
       })
 
+      if (registered.status === 'created' && input.actorTelegramUserId && input.actorDisplayName) {
+        await repository.ensureHouseholdMember({
+          householdId: registered.household.householdId,
+          telegramUserId: input.actorTelegramUserId,
+          displayName: input.actorDisplayName,
+          isAdmin: true
+        })
+      }
+
       return {
         status: registered.status,
         household: registered.household

packages/application/src/index.ts

@@ -6,6 +6,7 @@ export {
 } from './anonymous-feedback-service'
 export { createFinanceCommandService, type FinanceCommandService } from './finance-command-service'
 export { createHouseholdSetupService, type HouseholdSetupService } from './household-setup-service'
+export { createHouseholdAdminService, type HouseholdAdminService } from './household-admin-service'
 export {
   createHouseholdOnboardingService,
   type HouseholdMiniAppAccess,