edgebase-admin 0.1.3__tar.gz

edgebase_admin-0.1.3/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.venv/

edgebase_admin-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 melodysdreamj
+
+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.

edgebase_admin-0.1.3/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: edgebase-admin
+Version: 0.1.3
+Summary: Python admin SDK for EdgeBase service-key workloads
+Author: EdgeBase Team
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: edgebase-core<0.2.0,>=0.1.3
+Description-Content-Type: text/markdown
+
+# edgebase-admin
+
+Server-only Python admin SDK for EdgeBase.
+
+Use `edgebase-admin` from trusted environments that hold a Service Key, such as backend APIs, cron jobs, workers, and operational tooling. It exposes admin auth, service-key database access, storage management, raw SQL, functions, analytics, push, and native Cloudflare resources.
+
+If you want the unified package that also includes the higher-level `EdgeBaseServer` entry point and room helpers, install [`edgebase`](https://pypi.org/project/edgebase/) instead.
+
+## Documentation Map
+
+Use this README for the fast overview, then jump into the docs when you need depth:
+
+- [SDK Overview](https://edgebase.fun/docs/sdks)
+  Install commands and language matrix for all public SDKs
+- [Admin SDK](https://edgebase.fun/docs/sdks/client-vs-server)
+  Service-key concepts, trust boundaries, and admin-only capabilities
+- [Admin SDK Reference](https://edgebase.fun/docs/admin-sdk/reference)
+  Cross-language auth, database, storage, functions, and push examples
+- [Admin User Management](https://edgebase.fun/docs/authentication/admin-users)
+  Create, update, delete, and manage users with the Service Key
+- [Database Admin SDK](https://edgebase.fun/docs/database/admin-sdk)
+  Table queries, filters, pagination, batch writes, and raw SQL
+- [Storage](https://edgebase.fun/docs/storage/upload-download)
+  Uploads, downloads, metadata, and signed URLs
+- [Analytics Admin SDK](https://edgebase.fun/docs/analytics/admin-sdk)
+  Request metrics, event tracking, and event queries
+- [Push Admin SDK](https://edgebase.fun/docs/push/admin-sdk)
+  Push send, topic broadcast, token inspection, and logs
+- [Native Resources](https://edgebase.fun/docs/server/native-resources)
+  KV, D1, Vectorize, and other edge-native resources
+
+## For AI Coding Assistants
+
+This package includes an `llms.txt` file for AI-assisted development.
+
+Use it when you want an agent or code assistant to:
+
+- use the right Python admin method signatures
+- remember which surfaces are properties vs methods
+- avoid copying JavaScript or Go API shapes into Python
+- choose `edgebase-admin` instead of the broader `edgebase` package when only admin features are needed
+
+You can find it:
+
+- in this repository: [llms.txt](https://github.com/edge-base/edgebase/blob/main/packages/sdk/python/packages/admin/llms.txt)
+- in your environment after install, inside the `edgebase_admin` package directory as `llms.txt`
+
+## Installation
+
+```bash
+pip install edgebase-admin
+```
+
+## Quick Start
+
+```python
+import os
+
+from edgebase_admin import create_admin_client
+
+admin = create_admin_client(
+    "https://your-project.edgebase.fun",
+    service_key=os.environ["EDGEBASE_SERVICE_KEY"],
+)
+
+users = admin.admin_auth.list_users(limit=20)
+
+posts = (
+    admin.db("shared")
+    .table("posts")
+    .where("published", "==", True)
+    .order_by("createdAt", "desc")
+    .limit(10)
+    .get_list()
+)
+
+rows = admin.sql(
+    "shared",
+    None,
+    "SELECT COUNT(*) AS total FROM posts WHERE published = ?",
+    [1],
+)
+
+bucket = admin.storage().bucket("avatars")
+signed = bucket.create_signed_url("user-1.jpg", expires_in="1h")
+
+print(len(users.get("users", [])), len(posts.items), rows, signed.url)
+```
+
+## Core API
+
+- `AdminClient(base_url, service_key=...)`
+  Main admin entry point
+- `create_admin_client(base_url, service_key=...)`
+  Convenience helper matching the public docs
+- `admin.admin_auth`
+  Admin user management
+- `admin.db(namespace="shared", instance_id=None).table(name)`
+  Service-key database access
+- `admin.storage()`
+  Storage bucket access
+- `admin.sql(namespace="shared", instance_id=None, query="", params=None)`
+  Raw SQL
+- `admin.functions()`
+  Call app functions from trusted code
+- `admin.analytics()`
+  Query request metrics and track custom events
+- `admin.push()`
+  Send push notifications and inspect logs
+- `admin.kv(namespace)`, `admin.d1(database)`, `admin.vector(index)` / `admin.vectorize(index)`
+  Native Cloudflare resources
+
+## Requirements
+
+- Python `3.10+`
+- `edgebase-core>=0.1.3,<0.2.0`
+- A valid EdgeBase Service Key

edgebase_admin-0.1.3/README.md

@@ -0,0 +1,117 @@
+# edgebase-admin
+
+Server-only Python admin SDK for EdgeBase.
+
+Use `edgebase-admin` from trusted environments that hold a Service Key, such as backend APIs, cron jobs, workers, and operational tooling. It exposes admin auth, service-key database access, storage management, raw SQL, functions, analytics, push, and native Cloudflare resources.
+
+If you want the unified package that also includes the higher-level `EdgeBaseServer` entry point and room helpers, install [`edgebase`](https://pypi.org/project/edgebase/) instead.
+
+## Documentation Map
+
+Use this README for the fast overview, then jump into the docs when you need depth:
+
+- [SDK Overview](https://edgebase.fun/docs/sdks)
+  Install commands and language matrix for all public SDKs
+- [Admin SDK](https://edgebase.fun/docs/sdks/client-vs-server)
+  Service-key concepts, trust boundaries, and admin-only capabilities
+- [Admin SDK Reference](https://edgebase.fun/docs/admin-sdk/reference)
+  Cross-language auth, database, storage, functions, and push examples
+- [Admin User Management](https://edgebase.fun/docs/authentication/admin-users)
+  Create, update, delete, and manage users with the Service Key
+- [Database Admin SDK](https://edgebase.fun/docs/database/admin-sdk)
+  Table queries, filters, pagination, batch writes, and raw SQL
+- [Storage](https://edgebase.fun/docs/storage/upload-download)
+  Uploads, downloads, metadata, and signed URLs
+- [Analytics Admin SDK](https://edgebase.fun/docs/analytics/admin-sdk)
+  Request metrics, event tracking, and event queries
+- [Push Admin SDK](https://edgebase.fun/docs/push/admin-sdk)
+  Push send, topic broadcast, token inspection, and logs
+- [Native Resources](https://edgebase.fun/docs/server/native-resources)
+  KV, D1, Vectorize, and other edge-native resources
+
+## For AI Coding Assistants
+
+This package includes an `llms.txt` file for AI-assisted development.
+
+Use it when you want an agent or code assistant to:
+
+- use the right Python admin method signatures
+- remember which surfaces are properties vs methods
+- avoid copying JavaScript or Go API shapes into Python
+- choose `edgebase-admin` instead of the broader `edgebase` package when only admin features are needed
+
+You can find it:
+
+- in this repository: [llms.txt](https://github.com/edge-base/edgebase/blob/main/packages/sdk/python/packages/admin/llms.txt)
+- in your environment after install, inside the `edgebase_admin` package directory as `llms.txt`
+
+## Installation
+
+```bash
+pip install edgebase-admin
+```
+
+## Quick Start
+
+```python
+import os
+
+from edgebase_admin import create_admin_client
+
+admin = create_admin_client(
+    "https://your-project.edgebase.fun",
+    service_key=os.environ["EDGEBASE_SERVICE_KEY"],
+)
+
+users = admin.admin_auth.list_users(limit=20)
+
+posts = (
+    admin.db("shared")
+    .table("posts")
+    .where("published", "==", True)
+    .order_by("createdAt", "desc")
+    .limit(10)
+    .get_list()
+)
+
+rows = admin.sql(
+    "shared",
+    None,
+    "SELECT COUNT(*) AS total FROM posts WHERE published = ?",
+    [1],
+)
+
+bucket = admin.storage().bucket("avatars")
+signed = bucket.create_signed_url("user-1.jpg", expires_in="1h")
+
+print(len(users.get("users", [])), len(posts.items), rows, signed.url)
+```
+
+## Core API
+
+- `AdminClient(base_url, service_key=...)`
+  Main admin entry point
+- `create_admin_client(base_url, service_key=...)`
+  Convenience helper matching the public docs
+- `admin.admin_auth`
+  Admin user management
+- `admin.db(namespace="shared", instance_id=None).table(name)`
+  Service-key database access
+- `admin.storage()`
+  Storage bucket access
+- `admin.sql(namespace="shared", instance_id=None, query="", params=None)`
+  Raw SQL
+- `admin.functions()`
+  Call app functions from trusted code
+- `admin.analytics()`
+  Query request metrics and track custom events
+- `admin.push()`
+  Send push notifications and inspect logs
+- `admin.kv(namespace)`, `admin.d1(database)`, `admin.vector(index)` / `admin.vectorize(index)`
+  Native Cloudflare resources
+
+## Requirements
+
+- Python `3.10+`
+- `edgebase-core>=0.1.3,<0.2.0`
+- A valid EdgeBase Service Key

edgebase_admin-0.1.3/llms.txt

@@ -0,0 +1,170 @@
+# edgebase-admin
+
+Use this file as a quick-reference contract for AI coding assistants working with the `edgebase-admin` Python package.
+
+## Package Boundary
+
+Use `edgebase-admin` for trusted, service-key-backed server workloads.
+
+This package is the slim Python admin SDK. It is the right choice when you need admin auth, service-key database access, storage management, raw SQL, functions, analytics, push, or native Cloudflare resources without the broader `edgebase` package.
+
+## Source Of Truth
+
+- Package README: https://github.com/edge-base/edgebase/blob/main/packages/sdk/python/packages/admin/README.md
+- SDK overview: https://edgebase.fun/docs/sdks
+- Admin SDK guide: https://edgebase.fun/docs/sdks/client-vs-server
+- Admin SDK reference: https://edgebase.fun/docs/admin-sdk/reference
+- Admin users: https://edgebase.fun/docs/authentication/admin-users
+- Database admin SDK: https://edgebase.fun/docs/database/admin-sdk
+- Storage: https://edgebase.fun/docs/storage/upload-download
+- Analytics admin SDK: https://edgebase.fun/docs/analytics/admin-sdk
+- Push admin SDK: https://edgebase.fun/docs/push/admin-sdk
+- Native resources: https://edgebase.fun/docs/server/native-resources
+
+If docs, snippets, and assumptions disagree, prefer the current package API over guessed patterns from another runtime.
+
+## Canonical Examples
+
+### Create an admin client
+
+```python
+import os
+
+from edgebase_admin import create_admin_client
+
+admin = create_admin_client(
+    "https://your-project.edgebase.fun",
+    service_key=os.environ["EDGEBASE_SERVICE_KEY"],
+)
+```
+
+### Query data
+
+```python
+posts = (
+    admin.db("shared")
+    .table("posts")
+    .where("published", "==", True)
+    .order_by("createdAt", "desc")
+    .limit(20)
+    .get_list()
+)
+```
+
+### Manage users
+
+```python
+page = admin.admin_auth.list_users(limit=20)
+
+user = admin.admin_auth.create_user(
+    "june@example.com",
+    "securePassword",
+    data={"displayName": "June", "role": "editor"},
+)
+
+admin.admin_auth.set_custom_claims(user["id"], {"plan": "pro"})
+```
+
+### Storage
+
+```python
+bucket = admin.storage().bucket("avatars")
+
+bucket.upload("user-1.jpg", file_bytes, content_type="image/jpeg")
+signed = bucket.create_signed_url("user-1.jpg", expires_in="1h")
+```
+
+### Functions and analytics
+
+```python
+result = admin.functions().post("jobs/send-welcome-email", {"userId": "user-123"})
+
+admin.analytics().track(
+    "user_upgraded",
+    {"plan": "pro", "amount": 29.99},
+    user_id="user_123",
+)
+```
+
+### Native resources
+
+```python
+admin.kv("cache").set("homepage", "ready", ttl=300)
+rows = admin.d1("analytics").query("SELECT 1", [])
+matches = admin.vector("embeddings").search([0.1, 0.2, 0.3], top_k=5)
+```
+
+## Common Mistakes
+
+- use `create_admin_client(...)` or `AdminClient(...)`, not a browser/client SDK factory
+- `admin.admin_auth` is a property, not a method
+- `admin.storage()`, `admin.functions()`, `admin.analytics()`, and `admin.push()` are methods
+- `admin.db(namespace="shared", instance_id=None)` uses an optional positional instance id
+- `table.get()` returns `ListResult`, not a single record
+- use `table.get_one(id)` or `table.doc(id).get()` for a single record
+- `AdminClient.sql(...)` requires a non-empty query string
+- `admin.admin_auth.create_user(...)` accepts optional profile fields via `data=...`
+- `create_signed_upload_url(path, expires_in=...)` expects seconds as an `int`
+- `admin.vector(...)` and `admin.vectorize(...)` are both valid; `vectorize()` is just an alias
+
+## Quick Reference
+
+```python
+# Initialize
+admin = create_admin_client(base_url, service_key=service_key)
+
+# Admin auth (property)
+admin.admin_auth.get_user(user_id)                           # dict
+admin.admin_auth.create_user(email, password, data=None)     # dict
+admin.admin_auth.update_user(user_id, data)                  # dict
+admin.admin_auth.delete_user(user_id)                        # dict
+admin.admin_auth.list_users(limit=20, cursor=None)           # dict
+admin.admin_auth.set_custom_claims(user_id, claims)          # None
+admin.admin_auth.revoke_all_sessions(user_id)                # None
+admin.admin_auth.disable_mfa(user_id)                        # None
+
+# Database
+admin.db("shared").table("posts").get_list()                 # ListResult
+admin.db("shared").table("posts").get_one("id-1")           # dict
+admin.db("shared").table("posts").insert(record)            # dict
+admin.db("shared").table("posts").update("id-1", data)      # dict
+admin.db("shared").table("posts").delete("id-1")            # dict
+admin.sql("shared", None, query, params)                    # list
+
+# Storage
+bucket = admin.storage().bucket("avatars")
+bucket.get_url("user-1.jpg")                                # str
+bucket.upload("user-1.jpg", file_bytes, content_type="image/jpeg")   # dict
+bucket.download("user-1.jpg")                               # bytes
+bucket.get_metadata("user-1.jpg")                           # FileInfo
+bucket.update_metadata("user-1.jpg", metadata)              # dict
+bucket.list(prefix="", limit=100, offset=0)                 # list[FileInfo]
+bucket.list_page(prefix="", limit=100, cursor=None)         # FileListResult
+bucket.create_signed_url("user-1.jpg", expires_in="1h")     # SignedUrlResult
+bucket.create_signed_upload_url("large.zip", expires_in=600) # SignedUrlResult
+
+# Functions / analytics / push
+admin.functions().get("health", query=None)                 # Any
+admin.functions().post("jobs/run", body={})                 # Any
+admin.analytics().overview(range="7d")                      # dict
+admin.analytics().track(name, properties=None, user_id=None) # None
+admin.analytics().track_batch(events)                       # None
+admin.analytics().query_events(metric="list", range="7d")   # Any
+admin.push().send(user_id, payload)                         # dict
+admin.push().send_many(user_ids, payload)                   # dict
+admin.push().send_to_token(token, payload, platform=None)   # dict
+admin.push().send_to_topic(topic, payload)                  # dict
+admin.push().broadcast(payload)                             # dict
+admin.push().get_tokens(user_id)                            # list[dict]
+admin.push().get_logs(user_id, limit=None)                  # list[dict]
+
+# Native resources
+admin.kv("cache").get("key")                                # str | None
+admin.kv("cache").set("key", "value", ttl=300)              # None
+admin.kv("cache").list(prefix=None, limit=None, cursor=None) # dict
+admin.kv("cache").delete("key")                             # None
+admin.d1("analytics").exec("SELECT 1", [])                  # list
+admin.d1("analytics").query("SELECT 1", [])                 # list
+admin.vector("embeddings").search([0.1, 0.2], top_k=5)      # list[dict]
+admin.vectorize("embeddings").search([0.1, 0.2], top_k=5)   # list[dict]
+```

edgebase_admin-0.1.3/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "edgebase-admin"
+version = "0.1.3"
+description = "Python admin SDK for EdgeBase service-key workloads"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "EdgeBase Team" }
+]
+dependencies = ["edgebase-core>=0.1.3,<0.2.0"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/edgebase_admin", "README.md", "llms.txt"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/edgebase_admin"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"llms.txt" = "edgebase_admin/llms.txt"

edgebase_admin-0.1.3/src/edgebase_admin/__init__.py

@@ -0,0 +1,23 @@
+"""EdgeBase Admin SDK — admin auth, KV, D1, Vectorize."""
+
+from edgebase_admin.admin_auth import AdminAuthClient
+from edgebase_admin.analytics import AnalyticsClient
+from edgebase_admin.admin_client import AdminClient, DbRef, create_admin_client
+from edgebase_admin.kv import KvClient
+from edgebase_admin.d1 import D1Client
+from edgebase_admin.functions import FunctionsClient
+from edgebase_admin.vectorize import VectorizeClient
+from edgebase_admin.push import PushClient
+
+__all__ = [
+    "AdminAuthClient",
+    "AnalyticsClient",
+    "AdminClient",
+    "DbRef",
+    "create_admin_client",
+    "KvClient",
+    "D1Client",
+    "FunctionsClient",
+    "VectorizeClient",
+    "PushClient",
+]

edgebase_admin-0.1.3/src/edgebase_admin/admin_auth.py

@@ -0,0 +1,137 @@
+"""Admin authentication client — Service Key-based user management.
+
+Python SDK is server-only: AdminAuthClient validates the service key is present
+before making any request. Without a service key the server always returns 403,
+so we short-circuit locally to save a round-trip and give a clear error.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from edgebase_core.errors import EdgeBaseError
+from edgebase_core.http_client import HttpClient
+
+
+class AdminAuthClient:
+    """Admin auth — server-side user management via Service Key.
+
+    Usage::
+
+        user = admin.admin_auth.get_user("user-id")
+        new_user = admin.admin_auth.create_user(
+            email="admin@example.com", password="secure"
+        )
+        admin.admin_auth.set_custom_claims("user-id", {"role": "pro"})
+        admin.admin_auth.revoke_all_sessions("user-id")
+    """
+
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    # ── Guard ─────────────────────────────────────────────────────────────────
+
+    def _require_service_key(self) -> None:
+        """Raise EdgeBaseError(403) locally if no service key is configured.
+
+        All admin operations require a service key.
+        Failing fast here avoids an unnecessary network round-trip and surfaces
+        the misconfiguration immediately with a clear error message.
+        """
+        if not getattr(self._client, "_service_key", None):
+            raise EdgeBaseError(
+                status_code=403,
+                message="Service Key required for admin operations. "
+                "Pass service_key= when constructing EdgeBaseServer.",
+            )
+
+    @staticmethod
+    def _unwrap_user_payload(payload: dict[str, Any]) -> dict[str, Any]:
+        user = payload.get("user")
+        if isinstance(user, dict):
+            merged = dict(user)
+            for key, value in payload.items():
+                if key != "user" and key not in merged:
+                    merged[key] = value
+            return merged
+        return payload
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def get_user(self, user_id: str) -> dict[str, Any]:
+        """Get a user by ID."""
+        self._require_service_key()
+        result = self._client.get(f"/auth/admin/users/{user_id}")
+        return self._unwrap_user_payload(result if isinstance(result, dict) else {})
+
+    def create_user(
+        self,
+        email: str,
+        password: str,
+        data: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new user."""
+        self._require_service_key()
+        body: dict[str, Any] = {"email": email, "password": password}
+        if data:
+            body["data"] = data
+        result = self._client.post("/auth/admin/users", body)
+        return self._unwrap_user_payload(result if isinstance(result, dict) else {})
+
+    def update_user(self, user_id: str, data: dict[str, Any]) -> dict[str, Any]:
+        """Update a user."""
+        self._require_service_key()
+        result = self._client.patch(f"/auth/admin/users/{user_id}", data)
+        return self._unwrap_user_payload(result if isinstance(result, dict) else {})
+
+    def delete_user(self, user_id: str) -> dict[str, Any]:
+        """Delete a user."""
+        self._require_service_key()
+        return self._client.delete(f"/auth/admin/users/{user_id}")
+
+    def list_users(
+        self,
+        limit: int = 20,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """List users with cursor-based pagination.
+
+        Args:
+            limit: Maximum number of users to return (default 20).
+            cursor: Pagination cursor from previous response.
+
+        Returns:
+            Dict with 'users' list and optional 'cursor' for next page.
+        """
+        self._require_service_key()
+        params: dict[str, str] = {"limit": str(limit)}
+        if cursor:
+            params["cursor"] = cursor
+        result = self._client.get("/auth/admin/users", params)
+        return result if isinstance(result, dict) else {"users": [], "cursor": None}
+
+    def set_custom_claims(
+        self,
+        user_id: str,
+        claims: dict[str, Any],
+    ) -> None:
+        """Set custom claims for a user (reflected in JWT on next token refresh)."""
+        self._require_service_key()
+        self._client.put(f"/auth/admin/users/{user_id}/claims", claims)
+
+    def revoke_all_sessions(self, user_id: str) -> None:
+        """Revoke all sessions for a user (force re-authentication)."""
+        self._require_service_key()
+        self._client.post(f"/auth/admin/users/{user_id}/revoke")
+
+    def disable_mfa(self, user_id: str) -> None:
+        """Disable MFA for a user (admin operation via Service Key).
+
+        Removes all MFA factors for the specified user, allowing them
+        to sign in without MFA verification.
+
+        Args:
+            user_id: The user's ID whose MFA should be disabled.
+        """
+        self._require_service_key()
+        self._client.delete(f"/auth/admin/users/{user_id}/mfa")