perata-sdk 0.1.1 → 0.3.0

data/lib/perata/version.rb

@@ -4,7 +4,7 @@
 
 module Perata
   # This SDK's version.
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 
   # The contract this SDK was generated from.
   API_VERSION = "0.1.0"

data/lib/perata/webhooks.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Code generated by sdk/generator. DO NOT EDIT.
+
 require "json"
 require "openssl"
 
@@ -15,13 +17,19 @@ module Perata
     end
   end
 
-  # What Peráta posts to an endpoint.
+  # A webhook Peráta sent, verified: one subclass a kind of data
+  # (OrderWebhookEvent carries an Order…), or UnknownWebhookEvent for a type
+  # this SDK does not know yet. Within a class, +type+ says what happened.
   class WebhookEvent < Model
     MEMBERS = %i[id type timestamp data].freeze
 
-    # @return [String]
-    attr_reader :id, :type, :timestamp
-    # @return [Hash{String => String}]
+    # @return [String] the message's id, the same as the webhook-id header
+    attr_reader :id
+    # @return [String] what happened: order.paid…
+    attr_reader :type
+    # @return [String] when it happened, in RFC 3339
+    attr_reader :timestamp
+    # @return [Object] what the event carries
     attr_reader :data
 
     def initialize(id:, type:, timestamp:, data:)
@@ -33,16 +41,86 @@ module Perata
     end
   end
 
+  # The events that carry a WebhookBenefit; +data+ is WebhookBenefit.
+  class BenefitWebhookEvent < WebhookEvent
+    TYPES = %w[benefit.created benefit.updated].freeze
+  end
+
+  # The events that carry a BenefitGrant; +data+ is BenefitGrant.
+  class BenefitGrantWebhookEvent < WebhookEvent
+    TYPES = %w[benefit_grant.created benefit_grant.revoked benefit_grant.updated].freeze
+  end
+
+  # The events that carry a WebhookCheckout; +data+ is WebhookCheckout.
+  class CheckoutWebhookEvent < WebhookEvent
+    TYPES = %w[checkout.created checkout.expired checkout.updated].freeze
+  end
+
+  # The events that carry a Customer; +data+ is Customer.
+  class CustomerWebhookEvent < WebhookEvent
+    TYPES = %w[customer.created customer.deleted customer.updated].freeze
+  end
+
+  # The events that carry a WebhookDiscount; +data+ is WebhookDiscount.
+  class DiscountWebhookEvent < WebhookEvent
+    TYPES = %w[discount.created discount.deleted discount.updated].freeze
+  end
+
+  # The events that carry a WebhookDispute; +data+ is WebhookDispute.
+  class DisputeWebhookEvent < WebhookEvent
+    TYPES = %w[dispute.lost dispute.opened dispute.won].freeze
+  end
+
+  # The events that carry the event's identifiers; +data+ is Hash{String => String}.
+  class IdentifiersWebhookEvent < WebhookEvent
+    TYPES = %w[benefit.archived benefit.version_created benefit_product_link.linked benefit_product_link.unlinked checkout_link.archived checkout_link.created checkout_payment.authorized checkout_payment.canceled checkout_payment.captured checkout_payment.partially_refunded checkout_payment.refunded checkout_payment.refused checkout_session.confirmed checkout_session.expired checkout_session.failed checkout_session.opened checkout_session.succeeded customer.archived discount.exhausted discount.expired discount.reactivated discount.redeemed discount_redemption.released invoice.drafted invoice.issued invoice.settled invoice.uncollectible invoice.voided price.archived price.created product.archived refund.canceled refund.failed refund.requested refund.succeeded seat_allocation.opened seat_allocation.resized seat_assignment.claimed seat_assignment.invited seat_assignment.revoked usage_event.recorded usage_period.closed usage_period.opened usage_period_adjustment.created].freeze
+  end
+
+  # The events that carry an Order; +data+ is Order.
+  class OrderWebhookEvent < WebhookEvent
+    TYPES = %w[order.created order.paid order.refunded order.updated].freeze
+  end
+
+  # The events that carry a Product; +data+ is Product.
+  class ProductWebhookEvent < WebhookEvent
+    TYPES = %w[product.created product.updated].freeze
+  end
+
+  # The events that carry a Refund; +data+ is Refund.
+  class RefundWebhookEvent < WebhookEvent
+    TYPES = %w[refund.created refund.updated].freeze
+  end
+
+  # The events that carry a Subscription; +data+ is Subscription.
+  class SubscriptionWebhookEvent < WebhookEvent
+    TYPES = %w[subscription.active subscription.canceled subscription.created subscription.cycled subscription.past_due subscription.paused subscription.resumed subscription.revoked subscription.uncanceled subscription.updated].freeze
+  end
+
+  # An event of a type this SDK does not know yet, its data as it was sent.
+  class UnknownWebhookEvent < WebhookEvent
+  end
+
   # Checks a webhook Peráta sent and answers its event.
   #
   # The signature is an HMAC-SHA256 of +{webhook-id}.{webhook-timestamp}.{body}+
-  # under the key the endpoint's +whsec_+ secret encodes. Pass the body exactly
-  # as it arrived, before parsing it; +headers+ is a hash of the request's
-  # headers, in any case, or a Rack env.
+  # under the key the endpoint's +whsec_+ secret encodes, one of the signatures
+  # in the +webhook-signature+ header, which carries more than one while a
+  # secret is rotated. Pass the body exactly as it arrived, before parsing it;
+  # +headers+ is a hash of the request's headers, in any case, or a Rack env.
   #
   # @return [WebhookEvent]
   # @raise [WebhookVerificationError]
   def self.verify_webhook(secret, headers, body, now: Time.now)
+    verify_webhook_signature(secret, headers, body, now: now)
+    webhook_event(body.to_s.b.force_encoding(Encoding::UTF_8))
+  end
+
+  # Checks a webhook's signature as verify_webhook does, without reading its
+  # body.
+  #
+  # @return [nil]
+  # @raise [WebhookVerificationError]
+  def self.verify_webhook_signature(secret, headers, body, now: Time.now)
     key = begin
       secret.delete_prefix("whsec_").unpack1("m0")
     rescue ArgumentError
@@ -66,15 +144,33 @@ module Perata
       rescue ArgumentError
         next
       end
-      next unless decoded.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(decoded, expected)
-
-      event = JSON.parse(raw.force_encoding(Encoding::UTF_8))
-      return WebhookEvent.new(id: event.fetch("id"), type: event.fetch("type"), timestamp: event.fetch("timestamp"),
-                              data: event["data"] || {})
+      return nil if decoded.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(decoded, expected)
     end
     raise WebhookVerificationError
   end
 
+  # A verified body as the event its type names.
+  def self.webhook_event(raw)
+    event = JSON.parse(raw)
+    data = event["data"] || {}
+    message = { id: event.fetch("id"), type: event.fetch("type"), timestamp: event.fetch("timestamp") }
+    case message[:type]
+    when *BenefitWebhookEvent::TYPES then BenefitWebhookEvent.new(**message, data: WebhookBenefit.from_hash(data))
+    when *BenefitGrantWebhookEvent::TYPES then BenefitGrantWebhookEvent.new(**message, data: BenefitGrant.from_hash(data))
+    when *CheckoutWebhookEvent::TYPES then CheckoutWebhookEvent.new(**message, data: WebhookCheckout.from_hash(data))
+    when *CustomerWebhookEvent::TYPES then CustomerWebhookEvent.new(**message, data: Customer.from_hash(data))
+    when *DiscountWebhookEvent::TYPES then DiscountWebhookEvent.new(**message, data: WebhookDiscount.from_hash(data))
+    when *DisputeWebhookEvent::TYPES then DisputeWebhookEvent.new(**message, data: WebhookDispute.from_hash(data))
+    when *IdentifiersWebhookEvent::TYPES then IdentifiersWebhookEvent.new(**message, data: data)
+    when *OrderWebhookEvent::TYPES then OrderWebhookEvent.new(**message, data: Order.from_hash(data))
+    when *ProductWebhookEvent::TYPES then ProductWebhookEvent.new(**message, data: Product.from_hash(data))
+    when *RefundWebhookEvent::TYPES then RefundWebhookEvent.new(**message, data: Refund.from_hash(data))
+    when *SubscriptionWebhookEvent::TYPES then SubscriptionWebhookEvent.new(**message, data: Subscription.from_hash(data))
+    else UnknownWebhookEvent.new(**message, data: data)
+    end
+  end
+  private_class_method :webhook_event
+
   # A header's value, looked up in any case; a Rack env's HTTP_WEBHOOK_ID
   # names webhook-id.
   def self.webhook_header(headers, name)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: perata-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Peráta
@@ -45,7 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: 'Peráta''s SDK for Ruby: products, customers, checkouts, payments, subscriptions
   and webhooks.'