# searchSDK for TypeScript and JavaScript

ESM with declarations, zero runtime dependencies, direct provider APIs and an application gateway handler for Node servers.

Canonical: https://searchsdk.dev/docs/sdks/typescript
Markdown: https://searchsdk.dev/docs/sdks/typescript.md

<a id="requirements"></a>

## Requirements

- Use Node 24.22.1 or a newer patched Node 24 release. The SDK is ESM with TypeScript declarations and zero runtime dependencies.
- Use ESM imports in .mjs or a project with type: module; CommonJS callers can use dynamic import().
- This alpha is distributed as source and locally built artifacts. Public npm availability is not assumed. Record the reviewed source revision and commit your application lockfile.

<a id="install"></a>

## Install

**Terminal**

```bash
git clone https://github.com/Belweave/searchSDK.git
cd searchSDK
nvm use
npm ci
npm run build:sdk
npm pack -w @belweave/search-sdk

# In your Node server application:
npm install /absolute/path/searchSDK/belweave-search-sdk-0.1.0-alpha.0.tgz
```

Run the build commands in the source checkout, then install the resulting tarball in your application. For a new application, run `npm init --yes` first. For TypeScript files run directly with Node 24, set `type: module` with `npm pkg set type=module`. The artifact version is `0.1.0-alpha.0`; this version alone does not prove the artifact includes the latest gateway changes. Record its source revision.

<a id="server-credentials"></a>

## Configure server credentials

Store provider keys in your application's server secret store or server environment. The SDK accepts keys explicitly; it does not load environment files or read environment variables itself.

**credentials.ts · server**

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

For local development, add `.env` to your server project's `.gitignore`, then put `CONTEXT_API_KEY=your-provider-key` in that local file. Run your server example with `node --env-file=.env search.ts`. Node loads the file; the SDK does not. In production, inject `CONTEXT_API_KEY` through your host's server secret configuration.

Do not prefix provider credentials with `VITE_` or another public environment prefix. The hosted playground accepts request-scoped keys and calls providers from its server. The separate key-free demo uses fixtures. Call your own authenticated server route when building a browser application.

<a id="imports"></a>

## Choose the right import

| Import | Purpose |
| --- | --- |
| `@belweave/search-sdk` | `createSearch`, `SearchError`, and public normalized types |
| `@belweave/search-sdk/context` | Context.dev adapter and provider-specific exports |
| `@belweave/search-sdk/tinyfish` | TinyFish adapter and provider-specific exports |
| `@belweave/search-sdk/testing` | `createMockProvider` and fixture types |

- [Make your first request](https://searchsdk.dev/docs/quickstart)

<a id="pack-locally"></a>

## Rebuild the source artifact

Rebuild the local tarball when you change the SDK source. Use the checkout's `.nvmrc` and locked dependencies. This command does not publish the package.

**Source checkout · terminal**

```bash
git clone https://github.com/Belweave/searchSDK.git
cd searchSDK
nvm use
npm ci
npm run build:sdk
npm pack -w @belweave/search-sdk

# In your server application, use the actual generated tarball:
npm install /absolute/path/belweave-search-sdk-0.1.0-alpha.0.tgz
```