Interface IHouseholdRepository

Namespace

SEBT.Portal.Core.Repositories

Assembly

SEBT.Portal.Core.dll

Repository interface for managing household data. Uses state-configurable household identifiers (e.g. email, SNAP ID); the API resolves the identifier via IHouseholdIdentifierResolver then calls GetHouseholdByIdentifierAsync(HouseholdIdentifier, PiiVisibility, UserIalLevel, Guid?, bool, CancellationToken). UpsertHouseholdAsync is intended for data loading scripts, not for API endpoints.

public interface IHouseholdRepository

Methods

GetHouseholdByBenefitIdentifierAndGuardianDobAsync(string, string, DateOnly, PiiVisibility, UserIalLevel, Guid, string?, CancellationToken)

DC co-loaded fallback: loads household via warehouse IC + guardian DOB when rows use IC as PortalID. Sets envelope email to guardianLoginEmail; non-DC plugins return null.

Task<HouseholdData?> GetHouseholdByBenefitIdentifierAndGuardianDobAsync(string guardianLoginEmail, string benefitIdentifierIc, DateOnly guardianDateOfBirth, PiiVisibility piiVisibility, UserIalLevel userIalLevel, Guid portalUserId, string? socureReferenceId = null, CancellationToken cancellationToken = default)

Parameters

guardianLoginEmail string

benefitIdentifierIc string

guardianDateOfBirth DateOnly

piiVisibility PiiVisibility

userIalLevel UserIalLevel

portalUserId Guid

Portal User.Id. DC merges this into the warehouse GuardianIdentifiers JSON as PortalUUID for cross-system correlation.

socureReferenceId string

Socure reference ID (UUID) from the guardian's identity verification, when one exists. DC merges this into the warehouse GuardianIdentifiers JSON as SocureUUID.

cancellationToken CancellationToken

Returns

Task<HouseholdData>

GetHouseholdByEmailAsync(string, PiiVisibility, UserIalLevel, Guid?, bool, CancellationToken)

Retrieves household data by email address. Prefer GetHouseholdByIdentifierAsync(HouseholdIdentifier, PiiVisibility, UserIalLevel, Guid?, bool, CancellationToken) for API use so lookup is state-configurable. PII fields are filtered based on the visibility flags.

Task<HouseholdData?> GetHouseholdByEmailAsync(string email, PiiVisibility piiVisibility, UserIalLevel userIalLevel, Guid? portalUserId = null, bool includeCardService = true, CancellationToken cancellationToken = default)

Parameters

email string

The email address of the household.

piiVisibility PiiVisibility

Which PII elements to include. Required; no default. Callers must obtain this from IIdProofingService based on the user's ID proofing status.

userIalLevel UserIalLevel

Identity Assurance Level the user has achieved. Passed to state plugins for backend policy.

portalUserId Guid?

Portal User.Id. DC passes this as PortalUUID in warehouse @guardianIdentifiers for correlation in PortalLog.

includeCardService bool

cancellationToken CancellationToken

A token to monitor for cancellation requests.

Returns

Task<HouseholdData>

The household data if found; otherwise, null.

GetHouseholdByIdentifierAsync(HouseholdIdentifier, PiiVisibility, UserIalLevel, Guid?, bool, CancellationToken)

Retrieves household data by the given household identifier (type + value). The identifier type is determined by state configuration (e.g. Email, SNAP ID). PII fields (Address, Email, Phone etc.) are filtered based on the visibility flags.

Task<HouseholdData?> GetHouseholdByIdentifierAsync(HouseholdIdentifier identifier, PiiVisibility piiVisibility, UserIalLevel userIalLevel, Guid? portalUserId = null, bool includeCardService = true, CancellationToken cancellationToken = default)

Parameters

identifier HouseholdIdentifier

The household identifier (type and value) to look up.

piiVisibility PiiVisibility

Which PII elements to include. Required; no default. Callers must obtain this from IIdProofingService based on the user's IAL level.

userIalLevel UserIalLevel

Identity Assurance Level the user has achieved. Passed to state plugins for backend policy (e.g. whether to return address).

portalUserId Guid?

Portal User.Id. DC passes this as PortalUUID in warehouse @guardianIdentifiers for correlation in PortalLog.

includeCardService bool

cancellationToken CancellationToken

A token to monitor for cancellation requests.

Returns

Task<HouseholdData>

The household data if found; otherwise, null.

TryMatchCoLoadedGuardianByBenefitIdAndDobAsync(string, DateOnly, Guid, CancellationToken)

For co-loaded SNAP/TANF ID proofing: asks the state plugin whether the submitted benefit identifier (IC) and guardian date of birth match state warehouse data. Implemented for DC only; other states return false.

Task<bool> TryMatchCoLoadedGuardianByBenefitIdAndDobAsync(string benefitIdentifierIc, DateOnly guardianDateOfBirth, Guid portalUserId, CancellationToken cancellationToken = default)

Parameters

benefitIdentifierIc string

SNAP/TANF identifier from onboarding, mapped to warehouse IC.

guardianDateOfBirth DateOnly

Guardian DOB from ID proofing.

portalUserId Guid

Portal User.Id. DC merges this into the warehouse GuardianIdentifiers JSON as PortalUUID for cross-system correlation.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

true if the state reports a match.

UpsertHouseholdAsync(HouseholdData, CancellationToken)

Creates or updates household data.

Task UpsertHouseholdAsync(HouseholdData householdData, CancellationToken cancellationToken = default)

Parameters

householdData HouseholdData

The household data to create or update.

cancellationToken CancellationToken

A token to monitor for cancellation requests.

Returns

Task

A task representing the asynchronous operation.