spaps 0.1.0__py3-none-any.whl

spaps-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: spaps
+Version: 0.1.0
+Summary: Sweet Potato Authentication & Payment Service Python client
+Project-URL: Homepage, https://api.sweetpotato.dev
+Project-URL: Repository, https://github.com/sweet-potato/spaps
+Author-email: Sweet Potato Team <support@sweetpotato.dev>
+License: MIT License
+        
+        Copyright (c) 2025 Sweet Potato Team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+License-File: LICENSE
+Keywords: authentication,payments,spaps,sweet-potato
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Requires-Dist: httpx<0.28.0,>=0.27.0
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Provides-Extra: dev
+Requires-Dist: build<2.0.0,>=1.2.1; extra == 'dev'
+Requires-Dist: httpx<0.28.0,>=0.27.0; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.10.0; extra == 'dev'
+Requires-Dist: pydantic<3.0.0,>=2.7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx<0.23.0,>=0.22.0; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.5.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+---
+id: spaps-python-sdk
+title: Sweet Potato Python Client
+category: sdk
+tags:
+  - sdk
+  - python
+  - client
+ai_summary: |
+  Explains installation, configuration, and usage patterns for the spaps Python
+  SDK, including environment setup, async support, and integration guidance for
+  backend services.
+last_updated: 2025-02-14
+---
+
+# Sweet Potato Python Client
+
+> Python SDK for the Sweet Potato Authentication & Payment Service (SPAPS).
+
+This package is under active development. Follow the TDD plan in `TDD_PLAN.md`
+to track progress and upcoming milestones.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install spaps
+```
+
+For local development inside this repository:
+
+```bash
+pip install -e .[dev]
+```
+
+## Development
+
+```bash
+pytest
+```
+
+### Available clients
+
+- `AuthClient` – wallet, email/password, and magic link flows
+- `SessionsClient` – current session, validation, listing, revocation
+- `PaymentsClient` – checkout sessions, wallet deposits, crypto invoices
+- `UsageClient` – feature usage snapshots, recording, aggregated history
+- `SecureMessagesClient` – encrypted message creation and retrieval
+- `MetricsClient` – health and metrics convenience helpers
+
+### Quickstart
+
+```python
+from spaps_client import SpapsClient
+
+spaps = SpapsClient(base_url="http://localhost:3300", api_key="test_key_local_dev_only")
+
+# Authenticate (tokens are persisted automatically)
+spaps.auth.sign_in_with_password(email="user@example.com", password="Secret123!")
+
+# Call downstream services using the stored access token
+current = spaps.sessions.get_current_session()
+print(current.session_id)
+
+checkout = spaps.payments.create_checkout_session(
+    price_id="price_123",
+    mode="subscription",
+    success_url="https://example.com/success",
+    cancel_url="https://example.com/cancel",
+)
+print(checkout.checkout_url)
+
+spaps.close()
+```
+
+Configure retry/backoff and structured logging when constructing the client:
+
+```python
+from spaps_client import SpapsClient, RetryConfig, default_logging_hooks
+
+spaps = SpapsClient(
+    base_url="http://localhost:3300",
+    api_key="test_key_local_dev_only",
+    retry_config=RetryConfig(max_attempts=4, backoff_factor=0.2),
+    logging_hooks=default_logging_hooks(),
+)
+```
+
+### Async Quickstart
+
+```python
+import asyncio
+from spaps_client import AsyncSpapsClient
+
+async def main():
+    client = AsyncSpapsClient(base_url="http://localhost:3300", api_key="test_key_local_dev_only")
+    try:
+        await client.auth.sign_in_with_password(email="user@example.com", password="Secret123!")
+        current = await client.sessions.list_sessions()
+        print(len(current.sessions))
+    finally:
+        await client.aclose()
+
+asyncio.run(main())
+```
+
+### Useful Scripts
+
+```bash
+npm run test:python-client   # run pytest from repo root
+npm run lint:python-client   # ruff linting
+npm run typecheck:python-client # mypy type checking
+npm run build:python-client  # build wheel/sdist and run twine check
+npm run publish:python-client # build and upload via twine (requires PYPI_TOKEN)
+```
+
+Refer to `docs/RELEASE_CHECKLIST.md` for the full release process.
+
+Refer to the repository root documentation for integration details.
+
+## Documentation
+
+- [Quickstart (Python section)](../../docs/getting-started/quickstart.md#python-example---using-spaps)
+- [Python Backend Integration Guide](../../docs/guides/python-backend.md)
+- API references under `docs/api/` include Python usage snippets for sessions, payments, usage, whitelist, and secure messages.

spaps-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+spaps_client/__init__.py,sha256=W3NbWfDwSIpmZEQOggm407Vd60Q50V-x2WJpuao9L4c,4049
+spaps_client/async_client.py,sha256=2IdoQnRmKet4cgOagNtGlIyYe3wkEZa3I4NkeNU6gf0,7489
+spaps_client/auth.py,sha256=y2V0liV2oWKQ_Os5hqjzBaHtYVQy9TcFeZEgL7VAmTI,12950
+spaps_client/auth_async.py,sha256=pSoDcqpnSQrcavY0qpFF9tt3q2Fr3-jj0wA2OzHegDE,9152
+spaps_client/client.py,sha256=XTGnaHnrCVvZ7StTINthh3ZfhIJJTqV3vrhBnAvxBjI,7190
+spaps_client/config.py,sha256=CzjtyZWnlvRuOirTxjvNipdky6-f5Hlz_lZ1VKry5lQ,2183
+spaps_client/crypto.py,sha256=f6qmfynGstmwaj453RzmSwN2Z-CMzYbmWc2L4QBS4LY,8210
+spaps_client/crypto_async.py,sha256=ZjrU2lr4d11mKavflWeByyQ3x3A0WfEaRnWdbV38xMw,4452
+spaps_client/http.py,sha256=CzhS0lNWWDRncTRdB5mwZXB58r5nkc6ivfKq63g5OTo,5781
+spaps_client/http_async.py,sha256=NfhT5S0HUnHMsS0RGC_2dsU6tbASJO9ZXFaNPcusCew,2819
+spaps_client/metrics.py,sha256=hsP3cKu6Od3LqQQCxrX_F-gY8psIa3huIy_4EtF4ypo,1634
+spaps_client/metrics_async.py,sha256=Ckl4182Q828BMxkQjJWh-ERwBvnidl00zsAPMrktBIY,1443
+spaps_client/payments.py,sha256=NJJC9xgmk7T71bH_0rU4m6_1_F7JpVsnO5kVo2Uybng,11887
+spaps_client/payments_async.py,sha256=Rj2ftZ1_W-hRneTCAG9EeA6UiWlYirs2FemfPLJGhM8,8037
+spaps_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spaps_client/secure_messages.py,sha256=Yq1EBoRdZ2CATQxoCFcOu_ZDNM8ieJts866dpdEdb2c,5140
+spaps_client/secure_messages_async.py,sha256=CGMAFTbI-Na0VgA48o-JLEURDoxF4trxSuDscm1Nuhk,3705
+spaps_client/sessions.py,sha256=74wyOIdCaKU8qJPFsXCPK8JLcuPeS1meCNo805yw-9U,8502
+spaps_client/sessions_async.py,sha256=5L5CVqB5nh3jwTQfrUZo_narMCNbNtXBP-u-ySy5ylI,5605
+spaps_client/storage.py,sha256=VrDBwj23CUpCAw_fH4faLNjzrwsJFgGV8Xth3vxoPTM,4503
+spaps_client/usage.py,sha256=4QVpANBqDLt4xikTt8GBpvtuhTEGyopsveJY_AwNzIQ,7717
+spaps_client/usage_async.py,sha256=HBv2rYxKXOl8rGVJhMRrzbfhltMuh_--O4m7zkZzT2U,4731
+spaps_client/whitelist.py,sha256=EgscgzgTDkuFRvwxOVXsRSNFpOC3I_4ShuDdVNXj0Gs,8127
+spaps_client/whitelist_async.py,sha256=D7le5zhOpU1Y7hOlU831t3TTCvXUjHHjDXkCjnrq-JQ,6716
+spaps-0.1.0.dist-info/METADATA,sha256=prj-CeSPmvGzceLvLZ-g1qHyoo7ael9tjxXDwWDLxlc,6222
+spaps-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+spaps-0.1.0.dist-info/licenses/LICENSE,sha256=62pDTGM_ffmWeJk1DglVsvYY7BMWZxbgvj0o0napi-I,1075
+spaps-0.1.0.dist-info/RECORD,,

spaps-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

spaps-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Sweet Potato Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

spaps_client/__init__.py

@@ -0,0 +1,163 @@
+"""
+Sweet Potato Authentication & Payment Service Python client.
+
+This package exposes modules for authentication, session management,
+payments, and supporting utilities as implementation progresses.
+"""
+
+from .auth import AuthClient, AuthError, NonceResponse, TokenPair, TokenUser
+from .sessions import (
+    SessionError,
+    SessionSummary,
+    SessionValidationResult,
+    SessionListResult,
+    SessionRecord,
+    SessionTouchResult,
+    SessionRevokeResult,
+    SessionsClient,
+)
+from .payments import (
+    PaymentsClient,
+    PaymentsError,
+    CheckoutSession,
+    PaymentIntent,
+    WalletDeposit,
+    WalletTransaction,
+    SubscriptionPlan,
+    SubscriptionDetail,
+    SubscriptionCancellation,
+    BalanceOverview,
+    BalanceAmounts,
+    UsageSummary,
+    PaymentMethodUpdateResult,
+)
+from .whitelist import (
+    WhitelistClient,
+    WhitelistError,
+    WhitelistEntry,
+    WhitelistCheckResult,
+    WhitelistListResult,
+    WhitelistMessage,
+)
+from .config import Settings, create_http_client
+from .crypto import (
+    CryptoPaymentsClient,
+    CryptoPaymentsError,
+    CryptoInvoice,
+    CryptoInvoiceStatus,
+    CryptoReconcileJob,
+    verify_crypto_webhook_signature,
+)
+from .usage import (
+    UsageClient,
+    UsageError,
+    UsagePeriod,
+    UsageFeature,
+    UsageFeaturesResponse,
+    UsageRecordUsage,
+    UsageRecordResult,
+    UsageHistoryEntry,
+    UsageHistoryResponse,
+)
+from .secure_messages import (
+    SecureMessagesClient,
+    SecureMessagesError,
+    SecureMessage,
+)
+from .metrics import MetricsClient
+from .auth_async import AsyncAuthClient
+from .sessions_async import AsyncSessionsClient
+from .payments_async import AsyncPaymentsClient
+from .usage_async import AsyncUsageClient
+from .whitelist_async import AsyncWhitelistClient
+from .secure_messages_async import AsyncSecureMessagesClient
+from .metrics_async import AsyncMetricsClient
+from .crypto_async import AsyncCryptoPaymentsClient
+from .async_client import AsyncSpapsClient
+from .http_async import RetryAsyncClient
+from .client import SpapsClient
+from .storage import (
+    StoredTokens,
+    TokenStorage,
+    InMemoryTokenStorage,
+    FileTokenStorage,
+)
+from .http import RetryConfig, LoggingHooks, default_logging_hooks
+
+__all__ = [
+    "__version__",
+    "AuthClient",
+    "AuthError",
+    "NonceResponse",
+    "TokenPair",
+    "TokenUser",
+    "SessionsClient",
+    "SessionListResult",
+    "SessionRecord",
+    "SessionTouchResult",
+    "SessionRevokeResult",
+    "PaymentsClient",
+    "PaymentsError",
+    "CheckoutSession",
+    "PaymentIntent",
+    "WalletDeposit",
+    "WalletTransaction",
+    "SubscriptionPlan",
+    "SubscriptionDetail",
+    "SubscriptionCancellation",
+    "BalanceOverview",
+    "BalanceAmounts",
+    "UsageSummary",
+    "PaymentMethodUpdateResult",
+    "WhitelistClient",
+    "WhitelistError",
+    "WhitelistEntry",
+    "WhitelistCheckResult",
+    "WhitelistListResult",
+    "WhitelistMessage",
+    "Settings",
+    "create_http_client",
+    "SessionError",
+    "SessionSummary",
+    "SessionValidationResult",
+    "CryptoPaymentsClient",
+    "CryptoPaymentsError",
+    "CryptoInvoice",
+    "CryptoInvoiceStatus",
+    "CryptoReconcileJob",
+    "verify_crypto_webhook_signature",
+    "UsageClient",
+    "UsageError",
+    "UsagePeriod",
+    "UsageFeature",
+    "UsageFeaturesResponse",
+    "UsageRecordUsage",
+    "UsageRecordResult",
+    "UsageHistoryEntry",
+    "UsageHistoryResponse",
+    "SecureMessagesClient",
+    "SecureMessagesError",
+    "SecureMessage",
+    "MetricsClient",
+    "SpapsClient",
+    "AsyncSpapsClient",
+    "AsyncAuthClient",
+    "AsyncSessionsClient",
+    "AsyncPaymentsClient",
+    "AsyncUsageClient",
+    "AsyncWhitelistClient",
+    "AsyncSecureMessagesClient",
+    "AsyncMetricsClient",
+    "AsyncCryptoPaymentsClient",
+    "RetryAsyncClient",
+    "StoredTokens",
+    "TokenStorage",
+    "InMemoryTokenStorage",
+    "FileTokenStorage",
+    "RetryConfig",
+    "LoggingHooks",
+    "default_logging_hooks",
+]
+
+# Temporary development version; replaced during release automation.
+__version__ = "0.1.0"

spaps_client/async_client.py

@@ -0,0 +1,214 @@
+"""Async equivalents for the SPAPS client suite."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Optional, TYPE_CHECKING
+
+import httpx
+
+from .auth_async import AsyncAuthClient
+from .sessions_async import AsyncSessionsClient
+from .payments_async import AsyncPaymentsClient
+from .usage_async import AsyncUsageClient
+from .whitelist_async import AsyncWhitelistClient
+from .secure_messages_async import AsyncSecureMessagesClient
+from .metrics_async import AsyncMetricsClient
+from .storage import InMemoryTokenStorage, StoredTokens, TokenStorage
+from .config import Settings
+
+if TYPE_CHECKING:
+    from .http import RetryConfig, LoggingHooks
+
+
+class AsyncSpapsClient:
+    """Async client mirroring the ergonomics of the synchronous variant."""
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        request_timeout: Optional[float] = None,
+        token_storage: Optional[TokenStorage] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+        retry_config: Optional["RetryConfig"] = None,
+        logging_hooks: Optional["LoggingHooks"] = None,
+    ) -> None:
+        from .http_async import RetryAsyncClient
+
+        self.settings = Settings(base_url=base_url, api_key=api_key, request_timeout=request_timeout)
+        self._token_storage = token_storage or InMemoryTokenStorage()
+        from .http import RetryConfig as _RetryConfig, LoggingHooks as _LoggingHooks
+        if isinstance(retry_config, dict):
+            retry_config = _RetryConfig(**retry_config)
+        if isinstance(logging_hooks, dict):
+            logging_hooks = _LoggingHooks(**logging_hooks)
+        if http_client is not None:
+            self._client = http_client
+            self._owns_client = False
+        else:
+            self._client = RetryAsyncClient(
+                base_url=self.settings.base_url.rstrip("/"),
+                timeout=self.settings.request_timeout,
+                retry_config=retry_config,
+                logging_hooks=logging_hooks,
+            )
+            self._owns_client = True
+
+        self._auth = AsyncAuthClient(
+            base_url=self.settings.base_url,
+            api_key=self.settings.api_key,
+            client=self._client,
+            token_storage=self._token_storage,
+        )
+
+        self._sessions: Optional[AsyncSessionsClient] = None
+        self._payments: Optional[AsyncPaymentsClient] = None
+        self._usage: Optional[AsyncUsageClient] = None
+        self._whitelist: Optional[AsyncWhitelistClient] = None
+        self._secure_messages: Optional[AsyncSecureMessagesClient] = None
+        self._metrics: Optional[AsyncMetricsClient] = None
+
+    # Factories --------------------------------------------------------
+
+    @property
+    def auth(self) -> AsyncAuthClient:
+        return self._auth
+
+    @property
+    def sessions(self) -> AsyncSessionsClient:
+        access_token = self._require_access_token()
+        if self._sessions is None:
+            self._sessions = AsyncSessionsClient(
+                base_url=self.settings.base_url,
+                api_key=self.settings.api_key,
+                access_token=access_token,
+                client=self._client,
+            )
+        else:
+            self._sessions.access_token = access_token
+        return self._sessions
+
+    @property
+    def payments(self) -> AsyncPaymentsClient:
+        access_token = self._require_access_token()
+        if self._payments is None:
+            self._payments = AsyncPaymentsClient(
+                base_url=self.settings.base_url,
+                api_key=self.settings.api_key,
+                access_token=access_token,
+                client=self._client,
+            )
+        else:
+            self._payments.access_token = access_token
+        return self._payments
+
+    @property
+    def usage(self) -> AsyncUsageClient:
+        access_token = self._require_access_token()
+        if self._usage is None:
+            self._usage = AsyncUsageClient(
+                base_url=self.settings.base_url,
+                api_key=self.settings.api_key,
+                access_token=access_token,
+                client=self._client,
+            )
+        else:
+            self._usage.access_token = access_token
+        return self._usage
+
+    @property
+    def whitelist(self) -> AsyncWhitelistClient:
+        access_token = self._require_access_token()
+        if self._whitelist is None:
+            self._whitelist = AsyncWhitelistClient(
+                base_url=self.settings.base_url,
+                api_key=self.settings.api_key,
+                access_token=access_token,
+                client=self._client,
+            )
+        else:
+            self._whitelist.access_token = access_token
+        return self._whitelist
+
+    @property
+    def secure_messages(self) -> AsyncSecureMessagesClient:
+        access_token = self._require_access_token()
+        if self._secure_messages is None:
+            self._secure_messages = AsyncSecureMessagesClient(
+                base_url=self.settings.base_url,
+                api_key=self.settings.api_key,
+                access_token=access_token,
+                client=self._client,
+            )
+        else:
+            self._secure_messages.access_token = access_token
+        return self._secure_messages
+
+    @property
+    def metrics(self) -> AsyncMetricsClient:
+        if self._metrics is None:
+            self._metrics = AsyncMetricsClient(base_url=self.settings.base_url, client=self._client)
+        return self._metrics
+
+    # Token helpers ----------------------------------------------------
+
+    @property
+    def token_storage(self) -> TokenStorage:
+        return self._token_storage
+
+    def get_tokens(self) -> Optional[StoredTokens]:
+        return self._token_storage.load()
+
+    def set_tokens(
+        self,
+        *,
+        access_token: str,
+        refresh_token: Optional[str] = None,
+        token_type: Optional[str] = "Bearer",
+        expires_in: Optional[int] = None,
+        expires_at: Optional[datetime] = None,
+    ) -> None:
+        if expires_at is None and expires_in is not None:
+            expires_at = datetime.now(timezone.utc) + timedelta(seconds=expires_in)
+        tokens = StoredTokens(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_at=expires_at,
+            token_type=token_type,
+        )
+        self._token_storage.save(tokens)
+
+    def clear_tokens(self) -> None:
+        self._token_storage.clear()
+
+    # Lifecycle --------------------------------------------------------
+
+    async def aclose(self) -> None:
+        await self._auth.aclose()
+        for candidate in (
+            self._sessions,
+            self._payments,
+            self._usage,
+            self._whitelist,
+            self._secure_messages,
+            self._metrics,
+        ):
+            if candidate is not None:
+                await candidate.aclose()
+        if self._owns_client:
+            await self._client.aclose()
+
+    # Internal helpers -------------------------------------------------
+
+    def _require_access_token(self) -> str:
+        tokens = self._token_storage.load()
+        if not tokens or not tokens.access_token:
+            raise ValueError(
+                "Access token not found. Authenticate via auth helpers or call set_tokens()."
+            )
+        return tokens.access_token
+
+
+__all__ = ["AsyncSpapsClient"]