somewhere-tech 0.2.0__py3-none-any.whl

somewhere/__init__.py

@@ -0,0 +1,168 @@
+"""Official Python SDK for the somewhere.tech platform API.
+
+Supabase-compatible interface with query builder, auth, storage, email,
+and OpenAI-compatible chat completions.
+
+Usage:
+    from somewhere import Somewhere
+
+    sw = Somewhere(key='smt_...', project_id='my-project')
+
+    # Database (Supabase-style query builder)
+    result = sw.from_('users').select('*').eq('role', 'admin').execute()
+
+    # Auth
+    result = sw.auth.sign_up(email='u@test.com', password='pass123')
+
+    # Storage
+    result = sw.storage.from_('avatars').upload('photo.png', file_bytes)
+
+    # Email
+    result = sw.emails.send(to='user@test.com', subject='Hi', html='<h1>Hello</h1>')
+
+    # AI (OpenAI-compatible)
+    completion = sw.chat.completions.create(model='claude-sonnet-4-6', messages=[...])
+"""
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import httpx
+
+from .auth import AuthClient
+from .chat import ChatClient
+from .client import (
+    BillingClient,
+    CronClient,
+    DeployClient,
+    DomainsClient,
+    EnvClient,
+    FeedbackClient,
+    HttpClient,
+    JobsClient,
+    LogsClient,
+    PreviewClient,
+    ProjectsClient,
+    QueueClient,
+    UsageClient,
+)
+from .emails import EmailsClient
+from .errors import SomewhereError
+from .query_builder import QueryBuilder, Result
+from .storage import StorageClient
+
+__all__ = ["Somewhere", "SomewhereError", "Result"]
+__version__ = "0.2.0"
+
+
+class Somewhere:
+    """Entry point for the somewhere.tech SDK.
+
+    Provides a Supabase-compatible interface with query builder, auth,
+    storage, email, and OpenAI-compatible chat completions.
+
+    Args:
+        key: Developer API key (smt_...). Mutually exclusive with token.
+        token: App-user JWT. Mutually exclusive with key.
+        project_id: Default project ID for all operations.
+        base_url: API base URL (defaults to https://api.somewhere.tech/v1).
+        http_client: Custom httpx.Client instance (optional).
+        headers: Extra headers to send with every request (optional).
+        timeout: Request timeout in seconds (default 60).
+
+    Example:
+        sw = Somewhere(key='smt_...', project_id='booking-app')
+        result = sw.from_('users').select('*').eq('role', 'admin').execute()
+        print(result.data)
+    """
+
+    def __init__(
+        self,
+        *,
+        key: Optional[str] = None,
+        token: Optional[str] = None,
+        project_id: Optional[str] = None,
+        base_url: str = "https://api.somewhere.tech/v1",
+        http_client: Optional[httpx.Client] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self._http = HttpClient(
+            key=key,
+            token=token,
+            project_id=project_id,
+            base_url=base_url,
+            http_client=http_client,
+            headers=headers,
+            timeout=timeout,
+        )
+
+        # Supabase-compatible clients
+        self.auth = AuthClient(
+            project_id=self._http.project_id,
+            http_client=self._http.client,
+            base_url=self._http.base_url,
+            auth_header=self._http.auth_header,
+            extra_headers=self._http.extra_headers,
+        )
+        self.storage = StorageClient(
+            project_id=self._http.project_id,
+            http_client=self._http.client,
+            base_url=self._http.base_url,
+            auth_header=self._http.auth_header,
+            extra_headers=self._http.extra_headers,
+        )
+        self.emails = EmailsClient(
+            project_id=self._http.project_id,
+            http_client=self._http.client,
+            base_url=self._http.base_url,
+            auth_header=self._http.auth_header,
+            extra_headers=self._http.extra_headers,
+        )
+        self.chat = ChatClient(
+            project_id=self._http.project_id,
+            http_client=self._http.client,
+            base_url=self._http.base_url,
+            auth_header=self._http.auth_header,
+            extra_headers=self._http.extra_headers,
+        )
+
+        # Simple resource clients
+        self.env = EnvClient(self._http)
+        self.jobs = JobsClient(self._http)
+        self.cron = CronClient(self._http)
+        self.domains = DomainsClient(self._http)
+        self.projects = ProjectsClient(self._http)
+        self.deploy = DeployClient(self._http)
+        self.logs = LogsClient(self._http)
+        self.queue = QueueClient(self._http)
+        self.billing = BillingClient(self._http)
+        self.usage = UsageClient(self._http)
+        self.feedback = FeedbackClient(self._http)
+        self.preview = PreviewClient(self._http)
+
+    def from_(self, table: str) -> QueryBuilder:
+        """Start a Supabase-style query builder for the given table.
+
+        Uses `from_` because `from` is a reserved word in Python.
+
+        Args:
+            table: The database table name.
+
+        Returns:
+            A QueryBuilder that supports .select(), .insert(), .update(),
+            .delete(), .upsert(), plus filter chains (.eq(), .gt(), etc.)
+            ending with .execute().
+
+        Example:
+            result = sw.from_('users').select('*').eq('role', 'admin').execute()
+            result = sw.from_('users').insert({'name': 'A'}).execute()
+        """
+        return QueryBuilder(
+            table=table,
+            project_id=self._http.project_id,
+            http_client=self._http.client,
+            base_url=self._http.base_url,
+            auth_header=self._http.auth_header,
+            extra_headers=self._http.extra_headers,
+        )

somewhere/auth.py

@@ -0,0 +1,210 @@
+"""Auth client for the somewhere.tech platform -- Supabase-compatible interface.
+
+Provides sign_up, sign_in_with_password, get_user, sign_out, and other
+auth operations. All methods return Result objects (never raise).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .query_builder import Result
+
+
+class AuthClient:
+    """Supabase-compatible auth interface.
+
+    Usage:
+        result = sw.auth.sign_up(email='u@test.com', password='pass123')
+        result = sw.auth.sign_in_with_password(email='u@test.com', password='pass123')
+        result = sw.auth.get_user()
+        result = sw.auth.sign_out()
+    """
+
+    def __init__(
+        self,
+        project_id: str,
+        http_client: httpx.Client,
+        base_url: str,
+        auth_header: str,
+        extra_headers: Dict[str, str],
+    ) -> None:
+        self._project_id = project_id
+        self._http = http_client
+        self._base_url = base_url
+        self._auth_header = auth_header
+        self._extra_headers = extra_headers
+        self._session_token: Optional[str] = None
+
+    def sign_up(
+        self,
+        *,
+        email: str,
+        password: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Result:
+        """Create a new user account."""
+        return self._post("/auth/signup", {
+            "project_id": self._project_id,
+            "email": email,
+            "password": password,
+            "metadata": metadata,
+        })
+
+    def sign_in_with_password(
+        self,
+        *,
+        email: str,
+        password: str,
+    ) -> Result:
+        """Sign in with email and password. Stores session token internally."""
+        result = self._post("/auth/login", {
+            "project_id": self._project_id,
+            "email": email,
+            "password": password,
+        })
+        if result.data and isinstance(result.data, list) and len(result.data) > 0:
+            session = result.data[0]
+            if isinstance(session, dict):
+                self._session_token = session.get("token") or session.get("session_token")
+        return result
+
+    def get_user(self) -> Result:
+        """Get the currently authenticated user."""
+        return self._get("/auth/me")
+
+    def sign_out(self) -> Result:
+        """Sign out the current user."""
+        payload: Dict[str, Any] = {"project_id": self._project_id}
+        if self._session_token:
+            payload["session_token"] = self._session_token
+        result = self._post("/auth/logout", payload)
+        if not result.error:
+            self._session_token = None
+        return result
+
+    def forgot_password(self, *, email: str) -> Result:
+        """Send a password reset email."""
+        return self._post("/auth/forgot", {
+            "project_id": self._project_id,
+            "email": email,
+        })
+
+    def reset_password(self, *, token: str, new_password: str) -> Result:
+        """Reset password using a reset token."""
+        return self._post("/auth/reset", {
+            "project_id": self._project_id,
+            "token": token,
+            "new_password": new_password,
+        })
+
+    def verify_email(self, *, code: str) -> Result:
+        """Verify email with a verification code."""
+        return self._post("/auth/verify-email", {"code": code})
+
+    def request_verification(self) -> Result:
+        """Request a new email verification code."""
+        return self._post("/auth/request-email-verification", {})
+
+    def update_user(
+        self,
+        *,
+        display_name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Result:
+        """Update the current user's profile."""
+        payload: Dict[str, Any] = {}
+        if display_name is not None:
+            payload["display_name"] = display_name
+        if metadata is not None:
+            payload["metadata"] = metadata
+        return self._request("PATCH", "/auth/users/me", json_body=payload)
+
+    def delete_user(self) -> Result:
+        """Delete the current user's account."""
+        return self._request("DELETE", "/auth/users/me")
+
+    def list_users(
+        self,
+        *,
+        search: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        ids: Optional[List[str]] = None,
+    ) -> Result:
+        """List users (admin operation)."""
+        params: Dict[str, Any] = {"project_id": self._project_id}
+        if search is not None:
+            params["search"] = search
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        if ids is not None:
+            params["ids"] = ",".join(ids)
+        return self._get("/auth/users", params=params)
+
+    # --- Internal helpers ---
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": self._auth_header,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            **self._extra_headers,
+        }
+
+    def _post(self, path: str, payload: Dict[str, Any]) -> Result:
+        return self._request("POST", path, json_body=payload)
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Result:
+        return self._request("GET", path, params=params)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Result:
+        url = f"{self._base_url}{path}"
+        try:
+            if json_body is not None:
+                # Strip None values
+                json_body = {k: v for k, v in json_body.items() if v is not None}
+            if params is not None:
+                params = {k: v for k, v in params.items() if v is not None}
+
+            response = self._http.request(
+                method,
+                url,
+                json=json_body,
+                params=params,
+                headers=self._headers(),
+            )
+            return self._parse(response)
+        except httpx.HTTPError as exc:
+            return Result(error={"code": "NETWORK_ERROR", "message": str(exc)})
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> Result:
+        try:
+            body = response.json()
+        except ValueError:
+            return Result(error={
+                "code": "INVALID_RESPONSE",
+                "message": f"Non-JSON response (status {response.status_code})",
+            })
+
+        if isinstance(body, dict) and body.get("ok") is True:
+            data = body.get("data")
+            if isinstance(data, list):
+                return Result(data=data, count=len(data))
+            if isinstance(data, dict):
+                return Result(data=[data], count=1)
+            return Result(data=[data] if data is not None else [], count=1 if data else 0)
+
+        error_code = body.get("error", "UNKNOWN_ERROR") if isinstance(body, dict) else "UNKNOWN_ERROR"
+        error_message = body.get("message", "Unknown error") if isinstance(body, dict) else str(body)
+        return Result(error={"code": error_code, "message": error_message})

somewhere/chat.py

@@ -0,0 +1,297 @@
+"""OpenAI-compatible chat completions client for the somewhere.tech AI API.
+
+This module deliberately raises SomewhereError on failure (instead of returning
+Result) to match the OpenAI SDK convention where chat.completions.create raises
+on error.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .errors import SomewhereError
+
+
+class ChatMessage:
+    """A single message in a chat completion response."""
+
+    def __init__(self, role: str, content: str) -> None:
+        self.role = role
+        self.content = content
+
+    def __repr__(self) -> str:
+        preview = self.content[:80] + "..." if len(self.content) > 80 else self.content
+        return f"ChatMessage(role={self.role!r}, content={preview!r})"
+
+
+class ChatChoice:
+    """A single choice in a chat completion response."""
+
+    def __init__(
+        self,
+        index: int,
+        message: ChatMessage,
+        finish_reason: Optional[str] = None,
+    ) -> None:
+        self.index = index
+        self.message = message
+        self.finish_reason = finish_reason
+
+    def __repr__(self) -> str:
+        return f"ChatChoice(index={self.index}, finish_reason={self.finish_reason!r})"
+
+
+class ChatUsage:
+    """Token usage for a chat completion."""
+
+    def __init__(
+        self,
+        prompt_tokens: int = 0,
+        completion_tokens: int = 0,
+        total_tokens: int = 0,
+    ) -> None:
+        self.prompt_tokens = prompt_tokens
+        self.completion_tokens = completion_tokens
+        self.total_tokens = total_tokens
+
+    def __repr__(self) -> str:
+        return f"ChatUsage(prompt={self.prompt_tokens}, completion={self.completion_tokens}, total={self.total_tokens})"
+
+
+class ChatCompletion:
+    """OpenAI-compatible chat completion response object.
+
+    Usage:
+        completion = sw.chat.completions.create(
+            model='claude-sonnet-4-6',
+            messages=[{'role': 'user', 'content': 'Hello'}],
+        )
+        print(completion.choices[0].message.content)
+    """
+
+    def __init__(
+        self,
+        id: str,
+        model: str,
+        choices: List[ChatChoice],
+        usage: Optional[ChatUsage] = None,
+        created: Optional[int] = None,
+    ) -> None:
+        self.id = id
+        self.object = "chat.completion"
+        self.model = model
+        self.choices = choices
+        self.usage = usage
+        self.created = created
+
+    def __repr__(self) -> str:
+        return f"ChatCompletion(id={self.id!r}, model={self.model!r}, choices={len(self.choices)})"
+
+
+class ChatCompletionsClient:
+    """OpenAI-compatible completions interface.
+
+    Accessed via sw.chat.completions.create(...).
+    Raises SomewhereError on failure (matches OpenAI SDK behavior).
+    """
+
+    def __init__(
+        self,
+        project_id: str,
+        http_client: httpx.Client,
+        base_url: str,
+        auth_header: str,
+        extra_headers: Dict[str, str],
+    ) -> None:
+        self._project_id = project_id
+        self._http = http_client
+        self._base_url = base_url
+        self._auth_header = auth_header
+        self._extra_headers = extra_headers
+
+    def create(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, str]],
+        system: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        stop: Optional[List[str]] = None,
+        provider: Optional[str] = None,
+    ) -> ChatCompletion:
+        """Create a chat completion.
+
+        This method raises SomewhereError on failure (matching OpenAI SDK behavior).
+
+        Args:
+            model: Model identifier (e.g. 'claude-sonnet-4-6', 'gpt-4o').
+            messages: List of message dicts with 'role' and 'content' keys.
+            system: Optional system prompt.
+            max_tokens: Maximum tokens to generate.
+            temperature: Sampling temperature (0-2).
+            top_p: Nucleus sampling parameter.
+            stop: Stop sequences.
+            provider: Override the AI provider.
+
+        Returns:
+            ChatCompletion with choices[0].message.content containing the response.
+
+        Raises:
+            SomewhereError: On API errors (matches OpenAI SDK convention).
+        """
+        payload: Dict[str, Any] = {
+            "project_id": self._project_id,
+            "model": model,
+            "messages": messages,
+        }
+        if system is not None:
+            payload["system"] = system
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
+        if temperature is not None:
+            payload["temperature"] = temperature
+        if top_p is not None:
+            payload["top_p"] = top_p
+        if stop is not None:
+            payload["stop"] = stop
+        if provider is not None:
+            payload["provider"] = provider
+
+        url = f"{self._base_url}/ai/complete"
+        headers = {
+            "Authorization": self._auth_header,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            **self._extra_headers,
+        }
+
+        try:
+            response = self._http.post(url, json=payload, headers=headers)
+        except httpx.HTTPError as exc:
+            raise SomewhereError(
+                code="NETWORK_ERROR",
+                message=str(exc),
+                status_code=0,
+            )
+
+        try:
+            body = response.json()
+        except ValueError:
+            raise SomewhereError(
+                code="INVALID_RESPONSE",
+                message=f"Non-JSON response (status {response.status_code})",
+                status_code=response.status_code,
+            )
+
+        # Error response
+        if isinstance(body, dict) and body.get("ok") is False:
+            raise SomewhereError(
+                code=body.get("error", "UNKNOWN_ERROR"),
+                message=body.get("message", "Unknown error"),
+                status_code=response.status_code,
+                retry=bool(body.get("retry", False)),
+                retry_after_ms=body.get("retry_after_ms"),
+                body=body,
+            )
+
+        if not isinstance(body, dict) or body.get("ok") is not True:
+            raise SomewhereError(
+                code="INVALID_RESPONSE",
+                message=f"Unexpected response shape (status {response.status_code})",
+                status_code=response.status_code,
+                body=body,
+            )
+
+        data = body.get("data", {})
+        return self._to_completion(data, model)
+
+    @staticmethod
+    def _to_completion(data: Any, requested_model: str) -> ChatCompletion:
+        """Convert API response data into an OpenAI-compatible ChatCompletion."""
+        if not isinstance(data, dict):
+            data = {}
+
+        # The API may return data in different shapes. Handle both
+        # OpenAI-compatible and platform-native formats.
+
+        # If the response already has 'choices', use them directly
+        if "choices" in data:
+            choices = []
+            for i, choice_data in enumerate(data["choices"]):
+                msg = choice_data.get("message", {})
+                choices.append(ChatChoice(
+                    index=choice_data.get("index", i),
+                    message=ChatMessage(
+                        role=msg.get("role", "assistant"),
+                        content=msg.get("content", ""),
+                    ),
+                    finish_reason=choice_data.get("finish_reason"),
+                ))
+            usage_data = data.get("usage", {})
+            usage = ChatUsage(
+                prompt_tokens=usage_data.get("prompt_tokens", 0),
+                completion_tokens=usage_data.get("completion_tokens", 0),
+                total_tokens=usage_data.get("total_tokens", 0),
+            ) if usage_data else None
+
+            return ChatCompletion(
+                id=data.get("id", ""),
+                model=data.get("model", requested_model),
+                choices=choices,
+                usage=usage,
+                created=data.get("created"),
+            )
+
+        # Platform-native format: data might have 'content' or 'text' directly
+        content = data.get("content") or data.get("text") or data.get("response") or ""
+        model_used = data.get("model", requested_model)
+
+        usage_data = data.get("usage", {})
+        # Platform returns input_tokens/output_tokens, OpenAI uses prompt/completion
+        prompt = usage_data.get("prompt_tokens") or usage_data.get("input_tokens") or 0
+        completion = usage_data.get("completion_tokens") or usage_data.get("output_tokens") or 0
+        usage = ChatUsage(
+            prompt_tokens=prompt,
+            completion_tokens=completion,
+            total_tokens=usage_data.get("total_tokens") or (prompt + completion),
+        ) if usage_data else None
+
+        return ChatCompletion(
+            id=data.get("id", ""),
+            model=model_used,
+            choices=[
+                ChatChoice(
+                    index=0,
+                    message=ChatMessage(role="assistant", content=str(content)),
+                    finish_reason=data.get("finish_reason", "stop"),
+                ),
+            ],
+            usage=usage,
+            created=data.get("created"),
+        )
+
+
+class ChatClient:
+    """Top-level chat client. Access via sw.chat.
+
+    Provides sw.chat.completions.create(...) for OpenAI-compatible chat.
+    """
+
+    def __init__(
+        self,
+        project_id: str,
+        http_client: httpx.Client,
+        base_url: str,
+        auth_header: str,
+        extra_headers: Dict[str, str],
+    ) -> None:
+        self.completions = ChatCompletionsClient(
+            project_id=project_id,
+            http_client=http_client,
+            base_url=base_url,
+            auth_header=auth_header,
+            extra_headers=extra_headers,
+        )