cadrumo.adapters.outbound.google.document_link_resolver module

Scope-compatible resolution of recorded document links.

Ledger evidence may start from a recorded AttachmentSource link, but the link is not stored as evidence by itself. resolve_document_link() fetches reachable Drive content as bytes so the caller can persist those bytes through add_attachment(); the original link remains provenance metadata on that byte-bearing attachment. list_drive_folder_documents() extends the same minimal-scope posture to a folder: it lists the PDF/image children of a drive.file-reachable folder so a caller can bulk-fetch every invoice in one sweep instead of resolving one document link at a time.

The resolver stays inside the integration’s deliberate minimal-scope posture: drive.file can download Drive files the app created or the operator picked, so a GOOGLE_DRIVE reference to such a file resolves. Operator-external documents, arbitrary Drive files that require drive.readonly, and Gmail messages that require gmail.readonly are refused with OutboundStoragePermissionError instead of being silently stored as links.

class DocumentLinkPreconditionCondition(*values)

Bases: StrEnum

Closed terminal conditions owned by the document-link adapter.

API_CLIENT_AVAILABLE

REMOTE_SOURCE_SUPPORTED

DRIVE_REFERENCE_IDENTIFIED

SOURCE_SCOPE_SUFFICIENT

FILE_SCOPE_SUFFICIENT

MEDIA_TRANSPORT_AVAILABLE

MEDIA_PAYLOAD_BYTES

FOLDER_SCOPE_SUFFICIENT

FOLDER_FILES_LIST_VALID

FOLDER_ENTRY_VALID

FOLDER_PAGINATION_VALID

class DriveFolderDocument(**data)

Bases: BaseModel

One PDF/image child of a drive.file-reachable Drive folder.

Returned by list_drive_folder_documents(); carries just enough metadata for a caller to fetch the file (file_id) and report it to the operator (name, mime_type).

Parameters:

data (Any)

file_id: str

name: str

mime_type: str

class DriveFolderListing(documents, skipped_non_document_count)

Bases: object

The result of listing one Drive folder’s invoice-shaped children.

documents carries the PDF/image files the sweep will fetch; skipped_non_document_count records how many folder children were filtered out for carrying a non-invoice MIME type (e.g. a nested folder or an unrelated file), so the caller can report an honest total.

Parameters:

• documents (tuple[DriveFolderDocument, ...])

• skipped_non_document_count (int)

documents: tuple[DriveFolderDocument, ...]

skipped_non_document_count: int

parse_drive_file_id(reference)

Extract the Drive file id consumed by resolve_document_link().

Parameters:

reference (str) – A Drive URL, ?id=... link, bare Drive file id, or non-Drive reference.

Return type:

str | None

Returns:

The parsed Drive file id, or None when reference does not carry a recognisable Drive id.

resolve_document_link(*, source, reference, credentials=None, service=None)

Resolve a recorded AttachmentSource link to bytes.

Parameters:

• source (AttachmentSource) – The recorded link source.

• reference (str) – The link reference (Drive URL / file id, Gmail link, or URL).

• credentials (Credentials | None) – Google OAuth credentials carrying the granted scopes. Optional only because service may be injected instead; one of the two must be supplied.

• service (_DriveService | None) – Optional pre-built Drive v3 service. When None (the production path) the service is built from credentials; tests inject a transport-only seam here so the fetch path runs without a live network or real credentials.

Return type:

bytes

Returns:

The fetched document bytes for GOOGLE_DRIVE links the drive.file scope can reach.

Raises:

• OutboundStoragePermissionError – For Gmail links, arbitrary URLs, and Drive files outside the drive.file scope. The required sensitive scope is named in context["required_scope"].

• OutboundStorageValidationError – For sources that are not remote documents, or a Drive reference with no recognisable file id.

list_drive_folder_documents(*, folder_id, credentials=None, service=None)

List the PDF/image children of a drive.file-reachable Drive folder.

Stays inside the same minimal-scope posture as resolve_document_link(): drive.file only lists files the app created or the operator explicitly picked, so a folder the operator has not shared with the app (or does not own under this scope) surfaces no children rather than a permission escalation. A non-existent or unreachable folder_id maps Google’s 403/404 to the same OutboundStoragePermissionError scope-named refusal resolve_document_link() uses, so the two fetch surfaces read the same way.

Parameters:

• folder_id (str) – The Drive folder id (parsed the same way a document reference is via parse_drive_file_id(), or passed as a bare id).

• credentials (Credentials | None) – Google OAuth credentials carrying the granted scopes. Optional only because service may be injected instead; one of the two must be supplied.

• service (_DriveService | None) – Optional pre-built Drive v3 service (test seam).

Return type:

DriveFolderListing

Returns:

A DriveFolderListing naming every PDF/image child plus a count of filtered-out non-document children.

Raises:

• OutboundStoragePermissionError – When the folder is not reachable under the drive.file scope.

• OutboundStorageNetworkError – On any other transport or unmapped Drive failure.