Merge pull request #4 from ofspectrum/sync-sdk-v1.1.5

Sync SDK v1.1.5 from neo

Author: jlw463195395

AGENT_GUIDE.md

@@ -42,12 +42,20 @@ else:
 
 # Check your quota.
 quota = client.quotas.get_encode_quota()
-print(f"Remaining encode quota: {quota.remaining}/{quota.quota_limit} seconds")
+print(f"Remaining encode quota: {quota.remaining}/{quota.limit} seconds")
 ```
 
+## Building With AI Coding Agents
+
+If you are building an app or internal tool with this SDK, see [AGENT_GUIDE.md](./AGENT_GUIDE.md). It explains token modeling patterns, notebook/provenance guidance, security notes, test flows, and includes a copyable prompt for AI coding agents such as Codex.
+
+## Test Audio
+
+Synthetic WAV files for encode/decode smoke tests are available in [`examples/audio`](./examples/audio). They contain no third-party audio and are intended for local SDK verification.
+
 ## Token Management
 
-Standard tokens are the simplest option. Pro tokens support workflow-specific verification-key configuration. Enterprise token configuration is available for eligible enterprise accounts or existing enterprise tokens.
+Standard tokens are the simplest option. Pro tokens support workflow-specific verification-key configuration.
 
 ```python
 import os
@@ -72,7 +80,7 @@ token = client.tokens.update(
     name="New Name",
 )
 
-# Update a Pro or eligible Enterprise token verification key.
+# Update a Pro token verification key.
 token = client.tokens.update(
     token_id="token-uuid",
     public_key=verification_key,
@@ -132,6 +140,15 @@ print(f"Encoded {result.audio_duration:.2f}s of PCM")
 
 Attach notes and media files to tokens. Private notebooks require a credential, and limits depend on your account and token configuration.
 
+Notebook limits:
+
+| Token Type | Public Notebooks | Private Notebooks |
+|------------|------------------|-------------------|
+| `standard` | 1 | 0 |
+| `pro` | 1 | 1 |
+
+If the limit is reached, the SDK raises a `ValidationError` with a customer-facing message.
+
 ```python
 notebook = client.notebooks.create(
     token_id=token.id,
@@ -160,10 +177,10 @@ notebooks = client.notebooks.list(token_id=token.id)
 
 ```python
 quota = client.quotas.get_encode_quota()
-print(f"Remaining encode quota: {quota.remaining}")
+print(f"Remaining encode quota: {quota.remaining}/{quota.limit}")
 
 decode_quota = client.quotas.get_decode_quota()
-print(f"Remaining decode quota: {decode_quota.remaining}")
+print(f"Remaining decode quota: {decode_quota.remaining}/{decode_quota.limit}")
 
 if client.quotas.check_encode_available(duration_seconds=300):
     result = client.audio.encode(audio="input.mp3", token_id=token.id)
@@ -186,7 +203,7 @@ try:
 except RateLimitError as e:
     print(f"Rate limited. Retry after {e.retry_after} seconds")
 except QuotaExceededError as e:
-    print(f"Quota exceeded for {e.service}")
+    print(e.message)
 except WatermarkExistsError:
     print("Audio already has a watermark")
 except AuthenticationError:

README.md

@@ -26,10 +26,10 @@
 
     # Check quota
     quota = client.quotas.get_encode_quota()
-    print(f"Remaining: {quota.remaining}/{quota.quota_limit}")
+    print(f"Remaining: {quota.remaining}/{quota.limit}")
 """
 
-__version__ = "1.1.4"
+__version__ = "1.1.5"
 __author__ = "OfSpectrum"
 
 from .client import OfSpectrum, AsyncOfSpectrum

examples/audio/sample-broadband-10s.wav

@@ -167,6 +167,71 @@ def __init__(self, message: str = "Network error", **kwargs):
 }
 
 
+def _raise_direct_error(
+    error_code: str,
+    message: str,
+    status_code: int,
+    details: Optional[Dict[str, Any]] = None,
+):
+    """Raise SDK exceptions for legacy/direct API error payloads."""
+    details = details or {}
+
+    # Map common legacy error codes used by tokens_router and other endpoints.
+    if error_code == "QuotaExceeded":
+        raise QuotaExceededError(
+            message="Token quota exceeded. Please upgrade your plan or contact support.",
+            code=error_code,
+            status_code=status_code or 429,
+            details={},
+        )
+    elif error_code in ("QuotaMissing", "QuotaCheckFailed"):
+        raise QuotaExceededError(
+            message="Token quota is temporarily unavailable. Please try again later or contact support.",
+            code=error_code,
+            status_code=status_code or 500,
+            details={},
+        )
+    elif error_code in ("InsufficientBalance", "insufficient_balance") or status_code == 402:
+        raise QuotaExceededError(
+            message="Insufficient balance. Please add funds or choose a subscription.",
+            code=error_code,
+            status_code=status_code or 402,
+            details={},
+        )
+    elif error_code == "Unauthorized":
+        raise AuthenticationError(message=message, code=error_code, status_code=status_code or 403, details=details)
+    elif error_code in ("DuplicateName", "ValidationError"):
+        raise ValidationError(message=message, code=error_code, status_code=status_code or 400, details=details)
+    elif error_code == "Missing required fields" or error_code == "InvalidField":
+        raise ValidationError(message=message, code=error_code, status_code=status_code or 400, details=details)
+    elif error_code == "UnableToGenerate":
+        raise OfSpectrumError(message=message, code=error_code, status_code=status_code or 500, details=details)
+    else:
+        raise OfSpectrumError(message=message, code=error_code, status_code=status_code or 500, details=details)
+
+
+def _raise_detail_error(message: str, status_code: int):
+    """Raise sanitized SDK exceptions for FastAPI detail strings."""
+    if message == "Only one public notebook allowed per token":
+        raise ValidationError(
+            message="This token already has a public notebook. Each token supports one public notebook.",
+            code="NotebookLimit",
+            status_code=status_code or 400,
+            details={},
+        )
+    if message == "Private notebook limit reached for this token":
+        raise ValidationError(
+            message=(
+                "Private notebook limit reached for this token. Standard tokens do not support "
+                "private notebooks; Pro tokens support one private notebook."
+            ),
+            code="NotebookLimit",
+            status_code=status_code or 400,
+            details={},
+        )
+    raise OfSpectrumError(message=message, status_code=status_code)
+
+
 def raise_for_error(response_data, status_code: int):
     """
     Parse API error response and raise appropriate exception.
@@ -187,29 +252,20 @@ def raise_for_error(response_data, status_code: int):
     if "error" in response_data and isinstance(response_data.get("error"), str):
         error_code = response_data.get("error")
         message = response_data.get("message", error_code)
-
-        # Map common error codes
-        if error_code == "QuotaExceeded":
-            raise QuotaExceededError(message=message, status_code=status_code or 429)
-        elif error_code == "QuotaMissing" or error_code == "QuotaCheckFailed":
-            raise QuotaExceededError(message=message, status_code=status_code or 500)
-        elif error_code == "Unauthorized":
-            raise AuthenticationError(message=message, status_code=status_code or 403)
-        elif error_code == "DuplicateName":
-            raise ValidationError(message=message, status_code=status_code or 400)
-        elif error_code == "Missing required fields" or error_code == "InvalidField":
-            raise ValidationError(message=message, status_code=status_code or 400)
-        elif error_code == "UnableToGenerate":
-            raise OfSpectrumError(message=message, code=error_code, status_code=status_code or 500)
-        else:
-            raise OfSpectrumError(message=message, code=error_code, status_code=status_code or 500)
+        _raise_direct_error(error_code, message, status_code, response_data)
 
     if response_data.get("status") != "error":
         # Also check for FastAPI validation errors (detail field)
         if "detail" in response_data and status_code >= 400:
             detail = response_data.get("detail")
             if isinstance(detail, str):
-                raise OfSpectrumError(message=detail, status_code=status_code)
+                _raise_detail_error(detail, status_code)
+            elif isinstance(detail, dict):
+                error_code = detail.get("error") or detail.get("code")
+                message = detail.get("message") or detail.get("detail") or error_code or "API request failed"
+                if isinstance(error_code, str):
+                    _raise_direct_error(error_code, message, status_code, detail)
+                raise OfSpectrumError(message=str(message), status_code=status_code, details=detail)
             elif isinstance(detail, list):
                 # FastAPI validation error format
                 messages = [f"{d.get('loc', ['?'])[-1]}: {d.get('msg', '?')}" for d in detail]

examples/audio/sample-speech-like-12s.wav

@@ -3,59 +3,58 @@
 """
 
 from dataclasses import dataclass, field
-from typing import Optional, List, Literal
+from typing import Optional, List
 
 
 @dataclass
 class Quota:
     """Represents a service quota"""
 
-    service_name: str
-    quota_type: Literal["request_limit", "duration_limit"]
-    quota_limit: int
-    current_usage: int
+    limit: int
+    used: int
     reset_at: Optional[str] = None
+    _service: str = field(default="", repr=False)
+    _kind: str = field(default="", repr=False)
 
     @property
     def remaining(self) -> int:
         """Get remaining quota"""
-        return max(0, self.quota_limit - self.current_usage)
+        return max(0, self.limit - self.used)
 
     @property
     def used_percentage(self) -> float:
         """Get percentage of quota used"""
-        if self.quota_limit == 0:
+        if self.limit == 0:
             return 0.0
-        return (self.current_usage / self.quota_limit) * 100
+        return (self.used / self.limit) * 100
 
     @property
     def is_exceeded(self) -> bool:
         """Check if quota is exceeded"""
-        return self.current_usage >= self.quota_limit
+        return self.used >= self.limit
 
     @classmethod
     def from_dict(cls, data: dict) -> "Quota":
         """Create Quota from API response dict.
 
-        Handles both snake_case (from /quotas/all) and camelCase (from /quota) formats.
+        Handles API response formats.
         """
-        # Handle both snake_case and camelCase field names
-        service_name = data.get("service_name") or data.get("serviceName", "")
-        quota_type = data.get("quota_type") or data.get("quotaType", "request_limit")
-        quota_limit = data.get("quota_limit") or data.get("quotaLimit", 0)
-        current_usage = data.get("current_usage") or data.get("currentUsage", 0)
+        service = data.get("service_name") or data.get("serviceName", "")
+        kind = data.get("quota_type") or data.get("quotaType", "request_limit")
+        limit = data.get("quota_limit") or data.get("quotaLimit", 0)
+        used = data.get("current_usage") or data.get("currentUsage", 0)
         reset_at = data.get("reset_at") or data.get("resetDate") or data.get("reset_date")
 
         return cls(
-            service_name=service_name,
-            quota_type=quota_type,
-            quota_limit=int(quota_limit) if quota_limit else 0,
-            current_usage=int(current_usage) if current_usage else 0,
+            limit=int(limit) if limit else 0,
+            used=int(used) if used else 0,
             reset_at=reset_at,
+            _service=service,
+            _kind=kind,
         )
 
     def __str__(self) -> str:
-        return f"{self.service_name}: {self.current_usage}/{self.quota_limit} ({self.quota_type})"
+        return f"remaining: {self.remaining}"
 
 
 @dataclass
@@ -64,20 +63,20 @@ class QuotaList:
 
     quotas: List[Quota] = field(default_factory=list)
 
-    def get(self, service_name: str) -> Optional[Quota]:
+    def _get_by_service(self, service: str) -> Optional[Quota]:
         """Get quota for a specific service"""
         for quota in self.quotas:
-            if quota.service_name == service_name:
+            if quota._service == service:
                 return quota
         return None
 
     def get_encode_quota(self) -> Optional[Quota]:
         """Get AudioWatermarkEncode quota"""
-        return self.get("AudioWatermarkEncode")
+        return self._get_by_service("AudioWatermarkEncode")
 
     def get_decode_quota(self) -> Optional[Quota]:
         """Get AudioWatermarkDecode quota"""
-        return self.get("AudioWatermarkDecode")
+        return self._get_by_service("AudioWatermarkDecode")
 
     @classmethod
     def from_list(cls, data: List[dict]) -> "QuotaList":

ofspectrum/__init__.py

@@ -38,16 +38,14 @@ class TokenCreateParams:
     """Parameters for creating a new token"""
 
     name: str
-    token_type: Literal["standard", "pro", "enterprise"] = "standard"
+    token_type: Literal["standard", "pro"] = "standard"
     public_key: Optional[int] = None
-    enterprise_verification: bool = False
 
     def to_dict(self) -> dict:
         """Convert to API request dict"""
         data = {
             "name": self.name,
             "token_type": self.token_type,
-            "enterprise_verification": self.enterprise_verification,
         }
         if self.public_key is not None:
             data["public_key"] = self.public_key

ofspectrum/exceptions.py

@@ -32,7 +32,7 @@ def list(self, token_id: str) -> List[Notebook]:
         data = response.json()
         raise_for_error(data, response.status_code)
 
-        # Backend returns a direct list
+        # API returns a direct list
         notes_data = data if isinstance(data, list) else data.get("data", {}).get("notes", [])
         return [Notebook.from_dict(n) for n in notes_data]
 
@@ -47,15 +47,14 @@ def get(self, note_id: str) -> Notebook:
             Notebook object
 
         Note:
-            The backend doesn't have a single-note GET endpoint.
-            This uses PATCH with empty body to get the note (returns current state).
+            This returns the current notebook state when available.
         """
-        # Use PATCH with empty body - backend returns the updated note
+        # Use an empty update request to return the current note state.
         response = self._patch(f"/watermark-notes/{note_id}", data={})
         data = response.json()
         raise_for_error(data, response.status_code)
 
-        # Backend returns the note directly or wrapped in data
+        # API returns the note directly or wrapped in data
         note_data = data if isinstance(data, dict) and "id" in data else data.get("data", {})
         return Notebook.from_dict(note_data)
 
@@ -75,7 +74,7 @@ def create(
             note_name: Notebook name/title
             text_content: Notebook content (markdown supported)
             is_public: Whether the notebook is publicly visible (default: True)
-            credential_val: Credential for private notes (default: "123" if not provided)
+            credential_val: Optional credential for private notes
 
         Returns:
             Newly created Notebook object
@@ -100,7 +99,7 @@ def create(
         data = response.json()
         raise_for_error(data, response.status_code)
 
-        # Backend returns the note directly
+        # API returns the note directly
         note_data = data if isinstance(data, dict) and "id" in data else data.get("data", {})
         return Notebook.from_dict(note_data)
 
@@ -141,7 +140,7 @@ def update(
         data = response.json()
         raise_for_error(data, response.status_code)
 
-        # Backend returns the note directly
+        # API returns the note directly
         note_data = data if isinstance(data, dict) and "id" in data else data.get("data", {})
         return Notebook.from_dict(note_data)
 
@@ -230,7 +229,7 @@ def upload_media(
         resp_data = response.json()
         raise_for_error(resp_data, response.status_code)
 
-        # Backend returns the media record directly
+        # API returns the media record directly
         return resp_data if isinstance(resp_data, dict) else resp_data.get("data", {})
 
     def delete_media(self, media_id: str) -> bool:
@@ -270,7 +269,7 @@ def get_media_url(self, media_id: str) -> str:
         data = response.json()
         raise_for_error(data, response.status_code)
 
-        # Backend returns {"url": "..."} or {"data": {"url": "..."}}
+        # API returns {"url": "..."} or {"data": {"url": "..."}}
         if isinstance(data, dict):
             return data.get("url", "") or data.get("data", {}).get("url", "")
         return ""