# Official JavaScript and Python SDKs

Use small dependency-free clients with types generated from the deployed OpenAPI contract.

## JavaScript / TypeScript

Requires Node.js 22+ or a compatible server-side fetch runtime. Install the official downloadable npm archive:

```bash
npm install https://metaphrase.msalman.com/downloads/metaphrase-sdk-1.0.0.tgz
```

Save as `example.mjs`, set `METAPHRASE_API_KEY`, then run `node example.mjs`:

```javascript
import {MetaPhrase,MetaPhraseError} from '@metaphrase/sdk';
const client=new MetaPhrase({api_key:process.env.METAPHRASE_API_KEY});
try{
  const response=await client.grammar({text:'The best ideas deserves to be shared.',language:'en-US'});
  console.log(response.result.text,response.usage);
}catch(error){
  if(error instanceof MetaPhraseError)console.error(error.status,error.code,error.message,error.docs_url);
  else throw error;
}
```

All methods are named `paraphrase`, `grammar`, `detect`, `translate`, `summarize`, and `cite` and accept one typed request object. They return the full typed response envelope, not just text. Constructor options use snake_case: `api_key`, optional `base_url` (origin, without `/api/v1`), and `timeout_ms` (default 250,000). A custom `fetch` can be provided for server runtimes/tests. Pass `{signal: AbortSignal}` as the second method argument to cancel.

Use `client.stream('paraphrase', request)` for streaming; do not pass `stream:true` to an ordinary JSON method. See [streaming](https://metaphrase.msalman.com/docs/streaming.md). Secret-key SDKs belong on the backend; the JavaScript client rejects browser construction.

## Python

Requires Python 3.11+. Create a virtual environment and install the official wheel:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install https://metaphrase.msalman.com/downloads/metaphrase_sdk-1.0.0-py3-none-any.whl
```

Save as `example.py`, set `METAPHRASE_API_KEY`, then run `python example.py`:

```python
import os
from metaphrase_sdk import MetaPhrase, MetaPhraseError

client = MetaPhrase(api_key=os.environ['METAPHRASE_API_KEY'])
try:
    result = client.grammar({'text': 'The best ideas deserves to be shared.', 'language': 'en-US'})
    print(result['result']['text'])
    print(result['usage'])
except MetaPhraseError as error:
    print(error.status, error.code, str(error), error.docs_url)
```

The import package is `metaphrase_sdk` (with `phrase`); use that exact name. Constructor options: `api_key`, `base_url` (origin), and `timeout` in seconds (default 250). Methods accept a typed request dictionary and return typed response dictionaries; types are exported from `metaphrase_sdk.types`. The Python client uses only the standard library and does not automatically retry.

For streaming:

```python
import os
from metaphrase_sdk import MetaPhrase
client = MetaPhrase(api_key=os.environ['METAPHRASE_API_KEY'])
for event in client.stream('paraphrase', {'text': 'Good writing makes an idea easier to understand.'}):
    if event['event'] == 'delta':
        print(event['data']['text_delta'], end='', flush=True)
    elif event['event'] == 'done':
        print('\n', event['data']['usage'])
```

## Versioning and publication

SDK 1.0.0 targets REST `/api/v1`. The checked-in generator reads the same OpenAPI schemas used by the API docs. Every build regenerates client types, methods, downloads, Postman and Insomnia files. Contract checks detect differences between generated artifacts and the source schemas.

The archives above work with npm and pip without a registry account. Publication under npm/PyPI package names requires the operator's registry ownership and credentials; do not assume a similarly named public package is this official SDK. Install from this domain until registry publication is verified. The package source includes publication instructions and a specification checksum.