Keep provider SDK types at the edge of your Next.js SaaS. Your feature code should ask for the result it needs, not for an OpenAI response object, an Anthropic message block, or a Gemini candidate.
That boundary is worth designing before the second provider arrives. Once SDK-specific streaming events, safety results, tool calls, and errors reach route handlers or components, a provider change becomes a product-wide rewrite. A narrow server-side contract keeps the change local and makes the unsupported cases visible.
Start with the feature contract, not a provider comparison
Choose the one user-facing job first. A support-draft feature may need a prompt, account context, generated text, usage metadata, and a retryable failure. An extraction feature may instead need validated structured data. Those are different contracts even if both call a text model.
Do not begin by mirroring every method exposed by each SDK. OpenAI, Anthropic, and Gemini all publish text-generation APIs, but their request shapes, streaming events, content blocks, tool semantics, safety surfaces, and model options evolve independently. The useful application boundary is the smallest one your feature can own.
A request/result adapter diagram
feature or route handler
request: { prompt, accountId, purpose }
|
v
server-side AI boundary
validates input · selects policy · normalizes result
|
+-- OpenAI adapter: SDK request and response mapping
+-- Claude adapter: SDK request and response mapping
+-- Gemini adapter: SDK request and response mapping
|
v
result: { text, finishReason, usage?, provider, model }
The provider adapter is infrastructure. The feature owns the request it accepts and the result it can safely use. The route handler composes them on the server, where credentials, authorization, rate controls, and logging policy can remain private.
Define a narrow request and an honest result
A good first contract says what your product requires and nothing more. This example is deliberately small: it handles a non-streaming text task and reports enough metadata to make a result explainable. It is an example to adapt and test, not a copied Accelerator file.
type GenerateRequest = {
prompt: string;
purpose: "support-draft" | "release-summary";
maxOutputTokens?: number;
};
type GenerateResult = {
text: string;
provider: "openai" | "claude" | "gemini";
model: string;
finishReason: "complete" | "length" | "blocked" | "unknown";
usage?: { inputTokens?: number; outputTokens?: number };
};
type AiTextProvider = {
generate(request: GenerateRequest): Promise<GenerateResult>;
};
This does not promise identical token accounting or finish-reason vocabulary. It gives the adapter one place to map provider values into the application’s deliberately smaller vocabulary. Preserve the raw provider payload only in a protected diagnostic path when you have a defined retention and redaction policy; do not pass it through to the browser by default.
Keep selection and SDK calls on the server
The provider selector should be boring. Read an allowed provider configuration on the server, instantiate the matching adapter there, and expose only the feature contract to the rest of the application. In Next.js, that usually means a server-only domain module or a route handler, not a client component that imports an SDK.
The current Frontend Accelerator product repository follows this basic split: its AI domain declares a common adapter surface, a selector chooses OpenAI, Claude, or Gemini from configuration, and separate adapter files own the individual SDK calls. That is useful evidence for where the seam belongs. It is not evidence that every declared operation has the same behavior across providers.
For example, the current OpenAI adapter implements text generation, streaming, image generation, token estimation, and moderation. The Claude adapter throws for image generation and uses a provider-specific moderation workaround. The Gemini adapter throws for moderation. Treat that as a design signal: an interface with too many optional capabilities can hide a runtime failure behind a reassuring type.
Split capabilities before they become surprises
Prefer focused ports over one broad “AI provider” interface. A text-generation feature should depend on text generation. An image feature should depend on image generation. A safety workflow should have an explicit policy and a clear fallback when a selected provider does not expose the control you need.
- Text port: prompt, optional system or policy context, text result, and normalized completion reason.
- Streaming port: a stable event model you own, with explicit cancellation and an end-of-stream result.
- Structured-output port: a schema you validate after provider output; do not trust a provider request option as the only acceptance gate.
- Image port: a separate capability with its own output handling, moderation policy, and storage boundary.
- Safety port: an explicit decision about provider moderation, an application policy, or both—never an untested boolean that every adapter is assumed to supply.
This makes feature eligibility testable. If a provider cannot satisfy the chosen port, fail configuration validation or return a controlled feature-unavailable state. Do not select it and hope a method will work on the first customer request.
Make provider choice a configuration decision with a test seam
Keep the selector behind a constructor or factory that receives an allowed provider name and returns the focused port the feature needs. In production, that factory reads server-side configuration. In a test, it can return a fake that produces a known success, a length-limited result, or a provider failure without making a network call.
This arrangement gives you two complementary checks. Adapter contract tests prove each SDK mapping produces your normalized result. Feature tests prove the application responds correctly when that contract succeeds or fails. Neither test needs to claim that a model will always return the same words; they prove your code handles the states it owns.
Normalize semantics only after you write the failure rules
Text is the easy part. The difficult part is deciding what the product does when a request is rate-limited, cancelled, blocked, incomplete, malformed, or accepted but charged differently than expected. These are product decisions; adapters should translate provider behavior into signals that the feature can handle.
- Validate before calling. Bound input length, authorize the account, and reject a purpose that the feature does not support.
- Map only known outcomes. Translate a provider’s timeout, safety stop, invalid request, or rate limit into a small application error code with safe user-facing language.
- Keep retry ownership explicit. Retry only errors your feature can safely retry, with a defined limit. Do not retry an ambiguous completed request without an idempotency design.
- Record an auditable trace. Log a request identifier, selected provider and model, normalized outcome, latency, and token fields when available—without prompt secrets or personal data unless your policy permits them.
- Test the adapter boundary. Use a fake provider to verify a successful result, a blocked result, a rate-limit error, a malformed structured result, and a mid-stream cancellation.
OpenAI’s current text guide documents the Responses API and streaming options; Anthropic documents its Messages API; Google documents both synchronous and streaming content-generation endpoints. Those sources describe provider capabilities, not a shared contract. Your adapter is where the differences become a stable product decision.
Do not over-normalize tools, files, or conversation state
Some differences should remain visible. Tool calling, hosted retrieval, long-running work, server-side conversation state, image inputs, and safety controls can carry provider-specific lifecycle and data-handling implications. A generic method such as runAgent() often conceals more than it protects.
Start with a provider-neutral text or structured-output boundary when that is all the feature needs. Add a separate port only when you can name its input, output, cancellation model, authorization rule, test cases, and operational owner. If one provider feature is strategically important, it can be an explicit product capability instead of a pretend cross-provider abstraction.
A practical review checklist
- Does the feature depend on a small request/result contract rather than an SDK response type?
- Are credentials and provider selection server-only?
- Is every exposed capability implemented and tested for the selected provider?
- Are structured outputs validated after generation?
- Can the feature explain a blocked, incomplete, rate-limited, or cancelled result without exposing provider internals?
- Does the adapter test suite use fixtures or fakes for the failure behavior you claim to support?
- Would adding a second provider change one adapter file and configuration, rather than components and feature logic?
If the last answer is no, shrink the application contract before you add another SDK. A provider boundary does not make model behavior identical or remove the need to review outputs. It gives your product one place to make those differences deliberate.
Where Frontend Accelerator fits
Frontend Accelerator gives a Next.js SaaS a feature-first structure and separates AI, payment, and database provider code from product features. That gives a coding agent a clearer extension point than a blank repository, while leaving you responsible for provider credentials, feature policy, tests, monitoring, and the behavior you ship.
For the broader architectural pattern, see how to make a Next.js codebase AI-ready. Before merging a provider change, use the AI-agent change review guide. You can also explore the Frontend Accelerator feature set to see the connected SaaS foundation around those boundaries.
