AlexandrAI AGENTS.md
agents-md

nk304 API SDK Agent Guide

Project-specific AGENTS.md guidance for the nk304 api-sdk package, Axios factory, request ids, origin headers, CSRF handling, and unauthorized retry behavior.

AGENTS.md

Guidance for coding agents working on nk304 packages/api-sdk. This package provides the shared Axios client factory consumed by application surfaces.

Project Overview

packages/api-sdk exports createApiClient(), a small but security-sensitive client factory. It creates an Axios instance, injects request ids, injects the origin-domain header, optionally reads access and CSRF tokens from caller-provided callbacks, attaches CSRF only on mutating methods, and performs a single configurable unauthorized retry through onUnauthorized.

Because this package sits below app code, keep it generic. It should not know about web storage, mobile secure storage, React Query, route names, or concrete deployment origins.

Project Map

  • src/create-api-client.ts contains the public factory, configuration interface, request id generation, request interceptor, and response retry logic.
  • src/create-api-client.test.mts covers the factory behavior with the Node test runner.
  • package.json exposes ESM, CommonJS, and type declaration outputs from dist/.
  • tsup.config.ts owns the build configuration.

Setup Commands

bashpnpm --filter @nk304/api-sdk run build
pnpm --filter @nk304/api-sdk run test

If a consumer breaks, confirm the actual import path with rg "@nk304/api-sdk" from the monorepo root before changing the package surface.

Change Rules For Agents

  • Keep createApiClient() framework-neutral. Pass platform decisions through callbacks.
  • Do not persist tokens in this package. Callers own storage and refresh decisions.
  • Keep mutating-method CSRF behavior explicit and covered by tests.
  • Preserve the one-retry unauthorized guard. Avoid retry loops.
  • Keep request id creation overrideable for tests and deterministic consumers.
  • Keep header normalization compatible with Axios header objects and plain header inputs.
  • Treat exported type names as public within the monorepo; coordinate changes with web and mobile consumers.

Verification

Run the package test after every behavior change:

bashpnpm --filter @nk304/api-sdk run test
pnpm --filter @nk304/api-sdk run build

When changing request or response behavior, also run the closest web or mobile tests that exercise auth, CSRF, protected downloads, or transport crypto.

Security Notes

Never include real tokens, CSRF values, origin domains, or authorization header values in tests. Use explicit placeholders or synthetic strings. Do not add logging inside interceptors unless it is redacted and explicitly requested.

PR Checklist

  • Public config and return types remain stable or all consumers are updated.
  • Request id, origin-domain, CSRF, and unauthorized retry behavior are covered.
  • The package stays storage-agnostic and UI-agnostic.
  • Tests do not rely on private service origins or real credentials.