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

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

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

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

Installation

Installing the package

Installing the pod

About

Note

API

ProxyClient

get

post

put

patch

delete

ProxyEventSource

Constructor

addEventListener

removeEventListener

onMessage

onOpen

onComplete

disconnect

ProxyFileManager

upload

download

FormData

append

FormData.delete

FormData.get

getAll

has

value

FileData

ProxySocket

General Typings

IProxyOptions

IProxyAuthOptions

IRequestOptions

IClientResponse

EventSourceListenerCallback

EventSourceCompleteCallback

SocketType

ISocketOptions

SocketEmitErrorCallback

SocketOnEventListenerCallback

IFileData

IFileRequestOptions

Contributing

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads