Skip to content

fix(types)!: align send() response with real server contract ({ emails: [...], timestamp })#3

Merged
AminDhouib merged 1 commit into
mainfrom
fix/send-response-contract
Jul 18, 2026
Merged

fix(types)!: align send() response with real server contract ({ emails: [...], timestamp })#3
AminDhouib merged 1 commit into
mainfrom
fix/send-response-contract

Conversation

@AminDhouib

Copy link
Copy Markdown
Member

The drift

POST /api/emails has always returned:

{ "success": true, "data": { "emails": [{ "contact": { "id": "", "email": "" }, "email": "<email-record-uuid>" }], "timestamp": "" } }

i.e. data.emails has one entry per recipient (an array to fans out to several), and each entry is { contact: { id, email }, email } where the nested email is the id of the queued email record for that recipient.

The OpenAPI spec and this SDK's generated types instead declared a flat { contact, email, timestamp } and typed emails.send() as Promise<SendEmailData | SendEmailData[]>. So every TS user doing const { email } = await sendly.emails.send(...) got undefined.

Decision

The platform owner ruled the server shape canonical. The monorepo OpenAPI spec is already fixed and merged (DevinoSolutions/sendly main@ee407438). This PR regenerates the SDK from that corrected contract. Runtime SDK behavior was already correct — send() returns the response's unwrapped data verbatim — so only the types / spec / docs were stale.

What changed

  • openapi.json — byte-copied from the corrected monorepo spec. SendEmailData is now { emails: SendEmailRecipientResult[], timestamp }; SendEmailRecipientResult = { contact: { id, email }, email }; SendEmailResponse.data = SendEmailData (the old single | array union is gone). Batch keeps BatchSendResponse / BatchEntryResult (rows'' data = SendEmailData).
  • src/types.generated.ts — regenerated via pnpm build:types (never hand-edited).
  • src/resources/emails.tssend() return type is now the single corrected SendEmailData (was SendEmailData | SendEmailData[]); JSDoc updated.
  • src/__tests__/emails.test.ts — send tests now genuinely assert the unwrapped { emails: [...], timestamp } shape.
  • README.md — send example shows reading result.emails[0].email + result.timestamp.
  • CHANGELOG.md — 0.2.0 entry: breaking type change, runtime unchanged, spec corrected to match server.
  • package.json + SDK_VERSION — 0.1.0 → 0.2.0 (breaking type change; not yet published to npm).
  • dist/ — rebuilt and committed (the consuming monorepo pins the GitHub tarball and uses dist directly).

Verification (all run locally, no --no-verify)

  • pnpm lint (--max-warnings=0) — pass
  • pnpm check-types — pass
  • pnpm test — 74 passed (11 files)
  • pnpm build — regenerated committed dist/
  • pnpm format:check — pass
  • dist/index.d.ts confirmed: send(body, opts?): Promise<SendEmailData> with SendEmailData = { emails: SendEmailRecipientResult[]; timestamp }; no remaining SendEmailData | SendEmailData[] union.

pnpm check-spec-drift will WARN vs live prod (prod not yet redeployed) — expected and non-blocking.

…t ({ emails: [...], timestamp })

POST /api/emails has always returned
`data = { emails: [{ contact: { id, email }, email }], timestamp }` — one
`emails` entry per recipient (an array `to` fans out to several), where the
nested `email` is the id of the queued email record. The OpenAPI spec and the
generated types instead declared a FLAT `{ contact, email, timestamp }` and
typed `emails.send()` as `SendEmailData | SendEmailData[]`, so every caller
doing `const { email } = await sendly.emails.send(...)` got `undefined`.

The platform owner ruled the server shape canonical; the monorepo spec is
already corrected (DevinoSolutions/sendly main@ee407438). This regenerates the
SDK from that corrected `openapi.json`:

- openapi.json: byte-copied from the corrected monorepo spec
  (SendEmailData -> { emails: SendEmailRecipientResult[], timestamp };
   SendEmailResponse.data -> SendEmailData; the single|array union is gone).
- types.generated.ts: regenerated via `pnpm build:types`.
- emails.send(): return type is now the single corrected `SendEmailData`.
- tests: assert send unwraps to `{ emails: [...], timestamp }`.
- README / CHANGELOG: document the corrected shape and the breaking type change.
- package.json + SDK_VERSION: 0.1.0 -> 0.2.0.
- dist/: rebuilt (the consuming monorepo pins the GitHub tarball / uses dist).

Runtime was already correct — `send()` returns the response's unwrapped `data`
verbatim — so this is a TYPE-only breaking change; no runtime behavior changed.
@AminDhouib
AminDhouib merged commit 48f1d42 into main Jul 18, 2026
1 check passed
@AminDhouib
AminDhouib deleted the fix/send-response-contract branch July 18, 2026 21:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant