The API toolkit to facilitate mochabug adapt plugin development
npm install @mochabug/adapt-sdkWelcome to the Mochabug's Adapt Plugins Toolkit, your treasure trove for plugin development! This toolkit is packed with type definitions, classes, functions, and more, all tailored to simplify your plugin crafting journey.
getVariable(name: string): Promise> getVariables(...names: string[]): Promise>> ](#getvariablesnames-string-promiseresultrecordstring-string)getUserVariable(name: string): Promise> getUserVariables(...names: string[]): Promise>> ](#getuservariablesnames-string-promiseresultrecordstring-string)getUserToken(name: string): Promise> getUserTokens(...names: string[]): Promise>> ](#getusertokensnames-string-promiseresultrecordstring-token)userMtls(req: Request, name: string): PromisepluginMtls(req: Request, name: string): Promiseauthorize(token: string): Promise> readFile(path: string): Promise> readDirectory(path: string): Promise> getVertexConfig(fieldMask?: string[]): Promise> ](#getvertexconfigtfieldmask-string-promiseresultt)getBoundGlobalSignal(name: string): Promise> getBoundGlobalSignals(...names: string[]): Promise>> ](#getboundglobalsignalsnames-string-promiseresultrecordstring-any)getLocalStore(namespace: 'vertex' | 'plugin'): StoregetSessionApi(authHeader: string): SessionExecutorApiput(key: string, value: any, options?: PutOptions): thisget(key: string): thisdelete(key: string): thisbuild(): KeyValueOperation[]](#build-keyvalueoperation)constructor(service: T, namespace: N)constructor(env: ExecutorEnvironment, pluginToken: string, sessionAuthHeader: string)getSessionStore(namespace: 'vertex' | 'plugin'): Storeconstructor(env: ExecutorEnvironment, pluginToken: string, sessionAuthHeader: string)listBoundReceiverSignals(pageSize?: number, orderDescending?: boolean): Promise; receiver: string; cursor?: string }>> continueListBoundReceiverSignals(cursor: string): Promise; receiver: string; cursor?: string }>> getBoundReceiverSignal(name: string): Promise> getBoundReceiverSignals(...names: string[]): Promise>> ](#getboundreceiversignalsnames-string-promiseresultrecordstring-any)complete(transmitter: string, signals: { [name: string]: any; }): Promise> ](#completetransmitter-string-signals--name-string-any--promiseresultnever)executeProcedure(name: string, receiver: string, signals: { [name: string]: any; }): Promise> ](#executeprocedurename-string-receiver-string-signals--name-string-any--promiseresultprocedureoperation)getProcedure(id: string): Promise> cancelProcedure(id: string): Promise> startStream(name: string, receiver: string, signals: { [name: string]: any; }): Promise> ](#startstreamname-string-receiver-string-signals--name-string-any--promiseresultnever)cancelStream(name: string): Promise> constructor(env: ConfiguratorEnvironment, pluginToken: string)getVertexConfig(fieldMask?: string[]): Promise> ](#getvertexconfigtfieldmask-string-promiseresult-item-t-errors-configerror-receivererrors-bindingerror-bindingerrors-bindingerror-)patchVertexConfig(value: any): Promise> ](#patchvertexconfigtvalue-any-promiseresult-item-t-errors-configerror-receivererrors-bindingerror-bindingerrors-bindingerror-)postVertexConfig(value: T): Promise> ](#postvertexconfigtvalue-t-promiseresult-item-t-errors-configerror-receivererrors-bindingerror-bindingerrors-bindingerror-)listVertexTransmitters(filter?: string, pageSize?: number, orderBy?: 'vertex' | 'transmitter', orderDescending?: boolean, fieldMask?: string[]): Promise> ](#listvertextransmittersfilter-string-pagesize-number-orderby-vertex--transmitter-orderdescending-boolean-fieldmask-string-promiseresult-items-vertextransmitter-receiver-string-cursor-string-)continueListVertexTransmitters(cursor: string): Promise> ](#continuelistvertextransmitterscursor-string-promiseresult-items-vertextransmitter-receiver-string-cursor-string-)getReceiverName(): Promise> listGlobalSignals(filter?: string, pageSize?: number, orderBy?: 'name_desc' | 'name_asc', fieldMask?: string[]): Promise> ](#listglobalsignalsfilter-string-pagesize-number-orderby-name_desc--name_asc-fieldmask-string-promiseresult-items-globalsignal-cursor-string-)continueListGlobalSignals(cursor: string): Promise> ](#continuelistglobalsignalscursor-string-promiseresult-items-globalsignal-cursor-string-)getGlobalSignal(name: string): Promise> getGlobalSignals(...names: string[]): Promise>> ](#getglobalsignalsnames-string-promiseresultrecordstring-globalsignal)getLocalStore(namespace: 'vertex' | 'plugin'): StoreThe division of the APIs into various parts facilitates the management of underlying OAuth2 scopes specific to different endpoints. Thus, users don't have to delve deep into understanding the underlying scopes.
adaptkit --init or --add commands, the correct routing gets generated without the need for memorization.Installing our toolkit is a piece of cake:
``bash`
npm install @mochabug/adapt-plugin-toolkit
This router is employed when the vertex is executed on external endpoints.
`javascript
import { VertexConfig } from '@mochabug/adapt-plugin-toolkit/api';
import { ExternalExecutorRouter } from '@mochabug/adapt-plugin-toolkit/router';
/**
* Constructs an instance of ExternalExecutorRouter and sets up routes.
*
* @name router
* @type {ExternalExecutorRouter}
*/
export const router = new ExternalExecutorRouter()
/**
* Sets up a GET route for the '/api/config' endpoint.
* Handles authorization and retrieves vertex configuration.
*
* @method add
* @async
*/
.add('GET', '/api/config', async (req, api) => {
const authHeader = req.headers.get('Authorization')!;
const auth = await api.authorize(authHeader.substring('Bearer '.length));
if (!auth.ok) {
return new Response('Unauthorized', { status: 401 });
}
const res = await api.getVertexConfig
return res.ok
? new Response(JSON.stringify(res.data!.item), {
headers: { 'Content-Type': 'application/json' },
})
: new Response(res.errorMessage, { status: res.errorStatus });
})
/**
* Sets up a GET route for displaying a simplified "Hello World" page.
*
* @method add
* @async
*/
.add('GET', '(/?)', async () => {
return new Response(getHelloWorldPage(), {
headers: { 'Content-Type': 'text/html' },
});
});
function getHelloWorldPage(): string {
return
;
}
`$3
The 'InternalExecutorRouter' manages internal execution events, allowing developers to handle events such as start, stop, stream, and procedure.
javascript
import { InternalExecutorRouter } from '@mochabug/adapt-plugin-toolkit/router';/**
* Constructs an instance of InternalExecutorRouter and sets up event handlers.
*
* @name router
* @type {InternalExecutorRouter}
*/
export const router = new InternalExecutorRouter()
/**
* Handles the 'start' event, called when vertex execution begins.
*
* @method onStart
* @async
*/
.onStart(async (req, api) => {
const start = await req.json();
console.log('Start event triggered', start);
})
/**
* Handles the 'stop' event, called when the vertex stops, either from a trigger or forcibly.
*
* @method onStop
* @async
*/
.onStop(async (req, api) => {
console.log('Stop event triggered');
})
/**
* Handles the 'stream' event, called when stream content becomes available.
*
* @method onStream
* @async
*/
.onStream(async (req, api, name) => {
console.log(
Stream event triggered: ${name});
const res = await req.json();
console.log(res);
}) /**
* Handles the 'procedure' event, called when a procedure result is available.
*
* @method onProcedure
* @async
*/
.onProcedure(async (req, api, name) => {
console.log(
Procedure event triggered: ${name});
const res = await req.json();
console.log(res);
}); `$3
This router is employed when the vertex is in the configuration phase. It's always used for a configuring vertex.
javascript
import {
ConfiguratorApi,
Exchange,
SignalDescriptor
} from '@mochabug/adapt-plugin-toolkit/api';
import {
ExternalConfiguratorRouter,
joinPaths
} from '@mochabug/adapt-plugin-toolkit/router';
import { Component, Config } from './types';/**
* Constructs an instance of ExternalConfiguratorRouter.
*
* @name router
* @type {ExternalConfiguratorRouter}
*/
export const router = new ExternalConfiguratorRouter()
/**
* GET handler for configuration retrieval.
*
* @method add
* @async
*/
.add('GET', '/api/config', async (req, api) => {
const authHeader = req.headers.get('Authorization')!;
const auth = await api.authorize(authHeader.substring('Bearer '.length));
if (!auth.ok) {
console.error(auth);
return new Response(auth.errorMessage, { status: auth.errorStatus });
}
const res = await api.getVertexConfig(['config']);
if (!res.ok) {
console.error(res);
return new Response(res.errorMessage, { status: res.errorStatus });
}
const config = res.data!.item;
return new Response(JSON.stringify(config.config), {
headers: { 'Content-Type': 'application/json' },
});
})
/**
* Serves the index.html file.
*
* @method add
* @async
*/
.add('GET', '/', async (req, api) => {
return await readFile(api, 'index.html', req.headers.get('Accept-Encoding'));
})
/**
* Serves other required files.
*
* @method add
* @async
*/
.add('GET', '{*path}', async (req, api, route) => {
return await readFile(api, route.params.path, req.headers.get('Accept-Encoding'));
});
`$3
While currently, this router is only used to export as an empty router, more features will be incorporated into it over time.
javascript
import { InternalConfiguratorRouter } from '@mochabug/adapt-plugin-toolkit/router';export const router = new InternalConfiguratorRouter();
// As more features are added over time, corresponding handlers will be set up here.
`ApiBase Class Documentation
Represents the base class for the API. The executor and configurator APIs extend this class. It is not intended to be used on its own.
Methods
$3
Retrieves the variable with the specified name.
- Parameters:
-
: The name of the variable to retrieve.
- Returns:
- Promise: A promise that resolves to the variable value, or an error result if the variable does not exist.---
$3
Retrieves multiple variables with the specified names.
- Parameters:
-
...names: string[]: The names of the variables to retrieve.
- Returns:
- Promise: A promise that resolves to an object mapping variable names to their values.---
$3
Retrieves the user variable with the specified name.
- Parameters:
-
name: string: The name of the user variable to retrieve.
- Returns:
- Promise: A promise that resolves to the user variable value, or an error result if the user variable does not exist.---
$3
Retrieves multiple user variables with the specified names.
- Parameters:
-
...names: string[]: The names of the user variables to retrieve.
- Returns:
- Promise: A promise that resolves to an object mapping user variable names to their values.---
$3
Retrieves the user token with the specified name.
- Parameters:
-
name: string: The name of the user token to retrieve.
- Returns:
- Promise: A promise that resolves to the user token, or an error result if the user token does not exist.---
$3
Retrieves multiple user tokens with the specified names.
- Parameters:
-
...names: string[]: The names of the user tokens to retrieve.
- Returns:
- Promise: A promise that resolves to an object mapping user token names to their tokens.---
$3
Performs a user mTLS request.
- Parameters:
-
req: Request: The request object.
- name: string: The name of the request.
- Returns:
- Promise: A promise that resolves to the response of the request.---
$3
Performs a plugin mTLS request.
- Parameters:
-
req: Request: The request object.
- name: string: The name of the request.
- Returns:
- Promise: A promise that resolves to the response of the request.---
$3
Authorizes the request using the specified token. Defaults to bearer token authorization.
- Parameters:
-
token: string: The token to use for authorization.
- Returns:
- Promise: A promise that resolves to true if the request is authorized, false otherwise.---
$3
Reads a file from the specified path.
- Parameters:
-
path: string: The path of the file to read.
- Returns:
- Promise: A promise that resolves to the file content and MIME type, or an error result if the file does not exist or the MIME type is not supported.---
$3
Reads a directory from the specified path.
- Parameters:
-
path: string: The path of the directory to read.
- Returns:
- Promise: A promise that resolves to the directory content, or an error result if the directory does not exist or the content is not in the expected format.ExecutorApi
ExecutorApi represents the least privileged Executor API that cannot access the session. It extends the ApiBase class.$3
####
getVertexConfigRetrieves the vertex configuration.
- Parameters:
- fieldMask (optional) - The field mask for the vertex configuration. Type:
- Returns: A promise that resolves to the vertex configuration.####
Retrieves the global signal with the specified name.
- Parameters:
- name - The name of the global signal. Type:
- Returns: A promise that resolves to the global signal or an error result if not found.####
Retrieves multiple global signals with the specified names.
- Parameters:
- names - The names of the global signals. Type:
- Returns: A promise that resolves to an object mapping global signal names to their signals.####
Retrieves a local store instance based on the provided namespace.
- Parameters:
- namespace - The desired namespace for the store. Can be either 'vertex' or 'plugin'.
- Returns: An instance of the
class with the appropriate namespace.####
getSessionApi(authHeader: string): SessionExecutorApiRetrieves the session API from the basic api by setting the correct auth header value (i.e. Bearer ).
- Parameters:
- authHeader - The auth header value to use for the session API (e.g., Bearer ). Type:
- Returns: Returns the .
BatchBuilder
Utility class for building batch operations for the KV store.
$3
####
put(key: string, value: any, options?: PutOptions): thisAdds a
operation to the batch.- Parameters:
- key - The key to set. Type:
string
- value - The value to set for the key. Type:
- options (optional) - Optional settings for the operation. Type: PutOptions
- Returns: The current instance of the builder.####
Adds a
operation to the batch.- Parameters:
- key - The key to retrieve. Type:
string
- Returns: The current instance of the builder.####
Adds a
operation to the batch.- Parameters:
- key - The key to delete. Type:
string
- Returns: The current instance of the builder.####
Finalizes the batch and returns the array of operations.
- Returns: The array of operations.
Store
Represents a store on a specific namespace.
$3
####
Initializes a new instance of the
.- Parameters:
- service - The service instance. Type:
T
- namespace - The namespace. Type: $3
(For brevity, only the method signatures are provided here. You can use a similar format as provided for the
class to describe each method in detail.)-
put(key: string, value: any, options?: PutOptions): Promise
-
-
-
- Related Types and Interfaces
$3
This interface provides additional settings for
operations:- ttl (optional) - Type:
number
- failIfExists (optional) - Type: $3
Represents the result of a batch operation.
- Properties:
- status - The global status for the entire batch operation. Type:
- result - An array containing results of each operation within the batch. Type: StopExecutorApi
represents a basic API with session storage. This provides the available endpoints when a session is stopping. It extends the ExecutorApi class.$3
####
constructor(env: ExecutorEnvironment, pluginToken: string, sessionAuthHeader: string)Creates an instance of
.- Parameters:
- env - The executor environment. Type:
ExecutorEnvironment
- pluginToken - The plugin token from: X-Mochabug-Adapt-Plugin-Token. Type:
- sessionAuthHeader - The privileged authorization header. Type: $3
####
Retrieves a session store instance based on the provided namespace.
- Parameters:
- namespace - The desired namespace for the store. It can be either 'vertex' or 'plugin'.
- 'vertex' maps to
- 'plugin' maps to
- Returns: An instance of the class with the appropriate namespace for the session.SessionExecutorApi
SessionExecutorApi represents the Privileged Executor API and extends the StopExecutorApi class.$3
####
constructor(env: ExecutorEnvironment, pluginToken: string, sessionAuthHeader: string)Creates an instance of
.- Parameters:
- env - The executor environment. Type:
ExecutorEnvironment
- pluginToken - The plugin token from: X-Mochabug-Adapt-Plugin-Token. Type:
- sessionAuthHeader - The privileged authorization header. Type: $3
####
Lists bound receiver signals.
- Parameters:
- pageSize (optional) - The page size for the listing. Type:
- orderDescending (optional) - Indicates whether to order the signals in descending order. Type:
- Returns: A promise that resolves to the list of bound receiver signals.####
Continues listing bound receiver signals.
- Parameters:
- cursor - The cursor to continue listing from. Type:
- Returns: A promise that resolves to the continued list of bound receiver signals.####
Retrieves the bound receiver signal with the specified name.
- Parameters:
- name - The name of the bound receiver signal. Type:
- Returns: A promise that resolves to the receiver signal or an error.####
Retrieves multiple bound receiver signals with the specified names.
- Parameters:
- names - The names of the bound receiver signals. Type:
- Returns: A promise that resolves to a record of bound receiver signals.####
Completes an execution for the specified transmitter and signals.
- Parameters:
- transmitter - The transmitter identifier. Type:
- signals - The signals to be sent. Type:
- Returns: A promise that resolves when the execution is completed or encounters an error.####
Executes a procedure with the specified name, receiver, and signals.
- Parameters:
- name - The name of the procedure. Type:
- receiver - The receiver identifier. Type:
- signals - The signals to be sent. Type:
- Returns: A promise that resolves to the procedure operation or an error.####
Retrieves the procedure operation with the specified ID.
- Parameters:
- id - The ID of the procedure operation. Type:
- Returns: A promise that resolves to the procedure operation or an error.####
Cancels the procedure operation with the specified ID.
- Parameters:
- id - The ID of the procedure operation. Type:
- Returns: A promise that resolves when the procedure operation is canceled or encounters an error.####
Starts the stream with the specified name.
- Parameters:
- name - The name of the stream. Type:
- receiver - The receiver identifier. Type:
- signals - The signals to be sent. Type:
- Returns: A promise that resolves when the stream is started or encounters an error.####
Cancels the stream with the specified name.
- Parameters:
- name - The name of the stream. Type:
- Returns: A promise that resolves when the stream is canceled or encounters an error.ConfiguratorApi
represents the API for the Configurator and extends the ApiBase class.$3
####
constructor(env: ConfiguratorEnvironment, pluginToken: string)Creates an instance of
.- Parameters:
- env - The environment for the Configurator. Type:
ConfiguratorEnvironment
- pluginToken - The plugin token from X-Mochabug-Adapt-Plugin-Token. Type: $3
####
Retrieves the vertex configuration with an optional field mask.
- Parameters:
- fieldMask (optional) - The field mask. Type:
- Returns: A promise that resolves to the updated vertex configuration and errors.####
Patches the vertex configuration with the provided value using JSON Merge Patch (RFC 7396).
- Parameters:
- value - The patch value. Type:
- Returns: A promise that resolves to the updated vertex configuration and errors.####
Posts the vertex configuration with the specified value.
- Parameters:
- value - The updated value. Type:
- Returns: A promise that resolves to the updated vertex configuration and errors.####
Lists the vertex transmitters with optional filters, page size, ordering, and field mask.
- Parameters:
- filter (optional) - The filter. Type:
- pageSize (optional) - The page size. Type:
- orderBy (optional) - The ordering. Type:
- orderDescending (optional) - Indicates if the order is descending. Type:
- fieldMask (optional) - The field mask. Type:
- Returns: A promise that resolves to the list of vertex transmitters, receiver, and cursor.####
Continues the listing of vertex transmitters with the specified cursor.
- Parameters:
- cursor - The cursor. Type:
- Returns: A promise that resolves to the list of vertex transmitters, receiver, and cursor.####
Retrieves the receiver name.
- Returns: A promise that resolves to the receiver name.
####
Lists the global signals with optional filters, page size, ordering, and field mask.
- Parameters:
- filter (optional) - The filter. Type:
- pageSize (optional) - The page size. Type:
- orderBy (optional) - The ordering. Type:
- fieldMask (optional) - The field mask. Type:
- Returns: A promise that resolves to the list of global signals and cursor.####
Continues the listing of global signals with the specified cursor.
- Parameters:
- cursor - The cursor. Type:
- Returns: A promise that resolves to the list of global signals and cursor.####
Retrieves the global signal with the specified name.
- Parameters:
- name - The name of the global signal. Type:
- Returns: A promise that resolves to the global signal, or an error result if not found.####
Retrieves the global signals with the specified names.
- Parameters:
- names - The names of the global signals. Type:
- Returns: A promise that resolves to a record of the global signals.####
Retrieves a local store instance for the configurator based on the provided namespace.
- Parameters:
- namespace - The desired namespace for the configurator store.
maps to ConfiguratorServiceBatchStoreRequest_Namespace.NAMESPACE_VERTEX and 'plugin' maps to ConfiguratorServiceBatchStoreRequest_Namespace.NAMESPACE_PLUGIN. Type: 'vertex' | 'plugin'`@mochabug/adapt-plugin-toolkit s is a community-driven, open-source project, and we warmly welcome your contributions! If you have an idea for a new type, a bug report, or would like to help with documentation, please open an issue or submit a pull request.