unique-sdk 2026.20.0.dev2__tar.gz → 2026.20.0.dev4__tar.gz

{unique_sdk-2026.20.0.dev2 → unique_sdk-2026.20.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.20.0.dev2
+Version: 2026.20.0.dev4
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.20.0.dev2 → unique_sdk-2026.20.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.20.0.dev2"
+version = "2026.20.0.dev4"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.20.0.dev2 → unique_sdk-2026.20.0.dev4}/unique_sdk/api_resources/_content.py

@@ -31,6 +31,16 @@ class Content(APIResource["Content"]):
     expiredAt: str | None
     appliedIngestionConfig: dict[str, Any] | None
     mimeType: str | None
+    # Optional preview PDF blob registered against this content. When the
+    # caller passes ``previewPdfFileName`` to :meth:`upsert` (or to
+    # :func:`unique_sdk.utils.file_io.upload_file` via ``preview_pdf_path``),
+    # the platform stores the filename here and returns
+    # ``pdfPreviewWriteUrl`` so the PDF bytes can be uploaded directly to
+    # blob storage. The chat side panel resolves this filename to the
+    # ``/v1/content/{id}/preview-file`` endpoint when rendering Office /
+    # other formats whose in-browser preview is unreliable.
+    previewPdfFileName: str | None
+    pdfPreviewWriteUrl: str | None
 
     class QueryMode(Enum):
         Default = "default"
@@ -155,6 +165,11 @@ class Content(APIResource["Content"]):
         sourceOwnerType: NotRequired[str | None]
         storeInternally: NotRequired[bool | None]
         fileUrl: NotRequired[str | None]
+        # Pass a blob filename to attach a PDF preview to the upserted
+        # content. The response then carries ``pdfPreviewWriteUrl`` —
+        # a SAS URL the caller PUTs the PDF bytes to. ``file_io.upload_file``
+        # exposes this as ``preview_pdf_path`` for a one-call flow.
+        previewPdfFileName: NotRequired[str | None]
 
     class UpdateParams(RequestOptions):
         contentId: NotRequired[str]

{unique_sdk-2026.20.0.dev2 → unique_sdk-2026.20.0.dev4}/unique_sdk/utils/file_io.py

@@ -2,7 +2,7 @@ import asyncio
 import os
 import tempfile
 from pathlib import Path
-from typing import Any
+from typing import Any, TypedDict
 
 import requests
 
@@ -10,6 +10,15 @@ import unique_sdk
 from unique_sdk.api_resources._content import Content
 
 
+class _PreviewKwargs(TypedDict, total=False):
+    """Subset of ``Content.UpsertParams`` that we conditionally forward
+    to ``upsert``. Typing it as a ``total=False`` TypedDict lets us
+    expand ``**preview_kwargs`` without basedpyright assuming the dict
+    could collide with non-string params like ``headers``."""
+
+    previewPdfFileName: str
+
+
 # download readUrl a random directory in /tmp
 def download_file(url: str, filename: str):
     # Guard for callers without a type checker: fail fast with a clear error before reaching requests.
@@ -32,6 +41,38 @@ def download_file(url: str, filename: str):
     return file_path
 
 
+_PREVIEW_PDF_MIME_TYPE = "application/pdf"
+
+
+def _derive_preview_pdf_filename(displayed_filename: str) -> str:
+    """Return ``<stem>_preview.pdf`` for *displayed_filename*.
+
+    Keeps the preview blob filename predictable and collision-free with
+    the original (which has the user-visible extension), while still
+    making it obvious in storage which content the preview belongs to.
+    """
+    stem = displayed_filename.rsplit(".", 1)[0] or displayed_filename
+    return f"{stem}_preview.pdf"
+
+
+def _put_preview_pdf(write_url: str, preview_pdf_path: str) -> None:
+    """PUT *preview_pdf_path* bytes to the SAS URL returned by upsert."""
+    with open(preview_pdf_path, "rb") as preview_file:
+        response = requests.put(
+            write_url,
+            data=preview_file,
+            headers={
+                "X-Ms-Blob-Content-Type": _PREVIEW_PDF_MIME_TYPE,
+                "X-Ms-Blob-Type": "BlockBlob",
+            },
+        )
+    if response.status_code >= 400:
+        raise RuntimeError(
+            f"Preview PDF upload failed with status {response.status_code}: "
+            f"{response.text[:500]}"
+        )
+
+
 def upload_file(
     userId,
     companyId,
@@ -43,12 +84,77 @@ def upload_file(
     chat_id=None,
     ingestion_config: Content.IngestionConfig | None = None,
     metadata: dict[str, Any] | None = None,
+    preview_pdf_path: str | None = None,
+    preview_pdf_filename: str | None = None,
 ):
+    """Upload *path_to_file* as a Unique :class:`Content`.
+
+    When ``preview_pdf_path`` is provided, the caller gets a single-call
+    Office → PDF preview flow: we attach a ``previewPdfFileName`` to the
+    upserted content (so the platform mints a ``pdfPreviewWriteUrl``),
+    PUT the original blob, then PUT the PDF preview blob. The chat side
+    panel will pick the preview up automatically when rendering
+    PowerPoint / Word / similar formats whose in-browser preview is
+    unreliable.
+
+    Args:
+        userId: Acting user id.
+        companyId: Tenant id.
+        path_to_file: Path to the original blob to upload.
+        displayed_filename: Human-readable filename. Used as the content
+            ``key`` and ``title``.
+        mime_type: MIME type of the original blob.
+        description: Optional description.
+        scope_or_unique_path: Either a scope id, a folder path, or
+            ``None`` (when uploading into a chat).
+        chat_id: Chat id when uploading a chat attachment.
+        ingestion_config: Ingestion options.
+        metadata: Free-form metadata.
+        preview_pdf_path: Optional path to a sibling PDF that should be
+            rendered as the side-panel preview for this content. When
+            set, the upsert registers ``previewPdfFileName`` on the row
+            and the PDF bytes are PUT to ``pdfPreviewWriteUrl`` after the
+            original upload.
+        preview_pdf_filename: Optional override for the blob filename
+            stored against ``previewPdfFileName``. Defaults to
+            ``<displayed_filename without extension>_preview.pdf`` so
+            the preview blob is uniquely identifiable in storage.
+    """
     # check that chatid or scope_or_unique_path is provided
     if not chat_id and not scope_or_unique_path:
         raise ValueError("chat_id or scope_or_unique_path must be provided")
 
+    if preview_pdf_path is not None and not os.path.isfile(preview_pdf_path):
+        raise ValueError(
+            f"preview_pdf_path does not point to a readable file: {preview_pdf_path}"
+        )
+
+    # A filename without a path would register a phantom preview on the
+    # Content row (the upsert mints a pdfPreviewWriteUrl, but we never
+    # PUT any bytes), leaving the side panel pointing at a nonexistent
+    # blob. Treat it as a programmer mistake and fail fast.
+    if preview_pdf_filename is not None and preview_pdf_path is None:
+        raise ValueError(
+            "preview_pdf_filename was provided without preview_pdf_path; "
+            "pass the PDF path so the preview blob actually gets uploaded."
+        )
+
     size = os.path.getsize(path_to_file)
+    resolved_preview_filename = (
+        (preview_pdf_filename or _derive_preview_pdf_filename(displayed_filename))
+        if preview_pdf_path is not None
+        else None
+    )
+    # Only forward ``previewPdfFileName`` when we actually have one.
+    # Sending ``None`` would serialize as ``"previewPdfFileName": null``,
+    # which the server treats as a clearing operation and would erase
+    # an existing preview on a re-upload that doesn't ship one.
+    preview_kwargs: _PreviewKwargs = (
+        {"previewPdfFileName": resolved_preview_filename}
+        if resolved_preview_filename is not None
+        else {}
+    )
+
     createdContent = Content.upsert(
         user_id=userId,
         company_id=companyId,
@@ -62,6 +168,7 @@ def upload_file(
         },
         scopeId=scope_or_unique_path,
         chatId=chat_id,
+        **preview_kwargs,
     )
 
     uploadUrl = createdContent.writeUrl
@@ -79,6 +186,26 @@ def upload_file(
             },
         )
 
+    # Attach the optional preview-PDF blob in the same call. We do this
+    # *before* the second upsert so the byteSize patch and the preview
+    # don't race; if the SAS URL is missing we surface a clear error
+    # (the server only mints it when previewPdfFileName is set, so a
+    # missing URL signals a server-side regression).
+    if preview_pdf_path is not None:
+        # ``getattr`` so an older gateway that omits the field falls
+        # through to the RuntimeError below instead of raising the
+        # opaque ``AttributeError`` that ``UniqueObject.__getattr__``
+        # produces on a missing key.
+        preview_write_url = getattr(createdContent, "pdfPreviewWriteUrl", None)
+        if not preview_write_url:
+            raise RuntimeError(
+                "preview_pdf_path was provided but the upsert response carries "
+                "no pdfPreviewWriteUrl — refusing to silently drop the preview. "
+                "Verify the API gateway and node-ingestion expose "
+                "previewPdfFileName on the upsert mutation."
+            )
+        _put_preview_pdf(preview_write_url, preview_pdf_path)
+
     if chat_id:
         unique_sdk.Content.upsert(
             user_id=userId,
@@ -94,6 +221,7 @@ def upload_file(
             },
             fileUrl=createdContent.readUrl,
             chatId=chat_id,
+            **preview_kwargs,
         )
     else:
         unique_sdk.Content.upsert(
@@ -110,6 +238,7 @@ def upload_file(
             },
             fileUrl=createdContent.readUrl,
             scopeId=scope_or_unique_path,
+            **preview_kwargs,
         )
 
     return createdContent