feat(miniapp): add admin billing settings foundation

apps/bot/src/anonymous-feedback.test.ts

@@ -192,7 +192,37 @@ function createHouseholdConfigurationRepository(): HouseholdConfigurationReposit
       preferredLocale: locale,
       householdDefaultLocale: 'ru',
       isAdmin: false
-    })
+    }),
+    getHouseholdBillingSettings: async (householdId) => ({
+      householdId,
+      rentAmountMinor: null,
+      rentCurrency: 'USD',
+      rentDueDay: 20,
+      rentWarningDay: 17,
+      utilitiesDueDay: 4,
+      utilitiesReminderDay: 3,
+      timezone: 'Asia/Tbilisi'
+    }),
+    updateHouseholdBillingSettings: async (input) => ({
+      householdId: input.householdId,
+      rentAmountMinor: input.rentAmountMinor ?? null,
+      rentCurrency: input.rentCurrency ?? 'USD',
+      rentDueDay: input.rentDueDay ?? 20,
+      rentWarningDay: input.rentWarningDay ?? 17,
+      utilitiesDueDay: input.utilitiesDueDay ?? 4,
+      utilitiesReminderDay: input.utilitiesReminderDay ?? 3,
+      timezone: input.timezone ?? 'Asia/Tbilisi'
+    }),
+    listHouseholdUtilityCategories: async () => [],
+    upsertHouseholdUtilityCategory: async (input) => ({
+      id: input.slug ?? 'utility-category-1',
+      householdId: input.householdId,
+      slug: input.slug ?? 'custom',
+      name: input.name,
+      sortOrder: input.sortOrder,
+      isActive: input.isActive
+    }),
+    promoteHouseholdAdmin: async () => null
   }
 }
 

apps/bot/src/index.ts

@@ -36,7 +36,11 @@ import { createMiniAppAuthHandler, createMiniAppJoinHandler } from './miniapp-au
 import { createMiniAppDashboardHandler } from './miniapp-dashboard'
 import {
   createMiniAppApproveMemberHandler,
-  createMiniAppPendingMembersHandler
+  createMiniAppPendingMembersHandler,
+  createMiniAppPromoteMemberHandler,
+  createMiniAppSettingsHandler,
+  createMiniAppUpdateSettingsHandler,
+  createMiniAppUpsertUtilityCategoryHandler
 } from './miniapp-admin'
 import { createMiniAppLocalePreferenceHandler } from './miniapp-locale'
 
@@ -311,6 +315,42 @@ const server = createBotWebhookServer({
         logger: getLogger('miniapp-admin')
       })
     : undefined,
+  miniAppSettings: householdOnboardingService
+    ? createMiniAppSettingsHandler({
+        allowedOrigins: runtime.miniAppAllowedOrigins,
+        botToken: runtime.telegramBotToken,
+        onboardingService: householdOnboardingService,
+        miniAppAdminService: miniAppAdminService!,
+        logger: getLogger('miniapp-admin')
+      })
+    : undefined,
+  miniAppUpdateSettings: householdOnboardingService
+    ? createMiniAppUpdateSettingsHandler({
+        allowedOrigins: runtime.miniAppAllowedOrigins,
+        botToken: runtime.telegramBotToken,
+        onboardingService: householdOnboardingService,
+        miniAppAdminService: miniAppAdminService!,
+        logger: getLogger('miniapp-admin')
+      })
+    : undefined,
+  miniAppUpsertUtilityCategory: householdOnboardingService
+    ? createMiniAppUpsertUtilityCategoryHandler({
+        allowedOrigins: runtime.miniAppAllowedOrigins,
+        botToken: runtime.telegramBotToken,
+        onboardingService: householdOnboardingService,
+        miniAppAdminService: miniAppAdminService!,
+        logger: getLogger('miniapp-admin')
+      })
+    : undefined,
+  miniAppPromoteMember: householdOnboardingService
+    ? createMiniAppPromoteMemberHandler({
+        allowedOrigins: runtime.miniAppAllowedOrigins,
+        botToken: runtime.telegramBotToken,
+        onboardingService: householdOnboardingService,
+        miniAppAdminService: miniAppAdminService!,
+        logger: getLogger('miniapp-admin')
+      })
+    : undefined,
   miniAppLocalePreference: householdOnboardingService
     ? createMiniAppLocalePreferenceHandler({
         allowedOrigins: runtime.miniAppAllowedOrigins,

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

@@ -8,7 +8,10 @@ import type {
 
 import {
   createMiniAppApproveMemberHandler,
-  createMiniAppPendingMembersHandler
+  createMiniAppPendingMembersHandler,
+  createMiniAppPromoteMemberHandler,
+  createMiniAppSettingsHandler,
+  createMiniAppUpdateSettingsHandler
 } from './miniapp-admin'
 import { buildMiniAppInitData } from './telegram-miniapp-test-helpers'
 
@@ -109,7 +112,56 @@ function onboardingRepository(): HouseholdConfigurationRepository {
             householdDefaultLocale: household.defaultLocale,
             isAdmin: false
           }
+        : null,
+    getHouseholdBillingSettings: async (householdId) => ({
+      householdId,
+      rentAmountMinor: 70000n,
+      rentCurrency: 'USD',
+      rentDueDay: 20,
+      rentWarningDay: 17,
+      utilitiesDueDay: 4,
+      utilitiesReminderDay: 3,
+      timezone: 'Asia/Tbilisi'
+    }),
+    updateHouseholdBillingSettings: async (input) => ({
+      householdId: input.householdId,
+      rentAmountMinor: input.rentAmountMinor ?? 70000n,
+      rentCurrency: input.rentCurrency ?? 'USD',
+      rentDueDay: input.rentDueDay ?? 20,
+      rentWarningDay: input.rentWarningDay ?? 17,
+      utilitiesDueDay: input.utilitiesDueDay ?? 4,
+      utilitiesReminderDay: input.utilitiesReminderDay ?? 3,
+      timezone: input.timezone ?? 'Asia/Tbilisi'
+    }),
+    listHouseholdUtilityCategories: async () => [],
+    upsertHouseholdUtilityCategory: async (input) => ({
+      id: input.slug ?? 'utility-category-1',
+      householdId: input.householdId,
+      slug: input.slug ?? 'custom',
+      name: input.name,
+      sortOrder: input.sortOrder,
+      isActive: input.isActive
+    }),
+    promoteHouseholdAdmin: async (householdId, memberId) => {
+      const member = [
+        {
+          id: 'member-123456',
+          householdId,
+          telegramUserId: '123456',
+          displayName: 'Stan',
+          preferredLocale: null,
+          householdDefaultLocale: household.defaultLocale,
+          isAdmin: false
+        }
+      ].find((entry) => entry.id === memberId)
+
+      return member
+        ? {
+            ...member,
+            isAdmin: true
+          }
         : null
+    }
   }
 }
 
@@ -235,3 +287,216 @@ describe('createMiniAppApproveMemberHandler', () => {
     })
   })
 })
+
+describe('createMiniAppSettingsHandler', () => {
+  test('returns billing settings and admin 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',
+        preferredLocale: null,
+        householdDefaultLocale: 'ru',
+        isAdmin: true
+      }
+    ]
+    repository.listHouseholdMembers = async () => [
+      {
+        id: 'member-123456',
+        householdId: 'household-1',
+        telegramUserId: '123456',
+        displayName: 'Stan',
+        preferredLocale: null,
+        householdDefaultLocale: 'ru',
+        isAdmin: true
+      }
+    ]
+
+    const handler = createMiniAppSettingsHandler({
+      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/settings', {
+        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,
+      settings: {
+        householdId: 'household-1',
+        rentAmountMinor: '70000',
+        rentCurrency: 'USD',
+        rentDueDay: 20,
+        rentWarningDay: 17,
+        utilitiesDueDay: 4,
+        utilitiesReminderDay: 3,
+        timezone: 'Asia/Tbilisi'
+      },
+      categories: [],
+      members: [
+        {
+          id: 'member-123456',
+          householdId: 'household-1',
+          telegramUserId: '123456',
+          displayName: 'Stan',
+          preferredLocale: null,
+          householdDefaultLocale: 'ru',
+          isAdmin: true
+        }
+      ]
+    })
+  })
+})
+
+describe('createMiniAppUpdateSettingsHandler', () => {
+  test('updates billing settings 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',
+        preferredLocale: null,
+        householdDefaultLocale: 'ru',
+        isAdmin: true
+      }
+    ]
+
+    const handler = createMiniAppUpdateSettingsHandler({
+      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/settings/update', {
+        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'
+          }),
+          rentAmountMajor: '750',
+          rentCurrency: 'USD',
+          rentDueDay: 22,
+          rentWarningDay: 19,
+          utilitiesDueDay: 6,
+          utilitiesReminderDay: 5,
+          timezone: 'Asia/Tbilisi'
+        })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      settings: {
+        householdId: 'household-1',
+        rentAmountMinor: '75000',
+        rentCurrency: 'USD',
+        rentDueDay: 22,
+        rentWarningDay: 19,
+        utilitiesDueDay: 6,
+        utilitiesReminderDay: 5,
+        timezone: 'Asia/Tbilisi'
+      }
+    })
+  })
+})
+
+describe('createMiniAppPromoteMemberHandler', () => {
+  test('promotes a household member to admin 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',
+        preferredLocale: null,
+        householdDefaultLocale: 'ru',
+        isAdmin: true
+      }
+    ]
+
+    const handler = createMiniAppPromoteMemberHandler({
+      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/members/promote', {
+        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'
+          }),
+          memberId: 'member-123456'
+        })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      member: {
+        id: 'member-123456',
+        householdId: 'household-1',
+        telegramUserId: '123456',
+        displayName: 'Stan',
+        preferredLocale: null,
+        householdDefaultLocale: 'ru',
+        isAdmin: true
+      }
+    })
+  })
+})

apps/bot/src/miniapp-admin.ts

@@ -1,5 +1,7 @@
 import type { HouseholdOnboardingService, MiniAppAdminService } from '@household/application'
 import type { Logger } from '@household/observability'
+import type { HouseholdBillingSettingsRecord } from '@household/ports'
+import type { MiniAppSessionResult } from './miniapp-auth'
 
 import {
   allowedMiniAppOrigin,
@@ -38,6 +40,190 @@ async function readApprovalPayload(request: Request): Promise<{
   }
 }
 
+async function readSettingsUpdatePayload(request: Request): Promise<{
+  initData: string
+  rentAmountMajor?: string
+  rentCurrency?: string
+  rentDueDay: number
+  rentWarningDay: number
+  utilitiesDueDay: number
+  utilitiesReminderDay: number
+  timezone: 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: {
+    rentAmountMajor?: string
+    rentCurrency?: string
+    rentDueDay?: number
+    rentWarningDay?: number
+    utilitiesDueDay?: number
+    utilitiesReminderDay?: number
+    timezone?: string
+  }
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new Error('Invalid JSON body')
+  }
+
+  if (
+    typeof parsed.rentDueDay !== 'number' ||
+    typeof parsed.rentWarningDay !== 'number' ||
+    typeof parsed.utilitiesDueDay !== 'number' ||
+    typeof parsed.utilitiesReminderDay !== 'number' ||
+    typeof parsed.timezone !== 'string'
+  ) {
+    throw new Error('Missing billing settings fields')
+  }
+
+  return {
+    initData: payload.initData,
+    ...(typeof parsed.rentAmountMajor === 'string'
+      ? {
+          rentAmountMajor: parsed.rentAmountMajor
+        }
+      : {}),
+    ...(typeof parsed.rentCurrency === 'string'
+      ? {
+          rentCurrency: parsed.rentCurrency
+        }
+      : {}),
+    rentDueDay: parsed.rentDueDay,
+    rentWarningDay: parsed.rentWarningDay,
+    utilitiesDueDay: parsed.utilitiesDueDay,
+    utilitiesReminderDay: parsed.utilitiesReminderDay,
+    timezone: parsed.timezone
+  }
+}
+
+async function readUtilityCategoryPayload(request: Request): Promise<{
+  initData: string
+  slug?: string
+  name: string
+  sortOrder: number
+  isActive: boolean
+}> {
+  const clonedRequest = request.clone()
+  const payload = await readMiniAppRequestPayload(request)
+  if (!payload.initData) {
+    throw new Error('Missing initData')
+  }
+
+  const text = await clonedRequest.text()
+  let parsed: {
+    slug?: string
+    name?: string
+    sortOrder?: number
+    isActive?: boolean
+  }
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new Error('Invalid JSON body')
+  }
+
+  if (
+    typeof parsed.name !== 'string' ||
+    typeof parsed.sortOrder !== 'number' ||
+    typeof parsed.isActive !== 'boolean'
+  ) {
+    throw new Error('Missing utility category fields')
+  }
+
+  return {
+    initData: payload.initData,
+    ...(typeof parsed.slug === 'string' && parsed.slug.trim().length > 0
+      ? {
+          slug: parsed.slug.trim()
+        }
+      : {}),
+    name: parsed.name,
+    sortOrder: parsed.sortOrder,
+    isActive: parsed.isActive
+  }
+}
+
+async function readPromoteMemberPayload(request: Request): Promise<{
+  initData: string
+  memberId: 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: { memberId?: string }
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new Error('Invalid JSON body')
+  }
+
+  const memberId = parsed.memberId?.trim()
+  if (!memberId) {
+    throw new Error('Missing memberId')
+  }
+
+  return {
+    initData: payload.initData,
+    memberId
+  }
+}
+
+function serializeBillingSettings(settings: HouseholdBillingSettingsRecord) {
+  return {
+    householdId: settings.householdId,
+    rentAmountMinor: settings.rentAmountMinor?.toString() ?? null,
+    rentCurrency: settings.rentCurrency,
+    rentDueDay: settings.rentDueDay,
+    rentWarningDay: settings.rentWarningDay,
+    utilitiesDueDay: settings.utilitiesDueDay,
+    utilitiesReminderDay: settings.utilitiesReminderDay,
+    timezone: settings.timezone
+  }
+}
+
+async function authenticateAdminSession(
+  request: Request,
+  sessionService: ReturnType<typeof createMiniAppSessionService>,
+  origin: string | undefined
+): Promise<
+  | Response
+  | {
+      member: NonNullable<MiniAppSessionResult['member']>
+    }
+> {
+  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
+    )
+  }
+
+  return {
+    member: session.member
+  }
+}
+
 export function createMiniAppPendingMembersHandler(options: {
   allowedOrigins: readonly string[]
   botToken: string
@@ -112,6 +298,337 @@ export function createMiniAppPendingMembersHandler(options: {
   }
 }
 
+export function createMiniAppSettingsHandler(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 auth = await authenticateAdminSession(request, sessionService, origin)
+        if (auth instanceof Response) {
+          return auth
+        }
+        const { member } = auth
+
+        const result = await options.miniAppAdminService.getSettings({
+          householdId: member.householdId,
+          actorIsAdmin: member.isAdmin
+        })
+
+        if (result.status === 'rejected') {
+          return miniAppJsonResponse({ ok: false, error: 'Admin access required' }, 403, origin)
+        }
+
+        return miniAppJsonResponse(
+          {
+            ok: true,
+            authorized: true,
+            settings: serializeBillingSettings(result.settings),
+            categories: result.categories,
+            members: result.members
+          },
+          200,
+          origin
+        )
+      } catch (error) {
+        return miniAppErrorResponse(error, origin, options.logger)
+      }
+    }
+  }
+}
+
+export function createMiniAppUpdateSettingsHandler(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 readSettingsUpdatePayload(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.updateSettings({
+          householdId: session.member.householdId,
+          actorIsAdmin: session.member.isAdmin,
+          ...(payload.rentAmountMajor !== undefined
+            ? {
+                rentAmountMajor: payload.rentAmountMajor
+              }
+            : {}),
+          ...(payload.rentCurrency
+            ? {
+                rentCurrency: payload.rentCurrency
+              }
+            : {}),
+          rentDueDay: payload.rentDueDay,
+          rentWarningDay: payload.rentWarningDay,
+          utilitiesDueDay: payload.utilitiesDueDay,
+          utilitiesReminderDay: payload.utilitiesReminderDay,
+          timezone: payload.timezone
+        })
+
+        if (result.status === 'rejected') {
+          return miniAppJsonResponse(
+            {
+              ok: false,
+              error:
+                result.reason === 'invalid_settings'
+                  ? 'Invalid billing settings'
+                  : 'Admin access required'
+            },
+            result.reason === 'invalid_settings' ? 400 : 403,
+            origin
+          )
+        }
+
+        return miniAppJsonResponse(
+          {
+            ok: true,
+            authorized: true,
+            settings: serializeBillingSettings(result.settings)
+          },
+          200,
+          origin
+        )
+      } catch (error) {
+        return miniAppErrorResponse(error, origin, options.logger)
+      }
+    }
+  }
+}
+
+export function createMiniAppUpsertUtilityCategoryHandler(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 readUtilityCategoryPayload(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.upsertUtilityCategory({
+          householdId: session.member.householdId,
+          actorIsAdmin: session.member.isAdmin,
+          ...(payload.slug
+            ? {
+                slug: payload.slug
+              }
+            : {}),
+          name: payload.name,
+          sortOrder: payload.sortOrder,
+          isActive: payload.isActive
+        })
+
+        if (result.status === 'rejected') {
+          return miniAppJsonResponse(
+            {
+              ok: false,
+              error:
+                result.reason === 'invalid_category'
+                  ? 'Invalid utility category'
+                  : 'Admin access required'
+            },
+            result.reason === 'invalid_category' ? 400 : 403,
+            origin
+          )
+        }
+
+        return miniAppJsonResponse(
+          {
+            ok: true,
+            authorized: true,
+            category: result.category
+          },
+          200,
+          origin
+        )
+      } catch (error) {
+        return miniAppErrorResponse(error, origin, options.logger)
+      }
+    }
+  }
+}
+
+export function createMiniAppPromoteMemberHandler(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 readPromoteMemberPayload(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.promoteMemberToAdmin({
+          householdId: session.member.householdId,
+          actorIsAdmin: session.member.isAdmin,
+          memberId: payload.memberId
+        })
+
+        if (result.status === 'rejected') {
+          return miniAppJsonResponse(
+            {
+              ok: false,
+              error:
+                result.reason === 'member_not_found' ? 'Member not found' : 'Admin access required'
+            },
+            result.reason === 'member_not_found' ? 404 : 403,
+            origin
+          )
+        }
+
+        return miniAppJsonResponse(
+          {
+            ok: true,
+            authorized: true,
+            member: result.member
+          },
+          200,
+          origin
+        )
+      } catch (error) {
+        return miniAppErrorResponse(error, origin, options.logger)
+      }
+    }
+  }
+}
+
 export function createMiniAppApproveMemberHandler(options: {
   allowedOrigins: readonly string[]
   botToken: string

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

@@ -140,7 +140,37 @@ function onboardingRepository(): HouseholdConfigurationRepository {
             preferredLocale: locale
           }
         : null
-    }
+    },
+    getHouseholdBillingSettings: async (householdId) => ({
+      householdId,
+      rentAmountMinor: null,
+      rentCurrency: 'USD',
+      rentDueDay: 20,
+      rentWarningDay: 17,
+      utilitiesDueDay: 4,
+      utilitiesReminderDay: 3,
+      timezone: 'Asia/Tbilisi'
+    }),
+    updateHouseholdBillingSettings: async (input) => ({
+      householdId: input.householdId,
+      rentAmountMinor: input.rentAmountMinor ?? null,
+      rentCurrency: input.rentCurrency ?? 'USD',
+      rentDueDay: input.rentDueDay ?? 20,
+      rentWarningDay: input.rentWarningDay ?? 17,
+      utilitiesDueDay: input.utilitiesDueDay ?? 4,
+      utilitiesReminderDay: input.utilitiesReminderDay ?? 3,
+      timezone: input.timezone ?? 'Asia/Tbilisi'
+    }),
+    listHouseholdUtilityCategories: async () => [],
+    upsertHouseholdUtilityCategory: async (input) => ({
+      id: input.slug ?? 'utility-category-1',
+      householdId: input.householdId,
+      slug: input.slug ?? 'custom',
+      name: input.name,
+      sortOrder: input.sortOrder,
+      isActive: input.isActive
+    }),
+    promoteHouseholdAdmin: async () => null
   }
 }
 

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

@@ -135,7 +135,37 @@ function onboardingRepository(): HouseholdConfigurationRepository {
       ...household,
       defaultLocale: locale
     }),
-    updateMemberPreferredLocale: async () => null
+    updateMemberPreferredLocale: async () => null,
+    getHouseholdBillingSettings: async (householdId) => ({
+      householdId,
+      rentAmountMinor: null,
+      rentCurrency: 'USD',
+      rentDueDay: 20,
+      rentWarningDay: 17,
+      utilitiesDueDay: 4,
+      utilitiesReminderDay: 3,
+      timezone: 'Asia/Tbilisi'
+    }),
+    updateHouseholdBillingSettings: async (input) => ({
+      householdId: input.householdId,
+      rentAmountMinor: input.rentAmountMinor ?? null,
+      rentCurrency: input.rentCurrency ?? 'USD',
+      rentDueDay: input.rentDueDay ?? 20,
+      rentWarningDay: input.rentWarningDay ?? 17,
+      utilitiesDueDay: input.utilitiesDueDay ?? 4,
+      utilitiesReminderDay: input.utilitiesReminderDay ?? 3,
+      timezone: input.timezone ?? 'Asia/Tbilisi'
+    }),
+    listHouseholdUtilityCategories: async () => [],
+    upsertHouseholdUtilityCategory: async (input) => ({
+      id: input.slug ?? 'utility-category-1',
+      householdId: input.householdId,
+      slug: input.slug ?? 'custom',
+      name: input.name,
+      sortOrder: input.sortOrder,
+      isActive: input.isActive
+    }),
+    promoteHouseholdAdmin: async () => null
   }
 }
 

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

@@ -124,7 +124,37 @@ function repository(): HouseholdConfigurationRepository {
       }
       members.set(telegramUserId, next)
       return next
-    }
+    },
+    getHouseholdBillingSettings: async (householdId) => ({
+      householdId,
+      rentAmountMinor: null,
+      rentCurrency: 'USD',
+      rentDueDay: 20,
+      rentWarningDay: 17,
+      utilitiesDueDay: 4,
+      utilitiesReminderDay: 3,
+      timezone: 'Asia/Tbilisi'
+    }),
+    updateHouseholdBillingSettings: async (input) => ({
+      householdId: input.householdId,
+      rentAmountMinor: input.rentAmountMinor ?? null,
+      rentCurrency: input.rentCurrency ?? 'USD',
+      rentDueDay: input.rentDueDay ?? 20,
+      rentWarningDay: input.rentWarningDay ?? 17,
+      utilitiesDueDay: input.utilitiesDueDay ?? 4,
+      utilitiesReminderDay: input.utilitiesReminderDay ?? 3,
+      timezone: input.timezone ?? 'Asia/Tbilisi'
+    }),
+    listHouseholdUtilityCategories: async () => [],
+    upsertHouseholdUtilityCategory: async (input) => ({
+      id: input.slug ?? 'utility-category-1',
+      householdId: input.householdId,
+      slug: input.slug ?? 'custom',
+      name: input.name,
+      sortOrder: input.sortOrder,
+      isActive: input.isActive
+    }),
+    promoteHouseholdAdmin: async () => null
   }
 }
 

apps/bot/src/server.test.ts

@@ -34,6 +34,45 @@ describe('createBotWebhookServer', () => {
           }
         })
     },
+    miniAppSettings: {
+      handler: async () =>
+        new Response(
+          JSON.stringify({ ok: true, authorized: true, settings: {}, categories: [], members: [] }),
+          {
+            status: 200,
+            headers: {
+              'content-type': 'application/json; charset=utf-8'
+            }
+          }
+        )
+    },
+    miniAppUpdateSettings: {
+      handler: async () =>
+        new Response(JSON.stringify({ ok: true, authorized: true, settings: {} }), {
+          status: 200,
+          headers: {
+            'content-type': 'application/json; charset=utf-8'
+          }
+        })
+    },
+    miniAppUpsertUtilityCategory: {
+      handler: async () =>
+        new Response(JSON.stringify({ ok: true, authorized: true, category: {} }), {
+          status: 200,
+          headers: {
+            'content-type': 'application/json; charset=utf-8'
+          }
+        })
+    },
+    miniAppPromoteMember: {
+      handler: async () =>
+        new Response(JSON.stringify({ ok: true, authorized: true, member: {} }), {
+          status: 200,
+          headers: {
+            'content-type': 'application/json; charset=utf-8'
+          }
+        })
+    },
     miniAppApproveMember: {
       handler: async () =>
         new Response(JSON.stringify({ ok: true, authorized: true, member: {} }), {
@@ -154,6 +193,72 @@ describe('createBotWebhookServer', () => {
     })
   })
 
+  test('accepts mini app settings request', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/api/miniapp/admin/settings', {
+        method: 'POST',
+        body: JSON.stringify({ initData: 'payload' })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      settings: {},
+      categories: [],
+      members: []
+    })
+  })
+
+  test('accepts mini app settings update request', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/api/miniapp/admin/settings/update', {
+        method: 'POST',
+        body: JSON.stringify({ initData: 'payload' })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      settings: {}
+    })
+  })
+
+  test('accepts mini app utility category upsert request', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/api/miniapp/admin/utility-categories/upsert', {
+        method: 'POST',
+        body: JSON.stringify({ initData: 'payload' })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      category: {}
+    })
+  })
+
+  test('accepts mini app promote member request', async () => {
+    const response = await server.fetch(
+      new Request('http://localhost/api/miniapp/admin/members/promote', {
+        method: 'POST',
+        body: JSON.stringify({ initData: 'payload' })
+      })
+    )
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({
+      ok: true,
+      authorized: true,
+      member: {}
+    })
+  })
+
   test('accepts mini app approve member request', async () => {
     const response = await server.fetch(
       new Request('http://localhost/api/miniapp/admin/approve-member', {

apps/bot/src/server.ts

@@ -32,6 +32,30 @@ export interface BotWebhookServerOptions {
         handler: (request: Request) => Promise<Response>
       }
     | undefined
+  miniAppSettings?:
+    | {
+        path?: string
+        handler: (request: Request) => Promise<Response>
+      }
+    | undefined
+  miniAppUpdateSettings?:
+    | {
+        path?: string
+        handler: (request: Request) => Promise<Response>
+      }
+    | undefined
+  miniAppUpsertUtilityCategory?:
+    | {
+        path?: string
+        handler: (request: Request) => Promise<Response>
+      }
+    | undefined
+  miniAppPromoteMember?:
+    | {
+        path?: string
+        handler: (request: Request) => Promise<Response>
+      }
+    | undefined
   miniAppLocalePreference?:
     | {
         path?: string
@@ -75,6 +99,13 @@ export function createBotWebhookServer(options: BotWebhookServerOptions): {
     options.miniAppPendingMembers?.path ?? '/api/miniapp/admin/pending-members'
   const miniAppApproveMemberPath =
     options.miniAppApproveMember?.path ?? '/api/miniapp/admin/approve-member'
+  const miniAppSettingsPath = options.miniAppSettings?.path ?? '/api/miniapp/admin/settings'
+  const miniAppUpdateSettingsPath =
+    options.miniAppUpdateSettings?.path ?? '/api/miniapp/admin/settings/update'
+  const miniAppUpsertUtilityCategoryPath =
+    options.miniAppUpsertUtilityCategory?.path ?? '/api/miniapp/admin/utility-categories/upsert'
+  const miniAppPromoteMemberPath =
+    options.miniAppPromoteMember?.path ?? '/api/miniapp/admin/members/promote'
   const miniAppLocalePreferencePath =
     options.miniAppLocalePreference?.path ?? '/api/miniapp/preferences/locale'
   const schedulerPathPrefix = options.scheduler
@@ -109,6 +140,25 @@ export function createBotWebhookServer(options: BotWebhookServerOptions): {
         return await options.miniAppApproveMember.handler(request)
       }
 
+      if (options.miniAppSettings && url.pathname === miniAppSettingsPath) {
+        return await options.miniAppSettings.handler(request)
+      }
+
+      if (options.miniAppUpdateSettings && url.pathname === miniAppUpdateSettingsPath) {
+        return await options.miniAppUpdateSettings.handler(request)
+      }
+
+      if (
+        options.miniAppUpsertUtilityCategory &&
+        url.pathname === miniAppUpsertUtilityCategoryPath
+      ) {
+        return await options.miniAppUpsertUtilityCategory.handler(request)
+      }
+
+      if (options.miniAppPromoteMember && url.pathname === miniAppPromoteMemberPath) {
+        return await options.miniAppPromoteMember.handler(request)
+      }
+
       if (options.miniAppLocalePreference && url.pathname === miniAppLocalePreferencePath) {
         return await options.miniAppLocalePreference.handler(request)
       }