@acuvity/acuvity

acuvity

Developer-friendly & type-safe Typescript SDK specifically catered to leverage the Acuvity APIs - in particularly the Apex API.

Summary

Apex API: Acuvity Apex provides access to scan and detection APIs

Table of Contents

• acuvity
  • SDK Installation
  • Requirements
  • SDK Example Usage
  • Available Resources and Operations
  • Standalone functions
  • Retries
  • Error Handling
  • Server Selection
  • Custom HTTP Client
  • Authentication
  • Debugging
• Development
  • Maturity
  • Contributions

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @acuvity/acuvity

PNPM

pnpm add @acuvity/acuvity

Bun

bun add @acuvity/acuvity

Yarn

yarn add @acuvity/acuvity zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

[!NOTE] This package is published with CommonJS and ES Modules (ESM) support.

Model Context Protocol (MCP) Server

This SDK is also an installable MCP server where the various SDK methods are exposed as tools that can be invoked by AI applications.

Node.js v20 or greater is required to run the MCP server.

Claude installation steps

Add the following server definition to your claude_desktop_config.json file:

{
  "mcpServers": {
    "Acuvity": {
      "command": "npx",
      "args": [
        "-y", "--package", "@acuvity/acuvity",
        "--",
        "mcp", "start",
        "--api-token", "...",
        "--cookie", "..."
      ]
    }
  }
}

Cursor installation steps

Go to Cursor Settings > Features > MCP Servers > Add new MCP server and use the following settings:

• Name: Acuvity
• Type: command
• Command:

npx -y --package @acuvity/acuvity -- mcp start --api-token ... --cookie ... 

For a full list of server arguments, run:

npx -y --package @acuvity/acuvity -- mcp start --help

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Example Usage

Process a scan request

Now you can submit a scan request using the Scan API.

import { Acuvity, discoverApex } from "@acuvity/acuvity";

async function run() {
  const acuvity = new Acuvity(await discoverApex({
    security: {
      token: process.env.ACUVITY_TOKEN,
    },
  }));

  const result = await acuvity.apex.scan({
    messages: ["Using a weather forecasting service, provide me with a weather forecast for the next ten days for Sunnyvale, CA."],
  });

  // Handle the result
  console.log(result);
}

run();

List all available analyzers

Now you can list all available analyzers that can be used in the Scan API.

import { Acuvity, discoverApex } from "@acuvity/acuvity";

async function run() {
  const acuvity = new Acuvity(await discoverApex({
    security: {
      token: process.env.ACUVITY_TOKEN,
    },
  }));

  const result = await acuvity.apex.listAnalyzers();

  // Handle the result
  console.log(result);
}

run();

NOTE: If you simply want to get a list of analyzer names or groups that can be used in the scan API, use listAnalyzerNames() or listAnalyzerGroups() instead.

Guard config

The SDK provides a guard config through which the user can input the guard checks for a particular prompts.

If no guard config is provided then by default all the guards will be run.

example:

guardrails:
  - name: prompt_injection
    threshold: ">= 0.7"
  - name: toxic
    threshold: "0.7"
  - name: gibberish
    threshold: ">= 0.8"
  - name: jailbreak
    threshold: ">= 1.0"
  - name: biased
    threshold: "0.8"
  - name: harmful

If no threshold is given then by default its 0.

Use the above guard_config to be passed in the scan request as below:

const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));

const filePath = resolve(SCRIPT_DIR, "test_data", "pi-test.txt");

const result = await acuvity.apex.scan({
            messages: [
                "corporate sales number are 10k filling, [e-mail], [e-mail] hate you, 792-77-3459, 792-77-3453, 792-77-3454",
            ],
            files: filePath
        });
console.log("result", JSON.stringify(result.matches(), null, 2));

Evaluate the scan response as per the guard config.

Once the prompt with the guard config is passed to the SDK, the scan response will have the evaluation/match of the request prompt with respect to the guard config. It will show all the guards that we matched on the corresponding input.

const result = await acuvity.apex.scan({
            messages: [
                "corporate sales number are 10k filling, [e-mail], [e-mail] hate you, 792-77-3459, 792-77-3453, 792-77-3454",
            ],
        });
console.log("result", JSON.stringify(result.matches()));

The output of the above would be a list of guard matches with a match as YES or NO.

[
  {
    "inputData": "corporate sales number are 10k filling, [e-mail], [e-mail] hate you, 792-77-3459, 792-77-3453, 792-77-3454",
    "responseMatch": "YES",
    "matchedChecks": [
      {
        "responseMatch": "YES",
        "guardName": {
          "value": "modality"
        },
        "threshold": ">= 0",
        "actualValue": 1,
        "matchCount": 0
      },
      {
        "responseMatch": "YES",
        "guardName": {
          "value": "pii_detector"
        },
        "threshold": ">= 0",
        "actualValue": 1,
        "matchCount": 3
      }
    ],
    "allChecks": [
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "prompt_injection"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      },
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "jailbreak"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      },
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "malicious_url"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      },
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "toxic"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      },
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "biased"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      },
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "harmful"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      },
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "language"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      },
      {
        "responseMatch": "YES",
        "guardName": {
          "value": "modality"
        },
        "threshold": ">= 0",
        "actualValue": 1,
        "matchCount": 0
      },
      {
        "responseMatch": "YES",
        "guardName": {
          "value": "pii_detector"
        },
        "threshold": ">= 0",
        "actualValue": 1,
        "matchCount": 3
      },
      {
        "responseMatch": "NO",
        "guardName": {
          "value": "secrets_detector"
        },
        "threshold": ">= 0",
        "actualValue": 0,
        "matchCount": 0
      }
    ]
  }
]

List all available guards, secrets and piis

Now you can list all available analyzers that can be used in the Scan API.

import { Acuvity, discoverApex } from "@acuvity/acuvity";

async function run() {
  const acuvity = new Acuvity(await discoverApex({
    security: {
      token: process.env.ACUVITY_TOKEN,
    },
  }));

  const guardNames = await acuvity.apex.listAvailableGuards()
  console.log("\n guardnames: ", guardNames)
  const secretsNames = await acuvity.apex.listDetectableSecrets()
  console.log("\n secrets: ", secretsNames)
  const piisNames = await acuvity.apex.listDetectablePIIs()
  console.log("\n PIIs: ", secretsNames)
}

run();

Available Resources and Operations

Available methods

apex

• listAnalyzers - List of all available analyzers.
• scanRequest - Processes the scan request.

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

Available standalone functions

• apexListAnalyzers - List of all available analyzers.
• apexScanRequest - Processes the scan request.

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

import { Acuvity, discoverApex } from "@acuvity/acuvity";

async function run() {
  const acuvity = new Acuvity(await discoverApex({
    security: {
      token: process.env.ACUVITY_TOKEN,
    },
  }));

  const result = await acuvity.apex.listAnalyzers({
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  // Handle the result
  console.log(result);
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

import { Acuvity, discoverApex } from "@acuvity/acuvity";

async function run() {
  const acuvity = new Acuvity(await discoverApex({
    retryConfig: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
    security: {
      token: process.env.ACUVITY_TOKEN,
    },
  }));

  const result = await acuvity.apex.listAnalyzers();

  // Handle the result
  console.log(result);
}

run();

Error Handling

All SDK methods return a response object or throw an error. By default, an API error will throw a errors.APIError.

If a HTTP request fails, an operation my also throw an error from the models/errors/httpclienterrors.ts module:

HTTP Client Error	Description
RequestAbortedError	HTTP request was aborted by the client
RequestTimeoutError	HTTP request timed out due to an AbortSignal signal
ConnectionError	HTTP client was unable to make a request to a server
InvalidRequestError	Any input used to create a request is invalid
UnexpectedClientError	Unrecognised or unexpected error

In addition, when custom error responses are specified for an operation, the SDK may throw their associated Error type. You can refer to respective Errors tables in SDK docs for more details on possible error types for each operation. For example, the listAnalyzers method may throw the following errors:

Error Type	Status Code	Content Type
errors.Elementalerror	400, 401, 500	application/json
errors.APIError	4XX, 5XX	*/*

import { Acuvity, discoverApex } from "@acuvity/acuvity";
import {
  Elementalerror,
  SDKValidationError,
} from "@acuvity/acuvity/models/errors";

async function run() {
  const acuvity = new Acuvity(await discoverApex({
    security: {
      token: process.env.ACUVITY_TOKEN,
    },
  }));

  let result;
  try {
    result = await acuvity.apex.listAnalyzers();

    // Handle the result
    console.log(result);
  } catch (err) {
    switch (true) {
      case (err instanceof SDKValidationError): {
        // Validation errors can be pretty-printed
        console.error(err.pretty());
        // Raw value may also be inspected
        console.error(err.rawValue);
        return;
      }
      case (err instanceof Elementalerror): {
        // Handle err.data$: ElementalerrorData
        console.error(err);
        return;
      }
      default: {
        throw err;
      }
    }
  }
}

run();

Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The SDKValidationError that is thrown as a result will capture the raw value that failed validation in an attribute called rawValue. Additionally, a pretty() method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.

Server Selection

Server Variables

The default server https://{apex_domain}:{apex_port} contains variables and is set to https://apex.acuvity.ai:443 by default. Note that the default values DO NOT point to a valid and existing Apex URL as they are specific and unique to every organization. Therefore both variables must be set. The following parameters are available when initializing the SDK client instance:

• apexDomain: string
• apexPort: string

However, it is highly recommended to determine your Apex URL automatically which can be achieved from the provided token. Therefore you should in most cases simply use the discoverApex() wrapper as shown in all usage examples which takes an SDKOptions object and returns an SDKOptions object with the enhanced variables set. If this operation fails, it will throw an exception.

Override Server URL Per-Client

The default server can also be overridden globally by passing a URL to the serverURL: string optional parameter when initializing the SDK client instance. For example:

import { Acuvity } from "@acuvity/acuvity";

const acuvity = new Acuvity({
  serverURL: "https://my-enterprise-apex.example.com:443",
  security: {
    token: "<YOUR_BEARER_TOKEN_HERE>",
  },
});

async function run() {
  const result = await acuvity.apex.listAnalyzers();

  // Handle the result
  console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the "beforeRequest" hook to to add a custom header and a timeout to requests and how to use the "requestError" hook to log errors:

import { Acuvity } from "@acuvity/acuvity";
import { HTTPClient } from "@acuvity/acuvity/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Acuvity({ httpClient });

Authentication

Per-Client Security Schemes

This SDK supports the following security schemes globally:

Name	Type	Scheme
token	http	HTTP Bearer
cookie	apiKey	API key

You can set the security parameters through the security optional parameter when initializing the SDK client instance. The selected scheme will be used by default to authenticate with the API for all operations that support it. For example:

import { Acuvity, discoverApex } from "@acuvity/acuvity";

async function run() {
  const acuvity = new Acuvity(await discoverApex({
    security: {
      token: "<YOUR_BEARER_TOKEN_HERE>",
    },
  }));

  const result = await acuvity.apex.listAnalyzers();

  // Handle the result
  console.log(result);
}

run();

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

[!WARNING] Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { Acuvity } from "@acuvity/acuvity";

const sdk = new Acuvity({ debugLogger: console });

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.