paubox 0.3.2 → 1.0.0

data/lib/paubox/dynamic_templates.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Paubox
+  class DynamicTemplates
+
+    attr_accessor :id, :name, :api_customer_id, :body
+    
+    def initialize(args = {})
+      @id = args['id']
+      @name = args['name']
+      @api_customer_id = args['api_customer_id']
+      @body = args['body']
+    end
+
+    def update(template_file_path, template_name = nil)
+      path = "dynamic_templates/#{id}"
+      payload = {
+        data: {
+          name: template_name,
+          body: File.new(template_file_path) 
+        }
+        }
+
+      Paubox::Client.new.send_request(method: :patch, payload: payload, path: path)
+    end
+
+    def delete
+      path = "dynamic_templates/#{id}"
+      Paubox::Client.new.send_request(method: :delete, path: path)
+    end
+
+    class << self
+      def create(template_name, template_file_path)
+        path = "dynamic_templates"
+        payload = {
+          data: {
+            name: template_name,
+            body: File.new(template_file_path) 
+          }
+        }
+        Paubox::Client.new.send_request(method: :post, payload: payload, path: path)
+      end
+
+      def find(template_id)
+        path = "dynamic_templates/#{template_id.to_s}"
+        response = Paubox::Client.new.send_request(method: :get, path: path)
+        data = JSON.parse(response.body)
+        Paubox::DynamicTemplates.new(data)
+      end
+
+      def list
+        path = "dynamic_templates"
+        response = Paubox::Client.new.send_request(method: :get, path: path)
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/paubox/form.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Paubox
+  class Form
+    attr_reader :id, :title, :description, :form_html, :form_json, :form_css,
+                :vanity_url, :version, :active, :customer_id, :signable,
+                :signature_confirmation_label, :submission_count, :type,
+                :deleted, :archived, :created_at, :updated_at,
+                :recipient, :subscription_list_id, :old_form_id
+
+    def initialize(args = {})
+      @id                           = args['id']
+      @title                        = args['title']
+      @description                  = args['description']
+      @form_html                    = args['form_html']
+      @form_json                    = args['form_json']
+      @form_css                     = args['form_css']
+      @vanity_url                   = args['vanity_url']
+      @version                      = args['version']
+      @active                       = args['active']
+      @customer_id                  = args['customer_id']
+      @signable                     = args['signable']
+      @signature_confirmation_label = args['signature_confirmation_label']
+      @submission_count             = args['submission_count']
+      @type                         = args['type']
+      @deleted                      = args['deleted']
+      @archived                     = args['archived']
+      @created_at                   = args['created_at']
+      @updated_at                   = args['updated_at']
+      @recipient                    = args['recipient']
+      @subscription_list_id         = args['subscription_list_id']
+      @old_form_id                  = args['old_form_id']
+    end
+
+    def active?
+      @active
+    end
+
+    def deleted?
+      @deleted
+    end
+
+    def archived?
+      @archived
+    end
+
+    def signable?
+      @signable
+    end
+  end
+end

data/lib/paubox/form_submission.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Paubox
+  class FormSubmission
+    attr_reader :id, :form_id, :form_data, :storage_type, :storage_url,
+                :submitter_email, :recipients, :attachment_name,
+                :attachment_url, :attachment_type, :created_at
+
+    def initialize(args = {})
+      @id              = args['id']
+      @form_id         = args['form_id']
+      @form_data       = parse_form_data(args['form_data'])
+      @storage_type    = args['storage_type']
+      @storage_url     = args['storage_url']
+      @submitter_email = args['submitter_email']
+      @recipients      = args['recipients']
+      @attachment_name = args['attachment_name']
+      @attachment_url  = args['attachment_url']
+      @attachment_type = args['attachment_type']
+      @created_at      = args['created_at']
+    end
+
+    private
+
+    def parse_form_data(form_data)
+      return {} if form_data.nil?
+      return form_data if form_data.is_a?(Hash)
+
+      JSON.parse(form_data)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/paubox/forms_client.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require 'cgi'
+require 'rest-client'
+
+module Paubox
+  class FormsClient
+    FORMS_HOST     = 'api.paubox.com'
+    FORMS_PROTOCOL = 'https://'
+    FORMS_BASE     = '/forms'
+
+    TIMEOUT_SECONDS = 30
+
+    UUID_RE = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+    LIST_FORMS_PARAMS = %i[customer_id form_id search order order_by
+                           archived active page items].freeze
+    LIST_SUBMISSIONS_PARAMS = %i[submission_id order_by order page items].freeze
+
+    # Raised on any non-2xx response from the Forms API. Carries only
+    # status_code / url / response_body so error reporters that capture
+    # raising-frame locals never see the Authorization header or api_key.
+    class Error < StandardError
+      attr_reader :status_code, :url, :response_body
+
+      def initialize(message, status_code: nil, url: nil, response_body: nil)
+        super(message)
+        @status_code   = status_code
+        @url           = url
+        @response_body = response_body
+      end
+    end
+
+    def initialize(args = {})
+      @host     = args[:host]     || FORMS_HOST
+      @protocol = args[:protocol] || FORMS_PROTOCOL
+      @base     = args[:base]     || FORMS_BASE
+      @api_key  = args[:api_key]  ||
+                  (Paubox.configuration && Paubox.configuration.forms_api_key)
+    end
+
+    def get_form(form_id)
+      assert_uuid!(form_id, 'form_id')
+      url      = "#{@protocol}#{@host}#{@base}/public/form_data/#{encode_segment(form_id)}"
+      response = request(method: :get, url: url, headers: { accept: :json })
+      Paubox::Form.new(JSON.parse(response.body))
+    end
+
+    def submit_form(form_id, form_data:, attachments: [])
+      assert_uuid!(form_id, 'form_id')
+      url     = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}/submissions"
+      payload = { form_data: form_data }
+      payload[:attachments] = attachments unless attachments.empty?
+      request(method: :post, url: url, payload: payload.to_json,
+              headers: { content_type: :json, accept: :json })
+    end
+
+    def list_forms(params = {})
+      url   = "#{@protocol}#{@host}#{@base}/api/forms"
+      query = params.transform_keys(&:to_sym)
+                    .select { |k, _v| LIST_FORMS_PARAMS.include?(k) }
+      if query[:customer_id].nil?
+        raise ArgumentError, 'customer_id is required for list_forms and must ' \
+                             "match the API key's customer, e.g. " \
+                             'client.list_forms(customer_id: 123)'
+      end
+
+      response = request(method: :get, url: url,
+                         headers: auth_headers.merge(params: query))
+      body     = JSON.parse(response.body)
+      forms    = (body['results'] || []).map { |form| Paubox::Form.new(form) }
+      { forms: forms, page_info: body['page_info'] }
+    end
+
+    def create_form(attrs)
+      url      = "#{@protocol}#{@host}#{@base}/api/forms"
+      response = request(method: :post, url: url, payload: attrs.to_json,
+                         headers: auth_headers.merge(content_type: :json))
+      JSON.parse(response.body)
+    end
+
+    def find_form(form_id)
+      assert_uuid!(form_id, 'form_id')
+      url      = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}"
+      response = request(method: :get, url: url, headers: auth_headers)
+      Paubox::Form.new(JSON.parse(response.body)['data'])
+    end
+
+    def update_form(form_id, attrs)
+      assert_uuid!(form_id, 'form_id')
+      url      = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}"
+      response = request(method: :put, url: url, payload: attrs.to_json,
+                         headers: auth_headers.merge(content_type: :json))
+      JSON.parse(response.body)
+    end
+
+    def archive_form(form_id)
+      assert_uuid!(form_id, 'form_id')
+      url      = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}/archive"
+      response = request(method: :post, url: url, payload: '{}',
+                         headers: auth_headers.merge(content_type: :json))
+      JSON.parse(response.body)
+    end
+
+    def unarchive_form(form_id)
+      assert_uuid!(form_id, 'form_id')
+      url      = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}/unarchive"
+      response = request(method: :post, url: url, payload: '{}',
+                         headers: auth_headers.merge(content_type: :json))
+      JSON.parse(response.body)
+    end
+
+    def copy_form(form_id, title:)
+      assert_uuid!(form_id, 'form_id')
+      url      = "#{@protocol}#{@host}#{@base}/api/forms/copy"
+      payload  = { form_id: form_id, title: title }
+      response = request(method: :post, url: url, payload: payload.to_json,
+                         headers: auth_headers.merge(content_type: :json))
+      Paubox::Form.new(JSON.parse(response.body))
+    end
+
+    def form_stats(customer_id: nil)
+      url     = "#{@protocol}#{@host}#{@base}/api/forms/stats"
+      headers = auth_headers
+      headers = headers.merge(params: { customer_id: customer_id }) unless customer_id.nil?
+      response = request(method: :get, url: url, headers: headers)
+      JSON.parse(response.body)
+    end
+
+    def list_submissions(form_id, params = {})
+      assert_uuid!(form_id, 'form_id')
+      url      = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}/submissions"
+      query    = params.transform_keys(&:to_sym)
+                       .select { |k, _v| LIST_SUBMISSIONS_PARAMS.include?(k) }
+      response = request(method: :get, url: url,
+                         headers: auth_headers.merge(params: query))
+      body     = JSON.parse(response.body)
+      submissions = (body['data'] || []).map { |s| Paubox::FormSubmission.new(s) }
+      { submissions: submissions, total: body['total'], page: body['page'],
+        items: body['items'] }
+    end
+
+    def submissions_csv(form_id, submission_id: nil)
+      assert_uuid!(form_id, 'form_id')
+      base = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}" \
+             '/submissions/submission-csv'
+      url = if submission_id.nil?
+              base
+            else
+              assert_uuid!(submission_id, 'submission_id')
+              "#{base}/#{encode_segment(submission_id)}"
+            end
+      request(method: :get, url: url, headers: auth_headers(accept: 'text/csv')).body
+    end
+
+    def submission_pdf(form_id, submission_id)
+      assert_uuid!(form_id, 'form_id')
+      assert_uuid!(submission_id, 'submission_id')
+      url = "#{@protocol}#{@host}#{@base}/api/forms/#{encode_segment(form_id)}/submissions/" \
+            "#{encode_segment(submission_id)}/submission-pdf"
+      request(method: :get, url: url, headers: auth_headers(accept: 'application/pdf')).body
+    end
+
+    private
+
+    def auth_headers(accept: :json)
+      if @api_key.nil? || @api_key.to_s.empty?
+        raise ArgumentError, "api_key is required for this endpoint. Pass a scoped " \
+                             "API key with the 'forms' scope: " \
+                             'Paubox::FormsClient.new(api_key: ...)'
+      end
+
+      { authorization: "Bearer #{@api_key}", accept: accept }
+    end
+
+    def assert_uuid!(value, name)
+      return if value.is_a?(String) && value.match?(UUID_RE)
+
+      raise ArgumentError, "#{name} must be a UUID string (received #{value.inspect})"
+    end
+
+    def encode_segment(value)
+      CGI.escape(value.to_s)
+    end
+
+    # Funnels every request through RestClient::Request.execute so we can
+    # always set an explicit timeout (rest-client's default is nil) and
+    # translate ExceptionWithResponse into Paubox::FormsClient::Error,
+    # which carries only status_code / url / response_body — never the
+    # Authorization header or api_key. Keeps the Bearer token out of any
+    # error reporter that captures raising-frame locals.
+    def request(method:, url:, headers: {}, payload: nil)
+      RestClient::Request.execute(
+        method:  method,
+        url:     url,
+        payload: payload,
+        headers: headers,
+        timeout: TIMEOUT_SECONDS
+      )
+    rescue RestClient::ExceptionWithResponse => e
+      response = e.response
+      raise Error.new(
+        "Paubox Forms API request failed: #{e.class.name.split('::').last} " \
+        "(status #{response && response.code || 'unknown'})",
+        status_code:   response && response.code,
+        url:           url,
+        response_body: response && response.body
+      )
+    end
+  end
+end

data/lib/paubox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Paubox
-  VERSION = '0.3.2'
+  VERSION = '1.0.0'
 end

data/lib/paubox.rb

@@ -2,11 +2,15 @@
 
 require 'paubox/version'
 require 'paubox/client'
+require 'paubox/dynamic_templates'
 require 'paubox/format_helper'
 require 'paubox/mail_to_message'
 require 'paubox/message'
 require 'paubox/templated_message'
 require 'paubox/email_disposition'
+require 'paubox/form'
+require 'paubox/form_submission'
+require 'paubox/forms_client'
 require 'mail/paubox'
 
 module Paubox
@@ -20,6 +24,10 @@ module Paubox
   end
 
   class Configuration
-    attr_accessor :api_key, :api_user
+    attr_accessor :api_key, :forms_api_key
+
+    # Deprecated: api_user is no longer used by the Email API client.
+    # Kept only for backward compatibility; it has no effect on requests.
+    attr_accessor :api_user
   end
-end
+end

data/paubox_ruby.gemspec

@@ -29,6 +29,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec', '~> 3.2'
   spec.add_development_dependency 'webmock', '~> 2.1'
 
+  # base64 and ostruct left the default gems (base64 in Ruby 3.4, ostruct in
+  # 4.0). lib/ requires both, so they must be declared or the gem fails to load.
+  spec.add_dependency 'base64'
+  spec.add_dependency 'ostruct'
   spec.add_dependency 'mail', '>= 2.5'
   spec.add_dependency 'rest-client', '~> 2.0', '>= 2.0.2'
 end

data/release-please-config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "paubox",
+      "version-file": "lib/paubox/version.rb",
+      "include-component-in-tag": false,
+      "include-v-in-tag": true,
+      "draft": false,
+      "prerelease": false
+    }
+  }
+}

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: paubox
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Paubox
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,6 +79,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mail
   requirement: !ruby/object:Gem::Requirement
@@ -121,31 +148,42 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/scripts/assert_specs_ran.rb"
+- ".github/workflows/ci.yml"
+- ".github/workflows/pr-title.yml"
+- ".github/workflows/release-please.yml"
 - ".gitignore"
+- ".release-please-manifest.json"
 - ".rspec"
-- ".travis.yml"
+- CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- api.md
 - bin/console
 - bin/setup
 - lib/mail/paubox.rb
 - lib/paubox.rb
 - lib/paubox/client.rb
+- lib/paubox/dynamic_templates.rb
 - lib/paubox/email_disposition.rb
+- lib/paubox/form.rb
+- lib/paubox/form_submission.rb
 - lib/paubox/format_helper.rb
+- lib/paubox/forms_client.rb
 - lib/paubox/mail_to_message.rb
 - lib/paubox/message.rb
 - lib/paubox/templated_message.rb
 - lib/paubox/version.rb
 - lib/paubox_ruby.rb
 - paubox_ruby.gemspec
+- release-please-config.json
 homepage: https://www.paubox.com
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -160,8 +198,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.14
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Paubox's Official Ruby SDK
 test_files: []

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.3.1
-before_install: gem install bundler -v 1.14.6