feat: Add single-use AgentCard prepare_checkout for Square

Stainless-Generated-From: 0c1e767db4c047801717ec350cd4b40cd7eace0c

Author: kernel-internal[bot]

api.md

@@ -525,12 +525,16 @@ Types:
 ```python
 from kernel.types.vaults import (
     AgentcardCheckoutAuthorization,
+    AgentcardCheckoutPreparation,
+    AuthorizeVaultItemOperationRequest,
     CardVaultItemSpec,
     CardVaultItemState,
     FillVaultItemOperationRequest,
     FillVaultItemOperationResult,
+    PrepareCheckoutVaultItemOperationRequest,
     VaultCardAliases,
     VaultCardFillField,
+    VaultCheckoutContext,
     VaultFillFieldResult,
     VaultItem,
     VaultItemAction,

src/kernel/resources/vaults/items.py

@@ -20,10 +20,18 @@
 from .wallet_vault_item_state import WalletVaultItemState as WalletVaultItemState
 from .card_vault_item_spec_param import CardVaultItemSpecParam as CardVaultItemSpecParam
 from .vault_card_fill_field_param import VaultCardFillFieldParam as VaultCardFillFieldParam
+from .vault_checkout_context_param import VaultCheckoutContextParam as VaultCheckoutContextParam
 from .item_perform_operation_params import ItemPerformOperationParams as ItemPerformOperationParams
 from .vault_item_operation_response import VaultItemOperationResponse as VaultItemOperationResponse
+from .agentcard_checkout_preparation import AgentcardCheckoutPreparation as AgentcardCheckoutPreparation
 from .agentcard_checkout_authorization import AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization
 from .fill_vault_item_operation_result import FillVaultItemOperationResult as FillVaultItemOperationResult
 from .fill_vault_item_operation_request_param import (
     FillVaultItemOperationRequestParam as FillVaultItemOperationRequestParam,
 )
+from .authorize_vault_item_operation_request_param import (
+    AuthorizeVaultItemOperationRequestParam as AuthorizeVaultItemOperationRequestParam,
+)
+from .prepare_checkout_vault_item_operation_request_param import (
+    PrepareCheckoutVaultItemOperationRequestParam as PrepareCheckoutVaultItemOperationRequestParam,
+)

src/kernel/types/vaults/__init__.py

@@ -0,0 +1,43 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from datetime import datetime
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["AgentcardCheckoutPreparation"]
+
+
+class AgentcardCheckoutPreparation(BaseModel):
+    """One-use Square checkout preparation.
+
+    Keep the approval page open through token handoff. The amount is display-only and does not constrain the merchant's eventual charge.
+    """
+
+    browser_id: str
+
+    created_at: datetime
+
+    environment: Literal["production", "sandbox"]
+
+    merchant_origin: str
+
+    status: Literal["creating", "awaiting_approval", "ready", "consumed", "cancelled", "expired", "unknown"]
+    """
+    Preparation consumed means egress claimed the preparation and it cannot be
+    reused. It does not mean the attempt settled. Use the enclosing item's status as
+    the lifecycle indicator; item consumed means the attempt settled, not that an
+    order or charge succeeded.
+    """
+
+    id: Optional[str] = None
+
+    approval_url: Optional[str] = None
+
+    expires_at: Optional[datetime] = None
+    """
+    When ready, the absolute deadline to submit the first native request; no later
+    than provider readiness expiry or 30 seconds after Kernel first observes
+    readiness. Polling never extends this deadline.
+    """

src/kernel/types/vaults/agentcard_checkout_preparation.py

@@ -0,0 +1,16 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["AuthorizeVaultItemOperationRequestParam"]
+
+
+class AuthorizeVaultItemOperationRequestParam(TypedDict, total=False):
+    """Authorize a Link card using its existing purchase specification.
+
+    Use only after explicit user approval and when the item advertises authorize. Do not automatically retry provider failures or indeterminate outcomes. Checkout context is not accepted.
+    """
+
+    type: Required[Literal["authorize"]]

src/kernel/types/vaults/authorize_vault_item_operation_request_param.py

@@ -8,6 +8,7 @@
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
 from .vault_card_aliases import VaultCardAliases
+from .agentcard_checkout_preparation import AgentcardCheckoutPreparation
 from .agentcard_checkout_authorization import AgentcardCheckoutAuthorization
 
 __all__ = ["CardVaultItemState", "LinkCardState", "LinkCardStateMasks", "AgentCardCardState", "AgentCardCardStateMasks"]
@@ -76,14 +77,28 @@ def __getattr__(self, attr: str) -> str: ...
 class AgentCardCardState(BaseModel):
     provider: Literal["agentcard"]
 
-    status: Literal["requested", "ready", "pending_approval", "degraded", "recovery_required"]
-    """recovery_required means the original checkout outcome is unresolved.
-
-    Automatic reuse is blocked. Known authorization IDs must be reconciled through
-    provider observations or support. When no authorization ID was returned, an
-    explicitly confirmed item deletion may abandon the unresolved attempt so the
-    caller can create a replacement; deletion does not prove that the original
-    attempt failed. It does not mean declined or expired.
+    status: Literal[
+        "requested",
+        "ready",
+        "preparing",
+        "ready_to_submit",
+        "pending_approval",
+        "consumed",
+        "stopped",
+        "outcome_unknown",
+        "degraded",
+        "recovery_required",
+    ]
+    """ready_to_submit is device readiness for at most 30 seconds.
+
+    consumed means the prepared attempt has settled, not that an order succeeded.
+    stopped cannot be reused. outcome_unknown requires merchant reconciliation and
+    blocks new requests. recovery_required means the original checkout outcome is
+    unresolved. Automatic reuse is blocked. Known authorization IDs must be
+    reconciled through provider observations or support. When no authorization ID
+    was returned, an explicitly confirmed item deletion may abandon the unresolved
+    attempt so the caller can create a replacement; deletion does not prove that the
+    original attempt failed. It does not mean declined or expired.
     """
 
     aliases: Optional[VaultCardAliases] = None
@@ -96,6 +111,13 @@ class AgentCardCardState(BaseModel):
 
     masks: Optional[AgentCardCardStateMasks] = None
 
+    preparation: Optional[AgentcardCheckoutPreparation] = None
+    """One-use Square checkout preparation.
+
+    Keep the approval page open through token handoff. The amount is display-only
+    and does not constrain the merchant's eventual charge.
+    """
+
     status_reason: Optional[str] = None
 
 

src/kernel/types/vaults/card_vault_item_state.py

@@ -6,8 +6,14 @@
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
 from .vault_card_fill_field_param import VaultCardFillFieldParam
+from .vault_checkout_context_param import VaultCheckoutContextParam
 
-__all__ = ["ItemPerformOperationParams", "AuthorizeVaultItemOperationRequest", "FillVaultItemOperationRequest"]
+__all__ = [
+    "ItemPerformOperationParams",
+    "AuthorizeVaultItemOperationRequest",
+    "PrepareCheckoutVaultItemOperationRequest",
+    "FillVaultItemOperationRequest",
+]
 
 
 class AuthorizeVaultItemOperationRequest(TypedDict, total=False):
@@ -16,6 +22,21 @@ class AuthorizeVaultItemOperationRequest(TypedDict, total=False):
     type: Required[Literal["authorize"]]
 
 
+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.
+    """
+
+    type: Required[Literal["prepare_checkout"]]
+
+
 class FillVaultItemOperationRequest(TypedDict, total=False):
     id_or_name: Required[str]
 
@@ -38,4 +59,6 @@ class FillVaultItemOperationRequest(TypedDict, total=False):
     """Total operation deadline in milliseconds, not a per-field timeout."""
 
 
-ItemPerformOperationParams: TypeAlias = Union[AuthorizeVaultItemOperationRequest, FillVaultItemOperationRequest]
+ItemPerformOperationParams: TypeAlias = Union[
+    AuthorizeVaultItemOperationRequest, PrepareCheckoutVaultItemOperationRequest, FillVaultItemOperationRequest
+]

src/kernel/types/vaults/item_perform_operation_params.py

@@ -0,0 +1,27 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, TypedDict
+
+from .vault_checkout_context_param import VaultCheckoutContextParam
+
+__all__ = ["PrepareCheckoutVaultItemOperationRequestParam"]
+
+
+class PrepareCheckoutVaultItemOperationRequestParam(TypedDict, total=False):
+    """Prepare an unused AgentCard card for Square 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.
+    """
+
+    type: Required[Literal["prepare_checkout"]]

src/kernel/types/vaults/prepare_checkout_vault_item_operation_request_param.py

@@ -0,0 +1,27 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, TypedDict
+
+__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.
+    """
+
+    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."""
+
+    merchant_origin: Required[str]
+    """Canonical HTTPS origin of the top-level merchant document, not the Square
+    iframe.
+
+    HTTP localhost is accepted for tests.
+    """

src/kernel/types/vaults/vault_checkout_context_param.py

@@ -43,7 +43,7 @@ class WalletVaultItemAvailableOperation(BaseModel):
 
     description: str
 
-    type: Literal["authorize", "fill"]
+    type: Literal["authorize", "prepare_checkout", "fill"]
 
 
 class WalletVaultItemExpanded(BaseModel):
@@ -107,7 +107,7 @@ class CardVaultItemAvailableOperation(BaseModel):
 
     description: str
 
-    type: Literal["authorize", "fill"]
+    type: Literal["authorize", "prepare_checkout", "fill"]
 
 
 class CardVaultItem(BaseModel):