synquic-slide 0.1.0__py3-none-any.whl

synquic_slide/__init__.py

@@ -0,0 +1,62 @@
+from .client import AsyncSlideClient, SlideClient
+from .errors import (
+    SlideAuthError,
+    SlideError,
+    SlideNotFoundError,
+    SlideScopeError,
+    SlideValidationError,
+)
+from .types import (
+    Contact,
+    DiscountValidation,
+    EmailContact,
+    EmailTemplate,
+    InitiateOutboundCallResponse,
+    InstagramConversation,
+    InstagramProfile,
+    PaginatedResponse,
+    PaginationMeta,
+    SendEmailResponse,
+    SendInstagramMessageResponse,
+    SendWhatsAppTemplateResponse,
+    ShopifyCollection,
+    ShopifyOrder,
+    ShopifyProduct,
+    VoiceAgent,
+    VoiceAnalytics,
+    VoiceCall,
+    WhatsAppLog,
+    WhatsAppTemplate,
+)
+
+__all__ = [
+    "SlideClient",
+    "AsyncSlideClient",
+    "SlideError",
+    "SlideAuthError",
+    "SlideScopeError",
+    "SlideNotFoundError",
+    "SlideValidationError",
+    "PaginationMeta",
+    "PaginatedResponse",
+    "Contact",
+    "SendEmailResponse",
+    "EmailTemplate",
+    "EmailContact",
+    "SendWhatsAppTemplateResponse",
+    "WhatsAppLog",
+    "WhatsAppTemplate",
+    "InstagramProfile",
+    "InstagramConversation",
+    "SendInstagramMessageResponse",
+    "ShopifyProduct",
+    "ShopifyCollection",
+    "ShopifyOrder",
+    "DiscountValidation",
+    "VoiceAgent",
+    "VoiceCall",
+    "InitiateOutboundCallResponse",
+    "VoiceAnalytics",
+]
+
+__version__ = "0.1.0"

synquic_slide/client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import SlideAuthError, SlideError, SlideNotFoundError, SlideScopeError, SlideValidationError
+from .resources import (
+    AsyncContactsResource,
+    AsyncEmailResource,
+    AsyncInstagramResource,
+    AsyncShopifyResource,
+    AsyncVoiceResource,
+    AsyncWhatsAppResource,
+    ContactsResource,
+    EmailResource,
+    InstagramResource,
+    ShopifyResource,
+    VoiceResource,
+    WhatsAppResource,
+)
+
+_DEFAULT_BASE_URL = "https://slide.synquic.com/api"
+_DEFAULT_TIMEOUT = 30.0
+
+
+def _clean_params(params: Optional[Dict]) -> Optional[Dict]:
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        body = response.json()
+    except Exception:
+        body = {"message": response.text}
+    message: str = body.get("message", response.reason_phrase or "Request failed")
+
+    if response.status_code == 400:
+        raise SlideValidationError(message, body)
+    if response.status_code == 401:
+        raise SlideAuthError(message)
+    if response.status_code == 403:
+        raise SlideScopeError(message)
+    if response.status_code == 404:
+        raise SlideNotFoundError(message)
+    raise SlideError(response.status_code, message, body)
+
+
+class SlideClient:
+    """Synchronous Slide API client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/") + "/",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+        self.contacts = ContactsResource(self)
+        self.email = EmailResource(self)
+        self.whatsapp = WhatsAppResource(self)
+        self.instagram = InstagramResource(self)
+        self.shopify = ShopifyResource(self)
+        self.voice = VoiceResource(self)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        if "params" in kwargs:
+            kwargs["params"] = _clean_params(kwargs["params"])
+        response = self._http.request(method, path, **kwargs)
+        _raise_for_status(response)
+        if response.status_code == 204:
+            return None
+        return response.json()
+
+    def _request_multipart(self, method: str, path: str, *, files: Dict, data: Dict) -> Any:
+        response = self._http.request(method, path, files=files, data=data)
+        _raise_for_status(response)
+        return response.json()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> SlideClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class AsyncSlideClient:
+    """Async Slide API client — use with `async with` or `await client.close()`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/") + "/",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+        self.contacts = AsyncContactsResource(self)
+        self.email = AsyncEmailResource(self)
+        self.whatsapp = AsyncWhatsAppResource(self)
+        self.instagram = AsyncInstagramResource(self)
+        self.shopify = AsyncShopifyResource(self)
+        self.voice = AsyncVoiceResource(self)
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        if "params" in kwargs:
+            kwargs["params"] = _clean_params(kwargs["params"])
+        response = await self._http.request(method, path, **kwargs)
+        _raise_for_status(response)
+        if response.status_code == 204:
+            return None
+        return response.json()
+
+    async def _request_multipart(self, method: str, path: str, *, files: Dict, data: Dict) -> Any:
+        response = await self._http.request(method, path, files=files, data=data)
+        _raise_for_status(response)
+        return response.json()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSlideClient:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()

synquic_slide/errors.py

@@ -0,0 +1,28 @@
+from typing import Any, Optional
+
+
+class SlideError(Exception):
+    def __init__(self, status_code: int, message: str, body: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class SlideAuthError(SlideError):
+    def __init__(self, message: str = "Invalid or missing API key") -> None:
+        super().__init__(401, message)
+
+
+class SlideScopeError(SlideError):
+    def __init__(self, message: str) -> None:
+        super().__init__(403, message)
+
+
+class SlideNotFoundError(SlideError):
+    def __init__(self, message: str) -> None:
+        super().__init__(404, message)
+
+
+class SlideValidationError(SlideError):
+    def __init__(self, message: str, body: Optional[Any] = None) -> None:
+        super().__init__(400, message, body)

synquic_slide/resources/__init__.py

@@ -0,0 +1,15 @@
+from .contacts import ContactsResource, AsyncContactsResource
+from .email import EmailResource, AsyncEmailResource
+from .whatsapp import WhatsAppResource, AsyncWhatsAppResource
+from .instagram import InstagramResource, AsyncInstagramResource
+from .shopify import ShopifyResource, AsyncShopifyResource
+from .voice import VoiceResource, AsyncVoiceResource
+
+__all__ = [
+    "ContactsResource", "AsyncContactsResource",
+    "EmailResource", "AsyncEmailResource",
+    "WhatsAppResource", "AsyncWhatsAppResource",
+    "InstagramResource", "AsyncInstagramResource",
+    "ShopifyResource", "AsyncShopifyResource",
+    "VoiceResource", "AsyncVoiceResource",
+]

synquic_slide/resources/contacts.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..client import SlideClient, AsyncSlideClient
+
+from ..types import Contact, PaginatedResponse
+
+
+class ContactsResource:
+    def __init__(self, client: SlideClient) -> None:
+        self._c = client
+
+    def list(
+        self,
+        *,
+        page: int = 1,
+        limit: int = 50,
+        search: Optional[str] = None,
+    ) -> PaginatedResponse[Contact]:
+        return self._c._request("GET", "v1/contacts", params={
+            "page": page, "limit": limit, "search": search,
+        })
+
+
+class AsyncContactsResource:
+    def __init__(self, client: AsyncSlideClient) -> None:
+        self._c = client
+
+    async def list(
+        self,
+        *,
+        page: int = 1,
+        limit: int = 50,
+        search: Optional[str] = None,
+    ) -> PaginatedResponse[Contact]:
+        return await self._c._request("GET", "v1/contacts", params={
+            "page": page, "limit": limit, "search": search,
+        })

synquic_slide/resources/email.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from ..client import SlideClient, AsyncSlideClient
+
+from ..types import (
+    EmailContact,
+    EmailTemplate,
+    PaginatedResponse,
+    SendEmailResponse,
+)
+
+
+class EmailResource:
+    def __init__(self, client: SlideClient) -> None:
+        self._c = client
+
+    def send(
+        self,
+        *,
+        recipient: Dict,
+        template_id: str,
+        from_name: str,
+        from_email: str,
+        subject: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        variables: Optional[Dict[str, str]] = None,
+    ) -> SendEmailResponse:
+        body = {
+            "recipient": recipient,
+            "templateId": template_id,
+            "fromName": from_name,
+            "fromEmail": from_email,
+        }
+        if subject is not None:
+            body["subject"] = subject
+        if reply_to is not None:
+            body["replyTo"] = reply_to
+        if variables is not None:
+            body["variables"] = variables
+        return self._c._request("POST", "v1/email/send", json=body)
+
+    def list_templates(self) -> Dict:
+        return self._c._request("GET", "v1/email/templates")
+
+    def get_template(self, template_id: str) -> EmailTemplate:
+        return self._c._request("GET", f"v1/email/templates/{template_id}")
+
+    def list_contacts(
+        self,
+        *,
+        page: int = 1,
+        limit: int = 20,
+        search: Optional[str] = None,
+    ) -> PaginatedResponse[EmailContact]:
+        return self._c._request("GET", "v1/email/contacts", params={
+            "page": page, "limit": limit, "search": search,
+        })
+
+    def upsert_contact(
+        self,
+        *,
+        email: str,
+        first_name: Optional[str] = None,
+        last_name: Optional[str] = None,
+        phone: Optional[str] = None,
+        company: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        custom_fields: Optional[Dict[str, str]] = None,
+    ) -> EmailContact:
+        body: Dict = {"email": email}
+        if first_name is not None:
+            body["firstName"] = first_name
+        if last_name is not None:
+            body["lastName"] = last_name
+        if phone is not None:
+            body["phone"] = phone
+        if company is not None:
+            body["company"] = company
+        if tags is not None:
+            body["tags"] = tags
+        if custom_fields is not None:
+            body["customFields"] = custom_fields
+        return self._c._request("POST", "v1/email/contacts", json=body)
+
+
+class AsyncEmailResource:
+    def __init__(self, client: AsyncSlideClient) -> None:
+        self._c = client
+
+    async def send(
+        self,
+        *,
+        recipient: Dict,
+        template_id: str,
+        from_name: str,
+        from_email: str,
+        subject: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        variables: Optional[Dict[str, str]] = None,
+    ) -> SendEmailResponse:
+        body = {
+            "recipient": recipient,
+            "templateId": template_id,
+            "fromName": from_name,
+            "fromEmail": from_email,
+        }
+        if subject is not None:
+            body["subject"] = subject
+        if reply_to is not None:
+            body["replyTo"] = reply_to
+        if variables is not None:
+            body["variables"] = variables
+        return await self._c._request("POST", "v1/email/send", json=body)
+
+    async def list_templates(self) -> Dict:
+        return await self._c._request("GET", "v1/email/templates")
+
+    async def get_template(self, template_id: str) -> EmailTemplate:
+        return await self._c._request("GET", f"v1/email/templates/{template_id}")
+
+    async def list_contacts(
+        self,
+        *,
+        page: int = 1,
+        limit: int = 20,
+        search: Optional[str] = None,
+    ) -> PaginatedResponse[EmailContact]:
+        return await self._c._request("GET", "v1/email/contacts", params={
+            "page": page, "limit": limit, "search": search,
+        })
+
+    async def upsert_contact(
+        self,
+        *,
+        email: str,
+        first_name: Optional[str] = None,
+        last_name: Optional[str] = None,
+        phone: Optional[str] = None,
+        company: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        custom_fields: Optional[Dict[str, str]] = None,
+    ) -> EmailContact:
+        body: Dict = {"email": email}
+        if first_name is not None:
+            body["firstName"] = first_name
+        if last_name is not None:
+            body["lastName"] = last_name
+        if phone is not None:
+            body["phone"] = phone
+        if company is not None:
+            body["company"] = company
+        if tags is not None:
+            body["tags"] = tags
+        if custom_fields is not None:
+            body["customFields"] = custom_fields
+        return await self._c._request("POST", "v1/email/contacts", json=body)

synquic_slide/resources/instagram.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Dict, Optional
+
+if TYPE_CHECKING:
+    from ..client import SlideClient, AsyncSlideClient
+
+from ..types import (
+    InstagramConversation,
+    InstagramProfile,
+    PaginatedResponse,
+    SendInstagramMessageResponse,
+)
+
+
+class InstagramResource:
+    def __init__(self, client: SlideClient) -> None:
+        self._c = client
+
+    def get_profile(self) -> InstagramProfile:
+        return self._c._request("GET", "v1/instagram/profile")
+
+    def list_conversations(
+        self, *, page: int = 1, limit: int = 20
+    ) -> PaginatedResponse[InstagramConversation]:
+        return self._c._request("GET", "v1/instagram/conversations", params={"page": page, "limit": limit})
+
+    def send_message(
+        self, *, recipient_igsid: str, message: str
+    ) -> SendInstagramMessageResponse:
+        return self._c._request("POST", "v1/instagram/messages", json={
+            "recipientIgsid": recipient_igsid,
+            "message": message,
+        })
+
+    def get_insights(
+        self,
+        *,
+        period: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> Dict:
+        return self._c._request("GET", "v1/instagram/insights", params={
+            "period": period, "since": since, "until": until,
+        })
+
+
+class AsyncInstagramResource:
+    def __init__(self, client: AsyncSlideClient) -> None:
+        self._c = client
+
+    async def get_profile(self) -> InstagramProfile:
+        return await self._c._request("GET", "v1/instagram/profile")
+
+    async def list_conversations(
+        self, *, page: int = 1, limit: int = 20
+    ) -> PaginatedResponse[InstagramConversation]:
+        return await self._c._request("GET", "v1/instagram/conversations", params={"page": page, "limit": limit})
+
+    async def send_message(
+        self, *, recipient_igsid: str, message: str
+    ) -> SendInstagramMessageResponse:
+        return await self._c._request("POST", "v1/instagram/messages", json={
+            "recipientIgsid": recipient_igsid,
+            "message": message,
+        })
+
+    async def get_insights(
+        self,
+        *,
+        period: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
+    ) -> Dict:
+        return await self._c._request("GET", "v1/instagram/insights", params={
+            "period": period, "since": since, "until": until,
+        })

synquic_slide/resources/shopify.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+if TYPE_CHECKING:
+    from ..client import SlideClient, AsyncSlideClient
+
+from ..types import (
+    DiscountValidation,
+    ShopifyCollection,
+    ShopifyOrder,
+    ShopifyProduct,
+)
+
+
+class ShopifyResource:
+    def __init__(self, client: SlideClient) -> None:
+        self._c = client
+
+    def search_products(self, *, q: str, limit: int = 10) -> Dict:
+        return self._c._request("GET", "v1/shopify/products/search", params={"q": q, "limit": limit})
+
+    def get_product_types(self) -> Dict:
+        return self._c._request("GET", "v1/shopify/products/types")
+
+    def get_product(self, product_id: str) -> ShopifyProduct:
+        return self._c._request("GET", f"v1/shopify/products/{product_id}")
+
+    def list_collections(self) -> Dict:
+        return self._c._request("GET", "v1/shopify/collections")
+
+    def get_collection_products(self, collection_id: str, *, limit: int = 50) -> Dict:
+        return self._c._request("GET", f"v1/shopify/collections/{collection_id}/products", params={"limit": limit})
+
+    def get_order_status(self, *, identifier: str) -> Union[ShopifyOrder, List[ShopifyOrder]]:
+        return self._c._request("GET", "v1/shopify/orders/status", params={"identifier": identifier})
+
+    def get_customer_orders(self, *, identifier: str) -> Dict:
+        return self._c._request("GET", "v1/shopify/customers/orders", params={"identifier": identifier})
+
+    def validate_discount(self, *, code: str) -> DiscountValidation:
+        return self._c._request("GET", "v1/shopify/discounts/validate", params={"code": code})
+
+
+class AsyncShopifyResource:
+    def __init__(self, client: AsyncSlideClient) -> None:
+        self._c = client
+
+    async def search_products(self, *, q: str, limit: int = 10) -> Dict:
+        return await self._c._request("GET", "v1/shopify/products/search", params={"q": q, "limit": limit})
+
+    async def get_product_types(self) -> Dict:
+        return await self._c._request("GET", "v1/shopify/products/types")
+
+    async def get_product(self, product_id: str) -> ShopifyProduct:
+        return await self._c._request("GET", f"v1/shopify/products/{product_id}")
+
+    async def list_collections(self) -> Dict:
+        return await self._c._request("GET", "v1/shopify/collections")
+
+    async def get_collection_products(self, collection_id: str, *, limit: int = 50) -> Dict:
+        return await self._c._request("GET", f"v1/shopify/collections/{collection_id}/products", params={"limit": limit})
+
+    async def get_order_status(self, *, identifier: str) -> Union[ShopifyOrder, List[ShopifyOrder]]:
+        return await self._c._request("GET", "v1/shopify/orders/status", params={"identifier": identifier})
+
+    async def get_customer_orders(self, *, identifier: str) -> Dict:
+        return await self._c._request("GET", "v1/shopify/customers/orders", params={"identifier": identifier})
+
+    async def validate_discount(self, *, code: str) -> DiscountValidation:
+        return await self._c._request("GET", "v1/shopify/discounts/validate", params={"code": code})