mailinator_client 1.0.7 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d662d2fd2a1518a00a7ac85cde34555f177765316ed9b388a7e8f9b0802fed4a
-  data.tar.gz: 86a12779d39d7ba6fc7ca06a4db6128a2244e1987d56a5d82424c98f2faac972
+  metadata.gz: 842259c780481a4557f43335ae76aee7983c5d61f4c191e5513c73a8c513653d
+  data.tar.gz: c6581dbcda2131ac8673899a28589c7e19c4acbd52127835a6de24aff0a7e1f8
 SHA512:
-  metadata.gz: 4e14a072c15f1704646c9896f7bb02d1f0ba80be1d808b878b0b2725ab41b3348c4fb570dcb95d1db846dde4b2701d52a2740114a233da7d927f27cf3234e18d
-  data.tar.gz: 45bd500f1c146e4f087a5c3008dc08e41fa79d870d67cda8735cb793d81d7901ed4e67fcc63b9e2350559be5545cc280619e8f21bb2f78e227092800a05001de
+  metadata.gz: 44ff3ba0a414f96920f357d0aa9c069f3bb957dedc7fba2a1d586f79f490867c99a8a2654575b7797a3249c79e9c51fadb0ea67e1034f54e976a49fe805ce86d
+  data.tar.gz: 4ca92063bd2a63fb5e97cf0b60d54d849c4e766f282ab06c89df4860d74c6716aca3a02e2cc92c490a57c63dc9e431d8cb154a78a353e066a38b499fb41f74ba

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 adhere to the Test Expectations defined in the ai_instruction file (specifically: No mocking, 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,9 @@
+All AI agents (Codex, Copilot, Antigravity) must adhere to the rules defined in .agent/rules/ and this file.
+
+# Project Standards & Agent Behavior
+
+- **Primary Workflow:** We use the `tdd-flow` skill for all new feature development.
+- **Test Style:** Focus on behavior-driven assertions. No mocking.
+- **Anti-Pattern Guardrail:** Do not "hallucinate" implementation for skipped tests. If a test is ignored, the underlying code must remain untouched.
+- **Language/Framework:** Ruby with RSpec for testing.
+- **Spec-Strictness:** When generating tests for the SDK, only assert properties explicitly defined in the OpenAPI specification provided. Do not invent "common sense" validations that are not codified in the schema. Call out any ambiguities or gaps in the spec for human review instead of making assumptions.

data/AI_INSTRUCTIONS.md

@@ -2,7 +2,7 @@
 
 This document explains the relationship between this Ruby client and the Mailinator OpenAPI specification.
 
-**OpenAPI Specification:** [https://github.com/manybrain/mailinatordocs/blob/main/openapi/mailinator-api.yaml](https://github.com/manybrain/mailinatordocs/blob/main/openapi/mailinator-api.yaml)
+**OpenAPI Specification:** [Found on GitHub](https://github.com/manybrain/mailinatordocs/blob/main/openapi/mailinator-api.yaml)
 
 ## Codebase Structure
 
@@ -85,7 +85,7 @@ Extract every `paths` entry. For each path, record:
 - The tag (maps to the SDK module directory)
 - All query parameters defined under `parameters`
 
-### Step 2 — Catalogue the SDK
+### Step 2 — Catalog the SDK
 
 For each resource file under `lib/mailinator_client/` (`messages.rb`, `domains.rb`, `rules.rb`, etc.):
 1. Enumerate every public method that issues `@client.request(...)`.
@@ -116,6 +116,9 @@ Compare the base path used by each SDK method against the spec.
 #### D. Query parameter gaps
 For each existing SDK method, compare sent query parameters against the spec's declared parameters for that operation. List any missing parameters.
 
+#### Exception — Domain Listing
+The OpenAPI operation `GET /api/v2/domains/{domain}/inboxes` (list domain messages) is considered **covered** by `messages.fetch_inbox` when called with `inbox: "*"`. Do not treat this as a missing SDK method in future gap analyses.
+
 ### Step 4 — Build a Plan
 
 Before making any changes, write out a plan that includes:
@@ -192,3 +195,11 @@ After implementing:
 | No-token requests | Supported by instantiating `Client` without `auth_token` (used by some webhook flows). |
 | Deprecation marker | Use Ruby/YARD style deprecation comments near method definitions and reflect in README/docs. |
 | Entrypoint loading | `lib/mailinator_client.rb` requires resource/support files and delegates module methods to singleton client. |
+
+### Test Expectations
+
+- Integration tests should exercise real HTTP requests to Mailinator endpoints. Do not use request-mocking tools (for example, `WebMock.stub_request`) for endpoint coverage tests.
+- Assertions must validate response semantics, not just existence. Prefer checking:
+  - expected HTTP success behavior (or explicit failure with returned status code),
+  - expected JSON shape (required keys),
+  - important field-level values (for example, IDs or arrays) relevant to the endpoint contract.

data/CHANGELOG.md

@@ -5,10 +5,30 @@ 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.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 +60,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,12 +90,18 @@ When the Mailinator API returns a unsuccessful response, an instance of Response
 
 ## Testing
 
-Run integration tests with real API Key.
+Run individual integration tests with real API Key.
 
 ```ruby
 ruby -I test test/mailinator_client_api_test.rb
 ```
 
+OR run them all:
+
+```ruby
+bundle exec rake test
+```
+
 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.
 
 * `MAILINATOR_TEST_API_TOKEN` - API tokens for authentication; basic requirement across many tests;see also https://manybrain.github.io/m8rdocs/#api-authentication

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`, `AI_INSTRUCTIONS.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/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)