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:

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:

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, Commissions, Affiliates, Contents, and 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).

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, 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.

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

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:

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 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.

Plan application-level handling early (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 tab

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

Continue learning

Quickstart

Install the package and verify connectivity

Environments and secrets

Configure staging, production, and secret storage

Transactions

Order operations reference

Terms

Terms and acceptances reference