appflowysdk 0.1.0__tar.gz

appflowysdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AppFlowy SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

appflowysdk-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: appflowysdk
+Version: 0.1.0
+Summary: Type-safe Python SDK for the AppFlowy Cloud REST API
+Author: AppFlowy SDK Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AppFlowy-IO/appflowysdk
+Project-URL: Documentation, https://github.com/AppFlowy-IO/appflowysdk/tree/main/docs
+Project-URL: Repository, https://github.com/AppFlowy-IO/appflowysdk
+Project-URL: Issues, https://github.com/AppFlowy-IO/appflowysdk/issues
+Keywords: appflowy,api,sdk,cloud,productivity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Dynamic: license-file
+
+# AppFlowy SDK
+
+Type-safe Python SDK for the [AppFlowy Cloud REST API](https://beta.appflowy.cloud).
+
+## Installation
+
+```bash
+pip install appflowysdk 
+## or
+uv add appflowysdk
+```
+
+## Quick Start
+
+```python
+from appflowy import AppFlowy
+
+with AppFlowy(email="user@example.com", password="password") as client:
+    # Authenticate
+    token = client.login()
+    print(f"Logged in, token expires in {token.expires_in}s")
+
+    # List workspaces
+    workspaces = client.get_workspaces(include_member_count=True)
+    for ws in workspaces:
+        print(f"{ws.workspace_name} ({ws.workspace_id})")
+
+    # Get folder structure
+    folder = client.get_workspace_folder(workspaces[0].workspace_id)
+
+    # List databases
+    databases = client.get_databases(workspaces[0].workspace_id)
+
+    # Get database fields
+    fields = client.get_database_fields(
+        workspaces[0].workspace_id, databases[0].id
+    )
+
+    # Get row IDs
+    rows = client.get_database_row_ids(
+        workspaces[0].workspace_id, databases[0].id
+    )
+
+    # Get row details
+    if rows:
+        details = client.get_database_row_details(
+            workspaces[0].workspace_id,
+            databases[0].id,
+            [rows[0].id],
+            with_doc=True,
+        )
+
+    # Create a row
+    row_id = client.create_database_row(
+        workspaces[0].workspace_id,
+        databases[0].id,
+        cells={"field_id": "value"},
+    )
+
+    # Upsert a row
+    row_id = client.upsert_database_row(
+        workspaces[0].workspace_id,
+        databases[0].id,
+        pre_hash="unique-key",
+        cells={"field_id": "value"},
+    )
+```
+
+## OAuth
+
+```python
+client = AppFlowy()
+token = client.oauth_redirect_token(
+    code="auth_code_from_redirect",
+    grant_type="authorization_code",
+)
+```
+
+## Error Handling
+
+All SDK errors inherit from `AppFlowyError`:
+
+```python
+from src.exception import (
+    AppFlowyError,
+    LoginError,
+    RefreshTokenError,
+    APIError,
+    ValidationError,
+    NetworkError,
+)
+```
+
+## API Reference
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `login()` | `POST /gotrue/token?grant_type=password` | Password auth |
+| `refresh_token()` | `POST /gotrue/token?grant_type=refresh_token` | Refresh token |
+| `oauth_redirect_token()` | `GET /web-api/oauth-redirect/token` | OAuth token exchange |
+| `get_workspaces()` | `GET /api/workspace` | List workspaces |
+| `get_workspace_folder()` | `GET /api/workspace/{id}/folder` | Get folder tree |
+| `get_databases()` | `GET /api/workspace/{id}/database` | List databases |
+| `get_database_fields()` | `GET /api/workspace/{id}/database/{id}/fields` | List fields |
+| `get_database_row_ids()` | `GET /api/workspace/{id}/database/{id}/row` | List row IDs |
+| `create_database_row()` | `POST /api/workspace/{id}/database/{id}/row` | Create row |
+| `upsert_database_row()` | `PUT /api/workspace/{id}/database/{id}/row` | Upsert row |
+| `get_database_row_ids_updated()` | `GET /api/workspace/{id}/database/{id}/row/updated` | Updated rows |
+| `get_database_row_details()` | `GET /api/workspace/{id}/database/{id}/row/detail` | Row details |

appflowysdk-0.1.0/README.md

@@ -0,0 +1,109 @@
+# AppFlowy SDK
+
+Type-safe Python SDK for the [AppFlowy Cloud REST API](https://beta.appflowy.cloud).
+
+## Installation
+
+```bash
+pip install appflowysdk 
+## or
+uv add appflowysdk
+```
+
+## Quick Start
+
+```python
+from appflowy import AppFlowy
+
+with AppFlowy(email="user@example.com", password="password") as client:
+    # Authenticate
+    token = client.login()
+    print(f"Logged in, token expires in {token.expires_in}s")
+
+    # List workspaces
+    workspaces = client.get_workspaces(include_member_count=True)
+    for ws in workspaces:
+        print(f"{ws.workspace_name} ({ws.workspace_id})")
+
+    # Get folder structure
+    folder = client.get_workspace_folder(workspaces[0].workspace_id)
+
+    # List databases
+    databases = client.get_databases(workspaces[0].workspace_id)
+
+    # Get database fields
+    fields = client.get_database_fields(
+        workspaces[0].workspace_id, databases[0].id
+    )
+
+    # Get row IDs
+    rows = client.get_database_row_ids(
+        workspaces[0].workspace_id, databases[0].id
+    )
+
+    # Get row details
+    if rows:
+        details = client.get_database_row_details(
+            workspaces[0].workspace_id,
+            databases[0].id,
+            [rows[0].id],
+            with_doc=True,
+        )
+
+    # Create a row
+    row_id = client.create_database_row(
+        workspaces[0].workspace_id,
+        databases[0].id,
+        cells={"field_id": "value"},
+    )
+
+    # Upsert a row
+    row_id = client.upsert_database_row(
+        workspaces[0].workspace_id,
+        databases[0].id,
+        pre_hash="unique-key",
+        cells={"field_id": "value"},
+    )
+```
+
+## OAuth
+
+```python
+client = AppFlowy()
+token = client.oauth_redirect_token(
+    code="auth_code_from_redirect",
+    grant_type="authorization_code",
+)
+```
+
+## Error Handling
+
+All SDK errors inherit from `AppFlowyError`:
+
+```python
+from src.exception import (
+    AppFlowyError,
+    LoginError,
+    RefreshTokenError,
+    APIError,
+    ValidationError,
+    NetworkError,
+)
+```
+
+## API Reference
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `login()` | `POST /gotrue/token?grant_type=password` | Password auth |
+| `refresh_token()` | `POST /gotrue/token?grant_type=refresh_token` | Refresh token |
+| `oauth_redirect_token()` | `GET /web-api/oauth-redirect/token` | OAuth token exchange |
+| `get_workspaces()` | `GET /api/workspace` | List workspaces |
+| `get_workspace_folder()` | `GET /api/workspace/{id}/folder` | Get folder tree |
+| `get_databases()` | `GET /api/workspace/{id}/database` | List databases |
+| `get_database_fields()` | `GET /api/workspace/{id}/database/{id}/fields` | List fields |
+| `get_database_row_ids()` | `GET /api/workspace/{id}/database/{id}/row` | List row IDs |
+| `create_database_row()` | `POST /api/workspace/{id}/database/{id}/row` | Create row |
+| `upsert_database_row()` | `PUT /api/workspace/{id}/database/{id}/row` | Upsert row |
+| `get_database_row_ids_updated()` | `GET /api/workspace/{id}/database/{id}/row/updated` | Updated rows |
+| `get_database_row_details()` | `GET /api/workspace/{id}/database/{id}/row/detail` | Row details |

appflowysdk-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "appflowysdk"
+version = "0.1.0"
+description = "Type-safe Python SDK for the AppFlowy Cloud REST API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [
+    {name = "AppFlowy SDK Contributors"},
+]
+keywords = ["appflowy", "api", "sdk", "cloud", "productivity"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/AppFlowy-IO/appflowysdk"
+Documentation = "https://github.com/AppFlowy-IO/appflowysdk/tree/main/docs"
+Repository = "https://github.com/AppFlowy-IO/appflowysdk"
+Issues = "https://github.com/AppFlowy-IO/appflowysdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

appflowysdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

appflowysdk-0.1.0/src/appflowysdk/__init__.py

@@ -0,0 +1,70 @@
+"""Type-safe Python SDK for the AppFlowy Cloud REST API."""
+
+from appflowysdk.client import AppFlowy
+from appflowysdk.constants import BASE_URL
+from appflowysdk.exceptions import (
+    APIError,
+    AppFlowyError,
+    AuthenticationError,
+    LoginError,
+    NetworkError,
+    NotFoundError,
+    RefreshTokenError,
+    ValidationError,
+)
+from appflowysdk.models import (
+    AddDatabaseRowRequest,
+    ApiResponse,
+    Database,
+    DatabaseField,
+    DatabaseRow,
+    DatabaseRowDetail,
+    DatabaseRowUpdated,
+    FolderView,
+    FolderViewMin,
+    IconType,
+    Role,
+    Token,
+    TokenResponse,
+    UpsertDatabaseRowRequest,
+    ViewIcon,
+    ViewLayout,
+    Workspace,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client
+    "AppFlowy",
+    # Constants
+    "BASE_URL",
+    # Exceptions
+    "AppFlowyError",
+    "AuthenticationError",
+    "LoginError",
+    "RefreshTokenError",
+    "APIError",
+    "NotFoundError",
+    "ValidationError",
+    "NetworkError",
+    # Models
+    "Token",
+    "TokenResponse",
+    "ApiResponse",
+    "Workspace",
+    "ViewIcon",
+    "FolderViewMin",
+    "FolderView",
+    "Database",
+    "DatabaseField",
+    "DatabaseRow",
+    "DatabaseRowDetail",
+    "DatabaseRowUpdated",
+    "AddDatabaseRowRequest",
+    "UpsertDatabaseRowRequest",
+    # Enums
+    "IconType",
+    "ViewLayout",
+    "Role",
+]

appflowysdk-0.1.0/src/appflowysdk/client.py

@@ -0,0 +1,457 @@
+"""AppFlowy Cloud REST API client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from appflowysdk.constants import BASE_URL
+from appflowysdk.exceptions import (
+    APIError,
+    AuthenticationError,
+    LoginError,
+    NetworkError,
+    RefreshTokenError,
+    ValidationError,
+)
+from appflowysdk.logger import logger
+from appflowysdk.models import (
+    AddDatabaseRowRequest,
+    Database,
+    DatabaseField,
+    DatabaseFieldsResponse,
+    DatabaseRow,
+    DatabaseRowDetail,
+    DatabaseRowDetailsResponse,
+    DatabaseRowsResponse,
+    DatabaseRowsUpdatedResponse,
+    DatabaseRowUpdated,
+    DatabasesResponse,
+    FolderResponse,
+    FolderView,
+    Token,
+    TokenResponse,
+    UpsertDatabaseRowRequest,
+    Workspace,
+    WorkspacesResponse,
+)
+from appflowysdk.tokenstore import TokenStore
+
+
+class AppFlowy:
+    """Type-safe Python SDK for the AppFlowy Cloud REST API."""
+
+    def __init__(
+        self,
+        email: str | None = None,
+        password: str | None = None,
+        base_url: str = BASE_URL,
+    ) -> None:
+        self.email = email
+        self.password = password
+        self.base_url = base_url.rstrip("/")
+        self.token_store = TokenStore()
+        self._http_client = httpx.Client(timeout=30.0)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        access_token = self.token_store.get_access_token()
+        if access_token:
+            headers["Authorization"] = f"Bearer {access_token}"
+        return headers
+
+    def _handle_response(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            body: dict[str, Any] = response.json()
+        except Exception:
+            raise APIError(
+                "Failed to parse response body",
+                status_code=response.status_code,
+                body=response.text,
+            )
+
+        if response.status_code >= 400:
+            message = body.get("message", f"HTTP {response.status_code}")
+            raise APIError(
+                message=message,
+                status_code=response.status_code,
+                body=body,
+            )
+
+        return body
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        try:
+            response = self._http_client.request(
+                method=method,
+                url=url,
+                headers=self._headers(),
+                params=params,
+                json=json_body,
+            )
+            return self._handle_response(response)
+        except (APIError, AuthenticationError):
+            raise
+        except httpx.NetworkError as e:
+            raise NetworkError(f"Network error: {e}") from e
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}") from e
+        except Exception as e:
+            raise APIError(f"Unexpected error: {e}") from e
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+
+    def login(self) -> TokenResponse:
+        """Authenticate with email and password.
+
+        Returns:
+            TokenResponse with access and refresh tokens.
+
+        Raises:
+            LoginError: If credentials are missing or login fails.
+            NetworkError: If a network error occurs.
+        """
+        if not self.email or not self.password:
+            raise LoginError("Email and password are required for login.")
+
+        logger.info("Logging in as %s", self.email)
+        try:
+            body = self._request(
+                "POST",
+                "/gotrue/token?grant_type=password",
+                json_body={
+                    "email": self.email,
+                    "password": self.password,
+                },
+            )
+            token_response = TokenResponse(**body)
+            self.token_store.set_token_store(
+                Token(
+                    access_token=token_response.access_token,
+                    refresh_token=token_response.refresh_token,
+                    expires_in=token_response.expires_in,
+                )
+            )
+            logger.info("Login successful")
+            return token_response
+        except APIError as e:
+            raise LoginError(
+                f"Login failed: {e.message}",
+                status_code=e.status_code,
+                body=e.body,
+            ) from e
+
+    def refresh_token(self) -> TokenResponse:
+        """Refresh the access token using the stored refresh token.
+
+        Returns:
+            TokenResponse with new access and refresh tokens.
+
+        Raises:
+            RefreshTokenError: If no refresh token is stored or refresh fails.
+            NetworkError: If a network error occurs.
+        """
+        stored_refresh = self.token_store.get_refresh_token()
+        if not stored_refresh:
+            raise RefreshTokenError("No refresh token available. Please login first.")
+
+        logger.info("Refreshing access token")
+        try:
+            body = self._request(
+                "POST",
+                "/gotrue/token?grant_type=refresh_token",
+                json_body={"refresh_token": stored_refresh},
+            )
+            token_response = TokenResponse(**body)
+            self.token_store.set_token_store(
+                Token(
+                    access_token=token_response.access_token,
+                    refresh_token=token_response.refresh_token,
+                    expires_in=token_response.expires_in,
+                )
+            )
+            logger.info("Token refreshed successfully")
+            return token_response
+        except APIError as e:
+            raise RefreshTokenError(
+                f"Token refresh failed: {e.message}",
+                status_code=e.status_code,
+                body=e.body,
+            ) from e
+
+    def oauth_redirect_token(
+        self,
+        code: str,
+        grant_type: str,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        redirect_uri: str | None = None,
+        code_verifier: str | None = None,
+    ) -> TokenResponse:
+        """Exchange an OAuth authorization code for tokens.
+
+        Returns:
+            TokenResponse with access and refresh tokens.
+        """
+        params: dict[str, Any] = {
+            "code": code,
+            "grant_type": grant_type,
+        }
+        if client_id is not None:
+            params["client_id"] = client_id
+        if client_secret is not None:
+            params["client_secret"] = client_secret
+        if redirect_uri is not None:
+            params["redirect_uri"] = redirect_uri
+        if code_verifier is not None:
+            params["code_verifier"] = code_verifier
+
+        logger.info("Exchanging OAuth code for token")
+        body = self._request("GET", "/web-api/oauth-redirect/token", params=params)
+        token_response = TokenResponse(**body)
+        self.token_store.set_token_store(
+            Token(
+                access_token=token_response.access_token,
+                refresh_token=token_response.refresh_token,
+                expires_in=token_response.expires_in,
+            )
+        )
+        return token_response
+
+    # ------------------------------------------------------------------
+    # Workspaces
+    # ------------------------------------------------------------------
+
+    def get_workspaces(
+        self,
+        *,
+        include_member_count: bool | None = None,
+        include_role: bool | None = None,
+    ) -> list[Workspace]:
+        """Retrieve all workspaces for the authenticated user."""
+        params: dict[str, Any] = {}
+        if include_member_count is not None:
+            params["include_member_count"] = include_member_count
+        if include_role is not None:
+            params["include_role"] = include_role
+
+        body = self._request("GET", "/api/workspace", params=params)
+        response = WorkspacesResponse(**body)
+        return response.data
+
+    # ------------------------------------------------------------------
+    # Workspace folder
+    # ------------------------------------------------------------------
+
+    def get_workspace_folder(
+        self,
+        workspace_id: str,
+        *,
+        depth: int | None = None,
+        root_view_id: str | None = None,
+    ) -> FolderView:
+        """Retrieve the folder structure of a workspace."""
+        params: dict[str, Any] = {}
+        if depth is not None:
+            params["depth"] = depth
+        if root_view_id is not None:
+            params["root_view_id"] = root_view_id
+
+        body = self._request(
+            "GET",
+            f"/api/workspace/{workspace_id}/folder",
+            params=params,
+        )
+        response = FolderResponse(**body)
+        if response.data is None:
+            raise APIError("Server returned null folder data")
+        return response.data
+
+    # ------------------------------------------------------------------
+    # Databases
+    # ------------------------------------------------------------------
+
+    def get_databases(self, workspace_id: str) -> list[Database]:
+        """Retrieve all databases in a workspace."""
+        body = self._request(
+            "GET",
+            f"/api/workspace/{workspace_id}/database",
+        )
+        response = DatabasesResponse(**body)
+        return response.data
+
+    def get_database_fields(
+        self,
+        workspace_id: str,
+        database_id: str,
+    ) -> list[DatabaseField]:
+        """Retrieve all fields in a database."""
+        body = self._request(
+            "GET",
+            f"/api/workspace/{workspace_id}/database/{database_id}/fields",
+        )
+        response = DatabaseFieldsResponse(**body)
+        return response.data
+
+    # ------------------------------------------------------------------
+    # Database rows
+    # ------------------------------------------------------------------
+
+    def get_database_row_ids(
+        self,
+        workspace_id: str,
+        database_id: str,
+    ) -> list[DatabaseRow]:
+        """Retrieve all row IDs in a database."""
+        body = self._request(
+            "GET",
+            f"/api/workspace/{workspace_id}/database/{database_id}/row",
+        )
+        response = DatabaseRowsResponse(**body)
+        return response.data
+
+    def create_database_row(
+        self,
+        workspace_id: str,
+        database_id: str,
+        *,
+        cells: dict[str, Any] | None = None,
+        document: str | None = None,
+    ) -> str:
+        """Create a new row in a database.
+
+        Returns:
+            UUID of the newly created row.
+        """
+        request = AddDatabaseRowRequest(
+            cells=cells or {},
+            document=document,
+        )
+        body = self._request(
+            "POST",
+            f"/api/workspace/{workspace_id}/database/{database_id}/row",
+            json_body=request.model_dump(exclude_none=True),
+        )
+        return str(body.get("data", ""))
+
+    def upsert_database_row(
+        self,
+        workspace_id: str,
+        database_id: str,
+        pre_hash: str,
+        *,
+        cells: dict[str, Any] | None = None,
+        document: str | None = None,
+    ) -> str:
+        """Update or insert a row identified by ``pre_hash``.
+
+        Returns:
+            UUID of the created or updated row.
+        """
+        request = UpsertDatabaseRowRequest(
+            pre_hash=pre_hash,
+            cells=cells or {},
+            document=document,
+        )
+        body = self._request(
+            "PUT",
+            f"/api/workspace/{workspace_id}/database/{database_id}/row",
+            json_body=request.model_dump(exclude_none=True),
+        )
+        return str(body.get("data", ""))
+
+    # ------------------------------------------------------------------
+    # Row updates
+    # ------------------------------------------------------------------
+
+    def get_database_row_ids_updated(
+        self,
+        workspace_id: str,
+        database_id: str,
+        *,
+        after: datetime | str | None = None,
+    ) -> list[DatabaseRowUpdated]:
+        """Retrieve row IDs updated after a given timestamp."""
+        params: dict[str, Any] = {}
+        if after is not None:
+            params["after"] = (
+                after.isoformat() if isinstance(after, datetime) else after
+            )
+
+        body = self._request(
+            "GET",
+            f"/api/workspace/{workspace_id}/database/{database_id}/row/updated",
+            params=params,
+        )
+        response = DatabaseRowsUpdatedResponse(**body)
+        return response.data
+
+    # ------------------------------------------------------------------
+    # Row details
+    # ------------------------------------------------------------------
+
+    def get_database_row_details(
+        self,
+        workspace_id: str,
+        database_id: str,
+        row_ids: list[str],
+        *,
+        with_doc: bool | None = None,
+    ) -> list[DatabaseRowDetail]:
+        """Retrieve detailed information for specific database rows.
+
+        Raises:
+            ValidationError: If no row IDs are provided.
+        """
+        if not row_ids:
+            raise ValidationError("At least one row ID is required.")
+
+        params: dict[str, Any] = {"ids": ",".join(row_ids)}
+        if with_doc is not None:
+            params["with_doc"] = with_doc
+
+        body = self._request(
+            "GET",
+            f"/api/workspace/{workspace_id}/database/{database_id}/row/detail",
+            params=params,
+        )
+        response = DatabaseRowDetailsResponse(**body)
+        return response.data
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http_client.close()
+
+    def __enter__(self) -> AppFlowy:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        self.close()

appflowysdk-0.1.0/src/appflowysdk/constants.py

@@ -0,0 +1,3 @@
+"""AppFlowy Cloud API base URL."""
+
+BASE_URL: str = "https://beta.appflowy.cloud"

appflowysdk-0.1.0/src/appflowysdk/exceptions.py

@@ -0,0 +1,48 @@
+"""AppFlowy SDK exception hierarchy."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AppFlowyError(Exception):
+    """Base exception for all AppFlowy SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        body: Any = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+        super().__init__(self.message)
+
+
+class AuthenticationError(AppFlowyError):
+    """Raised when authentication fails (login or token refresh)."""
+
+
+class LoginError(AuthenticationError):
+    """Raised when login fails."""
+
+
+class RefreshTokenError(AuthenticationError):
+    """Raised when token refresh fails."""
+
+
+class APIError(AppFlowyError):
+    """Raised when an API request returns a non-2xx status code."""
+
+
+class NotFoundError(APIError):
+    """Raised when a resource is not found (404)."""
+
+
+class ValidationError(AppFlowyError):
+    """Raised when SDK-side input validation fails."""
+
+
+class NetworkError(AppFlowyError):
+    """Raised when a network-level error occurs."""

appflowysdk-0.1.0/src/appflowysdk/logger.py

@@ -0,0 +1,15 @@
+"""Structured logging for the AppFlowy SDK."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("appflowysdk")
+
+if not logger.handlers:
+    _handler = logging.StreamHandler()
+    _handler.setFormatter(
+        logging.Formatter("%(asctime)s %(name)s %(levelname)s %(message)s")
+    )
+    logger.addHandler(_handler)
+    logger.setLevel(logging.INFO)

appflowysdk-0.1.0/src/appflowysdk/models.py

@@ -0,0 +1,218 @@
+"""Pydantic models and enums for the AppFlowy Cloud API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import IntEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class IconType(IntEnum):
+    EMOJI = 0
+    URL = 1
+    ICON = 2
+
+
+class ViewLayout(IntEnum):
+    DOCUMENT = 0
+    GRID = 1
+    BOARD = 2
+    CALENDAR = 3
+    CHAT = 4
+
+
+class Role(IntEnum):
+    OWNER = 1
+    MEMBER = 2
+    GUEST = 3
+
+
+# ---------------------------------------------------------------------------
+# Token models
+# ---------------------------------------------------------------------------
+
+
+class Token(BaseModel):
+    """Internal token storage."""
+
+    access_token: str = ""
+    refresh_token: str = ""
+    expires_in: int = 0
+
+
+class TokenResponse(BaseModel):
+    """Server response from authentication endpoints."""
+
+    access_token: str
+    token_type: str | None = None
+    expires_in: int
+    expires_at: int | None = None
+    refresh_token: str
+    user: dict[str, Any] | None = None
+    provider_access_token: str | None = None
+    provider_refresh_token: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Generic API response
+# ---------------------------------------------------------------------------
+
+
+class ApiResponse(BaseModel):
+    code: int
+    message: str
+
+
+# ---------------------------------------------------------------------------
+# Workspace models
+# ---------------------------------------------------------------------------
+
+
+class Workspace(BaseModel):
+    workspace_id: str
+    database_storage_id: str | None = None
+    owner_uid: int | None = None
+    owner_name: str | None = None
+    owner_email: str | None = None
+    workspace_type: int | None = None
+    workspace_name: str | None = None
+    created_at: datetime | None = None
+    icon: str | None = None
+    member_count: int | None = None
+    role: Role | None = None
+
+
+# ---------------------------------------------------------------------------
+# View / Folder models
+# ---------------------------------------------------------------------------
+
+
+class ViewIcon(BaseModel):
+    ty: IconType | None = None
+    value: str | None = None
+
+
+class FolderViewMin(BaseModel):
+    view_id: str
+    name: str
+    icon: ViewIcon | None = None
+    layout: ViewLayout | None = None
+
+
+class FolderView(BaseModel):
+    view_id: str
+    name: str
+    icon: ViewIcon | None = None
+    is_space: bool | None = None
+    is_private: bool | None = None
+    is_published: bool | None = None
+    layout: ViewLayout | None = None
+    created_at: datetime | None = None
+    last_edited_time: datetime | None = None
+    is_locked: bool | None = None
+    extra: dict[str, Any] | None = None
+    children: list[FolderView] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Database models
+# ---------------------------------------------------------------------------
+
+
+class Database(BaseModel):
+    id: str
+    views: list[FolderViewMin] = Field(default_factory=list)
+
+
+class DatabaseField(BaseModel):
+    id: str
+    name: str | None = None
+    field_type: str | None = None
+    type_option: dict[str, Any] | None = None
+    is_primary: bool | None = None
+
+
+class DatabaseRow(BaseModel):
+    id: str
+
+
+class DatabaseRowUpdated(BaseModel):
+    id: str
+    updated_at: datetime | None = None
+
+
+class DatabaseRowDetail(BaseModel):
+    id: str
+    cells: dict[str, Any] = Field(default_factory=dict)
+    has_doc: bool | None = None
+    doc: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Request models
+# ---------------------------------------------------------------------------
+
+
+class AddDatabaseRowRequest(BaseModel):
+    cells: dict[str, Any] = Field(default_factory=dict)
+    document: str | None = None
+
+
+class UpsertDatabaseRowRequest(BaseModel):
+    pre_hash: str
+    cells: dict[str, Any] = Field(default_factory=dict)
+    document: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Typed API response wrappers
+# ---------------------------------------------------------------------------
+
+
+class WorkspacesResponse(BaseModel):
+    code: int
+    message: str
+    data: list[Workspace] = Field(default_factory=list)
+
+
+class FolderResponse(BaseModel):
+    code: int
+    message: str
+    data: FolderView | None = None
+
+
+class DatabasesResponse(BaseModel):
+    code: int
+    message: str
+    data: list[Database] = Field(default_factory=list)
+
+
+class DatabaseFieldsResponse(BaseModel):
+    code: int
+    message: str
+    data: list[DatabaseField] = Field(default_factory=list)
+
+
+class DatabaseRowsResponse(BaseModel):
+    code: int
+    message: str
+    data: list[DatabaseRow] = Field(default_factory=list)
+
+
+class DatabaseRowsUpdatedResponse(BaseModel):
+    code: int
+    message: str
+    data: list[DatabaseRowUpdated] = Field(default_factory=list)
+
+
+class DatabaseRowDetailsResponse(BaseModel):
+    code: int
+    message: str
+    data: list[DatabaseRowDetail] = Field(default_factory=list)

appflowysdk-0.1.0/src/appflowysdk/tokenstore.py

@@ -0,0 +1,47 @@
+"""In-memory token storage."""
+
+from __future__ import annotations
+
+from appflowysdk.models import Token
+
+
+class TokenStore:
+    def __init__(self) -> None:
+        self._access_token: str = ""
+        self._refresh_token: str = ""
+        self._expires_in: int = 0
+
+    def set_token_store(self, token: Token) -> None:
+        self._access_token = token.access_token
+        self._refresh_token = token.refresh_token
+        self._expires_in = token.expires_in
+
+    def set_access_token(self, access_token: str) -> None:
+        self._access_token = access_token
+
+    def set_refresh_token(self, refresh_token: str) -> None:
+        self._refresh_token = refresh_token
+
+    def set_expires_in(self, expires_in: int) -> None:
+        self._expires_in = expires_in
+
+    def get_access_token(self) -> str:
+        return self._access_token
+
+    def get_refresh_token(self) -> str:
+        return self._refresh_token
+
+    def get_expires_in(self) -> int:
+        return self._expires_in
+
+    def get_token_store(self) -> Token:
+        return Token(
+            access_token=self._access_token,
+            refresh_token=self._refresh_token,
+            expires_in=self._expires_in,
+        )
+
+    def clear(self) -> None:
+        self._access_token = ""
+        self._refresh_token = ""
+        self._expires_in = 0

appflowysdk-0.1.0/src/appflowysdk.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: appflowysdk
+Version: 0.1.0
+Summary: Type-safe Python SDK for the AppFlowy Cloud REST API
+Author: AppFlowy SDK Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AppFlowy-IO/appflowysdk
+Project-URL: Documentation, https://github.com/AppFlowy-IO/appflowysdk/tree/main/docs
+Project-URL: Repository, https://github.com/AppFlowy-IO/appflowysdk
+Project-URL: Issues, https://github.com/AppFlowy-IO/appflowysdk/issues
+Keywords: appflowy,api,sdk,cloud,productivity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Dynamic: license-file
+
+# AppFlowy SDK
+
+Type-safe Python SDK for the [AppFlowy Cloud REST API](https://beta.appflowy.cloud).
+
+## Installation
+
+```bash
+pip install appflowysdk 
+## or
+uv add appflowysdk
+```
+
+## Quick Start
+
+```python
+from appflowy import AppFlowy
+
+with AppFlowy(email="user@example.com", password="password") as client:
+    # Authenticate
+    token = client.login()
+    print(f"Logged in, token expires in {token.expires_in}s")
+
+    # List workspaces
+    workspaces = client.get_workspaces(include_member_count=True)
+    for ws in workspaces:
+        print(f"{ws.workspace_name} ({ws.workspace_id})")
+
+    # Get folder structure
+    folder = client.get_workspace_folder(workspaces[0].workspace_id)
+
+    # List databases
+    databases = client.get_databases(workspaces[0].workspace_id)
+
+    # Get database fields
+    fields = client.get_database_fields(
+        workspaces[0].workspace_id, databases[0].id
+    )
+
+    # Get row IDs
+    rows = client.get_database_row_ids(
+        workspaces[0].workspace_id, databases[0].id
+    )
+
+    # Get row details
+    if rows:
+        details = client.get_database_row_details(
+            workspaces[0].workspace_id,
+            databases[0].id,
+            [rows[0].id],
+            with_doc=True,
+        )
+
+    # Create a row
+    row_id = client.create_database_row(
+        workspaces[0].workspace_id,
+        databases[0].id,
+        cells={"field_id": "value"},
+    )
+
+    # Upsert a row
+    row_id = client.upsert_database_row(
+        workspaces[0].workspace_id,
+        databases[0].id,
+        pre_hash="unique-key",
+        cells={"field_id": "value"},
+    )
+```
+
+## OAuth
+
+```python
+client = AppFlowy()
+token = client.oauth_redirect_token(
+    code="auth_code_from_redirect",
+    grant_type="authorization_code",
+)
+```
+
+## Error Handling
+
+All SDK errors inherit from `AppFlowyError`:
+
+```python
+from src.exception import (
+    AppFlowyError,
+    LoginError,
+    RefreshTokenError,
+    APIError,
+    ValidationError,
+    NetworkError,
+)
+```
+
+## API Reference
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `login()` | `POST /gotrue/token?grant_type=password` | Password auth |
+| `refresh_token()` | `POST /gotrue/token?grant_type=refresh_token` | Refresh token |
+| `oauth_redirect_token()` | `GET /web-api/oauth-redirect/token` | OAuth token exchange |
+| `get_workspaces()` | `GET /api/workspace` | List workspaces |
+| `get_workspace_folder()` | `GET /api/workspace/{id}/folder` | Get folder tree |
+| `get_databases()` | `GET /api/workspace/{id}/database` | List databases |
+| `get_database_fields()` | `GET /api/workspace/{id}/database/{id}/fields` | List fields |
+| `get_database_row_ids()` | `GET /api/workspace/{id}/database/{id}/row` | List row IDs |
+| `create_database_row()` | `POST /api/workspace/{id}/database/{id}/row` | Create row |
+| `upsert_database_row()` | `PUT /api/workspace/{id}/database/{id}/row` | Upsert row |
+| `get_database_row_ids_updated()` | `GET /api/workspace/{id}/database/{id}/row/updated` | Updated rows |
+| `get_database_row_details()` | `GET /api/workspace/{id}/database/{id}/row/detail` | Row details |

appflowysdk-0.1.0/src/appflowysdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/appflowysdk/__init__.py
+src/appflowysdk/client.py
+src/appflowysdk/constants.py
+src/appflowysdk/exceptions.py
+src/appflowysdk/logger.py
+src/appflowysdk/models.py
+src/appflowysdk/tokenstore.py
+src/appflowysdk.egg-info/PKG-INFO
+src/appflowysdk.egg-info/SOURCES.txt
+src/appflowysdk.egg-info/dependency_links.txt
+src/appflowysdk.egg-info/requires.txt
+src/appflowysdk.egg-info/top_level.txt

appflowysdk-0.1.0/src/appflowysdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

appflowysdk-0.1.0/src/appflowysdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.28.1
+pydantic>=2.12.5

appflowysdk-0.1.0/src/appflowysdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+appflowysdk