lithic 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84dffb32640f09dd777742e8279eb660addc6b5783cf2787b133ec5247e50507
-  data.tar.gz: 75d175963aceb1d75c46f7d2022cba419f4a7df0bb2d01e98dabb21f4f004b98
+  metadata.gz: f8946d1c458ae277f59faee42210befe43f7ad248f2af24d1a96700ace4bffd5
+  data.tar.gz: 7ec367fffbd069f955681d5b3e59328ae0714493739c8d7f6f0291ebfa13315f
 SHA512:
-  metadata.gz: 982807e64981a671609612a7bb9381655301310165373e3d1bdb13387b89dfe6f1dec73099f436fe32d224a7b6417ee949a9b9cafe14869a3125c8ce957c3415
-  data.tar.gz: 9e2231d392a1eb813a3e6a797c1d7625720d84833720deddca711f76ea9316eec61e55c20248d1d6d3b06a746d86a6036a4f59840d8bbecbbe1b3ea222f8b85d
+  metadata.gz: f0ca88aa8c35a14f40e5387407acdf493491c40f5b100bef248632c2d55e5bf2c31bcf9a659f074319b4314a7560819da891a6d8ec58ce50fac2f1726d6997be
+  data.tar.gz: 9a0d64b55815fd2ad4a7e414ba4864e3612f3107e17e2d93609978023d8904df2c7450bb40f8f86efad97e1e7c7b1741a7e6f0c25c03868726cbab89e23f2d6a

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 (2025-12-10)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* **api:** add webhook schemas to SDKs - add parse and parse_unsafe ([c40835b](https://github.com/lithic-com/lithic-ruby/commit/c40835b8afae6973e80baccab4017a99d15b4ac4))
+
+
+### Chores
+
+* replace custom webhook signature verification with standardwebhooks ([c40835b](https://github.com/lithic-com/lithic-ruby/commit/c40835b8afae6973e80baccab4017a99d15b4ac4))
+
 ## 0.1.0 (2025-12-09)
 
 Full Changelog: [v0.1.0-alpha.56...v0.1.0](https://github.com/lithic-com/lithic-ruby/compare/v0.1.0-alpha.56...v0.1.0)

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "lithic", "~> 0.1.0"
+gem "lithic", "~> 0.2.0"
 ```
 
 <!-- x-release-please-end -->
@@ -64,6 +64,41 @@ if page.next_page?
 end
 ```
 
+### Webhooks
+
+Lithic uses webhooks to notify your application when events happen. The library provides signature verification via the optional `standardwebhooks` gem.
+
+#### Parsing and verifying webhooks
+
+```ruby
+# Verifies signature and returns typed event
+event = lithic.webhooks.parse(
+  request.body.read,
+  headers: request.headers,
+  secret: ENV["LITHIC_WEBHOOK_SECRET"] # optional, reads from env by default
+)
+
+case event
+when Lithic::Models::CardCreatedWebhookEvent
+  puts("Card created: #{event.data.token}")
+end
+```
+
+#### Parsing without verification
+
+```ruby
+# Parse only - skips signature verification (not recommended for production)
+event = lithic.webhooks.parse_unsafe(request.body.read)
+```
+
+#### Installing standardwebhooks (optional)
+
+To use signature verification, install from GitHub:
+
+```ruby
+gem "standardwebhooks", "~> 1.0", github: "standard-webhooks/standard-webhooks", glob: "libraries/ruby/*.gemspec"
+```
+
 ### Handling errors
 
 When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Lithic::Errors::APIError` will be thrown:

data/lib/lithic/client.rb

@@ -119,6 +119,9 @@ module Lithic
     # @return [Lithic::Resources::AccountActivity]
     attr_reader :account_activity
 
+    # @return [Lithic::Resources::Webhooks]
+    attr_reader :webhooks
+
     # Status of api
     #
     # @overload api_status(request_options: {})
@@ -225,6 +228,7 @@ module Lithic
       @fraud = Lithic::Resources::Fraud.new(client: self)
       @network_programs = Lithic::Resources::NetworkPrograms.new(client: self)
       @account_activity = Lithic::Resources::AccountActivity.new(client: self)
+      @webhooks = Lithic::Resources::Webhooks.new(client: self)
     end
   end
 end

data/lib/lithic/errors.rb

@@ -224,5 +224,20 @@ module Lithic
     class InternalServerError < Lithic::Errors::APIStatusError
       HTTP_STATUS = (500..)
     end
+
+    class MissingDependencyError < Lithic::Errors::Error
+      # @api private
+      #
+      # @param gem_name [String]
+      # @param feature [String]
+      def initialize(gem_name:, feature:)
+        message = [
+          "The '#{gem_name}' gem is required to use #{feature}.",
+          "Install it with: gem install #{gem_name}",
+          "Or add it to your Gemfile: gem '#{gem_name}'"
+        ].join("\n")
+        super(message)
+      end
+    end
   end
 end

data/lib/lithic/models/account_holder_created_webhook_event.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Models
+    class AccountHolderCreatedWebhookEvent < Lithic::Internal::Type::BaseModel
+      # @!attribute event_type
+      #   The type of event that occurred.
+      #
+      #   @return [Symbol, :"account_holder.created"]
+      required :event_type, const: :"account_holder.created"
+
+      # @!attribute token
+      #   The token of the account_holder that was created.
+      #
+      #   @return [String, nil]
+      optional :token, String
+
+      # @!attribute account_token
+      #   The token of the account that was created.
+      #
+      #   @return [String, nil]
+      optional :account_token, String
+
+      # @!attribute created
+      #   When the account_holder was created
+      #
+      #   @return [Time, nil]
+      optional :created, Time
+
+      # @!attribute required_documents
+      #
+      #   @return [Array<Lithic::Models::RequiredDocument>, nil]
+      optional :required_documents, -> { Lithic::Internal::Type::ArrayOf[Lithic::RequiredDocument] }
+
+      # @!attribute status
+      #   The status of the account_holder that was created.
+      #
+      #   @return [Symbol, Lithic::Models::AccountHolderCreatedWebhookEvent::Status, nil]
+      optional :status, enum: -> { Lithic::AccountHolderCreatedWebhookEvent::Status }
+
+      # @!attribute status_reason
+      #
+      #   @return [Array<String>, nil]
+      optional :status_reason, Lithic::Internal::Type::ArrayOf[String]
+
+      # @!method initialize(token: nil, account_token: nil, created: nil, required_documents: nil, status: nil, status_reason: nil, event_type: :"account_holder.created")
+      #   @param token [String] The token of the account_holder that was created.
+      #
+      #   @param account_token [String] The token of the account that was created.
+      #
+      #   @param created [Time] When the account_holder was created
+      #
+      #   @param required_documents [Array<Lithic::Models::RequiredDocument>]
+      #
+      #   @param status [Symbol, Lithic::Models::AccountHolderCreatedWebhookEvent::Status] The status of the account_holder that was created.
+      #
+      #   @param status_reason [Array<String>]
+      #
+      #   @param event_type [Symbol, :"account_holder.created"] The type of event that occurred.
+
+      # The status of the account_holder that was created.
+      #
+      # @see Lithic::Models::AccountHolderCreatedWebhookEvent#status
+      module Status
+        extend Lithic::Internal::Type::Enum
+
+        ACCEPTED = :ACCEPTED
+        PENDING_REVIEW = :PENDING_REVIEW
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/lithic/models/account_holder_document_updated_webhook_event.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Lithic
+  module Models
+    class AccountHolderDocumentUpdatedWebhookEvent < Lithic::Internal::Type::BaseModel
+      # @!attribute event_type
+      #   The type of event that occurred.
+      #
+      #   @return [Symbol, :"account_holder_document.updated"]
+      required :event_type, const: :"account_holder_document.updated"
+
+      # @!attribute token
+      #   The token of the account holder document
+      #
+      #   @return [String, nil]
+      optional :token, String
+
+      # @!attribute account_holder_token
+      #   The token of the account_holder that the document belongs to
+      #
+      #   @return [String, nil]
+      optional :account_holder_token, String
+
+      # @!attribute created
+      #   When the account_holder was created
+      #
+      #   @return [Time, nil]
+      optional :created, Time
+
+      # @!attribute document_type
+      #   Type of documentation to be submitted for verification of an account holder
+      #
+      #   @return [Symbol, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::DocumentType, nil]
+      optional :document_type, enum: -> { Lithic::AccountHolderDocumentUpdatedWebhookEvent::DocumentType }
+
+      # @!attribute entity_token
+      #   The token of the entity that the document belongs to
+      #
+      #   @return [String, nil]
+      optional :entity_token, String
+
+      # @!attribute required_document_uploads
+      #
+      #   @return [Array<Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload>, nil]
+      optional :required_document_uploads,
+               -> { Lithic::Internal::Type::ArrayOf[Lithic::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload] }
+
+      # @!method initialize(token: nil, account_holder_token: nil, created: nil, document_type: nil, entity_token: nil, required_document_uploads: nil, event_type: :"account_holder_document.updated")
+      #   @param token [String] The token of the account holder document
+      #
+      #   @param account_holder_token [String] The token of the account_holder that the document belongs to
+      #
+      #   @param created [Time] When the account_holder was created
+      #
+      #   @param document_type [Symbol, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::DocumentType] Type of documentation to be submitted for verification of an account holder
+      #
+      #   @param entity_token [String] The token of the entity that the document belongs to
+      #
+      #   @param required_document_uploads [Array<Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload>]
+      #
+      #   @param event_type [Symbol, :"account_holder_document.updated"] The type of event that occurred.
+
+      # Type of documentation to be submitted for verification of an account holder
+      #
+      # @see Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent#document_type
+      module DocumentType
+        extend Lithic::Internal::Type::Enum
+
+        DRIVERS_LICENSE = :DRIVERS_LICENSE
+        PASSPORT = :PASSPORT
+        PASSPORT_CARD = :PASSPORT_CARD
+        EIN_LETTER = :EIN_LETTER
+        TAX_RETURN = :TAX_RETURN
+        OPERATING_AGREEMENT = :OPERATING_AGREEMENT
+        CERTIFICATE_OF_FORMATION = :CERTIFICATE_OF_FORMATION
+        CERTIFICATE_OF_GOOD_STANDING = :CERTIFICATE_OF_GOOD_STANDING
+        ARTICLES_OF_INCORPORATION = :ARTICLES_OF_INCORPORATION
+        ARTICLES_OF_ORGANIZATION = :ARTICLES_OF_ORGANIZATION
+        BYLAWS = :BYLAWS
+        GOVERNMENT_BUSINESS_LICENSE = :GOVERNMENT_BUSINESS_LICENSE
+        PARTNERSHIP_AGREEMENT = :PARTNERSHIP_AGREEMENT
+        SS4_FORM = :SS4_FORM
+        BANK_STATEMENT = :BANK_STATEMENT
+        UTILITY_BILL_STATEMENT = :UTILITY_BILL_STATEMENT
+        SSN_CARD = :SSN_CARD
+        ITIN_LETTER = :ITIN_LETTER
+        FINCEN_BOI_REPORT = :FINCEN_BOI_REPORT
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      class RequiredDocumentUpload < Lithic::Internal::Type::BaseModel
+        # @!attribute token
+        #   The token of the document upload
+        #
+        #   @return [String, nil]
+        optional :token, String
+
+        # @!attribute accepted_entity_status_reasons
+        #
+        #   @return [Array<String>, nil]
+        optional :accepted_entity_status_reasons, Lithic::Internal::Type::ArrayOf[String]
+
+        # @!attribute created
+        #   When the document upload was created
+        #
+        #   @return [Time, nil]
+        optional :created, Time
+
+        # @!attribute image_type
+        #   The type of image that was uploaded
+        #
+        #   @return [Symbol, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload::ImageType, nil]
+        optional :image_type,
+                 enum: -> { Lithic::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload::ImageType }
+
+        # @!attribute rejected_entity_status_reasons
+        #
+        #   @return [Array<String>, nil]
+        optional :rejected_entity_status_reasons, Lithic::Internal::Type::ArrayOf[String]
+
+        # @!attribute status
+        #   The status of the document upload
+        #
+        #   @return [Symbol, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload::Status, nil]
+        optional :status,
+                 enum: -> { Lithic::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload::Status }
+
+        # @!attribute status_reasons
+        #
+        #   @return [Array<String>, nil]
+        optional :status_reasons, Lithic::Internal::Type::ArrayOf[String]
+
+        # @!attribute updated
+        #   When the document upload was last updated
+        #
+        #   @return [Time, nil]
+        optional :updated, Time
+
+        # @!method initialize(token: nil, accepted_entity_status_reasons: nil, created: nil, image_type: nil, rejected_entity_status_reasons: nil, status: nil, status_reasons: nil, updated: nil)
+        #   A document upload that belongs to the overall account holder document
+        #
+        #   @param token [String] The token of the document upload
+        #
+        #   @param accepted_entity_status_reasons [Array<String>]
+        #
+        #   @param created [Time] When the document upload was created
+        #
+        #   @param image_type [Symbol, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload::ImageType] The type of image that was uploaded
+        #
+        #   @param rejected_entity_status_reasons [Array<String>]
+        #
+        #   @param status [Symbol, Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload::Status] The status of the document upload
+        #
+        #   @param status_reasons [Array<String>]
+        #
+        #   @param updated [Time] When the document upload was last updated
+
+        # The type of image that was uploaded
+        #
+        # @see Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload#image_type
+        module ImageType
+          extend Lithic::Internal::Type::Enum
+
+          FRONT = :FRONT
+          BACK = :BACK
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # The status of the document upload
+        #
+        # @see Lithic::Models::AccountHolderDocumentUpdatedWebhookEvent::RequiredDocumentUpload#status
+        module Status
+          extend Lithic::Internal::Type::Enum
+
+          ACCEPTED = :ACCEPTED
+          REJECTED = :REJECTED
+          PENDING_UPLOAD = :PENDING_UPLOAD
+          UPLOADED = :UPLOADED
+          PARTIAL_APPROVAL = :PARTIAL_APPROVAL
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+  end
+end