feat(email): add bounded timeouts for outbound email providers

[telivity-otaip]

Summary

Adds hard send deadlines for outbound guest email providers. Slow or hung SMTP/HTTP transports return outcomeUnknown at the deadline instead of blocking callers indefinitely.

Changes

• New bounded-email-transport helper with configurable timeoutMs
• HTTP (Mailgun, SendGrid, SES): hard outer deadline around fetch and response-body consumption — returns at timeoutMs even when abort is ignored; detached in-flight work gets a rejection handler to prevent unhandled rejections
• SMTP: hard-close owned pool sockets at deadline via Promise.race; cleanup attached to sendMail settlement (scheduled late close is not cancelled from finally)
• EmailSendOptions extended across SMTP, SES, Mailgun, and SendGrid providers
• EmailService auto-retries definitely-not-sent failures only (default 3 attempts); never auto-retries outcomeUnknown
• SMTP integration tests for bounded greeting stall, active-transaction hard-close, and late-close behavior

Public contract (delivery / retry / correlation)

Every send returns one of three outcomes via EmailResult.status:

Status	Meaning	Auto-retry?
sent	Provider confirmed acceptance	N/A (done)
notSent	Definitely not accepted	Yes (safe)
outcomeUnknown	May have been accepted but response was lost	No — record for reconciliation / manual resend

EmailMessage optionally accepts correlation metadata (not deduplication guarantees):

• idempotencyKey — forwarded to providers as custom metadata (e.g. Mailgun v:haip-idempotency-key, SendGrid custom_args). Useful for log/trace correlation across retries. Not an exactly-once guarantee in Mailgun, SendGrid, SES, or SMTP.
• messageId — stable RFC Message-ID reused across retries when the provider supports setting it. Does not prevent duplicate delivery.

How to test

pnpm --filter @telivityhaip/api exec vitest run src/modules/agent/guest-comms/

Contributor credit

@agustinjch

[telivity-otaip]

@agustinjch

[agustinjch]

Thanks for splitting this out. I checked the PR at ddfc90e; the build/typecheck path and the focused guest-comms tests pass.

Before I confirm the merge, I think we should address these points:

1. apps/api/package.json and pnpm-lock.yaml include @telivityhaip/booking-requests, including a lockfile importer for packages/booking-requests. That package is not part of this PR and belongs to feat(booking-requests): add optional booking-requests module #348, so feat(email): add bounded timeouts for outbound email providers #349 is carrying unrelated package state. Please remove those booking-request entries from this PR while keeping the justified nodemailer dependency.
2. The PR says transports fail fast instead of blocking indefinitely, but boundedEmailFetch() aborts at the deadline and then continues awaiting fetch/body settlement; SMTP similarly closes the owned transport but still awaits sendMail(). If a transport does not settle after cancellation, the promise remains pending. Either make the settlement itself truly bounded or document this as a cooperative cancellation deadline and cover that contract explicitly.
3. The stable idempotencyKey / messageId provider metadata is useful for retry safety, but it is additional public behavior beyond the timeout summary. Please mention it in the PR description so the contract is clear.

Non-blocking: the SMTP hard-close walks Nodemailer private internals (transporter._connections, _socket). The integration tests reduce the risk, but it would be good to isolate/document that version-specific adapter.

Once the unrelated package entries and timeout contract are cleaned up, I am happy to re-review this first.

[telivity-otaip]

Thanks for the review — all four points addressed on bcd63ca (current head).

1. @telivityhaip/booking-requests removed
Dropped from apps/api/package.json and pnpm-lock.yaml. This PR only adds the justified nodemailer dependency for SMTP. No booking-requests package state.

2. Timeout contract — cooperative deadline, not “fail fast”
We did not leave hung promises pending:

• HTTP: boundedEmailFetch() aborts at timeoutMs but waits for settlement before returning outcomeUnknown, so we don’t mark a delivery retry-eligible while the original request may still complete. Documented in bounded-email-transport.ts and EmailSendOptions.
• SMTP: send() uses Promise.race — at the deadline we hard-close the owned pool and return outcomeUnknown even if sendMail is still settling.

PR description updated to say cooperative deadline instead of “fail fast.” Guest-comms tests still pass.

3. idempotencyKey / messageId
Documented in the PR description under Public contract (retry / idempotency) and in email-provider.interface.ts.

4. Nodemailer internals (non-blocking)
closeOwnedTransport documents that it uses version-specific pool/socket fields (_connections, _socket), covered by smtp-email.provider.spec.ts.

Ready for your re-review when you have a minute.

[agustinjch]

@telivity-otaip Thanks for the updates. I think the remaining issues are all fixable without removing retries altogether.

For email delivery, the important distinction is between:

• sent: the provider confirmed acceptance
• notSent: we know it was not accepted, so an automatic retry is safe
• outcomeUnknown: it may have been accepted but the response was lost, so an automatic retry can duplicate the guest email

The current provider metadata and reused Message-ID are useful correlation keys, but they do not provide actual deduplication in Mailgun, SendGrid, SES, or SMTP. My recommendation is therefore to retain automatic retries for definitely-not-sent failures, but not automatically retry outcomeUnknown. Record that state for reconciliation or an explicit manual resend, and describe the idempotency key as correlation rather than an exactly-once guarantee.

Two smaller implementation fixes remain:

1. Put a hard outer deadline around the entire HTTP operation, including response-body consumption. The operation should return at the deadline even if the underlying transport ignores abort; attach a background rejection handler so the detached work cannot produce an unhandled rejection.
2. For SMTP, close on timeout and attach cleanup to the eventual settlement of sendMailPromise. The scheduled late close should not be cancelled immediately from finally.

With those changes, the retry behavior remains useful while the contract becomes accurate and guest emails are not automatically duplicated after ambiguous outcomes.

[telivity-otaip]

Thanks @agustinjch — all points from your latest review are addressed on 72e3aff.

1. Delivery contract (sent / notSent / outcomeUnknown)

• EmailResult.status is now the canonical field (sent boolean kept as a convenience mirror).
• Providers return sent, notSent, or outcomeUnknown via shared helpers in bounded-email-transport.ts.
• EmailService auto-retries notSent only (default 3 attempts); outcomeUnknown is logged and not auto-retried.

2. Correlation vs deduplication

• idempotencyKey / messageId documented as correlation metadata only — not exactly-once guarantees in Mailgun, SendGrid, SES, or SMTP.
• PR description updated accordingly.

3. HTTP hard outer deadline

• boundedEmailFetch() races the full fetch+body work against a hard timer; returns at deadline even when abort is ignored.
• Detached in-flight work gets .catch(() => undefined) so no unhandled rejection.
• Tests cover hanging fetch and hanging response body (fake timers).

4. SMTP late-close fix

• On timeout: close transport + schedule setImmediate re-close; no clearImmediate in finally.
• Cleanup attached to sendMailPromise.finally() instead.
• New spec asserts clearImmediate is never called.

Tests: pnpm --filter @telivityhaip/api exec vitest run src/modules/agent/guest-comms/ — 54 passed.

Ready for re-review when you have a minute.