> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runonatlas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript

> `@runonatlas/core` is our JavaScript/TypeScript library for Atlas, which provides the base client for direct integration with Atlas services.

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

  * [Next.js SDK](/developer-portal/sdk/next) - For Next.js applications
  * [React SDK](/developer-portal/sdk/react) - For React applications
  * [Express SDK](/developer-portal/sdk/express) - For Express.js applications

  These framework-specific SDKs provide better integration and additional features tailored to each framework.
</Warning>

## Installation

<Tabs>
  <Tab title="npm">
    ```bash Terminal theme={null}
    npm install @runonatlas/core
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash Terminal theme={null}
    pnpm add @runonatlas/core
    ```
  </Tab>

  <Tab title="yarn">
    ```bash Terminal theme={null}
    yarn add @runonatlas/core
    ```
  </Tab>
</Tabs>

## Initialization

<Steps>
  <Step title="Set the Atlas API key in the environment variables">
    You can get it from the [Atlas Dashboard](https://app.runonatlas.com).

    ```bash .env theme={null}
    ATLAS_API_KEY="INSERT_YOUR_ATLAS_API_KEY"
    ```
  </Step>

  <Step title="Create the Atlas Client">
    To initialize the Atlas SDK, you need to instantiate the Atlas Client with your API key:

    ```typescript src/atlas/client.ts expandable theme={null}
    import { AtlasClient } from "@runonatlas/core";

    const atlas = new AtlasClient();
    ```
  </Step>
</Steps>

## Core Features

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

### Feature Management

#### Register Features

Register features that your application uses:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

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

### Pricing Model

Get information about your pricing model:

```typescript theme={null}
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:

```typescript src/atlas/client.ts expandable theme={null}
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.

```typescript theme={null}
  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.

```typescript src/index.ts theme={null}
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.

```typescript theme={null}
async function onProcessShutdown() {
  await atlas.flushEvents();
}
```