@igniter-js/plugin-better-auth/AGENTS.md

Igniter.js plugin that wires BetterAuth API into an 'auth' controller automatically.

# Agent Guide — @igniter-js/plugin-better-auth

Last Updated: 2025-11-06

## Purpose
Scaffold Igniter.js plugin that converts BetterAuth's `api` surface into an Igniter plugin controller (`auth`) with dynamic actions. The initial implementation is conservative and designed to be extended safely.

## Files
- `src/index.ts` — Public entry; creates the plugin object.
- `src/mapper.ts` — Internal API-to-controller/action mapper.
- `tsup.config.ts` — Build config.
- `tsconfig.json` — TypeScript config (inherits from workspace base).
- `README.md` — User-facing docs (English only).

## Design
- No compile-time dependency on BetterAuth types; runtime-only inspection of `auth.api`.
- Avoids `any` in the public API. Public options accept `unknown` and use guards internally.
- Controllers are registered under the plugin route: `/api/v1/plugins/{pluginName}/{controllerName}/...`.
- Default `pluginName` is `better-auth` and `controllerName` is `auth`.

## Mapping Rules (v1)
1. If a value is an object with methods named `get`, `post`, `put`, `patch`, `delete` (functions), create one action for each present method.
2. If a value is a function, create a `POST` action for the full property path.
3. Action path is `/${segments.join('/')}`.
4. Handler merges `{ ...params, ...query, ...body }` and forwards to the target function.
5. Errors are caught and returned via `response.status(500).error(...)`-style shape (JSON fallback).

## Extensibility Hooks
- Adjust `HTTP_METHOD_KEYS` to align with BetterAuth after validation.
- Replace default input forwarding strategy if BetterAuth expects a Request-like signature.
- Enrich with Zod schemas when BetterAuth exposes them.

## Testing
- For now, lightweight unit tests can stub an `auth` object with a shaped `api` and assert produced controller/actions and handler invocation.

## Publishing
- Uses `tsup` to build ESM/CJS + DTS.
- `publishConfig.access` is `public`.