Interface: CommonPackFormulaDef<T>¶

Inputs for creating a formula that are common between regular formulas and sync table formulas.

Extended by¶

Type Parameters¶

Type Parameter
`T` extends `ParamDefs`

Properties¶

cacheTtlSecs?¶

readonly optional cacheTtlSecs: number

Defined in: api_types.ts:597

How long formulas running with the same values should cache their results for.

connectionRequirement?¶

readonly optional connectionRequirement: ConnectionRequirement

Defined in: api_types.ts:589

Does this formula require a connection (aka an account)?

description¶

readonly description: string

Defined in: api_types.ts:556

A brief description of what the formula does.

examples?¶

readonly optional examples: object[]

Defined in: api_types.ts:578

Sample inputs and outputs demonstrating usage of this formula.

params¶

params: (PackFormulaValue | undefined)[]

result¶

result: PackFormulaResult

extraOAuthScopes?¶

readonly optional extraOAuthScopes: string[]

Defined in: api_types.ts:625

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.

instructions?¶

readonly optional instructions: string

Defined in: api_types.ts:561

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

isAction?¶

readonly optional isAction: boolean

Defined in: api_types.ts:584

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

isExperimental?¶

readonly optional isExperimental: boolean

Defined in: api_types.ts:603

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.

isSystem?¶

readonly optional isSystem: boolean

Defined in: api_types.ts:609

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.

name¶

readonly name: string

Defined in: api_types.ts:551

The name of the formula, used to invoke it.

network?¶

readonly optional network: Network

Defined in: api_types.ts:592

Deprecated¶

use isAction and connectionRequirement instead

parameters¶

readonly parameters: T

Defined in: api_types.ts:566

The parameter inputs to the formula, if any.

validateParameters?¶

optional validateParameters: MetadataFormula<ExecutionContext, ParameterValidationResult>

Defined in: api_types.ts:669

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

varargParameters?¶

readonly optional varargParameters: ParamDefs

Defined in: api_types.ts:573

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

Only supported in Superhuman Docs.