Artha JS SDK

The official JavaScript/TypeScript SDK for Artha billing infrastructure.

Installation

npm install artha-js

Quick Start

Basic Usage

import { Artha } from 'artha-js';

// Replace with your actual backend URL and API key
const artha = new Artha('https://your-backend-url.com', 'your-api-key');

// Check feature access
const checkResult = await artha.check({
  featureId: 'premium-feature',
  productId: 'pro-plan'
});

// Track usage
await artha.track({
  featureId: 'api-calls',
  value: 1,
  entityId: 'optional-entity-id'
});

// Attach product to customer
const attachResult = await artha.attach({
  productId: 'pro-plan',
  customerId: 'customer-123'
});

React Integration

import { ArthaProvider, useCustomer, useArtha } from 'artha-js/react';

function App() {
  return (
    <ArthaProvider 
      backendUrl={process.env.REACT_APP_ARTHA_BACKEND_URL} 
      apiKey={process.env.REACT_APP_ARTHA_API_KEY}
    >
      <CustomerDashboard />
    </ArthaProvider>
  );
}

function CustomerDashboard() {
  const { customer, loading } = useCustomer();
  const artha = useArtha();

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      <h1>Welcome, {customer?.name}</h1>
      <button onClick={() => artha.track({ featureId: 'button-click', value: 1 })}>
        Track Click
      </button>
    </div>
  );
}

Backend Integration

Next.js

import { createArthaHandler } from 'artha-js/next';

export const { GET, POST } = createArthaHandler({
  backendUrl: process.env.ARTHA_BACKEND_URL!,
  getCustomerId: (request) => {
    // Extract customer ID from your auth system
    return request.headers.get('x-customer-id');
  },
  getCustomerData: async (customerId) => {
    // Fetch customer data from your database
    return { name: 'John Doe', email: 'john@example.com' };
  }
});

Express.js

import express from 'express';
import { createArthaMiddleware } from 'artha-js/express';

const app = express();

app.use('/api/artha', createArthaMiddleware({
  backendUrl: process.env.ARTHA_BACKEND_URL!,
  getCustomerId: (req) => req.user?.id,
  getCustomerData: async (customerId) => {
    return await User.findById(customerId);
  }
}));

API Reference

Core Classes

`Artha`

Main SDK class for direct API interactions.

const artha = new Artha(backendUrl?: string, apiKey?: string);

Methods:

attach(params: CheckoutParams) - Attach a product to a customer
check(params: { featureId?: string; productId?: string }) - Check feature/product access
track(params: { featureId: string; value: number; entityId?: string }) - Track feature usage
getCustomer(customerId?: string) - Get customer information
getProducts() - Get available products

React Hooks

`useCustomer()`

const { customer, loading, error, refetch } = useCustomer();

`useProducts()`

const { products, loading, error, refetch } = useProducts();

`useArtha()`

const artha = useArtha(); // Returns Artha instance

Types

import type {
  Product,
  Customer,
  CheckoutParams,
  CheckoutResult,
  ApiResponse
} from 'artha-js';

Configuration

Environment Variables

Server-side (Node.js/Backend):

ARTHA_BACKEND_URL - Your Artha backend URL (e.g., https://api.artha.com)
ARTHA_API_KEY - Your secret API key

Client-side (React/Frontend):

REACT_APP_ARTHA_BACKEND_URL - Your Artha backend URL
REACT_APP_ARTHA_API_KEY - Your public API key (if needed)

Example .env file:

# Backend
ARTHA_BACKEND_URL=https://api.artha.com
ARTHA_API_KEY=sk_live_your_secret_key_here

# Frontend (React)
REACT_APP_ARTHA_BACKEND_URL=https://api.artha.com
REACT_APP_ARTHA_API_KEY=pk_live_your_public_key_here

Backend Handler Options

interface HandlerOptions {
  backendUrl: string;
  getCustomerId: (request: Request) => string | null;
  getCustomerData?: (customerId: string) => Promise<any>;
  apiKey?: string;
}

Error Handling

All SDK methods return ApiResponse<T> objects:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

// Usage
const result = await artha.check({ featureId: 'premium' });
if (result.success) {
  console.log('Feature check:', result.data);
} else {
  console.error('Error:', result.error);
}

Framework Support

✅ React - Full support with hooks and context
✅ Next.js - API route handlers
✅ Express.js - Middleware support
✅ Vanilla JS/TS - Core SDK
🔄 More frameworks coming soon

License

MIT

Support

For support, email support@artha.com or visit our documentation.