paubox 0.3.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3733459b49f6166432d85899d4ea38e9d9f983c6f1ef42d17ed430fc7095beb9
-  data.tar.gz: f4c0bf54df9f438dd499d178ca67eadb2b4f7e0aa3516089da2faed70b6f02cb
+  metadata.gz: da4b3dae43dc155032452be9913d48e4da7ba65878067923af62bb5497783ebc
+  data.tar.gz: f7e0db657ed86db45207f3c0fcd280febd834262ebcac0313a5c48c0b7e2f186
 SHA512:
-  metadata.gz: 66acb7c648c2ede8380ecdaeb60c8cde92cd97ed66f17dce81bf8ef9e175c9d53f777fab4d1527ee3c8ceb35d65b3975a74fa5047af8add6af90380fc8b17f5b
-  data.tar.gz: 3eeb0122292eb25f34dc24e5e62ed696200c8efd45304cde5a92467dec5c03bc0c27d01ff369ece52b4c6091c36651e886d119049922f752cafb2cc4c1c4ce97
+  metadata.gz: b450e2ca12166a1689fc460ec810c11dc6ad53cc2d1e71d29a06f701db91f901d2ead1ca4eb7c61f91ebb444c5caadcbc49c8a5f81157a256514bf90f4b33ac0
+  data.tar.gz: db478b8679f6acb5a5851b80826f81a1dd0b8360250acd68254812e4cf75c5f4bef83f21c8ec939bd43ec339e0489a554c4bfe271cc246719afcbb93816668c3

data/.github/scripts/assert_specs_ran.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Fail CI when a green rspec exit code does not mean the suite ran.
+#
+# A passing run is not evidence of coverage: an error outside an example, a
+# stray tag filter, or a spec_helper that stops loading files can leave rspec
+# reporting success having executed almost nothing. The failure mode is
+# invisible precisely because the exit code is 0.
+
+require 'json'
+
+# Floor, not a target. Only trips if coverage regresses; adding specs is free.
+MIN_EXAMPLES = 250
+
+summary = JSON.parse(File.read(ARGV.fetch(0))).fetch('summary')
+
+total    = summary.fetch('example_count')
+pending  = summary.fetch('pending_count')
+failures = summary.fetch('failure_count')
+errors   = summary.fetch('errors_outside_of_examples_count')
+executed = total - pending
+
+puts format(
+  'examples=%d executed=%d failures=%d pending=%d errors_outside_examples=%d',
+  total, executed, failures, pending, errors
+)
+
+problems = []
+problems << "#{errors} error(s) outside of examples" if errors.positive?
+if executed < MIN_EXAMPLES
+  problems << "only #{executed} example(s) executed, expected at least #{MIN_EXAMPLES}"
+end
+
+unless problems.empty?
+  warn "FAIL: #{problems.join('; ')}"
+  exit 1
+end
+
+puts "OK: suite executed #{executed} examples"

data/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  spec:
+    name: rspec (ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.1", "3.2", "3.3", "3.4"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          # Resolves bundler from the gemspec's own '~> 2.0' constraint and
+          # caches the installed gems.
+          bundler-cache: true
+
+      - name: Run specs
+        # Both formatters are explicit: a CLI --format overrides the one in
+        # .rspec, so without this the log would be empty on failure. The JSON
+        # file feeds the gate below.
+        run: >-
+          bundle exec rspec
+          --format documentation
+          --format json --out rspec-results.json
+
+      - name: Assert the suite actually executed
+        run: ruby .github/scripts/assert_specs_ran.rb rspec-results.json

data/.github/workflows/pr-title.yml

@@ -0,0 +1,36 @@
+name: PR Title
+
+on:
+  pull_request:
+    branches: [master, main]
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  conventional-title:
+    name: Conventional commit title
+    runs-on: ubuntu-latest
+    steps:
+      # With squash merging the squash commit subject is the PR title, so this
+      # string is all release-please ever parses. A title it cannot parse is
+      # silently dropped from the release rather than failing anything, so it is
+      # gated here instead.
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            perf
+            revert
+            docs
+            style
+            refactor
+            test
+            build
+            ci
+            chore
+            deps

data/.github/workflows/release-please.yml

@@ -0,0 +1,88 @@
+name: release-please
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    name: Release Please
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      # Maintains a release PR that bumps VERSION in lib/paubox/version.rb and
+      # writes CHANGELOG.md. Merging that PR creates the tag and the GitHub
+      # release, which gates the publish job below.
+      #
+      # The manifest is seeded from RubyGems (0.3.2), not from version.rb, which
+      # had drifted to 0.4.0. Neither 0.4.0 nor 0.3.1 was ever pushed, so
+      # seeding from the repo would have skipped two unused numbers.
+      #
+      # include-component-in-tag is false so tags stay bare `vX.Y.Z`, matching
+      # the existing v0.3.0 and v0.3.2 and the rest of the SDK fleet.
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    name: Publish ${{ needs.release-please.outputs.tag_name }} to RubyGems
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Required for OIDC. Without it the credentials step cannot identify
+      # itself to RubyGems.org and the push fails.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+          # The gemspec builds its file list from `git ls-files`, so the
+          # checkout has to keep the repository intact.
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rspec --format documentation
+
+      - name: Verify the tag and version.rb agree
+        # Cheap guard against pushing a gem whose version does not match the
+        # tag it was cut from. RubyGems only allows a yank within 72 hours and
+        # never allows the number to be reused.
+        env:
+          RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          GEM_VERSION=$(ruby -Ilib -e 'require "paubox/version"; print Paubox::VERSION')
+          if [ "v${GEM_VERSION}" != "${RELEASE_TAG}" ]; then
+            echo "::error::version.rb is ${GEM_VERSION} but the tag is ${RELEASE_TAG}"
+            exit 1
+          fi
+          echo "version.rb ${GEM_VERSION} matches ${RELEASE_TAG}"
+
+      - name: Build the gem
+        run: gem build paubox_ruby.gemspec
+
+      # Trusted publishing: exchanges GitHub's OIDC token for a short-lived
+      # RubyGems credential. There is no API key stored anywhere. RubyGems pins
+      # the trust to the repository and this workflow filename, so renaming
+      # this file breaks publishing until the trusted publisher entry for the
+      # `paubox` gem is updated to match.
+      - name: Configure RubyGems credentials
+        uses: rubygems/configure-rubygems-credentials@main
+
+      - name: Push the gem
+        run: gem push paubox-*.gem

data/.gitignore

@@ -11,4 +11,7 @@
 
 # rspec failure tracking
 .rspec_status
-.gem
+.gem
+
+# rspec JSON output written by CI.
+rspec-results.json

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}

data/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0](https://github.com/Paubox/paubox-ruby/compare/v0.3.2...v1.0.0) (2026-08-21)
+
+First stable release. RubyGems had been on `0.3.2` since October 2022.
+
+### ⚠ BREAKING CHANGES
+
+- Promotes the gem from `0.x` to a stable `1.0.0`. No public API is removed and existing code keeps working, but dependents pinned with a pessimistic `0.x` constraint will not resolve `1.0.0` without widening it. This affects `paubox_rails`, whose gemspec requires `paubox '~> 0.3'`
+
+### 🚀 New Features
+
+- Add `Paubox::FormsClient` for the Paubox Forms API, with `Paubox::Form` and `Paubox::FormSubmission` models
+  - Public endpoints, no credential attached: `get_form`, `submit_form`
+  - Form management with a scoped API key (`forms` scope, sent as `Authorization: Bearer <key>`): `list_forms`, `find_form`, `create_form`, `update_form`, `archive_form`, `unarchive_form`, `copy_form`, `form_stats`
+  - Submissions: `list_submissions`, `submissions_csv`, `submission_pdf`
+- The Email API no longer requires `api_user` — an API key alone authenticates
+
+### ⚠️ Behavior Changes
+
+- Email API base URLs move to `api.paubox.com`. `api_user` is accepted and ignored, and `Paubox::Client#api_user` is kept as a deprecated reader, so existing configuration keeps working
+- The Forms API host is `api.paubox.com`, moved from the earlier `apx.paubox.com/forms`
+
+### 🔒 Hardening
+
+- Validate and encode caller-supplied values interpolated into Forms request paths. Authenticated endpoints require a UUID; public endpoints encode the segment instead of rejecting it
+- Keep the Bearer token out of exception messages raised from Forms requests
+
+### 🐛 Fixes
+
+- Declare `base64` and `ostruct` as runtime dependencies. Both left the Ruby default gems (`base64` in 3.4, `ostruct` in 4.0) and `lib/` requires them, so the gem failed to load on Ruby 3.4 without them ([7299324](https://github.com/Paubox/paubox-ruby/commit/729932436a8982c11f2a71d0d2327265160317d3))
+
+### 🎉 Enhancements
+
+- Replace the dead Travis config with a GitHub Actions CI workflow running RSpec on Ruby 3.1 through 3.4
+
+## v0.3.2 / 2022-10-06
+
+### 🚀 New Features
+
+- Add support for sending messages using dynamic templates ([#8](https://github.com/Paubox/paubox-ruby/pull/8))
+
+## v0.3.0 / 2019-07-10
+
+### 🎉 Enhancements
+
+- Version bump and dependency maintenance
+
+## v0.2.3 / 2018-10-04
+
+### 🎉 Enhancements
+
+- Relax the `mail` dependency to `>= 2.5`
+- Declare a minimum Ruby version of 2.3
+
+## v0.1.3 / 2018-04-30
+
+### 🎉 Enhancements
+
+- Relax the `mail` dependency to `>= 2.6`
+
+## v0.1.1 / 2018-04-26
+
+### 🐛 Fixes
+
+- Packaging fixes following the initial release
+
+## v0.1.0 / 2018-04-17
+
+### 🚀 Major Release
+
+First release of the Paubox Transactional Email SDK for Ruby.

data/CLAUDE.md

@@ -0,0 +1,114 @@
+# Paubox Ruby Gem — Developer Context
+
+## Purpose
+
+This is the official Ruby gem for the Paubox platform. It provides:
+- **Email API**: send HIPAA-compliant email, manage dynamic templates, check delivery status
+- **Forms API**: fetch form definitions, submit form responses, and manage forms and submissions
+
+## Directory Structure
+
+```
+lib/
+  paubox.rb                  # Entry point: requires all lib files, holds Configuration
+  paubox_ruby.rb             # Alias for paubox.rb
+  paubox/
+    version.rb               # Gem version constant
+    client.rb                # Email API client (authenticated, api.paubox.com)
+    forms_client.rb          # Forms API client (api.paubox.com/forms; Bearer auth on management endpoints)
+    message.rb               # Builds send-message API payload from a hash
+    templated_message.rb     # Extends Message for template-based sends
+    mail_to_message.rb       # Adapts Ruby Mail::Message to API payload
+    dynamic_templates.rb     # CRUD for dynamic email templates
+    email_disposition.rb     # Parses delivery/open status responses
+    form.rb                  # Parses form metadata responses
+    form_submission.rb       # Parses form submission responses
+    format_helper.rb         # Shared utilities: base64, key mapping, normalization
+  mail/
+    paubox.rb                # Plugs Paubox into Ruby Mail as a delivery method
+
+spec/
+  spec_helper.rb             # RSpec + WebMock setup
+  paubox/                    # Unit specs per class
+  mail/                      # Specs for Ruby Mail integration
+  helpers/                   # Shared fixtures (MessageHelper, FormHelper, etc.)
+```
+
+## Key Classes
+
+| Class | Responsibility |
+|---|---|
+| `Paubox::Client` | Authenticated HTTP client for the Email API. Token auth via `Authorization: Token token=<key>`. Base URL: `https://api.paubox.com/v1`. |
+| `Paubox::FormsClient` | HTTP client for the Forms API. Base URL: `https://api.paubox.com/forms`. Public endpoints (`get_form`, `submit_form`) send no auth headers; management endpoints (list/create/find/update/archive/copy forms, stats, submissions, CSV/PDF export) require a "forms"-scoped API key sent as `Authorization: Bearer <api_key>`. |
+| `Paubox::Message` | Builds the JSON payload for `/messages`. Accepts `from`, `to`, `cc`, `bcc`, `subject`, `text_content`, `html_content`, `attachments`. |
+| `Paubox::TemplatedMessage` | Extends `Message`; overrides `send_message_payload` to include `template_name` / `template_values`. |
+| `Paubox::MailToMessage` | Converts a `Mail::Message` object into a Paubox API payload. |
+| `Paubox::DynamicTemplates` | Manages template CRUD via class methods (`create`, `list`, `find`) and instance methods (`update`, `delete`). |
+| `Paubox::EmailDisposition` | Parses the `/message_receipt` response into `MessageDelivery` and `MessageDeliveryStatus` structs. |
+| `Paubox::Form` | Parses form responses (`/public/form_data/<id>`, `/api/forms` endpoints). Exposes predicate methods: `active?`, `deleted?`, `archived?`, `signable?`. |
+| `Paubox::FormSubmission` | Parses a form submission from `/api/forms/<form_id>/submissions`. Exposes `id`, `form_id`, `form_data` (JSON string parsed to a Hash), `submitter_email`, `recipients`, attachment fields, `created_at`. |
+| `Paubox::FormatHelper` | Mixed into message builders; handles base64 encoding, snake_case→camelCase key mapping, email list normalization. |
+| `Mail::Paubox` | Delivery method for the Ruby Mail library. Delegates to `Paubox::Client`. |
+
+## Adding a New Feature
+
+### New API endpoint on the Email API
+1. Add a method to `Paubox::Client` that calls `send_request` or `RestClient` directly.
+2. If the response needs a structured model, create `lib/paubox/<model>.rb` following `EmailDisposition` as a pattern.
+3. Require the new file in `lib/paubox.rb`.
+4. Add specs in `spec/paubox/<feature>_spec.rb` using WebMock to stub HTTP.
+
+### New API endpoint on the Forms API
+1. Add a method to `Paubox::FormsClient`.
+2. If needed, add a response model following `Paubox::Form`.
+3. Require in `lib/paubox.rb`.
+4. Add specs in `spec/paubox/forms_client_spec.rb` or a new file.
+
+## Testing
+
+**Framework:** RSpec 3 + WebMock
+
+```bash
+bundle exec rspec                    # run all specs
+bundle exec rspec spec/paubox/form_spec.rb   # run a single file
+```
+
+WebMock stubs outbound HTTP. All specs must stub any HTTP calls they trigger — no real network requests are made.
+
+Fixtures live in `spec/helpers/` as includable modules (e.g. `Helpers::FormHelper`, `Helpers::MessageHelper`). Include them per spec file with `RSpec.configure { |c| c.include Helpers::XHelper }`.
+
+## Authentication
+
+- **Email API**: `Authorization: Token token=<api_key>` header on every request. The API key alone authenticates — no username/user segment is needed. Configured via `Paubox.configure` or `Paubox::Client.new(api_key:)`. `Configuration` keeps a deprecated `api_user` accessor for backward compatibility; it is ignored.
+- **Forms API**: Public endpoints (`get_form`, `submit_form`) need no auth — `Paubox::FormsClient` sends no auth headers for them. Management endpoints require an API key with the "forms" scope (validated server-side, not by the gem), sent as `Authorization: Bearer <api_key>`. This is a separate key from the Email API key: configure it via `Paubox.configure { |c| c.forms_api_key = ... }` or `Paubox::FormsClient.new(api_key:)` — the client never falls back to `Paubox.configuration.api_key`. Calling a management endpoint without a key raises `ArgumentError`. Note: `list_forms` requires `customer_id` (must match the API key's customer, enforced server-side; the gem raises `ArgumentError` if it is missing).
+
+## Dependencies
+
+- `rest-client` (~> 2.0) — HTTP client
+- `mail` (>= 2.5) — Ruby Mail integration
+
+## Releases
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please). Merging to `master` refreshes a standing release PR; merging *that* PR bumps `lib/paubox/version.rb`, writes `CHANGELOG.md`, creates a bare `vX.Y.Z` tag and a GitHub release, and then **pushes the gem to RubyGems**.
+
+Do **not** hand-edit `VERSION` or add a `CHANGELOG.md` entry — release-please owns both.
+
+The next version comes from PR titles, so the title is the only thing that matters: `feat:` gives a minor bump, `fix:` a patch, and a `!` suffix or a `BREAKING CHANGE:` footer gives a major. `.github/workflows/pr-title.yml` rejects titles release-please cannot parse.
+
+To force a specific version, land an empty commit carrying a `Release-As` footer. Put the release notes in that commit's body — a bare `chore: release X` produces an empty changelog entry, because the commits it would otherwise draw from get dropped if they are not conventional:
+
+```bash
+git commit --allow-empty -m "chore: release 1.0.0" -m "Release-As: 1.0.0"
+```
+
+### Publishing
+
+Publishing uses RubyGems **trusted publishing** (OIDC) — there is no API key stored anywhere. RubyGems pins the trust to the repository and the workflow filename, so **renaming `release-please.yml` breaks publishing** until the trusted publisher entry for the `paubox` gem is updated to match.
+
+If a push fails, re-run the failed `publish` job from the Actions tab. Note that a re-run uses the workflow file from the original commit, so it only helps when the fix is on the RubyGems side; a fix to the workflow itself needs a new release.
+
+Version numbers on RubyGems are effectively permanent — a yank is only possible within 72 hours and never frees the number for reuse.
+
+### Relationship to `paubox_rails`
+
+`paubox_rails` depends on this gem. Its gemspec constraint has to allow whatever major version is current here, so a major bump in `paubox` requires a matching `paubox_rails` release that widens the constraint. Release `paubox` first.