Oracle Digital Assistant Node.js SDK

This SDK is the main developer resource for Oracle Digital Asistant integrations in a Node.js express environment. It provides two primary solutions for custom implementations against the Digital Assistant platform:

• Creating Custom Component Services
• Creating Webhooks

SDK Installation

To install the SDK globally:

npm install -g @oracle/bots-node-sdk

To install the SDK locally in your current directory:

npm install @oracle/bots-node-sdk

When installed locally, use npx @oracle/bots-node-sdk instead of just bots-node-sdk to run the command-line interface (CLI) commands described in the Getting Started section.

Getting Started

This section explains the basic CLI commands to get your component service up and running. See the CLI documentation for a complete list of all the arguments and options that you can configure with each command.

Create a Component Service

Use the init command to create a component service package. For example:

bots-node-sdk init PizzaService --name pizza-service 

This example creates a component service named pizza-service in a directory named PizzaService. The component service includes one sample custom component named helloWorld.

Add a Custom Component to Existing Service

You use the init component <name> custom command to add a component to an existing package. For example:

bots-node-sdk init component myCustomComponent custom

This example creates a component of type custom named myCustomComponent. Instead of typing custom for the component type argument, you can type c as a shortcut.

Add an Entity Event Handler to Existing Service

You use the init component <name> entityEventHandler command to add an event handler to an existing package. For example:

bots-node-sdk init component myEventHandler entityEventHandler

This example creates a handler of type entityEventHandler that is named myEventHandler. Instead of typing entityEventHandler for the component type argument, you can type e as a shortcut.

Add an SQL Query Event Handler to Existing Service

You use the init component <name> sqlQueryEventHandler command to add an event handler to an existing package. For example:

bots-node-sdk init component myEventHandler sqlQueryEventHandler

This example creates a handler of type sqlQueryEventHandler that is named myEventHandler. Instead of typing sqlQueryEventHandler for the component type argument, you can type s as a shortcut.

Add an LLM Transformation Handler to Existing Service

You use the init component <name> llmTransformation command to add an event handler to an existing package. For example:

bots-node-sdk init component myEventHandler llmTransformation

This example creates a handler of type LlmTransformation that is named myEventHandler. Instead of typing llmTransformation for the component type argument, you can type t as a shortcut.

Add an LLM Validation & Customization Handler to Existing Service

You use the init component <name> llm command to add the event handler to an existing package. For example:

bots-node-sdk init component myEventHandler llm

This example creates a handler of type LlmComponent that is named myEventHandler. Instead of typing llm for the component type argument, you can type l as a shortcut.

Create a Component Service Package

To package the components, use the pack command. For example:

bots-node-sdk pack

This creates a component service package .tgz file that can be hosted as an express service, uploaded to a skill's embedded container in Digital Assistant, or uploaded to Oracle Mobile Hub.

Deploy as an External Component Service

To start a service on a local node server and host the custom component package, use the start command.

npm start

This example creates a component service running on a local node server. It uses the @oracle/bots-node-sdk dev dependency.

Alternatively, you can use this bots-node-sdk command to start the service. This command uses the global bots-node-sdk installation.

bots-node-sdk service

To see the metadata for all deployed components, run this cURL command:

curl -X GET localhost:3000/components

To deploy to a docker container, you can use the following commands:

npm run-script docker-build
docker-compose up

Using TypeScript

The SDK has full support for TypeScript. If you want to use TypeScript to write your custom components and event handlers, all you need to do is specify the language option when you create the component service. For example:

bots-node-sdk init MyComponentService --language typescript

or the shorter format:

bots-node-sdk init MyComponentService  -l t

This example creates a TypeScript project in the MyComponentService directory.

If you subsequently use the init component command to add a component to a TypeScript project, it creates a TypeScript component instead of a JavaScript component.

When run on a TypeScript project, the service and pack commands transpile all files under the src directory into JavaScript files in the build directory.

The benefit of using TypeScript over JavaScript is that it is strongly typed, so, if you use an editor like Visual Code Studio, you'll get code completion features and compile-time type checking similar to Java.

See the README.md that's created in your scaffolded TypeScript project for more information.

More Information

• Using the CLI - Command line capabilities to facilitate writing custom components and entity event handlers.
• Writing Custom Components - Guidelines and tips for writing custom components.
• Writing Entity Event Handlers - Guidelines and tips for writing entity event handlers.
• Writing SQL Query Event Handlers - Guidelines and tips for writing data query event handlers.
• Writing LLM Transformation Handlers - Guidelines and tips for writing LLM transformation handlers.
• Writing LLM Validation & Customization Handlers - Guidelines and tips for writing LLM validation & customization handlers.
• Conversation Messaging - Creating conversation messages from custom code.
• Writing Webhooks - Integrate with custom messaging channels using incoming/outgoing webhook.
• Unit Testing - Unit testing facilities.
• Documentation - Full SDK documentation.
• Release Notes - List of new features and fixed issues for each release.

Contributing

@oracle/bots-node-sdk is an open source project. See CONTRIBUTING for details.

License

Copyright © 2018-2023, Oracle and/or its affiliates. All rights reserved.

The Universal Permissive License (UPL), Version 1.0