feat(miniapp): add pending member admin approval

apps/bot/src/index.ts

@@ -5,6 +5,7 @@ import {
   createHouseholdAdminService,
   createFinanceCommandService,
   createHouseholdOnboardingService,
+  createMiniAppAdminService,
   createHouseholdSetupService,
   createReminderJobService
 } from '@household/application'
@@ -32,6 +33,10 @@ import { createSchedulerRequestAuthorizer } from './scheduler-auth'
 import { createBotWebhookServer } from './server'
 import { createMiniAppAuthHandler, createMiniAppJoinHandler } from './miniapp-auth'
 import { createMiniAppDashboardHandler } from './miniapp-dashboard'
+import {
+  createMiniAppApproveMemberHandler,
+  createMiniAppPendingMembersHandler
+} from './miniapp-admin'
 
 const runtime = getBotRuntimeConfig()
 configureLogger({
@@ -54,6 +59,9 @@ const householdOnboardingService = householdConfigurationRepositoryClient
       repository: householdConfigurationRepositoryClient.repository
     })
   : null
+const miniAppAdminService = householdConfigurationRepositoryClient
+  ? createMiniAppAdminService(householdConfigurationRepositoryClient.repository)
+  : null
 const telegramPendingActionRepositoryClient =
   runtime.databaseUrl && runtime.anonymousFeedbackEnabled
     ? createDbTelegramPendingActionRepository(runtime.databaseUrl!)
@@ -253,6 +261,24 @@ const server = createBotWebhookServer({
         logger: getLogger('miniapp-dashboard')
       })
     : undefined,
+  miniAppPendingMembers: householdOnboardingService
+    ? createMiniAppPendingMembersHandler({
+        allowedOrigins: runtime.miniAppAllowedOrigins,
+        botToken: runtime.telegramBotToken,
+        onboardingService: householdOnboardingService,
+        miniAppAdminService: miniAppAdminService!,
+        logger: getLogger('miniapp-admin')
+      })
+    : undefined,
+  miniAppApproveMember: householdOnboardingService
+    ? createMiniAppApproveMemberHandler({
+        allowedOrigins: runtime.miniAppAllowedOrigins,
+        botToken: runtime.telegramBotToken,
+        onboardingService: householdOnboardingService,
+        miniAppAdminService: miniAppAdminService!,
+        logger: getLogger('miniapp-admin')
+      })
+    : undefined,
   scheduler:
     reminderJobs && runtime.schedulerSharedSecret
       ? {

apps/bot/src/miniapp-admin.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from 'bun:test'
+
+import { createHouseholdOnboardingService, createMiniAppAdminService } from '@household/application'
+import type {
+  HouseholdConfigurationRepository,
+  HouseholdTopicBindingRecord
+} from '@household/ports'
+
+import {
+  createMiniAppApproveMemberHandler,
+  createMiniAppPendingMembersHandler
+} from './miniapp-admin'
+import { buildMiniAppInitData } from './telegram-miniapp-test-helpers'
+
+function onboardingRepository(): HouseholdConfigurationRepository {
+  const household = {
+    householdId: 'household-1',
+    householdName: 'Kojori House',
+    telegramChatId: '-100123',
+    telegramChatType: 'supergroup',
+    title: 'Kojori House'
+  }
+
+  return {
+    registerTelegramHouseholdChat: async () => ({
+      status: 'existing',
+      household
+    }),
+    getTelegramHouseholdChat: async () => household,
+    getHouseholdChatByHouseholdId: 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
+    }),
+    getHouseholdJoinToken: async () => null,
+    getHouseholdByJoinToken: async () => null,
+    upsertPendingHouseholdMember: async (input) => ({
+      householdId: household.householdId,
+      householdName: household.householdName,
+      telegramUserId: input.telegramUserId,
+      displayName: input.displayName,
+      username: input.username?.trim() || null,
+      languageCode: input.languageCode?.trim() || null
+    }),
+    getPendingHouseholdMember: async () => null,
+    findPendingHouseholdMemberByTelegramUserId: async () => null,
+    ensureHouseholdMember: async (input) => ({
+      id: `member-${input.telegramUserId}`,
+      householdId: household.householdId,
+      telegramUserId: input.telegramUserId,
+      displayName: input.displayName,
+      isAdmin: input.isAdmin === true
+    }),
+    getHouseholdMember: async () => null,
+    listHouseholdMembersByTelegramUserId: async () => [],
+    listPendingHouseholdMembers: async () => [
+      {
+        householdId: household.householdId,
+        householdName: household.householdName,
+        telegramUserId: '555777',
+        displayName: 'Mia',
+        username: 'mia',
+        languageCode: 'ru'
+      }
+    ],
+    approvePendingHouseholdMember: async (input) =>
+      input.telegramUserId === '555777'
+        ? {
+            id: 'member-555777',
+            householdId: household.householdId,
+            telegramUserId: '555777',
+            displayName: 'Mia',
+            isAdmin: false
+          }
+        : null
+  }
+}
+
+describe('createMiniAppPendingMembersHandler', () => {
+  test('lists pending members for an authenticated admin', async () => {
+    const authDate = Math.floor(Date.now() / 1000)
+    const repository = onboardingRepository()
+    repository.listHouseholdMembersByTelegramUserId = async () => [
+      {
+        id: 'member-123456',
+        householdId: 'household-1',
+        telegramUserId: '123456',
+        displayName: 'Stan',
+        isAdmin: true
+      }
+    ]
+
+    const handler = createMiniAppPendingMembersHandler({
+      allowedOrigins: ['http://localhost:5173'],
+      botToken: 'test-bot-token',
+      onboardingService: createHouseholdOnboardingService({
+        repository
+      }),
+      miniAppAdminService: createMiniAppAdminService(repository)
+    })
+
+    const response = await handler.handler(
+      new Request('http://localhost/api/miniapp/admin/pending-members', {
+        method: 'POST',
+        headers: {
+          origin: 'http://localhost:5173',
+          'content-type': 'application/json'
+        },
+        body: JSON.stringify({
+          initData: buildMiniAppInitData('test-bot-token', authDate, {
+            id: 123456,
+            first_name: 'Stan',
+            username: 'stanislav',
+            language_code: 'ru'
+          })
+        })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      members: [
+        {
+          householdId: 'household-1',
+          householdName: 'Kojori House',
+          telegramUserId: '555777',
+          displayName: 'Mia',
+          username: 'mia',
+          languageCode: 'ru'
+        }
+      ]
+    })
+  })
+})
+
+describe('createMiniAppApproveMemberHandler', () => {
+  test('approves a pending member for an authenticated admin', async () => {
+    const authDate = Math.floor(Date.now() / 1000)
+    const repository = onboardingRepository()
+    repository.listHouseholdMembersByTelegramUserId = async () => [
+      {
+        id: 'member-123456',
+        householdId: 'household-1',
+        telegramUserId: '123456',
+        displayName: 'Stan',
+        isAdmin: true
+      }
+    ]
+
+    const handler = createMiniAppApproveMemberHandler({
+      allowedOrigins: ['http://localhost:5173'],
+      botToken: 'test-bot-token',
+      onboardingService: createHouseholdOnboardingService({
+        repository
+      }),
+      miniAppAdminService: createMiniAppAdminService(repository)
+    })
+
+    const response = await handler.handler(
+      new Request('http://localhost/api/miniapp/admin/approve-member', {
+        method: 'POST',
+        headers: {
+          origin: 'http://localhost:5173',
+          'content-type': 'application/json'
+        },
+        body: JSON.stringify({
+          initData: buildMiniAppInitData('test-bot-token', authDate, {
+            id: 123456,
+            first_name: 'Stan',
+            username: 'stanislav',
+            language_code: 'ru'
+          }),
+          pendingTelegramUserId: '555777'
+        })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      member: {
+        id: 'member-555777',
+        householdId: 'household-1',
+        telegramUserId: '555777',
+        displayName: 'Mia',
+        isAdmin: false
+      }
+    })
+  })
+})

apps/bot/src/miniapp-admin.ts

@@ -0,0 +1,193 @@
+import type { HouseholdOnboardingService, MiniAppAdminService } from '@household/application'
+import type { Logger } from '@household/observability'
+
+import {
+  allowedMiniAppOrigin,
+  createMiniAppSessionService,
+  miniAppErrorResponse,
+  miniAppJsonResponse,
+  readMiniAppRequestPayload
+} from './miniapp-auth'
+
+async function readApprovalPayload(request: Request): Promise<{
+  initData: string
+  pendingTelegramUserId: string
+}> {
+  const clonedRequest = request.clone()
+  const payload = await readMiniAppRequestPayload(request)
+  if (!payload.initData) {
+    throw new Error('Missing initData')
+  }
+
+  const text = await clonedRequest.text()
+  let parsed: { pendingTelegramUserId?: string }
+  try {
+    parsed = JSON.parse(text) as { pendingTelegramUserId?: string }
+  } catch {
+    throw new Error('Invalid JSON body')
+  }
+
+  const pendingTelegramUserId = parsed.pendingTelegramUserId?.trim()
+  if (!pendingTelegramUserId) {
+    throw new Error('Missing pendingTelegramUserId')
+  }
+
+  return {
+    initData: payload.initData,
+    pendingTelegramUserId
+  }
+}
+
+export function createMiniAppPendingMembersHandler(options: {
+  allowedOrigins: readonly string[]
+  botToken: string
+  onboardingService: HouseholdOnboardingService
+  miniAppAdminService: MiniAppAdminService
+  logger?: Logger
+}): {
+  handler: (request: Request) => Promise<Response>
+} {
+  const sessionService = createMiniAppSessionService({
+    botToken: options.botToken,
+    onboardingService: options.onboardingService
+  })
+
+  return {
+    handler: async (request) => {
+      const origin = allowedMiniAppOrigin(request, options.allowedOrigins)
+
+      if (request.method === 'OPTIONS') {
+        return miniAppJsonResponse({ ok: true }, 204, origin)
+      }
+
+      if (request.method !== 'POST') {
+        return miniAppJsonResponse({ ok: false, error: 'Method Not Allowed' }, 405, origin)
+      }
+
+      try {
+        const payload = await readMiniAppRequestPayload(request)
+        if (!payload.initData) {
+          return miniAppJsonResponse({ ok: false, error: 'Missing initData' }, 400, origin)
+        }
+
+        const session = await sessionService.authenticate(payload)
+        if (!session) {
+          return miniAppJsonResponse(
+            { ok: false, error: 'Invalid Telegram init data' },
+            401,
+            origin
+          )
+        }
+
+        if (!session.authorized || !session.member) {
+          return miniAppJsonResponse(
+            { ok: false, error: 'Access limited to active household members' },
+            403,
+            origin
+          )
+        }
+
+        const result = await options.miniAppAdminService.listPendingMembers({
+          householdId: session.member.householdId,
+          actorIsAdmin: session.member.isAdmin
+        })
+
+        if (result.status === 'rejected') {
+          return miniAppJsonResponse({ ok: false, error: 'Admin access required' }, 403, origin)
+        }
+
+        return miniAppJsonResponse(
+          {
+            ok: true,
+            authorized: true,
+            members: result.members
+          },
+          200,
+          origin
+        )
+      } catch (error) {
+        return miniAppErrorResponse(error, origin, options.logger)
+      }
+    }
+  }
+}
+
+export function createMiniAppApproveMemberHandler(options: {
+  allowedOrigins: readonly string[]
+  botToken: string
+  onboardingService: HouseholdOnboardingService
+  miniAppAdminService: MiniAppAdminService
+  logger?: Logger
+}): {
+  handler: (request: Request) => Promise<Response>
+} {
+  const sessionService = createMiniAppSessionService({
+    botToken: options.botToken,
+    onboardingService: options.onboardingService
+  })
+
+  return {
+    handler: async (request) => {
+      const origin = allowedMiniAppOrigin(request, options.allowedOrigins)
+
+      if (request.method === 'OPTIONS') {
+        return miniAppJsonResponse({ ok: true }, 204, origin)
+      }
+
+      if (request.method !== 'POST') {
+        return miniAppJsonResponse({ ok: false, error: 'Method Not Allowed' }, 405, origin)
+      }
+
+      try {
+        const payload = await readApprovalPayload(request)
+
+        const session = await sessionService.authenticate({
+          initData: payload.initData
+        })
+        if (!session) {
+          return miniAppJsonResponse(
+            { ok: false, error: 'Invalid Telegram init data' },
+            401,
+            origin
+          )
+        }
+
+        if (!session.authorized || !session.member) {
+          return miniAppJsonResponse(
+            { ok: false, error: 'Access limited to active household members' },
+            403,
+            origin
+          )
+        }
+
+        const result = await options.miniAppAdminService.approvePendingMember({
+          householdId: session.member.householdId,
+          actorIsAdmin: session.member.isAdmin,
+          pendingTelegramUserId: payload.pendingTelegramUserId
+        })
+
+        if (result.status === 'rejected') {
+          const status = result.reason === 'pending_not_found' ? 404 : 403
+          const error =
+            result.reason === 'pending_not_found'
+              ? 'Pending member not found'
+              : 'Admin access required'
+
+          return miniAppJsonResponse({ ok: false, error }, status, origin)
+        }
+
+        return miniAppJsonResponse(
+          {
+            ok: true,
+            authorized: true,
+            member: result.member
+          },
+          200,
+          origin
+        )
+      } catch (error) {
+        return miniAppErrorResponse(error, origin, options.logger)
+      }
+    }
+  }
+}

apps/bot/src/server.test.ts

@@ -25,6 +25,24 @@ describe('createBotWebhookServer', () => {
           }
         })
     },
+    miniAppPendingMembers: {
+      handler: async () =>
+        new Response(JSON.stringify({ ok: true, authorized: true, members: [] }), {
+          status: 200,
+          headers: {
+            'content-type': 'application/json; charset=utf-8'
+          }
+        })
+    },
+    miniAppApproveMember: {
+      handler: async () =>
+        new Response(JSON.stringify({ ok: true, authorized: true, member: {} }), {
+          status: 200,
+          headers: {
+            'content-type': 'application/json; charset=utf-8'
+          }
+        })
+    },
     scheduler: {
       authorize: async (request) =>
         request.headers.get('x-household-scheduler-secret') === 'scheduler-secret',
@@ -120,6 +138,38 @@ describe('createBotWebhookServer', () => {
     })
   })
 
+  test('accepts mini app pending members request', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/api/miniapp/admin/pending-members', {
+        method: 'POST',
+        body: JSON.stringify({ initData: 'payload' })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      members: []
+    })
+  })
+
+  test('accepts mini app approve member request', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/api/miniapp/admin/approve-member', {
+        method: 'POST',
+        body: JSON.stringify({ initData: 'payload', pendingTelegramUserId: '123456' })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      member: {}
+    })
+  })
+
   test('rejects scheduler request with missing secret', async () => {
     const response = await server.fetch(
       new Request('http://localhost/jobs/reminder/utilities', {

apps/bot/src/server.ts

@@ -20,6 +20,18 @@ export interface BotWebhookServerOptions {
         handler: (request: Request) => Promise<Response>
       }
     | undefined
+  miniAppPendingMembers?:
+    | {
+        path?: string
+        handler: (request: Request) => Promise<Response>
+      }
+    | undefined
+  miniAppApproveMember?:
+    | {
+        path?: string
+        handler: (request: Request) => Promise<Response>
+      }
+    | undefined
   scheduler?:
     | {
         pathPrefix?: string
@@ -53,6 +65,10 @@ export function createBotWebhookServer(options: BotWebhookServerOptions): {
   const miniAppAuthPath = options.miniAppAuth?.path ?? '/api/miniapp/session'
   const miniAppDashboardPath = options.miniAppDashboard?.path ?? '/api/miniapp/dashboard'
   const miniAppJoinPath = options.miniAppJoin?.path ?? '/api/miniapp/join'
+  const miniAppPendingMembersPath =
+    options.miniAppPendingMembers?.path ?? '/api/miniapp/admin/pending-members'
+  const miniAppApproveMemberPath =
+    options.miniAppApproveMember?.path ?? '/api/miniapp/admin/approve-member'
   const schedulerPathPrefix = options.scheduler
     ? (options.scheduler.pathPrefix ?? '/jobs/reminder')
     : null
@@ -77,6 +93,14 @@ export function createBotWebhookServer(options: BotWebhookServerOptions): {
         return await options.miniAppJoin.handler(request)
       }
 
+      if (options.miniAppPendingMembers && url.pathname === miniAppPendingMembersPath) {
+        return await options.miniAppPendingMembers.handler(request)
+      }
+
+      if (options.miniAppApproveMember && url.pathname === miniAppApproveMemberPath) {
+        return await options.miniAppApproveMember.handler(request)
+      }
+
       if (url.pathname !== normalizedWebhookPath) {
         if (schedulerPathPrefix && url.pathname.startsWith(`${schedulerPathPrefix}/`)) {
           if (request.method !== 'POST') {