feat(api): add embed.session_generated and embed.viewed webhook event types

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 214
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/lithic/lithic-09b6d1b85c657173562e9a372adc74551f07d476122003078e9168467329f792.yml
-openapi_spec_hash: a2b3a526310ceccd4ccb59ec428d246f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/lithic/lithic-2d2600072500797474f0d7798c1a8b668bfbc4e0c6a8f076ca7b4cc7ad82058b.yml
+openapi_spec_hash: 7605eb6be77a3d150078916f0eb0e9ac
 config_hash: 5bb913c05ebeb301ec925b16e75bb251

api.md

@@ -915,6 +915,8 @@ Types:
 - <code><a href="./src/resources/webhooks.ts">DigitalWalletTokenizationUpdatedWebhookEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">DisputeUpdatedWebhookEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">DisputeEvidenceUploadFailedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">EmbedSessionGeneratedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">EmbedViewedWebhookEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">ExternalBankAccountCreatedWebhookEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">ExternalBankAccountUpdatedWebhookEvent</a></code>
 - <code><a href="./src/resources/webhooks.ts">ExternalPaymentCreatedWebhookEvent</a></code>

packages/mcp-server/src/local-docs-search.ts

@@ -3593,13 +3593,13 @@ const EMBEDDED_METHODS: MethodEntry[] = [
     httpMethod: 'get',
     summary: 'Embedded card UI',
     description:
-      '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.\n\nIn 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 (see Embedded Card UI or Changelog for upcoming changes in January). This means that the url for the request can be inserted straight into the `src` attribute of an iframe.\n\n```html\n<iframe id="card-iframe"\n        src="https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1..."\n        allow="clipboard-write" class="content"></iframe>\n```\n\nYou 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**.\n',
+      '**Deprecated.** Use the modern embedded card flow instead: create a session with `POST /v1/cards/{card_token}/embed` and render it via `GET /v1/embed`.\n\nHandling 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.\n\nIn 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 (see Embedded Card UI or Changelog for upcoming changes in January). This means that the url for the request can be inserted straight into the `src` attribute of an iframe.\n\n```html\n<iframe id="card-iframe"\n        src="https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1..."\n        allow="clipboard-write" class="content"></iframe>\n```\n\nYou 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**.\n',
     stainlessPath: '(resource) cards > (method) embed',
     qualified: 'client.cards.embed',
     params: ['embed_request: string;', 'hmac: string;'],
     response: 'string',
     markdown:
-      "## embed\n\n`client.cards.embed(embed_request: string, hmac: string): string`\n\n**get** `/v1/embed/card`\n\nHandling 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.\n\nIn 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 (see Embedded Card UI or Changelog for upcoming changes in January). This means that the url for the request can be inserted straight into the `src` attribute of an iframe.\n\n```html\n<iframe id=\"card-iframe\"\n        src=\"https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1...\"\n        allow=\"clipboard-write\" class=\"content\"></iframe>\n```\n\nYou 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**.\n\n\n### Parameters\n\n- `embed_request: string`\n  A base64 encoded JSON string of an EmbedRequest to specify which card to load.\n\n- `hmac: string`\n  SHA256 HMAC of the embed_request JSON string with base64 digest.\n\n### Returns\n\n- `string`\n\n### Example\n\n```typescript\nimport Lithic from 'lithic';\n\nconst client = new Lithic();\n\nconst response = await client.cards.embed({ embed_request: 'embed_request', hmac: 'hmac' });\n\nconsole.log(response);\n```",
+      "## embed\n\n`client.cards.embed(embed_request: string, hmac: string): string`\n\n**get** `/v1/embed/card`\n\n**Deprecated.** Use the modern embedded card flow instead: create a session with `POST /v1/cards/{card_token}/embed` and render it via `GET /v1/embed`.\n\nHandling 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.\n\nIn 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 (see Embedded Card UI or Changelog for upcoming changes in January). This means that the url for the request can be inserted straight into the `src` attribute of an iframe.\n\n```html\n<iframe id=\"card-iframe\"\n        src=\"https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1...\"\n        allow=\"clipboard-write\" class=\"content\"></iframe>\n```\n\nYou 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**.\n\n\n### Parameters\n\n- `embed_request: string`\n  A base64 encoded JSON string of an EmbedRequest to specify which card to load.\n\n- `hmac: string`\n  SHA256 HMAC of the embed_request JSON string with base64 digest.\n\n### Returns\n\n- `string`\n\n### Example\n\n```typescript\nimport Lithic from 'lithic';\n\nconst client = new Lithic();\n\nconst response = await client.cards.embed({ embed_request: 'embed_request', hmac: 'hmac' });\n\nconsole.log(response);\n```",
     perLanguage: {
       typescript: {
         method: 'client.cards.embed',

src/client.ts

@@ -225,6 +225,8 @@ import {
   DisputeTransactionCreatedWebhookEvent,
   DisputeTransactionUpdatedWebhookEvent,
   DisputeUpdatedWebhookEvent,
+  EmbedSessionGeneratedWebhookEvent,
+  EmbedViewedWebhookEvent,
   ExternalBankAccountCreatedWebhookEvent,
   ExternalBankAccountUpdatedWebhookEvent,
   ExternalPaymentCreatedWebhookEvent,
@@ -1623,6 +1625,8 @@ export declare namespace Lithic {
     type DigitalWalletTokenizationUpdatedWebhookEvent as DigitalWalletTokenizationUpdatedWebhookEvent,
     type DisputeUpdatedWebhookEvent as DisputeUpdatedWebhookEvent,
     type DisputeEvidenceUploadFailedWebhookEvent as DisputeEvidenceUploadFailedWebhookEvent,
+    type EmbedSessionGeneratedWebhookEvent as EmbedSessionGeneratedWebhookEvent,
+    type EmbedViewedWebhookEvent as EmbedViewedWebhookEvent,
     type ExternalBankAccountCreatedWebhookEvent as ExternalBankAccountCreatedWebhookEvent,
     type ExternalBankAccountUpdatedWebhookEvent as ExternalBankAccountUpdatedWebhookEvent,
     type ExternalPaymentCreatedWebhookEvent as ExternalPaymentCreatedWebhookEvent,

src/resources/cards/cards.ts

@@ -151,6 +151,9 @@ export class Cards extends APIResource {
   }
 
   /**
+   * **Deprecated.** Use the modern embedded card flow instead: create a session with
+   * `POST /v1/cards/{card_token}/embed` and render it via `GET /v1/embed`.
+   *
    * 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
@@ -179,13 +182,7 @@ export class Cards extends APIResource {
    * but **do not ever embed your API key into front end code, as doing so introduces
    * a serious security vulnerability**.
    *
-   * @example
-   * ```ts
-   * const response = await client.cards.embed({
-   *   embed_request: 'embed_request',
-   *   hmac: 'hmac',
-   * });
-   * ```
+   * @deprecated
    */
   embed(query: CardEmbedParams, options?: RequestOptions): APIPromise<string> {
     return this._client.get('/v1/embed/card', {

src/resources/events/events.ts

@@ -177,6 +177,10 @@ export interface Event {
    * This event is not emitted for Managed Disputes. Use
    * `dispute_transaction.created` and `dispute_transaction.updated` instead.
    *
+   * - embed.session_generated: Occurs when a card embed session is successfully
+   *   generated.
+   * - embed.viewed: Occurs when a card detail is successfully revealed through an
+   *   embed.
    * - external_bank_account.created: Occurs when an external bank account is
    *   created.
    * - external_bank_account.updated: Occurs when an external bank account is
@@ -253,6 +257,8 @@ export interface Event {
     | 'dispute_transaction.created'
     | 'dispute_transaction.updated'
     | 'dispute.updated'
+    | 'embed.session_generated'
+    | 'embed.viewed'
     | 'external_bank_account.created'
     | 'external_bank_account.updated'
     | 'external_payment.created'
@@ -338,6 +344,8 @@ export interface EventSubscription {
     | 'dispute_transaction.created'
     | 'dispute_transaction.updated'
     | 'dispute.updated'
+    | 'embed.session_generated'
+    | 'embed.viewed'
     | 'external_bank_account.created'
     | 'external_bank_account.updated'
     | 'external_payment.created'
@@ -461,6 +469,8 @@ export interface EventListParams extends CursorPageParams {
     | 'dispute_transaction.created'
     | 'dispute_transaction.updated'
     | 'dispute.updated'
+    | 'embed.session_generated'
+    | 'embed.viewed'
     | 'external_bank_account.created'
     | 'external_bank_account.updated'
     | 'external_payment.created'

src/resources/events/subscriptions.ts

@@ -199,6 +199,8 @@ export interface SubscriptionCreateParams {
     | 'dispute_transaction.created'
     | 'dispute_transaction.updated'
     | 'dispute.updated'
+    | 'embed.session_generated'
+    | 'embed.viewed'
     | 'external_bank_account.created'
     | 'external_bank_account.updated'
     | 'external_payment.created'
@@ -282,6 +284,8 @@ export interface SubscriptionUpdateParams {
     | 'dispute_transaction.created'
     | 'dispute_transaction.updated'
     | 'dispute.updated'
+    | 'embed.session_generated'
+    | 'embed.viewed'
     | 'external_bank_account.created'
     | 'external_bank_account.updated'
     | 'external_payment.created'
@@ -395,6 +399,8 @@ export interface SubscriptionSendSimulatedExampleParams {
     | 'dispute_transaction.created'
     | 'dispute_transaction.updated'
     | 'dispute.updated'
+    | 'embed.session_generated'
+    | 'embed.viewed'
     | 'external_bank_account.created'
     | 'external_bank_account.updated'
     | 'external_payment.created'

src/resources/index.ts

@@ -333,6 +333,8 @@ export {
   type DigitalWalletTokenizationUpdatedWebhookEvent,
   type DisputeUpdatedWebhookEvent,
   type DisputeEvidenceUploadFailedWebhookEvent,
+  type EmbedSessionGeneratedWebhookEvent,
+  type EmbedViewedWebhookEvent,
   type ExternalBankAccountCreatedWebhookEvent,
   type ExternalBankAccountUpdatedWebhookEvent,
   type ExternalPaymentCreatedWebhookEvent,

src/resources/webhooks.ts

@@ -1765,6 +1765,94 @@ export interface DisputeEvidenceUploadFailedWebhookEvent extends DisputesAPI.Dis
   event_type: 'dispute_evidence.upload_failed';
 }
 
+export interface EmbedSessionGeneratedWebhookEvent {
+  /**
+   * The token of the account associated with the card
+   */
+  account_token: string;
+
+  /**
+   * The token of the card associated with the embed session
+   */
+  card_token: string;
+
+  /**
+   * Details about the request that generated the embed session
+   */
+  device_details: EmbedSessionGeneratedWebhookEvent.DeviceDetails;
+
+  /**
+   * The type of event
+   */
+  event_type: 'embed.session_generated';
+
+  /**
+   * The identifier shared by webhook events for the same embed session.
+   */
+  session_id: string;
+
+  /**
+   * The type of embed session that was generated
+   */
+  session_type: 'CARD_EMBED' | 'PIN_SETTING_EMBED';
+}
+
+export namespace EmbedSessionGeneratedWebhookEvent {
+  /**
+   * Details about the request that generated the embed session
+   */
+  export interface DeviceDetails {
+    /**
+     * The IP address recorded for the request that generated the event
+     */
+    ip_address: string;
+  }
+}
+
+export interface EmbedViewedWebhookEvent {
+  /**
+   * The token of the account associated with the card
+   */
+  account_token: string;
+
+  /**
+   * The token of the card whose details were revealed
+   */
+  card_token: string;
+
+  /**
+   * Details about the request that revealed the card detail
+   */
+  device_details: EmbedViewedWebhookEvent.DeviceDetails;
+
+  /**
+   * The type of card detail that was revealed
+   */
+  embed_type: 'PAN' | 'CVV' | 'EXP_MONTH' | 'EXP_YEAR';
+
+  /**
+   * The type of event
+   */
+  event_type: 'embed.viewed';
+
+  /**
+   * The identifier shared by webhook events for the same embed session.
+   */
+  session_id: string;
+}
+
+export namespace EmbedViewedWebhookEvent {
+  /**
+   * Details about the request that revealed the card detail
+   */
+  export interface DeviceDetails {
+    /**
+     * The IP address recorded for the request that generated the event
+     */
+    ip_address: string;
+  }
+}
+
 export interface ExternalBankAccountCreatedWebhookEvent extends ExternalBankAccountsAPI.ExternalBankAccount {
   /**
    * The type of event that occurred.
@@ -2356,6 +2444,8 @@ export type ParsedWebhookEvent =
   | DigitalWalletTokenizationUpdatedWebhookEvent
   | DisputeUpdatedWebhookEvent
   | DisputeEvidenceUploadFailedWebhookEvent
+  | EmbedSessionGeneratedWebhookEvent
+  | EmbedViewedWebhookEvent
   | ExternalBankAccountCreatedWebhookEvent
   | ExternalBankAccountUpdatedWebhookEvent
   | ExternalPaymentCreatedWebhookEvent
@@ -2842,6 +2932,8 @@ export declare namespace Webhooks {
     type DigitalWalletTokenizationUpdatedWebhookEvent as DigitalWalletTokenizationUpdatedWebhookEvent,
     type DisputeUpdatedWebhookEvent as DisputeUpdatedWebhookEvent,
     type DisputeEvidenceUploadFailedWebhookEvent as DisputeEvidenceUploadFailedWebhookEvent,
+    type EmbedSessionGeneratedWebhookEvent as EmbedSessionGeneratedWebhookEvent,
+    type EmbedViewedWebhookEvent as EmbedViewedWebhookEvent,
     type ExternalBankAccountCreatedWebhookEvent as ExternalBankAccountCreatedWebhookEvent,
     type ExternalBankAccountUpdatedWebhookEvent as ExternalBankAccountUpdatedWebhookEvent,
     type ExternalPaymentCreatedWebhookEvent as ExternalPaymentCreatedWebhookEvent,