@code-exitos/react-native-proxy-client

This is a framework to interact with server-side applications that are accessible through proxies for React Native.

Installation

$3

Using _npm_:

``sh
npm install @code-exitos/react-native-proxy-client
`

Using _yarn_:

`sh
yarn add @code-exitos/react-native-proxy-client
`

Using _pnpm_:

`sh
pnpm add @code-exitos/react-native-proxy-client
`

$3

`sh
npx pod-install

or

cd ios && pod install
`

About

This package offers a series of module that allows the implementation of different type of clients. The modules are:

- ProxyClient: the module offers a class with a set of methods to make the basic HTTP requests.
- ProxyEventSource: the module offers a class that enables methods to connect and listen to events sent by a Server-Sent Events.
- ProxyWebSocket: the module offers a class that enables methods to connect and listen to events sent by a WebSocket. This module can be configured to use raw WebSocket or Socket.IO.
ProxyFileManager: the module offers a class that enables methods to upload and download files.

> ### Note
>
> All of the modules can be configured to use a proxy to perform their respective task.

API

The following guide provides a brief overview of the usage and an example of the modules.

$3

The ProxyClient module offers a class with a set of methods to make basic HTTP requests. The class can be configured to use a proxy to perform the requests.

#### get

The get method allows performing GET requests to a server.

Parameters:

| Name | Type | Description |
| :--------- | :------------------------------------ | :--------------------------- |
| endpoint | string | The endpoint of the request. |
| options | IRequestOptions | The options of the request. |

Returns: Promise<IClientResponse>

Example:

`ts
import { ProxyClient } from '@code-exitos/react-native-proxy-client';

const proxyClient = new ProxyClient();

const response = await proxyClient.get('https://example.com', {
headers: {
'Content-Type': 'application/json',
},
query: {
foo: 'bar',
},
timeout: 10000,
retries: 3,
proxy: {
host: 'localhost',
port: 8080,
},
});
`

#### post

The post method allows performing POST requests to a server.

Parameters:

| Name | Type | Description |
| :--------- | :------------------------------------ | :--------------------------- |
| endpoint | string | The endpoint of the request. |
| body | any | The body of the request. |
| options | IRequestOptions | The options of the request. |

Returns: Promise<IClientResponse>

Example:

`ts
import { ProxyClient } from '@code-exitos/react-native-proxy-client';

const proxyClient = new ProxyClient();

const response = await proxyClient.post(
'https://example.com',
{
foo: 'bar',
},
{
headers: {
'Content-Type': 'application/json',
},
query: {
foo: 'bar',
},
timeout: 10000,
retries: 3,
proxy: {
host: 'localhost',
port: 8080,
},
}
);
`

#### put

The put method allows performing PUT requests to a server.

Parameters:

| Name | Type | Description |
| :--------- | :------------------------------------ | :--------------------------- |
| endpoint | string | The endpoint of the request. |
| body | any | The body of the request. |
| options | IRequestOptions | The options of the request. |

Returns: Promise<IClientResponse>

Example:

`ts
import { ProxyClient } from '@code-exitos/react-native-proxy-client';

const proxyClient = new ProxyClient();

const response = await proxyClient.put(
'https://example.com',
{
foo: 'bar',
},
{
headers: {
'Content-Type': 'application/json',
},
query: {
foo: 'bar',
},
timeout: 10000,
retries: 3,
proxy: {
host: 'localhost',
port: 8080,
},
}
);
`

#### patch

The patch method allows performing PATCH requests to a server.

Parameters:

| Name | Type | Description |
| :--------- | :------------------------------------ | :--------------------------- |
| endpoint | string | The endpoint of the request. |
| body | any | The body of the request. |
| options | IRequestOptions | The options of the request. |

Returns: Promise<IClientResponse>

Example:

`ts
import { ProxyClient } from '@code-exitos/react-native-proxy-client';

const proxyClient = new ProxyClient();

const response = await proxyClient.patch(
'https://example.com',
{
foo: 'bar',
},
{
headers: {
'Content-Type': 'application/json',
},
query: {
foo: 'bar',
},
timeout: 10000,
retries: 3,
proxy: {
host: 'localhost',
port: 8080,
},
}
);
`

#### delete

The delete method allows performing DELETE requests to a server.

Parameters:

| Name | Type | Description |
| :--------- | :------------------------------------ | :--------------------------- |
| endpoint | string | The endpoint of the request. |
| options | IRequestOptions | The options of the request. |

Returns: Promise<IClientResponse>

Example:

`ts
import { ProxyClient } from '@code-exitos/react-native-proxy-client';

const proxyClient = new ProxyClient();

const response = await proxyClient.delete('https://example.com', {
headers: {
'Content-Type': 'application/json',
},
query: {
foo: 'bar',
},
timeout: 10000,
retries: 3,
proxy: {
host: 'localhost',
port: 8080,
},
});
`

$3

The ProxyEventSource module offers a class that allows to create a connection and listen to events on a given endpoint. The class can be configured to use a proxy to perform the requests.

> Note: The ProxyEventSource module has a pending work in progress. We need to assign a unique id per so that we can manage multiple instances.

#### Constructor

The ProxyEventSource class can be instantiated with the following parameters:

| Name | Type | Description |
| :--------- | :-------------------------------- | :--------------------------- |
| endpoint | string | The endpoint of the request. |
| headers | Record | The options of the request. |
| options | IProxyOptions | The options of the request. |

Example:

`ts
import { ProxyEventSource } from '@code-exitos/react-native-proxy-client';

const proxyEventSource = new ProxyEventSource(
'https://example.com/sse',
{
Authorization: 'Bearer your-token-goes-here',
},
{
host: 'localhost',
port: 8080,
}
);
`

#### addEventListener

The addEventListener method allows to add a custom listener to the event source.

Parameters:

| Name | Type | Description |
| :--------- | :------------------------------------------------------------ | :--------------------------- |
| event | string | The event of the request. |
| listener | EventSourceListenerCallback | The listener of the request. |

Returns: void

Example:

`ts
import { ProxyEventSource } from '@code-exitos/react-native-proxy-client';

const proxyEventSource = new ProxyEventSource('https://example.com/sse');

proxyEventSource.addEventListener('custom-event', (id, event, data) => {
console.log({ id, event, data });
});
`

#### removeEventListener

The removeEventListener method allows to remove a custom listener from the event source.

Parameters:

| Name | Type | Description |
| :------ | :------- | :------------------------ |
| event | string | The event of the request. |

Returns: void

Example:

`ts
import { ProxyEventSource } from '@code-exitos/react-native-proxy-client';

const proxyEventSource = new ProxyEventSource('https://example.com/sse');

proxyEventSource.removeEventListener('custom-event');
`

#### onMessage

The onMessage method allows to add a listener to the message event of the event source.

Parameters:

| Name | Type | Description |
| :------------------ | :------------------------------------------------------------ | :--------------------------- |
| onMessageCallback | EventSourceListenerCallback | The listener of the request. |

Returns: void

Example:

`ts
import { ProxyEventSource } from '@code-exitos/react-native-proxy-client';

const proxyEventSource = new ProxyEventSource('https://example.com/sse');

proxyEventSource.onMessage((id, event, data) => {
console.log({ id, event, data });
});
`

#### onOpen

The onOpen method allows to add a listener to the open event of the event source.

Parameters:

| Name | Type | Description |
| :--------------- | :----------- | :--------------------------- |
| onOpenCallback | () => void | The listener of the request. |

Returns: void

Example:

`ts
import { ProxyEventSource } from '@code-exitos/react-native-proxy-client';

const proxyEventSource = new ProxyEventSource('https://example.com/sse');

proxyEventSource.onOpen(() => {
console.log('Connection opened');
});
`

#### onComplete

The onComplete method allows to add a listener when the connection has ended.

Parameters:

| Name | Type | Description |
| :------------------- | :------------------------------------------------------------ | :--------------------------- |
| onCompleteCallback | EventSourceCompleteCallback | The listener of the request. |

Returns: void

Example:

`ts
import { ProxyEventSource } from '@code-exitos/react-native-proxy-client';

const proxyEventSource = new ProxyEventSource('https://example.com/sse');

proxyEventSource.onComplete((error, statusCode, shouldReconnect) => {
console.log({ error, statusCode, shouldReconnect });
});
`

#### disconnect

The disconnect method allows to disconnect the connection.

Returns: void

Example:

`ts
import { ProxyEventSource } from '@code-exitos/react-native-proxy-client';

const proxyEventSource = new ProxyEventSource('https://example.com/sse');

proxyEventSource.disconnect();
`

$3

The ProxyFileManager module offers a class that enables methods to upload and download files.

#### upload

The upload method allows to upload a file to a remote server. The method is hardcoded to use the POST method and a Content-Type of multipart/form-data.

Parameters:

| Name | Type | Description |
| :--------- | :-------------------------------------------- | :--------------------------- |
| endpoint | string | The endpoint of the request. |
| file | FormData | The file to be uploaded. |
| options | IFileRequestOptions | The options of the request. |

Returns: Promise<IClientResponse>

Example:

`ts
import { ProxyFileManager } from '@code-exitos/react-native-proxy-client';
import { FormData, FileData } from '@code-exitos/react-native-proxy-client';

const formData = new FormData();

formData.append('key', 'value');
formData.append(
'file',
new FileData(
'file.txt',
'text/plain',
123455,
'/file.txt',
'file:///file.txt'
)
);

const proxyFileManager = new ProxyFileManager();

proxyFileManager.upload('https://example.com/upload', formData, {
headers: {
Authorization: 'Bearer your-token-goes-here',
},
});
`

#### download

The download method allows to download a file from a remote server. The method is hardcoded to use the GET method.

Parameters:

| Name | Type | Description |
| :-------- | :-------------------------------------------- | :-------------------------- |
| from | string | The endpoint of the file. |
| to | string | The path to save the file. |
| options | IFileRequestOptions | The options of the request. |

Returns: Promise<IClientResponse>

Example:

`ts
import { ProxyFileManager } from '@code-exitos/react-native-proxy-client';

const proxyFileManager = new ProxyFileManager();

const res = await proxyFileManager.download(
'https://example.com/file.txt',
'/file.txt',
{
headers: {
Authorization: 'Bearer your-token-goes-here',
},
}
);

const path = res.data;
`

$3

The FormData class enables an alternative to the native JS FormData API. The problem that we have with this native class is that is to unpredictable as to what data is being appended to it.

To fix this, we created are own custom form data class that enforces the data that we can handle on the module.

The data that can be appended to the form data is:

- string
- FileData

#### append

The append method allows to append data to the form data.

Parameters:

| Name | Type | Description |
| :----- | :---------------------------------- | :----------------------- |
| key | string | The key of the data. |
| data | string \| FileData | The data to be appended. |

Returns: void

Example:

`ts
import { FormData, FileData } from '@code-exitos/react-native-proxy-client';

const formData = new FormData();

formData.append('key', 'value');
formData.append(
'file',
new FileData(
'file.txt',
'text/plain',
123455,
'/file.txt',
'file:///file.txt'
)
);
`

#### FormData.delete

The delete method allows to delete a key from the form data.

Parameters:

| Name | Type | Description |
| :---- | :------- | :------------------- |
| key | string | The key of the data. |

Returns: void

Example:

`ts
import { FormData } from '@code-exitos/react-native-proxy-client';

const formData = new FormData();

formData.append('key', 'value');

formData.delete('key');
`

#### FormData.get

The get method allows to get the data of a key from the form data.

Parameters:

| Name | Type | Description |
| :---- | :------- | :------------------- |
| key | string | The key of the data. |

Returns: string \| FileData

Example:

`ts
import { FormData, FileData } from '@code-exitos/react-native-proxy-client';

const formData = new FormData();

formData.append('key', 'value');

const data = formData.get('key');
`

#### getAll

The getAll method allows to get all the data from the form data.

Returns: Array

Example:

`ts
import { FormData, FileData } from '@code-exitos/react-native-proxy-client';

const formData = new FormData();

formData.append('key', 'value');
formData.append(
'file',
new FileData(
'file.txt',
'text/plain',
123455,
'/file.txt',
'file:///file.txt'
)
);

const data = formData.getAll();
`

#### has

The has method allows to check if the form data has a key.

Parameters:

| Name | Type | Description |
| :---- | :------- | :------------------- |
| key | string | The key of the data. |

Returns: boolean

Example:

`ts
import { FormData } from '@code-exitos/react-native-proxy-client';

const formData = new FormData();

formData.append('key', 'value');

const hasKey = formData.has('key');
`

#### value

The value getter exposes the value of the form data in the form of an object.

Returns: Record

`ts
import { FormData, FileData } from '@code-exitos/react-native-proxy-client';

const formData = new FormData();

formData.append('key', 'value');
formData.append(
'file',
new FileData(
'file.txt',
'text/plain',
123455,
'/file.txt',
'file:///file.txt'
)
);

const data = formData.value;
`

#### FileData

The FileData class defines an instance of the data that is going to be used to upload a file. The class implements the IFileData interface.

$3

The ProxySocket module offers a class that enables methods to connect to a remote server via a socket. The module can be configured to use either raw WebSockets or Socket.IO.

> Note
> The module doesn't work completely when applying proxies.
> | OS | Raw WebSockets with proxy | Socket.IO with proxy | Raw WebSockets without proxy | Socket.IO without proxy |
> | :--- | :--- | :--- | :--- | :--- |
> | Android | ❌ | ✅ | ✅ | ✅ |
> | iOS | ❌ | ❌ | ✅ | ✅ |

$3

#### IProxyOptions

The IProxyOptions interface defines the options that can be used to configure the proxies.

| Property | Type | Description |
| :------- | :---------------------------------------- | :------------------------------------ |
| host | string | The host of the proxy. |
| port | number | The port of the proxy. |
| auth | IProxyAuthOptions | The authentication info of the proxy. |

##### IProxyAuthOptions

The IProxyAuthOptions interface defines the options that can be used to configure the authentication of the proxies.

| Property | Type | Description |
| :--------- | :------- | :------------------------- |
| username | string | The username of the proxy. |
| password | string | The password of the proxy. |

#### IRequestOptions

The IRequestOptions interface defines the options that can be used to configure the requests.

| Property | Type | Description |
| :-------- | :-------------------------------- | :------------------------------------ |
| headers | Record | The headers of the request. |
| query | Record | The query parameters of the request. |
| timeout | number | The timeout of the request. |
| retries | number | The number of retries of the request. |
| proxy | IProxyOptions | The proxy of the request. |
| body | any | The body of the request. |

#### IClientResponse

The IClientResponse interface defines the response to the requests.

| Property | Type | Description |
| :----------- | :-------------------- | :----------------------------------- |
| data | T | The data of the response. |
| statusCode | number | The status of the response. |
| headers | Record | The headers of the response. |
| endpoint | string | The endpoint of the response. |
| method | string | The method of the response. |
| query | Record | The query parameters of the request. |

#### EventSourceListenerCallback

The EventSourceListenerCallback interface defines the callback that will be called when an event is received.

Parameters:

| Property | Type | Description |
| :------- | :------- | :--------------------- |
| id | string | The id of the event. |
| event | string | The name of the event. |
| data | string | The data of the event. |

Returns: void

#### EventSourceCompleteCallback

The EventSourceCompleteCallback interface defines the callback that will be called when the connection is closed.

Parameters:

| Property | Type | Description |
| :---------------- | :-------- | :--------------------------------------------------------- |
| error | Error | The possible error of the reason why the connection ended. |
| statusCode | number | The status code of the response. |
| shouldReconnect | boolean | Whether the connection should be reconnected. |

Returns: void

#### SocketType

The SocketType enum defines the different types of sockets that can be used to perform the requests.

Values:

- SocketIO = 'socket.io'
- WS = 'ws'

#### ISocketOptions

The ISocketOptions interface defines the options that can be used to configure the sockets.

| Property | Type | Description |
| :--------------------- | :-------------------- | :---------------------------------------------------- |
| type | string | The type of the socket. |
| headers | Record | The headers of the socket. |
| query | Record | The query parameters of the socket. |
| autoConnect | boolean | Whether the socket should be connected automatically. |
| timeout | number | The timeout of the socket. |
| reconnection | boolean | Whether the socket should be reconnected. |
| reconnectionAttempts | number | The number of reconnection attempts. |
| reconnectionDelay | number | The delay of the reconnection. |

#### SocketEmitErrorCallback

The SocketEmitErrorCallback interface defines the callback that will be called when an error is received.

Parameters:

| Property | Type | Description |
| :------- | :------- | :------------------------------------- |
| args | object | The arguments with the possible error. |

Returns: void

#### SocketOnEventListenerCallback

The SocketOnEventListenerCallback interface defines the callback that will be called when an event is received.

Parameters:

| Property | Type | Description |
| :------- | :------- | :--------------------------- |
| args | object | The data sent by the emitter |

Returns: void

#### IFileData

The IFileData interface defines the data that can be used to create a file.

| Property | Type | Description |
| :--------- | :------- | :------------------------- |
| filename | string | The name of the file. |
| mimetype | string | The mime type of the file. |
| size | number | The size of the file. |
| path | string | The path of the file. |
| uri | string | The uri of the file. |

#### IFileRequestOptions

The IFileRequestOptions interface defines the options that can be used to configure the file requests.

| Property | Type | Description |
| :-------- | :-------------------------------- | :------------------------------------ |
| headers | Record | The headers of the request. |
| query | Record | The query parameters of the request. |
| timeout | number | The timeout of the request. |
| retries | number | The number of retries of the request. |
| proxy | IProxyOptions` | The proxy of the request. |

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library