dominus-sdk-python 2.0.0__py3-none-any.whl

dominus/namespaces/courier.py

@@ -0,0 +1,251 @@
+"""
+Courier Namespace - Email delivery via Postmark.
+
+Provides email sending using Postmark templates.
+"""
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..start import Dominus
+
+
+class CourierNamespace:
+    """
+    Email delivery namespace.
+
+    All email operations go through /api/courier/* endpoints.
+    Uses Postmark for transactional email delivery.
+
+    Usage:
+        # Send welcome email
+        result = await dominus.courier.send(
+            template_alias="welcome",
+            to="user@example.com",
+            from_email="noreply@myapp.com",
+            model={
+                "name": "John Smith",
+                "product_name": "My App"
+            }
+        )
+
+        # Send with tracking tag
+        result = await dominus.courier.send(
+            template_alias="password-reset",
+            to="user@example.com",
+            from_email="noreply@myapp.com",
+            model={"reset_link": "https://..."},
+            tag="password-reset"
+        )
+    """
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    async def send(
+        self,
+        template_alias: str,
+        to: str,
+        from_email: str,
+        model: Dict[str, Any],
+        tag: Optional[str] = None,
+        reply_to: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Send email using Postmark template.
+
+        Args:
+            template_alias: Template alias in Postmark (e.g., "welcome", "password-reset")
+            to: Recipient email address
+            from_email: Sender email address (must be verified in Postmark)
+            model: Template model variables (dict of key-value pairs)
+            tag: Optional tag for tracking/filtering in Postmark
+            reply_to: Optional reply-to address
+
+        Returns:
+            Dict with:
+                - to: Recipient email
+                - message_id: Postmark message UUID
+                - submitted_at: Timestamp
+
+        Example:
+            result = await dominus.courier.send(
+                template_alias="welcome",
+                to="john@example.com",
+                from_email="hello@myapp.com",
+                model={
+                    "name": "John",
+                    "company_name": "My App",
+                    "action_url": "https://myapp.com/verify?token=abc123"
+                },
+                tag="welcome"
+            )
+            print(f"Email sent: {result['message_id']}")
+        """
+        body = {
+            "template_alias": template_alias,
+            "to": to,
+            "from": from_email,
+            "model": model
+        }
+
+        if tag:
+            body["tag"] = tag
+        if reply_to:
+            body["reply_to"] = reply_to
+
+        return await self._client._request(
+            endpoint="/api/courier/send",
+            body=body
+        )
+
+    # Convenience methods for common templates
+
+    async def send_welcome(
+        self,
+        to: str,
+        from_email: str,
+        name: str,
+        product_name: str,
+        action_url: Optional[str] = None,
+        **extra_model
+    ) -> Dict[str, Any]:
+        """
+        Send welcome email.
+
+        Args:
+            to: Recipient email
+            from_email: Sender email
+            name: User's name
+            product_name: Your product/app name
+            action_url: Optional action button URL
+            **extra_model: Additional template variables
+
+        Returns:
+            Send result dict
+        """
+        model = {
+            "name": name,
+            "product_name": product_name,
+            **extra_model
+        }
+        if action_url:
+            model["action_url"] = action_url
+
+        return await self.send(
+            template_alias="welcome",
+            to=to,
+            from_email=from_email,
+            model=model,
+            tag="welcome"
+        )
+
+    async def send_password_reset(
+        self,
+        to: str,
+        from_email: str,
+        name: str,
+        reset_url: str,
+        product_name: str,
+        **extra_model
+    ) -> Dict[str, Any]:
+        """
+        Send password reset email.
+
+        Args:
+            to: Recipient email
+            from_email: Sender email
+            name: User's name
+            reset_url: Password reset link
+            product_name: Your product/app name
+            **extra_model: Additional template variables
+
+        Returns:
+            Send result dict
+        """
+        return await self.send(
+            template_alias="password-reset",
+            to=to,
+            from_email=from_email,
+            model={
+                "name": name,
+                "action_url": reset_url,
+                "product_name": product_name,
+                **extra_model
+            },
+            tag="password-reset"
+        )
+
+    async def send_email_verification(
+        self,
+        to: str,
+        from_email: str,
+        name: str,
+        verify_url: str,
+        product_name: str,
+        **extra_model
+    ) -> Dict[str, Any]:
+        """
+        Send email verification email.
+
+        Args:
+            to: Recipient email
+            from_email: Sender email
+            name: User's name
+            verify_url: Email verification link
+            product_name: Your product/app name
+            **extra_model: Additional template variables
+
+        Returns:
+            Send result dict
+        """
+        return await self.send(
+            template_alias="email-verification",
+            to=to,
+            from_email=from_email,
+            model={
+                "name": name,
+                "action_url": verify_url,
+                "product_name": product_name,
+                **extra_model
+            },
+            tag="email-verification"
+        )
+
+    async def send_invitation(
+        self,
+        to: str,
+        from_email: str,
+        name: str,
+        invite_url: str,
+        inviter_name: str,
+        product_name: str,
+        **extra_model
+    ) -> Dict[str, Any]:
+        """
+        Send user invitation email.
+
+        Args:
+            to: Recipient email
+            from_email: Sender email
+            name: Invitee's name
+            invite_url: Invitation accept link
+            inviter_name: Name of person who invited
+            product_name: Your product/app name
+            **extra_model: Additional template variables
+
+        Returns:
+            Send result dict
+        """
+        return await self.send(
+            template_alias="invitation",
+            to=to,
+            from_email=from_email,
+            model={
+                "name": name,
+                "action_url": invite_url,
+                "inviter_name": inviter_name,
+                "product_name": product_name,
+                **extra_model
+            },
+            tag="invitation"
+        )

dominus/namespaces/db.py

@@ -0,0 +1,267 @@
+"""
+Database Namespace - Scribe data CRUD operations.
+
+Provides data operations for all schemas with support for secure table access.
+"""
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..start import Dominus
+
+
+class DbNamespace:
+    """
+    Database CRUD namespace.
+
+    All data operations go through /api/scribe/data/* endpoints.
+    Secure tables (registered in auth.secure_tables) require a `reason` parameter.
+
+    Usage:
+        # List tables
+        tables = await dominus.db.tables()
+        tables = await dominus.db.tables(schema="tenant_acme")
+
+        # Query with filters
+        users = await dominus.db.query("users", filters={"status": "active"})
+
+        # Query secure table (requires reason)
+        patients = await dominus.db.query(
+            "patients",
+            schema="tenant_acme",
+            reason="Reviewing chart for appointment #123",
+            actor=current_user_id
+        )
+
+        # Insert data
+        await dominus.db.insert("users", {"name": "John", "email": "john@example.com"})
+
+        # Update rows
+        await dominus.db.update("users", {"status": "inactive"}, filters={"id": user_id})
+
+        # Delete rows
+        await dominus.db.delete("users", filters={"id": user_id})
+    """
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    async def tables(self, schema: str = "public") -> List[Dict[str, Any]]:
+        """
+        List tables in a schema.
+
+        Args:
+            schema: Schema name (default: "public")
+
+        Returns:
+            List of table metadata
+        """
+        result = await self._client._request(
+            endpoint=f"/api/scribe/data/{schema}/tables",
+            method="GET"
+        )
+        return result.get("tables", result) if isinstance(result, dict) else result
+
+    async def columns(self, table: str, schema: str = "public") -> List[Dict[str, Any]]:
+        """
+        List columns in a table.
+
+        Args:
+            table: Table name
+            schema: Schema name (default: "public")
+
+        Returns:
+            List of column metadata
+        """
+        result = await self._client._request(
+            endpoint=f"/api/scribe/data/{schema}/{table}/columns",
+            method="GET"
+        )
+        return result.get("columns", result) if isinstance(result, dict) else result
+
+    async def query(
+        self,
+        table: str,
+        schema: str = "public",
+        filters: Optional[Dict[str, Any]] = None,
+        sort_by: Optional[str] = None,
+        sort_order: str = "ASC",
+        limit: int = 100,
+        offset: int = 0,
+        reason: Optional[str] = None,
+        actor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Query table data with filtering, sorting, and pagination.
+
+        Args:
+            table: Table name
+            schema: Schema name (default: "public")
+            filters: Column:value filter dictionary
+            sort_by: Column to sort by
+            sort_order: "ASC" or "DESC"
+            limit: Maximum rows to return (default: 100)
+            offset: Rows to skip (default: 0)
+            reason: Access justification (required for secure tables)
+            actor: User ID or "machine" for audit trail
+
+        Returns:
+            Dict with "rows" and "total" keys
+
+        Raises:
+            SecureTableError: If accessing secure table without reason
+        """
+        body = {
+            "filters": filters,
+            "sort_by": sort_by,
+            "sort_order": sort_order,
+            "limit": limit,
+            "offset": offset
+        }
+
+        if reason:
+            body["reason"] = reason
+        if actor:
+            body["actor"] = actor
+
+        return await self._client._request(
+            endpoint=f"/api/scribe/data/{schema}/{table}/query",
+            body=body
+        )
+
+    async def insert(
+        self,
+        table: str,
+        data: Dict[str, Any],
+        schema: str = "public",
+        reason: Optional[str] = None,
+        actor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Insert a row into a table.
+
+        Args:
+            table: Table name
+            data: Column:value dictionary
+            schema: Schema name (default: "public")
+            reason: Access justification (required for secure tables)
+            actor: User ID or "machine" for audit trail
+
+        Returns:
+            Inserted row data
+        """
+        body = {"data": data}
+
+        if reason:
+            body["reason"] = reason
+        if actor:
+            body["actor"] = actor
+
+        return await self._client._request(
+            endpoint=f"/api/scribe/data/{schema}/{table}/insert",
+            body=body
+        )
+
+    async def update(
+        self,
+        table: str,
+        data: Dict[str, Any],
+        filters: Dict[str, Any],
+        schema: str = "public",
+        reason: Optional[str] = None,
+        actor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Update rows matching filters.
+
+        Args:
+            table: Table name
+            data: Column:value dictionary of updates
+            filters: Column:value dictionary for WHERE clause
+            schema: Schema name (default: "public")
+            reason: Access justification (required for secure tables)
+            actor: User ID or "machine" for audit trail
+
+        Returns:
+            Dict with "affected_rows" count
+        """
+        body = {
+            "data": data,
+            "filters": filters
+        }
+
+        if reason:
+            body["reason"] = reason
+        if actor:
+            body["actor"] = actor
+
+        return await self._client._request(
+            endpoint=f"/api/scribe/data/{schema}/{table}/update",
+            body=body
+        )
+
+    async def delete(
+        self,
+        table: str,
+        filters: Dict[str, Any],
+        schema: str = "public",
+        reason: Optional[str] = None,
+        actor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Delete rows matching filters.
+
+        Args:
+            table: Table name
+            filters: Column:value dictionary for WHERE clause
+            schema: Schema name (default: "public")
+            reason: Access justification (required for secure tables)
+            actor: User ID or "machine" for audit trail
+
+        Returns:
+            Dict with "affected_rows" count
+        """
+        body = {"filters": filters}
+
+        if reason:
+            body["reason"] = reason
+        if actor:
+            body["actor"] = actor
+
+        return await self._client._request(
+            endpoint=f"/api/scribe/data/{schema}/{table}/delete",
+            body=body
+        )
+
+    async def bulk_insert(
+        self,
+        table: str,
+        rows: List[Dict[str, Any]],
+        schema: str = "public",
+        reason: Optional[str] = None,
+        actor: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Insert multiple rows at once.
+
+        Args:
+            table: Table name
+            rows: List of column:value dictionaries
+            schema: Schema name (default: "public")
+            reason: Access justification (required for secure tables)
+            actor: User ID or "machine" for audit trail
+
+        Returns:
+            Dict with "inserted_count" and optionally "rows"
+        """
+        body = {"rows": rows}
+
+        if reason:
+            body["reason"] = reason
+        if actor:
+            body["actor"] = actor
+
+        return await self._client._request(
+            endpoint=f"/api/scribe/data/{schema}/{table}/bulk-insert",
+            body=body
+        )
+