feat: add pluggable transport interface for sagemaker support (#492)

## Proposed changes

Adds a pluggable streaming-transport interface so the JS SDK can route
`listen.v1`, `listen.v2`, `speak.v1`, and `agent.v1` connections through
a custom transport instead of the default WebSocket. Also adds a
`reconnect` parity flag for clean handoff of retry responsibility to
custom transports.

This is the JS half of the cross-SDK pluggable-transport work that's
also landed in Python and Java for SageMaker support.

### What's new

1. **`DeepgramTransport` / `DeepgramTransportFactory` interface**
(`src/transport.ts`)
   - Hand-maintained type surface that custom transports implement
- Same `factory(url, headers, request)` shape as the Python/Java
equivalents, with JS-specific request metadata as a third argument

2. **`transportFactory` option on `DeepgramClient`** (wired in
`src/CustomClient.ts`)
- When set, `listen.v1` / `listen.v2` / `speak.v1` / `agent.v1`
`createConnection` paths build a `TransportWebSocketAdapter` that
exposes the SDK's expected `ReconnectingWebSocket` surface but delegates
to the custom transport underneath
- REST behaviour stays unchanged; only the streaming connection layer is
pluggable

3. **`reconnect` flag with auto-disable** (commit `b82d30b`)
   - New `reconnect?: boolean` option on `DeepgramClient`
   - Default is `true` (SDK manages reconnects, current behaviour)
- When `transportFactory` is set, auto-disabled to `false` — the custom
transport owns its retry/reconnect lifecycle; double-stacking the SDK's
wrapper retries on top would cause storm-on-storm under burst load
   - Callers can still opt back in with explicit `reconnect: true`
   - Exposed read-only as `client.reconnect`

### Context

- This is the SDK seam that `@deepgram/sagemaker`
(`deepgram-js-sdk-transport-sagemaker`) plugs into. That package's
`createSageMakerTransportFactory` returns a `DeepgramTransportFactory`
matching this interface.
- The `reconnect` flag mirrors the same parity work in:
  - `deepgram-java-sdk` 
  - `deepgram-python-sdk` #720
- The JS half of this work has been validated end-to-end against three
live SageMaker endpoints (Nova-3 STT, Flux, Aura TTS), including a
400-concurrent-connection burst against Nova-3 with mean WER 0.10% —
matching Java's reference test.

## Testing

- `pnpm build`
- `pnpm vitest run tests/unit/transport-factory.test.ts` — adapter-path
unit coverage including reconnect-flag defaults, explicit `reconnect:
false`, `transportFactory` auto-disable, and explicit `reconnect: true`
override
- `pnpm vitest run tests/unit/custom-client.test.ts`
- End-to-end validation against live SageMaker endpoints (Nova-3 STT,
Flux, Aura TTS); see the `@deepgram/sagemaker` package for the transport
implementation those tests exercise

## Types of changes

- [x] New feature (non-breaking change which adds functionality)

## Release impact

- `feat:` per commit message → minor version bump per release-please
- Fully backwards-compatible — both `transportFactory` and `reconnect`
are optional kwargs with sensible defaults; existing callers need no
code changes
- Hand-maintained files added to `.fernignore` so Fern regen doesn't
overwrite them

## Companion packages

This PR provides the SDK-side interface. The first consumer is:

- `@deepgram/sagemaker` (repo: `deepgram-js-sdk-transport-sagemaker`) —
SageMaker bidirectional HTTP/2 transport, validated end-to-end at 400
concurrent connections

## Checklist

- [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) doc
- [x] I have lint'ed all of my code using repo standards
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have added necessary documentation (if appropriate)

Author: GregHolmes

.fernignore

@@ -4,6 +4,7 @@ examples
 # Custom wrapper
 src/CustomClient.ts
 src/index.ts
+src/transport.ts
 
 # Custom Scripts
 scripts/fix-wire-test-imports.js
@@ -25,6 +26,7 @@ tests/unit/custom-client.test.ts
 tests/unit/error-handling.test.ts
 tests/unit/multiple-keyterms.test.ts
 tests/unit/nodejs-version-compatibility.test.ts
+tests/unit/transport-factory.test.ts
 tests/unit/websocket-reconnection.test.ts
 tests/unit/websocket-wrappers.test.ts
 tests/wire/websocket

AGENTS.md

@@ -22,8 +22,9 @@ How to identify:
 - The file lives **outside `src/api/`** in a hand-maintained location (e.g., `.claude/`, `docs/`, `scripts/`)
 
 Current permanently frozen files:
-- `src/CustomClient.ts` — entirely custom wrapper with WebSocket management, auth providers, and session ID handling; no Fern equivalent
+- `src/CustomClient.ts` — entirely custom wrapper with WebSocket management, auth providers, session ID handling, `transportFactory` plumbing, and the `reconnect` flag (auto-disabled when a custom transport is in use); no Fern equivalent
 - `src/index.ts` — curated re-export file with custom namespace handling
+- `src/transport.ts` — hand-maintained pluggable transport interface for SageMaker and other custom streaming transports
 - `scripts/fix-wire-test-imports.js`, `scripts/revert-wire-test-imports.js` — post-generation import fixup scripts
 - `scripts/proxy-server.js` — development proxy server
 - `scripts/validate-esm-build.mjs` — ESM build validation