Interface: BaseFormulaDef<ParamDefsT, ResultT>¶

OAuth scopes that the formula needs that weren't requested in the pack's overall authentication config. For example, a Slack pack can have one formula that needs admin privileges, but non-admins can use the bulk of the pack without those privileges. The platform will give users help in understanding that they need additional authentication to use a formula with extra OAuth scopes. Note that these scopes will always be requested in addition to the default scopes for the pack, so an end user must have both sets of permissions.

Inherited from¶

PackFormulaDef.extraOAuthScopes

instructions?¶

readonly optional instructions: string

Instructions for LLMs to use the formula, overrides the description for LLMs if set.

Inherited from¶

PackFormulaDef.instructions

isAction?¶

readonly optional isAction: boolean

Does this formula take an action (vs retrieve data or make a calculation)? Actions are presented as buttons in the Superhuman Docs UI.

Inherited from¶

PackFormulaDef.isAction

isExperimental?¶

readonly optional isExperimental: boolean

If specified, the formula will not be suggested to users in the formula autocomplete. The formula can still be invoked by manually typing its full name.

Inherited from¶

PackFormulaDef.isExperimental

isSystem?¶

readonly optional isSystem: boolean

Whether this is a formula that will be used internally and not exposed directly to users. Not for use by packs that are not Superhuman-authored.

Inherited from¶

PackFormulaDef.isSystem

name¶

readonly name: string

The name of the formula, used to invoke it.

Inherited from¶

PackFormulaDef.name

network?¶

readonly optional network: Network

Deprecated¶

use isAction and connectionRequirement instead

Inherited from¶

PackFormulaDef.network

parameters¶

readonly parameters: ParamDefsT

The parameter inputs to the formula, if any.

Inherited from¶

PackFormulaDef.parameters

validateParameters?¶

optional validateParameters: MetadataFormula<ExecutionContext, ParameterValidationResult>

The JavaScript function that implements parameter validation. This is only allowed on sync formulas.

This function takes in parameters and a context containing a PermissionSyncMode and validates the parameters. A formula may want to validate parameters differently for permissionSyncMode 'PermissionAware' vs 'Personal' vs undefined (which represents a formula).

Example¶

validateParameters: async function (context, _, params) {
  let {quantity, sku} = ensureExists(params);
  let errors = [];
  if (quantity < 0) {
    errors.push({message: "Must be a positive number.", propertyName: "quantity"});
  }
  if (!isValidSku(context, sku)) {
    errors.push({message: `Product SKU not found.`, propertyName: "sku"});
  }
  if (errors.length > 0) {
    return {
      isValid: false,
      message: "Invalid parameter values.",
      errors,
    };
  }
  return {
    isValid: true,
  };
},

Returns¶

a ParameterValidationResult

Inherited from¶

PackFormulaDef.validateParameters

varargParameters?¶

readonly optional varargParameters: ParamDefs

Variable argument parameters, used if this formula should accept arbitrary numbers of inputs.

Only supported in Superhuman Docs.

Inherited from¶

PackFormulaDef.varargParameters

Methods¶

execute()¶

execute(params, context): ResultT | Promise<ResultT>

The JavaScript function that implements this formula

Parameters¶

Parameter	Type
`params`	`ParamValues`<`ParamDefsT`>
`context`	`ExecutionContext`

Returns¶

ResultT | Promise<ResultT>

Inherited from¶

PackFormulaDef.execute

onError()?¶

optional onError(error): any

If specified, will catch errors in the execute function and call this function with the error, instead of letting them throw and the formula failing.

This is helpful for writing common error handling into a singular helper function that can then be applied to many different formulas in a pack.

Parameters¶

Parameter	Type
`error`	`Error`

Returns¶

any

Inherited from¶

OnErrorFormulaOptions.onError