zelf-sdk 1.0.0__py3-none-any.whl

zelf/__init__.py

@@ -0,0 +1,218 @@
+# Generated by codegen. Do not edit by hand.
+
+"""Python client for the ZelfAI APIs (spec version 1.0.0)."""
+
+from . import webhooks
+from ._client import AsyncZelfAPIClient, ZelfAPIClient, ZelfAPIClientAsync
+from ._exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    ErrorCode,
+    InternalServerError,
+    NotAcceptableError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ResponseParseError,
+    ServiceUnavailableError,
+    ZelfAPIError,
+    ZelfConnectionError,
+    ZelfError,
+    ZelfTimeoutError,
+)
+from ._models import (
+    AiAnalysis,
+    AiAnalysisCreateRequest,
+    AiAnalysisResult,
+    AiAnalysisRun,
+    Brand,
+    BrandAccount,
+    BrandAccountGroups,
+    BrandAccountsWriteRequest,
+    BrandCatalog,
+    BrandCatalogItem,
+    BrandCreateSubBrandRequest,
+    BrandKeywords,
+    Comment,
+    CommentAuthor,
+    Content,
+    ContentActionRequestRequest,
+    ContentActionResponse,
+    ContentCreator,
+    ContentDiscovery,
+    ContentDiscoveryRequestRequest,
+    ContentFilterInputRequest,
+    ContentScopeRequest,
+    ContentStatistics,
+    Creator,
+    CreatorSync,
+    CreatorSyncCreateRequest,
+    CreatorVetting,
+    CreatorVettingRequest,
+    CreatorVettingResult,
+    CreatorVettingRun,
+    Detection,
+    DetectionBrandHint,
+    DetectionBrandHintRequest,
+    DetectionBrandResult,
+    DetectionBrandSummary,
+    DetectionContext,
+    DetectionContextInputRequest,
+    DetectionCreateRequest,
+    DetectionHints,
+    DetectionHintsRequest,
+    DetectionPlacement,
+    DetectionResult,
+    DetectionSummary,
+    DetectionVideo,
+    Error,
+    Error1,
+    Error2,
+    Error3,
+    Error4,
+    Error5,
+    Error6,
+    Error7,
+    Error400,
+    Error401,
+    Error403,
+    Error404,
+    Error406,
+    Error429,
+    Error500,
+    Error503,
+    PatchedBrandUpdateRequest,
+    PatchedWebhookSubscriptionUpdateRequest,
+    ResultFile,
+    SafetyCheckRequest,
+    Usage,
+    UsageScope,
+    UsageWindow,
+    WebhookAvailableEvent,
+    WebhookData,
+    WebhookDeleteAcknowledgement,
+    WebhookDelivery,
+    WebhookFile,
+    WebhookPush,
+    WebhookSecret,
+    WebhookSecretCreated,
+    WebhookSecretCreateRequest,
+    WebhookSubscription,
+    WebhookSubscriptionCreated,
+    WebhookSubscriptionCreateRequest,
+)
+from ._pagination import AsyncPage, Envelope, Page
+from ._types import NOT_GIVEN, NotGiven
+from ._version import __version__
+from .webhooks import EventType, WebhookEvent, WebhookHandler
+
+__all__ = [
+    "AiAnalysis",
+    "AiAnalysisCreateRequest",
+    "AiAnalysisResult",
+    "AiAnalysisRun",
+    "AsyncPage",
+    "AsyncZelfAPIClient",
+    "AuthenticationError",
+    "BadRequestError",
+    "Brand",
+    "BrandAccount",
+    "BrandAccountGroups",
+    "BrandAccountsWriteRequest",
+    "BrandCatalog",
+    "BrandCatalogItem",
+    "BrandCreateSubBrandRequest",
+    "BrandKeywords",
+    "Comment",
+    "CommentAuthor",
+    "ConflictError",
+    "Content",
+    "ContentActionRequestRequest",
+    "ContentActionResponse",
+    "ContentCreator",
+    "ContentDiscovery",
+    "ContentDiscoveryRequestRequest",
+    "ContentFilterInputRequest",
+    "ContentScopeRequest",
+    "ContentStatistics",
+    "Creator",
+    "CreatorSync",
+    "CreatorSyncCreateRequest",
+    "CreatorVetting",
+    "CreatorVettingRequest",
+    "CreatorVettingResult",
+    "CreatorVettingRun",
+    "Detection",
+    "DetectionBrandHint",
+    "DetectionBrandHintRequest",
+    "DetectionBrandResult",
+    "DetectionBrandSummary",
+    "DetectionContext",
+    "DetectionContextInputRequest",
+    "DetectionCreateRequest",
+    "DetectionHints",
+    "DetectionHintsRequest",
+    "DetectionPlacement",
+    "DetectionResult",
+    "DetectionSummary",
+    "DetectionVideo",
+    "Envelope",
+    "Error",
+    "Error1",
+    "Error2",
+    "Error3",
+    "Error4",
+    "Error400",
+    "Error401",
+    "Error403",
+    "Error404",
+    "Error406",
+    "Error429",
+    "Error5",
+    "Error500",
+    "Error503",
+    "Error6",
+    "Error7",
+    "ErrorCode",
+    "EventType",
+    "InternalServerError",
+    "NOT_GIVEN",
+    "NotAcceptableError",
+    "NotFoundError",
+    "NotGiven",
+    "Page",
+    "PatchedBrandUpdateRequest",
+    "PatchedWebhookSubscriptionUpdateRequest",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ResponseParseError",
+    "ResultFile",
+    "SafetyCheckRequest",
+    "ServiceUnavailableError",
+    "Usage",
+    "UsageScope",
+    "UsageWindow",
+    "WebhookAvailableEvent",
+    "WebhookData",
+    "WebhookDeleteAcknowledgement",
+    "WebhookDelivery",
+    "WebhookEvent",
+    "WebhookFile",
+    "WebhookHandler",
+    "WebhookPush",
+    "WebhookSecret",
+    "WebhookSecretCreateRequest",
+    "WebhookSecretCreated",
+    "WebhookSubscription",
+    "WebhookSubscriptionCreateRequest",
+    "WebhookSubscriptionCreated",
+    "ZelfAPIClient",
+    "ZelfAPIClientAsync",
+    "ZelfAPIError",
+    "ZelfConnectionError",
+    "ZelfError",
+    "ZelfTimeoutError",
+    "webhooks",
+    "__version__",
+]

zelf/_client.py

@@ -0,0 +1,146 @@
+# Generated by codegen. Do not edit by hand.
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._transport import AsyncTransport, SyncTransport
+from .resources.ai_analysis import AiAnalysisResource, AsyncAiAnalysisResource
+from .resources.brand_accounts import AsyncBrandAccountsResource, BrandAccountsResource
+from .resources.brands import AsyncBrandsResource, BrandsResource
+from .resources.comments import AsyncCommentsResource, CommentsResource
+from .resources.content import AsyncContentResource, ContentResource
+from .resources.creator_sync import AsyncCreatorSyncResource, CreatorSyncResource
+from .resources.creator_vetting import AsyncCreatorVettingResource, CreatorVettingResource
+from .resources.creators import AsyncCreatorsResource, CreatorsResource
+from .resources.detection import AsyncDetectionResource, DetectionResource
+from .resources.sub_brands import AsyncSubBrandsResource, SubBrandsResource
+from .resources.usage import AsyncUsageResource, UsageResource
+from .resources.webhooks import AsyncWebhooksResource, WebhooksResource
+
+DEFAULT_BASE_URL = "https://api.hellozelf.com"
+BASE_URL_ENV = "ZELF_BASE_URL"
+
+
+def default_base_url() -> str:
+    """The explicit argument wins, then ZELF_BASE_URL, then the production API."""
+    return os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
+
+
+API_KEY_ENV = "ZELF_API_KEY"
+
+
+class ZelfAPIClient:
+    """Synchronous client for the ZelfAI APIs.
+
+    The key is read from the `api_key` argument, falling back to the
+    `ZELF_API_KEY` environment variable. It is sent as the `x-api-key`
+    header and is kept out of `repr()` output.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        retry_writes: bool = False,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = SyncTransport(
+            api_key or os.environ.get(API_KEY_ENV, ""),
+            base_url=base_url or default_base_url(),
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_writes=retry_writes,
+            default_headers=default_headers,
+            http_client=http_client,
+        )
+        self.ai_analysis = AiAnalysisResource(self._transport)
+        self.brand_accounts = BrandAccountsResource(self._transport)
+        self.brands = BrandsResource(self._transport)
+        self.comments = CommentsResource(self._transport)
+        self.content = ContentResource(self._transport)
+        self.creator_sync = CreatorSyncResource(self._transport)
+        self.creator_vetting = CreatorVettingResource(self._transport)
+        self.creators = CreatorsResource(self._transport)
+        self.detection = DetectionResource(self._transport)
+        self.sub_brands = SubBrandsResource(self._transport)
+        self.usage = UsageResource(self._transport)
+        self.webhooks = WebhooksResource(self._transport)
+
+    def __repr__(self) -> str:
+        return f"ZelfAPIClient(base_url={self._transport.base_url!r}, api_key='***')"
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> ZelfAPIClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class ZelfAPIClientAsync:
+    """Asynchronous client for the ZelfAI APIs.
+
+    The key is read from the `api_key` argument, falling back to the
+    `ZELF_API_KEY` environment variable. It is sent as the `x-api-key`
+    header and is kept out of `repr()` output.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        retry_writes: bool = False,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(
+            api_key or os.environ.get(API_KEY_ENV, ""),
+            base_url=base_url or default_base_url(),
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_writes=retry_writes,
+            default_headers=default_headers,
+            http_client=http_client,
+        )
+        self.ai_analysis = AsyncAiAnalysisResource(self._transport)
+        self.brand_accounts = AsyncBrandAccountsResource(self._transport)
+        self.brands = AsyncBrandsResource(self._transport)
+        self.comments = AsyncCommentsResource(self._transport)
+        self.content = AsyncContentResource(self._transport)
+        self.creator_sync = AsyncCreatorSyncResource(self._transport)
+        self.creator_vetting = AsyncCreatorVettingResource(self._transport)
+        self.creators = AsyncCreatorsResource(self._transport)
+        self.detection = AsyncDetectionResource(self._transport)
+        self.sub_brands = AsyncSubBrandsResource(self._transport)
+        self.usage = AsyncUsageResource(self._transport)
+        self.webhooks = AsyncWebhooksResource(self._transport)
+
+    def __repr__(self) -> str:
+        return f"ZelfAPIClientAsync(base_url={self._transport.base_url!r}, api_key='***')"
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> ZelfAPIClientAsync:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+
+# The earlier name for the asynchronous client; both are the same class.
+AsyncZelfAPIClient = ZelfAPIClientAsync

zelf/_exceptions.py

@@ -0,0 +1,190 @@
+# Generated by codegen. Do not edit by hand.
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import httpx
+
+
+class ZelfError(Exception):
+    pass
+
+
+class ZelfConnectionError(ZelfError):
+    def __init__(self, message: str = "Could not reach the ZelfAI API.") -> None:
+        super().__init__(message)
+
+
+class ZelfTimeoutError(ZelfConnectionError):
+    def __init__(self, message: str = "Request to the ZelfAI API timed out.") -> None:
+        super().__init__(message)
+
+
+class ResponseParseError(ZelfError):
+    """A row in a 2xx response did not match the model the SDK expects.
+
+    The call reached the API and the API answered, so this is not an APIError.
+    The field that failed and the response's log_id are carried so the call can
+    be reported, and the pydantic error stays on `__cause__`.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field: str | None = None,
+        log_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.field = field
+        self.log_id = log_id
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.field:
+            parts.append(f"(field={self.field})")
+        if self.log_id:
+            parts.append(f"(log_id={self.log_id})")
+        return " ".join(parts)
+
+
+class ZelfAPIError(ZelfError):
+    status_code: int = 0
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        details: dict[str, Any] | None = None,
+        log_id: str | None = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.details = details or {}
+        self.log_id = log_id
+        self.response = response
+
+    def __str__(self) -> str:
+        parts = [f"{self.status_code}"]
+        if self.code:
+            parts.append(self.code)
+        parts.append(self.message)
+        if self.log_id:
+            parts.append(f"(log_id={self.log_id})")
+        return " ".join(parts)
+
+
+def parse(response: httpx.Response) -> ZelfAPIError:
+    code = message = log_id = None
+    details: dict[str, Any] = {}
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict):
+        log_id = body.get("log_id")
+        error = body.get("error")
+        if isinstance(error, dict):
+            code = error.get("code")
+            message = error.get("message")
+            details = error.get("details") or {}
+    cls = STATUS_MAP.get(response.status_code, ZelfAPIError)
+    return cls(
+        message or f"HTTP {response.status_code} from the ZelfAI API.",
+        status_code=response.status_code,
+        code=code,
+        details=details,
+        log_id=log_id,
+        response=response,
+    )
+
+
+class BadRequestError(ZelfAPIError):
+    """`VALIDATION_ERROR`, `INVALID_ID`, `BRAND_ID_REQUIRED`."""
+
+    status_code = 400
+
+
+class AuthenticationError(ZelfAPIError):
+    """`INVALID_API_KEY`, `EXPIRED_API_KEY`, `REVOKED_API_KEY`."""
+
+    status_code = 401
+
+
+class PermissionDeniedError(ZelfAPIError):
+    """`PERMISSION_DENIED`."""
+
+    status_code = 403
+
+
+class NotFoundError(ZelfAPIError):
+    """`NOT_FOUND`."""
+
+    status_code = 404
+
+
+class NotAcceptableError(ZelfAPIError):
+    """`NOT_ACCEPTABLE`."""
+
+    status_code = 406
+
+
+class ConflictError(ZelfAPIError):
+    status_code = 409
+
+
+class RateLimitError(ZelfAPIError):
+    """`RATE_LIMIT_EXCEEDED`."""
+
+    status_code = 429
+
+
+class InternalServerError(ZelfAPIError):
+    """`INTERNAL_ERROR`."""
+
+    status_code = 500
+
+
+class ServiceUnavailableError(ZelfAPIError):
+    """`SERVICE_UNAVAILABLE`."""
+
+    status_code = 503
+
+
+class EmptyResultError(NotFoundError):
+    """A single-object read matched nothing. The API returns 200 with an
+    empty `results` array instead of a 404, so the SDK raises this."""
+
+
+STATUS_MAP: dict[int, type[ZelfAPIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    406: NotAcceptableError,
+    409: ConflictError,
+    429: RateLimitError,
+    500: InternalServerError,
+    503: ServiceUnavailableError,
+}
+
+ErrorCode = Literal[
+    "BRAND_ID_REQUIRED",
+    "EXPIRED_API_KEY",
+    "INTERNAL_ERROR",
+    "INVALID_API_KEY",
+    "INVALID_ID",
+    "NOT_ACCEPTABLE",
+    "NOT_FOUND",
+    "PERMISSION_DENIED",
+    "RATE_LIMIT_EXCEEDED",
+    "REVOKED_API_KEY",
+    "SERVICE_UNAVAILABLE",
+    "VALIDATION_ERROR",
+]