checkout-intents 0.1.0__tar.gz → 0.2.0__tar.gz

checkout_intents-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

checkout_intents-0.2.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.2.0 (2025-11-13)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/rye-com/checkout-intents-python/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* **api:** add polling helpers ([35dfc75](https://github.com/rye-com/checkout-intents-python/commit/35dfc75a2335fabb2ad1bab4b14f3f231deca600))
+* **api:** infer environment from api key ([341d678](https://github.com/rye-com/checkout-intents-python/commit/341d6781d5275abec09fcc6d4634d3725f096674))
+
+
+### Bug Fixes
+
+* **compat:** update signatures of `model_dump` and `model_dump_json` for Pydantic v1 ([004dd94](https://github.com/rye-com/checkout-intents-python/commit/004dd94cb5ec8647b21ba2568744bbb3e850c132))
+
+
+### Chores
+
+* **internal:** add type ignore annotations ([0d0990e](https://github.com/rye-com/checkout-intents-python/commit/0d0990e8b9f83614725366b69df65ca2c9aec402))
+* **internal:** replace rye with uv ([6cc9fcc](https://github.com/rye-com/checkout-intents-python/commit/6cc9fcc05af9040b863187affc79323812af3d83))
+
+
+### Documentation
+
+* **api:** add polling helpers ([7bd9f19](https://github.com/rye-com/checkout-intents-python/commit/7bd9f19fbec2bdc289cc3ace4edfa10e0914b3a2))
+* **internal:** replace rye with uv ([7fbabe6](https://github.com/rye-com/checkout-intents-python/commit/7fbabe69d822fc3577a1762804dae36e9ea7385a))
+
+## 0.1.0 (2025-11-11)
+
+Full Changelog: [v0.0.1...v0.1.0](https://github.com/rye-com/checkout-intents-python/compare/v0.0.1...v0.1.0)
+
+### Features
+
+* **api:** api update ([e4a0e20](https://github.com/rye-com/checkout-intents-python/commit/e4a0e206d7566f904ac22caea8954990ad5c7271))
+* **api:** api update ([7d95f0d](https://github.com/rye-com/checkout-intents-python/commit/7d95f0db63098d4edf209c7291959eb5f08df44b))
+
+
+### Chores
+
+* configure new SDK language ([a8f36d4](https://github.com/rye-com/checkout-intents-python/commit/a8f36d46dc5c0d3e868d289132bb83465736d0f5))
+* update SDK settings ([5271e8a](https://github.com/rye-com/checkout-intents-python/commit/5271e8aa9f149e67b203919039afb2f61deca5e2))
+* update SDK settings ([949efc6](https://github.com/rye-com/checkout-intents-python/commit/949efc6b67a53d856d11214bc6a924d879c2dfab))

{checkout_intents-0.1.0 → checkout_intents-0.2.0}/CONTRIBUTING.md

@@ -1,32 +1,32 @@
 ## Setting up the environment
 
-### With Rye
+### With `uv`
 
-We use [Rye](https://rye.astral.sh/) to manage dependencies because it will automatically provision a Python environment with the expected Python version. To set it up, run:
+We use [uv](https://docs.astral.sh/uv/) to manage dependencies because it will automatically provision a Python environment with the expected Python version. To set it up, run:
 
 ```sh
 $ ./scripts/bootstrap
 ```
 
-Or [install Rye manually](https://rye.astral.sh/guide/installation/) and run:
+Or [install uv manually](https://docs.astral.sh/uv/getting-started/installation/) and run:
 
 ```sh
-$ rye sync --all-features
+$ uv sync --all-extras
 ```
 
-You can then run scripts using `rye run python script.py` or by activating the virtual environment:
+You can then run scripts using `uv run python script.py` or by manually activating the virtual environment:
 
 ```sh
-# Activate the virtual environment - https://docs.python.org/3/library/venv.html#how-venvs-work
+# manually activate - https://docs.python.org/3/library/venv.html#how-venvs-work
 $ source .venv/bin/activate
 
-# now you can omit the `rye run` prefix
+# now you can omit the `uv run` prefix
 $ python script.py
 ```
 
-### Without Rye
+### Without `uv`
 
-Alternatively if you don't want to install `Rye`, you can stick with the standard `pip` setup by ensuring you have the Python version specified in `.python-version`, create a virtual environment however you desire and then install dependencies using this command:
+Alternatively if you don't want to install `uv`, you can stick with the standard `pip` setup by ensuring you have the Python version specified in `.python-version`, create a virtual environment however you desire and then install dependencies using this command:
 
 ```sh
 $ pip install -r requirements-dev.lock
@@ -45,7 +45,7 @@ All files in the `examples/` directory are not modified by the generator and can
 ```py
 # add an example to examples/<your-example>.py
 
-#!/usr/bin/env -S rye run python
+#!/usr/bin/env -S uv run python
 …
 ```
 
@@ -57,7 +57,7 @@ $ ./examples/<your-example>.py
 
 ## Using the repository from source
 
-If you’d like to use the repository from source, you can either install from git or link to a cloned repository:
+If you'd like to use the repository from source, you can either install from git or link to a cloned repository:
 
 To install via git:
 
@@ -72,7 +72,7 @@ Building this package will create two files in the `dist/` directory, a `.tar.gz
 To create a distributable version of the library, all you have to do is run this command:
 
 ```sh
-$ rye build
+$ uv build
 # or
 $ python -m build
 ```

{checkout_intents-0.1.0 → checkout_intents-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: checkout-intents
-Version: 0.1.0
+Version: 0.2.0
 Summary: The official Python library for the Checkout Intents API
 Project-URL: Homepage, https://github.com/rye-com/checkout-intents-python
 Project-URL: Repository, https://github.com/rye-com/checkout-intents-python
@@ -88,6 +88,98 @@ we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
 to add `CHECKOUT_INTENTS_API_KEY="My API Key"` to your `.env` file
 so that your API Key is not stored in source control.
 
+### Polling Helpers
+
+This SDK includes helper methods for the asynchronous checkout flow. The recommended pattern follows Rye's two-phase checkout:
+
+```python
+from checkout_intents import CheckoutIntents
+
+client = CheckoutIntents()
+
+# Phase 1: Create and wait for offer
+intent = client.checkout_intents.create_and_poll(
+    buyer={
+        "address1": "123 Main St",
+        "city": "New York",
+        "country": "US",
+        "email": "john.doe@example.com",
+        "first_name": "John",
+        "last_name": "Doe",
+        "phone": "5555555555",
+        "postal_code": "10001",
+        "province": "NY",
+    },
+    product_url="https://example.com/product",
+    quantity=1,
+)
+
+# Handle failure during offer retrieval
+if intent.state == "failed":
+    print(f"Failed: {intent.failure_reason}")
+else:
+    # Review pricing with user
+    print(f"Total: {intent.offer.cost.total}")
+
+    # Phase 2: Confirm and wait for completion
+    completed = client.checkout_intents.confirm_and_poll(
+        intent.id,
+        payment_method={
+            "type": "stripe_token",
+            "stripe_token": "tok_visa",
+        },
+    )
+
+    print(f"Status: {completed.state}")
+```
+
+For more examples, see the [`examples/`](https://github.com/rye-com/checkout-intents-python/tree/main/./examples) directory:
+
+- [`complete-checkout-intent.py`](https://github.com/rye-com/checkout-intents-python/tree/main/./examples/complete-checkout-intent.py) - Recommended two-phase flow
+- [`error-handling.py`](https://github.com/rye-com/checkout-intents-python/tree/main/./examples/error-handling.py) - Timeout and error handling with `PollTimeoutError`
+
+Available polling methods:
+
+- `create_and_poll()` - Create and poll until offer is ready (awaiting_confirmation or failed)
+- `confirm_and_poll()` - Confirm and poll until completion (completed or failed)
+- `poll_until_completed()` - Poll until completed or failed
+- `poll_until_awaiting_confirmation()` - Poll until offer is ready or failed
+
+All polling methods support customizable timeouts:
+
+```python
+# Configure polling behavior
+intent = client.checkout_intents.poll_until_completed(
+    intent_id,
+    poll_interval=5.0,  # Poll every 5 seconds (default)
+    max_attempts=120,  # Try up to 120 times, ~10 minutes (default)
+)
+```
+
+#### Handling Polling Timeouts
+
+When polling operations exceed `max_attempts`, a `PollTimeoutError` is raised with helpful context:
+
+```python
+from checkout_intents import CheckoutIntents, PollTimeoutError
+
+client = CheckoutIntents()
+
+try:
+    intent = client.checkout_intents.poll_until_completed(
+        intent_id,
+        poll_interval=5.0,
+        max_attempts=60,
+    )
+except PollTimeoutError as e:
+    print(f"Polling timed out for intent: {e.intent_id}")
+    print(f"Attempted {e.attempts} times over {(e.attempts * e.poll_interval) / 1000}s")
+
+    # You can retrieve the current state manually
+    current_intent = client.checkout_intents.retrieve(e.intent_id)
+    print(f"Current state: {current_intent.state}")
+```
+
 ## Async usage
 
 Simply import `AsyncCheckoutIntents` instead of `CheckoutIntents` and use `await` with each API call:
@@ -258,6 +350,26 @@ Error codes are as follows:
 | 429         | `RateLimitError`           |
 | >=500       | `InternalServerError`      |
 | N/A         | `APIConnectionError`       |
+| N/A         | `PollTimeoutError`         |
+
+### Polling Timeout Errors
+
+When using polling helper methods, if the operation exceeds the configured `max_attempts`, a `PollTimeoutError` is raised. This error includes detailed context about the timeout:
+
+```python
+from checkout_intents import CheckoutIntents, PollTimeoutError
+
+try:
+    intent = client.checkout_intents.poll_until_completed("intent_id")
+except PollTimeoutError as e:
+    # Access timeout details
+    print(f"Intent ID: {e.intent_id}")
+    print(f"Attempts: {e.attempts}")
+    print(f"Poll interval: {e.poll_interval}s")
+    print(f"Max attempts: {e.max_attempts}")
+```
+
+See the [error-handling.py example](https://github.com/rye-com/checkout-intents-python/tree/main/./examples/error-handling.py) for more detailed timeout handling patterns.
 
 ### Retries
 

{checkout_intents-0.1.0 → checkout_intents-0.2.0}/README.md

@@ -54,6 +54,98 @@ we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
 to add `CHECKOUT_INTENTS_API_KEY="My API Key"` to your `.env` file
 so that your API Key is not stored in source control.
 
+### Polling Helpers
+
+This SDK includes helper methods for the asynchronous checkout flow. The recommended pattern follows Rye's two-phase checkout:
+
+```python
+from checkout_intents import CheckoutIntents
+
+client = CheckoutIntents()
+
+# Phase 1: Create and wait for offer
+intent = client.checkout_intents.create_and_poll(
+    buyer={
+        "address1": "123 Main St",
+        "city": "New York",
+        "country": "US",
+        "email": "john.doe@example.com",
+        "first_name": "John",
+        "last_name": "Doe",
+        "phone": "5555555555",
+        "postal_code": "10001",
+        "province": "NY",
+    },
+    product_url="https://example.com/product",
+    quantity=1,
+)
+
+# Handle failure during offer retrieval
+if intent.state == "failed":
+    print(f"Failed: {intent.failure_reason}")
+else:
+    # Review pricing with user
+    print(f"Total: {intent.offer.cost.total}")
+
+    # Phase 2: Confirm and wait for completion
+    completed = client.checkout_intents.confirm_and_poll(
+        intent.id,
+        payment_method={
+            "type": "stripe_token",
+            "stripe_token": "tok_visa",
+        },
+    )
+
+    print(f"Status: {completed.state}")
+```
+
+For more examples, see the [`examples/`](./examples) directory:
+
+- [`complete-checkout-intent.py`](./examples/complete-checkout-intent.py) - Recommended two-phase flow
+- [`error-handling.py`](./examples/error-handling.py) - Timeout and error handling with `PollTimeoutError`
+
+Available polling methods:
+
+- `create_and_poll()` - Create and poll until offer is ready (awaiting_confirmation or failed)
+- `confirm_and_poll()` - Confirm and poll until completion (completed or failed)
+- `poll_until_completed()` - Poll until completed or failed
+- `poll_until_awaiting_confirmation()` - Poll until offer is ready or failed
+
+All polling methods support customizable timeouts:
+
+```python
+# Configure polling behavior
+intent = client.checkout_intents.poll_until_completed(
+    intent_id,
+    poll_interval=5.0,  # Poll every 5 seconds (default)
+    max_attempts=120,  # Try up to 120 times, ~10 minutes (default)
+)
+```
+
+#### Handling Polling Timeouts
+
+When polling operations exceed `max_attempts`, a `PollTimeoutError` is raised with helpful context:
+
+```python
+from checkout_intents import CheckoutIntents, PollTimeoutError
+
+client = CheckoutIntents()
+
+try:
+    intent = client.checkout_intents.poll_until_completed(
+        intent_id,
+        poll_interval=5.0,
+        max_attempts=60,
+    )
+except PollTimeoutError as e:
+    print(f"Polling timed out for intent: {e.intent_id}")
+    print(f"Attempted {e.attempts} times over {(e.attempts * e.poll_interval) / 1000}s")
+
+    # You can retrieve the current state manually
+    current_intent = client.checkout_intents.retrieve(e.intent_id)
+    print(f"Current state: {current_intent.state}")
+```
+
 ## Async usage
 
 Simply import `AsyncCheckoutIntents` instead of `CheckoutIntents` and use `await` with each API call:
@@ -224,6 +316,26 @@ Error codes are as follows:
 | 429         | `RateLimitError`           |
 | >=500       | `InternalServerError`      |
 | N/A         | `APIConnectionError`       |
+| N/A         | `PollTimeoutError`         |
+
+### Polling Timeout Errors
+
+When using polling helper methods, if the operation exceeds the configured `max_attempts`, a `PollTimeoutError` is raised. This error includes detailed context about the timeout:
+
+```python
+from checkout_intents import CheckoutIntents, PollTimeoutError
+
+try:
+    intent = client.checkout_intents.poll_until_completed("intent_id")
+except PollTimeoutError as e:
+    # Access timeout details
+    print(f"Intent ID: {e.intent_id}")
+    print(f"Attempts: {e.attempts}")
+    print(f"Poll interval: {e.poll_interval}s")
+    print(f"Max attempts: {e.max_attempts}")
+```
+
+See the [error-handling.py example](./examples/error-handling.py) for more detailed timeout handling patterns.
 
 ### Retries
 

checkout_intents-0.2.0/examples/complete-checkout-intent.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env -S uv run python
+
+"""
+Recommended checkout flow (two-phase):
+1. Create checkout intent and poll until offer is ready
+2. Review pricing with user
+3. Confirm with payment and poll until completion
+
+This follows the Rye documented checkout flow.
+"""
+
+import os
+
+from checkout_intents import CheckoutIntents
+
+
+def main() -> None:
+    """Demonstrate the complete two-phase checkout flow."""
+    client = CheckoutIntents(
+        api_key=os.getenv("CHECKOUT_INTENTS_API_KEY"),
+    )
+
+    # Phase 1: Create checkout intent and wait for offer
+    print("Creating checkout intent...")
+
+    intent = client.checkout_intents.create_and_poll(
+        buyer={
+            "address1": "123 Main St",
+            "city": "New York",
+            "country": "US",
+            "email": "john.doe@example.com",
+            "first_name": "John",
+            "last_name": "Doe",
+            "phone": "5555555555",
+            "postal_code": "10001",
+            "province": "NY",
+        },
+        product_url="https://flybyjing.com/collections/shop/products/sichuan-chili-crisp",
+        quantity=1,
+    )
+
+    print(f"Checkout intent created: {intent.id}")
+    print(f"State: {intent.state}")
+
+    # Handle failure during offer retrieval
+    if intent.state == "failed":
+        print(f"Failed to retrieve offer: {intent.failure_reason}")
+        return
+
+    # Review the offer with the user before confirming
+    if hasattr(intent, "offer"):
+        print("\nOffer Details:")
+        print(f"  Subtotal: {intent.offer.cost.subtotal}")
+        print(f"  Shipping: {intent.offer.cost.shipping or intent.offer.shipping}")
+        print(f"  Tax: {intent.offer.cost.tax}")
+        print(f"  Total: {intent.offer.cost.total}")
+
+    # Phase 2: User confirms, complete the checkout
+    print("\nConfirming checkout...")
+
+    completed = client.checkout_intents.confirm_and_poll(
+        intent.id,
+        payment_method={
+            "type": "stripe_token",
+            "stripe_token": "tok_visa",  # Use tok_visa in staging
+        },
+    )
+
+    print(f"Final state: {completed.state}")
+
+    if completed.state == "completed":
+        print("✓ Order placed successfully!")
+    elif completed.state == "failed":
+        print(f"✗ Order failed: {completed.failure_reason}")
+
+
+if __name__ == "__main__":
+    main()

checkout_intents-0.2.0/examples/error-handling.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env -S uv run python
+
+"""
+Handling polling timeouts and errors.
+
+This example demonstrates:
+- How to catch PollTimeoutError specifically
+- How to access timeout error details
+- How to configure polling parameters
+- How to handle different error scenarios
+- Best practices for error handling
+"""
+
+import os
+
+from checkout_intents import CheckoutIntents, PollTimeoutError, CheckoutIntentsError
+
+
+def main() -> None:
+    """Demonstrate error handling for polling operations."""
+    client = CheckoutIntents(
+        api_key=os.getenv("CHECKOUT_INTENTS_API_KEY"),
+    )
+
+    print("Creating checkout intent...")
+
+    intent = client.checkout_intents.create(
+        buyer={
+            "address1": "123 Main St",
+            "city": "New York",
+            "country": "US",
+            "email": "john.doe@example.com",
+            "first_name": "John",
+            "last_name": "Doe",
+            "phone": "5555555555",
+            "postal_code": "10001",
+            "province": "NY",
+        },
+        product_url="https://flybyjing.com/collections/shop/products/sichuan-chili-crisp",
+        quantity=1,
+    )
+
+    print(f"Created checkout intent: {intent.id}")
+
+    try:
+        print("\nPolling with immediate timeout (will timeout)...")
+
+        # Poll with immediate timeout to demonstrate error handling
+        client.checkout_intents.poll_until_awaiting_confirmation(
+            intent.id,
+            poll_interval=0,
+            max_attempts=1,
+        )
+
+        print("✓ Polling succeeded (unexpected)")
+
+    except PollTimeoutError as e:
+        print("✗ Polling timed out as expected")
+        print(f"\nPollTimeoutError details:")
+        print(f"  Intent ID: {e.intent_id}")
+        print(f"  Attempts made: {e.attempts}")
+        print(f"  Time elapsed: {e.attempts * e.poll_interval}s")
+        print(f"  Poll interval: {e.poll_interval}s")
+        print(f"  Max attempts: {e.max_attempts}")
+        print(f"\nError message:\n  {e}")
+
+        print("\nTo fix this:")
+        print("  - Increase max_attempts (e.g., 60 for ~5 minutes with 5s interval)")
+        print("  - Increase poll_interval if you want less frequent checks")
+        print("  - Use appropriate polling method (poll_until_awaiting_confirmation or poll_until_completed)")
+
+        # You can also retrieve the intent manually to check its current state
+        print(f"\nManually checking intent state...")
+        current_intent = client.checkout_intents.retrieve(e.intent_id)
+        print(f"  Current state: {current_intent.state}")
+
+    except CheckoutIntentsError as e:
+        # Catch other SDK errors (API errors, network errors, etc.)
+        print(f"✗ Other error: {e}")
+
+
+if __name__ == "__main__":
+    main()

{checkout_intents-0.1.0 → checkout_intents-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "checkout-intents"
-version = "0.1.0"
+version = "0.2.0"
 description = "The official Python library for the Checkout Intents API"
 dynamic = ["readme"]
 license = "MIT"
@@ -40,10 +40,13 @@ Repository = "https://github.com/rye-com/checkout-intents-python"
 [project.optional-dependencies]
 aiohttp = ["aiohttp", "httpx_aiohttp>=0.1.9"]
 
-[tool.rye]
+[tool.uv]
 managed = true
-# version pins are in requirements-dev.lock
-dev-dependencies = [
+required-version = ">=0.5.0"
+
+[dependency-groups]
+# version pins are in uv.lock
+dev = [
     "pyright==1.1.399",
     "mypy",
     "respx",
@@ -57,35 +60,9 @@ dev-dependencies = [
     "rich>=13.7.1",
     "pytest-xdist>=3.6.1",
 ]
-
-[tool.rye.scripts]
-format = { chain = [
-  "format:ruff",
-  "format:docs",
-  "fix:ruff",
-  # run formatting again to fix any inconsistencies when imports are stripped
-  "format:ruff",
-]}
-"format:docs" = "python scripts/utils/ruffen-docs.py README.md api.md"
-"format:ruff" = "ruff format"
-
-"lint" = { chain = [
-  "check:ruff",
-  "typecheck",
-  "check:importable",
-]}
-"check:ruff" = "ruff check ."
-"fix:ruff" = "ruff check --fix ."
-
-"check:importable" = "python -c 'import checkout_intents'"
-
-typecheck = { chain = [
-  "typecheck:pyright",
-  "typecheck:mypy"
-]}
-"typecheck:pyright" = "pyright"
-"typecheck:verify-types" = "pyright --verifytypes checkout_intents --ignoreexternal"
-"typecheck:mypy" = "mypy ."
+pydantic-v1 = [
+    "pydantic>=1.9.0, <3",
+]
 
 [build-system]
 requires = ["hatchling==1.26.3", "hatch-fancy-pypi-readme"]