feat(bot): add household admin approval flow

packages/adapters-db/src/household-config-repository.ts

@@ -5,6 +5,7 @@ import {
   HOUSEHOLD_TOPIC_ROLES,
   type HouseholdConfigurationRepository,
   type HouseholdJoinTokenRecord,
+  type HouseholdMemberRecord,
   type HouseholdPendingMemberRecord,
   type HouseholdTelegramChatRecord,
   type HouseholdTopicBindingRecord,
@@ -84,6 +85,20 @@ function toHouseholdPendingMemberRecord(row: {
   }
 }
 
+function toHouseholdMemberRecord(row: {
+  householdId: string
+  telegramUserId: string
+  displayName: string
+  isAdmin: number
+}): HouseholdMemberRecord {
+  return {
+    householdId: row.householdId,
+    telegramUserId: row.telegramUserId,
+    displayName: row.displayName,
+    isAdmin: row.isAdmin === 1
+  }
+}
+
 export function createDbHouseholdConfigurationRepository(databaseUrl: string): {
   repository: HouseholdConfigurationRepository
   close: () => Promise<void>
@@ -497,6 +512,156 @@ export function createDbHouseholdConfigurationRepository(databaseUrl: string): {
 
       const row = rows[0]
       return row ? toHouseholdPendingMemberRecord(row) : null
+    },
+
+    async ensureHouseholdMember(input) {
+      const rows = await db
+        .insert(schema.members)
+        .values({
+          householdId: input.householdId,
+          telegramUserId: input.telegramUserId,
+          displayName: input.displayName,
+          isAdmin: input.isAdmin ? 1 : 0
+        })
+        .onConflictDoUpdate({
+          target: [schema.members.householdId, schema.members.telegramUserId],
+          set: {
+            displayName: input.displayName,
+            ...(input.isAdmin
+              ? {
+                  isAdmin: 1
+                }
+              : {})
+          }
+        })
+        .returning({
+          householdId: schema.members.householdId,
+          telegramUserId: schema.members.telegramUserId,
+          displayName: schema.members.displayName,
+          isAdmin: schema.members.isAdmin
+        })
+
+      const row = rows[0]
+      if (!row) {
+        throw new Error('Failed to ensure household member')
+      }
+
+      return toHouseholdMemberRecord(row)
+    },
+
+    async getHouseholdMember(householdId, telegramUserId) {
+      const rows = await db
+        .select({
+          householdId: schema.members.householdId,
+          telegramUserId: schema.members.telegramUserId,
+          displayName: schema.members.displayName,
+          isAdmin: schema.members.isAdmin
+        })
+        .from(schema.members)
+        .where(
+          and(
+            eq(schema.members.householdId, householdId),
+            eq(schema.members.telegramUserId, telegramUserId)
+          )
+        )
+        .limit(1)
+
+      const row = rows[0]
+      return row ? toHouseholdMemberRecord(row) : null
+    },
+
+    async listPendingHouseholdMembers(householdId) {
+      const rows = await db
+        .select({
+          householdId: schema.householdPendingMembers.householdId,
+          householdName: schema.households.name,
+          telegramUserId: schema.householdPendingMembers.telegramUserId,
+          displayName: schema.householdPendingMembers.displayName,
+          username: schema.householdPendingMembers.username,
+          languageCode: schema.householdPendingMembers.languageCode
+        })
+        .from(schema.householdPendingMembers)
+        .innerJoin(
+          schema.households,
+          eq(schema.householdPendingMembers.householdId, schema.households.id)
+        )
+        .where(eq(schema.householdPendingMembers.householdId, householdId))
+        .orderBy(schema.householdPendingMembers.createdAt)
+
+      return rows.map(toHouseholdPendingMemberRecord)
+    },
+
+    async approvePendingHouseholdMember(input) {
+      return await db.transaction(async (tx) => {
+        const pendingRows = await tx
+          .select({
+            householdId: schema.householdPendingMembers.householdId,
+            householdName: schema.households.name,
+            telegramUserId: schema.householdPendingMembers.telegramUserId,
+            displayName: schema.householdPendingMembers.displayName,
+            username: schema.householdPendingMembers.username,
+            languageCode: schema.householdPendingMembers.languageCode
+          })
+          .from(schema.householdPendingMembers)
+          .innerJoin(
+            schema.households,
+            eq(schema.householdPendingMembers.householdId, schema.households.id)
+          )
+          .where(
+            and(
+              eq(schema.householdPendingMembers.householdId, input.householdId),
+              eq(schema.householdPendingMembers.telegramUserId, input.telegramUserId)
+            )
+          )
+          .limit(1)
+
+        const pending = pendingRows[0]
+        if (!pending) {
+          return null
+        }
+
+        const memberRows = await tx
+          .insert(schema.members)
+          .values({
+            householdId: pending.householdId,
+            telegramUserId: pending.telegramUserId,
+            displayName: pending.displayName,
+            isAdmin: input.isAdmin ? 1 : 0
+          })
+          .onConflictDoUpdate({
+            target: [schema.members.householdId, schema.members.telegramUserId],
+            set: {
+              displayName: pending.displayName,
+              ...(input.isAdmin
+                ? {
+                    isAdmin: 1
+                  }
+                : {})
+            }
+          })
+          .returning({
+            householdId: schema.members.householdId,
+            telegramUserId: schema.members.telegramUserId,
+            displayName: schema.members.displayName,
+            isAdmin: schema.members.isAdmin
+          })
+
+        await tx
+          .delete(schema.householdPendingMembers)
+          .where(
+            and(
+              eq(schema.householdPendingMembers.householdId, input.householdId),
+              eq(schema.householdPendingMembers.telegramUserId, input.telegramUserId)
+            )
+          )
+
+        const member = memberRows[0]
+        if (!member) {
+          throw new Error('Failed to approve pending household member')
+        }
+
+        return toHouseholdMemberRecord(member)
+      })
     }
   }
 

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,

packages/ports/src/household-config.ts

@@ -33,6 +33,13 @@ export interface HouseholdPendingMemberRecord {
   languageCode: string | null
 }
 
+export interface HouseholdMemberRecord {
+  householdId: string
+  telegramUserId: string
+  displayName: string
+  isAdmin: boolean
+}
+
 export interface RegisterTelegramHouseholdChatInput {
   householdName: string
   telegramChatId: string
@@ -86,4 +93,20 @@ export interface HouseholdConfigurationRepository {
   findPendingHouseholdMemberByTelegramUserId(
     telegramUserId: string
   ): Promise<HouseholdPendingMemberRecord | null>
+  ensureHouseholdMember(input: {
+    householdId: string
+    telegramUserId: string
+    displayName: string
+    isAdmin?: boolean
+  }): Promise<HouseholdMemberRecord>
+  getHouseholdMember(
+    householdId: string,
+    telegramUserId: string
+  ): Promise<HouseholdMemberRecord | null>
+  listPendingHouseholdMembers(householdId: string): Promise<readonly HouseholdPendingMemberRecord[]>
+  approvePendingHouseholdMember(input: {
+    householdId: string
+    telegramUserId: string
+    isAdmin?: boolean
+  }): Promise<HouseholdMemberRecord | null>
 }

packages/ports/src/index.ts

@@ -9,6 +9,7 @@ export {
   HOUSEHOLD_TOPIC_ROLES,
   type HouseholdConfigurationRepository,
   type HouseholdJoinTokenRecord,
+  type HouseholdMemberRecord,
   type HouseholdPendingMemberRecord,
   type HouseholdTelegramChatRecord,
   type HouseholdTopicBindingRecord,