Core Concepts

Architecture

Acme SDK follows a client-resource pattern. You initialize a single client instance and use it to interact with different resource types through namespaced methods.

AcmeClient
├── .resources    → CRUD operations on resources
├── .webhooks     → Manage webhook subscriptions
├── .analytics    → Query usage and metrics
└── .config       → Runtime configuration

Request Lifecycle

Every SDK method follows the same lifecycle:

Validation — Input parameters are validated against the schema
Authentication — Your API key is attached to the request
Transport — The request is sent to the Acme API
Retry — Failed requests are retried with exponential backoff
Response — The response is parsed and returned as a typed object

Error Handling

The SDK throws typed errors that you can catch and handle:

import { AcmeClient, AcmeError, RateLimitError } from "@acme/sdk";

try {
  const result = await client.resources.create({ name: "Example" });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    await delay(error.retryAfter);
  } else if (error instanceof AcmeError) {
    // Handle API error
    console.error(error.code, error.message);
  }
}

Pagination

List endpoints return paginated results. Use the built-in pagination helpers:

// Automatic pagination — iterates through all pages
for await (const resource of client.resources.list()) {
  console.log(resource.id);
}

// Manual pagination — control page-by-page
const page = await client.resources.list({ limit: 10, cursor: "abc123" });
console.log(page.data); // Current page items
console.log(page.nextCursor); // Cursor for next page