Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (97 loc) · 6.79 KB

AGENTS.md

File metadata and controls

146 lines (97 loc) · 6.79 KB
Raw

Altus 4 SDK — Agents Overview

This document was generated by scanning the repository and summarises the codebase, architecture, public surface, implementation details, and practical notes for contributors and automated agents.

Goal of this file

  • Provide a concise, machine- and human-readable overview of the SDK so agents (or new contributors) can quickly understand responsibilities, extension points, and where to make safe changes.

Checklist (user request)

  • Scan the codebase and produce a comprehensive understanding.
  • Add AGENTS.md to the repository root with a clear summary and guidance.

High-level summary

The repository implements a small, modular TypeScript SDK for the Altus 4 service (AI-enhanced MySQL full-text search). It exposes a single top-level SDK class (Altus4SDK) that composes multiple service clients. Core areas:

  • client/ — Base HTTP client, configuration defaults and re-exports.
  • services/ — Service-specific classes (Auth, ApiKeys, Database, Analytics, Management).
  • types/ — Centralised TypeScript types and interfaces (auth, api keys, analytics, database, management, common).
  • utils/ — Validation, formatting and date helpers used by services and consumers.
  • src/index.ts — Main SDK entry point and convenience exports + altus4 default instance.
  • tests/ — Basic unit tests validating SDK instantiation and token helpers.

Public API / Entry points

  • Altus4SDK class (default export) — central SDK instance that exposes:

    • .auth — AuthService
    • .apiKeys — ApiKeysService
    • .database — DatabaseService
    • .analytics — AnalyticsService
    • .management — ManagementService
    • Helpers: login, register, logout, getCurrentUser, isAuthenticated, setToken, clearToken, setBaseURL.

  • createAltus4SDK(config?) — factory helper.

  • altus4 — a default SDK instance (constructed with no config).

Important implementation notes

  • HTTP transport uses axios and a single BaseClient wrapper that configures interceptors for adding an Authorization header and basic 401 handling.

  • Token storage is currently implemented as in-memory fields on AuthService and also via BaseClient methods that read/write localStorage when window is available. This creates two storage places:

    • AuthService.token/tokenExpiry (in-memory) used to determine authentication state and refresh tokens.
    • BaseClient.getToken/setToken/clearToken use localStorage when running in a browser environment. (Note: server-side usage will not persist tokens.)

  • Services call this.request(...) which expects the API to respond with an ApiResponse<T> shape (defined under types/common). Error handling returns the API response body when present, otherwise a network-error shaped object.

  • Many services provide a setBaseURL override that delegates to the BaseClient to update axios defaults — allowing runtime reconfiguration.

File-by-file (important files)

  • package.json — scripts for build/test/lint and dependencies: axios, formlink in runtime; typescript, jest, eslint, etc. in dev.
  • tsconfig.json — strict TypeScript configuration, output to dist with declaration files.
  • src/client/base-client.ts — core HTTP client and interceptors.
  • src/client/config.ts — ClientConfig and DEFAULT_CONFIG.
  • src/services/*.ts — small, focused API wrappers that map to REST endpoints.
  • src/utils/validators.ts — many input validations used by services or callers.
  • src/index.ts — re-exports and Altus4SDK implementation.

Behavioural & runtime assumptions

  • The server API uses a consistent ApiResponse<T> envelope. Services call endpoints such as /auth/login, /keys, /databases, /analytics/*, and /health.
  • The code assumes browser-like runtime for token persistence (via localStorage) but will still operate server-side with in-memory tokens.
  • Error handling is intentionally tolerant: network or non-JSON responses are wrapped into a standardized error object.

How to build, test and lint (developer / agent actions)

These commands come from package.json:

  1. Install dependencies:
npm install
  1. Build (clean + TypeScript compile):
npm run build
  1. Typecheck only:
npm run typecheck
  1. Tests (Jest):
npm test
  1. Lint:
npm run lint

Extension points and recommended areas for automation

  • Add integration tests that stub HTTP responses (e.g. msw or axios-mock-adapter) to validate service methods' behavior.
  • Consider consolidating token persistence strategy (pick localStorage + optional adapter for Node.js) to avoid the in-memory vs storage mismatch.
  • Add small README sections in services/ describing endpoint contracts (request/response shapes). Typedoc is configured (docs script) and can be used to generate API docs.

Edge cases & gotchas

  • BaseClient.getToken() returns null on Node.js — callers relying on persistent tokens server-side will find Authorization not included unless setToken is called programmatically.
  • AuthService.isAuthenticated() is based on the in-memory token and expiry fields. If a page is reloaded, the in-memory token is lost unless BaseClient.getToken() and AuthService.setToken() are reconciled.
  • Validation helpers are permissive but should be reused by callers before sending sensitive operations.

Quick examples

  • Instantiate with custom base URL:
import { Altus4SDK } from './src';
const sdk = new Altus4SDK({ baseURL: 'https://api.altus4.com/api/v1' });
await sdk.login('me@example.com', 'password');

Assumptions made while scanning

  • I inferred runtime behaviour for token persistence (browser localStorage) from BaseClient and AuthService implementations.
  • I assumed ApiResponse<T> envelope is used consistently by the server based on usage in BaseClient.request and service return types.

Next recommended steps (low risk)

  1. Add a central token adapter that reads from localStorage in the browser and from an injectable storage for server-side usage.
  2. Add integration tests for AuthService refresh flow and for ApiKeysService create/regenerate endpoints.
  3. Expand README with example of using altus4 default instance and recommended auth flow.

Requirements coverage

  • "Scan through this code, get a full and comprehensive understanding of this codebase" — Done (files inspected: package.json, README.md, tsconfig.json, src/* key files, tests/).
  • "Add an AGENTS.md file to the root of the directory" — Done (this file).

Change log

  • Added: AGENTS.md — high level overview and guidance for agents and contributors.

If you want, I can now:

  • run the test suite locally to verify everything still passes, or
  • open a follow-up patch to convert token persistence to a configurable adapter.