feat: Wire Shop Pay into the vault API

Stainless-Generated-From: aaafed9fc90df045849ad32557040ab8365e13e8

Author: kernel-internal[bot]

api.md

@@ -634,6 +634,10 @@ from kernel.types.vaults import (
     RemovePaymentMethodVaultItemOperationRequest,
     RemovePaymentMethodVaultItemOperationResult,
     RestartVerificationVaultItemOperationRequest,
+    ShopPayCardState,
+    ShopPayCardVaultItemSpec,
+    ShopPayWalletState,
+    ShopPayWalletVaultItemSpec,
     VaultCardAliases,
     VaultCardFillField,
     VaultCheckoutContext,

src/kernel/resources/vaults/items.py

@@ -386,13 +386,13 @@ def delete(
         Unresolved payment operations normally block deletion, including operations on
         child cards of a wallet. Deleting a connected Kernel wallet first blocks new
         payments on it, then removes its enrolled card. If that fails, the wallet is
-        kept and keeps refusing payments; retry the deletion. A Link or Kernel card in
-        recovery_required for issuance, or an AgentCard card in recovery_required whose
-        checkout create response returned no authorization ID, may be explicitly
-        abandoned by deleting that card directly; deleting its wallet or vault remains
-        blocked until the card is deleted. Deleting or recreating an item is not proof
-        that a payment did not occur. Deleting a managed auth credential item leaves the
-        connection and its saved credential unchanged.
+        kept and keeps refusing payments; retry the deletion. A Link, Kernel or Shop Pay
+        card in recovery_required for issuance, or an AgentCard card in
+        recovery_required whose checkout create response returned no authorization ID,
+        may be explicitly abandoned by deleting that card directly; deleting its wallet
+        or vault remains blocked until the card is deleted. Deleting or recreating an
+        item is not proof that a payment did not occur. Deleting a managed auth
+        credential item leaves the connection and its saved credential unchanged.
 
         Args:
           extra_headers: Send extra headers
@@ -2371,13 +2371,13 @@ async def delete(
         Unresolved payment operations normally block deletion, including operations on
         child cards of a wallet. Deleting a connected Kernel wallet first blocks new
         payments on it, then removes its enrolled card. If that fails, the wallet is
-        kept and keeps refusing payments; retry the deletion. A Link or Kernel card in
-        recovery_required for issuance, or an AgentCard card in recovery_required whose
-        checkout create response returned no authorization ID, may be explicitly
-        abandoned by deleting that card directly; deleting its wallet or vault remains
-        blocked until the card is deleted. Deleting or recreating an item is not proof
-        that a payment did not occur. Deleting a managed auth credential item leaves the
-        connection and its saved credential unchanged.
+        kept and keeps refusing payments; retry the deletion. A Link, Kernel or Shop Pay
+        card in recovery_required for issuance, or an AgentCard card in
+        recovery_required whose checkout create response returned no authorization ID,
+        may be explicitly abandoned by deleting that card directly; deleting its wallet
+        or vault remains blocked until the card is deleted. Deleting or recreating an
+        item is not proof that a payment did not occur. Deleting a managed auth
+        credential item leaves the connection and its saved credential unchanged.
 
         Args:
           extra_headers: Send extra headers

src/kernel/types/vaults/__init__.py

@@ -13,13 +13,15 @@
 from .item_upsert_params import ItemUpsertParams as ItemUpsertParams
 from .vault_card_aliases import VaultCardAliases as VaultCardAliases
 from .kernel_wallet_state import KernelWalletState as KernelWalletState
+from .shop_pay_card_state import ShopPayCardState as ShopPayCardState
 from .card_vault_item_spec import CardVaultItemSpec as CardVaultItemSpec
 from .item_events_response import ItemEventsResponse as ItemEventsResponse
 from .item_retrieve_params import ItemRetrieveParams as ItemRetrieveParams
 from .vault_payment_method import VaultPaymentMethod as VaultPaymentMethod
 from .card_vault_item_state import CardVaultItemState as CardVaultItemState
 from .credential_vault_item import CredentialVaultItem as CredentialVaultItem
 from .link_shipping_address import LinkShippingAddress as LinkShippingAddress
+from .shop_pay_wallet_state import ShopPayWalletState as ShopPayWalletState
 from .vault_fill_field_param import VaultFillFieldParam as VaultFillFieldParam
 from .wallet_vault_item_spec import WalletVaultItemSpec as WalletVaultItemSpec
 from .vault_fill_field_result import VaultFillFieldResult as VaultFillFieldResult
@@ -39,9 +41,11 @@
 from .credential_account_vault_item import CredentialAccountVaultItem as CredentialAccountVaultItem
 from .item_perform_operation_params import ItemPerformOperationParams as ItemPerformOperationParams
 from .kernel_wallet_vault_item_spec import KernelWalletVaultItemSpec as KernelWalletVaultItemSpec
+from .shop_pay_card_vault_item_spec import ShopPayCardVaultItemSpec as ShopPayCardVaultItemSpec
 from .vault_item_operation_response import VaultItemOperationResponse as VaultItemOperationResponse
 from .agentcard_checkout_preparation import AgentcardCheckoutPreparation as AgentcardCheckoutPreparation
 from .payment_request_vault_item_spec import PaymentRequestVaultItemSpec as PaymentRequestVaultItemSpec
+from .shop_pay_wallet_vault_item_spec import ShopPayWalletVaultItemSpec as ShopPayWalletVaultItemSpec
 from .agentcard_checkout_authorization import AgentcardCheckoutAuthorization as AgentcardCheckoutAuthorization
 from .fill_vault_item_operation_result import FillVaultItemOperationResult as FillVaultItemOperationResult
 from .payment_request_vault_item_state import PaymentRequestVaultItemState as PaymentRequestVaultItemState
@@ -55,11 +59,13 @@
 from .kernel_wallet_vault_item_spec_param import KernelWalletVaultItemSpecParam as KernelWalletVaultItemSpecParam
 from .managed_auth_credential_vault_field import ManagedAuthCredentialVaultField as ManagedAuthCredentialVaultField
 from .passkey_vault_item_operation_result import PasskeyVaultItemOperationResult as PasskeyVaultItemOperationResult
+from .shop_pay_card_vault_item_spec_param import ShopPayCardVaultItemSpecParam as ShopPayCardVaultItemSpecParam
 from .one_password_credential_account_spec import OnePasswordCredentialAccountSpec as OnePasswordCredentialAccountSpec
 from .one_password_credential_account_state import (
     OnePasswordCredentialAccountState as OnePasswordCredentialAccountState,
 )
 from .payment_request_vault_item_spec_param import PaymentRequestVaultItemSpecParam as PaymentRequestVaultItemSpecParam
+from .shop_pay_wallet_vault_item_spec_param import ShopPayWalletVaultItemSpecParam as ShopPayWalletVaultItemSpecParam
 from .credential_vault_item_spec_input_param import (
     CredentialVaultItemSpecInputParam as CredentialVaultItemSpecInputParam,
 )

src/kernel/types/vaults/authorize_vault_item_operation_request_param.py

@@ -8,9 +8,8 @@
 
 
 class AuthorizeVaultItemOperationRequestParam(TypedDict, total=False):
-    """Authorize a Link or Kernel card using its existing purchase specification.
-
-    Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel inspects that checkout, chooses how the credential is delivered, and limits fill to that checkout's origin in any browser with this vault attached. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel cards do not accept browser_id or page_url.
+    """
+    Authorize a Link, Kernel or Shop Pay card using its existing purchase specification. Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel inspects that checkout, chooses how the credential is delivered, and limits fill to that checkout's origin in any browser with this vault attached. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel and Shop Pay cards do not accept browser_id or page_url.
     """
 
     type: Required[Literal["authorize"]]

src/kernel/types/vaults/card_vault_item_spec.py

@@ -6,6 +6,7 @@
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
 from .kernel_card_vault_item_spec import KernelCardVaultItemSpec
+from .shop_pay_card_vault_item_spec import ShopPayCardVaultItemSpec
 
 __all__ = [
     "CardVaultItemSpec",
@@ -161,6 +162,6 @@ class AgentCardCardVaultItemSpec(BaseModel):
 
 
 CardVaultItemSpec: TypeAlias = Annotated[
-    Union[LinkCardVaultItemSpec, AgentCardCardVaultItemSpec, KernelCardVaultItemSpec],
+    Union[LinkCardVaultItemSpec, AgentCardCardVaultItemSpec, KernelCardVaultItemSpec, ShopPayCardVaultItemSpec],
     PropertyInfo(discriminator="provider"),
 ]

src/kernel/types/vaults/card_vault_item_spec_param.py

@@ -6,6 +6,7 @@
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
 from .kernel_card_vault_item_spec_param import KernelCardVaultItemSpecParam
+from .shop_pay_card_vault_item_spec_param import ShopPayCardVaultItemSpecParam
 
 __all__ = [
     "CardVaultItemSpecParam",
@@ -161,5 +162,5 @@ class AgentCardCardVaultItemSpec(TypedDict, total=False):
 
 
 CardVaultItemSpecParam: TypeAlias = Union[
-    LinkCardVaultItemSpec, AgentCardCardVaultItemSpec, KernelCardVaultItemSpecParam
+    LinkCardVaultItemSpec, AgentCardCardVaultItemSpec, KernelCardVaultItemSpecParam, ShopPayCardVaultItemSpecParam
 ]

src/kernel/types/vaults/card_vault_item_state.py

@@ -9,6 +9,7 @@
 from ..._models import BaseModel
 from .kernel_card_state import KernelCardState
 from .vault_card_aliases import VaultCardAliases
+from .shop_pay_card_state import ShopPayCardState
 from .agentcard_checkout_preparation import AgentcardCheckoutPreparation
 from .agentcard_checkout_authorization import AgentcardCheckoutAuthorization
 
@@ -134,5 +135,5 @@ class AgentCardCardState(BaseModel):
 
 
 CardVaultItemState: TypeAlias = Annotated[
-    Union[LinkCardState, AgentCardCardState, KernelCardState], PropertyInfo(discriminator="provider")
+    Union[LinkCardState, AgentCardCardState, KernelCardState, ShopPayCardState], PropertyInfo(discriminator="provider")
 ]

src/kernel/types/vaults/confirm_transaction_vault_item_operation_request_param.py

@@ -12,9 +12,8 @@
 
 
 class ConfirmTransactionVaultItemOperationRequestParam(TypedDict, total=False):
-    """Report a real merchant transaction outcome for an issued Kernel Visa credential.
-
-    Never infer success from filling checkout or receiving a credential. Supply the observed status, transaction type, actual amount, currency and timestamp. Unknown outcomes require manual reconciliation, not retry. Each purchase accepts one report.
+    """
+    Report a real merchant transaction outcome for an issued Kernel Visa or Shop Pay credential. Shop Pay accepts PURCHASE, AUTHORIZATION and CAPTURE. Never infer success from filling checkout or receiving a credential. Supply the observed status, transaction type, actual amount, currency and timestamp. Unknown outcomes require manual reconciliation, not retry. Each purchase accepts one report.
     """
 
     amount: Required[int]

src/kernel/types/vaults/item_upsert_params.py

@@ -8,6 +8,7 @@
 from .card_vault_item_spec_param import CardVaultItemSpecParam
 from .kernel_wallet_vault_item_spec_param import KernelWalletVaultItemSpecParam
 from .payment_request_vault_item_spec_param import PaymentRequestVaultItemSpecParam
+from .shop_pay_wallet_vault_item_spec_param import ShopPayWalletVaultItemSpecParam
 from .credential_vault_item_spec_input_param import CredentialVaultItemSpecInputParam
 from .one_password_credential_account_spec_param import OnePasswordCredentialAccountSpecParam
 
@@ -190,6 +191,7 @@ class WalletVaultItemRequestSpecAgentCardWalletVaultItemSpec(TypedDict, total=Fa
     WalletVaultItemRequestSpecLinkWalletVaultItemRequestSpec,
     WalletVaultItemRequestSpecAgentCardWalletVaultItemSpec,
     KernelWalletVaultItemSpecParam,
+    ShopPayWalletVaultItemSpecParam,
 ]
 
 

src/kernel/types/vaults/shop_pay_card_state.py

@@ -0,0 +1,57 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import TYPE_CHECKING, Dict, List, Optional
+from typing_extensions import Literal
+
+from pydantic import Field as FieldInfo
+
+from ..._models import BaseModel
+
+__all__ = ["ShopPayCardState", "Masks"]
+
+
+class Masks(BaseModel):
+    brand: Optional[str] = None
+
+    last4: Optional[str] = None
+
+    token_last4: Optional[str] = None
+    """Last four digits of the network token presented to the merchant."""
+
+    if TYPE_CHECKING:
+        # Some versions of Pydantic <2.8.0 have a bug and don’t allow assigning a
+        # value to this field, so for compatibility we avoid doing it at runtime.
+        __pydantic_extra__: Dict[str, str] = FieldInfo(init=False)  # pyright: ignore[reportIncompatibleVariableOverride]
+
+        # Stub to indicate that arbitrary properties are accepted.
+        # To access properties that are not valid identifiers you can use `getattr`, e.g.
+        # `getattr(obj, '$type')`
+        def __getattr__(self, attr: str) -> str: ...
+    else:
+        __pydantic_extra__: Dict[str, str]
+
+
+class ShopPayCardState(BaseModel):
+    """Issued Shop Pay cards retain encrypted card material for the fill operation."""
+
+    provider: Literal["shop_pay"]
+
+    status: Literal[
+        "requested", "pending_authorization", "ready", "consumed", "expired", "declined", "recovery_required"
+    ]
+    """declined covers a request the shopper declined or that was cancelled.
+
+    recovery_required means a provider operation has an unresolved outcome and the
+    card cannot be used. When status_reason says the provider refused retrieval
+    before acceptance, no card was issued and a later read retries. Otherwise follow
+    status_reason: recovery for issuance can be abandoned by deleting the card and
+    creating a new one, and the shopper approves the new purchase separately.
+    Recovery while reporting a merchant transaction cannot be deleted and must be
+    reconciled with support.
+    """
+
+    domains: Optional[List[str]] = None
+
+    masks: Optional[Masks] = None
+
+    status_reason: Optional[str] = None