Add client.cards.get_embed_url() and client.cards.get_embed_html().

Author: stainless-bot

lithic/_base_client.py

@@ -24,6 +24,7 @@
 import anyio
 import httpx
 import pydantic
+from httpx import URL
 from pydantic import PrivateAttr
 
 from . import _base_exceptions as exceptions
@@ -349,6 +350,10 @@ def default_headers(self) -> Dict[str, str]:
     def user_agent(self) -> str:
         return f"{self.__class__.__name__}/Python {self._version}"
 
+    @property
+    def base_url(self) -> URL:
+        return self._client.base_url
+
     @lru_cache(maxsize=None)
     def platform_properties(self) -> str:
         arch, _ = platform.architecture()

lithic/resources/cards.py

@@ -1,6 +1,13 @@
 # File generated from our OpenAPI spec by Stainless.
 
+import hmac
+import json
+import base64
+import hashlib
 from typing import Union
+from datetime import datetime, timezone, timedelta
+
+from httpx import URL
 
 from .._types import NOT_GIVEN, Headers, Timeout, NotGiven
 from .._resource import SyncAPIResource, AsyncAPIResource
@@ -12,8 +19,11 @@
 from ..types.card_create_params import CardCreateParams
 from ..types.card_update_params import CardUpdateParams
 from ..types.card_reissue_params import CardReissueParams
+from ..types.embed_request_param import *
 from ..types.card_provision_params import CardProvisionParams
 from ..types.card_provision_response import *
+from ..types.card_get_embed_url_params import CardGetEmbedURLParams
+from ..types.card_get_embed_html_params import CardGetEmbedHTMLParams
 
 __all__ = ["Cards", "AsyncCards"]
 
@@ -144,6 +154,80 @@ def embed(
             cast_to=str,
         )
 
+    def get_embed_html(
+        self,
+        query: CardGetEmbedHTMLParams,
+        *,
+        headers: Union[Headers, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
+        timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
+    ) -> str:
+        """
+        Generates and executes an embed request, returning html you can serve to the
+        user.
+
+        Be aware that this html contains sensitive data whose presence on your server
+        could trigger PCI DSS.
+
+        If your company is not certified PCI compliant, we recommend using
+        `get_embed_url()` instead. You would then pass that returned URL to the
+        frontend, where you can load it via an iframe.
+        """
+        headers = {"Accept": "text/html", **(headers or {})}
+        return self._get(
+            str(self.get_embed_url(query)),
+            cast_to=str,
+            options=make_request_options(headers, max_retries, timeout),
+        )
+
+    def get_embed_url(self, query: CardGetEmbedURLParams) -> URL:
+        """
+        Handling full card PANs and CVV codes requires that you comply with the Payment
+        Card Industry Data Security Standards (PCI DSS). Some clients choose to reduce
+        their compliance obligations by leveraging our embedded card UI solution
+        documented below.
+
+        In this setup, PANs and CVV codes are presented to the end-user via a card UI
+        that we provide, optionally styled in the customer's branding using a specified
+        css stylesheet. A user's browser makes the request directly to api.lithic.com,
+        so card PANs and CVVs never touch the API customer's servers while full card
+        data is displayed to their end-users. The response contains an HTML document.
+        This means that the url for the request can be inserted straight into the `src`
+        attribute of an iframe.
+
+        ```html
+        <iframe
+          id="card-iframe"
+          src="https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1..."
+          allow="clipboard-write"
+          class="content"
+        ></iframe>
+        ```
+
+        You should compute the request payload on the server side. You can render it (or
+        the whole iframe) on the server or make an ajax call from your front end code,
+        but **do not ever embed your API key into front end code, as doing so introduces
+        a serious security vulnerability**.
+        """
+        # Default expiration of 1 minute from now.
+        query.setdefault("expiration", (datetime.now(timezone.utc) + timedelta(minutes=1)).isoformat())
+        serialized = json.dumps(query, sort_keys=True, separators=(",", ":"))
+        params = {
+            "embed_request": base64.b64encode(bytes(serialized, "utf-8")).decode("utf-8"),
+            "hmac": base64.b64encode(
+                hmac.new(
+                    key=bytes(self._client.api_key, "utf-8"),
+                    msg=bytes(serialized, "utf-8"),
+                    digestmod=hashlib.sha256,
+                ).digest()
+            ).decode("utf-8"),
+        }
+
+        # Copied nearly directly from httpx.BaseClient._merge_url
+        base_url = self._client.base_url
+        raw_path = base_url.raw_path + URL("embed/card").raw_path
+        return base_url.copy_with(raw_path=raw_path).copy_merge_params(params)
+
     def provision(
         self,
         card_token: str,
@@ -317,6 +401,80 @@ async def embed(
             cast_to=str,
         )
 
+    async def get_embed_html(
+        self,
+        query: CardGetEmbedHTMLParams,
+        *,
+        headers: Union[Headers, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
+        timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
+    ) -> str:
+        """
+        Generates and executes an embed request, returning html you can serve to the
+        user.
+
+        Be aware that this html contains sensitive data whose presence on your server
+        could trigger PCI DSS.
+
+        If your company is not certified PCI compliant, we recommend using
+        `get_embed_url()` instead. You would then pass that returned URL to the
+        frontend, where you can load it via an iframe.
+        """
+        headers = {"Accept": "text/html", **(headers or {})}
+        return await self._get(
+            str(self.get_embed_url(query)),
+            cast_to=str,
+            options=make_request_options(headers, max_retries, timeout),
+        )
+
+    def get_embed_url(self, query: CardGetEmbedURLParams) -> URL:
+        """
+        Handling full card PANs and CVV codes requires that you comply with the Payment
+        Card Industry Data Security Standards (PCI DSS). Some clients choose to reduce
+        their compliance obligations by leveraging our embedded card UI solution
+        documented below.
+
+        In this setup, PANs and CVV codes are presented to the end-user via a card UI
+        that we provide, optionally styled in the customer's branding using a specified
+        css stylesheet. A user's browser makes the request directly to api.lithic.com,
+        so card PANs and CVVs never touch the API customer's servers while full card
+        data is displayed to their end-users. The response contains an HTML document.
+        This means that the url for the request can be inserted straight into the `src`
+        attribute of an iframe.
+
+        ```html
+        <iframe
+          id="card-iframe"
+          src="https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1..."
+          allow="clipboard-write"
+          class="content"
+        ></iframe>
+        ```
+
+        You should compute the request payload on the server side. You can render it (or
+        the whole iframe) on the server or make an ajax call from your front end code,
+        but **do not ever embed your API key into front end code, as doing so introduces
+        a serious security vulnerability**.
+        """
+        # Default expiration of 1 minute from now.
+        query.setdefault("expiration", (datetime.now(timezone.utc) + timedelta(minutes=1)).isoformat())
+        serialized = json.dumps(query, sort_keys=True, separators=(",", ":"))
+        params = {
+            "embed_request": base64.b64encode(bytes(serialized, "utf-8")).decode("utf-8"),
+            "hmac": base64.b64encode(
+                hmac.new(
+                    key=bytes(self._client.api_key, "utf-8"),
+                    msg=bytes(serialized, "utf-8"),
+                    digestmod=hashlib.sha256,
+                ).digest()
+            ).decode("utf-8"),
+        }
+
+        # Copied nearly directly from httpx.BaseClient._merge_url
+        base_url = self._client.base_url
+        raw_path = base_url.raw_path + URL("embed/card").raw_path
+        return base_url.copy_with(raw_path=raw_path).copy_merge_params(params)
+
     async def provision(
         self,
         card_token: str,

lithic/types/__init__.py

@@ -13,6 +13,7 @@
 from .card_update_params import CardUpdateParams as CardUpdateParams
 from .account_list_params import AccountListParams as AccountListParams
 from .card_reissue_params import CardReissueParams as CardReissueParams
+from .embed_request_param import EmbedRequestParams as EmbedRequestParams
 from .account_update_params import AccountUpdateParams as AccountUpdateParams
 from .auth_rule_list_params import AuthRuleListParams as AuthRuleListParams
 from .card_provision_params import CardProvisionParams as CardProvisionParams
@@ -29,6 +30,8 @@
 from .auth_rule_create_response import AuthRuleCreateResponse as AuthRuleCreateResponse
 from .auth_rule_remove_response import AuthRuleRemoveResponse as AuthRuleRemoveResponse
 from .auth_rule_update_response import AuthRuleUpdateResponse as AuthRuleUpdateResponse
+from .card_get_embed_url_params import CardGetEmbedURLParams as CardGetEmbedURLParams
+from .card_get_embed_html_params import CardGetEmbedHTMLParams as CardGetEmbedHTMLParams
 from .funding_source_list_params import (
     FundingSourceListParams as FundingSourceListParams,
 )

lithic/types/card_get_embed_html_params.py

@@ -0,0 +1,40 @@
+# File generated from our OpenAPI spec by Stainless.
+
+from __future__ import annotations
+
+from typing_extensions import Required, TypedDict
+
+__all__ = ["CardGetEmbedHTMLParams"]
+
+
+class CardGetEmbedHTMLParams(TypedDict, total=False):
+    token: Required[str]
+    """Globally unique identifier for the card to be displayed."""
+
+    account_token: str
+    """Only needs to be included if one or more end-users have been enrolled."""
+
+    css: str
+    """
+    A publicly available URI, so the white-labeled card element can be styled with
+    the client's branding.
+    """
+
+    expiration: str
+    """An ISO 8601 timestamp for when the request should expire. UTC time zone.
+
+    If no timezone is specified, UTC will be used. If payload does not contain an
+    expiration, the request will never expire.
+
+    Using an `expiration` reduces the risk of a
+    [replay attack](https://en.wikipedia.org/wiki/Replay_attack). Without supplying
+    the `expiration`, in the event that a malicious user gets a copy of your request
+    in transit, they will be able to obtain the response data indefinitely.
+    """
+
+    target_origin: str
+    """Required if you want to post the element clicked to the parent iframe.
+
+    If you supply this param, you can also capture click events in the parent iframe
+    by adding an event listener.
+    """

lithic/types/card_get_embed_url_params.py

@@ -0,0 +1,40 @@
+# File generated from our OpenAPI spec by Stainless.
+
+from __future__ import annotations
+
+from typing_extensions import Required, TypedDict
+
+__all__ = ["CardGetEmbedURLParams"]
+
+
+class CardGetEmbedURLParams(TypedDict, total=False):
+    token: Required[str]
+    """Globally unique identifier for the card to be displayed."""
+
+    account_token: str
+    """Only needs to be included if one or more end-users have been enrolled."""
+
+    css: str
+    """
+    A publicly available URI, so the white-labeled card element can be styled with
+    the client's branding.
+    """
+
+    expiration: str
+    """An ISO 8601 timestamp for when the request should expire. UTC time zone.
+
+    If no timezone is specified, UTC will be used. If payload does not contain an
+    expiration, the request will never expire.
+
+    Using an `expiration` reduces the risk of a
+    [replay attack](https://en.wikipedia.org/wiki/Replay_attack). Without supplying
+    the `expiration`, in the event that a malicious user gets a copy of your request
+    in transit, they will be able to obtain the response data indefinitely.
+    """
+
+    target_origin: str
+    """Required if you want to post the element clicked to the parent iframe.
+
+    If you supply this param, you can also capture click events in the parent iframe
+    by adding an event listener.
+    """

lithic/types/embed_request_param.py

@@ -0,0 +1,40 @@
+# File generated from our OpenAPI spec by Stainless.
+
+from typing import Optional
+
+from .._models import BaseModel
+
+__all__ = ["EmbedRequestParams"]
+
+
+class EmbedRequestParams(BaseModel):
+    token: str
+    """Globally unique identifier for the card to be displayed."""
+
+    account_token: Optional[str]
+    """Only needs to be included if one or more end-users have been enrolled."""
+
+    css: Optional[str]
+    """
+    A publicly available URI, so the white-labeled card element can be styled with
+    the client's branding.
+    """
+
+    expiration: Optional[str]
+    """An ISO 8601 timestamp for when the request should expire. UTC time zone.
+
+    If no timezone is specified, UTC will be used. If payload does not contain an
+    expiration, the request will never expire.
+
+    Using an `expiration` reduces the risk of a
+    [replay attack](https://en.wikipedia.org/wiki/Replay_attack). Without supplying
+    the `expiration`, in the event that a malicious user gets a copy of your request
+    in transit, they will be able to obtain the response data indefinitely.
+    """
+
+    target_origin: Optional[str]
+    """Required if you want to post the element clicked to the parent iframe.
+
+    If you supply this param, you can also capture click events in the parent iframe
+    by adding an event listener.
+    """

poetry.lock

@@ -20,7 +20,7 @@ black = "^22.1.0"
 respx = "^0.19.2"
 pytest = "^7.1.1"
 pytest-asyncio = "^0.18.3"
-pyright = "^1.1.255"
+pyright = "^1.1.260"
 isort = "^5.10.1"
 autoflake = "^1.4"