mrzerlif/nsgifts

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