# Package reference

Every public package of the apistock library, generated from its Go doc comments on each build, so it always matches the code. Each page shows the package's constants, variables, functions and types with their documentation. Generated apps import these packages; test helpers are for your tests.

## Core packages

| Package | What it does |
|---|---|
| [actor](/reference/actor.md) | Package actor records who is performing an operation, in a context.Context. |
| [app](/reference/app.md) | Package app runs an application's long-running work and shuts it down in a defined order. |
| [audit](/reference/audit.md) | Package audit defines audit events and the Recorder contract that any module uses to record who did what to which resource, and whether it worked. |
| [buildinfo](/reference/buildinfo.md) | Package buildinfo reports the version, commit and build time of the running binary, from Go build information or a version set at link time. |
| [config](/reference/config.md) | Package config provides configuration helpers for the composition root of an apistock app: a Secret type that never leaks into logs or output, and environment lookup with *_FILE support for mounted secrets. |
| [health](/reference/health.md) | Package health serves liveness and readiness endpoints. |
| [httpx](/reference/httpx.md) | Package httpx provides the HTTP foundation of an apistock app: a server that runs under app.Run with safe timeouts, security middleware, and the RFC 9457 problem+json error contract with an application-owned error mapping (ADR-0018). |
| [mail](/reference/mail.md) | Package mail defines email messages and the Sender contract implemented by provider modules such as mail/resend and mail/smtp (ADR-0025). |
| [page](/reference/page.md) | Package page provides cursor pagination and sorting for list endpoints: bounded limits, opaque cursors and allowlisted sort fields. |
| [ratelimit](/reference/ratelimit.md) | Package ratelimit provides token-bucket rate limiting keyed by a string (an IP address, account or API key): the Taker interface, an in-memory Limiter, and HTTP middleware. |
| [requestid](/reference/requestid.md) | Package requestid generates, validates and carries request IDs in a context.Context, so HTTP middleware, logging, audit and jobs share one correlation value (ADR-0030). |

## Module packages

| Package | What it does |
|---|---|
| [modules/auditpg](/reference/modules/auditpg.md) | Package auditpg stores audit events in PostgreSQL and queries them for operator APIs (ADR-0036). |
| [modules/auth](/reference/modules/auth.md) | Package auth provides the building blocks of email and password authentication: argon2id password hashing, session tokens and one-time codes stored only as hashes, email normalisation, session cookies, the request middleware, a permission catalog and plain authentication emails (ADR-0024, ADR-0038). |
| [modules/auth/passkey](/reference/modules/auth/passkey.md) | Package passkey provides passkeys (WebAuthn) for apps: registration and sign-in ceremonies checked against the relying party's ID and allowed origins, credential records to store, and the association files native apps need (ADR-0044). |
| [modules/auth/social](/reference/modules/auth/social.md) | Package social signs people in with Google and Apple (ADR-0046): the web authorization code flow with state, nonce and PKCE, ID tokens from native apps checked against the app's client IDs, and Apple's client secret, token revocation and server-to-server notifications. |
| [modules/jobs](/reference/modules/jobs.md) | Package jobs runs background jobs on PostgreSQL with River (ADR-0033). |
| [modules/mail/resend](/reference/modules/mail/resend.md) | Package resend sends email with Resend (https://resend.com) through its HTTP API (ADR-0025, ADR-0037). |
| [modules/mail/smtp](/reference/modules/mail/smtp.md) | Package smtp sends email through any SMTP server: Amazon SES, Postmark, Mailgun, Google Workspace, your own server, or Mailpit in development (ADR-0025, ADR-0037). |
| [modules/openapi](/reference/modules/openapi.md) | Package openapi integrates Huma with apistock (ADR-0027): an API on the standard http.ServeMux, problem+json errors produced by the application's error mapper, an API reference at /docs in the apistock design (ADR-0049, rendered by package reference), and OpenAPI export. |
| [modules/openapi/reference](/reference/modules/openapi/reference.md) | Package reference renders an OpenAPI 3.1 document as an API reference in the apistock design (ADR-0049): an overview, and a page per operation with its parameters, responses, request examples in curl, Go and TypeScript, response examples and "Try it". |
| [modules/orgs](/reference/modules/orgs.md) | Package orgs holds the building blocks for organisations in multi-tenant apps (ADR-0023, ADR-0048): organisation IDs, the membership check every organisation operation starts with, and invitation emails. |
| [modules/postgres](/reference/modules/postgres.md) | Package postgres connects apistock apps to PostgreSQL: a pgx connection pool with OpenTelemetry tracing, transactions, error classification for repositories, a readiness check and goose migrations (ADR-0005, ADR-0032). |
| [modules/ratelimitpg](/reference/modules/ratelimitpg.md) | Package ratelimitpg shares rate limits across instances in PostgreSQL (ADR-0052). |
| [modules/releases](/reference/modules/releases.md) | Package releases records which build every instance of an app runs and answers which releases are running (ADR-0040). |
| [modules/settings](/reference/modules/settings.md) | Package settings provides runtime settings: non-secret tunables declared in Go with a default and bounds, stored in PostgreSQL only when changed, and applied on every instance without a restart (ADR-0031). |
| [modules/telemetry](/reference/modules/telemetry.md) | Package telemetry sets up OpenTelemetry tracing and metrics and structured logs correlated with requests and traces (ADR-0007). |

## Test helpers

| Package | What it does |
|---|---|
| [modules/auth/passkey/passkeytest](/reference/modules/auth/passkey/passkeytest.md) | Package passkeytest is a software passkey authenticator for tests. |
| [modules/auth/social/socialtest](/reference/modules/auth/social/socialtest.md) | Package socialtest runs an in-process OpenID Connect provider standing in for Google or Apple in tests: it serves signing keys, a token endpoint and a revocation endpoint, and issues signed ID tokens, authorization codes and Apple notifications. |
| [modules/postgres/pgtest](/reference/modules/postgres/pgtest.md) | Package pgtest gives each test its own PostgreSQL database on the Docker PostgreSQL server started with `docker compose up -d --wait` (ADR-0028). |