Installation

Installation

Get started with the Acme SDK in your project.

Requirements

• Node.js 18.0 or later
• npm, yarn, or pnpm

Quick Start

Install the SDK using your preferred package manager:

# npm
npm install @acme/sdk@1.2.0

# yarn
yarn add @acme/sdk@1.2.0

# pnpm
pnpm add @acme/sdk@1.2.0

Verify Installation

Create a simple test to verify the SDK is working:

import { Acme } from '@acme/sdk';

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
});

// Test the connection
const status = await client.ping();
console.log('Acme SDK connected:', status);

Version Compatibility

Upgrading? See the migration guide for breaking changes between versions.

Next Steps

Once installed, head to Configuration to set up your API credentials.

Configuration

Configuration

Learn how to configure the Acme SDK for different environments and use cases.

API Credentials

The SDK requires an API key for authentication. Get your key from the Acme Dashboard.

import { Acme } from '@acme/sdk';

const client = new Acme({
  apiKey: 'your-api-key',
  // Optional: specify API version (defaults to v3 in SDK 1.2.0)
  apiVersion: 'v3',
});

Environment Variables

We recommend using environment variables for sensitive configuration:

# .env
ACME_API_KEY=sk_live_xxxxx
ACME_API_VERSION=v3
ACME_TIMEOUT=30000

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  apiVersion: process.env.ACME_API_VERSION,
  timeout: parseInt(process.env.ACME_TIMEOUT),
});

Configuration Options

Environment-Specific Config

Development

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  baseUrl: 'https://sandbox.acme.dev',
  debug: true,
});

Production

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  retries: 5,
  timeout: 60000,
});

TypeScript Support

The SDK includes full TypeScript definitions:

import { Acme, AcmeConfig, User } from '@acme/sdk';

const config: AcmeConfig = {
  apiKey: process.env.ACME_API_KEY!,
  apiVersion: 'v3',
};

const client = new Acme(config);
const user: User = await client.users.get('user_123');

Next Steps

See API Reference for available methods and types.

API Reference

API Reference

Complete reference for all Acme SDK methods and types.

Users

Manage user accounts and profiles.

users.get(id)

Retrieve a user by ID.

const user = await client.users.get('user_123');
// Returns: { id, email, name, createdAt, ... }

users.list(options?)

List all users with optional filtering.

const users = await client.users.list({
  limit: 20,
  offset: 0,
  status: 'active',
});

users.create(data)

Create a new user.

const user = await client.users.create({
  email: 'jane@example.com',
  name: 'Jane Doe',
  role: 'member',
});

users.update(id, data)

Update an existing user.

const user = await client.users.update('user_123', {
  name: 'Jane Smith',
});

users.delete(id)

Delete a user.

await client.users.delete('user_123');

Widgets

New in v1.2.0 — Build custom UI components with the Widgets API.

widgets.create(config)

Create a new widget instance.

const widget = await client.widgets.create({
  type: 'payment-form',
  container: '#widget-container',
  theme: 'dark',
});

widgets.render()

Render the widget to the DOM.

await widget.render();

widgets.on(event, handler)

Subscribe to widget events.

widget.on('success', (data) => {
  console.log('Payment successful:', data);
});

widget.on('error', (error) => {
  console.error('Widget error:', error);
});

Events

Real-time event subscriptions.

events.subscribe(channel)

Subscribe to a channel for real-time updates.

const subscription = client.events.subscribe('user_123');

subscription.on('user.updated', (event) => {
  console.log('User updated:', event.data);
});

events.unsubscribe(channel)

Unsubscribe from a channel.

client.events.unsubscribe('user_123');

Error Handling

The SDK throws typed errors for different scenarios:

import { AcmeError, RateLimitError, AuthError } from '@acme/sdk';

try {
  await client.users.get('user_123');
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof AuthError) {
    console.log('Invalid API key');
  } else if (error instanceof AcmeError) {
    console.log('API error:', error.message);
  }
}

Next Steps

Learn about Customization for advanced usage patterns.

Advanced Usage

Advanced Usage

Learn advanced patterns for getting the most out of the Acme SDK.

Middleware

Add custom middleware to intercept requests and responses:

import { Acme } from '@acme/sdk';

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  middleware: [
    // Logging middleware
    async (request, next) => {
      console.log(`[Acme] ${request.method} ${request.url}`);
      const start = Date.now();
      const response = await next(request);
      console.log(`[Acme] Completed in ${Date.now() - start}ms`);
      return response;
    },
    // Auth refresh middleware
    async (request, next) => {
      try {
        return await next(request);
      } catch (error) {
        if (error.code === 'TOKEN_EXPIRED') {
          await refreshToken();
          return next(request);
        }
        throw error;
      }
    },
  ],
});

Batching Requests

Batch multiple operations for better performance:

const results = await client.batch([
  { method: 'users.get', params: { id: 'user_1' } },
  { method: 'users.get', params: { id: 'user_2' } },
  { method: 'users.get', params: { id: 'user_3' } },
]);

// results[0] = user_1 data
// results[1] = user_2 data
// results[2] = user_3 data

Pagination

Handle paginated responses with built-in iterators:

// Manual pagination
let page = await client.users.list({ limit: 100 });

while (page.hasMore) {
  for (const user of page.data) {
    console.log(user.name);
  }
  page = await page.next();
}

// Async iterator (recommended)
for await (const user of client.users.listAll()) {
  console.log(user.name);
}

Custom HTTP Client

Use your own HTTP client for advanced networking needs:

import { Acme } from '@acme/sdk';
import axios from 'axios';

const httpClient = {
  async request(config) {
    const response = await axios({
      url: config.url,
      method: config.method,
      headers: config.headers,
      data: config.body,
    });
    return {
      status: response.status,
      headers: response.headers,
      body: response.data,
    };
  },
};

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  httpClient,
});

Webhooks

Verify and handle incoming webhooks:

import { Acme, WebhookError } from '@acme/sdk';
import express from 'express';

const app = express();

app.post('/webhooks/acme', express.raw({ type: '*/*' }), (req, res) => {
  const signature = req.headers['x-acme-signature'];

  try {
    const event = Acme.webhooks.verify(
      req.body,
      signature,
      process.env.ACME_WEBHOOK_SECRET
    );

    switch (event.type) {
      case 'user.created':
        handleUserCreated(event.data);
        break;
      case 'user.deleted':
        handleUserDeleted(event.data);
        break;
    }

    res.status(200).send('OK');
  } catch (error) {
    if (error instanceof WebhookError) {
      console.error('Invalid webhook signature');
      res.status(400).send('Invalid signature');
    }
  }
});

Caching

Implement response caching for improved performance:

import { Acme } from '@acme/sdk';

const cache = new Map();

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  cache: {
    get: (key) => cache.get(key),
    set: (key, value, ttl) => {
      cache.set(key, value);
      setTimeout(() => cache.delete(key), ttl);
    },
  },
  cacheTTL: 60000, // 1 minute
});

Migration from v1.1.x

Breaking Changes in v1.2.0

Async/Await

All methods now return Promises instead of using callbacks:

// v1.1.x (deprecated)
client.users.get('user_123', (err, user) => {
  if (err) throw err;
  console.log(user);
});

// v1.2.x
const user = await client.users.get('user_123');

Import Changes

// v1.1.x
const Acme = require('@acme/sdk');

// v1.2.x
import { Acme } from '@acme/sdk';
// or
const { Acme } = require('@acme/sdk');

Deployment

Deployment

Best practices for deploying applications that use the Acme SDK.

Environment Setup

Production Checklist

Before deploying to production:

• Use production API keys (not sandbox)
• Set appropriate timeouts and retry limits
• Configure error monitoring
• Enable request logging
• Set up webhook endpoints

Environment Variables

Required environment variables:

# Required
ACME_API_KEY=sk_live_xxxxx

# Optional
ACME_API_VERSION=v3
ACME_TIMEOUT=30000
ACME_RETRIES=3
ACME_WEBHOOK_SECRET=whsec_xxxxx

Platform Guides

Node.js

// server.js
import { Acme } from '@acme/sdk';
import express from 'express';

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  retries: 5,
  timeout: 60000,
});

const app = express();

app.get('/api/users/:id', async (req, res) => {
  try {
    const user = await client.users.get(req.params.id);
    res.json(user);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Serverless (AWS Lambda)

// handler.js
import { Acme } from '@acme/sdk';

// Initialize outside handler for connection reuse
const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
});

export const handler = async (event) => {
  const user = await client.users.get(event.userId);
  return {
    statusCode: 200,
    body: JSON.stringify(user),
  };
};

Edge Functions (Cloudflare Workers)

// worker.js
import { Acme } from '@acme/sdk/edge';

export default {
  async fetch(request, env) {
    const client = new Acme({
      apiKey: env.ACME_API_KEY,
    });

    const url = new URL(request.url);
    const userId = url.searchParams.get('id');
    const user = await client.users.get(userId);

    return new Response(JSON.stringify(user), {
      headers: { 'Content-Type': 'application/json' },
    });
  },
};

Monitoring

Health Checks

Implement health checks to monitor SDK connectivity:

app.get('/health', async (req, res) => {
  try {
    await client.ping();
    res.json({ status: 'healthy', sdk: 'connected' });
  } catch (error) {
    res.status(503).json({ status: 'unhealthy', error: error.message });
  }
});

Error Tracking

Integrate with error tracking services:

import * as Sentry from '@sentry/node';
import { Acme, AcmeError } from '@acme/sdk';

const client = new Acme({
  apiKey: process.env.ACME_API_KEY,
  onError: (error) => {
    if (error instanceof AcmeError) {
      Sentry.captureException(error, {
        tags: { sdk: 'acme', version: '1.2.0' },
        extra: { requestId: error.requestId },
      });
    }
  },
});

Rate Limiting

The Acme API has rate limits. Handle them gracefully:

import { Acme, RateLimitError } from '@acme/sdk';

try {
  await client.users.list();
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
    await sleep(error.retryAfter * 1000);
    // Retry request
  }
}

Security

API Key Rotation

Rotate API keys periodically:

1. Generate a new key in the Dashboard
2. Update your environment variables
3. Deploy the update
4. Revoke the old key

Webhook Security

Always verify webhook signatures:

const isValid = Acme.webhooks.verify(
  payload,
  signature,
  process.env.ACME_WEBHOOK_SECRET
);

if (!isValid) {
  throw new Error('Invalid webhook signature');
}

Support

• Documentation: You're here!
• API Status: status.acme.dev
• Support: support@acme.dev
• Enterprise: enterprise@acme.dev

Print Version