FamiliesHandler

public protocol FamiliesHandler: Sendable

func fetchAll(pageNumber: Int, pageSize: Int) async throws -> FamilyResponse

let congregation = CongregationKit(auth: auth)
let response = try await congregation.families.fetchAll(
    pageNumber: 1,
    pageSize: 20
)

print("Fetched \(response.families.count) families")
if let metadata = response.metadata {
    print("Total families: \(metadata.total)")
    print("Has next page: \(metadata.hasNextPage)")
}

func fetch(id: FamilyID) async throws -> Family

func fetchMembers(familyId: FamilyID) async throws -> [Member]

let members = try await congregation.families.fetchMembers(
    familyId: FamilyID(rawValue: "FAM001")!
)

for member in members {
    print("- \(member.memberName ?? "Unknown")")
}

func fetchFamilyInfo(familyId: FamilyID) async throws -> FamilyInfo

let familyInfo = try await congregation.families.fetchFamilyInfo(
    familyId: familyId
)

print("Family size: \(familyInfo.familySize)")
print("Adults: \(familyInfo.adultCount)")
print("Children: \(familyInfo.childCount)")
print("Has minors: \(familyInfo.hasMinors)")

if familyInfo.isSingleParentFamily {
    print("Single-parent family")
}

if familyInfo.isMultiGenerational {
    print("Multi-generational family")
}

func createFamily(_ family: Family) async throws -> Family

func updateFamily(_ family: Family) async throws -> Family

func deleteFamily(id: FamilyID) async throws

func addMemberToFamily(
    memberId: MemberID,
    familyId: FamilyID,
    role: FamilyRole
) async throws -> FamilyMembership

let membership = try await congregation.families.addMemberToFamily(
    memberId: MemberID(rawValue: "TKT5678")!,
    familyId: FamilyID(rawValue: "FAM001")!,
    role: .child
)

print("Added member with role: \(membership.role.displayName)")

func removeMemberFromFamily(
    memberId: MemberID,
    familyId: FamilyID
) async throws

func updateMemberRole(
    memberId: MemberID,
    familyId: FamilyID,
    newRole: FamilyRole
) async throws -> FamilyMembership

func fetchRelationships(memberId: MemberID) async throws -> [MemberRelationship]

let relationships = try await congregation.families.fetchRelationships(
    memberId: MemberID(rawValue: "TKT1234")!
)

for rel in relationships {
    let targetId = rel.targetMemberId
    let type = rel.relationshipType.displayName
    print("Relationship: \(type) to \(targetId)")
}

func createRelationship(
    _ relationship: MemberRelationship
) async throws -> MemberRelationship

func createBidirectionalRelationship(
    _ relationship: MemberRelationship
) async throws -> (primary: MemberRelationship, inverse: MemberRelationship)

let parentChild = MemberRelationship(
    id: RelationshipID(rawValue: "REL001")!,
    sourceMemberId: MemberID(rawValue: "TKT1234")!,
    targetMemberId: MemberID(rawValue: "TKT5678")!,
    relationshipType: .parent,
    isPrimary: true
)

let (primary, inverse) = try await congregation.families.createBidirectionalRelationship(
    parentChild
)

print("Primary: \(primary.relationshipType.displayName)") // "Parent"
print("Inverse: \(inverse.relationshipType.displayName)") // "Child"

func deleteRelationship(id: RelationshipID) async throws

func updateRelationship(
    _ relationship: MemberRelationship
) async throws -> MemberRelationship

func suggestRelationships(
    for member: Member
) async throws -> [SuggestedRelationship]

let member = try await congregation.members.fetch(id: memberId)
let suggestions = try await congregation.families.suggestRelationships(
    for: member
)

for suggestion in suggestions where suggestion.isHighConfidence {
    print("Suggested: \(suggestion.suggestedType.displayName)")
    print("Confidence: \(suggestion.confidence)")
    print("Reason: \(suggestion.reason.description)")
}

func suggestRelationships(
    for member: Member,
    options: RelationshipSuggestionOptions
) async throws -> [SuggestedRelationship]

let options = RelationshipSuggestionOptions(
    minimumConfidence: 0.8,
    includeAddressMatching: true,
    includeNameMatching: true,
    includeAgeAnalysis: true,
    maxSuggestions: 5
)

let suggestions = try await congregation.families.suggestRelationships(
    for: member,
    options: options
)

func buildFamilyTree(
    startingFrom memberId: MemberID
) async throws -> FamilyTree

let tree = try await congregation.families.buildFamilyTree(
    startingFrom: MemberID(rawValue: "TKT1234")!
)

print("Generations: \(tree.generationCount)")
print("Total members: \(tree.memberCount)")
print("Total relationships: \(tree.relationshipCount)")

// Get members by generation
let rootGeneration = tree.nodes(inGeneration: 0)
let children = tree.nodes(inGeneration: 1)

func buildFamilyTree(
    forFamily familyId: FamilyID
) async throws -> FamilyTree

public struct RelationshipSuggestionOptions: Codable, Equatable, Sendable

let defaultOptions = RelationshipSuggestionOptions.default
// minimumConfidence: 0.5
// includeAddressMatching: true
// includeNameMatching: true
// includeAgeAnalysis: true
// maxSuggestions: 10

public struct FamilyInfo: Codable, Sendable