# alliance-gravity/xandr-sdk architecture

> Architecture diagram of the GitHub repository alliance-gravity/xandr-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alliance-gravity/xandr-sdk
- Repository: https://github.com/alliance-gravity/xandr-sdk

## Overview

Xandr SDK is a TypeScript client for Xandr APIs. A consumer creates XandrClient with credentials, then uses its resource-specific clients; those clients issue operations through the shared request/authentication layer and receive typed results. The package documents token refresh and HTTP 429 handling, and includes a batch-segment upload capability alongside campaign, audience, reporting, and reference-data APIs. Several resource clients are represented from the tree and README rather than inspected source, so their individual operations and internal links are not inferred.

Main entry points: [`src/index.ts`](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/index.ts) (Xandr client), [`src/utils.ts`](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/utils.ts) (Auth and requests), [`src/advertiser/index.ts`](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/advertiser/index.ts) (Advertisers), [`src/insertion-order/index.ts`](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/insertion-order/index.ts) (Insertion orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Client and transport"]
  node_client["Xandr client<br/>[index.ts]"]
  node_transport["Auth and requests<br/>[utils.ts]"]
  node_errors["API errors<br/>[errors.ts]"]
  node_xandr_types["Shared API types<br/>[xandr-types.ts]"]
end

subgraph group_campaign["Campaign resources"]
  node_advertiser["Advertisers<br/>[index.ts]"]
  node_insertion_order["Insertion orders<br/>[index.ts]"]
  node_line_item["Line items<br/>[index.ts]"]
  node_placement["Placements<br/>[index.ts]"]
  node_publisher["Publishers<br/>[index.ts]"]
end

subgraph group_audience["Audience and inventory"]
  node_segment["Segments<br/>[index.ts]"]
  node_apd["Audience targeting<br/>[index.ts]"]
  node_bss["Batch segment upload<br/>[index.ts]"]
  node_inventory_list["Inventory lists<br/>[index.ts]"]
  node_domain_list["Domain lists<br/>[index.ts]"]
  node_custom_model["Custom models<br/>[index.ts]"]
  node_billing_category["Segment billing<br/>[index.ts]"]
end

subgraph group_data["Reporting and reference data"]
  node_report["Reports<br/>[index.ts]"]
  node_geography["Geographic data<br/>[index.ts]"]
  node_dma["DMA data<br/>[index.ts]"]
  node_region["Region data<br/>[index.ts]"]
  node_currency["Currency data<br/>[index.ts]"]
  node_site["Sites<br/>[index.ts]"]
end

node_consumer(("SDK consumer"))
node_xandr_api{{"Xandr APIs"}}

node_consumer -->|"configures"| node_client
node_client -->|"authenticates and requests"| node_transport
node_client -->|"exposes"| node_advertiser
node_client -->|"exposes"| node_insertion_order
node_client -->|"exposes"| node_line_item
node_client -->|"exposes"| node_placement
node_client -->|"exposes"| node_publisher
node_client -->|"exposes"| node_segment
node_client -->|"exposes"| node_apd
node_client -->|"exposes"| node_bss
node_client -->|"exposes"| node_inventory_list
node_client -->|"exposes"| node_domain_list
node_client -->|"exposes"| node_custom_model
node_client -->|"exposes"| node_billing_category
node_client -->|"exposes"| node_report
node_client -->|"exposes"| node_geography
node_client -->|"exposes"| node_dma
node_client -->|"exposes"| node_region
node_client -->|"exposes"| node_currency
node_client -->|"exposes"| node_site
node_advertiser -->|"executes requests"| node_client
node_insertion_order -->|"executes requests"| node_client
node_line_item -->|"executes requests"| node_client
node_placement -->|"executes requests"| node_client
node_publisher -->|"executes requests"| node_client
node_segment -->|"executes requests"| node_client
node_apd -->|"executes requests"| node_client
node_bss -->|"requests and uploads"| node_client
node_inventory_list -->|"executes requests"| node_client
node_domain_list -->|"executes requests"| node_client
node_custom_model -->|"executes requests"| node_client
node_billing_category -->|"executes requests"| node_client
node_report -->|"executes requests"| node_client
node_geography -->|"executes requests"| node_client
node_dma -->|"executes requests"| node_client
node_region -->|"executes requests"| node_client
node_currency -->|"executes requests"| node_client
node_site -->|"executes requests"| node_client
node_transport -->|"sends API requests"| node_xandr_api

click node_client "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/index.ts"
click node_transport "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/utils.ts"
click node_errors "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/errors.ts"
click node_xandr_types "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/xandr-types.ts"
click node_advertiser "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/advertiser/index.ts"
click node_insertion_order "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/insertion-order/index.ts"
click node_line_item "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/line-item/index.ts"
click node_placement "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/placement/index.ts"
click node_publisher "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/publisher/index.ts"
click node_segment "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/segment/index.ts"
click node_apd "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/apd/index.ts"
click node_bss "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/bss/index.ts"
click node_inventory_list "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/inventory-list/index.ts"
click node_domain_list "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/domain-list/index.ts"
click node_custom_model "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/custom-model/index.ts"
click node_billing_category "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/segment-billing-category/index.ts"
click node_report "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/report/index.ts"
click node_geography "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/city/index.ts"
click node_dma "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/dma/index.ts"
click node_region "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/region/index.ts"
click node_currency "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/currency/index.ts"
click node_site "https://github.com/alliance-gravity/xandr-sdk/blob/master/src/site/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_transport,node_errors,node_xandr_types toneBlue
class node_advertiser,node_insertion_order,node_line_item,node_placement,node_publisher toneAmber
class node_segment,node_apd,node_bss,node_inventory_list,node_domain_list,node_custom_model,node_billing_category,node_xandr_api toneMint
class node_report,node_geography,node_dma,node_region,node_currency,node_site toneRose
class node_consumer toneIndigo
```

## Components

### Client and transport

- [Xandr client](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/index.ts): `src/index.ts`
- [Auth and requests](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/utils.ts): `src/utils.ts`
- [API errors](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/errors.ts): `src/errors.ts`
- [Shared API types](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/xandr-types.ts): `src/xandr-types.ts`

### Campaign resources

- [Advertisers](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/advertiser/index.ts): `src/advertiser/index.ts`
- [Insertion orders](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/insertion-order/index.ts): `src/insertion-order/index.ts`
- [Line items](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/line-item/index.ts): `src/line-item/index.ts`
- [Placements](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/placement/index.ts): `src/placement/index.ts`
- [Publishers](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/publisher/index.ts): `src/publisher/index.ts`

### Audience and inventory

- [Segments](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/segment/index.ts): `src/segment/index.ts`
- [Audience targeting](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/apd/index.ts): `src/apd/index.ts`
- [Batch segment upload](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/bss/index.ts): `src/bss/index.ts`
- [Inventory lists](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/inventory-list/index.ts): `src/inventory-list/index.ts`
- [Domain lists](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/domain-list/index.ts): `src/domain-list/index.ts`
- [Custom models](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/custom-model/index.ts): `src/custom-model/index.ts`
- [Segment billing](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/segment-billing-category/index.ts): `src/segment-billing-category/index.ts`

### Reporting and reference data

- [Reports](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/report/index.ts): `src/report/index.ts`
- [Geographic data](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/city/index.ts): `src/city/index.ts`
- [DMA data](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/dma/index.ts): `src/dma/index.ts`
- [Region data](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/region/index.ts): `src/region/index.ts`
- [Currency data](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/currency/index.ts): `src/currency/index.ts`
- [Sites](https://github.com/alliance-gravity/xandr-sdk/blob/master/src/site/index.ts): `src/site/index.ts`

### Other components

- **SDK consumer**
- **Xandr APIs**

## Connections

- SDK consumer → Xandr client: configures (evidence: `src/index.ts`)
- Xandr client → Auth and requests: authenticates and requests (evidence: `src/index.ts`)
- Xandr client → Advertisers: exposes (evidence: `src/index.ts`)
- Xandr client → Insertion orders: exposes (evidence: `src/index.ts`)
- Xandr client → Line items: exposes (evidence: `src/index.ts`)
- Xandr client → Placements: exposes (evidence: `src/index.ts`)
- Xandr client → Publishers: exposes (evidence: `src/index.ts`)
- Xandr client → Segments: exposes (evidence: `src/index.ts`)
- Xandr client → Audience targeting: exposes (evidence: `src/index.ts`)
- Xandr client → Batch segment upload: exposes (evidence: `src/index.ts`)
- Xandr client → Inventory lists: exposes (evidence: `src/index.ts`)
- Xandr client → Domain lists: exposes (evidence: `src/index.ts`)
- Xandr client → Custom models: exposes (evidence: `src/index.ts`)
- Xandr client → Segment billing: exposes (evidence: `src/index.ts`)
- Xandr client → Reports: exposes (evidence: `src/index.ts`)
- Xandr client → Geographic data: exposes (evidence: `src/index.ts`)
- Xandr client → DMA data: exposes (evidence: `src/index.ts`)
- Xandr client → Region data: exposes (evidence: `src/index.ts`)
- Xandr client → Currency data: exposes (evidence: `src/index.ts`)
- Xandr client → Sites: exposes (evidence: `src/index.ts`)
- Advertisers → Xandr client: executes requests (evidence: `src/advertiser/index.ts`)
- Insertion orders → Xandr client: executes requests (evidence: `src/insertion-order/index.ts`)
- Line items → Xandr client: executes requests (evidence: `src/line-item/index.ts`)
- Placements → Xandr client: executes requests (evidence: `src/placement/index.ts`)
- Publishers → Xandr client: executes requests (evidence: `src/publisher/index.ts`)
- Segments → Xandr client: executes requests (evidence: `src/segment/index.ts`)
- Audience targeting → Xandr client: executes requests (evidence: `src/apd/index.ts`)
- Batch segment upload → Xandr client: requests and uploads (evidence: `src/bss/index.ts`)
- Inventory lists → Xandr client: executes requests (evidence: `src/inventory-list/index.ts`)
- Domain lists → Xandr client: executes requests (evidence: `src/domain-list/index.ts`)
- Custom models → Xandr client: executes requests (evidence: `src/custom-model/index.ts`)
- Segment billing → Xandr client: executes requests (evidence: `src/segment-billing-category/index.ts`)
- Reports → Xandr client: executes requests (evidence: `src/report/index.ts`)
- Geographic data → Xandr client: executes requests (evidence: `src/city/index.ts`)
- DMA data → Xandr client: executes requests (evidence: `src/dma/index.ts`)
- Region data → Xandr client: executes requests (evidence: `src/region/index.ts`)
- Currency data → Xandr client: executes requests (evidence: `src/currency/index.ts`)
- Sites → Xandr client: executes requests (evidence: `src/site/index.ts`)
- Auth and requests → Xandr APIs: sends API requests
