# @api-ts/superagent-wrapper

Combines an api spec with `superagent`/`supertest` to create a type-checked api client.

## Getting started

First, either define or import an `io-ts-http` api spec. The following one will be used
for this guide:

```typescript
import * as h from '@api-ts/io-ts-http';
import * as t from 'io-ts';
import { NumberFromString } from 'io-ts-types';

export const Example = t.type({
  foo: t.string,
  bar: t.number,
});

export const GenericAPIError = t.type({
  message: t.string,
});

export const PutExample = h.httpRoute({
  path: '/example/{id}',
  method: 'PUT',
  request: h.httpRequest({
    params: {
      id: NumberFromString,
    },
    body: {
      example: Example,
    },
  }),
  response: {
    ok: Example,
    invalidRequest: GenericAPIError,
  },
});

export const ExampleAPI = h.apiSpec({
  'api.example': {
    put: PutExample,
  },
});
```

`ExampleAPI` can then be used to create a type-safe api client for either `superagent`
or `supertest`. This requires two steps: wrapping the `superagent`/`supertest` instance,
then binding it to the api spec.

For `superagent`:

```typescript
import { superagentRequestFactory, buildApiClient } from '@api-ts/superagent-wrapper';
import superagent from 'superagent';

import { ExampleAPI } from './see-the-above-example';

// The api root, in a real project probably coming from a config option
const BASE_URL = 'http://example.com/';

// Step one: wrap `superagent` and the api root
const requestFactory = superagentRequestFactory(superagent, BASE_URL);

// Step two: combine the request factory and imported api spec into an api client
// This is intended to be exported and used
export const apiClient = buildApiClient(requestFactory, ExampleAPI);
```

For `supertest` the process is almost identical except that `supertest` itself handles
knowing the root api url:

```typescript
import { supertestRequestFactory, buildApiClient } from '@api-ts/superagent-wrapper';
import supertest from 'superagent';

import { ExampleAPI } from './see-the-above-example';

// For the purposes of this guide, say we have an Express app that can be imported from the project.
// See the `supertest` docs for the options it has for instantiation.
import { app } from '../src/index';
const request = supertest(app);

// Step one: wrap the `supertest` request function created above
const requestFactory = superatestRequestFactory(request);

// Step two: combine the request factory and imported api spec into an api client
// This is intended to be exported and used
export const apiClient = buildApiClient(requestFactory, ExampleAPI);
```

The resulting `apiClient` can then be imported elsewhere and used:

```typescript
import { apiClient } from './api-client-example';

const doSomething = async () => {
  // The `api.example` here comes from the operation in the `ExampleAPI` definition from above
  const response = await apiClient['api.example']
    // The object passed to this function is type-checked against the request codec
    .put({ id: 42, example: { foo: 'hello', bar: 1 } })
    // This will use the set of response codecs to decode the response
    .decode();

  // The two main properties on `response` are `status` and `body`
  // If the value of `status` is checked, then TypeScript will infer the correct body type
  if (response.status === 200) {
    const { foo, bar } = response.body; // We know the correct body type here
  } else if (response.status === 400) {
    // The body is a GenericAPIError
    console.log(response.body.message);
  } else {
    // In case an unexpected status code comes back, or the response body does not correctly
    // decode, we can still access it as an `unknown` type.
    if (
      response.body &&
      typeof response.body === 'object' &&
      response.body.hasOwnProperty('message')
    ) {
      console.log(response.body.message);
    }
  }
};
```

For convenience, a `decodeExpecting` function is also added to requests. It accepts an
HTTP status code and throws if either the response code doesn't match, or it does but
the response body failed to decode.

```typescript
const expectOk = async () => {
  // The `api.example` here comes from the operation in the `ExampleAPI` definition from above
  const response = await apiClient['api.example']
    // The object passed to this function is type-checked against the request codec
    .put({ id: 42, example: { foo: 'hello', bar: 1 } })
    // This will use the set of response codecs to decode the response
    .decodeExpecting(200);

  const { foo, bar } = response.body;
};
```