Voiceflow fetch wrapper and error handling for SDKs
Voiceflow fetch wrapper and error handling for SDKs
``sh
yarn add --exact @voiceflow/fetch @voiceflow/exception
Usage
This is a universal library and can be used in the browser or in a Node.JS environment by passing a
fetch implementation.$3
`ts
import { FetchClient } from '@voiceflow/fetch';const fetch = new FetchClient({
/ config /
});
`$3
Make sure to install
undici when using in a Node.JS environment.`sh
yarn add --exact undici
``ts
import { FetchClient } from '@voiceflow/fetch/undici';const fetch = new FetchClient({
/ config /
});
`Configuration
-
baseURL (string): this will be added as a prefix to the URL of all requestsFeatures
- JSON requests
- JSON responses
- HTTP methods
- throws on non-2xx
- @voiceflow/exception integration
- raw request passthrough
$3
Use the
json option to pass a payload that will be serialized with JSON.stringify.
This will also automatically add the request header Content-Type: application/json.`ts
const fetch = new FetchClient();await fetch.put('http://example.com', {
json: { foo: 'bar' },
});
`$3
Use the
json() method attached to the returned promise to resolve a parsed version of the response payload without needing an additional await.
You can also specify a type for the parsed result, by default the type will be unknown.`ts
const fetch = new FetchClient();const result = await fetch.get('http://example.com').json<{ id: number; name: string }>();
`$3
Use the appropriate method to set the HTTP method being used in the request.
`ts
const fetch = new FetchClient();fetch.delete('/foo'); // DELETE /foo
fetch.get('/foo'); // GET /foo
fetch.head('/foo'); // HEAD /foo
fetch.patch('/foo'); // PATCH /foo
fetch.post('/foo'); // POST /foo
fetch.put('/foo'); // PUT /foo
`$3
Specify a base URL which should be used to build every request.
`ts
const fetch = new FetchClient({ baseURL: 'http://example.com/' });fetch.get('foo'); // GET http://example.com/foo
`If you make a request using a
URL instance then the baseURL option will be ignored.`ts
const fetch = new FetchClient({ baseURL: 'http://example.com/' });
const url = new URL('http://foo.com/bar');fetch.get(url); // GET http://foo.com/bar
`$3
If any non-
2xx HTTP status is returned then a ClientException from @voiceflow/exception is thrown.`ts
const fetch = new FetchClient();try {
await fetch.get('http://example.com'); // return 404
} catch (err) {
err; // ClientException
}
`$3
Internal error codes and other error details are automatically extracted from the response payload when a non-
2xx status is returned.`ts
import { ClientException } from '@voiceflow/exception';const fetch = new FetchClient();
try {
await fetch.get('http://example.com'); // return 404
} catch (err) {
if (ClientException.instanceOf(err)) {
err.errorCode; // ErrorCode | undefined
}
}
`$3
Use the
raw() method to bypass all of the features above to access the underlying fetch interface directly.#### Browser Native
fetch Request`ts
const fetch = new FetchClient();const url = new URL('http://example.com');
const request = new Request(url);
const response = await fetch.raw(request); // Response
`#### Node.JS Native
undici.fetch Request`ts
import { URL } from 'node:url';
import * as undici from 'undici';const fetch = new FetchClient(undici.fetch);
const url = new URL('http://example.com');
const request = new undici.Request(url);
const response = await fetch.raw(request); // undici.Response
``