Skip to content

cloudnode-pro/ts-client

BranchesTags

Repository files navigation

Cloudnode API Client

npm API Version: 5.13.0 Build CodeQL npm downloads

A client library for the Cloudnode API, written in TypeScript. Documentation

Install

npm install cloudnode-ts

Usage

JavaScript

Node.js (ES6)

import Cloudnode from 'cloudnode-ts';

const cloudnode = new Cloudnode("token_YourSecretToken123");

// get a newsletter
const newsletter = await cloudnode.newsletter.get("newsletter_123asd");
// get response status code
console.log(newsletter._response.status); // 200

Node.js (CommonJS)

const Cloudnode = require('cloudnode-ts');

const cloudnode = new Cloudnode("token_YourSecretToken123");

// get a newsletter
const newsletter = await cloudnode.newsletter.get("newsletter_123asd");
console.log(newsletter._response.status); // 200

Browser

Download the browser version from browser/Cloudnode.js or use our hosted version.

<script src="https://cdn.jsdelivr.net/npm/cloudnode-ts@latest/browser/Cloudnode.min.js"></script>
<script>
const cloudnode = new Cloudnode();

// get a newsletter
const newsletter = await cloudnode.newsletter.get("newsletter_123asd");
console.log(newsletter._response.status); // 200
</script>

Warning: You most likely don't want to set your private token in a public front-end website, as this will allow anyone who sees your front-end JavaScript code to use it for possibly malicious purposes. We advise you use a back-end server to proxy requests to our API, so you do not expose your token to the public.

TypeScript

import Cloudnode from 'cloudnode-ts';

const cloudnode = new Cloudnode("token_YourSecretToken123");

// get a newsletter
const newsletter: Cloudnode.Newsletter = await cloudnode.newsletter.get("newsletter_123asd");

If you want to access response metadata (headers, status code, etc.), use Cloudnode.ApiResponse<T>, e.g.:

const newsletter: Cloudnode.ApiResponse<Cloudnode.Newsletter> = await cloudnode.newsletter.get("newsletter_123asd");
console.log(newsletter.id); // newsletter_123asd
console.log(newsletter._response.status); // 200

Documentation

Table of contents

Class: Cloudnode

A client library for the Cloudnode API, written in TypeScript. Documentation

new Cloudnode([token], [options])

Construct a new Cloudnode API client

  • token string API token to use for requests.
  • options Partial<Cloudnode.Options> API client options. Default: {baseUrl: "https://api.cloudnode.pro/v5/", autoRetry: true, maxRetryDelay: 5, maxRetries: 3}

cloudnode.getPage<T>(response, page)

Get another page of paginated results

cloudnode.getNextPage<T>(response)

Get next page of paginated results

cloudnode.getPreviousPage<T>(response)

Get previous page of paginated results

cloudnode.getAllPages<T>(response)

Get all other pages of paginated results and return the complete data

Warning: Depending on the amount of data, this can take a long time and use a lot of memory.

cloudnode.checkCompatibility()

Check compatibility with the API

cloudnode.account.changePassword(currentPassword, newPassword)

Change account password. Requires token with scope account.details.password.update.

cloudnode.account.get()

Get account details. Requires token with scope account.details.

cloudnode.account.getEmail()

Get your primary e-mail address. Requires token with scope account.details.email.

cloudnode.account.getIdentity()

Get account identity. Requires token with scope account.details.identity.

cloudnode.account.listEmails()

List account e-mail addresses. Requires token with scope account.details.email.list.

cloudnode.account.listPermissions()

List account permissions with user-friendly descriptions. Some permissions (such as wildcard ones) may be excluded in this list if they don't have a description. Requires token with scope account.details.

cloudnode.account.replaceIdentity(username, name)

Replace account identity. Requires token with scope account.details.identity.update.

cloudnode.account.setEmail(email)

Set your primary e-mail address. Requires token with scope account.details.email.update.

cloudnode.account.updateIdentity(username, [name])

Update account identity. Requires token with scope account.details.identity.update.

cloudnode.auth.login(user, password)

Create a session using user ID/username/e-mail and password.

Note: Logging in can only be performed from residential IP. Proxying this endpoint will likely not work. It is normally not recommended to use this endpoint to gain API access. Instead, create a token from your account to use with the API.

cloudnode.auth.register(username, email, password)

Create an account and session. After signing up, a welcome e-mail is sent to confirm your e-mail address.

Note: Registering an account can only be performed from residential IP. Proxying this endpoint will likely not work. Creating multiple/alternate accounts is not allowed as per the Terms of Service.

  • username string The username to use for the account. Must be between 3 and 20 characters long. Cannot start with user_. May contain only letters, numbers, dashes and underscores. Must be unique.
  • email string The e-mail address to register. A valid unique non-disposable e-mail that can receive mail is required.
  • password string The password to use for the account. Must be at least 15 characters, or 8 characters if it contains a mix of letters, numbers and symbols.
  • Returns: Promise<Cloudnode.ApiResponse<{session: string}>> Session token. Also returned in Set-Cookie header.
  • Throws: Cloudnode.Error & {code: "INVALID_DATA"}
  • Throws: Cloudnode.Error & {code: "IP_REJECTED"}
  • Throws: Cloudnode.Error & {code: "RATE_LIMITED"}
  • Throws: Cloudnode.Error & {code: "INTERNAL_SERVER_ERROR"}
  • Throws: Cloudnode.Error & {code: "MAINTENANCE"}

cloudnode.newsletters.get(id)

Get newsletter

cloudnode.newsletters.list([limit], [page])

List newsletters

cloudnode.projects.create(name)

Create a project. Requires token with scope projects.create.own.

cloudnode.projects.delete(id)

Delete a project. Requires token with scope projects.delete.own.

cloudnode.projects.get(id)

Get a project. Requires token with scope projects.get.own.

cloudnode.projects.list([limit], [page])

List projects. Requires token with scope projects.get.own.

cloudnode.projects.update(id, name)

Update a project. Requires token with scope projects.update.own.

cloudnode.subscriptions.create(newsletter, email, [data])

Subscribe to newsletter

cloudnode.subscriptions.delete(id)

Unsubscribe from newsletter

cloudnode.subscriptions.get(id)

Get newsletter subscription

cloudnode.subscriptions.list([limit], [page])

List newsletter subscriptions. Requires token with scope newsletter.subscriptions.list.own.

cloudnode.tokens.create(permissions, lifetime, [note])

Create token. Requires token with scope tokens.create.own.

cloudnode.tokens.get(id)

Get token details. Requires token with scope tokens.get.own.

cloudnode.tokens.getRequest(id, request)

Get a recent request by ID. Requires token with scope tokens.get.own.requests.

cloudnode.tokens.list([limit], [page], [internal])

List tokens of user. Requires token with scope tokens.list.own.

cloudnode.tokens.listRequests(id, [limit], [page])

Get list of recent requests made with the token. Requires token with scope tokens.get.own.requests.

cloudnode.tokens.refresh(id)

Refresh current token. The token that was used to authenticate the request will be deleted. A new token with a new ID but the same permissions will be created and returned. The lifespan of the new token will be the same as the old one, starting from the time of the request. This operation effectively allows a token to be used indefinitely. Requires token with scope token.refresh.

cloudnode.tokens.revoke(id)

Revoke token. Requires token with scope tokens.revoke.own.

Namespace: Cloudnode

A client library for the Cloudnode API, written in TypeScript. Documentation

Class: Cloudnode.ApiResponse<T>

An API response. This class implements the interface provided as T and includes all of its properties.

Class: Cloudnode.RawResponse

Raw API response

  • headers Record<string, string> The headers returned by the server. (read-only)
  • ok boolean A boolean indicating whether the response was successful (status in the range 200 – 299) or not. (read-only)
  • redirected boolean Indicates whether or not the response is the result of a redirect (that is, its URL list has more than one entry). (read-only)
  • status number The status code of the response. (read-only)
  • statusText string The status message corresponding to the status code. (e.g., OK for 200). (read-only)
  • url string The URL of the response. (read-only)

Enum: Cloudnode.CompatibilityStatus

API client compatibility status

  • COMPATIBLE "compatible" Fully compatible (API patch version may differ)
  • OUTDATED "outdated" Compatible, but outdated (i.e. existing APIs will work, but you are missing out on new features).
  • INCOMPATIBLE "incompatible" API has implemented breaking changes which are not compatible with this client.

Interface: Cloudnode.AccountDetails

Details about your account

  • id string Your user ID
  • password boolean Whether you have a password set
  • group string The name of your permission group
  • permissions string[] A list of all permission that you have access to
  • identity AccountIdentity | null Personal information associated with your account. Requires account.details.identity to see. Maybe be null if the account is anonymised or you don't have permission to access the account identity.
  • email PrimaryEmail | null Your current primary account e-mail address. Requires account.details.email to see. Maybe be null if you don't have a primary e-mail address or you don't have permission to access the account's e-mail address.

Interface: Cloudnode.AccountEmail

An e-mail address you have added to your account

  • id string The ID of the e-mail address
  • address string | null Your e-mail address. May ben null if anonymised.
  • verified boolean Whether this e-mail address has been verified
  • primary boolean Whether this e-mail address is your primary e-mail address
  • added Date The date and time when this e-mail address was added to your account

Interface: Cloudnode.AccountIdentity

Personal information associated with your account

Interface: Cloudnode.DatedNewsletterSubscription

A newsletter subscription with a creation date

  • id string The ID of the subscription. Can be used to unsubscribe.
  • email string The email address of the subscriber
  • newsletter string The ID of the newsletter that was subscribed to
  • date Date The date the subscription was created

Interface: Cloudnode.DatedPrimaryEmail

Your current primary account e-mail address with a timestamp of when it was added to your account

  • id string The ID of the e-mail address
  • address string | null Your e-mail address. May ben null if anonymised.
  • verified boolean Whether this e-mail address has been verified
  • added Date The date and time when this e-mail address was added to your account

Interface: Cloudnode.Error

An API error response.

  • message string A human-readable description of this error
  • code string Error code
  • fields Record<string, string | Record<string, string>> Affected request fields. The key is the name of the input parameter (e.g. from the request body or query string) and the value is a human-readable error message for that field.

Interface: Cloudnode.Newsletter

A newsletter that you can subscribe to

  • id string The unique identifier for this newsletter
  • name string The name of this newsletter
  • data Record<string, NewsletterData> Additional data that is required to subscribe to this newsletter

Interface: Cloudnode.NewsletterData

A data field that is required to subscribe to this newsletter

  • name string The name of the field
  • description string | undefined Description of the field
  • type "string" | "number" | "boolean" The type of data
  • required boolean Whether this field is required

Interface: Cloudnode.NewsletterSubscription

Your subscription to a newsletter

  • id string The ID of the subscription. Can be used to unsubscribe.
  • email string The email address of the subscriber
  • newsletter string The ID of the newsletter that was subscribed to

Interface: Cloudnode.Options

API client options

  • baseUrl string The base URL of the API
  • autoRetry boolean Whether to automatically retry requests that fail temporarily. If enabled, when a request fails due to a temporary error, such as a rate limit, the request will be retried after the specified delay.
  • maxRetryDelay number The maximum number of seconds that is acceptable to wait before retrying a failed request. This requires autoRetry to be enabled.
  • maxRetries number The maximum number of times to retry a failed request. This requires autoRetry to be enabled.

Interface: Cloudnode.PaginatedData<T>

Paginated response

  • items T[] The page items
  • total number The total number of items
  • limit number The number of items per page
  • page number The current page number

Interface: Cloudnode.PartialToken

A token, however, the permissions field is not included

  • id string The ID or key of the token
  • created Date Date and time when this token was created
  • expires Date | null Date and time when this token expires. Null if it never expires.
  • internal string | undefined Whether this token is for internal use only, e.g. to power a session. In other words, an internal token is one that was not created by the client.
  • metadata Cloudnode.TokenMetadata Additional metadata about this token

Interface: Cloudnode.Permission

A permission node

  • permission string The permission node string
  • description string User-friendly description of the permission node
  • note string | null Additional user-friendly information about the permission node
  • group string | null A group/category title that can be used to group permissions together

Interface: Cloudnode.PrimaryEmail

Your current primary account e-mail address

  • id string The ID of the e-mail address
  • address string | null Your primary e-mail address. May ben null if anonymised.
  • verified boolean Whether this e-mail address has been verified

Interface: Cloudnode.Project

An isolated group of servers

  • id string The ID of the project
  • name string Project name
  • user string ID of the user that owns this project

Interface: Cloudnode.Request

A request

  • id string The ID of the request
  • method string The request method (e.g. GET, POST, HEAD, etc.
  • scheme "http" | "https" The URL scheme
  • host string The requested host name
  • url string The request URL path
  • status number The HTTP status code that was returned to this request
  • ip string The IP address of the client that made the request (can be both IPv4 and IPv6)
  • date Date The time when the request was received
  • responseTime number The time in milliseconds that the request took to process
  • hasEvents boolean Whether any server-side error events occurred while processing this request
  • requestHeaders Record<string, string> | null The request headers that were received
  • requestBody string | null The request body that was received (likely parsed and formatted as JSON)
  • responseHeaders Record<string, string> | null The headers that were returned by the server
  • responseBody {type: "Buffer", data: number[]} | null The response body that was returned by the server in response to this request

Interface: Cloudnode.ShortRequest

Overview of a request

  • id string The ID of the request
  • method string The request method (e.g. GET, POST, HEAD, etc.
  • scheme "http" | "https" The URL scheme
  • host string The requested host name
  • url string The request URL path
  • status number The HTTP status code that was returned to this request
  • ip string The IP address of the client that made the request (can be both IPv4 and IPv6)
  • date Date The time when the request was received
  • responseTime number The time in milliseconds that the request took to process
  • hasEvents boolean Whether any server-side error events occurred while processing this request

Interface: Cloudnode.Token

An authentication token

  • id string The ID or key of the token
  • created Date Date and time when this token was created
  • expires Date | null Date and time when this token expires. Null if it never expires.
  • permissions string[] Permission scopes that this token holds
  • internal string | undefined Whether this token is for internal use only, e.g. to power a session. In other words, an internal token is one that was not created by the client.
  • metadata Cloudnode.TokenMetadata Additional metadata about this token

Interface: Cloudnode.TokenMetadata

Token metadata

About

A client library for the Cloudnode API, written in TypeScript.

cloudnode.pro

Topics

api client library cloudnode

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 25

v3.0.3 Latest
Sep 12, 2023
+ 24 releases

Contributors 3

  •  
  •  
  •  

Languages