JavaScript SDK

Installation

Our JavaScript SDK is distributed via npm and can be installed using your favorite package manager (requires Node.js version 16+).

npm install @capeprivacy/cape-sdk

If you are using yarn:

yarn add @capeprivacy/cape-sdk

Or if you are using pnpm:

pnpm add @capeprivacy/cape-sdk

Import the SDK

There are three ways to import the Cape SDK into your project.

1. ES module style: Use the import statement (recommended):

   import { Cape } from "@capeprivacy/cape-sdk";

2. CommonJS style: Use the const statement:

   const { Cape } = require("@capeprivacy/cape-sdk");

3. Script tag: Use the script tag in an HTML document:

   <script type="module">
     import { Cape } from "https://cdn.skypack.dev/@capeprivacy/cape-sdk";
   </script>

Initialization

The Cape SDK exposes a single class Cape which is used to initialize the SDK. The Cape constructor can be initialized with the following object:

Property	Type	Description
authToken	string | undefined	Your account auth token which can be used to call functions. Required.
checkDate	Date | undefined	Enable a specific date to check the certificate against.
verbose	boolean | undefined	Whether or not to log Cape SDK logs to the console.

Example Usage

const cape = new Cape({ authToken: "YOUR AUTH TOKEN" });

cape.run

cape.run is used to run a function one time. It will open an enclave, send the data to the enclave, and then return the result. This method is useful if you do not need to manage the lifecycle of the enclave yourself. cape.run takes a single Object as an argument with the following properties:

async cape.run(config: Object): Promise<string>

Parameter	Type	Description
config	Object	The configuration object to run the function.

Property	Type	Description
id	string	The ID of the function to run. The ID can be in the form of <username>/<function_name> or the function ID itself. E.g., 26TmysX9Jmvu69fpUpXCYz
data	string | string[] | number | number[] | Buffer | ArrayBuffer | Uint8Array | Uint16Array | Uint32Array | Record<string, unknown> | Record<string, unknown>[]	The data to send to the enclave.

Example Usage

import { Cape } from "@capeprivacy/cape-sdk";

const cape = new Cape({ authToken: "YOUR_AUTH_TOKEN" });

try {
  const result = await cape.run({
    id: "YOUR_FUNCTION_ID",
    data: "YOUR_DATA",
  });
  console.log(result);
} catch (error) {
  console.error("Unexpected error occurred:", error);
}

cape.connect

cape.connect is used to set up the connection to an enclave. This method will open a connection with an enclave and remains open until cape.disconnect is called. This method isn't meant to be used by itself, but instead to be used in conjunction with cape.invoke and cape.disconnect to give you fine-grained control over the lifecycle of the enclave.

Please note that there is a 60-second inactivity timeout on the enclave connection. You may need to monitor the connection status and reconnect if there is a significant wait between inputs.

interface ConnectArgs {
  id: string
}

async cape.connect(config: Object): Promise<void>

Parameter	Type	Description
config	Object	The configuration object to connect to the enclave.

Property	Type	Description
id	string	The ID of the function to run. The ID can be in the form of <username>/<function_name> or the function ID itself. E.g., 26TmysX9Jmvu69fpUpXCYz

cape.invoke

cape.invoke invokes the function within the enclave. This method differs from cape.run as it does not open a new enclave, but instead uses the enclave that was opened by cape.connect. This method is useful if you need to call a function multiple times and want to avoid the overhead of opening a new enclave each time.

async cape.invoke(config: Object): Promise<string>

Parameter	Type	Description
config	Object	The configuration object to invoke a function in the enclave.

Property	Type	Description
data	string | string[] | number | number[] | Buffer | ArrayBuffer | Uint8Array | Uint16Array | Uint32Array | Record<string, unknown> | Record<string, unknown>[]	The data to send to the enclave.

Example Usage

import { Cape } from "@capeprivacy/cape-sdk";

const cape = new Cape({ authToken: "YOUR_AUTH_TOKEN" });

try {
  await cape.connect({ id: "YOUR_FUNCTION_ID" });

  const results = await Promise.all([
    cape.invoke({ data: "YOUR_DATA_1" }),
    cape.invoke({ data: "YOUR_DATA_2" }),
    cape.invoke({ data: "YOUR_DATA_3" }),
  ]);
  console.log(results);
} catch (error) {
  console.error("Unexpected error occurred:", error);
} finally {
  cape.disconnect();
}

cape.encrypt

cape.encrypt encrypts user-provided data in string format for use exclusively inside the enclave.

The input is HPKE encrypted with the provided publickey. If no public key is provided, then your own public key will be used.

async cape.encrypt(input: string): Promise<string>

Parameter	Type	Description
config	Object	The configuration object to invoke a function in the enclave.

Property	Type	Description
input	string	User provided input to be encrypted for running in an enclave.

Example Usage

import { Cape } from "@capeprivacy/cape-sdk";

const cape = new Cape({ authToken: "YOUR_PAT" });
const data = await cape.encrypt("hello world");
console.log(data);

You can also encrypt data that can only be decrypted by specific users.

import { Cape } from "@capeprivacy/cape-sdk";

const cape = new Cape({ authToken: "YOUR_PAT" });
const data = await cape.encrypt("hello world", { username: "capedocs" });
console.log(data);

cape.disconnect

cape.disconnect disconnects the connection with the enclave. This method must be called when manually managing the lifecycle of the enclave.

cape.disconnect(): void