# Provider-native transport

Use fixed-origin operations with typed inputs, bounded responses, explicit retries, and sanitized metadata.

Canonical: https://searchsdk.dev/docs/api/native-transport
Markdown: https://searchsdk.dev/docs/api/native-transport.md

<a id="choose-client"></a>

## Start with a provider client

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

Provider client factories bind supported operations to fixed origins and authentication. Use their typed methods for actual provider work. `createNativeTransport` is the lower-level primitive used by those clients; it does not discover endpoints or validate provider JSON schemas.

**native-search.ts · server**

```typescript
import { createContextClient } from '@belweave/search-sdk/native-context';

const apiKey = process.env.CONTEXT_API_KEY;
if (!apiKey) throw new Error('CONTEXT_API_KEY is required');

const client = createContextClient({ apiKey, maxConcurrency: 4 });
const response = await client.search({
  body: { query: 'SQLite write concurrency', numResults: 10 },
  timeoutMs: 8_000,
});
console.log(response.data.results);
console.log(response.metadata.status, response.metadata.attempts);
```

<a id="operation"></a>

## Operation and input

| Operation descriptor | Behavior |
| --- | --- |
| `id` | Static operation name; never put user input or secrets in it. |
| `method` | GET, POST, PUT, PATCH, DELETE, or HEAD. |
| `path` | Relative to the fixed base path; `{name}` placeholders use input.path. |
| `retryable` | Explicit replay eligibility. Defaults false, even for GET. |
| `response` | json by default; text, bytes, raw, or sse. |

| Request input | Behavior |
| --- | --- |
| `path` | Placeholder values encoded as single path segments; do not pre-encode IDs. |
| `query` | Scalar values or repeated arrays; null and undefined omitted. |
| `body` | JSON serialized; cannot coexist with rawBody. |
| `rawBody` | Fetch BodyInit, including FormData. Streaming request bodies are unsupported. |
| `headers` | Non-auth endpoint headers; configured headers cannot be overridden. |
| `signal`, `timeoutMs` | Cancellation and complete-operation deadline. |

<a id="response"></a>

## Data and metadata

**TypeScript · shape**

```typescript
interface NativeResponse<T> {
  data: T;
  metadata: {
    provider: string;
    operation: string;
    status: number;
    requestId?: string;
    attempts: readonly {
      attempt: number;
      durationMs: number;
      outcome: 'success' | 'error';
      status?: number;
      code?: string;
    }[];
  };
}
```

Metadata omits URLs, queries, request input, credentials, provider error bodies, and arbitrary headers. Successful `data` is native provider data and may itself contain sensitive fields. Generic response types are compile-time assertions, not runtime provider schema checks.

<a id="bounds"></a>

## Limits and credentials

| Setting | Default / boundary |
| --- | --- |
| `timeoutMs` | 10,000 ms, including queue, backoff, fetch, response parsing, and stream lifetime. |
| `maxConcurrency` | 8 per transport instance; 1–1,024 when configured. Queue shares the deadline. |
| `maxResponseBytes` | 10 MiB of decoded response bytes, including streaming data. |
| `retry.maxRetries` | 0; retries require both opt-in policy and operation eligibility. |

The base URL must be HTTPS and has no credentials, query, or fragment. Operation input cannot change origin or replace configured authentication. Raw responses are buffered under the size cap. Let Fetch set the multipart boundary for FormData.

The response cap is not a process-memory limit: decoded strings and parsed objects require additional memory. Uploads are materialized before dispatch and do not have an SDK upload-size cap; bound them in your application.

<a id="responses"></a>

## Response modes

| Mode | Returned data |
| --- | --- |
| `json` | Parsed native JSON. Empty 204/205 or HEAD becomes null. |
| `text` | Decoded text. |
| `bytes` | Uint8Array. |
| `raw` | A buffered, bounded Response. |
| `sse` | AsyncIterable<NativeSSEEvent>; incremental and single-consumer. |

- [Streaming event behavior](https://searchsdk.dev/docs/guides/streaming)
- [Retry eligibility](https://searchsdk.dev/docs/reliability/retries)
- [Provider operation inventories](https://searchsdk.dev/docs/providers)