paubox 0.3.2 → 1.0.0

data/README.md

@@ -1,15 +1,17 @@
 <img src="https://avatars.githubusercontent.com/u/22528478?s=200&v=4" alt="Paubox" width="150px">
 
 # Paubox Gem
-This is the official Ruby wrapper for the Paubox Email API. The Paubox Email API allows your application to send secure, HIPAA compliant email via Paubox and track deliveries and opens.
+This is the official Ruby wrapper for the Paubox API. It supports the Paubox Email API — which allows your application to send secure, HIPAA compliant email via Paubox and track deliveries and opens — and the Paubox Forms API, which allows you to fetch form definitions, submit form responses, and manage forms and their submissions.
 
 It extends the [Ruby Mail Library](https://github.com/mikel/mail) for seamless integration in your existing Ruby application. The API wrapper also allows you to construct and send messages directly without the Ruby Mail Library.
 
 # Table of Contents
 * [Installation](#installation)
-*  [Usage](#usage)
-*  [Contributing](#contributing)
-*  [License](#license)
+* [Usage](#usage)
+  * [Sending Email](#sending-messages-with-the-ruby-mail-library)
+  * [Paubox Forms](#paubox-forms)
+* [Contributing](#contributing)
+* [License](#license)
 
 
 <a name="#installation"></a>
@@ -30,7 +32,7 @@ Or install it yourself as:
     $ gem install paubox
 
 ### Getting Paubox API Credentials
-You will need to have a Paubox account. You can [sign up here](https://www.paubox.com/join/see-pricing?unit=messages).
+You will need to have a Paubox account. You can [sign up here](https://www.paubox.com/pricing/paubox-email-api).
 
 Once you have an account, follow the instructions on the Rest API dashboard to verify domain ownership and generate API credentials.
 
@@ -42,10 +44,11 @@ Keep your API credentials out of version control. Store these in environment var
 ```ruby
 Paubox.configure do |config|
   config.api_key = ENV['PAUBOX_API_KEY']
-  config.api_user = ENV['PAUBOX_API_USER']
 end
 ```
 
+_Note: earlier versions of this gem also required an `api_user`. It is no longer needed — the API key alone authenticates. The `api_user` configuration option is deprecated and ignored._
+
 If you need to send from multiple domains, you can pass credentials in the options hash when you set Ruby Mail's `Mail#delivery_method`, or when using `Paubox::Message`, when you instantiate `Paubox::Client`.
 
 **(optional) Setting credentials when using Ruby Mail:**
@@ -53,16 +56,14 @@ If you need to send from multiple domains, you can pass credentials in the optio
 ```ruby
 message = Mail.new do
   ...
-  delivery_method(Mail::Paubox, api_key: ENV['PAUBOX_API_KEY'],
-                                api_user: ENV['PAUBOX_API_USER'])
+  delivery_method(Mail::Paubox, api_key: ENV['PAUBOX_API_KEY'])
 end
 ```
 
 **(optional) Setting credentials when using Paubox::Client:**
 
 ```ruby
-client = Paubox::Client.new(api_key: ENV['PAUBOX_API_KEY'],
-                            api_user: ENV['PAUBOX_API_USER'])
+client = Paubox::Client.new(api_key: ENV['PAUBOX_API_KEY'])
 ```
 
 <a name="#usage"></a>
@@ -190,10 +191,42 @@ message = Paubox::Message.new(args)
 client = Paubox::Client.new
 client.deliver_mail(message)
 => {"message"=>"Service OK", "sourceTrackingId"=>"2a3c048485aa4cf6"}
+```
+### Manage Dynamic Templates
+Can manage(create, update, find and delete) the dynamic templates. by using the following commands and use these to send the Templated Messages.
+
+```ruby
+require 'Paubox'
+require 'json'
+
+template_name = "Template name"
+template_path = "Template File path"
+
+# For create the new dynamic template
+Paubox::DynamicTemplates.create(template_name, template_path)
+=> { "RestClient::Response"=>"201", "message"=>"Template #{name} created!" }
+
+# For getting the list of all dynamic template of your organization
+Paubox::DynamicTemplates.list
+=>[{"id"=>1, "name"=>"test", "api_customer_id"=>11},
+ {"id"=>3, "name"=>"Test", "api_customer_id"=>11}]
+
+
+# For update the existing dynamic template
+dynamic_template = Paubox::DynamicTemplates.find(template_id)
+dynamic_template.update(template_path, template_name)
+=> {"RestClient::Response"=>"200", "message"=>"Template #{name} updated!"}
+
+# For delete the existing dynamic template
+dynamic_template = Paubox::DynamicTemplates.find(template_id)
+dynamic_template.delete
+=> {"RestClient::Response"=>"200", "message"=>"Template #{name} deleted!"}
+
+
 ```
 
 ### Send Messages using Dynamic Templates
-Using [dynamic templates](https://docs.paubox.com/docs/paubox_email_api/dynamic_templates/) is similar to sending a regular message. Just create a `Paubox::TemplatedMessage` object and pass a `template` object with the name of the template and variables:
+Using above[dynamic templates](https://docs.paubox.com/email-api/dynamic-templates) is similar to sending a regular message. Just create a `Paubox::TemplatedMessage` object and pass a `template` object with the name of the template and variables:
 
 ```ruby
 require 'Paubox'
@@ -223,6 +256,7 @@ client.deliver_mail(templated_message)
 
 _Note that there is no `content` when using templated messages._
 
+
 ### Checking Email Dispositions
 ```ruby
 require 'Paubox'
@@ -259,10 +293,214 @@ status.opened_time
 => Mon, 30 Apr 2018 12:55:19 -0700
 ```
 
+<a name="#paubox-forms"></a>
+## Paubox Forms
+
+The Paubox Forms API has two kinds of endpoints. **Public endpoints** (fetching a form definition, submitting a form) require no authentication and are intended for form embed use cases. **Authenticated endpoints** (managing forms and their submissions) require a Paubox API key scoped to `forms`.
+
+### Public Endpoints (No Authentication)
+
+These endpoints send no auth header, so `Paubox::FormsClient` can be constructed without any credentials.
+
+#### Getting Form Metadata
+
+```ruby
+require 'Paubox'
+
+client = Paubox::FormsClient.new
+form   = client.get_form('550e8400-e29b-41d4-a716-446655440000')
+
+form.title            # => "Patient Intake Form"
+form.description      # => "Please complete before your appointment."
+form.active?          # => true
+form.signable?        # => false
+form.submission_count # => 42
+form.form_html        # => "<form>...</form>"
+form.form_json        # => { ... }
+```
+
+#### Submitting a Form
+
+```ruby
+require 'Paubox'
+
+client = Paubox::FormsClient.new
+
+client.submit_form('550e8400-e29b-41d4-a716-446655440000',
+  form_data: {
+    first_name: 'Jane',
+    last_name:  'Smith',
+    email:      'jane@example.com'
+  })
+```
+
+#### Submitting a Form with Attachments
+
+File attachments must be base64-encoded. The maximum request size is 250 MB.
+
+```ruby
+require 'Paubox'
+require 'base64'
+
+client = Paubox::FormsClient.new
+
+client.submit_form('550e8400-e29b-41d4-a716-446655440000',
+  form_data: {
+    first_name: 'Jane',
+    signature:  '{signature_field}'
+  },
+  attachments: [
+    {
+      name:    'consent.pdf',
+      content: Base64.strict_encode64(File.binread('consent.pdf'))
+    }
+  ])
+```
+
+### Authenticated Endpoints (Scoped API Key)
+
+Form management endpoints require a Paubox API key scoped to `forms`. This is a different key from the Email API key (`Paubox.configuration.api_key`), which is never used for Forms endpoints. Pass the forms key when you instantiate the client, or configure it via `Paubox.configure` (the client falls back to `Paubox.configuration.forms_api_key`). The key is sent as an `Authorization: Bearer` header on every management request.
+
+```ruby
+require 'Paubox'
+
+client = Paubox::FormsClient.new(api_key: ENV['PAUBOX_FORMS_API_KEY'])
+
+# or globally:
+Paubox.configure { |config| config.forms_api_key = ENV['PAUBOX_FORMS_API_KEY'] }
+client = Paubox::FormsClient.new
+```
+
+Calling a management endpoint without an API key raises `ArgumentError`.
+
+#### Listing Forms
+
+Supports filtering, ordering, and pagination. `customer_id` is required and must match the API key's customer — the client raises `ArgumentError` without it. Optional params: `form_id`, `search`, `order` (`'asc'`/`'desc'`), `order_by` (`'title'`, `'updated_at'`, `'submission_count'`, `'created_at'`), `archived`, `active`, `page`, and `items` (capped at 100 by the server).
+
+```ruby
+result = client.list_forms(customer_id: 123, search: 'intake',
+                           order_by: 'updated_at', order: 'desc',
+                           page: 1, items: 25)
+
+result[:forms].first.title # => "Patient Intake Form"
+result[:page_info]         # => {"count"=>42, "pages"=>2, "page"=>1, "items"=>25}
+```
+
+#### Creating a Form
+
+Required attributes: `title`, `form_json`, `customer_id`, and `version`. Optional attributes include `description`, `form_html`, `form_css`, `recipient`, `signable`, `signature_confirmation_label`, `subscription_list_id`, `type`, and `active`.
+
+```ruby
+client.create_form(title: 'Patient Intake Form',
+                   form_json: { fields: [{ name: 'first_name' }] },
+                   customer_id: 123,
+                   version: 1,
+                   recipient: 'intake@yourdomain.com')
+=> {"id"=>"550e8400-e29b-41d4-a716-446655440000"}
+```
+
+#### Finding a Form
+
+Returns a `Paubox::Form`. Unlike the public `get_form`, `find_form` can fetch inactive and archived forms.
+
+```ruby
+form = client.find_form('550e8400-e29b-41d4-a716-446655440000')
+
+form.title     # => "Patient Intake Form"
+form.archived? # => false
+form.recipient # => "intake@yourdomain.com"
+```
+
+#### Updating a Form
+
+Updates are partial: fields you omit are left unchanged. Updatable fields: `title`, `description`, `form_json`, `vanity_url`, `recipient`, `active`, and `subscription_list_id`.
+
+```ruby
+client.update_form('550e8400-e29b-41d4-a716-446655440000',
+                   title: 'Patient Intake Form (v2)',
+                   active: false)
+=> {"detail"=>"Form updated successfully", "form_id"=>"550e8400-e29b-41d4-a716-446655440000"}
+```
+
+#### Archiving and Unarchiving a Form
+
+```ruby
+client.archive_form('550e8400-e29b-41d4-a716-446655440000')
+=> {"detail"=>"Form archived."}
+
+client.unarchive_form('550e8400-e29b-41d4-a716-446655440000')
+=> {"detail"=>"Form unarchived."}
+```
+
+#### Copying a Form
+
+Copies an existing form under a new title and returns the new form as a `Paubox::Form`.
+
+```ruby
+form = client.copy_form('550e8400-e29b-41d4-a716-446655440000',
+                        title: 'Patient Intake Form (Copy)')
+
+form.id    # => "7c9e6679-7425-40de-944b-e07fc1f90ae7"
+form.title # => "Patient Intake Form (Copy)"
+```
+
+#### Form Stats
+
+Returns aggregate counts. `customer_id` is optional and defaults server-side to the API key's customer.
+
+```ruby
+client.form_stats
+=> {"active_form_count"=>12, "total_submission_count"=>340, "submissions_last_7_days"=>18}
+
+client.form_stats(customer_id: 123)
+```
+
+#### Listing Submissions
+
+Returns `Paubox::FormSubmission` objects plus pagination info. Available params: `submission_id`, `order_by` (`'submitter_email'`, `'created_at'`), `order`, `page`, and `items` (capped at 100 by the server).
+
+```ruby
+result = client.list_submissions('550e8400-e29b-41d4-a716-446655440000',
+                                 order_by: 'created_at', order: 'desc')
+
+result[:total] # => 42
+result[:page]  # => 1
+result[:items] # => 25
+
+submission = result[:submissions].first
+submission.submitter_email # => "jane@example.com"
+submission.form_data       # => {"first_name"=>"Jane", "last_name"=>"Smith"}
+submission.created_at      # => "2026-08-01T12:34:56Z"
+```
+
+#### Downloading Submissions as CSV
+
+Returns the raw CSV as a `String`. Pass `submission_id:` to download a single submission.
+
+```ruby
+# All submissions for a form
+csv = client.submissions_csv('550e8400-e29b-41d4-a716-446655440000')
+File.write('submissions.csv', csv)
+
+# A single submission
+csv = client.submissions_csv('550e8400-e29b-41d4-a716-446655440000',
+                             submission_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7')
+```
+
+#### Downloading a Submission as PDF
+
+Returns the raw PDF bytes as a `String`.
+
+```ruby
+pdf = client.submission_pdf('550e8400-e29b-41d4-a716-446655440000',
+                            '7c9e6679-7425-40de-944b-e07fc1f90ae7')
+File.binwrite('submission.pdf', pdf)
+```
+
 <a name="#contributing"></a>
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/paubox/paubox_ruby.
+Bug reports and pull requests are welcome on GitHub at https://github.com/paubox/paubox-ruby.
 
 
 <a name="#license"></a>
@@ -281,3 +519,8 @@ limitations under the License.
 ## Copyright
 Copyright &copy; 2022, Paubox, Inc.
 
+## 💬 Community & support
+
+Questions, ideas, or want to share what you built? Join the **[Paubox Community](https://github.com/Paubox/community/discussions)** — the single home for discussions across every Paubox SDK and API.
+
+🔐 Found a security issue? Email **devops@paubox.com** — please don't post it publicly.

data/api.md

@@ -0,0 +1,283 @@
+# Paubox Ruby Gem — API Reference
+
+## Email API
+
+### Authentication
+
+All Email API requests use token-based authentication. The API key alone authenticates — no username is required. Configure the key once globally or pass it per client instance.
+
+**Global configuration:**
+```ruby
+Paubox.configure do |config|
+  config.api_key = ENV['PAUBOX_API_KEY']
+end
+```
+
+**Per-instance:**
+```ruby
+client = Paubox::Client.new(api_key: ENV['PAUBOX_API_KEY'])
+```
+
+_The `api_user` configuration option is deprecated and ignored._
+
+**Authorization header sent on every request:**
+```
+Authorization: Token token=<api_key>
+```
+
+### Base URL
+
+```
+https://api.paubox.com/v1
+```
+
+All Email API paths below are relative to this base.
+
+---
+
+### Send Message
+
+**POST** `/messages`
+
+Sends a HIPAA-compliant email.
+
+**Request body:**
+```json
+{
+  "data": {
+    "message": {
+      "recipients": ["recipient@example.com"],
+      "cc": [],
+      "bcc": [],
+      "allowNonTLS": false,
+      "headers": {
+        "from": "sender@yourdomain.com",
+        "reply-to": "reply@yourdomain.com",
+        "subject": "Hello"
+      },
+      "content": {
+        "text/plain": "Plain text body",
+        "text/html": "<h1>HTML body</h1>"
+      },
+      "attachments": [
+        {
+          "fileName": "file.pdf",
+          "contentType": "application/pdf",
+          "content": "<base64-encoded content>"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Optional fields:**
+- `forceSecureNotification` (`"true"` / `"false"`) — forces portal delivery
+- `allowNonTLS` (`true` / `false`) — allows delivery without TLS
+
+**Response (200):**
+```json
+{ "message": "Service OK", "sourceTrackingId": "2a3c048485aa4cf6" }
+```
+
+---
+
+### Send Templated Message
+
+**POST** `/templated_messages`
+
+Sends a message using a dynamic template.
+
+**Request body:**
+```json
+{
+  "data": {
+    "recipients": ["recipient@example.com"],
+    "headers": { "from": "sender@yourdomain.com", "subject": "Hello" },
+    "template_name": "My Template",
+    "template_values": { "first_name": "Jane", "last_name": "Smith" }
+  }
+}
+```
+
+**Response (200):**
+```json
+{ "sourceTrackingId": "166904b5-dce7-4de1-92e8-3d505c165ff5", "data": "Service OK" }
+```
+
+---
+
+### Get Email Disposition
+
+**GET** `/message_receipt?sourceTrackingId=<id>`
+
+Returns delivery and open status for a sent message.
+
+**Response (200):**
+```json
+{
+  "sourceTrackingId": "2a3c048485aa4cf6",
+  "data": {
+    "message": {
+      "id": "...",
+      "message_deliveries": [
+        {
+          "recipient": "recipient@example.com",
+          "status": {
+            "deliveryStatus": "delivered",
+            "deliveryTime": "2024-01-15T12:54:19-07:00",
+            "openedStatus": "opened",
+            "openedTime": "2024-01-15T12:55:19-07:00"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### Dynamic Templates
+
+All paths are relative to the Email API base URL.
+
+| Operation      | Method  | Path                          |
+|----------------|---------|-------------------------------|
+| List templates | GET     | `/dynamic_templates`          |
+| Get template   | GET     | `/dynamic_templates/<id>`     |
+| Create         | POST    | `/dynamic_templates`          |
+| Update         | PATCH   | `/dynamic_templates/<id>`     |
+| Delete         | DELETE  | `/dynamic_templates/<id>`     |
+
+**Create / Update request body** (`multipart/form-data`):
+- `data[name]` — template name
+- `data[body]` — template file
+
+---
+
+### API Status
+
+**GET** `/status`
+
+Returns service health. No authentication required in practice.
+
+**Response (200):**
+```json
+{ "message": "Service OK" }
+```
+
+---
+
+## Forms API
+
+### Authentication
+
+**None required.** Forms API endpoints are public and designed for form embed use cases. No API key or authorization header is sent.
+
+### Base URL
+
+```
+https://api.paubox.com/forms
+```
+
+---
+
+### Get Form Metadata
+
+**GET** `/public/form_data/<form_id>`
+
+Returns the full form definition for a given UUID. Used to render a form to a respondent.
+
+**Path parameter:**
+- `form_id` (UUID, required) — the form to retrieve
+
+**Response (200):**
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "title": "Patient Intake Form",
+  "description": "Please complete before your appointment.",
+  "form_json": {},
+  "form_html": "<form>...</form>",
+  "form_css": "form { font-family: sans-serif; }",
+  "vanity_url": null,
+  "version": 1,
+  "active": true,
+  "customer_id": 123,
+  "signable": false,
+  "signature_confirmation_label": null,
+  "submission_count": 42,
+  "type": null,
+  "deleted": false,
+  "archived": false,
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-06-01T08:00:00Z"
+}
+```
+
+**Errors:**
+- `404` — form not found
+
+**Ruby usage:**
+```ruby
+client = Paubox::FormsClient.new
+form   = client.get_form('550e8400-e29b-41d4-a716-446655440000')
+
+form.title            # => "Patient Intake Form"
+form.active?          # => true
+form.signable?        # => false
+form.submission_count # => 42
+```
+
+---
+
+### Submit Form Response
+
+**POST** `/api/forms/<form_id>/submissions`
+
+Submits a respondent's answers for a form. On success, the service stores the submission, increments the submission count, emails configured recipients, and returns 201 with no body. Maximum request size is **250 MB**.
+
+**Path parameter:**
+- `form_id` (UUID, required) — the form being submitted
+
+**Request body:**
+```json
+{
+  "form_data": {
+    "first_name": "Jane",
+    "last_name": "Smith",
+    "email": "jane@example.com"
+  },
+  "attachments": [
+    {
+      "name": "consent.pdf",
+      "content": "<base64-encoded file content>"
+    }
+  ]
+}
+```
+
+- `form_data` (object, required) — key-value pairs matching the form's field schema
+- `attachments` (array, optional) — file attachments; each item requires `name` (filename) and `content` (base64-encoded)
+
+**Response:**
+- `201` — submission accepted (no body)
+- `400` — missing required `form_data` field
+- `404` — form not found
+
+**Ruby usage:**
+```ruby
+client = Paubox::FormsClient.new
+
+# Text fields only
+client.submit_form('550e8400-e29b-41d4-a716-446655440000',
+  form_data: { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com' })
+
+# With file attachments
+client.submit_form('550e8400-e29b-41d4-a716-446655440000',
+  form_data: { first_name: 'Jane', signature: '{signature_field}' },
+  attachments: [
+    { name: 'consent.pdf', content: Base64.strict_encode64(File.binread('consent.pdf')) }
+  ])
+```

data/lib/paubox/client.rb

@@ -5,12 +5,16 @@ module Paubox
   class Client
     require 'rest-client'
     require 'ostruct'
-    attr_reader :api_key, :api_user, :api_host, :api_protocol, :api_version
+    attr_reader :api_key, :api_host, :api_protocol, :api_version
+
+    # Deprecated: api_user is no longer used for authentication or URLs.
+    # It is kept only for backward compatibility and has no effect on requests.
+    attr_reader :api_user
 
     def initialize(args = {})
       args = defaults.merge(args)
       @api_key = args[:api_key]
-      @api_user = args[:api_user]
+      @api_user = args[:api_user] # deprecated no-op, kept for backward compatibility
       @api_host = args[:api_host]
       @api_protocol = args[:api_protocol]
       @api_version = args[:api_version]
@@ -50,6 +54,12 @@ module Paubox
     end
     alias message_receipt email_disposition
 
+    def send_request(method: :get, payload: {}, path: '')
+      url = request_endpoint(path)
+
+      RestClient::Request.execute(method: method, url: url, payload: payload, headers: auth_header)
+    end
+
     private
 
     def auth_header
@@ -59,7 +69,7 @@ module Paubox
     end
 
     def api_base_endpoint
-      "#{api_protocol}#{api_host}/#{api_version}/#{api_user}"
+      "#{api_protocol}#{api_host}/#{api_version}"
     end
 
     def request_endpoint(endpoint)
@@ -68,8 +78,8 @@ module Paubox
 
     def defaults
       { api_key: Paubox.configuration.api_key,
-        api_user: Paubox.configuration.api_user,
-        api_host: 'api.paubox.net', 
+        api_user: Paubox.configuration.api_user, # deprecated, unused
+        api_host: 'api.paubox.com',
         api_protocol: 'https://',
         api_version: 'v1',
         test_mode: false }