# mrzerlif/nsgifts architecture

> Architecture diagram of the GitHub repository mrzerlif/nsgifts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrzerlif/nsgifts
- Repository: https://github.com/mrzerlif/nsgifts

## Overview

#### Purpose and public entry point
`nsgifts-api` is an unofficial asynchronous Python 3.10+ SDK for NS.Gifts API v2. Consumers primarily instantiate `NSGiftsClient`, usually as an async context manager; it exposes grouped account, catalog, order, and Steam operations. Public-package exports are rooted in `nsgifts_api/__init__.py`, with orchestration in `nsgifts_api/client.py`.

#### Client composition and lifecycle
`NSGiftsClient` owns configuration, authentication/session state, transport, and service-specific method groups. Protected API calls trigger lazy authentication unless callers invoke authentication explicitly. Context-manager lifecycle likely creates and closes the underlying async HTTP resources.
- `nsgifts_api/client.py`
- `nsgifts_api/config.py`
- `nsgifts_api/auth.py`

#### Configuration and security boundary
Configuration accepts the partner numeric user ID, NS.Gifts login/password, Base64 API secret, and configurable API base URL. Credentials and sensitive values are represented/masked safely. Each request is authenticated with the API secret, partner user ID, timestamp/replay protection, HMAC-SHA256 signature, and session token; session tokens last two hours. NS.Gifts controls credential issuance and IP allowlisting.
- `nsgifts_api/config.py`
- `nsgifts_api/auth.py`
- `.env.example`

#### Transport, signing, retries, and errors
The transport layer is the HTTP boundary to `https://api.ns.gifts`. It applies request construction/signing and response handling, while endpoint and HTTP method constants centralize API protocol details. Retries are deliberately operation-sensitive: read-only calls may retry transient network, rate-limit, and server failures, with fresh timestamps/signatures; order creation and payment are never automatically replayed after uncertain outcomes. HTTP/API conditions are translated into typed domain exceptions.
- `nsgifts_api/transport.py`
- `nsgifts_api/errors.py`
- `nsgifts_api/enums/endpoints.py`
- `nsgifts_api/enums/http_methods.py`

#### Typed API contract layer
Pydantic request/response models form the serialization and validation boundary between callers and the remote API. Request models cover authentication, orders, and Steam operations; response models represent account state, auth sessions, orders, stock catalog data, and Steam results. Enums encode protocol/API values and order states rather than distributing raw strings/integers through method implementations.
- `nsgifts_api/models/requests/auth.py`
- `nsgifts_api/models/requests/orders.py`
- `nsgifts_api/models/responses/stock.py`
- `nsgifts_api/enums/api.py`

#### Domain service façades
Method classes provide the user-facing domain API over a shared base abstraction and transport:
- Account balance retrieval: `nsgifts_api/methods/account.py`
- Dynamic `/stock` catalog retrieval: `nsgifts_api/methods/catalog.py`
- Unified order create/pay/status flow: `nsgifts_api/methods/orders.py`
- Steam exchange rates, app listing, and account checks: `nsgifts_api/methods/steam.py`
- Shared service behavior: `nsgifts_api/methods/base.py`

#### Core order control flow
Callers first fetch live stock, which supplies mutable service IDs, prices, availability, and dynamic field schemas. They create an order using a caller-provided or generated UUID4 `custom_id`, then pay exactly once. Payment can require caller-supplied TOTP; the SDK neither generates nor stores it. On payment outcome uncertainty, it raises an exception carrying the custom ID so callers reconcile via order lookup. Steam Gift fulfillment may remain `in_progress`, requiring application-managed polling until a terminal order status.
- `nsgifts_api/methods/catalog.py`
- `nsgifts_api/methods/orders.py`
- `nsgifts_api/models/responses/orders.py`

Main entry points: [`nsgifts_api/transport.py`](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/transport.py) (Async Transport), [`nsgifts_api/client.py`](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/client.py) (NSGiftsClient), [`nsgifts_api/methods/base.py`](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/base.py) (Service Base), [`nsgifts_api/methods/orders.py`](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/orders.py) (Orders Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SDK Core"]
  node_exports["Public Exports<br/>package API<br/>[__init__.py]"]
  node_client["NSGiftsClient<br/>client orchestrator<br/>[client.py]"]
  node_config["Configuration<br/>credentials config<br/>[config.py]"]
  node_auth["Authentication<br/>session manager<br/>[auth.py]"]
end

subgraph group_protocol["API Boundary"]
  node_models["Typed Contracts<br/>Pydantic models<br/>[orders.py]"]
  node_enums["Protocol Enums<br/>API constants<br/>[endpoints.py]"]
  node_transport["Async Transport<br/>HTTP boundary<br/>[transport.py]"]
  node_errors["Typed Errors<br/>domain exceptions<br/>[errors.py]"]
end

subgraph group_services["Domain Services"]
  node_services_base["Service Base<br/>shared service abstraction<br/>[base.py]"]
  node_account["Account Service<br/>domain façade<br/>[account.py]"]
  node_catalog["Catalog Service<br/>domain façade<br/>[catalog.py]"]
  node_orders["Orders Service<br/>domain façade<br/>[orders.py]"]
  node_steam["Steam Service<br/>domain façade<br/>[steam.py]"]
end

node_consumer(("SDK Consumer<br/>caller"))
node_ns_gifts{{"NS.Gifts API v2<br/>external API"}}
node_order_fulfillment["Order Fulfillment<br/>remote order state"]

node_consumer -->|"imports"| node_exports
node_exports -->|"exposes"| node_client
node_consumer -->|"async context manager"| node_client
node_client -->|"owns"| node_config
node_client -->|"owns session"| node_auth
node_client -->|"uses"| node_transport
node_client -->|"composes"| node_services_base
node_services_base -->|"shared base"| node_account
node_services_base -->|"shared base"| node_catalog
node_services_base -->|"shared base"| node_orders
node_services_base -->|"shared base"| node_steam
node_account -->|"API calls"| node_transport
node_catalog -->|"API calls"| node_transport
node_orders -->|"create, pay, lookup"| node_transport
node_steam -->|"API calls"| node_transport
node_catalog -->|"live stock informs order"| node_orders
node_orders -->|"creates and pays once"| node_order_fulfillment
node_consumer -.->|"polls until terminal"| node_order_fulfillment
node_auth -->|"token and request auth"| node_transport
node_config -->|"credentials and secret"| node_auth
node_transport -->|"serializes and validates"| node_models
node_transport -->|"endpoint and method constants"| node_enums
node_transport -->|"translates failures"| node_errors
node_transport -->|"signed HTTPS requests"| node_ns_gifts
node_ns_gifts -->|"processes fulfillment"| node_order_fulfillment

click node_exports "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/__init__.py"
click node_client "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/client.py"
click node_config "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/config.py"
click node_auth "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/auth.py"
click node_services_base "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/base.py"
click node_account "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/account.py"
click node_catalog "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/catalog.py"
click node_orders "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/orders.py"
click node_steam "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/steam.py"
click node_models "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/models/requests/orders.py"
click node_enums "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/enums/endpoints.py"
click node_transport "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/transport.py"
click node_errors "https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/errors.py"

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_exports,node_client,node_config,node_auth toneBlue
class node_models,node_enums,node_transport,node_errors toneAmber
class node_services_base,node_account,node_catalog,node_orders,node_steam toneMint
class node_consumer,node_ns_gifts,node_order_fulfillment toneNeutral
```

## Components

### SDK Core

- [Public Exports](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/__init__.py): package API · `nsgifts_api/__init__.py`
- [NSGiftsClient](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/client.py): client orchestrator · Owns configuration, session state, transport, and service façades. · `nsgifts_api/client.py`
- [Configuration](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/config.py): credentials config · Holds partner identity, credentials, API secret, and base URL. · `nsgifts_api/config.py`
- [Authentication](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/auth.py): session manager · Lazily authenticates protected calls and maintains two-hour tokens. · `nsgifts_api/auth.py`

### API Boundary

- [Typed Contracts](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/models/requests/orders.py): Pydantic models · Validates and serializes auth, order, Steam, stock, and account payloads. · `nsgifts_api/models/requests/orders.py`
- [Protocol Enums](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/enums/endpoints.py): API constants · Centralizes API values, endpoints, HTTP methods, and order states. · `nsgifts_api/enums/endpoints.py`
- [Async Transport](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/transport.py): HTTP boundary · Builds signed requests, applies operation-sensitive retries, and handles responses. · `nsgifts_api/transport.py`
- [Typed Errors](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/errors.py): domain exceptions · Represents translated HTTP/API failures and uncertain payment outcomes. · `nsgifts_api/errors.py`

### Domain Services

- [Service Base](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/base.py): shared service abstraction · `nsgifts_api/methods/base.py`
- [Account Service](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/account.py): domain façade · Retrieves account balance. · `nsgifts_api/methods/account.py`
- [Catalog Service](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/catalog.py): domain façade · Retrieves live stock, pricing, availability, and field schemas. · `nsgifts_api/methods/catalog.py`
- [Orders Service](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/orders.py): domain façade · Creates, pays, and reconciles orders without replaying uncertain payments. · `nsgifts_api/methods/orders.py`
- [Steam Service](https://github.com/mrzerlif/nsgifts/blob/main/nsgifts_api/methods/steam.py): domain façade · Provides rates, app listings, and account checks. · `nsgifts_api/methods/steam.py`

### Other components

- **SDK Consumer**: caller · Uses the async client and manages fulfillment polling.
- **NS.Gifts API v2**: external API · Controls credential issuance, IP allowlisting, and remote order fulfillment.
- **Order Fulfillment**: remote order state · Steam Gift orders can remain in_progress until terminal status.

## Connections

- SDK Consumer → Public Exports: imports
- Public Exports → NSGiftsClient: exposes
- SDK Consumer → NSGiftsClient: async context manager
- NSGiftsClient → Configuration: owns
- NSGiftsClient → Authentication: owns session
- NSGiftsClient → Async Transport: uses
- NSGiftsClient → Service Base: composes
- Service Base → Account Service: shared base
- Service Base → Catalog Service: shared base
- Service Base → Orders Service: shared base
- Service Base → Steam Service: shared base
- Account Service → Async Transport: API calls
- Catalog Service → Async Transport: API calls
- Orders Service → Async Transport: create, pay, lookup
- Steam Service → Async Transport: API calls
- Catalog Service → Orders Service: live stock informs order
- Orders Service → Order Fulfillment: creates and pays once
- SDK Consumer → Order Fulfillment: polls until terminal
- Authentication → Async Transport: token and request auth
- Configuration → Authentication: credentials and secret
- Async Transport → Typed Contracts: serializes and validates
- Async Transport → Protocol Enums: endpoint and method constants
- Async Transport → Typed Errors: translates failures
- Async Transport → NS.Gifts API v2: signed HTTPS requests
- NS.Gifts API v2 → Order Fulfillment: processes fulfillment