Fix #84

[narekhovhannisyan]

Motivation

Fixed the type mismatch between Mailtrap's template platform and the Node.js SDK. The Mailtrap template platform supports JSON attributes with arrays and nested objects, but the SDK's TemplateVariables type only allowed primitive values (string | number | boolean). This prevented users from using the auto-generated JSON from the Mailtrap template platform directly, forcing them to cast to any as a workaround. Fixes #84

Changes

• Added recursive TemplateValue type definition in src/types/mailtrap.ts that supports:
  • Primitive values: string | number | boolean
  • Arrays: TemplateValue[]
  • Nested objects: { [key: string]: TemplateValue }
• Updated TemplateVariables type to use Record<string, TemplateValue> instead of Record<string, string | number | boolean>
• Updated TemplateBatchSendBase.template_variables from Record<string, string> to TemplateVariables in src/types/mailtrap.ts
• Updated BatchSendRequest.requests[].template_variables from Record<string, string> to TemplateVariables in src/types/mailtrap.ts
• Updated MailtrapMailOptions.templateVariables from Record<string, string | number | boolean> to TemplateVariables in src/types/transport.ts

How to test

• Run npm run lint:tsc to verify TypeScript compilation passes without errors
• Run npm test to ensure all 238 existing tests pass (backward compatibility)
• Create a template with nested objects in Mailtrap platform and verify the SDK accepts it without type errors
• Test simple values still work: template_variables: { user_name: "John", age: 30 }
• Test nested objects: template_variables: { x: { y: "value", z: 123 } }
• Test arrays: template_variables: { tags: ["tag1", "tag2"] }
• Test complex nested structures: template_variables: { order: { id: "123", items: [{ name: "Product", price: 29.99 }] } }

Summary by CodeRabbit

• New Features
  • Template variables now support nested objects and arrays for complex and flexible template data structures.

[coderabbitai]

Walkthrough

Introduces a recursive TemplateValue type to support nested objects and arrays in template variables. Updates TemplateVariables across mailtrap and transport type definitions from flat primitives to use the new recursive type, enabling complex template variable structures.

Changes

Cohort / File(s)	Summary
Type Definition Updates src/types/mailtrap.ts	Introduces new recursive TemplateValue type (string | number | boolean | TemplateValue[] | { [key: string]: TemplateValue }). Updates exported TemplateVariables to use TemplateValue instead of flat primitives. Updates TemplateBatchSendBase and BatchSendRequest fields to use TemplateVariables type.
Transport Type Alignment src/types/transport.ts	Updates MailtrapMailOptions interface templateVariables property to use TemplateVariables type instead of inline Record<string, string | number | boolean>.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Review the new recursive TemplateValue type definition for correctness and any potential issues with circular reference handling
• Verify type propagation through all affected interface fields (TemplateBatchSendBase, BatchSendRequest, MailtrapMailOptions)
• Confirm backward compatibility implications for existing API consumers

Possibly related issues

• Mismatch between Mailtrap template platform and Node.js SDK template variable types #84: Directly addresses the mismatch between Mailtrap template platform and Node.js SDK template variable types by implementing the exact recursive TemplateValue and updated TemplateVariables types proposed in the issue

Poem

🐰 Nested templates now flourish with glee,
Objects and arrays dance wild and free,
Recursion's magic, no flat anymore—
Template variables unlock a new door! 🎉

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Title Check	❓ Inconclusive	The title "Fix #84" is vague and generic in that it only references an issue number without describing the actual change. While the title is technically related to the changeset since issue #84 is being fixed, it does not convey meaningful information about what the primary change accomplishes. A reviewer scanning the git history would not understand that this PR adds support for nested objects and arrays in template variables without examining the issue or description. The title lacks descriptive content that would clarify the nature of the fix.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues Check	✅ Passed	The PR directly implements all coding requirements from issue #84. The changes introduce the exact recursive TemplateValue type proposed in the issue (string | number | boolean | TemplateValue[] | { [key: string]: TemplateValue }), update TemplateVariables to Record<string, TemplateValue>, and propagate this type throughout the affected API surfaces in both src/types/mailtrap.ts and src/types/transport.ts. The PR's changes match the stated objectives of broadening type definitions to support nested arrays and objects, enabling the SDK to accept auto-generated JSON from the Mailtrap template platform without requiring any type casting.
Out of Scope Changes Check	✅ Passed	All changes in this PR are directly scoped to the objectives defined in issue #84. The modifications are limited to type definitions in src/types/mailtrap.ts and src/types/transport.ts, which are the files responsible for template variable type definitions. No unrelated changes or refactoring have been introduced, and no functional logic modifications exist outside the scope of enabling recursive type support for template variables as requested in the linked issue.
Description Check	✅ Passed	The pull request description follows the repository's template structure and includes all required sections. The Motivation section clearly explains the type mismatch problem and user impact. The Changes section provides detailed bullet points documenting each modification across both files. The How to Test section includes comprehensive test cases with checkboxes covering TypeScript compilation, backward compatibility, and specific nested structure scenarios. While the Images and GIFs section is not included, it is not applicable to this type-definition change and appears to be an optional template element.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-#84

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

src/types/mailtrap.ts (3)

29-36: Good recursive model; consider JSON null and readonly support.

The recursive union looks right and solves #84. Two optional enhancements:

• Include null (JSON supports it and templates may emit it).
• Accept readonly arrays/objects to ease usage with as const.

Example minimal tweak:

 export type TemplateValue =
   | string
   | number
   | boolean
+  | null
   | TemplateValue[]
-  | { [key: string]: TemplateValue };
+  | { [key: string]: TemplateValue };
+// If desired, a more permissive variant:
+// | ReadonlyArray<TemplateValue>
+// | { readonly [key: string]: TemplateValue };

If the platform never returns null, feel free to skip it. Otherwise, adding null avoids downstream casts. Can you confirm expected payloads?

---

111-112: Type alignment: ✅ Also, unify custom_variables types for consistency.

Switching to TemplateVariables here is correct. Noted inconsistency: several places still use Record<string, string> for custom_variables while CustomVariables is broader.

Unify to the existing alias:

 interface TemplateBatchSendBase extends Omit<Mail, "to"> {
   from: BaseAddress;
   template_uuid: string; // Required for template usage
   template_variables?: TemplateVariables;
-  custom_variables?: Record<string, string>;
+  custom_variables?: CustomVariables;
   reply_to?: BaseAddress;
 }

Same applies to InlineBatchSendBase (Line 103) and BatchSendRequest.requests (Line 129). Keeps the surface coherent and avoids silent narrowing.

---

128-129: Unify batch request custom_variables to use CustomVariables type for consistency.

The CustomVariables type is already defined in the file as Record<string, string | number | boolean> and is used in the main Mail type. Applying the same type to BatchSendRequest.requests.custom_variables (line 129) ensures consistent typing across the API and enables complex variable values in per-request overrides.

Note: The same type inconsistency exists in InlineBatchSendBase (line 103) and TemplateBatchSendBase (line 112), which also use Record<string, string> and should be unified for complete API consistency.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 70796f4 and 675a6e6.

📒 Files selected for processing (2)

• src/types/mailtrap.ts (3 hunks)
• src/types/transport.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/types/transport.ts (1)

src/types/mailtrap.ts (1)

• TemplateVariables (36-36)

🔇 Additional comments (1)

src/types/transport.ts (1)

39-39: LGTM: templateVariables now matches the canonical TemplateVariables type.

Verification confirmed that TemplateVariables is exported from src/types/mailtrap.ts and properly re-exported to consumers via the main entry point through export * from "./types/mailtrap" in src/index.ts. This aligns transport options with the recursive type definition and removes the need for any casts. No breaking change expected.