casfa-client 0.1.0__tar.gz

casfa_client-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: casfa-client
+Version: 0.1.0
+Summary: CASFA (Content-Addressable Storage for Agents) Python SDK
+Author: Mitsein Team
+License-Expression: MIT
+Keywords: casfa,cas,content-addressable,storage,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# CASFA Python SDK
+
+Python client for CASFA (Content-Addressable Storage for Agents).
+
+## Installation
+
+```bash
+pip install casfa-client
+```
+
+## Quick Start
+
+### Agent Token Authentication
+
+```python
+import asyncio
+from casfa import create_casfa_client, CasfaClientConfig, TokenAuthConfig
+
+async def main():
+    # Create client with agent token
+    client = create_casfa_client(CasfaClientConfig(
+        base_url="https://casfa.example.com",
+        auth=TokenAuthConfig(type="token", token="casfa_xxx"),
+        realm_id="user:ABC123",
+    ))
+
+    # Get realm usage
+    result = await client.realm.get_usage()
+    if result.ok:
+        print(f"Nodes: {result.data.node_count}")
+        print(f"Bytes: {result.data.total_bytes}")
+    else:
+        print(f"Error: {result.error.message}")
+
+    # List depots
+    result = await client.depots.list()
+    if result.ok:
+        for depot in result.data.items:
+            print(f"Depot: {depot.title} (v{depot.version})")
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+### Ticket Authentication
+
+```python
+from casfa import create_casfa_client, CasfaClientConfig, TicketAuthConfig
+
+async def process_with_ticket(ticket_id: str):
+    client = create_casfa_client(CasfaClientConfig(
+        base_url="https://casfa.example.com",
+        auth=TicketAuthConfig(type="ticket", ticket_id=ticket_id),
+    ))
+
+    # Read nodes allowed by ticket scope
+    result = await client.nodes.get(key="node:abc123...")
+    if result.ok:
+        data = result.data  # bytes
+        # Process data...
+
+    # Commit output
+    result = await client.tickets.commit(
+        ticket_id=ticket_id,
+        output="node:result123...",
+    )
+
+    await client.close()
+```
+
+## API Reference
+
+### Client Creation
+
+```python
+from casfa import create_casfa_client, CasfaClientConfig
+
+client = create_casfa_client(CasfaClientConfig(
+    base_url="https://casfa.example.com",
+    auth=auth_config,  # TokenAuthConfig, TicketAuthConfig, etc.
+    realm_id="user:ABC123",  # Optional
+))
+```
+
+### API Namespaces
+
+| Namespace | Description |
+|-----------|-------------|
+| `client.oauth` | OAuth/Cognito authentication |
+| `client.auth` | AWP clients and Agent tokens |
+| `client.admin` | Admin user management |
+| `client.mcp` | MCP JSON-RPC tool calls |
+| `client.realm` | Realm info and usage |
+| `client.tickets` | Ticket management |
+| `client.depots` | Depot management |
+| `client.nodes` | Node storage operations |
+
+### Result Pattern
+
+All API methods return `FetchResult[T]`:
+
+```python
+result = await client.tickets.create(...)
+
+if result.ok:
+    ticket = result.data  # TicketInfo
+    print(ticket.ticket_id)
+else:
+    error = result.error  # CasfaError
+    print(f"Error: {error.code} - {error.message}")
+```
+
+### Authentication Types
+
+| Type | Config | Header |
+|------|--------|--------|
+| Agent Token | `TokenAuthConfig` | `AgentToken {token}` |
+| Ticket | `TicketAuthConfig` | `Ticket {ticketId}` |
+| User OAuth | `UserAuthConfig` | `Bearer {accessToken}` |
+| P256 (AWP) | `P256AuthConfig` | `X-AWP-*` headers |
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type check
+mypy casfa
+
+# Lint
+ruff check casfa
+```
+
+## License
+
+MIT

casfa_client-0.1.0/README.md

@@ -0,0 +1,141 @@
+# CASFA Python SDK
+
+Python client for CASFA (Content-Addressable Storage for Agents).
+
+## Installation
+
+```bash
+pip install casfa-client
+```
+
+## Quick Start
+
+### Agent Token Authentication
+
+```python
+import asyncio
+from casfa import create_casfa_client, CasfaClientConfig, TokenAuthConfig
+
+async def main():
+    # Create client with agent token
+    client = create_casfa_client(CasfaClientConfig(
+        base_url="https://casfa.example.com",
+        auth=TokenAuthConfig(type="token", token="casfa_xxx"),
+        realm_id="user:ABC123",
+    ))
+
+    # Get realm usage
+    result = await client.realm.get_usage()
+    if result.ok:
+        print(f"Nodes: {result.data.node_count}")
+        print(f"Bytes: {result.data.total_bytes}")
+    else:
+        print(f"Error: {result.error.message}")
+
+    # List depots
+    result = await client.depots.list()
+    if result.ok:
+        for depot in result.data.items:
+            print(f"Depot: {depot.title} (v{depot.version})")
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+### Ticket Authentication
+
+```python
+from casfa import create_casfa_client, CasfaClientConfig, TicketAuthConfig
+
+async def process_with_ticket(ticket_id: str):
+    client = create_casfa_client(CasfaClientConfig(
+        base_url="https://casfa.example.com",
+        auth=TicketAuthConfig(type="ticket", ticket_id=ticket_id),
+    ))
+
+    # Read nodes allowed by ticket scope
+    result = await client.nodes.get(key="node:abc123...")
+    if result.ok:
+        data = result.data  # bytes
+        # Process data...
+
+    # Commit output
+    result = await client.tickets.commit(
+        ticket_id=ticket_id,
+        output="node:result123...",
+    )
+
+    await client.close()
+```
+
+## API Reference
+
+### Client Creation
+
+```python
+from casfa import create_casfa_client, CasfaClientConfig
+
+client = create_casfa_client(CasfaClientConfig(
+    base_url="https://casfa.example.com",
+    auth=auth_config,  # TokenAuthConfig, TicketAuthConfig, etc.
+    realm_id="user:ABC123",  # Optional
+))
+```
+
+### API Namespaces
+
+| Namespace | Description |
+|-----------|-------------|
+| `client.oauth` | OAuth/Cognito authentication |
+| `client.auth` | AWP clients and Agent tokens |
+| `client.admin` | Admin user management |
+| `client.mcp` | MCP JSON-RPC tool calls |
+| `client.realm` | Realm info and usage |
+| `client.tickets` | Ticket management |
+| `client.depots` | Depot management |
+| `client.nodes` | Node storage operations |
+
+### Result Pattern
+
+All API methods return `FetchResult[T]`:
+
+```python
+result = await client.tickets.create(...)
+
+if result.ok:
+    ticket = result.data  # TicketInfo
+    print(ticket.ticket_id)
+else:
+    error = result.error  # CasfaError
+    print(f"Error: {error.code} - {error.message}")
+```
+
+### Authentication Types
+
+| Type | Config | Header |
+|------|--------|--------|
+| Agent Token | `TokenAuthConfig` | `AgentToken {token}` |
+| Ticket | `TicketAuthConfig` | `Ticket {ticketId}` |
+| User OAuth | `UserAuthConfig` | `Bearer {accessToken}` |
+| P256 (AWP) | `P256AuthConfig` | `X-AWP-*` headers |
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type check
+mypy casfa
+
+# Lint
+ruff check casfa
+```
+
+## License
+
+MIT

casfa_client-0.1.0/casfa/__init__.py

@@ -0,0 +1,227 @@
+"""CASFA Python SDK - Content-Addressable Storage for Agents.
+
+This SDK provides a Python client for interacting with the CASFA API,
+mirroring the TypeScript Client V2 (`@agent-web-portal/casfa-client-v2`).
+
+Example:
+    >>> from casfa import create_casfa_client, CasfaClientConfig, TokenAuthConfig
+    >>>
+    >>> client = create_casfa_client(CasfaClientConfig(
+    ...     base_url="https://casfa.example.com",
+    ...     auth=TokenAuthConfig(type="token", token="casfa_xxx"),
+    ...     realm_id="user:ABC123",
+    ... ))
+    >>>
+    >>> # Get realm usage
+    >>> result = await client.realm.get_usage()
+    >>> if result.ok:
+    ...     print(f"Nodes: {result.data.node_count}")
+    ...
+    >>> # Create a ticket
+    >>> result = await client.tickets.create(
+    ...     input=["node:abc123..."],
+    ...     purpose="Process data",
+    ... )
+"""
+
+# =============================================================================
+# Main Client
+# =============================================================================
+
+from casfa.auth.p256 import P256Auth, create_p256_auth
+from casfa.auth.permissions import (
+    API_PERMISSIONS,
+    ApiName,
+    PermissionCheckResult,
+    assert_access,
+    can_access,
+    check_permission,
+    get_required_auth,
+    is_public_api,
+)
+from casfa.auth.ticket import TicketAuth, create_ticket_auth
+from casfa.auth.token import TokenAuth, create_token_auth
+
+# =============================================================================
+# Auth Strategies
+# =============================================================================
+from casfa.auth.user import UserAuth, create_user_auth
+from casfa.client import CasfaClient, CasfaClientConfig, create_casfa_client
+
+# =============================================================================
+# Types - API
+# =============================================================================
+from casfa.types.api import (
+    # Agent Token
+    AgentTokenInfo,
+    # AWP Client
+    AwpAuthInitResponse,
+    AwpAuthPollResponse,
+    AwpClientInfo,
+    # OAuth
+    CognitoConfig,
+    CreateAgentTokenResponse,
+    DepotDetail,
+    DepotHistoryEntry,
+    # Depot
+    DepotInfo,
+    DictNodeMetadata,
+    FileNodeMetadata,
+    McpError,
+    # MCP
+    McpRequest,
+    McpResponse,
+    NodeKind,
+    # Node
+    NodeMetadata,
+    # Pagination
+    PaginatedResponse,
+    PrepareNodesResult,
+    # Realm
+    RealmInfo,
+    RealmUsage,
+    SuccessorNodeMetadata,
+    # Ticket
+    TicketInfo,
+    TicketListItem,
+    TokenResponse,
+    UserInfo,
+    # Admin
+    UserListItem,
+    WritableConfig,
+)
+
+# =============================================================================
+# Types - Auth
+# =============================================================================
+from casfa.types.auth import (
+    AuthConfig,
+    AuthState,
+    AuthType,
+    # P256
+    P256AuthCallbacks,
+    P256AuthConfig,
+    P256AuthState,
+    P256PollStatus,
+    TicketAuthConfig,
+    # Ticket
+    TicketAuthState,
+    TokenAuthConfig,
+    # Token
+    TokenAuthState,
+    # User
+    UserAuthCallbacks,
+    UserAuthConfig,
+    UserAuthState,
+)
+
+# =============================================================================
+# Types - Providers
+# =============================================================================
+from casfa.types.providers import (
+    HashProvider,
+    KeyPairProvider,
+    P256KeyPair,
+    StorageProvider,
+)
+
+# =============================================================================
+# Utils
+# =============================================================================
+from casfa.utils.errors import (
+    CasfaError,
+    CasfaErrorCode,
+    create_error,
+    is_casfa_error,
+)
+from casfa.utils.fetch import FetchResult, FetchResultErr, FetchResultOk
+
+# =============================================================================
+# Version
+# =============================================================================
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client
+    "CasfaClient",
+    "CasfaClientConfig",
+    "create_casfa_client",
+    # API Types
+    "CognitoConfig",
+    "TokenResponse",
+    "UserInfo",
+    "AwpAuthInitResponse",
+    "AwpAuthPollResponse",
+    "AwpClientInfo",
+    "AgentTokenInfo",
+    "CreateAgentTokenResponse",
+    "UserListItem",
+    "RealmInfo",
+    "RealmUsage",
+    "TicketInfo",
+    "TicketListItem",
+    "WritableConfig",
+    "DepotInfo",
+    "DepotDetail",
+    "DepotHistoryEntry",
+    "NodeMetadata",
+    "DictNodeMetadata",
+    "FileNodeMetadata",
+    "SuccessorNodeMetadata",
+    "NodeKind",
+    "PrepareNodesResult",
+    "McpRequest",
+    "McpResponse",
+    "McpError",
+    "PaginatedResponse",
+    # Auth Types
+    "AuthConfig",
+    "AuthState",
+    "AuthType",
+    "UserAuthCallbacks",
+    "UserAuthState",
+    "UserAuthConfig",
+    "TokenAuthState",
+    "TokenAuthConfig",
+    "TicketAuthState",
+    "TicketAuthConfig",
+    "P256AuthCallbacks",
+    "P256AuthState",
+    "P256AuthConfig",
+    "P256PollStatus",
+    # Provider Types
+    "StorageProvider",
+    "HashProvider",
+    "KeyPairProvider",
+    "P256KeyPair",
+    # Auth Strategies
+    "UserAuth",
+    "create_user_auth",
+    "TokenAuth",
+    "create_token_auth",
+    "TicketAuth",
+    "create_ticket_auth",
+    "P256Auth",
+    "create_p256_auth",
+    # Permissions
+    "ApiName",
+    "API_PERMISSIONS",
+    "can_access",
+    "assert_access",
+    "get_required_auth",
+    "is_public_api",
+    "check_permission",
+    "PermissionCheckResult",
+    # Errors
+    "CasfaError",
+    "CasfaErrorCode",
+    "create_error",
+    "is_casfa_error",
+    # Fetch Result
+    "FetchResult",
+    "FetchResultOk",
+    "FetchResultErr",
+    # Version
+    "__version__",
+]

casfa_client-0.1.0/casfa/api/__init__.py

@@ -0,0 +1,21 @@
+"""CASFA API namespaces."""
+
+from casfa.api.admin import AdminApi
+from casfa.api.auth import AuthApi
+from casfa.api.depots import DepotApi
+from casfa.api.mcp import McpApi
+from casfa.api.nodes import NodeApi
+from casfa.api.oauth import OAuthApi
+from casfa.api.realm import RealmApi
+from casfa.api.tickets import TicketApi
+
+__all__ = [
+    "OAuthApi",
+    "AuthApi",
+    "AdminApi",
+    "McpApi",
+    "RealmApi",
+    "TicketApi",
+    "DepotApi",
+    "NodeApi",
+]

casfa_client-0.1.0/casfa/api/admin.py

@@ -0,0 +1,81 @@
+"""Admin API - User management for admins."""
+
+from casfa.types.api import PaginatedResponse, UserListItem
+from casfa.utils.fetch import Fetcher, FetchResult, FetchResultOk, RequestOptions
+
+
+class AdminApi:
+    """Admin API namespace for user management."""
+
+    def __init__(self, fetcher: Fetcher) -> None:
+        self._fetcher = fetcher
+
+    async def list_users(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> FetchResult[PaginatedResponse[UserListItem]]:
+        """List all users (admin only)."""
+        params = []
+        if cursor:
+            params.append(f"cursor={cursor}")
+        if limit:
+            params.append(f"limit={limit}")
+
+        path = "/api/admin/users"
+        if params:
+            path += "?" + "&".join(params)
+
+        result = await self._fetcher.request(path)
+        if result.ok:
+            data = result.data
+            items = [
+                UserListItem(
+                    user_id=item["user_id"],
+                    email=item["email"],
+                    role=item["role"],
+                    created_at=item["created_at"],
+                    realm_id=item.get("realm_id"),
+                )
+                for item in data.get("items", [])
+            ]
+            return FetchResultOk(
+                ok=True,
+                data=PaginatedResponse(
+                    items=items,
+                    next_cursor=data.get("next_cursor"),
+                    total=data.get("total"),
+                ),
+                status=result.status,
+            )
+        return result
+
+    async def update_user_role(
+        self,
+        *,
+        user_id: str,
+        role: str,
+    ) -> FetchResult[UserListItem]:
+        """Update a user's role (admin only)."""
+        result = await self._fetcher.request(
+            f"/api/admin/users/{user_id}/role",
+            RequestOptions(
+                method="PUT",
+                body={"role": role},
+            ),
+        )
+        if result.ok:
+            data = result.data
+            return FetchResultOk(
+                ok=True,
+                data=UserListItem(
+                    user_id=data["user_id"],
+                    email=data["email"],
+                    role=data["role"],
+                    created_at=data["created_at"],
+                    realm_id=data.get("realm_id"),
+                ),
+                status=result.status,
+            )
+        return result