API stability

Generated from STABILITY.md in the AstroBaaS repository. The repository is the source of truth; this page is a copy of it.

This document defines what AstroBaaS promises to theme and plugin authors, and what it doesn’t — so you can build on it without being surprised by an upgrade.

TL;DR

The public API is everything exported from astrobaas/core, astrobaas/plugins, and astrobaas/client. Build against those import paths only.
AstroBaaS is pre-1.0 (@alpha). The public API may still change, but every breaking change to it is called out in CHANGELOG.md under a Breaking heading.
Anything under src/lib/*, src/pages/*, src/components/* is internal and can change in any release with no notice. Don’t import it directly.

The public surface

Covered by the stability policy below.

`astrobaas/core` (server + shared)

Export	Kind	Notes
`Post`, `Category`, `User`, `MediaFile`, `Theme`, `ThemeConfig`, `Setting`, `ContentChange`, `PluginRecord`, `CustomEntity`, `ApiKey`, `Webhook`, `WebhookDelivery`, `AuditEvent`, `PostRevision`, `TwoFactor`, `Role`, `PostStatus`, `EntityType`, `DatabaseSchema`	types	Domain models.
`Storage`	type	The storage contract the app depends on.
`Plugin`, `FilterFn`, `ActionFn`, `PluginSettings`	types	Plugin shapes.
`PluginManager`, `pluginManager`	class/value	Hook registry + the shared instance.
`PLUGIN_HOOKS`	const	The canonical hook-name catalog. Always reference these constants, never raw strings.
`definePlugin`, `defineTheme`	fn	Author helpers (type inference).
`registerContentType`, `getContentTypes`, `getContentType`, `schemaForContentType`	fn/registry	Custom content types.
`THEME_SLOTS`, `ThemeSlotName`, `ThemeSlotProps`, `ThemeComponents`, `HeaderProps`, `FooterProps`, `PostCardProps`, `PostCardData`, `PostArticleProps`, `SidebarProps`, `isThemeSlot`, `overriddenSlots`	const/types/fn	Theme template-override contract. Adding a NEW slot is additive: themes that don’t know about it inherit the default, so it is not a breaking change.
`validateManifest`, `renderHeadTags`, `manifestContentTypes`, `apiRangeSatisfied`, `MANIFEST_API_VERSION`, `MANIFEST_LIMITS`, `PluginManifest`, `ManifestCapabilities`, `ManifestHeadTag`, `ManifestWebhook`, `ManifestValidationResult`	fn/const/types	Declarative plugin manifests. `MANIFEST_API_VERSION` is its own semver line: a manifest declares the major it targets via `astrobaasApi`, and a mismatched major is refused rather than half-honoured. Adding a capability is additive; removing or changing one is a MAJOR bump.
`sanitizeHtml`	fn	Allow-list HTML sanitizer; run on any author HTML before `set:html`.
`validate`, `slugify`, `Schema`, `FieldRule`	fn/types	Input validation.
`ApiResponseBuilder`, `ApiResponse`	class/type	The house response shape for custom endpoints.
`fireEvent`, `webhookMatches`, `webhookBody`, `WEBHOOK_EVENTS`	fn/const	Outbound webhook dispatch + helpers.
`signWebhook`, `newWebhookSecret`	fn	HMAC signing for webhook payloads (also for verifying receivers).
`sendEmail`, `getEmailTransport`, `setEmailTransport`, `consoleTransport`, `webhookTransport`, `EmailMessage`, `EmailTransport`	fn/type	Pluggable email transport.
`recordAudit`, `AUDIT`, `AuditDetails`	fn/const/type	Security audit log — record sensitive actions from plugins/custom routes.

`astrobaas/client` (frontend SDK)

Export	Kind	Notes
`createClient`, `AstroBaasClient`	fn/class	Typed REST client over bearer auth.
`AstroBaasError`	class	Thrown on non-2xx / `{success:false}`; carries `status`, `code`, `details`.
`verifyWebhookSignature`	fn	Receiver-side HMAC verifier (WebCrypto, constant-time).
`ClientOptions`, `ListPostsOptions`, `Page`, `PageMeta`, `CreatePostInput`, `UpdatePostInput`, `CreateKeyInput`, `CreatedKey`, `ApiKeyInfo`, `RegisterWebhookInput`, `RegisteredWebhook`, `WebhookInfo`, `WebhookDeliveryInfo`, `AuditEventInfo`, `LocaleConfig`, `ContentApi`, `CurrentPrincipal`, `ApiKeyPrincipal`	types	SDK input/output shapes.

Policy

While pre-1.0:

Additive changes (new exports, new optional fields, new hooks) can land in any minor release.
Breaking changes to the public surface are allowed but will be:
1. listed under Breaking in the CHANGELOG, and
2. accompanied by the reason and a migration note.
Hook names in PLUGIN_HOOKS will not be silently renamed or removed — a removed hook is a documented breaking change.

At 1.0 and after the public surface follows semver: breaking changes only in major versions.

What is explicitly not covered

Internal modules (src/lib/*, src/middleware.ts, route files, components).
The on-disk db.json format (it’s seeded/migrated by the app; don’t write it directly — go through Storage).
The admin UI markup/DOM structure.
The bundled-plugin loading mechanism’s internals (use the documented BUNDLED_PLUGINS registry).

Hook contract

Each hook in PLUGIN_HOOKS documents its kind (filter/action) and payload in PLUGIN_DEVELOPMENT.md. Filters must return the same type they receive. post_content filter output is re-sanitized at the render boundary, so a content filter cannot introduce XSS.