bb-studio 1.0.0__py3-none-any.whl

bb_studio/__init__.py

@@ -0,0 +1,139 @@
+from .client import (
+    ApplicationProxy,
+    BBStudio,
+    BBStudioClient,
+    BBStudioError,
+    DatasetRef,
+    TransactionContext,
+    bb_above,
+    bb_atLeast,
+    bb_atMost,
+    bb_at_least,
+    bb_at_most,
+    bb_auth,
+    bb_below,
+    bb_contains,
+    bb_create,
+    bb_createMany,
+    bb_create_many,
+    bb_delete,
+    bb_deleteFile,
+    bb_deleteMany,
+    bb_delete_file,
+    bb_delete_many,
+    bb_empty,
+    bb_endsWith,
+    bb_ends_with,
+    bb_exists,
+    bb_expectedVersion,
+    bb_expected_version,
+    bb_get,
+    bb_getFileUrl,
+    bb_get_file_url,
+    bb_inside,
+    bb_invoke,
+    bb_is,
+    bb_isNot,
+    bb_isNull,
+    bb_is_not,
+    bb_is_null,
+    bb_limit,
+    bb_listFiles,
+    bb_list_files,
+    bb_noneOf,
+    bb_none_of,
+    bb_notEmpty,
+    bb_notExists,
+    bb_notNull,
+    bb_not_empty,
+    bb_not_exists,
+    bb_not_null,
+    bb_offset,
+    bb_oneOf,
+    bb_one_of,
+    bb_outside,
+    bb_sortAsc,
+    bb_sortDesc,
+    bb_sort_asc,
+    bb_sort_desc,
+    bb_startsWith,
+    bb_starts_with,
+    bb_storage,
+    bb_track,
+    bb_transaction,
+    bb_update,
+    bb_updateMany,
+    bb_update_many,
+    bb_uploadFile,
+    bb_upload_file,
+)
+
+__all__ = [
+    "ApplicationProxy",
+    "BBStudio",
+    "BBStudioClient",
+    "BBStudioError",
+    "DatasetRef",
+    "TransactionContext",
+    "bb_above",
+    "bb_atLeast",
+    "bb_atMost",
+    "bb_at_least",
+    "bb_at_most",
+    "bb_auth",
+    "bb_below",
+    "bb_contains",
+    "bb_create",
+    "bb_createMany",
+    "bb_create_many",
+    "bb_delete",
+    "bb_deleteFile",
+    "bb_deleteMany",
+    "bb_delete_file",
+    "bb_delete_many",
+    "bb_empty",
+    "bb_endsWith",
+    "bb_ends_with",
+    "bb_exists",
+    "bb_expectedVersion",
+    "bb_expected_version",
+    "bb_get",
+    "bb_getFileUrl",
+    "bb_get_file_url",
+    "bb_inside",
+    "bb_invoke",
+    "bb_is",
+    "bb_isNot",
+    "bb_isNull",
+    "bb_is_not",
+    "bb_is_null",
+    "bb_limit",
+    "bb_listFiles",
+    "bb_list_files",
+    "bb_noneOf",
+    "bb_none_of",
+    "bb_notEmpty",
+    "bb_notExists",
+    "bb_notNull",
+    "bb_not_empty",
+    "bb_not_exists",
+    "bb_not_null",
+    "bb_offset",
+    "bb_oneOf",
+    "bb_one_of",
+    "bb_outside",
+    "bb_sortAsc",
+    "bb_sortDesc",
+    "bb_sort_asc",
+    "bb_sort_desc",
+    "bb_startsWith",
+    "bb_starts_with",
+    "bb_storage",
+    "bb_track",
+    "bb_transaction",
+    "bb_update",
+    "bb_updateMany",
+    "bb_update_many",
+    "bb_uploadFile",
+    "bb_upload_file",
+]

bb_studio/client.py

@@ -0,0 +1,832 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, Union
+from urllib.parse import quote
+
+import httpx
+
+
+class BBStudioError(Exception):
+    """Structured exception raised by BB-Studio SDK operations."""
+
+    def __init__(self, code: str, message: str, status_code: Optional[int] = None) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        super().__init__(f"{code}: {message}")
+
+
+def _join_url(base: str, path: str) -> str:
+    b = (base or "").strip().rstrip("/")
+    p = (path or "").strip().lstrip("/")
+    return f"{b}/{p}" if b else f"/{p}"
+
+
+def _resolve_base_api(endpoint: str) -> str:
+    ep = (endpoint or "").strip().rstrip("/")
+    return ep if "/api/v1" in ep else _join_url(ep, "api/v1")
+
+
+@dataclass(frozen=True)
+class DatasetRef:
+    app_id: str
+    runtime_ref: str
+    dataset_name: str
+    endpoint: str
+    _bb_studio_ref: bool = True
+
+
+class ApplicationProxy:
+    def __init__(self, client: BBStudioClient, runtime_ref: str) -> None:
+        self._client = client
+        self._app_id = client.application_id
+        self._runtime_ref = runtime_ref
+        self.endpoint = client.endpoint
+
+    def dataset(self, name: str) -> DatasetRef:
+        return DatasetRef(
+            app_id=self._app_id,
+            runtime_ref=self._runtime_ref,
+            dataset_name=name,
+            endpoint=self.endpoint,
+        )
+
+    def __getattr__(self, name: str) -> DatasetRef:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return self.dataset(name)
+
+
+class BBStudioClient:
+    def __init__(
+        self,
+        application: str,
+        endpoint: str,
+        timeout: float = 30.0,
+    ) -> None:
+        if not application or not application.strip():
+            raise ValueError("BBStudio application ID is required.")
+        ep = (endpoint or "").strip().rstrip("/")
+        if not ep:
+            raise ValueError("BBStudio backend endpoint is required and cannot be empty.")
+        self.application_id = application.strip()
+        self.endpoint = ep
+        self.http = httpx.Client(timeout=timeout)
+        self._tokens: Dict[str, str] = {}
+
+    def application(self, runtime_ref: str) -> ApplicationProxy:
+        return ApplicationProxy(self, runtime_ref)
+
+
+class BBStudio:
+    _default_client: Optional[BBStudioClient] = None
+
+    @classmethod
+    def initialize(
+        cls,
+        application: str,
+        endpoint: str,
+        timeout: float = 30.0,
+    ) -> BBStudioClient:
+        client = BBStudioClient(application=application, endpoint=endpoint, timeout=timeout)
+        cls._default_client = client
+        return client
+
+    @classmethod
+    def default_client(cls) -> BBStudioClient:
+        if cls._default_client is None:
+            raise BBStudioError("NOT_INITIALIZED", "Call BBStudio.initialize(...) first.")
+        return cls._default_client
+
+
+# ---------------------------------------------------------------------------
+# Condition, Sort, Pagination & Version Builders
+# ---------------------------------------------------------------------------
+
+def bb_is(field: str, value: Any) -> Dict[str, Any]:
+    return {"type": "IS", "field": field, "value": value}
+
+
+def bb_is_not(field: str, value: Any) -> Dict[str, Any]:
+    return {"type": "IS_NOT", "field": field, "value": value}
+
+
+def bb_above(field: str, value: Any) -> Dict[str, Any]:
+    return {"type": "ABOVE", "field": field, "value": value}
+
+
+def bb_below(field: str, value: Any) -> Dict[str, Any]:
+    return {"type": "BELOW", "field": field, "value": value}
+
+
+def bb_at_least(field: str, value: Any) -> Dict[str, Any]:
+    return {"type": "AT_LEAST", "field": field, "value": value}
+
+
+def bb_at_most(field: str, value: Any) -> Dict[str, Any]:
+    return {"type": "AT_MOST", "field": field, "value": value}
+
+
+def bb_empty(field: str) -> Dict[str, Any]:
+    return {"type": "EMPTY", "field": field}
+
+
+def bb_not_empty(field: str) -> Dict[str, Any]:
+    return {"type": "NOT_EMPTY", "field": field}
+
+
+def bb_is_null(field: str) -> Dict[str, Any]:
+    return {"type": "IS_NULL", "field": field}
+
+
+def bb_not_null(field: str) -> Dict[str, Any]:
+    return {"type": "NOT_NULL", "field": field}
+
+
+def bb_inside(field: str, lower: Any, upper: Any) -> Dict[str, Any]:
+    return {"type": "INSIDE", "field": field, "lower": lower, "upper": upper}
+
+
+def bb_outside(field: str, lower: Any, upper: Any) -> Dict[str, Any]:
+    return {"type": "OUTSIDE", "field": field, "lower": lower, "upper": upper}
+
+
+def bb_one_of(field: str, values: List[Any]) -> Dict[str, Any]:
+    return {"type": "ONE_OF", "field": field, "values": values}
+
+
+def bb_none_of(field: str, values: List[Any]) -> Dict[str, Any]:
+    return {"type": "NONE_OF", "field": field, "values": values}
+
+
+def bb_contains(field: str, text: str) -> Dict[str, Any]:
+    return {"type": "CONTAINS", "field": field, "text": text}
+
+
+def bb_starts_with(field: str, text: str) -> Dict[str, Any]:
+    return {"type": "STARTS_WITH", "field": field, "text": text}
+
+
+def bb_ends_with(field: str, text: str) -> Dict[str, Any]:
+    return {"type": "ENDS_WITH", "field": field, "text": text}
+
+
+def bb_sort_asc(field: str) -> Dict[str, Any]:
+    return {"_control": "SORT", "field": field, "direction": "ASC"}
+
+
+def bb_sort_desc(field: str) -> Dict[str, Any]:
+    return {"_control": "SORT", "field": field, "direction": "DESC"}
+
+
+def bb_limit(count: int) -> Dict[str, Any]:
+    return {"_control": "LIMIT", "count": count}
+
+
+def bb_offset(count: int) -> Dict[str, Any]:
+    return {"_control": "OFFSET", "count": count}
+
+
+def bb_exists(reference: Any) -> Dict[str, Any]:
+    return {"type": "EXISTS", "reference": reference}
+
+
+def bb_not_exists(reference: Any) -> Dict[str, Any]:
+    return {"type": "NOT_EXISTS", "reference": reference}
+
+
+def bb_expected_version(version: int) -> Dict[str, Any]:
+    return {"type": "EXPECTED_VERSION", "value": version}
+
+
+# JS-style camelCase aliases
+bb_isNot = bb_is_not
+bb_atLeast = bb_at_least
+bb_atMost = bb_at_most
+bb_notEmpty = bb_not_empty
+bb_isNull = bb_is_null
+bb_notNull = bb_not_null
+bb_oneOf = bb_one_of
+bb_noneOf = bb_none_of
+bb_startsWith = bb_starts_with
+bb_endsWith = bb_ends_with
+bb_sortAsc = bb_sort_asc
+bb_sortDesc = bb_sort_desc
+bb_notExists = bb_not_exists
+bb_expectedVersion = bb_expected_version
+
+
+# ---------------------------------------------------------------------------
+# Internal HTTP Helper
+# ---------------------------------------------------------------------------
+
+def _get_http(client: Optional[BBStudioClient] = None) -> httpx.Client:
+    if client is not None:
+        return client.http
+    if BBStudio._default_client is not None:
+        return BBStudio._default_client.http
+    return httpx.Client(timeout=30.0)
+
+
+def _req(target: DatasetRef, path: str, body: Dict[str, Any]) -> Any:
+    if not isinstance(target, DatasetRef):
+        raise BBStudioError(
+            "INVALID_REFERENCE",
+            "Dataset reference invalid. Expected app.dataset (e.g. app1.users).",
+        )
+    base_api = _resolve_base_api(target.endpoint)
+    url = _join_url(base_api, f"frontend-apps/{quote(target.app_id, safe='')}/data/{path}")
+    res = _get_http().post(
+        url,
+        headers={"Content-Type": "application/json", "x-frontend-app-id": target.app_id},
+        json=body,
+    )
+    try:
+        data = res.json()
+    except Exception:
+        data = None
+    if not res.is_success:
+        raise BBStudioError(
+            (data or {}).get("code", "DATABASE_ERROR"),
+            (data or {}).get("message", f"Request failed with status {res.status_code}"),
+            res.status_code,
+        )
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Data CRUD & Batch Operations
+# ---------------------------------------------------------------------------
+
+def bb_get(target: DatasetRef, *args: Dict[str, Any]) -> Any:
+    conditions: List[Dict[str, Any]] = []
+    sorts: List[Dict[str, str]] = []
+    limit: Optional[int] = None
+    offset: Optional[int] = None
+
+    for a in args:
+        if not a:
+            continue
+        ctrl = a.get("_control")
+        if ctrl == "SORT":
+            sorts.append({"field": a["field"], "direction": a["direction"]})
+        elif ctrl == "LIMIT":
+            limit = a["count"]
+        elif ctrl == "OFFSET":
+            offset = a["count"]
+        elif a.get("type"):
+            conditions.append(a)
+
+    if not conditions:
+        raise BBStudioError("INVALID_INPUT", "At least one filter condition is required for bb_get.")
+
+    payload: Dict[str, Any] = {
+        "runtimeRef": target.runtime_ref,
+        "datasetName": target.dataset_name,
+        "conditions": conditions,
+    }
+    if sorts:
+        payload["sorts"] = sorts
+    if limit is not None:
+        payload["limit"] = limit
+    if offset is not None:
+        payload["offset"] = offset
+    return _req(target, "query", payload)
+
+
+def bb_create(target: DatasetRef, record: Dict[str, Any]) -> Any:
+    return _req(
+        target,
+        "create",
+        {"runtimeRef": target.runtime_ref, "datasetName": target.dataset_name, "record": record},
+    )
+
+
+def bb_update(target: DatasetRef, data: Dict[str, Any], *conditions: Dict[str, Any]) -> Any:
+    valid = [c for c in conditions if c and c.get("type")]
+    if not valid:
+        raise BBStudioError("INVALID_INPUT", "At least one filter condition is required for bb_update.")
+    return _req(
+        target,
+        "update",
+        {
+            "runtimeRef": target.runtime_ref,
+            "datasetName": target.dataset_name,
+            "data": data,
+            "conditions": valid,
+        },
+    )
+
+
+def bb_delete(target: DatasetRef, *conditions: Dict[str, Any]) -> Any:
+    valid = [c for c in conditions if c and c.get("type")]
+    if not valid:
+        raise BBStudioError("INVALID_INPUT", "At least one filter condition is required for bb_delete.")
+    return _req(
+        target,
+        "delete",
+        {"runtimeRef": target.runtime_ref, "datasetName": target.dataset_name, "conditions": valid},
+    )
+
+
+def bb_create_many(target: DatasetRef, records: List[Dict[str, Any]]) -> Any:
+    return _req(
+        target,
+        "batch/create",
+        {"runtimeRef": target.runtime_ref, "datasetName": target.dataset_name, "records": records},
+    )
+
+
+def bb_update_many(target: DatasetRef, data: Dict[str, Any], *conditions: Dict[str, Any]) -> Any:
+    valid = [c for c in conditions if c and c.get("type")]
+    if not valid:
+        raise BBStudioError("INVALID_INPUT", "At least one filter condition is required for bb_update_many.")
+    return _req(
+        target,
+        "batch/update",
+        {
+            "runtimeRef": target.runtime_ref,
+            "datasetName": target.dataset_name,
+            "data": data,
+            "conditions": valid,
+        },
+    )
+
+
+def bb_delete_many(target: DatasetRef, *conditions: Dict[str, Any]) -> Any:
+    valid = [c for c in conditions if c and c.get("type")]
+    if not valid:
+        raise BBStudioError("INVALID_INPUT", "At least one filter condition is required for bb_delete_many.")
+    return _req(
+        target,
+        "batch/delete",
+        {"runtimeRef": target.runtime_ref, "datasetName": target.dataset_name, "conditions": valid},
+    )
+
+
+bb_createMany = bb_create_many
+bb_updateMany = bb_update_many
+bb_deleteMany = bb_delete_many
+
+
+# ---------------------------------------------------------------------------
+# Atomic Transactions
+# ---------------------------------------------------------------------------
+
+class TransactionContext:
+    def __init__(self, op_fn: Callable[[Dict[str, Any]], Any]) -> None:
+        self._op = op_fn
+
+    @staticmethod
+    def _resolve_name(d: Union[DatasetRef, str]) -> str:
+        return d if isinstance(d, str) else d.dataset_name
+
+    def get(self, dataset: Union[DatasetRef, str], *args: Dict[str, Any]) -> Any:
+        c: List[Dict[str, Any]] = []
+        s: List[Dict[str, str]] = []
+        l: Optional[int] = None
+        o: Optional[int] = None
+        for a in args:
+            if not a:
+                continue
+            ctrl = a.get("_control")
+            if ctrl == "SORT":
+                s.append({"field": a["field"], "direction": a["direction"]})
+            elif ctrl == "LIMIT":
+                l = a["count"]
+            elif ctrl == "OFFSET":
+                o = a["count"]
+            elif a.get("type"):
+                c.append(a)
+        if not c:
+            raise BBStudioError("INVALID_INPUT", "At least one filter condition required")
+        body: Dict[str, Any] = {
+            "datasetName": self._resolve_name(dataset),
+            "operation": "GET",
+            "conditions": c,
+        }
+        if s:
+            body["sorts"] = s
+        if l is not None:
+            body["limit"] = l
+        if o is not None:
+            body["offset"] = o
+        return self._op(body)
+
+    def create(self, dataset: Union[DatasetRef, str], record: Dict[str, Any]) -> Any:
+        return self._op({"datasetName": self._resolve_name(dataset), "operation": "CREATE", "record": record})
+
+    def update(self, dataset: Union[DatasetRef, str], data: Dict[str, Any], *conditions: Dict[str, Any]) -> Any:
+        c = [x for x in conditions if x and x.get("type")]
+        if not c:
+            raise BBStudioError("INVALID_INPUT", "Filter condition required")
+        return self._op(
+            {"datasetName": self._resolve_name(dataset), "operation": "UPDATE", "data": data, "conditions": c}
+        )
+
+    def delete(self, dataset: Union[DatasetRef, str], *conditions: Dict[str, Any]) -> Any:
+        c = [x for x in conditions if x and x.get("type")]
+        if not c:
+            raise BBStudioError("INVALID_INPUT", "Filter condition required")
+        return self._op({"datasetName": self._resolve_name(dataset), "operation": "DELETE", "conditions": c})
+
+    def create_many(self, dataset: Union[DatasetRef, str], records: List[Dict[str, Any]]) -> Any:
+        return self._op({"datasetName": self._resolve_name(dataset), "operation": "CREATE_MANY", "records": records})
+
+    def update_many(self, dataset: Union[DatasetRef, str], data: Dict[str, Any], *conditions: Dict[str, Any]) -> Any:
+        c = [x for x in conditions if x and x.get("type")]
+        if not c:
+            raise BBStudioError("INVALID_INPUT", "Filter condition required")
+        return self._op(
+            {"datasetName": self._resolve_name(dataset), "operation": "UPDATE_MANY", "data": data, "conditions": c}
+        )
+
+    def delete_many(self, dataset: Union[DatasetRef, str], *conditions: Dict[str, Any]) -> Any:
+        c = [x for x in conditions if x and x.get("type")]
+        if not c:
+            raise BBStudioError("INVALID_INPUT", "Filter condition required")
+        return self._op({"datasetName": self._resolve_name(dataset), "operation": "DELETE_MANY", "conditions": c})
+
+    createMany = create_many
+    updateMany = update_many
+    deleteMany = delete_many
+
+
+def bb_transaction(
+    app_ref: ApplicationProxy,
+    callback: Callable[[TransactionContext], Any],
+    idempotency_key: Optional[str] = None,
+) -> Any:
+    base_api = _resolve_base_api(app_ref.endpoint)
+    app_id = app_ref._app_id
+    http_client = app_ref._client.http
+
+    begin_res = http_client.post(
+        _join_url(base_api, f"frontend-apps/{quote(app_id, safe='')}/transactions/begin"),
+        json={"runtimeRef": app_ref._runtime_ref, "idempotencyKey": idempotency_key},
+    )
+    try:
+        begin_data = begin_res.json()
+    except Exception:
+        begin_data = {}
+    if not begin_res.is_success:
+        raise BBStudioError(
+            begin_data.get("code", "DATABASE_ERROR"),
+            begin_data.get("message", "Transaction start failed"),
+            begin_res.status_code,
+        )
+
+    tx_id = begin_data["txId"]
+    active = True
+
+    def tx_op(body: Dict[str, Any]) -> Any:
+        if not active:
+            raise BBStudioError("TRANSACTION_ABORTED", "Transaction closed")
+        r = http_client.post(
+            _join_url(base_api, f"frontend-apps/{quote(app_id, safe='')}/transactions/{quote(tx_id, safe='')}/operation"),
+            json=body,
+        )
+        try:
+            d = r.json()
+        except Exception:
+            d = {}
+        if not r.is_success:
+            raise BBStudioError(d.get("code", "DATABASE_ERROR"), d.get("message", "Operation failed"), r.status_code)
+        return d
+
+    try:
+        res = callback(TransactionContext(tx_op))
+        cr = http_client.post(
+            _join_url(base_api, f"frontend-apps/{quote(app_id, safe='')}/transactions/{quote(tx_id, safe='')}/commit"),
+            json={"idempotencyKey": idempotency_key},
+        )
+        try:
+            cd = cr.json()
+        except Exception:
+            cd = {}
+        if not cr.is_success or cd.get("committed") is False:
+            raise BBStudioError(
+                cd.get("code", "DATABASE_ERROR"),
+                cd.get("message", "Transaction commit failed"),
+                cr.status_code,
+            )
+        active = False
+        return res
+    except Exception as err:
+        active = False
+        try:
+            http_client.post(
+                _join_url(
+                    base_api,
+                    f"frontend-apps/{quote(app_id, safe='')}/transactions/{quote(tx_id, safe='')}/rollback",
+                ),
+                json={"reason": str(err)},
+            )
+        except Exception:
+            pass
+        raise
+
+
+# ---------------------------------------------------------------------------
+# End-User Authentication (bb_auth)
+# ---------------------------------------------------------------------------
+
+class _BBAuth:
+    @staticmethod
+    def get_token(client: Optional[BBStudioClient] = None) -> Optional[str]:
+        c = client or BBStudio.default_client()
+        return c._tokens.get(c.application_id)
+
+    @staticmethod
+    def logout(client: Optional[BBStudioClient] = None) -> None:
+        c = client or BBStudio.default_client()
+        c._tokens.pop(c.application_id, None)
+
+    @staticmethod
+    def register(payload: Dict[str, Any], client: Optional[BBStudioClient] = None) -> Any:
+        c = client or BBStudio.default_client()
+        base_api = _resolve_base_api(c.endpoint)
+        res = c.http.post(_join_url(base_api, f"app-auth/{quote(c.application_id, safe='')}/register"), json=payload)
+        try:
+            data = res.json()
+        except Exception:
+            data = None
+        if not res.is_success:
+            raise BBStudioError("AUTH_ERROR", (data or {}).get("message", "Registration failed"), res.status_code)
+        if isinstance(data, dict) and data.get("token"):
+            c._tokens[c.application_id] = data["token"]
+        return data
+
+    @staticmethod
+    def login(payload: Dict[str, Any], client: Optional[BBStudioClient] = None) -> Any:
+        c = client or BBStudio.default_client()
+        base_api = _resolve_base_api(c.endpoint)
+        res = c.http.post(_join_url(base_api, f"app-auth/{quote(c.application_id, safe='')}/login"), json=payload)
+        try:
+            data = res.json()
+        except Exception:
+            data = None
+        if not res.is_success:
+            raise BBStudioError("AUTH_ERROR", (data or {}).get("message", "Login failed"), res.status_code)
+        if isinstance(data, dict) and data.get("token"):
+            c._tokens[c.application_id] = data["token"]
+        return data
+
+    @staticmethod
+    def me(client: Optional[BBStudioClient] = None) -> Any:
+        c = client or BBStudio.default_client()
+        tok = _BBAuth.get_token(c)
+        if not tok:
+            return None
+        base_api = _resolve_base_api(c.endpoint)
+        res = c.http.get(
+            _join_url(base_api, f"app-auth/{quote(c.application_id, safe='')}/me"),
+            headers={"x-bb-auth-token": tok},
+        )
+        if res.status_code in (401, 403):
+            _BBAuth.logout(c)
+            return None
+        try:
+            data = res.json()
+        except Exception:
+            data = None
+        if not res.is_success:
+            raise BBStudioError("AUTH_ERROR", (data or {}).get("message", "Failed to load profile"), res.status_code)
+        return data
+
+    @staticmethod
+    def update_profile(payload: Dict[str, Any], client: Optional[BBStudioClient] = None) -> Any:
+        c = client or BBStudio.default_client()
+        tok = _BBAuth.get_token(c)
+        if not tok:
+            raise BBStudioError("UNAUTHORIZED", "Not signed in.")
+        base_api = _resolve_base_api(c.endpoint)
+        res = c.http.patch(
+            _join_url(base_api, f"app-auth/{quote(c.application_id, safe='')}/me"),
+            headers={"x-bb-auth-token": tok},
+            json=payload,
+        )
+        try:
+            data = res.json()
+        except Exception:
+            data = None
+        if not res.is_success:
+            raise BBStudioError("AUTH_ERROR", (data or {}).get("message", "Failed to update profile"), res.status_code)
+        return data
+
+    getToken = get_token
+    updateProfile = update_profile
+
+
+bb_auth = _BBAuth()
+
+
+# ---------------------------------------------------------------------------
+# File & Media Storage (bb_storage)
+# ---------------------------------------------------------------------------
+
+def bb_upload_file(
+    bucket_or_file: Union[str, Any],
+    file_obj: Any = None,
+    *,
+    folder: Optional[str] = None,
+    private: bool = False,
+    filename: str = "upload.bin",
+    client: Optional[BBStudioClient] = None,
+) -> Any:
+    c = client or BBStudio._default_client
+    bucket_url = bucket_or_file if isinstance(bucket_or_file, str) else None
+    actual_file = file_obj if bucket_url else bucket_or_file
+    if actual_file is None:
+        raise BBStudioError("INVALID_INPUT", "A file object or bytes is required for bb_upload_file.")
+    if not bucket_url and c is None:
+        raise BBStudioError("INVALID_INPUT", "Bucket URL or initialized BBStudio client is required.")
+
+    tok = bb_auth.get_token(c) if c else None
+    headers = {"x-bb-auth-token": tok} if tok else {}
+    target_url = (
+        _join_url(bucket_url, "upload")
+        if bucket_url
+        else _join_url(_resolve_base_api(c.endpoint), f"storage/{quote(c.application_id, safe='')}/upload")  # type: ignore[union-attr]
+    )
+    form_data: Dict[str, str] = {}
+    if folder:
+        form_data["folder"] = folder
+    if private:
+        form_data["private"] = "true"
+
+    fname = getattr(actual_file, "name", filename)
+    res = _get_http(c).post(
+        target_url,
+        headers=headers,
+        data=form_data,
+        files={"file": (fname, actual_file)},
+    )
+    try:
+        data = res.json()
+    except Exception:
+        data = None
+    if not res.is_success:
+        raise BBStudioError("STORAGE_ERROR", (data or {}).get("message", "File upload failed"), res.status_code)
+    if isinstance(data, dict) and data.get("id") and not data.get("fileId"):
+        data["fileId"] = data["id"]
+    return data
+
+
+def bb_list_files(bucket_url: str, client: Optional[BBStudioClient] = None) -> Any:
+    c = client or BBStudio._default_client
+    tok = bb_auth.get_token(c) if c else None
+    headers = {"x-bb-auth-token": tok} if tok else {}
+    res = _get_http(c).get(_join_url(bucket_url, "files"), headers=headers)
+    try:
+        data = res.json()
+    except Exception:
+        data = None
+    if not res.is_success:
+        raise BBStudioError("STORAGE_ERROR", (data or {}).get("message", "Could not list bucket files"), res.status_code)
+    return data
+
+
+def bb_get_file_url(
+    file_id: str,
+    *,
+    bucket_url: Optional[str] = None,
+    expires_in_seconds: Optional[int] = None,
+    client: Optional[BBStudioClient] = None,
+) -> Any:
+    c = client or BBStudio._default_client
+    tok = bb_auth.get_token(c) if c else None
+    headers = {"x-bb-auth-token": tok} if tok else {}
+    qs = f"?expiresInSeconds={expires_in_seconds}" if expires_in_seconds else ""
+    target_url = (
+        _join_url(bucket_url, f"{quote(file_id, safe='')}/url{qs}")
+        if bucket_url
+        else _join_url(
+            _resolve_base_api(c.endpoint),  # type: ignore[union-attr]
+            f"storage/{quote(c.application_id, safe='')}/{quote(file_id, safe='')}/url{qs}",  # type: ignore[union-attr]
+        )
+    )
+    res = _get_http(c).get(target_url, headers=headers)
+    try:
+        data = res.json()
+    except Exception:
+        data = None
+    if not res.is_success:
+        raise BBStudioError("STORAGE_ERROR", (data or {}).get("message", "Could not resolve file URL"), res.status_code)
+    return data
+
+
+def bb_delete_file(
+    file_id: str,
+    *,
+    bucket_url: Optional[str] = None,
+    client: Optional[BBStudioClient] = None,
+) -> Any:
+    c = client or BBStudio._default_client
+    tok = bb_auth.get_token(c) if c else None
+    headers = {"x-bb-auth-token": tok} if tok else {}
+    target_url = (
+        _join_url(bucket_url, quote(file_id, safe=""))
+        if bucket_url
+        else _join_url(
+            _resolve_base_api(c.endpoint),  # type: ignore[union-attr]
+            f"storage/{quote(c.application_id, safe='')}/{quote(file_id, safe='')}",  # type: ignore[union-attr]
+        )
+    )
+    res = _get_http(c).delete(target_url, headers=headers)
+    try:
+        data = res.json()
+    except Exception:
+        data = None
+    if not res.is_success:
+        raise BBStudioError("STORAGE_ERROR", (data or {}).get("message", "Could not delete file"), res.status_code)
+    return data
+
+
+bb_uploadFile = bb_upload_file
+bb_listFiles = bb_list_files
+bb_getFileUrl = bb_get_file_url
+bb_deleteFile = bb_delete_file
+
+
+class _BBStorage:
+    upload = staticmethod(bb_upload_file)
+    list = staticmethod(bb_list_files)
+    get_url = staticmethod(bb_get_file_url)
+    getUrl = staticmethod(bb_get_file_url)
+    delete = staticmethod(bb_delete_file)
+
+
+bb_storage = _BBStorage()
+
+
+# ---------------------------------------------------------------------------
+# Cloud Functions & Telemetry
+# ---------------------------------------------------------------------------
+
+def bb_invoke(
+    slug: str,
+    payload: Any = None,
+    method: str = "POST",
+    headers: Optional[Dict[str, str]] = None,
+    client: Optional[BBStudioClient] = None,
+) -> Any:
+    c = client or BBStudio.default_client()
+    base_api = _resolve_base_api(c.endpoint)
+    tok = bb_auth.get_token(c)
+    req_headers = {
+        "Content-Type": "application/json",
+        "x-bb-sdk": "1",
+        **({"x-bb-auth-token": tok} if tok else {}),
+        **(headers or {}),
+    }
+    url = _join_url(base_api, f"fn/{quote(c.application_id, safe='')}/{quote(slug, safe='')}")
+    upper = method.upper()
+    t0 = time.monotonic()
+    res = c.http.request(
+        upper,
+        url,
+        headers=req_headers,
+        json=None if upper in ("GET", "HEAD") else ({} if payload is None else payload),
+    )
+    latency_ms = int((time.monotonic() - t0) * 1000)
+    bb_track("API_CALL", path=f"/fn/{slug}", status_code=res.status_code, latency_ms=latency_ms, client=c)
+    try:
+        data = res.json()
+    except Exception:
+        data = None
+    if not res.is_success:
+        raise BBStudioError(
+            (data or {}).get("code", "FUNCTION_ERROR"),
+            (data or {}).get("error") or (data or {}).get("message") or f"Cloud Function failed with status {res.status_code}",
+            res.status_code,
+        )
+    return data
+
+
+def bb_track(
+    event_type: str,
+    *,
+    path: str = "/",
+    status_code: Optional[int] = None,
+    latency_ms: Optional[int] = None,
+    message: Optional[str] = None,
+    client: Optional[BBStudioClient] = None,
+) -> None:
+    try:
+        c = client or BBStudio._default_client
+        if c is None:
+            return
+        base_api = _resolve_base_api(c.endpoint)
+        body: Dict[str, Any] = {"eventType": event_type or "CUSTOM", "path": path}
+        if status_code is not None:
+            body["statusCode"] = status_code
+        if latency_ms is not None:
+            body["latencyMs"] = latency_ms
+        if message is not None:
+            body["message"] = message
+        c.http.post(_join_url(base_api, f"telemetry/{quote(c.application_id, safe='')}/ingest"), json=body)
+    except Exception:
+        pass

bb_studio-1.0.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: bb_studio
+Version: 1.0.0
+Summary: Official Python SDK for BB-Studio (Data CRUD, Transactions, End-User Auth, Storage Buckets, Cloud Functions & Telemetry)
+License: MIT
+Project-URL: Homepage, https://bb.previewbox.dpdns.org
+Keywords: bb-studio,baas,database,auth,storage,cloud-functions
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Dynamic: license-file
+
+# `bb_studio` (Python SDK)
+
+Official Python client SDK for **BB-Studio**.
+
+## Installation
+
+```bash
+pip install bb_studio
+```
+
+## Quick Start
+
+```python
+from bb_studio import (
+    BBStudio,
+    bb_get,
+    bb_create,
+    bb_is,
+    bb_sort_desc,
+    bb_limit,
+    bb_auth,
+    bb_upload_file,
+    bb_invoke,
+)
+
+bb = BBStudio.initialize(
+    application="APP-XXXXXXXX",
+    endpoint="https://bb.previewbox.dpdns.org",
+)
+app1 = bb.application("RT-XXXXXXXX")
+
+# Query records
+users = bb_get(app1.users, bb_is("status", "ACTIVE"), bb_sort_desc("createdAt"), bb_limit(20))
+
+# Authenticate end-user
+bb_auth.login({"email": "alice@example.com", "password": "Secret123!"})
+
+# Upload file to granted bucket1
+with open("avatar.png", "rb") as f:
+    uploaded = bb_upload_file("https://bb.previewbox.dpdns.org/api/v1/storage/b/BKT-XXXXXXXX", f)
+
+# Invoke Cloud Function
+result = bb_invoke("send-welcome", {"name": "Alice"})
+```

bb_studio-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+bb_studio/__init__.py,sha256=wLZ2xG1pqduFbWzv8wMcNUxB91RWoadKccPuMIwNeKA,2467
+bb_studio/client.py,sha256=Zhn9bbMYGKjE2QPBDP6Masog_MfTHZ4LU0F1SPGQbHg,28257
+bb_studio-1.0.0.dist-info/licenses/LICENSE,sha256=keKPU_HsHCjH4NB4V02-4mho9rD2TEb9ko8SZVr3qzA,1066
+bb_studio-1.0.0.dist-info/METADATA,sha256=rWcL99uVomgpbgBJ1HbgLKwpwjjfw4iBTJKNusIlV14,1368
+bb_studio-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+bb_studio-1.0.0.dist-info/top_level.txt,sha256=5gPoQ3nJSolm-e0cz4qd2Ru6VVUjIUxmsRFGcjT63OE,10
+bb_studio-1.0.0.dist-info/RECORD,,

bb_studio-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bb_studio-1.0.0.dist-info/licenses/LICENSE

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

bb_studio-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bb_studio