## Classes

<dl>
<dt><a href="#SDK">SDK</a></dt>
<dd><p>A programmatic API to build flow-nodes.</p>
</dd>
</dl>

## Functions

<dl>
<dt><a href="#actionHandler">actionHandler(params, options)</a> ⇒ <code>*</code></dt>
<dd><p>An async function that implements an flow-node method and is assigned via
<a href="#SDK+action">action</a>.</p>
</dd>
</dl>

<a name="SDK"></a>

## SDK
A programmatic API to build flow-nodes.

**Kind**: global class  

* [SDK](#SDK)
    * [new SDK([options])](#new_SDK_new)
    * [.add(key, [options])](#SDK+add) ⇒ [<code>SDK</code>](#SDK)
    * [.method(key, [options])](#SDK+method) ⇒ [<code>SDK</code>](#SDK)
    * [.group(name)](#SDK+group) ⇒ [<code>SDK</code>](#SDK)
    * [.parameter(name, schema, [options])](#SDK+parameter) ⇒ [<code>SDK</code>](#SDK)
    * [.output(key, [options])](#SDK+output) ⇒ [<code>SDK</code>](#SDK)
    * [.action(handler, [options])](#SDK+action) ⇒ [<code>SDK</code>](#SDK)
    * [.load(file, actions, [options])](#SDK+load) ⇒ [<code>SDK</code>](#SDK)
    * [.getPlugin()](#SDK+getPlugin) ⇒ <code>object</code>

<a name="new_SDK_new"></a>

### new SDK([options])
Constructs the SDK to build flow-node(s) and prepares the `SDK` to
accept the following operations:
 * [.add(key, [options])](#SDK+add) used to add a flow-node
   programmatically.
 * [.load(file, actions, [options])](#SDK+load) used to add
   flow-nodes via an external plugin specification document.

When done with your flow-node definition, you can call
[getPlugin](#SDK+getPlugin) and export this from the entry point of your main
module so that your plugin may be imported by API Builder on startup.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [options] | <code>object</code> |  | The options for the builder. |
| [options.validate] | <code>boolean</code> | <code>false</code> | Enables parameter validation. Disable if you need to use refs. |
| [options.pluginConfig] | <code>object</code> |  | Configuration object passed from API Builder to `getPlugin` in `index.js`. This will be available in all action methods. |

<a name="SDK+add"></a>

### sdK.add(key, [options]) ⇒ [<code>SDK</code>](#SDK)
Adds a new flow-node and prepares the `SDK` to accept the following
SDK operations:
 * [.method(key, [options])](#SDK+method) used to add a method to
   flow-node.

The `key` parameter is used to uniquely identify the flow-node and
represents a distinct instance of a node for the flow editor.

The `options` provide additional settings for the flow-node.
The flow-node will use `key` as the `name` if the `name` option is not
provided. The `icon` option can be bmp, jpeg, png, gif, tiff, or svg
file. The new node will appear under the "general" category by default,
or under the provided `category` option.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: [<code>SDK</code>](#SDK) - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| key | <code>string</code> |  | A unique key identifier for the node. |
| [options] | <code>object</code> |  | Options for the node. |
| [options.name] | <code>string</code> |  | A friendly name for the node as it will appear in the UI.  Defaults to `key` if not provided. |
| [options.icon] | <code>string</code> |  | The absolute path to an icon file. |
| [options.description] | <code>string</code> |  | A description for the flow-node. |
| [options.category] | <code>string</code> | <code>&quot;general&quot;</code> | A category under which the node will appear in the UI. |

**Example**  
```js
sdk.add('encodeURI', {
	icon: path.join(__dirname, 'encode.svg'),
	name: 'Encode URI',
	description: 'Encodes a URI string',
	category: 'utils'
});
```
<a name="SDK+method"></a>

### sdK.method(key, [options]) ⇒ [<code>SDK</code>](#SDK)
Adds a new method to the current node flow-node and prepares the `SDK`
to accept the following method operations:
- [.parameter(name, schema, [options])](#SDK+parameter) used to add
  a parameter to the method.
- [.output(key, options)](#SDK+output) used to add an output to
  the method.
- [.action(handler, options)](#SDK+action) used to assign an action
  handler function to the method and finish the method definition.

[.add(key, [options])](#SDK+add) must be called prior to this.

The `key` uniquely identifies the method for the node and will be used
as the name unless the `name` option is provided.

The `options` provide additional settings for the method.

Calling [action](#SDK+action) terminates the method definition.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: [<code>SDK</code>](#SDK) - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | A unique key identifier for the method. |
| [options] | <code>object</code> | Options for the method. |
| [options.name] | <code>string</code> | A friendly name for the method as it will appear in the UI.  If not set, defaults to `key`. |
| [options.description] | <code>string</code> | A description for the method. |

**Example**  
```js
sdk.add('encodeURI')
	.method('encode', { name: 'Encode URI' });
```
**Example** *(Enable parameter JSON schema validation)*  
```js
sdk.add('encodeURI')
	.method('encode', { $ref: '#/definitions/foo' });
```
<a name="SDK+group"></a>

### sdK.group(name) ⇒ [<code>SDK</code>](#SDK)
Adds a parameter group to the [method](#SDK+method) and prepares the `SDK`
and affects the following methods:
- [.parameter(name, schema, [options])](#SDK+parameter) used to add
  a parameter to the method.

[.method(key, [options])](#SDK+method) must be called prior to this.

Any [parameter](#SDK+parameter) added after adding a group will automatically
be added to the group.  Therefore, you need to add all your ungrouped
parameters first, before calling [group](#SDK+group).

Calling [action](#SDK+action) terminates the method definition and the
parameter group.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: [<code>SDK</code>](#SDK) - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| name | <code>string</code> | A unique name for the parameter group as it will appear in the UI.  The name _Authorization_ has special meaning in that it begins a group for Authorization parameters that allows credential type inputs. |

**Example**  
```js
sdk.add('encodeURI')
	.method('encode', { name: 'Encode URI' })
	.group('Advanced')
	.parameter('uri', { type: 'string' });
```
<a name="SDK+parameter"></a>

### sdK.parameter(name, schema, [options]) ⇒ [<code>SDK</code>](#SDK)
Adds a new parameter to the current method. Any number of parameters can
be added to a method.

[.method(key, [options])](#SDK+method) must be called prior to this.

The `name` uniquely identifies the parameter. The `schema` is a valid
[JSON Schema](http://json-schema.org) definition (both
[draft-04](http://json-schema.org/draft-04/schema) and
[draft-06](http://json-schema.org/draft-06/schema) are supported).

The `options` provide additional settings for the parameter.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: [<code>SDK</code>](#SDK) - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| name | <code>string</code> |  | A unique name for the parameter as it will appear in the UI. |
| schema | <code>object</code> |  | A schema used to validate the parameter. |
| [options] | <code>object</code> |  | Specifies additional options to configure the parameter. |
| [options.required] | <code>boolean</code> | <code>true</code> | specifies that the parameter is required. |
| [options.multilineWrapper] | <code>object</code> |  | Describes the before and after parts that surrounds user provided value in the UI. |
| options.multilineWrapper.before | <code>string</code> |  | Read-only string that is placed before the user provided value in the UI. |
| options.multilineWrapper.after | <code>string</code> |  | Read-only string that is placed after the user provided value in the UI. |
| [options.initialType] | <code>string</code> |  | The type to display by default in the UI for this parameter. Allowed values are object, array, string, selector, null, boolean, and number. |

**Example**  
```js
sdk.add('encodeURI')
	.method('encode', { name: 'Encode URI' })
	.parameter('uri', { type: 'string' });
```
<a name="SDK+output"></a>

### sdK.output(key, [options]) ⇒ [<code>SDK</code>](#SDK)
Adds a new output to the current method.  Any number of outputs can be
added to a method, but for usability-sake, you should limit this.  The
`output` represents one of the possible callback routes for your method.
For example, if your method tested if a number was a prime number, then
the first output should be `next`, meaning it was a prime number, and
the other output `error`, would mean that there was some kind of
unexpected error.

[.method(key, [options])](#SDK+method) must be called prior to this.

The `key` uniquely identifies the output route.  The `schema` is a
valid
[JSON Schema](http://json-schema.org) definition (both
[draft-04](http://json-schema.org/draft-04/schema) and
[draft-06](http://json-schema.org/draft-06/schema) are supported).
If `schema` is not provided, then the output type is effectively _any_
type.

The `options` provide additional settings for the output.  The `context`
is a valid [JSON Path](https://github.com/json-path/JsonPath)
and is used as the default by the flow editor.  When the output is
invoked, the configured context is where the output value will be
written.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: [<code>SDK</code>](#SDK) - The current object (this).  
**Access**: public  

| Param | Type | Description |
| --- | --- | --- |
| key | <code>string</code> | A unique key for the output. |
| [options] | <code>object</code> | output options |
| [options.name] | <code>string</code> | A friendly name for the output as it will appear in the UI. |
| [options.description] | <code>string</code> | The output description. |
| [options.context] | <code>string</code> | The default context string. |
| [options.schema] | <code>object</code> | The expected JSON schema for the output value. |

**Example**  
```js
sdk.add('encodeURI')
	.method('encode', { name: 'Encode URI' })
	.parameter('uri', { type: 'string' })
	.output('next', { context: '$.encodedURI', schema: { type: 'string' } });
```
<a name="SDK+action"></a>

### sdK.action(handler, [options]) ⇒ [<code>SDK</code>](#SDK)
Assigns an action [`handler`](#actionHandler) to the current method.
The method can only have one action handler. Assigning an action will
terminate the current method definition.

[.method(key, [options])](#SDK+method) must be called prior to this.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: [<code>SDK</code>](#SDK) - The current object (this).

The `options` provide additional settings for the action.  The
`pluginContext` can be used to provide a global context to the action
method at runtime.  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| handler | [<code>actionHandler</code>](#actionHandler) |  | The action [actionHandler](#actionHandler) that implements the flow-node method. |
| [options] | <code>Object</code> | <code>{}</code> | The action options. |
| [options.pluginContext] | <code>\*</code> |  | The pluginContext value. |

**Example**  
```js
sdk.add('encodeURI')
	.method('encode', { name: 'Encode URI' })
	.parameter('uri', { type: 'string' })
	.output('next', { context: '$.encodedURI', schema: { type: 'string' } })
	.action(async params => encodeURI(params.uri));
```
**Example**  
```js
sdk.add('decodeURI')
	.method('decode', { name: 'Decode URI' })
	.parameter('uri', { type: 'string' })
	.output('next', { context: '$.decodedURI', schema: { type: 'string' } })
	.action(action.decode, { pluginContext });
```
<a name="SDK+load"></a>

### sdK.load(file, actions, [options]) ⇒ [<code>SDK</code>](#SDK)
Loads a plugin via a specification file.

The `file` supports both JSON or YAML.  The `actions` is an object where
each [method](#SDK+method) key that is defined in the `file` has a
corresponding function that defines the method implementation.

The `options` provide additional settings for the loader.  You can
provide a `pluginContext` through the load `options` that would be
available to all action methods via their `options` parameter.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: [<code>SDK</code>](#SDK) - The current object (this).  
**Access**: public  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| file | <code>string</code> |  | The absolute path to the JSON or YAML file. |
| actions | <code>object</code> |  | An object where each key name corresponds to a method key defined in the specification. |
| [options] | <code>Object</code> | <code>{}</code> | The plugin options. |
| [options.pluginContext] | <code>\*</code> |  | The context that will be passed to all `action` methods. |

**Example**  
```js
sdk.load(path.join(__dirname, 'flow-nodes.yaml'), { encode });
```
<a name="SDK+getPlugin"></a>

### sdK.getPlugin() ⇒ <code>object</code>
Gets the plugin specification.

**Kind**: instance method of [<code>SDK</code>](#SDK)  
**Returns**: <code>object</code> - Returns the plugin specification.  
**Access**: public  
<a name="actionHandler"></a>

## actionHandler(params, options) ⇒ <code>\*</code>
An async function that implements an flow-node method and is assigned via
[action](#SDK+action).

**Kind**: global function  
**Returns**: <code>\*</code> - The response value (resolves to "next" output, or if the method
does not define "next", the first defined output).  

| Param | Type | Description |
| --- | --- | --- |
| params | <code>object</code> | A map of all the parameters passed from the flow. |
| options | <code>object</code> | The additional options provided from the flow engine. |
| options.pluginConfig | <code>object</code> | The service configuration for this plugin from API Builder config.pluginConfig['api-builder-plugin-pluginName'] |
| options.logger | <code>object</code> | The API Builder logger which can be used to log messages to the console. When run in unit-tests, the messages are not logged.  If you wish to test logging, you will need to create a mocked logger (e.g. using `simple-mock`) and override in `MockRuntime.loadPlugin`.  For more information about the logger, see: https://docs.axway.com/bundle/api-builder/page/docs/developer_guide/project/logging/index.html |
| [options.pluginContext] | <code>\*</code> | The data provided by calling `sdk.setContext(pluginContext)` in `getPlugin` in `index.js`. |