feat: Add processor-bound AgentCard preparation contracts

Stainless-Generated-From: 1b2956dd517385b95316303d9f6b5e962f8d2a40

Author: kernel-internal[bot]

api.md

@@ -526,6 +526,7 @@ Types:
 from kernel.types.vaults import (
     AgentcardCheckoutAuthorization,
     AgentcardCheckoutPreparation,
+    AgentcardPreparedProcessor,
     AuthorizeVaultItemOperationRequest,
     CardVaultItemSpec,
     CardVaultItemState,

src/kernel/resources/vaults/items.py

@@ -511,11 +511,11 @@ def perform_operation(
         leave the outcome unknown; do not automatically retry.
 
         Args:
-          checkout: Required when preparing an unused AgentCard card for Square. Consent is bound to
-              this browser and declared merchant origin, not a tab. Wait for the item's
-              ready_to_submit status before native Pay and submit within its readiness
-              deadline. Unused preparations expire automatically; every preparation is
-              single-use, including after failure or expiry.
+          checkout: Required when preparing an unused AgentCard card for a supported tokenization
+              processor. Consent is bound to this browser and declared merchant origin, not a
+              tab. Wait for the item's ready_to_submit status before native Pay and submit
+              within its readiness deadline. Unused preparations expire automatically; every
+              preparation is single-use, including after failure or expiry.
 
           extra_headers: Send extra headers
 
@@ -1274,11 +1274,11 @@ async def perform_operation(
         leave the outcome unknown; do not automatically retry.
 
         Args:
-          checkout: Required when preparing an unused AgentCard card for Square. Consent is bound to
-              this browser and declared merchant origin, not a tab. Wait for the item's
-              ready_to_submit status before native Pay and submit within its readiness
-              deadline. Unused preparations expire automatically; every preparation is
-              single-use, including after failure or expiry.
+          checkout: Required when preparing an unused AgentCard card for a supported tokenization
+              processor. Consent is bound to this browser and declared merchant origin, not a
+              tab. Wait for the item's ready_to_submit status before native Pay and submit
+              within its readiness deadline. Unused preparations expire automatically; every
+              preparation is single-use, including after failure or expiry.
 
           extra_headers: Send extra headers
 

src/kernel/types/vaults/__init__.py

@@ -24,6 +24,7 @@
 from .credential_vault_item_spec import CredentialVaultItemSpec as CredentialVaultItemSpec
 from .credential_vault_field_type import CredentialVaultFieldType as CredentialVaultFieldType
 from .credential_vault_item_state import CredentialVaultItemState as CredentialVaultItemState
+from .agentcard_prepared_processor import AgentcardPreparedProcessor as AgentcardPreparedProcessor
 from .credential_collection_action import CredentialCollectionAction as CredentialCollectionAction
 from .credential_vault_field_state import CredentialVaultFieldState as CredentialVaultFieldState
 from .vault_checkout_context_param import VaultCheckoutContextParam as VaultCheckoutContextParam

src/kernel/types/vaults/agentcard_checkout_preparation.py

@@ -5,12 +5,13 @@
 from typing_extensions import Literal
 
 from ..._models import BaseModel
+from .agentcard_prepared_processor import AgentcardPreparedProcessor
 
 __all__ = ["AgentcardCheckoutPreparation"]
 
 
 class AgentcardCheckoutPreparation(BaseModel):
-    """One-use Square checkout preparation.
+    """One-use processor-bound checkout preparation.
 
     Keep the approval page open through token handoff. The amount is display-only and does not constrain the merchant's eventual charge.
     """
@@ -19,10 +20,12 @@ class AgentcardCheckoutPreparation(BaseModel):
 
     created_at: datetime
 
-    environment: Literal["production", "sandbox"]
+    environment: Literal["production", "sandbox", "shared"]
 
     merchant_origin: str
 
+    psp: AgentcardPreparedProcessor
+
     status: Literal["creating", "awaiting_approval", "ready", "consumed", "cancelled", "expired", "unknown"]
     """
     Preparation consumed means egress claimed the preparation and it cannot be

src/kernel/types/vaults/agentcard_prepared_processor.py

@@ -0,0 +1,7 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing_extensions import Literal, TypeAlias
+
+__all__ = ["AgentcardPreparedProcessor"]
+
+AgentcardPreparedProcessor: TypeAlias = Literal["square", "braintree", "worldpay", "bambora", "mercado_pago"]

src/kernel/types/vaults/card_vault_item_state.py

@@ -112,7 +112,7 @@ class AgentCardCardState(BaseModel):
     masks: Optional[AgentCardCardStateMasks] = None
 
     preparation: Optional[AgentcardCheckoutPreparation] = None
-    """One-use Square checkout preparation.
+    """One-use processor-bound checkout preparation.
 
     Keep the approval page open through token handoff. The amount is display-only
     and does not constrain the merchant's eventual charge.

src/kernel/types/vaults/item_perform_operation_params.py

@@ -33,12 +33,12 @@ class PrepareCheckoutVaultItemOperationRequest(TypedDict, total=False):
     id_or_name: Required[str]
 
     checkout: Required[VaultCheckoutContextParam]
-    """Required when preparing an unused AgentCard card for Square.
-
-    Consent is bound to this browser and declared merchant origin, not a tab. Wait
-    for the item's ready_to_submit status before native Pay and submit within its
-    readiness deadline. Unused preparations expire automatically; every preparation
-    is single-use, including after failure or expiry.
+    """
+    Required when preparing an unused AgentCard card for a supported tokenization
+    processor. Consent is bound to this browser and declared merchant origin, not a
+    tab. Wait for the item's ready_to_submit status before native Pay and submit
+    within its readiness deadline. Unused preparations expire automatically; every
+    preparation is single-use, including after failure or expiry.
     """
 
     type: Required[Literal["prepare_checkout"]]

src/kernel/types/vaults/prepare_checkout_vault_item_operation_request_param.py

@@ -10,18 +10,18 @@
 
 
 class PrepareCheckoutVaultItemOperationRequestParam(TypedDict, total=False):
-    """Prepare an unused AgentCard card for Square checkout.
+    """Prepare an unused AgentCard card for a supported tokenization checkout.
 
     Deliver the returned approval URL and keep the approval page open. Poll the item until ready_to_submit, then submit native Pay before preparation.expires_at. Readiness lasts at most 30 seconds. Unused preparations expire automatically. Preparations are single-use even after failure or expiry; do not automatically retry and reconcile uncertain outcomes with the merchant.
     """
 
     checkout: Required[VaultCheckoutContextParam]
-    """Required when preparing an unused AgentCard card for Square.
-
-    Consent is bound to this browser and declared merchant origin, not a tab. Wait
-    for the item's ready_to_submit status before native Pay and submit within its
-    readiness deadline. Unused preparations expire automatically; every preparation
-    is single-use, including after failure or expiry.
+    """
+    Required when preparing an unused AgentCard card for a supported tokenization
+    processor. Consent is bound to this browser and declared merchant origin, not a
+    tab. Wait for the item's ready_to_submit status before native Pay and submit
+    within its readiness deadline. Unused preparations expire automatically; every
+    preparation is single-use, including after failure or expiry.
     """
 
     type: Required[Literal["prepare_checkout"]]

src/kernel/types/vaults/vault_checkout_context_param.py

@@ -4,24 +4,36 @@
 
 from typing_extensions import Literal, Required, TypedDict
 
+from .agentcard_prepared_processor import AgentcardPreparedProcessor
+
 __all__ = ["VaultCheckoutContextParam"]
 
 
 class VaultCheckoutContextParam(TypedDict, total=False):
-    """Required when preparing an unused AgentCard card for Square.
-
-    Consent is bound to this browser and declared merchant origin, not a tab. Wait for the item's ready_to_submit status before native Pay and submit within its readiness deadline. Unused preparations expire automatically; every preparation is single-use, including after failure or expiry.
+    """
+    Required when preparing an unused AgentCard card for a supported tokenization processor. Consent is bound to this browser and declared merchant origin, not a tab. Wait for the item's ready_to_submit status before native Pay and submit within its readiness deadline. Unused preparations expire automatically; every preparation is single-use, including after failure or expiry.
     """
 
     browser_id: Required[str]
     """Active browser session with this vault bound to it."""
 
-    environment: Required[Literal["production", "sandbox"]]
-    """Square environment, independent of the AgentCard credential mode."""
+    environment: Required[Literal["production", "sandbox", "shared"]]
+    """
+    Use production or sandbox for Square, Braintree and Worldpay; shared for Bambora
+    and Mercado Pago. Shared endpoints do not establish test mode. Merchant
+    credentials/configuration determine processor test mode, independently of the
+    AgentCard credential mode.
+    """
 
     merchant_origin: Required[str]
-    """Canonical HTTPS origin of the top-level merchant document, not the Square
-    iframe.
+    """
+    Canonical HTTPS origin of the top-level merchant document, not a processor
+    iframe. HTTP localhost is accepted for tests.
+    """
+
+    psp: AgentcardPreparedProcessor
+    """Tokenization processor.
 
-    HTTP localhost is accepted for tests.
+    Omit for Square compatibility. Non-Square processors require multi-processor
+    preparation enablement.
     """

tests/api_resources/vaults/test_items.py

@@ -604,6 +604,22 @@ def test_method_perform_operation_overload_3(self, client: Kernel) -> None:
         )
         assert_matches_type(VaultItemOperationResponse, item, path=["response"])
 
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_method_perform_operation_with_all_params_overload_3(self, client: Kernel) -> None:
+        item = client.vaults.items.perform_operation(
+            key="key",
+            id_or_name="id_or_name",
+            checkout={
+                "browser_id": "browser_id",
+                "environment": "production",
+                "merchant_origin": "merchant_origin",
+                "psp": "square",
+            },
+            type="prepare_checkout",
+        )
+        assert_matches_type(VaultItemOperationResponse, item, path=["response"])
+
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     def test_raw_response_perform_operation_overload_3(self, client: Kernel) -> None:
@@ -1793,6 +1809,22 @@ async def test_method_perform_operation_overload_3(self, async_client: AsyncKern
         )
         assert_matches_type(VaultItemOperationResponse, item, path=["response"])
 
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_method_perform_operation_with_all_params_overload_3(self, async_client: AsyncKernel) -> None:
+        item = await async_client.vaults.items.perform_operation(
+            key="key",
+            id_or_name="id_or_name",
+            checkout={
+                "browser_id": "browser_id",
+                "environment": "production",
+                "merchant_origin": "merchant_origin",
+                "psp": "square",
+            },
+            type="prepare_checkout",
+        )
+        assert_matches_type(VaultItemOperationResponse, item, path=["response"])
+
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     async def test_raw_response_perform_operation_overload_3(self, async_client: AsyncKernel) -> None: