perata-sdk 0.1.1

data/lib/perata/params.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+module Perata
+  # The body of checkouts:create.
+  class CheckoutsCreateParams < Params
+    MEMBERS = %i[cancel_url label price_id product_id quantity success_url].freeze
+
+    # @return [String, nil]
+    attr_reader :cancel_url
+
+    # @return [String, nil]
+    attr_reader :label
+
+    # @return [String]
+    attr_reader :price_id
+
+    # @return [String]
+    attr_reader :product_id
+
+    # @return [Integer, nil]
+    attr_reader :quantity
+
+    # @return [String, nil]
+    attr_reader :success_url
+
+    def initialize(cancel_url: nil, label: nil, price_id:, product_id:, quantity: nil, success_url: nil)
+      @cancel_url = cancel_url
+      @label = label
+      @price_id = price_id
+      @product_id = product_id
+      @quantity = quantity
+      @success_url = success_url
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["cancel_url"] = @cancel_url unless @cancel_url.nil?
+      wire["label"] = @label unless @label.nil?
+      wire["price_id"] = @price_id
+      wire["product_id"] = @product_id
+      wire["quantity"] = @quantity unless @quantity.nil?
+      wire["success_url"] = @success_url unless @success_url.nil?
+      wire
+    end
+  end
+
+  # The body of customers:create.
+  class CustomersCreateParams < Params
+    MEMBERS = %i[email external_id name].freeze
+
+    # @return [String]
+    attr_reader :email
+
+    # @return [String, nil]
+    attr_reader :external_id
+
+    # @return [String]
+    attr_reader :name
+
+    def initialize(email:, external_id: nil, name:)
+      @email = email
+      @external_id = external_id
+      @name = name
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["email"] = @email
+      wire["external_id"] = @external_id unless @external_id.nil?
+      wire["name"] = @name
+      wire
+    end
+  end
+
+  # The body of prices:create.
+  class PricesCreateParams < Params
+    MEMBERS = %i[amount_cents interval product_id type].freeze
+
+    # @return [Integer]
+    attr_reader :amount_cents
+
+    # @return [String ("month", "year"), nil]
+    attr_reader :interval
+
+    # @return [String]
+    attr_reader :product_id
+
+    # @return [String ("one_time", "recurring")]
+    attr_reader :type
+
+    def initialize(amount_cents:, interval: nil, product_id:, type:)
+      @amount_cents = amount_cents
+      @interval = interval
+      @product_id = product_id
+      @type = type
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["amount_cents"] = @amount_cents
+      wire["interval"] = @interval unless @interval.nil?
+      wire["product_id"] = @product_id
+      wire["type"] = @type
+      wire
+    end
+  end
+
+  # The body of products:create.
+  class ProductsCreateParams < Params
+    MEMBERS = %i[description name].freeze
+
+    # @return [String, nil]
+    attr_reader :description
+
+    # @return [String]
+    attr_reader :name
+
+    def initialize(description: nil, name:)
+      @description = description
+      @name = name
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["description"] = @description unless @description.nil?
+      wire["name"] = @name
+      wire
+    end
+  end
+
+  # The body of refunds:create.
+  class RefundsCreateParams < Params
+    MEMBERS = %i[amount_cents note payment_id reason].freeze
+
+    # @return [Integer]
+    attr_reader :amount_cents
+
+    # @return [String, nil]
+    attr_reader :note
+
+    # @return [String]
+    attr_reader :payment_id
+
+    # @return [String ("requested_by_customer", "duplicate", "fraudulent", "product_unavailable", "service_disruption", "other")]
+    attr_reader :reason
+
+    def initialize(amount_cents:, note: nil, payment_id:, reason:)
+      @amount_cents = amount_cents
+      @note = note
+      @payment_id = payment_id
+      @reason = reason
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["amount_cents"] = @amount_cents
+      wire["note"] = @note unless @note.nil?
+      wire["payment_id"] = @payment_id
+      wire["reason"] = @reason
+      wire
+    end
+  end
+
+  # The body of subscriptions:cancel.
+  class SubscriptionsCancelParams < Params
+    MEMBERS = %i[at_period_end reason].freeze
+
+    # @return [Boolean, nil]
+    attr_reader :at_period_end
+
+    # @return [String, nil]
+    attr_reader :reason
+
+    def initialize(at_period_end: nil, reason: nil)
+      @at_period_end = at_period_end
+      @reason = reason
+      freeze
+    end
+
+    # The body as the API reads it.
+    def to_wire
+      wire = {}
+      wire["at_period_end"] = @at_period_end unless @at_period_end.nil?
+      wire["reason"] = @reason unless @reason.nil?
+      wire
+    end
+  end
+end

data/lib/perata/services.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+module Perata
+  # The API's checkouts.
+  class CheckoutsService
+    def initialize(client)
+      @client = client
+    end
+
+    # Create a checkout address for one product and price.
+    #
+    # @param params [CheckoutsCreateParams, Hash]
+    # @return [Checkout]
+    def create(params, idempotency_key: nil, api_key: nil)
+      data = @client.request("POST", "/api/v1/checkouts", body: CheckoutsCreateParams.coerce(params).to_wire, idempotency_key: idempotency_key, api_key: api_key)
+      Checkout.from_hash(data)
+    end
+  end
+
+  # The API's customers.
+  class CustomersService
+    def initialize(client)
+      @client = client
+    end
+
+    # Create a customer.
+    #
+    # @param params [CustomersCreateParams, Hash]
+    # @return [Customer]
+    def create(params, idempotency_key: nil, api_key: nil)
+      data = @client.request("POST", "/api/v1/customers", body: CustomersCreateParams.coerce(params).to_wire, idempotency_key: idempotency_key, api_key: api_key)
+      Customer.from_hash(data)
+    end
+
+    # Read a customer.
+    #
+    # @return [Customer]
+    def get(customer, api_key: nil)
+      data = @client.request("GET", "/api/v1/customers/#{Perata.segment(customer)}", api_key: api_key)
+      Customer.from_hash(data)
+    end
+
+    # List customers. One page; +list_iter+ walks every page.
+    #
+    # @return [Page<Customer>]
+    def list(page: nil, limit: nil, api_key: nil)
+      query = { "page" => page, "limit" => limit }
+      data = @client.request("GET", "/api/v1/customers", query: query, api_key: api_key)
+      Page.from_hash(data) { |item| Customer.from_hash(item) }
+    end
+
+    # Walks every page of customers:list from +page+, item by item.
+    #
+    # @return [Enumerator<Customer>]
+    def list_iter(page: nil, limit: nil, api_key: nil, &block)
+      items = Page.iterate(page) do |at|
+        list(page: at, limit: limit, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+
+  # The API's orders.
+  class OrdersService
+    def initialize(client)
+      @client = client
+    end
+
+    # List orders: paid checkouts. One page; +list_iter+ walks every page.
+    #
+    # @return [Page<Order>]
+    def list(page: nil, limit: nil, api_key: nil)
+      query = { "page" => page, "limit" => limit }
+      data = @client.request("GET", "/api/v1/orders", query: query, api_key: api_key)
+      Page.from_hash(data) { |item| Order.from_hash(item) }
+    end
+
+    # Walks every page of orders:list from +page+, item by item.
+    #
+    # @return [Enumerator<Order>]
+    def list_iter(page: nil, limit: nil, api_key: nil, &block)
+      items = Page.iterate(page) do |at|
+        list(page: at, limit: limit, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+
+  # The API's payment_methods.
+  class PaymentMethodsService
+    def initialize(client)
+      @client = client
+    end
+
+    # Stop charging a stored card; refused while an active subscription charges it.
+    #
+    # @return [PaymentMethodDetached]
+    def detach(payment_method, idempotency_key: nil, api_key: nil)
+      data = @client.request("POST", "/api/v1/payment_methods/#{Perata.segment(payment_method)}/detach", idempotency_key: idempotency_key, api_key: api_key)
+      PaymentMethodDetached.from_hash(data)
+    end
+
+    # List a customer's stored cards: brand, last four digits and expiry. One page; +list_iter+ walks every page.
+    #
+    # @return [Page<PaymentMethod>]
+    def list(customer, page: nil, limit: nil, api_key: nil)
+      query = { "page" => page, "limit" => limit }
+      data = @client.request("GET", "/api/v1/customers/#{Perata.segment(customer)}/payment_methods", query: query, api_key: api_key)
+      Page.from_hash(data) { |item| PaymentMethod.from_hash(item) }
+    end
+
+    # Walks every page of payment_methods:list from +page+, item by item.
+    #
+    # @return [Enumerator<PaymentMethod>]
+    def list_iter(customer, page: nil, limit: nil, api_key: nil, &block)
+      items = Page.iterate(page) do |at|
+        list(customer, page: at, limit: limit, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+
+  # The API's payments.
+  class PaymentsService
+    def initialize(client)
+      @client = client
+    end
+
+    # Read a payment.
+    #
+    # @return [Payment]
+    def get(payment, api_key: nil)
+      data = @client.request("GET", "/api/v1/payments/#{Perata.segment(payment)}", api_key: api_key)
+      Payment.from_hash(data)
+    end
+
+    # List payments. One page; +list_iter+ walks every page.
+    #
+    # @return [Page<Payment>]
+    def list(page: nil, limit: nil, api_key: nil)
+      query = { "page" => page, "limit" => limit }
+      data = @client.request("GET", "/api/v1/payments", query: query, api_key: api_key)
+      Page.from_hash(data) { |item| Payment.from_hash(item) }
+    end
+
+    # Walks every page of payments:list from +page+, item by item.
+    #
+    # @return [Enumerator<Payment>]
+    def list_iter(page: nil, limit: nil, api_key: nil, &block)
+      items = Page.iterate(page) do |at|
+        list(page: at, limit: limit, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+
+  # The API's prices.
+  class PricesService
+    def initialize(client)
+      @client = client
+    end
+
+    # Create a BRL price, one-time or recurring.
+    #
+    # @param params [PricesCreateParams, Hash]
+    # @return [Price]
+    def create(params, idempotency_key: nil, api_key: nil)
+      data = @client.request("POST", "/api/v1/prices", body: PricesCreateParams.coerce(params).to_wire, idempotency_key: idempotency_key, api_key: api_key)
+      Price.from_hash(data)
+    end
+
+    # List prices, optionally of one product (product_id). One page; +list_iter+ walks every page.
+    #
+    # @return [Page<Price>]
+    def list(page: nil, limit: nil, product_id: nil, api_key: nil)
+      query = { "page" => page, "limit" => limit, "product_id" => product_id }
+      data = @client.request("GET", "/api/v1/prices", query: query, api_key: api_key)
+      Page.from_hash(data) { |item| Price.from_hash(item) }
+    end
+
+    # Walks every page of prices:list from +page+, item by item.
+    #
+    # @return [Enumerator<Price>]
+    def list_iter(page: nil, limit: nil, product_id: nil, api_key: nil, &block)
+      items = Page.iterate(page) do |at|
+        list(page: at, limit: limit, product_id: product_id, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+
+  # The API's products.
+  class ProductsService
+    def initialize(client)
+      @client = client
+    end
+
+    # Create a product.
+    #
+    # @param params [ProductsCreateParams, Hash]
+    # @return [Product]
+    def create(params, idempotency_key: nil, api_key: nil)
+      data = @client.request("POST", "/api/v1/products", body: ProductsCreateParams.coerce(params).to_wire, idempotency_key: idempotency_key, api_key: api_key)
+      Product.from_hash(data)
+    end
+
+    # Read a product.
+    #
+    # @return [Product]
+    def get(product, api_key: nil)
+      data = @client.request("GET", "/api/v1/products/#{Perata.segment(product)}", api_key: api_key)
+      Product.from_hash(data)
+    end
+
+    # List products. One page; +list_iter+ walks every page.
+    #
+    # @return [Page<Product>]
+    def list(page: nil, limit: nil, api_key: nil)
+      query = { "page" => page, "limit" => limit }
+      data = @client.request("GET", "/api/v1/products", query: query, api_key: api_key)
+      Page.from_hash(data) { |item| Product.from_hash(item) }
+    end
+
+    # Walks every page of products:list from +page+, item by item.
+    #
+    # @return [Enumerator<Product>]
+    def list_iter(page: nil, limit: nil, api_key: nil, &block)
+      items = Page.iterate(page) do |at|
+        list(page: at, limit: limit, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+
+  # The API's refunds.
+  class RefundsService
+    def initialize(client)
+      @client = client
+    end
+
+    # Refund part or all of a payment.
+    #
+    # @param params [RefundsCreateParams, Hash]
+    # @return [Refund]
+    def create(params, idempotency_key: nil, api_key: nil)
+      data = @client.request("POST", "/api/v1/refunds", body: RefundsCreateParams.coerce(params).to_wire, idempotency_key: idempotency_key, api_key: api_key)
+      Refund.from_hash(data)
+    end
+  end
+
+  # The API's subscriptions.
+  class SubscriptionsService
+    def initialize(client)
+      @client = client
+    end
+
+    # Cancel a subscription, by default at the end of its period.
+    #
+    # @param params [SubscriptionsCancelParams, Hash]
+    # @return [Subscription]
+    def cancel(subscription, params, idempotency_key: nil, api_key: nil)
+      data = @client.request("POST", "/api/v1/subscriptions/#{Perata.segment(subscription)}/cancel", body: SubscriptionsCancelParams.coerce(params).to_wire, idempotency_key: idempotency_key, api_key: api_key)
+      Subscription.from_hash(data)
+    end
+
+    # Read a subscription.
+    #
+    # @return [Subscription]
+    def get(subscription, api_key: nil)
+      data = @client.request("GET", "/api/v1/subscriptions/#{Perata.segment(subscription)}", api_key: api_key)
+      Subscription.from_hash(data)
+    end
+
+    # List subscriptions, optionally of one customer (customer_id). One page; +list_iter+ walks every page.
+    #
+    # @return [Page<Subscription>]
+    def list(page: nil, limit: nil, customer_id: nil, api_key: nil)
+      query = { "page" => page, "limit" => limit, "customer_id" => customer_id }
+      data = @client.request("GET", "/api/v1/subscriptions", query: query, api_key: api_key)
+      Page.from_hash(data) { |item| Subscription.from_hash(item) }
+    end
+
+    # Walks every page of subscriptions:list from +page+, item by item.
+    #
+    # @return [Enumerator<Subscription>]
+    def list_iter(page: nil, limit: nil, customer_id: nil, api_key: nil, &block)
+      items = Page.iterate(page) do |at|
+        list(page: at, limit: limit, customer_id: customer_id, api_key: api_key)
+      end
+      block ? items.each(&block) : items
+    end
+  end
+end

data/lib/perata/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+module Perata
+  # This SDK's version.
+  VERSION = "0.1.1"
+
+  # The contract this SDK was generated from.
+  API_VERSION = "0.1.0"
+
+  # Peráta's API. The environment, test or live, is the API key's: prk_test_…
+  # or prk_live_….
+  DEFAULT_BASE_URL = "https://perata.sh"
+end

data/lib/perata/webhooks.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+# Verifying the webhooks Peráta sends, as Standard Webhooks signs them.
+module Perata
+  # How far from now a webhook's timestamp may be, in seconds.
+  WEBHOOK_TOLERANCE_SECONDS = 300
+
+  # A request Peráta did not sign, or signed too long ago.
+  class WebhookVerificationError < StandardError
+    def initialize(message = "perata: webhook signature does not verify")
+      super
+    end
+  end
+
+  # What Peráta posts to an endpoint.
+  class WebhookEvent < Model
+    MEMBERS = %i[id type timestamp data].freeze
+
+    # @return [String]
+    attr_reader :id, :type, :timestamp
+    # @return [Hash{String => String}]
+    attr_reader :data
+
+    def initialize(id:, type:, timestamp:, data:)
+      @id = id
+      @type = type
+      @timestamp = timestamp
+      @data = data
+      freeze
+    end
+  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.
+  #
+  # @return [WebhookEvent]
+  # @raise [WebhookVerificationError]
+  def self.verify_webhook(secret, headers, body, now: Time.now)
+    key = begin
+      secret.delete_prefix("whsec_").unpack1("m0")
+    rescue ArgumentError
+      ""
+    end
+    raise ArgumentError, "perata: the webhook secret is whsec_ and a base64 key" if key.empty?
+
+    raw = body.to_s.b
+    webhook_id = webhook_header(headers, "webhook-id")
+    stamp = webhook_header(headers, "webhook-timestamp")
+    raise WebhookVerificationError if webhook_id.empty? || !stamp.match?(/\A\d+\z/)
+    raise WebhookVerificationError if (now.to_i - stamp.to_i).abs > WEBHOOK_TOLERANCE_SECONDS
+
+    expected = OpenSSL::HMAC.digest("SHA256", key, "#{webhook_id}.#{stamp}.".b + raw)
+    webhook_header(headers, "webhook-signature").split.each do |signature|
+      version, encoded = signature.split(",", 2)
+      next unless version == "v1" && encoded
+
+      decoded = begin
+        encoded.unpack1("m0")
+      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"] || {})
+    end
+    raise WebhookVerificationError
+  end
+
+  # 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)
+    headers.each do |key, value|
+      return value.to_s if key.to_s.downcase.tr("_", "-").delete_prefix("http-") == name
+    end
+    ""
+  end
+  private_class_method :webhook_header
+end

data/lib/perata.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Code generated by sdk/generator. DO NOT EDIT.
+
+# Peráta's SDK for Ruby, generated from Peráta's API contract.
+#
+#   perata = Perata::Client.new(ENV.fetch("PERATA_API_KEY"))
+#   product = perata.products.create({ name: "Curso" }, idempotency_key: "produto-curso")
+#   perata.products.list_iter.each { |product| puts product.name }
+module Perata
+  # A path parameter, escaped.
+  def self.segment(value)
+    value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/) { |char| format("%%%02X", char.ord) }
+  end
+
+  # A value as JSON writes it: params and models as hashes, lists and maps of
+  # them walked.
+  def self.wire(value)
+    case value
+    when Params then value.to_wire
+    when Model then value.to_h.transform_keys(&:to_s).transform_values { |each| wire(each) }
+    when Array then value.map { |each| wire(each) }
+    when Hash then value.transform_values { |each| wire(each) }
+    else value
+    end
+  end
+end
+
+require_relative "perata/version"
+require_relative "perata/error"
+require_relative "perata/model"
+require_relative "perata/models"
+require_relative "perata/params"
+require_relative "perata/page"
+require_relative "perata/services"
+require_relative "perata/client"
+require_relative "perata/webhooks"

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: perata-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Peráta
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/perata.rb
+- lib/perata/client.rb
+- lib/perata/error.rb
+- lib/perata/model.rb
+- lib/perata/models.rb
+- lib/perata/page.rb
+- lib/perata/params.rb
+- lib/perata/services.rb
+- lib/perata/version.rb
+- lib/perata/webhooks.rb
+homepage: https://perata.sh
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://perata.sh
+  source_code_uri: https://github.com/perata-sh/sdk
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Peráta''s SDK for Ruby: products, customers, checkouts, payments, subscriptions
+  and webhooks.'
+test_files: []