AppCenter Node.js SDK

Official Node.js SDK for AppCenter - Manage apps and premium users with token-based subscriptions.

Installation

npm install @appmerge/appcenter-sdk

Quick Start

const AppCenter = require('@appmerge/appcenter-sdk');

// Initialize with your project key
const client = new AppCenter('your-project-key-uuid');

// Get app information
const app = await client.apps.get();
console.log(app.name, app.token_cost);

// Get premium user
const user = await client.premiumUsers.getUser('user123');
console.log(user.renewtoken, user.nonrenewtoken, user.token);

// Decrement tokens manually
await client.premiumUsers.decrementTokens('user123', 5);

// Decrement tokens by app's token_cost
await client.premiumUsers.decrementTokensByAppCost('user123');

Features

• Apps Management - Retrieve app information by project key
• Premium Users - Manage user tokens and subscriptions
• Token Operations - Decrement tokens manually or by app cost
• Smart Caching - Automatic 1-hour cache for app data
• Error Handling - Comprehensive error classes for robust error handling
• TypeScript Support - Full TypeScript type definitions included

API Reference

Initialization

const AppCenter = require('@appmerge/appcenter-sdk');

const client = new AppCenter('your-project-key-uuid');

Parameters:

• projectKey (string, required) - Your app's project_key UUID

Apps Service

client.apps.get(skipCache)

Get app information by project key (with automatic caching).

Parameters:

• skipCache (boolean, optional) - Set to true to bypass cache and fetch fresh data. Default: false

Returns: Promise<App>

const app = await client.apps.get();

// Force fresh data
const app = await client.apps.get(true);

Throws:

• AppNotFoundError - If app with project key not found
• ApiError - If API operation fails

client.apps.clearCache()

Clear the cached app data for this project key.

Returns: boolean

client.apps.getCacheStats()

Get cache statistics for monitoring and debugging.

Returns: Object - { hits, misses, keys, ksize, vsize }

Premium Users Service

client.premiumUsers.getUser(userId)

Get premium user information by user_id.

Parameters:

• userId (string, required) - User ID

Returns: Promise<PremiumUser>

const user = await client.premiumUsers.getUser('user123');
console.log(user.renewtoken, user.nonrenewtoken, user.token);

Throws:

• UserNotFoundError - If user not found
• ApiError - If API operation fails

client.premiumUsers.decrementTokens(userId, amount)

Decrement tokens from user balance with a manual amount.

Parameters:

• userId (string, required) - User ID
• amount (number, required) - Amount of tokens to decrement

Returns: Promise<PremiumUser> - Updated user object

const user = await client.premiumUsers.decrementTokens('user123', 5);

Throws:

• UserNotFoundError - If user not found
• InsufficientTokensError - If user doesn't have enough tokens
• ApiError - If API operation fails

client.premiumUsers.decrementTokensByAppCost(userId)

Decrement tokens based on the app's token_cost value.

Parameters:

• userId (string, required) - User ID

Returns: Promise<PremiumUser> - Updated user object

const user = await client.premiumUsers.decrementTokensByAppCost('user123');

Throws:

• UserNotFoundError - If user not found
• InsufficientTokensError - If user doesn't have enough tokens
• InvalidTokenCostError - If app's token_cost is 0 or invalid
• ApiError - If API operation fails

Connection Test

client.testConnection()

Test the connection to AppCenter API.

Returns: Promise<boolean>

const isConnected = await client.testConnection();

Caching

The SDK includes automatic caching for app data:

• Cache Duration: 1 hour (3600 seconds)
• Auto Cleanup: Every 10 minutes

const app = await client.apps.get();       // First call - fetches from API
const app2 = await client.apps.get();      // Cached
const app3 = await client.apps.get(true);  // Force fresh from API
client.apps.clearCache();                  // Clear cache manually

Error Handling

const AppCenter = require('@appmerge/appcenter-sdk');

const client = new AppCenter('your-project-key-uuid');

try {
  await client.premiumUsers.decrementTokensByAppCost('user123');
} catch (error) {
  if (error instanceof AppCenter.AppNotFoundError) {
    // App not found - error.projectKey
  } else if (error instanceof AppCenter.UserNotFoundError) {
    // User not found - error.userId
  } else if (error instanceof AppCenter.InsufficientTokensError) {
    // Not enough tokens - error.required
  } else if (error instanceof AppCenter.InvalidTokenCostError) {
    // Invalid token cost - error.tokenCost
  } else if (error instanceof AppCenter.ApiError) {
    // API error - error.originalError
  }
}

Error Classes

| Error | Code | Properties | |---|---|---| | AppNotFoundError | APP_NOT_FOUND | projectKey | | UserNotFoundError | USER_NOT_FOUND | userId | | InsufficientTokensError | INSUFFICIENT_TOKENS | userId, required, available | | InvalidTokenCostError | INVALID_TOKEN_COST | tokenCost | | ApiError | API_ERROR | originalError |

TypeScript Support

import AppCenter, { App, PremiumUser } from '@appmerge/appcenter-sdk';

const client = new AppCenter('your-project-key-uuid');

const app: App = await client.apps.get();
const user: PremiumUser = await client.premiumUsers.getUser('user123');

Requirements

• Node.js >= 18.0.0 (uses built-in fetch)

License

ISC