Rivet Enter Plugin

This project contains the custom Rivet plugin for Enter.

• Using the plugin
  • In Rivet
  • In Code
• Black Pearl OAuth authentication
• Publishing to npm
  • Manual release
  • Future GitHub Actions workflow
• Updating installed plugins
• Making your own plugin
  • ⚠️ Important Notes ⚠️
  • 1. Plugin Definition
  • 2. Node Definitions
  • 3. Bundling
  • 4. NPM
• Local Development

Using the plugin

In Rivet

To use this plugin in Rivet:

1. Open the plugins overlay at the top of the screen.
2. Go to "NPM Plugin" on the bottom of the list and click on "Add" button.
3. Enter "enter-rivet-plugin" for the package name and use "latest" or a specific published version.
4. Click the "Add" button to install the plugin into your current project.

In Code

Load your plugin and Rivet into your application:

import * as Rivet from "@ironclad/rivet-core";
import enterPlugin from "enter-rivet-plugin";

Register the plugin with Rivet by using the globalRivetNodeRegistry or creating a new NodeRegistration and registering with that:

Rivet.globalRivetNodeRegistry.registerPlugin(enterPlugin(Rivet));

Black Pearl OAuth authentication

In Rivet, open Settings → Enter, set Black Pearl API URL to the protected API (for example https://dev.service.app.talismanai.co) and OAuth login URL to the official login page (for example https://dev.admin.getenter.ai/login). A JSON callback URL and redirect_uri are not required.

Deploy Project, Data Fetcher V1, Fetch Input, Talisman LLM, and Intelligence share this login flow. When the API key is missing, empty, or whitespace-only, Rivet opens an isolated Chrome window before making the protected request. Sign in normally. Rivet captures the JWT from an Authorization: Bearer <jwt> request made by the login app to the exact origin configured in Black Pearl API URL, after that request receives a successful HTTP response. Requests to Google or unrelated origins and rejected tokens are ignored. If the login app has not yet called the configured API, open a page in it that does so.

Rivet reuses the captured token as Authorization: Bearer <jwt> for plugin calls. JWT exp supplies the session lifetime when present. With a current Rivet build, nodes and later runs of the same open project reuse that session; concurrent requests share one login window. Closing the project/app (or disconnecting the Node debugger) clears the authentication cache. With an API key configured, OAuth remains a fallback for HTTP 401/403 and OAuth redirects. Fetch Input uses graph-provided content without signing in when no API call is necessary.

Use a Rivet desktop build and rebuilt executor sidecar with header-capture support. Older builds retain API-key-only behavior when no OAuth URL is configured.

Run plugin regression tests with node --test test/*.test.mjs and a compatible @ironclad/rivet-core. During development, RIVET_CORE_MODULE can point to that core module; loading TypeScript source also requires tsx.

Publishing to npm

The npm package is enter-rivet-plugin. Rivet downloads package metadata from https://registry.npmjs.org/enter-rivet-plugin/<tag-or-version>, then downloads the tarball identified by that metadata and loads dist/bundle.js. latest is an npm distribution tag, not a Git branch.

There is currently no publishing workflow in this repository. Merging a PR, pushing a Git tag, or creating a GitHub release does not publish the package to npm automatically.

Manual release

Use an npm account with publishing permission for enter-rivet-plugin and complete any authentication or two-factor verification requested by npm.

1. Merge the intended changes and update your local main checkout:

   git switch main
   git pull --ff-only origin main
   yarn install --immutable
   

2. Check the published version, choose a previously unused version, and build. The example below increments the local patch version:

   npm view enter-rivet-plugin@latest version
   npm version patch --no-git-tag-version
   yarn build
   npm pack --dry-run --ignore-scripts
   

   Review the package contents, including dist/bundle.js and its declarations. Commit the version changes in package.json and package-lock.json, along with any intended generated distribution changes, through the normal review process. Publish from the resulting release commit.

3. Publish the built package and update the latest tag:

   npm login
   npm whoami
   npm publish --ignore-scripts --access public --tag latest
   

   Run this explicit command rather than yarn publish or npm run publish. The existing publish script uses the invalid --access private option and calls npm publish from npm's publish lifecycle. --ignore-scripts bypasses that script; the build must be completed separately first. This unscoped package is published publicly.

4. Verify that npm's latest tag points to the version you just released:

   npm view enter-rivet-plugin dist-tags --json
   

An existing npm package/version combination cannot be overwritten. If another release has already used the selected version, choose a new version before publishing. See the npm publishing documentation.

Future GitHub Actions workflow

Create release automation in this repository, talismanai/rivet-plugin, at .github/workflows/publish.yml. It is not part of the Rivet desktop repository. The workflow has not been implemented yet.

A suitable release flow is:

1. Merge a version bump and the intended plugin changes.
2. Push a version tag such as v0.1.11 on the release commit.
3. Have the workflow verify that the tag matches package.json, install locked dependencies, build, inspect the package, and publish it to npm with latest.

Prefer npm trusted publishing with GitHub Actions OIDC. In the npm package's trusted-publisher settings, configure owner talismanai, repository rivet-plugin, workflow filename publish.yml, and allow publishing. If a GitHub environment is used, its name must also match. The publishing job needs contents: read and id-token: write, a supported GitHub-hosted runner, and a Node/npm version supported by npm trusted publishing. This avoids storing a long-lived npm publishing token in GitHub secrets.

Correct the existing publish script before adopting it in automation, or keep building explicitly and use the explicit publish command shown above.

Updating installed plugins

A project using the following entry tracks the version published under npm's latest tag:

- id: enter-rivet-plugin@latest
  package: enter-rivet-plugin
  tag: latest
  type: package

When Rivet loads the plugin, it compares the installed version with the npm version and reinstalls it if a newer version is available. Restart Rivet and reopen the project to load an update. To pin a release, use its version in both id and tag, for example [email protected] and 0.1.11 after that version has been published.

On macOS, the default installation directory is:

~/Library/Application Support/com.ironcladapp.rivet/plugins/enter-rivet-plugin-latest/package

Local development synchronization places a .git marker in that directory. While it exists, Rivet skips npm reinstalls so local changes are preserved. Use the local synchronization commands below to update that copy. To return to npm-managed installation, quit Rivet and move the entire enter-rivet-plugin-latest cache directory somewhere safe; reopen the project to download the published package again.

Publishing the plugin does not update the Rivet application. The OAuth feature requires a compatible Rivet desktop build and rebuilt executor sidecar, plus Chrome/Chromium installed on the user's machine.

Making your own plugin

⚠️ Important Notes ⚠️

• You must bundle your plugins, or include all code for your plugin in the ESM files. Plugins are loaded using import(pluginUrl) so must follow all rules for ESM modules. This means that you cannot use require or module.exports in your plugin code. If you need to use external libraries, you must bundle them.

• You also cannot import nor bundle @ironclad/rivet-core in your plugin. The rivet core library is passed into your default export function as an argument. Be careful to only use import type statements for the core library, otherwise your plugin will not bundle successfully.

This repository has examples for both bundling with ESBuild and only importing types from @ironclad/rivet-core.

1. Plugin Definition

Follow the example in src/index.ts to define your plugin. Your plugin must default-export a function that takes in the Rivet Core library as its only argument, and returns a valid RivetPlugin object.

2. Node Definitions

Follow the example in src/nodes/ExamplePluginNode.ts to define your plugin's nodes. You should follow a simlar syntax of exporting functions that take in the Rivet Core library.

• Nodes must implement PluginNodeDefinition<T> by calling pluginNodeDefinition(yourPluginImpl, "Node Name").
• Node implementations must implement PluginNodeImpl<T>.
• T should be your plugin's type definition.

3. Bundling

See bundle.ts for an example of how to bundle your plugin. You can use any bundler you like, but you must bundle your plugin into a single file. You can use the ESBuild bundler to bundle your plugin into a single file.

It is important that all external libraries are bundled, because browsers cannot load bare imports.

4. NPM

Publish the plugin to npm so that Rivet users can install it through the UI or SDK. See Publishing to npm for this repository's release procedure.

Local Development

1. Run yarn dev to start the compiler and bundler in watch mode. This will automatically recombine and rebundle your changes into the dist folder. This will also copy the bundled files into the plugin install directory.
2. After each change, you must restart Rivet to see the changes.

For a one-time build and synchronization of the checked-out source:

yarn build
yarn exec tsx bundle.ts --sync

The synchronization copies dist and package.json to Rivet's local plugin installation and marks it as a local development copy. Restart Rivet afterward. No npm release is created by these commands.

Copy the OAuth JWT into project context

In Settings → Enter, set OAuth token context key beside OAuth login URL to a name such as apiJwt. Leave it blank to disable copying. After a successful login, and whenever the authenticated session is reused, Rivet writes Bearer <jwt> to that key as a secret string in the project's context. An existing value at that key is replaced; other context entries are preserved.

Use a Context node with that ID and String data type to read it. During the first run, arrange execution so the Context node runs after an authenticated node. A Context node that already ran does not execute again automatically. Token refresh replaces the copied value. The context value is a copy, not the authentication cache; it does not keep a login valid after the cache expires or the app closes.

This opt-in value follows Rivet's existing project-context storage and persistence; the secret flag masks it in the UI and does not encrypt it. This feature requires both the updated Enter plugin and a Rivet build supporting OAuth context mirroring.

Sign in before running a node

Open a project and go to Settings → Enter. Set Black Pearl API URL and OAuth login URL, then click Sign in beside the login URL. This always opens a fresh login, even when a JWT is cached, and does not execute an API request or deploy the project. The result replaces the project's session and updates OAuth token context key with Bearer <jwt> when that field is configured. Subsequent nodes reuse the session in both desktop and Node executors, including when the Node executor connects after sign-in. Cancelling preserves an existing working session. Closing Settings or switching projects cancels an unfinished login.

Automatic token capture

Set OAuth login URL to the official platform login page. Rivet automatically captures a valid Bearer JWT from a successful HTTP request initiated by that page. The API hostname and path used by the login page can change without updating Rivet settings, and may differ from Black Pearl API URL. Requests initiated by Google or unrelated browser frames are excluded. Manual Sign in and node-triggered authentication use the same logic. The JWT is reused for Black Pearl API requests and copied as Bearer <jwt> to the configured context key. No token capture URL needs to be configured; obsolete values are ignored.