[**Documentation**](index.md)

***

[Documentation](packages.md) / Vonage Vetch

# Vonage Vetch SDK for Node.js

![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/vonage/vonage-node-sdk/ci.yml?branch=3.x) [![Codecov](https://img.shields.io/codecov/c/github/vonage/vonage-node-sdk?label=Codecov&logo=codecov&style=flat-square)](https://codecov.io/gh/Vonage/vonage-server-sdk) ![Latest Release](https://img.shields.io/npm/v/@vonage/vetch?label=%40vonage%2Fvetch&style=flat-square) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg?style=flat-square)](../../CODE_OF_CONDUCT.md) [![License](https://img.shields.io/npm/l/@vonage/accounts?label=License&style=flat-square)][license]

<img src="https://developer.nexmo.com/images/logos/vbc-logo.svg" height="48px" alt="Vonage" />

This is the Vonage `Vetch`er SDK for Node.js used to wrap a request using `node-fetch` to call [Vonage APIs](https://www.vonage.com/). To use it you will need a Vonage account. Sign up [for free at vonage.com][signup].

For full API documentation refer to [developer.vonage.com](https://developer.vonage.com/).

* [Installation](#installation)
* [Usage](#usage)
    * [Options](#options)
* [Testing](#testing)

## Installation

### With NPM

```bash
npm install @vonage/vetch
```

### With Yarn

```bash
yarn add @vonage/vetch
```

## Using the Vonage Vetch SDK

Vetch will return a [`VetchResponse`](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/vetch/lib/types.ts#L28)

```js
const { request } = require('@vonage/vetch');

const response = await request({
  url: 'https://rest.nexmo.com/account/numbers'
})

console.log(response.data);
// Will output the json data from the API response
```

### Options

`options` are a superset from the request package. See [`VetchOptions`](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/vetch/lib/interfaces/vetchOptions.ts) for more detail

## Testing

Run:

```bash
npm run test
```

[signup]: https://dashboard.nexmo.com/sign-up?utm_source=DEV_REL&utm_medium=github&utm_campaign=node-server-sdk
[license]: _media/LICENSE.txt

## Enumerations

### ContentType

Defined in: [packages/vetch/lib/enums/contentType.ts:9](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/contentType.ts#L9)

Enum representing possible MIME types for the 'content-type' HTTP header that
Vonage API's could accept.

Note: Most of the APIs will only accept `application/json`.  Please refer
to the specific API documentation to determine if another content type is
accepted

#### Enumeration Members

| Enumeration Member | Value | Description | Defined in |
| ------ | ------ | ------ | ------ |
| <a id="csv"></a> `CSV` | `"text/csv"` | Represents the MIME type for CSV data. | [packages/vetch/lib/enums/contentType.ts:20](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/contentType.ts#L20) |
| <a id="form_urlencoded"></a> `FORM_URLENCODED` | `"application/x-www-form-urlencoded"` | Represents the MIME type for URL-encoded form data. | [packages/vetch/lib/enums/contentType.ts:14](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/contentType.ts#L14) |
| <a id="json"></a> `JSON` | `"application/json"` | Represents the MIME type for JSON data. | [packages/vetch/lib/enums/contentType.ts:11](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/contentType.ts#L11) |
| <a id="xml"></a> `XML` | `"application/xml"` | Represents the MIME type for XML data. | [packages/vetch/lib/enums/contentType.ts:17](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/contentType.ts#L17) |

***

### HTTPMethods

Defined in: [packages/vetch/lib/enums/HTTPMethods.ts:4](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/HTTPMethods.ts#L4)

Enum representing the HTTP methods that can be used for Vonage API requests.

#### Enumeration Members

| Enumeration Member | Value | Description | Defined in |
| ------ | ------ | ------ | ------ |
| <a id="delete"></a> `DELETE` | `"DELETE"` | Represents an HTTP DELETE request. | [packages/vetch/lib/enums/HTTPMethods.ts:12](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/HTTPMethods.ts#L12) |
| <a id="get"></a> `GET` | `"GET"` | Represents an HTTP GET request. | [packages/vetch/lib/enums/HTTPMethods.ts:6](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/HTTPMethods.ts#L6) |
| <a id="patch"></a> `PATCH` | `"PATCH"` | Represents an HTTP PATCH request. | [packages/vetch/lib/enums/HTTPMethods.ts:18](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/HTTPMethods.ts#L18) |
| <a id="post"></a> `POST` | `"POST"` | Represents an HTTP POST request. | [packages/vetch/lib/enums/HTTPMethods.ts:9](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/HTTPMethods.ts#L9) |
| <a id="put"></a> `PUT` | `"PUT"` | Represents an HTTP PUT request. | [packages/vetch/lib/enums/HTTPMethods.ts:15](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/HTTPMethods.ts#L15) |

***

### ~~ResponseTypes~~

Defined in: [packages/vetch/lib/enums/responseTypes.ts:7](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/responseTypes.ts#L7)

#### Deprecated

Enum representing the expected response types for API requests. This was
originaly used to set what the expected response type will be. It is better
to use the content-type header from the response to decode properly.

#### Enumeration Members

| Enumeration Member | Value | Description | Defined in |
| ------ | ------ | ------ | ------ |
| <a id="json-1"></a> `json` | `"json"` | Represents a JSON-formatted response. | [packages/vetch/lib/enums/responseTypes.ts:11](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/responseTypes.ts#L11) |
| <a id="stream"></a> `stream` | `"stream"` | Represents a stream response, typically for handling large data or files. | [packages/vetch/lib/enums/responseTypes.ts:16](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/responseTypes.ts#L16) |
| <a id="text"></a> `text` | `"text"` | Represents a plain text response. | [packages/vetch/lib/enums/responseTypes.ts:21](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/enums/responseTypes.ts#L21) |

## Classes

### VetchError

Defined in: [packages/vetch/lib/errors/vetchError.ts:15](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/errors/vetchError.ts#L15)

Class representing an error from a Vetch API request. Extends the built-in
Error class and adds additional properties related to the API request and
response.

#### Template

The type of the data payload in the VetchResponse, expected to be an object that has been decoded from JSON or WebForm.

#### Extends

- `Error`

#### Constructors

##### Constructor

```ts
new VetchError(
   message, 
   options, 
   response?): VetchError;
```

Defined in: [packages/vetch/lib/errors/vetchError.ts:27](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/errors/vetchError.ts#L27)

Creates an instance of VetchError.

###### Parameters

###### message

`string`

The error message.

###### options

[`VetchOptions`](#vetchoptions)

Configuration options for the API request.

###### response?

`Response`

Configuration options for the API request.

###### Returns

[`VetchError`](#vetcherror)

###### Overrides

```ts
Error.constructor
```

#### Properties

##### cause?

```ts
optional cause: unknown;
```

Defined in: node\_modules/typescript/lib/lib.es2022.error.d.ts:24

###### Inherited from

```ts
Error.cause
```

##### code?

```ts
optional code: string;
```

Defined in: [packages/vetch/lib/errors/vetchError.ts:16](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/errors/vetchError.ts#L16)

An optional error code.

##### config

```ts
config: VetchOptions;
```

Defined in: [packages/vetch/lib/errors/vetchError.ts:17](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/errors/vetchError.ts#L17)

Configuration options for the API request.

##### message

```ts
message: string;
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1077

###### Inherited from

```ts
Error.message
```

##### name

```ts
name: string;
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1076

###### Inherited from

```ts
Error.name
```

##### response?

```ts
optional response: Response;
```

Defined in: [packages/vetch/lib/errors/vetchError.ts:18](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/errors/vetchError.ts#L18)

The API response that resulted in the error.

##### stack?

```ts
optional stack: string;
```

Defined in: node\_modules/typescript/lib/lib.es5.d.ts:1078

###### Inherited from

```ts
Error.stack
```

##### stackTraceLimit

```ts
static stackTraceLimit: number;
```

Defined in: node\_modules/@types/node/globals.d.ts:161

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured _after_ the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

###### Inherited from

```ts
Error.stackTraceLimit
```

#### Methods

##### captureStackTrace()

```ts
static captureStackTrace(targetObject, constructorOpt?): void;
```

Defined in: node\_modules/@types/node/globals.d.ts:145

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

###### Parameters

###### targetObject

`object`

###### constructorOpt?

`Function`

###### Returns

`void`

###### Inherited from

```ts
Error.captureStackTrace
```

##### prepareStackTrace()

```ts
static prepareStackTrace(err, stackTraces): any;
```

Defined in: node\_modules/@types/node/globals.d.ts:149

###### Parameters

###### err

`Error`

###### stackTraces

`CallSite`[]

###### Returns

`any`

###### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

###### Inherited from

```ts
Error.prepareStackTrace
```

## Type Aliases

### Headers

```ts
type Headers = object;
```

Defined in: [packages/vetch/lib/types/headers.ts:7](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/headers.ts#L7)

Interface representing HTTP headers as a string-keyed object. Each property
represents a header name, and the associated value can be a string or an
array of strings. Includes optional 'authorization' and 'content-type'
properties with restricted possible values for 'content-type'.

#### Index Signature

```ts
[index: string]: string
```

***

### VetchOptions

```ts
type VetchOptions = object;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:7](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L7)

Options to configure the Vetch request.

#### Properties

##### appendUserAgent?

```ts
optional appendUserAgent: string;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:50](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L50)

Additional user agent string to append.

##### ~~body?~~

```ts
optional body: Record<string, string | readonly string[]> | string;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:29](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L29)

###### Deprecated

Use 'data' instead of 'body'

##### checkStatus()?

```ts
optional checkStatus: (status) => boolean;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:45](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L45)

A function to check the response status.

###### Parameters

###### status

`number`

###### Returns

`boolean`

##### data?

```ts
optional data: Record<string, string | readonly string[]> | string;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:26](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L26)

Request body data. Use 'data' instead of 'body' for newer implementations.

##### headers?

```ts
optional headers: Headers;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:55](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L55)

The headers to be sent with the request.

##### method

```ts
method: HTTPMethods;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:16](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L16)

The HTTP method to use for the request, e.g., GET, POST, etc.

##### params?

```ts
optional params: Record<string, string | readonly string[]>;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:34](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L34)

Query parameters for the request.

##### ~~responseType?~~

```ts
optional responseType: ResponseTypes;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:40](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L40)

Expected response type.

###### Deprecated

`ResponseTypes` is deprecated and will be removed in future versions.

##### timeout?

```ts
optional timeout: number;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:60](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L60)

Time in milliseconds to wait for the request to complete.

##### type

```ts
type: ContentType;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:11](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L11)

The content type for the request, e.g., JSON, WebForm, etc.

##### url

```ts
url: string;
```

Defined in: [packages/vetch/lib/types/vetchOptions.ts:21](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchOptions.ts#L21)

The URL endpoint for the request.

***

### ~~VetchPromise\<T\>~~

```ts
type VetchPromise<T> = Promise<VetchResponse<T>>;
```

Defined in: [packages/vetch/lib/types/vetchPromise.ts:12](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchPromise.ts#L12)

Type representing a promise that resolves with a standardized Vetch API
response. Vetch ("Vonage Fetch") ensures a consistent API response
structure, irrespective of the HTTP adapter utilized by the developer.

#### Type Parameters

##### T

`T`

The type of the data payload in the VetchResponse, expected to be an object that has been decoded from JSON or WebForm.

#### Deprecated

***

### VetchResponse\<T\>

```ts
type VetchResponse<T> = object;
```

Defined in: [packages/vetch/lib/types/vetchResponse.ts:9](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchResponse.ts#L9)

Represents the response returned by a Vetch request.

#### Type Parameters

##### T

`T`

The type of the response data.

#### Properties

##### config

```ts
config: VetchOptions;
```

Defined in: [packages/vetch/lib/types/vetchResponse.ts:13](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchResponse.ts#L13)

The configuration options used for the request.

##### data

```ts
data: T;
```

Defined in: [packages/vetch/lib/types/vetchResponse.ts:18](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchResponse.ts#L18)

The parsed response data.

##### headers

```ts
headers: Headers;
```

Defined in: [packages/vetch/lib/types/vetchResponse.ts:23](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchResponse.ts#L23)

The response headers.

##### request

```ts
request: VetchOptions;
```

Defined in: [packages/vetch/lib/types/vetchResponse.ts:38](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchResponse.ts#L38)

The configuration options for the request (same as 'config').

##### status

```ts
status: number;
```

Defined in: [packages/vetch/lib/types/vetchResponse.ts:28](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchResponse.ts#L28)

The HTTP status code of the response.

##### statusText

```ts
statusText: string;
```

Defined in: [packages/vetch/lib/types/vetchResponse.ts:33](https://github.com/Vonage/vonage-node-sdk/blob/3846dd78a7cd39b838839d5c93db0b1652c0d168/packages/vetch/lib/types/vetchResponse.ts#L33)

The HTTP status text of the response.