unique-sdk 2026.26.0.dev8__tar.gz → 2026.26.0.dev10__tar.gz

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.26.0.dev8
+Version: 2026.26.0.dev10
 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.26.0.dev8 → unique_sdk-2026.26.0.dev10}/pyproject.toml

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

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev10}/unique_sdk/api_resources/_content.py

@@ -170,6 +170,50 @@ class Content(APIResource["Content"]):
         # 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]
+        # When true, the platform archives previous blobs for this
+        # content and makes them restorable through the version APIs.
+        versioningEnabled: NotRequired[bool | None]
+
+    class VersionsParams(RequestOptions):
+        contentId: str
+        skip: NotRequired[int | None]
+        take: NotRequired[int | None]
+
+    class ContentVersion(TypedDict):
+        id: str
+        contentId: str
+        versionNumber: int
+        reason: str
+        blobObjectKey: str
+        key: str
+        title: str | None
+        description: str | None
+        url: str | None
+        byteSize: int
+        mimeType: str
+        ownerType: str
+        ownerId: str
+        contentHash: str | None
+        archivedAt: str
+        archivedBy: str | None
+        originalCreatedAt: str
+        originalCreatedBy: str | None
+        createdBy: str | None
+
+    class PaginatedContentVersions(TypedDict):
+        data: list["Content.ContentVersion"]
+        object: str
+
+    class VersionDownloadUrlParams(RequestOptions):
+        contentVersionId: str
+
+    class ContentVersionDownloadUrl(TypedDict):
+        id: str
+        object: str
+        url: str
+
+    class RestoreVersionParams(RequestOptions):
+        contentVersionId: str
 
     class UpdateParams(RequestOptions):
         contentId: NotRequired[str]
@@ -467,6 +511,120 @@ class Content(APIResource["Content"]):
             ),
         )
 
+    @classmethod
+    def versions(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionsParams"],
+    ) -> "Content.PaginatedContentVersions":
+        content_id = params.pop("contentId")
+        return cast(
+            Content.PaginatedContentVersions,
+            cls._static_request(
+                "get",
+                f"/content/{content_id}/versions",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def versions_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionsParams"],
+    ) -> "Content.PaginatedContentVersions":
+        content_id = params.pop("contentId")
+        return cast(
+            Content.PaginatedContentVersions,
+            await cls._static_request_async(
+                "get",
+                f"/content/{content_id}/versions",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    def version_download_url(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionDownloadUrlParams"],
+    ) -> "Content.ContentVersionDownloadUrl":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentVersionDownloadUrl,
+            cls._static_request(
+                "get",
+                f"/content/versions/{content_version_id}/download-url",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def version_download_url_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.VersionDownloadUrlParams"],
+    ) -> "Content.ContentVersionDownloadUrl":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentVersionDownloadUrl,
+            await cls._static_request_async(
+                "get",
+                f"/content/versions/{content_version_id}/download-url",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    def restore_version(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.RestoreVersionParams"],
+    ) -> "Content.ContentInfo":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentInfo,
+            cls._static_request(
+                "post",
+                f"/content/versions/{content_version_id}/restore",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def restore_version_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Content.RestoreVersionParams"],
+    ) -> "Content.ContentInfo":
+        content_version_id = params.pop("contentVersionId")
+        return cast(
+            Content.ContentInfo,
+            await cls._static_request_async(
+                "post",
+                f"/content/versions/{content_version_id}/restore",
+                user_id,
+                company_id,
+                params=params,
+            ),
+        )
+
     @classmethod
     def ingest_magic_table_sheets(
         cls,

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev10}/unique_sdk/cli/cli.py

@@ -20,7 +20,14 @@ from unique_sdk.cli.commands.elicitation import (
     cmd_elicit_respond,
     cmd_elicit_wait,
 )
-from unique_sdk.cli.commands.files import cmd_download, cmd_mv_file, cmd_rm, cmd_upload
+from unique_sdk.cli.commands.files import (
+    cmd_download,
+    cmd_mv_file,
+    cmd_restore_version,
+    cmd_rm,
+    cmd_upload,
+    cmd_versions,
+)
 from unique_sdk.cli.commands.folders import cmd_mkdir, cmd_mvdir, cmd_rmdir
 from unique_sdk.cli.commands.mcp import cmd_mcp
 from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
@@ -91,6 +98,7 @@ Path formats accepted by all commands:
 \b
 File identifiers:
   report.pdf          File name (matched in current directory)
+  /Reports/report.pdf File path (absolute or relative)
   cont_abc123         Content ID (used directly)
 
 \b
@@ -99,8 +107,10 @@ Examples:
   unique-cli ls                     List root folders
   unique-cli ls /Reports            List a specific folder
   unique-cli search "revenue" -l 50 Search with custom limit
-  unique-cli upload ./file.pdf      Upload to current folder
+  unique-cli upload ./file.pdf      Upload versioned to current folder
   unique-cli download cont_abc123   Download by content ID
+  unique-cli versions cont_abc123   List archived file versions
+  unique-cli restore-version cver_1 Restore a file from a version
   unique-cli elicit ask "Which?"    Ask the user a question synchronously
   unique-cli subagent Legal "Review" Invoke a connected space/subagent
   unique-cli web-search search "x"  Search the web via the public API
@@ -261,12 +271,13 @@ def mvdir(ctx: click.Context, old_name: str, new_name: str) -> None:
 @click.argument("destination", required=False, default=None)
 @click.pass_context
 def upload(ctx: click.Context, local_path: str, destination: str | None) -> None:
-    """Upload a local file (works like Linux cp).
+    """Upload a local file with versioning enabled (works like Linux cp).
 
     \b
-    Uploads LOCAL_PATH to the Unique platform. DESTINATION works like
-    the target in cp -- it can be a folder path, a new filename, or
-    a combination of both. MIME type is auto-detected.
+    Uploads LOCAL_PATH to the Unique platform with immutable versioning
+    enabled. DESTINATION works like the target in cp -- it can be a
+    folder path, a new filename, or a combination of both. MIME type is
+    auto-detected.
 
     \b
     Destination formats:
@@ -288,6 +299,48 @@ def upload(ctx: click.Context, local_path: str, destination: str | None) -> None
     click.echo(cmd_upload(LazyState.get(ctx), local_path, destination))
 
 
+@main.command()
+@click.argument("name_or_id")
+@click.option("--skip", type=int, default=None, help="Number of versions to skip.")
+@click.option("--take", type=int, default=None, help="Number of versions to return.")
+@click.pass_context
+def versions(
+    ctx: click.Context,
+    name_or_id: str,
+    skip: int | None,
+    take: int | None,
+) -> None:
+    """List archived versions for a file.
+
+    \b
+    NAME_OR_ID is a file path, a file name matched in the current
+    directory, or a content ID (cont_...) which is resolved directly.
+
+    \b
+    Examples:
+      unique-cli versions report.pdf
+      unique-cli versions /Reports/Q1/report.pdf
+      unique-cli versions cont_abc123 --take 10
+    """
+    click.echo(cmd_versions(LazyState.get(ctx), name_or_id, skip=skip, take=take))
+
+
+@main.command(name="restore-version")
+@click.argument("content_version_id")
+@click.pass_context
+def restore_version(ctx: click.Context, content_version_id: str) -> None:
+    """Restore a file from a content version ID.
+
+    \b
+    CONTENT_VERSION_ID is returned by `unique-cli versions`.
+
+    \b
+    Examples:
+      unique-cli restore-version cver_abc123
+    """
+    click.echo(cmd_restore_version(LazyState.get(ctx), content_version_id))
+
+
 @main.command()
 @click.argument("name_or_id")
 @click.argument("local_dest", required=False, default=None)
@@ -296,8 +349,8 @@ def download(ctx: click.Context, name_or_id: str, local_dest: str | None) -> Non
     """Download a file to your local machine.
 
     \b
-    NAME_OR_ID is a file name (matched in the current directory) or
-    a content ID (cont_...) which is resolved directly.
+    NAME_OR_ID is a file path, a file name matched in the current
+    directory, or a content ID (cont_...) which is resolved directly.
 
     \b
     LOCAL_DEST is an optional path (directory or file) to save to.
@@ -306,6 +359,7 @@ def download(ctx: click.Context, name_or_id: str, local_dest: str | None) -> Non
     \b
     Examples:
       unique-cli download annual.pdf
+      unique-cli download /Reports/Q1/annual.pdf
       unique-cli download annual.pdf ./downloads/
       unique-cli download cont_abc123 ~/Desktop/
     """
@@ -331,10 +385,12 @@ def cite(
     \b
     Registers [filesourceN] markers for pages you referenced in your answer.
     Does NOT read or extract the file — use your own tools for that.
+    NAME_OR_ID can be a file path, current-directory file name, or content ID.
 
     \b
     Examples:
       unique-cli cite report.pdf --pages 3,5,7
+      unique-cli cite /Reports/Q1/report.pdf --pages 3,5,7
       unique-cli cite cont_abc123 --pages 1-4
     """
     click.echo(cmd_cite_file(LazyState.get(ctx), name_or_id, pages))
@@ -342,9 +398,41 @@ def cite(
 
 @main.command(name="read")
 @click.argument("cont_id")
+@click.option(
+    "--page",
+    "-p",
+    type=int,
+    default=None,
+    help="Read a single page (shorthand for --from-page N --to-page N).",
+)
+@click.option(
+    "--from-page",
+    type=int,
+    default=None,
+    help="First page to include (inclusive).",
+)
+@click.option(
+    "--to-page",
+    type=int,
+    default=None,
+    help="Last page to include (inclusive).",
+)
+@click.option(
+    "--max-chars",
+    type=int,
+    default=None,
+    help="Truncate the printed text to at most N characters.",
+)
 @click.pass_context
-def read_cmd(ctx: click.Context, cont_id: str) -> None:
-    """Read all indexed text chunks for a known content ID.
+def read_cmd(
+    ctx: click.Context,
+    cont_id: str,
+    page: int | None,
+    from_page: int | None,
+    to_page: int | None,
+    max_chars: int | None,
+) -> None:
+    """Read indexed text chunks for a known content ID.
 
     \b
     CONT_ID must be a content ID (cont_...) obtained from a prior `ls` or
@@ -355,11 +443,34 @@ def read_cmd(ctx: click.Context, cont_id: str) -> None:
     Use `search` when you need to find documents by topic or keyword.
     Use `read` when you already know the content ID and want the full text.
 
+    \b
+    Restrict to a page range with --page (single page) or --from-page/--to-page.
+    A chunk spanning pages 2-4 is returned for any overlapping request; files
+    without page numbers (e.g. plain text/markdown) are returned only without a
+    page range.
+
     \b
     Examples:
       unique-cli read cont_abc123
+      unique-cli read cont_abc123 --page 12
+      unique-cli read cont_abc123 --from-page 5 --to-page 9
+      unique-cli read cont_abc123 --to-page 3 --max-chars 8000
     """
-    output = cmd_read(LazyState.get(ctx), cont_id)
+    if page is not None and (from_page is not None or to_page is not None):
+        click.echo(
+            "read: use either --page or --from-page/--to-page, not both", err=True
+        )
+        raise SystemExit(1)
+    if page is not None:
+        from_page = page
+        to_page = page
+    output = cmd_read(
+        LazyState.get(ctx),
+        cont_id,
+        from_page=from_page,
+        to_page=to_page,
+        max_chars=max_chars,
+    )
     if _is_read_error_output(output):
         click.echo(output, err=True)
         raise SystemExit(1)
@@ -442,15 +553,16 @@ def dynamic_frontend_list(ctx: click.Context, output_json: bool) -> None:
 @click.argument("name_or_id")
 @click.pass_context
 def rm(ctx: click.Context, name_or_id: str) -> None:
-    """Delete a file by name or content ID.
+    """Delete a file by path, name, or content ID.
 
     \b
-    NAME_OR_ID is a file name (matched in the current directory) or
-    a content ID (cont_...).
+    NAME_OR_ID is a file path, a file name matched in the current
+    directory, or a content ID (cont_...).
 
     \b
     Examples:
       unique-cli rm report.pdf
+      unique-cli rm /Reports/Q1/report.pdf
       unique-cli rm cont_abc123
     """
     click.echo(cmd_rm(LazyState.get(ctx), name_or_id))
@@ -465,11 +577,12 @@ def mv(ctx: click.Context, old_name: str, new_name: str) -> None:
 
     \b
     Changes the file's display title without changing its content ID
-    or location. OLD_NAME can be a file name or content ID.
+    or location. OLD_NAME can be a file path, file name, or content ID.
 
     \b
     Examples:
       unique-cli mv annual.pdf annual-2025.pdf
+      unique-cli mv /Reports/Q1/annual.pdf annual-2025.pdf
       unique-cli mv cont_abc123 "New Title.pdf"
     """
     click.echo(cmd_mv_file(LazyState.get(ctx), old_name, new_name))

{unique_sdk-2026.26.0.dev8 → unique_sdk-2026.26.0.dev10}/unique_sdk/cli/commands/files.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import mimetypes
 import shutil
+from collections.abc import Mapping, Sequence
 from pathlib import Path
 from typing import Any
 
@@ -13,32 +14,113 @@ from unique_sdk.cli.state import ShellState
 from unique_sdk.utils.file_io import download_content, upload_file
 
 
+def _normalize_unique_file_path(cwd: str, path: str) -> str:
+    """Normalize a Unique file path without allowing traversal above root."""
+    raw_parts = (
+        path.split("/") if path.startswith("/") else [*cwd.split("/"), *path.split("/")]
+    )
+    parts: list[str] = []
+    for part in raw_parts:
+        if part in ("", "."):
+            continue
+        if part == "..":
+            if not parts:
+                raise ValueError(f"File path escapes root: {path}")
+            parts.pop()
+            continue
+        parts.append(part)
+    return "/" + "/".join(parts)
+
+
 def _resolve_content_id(state: ShellState, name_or_id: str) -> tuple[str, str]:
     """Resolve a file name or content ID to (content_id, display_name).
 
-    Accepts either a content ID (cont_...) or a file name/path.
+    Accepts a content ID (cont_...), a file name in the current folder,
+    or an absolute/relative Unique file path.
     """
     if name_or_id.startswith("cont_"):
+        if not state.is_content_within_workspace(name_or_id):
+            raise ValueError("permission denied (outside workspace scope)")
         return name_or_id, name_or_id
 
+    lookup_name = name_or_id
     scope_id = state.scope_id
+    if "/" in name_or_id:
+        unique_path = _normalize_unique_file_path(state.cwd, name_or_id)
+        folder_path, lookup_name = unique_path.rsplit("/", 1)
+        if not lookup_name:
+            raise ValueError(f"File path must include a file name: {name_or_id}")
+        if not folder_path:
+            folder_path = "/"
+        if not state.is_folder_target_within_workspace(folder_path):
+            raise ValueError("permission denied (outside workspace scope)")
+
+        info = unique_sdk.Folder.get_info(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            folderPath=folder_path,
+        )
+        scope_id = info.get("id")
+        if not scope_id:
+            raise ValueError(f"folder not found: {folder_path}")
+    elif not state.is_within_workspace():
+        raise ValueError("permission denied (outside workspace scope)")
+
     params: dict[str, Any] = {}
     if scope_id:
         params["parentId"] = scope_id
 
-    result = unique_sdk.Content.get_infos(
-        user_id=state.config.user_id,
-        company_id=state.config.company_id,
-        **params,
-    )
-    for info in result.get("contentInfos", []):
-        title = info.get("title") or info.get("key") or ""
-        if title == name_or_id:
-            return info["id"], title
+    take = 100
+    skip = 0
+    while True:
+        result = unique_sdk.Content.get_infos(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            skip=skip,
+            take=take,
+            **params,
+        )
+        content_infos = result.get("contentInfos", [])
+        if not content_infos:
+            break
+
+        for info in content_infos:
+            title = info.get("title") or ""
+            key = info.get("key") or ""
+            if lookup_name in {title, key}:
+                return info["id"], title or key
+
+        skip += len(content_infos)
 
     raise ValueError(f"File not found: {name_or_id}")
 
 
+def _format_version_value(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _format_content_versions(versions: Sequence[Mapping[str, Any]]) -> str:
+    if not versions:
+        return "No versions found."
+
+    lines = ["VERSION  VERSION_ID  ARCHIVED_AT  REASON  TITLE"]
+    for version in versions:
+        lines.append(
+            "  ".join(
+                [
+                    _format_version_value(version.get("versionNumber")),
+                    _format_version_value(version.get("id")),
+                    _format_version_value(version.get("archivedAt")),
+                    _format_version_value(version.get("reason")),
+                    _format_version_value(version.get("title") or version.get("key")),
+                ]
+            )
+        )
+    return "\n".join(lines)
+
+
 def _resolve_upload_destination(
     state: ShellState,
     local_filename: str,
@@ -144,6 +226,7 @@ def cmd_upload(
             displayed_filename=display_name,
             mime_type=mime_type,
             scope_or_unique_path=scope_id,
+            versioning_enabled=True,
         )
 
         content_id = result.id if hasattr(result, "id") else "?"
@@ -158,6 +241,49 @@ def cmd_upload(
         return f"upload: {e}"
 
 
+def cmd_versions(
+    state: ShellState,
+    name_or_id: str,
+    skip: int | None = None,
+    take: int | None = None,
+) -> str:
+    """List archived versions for a file by name or content ID."""
+    try:
+        content_id, display_name = _resolve_content_id(state, name_or_id)
+        params: dict[str, Any] = {"contentId": content_id}
+        if skip is not None:
+            params["skip"] = skip
+        if take is not None:
+            params["take"] = take
+
+        result = unique_sdk.Content.versions(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            **params,
+        )
+        data = result.get("data", [])
+        return f"Versions for {display_name} ({content_id}):\n{_format_content_versions(data)}"
+    except (ValueError, unique_sdk.APIError) as e:
+        return f"versions: {e}"
+
+
+def cmd_restore_version(state: ShellState, content_version_id: str) -> str:
+    """Restore a file from an archived content version ID."""
+    if not state.is_within_workspace():
+        return "restore-version: permission denied (outside workspace scope)"
+    try:
+        result = unique_sdk.Content.restore_version(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            contentVersionId=content_version_id,
+        )
+        title = result.get("title") or result.get("key") or result.get("id", "?")
+        content_id = result.get("id", "?")
+        return f"Restored: {title} ({content_id}) from version {content_version_id}"
+    except (ValueError, unique_sdk.APIError) as e:
+        return f"restore-version: {e}"
+
+
 def cmd_download(
     state: ShellState,
     name_or_id: str,