aeat.domain.attachments._service module

Service-layer helpers over AttachmentStoreProtocol.

Thin orchestration on top of AttachmentStoreProtocol primitives: ingest a file from disk, build the corresponding Attachment manifest, persist it, and expose simple read paths for callers that do not need the full repository API.

add_attachment(store, *, path, kind, source, source_reference, mime_type, captured_at, bucket_id=None, link_transaction_ids=(), link_invoice_ids=(), metadata=None, notes='')

Store attachment bytes from a file and persist the corresponding manifest.

The stored bytes’ SHA-256 doubles as the attachment id so equal files deduplicate naturally.

Parameters:

• store (AttachmentStoreProtocol) – Backing AttachmentStoreProtocol for blob storage and manifest persistence.

• path (Path) – Local filesystem path to the bytes being ingested.

• kind (AttachmentKind) – Logical AttachmentKind for the attachment.

• source (AttachmentSource) – Originating AttachmentSource channel.

• source_reference (str) – Caller-supplied opaque reference into the originating system (e.g. invoice number, e-mail UID).

• mime_type (str) – MIME type of the attachment bytes.

• captured_at (datetime) – Wall-clock timestamp when the bytes were captured upstream.

• bucket_id (str | None) – Optional owning profile bucket for the evidence record.

• link_transaction_ids (tuple[str, ...]) – Optional tuple of transaction ids the attachment evidences.

• link_invoice_ids (tuple[str, ...]) – Optional tuple of invoice ids the attachment evidences.

• metadata (Mapping[str, str] | None) – Optional free-form key/value metadata.

• notes (str) – Free-form operator notes; defaults to empty.

Return type:

Attachment

Returns:

The persisted Attachment manifest.

add_attachment_bytes(store, *, data, kind, source, source_reference, mime_type, captured_at, bucket_id=None, link_transaction_ids=(), link_invoice_ids=(), metadata=None, notes='')

Store in-memory attachment bytes and persist the corresponding manifest.

The byte-bearing companion to add_attachment(): it accepts the already-fetched document data (e.g. a Drive download resolved via adapters.outbound.google.resolve_document_link()) instead of a filesystem path, stores the encrypted blob through the same put_bytes / write_manifest path, and records the real SHA-256 and supplied mime_type. The stored bytes’ SHA-256 is the attachment id, so equal documents deduplicate naturally. There is deliberately no link-only path: an evidence record always carries the document’s encrypted bytes.

Parameters:

• store (AttachmentStoreProtocol) – Backing AttachmentStoreProtocol.

• data (bytes) – The already-fetched document bytes to encrypt and store.

• kind (AttachmentKind) – Logical AttachmentKind.

• source (AttachmentSource) – Originating AttachmentSource.

• source_reference (str) – The original link / reference recorded as provenance.

• mime_type (str) – MIME type of the fetched bytes.

• captured_at (datetime) – Wall-clock timestamp when the bytes were captured.

• bucket_id (str | None) – Optional owning profile bucket for the evidence record.

• link_transaction_ids (tuple[str, ...]) – Optional transaction ids the attachment evidences.

• link_invoice_ids (tuple[str, ...]) – Optional invoice ids the attachment evidences.

• metadata (Mapping[str, str] | None) – Optional free-form key/value metadata.

• notes (str) – Free-form operator notes; defaults to empty.

Return type:

Attachment

Returns:

The persisted Attachment manifest carrying the real sha256 and mime_type.

load_attachment(store, attachment_id)

Load one attachment manifest from the store.

Parameters:

• store (AttachmentStoreProtocol) – Backing AttachmentStoreProtocol.

• attachment_id (str) – SHA-256 of the attachment bytes.

Return type:

Attachment

Returns:

The Attachment manifest for attachment_id.

link_attachment_invoice(store, *, attachment_id, invoice_id)

Append invoice_id to an already-persisted attachment’s linked_invoice_ids.

Closes the provenance loop the other direction from add_attachment(_bytes)’s link_invoice_ids parameter: that parameter can only be populated for an invoice that already exists before the evidence is captured, but the evidence-confirmation flow mints the Invoice after the attachment is already stored. This helper re-persists the same manifest (attachment id and bytes unchanged) through the same AttachmentStoreProtocol.write_manifest() write path (composition-service-no-parallel-write-path), with invoice_id appended.

Idempotent by construction: Attachment’s linked_invoice_ids validator deduplicates and preserves first-seen order, so calling this twice with the same invoice_id is a no-op – the manifest’s byte content after the second call is identical to after the first (a real re-confirm safely re-links without growing the tuple).

Parameters:

• store (AttachmentStoreProtocol) – Backing AttachmentStoreProtocol.

• attachment_id (str) – SHA-256 of the attachment bytes to update.

• invoice_id (str) – Stable Invoice identifier to record as evidenced by this attachment.

Return type:

Attachment

Returns:

The re-persisted Attachment manifest carrying invoice_id in Attachment.linked_invoice_ids.

list_attachments(store, *, linked_to=None, kind=None)

List attachment manifests, optionally filtered by link or kind.

Parameters:

• store (AttachmentStoreProtocol) – Backing AttachmentStoreProtocol.

• linked_to (str | None) – When provided, return only attachments whose linked_transaction_ids or linked_invoice_ids tuple contains this id.

• kind (AttachmentKind | None) – When provided, return only attachments of this AttachmentKind.

Return type:

tuple[Attachment, ...]

Returns:

Filtered tuple of Attachment manifests in store iteration order.