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

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

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

checkout_intents-0.3.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.3.0 (2025-11-18)
+
+Full Changelog: [v0.2.0...v0.3.0](https://github.com/rye-com/checkout-intents-python/compare/v0.2.0...v0.3.0)
+
+### Features
+
+* Add python sdk target to stainless config ([eea256f](https://github.com/rye-com/checkout-intents-python/commit/eea256fef46bb35554488dba5a0818345096a66a))
+
+
+### Bug Fixes
+
+* **docs:** supply valid buyer details ([12d25b1](https://github.com/rye-com/checkout-intents-python/commit/12d25b12808a05aaedcf48fc97384b5da40ca7e4))
+
+
+### Chores
+
+* **internal:** format code ([445dea0](https://github.com/rye-com/checkout-intents-python/commit/445dea070ddcc8574d0304001e79bd25ca2f9de7))
+
+## 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.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: checkout-intents
-Version: 0.1.0
+Version: 0.3.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
@@ -59,9 +59,11 @@ pip install checkout-intents
 The full API of this library can be found in [api.md](https://github.com/rye-com/checkout-intents-python/tree/main/api.md).
 
 ```python
+import os
 from checkout_intents import CheckoutIntents
 
 client = CheckoutIntents(
+    api_key=os.environ.get("CHECKOUT_INTENTS_API_KEY"),  # This is the default and can be omitted
     # defaults to "staging".
     environment="production",
 )
@@ -74,7 +76,7 @@ checkout_intent = client.checkout_intents.create(
         "email": "john.doe@example.com",
         "first_name": "John",
         "last_name": "Doe",
-        "phone": "5555555555",
+        "phone": "1234567890",
         "postal_code": "10001",
         "province": "NY",
     },
@@ -88,15 +90,109 @@ 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": "1234567890",
+        "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:
 
 ```python
+import os
 import asyncio
 from checkout_intents import AsyncCheckoutIntents
 
 client = AsyncCheckoutIntents(
+    api_key=os.environ.get("CHECKOUT_INTENTS_API_KEY"),  # This is the default and can be omitted
     # defaults to "staging".
     environment="production",
 )
@@ -111,7 +207,7 @@ async def main() -> None:
             "email": "john.doe@example.com",
             "first_name": "John",
             "last_name": "Doe",
-            "phone": "5555555555",
+            "phone": "1234567890",
             "postal_code": "10001",
             "province": "NY",
         },
@@ -146,6 +242,7 @@ from checkout_intents import AsyncCheckoutIntents
 
 async def main() -> None:
     async with AsyncCheckoutIntents(
+        api_key="My API Key",
         http_client=DefaultAioHttpClient(),
     ) as client:
         checkout_intent = await client.checkout_intents.create(
@@ -156,7 +253,7 @@ async def main() -> None:
                 "email": "john.doe@example.com",
                 "first_name": "John",
                 "last_name": "Doe",
-                "phone": "5555555555",
+                "phone": "1234567890",
                 "postal_code": "10001",
                 "province": "NY",
             },
@@ -177,6 +274,77 @@ Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typ
 
 Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
 
+## Pagination
+
+List methods in the Checkout Intents API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+from checkout_intents import CheckoutIntents
+
+client = CheckoutIntents()
+
+all_checkout_intents = []
+# Automatically fetches more pages as needed.
+for checkout_intent in client.checkout_intents.list(
+    limit=20,
+):
+    # Do something with checkout_intent here
+    all_checkout_intents.append(checkout_intent)
+print(all_checkout_intents)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+from checkout_intents import AsyncCheckoutIntents
+
+client = AsyncCheckoutIntents()
+
+
+async def main() -> None:
+    all_checkout_intents = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for checkout_intent in client.checkout_intents.list(
+        limit=20,
+    ):
+        all_checkout_intents.append(checkout_intent)
+    print(all_checkout_intents)
+
+
+asyncio.run(main())
+```
+
+Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
+
+```python
+first_page = await client.checkout_intents.list(
+    limit=20,
+)
+if first_page.has_next_page():
+    print(f"will fetch next page using these details: {first_page.next_page_info()}")
+    next_page = await first_page.get_next_page()
+    print(f"number of items we just fetched: {len(next_page.data)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.checkout_intents.list(
+    limit=20,
+)
+
+print(f"next page cursor: {first_page.page_info.end_cursor}")  # => "next page cursor: ..."
+for checkout_intent in first_page.data:
+    print(checkout_intent)
+
+# Remove `await` for non-async usage.
+```
+
 ## Nested params
 
 Nested parameters are dictionaries, typed using `TypedDict`, for example:
@@ -194,12 +362,12 @@ checkout_intent = client.checkout_intents.create(
         "email": "john.doe@example.com",
         "first_name": "John",
         "last_name": "Doe",
-        "phone": "5555555555",
+        "phone": "1234567890",
         "postal_code": "10001",
         "province": "NY",
     },
     product_url="productUrl",
-    quantity=0,
+    quantity=1,
 )
 print(checkout_intent.buyer)
 ```
@@ -228,7 +396,7 @@ try:
             "email": "john.doe@example.com",
             "first_name": "John",
             "last_name": "Doe",
-            "phone": "5555555555",
+            "phone": "1234567890",
             "postal_code": "10001",
             "province": "NY",
         },
@@ -258,6 +426,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
 
@@ -285,7 +473,7 @@ client.with_options(max_retries=5).checkout_intents.create(
         "email": "john.doe@example.com",
         "first_name": "John",
         "last_name": "Doe",
-        "phone": "5555555555",
+        "phone": "1234567890",
         "postal_code": "10001",
         "province": "NY",
     },
@@ -322,7 +510,7 @@ client.with_options(timeout=5.0).checkout_intents.create(
         "email": "john.doe@example.com",
         "first_name": "John",
         "last_name": "Doe",
-        "phone": "5555555555",
+        "phone": "1234567890",
         "postal_code": "10001",
         "province": "NY",
     },
@@ -377,7 +565,7 @@ response = client.checkout_intents.with_raw_response.create(
         "email": "john.doe@example.com",
         "first_name": "John",
         "last_name": "Doe",
-        "phone": "5555555555",
+        "phone": "1234567890",
         "postal_code": "10001",
         "province": "NY",
     },
@@ -409,7 +597,7 @@ with client.checkout_intents.with_streaming_response.create(
         "email": "john.doe@example.com",
         "first_name": "John",
         "last_name": "Doe",
-        "phone": "5555555555",
+        "phone": "1234567890",
         "postal_code": "10001",
         "province": "NY",
     },