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