Nine Pounds of Mayonnaise

    onetimesecret-api
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • Public • Published

    npm version Build Status

    onetimesecret-api

    A thin Javascript wrapper around the OneTimeSecret API.

    OneTimeSecret is an open-source secret-sharing service that ensures that secrets can be shared securely and are only read once. The service can be accessed via the webpage, or via API. This project provides a thin Javascript wrapper for the API that makes it easy to use the service or a self-hosted server in any Javascript project. You can find the source code in the OneTimeSecret Github.

    The module is published on NPM as onetimesecret-api.

    Dependencies

    • Node.js: 8 and 10+

    Installation

    yarn add onetimesecret-api

    or

    npm install onetimesecret-api

    Usage

    The API wrapper is implemented for asynchronous control flow using promises. For most calls the promise resolves into a Javascript object containing all attributes provided by the server. Configuration or server errors are thrown and have to be handled by the caller. Only the most important attributes of a call are documented here, please check out the API description for the full documentation.

    In order to use the API the API class must be imported and setup to get a handler.

    OneTimeSecretApi(<username>, <api_key>, [<options>])
    
    • <username>: username specified during sign-up at the OneTimeSecret Service, or your server of choice (if defined in the <options>)
    • <password>: Password or API key created for your account
    • <options>: additional api options
      • <url>: server url of a custom server
      • <apiVersion>: API version to use (currently only "v1"). ApiVersion provides a list of supported API versions
    • Returns instance of the API
    • Throws InputError if <username> or <password> is missing

    Example:

    import {OneTimeSecretApi} from "onetimesecret-api";
    
    const ots = new OneTimeSecretApi("tom@example.com", "04821d62");

    or

    import {OneTimeSecretApi} from "onetimesecret-api";
    
    const ots = new OneTimeSecretApi(
        "tom@example.com",
        "04821d62",
        { url: "https://www.my-ots-server.com", apiVersion: "v1" });

    or

    import {InputError, OneTimeSecretApi} from "onetimesecret-api";
    
    try {
        const ots = new OneTimeSecretApi();
    } catch(error) {
        if (error instanceof InputError) {
            console.error("Username or password missing");
        } else {
            console.error(`Unknown error: ${error}`);
        }
    }

    Status

    Request the server status as boolean.

    status() -> boolean
    
    • Returns boolean state of server
    • Throws
      • InternalServerError: unspecified internal server error
      • NotAuthorizedError: invalid username or password
      • RateLimitedError: account has been rate limited due to many requests
      • TimeoutError: request timeout

    Example:

    ots.status()
    .then((status) => {
        console.log(`Status: ${status}`);
    })
    .catch((error) => {
        console.error(`Error: ${error}`);
    });

    Share

    Encrypt and share a secret.

    share(<secret>, [<options>]) -> object
    
    • <secret>: the secret to share (depending on your account type 1k to 10k length)
    • <options>: additional api options of type ApiOptionsShare
      • <passphrase>: passphrase that will be required to read the secret
      • <ttl>: time in seconds after which the secret will be automatically be deleted ("burned")
      • <recipient>: email address of the person the secret should be sent to by the server
    • Returns a promise that provides an ApiResponseShare object. The returned object contains all of the metadata of the newly created secret. Important values:
      • secret_key: the secret key that is used to share the secret
      • share_link: the share link of the secret that is supposed to be be shared
      • metadata_key: key used to manage the secret; this key must remain private
    • Throws
      • InputError: no secret provided
      • InternalServerError: unspecified internal server error
      • NetworkError: network request failed
      • NotFoundError: the call isn't supported by the server
      • NotAuthorizedError: invalid username or password
      • RateLimitedError: account has been rate limited due to many requests
      • TimeoutError: request timeout

    Examples:

    ots.share('My very special secret')
    .then((response) => {
        console.log(`Secret key: ${response.secret_key}`);
    })
    catch((error) => {
        console.error(`Error: ${error}`);
    });

    or

    ots.share('My very special secret', { ttl: 3600 })
    .then((response) => {
        console.log(`Secret key: ${response.secret_key}`);
    })
    .catch((error) => {
        console.error(`Error: ${error}`);
    });

    Generate

    Generate a short, encrypted secret and share it.

    generate([<options>]) -> object
    
    • <options>: additional api options of type ApiOptionsGenerate
      • <passphrase>: passphrase that will be required to read the secret
      • <ttl>: time in seconds after which the secret will be automatically be deleted ("burned")
      • <recipient>: email address of the person the secret should be sent to by the server
    • Returns a promise that provides an ApiResponseGenerate object. The returned object contains all of the metadata of the newly created secret. Important values:
      • secret_key: the secret key that is used to share the secret
      • share_link: the share link of the secret that is supposed to be be shared
      • metadata_key: key used to manage the secret; this key must remain private
    • Throws
      • InternalServerError: unspecified internal server error
      • NetworkError: network request failed
      • NotFoundError: the call isn't supported by the server
      • NotAuthorizedError: invalid username or password
      • RateLimitedError: account has been rate limited due to many requests
      • TimeoutError: request timeout

    Example:

    ots.generate()
    .then((response) => {
        console.log(`Secret key: ${response.secret_key}`);
    })
    .catch((error) => {
        console.error(`Error: ${error}`);
    });

    Retrieve secret

    Retrieve a secret from the server. This call is used to get a secret someone else shared with you. If the secret was shared with a passphrase it has to be provided to the call in the options.

    retrieveSecret(secret_key, [<options>]) -> object
    
    • <secret_key>: secret key that was shared with you
    • <options>: additional api options of type ApiOptionsRetrieveSecret
      • <passphrase>: passphrase that will be required to read the secret
    • Returns a promise that provides an ApiResponseRetrieveSecret object. The returned object contains all the information of the secret you can access. Important values:
      • value: the secret shared with you
    • Throws
      • InputError: no secret key provided
      • InternalServerError: unspecified internal server error
      • NetworkError: network request failed
      • NotFoundError: the call isn't supported by the server
      • NotAuthorizedError: invalid username or password
      • RateLimitedError: account has been rate limited due to many requests
      • TimeoutError: request timeout
      • UnknownSecretError: secret key not found

    Example:

    ots.retrieveSecret('hbo11uxhmg2gze0mlcmyf4x0qahawqa')
    .then((response) => {
        console.log(`Secret value: ${response.value}`);
    })
    .catch((error) => {
        console.error(`Error: ${error}`);
    });

    Retrieve metadata

    Retrieve metadata for a secret you created.

    retrieveMetadata(metadata_key) -> object
    
    • <metadata_key>: metadata key that was shared with you
    • Returns a promise that provides an ApiResponseRetrieveMetadata object. The returned object contains all of the metadata of the newly created secret. Important values:
      • secret_key: the secret key that is used to share the secret
      • share_link: the share link of the secret that is supposed to be be shared
      • status: status of the secret, e.g. "new", "received", "burned", "viewed", ...
    • Throws
      • InputError: no metadata key provided
      • InternalServerError: unspecified internal server error
      • NetworkError: network request failed
      • NotFoundError: the call isn't supported by the server
      • NotAuthorizedError: invalid username or password
      • RateLimitedError: account has been rate limited due to many requests
      • TimeoutError: request timeout
      • UnknownSecretError: metadata key not found

    Example:

    ots.retrieveMetadata('hbo11uxhmg2gze0mlcmyf4x0qahawqa')
    .then((response) => {
        console.log(`Status: ${response.status}`);
    })
    .catch((error) => {
        console.error(`Error: ${error}`);
    });

    Burn secret

    Destroy a secret you created.

    burn(metadata_key) -> object
    
    • <metadata_key>: metadata key that was shared with you
    • Returns a promise that provides an ApiResponseBurn object. The returned object contains all of the metadata of the newly created secret. Important values:
      • secret_key: the secret key that is used to share the secret
      • status: status of the secret set to "burned"
    • Throws
      • InputError: no metadata key provided
      • InternalServerError: unspecified internal server error
      • NetworkError: network request failed
      • NotFoundError: the call isn't supported by the server
      • NotAuthorizedError: invalid username or password
      • RateLimitedError: account has been rate limited due to many requests
      • TimeoutError: request timeout
      • UnknownSecretError: metadata key not found

    Example:

    ots.burn('raldp8yshsh42hyse')
    .then((response) => {
        console.log(`Status: ${response.status}`);
    })
    .catch((error) => {
        console.error(`Error: ${error}`);
    });

    Retrieve recent secrets

    Retrieve all recently created secrets and most of its metadata.

    recentMetadata() -> Array[object]
    
    • Returns a promise that provides an ApiResponseRecentMetadata object. The returned object contains a list if objects where each object represents a secret. It has a subset of attributes as described for retrieve_metadata.
    • Throws
      • InternalServerError: unspecified internal server error
      • NetworkError: network request failed
      • NotFoundError: the call isn't supported by the server
      • NotAuthorizedError: invalid username or password
      • RateLimitedError: account has been rate limited due to many requests
      • TimeoutError: request timeout

    Example:

    ots.recentMetadata()
    .then((response) => {
        console.log(`Secret 0 state: ${response[0].state}`);
    })
    .catch((error) => {
        console.error(`Error: ${error}`);
    });

    Release

    1. Update and commit changes
    2. Compile Javascript files: yarn build
    3. Commit Javascript files
    4. Publish to npm: yarn publish or npm publish

    Install

    npm i onetimesecret-api

    DownloadsWeekly Downloads

    1

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    60.5 kB

    Total Files

    15

    Last publish

    Collaborators

    • tgamauf