mailinator_client 1.0.7 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d662d2fd2a1518a00a7ac85cde34555f177765316ed9b388a7e8f9b0802fed4a
-  data.tar.gz: 86a12779d39d7ba6fc7ca06a4db6128a2244e1987d56a5d82424c98f2faac972
+  metadata.gz: 5b5772a96aa7fe7712e84ceadf80128142dd49f12feee1f3d41a2fe5d261f2eb
+  data.tar.gz: db22de067afd78c1b7f552f07ea379c52a40aa3a17693ad9181d4c5194c04aa9
 SHA512:
-  metadata.gz: 4e14a072c15f1704646c9896f7bb02d1f0ba80be1d808b878b0b2725ab41b3348c4fb570dcb95d1db846dde4b2701d52a2740114a233da7d927f27cf3234e18d
-  data.tar.gz: 45bd500f1c146e4f087a5c3008dc08e41fa79d870d67cda8735cb793d81d7901ed4e67fcc63b9e2350559be5545cc280619e8f21bb2f78e227092800a05001de
+  metadata.gz: 330f04a4ce7ffe53d8bfde1427fb914bf37403406454c3ac416284b8ecb6d7be102b5ef48bd521ccc4a38e6e684d24f39bbd44230ac22faa61034b8c3c2f1220
+  data.tar.gz: edf9ee55e65670d3c25613306e3741258c482576af9431572ad855e7e73abe1182df761514559cea68b530e1475409246e19cafc9ac03905f5677fc8652a3d9b

data/.agent/rules/tdd.md

@@ -0,0 +1,7 @@
+# TDD Protocol Rules
+- **Scope:** These rules apply ONLY when the goal is "Feature Implementation" or "Bug Fix."
+- **Passive Mode:** If I am manually editing a `*.test.*` or `*_test.*` file, switch to **Passive Mode**. 
+- **Passive Mode Behavior:** - Do not trigger the Red-Green-Refactor flow.
+    - Provide autocomplete and suggestions only. 
+    - Do not ask for "Approval" to proceed.
+- **Code Preservation:** Always enforced. Never delete implementation logic unless specifically told to "Clean up" or "Refactor."

data/.agent/tdd-flow/skill.md

@@ -0,0 +1,15 @@
+---
+name: tdd-flow
+description: Strict Red-Green-Refactor agentic workflow.
+triggers:
+  - user_mentions: ["$tdd", "implement", "build feature"]
+---
+
+## Workflow Steps
+1. **Red Phase:** Write ONE failing test. Explain the failure. **STOP.**
+- Requirement: All tests generated in this phase must follow the test expectations in `AGENTS.md` (specifically: no mocked endpoint integration tests, real HTTP requests, and semantic validation).
+2. **Green Phase:** Write the simplest possible implementation to pass that specific test. **STOP.**
+3. **Refactor Phase:** Suggest improvements to the implementation. Do not change tests.
+
+## Constraint
+- Do not jump to Step 2 until the user confirms Step 1 passes (or fails correctly).

data/.env.example

@@ -1,12 +1,25 @@
+# Mailinator API Configuration
+# Documentation: https://www.mailinator.com/documentation/docs/api/index.html
+# Visit https://www.mailinator.com/ to get your API token and configure domains
+
 MAILINATOR_TEST_API_TOKEN=
 MAILINATOR_TEST_INBOX=
 MAILINATOR_TEST_PHONE_NUMBER=
 MAILINATOR_TEST_MESSAGE_WITH_ATTACHMENT_ID=
-MAILINATOR_TEST_ATTACHMENT_ID=
+
+# Delete domain (WARNING: use with caution - only if you are 100% sure)
 MAILINATOR_TEST_DELETE_DOMAIN=
+
+# Webhook token configuration
+# This assumees you have multiple webhook tokens for different testing scenarios (e.g., private domain vs twilio). Adjust as needed based on your actual test setup.
 MAILINATOR_TEST_WEBHOOKTOKEN_PRIVATEDOMAIN=
 MAILINATOR_TEST_WEBHOOKTOKEN_CUSTOMSERVICE=
+
+# Authenticator configuration
 MAILINATOR_TEST_AUTH_SECRET=
 MAILINATOR_TEST_AUTH_ID=
+
+# Webhook configuration
+# Custom service might be something like "twilio" or "sendgrid"
 MAILINATOR_TEST_WEBHOOK_INBOX=
 MAILINATOR_TEST_WEBHOOK_CUSTOMSERVICE=

data/.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+# TDD Instructions for Copilot
+Refer to the project standards in AGENTS.md and the rules in .agent/rules/tdd.md.
+
+## Critical Constraints:
+1. **Red-Green-Refactor:** When I ask for a feature, write a failing test FIRST. Stop and wait for me to run it. Do not provide implementation until I approve the test.
+2. **No Deletions:** Never remove implementation code, even if a test is skipped.
+3. **Minimalism:** Write only the assertions I ask for. Do not add boilerplate "safety" assertions.

data/AGENTS.md

@@ -0,0 +1,17 @@
+All AI agents (Codex, Copilot, Antigravity) must follow this file and the rules in `.agent/rules/`.
+
+# Project Standards and Agent Behavior
+
+- **Language and tests:** This is a Ruby SDK tested with Minitest.
+- **Primary workflow:** Use the `.agent/tdd-flow` skill for feature implementation and bug fixes, subject to `.agent/rules/tdd.md`.
+- **Test style:** Write behavior-driven assertions. Endpoint integration tests must use real HTTP requests; do not mock them.
+- **Skipped tests:** Never infer or change implementation for a skipped test. Leave the underlying code untouched.
+- **OpenAPI source of truth:** Use the [Mailinator OpenAPI specification](https://raw.githubusercontent.com/manybrain/mailinatordocs/main/openapi/mailinator-api.yaml).
+- **Spec strictness:** Only assert behavior and properties explicitly defined by the OpenAPI specification. Do not invent validations. Flag ambiguities or gaps for human review.
+- **Request paths:** Resource wrappers use paths relative to `https://api.mailinator.com/api/v2`; do not include `/api/v2` or `/v2` in resource method paths.
+- **Gap-analysis changes:** Follow `docs/openapi-maintenance.md`. Present the implementation plan and wait for approval before changing SDK coverage.
+
+# Project References
+
+- `docs/openapi-maintenance.md` documents the SDK architecture, conventions, and OpenAPI gap-analysis workflow.
+- `ROADMAP.md` tracks known gaps and planned improvements.

data/CHANGELOG.md

@@ -5,10 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [1.1.1]
+
+### Security
+
+- Updated `httparty` to `>= 0.24, < 0.25` to address the SSRF and API-key leakage vulnerability in CVE-2025-68696.
+- Required `addressable >= 2.9, < 3.0` for development to address the URI-template ReDoS vulnerability in CVE-2026-35611.
+
+### Changed
+
+- Raised the minimum supported Ruby version from 2.1 to 2.7, matching the requirement of the fixed `httparty` release line.
+- Updated development dependency floors for `minitest`, `rake`, and `webmock`.
+
+## [1.1.0]
+
+### Changed
+
+- Added `messages.fetch_message_summary` for `GET /api/v2/domains/{domain}/messages/{messageId}/summary`.
+- Added `messages.fetch_message_text` for `GET /api/v2/domains/{domain}/messages/{messageId}/text`.
+- Added `messages.fetch_message_textplain` for `GET /api/v2/domains/{domain}/messages/{messageId}/textplain`.
+- Added `messages.fetch_message_texthtml` for `GET /api/v2/domains/{domain}/messages/{messageId}/texthtml`.
+- Added `messages.fetch_message_headers` for `GET /api/v2/domains/{domain}/messages/{messageId}/headers`.
+- Added `messages.stream_domain_messages` for `GET /api/v2/domains/{domain}/stream`.
+- Added `messages.stream_inbox_messages` for `GET /api/v2/domains/{domain}/stream/{inbox}`.
+- Removed `wait` query parameter from `messages.fetch_sms_message` because the endpoint does not support it.
+- Removed `wait` query parameter from `messages.fetch_inbox`.
+- Fixed `webhooks.private_webhook` to include the webhook payload in the request body.
+- Debugging and test updates.
+- Made attachment download tests derive attachment IDs from the attachments list, removing the need for `MAILINATOR_TEST_ATTACHMENT_ID`.
+- Documented that `GET /domains/{domain}/inboxes` is covered by `messages.fetch_inbox` with `inbox: "*"`.
+
+## [1.0.7]
 
 ### Added
 
+- Optional `delete` query parameter support to `messages.fetch_inbox_message`.
+- Inbox-list query parameters to `messages.fetch_sms_message` (`skip`, `limit`, `sort`, `decode_subject`, `cursor`, `full`, `delete`).
 - `.env.example` with Mailinator integration test variables.
 - Resource-scoped integration test files:
   - `test/authenticators_api_test.rb`
@@ -40,11 +72,6 @@ and this project aims to follow [Semantic Versioning](https://semver.org/).
   - Development: `minitest >= 5.25, < 7.0`, `rake >= 13.0, < 14.0`, `webmock >= 3.26, < 4.0`
 - Updated integration testing structure by splitting the previous monolithic `test/mailinator_client_api_test.rb`.
 - Added `.env` loading support in `test/test_helper.rb`.
-
-### Fixed
-
-- Added optional `delete` query parameter support to `messages.fetch_inbox_message`.
-- Added inbox-list query parameters to `messages.fetch_sms_message` (`skip`, `limit`, `sort`, `decode_subject`, `cursor`, `full`, `wait`, `delete`).
 - Hardened API error handling for non-JSON/empty error responses:
   - `MailinatorClient::ResponseError` now handles `nil` parsed responses safely.
   - `Client#request` now passes raw response body into `ResponseError`.

data/README.md

@@ -90,13 +90,19 @@ When the Mailinator API returns a unsuccessful response, an instance of Response
 
 ## Testing
 
-Run integration tests with real API Key.
+Run an individual integration test with a real API key:
 
 ```ruby
-ruby -I test test/mailinator_client_api_test.rb
+bundle exec ruby -Itest test/messages_api_test.rb
 ```
 
-Most of the tests require env variables with valid values. Visit tests source code and review `mailinator_client_api_test.rb` file. The more env variables you set, the more tests are run.
+Or run the full test suite:
+
+```ruby
+bundle exec rake test
+```
+
+Most integration tests require environment variables with valid values. Review the files under `test/` and `.env.example`; the tests whose required variables are unavailable will be skipped.
 
 * `MAILINATOR_TEST_API_TOKEN` - API tokens for authentication; basic requirement across many tests;see also https://manybrain.github.io/m8rdocs/#api-authentication
 * `MAILINATOR_TEST_INBOX` - some already existing inbox within the private domain

data/ROADMAP.md

@@ -1,24 +1,58 @@
 # Roadmap
 
-This document tracks planned improvements for the Mailinator Ruby client.
+This document tracks completed work, current gaps, and planned improvements for the Mailinator Ruby client.
 
-## Phase 1
+Gap analysis source of truth: Mailinator OpenAPI spec (`version: 2026-03-04`) from:
+`https://raw.githubusercontent.com/manybrain/mailinatordocs/main/openapi/mailinator-api.yaml`
 
-- [x] Add structural docs (`ROADMAP.md`, `CHANGELOG.md`, `AI_INSTRUCTIONS.md`, `EXAMPLEs.md`) - completed
-- [x] Update outdated dependencies (`rake` and `webmock` updated; `httparty` pinned to latest Ruby 2.6-compatible range)
-- [x] Update version number - completed (`1.0.7`)
-- [ ] Publish those changes (minor release)
+## Hardening (Phase 3)
 
-## Next
+- [ ] Produce and maintain endpoint coverage matrix (OpenAPI operationId -> SDK method)
+- [ ] Add CI check to detect future OpenAPI drift against SDK path+method map
+- [ ] Define policy for operations present in SDK but missing from spec:
+  - [ ] keep + mark deprecated
+  - [ ] keep + annotate as undocumented
+  - [ ] remove in next major release (requires explicit approval)
+- [ ] Define policy for flaky/500-prone integration flows (`messages.fetch_inbox` with `full`/`wait`, `webhooks.private_webhook`):
+  - [ ] gate by env vars and/or quarantine tags
+  - [ ] separate smoke and full integration suites
 
-- [ ] Mark deprecated endpoints as deprecated in code 
-    - Rules endpoints marked deprecated in code/docs
-    - `client.domains.create_domain` and `client.domains.delete_domain` marked deprecated in code/docs
-- [ ] Fix URL path inconsistencies between SDK and OpenAPI specification
+Webhooks (`lib/mailinator_client/webhooks.rb`):
+- [ ] Add domain-scoped webhook methods matching spec routes
+- [ ] Keep existing private-webhook methods for backward compatibility until deprecation decision is approved
+
+- [ ] Fix messages_api_test.rb. Split up into multiple files if needed to isolate new test cases and avoid timeouts. Assert on the body of the responses. 
+- [ ] Fix integration test bug: use `MAILINATOR_TEST_WEBHOOKTOKEN_CUSTOMSERVICE` for custom-service webhook tests
+- [ ] Add explicit assertions for custom-service webhook calls
+- [ ] Update README/docs links to current API reference and remove stale `manybrain.github.io/m8rdocs` links
+- [ ] Align docs arg naming with SDK (`domain`, `inbox`, `messageId`)
+
+
+## Completed (Phase 1)
+
+- [x] Add structural docs (`ROADMAP.md`, `CHANGELOG.md`, `docs/openapi-maintenance.md`, `EXAMPLES.md`)
+- [x] Update outdated dependencies (`rake` and `webmock`; `httparty` pinned to latest Ruby 2.6-compatible range)
+- [x] Update version number (`1.0.7`)
+- [x] Publish those changes (minor release)
 - [x] Add optional query parameter support:
-    - `messages.fetch_inbox_message` now supports optional `delete`
-    - `messages.fetch_sms_message` now supports inbox listing query params (`skip`, `limit`, `sort`, `decode_subject`, `cursor`, `full`, `wait`, `delete`)
-- [ ] Implement Streaming Messages endpoint (`/api/v2/domains/private/stream/` and inbox variant) with supported query params (`full`, `limit`, `throttleInterval`, `delete`)
-- [ ] Fix integration test bug: custom-service webhook tests use `@webhookTokenPrivateDomain` instead of `@webhookTokenCustomService`
-- [ ] Decide policy for flaky/500-prone integration flows (`messages.fetch_inbox` with `full`/`wait`, and `webhooks.private_webhook`) and gate or quarantine accordingly
-- [ ] Publish those changes
+  - `messages.fetch_inbox_message` supports optional `delete`
+  - `messages.fetch_sms_message` supports inbox listing query params (`skip`, `limit`, `sort`, `decode_subject`/`decodeSubject`, `cursor`, `full`, `wait`, `delete`)
+- [x] Mark deprecated endpoints as deprecated in code/docs:
+  - Rules endpoints
+  - `client.domains.create_domain` and `client.domains.delete_domain`
+
+## Completed (Phase 2)
+
+### Added Missing Spec Endpoints
+
+Messages (`lib/mailinator_client/messages.rb`):
+- [x] Add `fetch_message_summary` for `GET /domains/{domain}/messages/{messageId}/summary`
+- [x] Add `fetch_message_text` for `GET /domains/{domain}/messages/{messageId}/text`
+- [x] Add `fetch_message_text_plain` for `GET /domains/{domain}/messages/{messageId}/textplain`
+- [x] Add `fetch_message_text_html` for `GET /domains/{domain}/messages/{messageId}/texthtml`
+- [x] Add `fetch_message_headers` for `GET /domains/{domain}/messages/{messageId}/headers`
+- [x] Add `stream_domain_messages` for `GET /domains/{domain}/stream`
+- [x] Add `stream_inbox_messages` for `GET /domains/{domain}/stream/{inbox}`
+- [x] Add `list_domain_messages` for `GET /domains/{domain}/inboxes` (covered by `messages.fetch_inbox` with `inbox: "*"`)
+
+Note: We are intentionally not adding a separate SDK method for `GET /domains/{domain}/inboxes`. The existing `messages.fetch_inbox` with `inbox: "*"` provides equivalent domain-wide listing. Future gap analyses should treat this as covered.

data/docs/openapi-maintenance.md

@@ -0,0 +1,150 @@
+# OpenAPI Maintenance
+
+This document describes the Ruby client's architecture and the workflow for auditing it against the Mailinator OpenAPI specification.
+
+**OpenAPI specification:** [raw YAML](https://raw.githubusercontent.com/manybrain/mailinatordocs/main/openapi/mailinator-api.yaml) ([GitHub view](https://github.com/manybrain/mailinatordocs/blob/main/openapi/mailinator-api.yaml))
+
+## Codebase Structure
+
+The structure under `lib/mailinator_client/` reflects Mailinator API resource groups.
+
+- `lib/mailinator_client.rb` loads all components and delegates module-level calls to a singleton `Client`.
+- `lib/mailinator_client/client.rb` implements shared HTTP request behavior.
+- `authenticators.rb`, `domains.rb`, `messages.rb`, `rules.rb`, `stats.rb`, and `webhooks.rb` contain resource wrappers.
+- `utils.rb` normalizes input and query structures.
+- `error.rb` defines `ResponseError`.
+- `version.rb` defines gem version metadata used in user-agent headers.
+
+## Request and Response Conventions
+
+The client uses resource wrappers rather than per-operation request classes. Each resource method generally:
+
+1. Accepts a params hash and normalizes its keys with `Utils.symbolize_hash_keys`.
+2. Validates required keys with `ArgumentError`.
+3. Constructs a resource-relative `path`, `query`, and optional `body`.
+4. Calls `@client.request(...)`.
+
+`Client#request` joins resource-relative paths such as `/domains/example.com/inboxes/test` to the base URL `https://api.mailinator.com/api/v2`. Resource methods must not include `/api/v2` or `/v2` in their paths.
+
+Requests use HTTParty with JSON headers and optional authorization. Responses with status codes of 400 or higher raise `MailinatorClient::ResponseError`, which exposes the HTTP `code`, API error `type`, and response message.
+
+The SDK generally returns parsed Hash and Array values rather than typed model objects.
+
+## Gap Analysis Workflow
+
+Use this workflow to identify differences between the OpenAPI specification and SDK coverage.
+
+### 1. Read the OpenAPI Specification
+
+Retrieve and parse the raw YAML linked above. For every `paths` entry, record:
+
+- HTTP method
+- Full specification path
+- `operationId`
+- Tag
+- Path and query parameters
+- Request and response schemas relevant to implementation and tests
+
+### 2. Catalog the SDK
+
+For each resource wrapper under `lib/mailinator_client/`:
+
+1. Enumerate every public method that calls `@client.request(...)`.
+2. Record its HTTP method and resource-relative path template.
+3. Record the query parameters it sends.
+4. Note methods marked as deprecated.
+5. Map the resource file to the corresponding OpenAPI tag.
+
+### 3. Report Gaps
+
+Report these categories:
+
+#### Operations missing from the SDK
+
+List specification operations with no corresponding Ruby method.
+
+#### SDK operations missing from the specification
+
+List SDK methods whose resolved path and HTTP method have no specification entry. Note deprecated methods separately; flag other methods for clarification.
+
+#### URL construction mismatches
+
+The specification paths begin with `/api/v2/`, while SDK resource methods use paths relative to the client's `/api/v2` base URL. Flag:
+
+- A client base URL that does not end in `/api/v2`.
+- Resource paths containing `/api/v2` or `/v2`, which would duplicate or bypass the client base path.
+- Resolved SDK URLs that do not match the specification path.
+
+#### Parameter gaps
+
+For each matched operation, compare the SDK's path and query parameters with those declared by the specification.
+
+#### Domain-listing exception
+
+Treat `GET /api/v2/domains/{domain}/inboxes` as covered by `messages.fetch_inbox` with `inbox: "*"`. Do not report it as a missing SDK method.
+
+### 4. Propose a Plan
+
+Before changing code, present a plan containing:
+
+1. New methods, grouped by resource file.
+2. URL-construction fixes.
+3. Parameter additions.
+4. Deprecated or undocumented methods, without removing them unless explicitly approved.
+5. Response-shape expectations grounded in the specification.
+
+Wait for approval before implementing SDK coverage changes.
+
+### 5. Implement
+
+Follow the patterns already present in the matching resource wrapper:
+
+```ruby
+def get_example(params = {})
+  params = Utils.symbolize_hash_keys(params)
+  query_params = {}
+  headers = {}
+  body = nil
+
+  raise ArgumentError, "domain is required" unless params.has_key?(:domain)
+  raise ArgumentError, "id is required" unless params.has_key?(:id)
+
+  path = "/domains/#{params[:domain]}/examples/#{params[:id]}"
+
+  @client.request(
+    method: :get,
+    path: path,
+    query: query_params,
+    headers: headers,
+    body: body
+  )
+end
+```
+
+Keep methods in the appropriate resource file, use snake_case method names, preserve the parameter naming conventions of that file, and document optional parameters.
+
+## Verification
+
+Run the complete suite:
+
+```sh
+bundle exec rake test
+```
+
+Run a focused test when appropriate:
+
+```sh
+bundle exec ruby -Itest test/messages_query_params_test.rb
+```
+
+Integration tests load local values from `.env` and skip when their required variables are missing. For each changed operation, verify that the resolved URL and query parameters exactly match the specification. Assertions must test response semantics and only fields guaranteed by the specification.
+
+## Additional Conventions
+
+| Convention | Detail |
+|---|---|
+| Version source | `MailinatorClient::VERSION` in `lib/mailinator_client/version.rb`, referenced by the gemspec and user-agent string |
+| Authorization | `Client#request` adds the `Authorization` header when an auth token is provided |
+| No-token requests | Supported for flows such as some webhook operations |
+| Deprecation | Use Ruby/YARD comments and reflect the status in user-facing documentation |
+| Entrypoint | `lib/mailinator_client.rb` requires resource and support files and delegates to the singleton client |

data/lib/mailinator_client/client.rb

@@ -6,7 +6,7 @@ module MailinatorClient
   #
   # User API for accessing Mailinator data
   class Client
-    #attr_reader :auth_token, :url
+    attr_reader :auth_token, :url
 
     def initialize(options = {})
       @auth_token = options.fetch(:auth_token, nil)
@@ -47,6 +47,13 @@ module MailinatorClient
       headers["Authorization"]  = @auth_token if @auth_token
       path = @url + options.fetch(:path, "")
 
+      debug_request = ENV["MAILINATOR_DEBUG_REQUESTS"].to_s.strip.downcase
+      if debug_request == "1" || debug_request == "true"
+        warn "[mailinator] #{method.to_s.upcase} #{path}"
+        warn "[mailinator] headers=#{headers}"
+        warn "[mailinator] query=#{Utils.fix_query_arrays(options[:query])}"
+      end
+
       response = HTTParty.send(method, path,
         query: Utils.fix_query_arrays(options[:query]),
         body: options[:body] && options[:body].to_json(),
@@ -54,6 +61,11 @@ module MailinatorClient
         timeout: 125
       )
 
+      if debug_request == "1" || debug_request == "true"
+        warn "[mailinator] response_code=#{response.code}"
+        warn "[mailinator] response_body=#{response.body}"
+      end
+
       result = response.parsed_response
       if response.code >= 400
         raise ResponseError.new(response.code, result, response.body)

data/lib/mailinator_client/domains.rb

@@ -39,7 +39,7 @@ module MailinatorClient
     # access token to call this action.
     #
     # Parameters:
-    # *  {string} domainId - The Domain name or the Domain id
+    # *  {string} domainId - The Domain name or simply 'private'
     #
     # Responses:
     # *  Domain (https://manybrain.github.io/m8rdocs/#get-domain)
@@ -100,7 +100,7 @@ module MailinatorClient
     # access token to call this action.
     #
     # Parameters:
-    # *  {string} domainId - The Domain name or the Domain id
+    # *  {string} domainId - The Domain name or simply 'private'
     #
     # Responses:
     # *  Status (https://manybrain.github.io/m8rdocs/#delete-domain)