# edgen-client

> The official TypeScript library for the Edgen API

Latest version **0.1.2** (published 2024-01-25) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install edgen-client
pnpm add edgen-client
yarn add edgen-client
bun add edgen-client
```

Provides the command `edgen-client`.

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.2 |
| Published | 2024-01-25 |
| First published | 2024-01-24 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 10 |
| Unpacked size | 601.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Edgen |
| Maintainers | francis2tm |

## Links

- npm: https://www.npmjs.com/package/edgen-client
- Repository: https://github.com/edgenai/edgen-client-node
- npm.io page: https://npm.io/package/edgen-client

## Dependencies (10)

- [mocha](https://npm.io/package/mocha.md) ^10.2.0
- [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.7
- [@types/node](https://npm.io/package/@types/node.md) ^18.11.18
- [digest-fetch](https://npm.io/package/digest-fetch.md) ^1.3.0
- [formdata-node](https://npm.io/package/formdata-node.md) ^4.3.2
- [agentkeepalive](https://npm.io/package/agentkeepalive.md) ^4.2.1
- [abort-controller](https://npm.io/package/abort-controller.md) ^3.0.0
- [@types/node-fetch](https://npm.io/package/@types/node-fetch.md) ^2.6.4
- [form-data-encoder](https://npm.io/package/form-data-encoder.md) 1.7.2
- [web-streams-polyfill](https://npm.io/package/web-streams-polyfill.md) ^3.2.1

## Recent versions

- 0.1.2 (latest) — 2024-01-25
- 0.1.1 — 2024-01-25
- 0.1.0 — 2024-01-24
- 4.24.7 — 2024-01-24

## README

# Edgen Node API Library

This library provides convenient access to the Edgen REST API from TypeScript or JavaScript.
It is a fork of the official OpenAI Python library.

The original library was generated from the [OpenAPI specification](https://github.com/openai/openai-openapi) with [Stainless](https://stainlessapi.com/).

## Installation

```sh
npm install --save edgen
# or
yarn add edgen
```

## Usage

The full API of this library can be found in [api.md file](api.md) along with many [code examples](https://github.com/edgenai/edgen-client-node/tree/master/examples). The code below shows how to get started using the chat completions API.

<!-- prettier-ignore -->
```js
import Edgen from 'edgen';

const edgen = new Edgen({
  baseURL: process.env['EDGEN_BASE_URL'], // This is the default and can be omitted
});

async function main() {
  const chatCompletion = await edgen.chat.completions.create({
    messages: [{ role: 'user', content: 'Say this is a test' }],
    model: 'gpt-3.5-turbo',
  });
}

main();
```

## Streaming Responses

We provide support for streaming responses using Server Sent Events (SSE).

```ts
import Edgen from 'edgen';

const edgen = new Edgen();

async function main() {
  const stream = await edgen.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Say this is a test' }],
    stream: true,
  });
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
}

main();
```

If you need to cancel a stream, you can `break` from the loop
or call `stream.controller.abort()`.

### Request & Response types

This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:

<!-- prettier-ignore -->
```ts
import Edgen from 'edgen';

const edgen = new Edgen();

async function main() {
  const params: Edgen.Chat.ChatCompletionCreateParams = {
    messages: [{ role: 'user', content: 'Say this is a test' }],
    model: 'gpt-3.5-turbo',
  };
  const chatCompletion: Edgen.Chat.ChatCompletion = await edgen.chat.completions.create(params);
}

main();
```

Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.

## Handling errors

When the library is unable to connect to the API,
or if the API returns a non-success status code (i.e., 4xx or 5xx response),
a subclass of `APIError` will be thrown:

<!-- prettier-ignore -->
```ts
async function main() {
  const job = await edgen.chat.completions
    .create({
        messages: [{ role: 'user', content: 'Say this is a test' }],
        model: 'gpt-3.5-turbo',
     })
    .catch((err) => {
      if (err instanceof Edgen.APIError) {
        console.log(err.status); // 400
        console.log(err.name); // BadRequestError
        console.log(err.headers); // {server: 'nginx', ...}
      } else {
        throw err;
      }
    });
}

main();
```

Error codes are as followed:

| Status Code | Error Type                 |
| ----------- | -------------------------- |
| 400         | `BadRequestError`          |
| 401         | `AuthenticationError`      |
| 403         | `PermissionDeniedError`    |
| 404         | `NotFoundError`            |
| 422         | `UnprocessableEntityError` |
| 429         | `RateLimitError`           |
| >=500       | `InternalServerError`      |
| N/A         | `APIConnectionError`       |

### Retries

Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
429 Rate Limit, and >=500 Internal errors will all be retried by default.

You can use the `maxRetries` option to configure or disable this:

<!-- prettier-ignore -->
```js
// Configure the default for all requests:
const edgen = new Edgen({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await edgen.chat.completions.create({ messages: [{ role: 'user', content: 'How can I get the name of the current day in Node.js?' }], model: 'gpt-3.5-turbo' }, {
  maxRetries: 5,
});
```

### Timeouts

Requests time out after 10 minutes by default. You can configure this with a `timeout` option:

<!-- prettier-ignore -->
```ts
// Configure the default for all requests:
const edgen = new Edgen({
  timeout: 20 * 1000, // 20 seconds (default is 10 minutes)
});

// Override per-request:
await edgen.chat.completions.create({ messages: [{ role: 'user', content: 'How can I list all files in a directory using Python?' }], model: 'gpt-3.5-turbo' }, {
  timeout: 5 * 1000,
});
```

On timeout, an `APIConnectionTimeoutError` is thrown.

Note that requests which time out will be [retried twice by default](#retries).

## Advanced Usage

## Customizing the fetch client

By default, this library uses `node-fetch` in Node, and expects a global `fetch` function in other environments.

If you would prefer to use a global, web-standards-compliant `fetch` function even in a Node environment,
(for example, if you are running Node with `--experimental-fetch` or using NextJS which polyfills with `undici`),
add the following import before your first import `from "Edgen"`:

```ts
// Tell TypeScript and the package to use the global web fetch instead of node-fetch.
// Note, despite the name, this does not add any polyfills, but expects them to be provided if needed.
import 'edgen/shims/web';
import Edgen from 'edgen';
```

To do the inverse, add `import "edgen/shims/node"` (which does import polyfills).
This can also be useful if you are getting the wrong TypeScript types for `Response` - more details [here](https://github.com/edgenai/edgen-client-node/tree/master/src/_shims#readme).

You may also provide a custom `fetch` function when instantiating the client,
which can be used to inspect or alter the `Request` or `Response` before/after each request:

```ts
import { fetch } from 'undici'; // as one example
import Edgen from 'edgen';

const client = new Edgen({
  fetch: async (url: RequestInfo, init?: RequestInfo): Promise<Response> => {
    console.log('About to make a request', url, init);
    const response = await fetch(url, init);
    console.log('Got response', response);
    return response;
  },
});
```

Note that if given a `DEBUG=true` environment variable, this library will log all requests and responses automatically.
This is intended for debugging purposes only and may change in the future without notice.

## Semantic Versioning

This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.

## Requirements

TypeScript >= 4.5 is supported.

The following runtimes are supported:

- Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
- Bun 1.0 or later.
- Cloudflare Workers.
- Vercel Edge Runtime.
- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
- Nitro v2.6 or greater.

Note that React Native is not supported at this time.

If you are interested in other runtime environments, please open or upvote an issue on GitHub.

---
_Source: https://npm.io/package/edgen-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._