Modules and integrations

Beyond themes, the Aetheris platform can be extended with modules and integrations. A module is a packaged unit of functionality (a payment gateway, a notification channel, a storage driver, a UI panel); an integration is the concrete wiring of a module to an external service.

Module manifest

Every module ships a manifest.json that describes it:

{
  "id": "gateway-coinbase",
  "name": "Coinbase Commerce",
  "category": "payment-gateway",
  "version": "1.0.0",
  "author": {
    "name": "Leonardo Galli",
    "github": "Leo-Galli"
  },
  "license": "AGPL-3.0",
  "entry": "src/index.ts",
  "requires": ["billing"],
  "description": "Accept crypto payments through Coinbase Commerce.",
  "documentation": "README.md"
}

Manifest fields:

Field	Required	Description
`id`	yes	Unique kebab-case identifier
`name`	yes	Human-readable module name
`category`	yes	`payment-gateway`, `notification`, `storage`, `utility`, `panel`
`version`	yes	Semantic version
`author`	yes	`name` and `github` handle of the maintainer
`license`	yes	License identifier (e.g. `AGPL-3.0`)
`entry`	yes	Main entry point relative to the module root
`requires`	no	Platform features the module depends on (`billing`, `vncConsole`, ...)
`description`	yes	One-line description shown in the store
`documentation`	no	Relative path to the module README

Creating a module

Clone the addons repository and create a folder under addons/ named after the module id:

git clone https://github.com/aetheris-project/aetheris-addons.git
cd aetheris-addons
mkdir -p addons/gateway-coinbase/src

Write manifest.json following the schema above.
Implement the module entry point. Payment gateways implement the PaymentGateway contract, notification channels the NotificationChannel contract, storage drivers the StorageDriver contract - the type definitions live in types/ at the repository root.
Write a README.md documenting setup, environment variables and usage.

Validate the manifest:

python tools/validate.py addons/gateway-coinbase

Open a pull request. See the store page for the contribution flow.

Module contracts

Payment gateway

interface PaymentGateway {
  readonly id: string;
  createCheckout(amountCents: number, currency: string, metadata: Record<string, string>): Promise<CheckoutSession>;
  capturePayment(sessionId: string): Promise<PaymentResult>;
  refund(paymentId: string, amountCents?: number): Promise<RefundResult>;
  verifyWebhook(payload: string, signature: string): Promise<WebhookEvent>;
}

Notification channel

interface NotificationChannel {
  readonly id: string;
  send(message: NotificationMessage): Promise<void>;
  test(): Promise<void>;
}

Local development

Modules are plain TypeScript with no runtime dependency on the platform SDK. Run npm run typecheck from the repository root to typecheck every module, and python -m pytest to run the manifest validation suite.

Publishing a module

Create addons/<id>/ with a valid manifest.json, the entry point (src/index.ts by default) and a README.md.

Validate the manifest locally:

python tools/validate.py addons/<id>/manifest.json

Implement the interface required by your category (see the manifest schema in docs/manifest-schema.md for the exact contracts).
Add tests under tests/ and run the suite: python -m pytest.
Open a pull request against aetheris-addons. CI runs the manifest validation and the test suite; a PR with an invalid manifest cannot be merged.
Once merged, the module appears in the store catalog (store.json) automatically and can be installed from the Admin Panel.