> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lomadee.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# How the SDK works

> Understand the Lomadee client, resource clients, and backend microservices

The Lomadee SDK is a thin, typed facade over Lomadee partner microservices. Understanding its layout helps you choose the right resource client, import the right types, and place credentials safely in your architecture—without re-implementing HTTP plumbing.

## One entry class, many resources

Import a single class from the package root:

```typescript theme={null}
import { Lomadee } from '@thelomadee/sdk';
```

Construct it once per process (or per request scope in serverless, depending on your framework) and access domain operations through **resource properties**:

```typescript theme={null}
import { ContentStatus } from '@thelomadee/sdk/domains';

const sdk = new Lomadee({ authKey: process.env.LOMADEE_AUTH_KEY! });

await sdk.transactions.list({ page: 1 });
await sdk.commissions.get('commission-id');
await sdk.affiliates.get('affiliate-id');
await sdk.contents.list({ status: ContentStatus.ACTIVE });
await sdk.terms.latest();
await sdk.terms.acceptances.list('user-id');
```

Each property is a small class focused on one domain. Method names mirror REST operations (`list`, `get`, `create`, `update`, `delete` where supported). Detailed method signatures live in the per-domain reference pages: [Transactions](/docs/sdk/reference/transactions), [Commissions](/docs/sdk/reference/commissions), [Affiliates](/docs/sdk/reference/affiliates), [Contents](/docs/sdk/reference/contents), and [Terms](/docs/sdk/reference/terms).

## Shared HTTP client

When you construct `Lomadee`, the SDK:

1. Resolves **`environment`** to `'production'` unless you pass `'staging'`
2. Creates one **Axios instance** with your `authKey` on the **`x-auth-key`** header
3. Applies a fixed **10 second request timeout** to that instance
4. Wires **resource clients** to the appropriate Lomadee services for the selected environment

All resource clients reuse the same authenticated Axios instance. You do not pass headers per call or manage tokens manually.

```
┌─────────────────────────────────────────┐
│              Lomadee                    │
│  authKey ──► x-auth-key (all requests)  │
│  timeout: 10s                           │
├─────────────┬─────────────┬─────────────┤
│ transactions│ commissions │ affiliates  │
│ contents    │ terms (+ acceptances)     │
└─────────────┴─────────────┴─────────────┘
         │ shared Axios instance
         ▼
   Lomadee partner microservices
```

There is **no** public API to:

* Override base URLs or per-service hosts
* Attach Axios interceptors through the SDK
* Change the timeout on the shared client
* Enable automatic retries inside the SDK

If you need those behaviors, implement them **outside** the SDK in your application layer ([Error handling](/docs/sdk/guides/error-handling)).

## Authentication model

Partner integrations authenticate with the **`authKey`** issued during onboarding. The SDK sends it on every request as **`x-auth-key`**.

This is separate from the [Affiliate API](/api-reference/introduction), which is a public REST product for the affiliate network and uses **`x-api-key`**. The two credentials are not interchangeable, and the SDK is not a wrapper around the Affiliate API OpenAPI surface.

<Warning>
  Because authentication is fixed at construction time, treat `new Lomadee({ authKey })` as holding a live credential. Instantiate it only in trusted server contexts.
</Warning>

## TypeScript modules and domain types

The package is **ESM-only**. Use `import` syntax and ensure your bundler or runtime resolves `"type": "module"` (or TypeScript `moduleResolution: "NodeNext"`).

Exports are split intentionally:

| Import path               | Contains                                                                |
| ------------------------- | ----------------------------------------------------------------------- |
| `@thelomadee/sdk`         | `Lomadee` class, `SdkParams`, `Environment`, `SdkResponse`              |
| `@thelomadee/sdk/domains` | Data types and enums (orders, commissions, affiliates, contents, terms) |

Advanced resource **implementation** classes (uncommon—prefer `new Lomadee(...)` on the root import):

| Root property  | Advanced import                       | Class                    |
| -------------- | ------------------------------------- | ------------------------ |
| `transactions` | `@thelomadee/sdk/domains/orders`      | `Transaction`            |
| `commissions`  | `@thelomadee/sdk/domains/commissions` | `Commission`             |
| `affiliates`   | `@thelomadee/sdk/domains/affiliates`  | `Affiliate`              |
| `contents`     | `@thelomadee/sdk/domains/contents`    | `Content`                |
| `terms`        | `@thelomadee/sdk/domains/terms`       | `Term`, `TermAcceptance` |

Import domain types when typing variables, validators, or mappers in your code:

```typescript theme={null}
import type { TermData, CreateOrderBody } from '@thelomadee/sdk/domains';
```

You do not need to import domain types for the SDK to function—only when your application code references those shapes explicitly.

## Resource overview

The table below describes **what each client is for**, not internal routing details. Use the linked reference pages for method-level documentation.

| Client              | Role                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `transactions`      | Order lifecycle—list, retrieve, create, update, and delete transactions                         |
| `commissions`       | Commission rule management (when provisioned for your integration)                              |
| `affiliates`        | Affiliate listing and signup/update flows (signup may use a dedicated auth path inside the SDK) |
| `contents`          | Read-only access to content center items                                                        |
| `terms`             | Latest terms document metadata via `latest()`                                                   |
| `terms.acceptances` | Record and query term acceptance for a user                                                     |

Discover resources progressively: start with [Quickstart](/docs/sdk/quickstart) and `terms.latest()`, then open the reference page for the domain you integrate next.

## Errors and responses

Failed HTTP calls reject with **Axios errors** unchanged. The SDK does not normalize status codes or response bodies into a partner-facing error catalog. Return typing varies by resource: some methods use `SdkResponse<T>` or concrete domain types; **`transactions` list/get/create/update return `Promise<unknown>`** in the current SDK—see the [Transactions reference](/docs/sdk/reference/transactions).

Plan application-level handling early ([Error handling](/docs/sdk/guides/error-handling)) rather than expecting the SDK to classify failures for you.

## Mental model vs. the Affiliate API

|               | Lomadee SDK                       | Affiliate API                                    |
| ------------- | --------------------------------- | ------------------------------------------------ |
| Audience      | Partner integrations (onboarding) | Affiliate network developers                     |
| Credential    | `authKey` → `x-auth-key`          | API key → `x-api-key`                            |
| Client        | `@thelomadee/sdk` npm package     | Direct HTTPS to public REST base URL             |
| Documentation | SDK tab (this section)            | [Affiliate API](/api-reference/introduction) tab |

Choose one product per integration path. Mixing credentials or documentation across the two leads to auth failures and incorrect endpoint assumptions.

## Continue learning

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/sdk/quickstart">
    Install the package and verify connectivity
  </Card>

  <Card title="Environments and secrets" icon="key" href="/docs/sdk/guides/environments-and-secrets">
    Configure staging, production, and secret storage
  </Card>

  <Card title="Transactions" icon="receipt" href="/docs/sdk/reference/transactions">
    Order operations reference
  </Card>

  <Card title="Terms" icon="file-contract" href="/docs/sdk/reference/terms">
    Terms and acceptances reference
  </Card>
</CardGroup>