rafikidb 0.1.0__tar.gz

rafikidb-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+.env.*
+!.env.example
+node_modules/
+frontend/node_modules/
+landing/node_modules/
+sdks/js/node_modules/
+backend/tmp/
+vendor/
+sdks/php/vendor/

rafikidb-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: rafikidb
+Version: 0.1.0
+Summary: Typed Python client for RafikiDB - data, auth, realtime, storage, env vars, secrets, webhooks, edge functions and payments.
+Author: RafikiDB
+License: MIT
+Keywords: baas,backend,database,rafikidb,realtime
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: realtime
+Requires-Dist: websockets>=12.0; extra == 'realtime'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# rafikidb
+
+Typed Python client for [RafikiDB](https://rafikidb.com) - data, auth,
+realtime, storage, environment variables, secrets, webhooks, edge functions
+and payments.
+
+- **Zero required dependencies** (stdlib HTTP)
+- Optional `websockets` for the WebSocket realtime transport
+- Same envelope and error model as the REST API
+- Python 3.10+
+
+## Install
+
+```bash
+pip install rafikidb            # core
+pip install rafikidb[realtime]  # with WebSocket realtime
+```
+
+## Quick start
+
+```python
+from rafikidb import create_client
+
+db = create_client(
+    project_id="5c73dab0-...",
+    api_key="raf_live_...",
+    base_url="https://api.rafikidb.com/api/v1",  # optional
+)
+```
+
+Every call returns an `Envelope`:
+
+```python
+rows = db.from_("profiles").select("id, nationality").eq("nationality", "Tanzania").limit(25).execute()
+rows.success      # True
+rows.data         # list of dicts
+rows.message      # "Request was successful"
+```
+
+Failures raise `RafikiDBError` with `message`, `status`, `code` and `errors`.
+
+## Data
+
+```python
+# Filters: eq, neq, gt, gte, lt, lte, like, ilike, is_null, is_not_null, in_
+db.from_("profiles").eq("nationality", "Tanzania").is_not_null("user_id")
+
+# Ordering and pagination
+db.from_("profiles").order("created_at", ascending=False).limit(50).offset(100)
+
+# Keyset pagination (O(1) per page on large tables)
+db.from_("logs").select("id").limit(100).cursor(last_id)
+
+# Joins (column-based, no SQL)
+from rafikidb import JoinSpec
+rows = (
+    db.from_("messages")
+    .select("id as message_id, message, users.full_name as full_name")
+    .join(JoinSpec(table="users", from_column="user_id", to_column="id"))
+    .limit(20)
+).execute()
+# rows.data[i]["full_name"]
+
+# Row operations
+db.from_("profiles").get(record_id)
+db.from_("profiles").single()
+db.from_("profiles").head()              # {"count": n}
+db.from_("profiles").insert({...})       # single or list
+db.from_("profiles").update({...}).eq("id", record_id)
+db.from_("profiles").delete().eq("id", record_id)
+```
+
+## Auth
+
+```python
+session = db.auth.signup(
+    email="user@example.com", password="strong-pass1",
+    full_name="Asha Mwinyi", phone="+255712345678",
+)
+session = db.auth.login(email="user@example.com", password="strong-pass1")
+
+# The session is stored on the client and sent with every request,
+# so RLS sees the logged-in user.
+db.client.access_token     # the project-user JWT
+
+db.auth.sign_out()
+
+# OTP
+db.auth.otp_request("+255712345678")
+db.auth.otp_verify(phone="+255712345678", code="123456", full_name="Asha Mwinyi")
+
+# Password reset
+db.auth.reset_password("user@example.com")
+db.auth.confirm_reset_password(email="user@example.com", code="123456", new_password="brand-new-pass1")
+```
+
+## Realtime
+
+```python
+def on_event(event):
+    print(event.type, event.table, event.record)
+
+sub = db.realtime.subscribe("messages", on_event, events=["INSERT", "DELETE"])
+
+# Stop listening (or sub.wait() to block)
+sub.close()
+```
+
+Default transport: WebSocket when `websockets` is installed, SSE otherwise.
+
+```python
+db.realtime.subscribe("messages", on_event, transport="sse")
+db.realtime.subscribe("messages", on_event, transport="websocket")
+```
+
+## Storage / env / secrets / webhooks / functions / payments
+
+```python
+db.storage.create_bucket(name="Avatars", slug="avatars", is_public=True)
+db.storage.signed_upload_url(bucket_id=..., object_name="user-1.png")
+
+db.env.set("STRIPE_KEY", "sk_test_123", environment="production")
+db.env.bulk_set("development", {"DEBUG": "true"})
+
+db.secrets.set(key="API_SECRET", value="s3cr3t")
+db.secrets.reveal(secret_id)
+
+db.webhooks.create(name="order.created", url="https://myapp.com/hooks/orders", events=["order.created"])
+db.webhooks.list_deliveries(webhook_id)
+
+db.functions.create(name="hello", runtime="javascript", code="...")
+db.functions.deploy(fn_id)
+db.functions.invoke(fn_id, body='{"name":"Asha"}')
+
+db.payments.stk_push(phone="+255712345678", amount=5000, description="Order #123")
+db.payments.snippe_status(reference)
+db.payments.list_transactions()
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m unittest discover -s tests -q
+```

rafikidb-0.1.0/README.md

@@ -0,0 +1,145 @@
+# rafikidb
+
+Typed Python client for [RafikiDB](https://rafikidb.com) - data, auth,
+realtime, storage, environment variables, secrets, webhooks, edge functions
+and payments.
+
+- **Zero required dependencies** (stdlib HTTP)
+- Optional `websockets` for the WebSocket realtime transport
+- Same envelope and error model as the REST API
+- Python 3.10+
+
+## Install
+
+```bash
+pip install rafikidb            # core
+pip install rafikidb[realtime]  # with WebSocket realtime
+```
+
+## Quick start
+
+```python
+from rafikidb import create_client
+
+db = create_client(
+    project_id="5c73dab0-...",
+    api_key="raf_live_...",
+    base_url="https://api.rafikidb.com/api/v1",  # optional
+)
+```
+
+Every call returns an `Envelope`:
+
+```python
+rows = db.from_("profiles").select("id, nationality").eq("nationality", "Tanzania").limit(25).execute()
+rows.success      # True
+rows.data         # list of dicts
+rows.message      # "Request was successful"
+```
+
+Failures raise `RafikiDBError` with `message`, `status`, `code` and `errors`.
+
+## Data
+
+```python
+# Filters: eq, neq, gt, gte, lt, lte, like, ilike, is_null, is_not_null, in_
+db.from_("profiles").eq("nationality", "Tanzania").is_not_null("user_id")
+
+# Ordering and pagination
+db.from_("profiles").order("created_at", ascending=False).limit(50).offset(100)
+
+# Keyset pagination (O(1) per page on large tables)
+db.from_("logs").select("id").limit(100).cursor(last_id)
+
+# Joins (column-based, no SQL)
+from rafikidb import JoinSpec
+rows = (
+    db.from_("messages")
+    .select("id as message_id, message, users.full_name as full_name")
+    .join(JoinSpec(table="users", from_column="user_id", to_column="id"))
+    .limit(20)
+).execute()
+# rows.data[i]["full_name"]
+
+# Row operations
+db.from_("profiles").get(record_id)
+db.from_("profiles").single()
+db.from_("profiles").head()              # {"count": n}
+db.from_("profiles").insert({...})       # single or list
+db.from_("profiles").update({...}).eq("id", record_id)
+db.from_("profiles").delete().eq("id", record_id)
+```
+
+## Auth
+
+```python
+session = db.auth.signup(
+    email="user@example.com", password="strong-pass1",
+    full_name="Asha Mwinyi", phone="+255712345678",
+)
+session = db.auth.login(email="user@example.com", password="strong-pass1")
+
+# The session is stored on the client and sent with every request,
+# so RLS sees the logged-in user.
+db.client.access_token     # the project-user JWT
+
+db.auth.sign_out()
+
+# OTP
+db.auth.otp_request("+255712345678")
+db.auth.otp_verify(phone="+255712345678", code="123456", full_name="Asha Mwinyi")
+
+# Password reset
+db.auth.reset_password("user@example.com")
+db.auth.confirm_reset_password(email="user@example.com", code="123456", new_password="brand-new-pass1")
+```
+
+## Realtime
+
+```python
+def on_event(event):
+    print(event.type, event.table, event.record)
+
+sub = db.realtime.subscribe("messages", on_event, events=["INSERT", "DELETE"])
+
+# Stop listening (or sub.wait() to block)
+sub.close()
+```
+
+Default transport: WebSocket when `websockets` is installed, SSE otherwise.
+
+```python
+db.realtime.subscribe("messages", on_event, transport="sse")
+db.realtime.subscribe("messages", on_event, transport="websocket")
+```
+
+## Storage / env / secrets / webhooks / functions / payments
+
+```python
+db.storage.create_bucket(name="Avatars", slug="avatars", is_public=True)
+db.storage.signed_upload_url(bucket_id=..., object_name="user-1.png")
+
+db.env.set("STRIPE_KEY", "sk_test_123", environment="production")
+db.env.bulk_set("development", {"DEBUG": "true"})
+
+db.secrets.set(key="API_SECRET", value="s3cr3t")
+db.secrets.reveal(secret_id)
+
+db.webhooks.create(name="order.created", url="https://myapp.com/hooks/orders", events=["order.created"])
+db.webhooks.list_deliveries(webhook_id)
+
+db.functions.create(name="hello", runtime="javascript", code="...")
+db.functions.deploy(fn_id)
+db.functions.invoke(fn_id, body='{"name":"Asha"}')
+
+db.payments.stk_push(phone="+255712345678", amount=5000, description="Order #123")
+db.payments.snippe_status(reference)
+db.payments.list_transactions()
+```
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m unittest discover -s tests -q
+```

rafikidb-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rafikidb"
+version = "0.1.0"
+description = "Typed Python client for RafikiDB - data, auth, realtime, storage, env vars, secrets, webhooks, edge functions and payments."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "RafikiDB" }]
+keywords = ["rafikidb", "baas", "backend", "database", "realtime"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+realtime = ["websockets>=12.0"]
+test = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["rafikidb"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rafikidb-0.1.0/rafikidb/__init__.py

@@ -0,0 +1,78 @@
+"""RafikiDB Python SDK - typed client for data, auth, realtime, storage, env
+vars, secrets, webhooks, edge functions and payments."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, TypeVar
+
+from .client import DEFAULT_BASE, RafikiDBClient
+from .types import (
+    AuthSession,
+    Envelope,
+    JoinSpec,
+    ProjectTokens,
+    ProjectUser,
+    RafikiDBError,
+    RealtimeEvent,
+    Record,
+)
+from .data import DataBuilder
+from .auth import Auth
+from .realtime import Realtime, Subscription
+from .modules import Storage, Env, Secrets, Webhooks, Functions, Payments
+
+__all__ = [
+    "create_client",
+    "RafikiDBError",
+    "Envelope",
+    "AuthSession",
+    "ProjectUser",
+    "ProjectTokens",
+    "RealtimeEvent",
+    "Record",
+    "JoinSpec",
+    "DEFAULT_BASE",
+]
+
+R = TypeVar("R", bound=Record)
+
+
+class RafikiDB:
+    """Facade returned by create_client()."""
+
+    def __init__(self, client: RafikiDBClient):
+        self.client = client
+        self.auth = Auth(client)
+        self.realtime = Realtime(client)
+        self.storage = Storage(client)
+        self.env = Env(client)
+        self.secrets = Secrets(client)
+        self.webhooks = Webhooks(client)
+        self.functions = Functions(client)
+        self.payments = Payments(client)
+
+    def from_(self, table: str) -> DataBuilder:
+        """Typed data builder: `db.from_("messages").select(...).eq(...)`"""
+        return DataBuilder(self.client, table)
+
+    def request(self, path: str, method: str = "GET", body: Optional[Dict[str, Any]] = None) -> Envelope[Any]:
+        return self.client.request(path, method=method, body=body)
+
+
+def create_client(
+    project_id: str,
+    api_key: str,
+    base_url: Optional[str] = None,
+    session: Optional[Dict[str, Any]] = None,
+    timeout: float = 30.0,
+) -> RafikiDB:
+    """Create a typed RafikiDB client.
+
+    Example:
+        db = create_client(
+            project_id="5c73dab0-...",
+            api_key="raf_live_...",
+            base_url="https://api.rafikidb.com/api/v1",
+        )
+    """
+    return RafikiDB(RafikiDBClient(project_id, api_key, base_url, session, timeout))

rafikidb-0.1.0/rafikidb/auth.py

@@ -0,0 +1,107 @@
+"""Auth flows for the RafikiDB Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .client import RafikiDBClient
+from .types import AuthSession, Envelope, ProjectTokens
+
+
+class Auth:
+    """Project auth: signup, login, OTP, password reset. Sessions are stored
+    on the client automatically and sent with every request."""
+
+    def __init__(self, client: RafikiDBClient):
+        self._client = client
+
+    def signup(
+        self,
+        email: str,
+        password: str,
+        full_name: str,
+        phone: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Envelope[AuthSession]:
+        env = self._client.post(
+            f"/projects/{self._client.project_id}/auth/signup",
+            body={
+                "email": email,
+                "password": password,
+                "full_name": full_name,
+                "phone": phone,
+                "metadata": metadata,
+            },
+        )
+        session_env = self._to_session(env)
+        self._store_session(session_env)
+        return session_env
+
+    def login(self, email: str, password: str) -> Envelope[AuthSession]:
+        """Sign an end-user of THIS project in (POST /auth/signin)."""
+        env = self._client.post(
+            f"/projects/{self._client.project_id}/auth/signin",
+            body={"email": email, "password": password},
+        )
+        session_env = self._to_session(env)
+        self._store_session(session_env)
+        return session_env
+
+    signin = login
+
+    def otp_request(self, phone: str) -> Envelope[Dict[str, Any]]:
+        return self._client.post(
+            f"/projects/{self._client.project_id}/auth/otp/request",
+            body={"phone": phone},
+        )
+
+    def otp_verify(self, phone: str, code: str, full_name: str, metadata: Optional[Dict[str, Any]] = None) -> Envelope[AuthSession]:
+        env = self._client.post(
+            f"/projects/{self._client.project_id}/auth/otp/verify",
+            body={"phone": phone, "code": code, "full_name": full_name, "metadata": metadata},
+        )
+        session_env = self._to_session(env)
+        self._store_session(session_env)
+        return session_env
+
+    def reset_password(self, email: str) -> Envelope[Dict[str, Any]]:
+        return self._client.post(
+            f"/projects/{self._client.project_id}/auth/reset-password",
+            body={"email": email},
+        )
+
+    def confirm_reset_password(self, email: str, code: str, new_password: str) -> Envelope[Dict[str, Any]]:
+        return self._client.post(
+            f"/projects/{self._client.project_id}/auth/reset-password/confirm",
+            body={"email": email, "code": code, "new_password": new_password},
+        )
+
+    def sign_out(self) -> None:
+        """Clear the stored project-user session."""
+        self._client.set_session(None)
+
+    def refresh(self, refresh_token: str) -> Envelope[ProjectTokens]:
+        return self._client.post("/auth/refresh", body={"refresh_token": refresh_token})
+
+    def logout(self, refresh_token: str) -> Envelope[None]:
+        return self._client.post("/auth/logout", body={"refresh_token": refresh_token})
+
+    # -- internals ----------------------------------------------------------
+
+    def _store_session(self, env: Envelope[AuthSession]) -> None:
+        if env.data and env.data.tokens.access_token:
+            self._client.set_session(
+                {
+                    "user": {
+                        k: v for k, v in env.data.user.__dict__.items()
+                        if not k.startswith("_")
+                    },
+                    "tokens": env.data.tokens.__dict__,
+                }
+            )
+
+    def _to_session(self, env: Envelope[Any]) -> Envelope[AuthSession]:
+        if env.data and isinstance(env.data, dict):
+            session = AuthSession.from_payload(env.data)
+            return Envelope(env.success, env.message, session, env.errors)
+        return Envelope(env.success, env.message, env.data, env.errors)

rafikidb-0.1.0/rafikidb/client.py

@@ -0,0 +1,115 @@
+"""HTTP client for the RafikiDB Python SDK (stdlib only)."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+from .types import Envelope, RafikiDBError
+
+DEFAULT_BASE = "http://localhost:8080/api/v1"
+
+
+class RafikiDBClient:
+    """Low-level HTTP client. Sends the API key and optional session token."""
+
+    def __init__(
+        self,
+        project_id: str,
+        api_key: str,
+        base_url: Optional[str] = None,
+        session: Optional[Dict[str, Any]] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.project_id = project_id
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE).rstrip("/")
+        self.timeout = timeout
+        self._session: Optional[Dict[str, Any]] = session
+
+    # -- session ------------------------------------------------------------
+
+    @property
+    def session(self) -> Optional[Dict[str, Any]]:
+        return self._session
+
+    def set_session(self, session: Optional[Dict[str, Any]]) -> None:
+        self._session = session
+
+    @property
+    def access_token(self) -> Optional[str]:
+        if self._session:
+            return self._session.get("tokens", {}).get("access_token")
+        return None
+
+    # -- request ------------------------------------------------------------
+
+    def request(
+        self,
+        path: str,
+        method: str = "GET",
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, str]] = None,
+    ) -> Envelope[Any]:
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+
+        headers = {
+            "X-AFRIBASE-API-Key": self.api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        token = self.access_token
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+        status: Optional[int] = None
+        payload: Dict[str, Any] = {}
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                status = resp.status
+                raw = resp.read()
+                if raw:
+                    payload = json.loads(raw)
+        except urllib.error.HTTPError as err:
+            status = err.code
+            raw = err.read()
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError:
+                payload = {}
+        except urllib.error.URLError as err:
+            raise RafikiDBError(f"Connection error: {err.reason}", 0) from err
+
+        envelope = Envelope.from_payload(payload)
+        if not envelope.success or (status is not None and status >= 400):
+            raise RafikiDBError(
+                envelope.message or f"Request failed ({status})",
+                status or 500,
+                envelope.errors,
+            )
+        return envelope
+
+    # -- typed convenience ----------------------------------------------
+
+    def get(self, path: str, query: Optional[Dict[str, str]] = None) -> Envelope[Any]:
+        return self.request(path, "GET", query=query)
+
+    def post(self, path: str, body: Optional[Dict[str, Any]] = None) -> Envelope[Any]:
+        return self.request(path, "POST", body=body)
+
+    def patch(self, path: str, body: Optional[Dict[str, Any]] = None) -> Envelope[Any]:
+        return self.request(path, "PATCH", body=body)
+
+    def put(self, path: str, body: Optional[Dict[str, Any]] = None) -> Envelope[Any]:
+        return self.request(path, "PUT", body=body)
+
+    def delete(self, path: str) -> Envelope[Any]:
+        return self.request(path, "DELETE")