Skip to content

Latest commit

 

History

History
1367 lines (1053 loc) · 67 KB

api.md

File metadata and controls

1367 lines (1053 loc) · 67 KB
Raw

Classes

TDXApi

Typedefs

TDXApiError : Error

The TDX api supplies detailed error information depending on the context of the call. In some instances, e.g. attempting to retrieve a resource that does not exist, the error will be a simple NotFound string message. In other cases, e.g. attempting to update 100 documents in a single call, the error will supply details for each document update that failed, such as the primary key of the document and the reason for the failure.

CommandResult : object
DatasetData : object
Resource : object
ResourceAccess : object
Zone : object

TDXApi

Kind: global class

new TDXApi(config)

Create a TDXApi instance

Param Type Description
config object the TDX configuration for the remote TDX
[config.tdxServer] string the URL of the TDX auth server, e.g. https://tdx.nqminds.com. Usually this is the only host parameter needed, as long as the target TDX conforms to the standard service naming conventions e.g. https://[service].[tdx-domain].com. In this case the individual service hosts can be derived from the tdxHost name. Optionally, you can specify each individual service host (see below). Note you only need to provide the host for services you intend to use. For example, if you only need query services, just provide the query host.
[config.commandServer] string the URL of the TDX command service, e.g. https://cmd.nqminds.com
[config.queryServer] string the URL of the TDX query service, e.g. https://q.nqminds.com
[config.databotServer] string the URL of the TDX databot service, e.g. https://databot.nqminds.com
[config.accessToken] string an access token that will be used to authorise commands and queries. Alternatively you can use the authenticate method to acquire a token.
[config.accessTokenTTL] number the TTL in seconds of the access token created when authenticating.
[config.doNotThrow] bool set to prevent throwing response errors. They will be returned in the CommandResult object. This was set by default prior to 0.5.x

Example (standard usage)

import TDXApi from "nqm-api-tdx";
const api = new TDXApi({tdxServer: "https://tdx.acme.com"});

tdxApi.authenticate(id, secret, [ttl]) ⇒ string

Authenticates with the TDX, acquiring an authorisation token.

Kind: instance method of TDXApi
Returns: string - The access token.
Throws:

  • Will throw if credentials are invalid or there is a network error contacting the TDX.
Param Type Default Description
id string the account id, or a pre-formed credentials string, e.g. "DKJG8dfg:letmein"
secret string the account secret
[ttl] number 3600 the Time-To-Live of the token in seconds, default is 1 hour. Will default to config.accessTokenTTL if not given here.

Example (authenticate using a share key and secret)

tdxApi.authenticate("DKJG8dfg", "letmein");

Example (authenticate using custom ttl of 2 hours)

tdxApi.authenticate("DKJG8dfg", "letmein", 7200);

tdxApi.addAccount(options, [wait]) ⇒ CommandResult

Adds an account to the TDX. An account can be an e-mail based user account, a share key (token) account, a databot host, an application, or an account-set (user group).

Kind: instance method of TDXApi

Param Type Default Description
options object new account options
options.accountType string the type of account, one of ["user", "token"]
[options.approved] bool account is pre-approved (reserved for system use only)
[options.authService] string the authentication type, one of ["local", "oauth:google", "oauth:github"]. Required for user-based accounts. Ignored for non-user accounts.
[options.displayName] string the human-friendly display name of the account, e.g. "Toby's share key"
[options.expires] number a timestamp at which the account expires and will no longer be granted a token
[options.key] string the account secret. Required for all but oauth-based account types.
[options.owner] string the owner of the account.
[options.scratchAccess] bool indicates this account can create resources in the owners scratch folder. Ignored for all accounts except share key (token) accounts. Is useful for databots that need to create intermediate or temporary resources without specifying a parent resource - if no parent resource is given when a resource is created and scratch access is enabled, the resource will be created in the owner's scratch folder.
[options.settings] object free-form JSON object for user data.
[options.username] string the username of the new account. Required for user-based accounts, and should be the account e-mail address. Can be omitted for non-user accounts, and will be auto-generated.
[options.verified] bool account is pre-verified (reserved for system use only)
[options.whitelist] Array.<string> a list of IP addresses. Tokens will only be granted if the requesting IP address is in this list
[wait] bool false flag indicating this method will wait for the account to be fully created before returning.

tdxApi.addAccountApplicationConnection(accountId, applicationId, [wait])

Adds the application/user connection resource. The authenticated token must belong to the application.

Kind: instance method of TDXApi

Param Type Default Description
accountId string the account id
applicationId string the application id
[wait] bool true whether or not to wait for the projection to catch up.

tdxApi.approveAccount(username, approved)

Set account approved status. Reserved for system use.

Kind: instance method of TDXApi

Param Type Description
username string the full TDX identity of the account.
approved bool account approved status

tdxApi.deleteAccount(username)

Delete an account

Kind: instance method of TDXApi

Param Type Description
username string the full TDX identity of the account to delete.

tdxApi.resetAccount(username, key)

Change account secret.

Kind: instance method of TDXApi

Param Type Description
username string the full TDX identity of the account.
key string the new secret

tdxApi.updateAccount(username, options)

Updates account details. All update properties are optional. See createAccount for full details of each option.

Kind: instance method of TDXApi

Param Type Description
username string the full TDX identity of the account to update.
options object the update options
[options.displayName] string
[options.key] string
[options.scratchAccess] bool
[options.settings] object
[options.whitelist] Array.<string>

tdxApi.verifyAccount(username, approved)

Set account verified status. Reserved for system use.

Kind: instance method of TDXApi

Param Type Description
username string the full TDX identity of the account.
approved bool account verified status

tdxApi.addTrustedExchange(options)

Adds a data exchange to the list of trusted exchanges known to the current TDX.

Kind: instance method of TDXApi

Param Type Description
options object
options.owner string the account on this TDX to which the trust relates, e.g. bob@mail.com/tdx.acme.com
options.targetServer string the TDX to be trusted, e.g. tdx.nqminds.com
options.targetOwner string the account on the target TDX that is trusted, e.g. alice@mail.com/tdx.nqminds.com.

tdxApi.addResource(options, [wait])

Adds a resource to the TDX.

Kind: instance method of TDXApi

Param Type Default Description
options object details of the resource to be added.
[options.basedOnSchema] string "dataset" the id of the schema on which this resource will be based.
[options.derived] object definition of derived filter, implying this resource is a view on an existing dataset.
[options.derived.filter] object the (read) filter to apply, in mongodb query format, e.g. {"temperature": {"$gt": 15}} will mean that only data with a temperature value greater than 15 will be available in this view. The filter can be any arbitrarily complex mongodb query. Use the placeholder "@@_identity_@@" to indicate that the identity of the currently authenticated user should be substituted. For example, if the user bob@acme.com/tdx.acme.com is currently authenticated, a filter of {"username": "@@_identity_@@"} will resolve at runtime to {"username": "bob@acme.com/tdx.acme.com"}.
[options.derived.projection] object the (read) projection to apply, in mongodb projection format, e.g. {"timestamp": 1, "temperature": 1} implies only the 'timestamp' and 'temperature' properties will be returned.
[options.derived.source] string the id of the source dataset on which to apply the filters and projections.
[options.derived.writeFilter] object the write filter to apply, in mongodb query format. This controls what data can be written to the underlying source dataset. For example, a write filter of {"temperature": {"$lt": 40}} means that attempts to write a temperature value greater than or equal to 40 will fail. The filter can be any arbitrarily complex mongodb query.
[options.derived.writeProjection] object the write projection to apply, in mongodb projection format. This controls what properties can be written to the underlying dataset. For example, a write projection of {"temperature": 1} means that only the temperature field can be written, and attempts to write data to other properties will fail. To allow a view to create new data in the underlying dataset, the primary key fields must be included in the write projection.
[options.description] string a description for the resource.
[options.id] string the requested ID of the new resource. Must be unique. Will be auto-generated if omitted (recommended).
options.name string the name of the resource. Must be unique in the parent folder.
[options.meta] object a free-form object for storing metadata associated with this resource.
[options.parentId] string the id of the parent resource. If omitted, will default to the appropriate root folder based on the type of resource being created.
[options.provenance] string a description of the provenance of the resource. Markdown format is supported.
[options.queryProxy] string a url or IP address that will handle all queries to this resource
[options.schema] object optional schema definition.
[options.shareMode] string the share mode assigned to the new resource. One of ["pw", "pr", "tr"], corresponding to "public read/write", "public read/trusted write", "trusted only".
[options.tags] Array.<string> a list of tags to associate with the resource.
[options.textContent] string the text content for the resource. Only applicable to text content based resources.
[wait] bool | string false indicates if the call should wait for the index to be built before it returns. You can pass a string here to indicate the status you want to wait for, default is 'built'.

Example (usage)

// Creates a dataset resource in the authenticated users' scratch folder. The dataset stores key/value pairs
// where the `key` property is the primary key and the `value` property can take any JSON value.
tdxApi.addResource({
  name: "resource #1",
  schema: {
    dataSchema: {
      key: "string",
      value: {}
    },
    uniqueIndex: {key: 1}
  }
})

tdxApi.addResourceAccess(resourceId, accountId, sourceId, access)

Adds read and/or write permission for an account to access a resource. Permission is required equivalent to that which is being added, e.g. adding write permission requires existing write access.

Kind: instance method of TDXApi

Param Type Description
resourceId string The resource id
accountId string The account id to assign permission to
sourceId string The id of the resource acting as the source of the access. This is usually the same as the target resourceId, but can also be a parent resource. For example, if write access is granted with the sourceId set to be a parent, then if the permission is revoked from the parent resource it will also be revoked from this resource.
access Array.<string> The access, one or more of ["r", "w"]. Can be an array or an individual string.

Example (add access to an account)

tdxApi.addResourceAccess(myResourceId, "bob@acme.com/tdx.acme.com", myResourceId, ["r"]);

tdxApi.deleteResource(resourceId)

Permanently deletes a resource.

Kind: instance method of TDXApi

Param Type Description
resourceId string the id of the resource to delete. Requires write permission to the resource.

tdxApi.deleteManyResources(resourceList) ⇒ CommandResult

Permanently deletes a list of resources. Will fail all deletes if any of the permission checks fail.

Kind: instance method of TDXApi

Param Type Description
resourceList Array.<Resource> The list of resources to delete. Note only the id property of each resource is required.

tdxApi.fileUpload(resourceId, file, [stream], [compressed], [base64Encoded])

Upload a file to a resource.

Kind: instance method of TDXApi

Param Type Default Description
resourceId string The id of the destination resource.
file object The file to upload, obtained from an <input type="file"> element.
[stream] bool false Flag indicating whether the call should return a stream allowing callees to monitor progress.
[compressed] bool false Flag indicating the file should be decompressed after upload. ZIP format only.
[base64Encoded] bool false = Flag indicating the file should be decoded from base64 after upload.

tdxApi.moveResource(id, fromParentId, toParentId)

Move resource from one folder to another. Requires write permission on the resource, the source parent and the target parent resources.

Kind: instance method of TDXApi

Param Type Description
id string the id of the resource to move.
fromParentId string the current parent resource to move from.
toParentId string the target folder resource to move to.

tdxApi.rebuildResourceIndex(resourceId)

Resets the resource index. This involves deleting existing indexes and rebuilding them. May take a while depending on the size of any associated dataset and the number and complexity of indexes.

Kind: instance method of TDXApi

Param Type Description
resourceId string the id of the resource, requires write permission.

tdxApi.removeResourceAccess(resourceId, accountId, addedBy, sourceId, access)

Removes access for an account to a resource. Permission is required equivalent to that which is being added, e.g. adding write permission requires existing write access.

Kind: instance method of TDXApi

Param Type Description
resourceId string The resource id.
accountId string The account id to remove access from.
addedBy string The account id that originally added the access, probably your account id.
sourceId string The source of the access, usually the resource itself.
access Array.<string> The access, one or more of ["r", "w"].

tdxApi.setResourceImporting(resourceId, importing) ⇒ CommandResult

Set the resource import flag.

Kind: instance method of TDXApi

Param Type Description
resourceId string The id of the dataset-based resource.
importing boolean Indicates the state of the import flag.

tdxApi.setResourceSchema(resourceId, schema) ⇒ CommandResult

Set the resource schema.

Kind: instance method of TDXApi

Param Type Description
resourceId string The id of the dataset-based resource.
schema object The new schema definition. TODO - document

tdxApi.setResourceShareMode(resourceId, shareMode)

Set the share mode for a resource.

Kind: instance method of TDXApi

Param Type Description
resourceId string The resource id.
shareMode string The share mode to set, one or ["pw", "pr", "tr"] corresponding to 'public read/write', 'public read, trusted write', 'trusted only'.

tdxApi.setResourcePermissiveShare(resourceId, allowPermissive)

Sets the permissive share mode of the resource. Permissive share allows anybody with acces to the resource to share it with others. If a resource is not in permissive share mode, only the resource owner can share it with others.

Kind: instance method of TDXApi

Param Type Description
resourceId string The resource id.
allowPermissive bool The required permissive share mode.

tdxApi.setResourceTextContent(resourceId, textContent)

Set the text for a text-content based resource.

Kind: instance method of TDXApi

Param Type Description
resourceId string The resource id.
textContent string The text content to set.

Example (usage)

// Sets the text content for a text-html resource.
tdxApi.setResourceTextContent(
  "HyeqJgVdJ7",
  "<html><body><p>Hello World</p></body></html>"
);

tdxApi.suspendResourceIndex(resourceId)

Suspends the resource index. This involves deleting any existing indexes. Requires write permission. When a resource index is in suspended status, it is not possible to run any queries or updates against the resource.

Kind: instance method of TDXApi

Param Type Description
resourceId string the id of the resource. Requires write permission.

tdxApi.truncateResource(resourceId)

Removes all data from the resource. Applicable to dataset-based resources only. This can not be undone.

Kind: instance method of TDXApi

Param Type Description
resourceId string The resource id to truncate.

tdxApi.updateResource(resourceId, update)

Modify one or more of the meta data associated with the resource.

Kind: instance method of TDXApi

Param Type Description
resourceId string id of the resource to update
update object object containing the properties to update. Can be one or more of those listed below. See the addResource method for semantics and syntax of each property.
[update.derived] string
[update.description] string
[update.meta] object
[update.name] string
[update.overwrite] bool set this flag to overwrite existing data rather than merging (default). This currently only applies to the meta property.
[update.provenance] string
[update.queryProxy] string
[update.tags] array
[update.textContent] string see also setResourceTextContent

tdxApi.addData(datasetId, data, [doNotThrow])

Add data to a dataset resource.

Kind: instance method of TDXApi

Param Type Default Description
datasetId string The id of the dataset-based resource to add data to.
data object | array The data to add. Must conform to the schema defined by the resource metadata.
[doNotThrow] bool false set to override default error handling. See TDXApi. Supports creating an individual document or many documents.

Example (create an individual document)

// Assumes the dataset primary key is 'lsoa'
tdxApi.addData(myDatasetId, {lsoa: "E0000001", count: 398});

Example (create multiple documents)

tdxApi.addData(myDatasetId, [
 {lsoa: "E0000001", count: 398},
 {lsoa: "E0000002", count: 1775},
 {lsoa: "E0000005", count: 4533},
]);

tdxApi.deleteData(datasetId, data, [doNotThrow])

Deletes data from a dataset-based resource.

Kind: instance method of TDXApi

Param Type Default Description
datasetId string The id of the dataset-based resource to delete data from.
data object | array The primary key data to delete.
[doNotThrow] bool false set to override default error handling. See TDXApi.

tdxApi.deleteDataByQuery(datasetId, query, [doNotThrow])

Deletes data from a dataset-based resource using a query to specify the documents to be deleted.

Kind: instance method of TDXApi

Param Type Default Description
datasetId string The id of the dataset-based resource to delete data from.
query object The query that specifies the data to delete. All documents matching the query will be deleted.
[doNotThrow] bool false set to override default error handling. See TDXApi.

Example

// Delete all documents with English lsoa.
tdxApi.deleteDataByQuery(myDatasetId, {lsoa: {$regex: "E*"}});

tdxApi.patchData(datasetId, data, [doNotThrow])

Patches data in a dataset resource. Uses the JSON patch format, which involves defining the primary key data followed by a flexible update specification.

Kind: instance method of TDXApi

Param Type Default Description
datasetId string The id of the dataset-based resource to update.
data object The patch definition.
data.__update object | array An array of JSON patch specifications.
[doNotThrow] bool false set to override default error handling. See TDXApi.

Example (patch a single value in a single document)

tdxApi.patchData(myDatasetId, {lsoa: "E000001", __update: [{path: "/count", op: "replace", value: 948}]});

Example (patch a more than one value in a single document)

tdxApi.patchData(myDatasetId, {lsoa: "E000001", __update: [
  {path: "/count", op: "replace", value: 948}
  {path: "/modified", op: "add", value: Date.now()}
]});

tdxApi.updateData(datasetId, data, [upsert], [doNotThrow]) ⇒ CommandResult

Updates data in a dataset resource.

Kind: instance method of TDXApi
Returns: CommandResult - - Use the result property to check for errors.

Param Type Default Description
datasetId string The id of the dataset-based resource to update.
data object | array The data to update. Must conform to the schema defined by the resource metadata. Supports updating individual or multiple documents.
[upsert] bool false Indicates the data should be created if no document is found matching the
[doNotThrow] bool false set to override default error handling. See TDXApi. primary key.

Example (update an existing document)

tdxApi.updateData(myDatasetId, {lsoa: "E000001", count: 488});

Example (upsert a document)

// Will create a document if no data exists matching key 'lsoa': "E000004"
tdxApi.updateData(myDatasetId, {lsoa: "E000004", count: 288}, true);

tdxApi.updateDataByQuery(datasetId, query, [doNotThrow])

Updates data in a dataset-based resource using a query to specify the documents to be updated.

Kind: instance method of TDXApi

Param Type Default Description
datasetId string The id of the dataset-based resource to update data in.
query object The query that specifies the data to update. All documents matching the
[doNotThrow] bool false set to override default error handling. See TDXApi. query will be updated.

Example

// Update all documents with English lsoa, setting `count` to 1000.
tdxApi.updateDataByQuery(myDatasetId, {lsoa: {$regex: "E*"}}, {count: 1000});

tdxApi.deleteDatabotHost(payload)

Deletes one or more hosts, depending on the given parameters. E.g. if just a hostId is given, all hosts will be deleted with that id. If an ip address is also given, all hosts with the id on that ip address will be deleted and so on. Note that hosts can only be deleted if they are in the offline status.

Kind: instance method of TDXApi

Param Type Description
payload object The definition of the host(s) to delete. Can be an array of objects or a single object
payload.hostId string The id of the hosts to be deleted.
[payload.hostIp] string The optional ip of the hosts to be deleted.
[payload.hostPort] number The optional port number of the host to be deleted.

tdxApi.deleteDatabotInstance(instanceId)

Deletes a databot instance and all output/debug data associated with it.

Kind: instance method of TDXApi

Param Type Description
instanceId Array.<string> The id(s) of the instances to delete. Can be an array of instance ids or an individual string id

tdxApi.getDatabotInstance(instanceId)

Gets databot instance data for the given instance id.

Kind: instance method of TDXApi

Param Type Description
instanceId string The id of the instance to retrieve.

tdxApi.getDatabotInstanceOutput(instanceId, [processId])

Get databot instance output.

Kind: instance method of TDXApi

Param Type Description
instanceId string The instance id to retrieve output for.
[processId] string Optional process id. If omitted, output for all instance processes will be returned.

tdxApi.getDatabotInstanceStatus(instanceId)

Get databot instance status.

Kind: instance method of TDXApi

Param Type Description
instanceId string The id of the databot instance for which status is retrieved.

tdxApi.registerDatabotHost(payload)

Registers a databot host with the TDX. Once registered, a host is eligible to receive commands from the TDX.

Kind: instance method of TDXApi

Param Type Description
payload object The databot host identifier payload.
payload.port number the port number the host is listening on.
payload.version string the databot host software version.
payload.hostStatus string the current status of the host, "idle" or "busy".
[payload.ip] string optional ip address of the host. Usually the TDX can deduce this from the incoming request.

Example (register a databot host)

tdxApi.registerDatabotHost({version: "0.3.11", port: 2312, hostStatus: "idle"});

tdxApi.sendDatabotHostCommand(command, hostId, [hostIp], [hostPort], [payload])

Sends a command to a databot host. Reserved for system use.

Kind: instance method of TDXApi

Param Type Description
command string The command to send. Must be one of ["stopHost", "updateHost", "runInstance", "stopInstance", "clearInstance"]
hostId string The id of the host.
[hostIp] string The ip address of the host. If omitted, the command will be sent to all host ip addresses.
[hostPort] number The port number of the host. If omitted, the command will be sent to all host ports.
[payload] object The command payload.

tdxApi.startDatabotInstance(databotId, payload)

Starts a databot instance.

Kind: instance method of TDXApi

Param Type Default Description
databotId string The id of the databot definition to start.
payload object The instance input and parameters.
[payload.authTokenTTL] number The time-to-live to use when creating the auth token, in seconds. Will default to the TDX-configured default if not given (usually 1 hour).
[payload.chunks] number 1 The number of processes to instantiate. Each will be given the same input data, with only the chunk number varying.
[payload.debugMode] bool false Flag indicating this instance should be run in debug mode, meaning all debug output will be captured and stored on the TDX. n.b. setting this will also restrict the hosts available to run the instance to those that are willing to run in debug mode.
[payload.description] string The description for this instance.
[payload.inputs] object The input data. A free-form object that should conform to the specification in the associated databot definition.
[payload.name] string The name to associate with this instance, e.g. "Male population projection 2017"
[payload.overwriteExisting] string The id of an existing instance that should be overwritten.
[payload.priority] number The priority to assign this instance. Reserved for system use.
payload.shareKeyId string The share key to run the databot under.
[payload.shareKeySecret] string The secret of the share key. Ignored if the share key id refers to a user-based account.

tdxApi.abortDatabotInstance(instanceId)

Aborts a running databot instance.

Kind: instance method of TDXApi

Param Type Description
instanceId string The id of the instance to abort.

tdxApi.stopDatabotInstance(instanceId, mode)

Terminates or pauses a running databot instance.

Kind: instance method of TDXApi

Param Type Description
instanceId string The id of the instance to terminate or pause.
mode string One of ["stop", "pause", "resume"]

tdxApi.updateDatabotHostStatus(payload)

Updates a databot host status.

n.b. the response to this request will contain any commands from the TDX that the host should action ( see commands).

Kind: instance method of TDXApi

Param Type Description
payload object The databot host status payload.
payload.port number The port number on which the host is listening.
payload.hostStatus string The current host status, either "idle" or "busy".
[payload.ip] string optional ip address of the host. Usually the TDX can deduce this from the incoming request.

Example (update databot host status)

tdxApi.updateDatabotHostStatus({port: 2312, hostStatus: "idle"});

tdxApi.writeDatabotHostInstanceOutput(output)

Stores databot instance output on the TDX.

Kind: instance method of TDXApi

Param Type Description
output object The output payload for the databot instance.

tdxApi.addZoneConnection(options)

Adds a zone connection to a remote TDX. The details for the connection should be retrieved by a call to the certificate endpoint for the TDX, e.g. https://tdx.nqminds.com/certficate.

Kind: instance method of TDXApi

Param Type Description
options object The zone connection details
options.owner string The owner of the zone connection. Must be the same as the authenticated account.
options.tdxServer string The URL of the target TDX auth server, e.g. https://tdx.nqminds.com
[options.commandServer] string The URL of the target TDX command server, e.g. https://cmd.nqminds.com
[options.queryServer] string The URL of the target TDX query server, e.g. https://q.nqminds.com
[options.ddpServer] string The URL of the target TDX ddp server, e.g. https://ddp.nqminds.com
[options.databotServer] string The URL of the target TDX databot server, e.g. https://databot.nqminds.com
[options.displayName] string The friendly name of the TDX.

tdxApi.deleteZoneConnection(id)

Deletes a zone connection. The authenticated account must own the zone connection.

Kind: instance method of TDXApi

Param Type Description
id string The id of the zone connection to delete.

tdxApi.rollbackCommand()

AUDIT COMMANDS

Kind: instance method of TDXApi

tdxApi.createTDXToken(username, [ip], [ttl]) ⇒ object

Creates a client user token (e.g. bound to the browser IP) for an application-user token bound to the given IP or the currently authenticated token IP. The currently authenticated token must be an application token, whereby the application has been authorised by the user and the user has permission to access the application. The returned token will be bound to the given IP or the IP of the currently authenticated token (i.e the application server IP).

Kind: instance method of TDXApi
Returns: object - - The new application-user token, bound to the given IP.

Param Type Description
username string The users' TDX id.
[ip] string The optional IP address to bind the user token to.
[ttl] number The ttl in seconds.

Example (create token bound to server ip with default TDX ttl)

tdxApi.createTDXToken("bob@bob.com/acme.tdx.com");

Example (create for specific IP)

tdxApi.createTDXToken("bob@bob.com/acme.tdx.com", newClientIP);

tdxApi.exchangeTDXToken(token, [validateIP], [exchangeIP], [ttl]) ⇒ object

Exchanges a client user token (e.g. bound to the browser IP) for an application-user token bound to the given IP or the currently authenticated token IP. The currently authenticated token must be an application token, whereby the application has been authorised by the user and the user has permission to access the application. The returned token will be bound to the given IP or the IP of the currently authenticated token (i.e the application server IP).

Kind: instance method of TDXApi
Returns: object - - The new token application-user token, bound to the server IP.

Param Type Description
token string The users' TDX auth server token to validate.
[validateIP] string The optional IP address to validate the user token against.
[exchangeIP] string The optional IP address to bind the new token to.
[ttl] number The ttl in seconds.

Example (validate against current IP)

tdxApi.exchangeTDXToken(clientToken);

Example (validate against different IP)

tdxApi.exchangeTDXToken(clientToken, newClientIP);

Example (validate against current IP, bind to a new IP)

tdxApi.exchangeTDXToken(clientToken, null, serverIP);

tdxApi.downloadResource(resourceId) ⇒ object

Streams the contents of a resource. For dataset-based resources this will stream the dataset contents in newline delimited JSON (NDJSON). For raw file resources this will stream the raw file contents (zip, raw JSON etc).

Kind: instance method of TDXApi
Returns: object - - Response object, where the response body is a stream object.

Param Type Description
resourceId string The id of the resource to be downloaded.

tdxApi.getAccount(accountId) ⇒ Zone

Gets the details for a given account id.

Kind: instance method of TDXApi
Returns: Zone - zone

Param Type Description
accountId string the id of the account to be retrieved.

tdxApi.getAccounts(filter) ⇒ Array.<Zone>

Gets the details for all peer accounts.

Kind: instance method of TDXApi
Returns: Array.<Zone> - zone

Param Type Description
filter object query filter.
filter.accountType string the account type to filter by, e.g. "user", "token", "host" etc.

Example (Get all databots owned by bob)

api.getAccounts({accountType: "host", own: "bob@nqminds.com"})

tdxApi.getAggregateDataStream(datasetId, pipeline, [ndJSON]) ⇒ object

Performs an aggregate query on the given dataset resource, returning a response object with stream in the body

Kind: instance method of TDXApi
Returns: object - - Response object, where the response body is a stream object.

Param Type Description
datasetId string The id of the dataset-based resource to perform the aggregate query on.
pipeline object | string The aggregate pipeline, as defined in the mongodb docs. Can be given as a JSON object or as a stringified JSON object.
[ndJSON] bool If set, the data is sent in newline delimited json format.

tdxApi.getAggregateData(datasetId, pipeline, [ndJSON]) ⇒ DatasetData

Performs an aggregate query on the given dataset resource.

Kind: instance method of TDXApi

Param Type Description
datasetId string The id of the dataset-based resource to perform the aggregate query on.
pipeline object | string The aggregate pipeline, as defined in the mongodb docs. Can be given as a JSON object or as a stringified JSON object.
[ndJSON] bool If set, the data is sent in newline delimited json format.

tdxApi.getAuthenticatedAccount() ⇒ object

Gets details of the currently authenticated account.

Kind: instance method of TDXApi
Returns: object - - Details of the authenticated account.

tdxApi.getDataStream(datasetId, [filter], [projection], [options], [ndJSON]) ⇒ object

Gets all data from the given dataset resource that matches the filter provided and returns a response object with stream in the body.

Kind: instance method of TDXApi
Returns: object - - Response object, where the response body is a stream object.

Param Type Description
datasetId string The id of the dataset-based resource.
[filter] object A mongodb filter object. If omitted, all data will be retrieved.
[projection] object A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
[options] object A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
[options.nqmMeta] bool When set, the resource metadata will be returned along with the dataset data. Can be used to avoid a second call to getResource. Otherwise a URL to the metadata is provided.
[ndJSON] bool If set, the data is sent in newline delimited json format.

tdxApi.getData(datasetId, [filter], [projection], [options], [ndJSON]) ⇒ DatasetData

For structured resources, e.g. datasets, this function gets all data from the given dataset resource that matches the filter provided.

For non-structured resources such as text-content or raw files etc only the datasetId argument is relevant and this method is equivalent to downloadResource.

Kind: instance method of TDXApi

Param Type Description
datasetId string The id of the dataset-based resource.
[filter] object A mongodb filter object. If omitted, all data will be retrieved.
[projection] object A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
[options] object A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
[options.nqmMeta] bool When set, the resource metadata will be returned along with the dataset data. Can be used to avoid a second call to getResource. Otherwise a URL to the metadata is provided.
[ndJSON] bool If set, the data is sent in newline delimited json format.

tdxApi.getNDData()

Sugar for newline delimited data. See getData for details.

Kind: instance method of TDXApi

tdxApi.getDatasetDataStream(datasetId, [filter], [projection], [options], [ndJSON]) ⇒ object

Deprecated

Kind: instance method of TDXApi
Returns: object - - Response object, where the response body is a stream object.

Param Type Description
datasetId string The id of the dataset-based resource.
[filter] object A mongodb filter object. If omitted, all data will be retrieved.
[projection] object A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
[options] object A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
[options.nqmMeta] bool When set, the resource metadata will be returned along with the dataset data. Can be used to avoid a second call to getResource. Otherwise a URL to the metadata is provided.
[ndJSON] bool If set, the data is sent in newline delimited json format.

tdxApi.getDatasetData(datasetId, [filter], [projection], [options], [ndJSON]) ⇒ DatasetData

Deprecated

Kind: instance method of TDXApi

Param Type Description
datasetId string The id of the dataset-based resource.
[filter] object A mongodb filter object. If omitted, all data will be retrieved.
[projection] object A mongodb projection object. Should be used to restrict the payload to the minimum properties needed if a lot of data is being retrieved.
[options] object A mongodb options object. Can be used to limit, skip, sort etc. Note a default limit of 1000 is applied if none is given here.
[options.nqmMeta] bool When set, the resource metadata will be returned along with the dataset data. Can be used to avoid a second call to getResource. Otherwise a URL to the metadata is provided.
[ndJSON] bool If set, the data is sent in newline delimited json format.

tdxApi.getDataCount(datasetId, [filter])

Gets a count of the data in a dataset-based resource, after applying the given filter.

Kind: instance method of TDXApi

Param Type Description
datasetId string The id of the dataset-based resource.
[filter] object An optional mongodb filter to apply before counting the data.

tdxApi.getDatasetDataCount(datasetId, [filter])

Deprecated

Kind: instance method of TDXApi

Param Type Description
datasetId string The id of the dataset-based resource.
[filter] object An optional mongodb filter to apply before counting the data.

tdxApi.getDistinct(datasetId, key, [filter]) ⇒ Array.<object>

Gets a list of distinct values for a given property in a dataset-based resource.

Kind: instance method of TDXApi
Returns: Array.<object> - - The distinct values.

Param Type Description
datasetId string The id of the dataset-based resource.
key string The name of the property to use. Can be a property path, e.g. "address.postcode".
[filter] object An optional mongodb filter to apply.

tdxApi.getResource(resourceId, [noThrow]) ⇒ Resource

Gets the details for a given resource id.

Kind: instance method of TDXApi
Throws:

  • Will throw if the resource is not found (see noThrow flag) or permission is denied.
Param Type Default Description
resourceId string The id of the resource to retrieve.
[noThrow] bool false If set, the call won't reject or throw if the resource doesn't exist.

Example

api.getResource(myResourceId)
 .then((resource) => {
   console.log(resource.name);
 });

tdxApi.getResourceAccess(resourceId) ⇒ Array.<ResourceAccess>

Gets all access the authenticated account has to the given resource id.

Kind: instance method of TDXApi
Returns: Array.<ResourceAccess> - - Array of ResourceAccess objects.

Param Type Description
resourceId string The id of the resource whose access is to be retrieved.

Example

api.getResourceAccess(myResourceId)
 .then((resourceAccess) => {
   console.log("length of access list: ", resourceAccess.length);
 });

tdxApi.getResourceAncestors(resourceId) ⇒ Array.<Resource>

Gets all resources that are ancestors of the given resource.

Kind: instance method of TDXApi

Param Type Description
resourceId string The id of the resource whose parents are to be retrieved.

tdxApi.getResources([filter], [projection], [options]) ⇒ Array.<Resource>

Gets the details of all resources that match the given filter.

Kind: instance method of TDXApi

Param Type Description
[filter] object A mongodb filter definition
[projection] object A mongodb projection definition, can be used to restrict which properties are returned thereby limiting the payload.
[options] object A mongodb options definition, can be used for limit, skip, sorting etc.

tdxApi.getResourcesWithSchema(schemaId) ⇒ Array.<Resource>

Retrieves all resources that have an immediate ancestor of the given schema id.

Kind: instance method of TDXApi

Param Type Description
schemaId string The id of the schema to match, e.g. "geojson".

tdxApi.getTDXToken(tdx) ⇒ string

Retrieves an authorisation token for the given TDX instance

Kind: instance method of TDXApi

Param Type Description
tdx string The TDX instance name, e.g. "tdx.acme.com".

tdxApi.getZone(accountId) ⇒ Zone

Gets the details for a given zone (account) id.

Kind: instance method of TDXApi
Returns: Zone - zone

Param Type Description
accountId string the id of the zone to be retrieved.

tdxApi.isInGroup(accountId, groupId)

Determines if the given account is a member of the given group.

Kind: instance method of TDXApi

Param Type Description
accountId string the id of the account
groupId * the id of the group

tdxApi.validateTDXToken(token, [ip]) ⇒ object

Validates the given token was signed by this TDX, and returns the decoded token data.

Kind: instance method of TDXApi
Returns: object - - The decoded token data.

Param Type Description
token string The TDX auth server token to validate.
[ip] string The optional IP address to validate against.

TDXApiError : Error

The TDX api supplies detailed error information depending on the context of the call. In some instances, e.g. attempting to retrieve a resource that does not exist, the error will be a simple NotFound string message. In other cases, e.g. attempting to update 100 documents in a single call, the error will supply details for each document update that failed, such as the primary key of the document and the reason for the failure.

Kind: global typedef
Properties

Name Type Description
name string "TDXApiError", indicating the error originated from this library.
code number The HTTP response status code, e.g. 401
message string Deprecated - A string-encoded form of the error, essentially a JSON stringified copy of the entire error object. This is included for legacy reasons and may be removed in a future release.
from string Usually the name of the API call that originated the error, e.g. updateData
stack string the stack trace
failure object an object containing the error information as received from the TDX
failure.code string the TDX short error code, e.g. NotFound, PermissionDenied etc.
failure.message string | array details of the failure. For simple cases this will be a string, e.g. resource not found: KDiEI3k_. In other instance this will be an array of objects describing each error. See the example below showing a failed attempt to update 2 documents. One of the errors is a simple document not found and the other is a validation error giving details of the exact path in the document that failed validation.

Example (`failure` for simple query error)

failure: {
 code: "NotFound",
 message: "resource not found: KDiEI3k_"
}

Example (`failure` for complex data update error)

failure: {
 code: "BadRequestError",
 message: [
   {
     key: {id: "foo"},
     error: {
       message: "document not found matching key 'foo'"
     }
   },
   {
     key: {id: "bar"},
     error: {
       message: "'hello' is not a valid enum value",
       name: "ValidatorError",
       kind: "enum"
       path: "value"
     }
   }
 ]
}

CommandResult : object

Kind: global typedef
Properties

Name Type Description
commandId string The auto-generated unique id of the command.
response object | string The response of the command. If a command is sent asynchronously, this will simply be the string "ack". In synchronous mode, this will usually be an object consisting of the primary key of the data that was affected by the command.
result object Contains success flag and detailed error information when available.
result.errors array Will contain error information when appropriate.
result.ok array Contains details of each successfully commited document.

DatasetData : object

Kind: global typedef
Properties

Name Type Description
metaData object The dataset metadata (see nqmMeta option in getDatasetData).
metaDataUrl string The URL to the dataset metadata (see nqmMeta option in getDatasetData.
data Array.<object> The dataset documents.

Resource : object

Kind: global typedef
Properties

Name Type
description string
id string
name string
parents Array.<string>
schemaDefinition object
tags Array.<string>

ResourceAccess : object

Kind: global typedef
Properties

Name Type Description
aid string account id that is the subject of this access
by string comma-delimited list of attribution for this access
rid string resource id to which this access refers
grp string indicates the share mode (user groups only)
own string account that owns the resource
par Array.<string> the parent(s) of the resource
typ string the base type of the resource
r Array.<string> array of resource ids that are the source of read access (e.g. parent)
w Array.<string> array of resource ids that are the source of write access

Zone : object

Kind: global typedef
Properties

Name Type
accountType string
displayName string
username string