matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab/literature.py

@@ -0,0 +1,1243 @@
+import json
+import math
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Literal, TypeAlias, cast
+
+from pydantic import ValidationError
+
+from matelab._generated.models import BasicSuccessResponse as WireBasicSuccessResponse
+from matelab._generated.models import DeleteLiteratureCommentRequest as WireDeleteLiteratureCommentRequest
+from matelab._generated.models import DeleteLiteraturePdfRequest as WireDeleteLiteraturePdfRequest
+from matelab._generated.models import DeletePersonalLiteratureItemRequest as WireDeletePersonalLiteratureItemRequest
+from matelab._generated.models import DownloadLiteraturePdfParametersQuery as WireDownloadLiteraturePdfQuery
+from matelab._generated.models import ExtractedLiteratureAuthor as WireExtractedLiteratureAuthor
+from matelab._generated.models import ExtractLiteratureMetadataRequest as WireExtractLiteratureMetadataRequest
+from matelab._generated.models import ListLiteratureItemsParametersQuery as WireListLiteratureItemsQuery
+from matelab._generated.models import LiteratureContent1 as WireInvalidLiteratureContent
+from matelab._generated.models import LiteratureContentObject as WireLiteratureContentObject
+from matelab._generated.models import LiteratureDetailResponse as WireLiteratureDetailResponse
+from matelab._generated.models import LiteratureFieldDefinition as WireLiteratureFieldDefinition
+from matelab._generated.models import LiteratureLibrariesResponse as WireLiteratureLibrariesResponse
+from matelab._generated.models import LiteratureLibrary as WireLiteratureLibrary
+from matelab._generated.models import LiteratureListItem as WireLiteratureListItem
+from matelab._generated.models import LiteratureListResponse as WireLiteratureListResponse
+from matelab._generated.models import LiteratureMetadataExtractionResponse as WireLiteratureMetadataExtractionResponse
+from matelab._generated.models import LiteratureTemplateResponse as WireLiteratureTemplateResponse
+from matelab._generated.models import ReadLiteratureDetailParametersQuery as WireReadLiteratureDetailQuery
+from matelab._generated.models import ReplaceLiteraturePdfRequest as WireReplaceLiteraturePdfRequest
+from matelab._generated.models import SaveLiteratureCommentRequest as WireSaveLiteratureCommentRequest
+from matelab._generated.models import SaveLiteratureContent as WireSaveLiteratureContent
+from matelab._generated.models import SaveLiteratureItemRequest as WireSaveLiteratureItemRequest
+from matelab._generated.models import ShareLiteratureItemsRequest as WireShareLiteratureItemsRequest
+from matelab._transport import Encoding, Operation, SessionTransport, StreamOperation, multipart_fields
+from matelab.errors import MatelabError, MatelabProtocolError, MatelabUsageError, MatelabVerificationError
+from matelab.streaming import ByteRange, DownloadStream
+from matelab.uploads import StagedFile, UploadBindingRef
+from matelab.users import UserRef, UserSummary
+
+_LIST_LIBRARIES = Operation(
+    method="GET",
+    path="/recommend_fav/stores",
+    encoding=Encoding.NONE,
+    response_model=WireLiteratureLibrariesResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_LIST_ITEMS = Operation(
+    method="GET",
+    path="/recommend_fav/list",
+    encoding=Encoding.QUERY,
+    response_model=WireLiteratureListResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_READ_ITEM = Operation(
+    method="GET",
+    path="/recommend_fav/detail",
+    encoding=Encoding.QUERY,
+    response_model=WireLiteratureDetailResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_SAVE_COMMENT = Operation(
+    method="POST",
+    path="/recommend_fav/comment",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_COMMENT = Operation(
+    method="POST",
+    path="/recommend_fav/comment_del",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_SHARE_ITEMS = Operation(
+    method="POST",
+    path="/recommend_fav/share",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_PERSONAL_ITEM = Operation(
+    method="POST",
+    path="/recommend_fav/del",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_READ_CREATION_SCHEMA = Operation(
+    method="GET",
+    path="/recommend_fav/template",
+    encoding=Encoding.NONE,
+    response_model=WireLiteratureTemplateResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_EXTRACT_METADATA = Operation(
+    method="POST",
+    path="/actions/pdf_doi",
+    encoding=Encoding.MULTIPART,
+    response_model=WireLiteratureMetadataExtractionResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+_SAVE_ITEM = Operation(
+    method="POST",
+    path="/recommend_fav/edit",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_REPLACE_PDF = Operation(
+    method="POST",
+    path="/recommend_fav/pdf_add",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_DELETE_PDF = Operation(
+    method="POST",
+    path="/recommend_fav/pdf_del",
+    encoding=Encoding.MULTIPART,
+    response_model=WireBasicSuccessResponse,
+    success_codes=frozenset({0}),
+)
+_DOWNLOAD_PDF = StreamOperation(
+    method="GET",
+    path="/url_eln/hash",
+    retry_on_access_expired=True,
+    media_types=frozenset({"application/pdf", "application/octet-stream"}),
+)
+_SHA256_PATTERN = re.compile(r"^[0-9a-f]{64}$")
+_COMMENT_ATTACHMENT_MARKER = "matelab-staged-file"
+
+
+def _empty_mapping() -> Mapping[str, object]:
+    return MappingProxyType({})
+
+
+class LiteratureSource(StrEnum):
+    SUBSCRIBED = "subscribed"
+    USER_CREATED = "user_created"
+    SHARED_COPY = "shared_copy"
+
+
+@dataclass(frozen=True, slots=True)
+class PersonalLiteratureLibraryRef:
+    """The caller's synthetic private library (`store_id=0`)."""
+
+
+@dataclass(frozen=True, slots=True)
+class SharedLiteratureLibraryRef:
+    literature_library_id: int
+
+
+LiteratureLibraryRef: TypeAlias = PersonalLiteratureLibraryRef | SharedLiteratureLibraryRef
+
+
+@dataclass(frozen=True, slots=True)
+class PendingLiteratureShareRef:
+    """A pending copy identity, not a readable library-item identity."""
+
+    pending_item_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class PersonalLiteratureItemRef:
+    literature_item_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class SharedLiteratureItemRef:
+    literature_item_id: int
+    library: SharedLiteratureLibraryRef
+
+
+LiteratureItemRef: TypeAlias = PersonalLiteratureItemRef | SharedLiteratureItemRef
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureLibrarySummary:
+    ref: LiteratureLibraryRef | None
+    kind: Literal["personal", "shared", "dangling_membership"]
+    name: str | None
+    permission_mask: int
+    item_count: int
+    keywords: tuple[str, ...]
+    introduction: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class PendingLiteratureShareComment:
+    comment_id: int
+    share: PendingLiteratureShareRef
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class PendingLiteratureShare:
+    ref: PendingLiteratureShareRef
+    title: str | None
+    sender_name: str
+    introduction: str | None
+    keywords: tuple[str, ...]
+    comments: tuple[PendingLiteratureShareComment, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureLibraries:
+    personal: LiteratureLibrarySummary
+    shared: tuple[LiteratureLibrarySummary, ...]
+    dangling_memberships: tuple[LiteratureLibrarySummary, ...]
+    pending_shares: tuple[PendingLiteratureShare, ...]
+    unmatched_pending_comments: tuple[PendingLiteratureShareComment, ...]
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureCitation:
+    year: float | None = None
+    volume: str | None = None
+    issue: str | None = None
+    page: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureMetadata:
+    """Complete canonical metadata replacement accepted by the Provider template."""
+
+    title: str
+    journal: str | None = None
+    citation: LiteratureCitation | None = None
+    author: str | None = None
+    keywords: tuple[str, ...] | None = ()
+    abstract: str | None = ""
+    doi: str | None = None
+    url: str | None = None
+    references: tuple[str, ...] | None = ()
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureStoredMetadata:
+    """Decoded stored metadata, including source fields a canonical update would drop."""
+
+    valid_object: bool
+    title: str | None
+    journal: str | None
+    citation: LiteratureCitation | None
+    author: str | None
+    authors: tuple[str, ...] | None
+    keywords: tuple[str, ...] | None
+    abstract: str | None
+    reference_information: str | None
+    doi: str | None
+    url: str | None
+    references: tuple[str, ...] | None
+    extension_fields: Mapping[str, object] = field(default_factory=_empty_mapping)
+    fields_dropped_by_canonical_update: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class LiteraturePdf:
+    item: LiteratureItemRef
+    sha256: str | None = field(repr=False)
+    filename: str | None
+    size: int | None
+
+    @property
+    def is_attached(self) -> bool:
+        return self.sha256 is not None or self.filename is not None or self.size is not None
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureItemSummary:
+    ref: LiteratureItemRef
+    source: LiteratureSource
+    star: int
+    title: str
+    author: str
+    citation_html: str
+    abstract: str
+    journal: str
+    keywords: tuple[str, ...]
+    publication_date: str
+    matching_author_fragments: tuple[str, ...]
+    pdf: LiteraturePdf
+
+
+@dataclass(frozen=True, slots=True)
+class LiteraturePage:
+    library: LiteratureLibraryRef
+    items: tuple[LiteratureItemSummary, ...]
+    library_keywords: tuple[str, ...]
+    library_name: str
+    permission_mask: int
+    page: int
+    requested_page_size: int
+    effective_page_size: int
+    total_count: int
+    has_more: bool
+    ordering: Literal["descending_item_id"] = "descending_item_id"
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureNestedField:
+    field_id: str
+    field_type: str
+    label: str | tuple[str, str]
+    width: int | None
+    attributes: Mapping[str, object] = field(default_factory=_empty_mapping)
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureField:
+    field_id: str
+    field_type: str
+    label: str | tuple[str, str]
+    required: bool | None
+    group: str | None
+    help_text: str | tuple[str, str] | None
+    print_template: str | None
+    nested: tuple[LiteratureNestedField, ...]
+    visible: bool | None
+    width: int | None
+    condition: Mapping[str, object] | None
+    attributes: Mapping[str, object] = field(default_factory=_empty_mapping)
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureCreationSchema:
+    fields: tuple[LiteratureField, ...]
+    metadata_extraction_available: bool
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureCommentRef:
+    item: LiteratureItemRef
+    comment_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureComment:
+    ref: LiteratureCommentRef
+    content: str
+    author: UserRef
+    author_name: str | None
+    created_at: str
+    owned_by_caller: bool
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureDetail:
+    ref: LiteratureItemRef
+    metadata: LiteratureStoredMetadata
+    schema_fields: tuple[LiteratureField, ...]
+    library_keywords: tuple[str, ...]
+    item_keywords: tuple[str, ...]
+    star: int
+    comments: tuple[LiteratureComment, ...]
+    pdf: LiteraturePdf
+    source: LiteratureSource
+    permission_mask: int
+    library_name: str
+    authorization_scope: Literal["provider_authorized_response_pvd_011_not_security_proof"] = (
+        "provider_authorized_response_pvd_011_not_security_proof"
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class DoiMetadataSource:
+    doi: str
+
+
+@dataclass(frozen=True, slots=True)
+class StagedPdfMetadataSource:
+    staged_pdf: StagedFile
+
+
+LiteratureMetadataSource: TypeAlias = DoiMetadataSource | StagedPdfMetadataSource
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedLiteratureAuthor:
+    name: str
+    affiliations: tuple[str, ...] | None
+    email: str | None
+    corresponding: bool | None
+    orcid: str | None
+    extension_fields: Mapping[str, object] = field(default_factory=_empty_mapping)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedLiteratureMetadata:
+    doi: str | None
+    url: str | None
+    publication_date: str | None
+    publisher: str | None
+    journal: str | None
+    issue: str | None
+    volume: str | None
+    page: str | None
+    title: str | None
+    abstract: str | None
+    authors: tuple[ExtractedLiteratureAuthor, ...] | None
+    keywords: tuple[str, ...] | None
+    references: tuple[str, ...] | None
+    fundings: tuple[object, ...] | None
+    language: str | None
+    citation_count: int | None
+    extension_fields: Mapping[str, object] = field(default_factory=_empty_mapping)
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureCreateResult:
+    requested: LiteratureMetadata
+    staged_pdf: StagedFile | None
+    created_item: None = None
+    identity_status: Literal["provider_did_not_return_identity"] = "provider_did_not_return_identity"
+    persistence: Literal["provider_acknowledged_not_readback_identifiable"] = (
+        "provider_acknowledged_not_readback_identifiable"
+    )
+    metadata_pdf_atomicity: Literal["not_guaranteed"] = "not_guaranteed"
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureUpdateResult:
+    item: LiteratureItemRef
+    requested: LiteratureMetadata
+    observed: LiteratureDetail
+    confirmation: Literal["observed_matching", "observed_mismatch"]
+    source_metadata_loss_authorized: bool
+    provider_cas: Literal[False] = False
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiteraturePdfReplaceResult:
+    item: LiteratureItemRef
+    staged_pdf: StagedFile
+    observed: LiteraturePdf
+    confirmation: Literal["observed_matching", "observed_mismatch"]
+    metadata_pdf_atomicity: Literal["separate_mutation_not_atomic"] = "separate_mutation_not_atomic"
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiteraturePdfDeleteResult:
+    item: LiteratureItemRef
+    observed: LiteraturePdf
+    absence_confirmed: bool
+    metadata_pdf_atomicity: Literal["separate_mutation_not_atomic"] = "separate_mutation_not_atomic"
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiteraturePermanentDeleteResult:
+    item: PersonalLiteratureItemRef
+    absence_confirmed: bool
+    verification: Literal["personal_library_snapshot"]
+    recoverable: Literal[False] = False
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureShareResult:
+    items: tuple[LiteratureItemRef, ...]
+    recipients: tuple[UserRef, ...]
+    copied_owner_comment: bool
+    per_recipient_results: None = None
+    outcome: Literal["provider_acknowledged_unverified_batch"] = "provider_acknowledged_unverified_batch"
+    atomicity: Literal["provider_does_not_report_or_guarantee_batch_atomicity"] = (
+        "provider_does_not_report_or_guarantee_batch_atomicity"
+    )
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureCommentDraft:
+    """Rich text; use one `matelab-staged-file` marker when attaching a staged file."""
+
+    html: str
+    attachment: StagedFile | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureCommentSaveResult:
+    item: LiteratureItemRef
+    action: Literal["created", "updated"]
+    upload_binding: UploadBindingRef
+    owner_comments_after: tuple[LiteratureComment, ...]
+    observed: LiteratureComment | None
+    confirmation: Literal["one_owner_comment_observed", "no_owner_comment_observed", "multiple_owner_comments_observed"]
+    binding_authorization: Literal["provider_does_not_verify_uploader"] = "provider_does_not_verify_uploader"
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class LiteratureCommentDeleteResult:
+    comment: LiteratureCommentRef
+    absence_confirmed: bool
+    automatic_retry: Literal[False] = False
+
+
+class Literature:
+    """Literature discovery, canonical metadata, sharing, comments, and PDF workflows."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def libraries(self) -> LiteratureLibraries:
+        response = await self._transport.request(_LIST_LIBRARIES)
+        personal_items = [item for item in response.stores if item.id == 0]
+        if len(personal_items) != 1:
+            raise MatelabProtocolError("Matelab did not return exactly one synthetic personal literature library.")
+        personal_wire = personal_items[0]
+        personal = self._library(personal_wire, kind="personal")
+        shared = tuple(self._library(item, kind="shared") for item in response.stores if item.id not in {0, None})
+        dangling = tuple(self._library(item, kind="dangling_membership") for item in response.stores if item.id is None)
+        comments = tuple(
+            PendingLiteratureShareComment(
+                comment_id=item.id, share=PendingLiteratureShareRef(pending_item_id=item.fav_id), content=item.content
+            )
+            for item in response.share_comments
+        )
+        comment_by_share: dict[int, list[PendingLiteratureShareComment]] = {}
+        for comment in comments:
+            comment_by_share.setdefault(comment.share.pending_item_id, []).append(comment)
+        shares = tuple(
+            PendingLiteratureShare(
+                ref=PendingLiteratureShareRef(pending_item_id=item.id),
+                title=item.title,
+                sender_name=item.username,
+                introduction=item.intro,
+                keywords=tuple(item.keywords),
+                comments=tuple(comment_by_share.get(item.id, ())),
+            )
+            for item in response.share
+        )
+        known_share_ids = {item.ref.pending_item_id for item in shares}
+        return LiteratureLibraries(
+            personal=personal,
+            shared=shared,
+            dangling_memberships=dangling,
+            pending_shares=shares,
+            unmatched_pending_comments=tuple(
+                comment for comment in comments if comment.share.pending_item_id not in known_share_ids
+            ),
+        )
+
+    async def list(
+        self,
+        library: LiteratureLibraryRef | None = None,
+        *,
+        page: int = 1,
+        page_size: int = 10,
+        sources: Sequence[LiteratureSource] = (),
+        stars: Sequence[int] = (),
+        keywords: Sequence[str] = (),
+        search: str = "",
+        search_author: bool = False,
+    ) -> LiteraturePage:
+        selected_library: LiteratureLibraryRef = library or PersonalLiteratureLibraryRef()
+        store_id = self._library_id(selected_library)
+        source_values = tuple(self._source_wire_value(source) for source in sources)
+        star_values = tuple(stars)
+        keyword_values = tuple(keywords)
+        if (
+            len(source_values) != len(set(source_values))
+            or any(type(star) is not int or not 1 <= star <= 5 for star in star_values)
+            or len(star_values) != len(set(star_values))
+            or any(not isinstance(keyword, str) for keyword in cast(tuple[object, ...], keyword_values))
+            or len(keyword_values) != len(set(keyword_values))
+            or type(search_author) is not bool
+        ):
+            raise MatelabUsageError("Literature list filters contain invalid or duplicate values.")
+        try:
+            request = WireListLiteratureItemsQuery.model_validate(
+                {
+                    "page": page,
+                    "page_size": page_size,
+                    "store_id": store_id,
+                    "types": json.dumps(source_values, separators=(",", ":")) if source_values else "",
+                    "stars": json.dumps(star_values, separators=(",", ":")) if star_values else "",
+                    "keywords": (
+                        json.dumps(keyword_values, ensure_ascii=False, separators=(",", ":")) if keyword_values else ""
+                    ),
+                    "search": search,
+                    "search_type": int(search_author),
+                }
+            )
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Literature list filters do not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_LIST_ITEMS, payload=request.model_dump(mode="json"))
+        normalized_page = max(1, request.page)
+        effective_page_size = max(request.page_size, 10)
+        return LiteraturePage(
+            library=selected_library,
+            items=tuple(self._summary(item, selected_library) for item in response.items),
+            library_keywords=tuple(response.keywords),
+            library_name=response.store_name,
+            permission_mask=response.power,
+            page=normalized_page,
+            requested_page_size=request.page_size,
+            effective_page_size=effective_page_size,
+            total_count=response.count,
+            has_more=normalized_page * effective_page_size < response.count,
+        )
+
+    async def read(self, item: LiteratureItemRef) -> LiteratureDetail:
+        item_id = self._item_id(item)
+        try:
+            request = WireReadLiteratureDetailQuery(id=item_id)
+        except ValidationError:
+            raise MatelabUsageError("Literature item identity does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_READ_ITEM, payload=request.model_dump(mode="json"))
+        return self._detail(item, response)
+
+    async def creation_schema(self) -> LiteratureCreationSchema:
+        response = await self._transport.request(_READ_CREATION_SCHEMA)
+        return LiteratureCreationSchema(
+            fields=tuple(self._field(item) for item in response.template), metadata_extraction_available=response.doipdf
+        )
+
+    async def extract_metadata(self, source: LiteratureMetadataSource) -> ExtractedLiteratureMetadata:
+        raw_source = cast(object, source)
+        if isinstance(raw_source, DoiMetadataSource):
+            payload: dict[str, object] = {"id": 0, "doi": raw_source.doi}
+        elif isinstance(raw_source, StagedPdfMetadataSource):
+            self._validate_staged_file(raw_source.staged_pdf)
+            payload = {"id": raw_source.staged_pdf.temporary_file_id, "doi": ""}
+        else:
+            raise MatelabUsageError("Literature metadata extraction needs a DOI or a completed staged PDF.")
+        try:
+            request = WireExtractLiteratureMetadataRequest.model_validate(payload)
+        except ValidationError:
+            raise MatelabUsageError("Literature metadata source does not satisfy the Integration Contract.") from None
+        request_payload = cast(dict[str, object], request.model_dump(mode="json"))
+        response = await self._transport.request(_EXTRACT_METADATA, files=multipart_fields(request_payload))
+        item = response.doi
+        return ExtractedLiteratureMetadata(
+            doi=item.DOI,
+            url=item.url,
+            publication_date=item.date,
+            publisher=item.publisher,
+            journal=item.publication,
+            issue=item.issue,
+            volume=item.volume,
+            page=item.page,
+            title=item.title,
+            abstract=item.abstract,
+            authors=(
+                tuple(self._extracted_author(author) for author in item.authors) if item.authors is not None else None
+            ),
+            keywords=tuple(item.keywords) if item.keywords is not None else None,
+            references=tuple(item.refs) if item.refs is not None else None,
+            fundings=tuple(cast(list[object], item.fundings)) if item.fundings is not None else None,
+            language=item.language,
+            citation_count=item.citation_count,
+            extension_fields=MappingProxyType(cast(dict[str, object], dict(item.model_extra or {}))),
+        )
+
+    async def download_pdf(
+        self, pdf: LiteraturePdf, *, byte_range: ByteRange | None = None, preview: bool = True
+    ) -> DownloadStream:
+        if (
+            pdf.sha256 is None
+            or _SHA256_PATTERN.fullmatch(pdf.sha256) is None
+            or type(preview) is not bool
+            or self._item_id(pdf.item) < 1
+        ):
+            raise MatelabUsageError("Literature PDF identity does not satisfy the Integration Contract.")
+        try:
+            request = WireDownloadLiteraturePdfQuery.model_validate(
+                {
+                    "t": "recommend_fav_pdf",
+                    "id": self._item_id(pdf.item),
+                    "h": pdf.sha256,
+                    "f": pdf.filename or "",
+                    "c": int(preview),
+                    "thumb": 0,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Literature PDF identity does not satisfy the Integration Contract.") from None
+        return await self._transport.stream(
+            _DOWNLOAD_PDF,
+            payload=request.model_dump(mode="json"),
+            range_header=byte_range.to_header() if byte_range is not None else None,
+        )
+
+    async def create(
+        self, metadata: LiteratureMetadata, *, staged_pdf: StagedFile | None = None
+    ) -> LiteratureCreateResult:
+        if staged_pdf is not None:
+            self._validate_staged_file(staged_pdf)
+        request = self._save_request(metadata, item=None, staged_pdf=staged_pdf)
+        request_payload = cast(dict[str, object], request.model_dump(mode="json"))
+        _ = await self._transport.request(_SAVE_ITEM, files=multipart_fields(request_payload))
+        return LiteratureCreateResult(requested=metadata, staged_pdf=staged_pdf)
+
+    async def update(
+        self, item: LiteratureItemRef, metadata: LiteratureMetadata, *, allow_source_metadata_loss: bool = False
+    ) -> LiteratureUpdateResult:
+        if type(cast(object, allow_source_metadata_loss)) is not bool:
+            raise MatelabUsageError("Source-metadata-loss acknowledgement must be a boolean.")
+        before = await self.read(item)
+        if before.metadata.fields_dropped_by_canonical_update and not allow_source_metadata_loss:
+            fields = ", ".join(before.metadata.fields_dropped_by_canonical_update)
+            message = (
+                f"Canonical replacement would drop source metadata ({fields}); "
+                + "set allow_source_metadata_loss=True only when that loss is intentional."
+            )
+            raise MatelabUsageError(message)
+        request = self._save_request(metadata, item=item, staged_pdf=None)
+        request_payload = cast(dict[str, object], request.model_dump(mode="json"))
+        _ = await self._transport.request(_SAVE_ITEM, files=multipart_fields(request_payload))
+        observed = await self._verified_read(item, "literature metadata replacement")
+        return LiteratureUpdateResult(
+            item=item,
+            requested=metadata,
+            observed=observed,
+            confirmation="observed_matching"
+            if self._metadata_matches(observed.metadata, metadata)
+            else "observed_mismatch",
+            source_metadata_loss_authorized=allow_source_metadata_loss,
+        )
+
+    async def replace_pdf(self, item: LiteratureItemRef, staged_pdf: StagedFile) -> LiteraturePdfReplaceResult:
+        self._validate_staged_file(staged_pdf)
+        try:
+            request = WireReplaceLiteraturePdfRequest.model_validate(
+                {"id": self._item_id(item), "uid": staged_pdf.binding.uid}
+            )
+        except ValidationError:
+            raise MatelabUsageError("Literature PDF replacement does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_REPLACE_PDF, files=multipart_fields(request.model_dump(mode="json")))
+        observed = (await self._verified_read(item, "literature PDF replacement")).pdf
+        matches = (
+            observed.sha256 == staged_pdf.sha256
+            and observed.filename == staged_pdf.filename
+            and observed.size == staged_pdf.size
+        )
+        return LiteraturePdfReplaceResult(
+            item=item,
+            staged_pdf=staged_pdf,
+            observed=observed,
+            confirmation="observed_matching" if matches else "observed_mismatch",
+        )
+
+    async def delete_pdf(self, item: LiteratureItemRef) -> LiteraturePdfDeleteResult:
+        try:
+            request = WireDeleteLiteraturePdfRequest(id=self._item_id(item))
+        except ValidationError:
+            raise MatelabUsageError("Literature PDF identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_DELETE_PDF, files=multipart_fields(request.model_dump(mode="json")))
+        observed = (await self._verified_read(item, "literature PDF deletion")).pdf
+        return LiteraturePdfDeleteResult(item=item, observed=observed, absence_confirmed=not observed.is_attached)
+
+    async def permanently_delete(self, item: PersonalLiteratureItemRef) -> LiteraturePermanentDeleteResult:
+        raw_item = cast(object, item)
+        if not isinstance(raw_item, PersonalLiteratureItemRef):
+            raise MatelabUsageError(
+                "Permanent literature deletion only accepts an item observed in the personal library."
+            )
+        try:
+            request = WireDeletePersonalLiteratureItemRequest(id=self._item_id(item))
+        except ValidationError:
+            raise MatelabUsageError("Personal literature identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(
+            _DELETE_PERSONAL_ITEM, files=multipart_fields(request.model_dump(mode="json"))
+        )
+        absent = await self._verified_personal_absence(item)
+        return LiteraturePermanentDeleteResult(
+            item=item, absence_confirmed=absent, verification="personal_library_snapshot"
+        )
+
+    async def share(
+        self,
+        items: Sequence[LiteratureItemSummary],
+        recipients: Sequence[UserSummary],
+        *,
+        introduction: str = "",
+        copy_owner_comment: bool = False,
+    ) -> LiteratureShareResult:
+        selected = tuple(items)
+        targets = tuple(recipients)
+        item_ids = tuple(self._item_id(item.ref) for item in selected)
+        userids = tuple(target.ref.userid for target in targets)
+        identity = self._transport.require_session().identity
+        if (
+            not selected
+            or len(item_ids) != len(set(item_ids))
+            or not targets
+            or any(type(userid) is not int or userid < 1 for userid in userids)
+            or len(userids) != len(set(userids))
+            or identity is None
+            or identity.userid in userids
+            or type(copy_owner_comment) is not bool
+        ):
+            message = (
+                "Literature sharing needs distinct list-observed items, distinct search-observed non-self users, "
+                + "and a resolved caller identity."
+            )
+            raise MatelabUsageError(message)
+        if copy_owner_comment:
+            for selected_item in selected:
+                detail = await self.read(selected_item.ref)
+                if sum(comment.owned_by_caller for comment in detail.comments) > 1:
+                    raise MatelabUsageError(
+                        "The source has multiple caller-owned comments, so comment copying is ambiguous (PVD-035)."
+                    )
+        try:
+            request = WireShareLiteratureItemsRequest.model_validate(
+                {
+                    "ids": json.dumps(item_ids, separators=(",", ":")),
+                    "users": json.dumps(userids, separators=(",", ":")),
+                    "comm": int(copy_owner_comment),
+                    "intro": introduction,
+                }
+            )
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Literature share input does not satisfy the Integration Contract.") from None
+        share_payload = cast(dict[str, object], request.model_dump(mode="json"))
+        _ = await self._transport.request(_SHARE_ITEMS, files=multipart_fields(share_payload))
+        return LiteratureShareResult(
+            items=tuple(item.ref for item in selected),
+            recipients=tuple(target.ref for target in targets),
+            copied_owner_comment=copy_owner_comment,
+        )
+
+    async def save_comment(self, item: LiteratureItemRef, draft: LiteratureCommentDraft) -> LiteratureCommentSaveResult:
+        before = await self.read(item)
+        owned_before = tuple(comment for comment in before.comments if comment.owned_by_caller)
+        if len(owned_before) > 1:
+            raise MatelabUsageError(
+                "The caller already owns multiple comments on this item, so create/edit selection is ambiguous (PVD-035)."
+            )
+        rendered, binding = self._render_comment(draft)
+        if owned_before:
+            payload: dict[str, object] = {
+                "id": owned_before[0].ref.comment_id,
+                "fav_id": 0,
+                "comment": rendered,
+                "uid": binding.uid,
+            }
+            action: Literal["created", "updated"] = "updated"
+        else:
+            payload = {"id": 0, "fav_id": self._item_id(item), "comment": rendered, "uid": binding.uid}
+            action = "created"
+        try:
+            request = WireSaveLiteratureCommentRequest.model_validate(payload)
+        except ValidationError:
+            raise MatelabUsageError("Literature comment does not satisfy the Integration Contract.") from None
+        request_payload = cast(dict[str, object], request.model_dump(mode="json"))
+        _ = await self._transport.request(_SAVE_COMMENT, files=multipart_fields(request_payload))
+        after = await self._verified_read(item, "literature comment save")
+        owned_after = tuple(comment for comment in after.comments if comment.owned_by_caller)
+        if len(owned_after) == 1:
+            confirmation: Literal[
+                "one_owner_comment_observed", "no_owner_comment_observed", "multiple_owner_comments_observed"
+            ] = "one_owner_comment_observed"
+            observed = owned_after[0]
+        elif not owned_after:
+            confirmation = "no_owner_comment_observed"
+            observed = None
+        else:
+            confirmation = "multiple_owner_comments_observed"
+            observed = None
+        return LiteratureCommentSaveResult(
+            item=item,
+            action=action,
+            upload_binding=binding,
+            owner_comments_after=owned_after,
+            observed=observed,
+            confirmation=confirmation,
+        )
+
+    async def delete_comment(self, comment: LiteratureComment) -> LiteratureCommentDeleteResult:
+        if not comment.owned_by_caller:
+            raise MatelabUsageError("Only a caller-owned, detail-observed literature comment can be deleted.")
+        try:
+            request = WireDeleteLiteratureCommentRequest(id=comment.ref.comment_id)
+        except ValidationError:
+            raise MatelabUsageError("Literature comment identity does not satisfy the Integration Contract.") from None
+        _ = await self._transport.request(_DELETE_COMMENT, files=multipart_fields(request.model_dump(mode="json")))
+        after = await self._verified_read(comment.ref.item, "literature comment deletion")
+        return LiteratureCommentDeleteResult(
+            comment=comment.ref,
+            absence_confirmed=all(item.ref.comment_id != comment.ref.comment_id for item in after.comments),
+        )
+
+    async def _verified_read(self, item: LiteratureItemRef, action: str) -> LiteratureDetail:
+        try:
+            return await self.read(item)
+        except MatelabError as exc:
+            raise MatelabVerificationError(
+                f"Matelab acknowledged the {action}, but readback failed; the mutation may have persisted."
+            ) from exc
+
+    async def _verified_personal_absence(self, item: PersonalLiteratureItemRef) -> bool:
+        try:
+            first = await self.list(PersonalLiteratureLibraryRef(), page=1, page_size=256)
+            if any(summary.ref == item for summary in first.items):
+                return False
+            for page_number in range(2, math.ceil(first.total_count / first.effective_page_size) + 1):
+                page = await self.list(
+                    PersonalLiteratureLibraryRef(), page=page_number, page_size=first.effective_page_size
+                )
+                if any(summary.ref == item for summary in page.items):
+                    return False
+            return True
+        except MatelabError as exc:
+            message = (
+                "Matelab acknowledged permanent literature deletion, but personal-library readback failed; "
+                + "the deletion may have persisted."
+            )
+            raise MatelabVerificationError(message) from exc
+
+    def _save_request(
+        self, metadata: LiteratureMetadata, *, item: LiteratureItemRef | None, staged_pdf: StagedFile | None
+    ) -> WireSaveLiteratureItemRequest:
+        wire_metadata = self._wire_metadata(metadata)
+        payload = {
+            "id": self._item_id(item) if item is not None else 0,
+            "store_id": 0,
+            "uid": staged_pdf.binding.uid if staged_pdf is not None else "",
+            "info": json.dumps(wire_metadata.model_dump(mode="json"), ensure_ascii=False, separators=(",", ":")),
+        }
+        try:
+            return WireSaveLiteratureItemRequest.model_validate(payload)
+        except (ValidationError, TypeError, ValueError):
+            raise MatelabUsageError("Literature save input does not satisfy the Integration Contract.") from None
+
+    @staticmethod
+    def _wire_metadata(metadata: LiteratureMetadata) -> WireSaveLiteratureContent:
+        raw_metadata = cast(object, metadata)
+        if (
+            not isinstance(raw_metadata, LiteratureMetadata)
+            or any(not isinstance(value, str) for value in cast(tuple[object, ...], raw_metadata.keywords or ()))
+            or any(not isinstance(value, str) for value in cast(tuple[object, ...], raw_metadata.references or ()))
+            or (
+                raw_metadata.citation is not None
+                and (
+                    not isinstance(cast(object, raw_metadata.citation), LiteratureCitation)
+                    or isinstance(raw_metadata.citation.year, bool)
+                )
+            )
+        ):
+            raise MatelabUsageError("Literature metadata contains invalid canonical fields.")
+        try:
+            return WireSaveLiteratureContent.model_validate(
+                {
+                    "title": metadata.title,
+                    "journal": metadata.journal,
+                    "info": (
+                        {
+                            "year": metadata.citation.year,
+                            "volume": metadata.citation.volume,
+                            "issue": metadata.citation.issue,
+                            "page": metadata.citation.page,
+                        }
+                        if metadata.citation is not None
+                        else None
+                    ),
+                    "author": metadata.author,
+                    "keywords": list(metadata.keywords) if metadata.keywords is not None else None,
+                    "abstract": metadata.abstract,
+                    "doi": metadata.doi,
+                    "url": metadata.url,
+                    "reference": list(metadata.references) if metadata.references is not None else None,
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Literature metadata does not satisfy the Integration Contract.") from None
+
+    def _detail(self, item: LiteratureItemRef, response: WireLiteratureDetailResponse) -> LiteratureDetail:
+        return LiteratureDetail(
+            ref=item,
+            metadata=self._stored_metadata(response.content.root),
+            schema_fields=tuple(self._field(field) for field in response.template),
+            library_keywords=tuple(response.keywords),
+            item_keywords=tuple(response.keywords_item),
+            star=response.star,
+            comments=tuple(
+                LiteratureComment(
+                    ref=LiteratureCommentRef(item=item, comment_id=comment.id),
+                    content=comment.content,
+                    author=UserRef(userid=comment.userid),
+                    author_name=comment.user,
+                    created_at=comment.dtime,
+                    owned_by_caller=comment.owner,
+                )
+                for comment in response.comments
+            ),
+            pdf=LiteraturePdf(item=item, sha256=response.hash, filename=response.filename, size=response.size),
+            source=self._source(response.source),
+            permission_mask=response.power,
+            library_name=response.store_name,
+        )
+
+    @staticmethod
+    def _stored_metadata(
+        content: WireLiteratureContentObject | WireInvalidLiteratureContent,
+    ) -> LiteratureStoredMetadata:
+        if isinstance(content, WireInvalidLiteratureContent):
+            return LiteratureStoredMetadata(
+                valid_object=False,
+                title=None,
+                journal=None,
+                citation=None,
+                author=None,
+                authors=None,
+                keywords=None,
+                abstract=None,
+                reference_information=None,
+                doi=None,
+                url=None,
+                references=None,
+            )
+        extension_fields = cast(dict[str, object], dict(content.model_extra or {}))
+        dropped = set(extension_fields)
+        if content.authors is not None:
+            dropped.add("authors")
+        if content.reference_information is not None:
+            dropped.add("reference_information")
+        return LiteratureStoredMetadata(
+            valid_object=True,
+            title=content.title,
+            journal=content.journal,
+            citation=(
+                LiteratureCitation(
+                    year=content.info.year, volume=content.info.volume, issue=content.info.issue, page=content.info.page
+                )
+                if content.info is not None
+                else None
+            ),
+            author=content.author,
+            authors=tuple(content.authors) if content.authors is not None else None,
+            keywords=tuple(content.keywords) if content.keywords is not None else None,
+            abstract=content.abstract,
+            reference_information=content.reference_information,
+            doi=content.doi,
+            url=content.url,
+            references=tuple(content.reference) if content.reference is not None else None,
+            extension_fields=MappingProxyType(extension_fields),
+            fields_dropped_by_canonical_update=tuple(sorted(dropped)),
+        )
+
+    @staticmethod
+    def _metadata_matches(observed: LiteratureStoredMetadata, requested: LiteratureMetadata) -> bool:
+        return (
+            observed.valid_object
+            and observed.title == requested.title
+            and observed.journal == requested.journal
+            and observed.citation == requested.citation
+            and observed.author == requested.author
+            and (observed.keywords or ()) == (requested.keywords or ())
+            and (observed.abstract or "") == (requested.abstract or "")
+            and observed.doi == requested.doi
+            and observed.url == requested.url
+            and (observed.references or ()) == (requested.references or ())
+        )
+
+    def _render_comment(self, draft: LiteratureCommentDraft) -> tuple[str, UploadBindingRef]:
+        raw_draft = cast(object, draft)
+        if not isinstance(raw_draft, LiteratureCommentDraft) or not isinstance(cast(object, raw_draft.html), str):
+            raise MatelabUsageError("Literature comment draft is invalid.")
+        if raw_draft.attachment is None:
+            if _COMMENT_ATTACHMENT_MARKER in raw_draft.html or "url_eln/temp" in raw_draft.html:
+                raise MatelabUsageError("Temporary literature-comment URLs require a completed staged-file object.")
+            return raw_draft.html, UploadBindingRef.new()
+        self._validate_staged_file(raw_draft.attachment)
+        if raw_draft.html.count(_COMMENT_ATTACHMENT_MARKER) != 1 or "url_eln/temp" in raw_draft.html:
+            raise MatelabUsageError(
+                "A literature comment attachment requires exactly one matelab-staged-file marker and no raw temp URL."
+            )
+        return (
+            raw_draft.html.replace(_COMMENT_ATTACHMENT_MARKER, raw_draft.attachment.temporary_url),
+            raw_draft.attachment.binding,
+        )
+
+    @staticmethod
+    def _validate_staged_file(staged: StagedFile) -> None:
+        raw_staged = cast(object, staged)
+        if (
+            not isinstance(raw_staged, StagedFile)
+            or raw_staged.temporary_file_id < 1
+            or not raw_staged.binding.uid
+            or len(raw_staged.binding.uid) > 45
+            or not raw_staged.session.upload_session_id
+            or len(raw_staged.session.upload_session_id) > 45
+            or raw_staged.session.next_offset != raw_staged.size
+            or not raw_staged.filename
+            or "\r" in raw_staged.filename
+            or "\n" in raw_staged.filename
+            or raw_staged.size < 0
+            or _SHA256_PATTERN.fullmatch(raw_staged.sha256) is None
+            or not raw_staged.temporary_url
+            or raw_staged.completion != "provider_acknowledged_complete"
+            or raw_staged.binding_state != "staged_not_bound"
+        ):
+            raise MatelabUsageError("Completed staged-file metadata is invalid.")
+
+    @staticmethod
+    def _library(
+        item: WireLiteratureLibrary, *, kind: Literal["personal", "shared", "dangling_membership"]
+    ) -> LiteratureLibrarySummary:
+        if kind == "personal":
+            ref: LiteratureLibraryRef | None = PersonalLiteratureLibraryRef()
+        elif kind == "shared" and item.id is not None:
+            ref = SharedLiteratureLibraryRef(literature_library_id=item.id)
+        else:
+            ref = None
+        return LiteratureLibrarySummary(
+            ref=ref,
+            kind=kind,
+            name=item.showtext,
+            permission_mask=item.power,
+            item_count=item.num,
+            keywords=tuple(item.keywords),
+            introduction=item.intro,
+        )
+
+    @staticmethod
+    def _summary(item: WireLiteratureListItem, library: LiteratureLibraryRef) -> LiteratureItemSummary:
+        if isinstance(library, PersonalLiteratureLibraryRef):
+            ref: LiteratureItemRef = PersonalLiteratureItemRef(literature_item_id=item.id)
+        else:
+            ref = SharedLiteratureItemRef(literature_item_id=item.id, library=library)
+        pdf = LiteraturePdf(item=ref, sha256=item.hash or None, filename=item.filename or None, size=None)
+        return LiteratureItemSummary(
+            ref=ref,
+            source=Literature._source(item.source),
+            star=item.star,
+            title=item.title,
+            author=item.author,
+            citation_html=item.info,
+            abstract=item.abstract,
+            journal=item.journal,
+            keywords=tuple(item.keywords),
+            publication_date=item.dtime,
+            matching_author_fragments=tuple(item.authors_bold),
+            pdf=pdf,
+        )
+
+    @staticmethod
+    def _field(item: WireLiteratureFieldDefinition) -> LiteratureField:
+        label: str | tuple[str, str]
+        if isinstance(item.name, str):
+            label = item.name
+        else:
+            label = cast(tuple[str, str], tuple(item.name.root))
+        if isinstance(item.comm, str) or item.comm is None:
+            help_text: str | tuple[str, str] | None = item.comm
+        else:
+            help_text = cast(tuple[str, str], tuple(item.comm.root))
+        nested = tuple(
+            LiteratureNestedField(
+                field_id=child.id,
+                field_type=child.type.value,
+                label=(child.name if isinstance(child.name, str) else cast(tuple[str, str], tuple(child.name.root))),
+                width=child.width,
+                attributes=MappingProxyType(cast(dict[str, object], dict(child.model_extra or {}))),
+            )
+            for child in item.template or ()
+        )
+        return LiteratureField(
+            field_id=item.id,
+            field_type=item.type.value,
+            label=label,
+            required=item.required,
+            group=item.group,
+            help_text=help_text,
+            print_template=item.print,
+            nested=nested,
+            visible=item.show,
+            width=item.width,
+            condition=(
+                MappingProxyType(cast(dict[str, object], item.condition.model_dump(mode="json")))
+                if item.condition is not None
+                else None
+            ),
+            attributes=MappingProxyType(cast(dict[str, object], dict(item.model_extra or {}))),
+        )
+
+    @staticmethod
+    def _extracted_author(item: WireExtractedLiteratureAuthor) -> ExtractedLiteratureAuthor:
+        return ExtractedLiteratureAuthor(
+            name=item.name,
+            affiliations=tuple(item.affiliation) if item.affiliation is not None else None,
+            email=item.email,
+            corresponding=item.is_corresponding,
+            orcid=item.orcid,
+            extension_fields=MappingProxyType(cast(dict[str, object], dict(item.model_extra or {}))),
+        )
+
+    @staticmethod
+    def _source(value: object) -> LiteratureSource:
+        source = int(cast(int, value))
+        mapping = {1: LiteratureSource.SUBSCRIBED, 2: LiteratureSource.USER_CREATED, 3: LiteratureSource.SHARED_COPY}
+        try:
+            return mapping[source]
+        except KeyError:
+            raise MatelabProtocolError("Matelab returned an unknown literature source.") from None
+
+    @staticmethod
+    def _source_wire_value(value: LiteratureSource) -> int:
+        try:
+            source = LiteratureSource(value)
+        except (TypeError, ValueError):
+            raise MatelabUsageError("Literature source filter is invalid.") from None
+        return {LiteratureSource.SUBSCRIBED: 1, LiteratureSource.USER_CREATED: 2, LiteratureSource.SHARED_COPY: 3}[
+            source
+        ]
+
+    @staticmethod
+    def _library_id(library: LiteratureLibraryRef) -> int:
+        raw_library = cast(object, library)
+        if isinstance(raw_library, PersonalLiteratureLibraryRef):
+            return 0
+        if (
+            isinstance(raw_library, SharedLiteratureLibraryRef)
+            and type(raw_library.literature_library_id) is int
+            and raw_library.literature_library_id >= 1
+        ):
+            return raw_library.literature_library_id
+        raise MatelabUsageError("Literature library identity is invalid.")
+
+    @staticmethod
+    def _item_id(item: LiteratureItemRef | None) -> int:
+        if isinstance(item, (PersonalLiteratureItemRef, SharedLiteratureItemRef)):
+            value = item.literature_item_id
+            if type(value) is int and value >= 1:
+                if isinstance(item, SharedLiteratureItemRef):
+                    _ = Literature._library_id(item.library)
+                return value
+        raise MatelabUsageError("Literature item identity is invalid.")