shopdb-flask/docs/PLUGIN-HOOKS.md

Plugin Hooks Reference

This page is the contract, and it is the only page that defines it. Every hook a plugin may implement, every manifest field, and every name a plugin may import is specified here. PLUGIN-QUICKSTART and PLUGIN-GUIDE TEACH - they show one plugin making one set of choices, and they link back here for the shape of anything they use. If one of them disagrees with this page, this page is right and the other page is a defect: fix it here and delete the copy there.

Plugin authors implement BasePlugin and override the hooks they care about. Required hooks must be implemented; optional hooks have defaults and can be left alone. Every section carries a stable anchor (#hook-get_reports and so on) so another page links to exactly the hook it means.

The contract is locked in ADR-001 and versioned per ADR-002.

Hook index

Jump straight to the one you need; you should never have to read this page end to end.

Hook		Contributes
meta	required	The plugin's identity, built from manifest.json
get_blueprint	required	The Flask blueprint mounted at api_prefix
get_models	required	The SQLAlchemy models the plugin owns
init_app	optional	Anything else at startup: schemas, a second blueprint
get_cli_commands	optional	Click commands on the Flask CLI
get_services	optional	Named services another plugin can obtain
get_dashboard_widgets	optional	Cards on the dashboard queue
get_navigation_items	optional	The sidebar entry
get_reports	optional	Cards on the Reports hub
get_permissions	optional	The RBAC permissions the plugin's routes enforce
get_guest_grantable_permissions	optional	Which of its WRITES a site may grant to guest
get_settings_cards	optional	Cards in the settings rail
get_asset_panels	optional	Panels on asset detail pages
get_map_overlays	optional	Badges/rings and a legend entry on the floor map
get_asset_presentation	optional	Icon and detail route for an asset type it owns
get_provisioning_note	optional	What the setup wizard warns a site it will create
get_config_schema	optional	Config fields the setup wizard prompts for
get_settings_defaults	optional	The Setting rows the plugin owns
get_collector_schema	optional	JSON Schema for an external collector push
apply_collector_payload	conditional	The upsert behind that collector
on_install / on_uninstall / on_enable / on_disable	optional	State-transition work
get_setting / set_setting	provided	Plugin-scoped settings (you call these, not override)

The rest of the contract: manifest fields - frontend contribution - the shopdb.api import surface - helpers - removed hooks - changing the contract - the bulk-import journal.

One rule holds for every list-returning hook below. The endpoint that consumes it skips disabled plugins, and isolates a plugin that raises: logged and dropped in production, re-raised in dev and test so you see it.

Plugin metadata

Each plugin ships a manifest.json, the single source of truth for its identity; the dataclass PluginMeta is constructed from it.

{
    "name": "computers",
    "version": "1.0.0",
    "description": "Tracks shop-floor PCs and engineering workstations",
    "author": "shopdb-flask",
    "dependencies": [],
    "core_version": ">=0.1.0,<1.0.0",
    "api_prefix": "/api/computers"
}

Field	Required	Notes
name	Yes	Lowercase concatenated, no underscores or dashes
version	Yes	Plugin's own semver
description	Yes	One sentence
dependencies	No	List of plugin names that must load first
core_version	Yes	Range of framework __contract_version__ this plugin supports
api_prefix	No	Defaults to /api/<name>
display_name	No	Human label for UIs; defaults to the title-cased name
default_enabled	No	false means installing does not turn the plugin on

core_version is checked at load time and a plugin outside the range is refused. The framework declares its own version in shopdb/__init__.py as __contract_version__; the current value is in PROJECT-MAP.md, which is generated from the code. This page does not restate it, because a version copied into prose is stale within a fortnight and a plugin pinned against a stale one is refused at startup. How tight to pin, and what happens on a mismatch, are in PLUGIN-EXTERNAL-REPO.md.

Required hooks

meta -> PluginMeta

Returns the plugin's metadata. Read it from manifest.json rather than typing the values twice - the scaffold (flask plugin new) writes this for you:

from shopdb.plugins.base import BasePlugin, PluginMeta

class ComputersPlugin(BasePlugin):
    @property
    def meta(self) -> PluginMeta:
        return PluginMeta(
            name=self._manifest['name'],
            version=self._manifest['version'],
            description=self._manifest['description'],
            dependencies=self._manifest.get('dependencies', []),
            core_version=self._manifest.get('core_version', '>=0.1.0'),
            api_prefix=self._manifest.get('api_prefix'),
        )

get_blueprint() -> Optional[Blueprint]

Returns a Flask Blueprint with the plugin's API routes, or None if the plugin has no HTTP routes. The loader registers the blueprint at the api_prefix from the manifest.

from flask import Blueprint
from .api import computers_bp

class ComputersPlugin(BasePlugin):
    def get_blueprint(self):
        return computers_bp

get_models() -> List[Type]

Returns the SQLAlchemy model classes the plugin defines. Used by the migration runner and admin tooling.

from .models import Computer, ComputerSoftware

class ComputersPlugin(BasePlugin):
    def get_models(self):
        return [Computer, ComputerSoftware]

Optional hooks

init_app(app, db) -> None

Custom initialization. Called by the loader after the blueprint is registered and models are known. Use for Marshmallow schema registration, Caching configuration, secondary blueprint registration, or anything else the plugin needs.

class PrintersPlugin(BasePlugin):
    def init_app(self, app, db):
        from .api import printers_legacy_bp
        app.register_blueprint(printers_legacy_bp, url_prefix='/api/printers/legacy')

get_cli_commands() -> List

Returns a list of Click commands or command groups to register on the Flask CLI.

import click

@click.group()
def computers_cli():
    pass

@computers_cli.command()
def reset_computers():
    """Reset all computer status flags."""
    ...

class ComputersPlugin(BasePlugin):
    def get_cli_commands(self):
        return [computers_cli]

get_services() -> Dict[str, Type]

Returns a dict of service-name to service-class. Another plugin obtains one via plugin_manager.get_service('<name>'), which searches enabled plugins and returns the registered class/factory (or None).

from .services import ZabbixService

class PrintersPlugin(BasePlugin):
    def get_services(self):
        return {'zabbix': ZabbixService}

get_dashboard_widgets() -> List[Dict]

Returns dashboard card definitions for the home page.

A card declares DATA AND SHAPE, never a component name. Core owns a small set of generic renderers and draws the card; the plugin says what to show, where it comes from, and how to link it.

A card using the pre-0.19.0 shape ('component': 'SomeWidget.vue') is ignored and renders nothing - if a card of yours is silently absent, that is why. The reasoning is in the 0.19.0 row of CONTRACT-STABILITY.md.

class WarrantyPlugin(BasePlugin):
    def get_dashboard_widgets(self):
        return [{
            'id': 'warranty-expiring',        # stable, unique across plugins
            'title': 'Warranties expiring',
            'endpoint': '/api/warranty/dashboard/expiring',
            'render': 'exceptions',           # a core renderer, not a component
            'severity': 'info',               # orders cards on the page
            'permission': 'warranty.view',    # hidden without it
            'empty': 'hide',                  # say nothing when there is nothing
            'position': 50,
            'viewall': '/reports/warranty',   # optional link behind the heading
            'map': {'title': 'hostname', 'detail': 'state'},
        }]

empty: 'hide' is not cosmetic. A card that reports "nothing wrong" every day teaches people to stop reading the page.

Consumed by GET /api/dashboard/widgets, which merges every enabled plugin's widgets sorted by position.

get_navigation_items() -> List[Dict]

Returns navigation menu items. A plugin owns its own sidebar entry here, so it appears when the plugin is installed and disappears when it is not (including in a lean per-site build that omits the plugin).

class ComputersPlugin(BasePlugin):
    def get_navigation_items(self):
        return [{
            'name': 'Computers',
            'icon': 'desktop',
            'route': '/computers',
            'position': 10,
        }]

Placement. position (int) sets both the sort order and which section the item lands in - the core sidebar (AppLayout.vue:buildNavItems) assigns section headers by position range:

position	section
< 10	top, above any header (Dashboard is 0, Map is 4)
10-29	Assets
30-49	Information
>= 50	trailing, below Information

Lower number sorts higher within a section. An explicit 'section': 'information' forces the Information group regardless of position. Only these two named sections exist; a new section needs a core edit to buildNavItems. The Displays group (kiosk/TV links) is hardcoded in AppLayout.vue, not plugin-driven.

icon is a string key mapped to a Lucide component core-side (same idea as get_settings_cards); an unknown key renders with no icon.

get_reports() -> List[Dict]

Returns report card definitions for the Reports hub. Added in contract 0.6.0.

Each entry has id, name, description, category, plus EXACTLY ONE of route (a frontend path for a dedicated report page) or endpoint (an API endpoint the hub renders inline).

class WarrantyPlugin(BasePlugin):
    def get_reports(self):
        return [{
            'id': 'warranty',
            'name': 'Warranty Report',
            'description': 'Assets bucketed by coverage: expired, expiring soon, active',
            'category': 'warranty',
            'route': '/reports/warranty',
        }]

Consumed by GET /api/reports, which merges plugin cards after the static core reports; the frontend groups them by category.

get_permissions() -> List

Returns the RBAC permissions this plugin owns. Added in contract 0.10.0. A plugin declares the permission names its own routes enforce via require_permission, instead of core accumulating every plugin's permissions in one catalog (plugin-is-the-product).

Each entry is a (name, description, category) tuple, matching the core permission catalog shape (dicts with those keys are also accepted). Names follow the naming convention (lowercase dotted, e.g. machines.edit).

class MachinesPlugin(BasePlugin):
    def get_permissions(self):
        return [
            ('machines.view', 'View machines', 'machines'),
            ('machines.create', 'Create machines', 'machines'),
            ('machines.edit', 'Edit machines', 'machines'),
            ('machines.delete', 'Delete machines', 'machines'),
        ]

Consumed by the core helper full_permission_catalog() (core permissions plus every ENABLED plugin's get_permissions()), which backs three consumers:

• flask seed permissions seeds the full catalog.
• The role-management grid (GET /api/users/permissions) lists it, grouped by category.
• API-token scope validation (ApiToken.unknown_scope_names) accepts a plugin permission as a scope only while that plugin is enabled.

Plugin install and enable also seed the plugin's own permissions idempotently, so enabling a fresh plugin creates its Permission rows without a separate seed pass.

Disabled-plugin edge case: a disabled plugin is skipped by the catalog, so its permissions are no longer offered for new scope grants or new role assignments. The Permission ROWS already in the database are NOT deleted, so roles that already reference them keep working until an admin edits the role. A broken plugin is isolated in prod and re-raised in dev/test.

get_guest_grantable_permissions() -> List[str]

Names the WRITE permissions this plugin allows a site to grant to the guest role. Added in contract 0.21.0.

Anyone with no account holds the guest role. It is seeded with nothing, and a site opens a door by granting it a permission in the role grid - which replaced the per-feature booleans (securesend_allow_guests, one per kiosk) that used to answer the same question one feature at a time.

Any .view or .read permission is grantable without a plugin saying anything. This hook is only for the exception: a write that is genuinely meant to work for somebody who never signs in. Naming one here does not open it - it makes the checkbox available, and a site still has to tick it.

class ToolsPlugin(BasePlugin):
    def get_guest_grantable_permissions(self):
        # Sending a password to a vendor: the recipient has no account here,
        # and often neither does the sender. The unguessable token is the
        # authorisation and the link is one-view.
        return ['tools.secrets']

The bar for naming one: could this action be attributed to nobody, forever, and still be defensible in the audit log? A guest write records no creator - the trail says when and from where, never who. Return [] (the default) and none of this plugin's writes can ever be made anonymous; anything not named is refused by the API when an admin tries to grant it, not merely warned about.

Consumed by guest_grantable_permissions(), which backs the role API's guard on the guest role and the greyed-out checkboxes in the role grid. A plugin may only bless permissions that already exist in the catalog, so a typo widens nothing.

get_settings_cards() -> List[Dict]

Returns settings-catalog card definitions. Added in contract 0.7.0 (ADR-010). Each card is merged into the settings rail and landing overview without the plugin hand-editing the core settingsNav.js catalog. icon is a string key mapped to a Lucide component core-side, exactly like get_navigation_items.

class PrintersPlugin(BasePlugin):
    def get_settings_cards(self):
        return [{
            'group': 'Printers',               # rail group title (created if new)
            'to': '/settings/printer-alerts',
            'icon': 'bell',                    # string key, mapped core-side
            'title': 'Low-Toner Alerts',
            'description': 'Who gets warning and critical toner emails',
            'position': 48,                    # order within the group
        }]

Consumed by GET /api/pluginui/settings-cards, which merges enabled plugins' cards into the core catalog.

get_asset_panels() -> List[Dict]

Returns asset-detail extension-panel definitions. Added in contract 0.7.0 (ADR-010). A generic core AssetPanel component renders each panel on the matching detail pages, fetching the panel's endpoint. This replaces hand-composing a plugin panel component into each detail view.

class WarrantyPlugin(BasePlugin):
    def get_asset_panels(self):
        return [{
            'id': 'warranty',
            'title': 'Warranty',
            'assettypes': ['*'],               # detail pages it appears on; ['*'] = all
            'endpoint': '/api/warranty/asset/{assetid}',
            'render': 'table',                 # 'keyvalue' | 'table' | 'badge'
            'position': 30,
        }]

Consumed by GET /api/pluginui/asset-panels?assetid=<id>, which returns the panels whose assettypes match that asset's type. A panel that needs bespoke UI (a chart) is out of scope for this data-only hook.

get_map_overlays() -> List[Dict]

Returns shop-floor map overlay/decoration definitions. Added in contract 0.7.0 (ADR-010). The map stays data-driven off asset types + positions; an overlay adds decoration data (a badge or ring) plus an optional legend entry, with no plugin-side map code.

No bundled plugin implements this hook on this line, so the example below is written out rather than pointed at. GET /api/pluginui/map-overlays returns an empty list until a plugin declares one, which is the correct behaviour and not a fault. Take the shape from here and from ADR-010.

class CamerasPlugin(BasePlugin):
    def get_map_overlays(self):
        return [{
            'id': 'camera-offline',
            'label': 'Camera offline',         # legend label
            'endpoint': '/api/cameras/map-overlay',  # -> [{assetid, color, label}]
            'style': 'badge',                  # 'badge' | 'ring'
            'legend': True,
        }]

Consumed by GET /api/pluginui/map-overlays.

An overlay keys on assetid and never on coordinates, so it needs to know nothing about buildings or levels (ADR-017): it decorates whichever marker that asset already has, on whatever level that marker is on. Do not return mapx / mapy / levelid from an overlay endpoint - a position belongs to the asset, and a second copy of it in an overlay is one that can disagree.

get_asset_presentation() -> List[Dict]

Returns asset-type presentation/routing definitions. Added in contract 0.7.0 (ADR-010). Declares how a plugin-owned asset type renders in global-search rows and cross-links (which icon, which detail route), so core never hardcodes a plugin's route or icon.

No bundled plugin implements this hook on this line either, so this example is also written out. GET /api/pluginui/asset-presentation returns an empty list until a plugin declares one; core then falls back to its own icon and route for the asset type.

class CamerasPlugin(BasePlugin):
    def get_asset_presentation(self):
        return [{
            'assettype': 'camera',             # AssetType.assettype key the plugin owns
            'icon': 'video',
            'label': 'Camera',
            'route': '/cameras/{assetid}',
        }]

Consumed by GET /api/pluginui/asset-presentation.

get_provisioning_note() -> Optional[Dict]

Transparency note the setup wizard shows the moment a site checks this plugin during setup. Return None (the default) for plugins that need no special setup. Plugins that create extra tables beyond their asset-extension table return:

No bundled plugin declares one on this line; the shape is:

class CamerasPlugin(BasePlugin):
    def get_provisioning_note(self):
        return {
            'tables': ['camerastreams'],
            'note': 'Creates a stream-credential table in the shopdb database.',
            'docs': 'plugins/cameras/README.md',
        }

get_config_schema() -> List[Dict]

Declares the config fields this plugin needs, so the setup wizard can prompt for them. Return [] (the default) if the plugin needs no configuration. Each field is a dict:

Key	Meaning
key	the Setting key (non-secret) it maps to
label	human label shown in the wizard
type	'text' / 'number' / 'password'
secret	True for credentials; NOT stored in the DB - the wizard emits an .env line for the operator instead
envvar	(secret only) the .env variable name to emit
default	optional placeholder
help	optional hint

class PrintersPlugin(BasePlugin):
    def get_config_schema(self):
        return [
            {'key': 'zabbix_url', 'label': 'Zabbix URL', 'type': 'text',
             'help': 'Base URL of the Zabbix server for supply lookups'},
            {'key': 'zabbix_token', 'label': 'Zabbix API token', 'type': 'password',
             'secret': True, 'envvar': 'ZABBIX_TOKEN'},
        ]

get_settings_defaults() -> List[Dict] (0.16.0)

Declares the Setting rows this plugin owns. Return [] (the default) if it owns none. Each entry is a dict:

Key	Meaning
key	the Setting key
value	default value in string form
valuetype	'string' / 'boolean' / 'integer' / 'json'
category	grouping the plugin's settings page filters on
description	what the setting does
public	True if an unauthenticated caller may read it; default False

class BackupsPlugin(BasePlugin):
    def get_settings_defaults(self):
        return [
            {'key': 'backups_intervalhours', 'value': '24', 'valuetype': 'integer',
             'category': 'backups', 'public': True,
             'description': 'Minimum hours between collection attempts on a PC'},
        ]

public: True there is load-bearing, not tidiness: the collecting script reads that value from /api/settings/public BEFORE it has any credential. Left private, the setting looked configurable and was not.

The framework seeds declared keys at install, at enable, and on every flask plugin upgrade-all, so a key added in a later plugin version reaches a site that installed an earlier one. Existing values are never overwritten.

Declaring a key is also what tells the settings API which category and type to use when an admin's save creates the row for the first time. Do not seed settings by hand in on_install / on_enable: those hooks fire only on a state transition, so a hand-seeded key added later never reaches an existing site, and the row the first save creates lands in the placeholder plugin category where the plugin's own settings page (which filters by category) cannot see it.

public: True puts the key on the unauthenticated read allowlist of GET /api/settings/<key> and GET /api/settings. Use it only for cosmetic values that a page rendering before login needs (a kiosk, a print page). Never mark a credential, a hostname, or an integration URL public.

get_collector_schema() -> Optional[Dict]

Declares the JSON Schema for an external collector pushing to /api/collector/<pluginname>. See ADR-006 for the contract.

class ComputersPlugin(BasePlugin):
    def get_collector_schema(self):
        return {
            'identityfield': 'hostname',
            'fields': {
                'hostname': {'type': 'string', 'required': True},
                'macaddress': {'type': 'string'},
                'osname': {'type': 'string'},
                'osversion': {'type': 'string'},
                'currentuser': {'type': 'string'},
                'ipaddress': {'type': 'string'},
            }
        }

If the hook returns None (the default), no collector endpoint is registered.

apply_collector_payload(payload: Dict) -> Dict

Companion to get_collector_schema (ADR-006). The generic /api/collector/<pluginname> endpoint calls this after the payload passes identity validation, to idempotently upsert an asset. Return a dict with at least action (created | updated | noop), assetid, and warnings (list).

This is a CONDITIONAL hook: it is only required when get_collector_schema returns non-None. The BasePlugin default raises NotImplementedError (the dispatcher turns that into a 500), so a plugin that declares a schema but forgets the upsert fails loud. Plugins with no collector schema never need it. The test_schema_declaring_plugins_implement_apply contract test enforces the pairing.

def apply_collector_payload(self, payload):
    host = payload['hostname']
    comp = Computer.query.filter(Computer.hostname.ilike(host)).first()
    action = 'updated' if comp else 'created'
    # ... create-or-update Asset + extension ...
    db.session.commit()
    return {'action': action, 'assetid': comp.assetid, 'warnings': []}

Frontend contribution

A plugin's UI is part of the plugin, not part of core. This section is the contract for it; ADR-013 has the reasoning.

Where the files live. plugins/<name>/frontend/, holding routes.js and views/. Nothing is written into frontend/src/. scripts/stage-frontend.mjs (run by npm predev/prebuild) copies each chosen plugin's frontend/ into frontend/src/.plugins-staged/<name>/ and codegens frontend/src/router/routes.gen.js, which the router imports. Both outputs are generated and gitignored.

What a lean build stages. SITE_PLUGINS=machines,printers npm run build stages only those plugins; unset, it stages every plugin that has a frontend/routes.js. The exception, and the rest of the lean-build model, is in PLUGINS.md.

The route module. routes.js default-exports an array of routes and may also export toplevel for full-screen routes that render outside AppLayout (a kiosk, a print page). toplevel is optional: the codegen imports each staged module as a namespace, so a module without it is not a build error. Every route carries meta: { plugin: '<name>' }; the router guard redirects to the dashboard when the backend plugin is disabled, so a route never loads a shell over a plugin that is not there.

One import rule, and staging is the reason. Anything from the CORE tree uses the @ alias (@/api, @/components/PaginationBar.vue, @/stores/auth); anything inside your own plugin is relative (./views/...). A relative path into the core tree such as ../../api is correct where the file sits in your plugin and wrong once staged into .plugins-staged/<name>/. The failure is a build error, not anything subtle.

Menus follow the build, not a flag. The sidebar nav, the settings rail and the Displays links gate on whether your route was actually staged, so an omitted plugin's nav item, settings cards and kiosk links vanish together - your hooks cannot leave a menu entry pointing at a page that is not there.

Lifecycle hooks

These run when the plugin's installation state changes. All optional.

Hook	When	Use case
on_install(app)	First time the plugin is installed via flask plugin install	Seed reference data, run plugin-specific migrations, register webhooks
on_uninstall(app)	When the plugin is removed via flask plugin uninstall	Clean up reference data, deregister webhooks
on_enable(app)	When the plugin is enabled at runtime	Subscribe to events, warm caches
on_disable(app)	When the plugin is disabled at runtime	Unsubscribe, drain queues

The import surface (shopdb.api)

shopdb.api is the ONLY core module a plugin may import from (besides shopdb.plugins.base for BasePlugin / PluginMeta). Importing internal paths like shopdb.core.models.*, shopdb.extensions, or shopdb.utils.* is a contract violation and fails the test tests/test_plugin_contract.py::test_plugins_only_import_contract_surface.

What shopdb.api exposes. The machine-readable truth is __all__ in shopdb/api/__init__.py; this list groups the same names by what they are for.

Infrastructure and model bases - db, cache, BaseModel, AuditMixin.

Core models (the asset contract, ADR-001) - Asset, AssetType, AssetStatus, AssetRelationship, RelationshipType, Vendor, Model, Location, Communication, CommunicationType, Setting, AuditLog, Application, AppVersion, OperatingSystem, Script (the hosted script library), User, Role, SupportTeam (carries a webhookurl, so an alerting plugin can route to a team's webhook).

Displays - DashboardDefault, DISPLAY_ROLES, DISPLAY_ROLE_PATHS, normalize_display_role. The role vocabulary is core's, so a plugin that reports on displays reads it instead of keeping a copy that drifts.

Responses and pagination - success_response, error_response, paginated_response, ErrorCodes, get_pagination_params, paginate_query.

Authorization - require_permission, require_any_permission (a read two different rights should reach), require_role, and caller_holds(permission), which ANSWERS whether the caller holds a permission without refusing the request - for a route that serves everyone but should only offer what the caller can act on.

Service and collector tokens - service_token_authorized(scope) returns True when the request carries a managed service token scoped for scope whose owner holds that permission; authorized_service_token(scope) returns the ApiToken itself so a plugin can honor the token's optional resource binding (token.resourcescopelist, NULL = unrestricted); mint_service_token, list_service_tokens and revoke_service_tokens provision, list and revoke a single-scope token from a plugin's own UI; collector_authorized(pluginname) gates an agent-facing route that lives outside the generic collector blueprint on the same per-plugin key and kill switch the ingest route uses.

Serving uploads - send_upload, harden_upload_response. Use them for any user-supplied bytes: they set the headers that keep an SVG or an HTML file from running as script in this origin.

Caller IP - client_ip, strip_port. Do not hand-roll this. The obvious version reads the first X-Forwarded-For hop, which the caller supplies, so a rate limit keyed on it is defeated by rotating the header.

Request-argument and value parsing - intarg, intargs, QueryArgError; parse_date, parse_date_fields, DateValueError; badge_kind, normalise_badge, BadgeShapeError (one badge vocabulary for the site, since both kiosks read the same physical badges).

Helpers - audit_log, resolve_asset_position, resolve_dualpath_pairs, dualpath_single_machine_enabled.

Mail and webhooks - send_email(to, subject, html, text=None), send_alert(subject, html, text=None) (settings-first, no-op safe when email is unconfigured; targets the site's alert_recipients) and send_webhook(title, text) (Teams Incoming Webhook / Workflow, or generic JSON via the alert_webhook_format setting; best-effort, no-op when unset). send_alert fans out to the webhook automatically alongside email.

Bulk import - apply_import_timestamps, import_mode_active, parse_import_datetime; register_import_hook and RowWarning (a plugin owns a VIRTUAL COLUMN on an importable CSV table plus a post-write row hook; core never learns what the column means); and the journal models under Reversible bulk-import journal.

External directories - employee_connection, a read-only handle on a site's existing HR database. Core global search and audit-log name resolution use it; a plugin may too. It returns nothing when EMPLOYEE_DB_* is unset, so guard on that rather than assuming a site has one.

from shopdb.api import db, Asset, AssetType, success_response, paginate_query

Adding a name to shopdb.api is an additive (minor) contract bump; removing one is breaking (major). See ADR-002.

Helpers exposed to plugins

Everything importable is listed above; this section is only the semantics you cannot guess from the name.

audit_log(action, entitytype, entityid=None, entityname=None, changes=None, details=None) - write an audit row on every mutation. changes takes {'before': ..., 'after': ...}. The current user, IP and timestamp are captured for you.

get_setting(key, default=None) / set_setting(key, value, valuetype='string', description=None) - methods ON your plugin class, reading and writing the core Setting store under the namespaced key plugin.<pluginname>.<key>, so two plugins cannot collide. Use them to READ; declare the rows themselves from get_settings_defaults rather than writing them in on_install.

resolve_asset_position(asset) - returns {'mapx', 'mapy', 'levelid', 'positionsource'}, where positionsource is 'self' | 'related' | 'location' | None. The resolution order is in ADR-001; the levelid belongs to whichever source supplied the coordinates, and a plugin that writes a position MUST write its level with it (ADR-017) - a marker drawn on the wrong floor plan looks correct.

resolve_dualpath_pairs() / dualpath_single_machine_enabled() - a Dualpath pair is one physical dual-bay machine recorded as two asset rows. When the site setting dualpath_single_machine is on (the default), lists, dashboard/report counts and the map show the pair as one machine by hiding the SECONDARY bay; both rows always exist and detail pages stay per-bay. PRIMARY is the pair member with the lower natural-sort assetnumber. resolve_dualpath_pairs() returns secondaryassetids (the ids to hide) and partnerbyasset (assetid -> partner, for both members, for banners) and IGNORES the toggle, so a detail-page sibling banner can always show; gate the collapse itself on dualpath_single_machine_enabled().

apply_import_timestamps(row, data) / import_mode_active() / parse_import_datetime(value) - bulk imports from the classic ASP shopdb preserve each row's original createddate / modifieddate instead of stamping "now". apply_import_timestamps is a no-op unless the caller is an admin AND sent X-Import-Mode: true, so it never affects normal traffic; call it after db.session.add(row) and before the commit. import_mode_active() is the same predicate, for guarding other backdated behaviour (accepting a historical checkouttime, say). parse_import_datetime reads both ISO 2020-01-05T12:00:00 and legacy YYYY-MM-DD HH:MM:SS into naive UTC. The operator manual is IMPORT-API.md.

Removed hooks

The following hooks existed in early drafts and have been removed for v1:

Hook	Reason
get_event_handlers	Event bus deferred indefinitely. No real use case yet. Add via new ADR if needed.
get_searchable_fields	Removed in 0.4.0. Global search (/api/search) is a core concern over the asset model, already covering every bundled asset type, and honours runtime enable/disable. No plugin ever implemented it.

Versioning your changes

When you change anything documented here, you must:

1. Bump __contract_version__ per ADR-002: major for removals or signature changes, minor for additive optional hooks, patch for docs.
2. Update ADR-001 if the contract surface itself changed (or supersede with a new ADR).
3. Add or update the test in tests/test_plugin_contract.py that asserts the new behavior.
4. Update this page in the same change. tests/test_docs_contract.py fails the build when a public BasePlugin hook is not mentioned here.

Reversible bulk-import journal

Contract version 0.30.0.

A plugin that drives a bulk import - a site asset adoption, an integration sync - records the primitive changes it makes so the whole batch can be reversed later. The journal is import-agnostic: it stores primitive mutations (set a cell, insert a row) tied to a batch id, and a generic undo replays them in reverse. Nothing in core learns what the import means.

Exposed on shopdb.api: ImportBatch (one row per applied import; batchid is the identity the approval step, the write and the undo all reference; status is BATCH_APPLIED or BATCH_UNDONE) and ImportJournalEntry (one reversible mutation; operation is OP_UPDATE, carrying oldvalue/newvalue, or OP_INSERT, a row this batch created).

A plugin READS these and does not write them. Its import UI lists applied batches and offers "Undo import" per batch. The write and undo logic lives with the import writer (scripts/site_imports/journal.py), which journals in the SAME transaction as the mutation it describes and reverses conservatively: an update is put back only if the cell still holds the value the import wrote (a value a human has since changed is left alone and reported), and an insert is hard-deleted only when nothing outside the batch references the created row.

The tables are core-owned (migration 7d37_import_batches_and_journal), so they exist regardless of which plugins are installed.