Plugin change governance

The plugins in this repository contain shared business logic used by the Investec Online platform. Consuming teams can contribute bounded additions to an existing plugin when the behaviour fits that plugin's documented purpose.

Contact the Web Platform team before creating a plugin or making a change that alters platform architecture, security, lifecycle, or an existing public contract.

Where a plugin package is installed

The platform team installs every released plugin package into the Investec Online shell application. A consuming team never adds a plugin package as a direct dependency of its own consumer or feature application, and never asks an AI assistant to do so on its behalf. A consuming team uses a plugin's behaviour through the Invsy SDK, or through the bounded contribution process described below, which changes the plugin's own source in this repository so the platform team can review, build, and ship the update.

The livechat plugin is the one documented exception. It carries an explicit, approved integration contract that permits direct installation into a consumer application, alongside its normal platform installation path. Treat every other plugin as platform-only unless a future plugin's canonical page states an equivalent approved exception, agreed with the Web Platform team.

Choose where the change belongs

Requirement	Correct location
Application-only UI, filtering, presentation, or navigation policy	Consuming application
New configuration entry supported by an existing plugin model	Existing plugin
New API call that belongs to an existing plugin's business domain	Existing plugin
Shared mapping, normalisation, or aggregation required by multiple consumers	Existing plugin
New public method or type within an existing plugin's purpose	Existing plugin, with compatibility review
Behaviour spanning unrelated plugin domains	Discuss with the Web Platform team
New provider, authentication model, security boundary, or cross-frame protocol	Web Platform team approval
New plugin package	Web Platform team approval before implementation

Do not create a new plugin because the existing package API is inconvenient. First check whether the change belongs in an existing plugin, a consumer-owned wrapper, or a new explicit extension hook.

Changes an agent can implement

An AI or contributor can implement a bounded existing-plugin change when all of these conditions are true:

• the requirement clearly fits the plugin purpose documented on its page;
• the upstream API, configuration value, or mapping is already approved;
• existing package-root imports remain compatible;
• no authentication, authorisation, privacy, or secret-handling boundary changes;
• tests can describe the new behaviour without relying on production data;
• the plugin page and public exports can be updated in the same change.

Typical examples include:

• adding an approved menu or portfolio endpoint to an existing configuration;
• adding a route rule to an existing rule table;
• adding a new mapping entry to an existing navigation or toggle config;
• adding a typed API helper beside related helpers;
• extending an existing response type with an optional field;
• adding tests for a newly approved client type or environment value.

Changes that require approval

Stop and contact the Web Platform team before implementation when the change:

• creates, renames, splits, or removes a plugin;
• changes a published package name or removes a public export;
• introduces a breaking payload, state, event, or lifecycle change;
• changes authentication, authorisation, cookies, tokens, permissions, trusted origins, redaction, or customer-data handling;
• introduces a new third-party provider or dependency;
• adds platform-owned routes or changes proxy ownership;
• changes cross-frame messaging or Invsy protocol identifiers;
• changes shared fallback, caching, retry, or error semantics;
• substantially restructures a stateful builder or moves responsibility between plugins;
• cannot be proven safe from the plugin's tests and documented contract.

Security- and privacy-sensitive plugins can have stricter rules on their individual pages.

Implement an existing-plugin change

1. Read the plugin page and its source_of_truth files.
2. Confirm that the requirement belongs to the plugin's stated purpose.
3. Identify the existing extension location: API helper, environment config, rule table, mapping table, state object, or public method.
4. Preserve existing package-root imports and default behaviour.
5. Add or update types before using new response data.
6. Handle unsuccessful HTTP responses and malformed data explicitly.
7. Add focused unit tests for success, failure, and relevant environment or client conditions.
8. Export a new supported API through src/index.ts.
9. Update the plugin page with the new configuration, API, prerequisites, and failure behaviour.
10. Build and test the affected Nx project.
11. Use the package pipeline for publication.
12. Update the platform dependency and verify the consuming platform separately.

A plugin publication does not update the platform automatically. The platform must consume the released version through its own reviewed dependency and deployment process.

API addition checklist

• [ ] The endpoint is owned by the same business domain as the plugin.
• [ ] The route and authentication model are approved.
• [ ] Environment differences are represented in the existing environment configuration where required.
• [ ] Request and response types are explicit.
• [ ] HTTP errors and invalid responses do not become success-shaped data.
• [ ] Customer data, tokens, and headers are not logged.
• [ ] The API can be tested with synthetic fixtures.
• [ ] The public export and documentation are updated.

Configuration addition checklist

• [ ] The entry belongs in the existing configuration table.
• [ ] All supported environments are considered.
• [ ] Identifiers, priorities, and paths do not collide with existing entries.
• [ ] Default behaviour remains unchanged for unrelated consumers.
• [ ] Tests cover the new match or mapping and a non-match.
• [ ] Rollback consists of removing or reverting the isolated entry.

Related pages

• Plugin overview
• Extension patterns
• Workspace setup and publishing