pierre-storage 0.10.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

pierre_storage/__init__.py

@@ -27,8 +27,12 @@ from pierre_storage.types import (
     ListBranchesResult,
     ListCommitsResult,
     ListFilesResult,
+    ListReposResult,
+    NoteReadResult,
+    NoteWriteResult,
     RefUpdate,
     Repo,
+    RepoInfo,
     RestoreCommitResult,
 )
 from pierre_storage.version import PACKAGE_VERSION
@@ -71,7 +75,11 @@ __all__ = [
     "ListBranchesResult",
     "ListCommitsResult",
     "ListFilesResult",
+    "ListReposResult",
+    "NoteReadResult",
+    "NoteWriteResult",
     "RefUpdate",
+    "RepoInfo",
     "Repo",
     "RestoreCommitResult",
     # Webhook

pierre_storage/client.py

@@ -2,6 +2,7 @@
 
 import uuid
 from typing import Any, Dict, Optional
+from urllib.parse import urlencode
 
 import httpx
 
@@ -11,7 +12,9 @@ from pierre_storage.repo import DEFAULT_TOKEN_TTL_SECONDS, RepoImpl
 from pierre_storage.types import (
     DeleteRepoResult,
     GitStorageOptions,
+    ListReposResult,
     Repo,
+    RepoInfo,
 )
 from pierre_storage.version import get_user_agent
 
@@ -178,6 +181,66 @@ class GitStorage:
             self._generate_jwt,
         )
 
+    async def list_repos(
+        self,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        ttl: Optional[int] = None,
+    ) -> ListReposResult:
+        """List repositories for the organization."""
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self._generate_jwt(
+            "org",
+            {"permissions": ["org:read"], "ttl": ttl},
+        )
+
+        params: Dict[str, str] = {}
+        if cursor:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        url = f"{self.options['api_base_url']}/api/v{self.options['api_version']}/repos"
+        if params:
+            url += f"?{urlencode(params)}"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                timeout=30.0,
+            )
+
+            if not response.is_success:
+                raise ApiError(
+                    f"Failed to list repositories: {response.status_code} {response.reason_phrase}",
+                    status_code=response.status_code,
+                    response=response,
+                )
+
+            data = response.json()
+            repos: list[RepoInfo] = []
+            for repo in data.get("repos", []):
+                entry: RepoInfo = {
+                    "repo_id": repo.get("repo_id", ""),
+                    "url": repo.get("url", ""),
+                    "default_branch": repo.get("default_branch", "main"),
+                    "created_at": repo.get("created_at", ""),
+                }
+                if repo.get("base_repo"):
+                    entry["base_repo"] = repo.get("base_repo")
+                repos.append(entry)
+
+            return {
+                "repos": repos,
+                "next_cursor": data.get("next_cursor"),
+                "has_more": data.get("has_more", False),
+            }
+
     async def find_one(self, *, id: str) -> Optional[Repo]:
         """Find a repository by ID.
 

pierre_storage/repo.py

@@ -33,6 +33,8 @@ from pierre_storage.types import (
     ListBranchesResult,
     ListCommitsResult,
     ListFilesResult,
+    NoteReadResult,
+    NoteWriteResult,
     RefUpdate,
     RestoreCommitResult,
 )
@@ -498,6 +500,122 @@ class RepoImpl:
                 "has_more": data["has_more"],
             }
 
+    async def get_note(
+        self,
+        *,
+        sha: str,
+        ttl: Optional[int] = None,
+    ) -> NoteReadResult:
+        """Read a git note."""
+        sha_clean = sha.strip()
+        if not sha_clean:
+            raise ValueError("get_note sha is required")
+
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self.generate_jwt(self._id, {"permissions": ["git:read"], "ttl": ttl})
+
+        url = f"{self.api_base_url}/api/v{self.api_version}/repos/notes?{urlencode({'sha': sha_clean})}"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            return {
+                "sha": data["sha"],
+                "note": data["note"],
+                "ref_sha": data["ref_sha"],
+            }
+
+    async def create_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional[CommitSignature] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Create a git note."""
+        return await self._write_note(
+            action_label="create_note",
+            action="add",
+            sha=sha,
+            note=note,
+            expected_ref_sha=expected_ref_sha,
+            author=author,
+            ttl=ttl,
+        )
+
+    async def append_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional[CommitSignature] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Append to a git note."""
+        return await self._write_note(
+            action_label="append_note",
+            action="append",
+            sha=sha,
+            note=note,
+            expected_ref_sha=expected_ref_sha,
+            author=author,
+            ttl=ttl,
+        )
+
+    async def delete_note(
+        self,
+        *,
+        sha: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional[CommitSignature] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Delete a git note."""
+        sha_clean = sha.strip()
+        if not sha_clean:
+            raise ValueError("delete_note sha is required")
+
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self.generate_jwt(self._id, {"permissions": ["git:write"], "ttl": ttl})
+
+        payload: Dict[str, Any] = {"sha": sha_clean}
+        if expected_ref_sha and expected_ref_sha.strip():
+            payload["expected_ref_sha"] = expected_ref_sha.strip()
+        if author:
+            author_name = author.get("name", "").strip()
+            author_email = author.get("email", "").strip()
+            if not author_name or not author_email:
+                raise ValueError("delete_note author name and email are required when provided")
+            payload["author"] = {"name": author_name, "email": author_email}
+
+        url = f"{self.api_base_url}/api/v{self.api_version}/repos/notes"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.request(
+                "DELETE",
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Content-Type": "application/json",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                json=payload,
+                timeout=30.0,
+            )
+
+            return self._parse_note_write_response(response, "delete_note")
+
     async def get_branch_diff(
         self,
         *,
@@ -1046,6 +1164,123 @@ class RepoImpl:
             self.api_version,
         )
 
+    async def _write_note(
+        self,
+        *,
+        action_label: str,
+        action: str,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str],
+        author: Optional[CommitSignature],
+        ttl: Optional[int],
+    ) -> NoteWriteResult:
+        sha_clean = sha.strip()
+        if not sha_clean:
+            raise ValueError(f"{action_label} sha is required")
+
+        note_clean = note.strip()
+        if not note_clean:
+            raise ValueError(f"{action_label} note is required")
+
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self.generate_jwt(self._id, {"permissions": ["git:write"], "ttl": ttl})
+
+        payload: Dict[str, Any] = {
+            "sha": sha_clean,
+            "action": action,
+            "note": note_clean,
+        }
+        if expected_ref_sha and expected_ref_sha.strip():
+            payload["expected_ref_sha"] = expected_ref_sha.strip()
+        if author:
+            author_name = author.get("name", "").strip()
+            author_email = author.get("email", "").strip()
+            if not author_name or not author_email:
+                raise ValueError(f"{action_label} author name and email are required when provided")
+            payload["author"] = {"name": author_name, "email": author_email}
+
+        url = f"{self.api_base_url}/api/v{self.api_version}/repos/notes"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Content-Type": "application/json",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                json=payload,
+                timeout=30.0,
+            )
+
+            return self._parse_note_write_response(response, action_label)
+
+    def _parse_note_write_response(
+        self,
+        response: httpx.Response,
+        action_label: str,
+    ) -> NoteWriteResult:
+        try:
+            payload = response.json()
+        except Exception as exc:
+            message = f"{action_label} failed with HTTP {response.status_code}"
+            if response.reason_phrase:
+                message += f" {response.reason_phrase}"
+            try:
+                body_text = response.text
+            except Exception:
+                body_text = ""
+            if body_text:
+                message += f": {body_text[:200]}"
+            raise ApiError(message, status_code=response.status_code, response=response) from exc
+
+        if isinstance(payload, dict) and "error" in payload:
+            raise ApiError(
+                str(payload.get("error")),
+                status_code=response.status_code,
+                response=response,
+            )
+
+        if not isinstance(payload, dict) or "result" not in payload:
+            message = f"{action_label} failed with HTTP {response.status_code}"
+            if response.reason_phrase:
+                message += f" {response.reason_phrase}"
+            raise ApiError(message, status_code=response.status_code, response=response)
+
+        result = payload.get("result", {})
+        note_result: NoteWriteResult = {
+            "sha": payload.get("sha", ""),
+            "target_ref": payload.get("target_ref", ""),
+            "new_ref_sha": payload.get("new_ref_sha", ""),
+            "result": {
+                "success": bool(result.get("success")),
+                "status": str(result.get("status", "")),
+            },
+        }
+
+        base_commit = payload.get("base_commit")
+        if isinstance(base_commit, str) and base_commit:
+            note_result["base_commit"] = base_commit
+        if result.get("message"):
+            note_result["result"]["message"] = result.get("message")
+
+        if not result.get("success"):
+            raise RefUpdateError(
+                result.get(
+                    "message",
+                    f"{action_label} failed with status {result.get('status')}",
+                ),
+                status=result.get("status"),
+                ref_update={
+                    "branch": payload.get("target_ref", ""),
+                    "old_sha": payload.get("base_commit", ""),
+                    "new_sha": payload.get("new_ref_sha", ""),
+                },
+            )
+
+        return note_result
+
     def _to_ref_update(self, result: Dict[str, Any]) -> RefUpdate:
         """Convert result to ref update."""
         return {

pierre_storage/types.py

@@ -57,6 +57,33 @@ class DeleteRepoResult(TypedDict):
     message: str
 
 
+# Repository list types
+class RepoBaseInfo(TypedDict):
+    """Base repository info for listed repositories."""
+
+    provider: str
+    owner: str
+    name: str
+
+
+class RepoInfo(TypedDict, total=False):
+    """Repository info in list responses."""
+
+    repo_id: str
+    url: str
+    default_branch: str
+    created_at: str
+    base_repo: NotRequired[RepoBaseInfo]
+
+
+class ListReposResult(TypedDict):
+    """Result from listing repositories."""
+
+    repos: List[RepoInfo]
+    next_cursor: Optional[str]
+    has_more: bool
+
+
 # Removed: GetRemoteURLOptions - now uses **kwargs
 # Removed: CreateRepoOptions - now uses **kwargs
 # Removed: FindOneOptions - now uses **kwargs
@@ -127,6 +154,33 @@ class ListCommitsResult(TypedDict):
     has_more: bool
 
 
+# Git notes types
+class NoteReadResult(TypedDict):
+    """Result from reading a git note."""
+
+    sha: str
+    note: str
+    ref_sha: str
+
+
+class NoteWriteResultPayload(TypedDict):
+    """Result payload for note writes."""
+
+    success: bool
+    status: str
+    message: NotRequired[str]
+
+
+class NoteWriteResult(TypedDict):
+    """Result from writing a git note."""
+
+    sha: str
+    target_ref: str
+    base_commit: NotRequired[str]
+    new_ref_sha: str
+    result: NoteWriteResultPayload
+
+
 # Diff types
 class DiffStats(TypedDict):
     """Statistics about a diff."""
@@ -417,6 +471,50 @@ class Repo(Protocol):
         """List commits in the repository."""
         ...
 
+    async def get_note(
+        self,
+        *,
+        sha: str,
+        ttl: Optional[int] = None,
+    ) -> NoteReadResult:
+        """Read a git note."""
+        ...
+
+    async def create_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional["CommitSignature"] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Create a git note."""
+        ...
+
+    async def append_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional["CommitSignature"] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Append to a git note."""
+        ...
+
+    async def delete_note(
+        self,
+        *,
+        sha: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional["CommitSignature"] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Delete a git note."""
+        ...
+
     async def get_branch_diff(
         self,
         *,

{pierre_storage-0.10.0.dist-info → pierre_storage-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pierre-storage
-Version: 0.10.0
+Version: 0.11.0
 Summary: Pierre Git Storage SDK for Python
 Author-email: Pierre <support@pierre.io>
 License-Expression: MIT
@@ -149,6 +149,10 @@ repo = await storage.create_repo()
 # or
 repo = await storage.find_one(id="existing-repo-id")
 
+# List repositories for the org
+repos = await storage.list_repos(limit=20)
+print(repos["repos"])
+
 # Get file content (streaming)
 response = await repo.get_file_stream(
     path="README.md",
@@ -190,6 +194,27 @@ commits = await repo.list_commits(
 )
 print(commits["commits"])
 
+# Read a git note for a commit
+note = await repo.get_note(sha="abc123...")
+print(note["note"])
+
+# Add a git note
+note_result = await repo.create_note(
+    sha="abc123...",
+    note="Release QA approved",
+    author={"name": "Release Bot", "email": "release@example.com"},
+)
+print(note_result["new_ref_sha"])
+
+# Append to a git note
+await repo.append_note(
+    sha="abc123...",
+    note="Follow-up review complete",
+)
+
+# Delete a git note
+await repo.delete_note(sha="abc123...")
+
 # Get branch diff
 branch_diff = await repo.get_branch_diff(
     branch="feature-branch",

pierre_storage-0.11.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pierre_storage/__init__.py,sha256=8t6r3VUY4MSZhSuBXaoxzuxd4FLRAbVLWFxXiC_fcQY,1905
+pierre_storage/auth.py,sha256=aT0KNaUKa9fXERtQvJb8C6zL5IxrfA1KLxMBcprAq5A,2074
+pierre_storage/client.py,sha256=LPU0iZoduQvE7CDAMEKcYnMDn6WDH8vZtJw4BKO8lAg,13213
+pierre_storage/commit.py,sha256=ks5hKScHHricJ3sx8DyLSAASM72CPmVv-tbtUgHbUF4,16766
+pierre_storage/errors.py,sha256=-vuA2BUGwyDlErFtdh2boLdk0fDFDFYBEIohJk4AsIs,2184
+pierre_storage/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
+pierre_storage/repo.py,sha256=wnTDVtHx9v8tJTHJ9cHJs8cn5dImsCA3M3xxx7RqhS8,44117
+pierre_storage/types.py,sha256=MNTp4LYIActTUaxII-Qa0xjsKszVSPJKlLOvaw6nIOY,14425
+pierre_storage/version.py,sha256=HFSPY5BelU4QBXsW9MXZlFAE6Sa70XR3e_RzOQe1RO4,315
+pierre_storage/webhook.py,sha256=hyjSmTlU_x35m612erXDqNXbLUh5i5As5GRw7kxylFc,7425
+pierre_storage-0.11.0.dist-info/licenses/LICENSE,sha256=CFzxoMyurfMUB0u0RaXBFZ6IDeUd6FQhKrLR_IeXtuU,1063
+pierre_storage-0.11.0.dist-info/METADATA,sha256=0TaxHV-8GRD2iX1u6JpUrZHGe7P0wKdmp1sg0F8DyVg,22367
+pierre_storage-0.11.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+pierre_storage-0.11.0.dist-info/top_level.txt,sha256=RzcYFaSdETlcwX-45G9Q39xUgXWZLJEWcOiK0p6ZepY,15
+pierre_storage-0.11.0.dist-info/RECORD,,

pierre_storage-0.10.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-pierre_storage/__init__.py,sha256=uHHdwkzdHldq7OW6WpE6C2S-ooqvMw35oSxvYMb5oGc,1745
-pierre_storage/auth.py,sha256=aT0KNaUKa9fXERtQvJb8C6zL5IxrfA1KLxMBcprAq5A,2074
-pierre_storage/client.py,sha256=qJlQrxvt5YhVYp1RJAEt7pmmYLf6LwleTDb5lvs30kE,11080
-pierre_storage/commit.py,sha256=ks5hKScHHricJ3sx8DyLSAASM72CPmVv-tbtUgHbUF4,16766
-pierre_storage/errors.py,sha256=-vuA2BUGwyDlErFtdh2boLdk0fDFDFYBEIohJk4AsIs,2184
-pierre_storage/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
-pierre_storage/repo.py,sha256=EK82B9yBkB-69t9-lQPCE3Mj5BQ729IQYqg3C1UV4Yg,35982
-pierre_storage/types.py,sha256=u7iispDYc4C2bs-NweJc-sYVjwNlHNgqZ9ywltL11U4,12369
-pierre_storage/version.py,sha256=HFSPY5BelU4QBXsW9MXZlFAE6Sa70XR3e_RzOQe1RO4,315
-pierre_storage/webhook.py,sha256=hyjSmTlU_x35m612erXDqNXbLUh5i5As5GRw7kxylFc,7425
-pierre_storage-0.10.0.dist-info/licenses/LICENSE,sha256=CFzxoMyurfMUB0u0RaXBFZ6IDeUd6FQhKrLR_IeXtuU,1063
-pierre_storage-0.10.0.dist-info/METADATA,sha256=Erw1tJIeuOgE1eHNdeu_V_p4xr5L7gW6P5aSQdgpCKc,21790
-pierre_storage-0.10.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-pierre_storage-0.10.0.dist-info/top_level.txt,sha256=RzcYFaSdETlcwX-45G9Q39xUgXWZLJEWcOiK0p6ZepY,15
-pierre_storage-0.10.0.dist-info/RECORD,,