npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

voltcloud-for-servers

v0.1.2

Published

a simple VoltCloud library for servers

Downloads

9

Readme

voltcloud-for-servers

a simple VoltCloud library for servers

this module is currently under active development and not yet ready for being used. Please, stay tuned.

VoltCloud.io is a simple (and reasonably priced) deployment server for web applications with integrated user management and key-value stores for both the application itself and any of its users.

voltcloud-for-servers is a simple client library for servers based on Node.js which need access to VoltCloud and its functions.

See below for a "smoke test" which may also serve as an example for how to use this library.

Please note: the author is not affiliated with the NSB Corporation in any way. If you want to blame any of the author's VoltCloud-related tools and libraries for some misbehaviour, it's not the fault of George Henne and his team - it is the author's mistake!

NPM users: please consider the Github README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Just a small note: if you like this module and plan to use it, consider "starring" this repository (you will find the "Star" button on the top right of this page), so that I know which of my repositories to take most care of.

Prerequisites

voltcloud-for-servers requires Node.js. Since you are visiting this page, chances are good that you already have Node.js installed on your machine - if not, please follow the instructions found on nodejs.org to install it (the LTS version is sufficient if you don't plan to use Node.js on a regular basis)

Installation

Simply install the package into your build environment using NPM with the command

npm install voltcloud-for-servers

Access

Within your Node.js script, you may then import any functions you need - the following example will import all of them:

import {
  actOnBehalfOfDeveloper, ApplicationRecords, CustomerRecords,
  focusOnApplication, focusOnApplicationCalled, focusOnNewApplication,
  ApplicationRecord, changeApplicationNameTo, updateApplicationRecordBy,
    uploadToApplication, deleteApplication,
  ApplicationStorage, ApplicationStorageEntry, setApplicationStorageEntryTo,
    deleteApplicationStorageEntry, clearApplicationStorage,
  focusOnCustomer, focusOnCustomerWithAddress, focusOnNewCustomer,
  resendConfirmationEMailToCustomer, confirmCustomerUsing,
  startPasswordResetForCustomer, resetCustomerPasswordUsing,
  CustomerRecord, deleteCustomer,
  CustomerStorage, CustomerStorageEntry, setCustomerStorageEntryTo,
    deleteCustomerStorageEntry, clearCustomerStorage
} from 'voltcloud-for-servers'

Just copy that statement into your source code and remove all unwanted functions.

API Reference

exported Constants

voltcloud-for-servers exports the following constants:

  • const ApplicationNamePattern = /^([a-z0-9]|[a-z0-9][-a-z0-9]*[a-z0-9])$/this value defines the regular expression pattern, any VoltCloud application name must match to
  • const maxApplicationNameLength = 63this value defines the maximum length of any VoltCloud application name
  • const maxEMailAddressLength = 255this value defines the maximum length of the email address used to identify developers and customers
  • const maxNamePartLength = 255this value defines the maximum length of the first or last name of any customer
  • const maxStorageKeyLength = 255this value defines the maximum length of any key in a VoltCloud key-value store
  • const maxStorageValueLength = 1048574this value defines the maximum length of any value in a VoltCloud key-value store

exported Types

TypeScript programmers may import the following types in order to benefit from static type checking (JavaScript programmers may simply skip this section):

  • type VC_ApplicationName = stringapplication names must be string with 1...maxApplicationNameLength characters matching the regular expression ApplicationNamePattern
  • type VC_ApplicationRecord = {id:string, owner:string, subdomain:string, disabled:boolean, url:string, canonical_domain?:string, confirmation_url?:string, reset_url?:string, last_upload?:string, nice_links:boolean, cors_type:string, cors_domain?:string, frame_type:string, frame_domain?:string}instances of this type are returned when details of an existing application are requested
  • type VC_ApplicationUpdate = {subdomain?:string, disabled?:boolean, canonical_domain?:string, confirmation_url?:string, reset_url?:string, nice_links?:boolean, cors_type?:string, cors_domain?:string, frame_type?:string, frame_domain?:string}instances of this type are used when specific details of an existing application shall be changed
  • type VC_CustomerRecord = { id:string, email:VC_EMailAddress, first_name?:VC_NamePart, last_name?:VC_NamePart, confirmed:boolean, admin:boolean, meta?:any }instances of this type are returned when details of an already registered user are requested
  • type VC_CustomerUpdate = { email?:VC_EMailAddress, password?:{ old:string, new:string, confirmation:string }, first_name?:string, last_name?:string }instances of this type are used when specific details of an already registered user shall be changed
  • type VC_EMailAddress = stringthe EMail addresses used to identify developers and customers are strings with up to maxEMailAddressLength characters
  • type VC_Password = stringVoltCloud passwords are strings
  • type VC_NamePart = stringthe first and last names of any customer are strings with up to maxNamePartLength characters
  • type VC_StorageKey = stringVoltCloud storage keys are strings with a length of up to maxStorageKeyLength characters
  • type VC_StorageValue = string | undefinedVoltCloud storage values are strings with a length of up to maxStorageValueLength characters. While VoltCloud itself responds with an error when non-existing entries are read, voltcloud-for-applications returns undefined instead
  • type VC_StorageSet = { [Key:string]:VC_StorageValue }a VoltCloud storage can be seen as an associative array with literal keys and values

exported Functions

  • ValueIsPassword (Value:any):booleanreturns true if the given value may be used as a VoltCloud password (i.e., if it is a string which fulfills the requirements of a VoltCloud password) or false otherwise
  • allowPassword (Description:string, Argument:any):stringchecks if the given Argument (if it exists), may be used as a VoltCloud password (i.e., is a string which fulfills the requirements of a VoltCloud password). If this is the case (or Argument is missing), the function returns the primitive value of the given Argument, otherwise an error with the message "the given ${Description} is no valid VoltCloud password" is thrown, which uses the given Description. As in the javascript-interface-library, the variants allowedPassword, expectPassword and expectedPassword exist as well 
  • ValueIsApplicationName (Value:any):booleanreturns true if the given value may be used as a VoltCloud application name (i.e., if it is a string with 1...maxApplicationNameLength characters matching the regular expression ApplicationNamePattern) or false otherwise
  • allowApplicationName (Description:string, Argument:any):stringchecks if the given Argument (if it exists), may be used as a VoltCloud application name (i.e., is a string with 1...maxApplicationNameLength characters matching the regular expression ApplicationNamePattern). If this is the case (or Argument is missing), the function returns the primitive value of the given Argument, otherwise an error with the message "the given ${Description} is no valid VoltCloud application name" is thrown, which uses the given Description. As in the javascript-interface-library, the variants allowedApplicationName, expectApplicationName and expectedApplicationName exist as well 
  • ValueIsStorageKey (Value:any):booleanreturns true if the given value may be used as a key for a VoltCloud key-value store or false otherwise
  • expectStorageKey (Description:string, Argument:any):stringchecks if the given Argument (if it exists), may be used as a key for a VoltCloud key-value store. If this is the case (or Argument is missing), the function returns the primitive value of the given Argument, otherwise an error with the message "the given ${Description} is no valid VoltCloud storage key" is thrown, which uses the given Description. As in the javascript-interface-library, the variants allowedStorageKey, expectStorageKey and expectedStorageKey exist as well 
  • ValueIsStorageValue (Value:any):booleanreturns true if the given value may be used as a value in a VoltCloud key-value store or false otherwise
  • expectStorageValue (Description:string, Argument:any):stringchecks if the given Argument (if it exists), may be used as a value for a VoltCloud key-value store. If this is the case (or Argument is missing), the function returns the primitive value of the given Argument, otherwise an error with the message "the given ${Description} is no valid VoltCloud storage value" is thrown, which uses the given Description. As in the javascript-interface-library, the variants allowedStorageValue, expectStorageValue and expectedStorageValue exist as well 
  • async function actOnBehalfOfDeveloper (EMailAddress:string, Password:string):Promise<void>uses the given EMailAddress and Password to request an "access token" from VoltCloud, which is then used to authenticate any non-public VoltCloud request. Note: EMailAddress and Password are kept in memory while the process is running in order to automatically refresh the token upon expiry 
  • async function ApplicationRecords ():Promise<VC_ApplicationRecord[]>retrieves a (potentially empty) list with the details of all applications created by the currently configured developer. See above for the internals of the delivered list items 
  • async function focusOnApplication (ApplicationId:string):Promise<void>sets the application given by ApplicationId as the target for all following application-specific requests. The function will fail, if no such application exists for the currently configured developer
  • async function focusOnApplicationCalled (ApplicationName:VC_ApplicationName):Promise<void>sets the application given by ApplicationName as the target for all following application-specific requests. The function will fail, if no such application exists for the currently configured developer
  • async function focusOnNewApplication ():Promise<void>creates a new application for the currently configured developer and sets it as the target for all following application-specific requests
  • async function ApplicationRecord ():Promise<VC_ApplicationRecord | undefined>retrieves a record with details of the current target application. See above for the internals of the delivered object
  • async function changeApplicationNameTo (ApplicationName:VC_ApplicationName):Promise<void>renames the current target application to ApplicationName
  • async function updateApplicationRecordBy (Settings:VC_ApplicationUpdate):Promise<void>updates the details given by Settings in the current target application. See above for the internals of the Settings object
  • async function uploadToApplication (ZIPArchive:Buffer):Promise<void>uploads the ZIP archive given by ZIPArchive to the current target application
  • async function deleteApplication (ApplicationId:string):Promise<void>deletes the currently focused application 
  • async function ApplicationStorage ():Promise<VC_StorageSet>retrieves the complete key-value store for the current target application and delivers it as a JavaScript object
  • async function ApplicationStorageEntry (StorageKey:VC_StorageKey):Promise<VC_StorageValue | undefined>retrieves an entry (given by StorageKey) from the key-value store for the current target application and returns its value (as a JavaScript string) - or undefined if the requested entry does not exist
  • async function setApplicationStorageEntryTo (StorageKey:VC_StorageKey, StorageValue:VC_StorageValue):Promise<void>sets the entry given by StorageKey in the key-value store for the current target application to the value given by StorageValue (which must be a JavaScript string). If the entry does not yet exist, it will be created
  • async function deleteApplicationStorageEntry (StorageKey:VC_StorageKey):Promise<void>removes the entry given by StorageKey from the key-value store for the current target application. It is ok to "delete" a non-existing entry (this function is "idempotent")
  • async function clearApplicationStorage ():Promise<void>removes all entries from the key-value store for the current target application. It is ok to "clear" an empty store (this function is "idempotent") 
  • async function CustomerRecords ():Promise<VC_CustomerRecord[]>retrieves a (potentially empty) list with the details of all customers who registered for the current target application. See above for the internals of the delivered list items 
  • async function focusOnCustomer (CustomerId:string):Promise<void>sets the customer given by CustomerId as the target for all following (customer-specific) requests
  • async function focusOnCustomerWithAddress (EMailAddress:string):Promise<void>sets the customer with the email address given by EMailAddress as the target for all following (customer-specific) requests
  • async function focusOnNewCustomer (EMailAddress:string, Password:string):Promise<void>registers a new customer with the email address given by EMailAddress, sets the given Password as the initial password and sets him/her as the target for all following (customer-specific) requests. If configured for the current target application, this request will automatically send a customer confirmation email to the given address 
  • async function resendConfirmationEMailToCustomer (EMailAddress?:string):Promise<void>if configured for the current target application, this function will send another customer confirmation email to the address given by EMailAddress - if no such address is given, that email is sent to the current target customer
  • async function confirmCustomerUsing (Token:string):Promise<void>confirms the email address given for a newly registered customer by providing the Token sent as part of a customer confirmation email. This token internally also specifies the customer to whom it was sent 
  • async function startPasswordResetForCustomer (EMailAddress?:string):Promise<void>if configured for the current target application, this function will send a password reset email to the address given by EMailAddress - if no such address is given, that email is sent to the current target customer
  • async function resetCustomerPasswordUsing (Token:string, Password:string):Promise<void>sets Password as the new password for a customer by providing the Token sent as part of a password reset email. This token internally also specifies the customer to whom it was sent 
  • async function CustomerRecord (CustomerId?:string):Promise<VC_CustomerRecord | undefined>retrieves a record with all current VoltCloud settings for the customer given by CustomerId - if no such id is given, the current target customer's record will be retrieved. If no such customer exists (for the current target application), undefined is returned instead. See above for the internals of the delivered object
  • async function deleteCustomer ():Promise<void>deletes the current target customer 
  • async function CustomerStorage ():Promise<VC_StorageSet>retrieves the complete key-value store for the current target customer and delivers it as a JavaScript object
  • async function CustomerStorageEntry (StorageKey:VC_StorageKey):Promise<VC_StorageValue | undefined>retrieves an entry (given by StorageKey) from the key-value store for the current target customer and returns its value (as a JavaScript string) - or undefined if the requested entry does not exist
  • async function setCustomerStorageEntryTo (StorageKey:VC_StorageKey, StorageValue:VC_StorageValue):Promise<void>sets the entry given by StorageKey in the key-value store for the current target customer to the value given by StorageValue (which must be a JavaScript string). If the entry does not yet exist, it will be created
  • async function deleteCustomerStorageEntry (StorageKey:VC_StorageKey):Promise<void>removes the entry given by StorageKey from the key-value store for the current target customer. It is ok to "delete" a non-existing entry (this function is "idempotent")
  • async function clearCustomerStorage ():Promise<void>removes all entries from the key-value store for the current target customer. It is ok to "clear" an empty store (this function is "idempotent")

Smoke Test

This repository contains a small "smoke test" (in a file called "smoke-test.js") which may also serve as an example for how to use voltcloud-for-servers. It illustrates the "good cases" of all functions offered by this library.

Preparation

The test becomes available if you download this repository (either using git in any of its variants or by unpacking a downloaded a ZIP archive containing this repo)

Now navigate to the folder containg the files of this repository and run

npm install

once in order to install any dependencies for the test.

The smoke test itself may be configured using the following set of environment variables:

  • developer_email_address - set this to the email address of the developer for whom the test should run
  • developer_password - set this to the developer's password
  • customer_email_address - set this to an email address (different from that for the developer!) you have access to. It will become the address of a "customer"
  • customer_password - set this to the "customer"s password (which must meet the VoltCLoud password requirements)
  • customer_confirmation_token - initially, this variable should remain blank. Follow the instructions given by "smoke-test.js" to set it to a customer confirmation token when needed
  • customer_password_reset_token - initially, this variable should remain blank. Follow the instructions given by "smoke-test.js" to set it to a password reset token when needed

Execution

The test may be started from within a shell using

node smoke-test.js

Important: for all procedures to get tested, you will have to start the script four times - in between, you may have to set the environment variables customer_confirmation_token or customer_password_reset_token following the instructions printed on the console

Build Instructions

You may easily build this package yourself.

Just install NPM according to the instructions for your platform and follow these steps:

  1. either clone this repository using git or download a ZIP archive with its contents to your disk and unpack it there
  2. open a shell and navigate to the root directory of this repository
  3. run npm install in order to install the complete build environment
  4. execute npm run build to create a new build

If you made some changes to the source code, you may also try

npm run agadoo

in order to check if the result is still tree-shakable.

You may also look into the author's build-configuration-study for a general description of his build environment.

License

MIT License