@randomorg/core
Version:
The official library to access the RANDOM.ORG JSON-RPC API
818 lines (789 loc) • 125 kB
JavaScript
'use strict';
const {
RandomOrgBadHTTPResponseError,
RandomOrgInsufficientBitsError,
RandomOrgInsufficientRequestsError,
RandomOrgJSONRPCError,
RandomOrgKeyNotRunningError,
RandomOrgRANDOMORGError,
RandomOrgSendTimeoutError
} = require('./RandomOrgErrors.js');
const RandomOrgCache = require('./RandomOrgCache.js');
/* node-import */
const XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
/* end-node-import */
/**
* RandomOrgClient main class through which API functions are accessed.
*
* This class provides access to both the signed and unsigned methods of the
* RANDOM.ORG API.
*
* The class also provides access to the creation of a convenience class, RandomOrgCache,
* for precaching API responses when the request is known in advance.
*
* This class will only allow the creation of one instance per API key. If an
* instance of this class already exists for a given key, that instance will be
* returned instead of a new instance.
*
* This class obeys most of the guidelines set forth in https://api.random.org/json-rpc/4
* All requests respect the server's advisoryDelay returned in any responses, or use
* DEFAULT_DELAY if no advisoryDelay is returned. If the supplied API key is paused, i.e.,
* has exceeded its daily bit/request allowance, this implementation will back off until
* midnight UTC.
*/
module.exports = class RandomOrgClient {
// Basic API
static #INTEGER_METHOD = 'generateIntegers';
static #INTEGER_SEQUENCE_METHOD = 'generateIntegerSequences';
static #DECIMAL_FRACTION_METHOD = 'generateDecimalFractions';
static #GAUSSIAN_METHOD = 'generateGaussians';
static #STRING_METHOD = 'generateStrings';
static #UUID_METHOD = 'generateUUIDs';
static #BLOB_METHOD = 'generateBlobs';
static #GET_USAGE_METHOD = 'getUsage';
// Signed API
static #SIGNED_INTEGER_METHOD = 'generateSignedIntegers';
static #SIGNED_INTEGER_SEQUENCE_METHOD = 'generateSignedIntegerSequences';
static #SIGNED_DECIMAL_FRACTION_METHOD = 'generateSignedDecimalFractions';
static #SIGNED_GAUSSIAN_METHOD = 'generateSignedGaussians';
static #SIGNED_STRING_METHOD = 'generateSignedStrings';
static #SIGNED_UUID_METHOD = 'generateSignedUUIDs';
static #SIGNED_BLOB_METHOD = 'generateSignedBlobs';
static #GET_RESULT_METHOD = 'getResult';
static #CREATE_TICKET_METHOD = 'createTickets';
static #LIST_TICKET_METHOD = 'listTickets';
static #REVEAL_TICKET_METHOD = 'revealTickets';
static #GET_TICKET_METHOD = 'getTicket';
static #VERIFY_SIGNATURE_METHOD = 'verifySignature';
// Blob format literals
/** Blob format literal, base64 encoding (default). */
static BLOB_FORMAT_BASE64 = 'base64';
/** Blob format literal, hex encoding. */
static BLOB_FORMAT_HEX = 'hex';
// Default values
/** Default value for the replacement parameter (true). */
static DEFAULT_REPLACEMENT = true;
/** Default value for the base parameter (10). */
static DEFAULT_BASE = 10;
/** Default value for the userData parameter (null). */
static DEFAULT_USER_DATA = null;
/** Default value for the ticketId parameter (null). */
static DEFAULT_TICKET_ID = null;
/** Default value for the pregeneratedRandomization parameter (null). */
static DEFAULT_PREGENERATED_RANDOMIZATION = null;
/** Default value for the licenseData parameter (null). */
static DEFAULT_LICENSE_DATA = null;
/** Size of a single UUID in bits. */
static UUID_SIZE = 122;
/** Default value for the blockingTimeout parameter (1 day). */
static DEFAULT_BLOCKING_TIMEOUT = 24 * 60 * 60 * 1000;
/** Default value for the httpTimeout parameter (2 minutes). */
static DEFAULT_HTTP_TIMEOUT = 120 * 1000;
/** Maximum number of characters allowed in a signature verficiation URL. */
static MAX_URL_LENGTH = 2046;
// Default back-off to use if no advisoryDelay back-off supplied by server (1 second)
static #DEFAULT_DELAY = 1*1000;
// On request fetch fresh allowance state if current state data is older than
// this value (1 hour).
static #ALLOWANCE_STATE_REFRESH_SECONDS = 3600 * 1000;
// Maintains usage statistics from server.
#bitsLeft = -1;
#requestsLeft = -1;
// Back-off info for when the API key is detected as not running, probably
// because the key has exceeded its daily usage limit. Back-off runs until
// midnight UTC.
#backoff = -1;
#backoffError = '';
#apiKey = '';
#blockingTimeout = RandomOrgClient.DEFAULT_BLOCKING_TIMEOUT;
#httpTimeout = RandomOrgClient.DEFAULT_HTTP_TIMEOUT;
// Maintain info to obey server advisory delay
#advisoryDelay = 0;
#lastResponseReceivedTime = 0;
// Maintains a dictionary of API keys and their instances.
static #keyIndexedInstances = {};
static #ERROR_CODES = [ 100, 101, 200, 201, 202, 203, 204, 300,
301, 302, 303, 304, 305, 306, 307, 400, 401, 402, 403, 404,
405, 420, 421, 422, 423, 424, 425, 426, 500, 32000 ];
/**
* Constructor. Ensures only one instance of RandomOrgClient exists per API
* key. Creates a new instance if the supplied key isn't already known,
* otherwise returns the previously instantiated one.
* @constructor
* @param {string} apiKey API key of instance to create/find, obtained from
* RANDOM.ORG, see https://api.random.org/api-keys
* @param {{blockingTimeout?: number, httpTimeout?: number}} options An object
* which may contains any of the following optional parameters:
* @param {number} [options.blockingTimeout = 24 * 60 * 60 * 1000] Maximum
* time in milliseconds to wait before being allowed to send a request.
* Note this is a hint not a guarantee. The advisory delay from server
* must always be obeyed. Supply a value of -1 to allow blocking forever
* (default 24 * 60 * 60 * 1000, i.e., 1 day).
* @param {number} [options.httpTimeout = 120 * 1000] Maximum time in
* milliseconds to wait for the server response to a request (default
* 120*1000).
*/
constructor(apiKey, options = {}) {
if (RandomOrgClient.#keyIndexedInstances && RandomOrgClient.#keyIndexedInstances[apiKey]) {
return RandomOrgClient.#keyIndexedInstances[apiKey];
} else {
this.#apiKey = apiKey;
this.#blockingTimeout = options.blockingTimeout || 24 * 60 * 60 * 1000;
this.#httpTimeout = options.httpTimeout || 120 * 1000;
RandomOrgClient.#keyIndexedInstances[apiKey] = this;
}
}
// Basic API
/**
* Requests and returns an array of true random integers within a user-defined
* range from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateIntegers
* @param {number} n The number of random integers you need. Must be within
* the [1,1e4] range.
* @param {number} min The lower boundary for the range from which the random
* numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {number} max The upper boundary for the range from which the random
* numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {{replacement?: boolean, base?: number, pregeneratedRandomization?:
* Object}} options An object which may contains any of the following
* optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* numbers should be picked with replacement. If true, the resulting numbers
* may contain duplicate values, otherwise the numbers will all be unique
* (default true).
* @param {number} [options.base=10] The base that will be used to display
* the numbers. Values allowed are 2, 8, 10 and 16 (default 10).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {(Promise<number[]>|Promise<string[]>)} A Promise which, if
* resolved successfully, represents an array of true random integers.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
* */
async generateIntegers(n, min, max, options = {}) {
let request = this.#integerRequest(n, min, max, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns an array of true random integer sequences within a
* user-defined range from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateIntegerSequences
* @param {number} n How many arrays of random integers you need. Must be
* within the [1,1e3] range.
* @param {(number|number[])} length The length of each array of random
* integers requested. For uniform sequences, length must be an integer
* in the [1, 1e4] range. For multiform sequences, length can be an array
* with n integers, each specifying the length of the sequence identified
* by its index. In this case, each value in length must be within the
* [1, 1e4] range and the total sum of all the lengths must be in the
* [1, 1e4] range.
* @param {(number|number[])} min The lower boundary for the range from which
* the random numbers will be picked. For uniform sequences, min must be
* an integer in the [-1e9, 1e9] range. For multiform sequences, min can
* be an array with n integers, each specifying the lower boundary of the
* sequence identified by its index. In this case, each value in min must
* be within the [-1e9, 1e9] range.
* @param {(number|number[])} max The upper boundary for the range from which
* the random numbers will be picked. For uniform sequences, max must be
* an integer in the [-1e9, 1e9] range. For multiform sequences, max can
* be an array with n integers, each specifying the upper boundary of the
* sequence identified by its index. In this case, each value in max must
* be within the [-1e9, 1e9] range.
* @param {{replacement?: boolean|boolean[], base?: number|number[],
* pregeneratedRandomization?: Object}} options An object which may contains
* any of the following optional parameters:
* @param {(boolean|boolean[])} [options.replacement=true] Specifies whether
* the random numbers should be picked with replacement. If true, the
* resulting numbers may contain duplicate values, otherwise the numbers
* will all be unique. For multiform sequences, replacement can be an array
* with n boolean values, each specifying whether the sequence identified
* by its index will be created with (true) or without (false) replacement
* (default true).
* @param {(number|number[])} [options.base=10] The base that will be used
* to display the numbers. Values allowed are 2, 8, 10 and 16. For multiform
* sequences, base can be an array with n integer values taken from the
* same set, each specifying the base that will be used to display the
* sequence identified by its index (default 10).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {(Promise<number[][]>|Promise<string[][]>)} A Promise which, if
* resolved successfully, represents an array of true random integer
* sequences.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateIntegerSequences(n, length, min, max, options = {}) {
let request = this.#integerSequenceRequest(n, length, min, max, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of true random decimal fractions,
* from a uniform distribution across the [0,1] interval with a user-defined
* number of decimal places from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateDecimalFractions
* @param {number} n How many random decimal fractions you need. Must be
* within the [1,1e4] range.
* @param {number} decimalPlaces The number of decimal places to use. Must be
* within the [1,20] range.
* @param {{replacement?: boolean, pregeneratedRandomization?: Object}} options
* An object which may contains any of the following optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* numbers should be picked with replacement. If true, the resulting numbers
* may contain duplicate values, otherwise the numbers will all be unique
* (default true).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<number[]>} A Promise which, if resolved successfully,
* represents an array of true random decimal fractions.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateDecimalFractions(n, decimalPlaces, options = {}) {
let request = this.#decimalFractionRequest(n, decimalPlaces, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of true random numbers from a
* Gaussian distribution (also known as a normal distribution).
*
* The form uses a Box-Muller Transform to generate the Gaussian distribution
* from uniformly distributed numbers.
* See: https://api.random.org/json-rpc/4/basic#generateGaussians
* @param {number} n How many random numbers you need. Must be within the
* [1,1e4] range.
* @param {number} mean The distribution's mean. Must be within the
* [-1e6,1e6] range.
* @param {number} standardDeviation The distribution's standard deviation.
* Must be within the [-1e6,1e6] range.
* @param {number} significantDigits The number of significant digits to use.
* Must be within the [2,20] range.
* @param {{pregeneratedRandomization?: Object}} options An object which may
* contains any of the following optional parameters:
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<number[]>} A Promise which, if resolved successfully,
* represents an array of true random numbers from a Gaussian distribution.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateGaussians(n, mean, standardDeviation, significantDigits, options = {}) {
let request = this.#gaussianRequest(n, mean, standardDeviation,
significantDigits, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of true random unicode strings from
* the server. See: https://api.random.org/json-rpc/4/basic#generateStrings
* @param {number} n How many random strings you need. Must be within the
* [1,1e4] range.
* @param {number} length The length of each string. Must be within the
* [1,20] range. All strings will be of the same length.
* @param {string} characters A string that contains the set of characters
* that are allowed to occur in the random strings. The maximum number
* of characters is 80.
* @param {{replacement?: boolean, pregeneratedRandomization?: Object}} options
* An object which may contains any of the following optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* strings should be picked with replacement. If true, the resulting list
* of strings may contain duplicates, otherwise the strings will all be
* unique (default true).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<string[]>} A Promise which, if resolved successfully,
* represents an array of true random strings.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateStrings(n, length, characters, options = {}) {
let request = this.#stringRequest(n, length, characters, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of version 4 true random Universally
* Unique IDentifiers (UUIDs) in accordance with section 4.4 of RFC 4122,
* from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateUUIDs
* @param {number} n How many random UUIDs you need. Must be within the
* [1,1e3] range.
* @param {{pregeneratedRandomization?: Object}} options An object which may
* contains any of the following optional parameters:
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<string[]>} A Promise which, if resolved successfully,
* represents an array of true random UUIDs.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateUUIDs(n, options = {}) {
let request = this.#UUIDRequest(n, options);
return this.#extractBasic(this.#sendRequest(request));
}
/**
* Requests and returns a list (size n) of Binary Large OBjects (BLOBs)
* as unicode strings containing true random data from the server.
*
* See: https://api.random.org/json-rpc/4/basic#generateBlobs
* @param {number} n How many random blobs you need. Must be within the
* [1,100] range.
* @param {number} size The size of each blob, measured in bits. Must be
* within the [1,1048576] range and must be divisible by 8.
* @param {{format?: string, pregeneratedRandomization?: Object}} options
* An object which may contains any of the following optional parameters:
* @param {string} [options.format='base64'] Specifies the format in which
* the blobs will be returned. Values allowed are 'base64' and 'hex'
* (default 'base64').
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @returns {Promise<number[]>} A Promise which, if resolved successfully,
* represents an array of true random blobs as strings.
* @see {@link RandomOrgClient#BLOB_FORMAT_BASE64} for 'base64' (default).
* @see {@link RandomOrgClient#BLOB_FORMAT_HEX} for 'hex'.
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateBlobs(n, size, options = {}) {
let request = this.#blobRequest(n, size, options);
return this.#extractBasic(this.#sendRequest(request));
}
// SIGNED API
/**
* Requests a list (size n) of true random integers within a user-defined
* range from the server.
*
* Returns a Promise which, if resolved successfully, respresents an object
* with the parsed integer list mapped to 'data', the original response mapped
* to 'random', and the response's signature mapped to 'signature'.
* See: https://api.random.org/json-rpc/4/signed#generateSignedIntegers
* @param {number} n How many random integers you need. Must be within the
* [1,1e4] range.
* @param {number} min The lower boundary for the range from which the
* random numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {number} max The upper boundary for the range from which the
* random numbers will be picked. Must be within the [-1e9,1e9] range.
* @param {{replacement?: boolean, base?: number, pregeneratedRandomization?:
* Object, licenseData?: Object, userData?: Object|number|string, ticketId?:
* string}} options An object which may contains any of the following
* optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* numbers should be picked with replacement. If true, the resulting numbers
* may contain duplicate values, otherwise the numbers will all be unique
* (default true).
* @param {number} [options.base=10] The base that will be used to display
* the numbers. Values allowed are 2, 8, 10 and 16 (default 10).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @param {Object} [options.licenseData=null] A dictionary object which allows
* the caller to include data of relevance to the license that is associated
* with the API Key. This is mandatory for API Keys with the license type
* 'Flexible Gambling' and follows the format { 'maxPayout': { 'currency':
* 'XTS', 'amount': 0.0 }}. This information is used in licensing
* requested random values and in billing. The currently supported
* currencies are: 'USD', 'EUR', 'GBP', 'BTC', 'ETH'. The most up-to-date
* information on the currencies can be found in the Signed API
* documentation, here: https://api.random.org/json-rpc/4/signed
* @param {(string|number|Object)} [options.userData=null] Object that will be
* included in unmodified form. Its maximum size in encoded (string) form is
* 1,000 characters (default null).
* @param {string} [options.ticketId=null] A string with ticket identifier obtained
* via the {@link RandomOrgClient#createTickets} method. Specifying a value
* for ticketId will cause RANDOM.ORG to record that the ticket was used
* to generate the requested random values. Each ticket can only be used
* once (default null).
* @returns {Promise<{data: number[]|string[], random: Object, signature: string}>}
* A Promise which, if resolved successfully, represents an object with the
* following structure:
* * **data**: array of true random integers
* * **random**: random field as returned from the server
* * **signature**: signature string
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateSignedIntegers(n, min, max, options = {}) {
let request = this.#integerRequest(n, min, max, options, true);
return this.#extractSigned(this.#sendRequest(request));
}
/**
* Requests and returns uniform or multiform sequences of true random integers
* within user-defined ranges from the server.
*
* Returns a Promise which, if resolved successfully, respresents an object
* with the parsed array of integer sequences mapped to 'data', the original
* response mapped to 'random', and the response's signature mapped to
* 'signature'.
* See: https://api.random.org/json-rpc/4/signed#generateIntegerSequences
* @param {number} n How many arrays of random integers you need. Must be
* within the [1,1e3] range.
* @param {(number|number[])} length The length of each array of random
* integers requested. For uniform sequences, length must be an integer
* in the [1, 1e4] range. For multiform sequences, length can be an array
* with n integers, each specifying the length of the sequence identified
* by its index. In this case, each value in length must be within the
* [1, 1e4] range and the total sum of all the lengths must be in the
* [1, 1e4] range.
* @param {(number|number[])} min The lower boundary for the range from which
* the random numbers will be picked. For uniform sequences, min must be
* an integer in the [-1e9, 1e9] range. For multiform sequences, min can
* be an array with n integers, each specifying the lower boundary of the
* sequence identified by its index. In this case, each value in min must
* be within the [-1e9, 1e9] range.
* @param {(number|number[])} max The upper boundary for the range from which
* the random numbers will be picked. For uniform sequences, max must be
* an integer in the [-1e9, 1e9] range. For multiform sequences, max can
* be an array with n integers, each specifying the upper boundary of the
* sequence identified by its index. In this case, each value in max must
* be within the [-1e9, 1e9] range.
* @param {{replacement?: boolean|boolean[], base?: number|number[],
* pregeneratedRandomization?: Object, licenseData?: Object, userData?:
* Object|number|string, ticketId?: string}} options An object which may
* contains any of the following optional parameters:
* @param {(boolean|boolean[])} [options.replacement=true] Specifies whether
* the random numbers should be picked with replacement. If true, the
* resulting numbers may contain duplicate values, otherwise the numbers
* will all be unique. For multiform sequences, replacement can be an array
* with n boolean values, each specifying whether the sequence identified by
* its index will be created with (true) or without (false) replacement
* (default true).
* @param {(number|number[])} [options.base=10] The base that will be used to
* display the numbers. Values allowed are 2, 8, 10 and 16. For multiform
* sequences, base can be an array with n integer values taken from the same
* set, each specifying the base that will be used to display the sequence
* identified by its index (default 10).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @param {Object} [options.licenseData=null] A dictionary object which allows
* the caller to include data of relevance to the license that is associated
* with the API Key. This is mandatory for API Keys with the license type
* 'Flexible Gambling' and follows the format { 'maxPayout': { 'currency':
* 'XTS', 'amount': 0.0 }}. This information is used in licensing
* requested random values and in billing. The currently supported
* currencies are: 'USD', 'EUR', 'GBP', 'BTC', 'ETH'. The most up-to-date
* information on the currencies can be found in the Signed API
* documentation, here: https://api.random.org/json-rpc/4/signed
* @param {(string|number|Object)} [options.userData=null] Object that will be
* included in unmodified form. Its maximum size in encoded (String) form
* is 1,000 characters (default null).
* @param {string} [options.ticketId=null] A string with ticket identifier
* obtained via the {@link RandomOrgClient#createTickets} method. Specifying
* a value for ticketId will cause RANDOM.ORG to record that the ticket was
* used to generate the requested random values. Each ticket can only be used
* once (default null).
* @returns {Promise<{data: number[][]|string[][], random: Object, signature: string}>}
* A Promise which, if resolved successfully, represents an object with the
* following structure:
* * **data**: array of true random integer sequences
* * **random**: random field as returned from the server
* * **signature**: signature string
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateSignedIntegerSequences(n, length, min, max, options = {}) {
let request = this.#integerSequenceRequest(n, length, min, max, options, true);
return this.#extractSigned(this.#sendRequest(request));
}
/**
* Request a list (size n) of true random decimal fractions, from a uniform
* distribution across the [0,1] interval with a user-defined number of
* decimal places from the server.
*
* Returns a Promise which, if resolved successfully, respresents an object
* with the parsed decimal fractions mapped to 'data', the original response
* mapped to 'random', and the response's signature mapped to 'signature'. See:
* https://api.random.org/json-rpc/4/signed#generateSignedDecimalFractions
* @param {number} n How many random decimal fractions you need. Must be
* within the [1,1e4] range.
* @param {number} decimalPlaces The number of decimal places to use. Must
* be within the [1,20] range.
* @param {{replacement?: boolean, pregeneratedRandomization?: Object, licenseData?:
* Object, userData?: Object|number|string, ticketId?: string}} options An
* object which may contains any of the following optional parameters:
* @param {boolean} [options.replacement=true] Specifies whether the random
* numbers should be picked with replacement. If true, the resulting numbers
* may contain duplicate values, otherwise the numbers will all be unique
* (default true).
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @param {Object} [options.licenseData=null] A dictionary object which allows
* the caller to include data of relevance to the license that is associated
* with the API Key. This is mandatory for API Keys with the license type
* 'Flexible Gambling' and follows the format { 'maxPayout': { 'currency':
* 'XTS', 'amount': 0.0 }}. This information is used in licensing
* requested random values and in billing. The currently supported
* currencies are: 'USD', 'EUR', 'GBP', 'BTC', 'ETH'. The most up-to-date
* information on the currencies can be found in the Signed API
* documentation, here: https://api.random.org/json-rpc/4/signed
* @param {(string|number|Object)} [options.userData=null] Object that will be
* included in unmodified form. Its maximum size in encoded (String) form
* is 1,000 characters (default null).
* @param {string} [options.ticketId=null] A string with ticket identifier
* obtained via the {@link RandomOrgClient#createTickets} method. Specifying
* a value for ticketId will cause RANDOM.ORG to record that the ticket was
* used to generate the requested random values. Each ticket can only be used
* once (default null).
* @returns {Promise<{data: number[], random: Object, signature: string}>} A
* Promise which, if resolved successfully, represents an object with the
* following structure:
* * **data**: array of true random decimal fractions
* * **random**: random field as returned from the server
* * **signature**: signature string
* @throws {RandomOrgSendTimeoutError} Thrown when blocking timeout is exceeded
* before the request can be sent.
* @throws {RandomOrgKeyNotRunningError} Thrown when the API key has been
* stopped.
* @throws {RandomOrgInsufficientRequestsError} Thrown when the API key's server
* requests allowance has been exceeded.
* @throws {RandomOrgInsufficientBitsError} Thrown when the API key's server
* bits allowance has been exceeded.
* @throws {RandomOrgBadHTTPResponseError} Thrown when a HTTP 200 OK response
* is not received.
* @throws {RandomOrgRANDOMORGError} Thrown when the server returns a RANDOM.ORG
* Error.
* @throws {RandomOrgJSONRPCError} Thrown when the server returns a JSON-RPC Error.
*/
async generateSignedDecimalFractions(n, decimalPlaces, options = {}) {
let request = this.#decimalFractionRequest(n, decimalPlaces, options, true);
return this.#extractSigned(this.#sendRequest(request));
}
/**
* Request a list (size n) of true random numbers from a Gaussian distribution
* (also known as a normal distribution).
*
* Returns a Promise which, if resolved successfully, respresents an object
* with the parsed numbers mapped to 'data', the original response mapped to
* 'random', and the response's signature mapped to 'signature'. See:
* https://api.random.org/json-rpc/4/signed#generateSignedGaussians
* @param {number} n How many random numbers you need. Must be within the
* [1,1e4] range.
* @param {number} mean The distribution's mean. Must be within the [-1e6,1e6]
* range.
* @param {number} standardDeviation The distribution's standard deviation.
* Must be within the [-1e6,1e6] range.
* @param {number} significantDigits The number of significant digits to use.
* Must be within the [2,20] range.
* @param {{pregeneratedRandomization?: Object, licenseData?: Object, userData?:
* Object|number|string, ticketId?: string}} options An object which may
* contains any of the following optional parameters:
* @param {Object} [options.pregeneratedRandomization=null] A dictionary object
* which allows the client to specify that the random values should be
* generated from a pregenerated, historical randomization instead of a
* one-time on-the-fly randomization. There are three possible cases:
* * **null**: The standard way of calling for random values, i.e.true
* randomness is generated and discarded afterwards.
* * **date**: RANDOM.ORG uses historical true randomness generated on the
* corresponding date (past or present, format: { 'date', 'YYYY-MM-DD' }).
* * **id**: RANDOM.ORG uses historical true randomness derived from the
* corresponding identifier in a deterministic manner. Format: { 'id',
* 'PERSISTENT-IDENTIFIER' } where 'PERSISTENT-IDENTIFIER' is a string
* with length in the [1, 64] range.
* @param {Object} [options.licenseData=null] A dictionary object which allows
* the caller to include data of relevance to the license that is associated
* with the API Key. This is mandatory for API Keys with the license type
* 'Flexible Gambling' and follows the format { 'maxPayout': { 'currency':
* 'XTS', 'amount': 0.0 }}. This information is used in licensing
* requested random values and in billing. The currently supported
* currencies are: 'USD', 'EUR', 'GBP', 'BTC', 'ETH'. The most up-to-date
* information on the currencies can be found in the Signed API
* documentation, here: https://api.random.org/json-rpc/4/signed
* @param {(string