@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

Installing the package

Using npm:

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

Using yarn:

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

Using pnpm:

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

Installing the pod

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.

ProxyClient

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](#iclientresponse)>

Example:

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](#iclientresponse)>

Example:

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](#iclientresponse)>

Example:

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](#iclientresponse)>

Example:

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](#iclientresponse)>

Example:

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,
  },
});

ProxyEventSource

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<string, any>	The options of the request.
options	IProxyOptions	The options of the request.

Example:

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:

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:

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:

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:

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:

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:

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

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

proxyEventSource.disconnect();

ProxyFileManager

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](#iclientresponse)<T>>

Example:

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](#iclientresponse)<T>>

Example:

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;

FormData

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:

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:

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:

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<string \| FileData>

Example:

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:

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<string, string \| FileData>

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.

ProxySocket

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	❌	❌	✅	✅

General Typings

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<string, any>	The headers of the request.
query	Record<string, any>	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<string, any>	The headers of the response.
endpoint	string	The endpoint of the response.
method	string	The method of the response.
query	Record<string, any>	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<string, any>	The headers of the socket.
query	Record<string, any>	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<string, any>	The headers of the request.
query	Record<string, any>	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