Skip to main content
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

  • npm
  • pnpm
  • yarn
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 may have 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: [...] }

​
Limit-based features

Sometimes, just having a feature as enabled or disabled is not enough, and our pricing models require limits to be set. For example, 5 users per account, or 20GB of storage. Setting this up with Atlas is very easy. And, if at some point the limits change, you won’t need to change the code again! 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;
    },
  },
});

​
Usage-based features

Usage-based and credit-based features allow you to bill customers based on their consumption. These features track usage events and apply billing according to your pricing model configuration.

​
Reporting events

To bill your customers correctly, your application must send an event to Atlas each time a usage-based feature is consumed. To do this, you can use the enqueueEvents method of the Atlas client. 
  await atlas.enqueueEvents({
    customerId: "customer-123",
    featureIds: ["usage-based-feature"],
    quantity: Math.floor(Math.random() * 10),
  });

​
Batching events

To optimize performance and avoid rate limits, the Atlas client automatically batches usage events before sending them. You can customize this batching behavior by configuring the eventsFlushAt (number of events) and eventsFlushInterval (time in milliseconds) options during client initialization.
src/index.ts
import { AtlasClient } from "@runonatlas/core";

const atlas = new AtlasClient({
  eventsFlushAt: 10,
  eventsFlushInterval: 1000,
});
You can also trigger a manual flush of all enqueued events at any time using the flushEvents method. This is particularly useful for ensuring no events are lost during a graceful shutdown of your application. 
async function onProcessShutdown() {
  await atlas.flushEvents();
}