Extending Tidemark

Tidemark is designed to be extended by a separate Composer package, for example a hosted service that adds billing. Packages use these hooks and never need to edit Tidemark itself.

Entitlements

App\Contracts\Entitlements decides what an account may do:

interface Entitlements
{
    public function canCreateSite(User $user): true|string;   // true, or a message shown to the user
    public function allowsRecording(array $site): bool;       // called for every event; keep it fast
}

The default implementation only applies TIDEMARK_MAX_SITES. A package binds its own in its service provider with $this->app->singleton(Entitlements::class, MyEntitlements::class). When allowsRecording() returns false, the event is dropped but the tracker still receives 202 ok, so visitors' browsers never see an error. $site contains id, domain and owner_id.

Events

Dashboard modules

Add the URL of a JavaScript module to config('tidemark.extensions'). Its default export runs before the dashboard renders and receives an api object:

export default function (api) {
  const { html } = api;
  api.registerAccountTab({ key: 'billing', label: 'Billing', component: Billing, dot: (user) => user.past_due });
  api.registerBanner(({ user }) => html`<div class="banner">Your trial ends soon</div>`);
  api.registerRoute('/pricing', PricingPage);
}

api.lib, api.ui and api.chart give access to the dashboard's helpers and components (Preact + htm, no build step needed). Account tabs appear in Account settings. The extension API is versioned (api.version).