feat(bot): add multi-household setup flow

packages/ports/src/household-config.ts

@@ -0,0 +1,52 @@
+export const HOUSEHOLD_TOPIC_ROLES = ['purchase', 'feedback', 'reminders'] as const
+
+export type HouseholdTopicRole = (typeof HOUSEHOLD_TOPIC_ROLES)[number]
+
+export interface HouseholdTelegramChatRecord {
+  householdId: string
+  householdName: string
+  telegramChatId: string
+  telegramChatType: string
+  title: string | null
+}
+
+export interface HouseholdTopicBindingRecord {
+  householdId: string
+  role: HouseholdTopicRole
+  telegramThreadId: string
+  topicName: string | null
+}
+
+export interface RegisterTelegramHouseholdChatInput {
+  householdName: string
+  telegramChatId: string
+  telegramChatType: string
+  title?: string
+}
+
+export interface RegisterTelegramHouseholdChatResult {
+  status: 'created' | 'existing'
+  household: HouseholdTelegramChatRecord
+}
+
+export interface HouseholdConfigurationRepository {
+  registerTelegramHouseholdChat(
+    input: RegisterTelegramHouseholdChatInput
+  ): Promise<RegisterTelegramHouseholdChatResult>
+  getTelegramHouseholdChat(telegramChatId: string): Promise<HouseholdTelegramChatRecord | null>
+  bindHouseholdTopic(input: {
+    householdId: string
+    role: HouseholdTopicRole
+    telegramThreadId: string
+    topicName?: string
+  }): Promise<HouseholdTopicBindingRecord>
+  getHouseholdTopicBinding(
+    householdId: string,
+    role: HouseholdTopicRole
+  ): Promise<HouseholdTopicBindingRecord | null>
+  findHouseholdTopicByTelegramContext(input: {
+    telegramChatId: string
+    telegramThreadId: string
+  }): Promise<HouseholdTopicBindingRecord | null>
+  listHouseholdTopicBindings(householdId: string): Promise<readonly HouseholdTopicBindingRecord[]>
+}

packages/ports/src/index.ts

@@ -5,6 +5,15 @@ export {
   type ReminderDispatchRepository,
   type ReminderType
 } from './reminders'
+export {
+  HOUSEHOLD_TOPIC_ROLES,
+  type HouseholdConfigurationRepository,
+  type HouseholdTelegramChatRecord,
+  type HouseholdTopicBindingRecord,
+  type HouseholdTopicRole,
+  type RegisterTelegramHouseholdChatInput,
+  type RegisterTelegramHouseholdChatResult
+} from './household-config'
 export type {
   AnonymousFeedbackMemberRecord,
   AnonymousFeedbackModerationStatus,