This guide is for direct JavaScript/TypeScript integration. If you’re using one of our supported frameworks, we recommend using their dedicated SDKs instead:

These framework-specific SDKs provide better integration and additional features tailored to each framework.

​
Installation

Terminal
npm install @runonatlas/core

​
Initialization

1

Set the Atlas API key in the environment variables

You can get it from the Atlas Dashboard.

.env
ATLAS_API_KEY="INSERT_YOUR_ATLAS_API_KEY"
2

Create the Atlas Client

To initialize the Atlas SDK, you need to instantiate the Atlas Client with your API key:

src/atlas/client.ts
import { AtlasClient } from "@runonatlas/core";

const atlas = new AtlasClient();

​
Core Features

The Atlas JavaScript client provides several methods to interact with Atlas services:

​
Feature Management

​
Register Features

Register features that your application uses:

await atlas.registerFeatureUsage("data-explorer");

The feature registration is used to ensure that the feature is registered in Atlas. If the feature is not registered, it will be registered automatically and an alert will be sent to the administrators.

​
Check Feature Access

Check if a customer has access to specific features:

const { ok, features } = await atlas.areFeaturesAllowed("customer-123", [
  "data-explorer",
  "ai-assistant",
]);

if (ok) {
  // Customer has access to all required features
} else {
  // Check individual feature access
  console.log(features); // { "data-explorer": true, "ai-assistant": false }
}

​
Customer Management

​
Get Customer Features

Retrieve all features a customer has access to:

const features = await atlas.getCustomerFeatures("customer-123");
console.log(features); // { "data-explorer": { allowed: true, included: true, limit: 10, currentUsage: 5 }, "ai-assistant": { allowed: false, included: false } }

​
Get Customer Details

Get detailed information about a customer:

const customer = await atlas.getCustomerDetails("customer-123");
console.log(customer); // { id: "customer-123", name: "John Doe", ... }

​
Pricing Model

Get information about your pricing model:

const pricingModel = await atlas.getPricingModel();
console.log(pricingModel); // { plans: [...], features: [...] }

​
Setting up limit-based features

When initializing the Atlas client, you can configure a limit callback for a feature. This callback will be called when a limit-based feature is checked. The callback should return the number of usages for the feature.

For example:

src/atlas/client.ts
import { AtlasClient } from "@runonatlas/core";

const atlas = new AtlasClient({
  limits: {
    "data-explorer": async () => {
      // Return the number of usages for the data-explorer feature
      return 5;
    },
  },
});