arolariu.Backend.Domain.Invoices.DTOs.Responses
arolariu.Backend.Domain.Invoices
arolariu.Backend.Domain.Invoices.DTOs.Responses Namespace
Structs
InvoiceResponseDto Struct
Response DTO representing a complete invoice returned from the REST API.
public readonly record struct InvoiceResponseDto : System.IEquatable<arolariu.Backend.Domain.Invoices.DTOs.Responses.InvoiceResponseDto>
Implements System.IEquatable<InvoiceResponseDto>
Example
// Creating from domain entity (recommended)
Invoice domainInvoice = await invoiceService.ReadInvoiceAsync(invoiceId);
InvoiceResponseDto dto = InvoiceResponseDto.FromInvoice(domainInvoice);
// Returning from API endpoint
return TypedResults.Ok(dto);
Remarks
Purpose: Provides a clean, stable API contract separate from the internal Invoice domain model. This decoupling allows the domain to evolve independently without breaking API consumers.
Immutability: This is a readonly record struct, ensuring:
- Thread-safety without synchronization
- Value semantics for equality comparisons
- Efficient stack allocation for small instances
Serialization: Marked [Serializable] for JSON serialization in API responses.
All collection properties use read-only interfaces to prevent mutation after creation.
Usage Pattern: Always use the FromInvoice(Invoice) factory method to create instances from domain entities. Direct construction is supported but discouraged outside of testing scenarios.
Content: Includes complete invoice data: line items, scans (OCR sources), AI-generated recipes, shared access list, payment details, and extensible metadata.
See Also
Constructors
InvoiceResponseDto(Guid, Guid, IReadOnlyCollection<Guid>, string, string, InvoiceCategory, IReadOnlyCollection<InvoiceScan>, PaymentInformation, Guid, IReadOnlyCollection<ProductResponseDto>, IReadOnlyCollection<Recipe>, IReadOnlyDictionary<string,object>, bool, bool, DateTimeOffset, Guid, DateTimeOffset, Guid, int) Constructor
Response DTO representing a complete invoice returned from the REST API.
public InvoiceResponseDto(System.Guid Id, System.Guid UserIdentifier, System.Collections.Generic.IReadOnlyCollection<System.Guid> SharedWith, string Name, string Description, arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.InvoiceCategory Category, System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.InvoiceScan> Scans, arolariu.Backend.Domain.Invoices.DDD.ValueObjects.PaymentInformation PaymentInformation, System.Guid MerchantReference, System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DTOs.Responses.ProductResponseDto> Items, System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DDD.ValueObjects.Recipe> PossibleRecipes, System.Collections.Generic.IReadOnlyDictionary<string,object> AdditionalMetadata, bool IsImportant, bool IsSoftDeleted, System.DateTimeOffset CreatedAt, System.Guid CreatedBy, System.DateTimeOffset LastUpdatedAt, System.Guid LastUpdatedBy, int NumberOfUpdates);
Parameters
Id System.Guid
The unique invoice identifier (Version 7 GUID). Immutable after creation.
UserIdentifier System.Guid
The owner's user identifier. System.Guid.Empty indicates system-owned or unassigned.
SharedWith System.Collections.Generic.IReadOnlyCollection<System.Guid>
Collection of user identifiers granted read access. Empty collection if not shared.
Name System.String
The invoice display name (user-provided or auto-generated). Never null; may be empty string.
Description System.String
A detailed description of the invoice contents. Never null; may be empty string.
Category InvoiceCategory
The invoice category classification. Defaults to NOT_DEFINED until AI analysis categorizes the invoice.
Scans System.Collections.Generic.IReadOnlyCollection<InvoiceScan>
Collection of invoice scan records (photos, PDFs). Each scan includes URI and metadata. Empty if no scans have been uploaded.
PaymentInformation PaymentInformation
Payment details including currency code, total amount, tax breakdown, and payment method.
MerchantReference System.Guid
Reference to an associated merchant entity. System.Guid.Empty if no merchant is linked (pre-analysis state or manual invoice).
Items System.Collections.Generic.IReadOnlyCollection<ProductResponseDto>
Collection of line items as ProductResponseDto. Empty for newly created invoices before OCR analysis extracts products.
PossibleRecipes System.Collections.Generic.IReadOnlyCollection<Recipe>
Collection of AI-inferred recipes based on invoice items. Populated after analysis. Empty if analysis not performed or no recipes detected.
AdditionalMetadata System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>
Extensible key-value metadata dictionary for custom fields. Keys are case-sensitive strings; values are serializable objects. Empty dictionary if no custom metadata.
IsImportant System.Boolean
Flag indicating user-marked importance for filtering/sorting. Defaults to false.
IsSoftDeleted System.Boolean
Flag indicating soft deletion status. Soft-deleted invoices may still be returned in specific queries but are excluded from standard listings.
CreatedAt System.DateTimeOffset
UTC timestamp when the invoice was first created. Immutable after creation.
CreatedBy System.Guid
The user identifier who created this invoice. System.Guid.Empty for system-created.
LastUpdatedAt System.DateTimeOffset
UTC timestamp of the most recent modification. Updated on every change.
LastUpdatedBy System.Guid
The user identifier who last modified this invoice.
NumberOfUpdates System.Int32
Count of modifications performed on this invoice. Incremented on each update operation.
Example
// Creating from domain entity (recommended)
Invoice domainInvoice = await invoiceService.ReadInvoiceAsync(invoiceId);
InvoiceResponseDto dto = InvoiceResponseDto.FromInvoice(domainInvoice);
// Returning from API endpoint
return TypedResults.Ok(dto);
Remarks
Purpose: Provides a clean, stable API contract separate from the internal Invoice domain model. This decoupling allows the domain to evolve independently without breaking API consumers.
Immutability: This is a readonly record struct, ensuring:
- Thread-safety without synchronization
- Value semantics for equality comparisons
- Efficient stack allocation for small instances
Serialization: Marked [Serializable] for JSON serialization in API responses.
All collection properties use read-only interfaces to prevent mutation after creation.
Usage Pattern: Always use the FromInvoice(Invoice) factory method to create instances from domain entities. Direct construction is supported but discouraged outside of testing scenarios.
Content: Includes complete invoice data: line items, scans (OCR sources), AI-generated recipes, shared access list, payment details, and extensible metadata.
See Also
Properties
InvoiceResponseDto.AdditionalMetadata Property
Extensible key-value metadata dictionary for custom fields. Keys are case-sensitive strings; values are serializable objects. Empty dictionary if no custom metadata.
public System.Collections.Generic.IReadOnlyDictionary<string,object> AdditionalMetadata { get; init; }
Property Value
System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>
InvoiceResponseDto.Category Property
The invoice category classification. Defaults to NOT_DEFINED until AI analysis categorizes the invoice.
public arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.InvoiceCategory Category { get; init; }
Property Value
InvoiceResponseDto.CreatedAt Property
UTC timestamp when the invoice was first created. Immutable after creation.
public System.DateTimeOffset CreatedAt { get; init; }
Property Value
InvoiceResponseDto.CreatedBy Property
The user identifier who created this invoice. System.Guid.Empty for system-created.
public System.Guid CreatedBy { get; init; }
Property Value
InvoiceResponseDto.Description Property
A detailed description of the invoice contents. Never null; may be empty string.
public string Description { get; init; }
Property Value
InvoiceResponseDto.Id Property
The unique invoice identifier (Version 7 GUID). Immutable after creation.
public System.Guid Id { get; init; }
Property Value
InvoiceResponseDto.IsImportant Property
Flag indicating user-marked importance for filtering/sorting. Defaults to false.
public bool IsImportant { get; init; }
Property Value
InvoiceResponseDto.IsSoftDeleted Property
Flag indicating soft deletion status. Soft-deleted invoices may still be returned in specific queries but are excluded from standard listings.
public bool IsSoftDeleted { get; init; }
Property Value
InvoiceResponseDto.Items Property
Collection of line items as ProductResponseDto. Empty for newly created invoices before OCR analysis extracts products.
public System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DTOs.Responses.ProductResponseDto> Items { get; init; }
Property Value
System.Collections.Generic.IReadOnlyCollection<ProductResponseDto>
InvoiceResponseDto.LastUpdatedAt Property
UTC timestamp of the most recent modification. Updated on every change.
public System.DateTimeOffset LastUpdatedAt { get; init; }
Property Value
InvoiceResponseDto.LastUpdatedBy Property
The user identifier who last modified this invoice.
public System.Guid LastUpdatedBy { get; init; }
Property Value
InvoiceResponseDto.MerchantReference Property
Reference to an associated merchant entity. System.Guid.Empty if no merchant is linked (pre-analysis state or manual invoice).
public System.Guid MerchantReference { get; init; }
Property Value
InvoiceResponseDto.Name Property
The invoice display name (user-provided or auto-generated). Never null; may be empty string.
public string Name { get; init; }
Property Value
InvoiceResponseDto.NumberOfUpdates Property
Count of modifications performed on this invoice. Incremented on each update operation.
public int NumberOfUpdates { get; init; }
Property Value
InvoiceResponseDto.PaymentInformation Property
Payment details including currency code, total amount, tax breakdown, and payment method.
public arolariu.Backend.Domain.Invoices.DDD.ValueObjects.PaymentInformation PaymentInformation { get; init; }
Property Value
InvoiceResponseDto.PossibleRecipes Property
Collection of AI-inferred recipes based on invoice items. Populated after analysis. Empty if analysis not performed or no recipes detected.
public System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DDD.ValueObjects.Recipe> PossibleRecipes { get; init; }
Property Value
System.Collections.Generic.IReadOnlyCollection<Recipe>
InvoiceResponseDto.Scans Property
Collection of invoice scan records (photos, PDFs). Each scan includes URI and metadata. Empty if no scans have been uploaded.
public System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.InvoiceScan> Scans { get; init; }
Property Value
System.Collections.Generic.IReadOnlyCollection<InvoiceScan>
InvoiceResponseDto.SharedWith Property
Collection of user identifiers granted read access. Empty collection if not shared.
public System.Collections.Generic.IReadOnlyCollection<System.Guid> SharedWith { get; init; }
Property Value
System.Collections.Generic.IReadOnlyCollection<System.Guid>
InvoiceResponseDto.UserIdentifier Property
The owner's user identifier. System.Guid.Empty indicates system-owned or unassigned.
public System.Guid UserIdentifier { get; init; }
Property Value
Methods
InvoiceResponseDto.FromInvoice(Invoice) Method
Creates an InvoiceResponseDto from a domain Invoice aggregate.
public static arolariu.Backend.Domain.Invoices.DTOs.Responses.InvoiceResponseDto FromInvoice(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice invoice);
Parameters
invoice Invoice
The domain invoice aggregate to convert. Must not be null. All properties are read and mapped to the corresponding DTO properties.
Returns
InvoiceResponseDto
A fully populated InvoiceResponseDto containing all invoice data
suitable for API serialization and client consumption.
Exceptions
System.ArgumentNullException
Thrown when invoice is null.
Example
// Single invoice conversion
Invoice invoice = await repository.GetByIdAsync(invoiceId);
InvoiceResponseDto dto = InvoiceResponseDto.FromInvoice(invoice);
// Batch conversion using LINQ
IEnumerable<InvoiceResponseDto> dtos = invoices.Select(InvoiceResponseDto.FromInvoice);
Remarks
Factory Pattern: This is the preferred method for creating DTOs from domain entities. It ensures consistent mapping and proper conversion of nested collections.
Collection Handling: All collections are converted to read-only snapshots:
- Items are mapped through FromProduct(Product)
- Collections use
ToList().AsReadOnly()for immutability - Metadata dictionary is copied to prevent external mutation
Performance: Performs shallow copies of value types and creates new collection instances. For large invoices with many items, consider caching the result.
InvoiceScanResponseDto Struct
Response DTO representing an invoice scan (receipt image or document).
public readonly record struct InvoiceScanResponseDto : System.IEquatable<arolariu.Backend.Domain.Invoices.DTOs.Responses.InvoiceScanResponseDto>
Implements System.IEquatable<InvoiceScanResponseDto>
Example
// Converting from domain object
InvoiceScan domainScan = invoice.Scans.First();
InvoiceScanResponseDto dto = InvoiceScanResponseDto.FromInvoiceScan(domainScan);
// Accessing scan data
Console.WriteLine($"Scan type: {dto.Type}, Location: {dto.Location}");
Remarks
Purpose: Provides a clean API contract for invoice scan data, decoupled from the internal InvoiceScan domain value object.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
Storage: The Location URI typically points to Azure Blob Storage where the original scan image/document is stored.
Metadata: May contain OCR confidence scores, extraction timestamps, or other processing artifacts from the Document Intelligence service.
See Also
Constructors
InvoiceScanResponseDto(ScanType, Uri, IReadOnlyDictionary<string,object>) Constructor
Response DTO representing an invoice scan (receipt image or document).
public InvoiceScanResponseDto(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.ScanType Type, System.Uri Location, System.Collections.Generic.IReadOnlyDictionary<string,object>? Metadata);
Parameters
Type ScanType
The scan format type. Supported types include JPG, PNG, PDF, TIFF. Determines how the scan is processed during analysis.
Location System.Uri
The URI location where the scan is stored. Must be a valid, accessible URI. Typically an Azure Blob Storage URL with SAS token for authorized access.
Metadata System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>
Optional key-value metadata associated with this scan. May include: OCR confidence scores, extraction timestamps, page counts (for PDFs), or custom fields. Null if no metadata is associated.
Example
// Converting from domain object
InvoiceScan domainScan = invoice.Scans.First();
InvoiceScanResponseDto dto = InvoiceScanResponseDto.FromInvoiceScan(domainScan);
// Accessing scan data
Console.WriteLine($"Scan type: {dto.Type}, Location: {dto.Location}");
Remarks
Purpose: Provides a clean API contract for invoice scan data, decoupled from the internal InvoiceScan domain value object.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
Storage: The Location URI typically points to Azure Blob Storage where the original scan image/document is stored.
Metadata: May contain OCR confidence scores, extraction timestamps, or other processing artifacts from the Document Intelligence service.
See Also
Properties
InvoiceScanResponseDto.Location Property
The URI location where the scan is stored. Must be a valid, accessible URI. Typically an Azure Blob Storage URL with SAS token for authorized access.
public System.Uri Location { get; init; }
Property Value
InvoiceScanResponseDto.Metadata Property
Optional key-value metadata associated with this scan. May include: OCR confidence scores, extraction timestamps, page counts (for PDFs), or custom fields. Null if no metadata is associated.
public System.Collections.Generic.IReadOnlyDictionary<string,object>? Metadata { get; init; }
Property Value
System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>
InvoiceScanResponseDto.Type Property
The scan format type. Supported types include JPG, PNG, PDF, TIFF. Determines how the scan is processed during analysis.
public arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.ScanType Type { get; init; }
Property Value
Methods
InvoiceScanResponseDto.FromInvoiceScan(InvoiceScan) Method
Creates an InvoiceScanResponseDto from a domain InvoiceScan.
public static arolariu.Backend.Domain.Invoices.DTOs.Responses.InvoiceScanResponseDto FromInvoiceScan(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.InvoiceScan scan);
Parameters
scan InvoiceScan
The domain scan to convert. All properties are directly mapped.
Returns
InvoiceScanResponseDto
A new InvoiceScanResponseDto instance with copied values.
Remarks
Factory Pattern: Preferred method for creating DTOs from domain objects. Ensures consistent mapping and proper handling of nullable metadata.
Metadata Copying: If metadata exists, a new dictionary is created to prevent external mutation of the original domain object's data.
MerchantResponseDto Struct
Response DTO representing a merchant entity returned from the API.
public readonly record struct MerchantResponseDto : System.IEquatable<arolariu.Backend.Domain.Invoices.DTOs.Responses.MerchantResponseDto>
Implements System.IEquatable<MerchantResponseDto>
Example
// Converting from domain entity
Merchant domainMerchant = await merchantService.GetMerchantAsync(merchantId);
MerchantResponseDto dto = MerchantResponseDto.FromMerchant(domainMerchant);
// Displaying merchant summary
Console.WriteLine($"Merchant: {dto.Name} ({dto.Category})");
Console.WriteLine($"Invoices: {dto.ReferencedInvoiceCount}");
Console.WriteLine($"Last updated: {dto.LastUpdatedAt:u}");
Remarks
Purpose: Provides a clean API contract for merchant data, fully decoupled from the internal Merchant domain entity.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
Relationships: Includes ReferencedInvoiceCount and ReferencedInvoiceIds for quick relationship access without additional queries.
Auditing: Tracks creation and update metadata via CreatedAt, CreatedBy, LastUpdatedAt, LastUpdatedBy, and NumberOfUpdates.
See Also
Constructors
MerchantResponseDto(Guid, string, string, MerchantCategory, ContactInformation, Guid, int, IReadOnlyCollection<Guid>, IReadOnlyDictionary<string,string>, bool, bool, DateTimeOffset, Guid, DateTimeOffset, Guid, int) Constructor
Response DTO representing a merchant entity returned from the API.
public MerchantResponseDto(System.Guid Id, string Name, string Description, arolariu.Backend.Domain.Invoices.DDD.Entities.Merchants.MerchantCategory Category, arolariu.Backend.Common.DDD.ValueObjects.ContactInformation Address, System.Guid ParentCompanyId, int ReferencedInvoiceCount, System.Collections.Generic.IReadOnlyCollection<System.Guid> ReferencedInvoiceIds, System.Collections.Generic.IReadOnlyDictionary<string,string> AdditionalMetadata, bool IsImportant, bool IsSoftDeleted, System.DateTimeOffset CreatedAt, System.Guid CreatedBy, System.DateTimeOffset LastUpdatedAt, System.Guid LastUpdatedBy, int NumberOfUpdates);
Parameters
Id System.Guid
Unique merchant identifier (Version 7 GUID, time-ordered). Used for all merchant operations and cross-referencing.
Name System.String
The merchant's display name (e.g., "Kaufland Iasi Pacurari"). Required, non-empty.
Description System.String
A detailed description of the merchant. May be empty if not provided.
Category MerchantCategory
Business category classification (e.g., Grocery, Restaurant, Pharmacy). Defaults to NOT_DEFINED if unclassified.
Address arolariu.Backend.Common.DDD.ValueObjects.ContactInformation
Structured contact and address information including street, city, postal code, country, phone, and email.
ParentCompanyId System.Guid
Reference to a parent company merchant (for franchise/chain stores). System.Guid.Empty if no parent company exists.
ReferencedInvoiceCount System.Int32
Count of invoices associated with this merchant. Useful for UI display without needing to load the full invoice list.
ReferencedInvoiceIds System.Collections.Generic.IReadOnlyCollection<System.Guid>
Collection of invoice identifiers referencing this merchant. Returns an empty collection if no invoices are associated.
AdditionalMetadata System.Collections.Generic.IReadOnlyDictionary<System.String,System.String>
Extensible key-value metadata for custom merchant attributes (e.g., loyalty program IDs, tax identifiers, operating hours).
IsImportant System.Boolean
Flag indicating if the merchant is marked as important/favorite by the user.
IsSoftDeleted System.Boolean
Flag indicating soft deletion status. Soft-deleted merchants are excluded from normal queries but retained for historical data.
CreatedAt System.DateTimeOffset
UTC timestamp when the merchant was first created.
CreatedBy System.Guid
Identifier of the user who created this merchant record.
LastUpdatedAt System.DateTimeOffset
UTC timestamp of the most recent update. Equals CreatedAt if never updated.
LastUpdatedBy System.Guid
Identifier of the user who last modified this merchant. Equals CreatedBy if never updated by a different user.
NumberOfUpdates System.Int32
Total count of update operations performed on this merchant. Zero for newly created merchants.
Example
// Converting from domain entity
Merchant domainMerchant = await merchantService.GetMerchantAsync(merchantId);
MerchantResponseDto dto = MerchantResponseDto.FromMerchant(domainMerchant);
// Displaying merchant summary
Console.WriteLine($"Merchant: {dto.Name} ({dto.Category})");
Console.WriteLine($"Invoices: {dto.ReferencedInvoiceCount}");
Console.WriteLine($"Last updated: {dto.LastUpdatedAt:u}");
Remarks
Purpose: Provides a clean API contract for merchant data, fully decoupled from the internal Merchant domain entity.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
Relationships: Includes ReferencedInvoiceCount and ReferencedInvoiceIds for quick relationship access without additional queries.
Auditing: Tracks creation and update metadata via CreatedAt, CreatedBy, LastUpdatedAt, LastUpdatedBy, and NumberOfUpdates.
See Also
Properties
MerchantResponseDto.AdditionalMetadata Property
Extensible key-value metadata for custom merchant attributes (e.g., loyalty program IDs, tax identifiers, operating hours).
public System.Collections.Generic.IReadOnlyDictionary<string,string> AdditionalMetadata { get; init; }
Property Value
System.Collections.Generic.IReadOnlyDictionary<System.String,System.String>
MerchantResponseDto.Address Property
Structured contact and address information including street, city, postal code, country, phone, and email.
public arolariu.Backend.Common.DDD.ValueObjects.ContactInformation Address { get; init; }
Property Value
arolariu.Backend.Common.DDD.ValueObjects.ContactInformation
MerchantResponseDto.Category Property
Business category classification (e.g., Grocery, Restaurant, Pharmacy). Defaults to NOT_DEFINED if unclassified.
public arolariu.Backend.Domain.Invoices.DDD.Entities.Merchants.MerchantCategory Category { get; init; }
Property Value
MerchantResponseDto.CreatedAt Property
UTC timestamp when the merchant was first created.
public System.DateTimeOffset CreatedAt { get; init; }
Property Value
MerchantResponseDto.CreatedBy Property
Identifier of the user who created this merchant record.
public System.Guid CreatedBy { get; init; }
Property Value
MerchantResponseDto.Description Property
A detailed description of the merchant. May be empty if not provided.
public string Description { get; init; }
Property Value
MerchantResponseDto.Id Property
Unique merchant identifier (Version 7 GUID, time-ordered). Used for all merchant operations and cross-referencing.
public System.Guid Id { get; init; }
Property Value
MerchantResponseDto.IsImportant Property
Flag indicating if the merchant is marked as important/favorite by the user.
public bool IsImportant { get; init; }
Property Value
MerchantResponseDto.IsSoftDeleted Property
Flag indicating soft deletion status. Soft-deleted merchants are excluded from normal queries but retained for historical data.
public bool IsSoftDeleted { get; init; }
Property Value
MerchantResponseDto.LastUpdatedAt Property
UTC timestamp of the most recent update. Equals CreatedAt if never updated.
public System.DateTimeOffset LastUpdatedAt { get; init; }
Property Value
MerchantResponseDto.LastUpdatedBy Property
Identifier of the user who last modified this merchant. Equals CreatedBy if never updated by a different user.
public System.Guid LastUpdatedBy { get; init; }
Property Value
MerchantResponseDto.Name Property
The merchant's display name (e.g., "Kaufland Iasi Pacurari"). Required, non-empty.
public string Name { get; init; }
Property Value
MerchantResponseDto.NumberOfUpdates Property
Total count of update operations performed on this merchant. Zero for newly created merchants.
public int NumberOfUpdates { get; init; }
Property Value
MerchantResponseDto.ParentCompanyId Property
Reference to a parent company merchant (for franchise/chain stores). System.Guid.Empty if no parent company exists.
public System.Guid ParentCompanyId { get; init; }
Property Value
MerchantResponseDto.ReferencedInvoiceCount Property
Count of invoices associated with this merchant. Useful for UI display without needing to load the full invoice list.
public int ReferencedInvoiceCount { get; init; }
Property Value
MerchantResponseDto.ReferencedInvoiceIds Property
Collection of invoice identifiers referencing this merchant. Returns an empty collection if no invoices are associated.
public System.Collections.Generic.IReadOnlyCollection<System.Guid> ReferencedInvoiceIds { get; init; }
Property Value
System.Collections.Generic.IReadOnlyCollection<System.Guid>
Methods
MerchantResponseDto.FromMerchant(Merchant) Method
Creates a MerchantResponseDto from a domain Merchant entity.
public static arolariu.Backend.Domain.Invoices.DTOs.Responses.MerchantResponseDto FromMerchant(arolariu.Backend.Domain.Invoices.DDD.Entities.Merchants.Merchant merchant);
Parameters
merchant Merchant
The domain merchant entity to convert. Must not be null.
Returns
MerchantResponseDto
A new MerchantResponseDto instance with all fields mapped from the domain entity.
Exceptions
System.ArgumentNullException
Thrown when merchant is null.
Remarks
Factory Pattern: Preferred method for creating DTOs from domain entities. Ensures consistent mapping and defensive copying of collections.
Defensive Copying: The ReferencedInvoiceIds and AdditionalMetadata are copied to prevent external mutation.
ProductMetadataDto Struct
Nested metadata DTO preserving 1:1 parity with the frontend ProductMetadata type.
public readonly record struct ProductMetadataDto : System.IEquatable<arolariu.Backend.Domain.Invoices.DTOs.Responses.ProductMetadataDto>
Implements System.IEquatable<ProductMetadataDto>
Constructors
ProductMetadataDto(bool, bool, bool, double) Constructor
Nested metadata DTO preserving 1:1 parity with the frontend ProductMetadata type.
public ProductMetadataDto(bool IsEdited, bool IsComplete, bool IsSoftDeleted, double Confidence);
Parameters
IsEdited System.Boolean
IsComplete System.Boolean
IsSoftDeleted System.Boolean
Confidence System.Double
Properties
ProductMetadataDto.Confidence Property
public double Confidence { get; init; }
Property Value
ProductMetadataDto.IsComplete Property
public bool IsComplete { get; init; }
Property Value
ProductMetadataDto.IsEdited Property
public bool IsEdited { get; init; }
Property Value
ProductMetadataDto.IsSoftDeleted Property
public bool IsSoftDeleted { get; init; }
Property Value
ProductResponseDto Struct
Response DTO representing a line item product within an invoice.
public readonly record struct ProductResponseDto : System.IEquatable<arolariu.Backend.Domain.Invoices.DTOs.Responses.ProductResponseDto>
Implements System.IEquatable<ProductResponseDto>
Example
// Converting from domain value object
Product domainProduct = invoice.Items.First();
ProductResponseDto dto = ProductResponseDto.FromProduct(domainProduct);
// Displaying product info
Console.WriteLine($"{dto.Name}: {dto.Quantity} {dto.QuantityUnit} @ {dto.Price:C}");
Console.WriteLine($"Total: {dto.TotalPrice:C}");
if (dto.DetectedAllergens.Any())
Console.WriteLine($"Allergens: {string.Join(", ", dto.DetectedAllergens)}");
Remarks
Purpose: Provides a clean API contract for product/line item data, fully decoupled from the internal Product domain value object.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
Product Name:Name contains the product name as extracted from the invoice via OCR, used for display, aggregation, and analytics.
Computed Fields:TotalPrice is computed as
Quantity × Price and stored for consistency.
Allergen Detection: The DetectedAllergens collection is populated by AI analysis and may include common allergens like gluten, lactose, nuts, etc.
See Also
Constructors
ProductResponseDto(string, ProductCategory, decimal, string, string, decimal, decimal, IReadOnlyCollection<Allergen>, ProductMetadataDto) Constructor
Response DTO representing a line item product within an invoice.
public ProductResponseDto(string Name, arolariu.Backend.Domain.Invoices.DDD.ValueObjects.Products.ProductCategory Category, decimal Quantity, string QuantityUnit, string ProductCode, decimal Price, decimal TotalPrice, System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DDD.ValueObjects.Allergen> DetectedAllergens, arolariu.Backend.Domain.Invoices.DTOs.Responses.ProductMetadataDto Metadata);
Parameters
Name System.String
The name of the product as extracted from the invoice via OCR. Used for display, aggregation, allergen inference heuristics and recipe matching.
Category ProductCategory
Product category classification (e.g., Dairy, Meat, Beverages). Defaults to NOT_DEFINED if AI classification was not performed.
Quantity System.Decimal
The quantity of product units purchased. Always positive. Decimal to support fractional quantities (e.g., 1.5 kg of produce).
QuantityUnit System.String
The unit of measure (e.g., "kg", "L", "buc", "pcs"). May vary based on invoice origin and OCR extraction.
ProductCode System.String
Optional SKU, barcode (EAN/UPC), or internal product code. Empty string if not present on the invoice.
Price System.Decimal
Unit price per single quantity unit. Currency is determined by the parent invoice.
TotalPrice System.Decimal
Computed extended line total (Quantity × Price).
May differ slightly from simple multiplication due to rounding on the original invoice.
DetectedAllergens System.Collections.Generic.IReadOnlyCollection<Allergen>
Collection of allergens detected by AI analysis. Common values include: Gluten, Lactose, Nuts, Eggs, Soy, Fish, Shellfish. Empty collection if no allergens detected or analysis not performed.
Metadata ProductMetadataDto
Nested metadata containing edit status, completeness, soft-deletion flag, and OCR confidence score. Preserves 1:1 parity with frontend ProductMetadata type.
Example
// Converting from domain value object
Product domainProduct = invoice.Items.First();
ProductResponseDto dto = ProductResponseDto.FromProduct(domainProduct);
// Displaying product info
Console.WriteLine($"{dto.Name}: {dto.Quantity} {dto.QuantityUnit} @ {dto.Price:C}");
Console.WriteLine($"Total: {dto.TotalPrice:C}");
if (dto.DetectedAllergens.Any())
Console.WriteLine($"Allergens: {string.Join(", ", dto.DetectedAllergens)}");
Remarks
Purpose: Provides a clean API contract for product/line item data, fully decoupled from the internal Product domain value object.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
Product Name:Name contains the product name as extracted from the invoice via OCR, used for display, aggregation, and analytics.
Computed Fields:TotalPrice is computed as
Quantity × Price and stored for consistency.
Allergen Detection: The DetectedAllergens collection is populated by AI analysis and may include common allergens like gluten, lactose, nuts, etc.
See Also
Properties
ProductResponseDto.Category Property
Product category classification (e.g., Dairy, Meat, Beverages). Defaults to NOT_DEFINED if AI classification was not performed.
public arolariu.Backend.Domain.Invoices.DDD.ValueObjects.Products.ProductCategory Category { get; init; }
Property Value
ProductResponseDto.DetectedAllergens Property
Collection of allergens detected by AI analysis. Common values include: Gluten, Lactose, Nuts, Eggs, Soy, Fish, Shellfish. Empty collection if no allergens detected or analysis not performed.
public System.Collections.Generic.IReadOnlyCollection<arolariu.Backend.Domain.Invoices.DDD.ValueObjects.Allergen> DetectedAllergens { get; init; }
Property Value
System.Collections.Generic.IReadOnlyCollection<Allergen>
ProductResponseDto.Metadata Property
Nested metadata containing edit status, completeness, soft-deletion flag, and OCR confidence score. Preserves 1:1 parity with frontend ProductMetadata type.
public arolariu.Backend.Domain.Invoices.DTOs.Responses.ProductMetadataDto Metadata { get; init; }
Property Value
ProductResponseDto.Name Property
The name of the product as extracted from the invoice via OCR. Used for display, aggregation, allergen inference heuristics and recipe matching.
public string Name { get; init; }
Property Value
ProductResponseDto.Price Property
Unit price per single quantity unit. Currency is determined by the parent invoice.
public decimal Price { get; init; }
Property Value
ProductResponseDto.ProductCode Property
Optional SKU, barcode (EAN/UPC), or internal product code. Empty string if not present on the invoice.
public string ProductCode { get; init; }
Property Value
ProductResponseDto.Quantity Property
The quantity of product units purchased. Always positive. Decimal to support fractional quantities (e.g., 1.5 kg of produce).
public decimal Quantity { get; init; }
Property Value
ProductResponseDto.QuantityUnit Property
The unit of measure (e.g., "kg", "L", "buc", "pcs"). May vary based on invoice origin and OCR extraction.
public string QuantityUnit { get; init; }
Property Value
ProductResponseDto.TotalPrice Property
Computed extended line total (Quantity × Price).
May differ slightly from simple multiplication due to rounding on the original invoice.
public decimal TotalPrice { get; init; }
Property Value
Methods
ProductResponseDto.FromProduct(Product) Method
Creates a ProductResponseDto from a domain Product value object.
public static arolariu.Backend.Domain.Invoices.DTOs.Responses.ProductResponseDto FromProduct(arolariu.Backend.Domain.Invoices.DDD.ValueObjects.Products.Product product);
Parameters
product Product
The domain product value object to convert. Must not be null.
Returns
ProductResponseDto
A new ProductResponseDto instance with all fields mapped.
Exceptions
System.ArgumentNullException
Thrown when product is null.
Remarks
Factory Pattern: Preferred method for creating DTOs from domain objects. Ensures consistent mapping and proper handling of collection types.
Allergen Collection: If the source allergens collection is already System.Collections.Generic.IReadOnlyCollection<>, it is used directly. Otherwise, a new read-only list is created for immutability.
Metadata: The product's ProductMetadataDto is preserved as a nested structure for 1:1 parity with the frontend TypeScript type.
ResourceCreatedResponseDto Struct
Response DTO indicating successful creation of a resource via POST operation.
public readonly record struct ResourceCreatedResponseDto : System.IEquatable<arolariu.Backend.Domain.Invoices.DTOs.Responses.ResourceCreatedResponseDto>
Implements System.IEquatable<ResourceCreatedResponseDto>
Example
// Creating a resource and returning the response
var invoice = await invoiceService.CreateInvoiceAsync(request);
var response = new ResourceCreatedResponseDto(
Id: invoice.id,
Location: $"/api/invoices/{invoice.id}",
CreatedAt: invoice.CreatedAt);
return Results.Created(response.Location, response);
Remarks
Purpose: Provides a standardized response for HTTP POST operations that create new resources, following REST best practices for resource creation responses.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
HTTP Semantics: This DTO is typically returned with HTTP 201 Created status. The Location field should be set in the Location header as well.
Applicable Resources: Used for invoices, merchants, products, scans, and any other domain entity that supports creation via the API.
Constructors
ResourceCreatedResponseDto(Guid, string, DateTimeOffset) Constructor
Response DTO indicating successful creation of a resource via POST operation.
public ResourceCreatedResponseDto(System.Guid Id, string Location, System.DateTimeOffset CreatedAt);
Parameters
Id System.Guid
The unique identifier (Version 7 GUID) of the newly created resource. Clients should use this ID for subsequent operations on the resource.
Location System.String
The absolute URI where the newly created resource can be retrieved via GET.
Follows the pattern: /api/invoices/{id} or similar.
CreatedAt System.DateTimeOffset
UTC timestamp indicating when the resource was created. Useful for client-side caching and audit purposes.
Example
// Creating a resource and returning the response
var invoice = await invoiceService.CreateInvoiceAsync(request);
var response = new ResourceCreatedResponseDto(
Id: invoice.id,
Location: $"/api/invoices/{invoice.id}",
CreatedAt: invoice.CreatedAt);
return Results.Created(response.Location, response);
Remarks
Purpose: Provides a standardized response for HTTP POST operations that create new resources, following REST best practices for resource creation responses.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
HTTP Semantics: This DTO is typically returned with HTTP 201 Created status. The Location field should be set in the Location header as well.
Applicable Resources: Used for invoices, merchants, products, scans, and any other domain entity that supports creation via the API.
Properties
ResourceCreatedResponseDto.CreatedAt Property
UTC timestamp indicating when the resource was created. Useful for client-side caching and audit purposes.
public System.DateTimeOffset CreatedAt { get; init; }
Property Value
ResourceCreatedResponseDto.Id Property
The unique identifier (Version 7 GUID) of the newly created resource. Clients should use this ID for subsequent operations on the resource.
public System.Guid Id { get; init; }
Property Value
ResourceCreatedResponseDto.Location Property
The absolute URI where the newly created resource can be retrieved via GET.
Follows the pattern: /api/invoices/{id} or similar.
public string Location { get; init; }
Property Value
ResourceUpdatedResponseDto Struct
Response DTO indicating successful update of a resource via PUT/PATCH operation.
public readonly record struct ResourceUpdatedResponseDto : System.IEquatable<arolariu.Backend.Domain.Invoices.DTOs.Responses.ResourceUpdatedResponseDto>
Implements System.IEquatable<ResourceUpdatedResponseDto>
Example
// Updating a resource and returning the response
var invoice = await invoiceService.UpdateInvoiceAsync(id, request);
var response = new ResourceUpdatedResponseDto(
Id: invoice.id,
Location: $"/api/invoices/{invoice.id}",
UpdatedAt: invoice.LastUpdatedAt);
return Results.Ok(response);
Remarks
Purpose: Provides a standardized response for HTTP PUT and PATCH operations that modify existing resources, following REST best practices.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
HTTP Semantics: This DTO is typically returned with HTTP 200 OK status. For idempotent PUT operations, confirms the resource state was updated. For partial PATCH operations, confirms the specified fields were modified.
Applicable Resources: Used for invoices, merchants, products, metadata, and any other domain entity that supports modification via the API.
Constructors
ResourceUpdatedResponseDto(Guid, string, DateTimeOffset) Constructor
Response DTO indicating successful update of a resource via PUT/PATCH operation.
public ResourceUpdatedResponseDto(System.Guid Id, string Location, System.DateTimeOffset UpdatedAt);
Parameters
Id System.Guid
The unique identifier (Version 7 GUID) of the updated resource. Confirms which resource was modified by the operation.
Location System.String
The absolute URI where the updated resource can be retrieved via GET.
Follows the pattern: /api/invoices/{id} or similar.
UpdatedAt System.DateTimeOffset
UTC timestamp indicating when the resource was last modified. Useful for optimistic concurrency, caching, and audit trails.
Example
// Updating a resource and returning the response
var invoice = await invoiceService.UpdateInvoiceAsync(id, request);
var response = new ResourceUpdatedResponseDto(
Id: invoice.id,
Location: $"/api/invoices/{invoice.id}",
UpdatedAt: invoice.LastUpdatedAt);
return Results.Ok(response);
Remarks
Purpose: Provides a standardized response for HTTP PUT and PATCH operations that modify existing resources, following REST best practices.
Immutability: This is a readonly record struct ensuring thread-safety
and value semantics for equality comparisons.
HTTP Semantics: This DTO is typically returned with HTTP 200 OK status. For idempotent PUT operations, confirms the resource state was updated. For partial PATCH operations, confirms the specified fields were modified.
Applicable Resources: Used for invoices, merchants, products, metadata, and any other domain entity that supports modification via the API.
Properties
ResourceUpdatedResponseDto.Id Property
The unique identifier (Version 7 GUID) of the updated resource. Confirms which resource was modified by the operation.
public System.Guid Id { get; init; }
Property Value
ResourceUpdatedResponseDto.Location Property
The absolute URI where the updated resource can be retrieved via GET.
Follows the pattern: /api/invoices/{id} or similar.
public string Location { get; init; }
Property Value
ResourceUpdatedResponseDto.UpdatedAt Property
UTC timestamp indicating when the resource was last modified. Useful for optimistic concurrency, caching, and audit trails.
public System.DateTimeOffset UpdatedAt { get; init; }