liq-integrations

Superseded

This package is deprecated and no longer maintained. Its functionality — the IntegrationsManager hook registry, app.ext.integrations, the 'setup integrations' setup method, the integrationPluginName path variable, and the four /server/plugins/integrations/… endpoints — is now built directly into @liquid-labs/plugable-express 1.0.0-alpha.58 or later. No plugin installation step is needed any more: the capability is always present on a plugable-express server.

Migrating

There are two ways this package might currently be in your server, and repointing looks different for each.

• Declared as an npm dependency (e.g. in a package.json's dependencies, with a matching entry in an explicitPlugins array passed to appInit()): remove the @liquid-labs/liq-integrations entry from dependencies, remove it from explicitPlugins, drop it from any test that asserts an expected plugin list, and reinstall (npm install). Nothing replaces it — the capability becomes implicit in @liquid-labs/plugable-express itself, and no new dependency is added.

• Installed at runtime (via catalyst server plugins handlers add -- npmName=@liquid-labs/liq-integrations, the route this README used to advertise): remove it with the corresponding removal command, e.g.:

  catalyst server plugins remove -- npmName=@liquid-labs/liq-integrations

  Where catalyst may be replaced by the CLI for the particular plugable-express-based server. This is the case with no repository to grep — there's nothing tracked in source control to search for — so it has to be found and removed by hand.

Repointing is not urgent. plugable-express skips this package with a warning if it is still installed, so an unchanged server keeps starting cleanly; migration is cleanup, not a breaking change to react to on a deadline.

Provider installation

Installing an integration provider still works the same way, since that endpoint is now served by plugable-express itself rather than by this package:

catalyst server plugins integrations add -- npmName=@liquid-labs/liq-integrations-issues-github

Where catalyst may be replaced by the CLI for the particular plugable-express-based server. @liquid-labs/liq-integrations-issues-github itself is unaffected by this retirement and needs no change — it couples only to app.ext.integrations and to a setup method carrying deps: ['setup integrations'], both of which plugable-express now provides directly.

Integrations overview

This section documents the mechanism as it now lives in plugable-express; it is retained here as the functional spec the port preserves. It is aimed primarily at those seeking a deeper understanding of how integrations work, e.g. integration developers. Casual users can skip this section.

Structure

An integration spec defines a single integration:

• hooks: an object containing hook functions referenced by name. The hook functions are what are ultimately executed by IntegrationsManager.callHook(). Every integration which is a providerFor a particular thing will define the same set of hooks. The hooks are "what the integration can do".
• name: a simple name describing the integration spec. (The use of name is still in flux and may be dropped.)
• npmName: the name of the package providing the integrations.
• providerFor: a noun or verb naming the thing (e.g. 'tickets'). The providerFor value is used by IntegrationsManager.callHook() to for first-level selection of possible integration providers.
• providerTest: a test function which decides whether this integration fits this project. The provider test always receives pkgJSON, which is the package.json value for the project being acted upon and may receive additional arguments depending on the providerFor type.

Flow

1. On startup, appInit() pushes a 'setup integrations' setup method that sets app.ext.integrations = new IntegrationsManager(), and registers the integrationPluginName path variable used by the plugin-management endpoints.
2. Each integration provider package registers itself independently: it pushes its own setup method carrying deps: ['setup integrations'] (so it runs after the manager exists) and calls app.ext.integrations.register(...) to add its integration spec. @liquid-labs/liq-integrations-issues-github is the live example of this pattern.
3. When an integration is required (e.g., to create a pull request), instead of calling a function directly, IntegrationsManager.callHook() is invoked with the following parameters:
   • providerFor: a string naming the integration basic domain / purpose (e.g., 'pull requests')
   • providerArgs: a parameter object containing the pkgJSON for the project in question and (depending on the providerFor type) possibly additional arguments.
   • hook: the name of the specific hook in the integrations to be invoked (e.g., 'createOrUpdatePullRequest').
   • hookArgs: a parameter object containing arguments particular to the hook.
4. The IntegrationsManager.callHook() will filter the available integrations based on providerFor and then the integrations providerTest. Once found, the integrations hook is invoked with the caller's hookArgs. If no applicable integration is found, then an exception is raised.

Note in theory, it would be possible to find an integration based on the hook name alone but we retain providerFor as it clarifies things and to make determination of providerArgs content more clear in particular. There is also the thought that it helps avoid hook name collisions in future.

Known consumers

As of this retirement:

• @sdlcforge/core-server — the only project that declares this package as an npm dependency, with a matching entry in the explicitPlugins array passed to appInit(). Repointing is deletion of both, plus dropping the package from any test's expected-plugin-list assertions.
• plugable-registry's registry.yaml — carries a catalog entry, membership in the sdlcpilot-github-node server bundle, and two dependencies references. All four are to be removed once this retirement publishes.

@liquid-labs/liq-integrations-issues-github, @liquid-labs/liq-work, and @liquid-labs/liq-controls are not npm dependents of this package — they couple only to the runtime contract (app.ext.integrations, deps: ['setup integrations']) that plugable-express now provides directly — and need no change.