feat: exception control, timeouts, and type-level tests

Network failures (connection refused, DNS) are now wrapped in
SendDockError with status 0 and retried instead of leaking a raw
TypeError; a 2xx with a non-JSON body throws a typed error instead of a
SyntaxError; every request carries an abort signal with a configurable
timeout (default 30s) so a hung connection cannot block forever; a
hostile Retry-After is capped at 60s.

Tests grow from 14 to 34: constructor validation, network retry and
timeout paths, malformed server responses, retry exhaustion, plus a
compile-time contract suite (vitest typecheck) asserting that invalid
send/batch/broadcast/import bodies fail to compile and response unions
narrow correctly.

Author: JuansesDev

src/client.ts

@@ -20,6 +20,7 @@ export class SendDock {
   private readonly apiKey: string
   private readonly projectId: string
   private readonly maxRetries: number
+  private readonly timeoutMs: number
   private readonly fetchImpl: typeof globalThis.fetch
 
   constructor(options: SendDockOptions) {
@@ -30,6 +31,7 @@ export class SendDock {
     this.apiKey = options.apiKey
     this.projectId = options.projectId
     this.maxRetries = options.maxRetries ?? 2
+    this.timeoutMs = options.timeoutMs ?? 30_000
     this.fetchImpl = options.fetch ?? globalThis.fetch
   }
 
@@ -72,10 +74,31 @@ export class SendDock {
 
     let lastError: SendDockError | undefined
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      const response = await this.fetchImpl(url, { method, headers, body: payload })
+      let response: Response
+      try {
+        response = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: payload,
+          signal: AbortSignal.timeout(this.timeoutMs),
+        })
+      } catch (cause) {
+        lastError = networkError(cause, this.timeoutMs)
+        if (attempt === this.maxRetries) throw lastError
+        await sleep(500 * 2 ** attempt)
+        continue
+      }
 
       if (response.ok) {
-        return (await response.json()) as T
+        try {
+          return (await response.json()) as T
+        } catch (cause) {
+          throw new SendDockError(
+            response.status,
+            'the server returned a non-JSON response body',
+            cause,
+          )
+        }
       }
 
       const error = await this.toError(response)
@@ -104,6 +127,14 @@ export class SendDock {
   }
 }
 
+function networkError(cause: unknown, timeoutMs: number): SendDockError {
+  if (cause instanceof DOMException && cause.name === 'TimeoutError') {
+    return new SendDockError(0, `request timed out after ${timeoutMs}ms`, cause)
+  }
+  const detail = cause instanceof Error ? cause.message : String(cause)
+  return new SendDockError(0, `network error: ${detail}`, cause)
+}
+
 function retryDelayMs(response: Response, attempt: number): number {
   const retryAfter = Number(response.headers.get('Retry-After'))
   if (Number.isFinite(retryAfter) && retryAfter > 0) {

src/error.ts

@@ -17,6 +17,10 @@ export class SendDockError extends Error {
     return this.status === 429
   }
 
+  get isNetworkError(): boolean {
+    return this.status === 0
+  }
+
   get isNotFound(): boolean {
     return this.status === 404
   }

src/exceptions.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from 'vitest'
+import { SendDock } from './client.js'
+import { SendDockError } from './error.js'
+
+function jsonResponse(status: number, body: unknown, headers?: Record<string, string>) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json', ...headers },
+  })
+}
+
+function makeClient(fetchImpl: typeof fetch, maxRetries = 0) {
+  return new SendDock({
+    baseUrl: 'https://mail.example.com',
+    apiKey: 'sk_test_123',
+    projectId: 'proj-1',
+    fetch: fetchImpl,
+    maxRetries,
+  })
+}
+
+describe('constructor validation', () => {
+  it.each([
+    ['baseUrl', { baseUrl: '', apiKey: 'sk', projectId: 'p' }],
+    ['apiKey', { baseUrl: 'https://x.com', apiKey: '', projectId: 'p' }],
+    ['projectId', { baseUrl: 'https://x.com', apiKey: 'sk', projectId: '' }],
+  ])('throws synchronously when %s is missing', (_field, opts) => {
+    expect(() => new SendDock(opts)).toThrow()
+  })
+
+  it('normalizes a trailing slash in baseUrl', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, {}))
+    const sd = new SendDock({
+      baseUrl: 'https://mail.example.com///',
+      apiKey: 'sk',
+      projectId: 'p',
+      fetch: fetchMock,
+    })
+    await sd.stats()
+    expect(fetchMock.mock.calls[0]![0]).toBe(
+      'https://mail.example.com/api/v1/projects/p/stats',
+    )
+  })
+})
+
+describe('network failures', () => {
+  it('wraps a connection failure in SendDockError instead of leaking a raw TypeError', async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new TypeError('fetch failed'))
+    const sd = makeClient(fetchMock)
+
+    const err = await sd.stats().catch((e: unknown) => e)
+
+    expect(err).toBeInstanceOf(SendDockError)
+    expect((err as SendDockError).status).toBe(0)
+    expect((err as SendDockError).isNetworkError).toBe(true)
+    expect((err as SendDockError).message).toContain('fetch failed')
+  })
+
+  it('retries network failures before giving up', async () => {
+    vi.useFakeTimers()
+    try {
+      const fetchMock = vi
+        .fn()
+        .mockRejectedValueOnce(new TypeError('fetch failed'))
+        .mockResolvedValueOnce(jsonResponse(200, { message: 'sent' }))
+      const sd = makeClient(fetchMock, 2)
+
+      const pending = sd.send({ to: 'a@example.com', template_id: 't-1' })
+      await vi.advanceTimersByTimeAsync(500)
+
+      expect(await pending).toEqual({ message: 'sent' })
+      expect(fetchMock).toHaveBeenCalledTimes(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('reports a timeout as a SendDockError naming the limit', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockRejectedValue(new DOMException('signal timed out', 'TimeoutError'))
+    const sd = makeClient(fetchMock)
+
+    const err = await sd.stats().catch((e: unknown) => e)
+
+    expect(err).toBeInstanceOf(SendDockError)
+    expect((err as SendDockError).message).toBe('request timed out after 30000ms')
+  })
+
+  it('passes an abort signal so hung requests cannot hang forever', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(200, {}))
+    const sd = makeClient(fetchMock)
+
+    await sd.stats()
+
+    const [, init] = fetchMock.mock.calls[0]!
+    expect(init.signal).toBeInstanceOf(AbortSignal)
+  })
+})
+
+describe('malformed server responses', () => {
+  it('wraps invalid JSON on a 2xx instead of leaking a SyntaxError', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response('<html>gateway</html>', { status: 200 }))
+    const sd = makeClient(fetchMock)
+
+    const err = await sd.stats().catch((e: unknown) => e)
+
+    expect(err).toBeInstanceOf(SendDockError)
+    expect((err as SendDockError).message).toBe('the server returned a non-JSON response body')
+  })
+
+  it('handles a non-JSON error body without crashing', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response('Bad Gateway', { status: 502 }))
+    const sd = makeClient(fetchMock)
+
+    const err = await sd.stats().catch((e: unknown) => e)
+
+    expect(err).toBeInstanceOf(SendDockError)
+    expect((err as SendDockError).status).toBe(502)
+    expect((err as SendDockError).message).toBe('request failed with status 502')
+  })
+
+  it('handles an error body whose error field is not a string', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(jsonResponse(400, { error: { nested: true } }))
+    const sd = makeClient(fetchMock)
+
+    const err = await sd.stats().catch((e: unknown) => e)
+
+    expect((err as SendDockError).message).toBe('request failed with status 400')
+    expect((err as SendDockError).body).toEqual({ error: { nested: true } })
+  })
+})
+
+describe('retry exhaustion', () => {
+  it('throws the last error after exhausting retries on 5xx', async () => {
+    vi.useFakeTimers()
+    try {
+      const fetchMock = vi
+        .fn()
+        .mockImplementation(() => Promise.resolve(jsonResponse(503, { error: 'unavailable' })))
+      const sd = makeClient(fetchMock, 2)
+
+      const pending = sd.stats().catch((e: unknown) => e)
+      await vi.advanceTimersByTimeAsync(10_000)
+      const err = await pending
+
+      expect(fetchMock).toHaveBeenCalledTimes(3)
+      expect((err as SendDockError).status).toBe(503)
+      expect((err as SendDockError).message).toBe('unavailable')
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('caps a hostile Retry-After at 60 seconds', async () => {
+    vi.useFakeTimers()
+    try {
+      const fetchMock = vi
+        .fn()
+        .mockResolvedValueOnce(
+          jsonResponse(429, { error: 'slow down' }, { 'Retry-After': '86400' }),
+        )
+        .mockResolvedValueOnce(jsonResponse(200, {}))
+      const sd = makeClient(fetchMock, 1)
+
+      const pending = sd.stats()
+      await vi.advanceTimersByTimeAsync(60_000)
+
+      await expect(pending).resolves.toEqual({})
+      expect(fetchMock).toHaveBeenCalledTimes(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('never retries 4xx client errors even with retries configured', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(404, { error: 'project not found' }))
+    const sd = makeClient(fetchMock, 3)
+
+    const err = await sd.stats().catch((e: unknown) => e)
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect((err as SendDockError).isNotFound).toBe(true)
+  })
+})

src/types.test-d.ts

@@ -0,0 +1,54 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import { SendDock } from './client.js'
+import type { ImportResponse, SendResponse, Stats } from './types.js'
+
+declare const sd: SendDock
+
+describe('compile-time contract', () => {
+  it('accepts the three valid send shapes', () => {
+    expectTypeOf(sd.send({ to: 'a@b.co', template_id: 't' })).resolves.toEqualTypeOf<SendResponse>()
+    expectTypeOf(sd.send({ subscriber_id: 's', template_id: 't' })).resolves.toEqualTypeOf<SendResponse>()
+    expectTypeOf(sd.send({ to: 'a@b.co', subject: 'x', html_body: '<p>x</p>' })).resolves.toEqualTypeOf<SendResponse>()
+  })
+
+  it('rejects invalid send bodies at compile time', () => {
+    // @ts-expect-error a recipient alone is not a valid send shape
+    void sd.send({ to: 'a@b.co' })
+    // @ts-expect-error raw html requires a subject
+    void sd.send({ to: 'a@b.co', html_body: '<p>x</p>' })
+    // @ts-expect-error empty body is not a valid send shape
+    void sd.send({})
+  })
+
+  it('rejects invalid batch and broadcast bodies at compile time', () => {
+    // @ts-expect-error recipients is required
+    void sd.sendBatch({ template_id: 't' })
+    // @ts-expect-error recipients entries need a to address
+    void sd.sendBatch({ template_id: 't', recipients: [{ data: {} }] })
+    // @ts-expect-error template_id is required
+    void sd.broadcast({ segment_id: 's' })
+  })
+
+  it('rejects invalid import rows at compile time', () => {
+    // @ts-expect-error email is required on every row
+    void sd.importSubscribers([{ name: 'Ada' }])
+    // @ts-expect-error status is a closed union
+    void sd.importSubscribers([{ email: 'a@b.co', status: 'banned' }])
+  })
+
+  it('types the responses precisely', () => {
+    expectTypeOf(sd.stats()).resolves.toEqualTypeOf<Stats>()
+    expectTypeOf(sd.importSubscribers([{ email: 'a@b.co' }])).resolves.toEqualTypeOf<ImportResponse>()
+  })
+
+  it('narrows the send response union on the suppressed discriminant', async () => {
+    const result = await sd.send({ to: 'a@b.co', template_id: 't' })
+    if ('message' in result && result.message === 'suppressed') {
+      expectTypeOf(result.suppressed).toEqualTypeOf<number>()
+    }
+    if ('sent' in result) {
+      expectTypeOf(result.sent).toEqualTypeOf<number>()
+      expectTypeOf(result.suppressed).toEqualTypeOf<number | undefined>()
+    }
+  })
+})

src/types.ts

@@ -3,6 +3,7 @@ export interface SendDockOptions {
   apiKey: string
   projectId: string
   maxRetries?: number
+  timeoutMs?: number
   fetch?: typeof globalThis.fetch
 }
 

vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    typecheck: { enabled: true },
+  },
+})