{"_id":"@cognigy/create-extension","_rev":"23-932c17c92d94475946292d0c7ae16fdb","name":"@cognigy/create-extension","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@cognigy/create-extension","version":"0.0.1","keywords":["Cognigy.AI","4.0.0","extensions"],"author":{"name":"Cognigy GmbH"},"license":"SEE LICENSE IN LICENSE","_id":"@cognigy/create-extension@0.0.1","maintainers":[{"name":"pedily","email":"kontakt@robinschuster.net"},{"name":"monty0157","email":"kaspermz@hotmail.com"},{"name":"mayrbenjamin92","email":"b.mayr@cognigy.com"}],"homepage":"https://github.com/Cognigy/create-extension#readme","bugs":{"url":"https://github.com/Cognigy/create-extension/issues"},"bin":{"create-extension":"bin/create-extension-folder.js"},"dist":{"shasum":"e6dc9da4f588cb823df150d3cbe18a92b9a1c19f","tarball":"https://registry.npmjs.org/@cognigy/create-extension/-/create-extension-0.0.1.tgz","fileCount":30,"integrity":"sha512-JzT8ZHUoAGo5rMc/2Wi7V1JHhWMQhIZEZgQbIY1bp4414wMzt7c4JfboZWuXtkxh1RLQJGrNNWGVTARQ1Zb99A==","signatures":[{"sig":"MEQCICf284bO1baRjWtHPlDhX7QrOdlIQmAkqHVfe7tD8vA7AiBSf8dWZx45VzJJdrChflb/z4AyyKKBGCYKdNzIy4jOGw==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":49640,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJh2DDHCRA9TVsSAnZWagAAKj4P/jQnEj0KcfQCsbascKRN\nI3dX7BVYQiaSE05CDgsWcLJCCp1it2zJk8Dh9fRol4rs9RYszo3f/TkPAAy1\naydtN4Qrs9gv87OrfS++wWZ1BM3kjfE+1Am28qo8xUgmZBZ8LJ9reo/VlK+R\nUI/TVvupte5gdQhQrdIpe2BJH74OwjvGkncp+tp/ZxTr7eMnGT3wqmEhJaUD\n1R1Osk37J4ou6x7LcuJnmMCmvKqgA3d5/k/Tw8SyWwTWdmo7c5Or3Hg1/yVs\nPUxJwqkG0JBBfVTH5/STQazcwyGVv7TohAdCdHdKGx1J3MmdJHvAyZDbIux4\nHoMhobeQDvbxbfncqaTjxIteQfSXKKO6NUAnsR0WsTDOzl2ISXRj7Ie8r53B\nCqEgqjRmn/2ySMApLgiEXHDn9V++Fr7RhUI9ttY2iUYclwVsUv4iEAyfIiwQ\n0HkkXjKK7Pbu9q/N1mGk1OexzHd7Ud/bk+vmdG6iMP4xMCKugcUp8qOrRhcb\n6xN7H79h9KQiRemo7tln4zJY2szprgq1Ye6gkrT5T88FlsJvqgtARMY843C/\nuExD+LwO5wlB1OEmQWf/5Pr3dtDcat2bNM0RJHmltn0DxskFdgds5IASVJm3\n2/YhYXpg6ZjiRE0PVSiGjSrQJgHGd3AoxYVyEJGT8X/WBsTMGQgCTa8Ngral\nuf3y\r\n=oCZv\r\n-----END PGP SIGNATURE-----\r\n"},"main":"./bin/create-extension-folder.js","gitHead":"1926a6da3e10617940214c15686c5ece8940707a","_npmUser":{"name":"pedily","email":"kontakt@robinschuster.net"},"repository":{"url":"git+https://github.com/Cognigy/create-extension.git","type":"git"},"_npmVersion":"6.13.4","description":"This repository will become the new 'custom-modules' repository for Cognigy.AI 4.0.0. We are no longer using the name 'custom-module' but the new term 'extension'.","directories":{},"_nodeVersion":"12.14.1","dependencies":{"ora":"^4.0.5","minimist":"^1.2.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/create-extension_0.0.1_1597052443955_0.8376265604617548","host":"s3://npm-registry-packages"}}},"time":{"created":"2020-08-10T09:40:43.697Z","modified":"2026-08-17T13:14:58.944Z","0.0.1":"2020-08-10T09:40:44.143Z"},"bugs":{"url":"https://github.com/Cognigy/create-extension/issues"},"author":{"name":"Cognigy GmbH"},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/Cognigy/create-extension#readme","keywords":["Cognigy.AI","4.0.0","extensions"],"repository":{"url":"git+https://github.com/Cognigy/create-extension.git","type":"git"},"description":"This repository will become the new 'custom-modules' repository for Cognigy.AI 4.0.0. We are no longer using the name 'custom-module' but the new term 'extension'.","maintainers":[{"email":"b.mayr@cognigy.com","name":"mayrbenjamin92"},{"email":"kontakt@robinschuster.net","name":"pedily"},{"email":"npm@ostasevich.com","name":"kwinto"},{"email":"wellereitetclub@gmail.com","name":"dshire"},{"email":"lekshmi.kolappan@gmail.com","name":"lkolapp"},{"email":"m.frindt@cognigy.com","name":"catharsis68"},{"email":"a.komitaki@cognigy.com","name":"cu4nt0m"},{"email":"jorda.murria.xavier@gmail.com","name":"x.jorda"},{"email":"r.chhetri@cognigy.com","name":"rchhetri-cognigy"},{"email":"fahad.khalid@cognigy.nice.com","name":"fkhalid"},{"email":"lucas.sramos.de@gmail.com","name":"lucasdssramos"},{"email":"f.asad@cognigy.com","name":"f.asad"},{"email":"Jose.OrtegaDiaz@nice.com","name":"jortegadiazcognigy"},{"email":"p.heltewig@cognigy.com","name":"mastasky"},{"email":"diogo.gomes@nice.com","name":"dcg-cognigy"},{"email":"fabian.gruber@nice.com","name":"cognigy-fabian"},{"email":"anton.demin@nice.com","name":"anton.demin"}],"readme":"# Create Cognigy-4 Extension\r\n\r\nThis repository will become the new 'custom-modules' repository for Cognigy.AI 4.0.0. We are no longer using the name 'custom-module' but the new term 'extension'.\r\n\r\nCurrently, extensions can only contain flow-nodes and connections, but we want to add more functionality later on.\r\n\r\n- [Download](#creating-an-extension) – How to install a template project.\r\n- [Development](#development) – How to code a new Extension.\r\n\r\nThis script works on macOS, Windows, and Linux.<br>\r\n\r\n## Creating an Extension\r\n\r\n```sh\r\nnpm init @cognigy/extension my-extension basic\r\ncd ./my-extension\r\n```\r\nRun those two simple commands to install a new basic template project and get started with development. You can use [additional arguments](#Creating_an_Extension) \r\n\r\n### Get Started Immediately\r\n\r\nYou do not need to install or configure any additional tools.<br>\r\nThey are preconfigured and hidden so that you can focus on the code.\r\n\r\n### installing with `npm init @cognigy/extension <arguments> <my-extension-name>`\r\nUse this command and you are ready to go. Here are the arguments you can use:\r\n\r\n* `example` gives you an example extension\r\n* `empty` gives you an (almost) empty project\r\n* `basic` gives you a basic project with only very few, basic elements\r\n* no argument also gives you the basic project\r\n\r\n### building with `npm run build`\r\n\r\nBuilds the app for production and recreates a .tar.gz archive to be seamlessly uploaded.\r\n\r\n### deploying with `npm run deploy`\r\n\r\n***(not yet working!)***\r\n\r\n*advanced* <br> Use the Cognigy API to upload your extension without using the website.\r\n\r\n# Development\r\n## How to get started?\r\nIf you want to build an extension, please first have a look at the 'example' project template as it contains the code for an extension which includes multiple flow-nodes and uses most of the important concepts we have introduced with the new 'extensions' functionality in Cognigy.AI 4.0.0. <br>Install the 'example' project template with `npm init @cognigy/extension example example-project`\r\n\r\n## @cognigy/extension-tools\r\n\r\n### createNodeDescriptor\r\nThe method `createNodeDescriptor` is one of the most central methods exposed by the 'extension-tools' package. It is recommended to only use one `createNodeDescriptor` per file (unless it has children), since it is now possible to include multiple descriptory files per Extension.\r\n\r\nDefining a node essentially looks like this (you can find this example in 'example/src/nodes/reverseSay):\r\n\r\n```typescript\r\nimport { createNodeDescriptor, INodeFunctionBaseParams } from \"@cognigy/extension-tools\";\r\n\r\nexport interface IReverseSayParams extends INodeFunctionBaseParams {\r\n\tconfig: {\r\n\t\ttext: string;\r\n\t}\r\n}\r\n\r\nexport const reverseSay = createNodeDescriptor({\r\n\ttype: \"reverseSay\",\r\n\r\n\tdefaults: {\r\n\t\tlabel: \"Simple Reverse Say\",\r\n\t\tcomment: \"Reverses the given string and sends it.\",\r\n\t\tconfig: {\r\n\t\t\ttext: \"{{ci.text}}\"\r\n\t\t}\r\n\t},\r\n\r\n\tfields: [\r\n\t\t{\r\n\t\t\tkey: \"text\",\r\n\t\t\tlabel: \"The text you want to reverse.\",\r\n\t\t\ttype: \"cognigyText\"\r\n\t\t}\r\n\t],\r\n\r\n\tfunction: async ({ cognigy, config }: IReverseSayParams) => {\r\n\t\tconst { api } = cognigy;\r\n\t\tconst { text } = config;\r\n\r\n\t\tconst reversedText = text.split(\"\").reverse().join();\r\n\r\n\t\tapi.say(reversedText);\r\n\t}\r\n});\r\n```\r\n\r\nLet's analyze the different pieces we can see in the code-window above:\r\n```typescript\r\nimport { createNodeDescriptor, INodeFunctionBaseParams } from \"@trash-planet/extension-tools\";\r\n```\r\n\r\nHere we are just importing the `createNodeDescriptor` method from the extension-tools package. We are also importing a Typescript interface we want to use.\r\n\r\n```typescript\r\nexport interface IReverseSayParams extends INodeFunctionBaseParams {\r\n\tconfig: {\r\n\t\ttext: string;\r\n\t}\r\n}\r\n```\r\n\r\nIn this part of the node-code we are crafting a `new Typescript interface` for the config (the arguments) of the new flow-node. We advise you to do this for your nodes as you will have a better developer experience when you are actually creating the `code` (aka the `function`) of your flow-node. Make sure that you extend on our `INodeFunctionBaseParams` interface - this will give you access to:\r\n- **cognigy** object with sub-properties:\r\n  - **api**: This exposes the APi your flow-nodes can use.\r\n  - **input**: The Cognigy Input Object, this is a proxy so you can set/get values.\r\n  - **context**: The Cognigy Context Object, this is a proxy so you can set/get values.\r\n  - **profile**; The Cognigy Contact Profile Object, this, too, is a proxy so you can set/get values.\r\n- **nodeId** the actual id of the node that is being executed\r\n- **config** this is the config/arguments of your node - that's why you should overwrit this in your own Interface\r\n- **childConfigs[]** in case your node has children, this array contains those children's configs\r\n\r\n```typescript\r\nexport const reverseSay = createNodeDescriptor({\r\n\ttype: \"reverseSay\",\r\n\tdefaultLabel: \"Reverse Say\",\r\n\tfields: [\r\n\t\t{\r\n\t\t\tkey: \"text\",\r\n\t\t\tlabel: \"The text you want to reverse.\",\r\n\t\t\ttype: \"cognigyText\",\r\n\t\t\tdefaultValue: \"{{input.text}}\"\r\n\t\t}\r\n\t],\r\n\tpreview: {\r\n\t\ttype: \"text\",\r\n\t\tkey: \"text\"\r\n\t},\r\n\r\n\tfunction: async ({ cognigy, config }: IReverseSayParams) => {\r\n\t\tconst { api } = cognigy;\r\n\t\tconst { text } = config;\r\n\r\n\t\tconst reversedText = text.split(\"\").reverse().join();\r\n\r\n\t\tapi.say(reversedText);\r\n\t}\r\n});\r\n```\r\n\r\nNow comes the actual definition & implementation of your flow-node. You essentially pass in an object into `createNodeDescriptor` and it will create a full node-descriptor for you. The method will fill-up on properties you don't set with compatible default values. Let's discuss some of the properties you have to set:\r\n- **type**: This is the `type` of your node. Every node needs to have its own type. \r\n- **defaultslabel**: The default label of your node is the name that is displaed in the flow by default.\r\n- **fields**: This section defines the user interface which will get generated for your node-config. You have to add a `field definition` per key in your `config` object. You reference the `key in your config` using the `key` property in the field definition. The label is used in the UI as well. The type gives you a variety of possibilities - you can e.g. say that your field should be of type `cognigyText` or e.g. of type json or toggle.\r\n- **preview**: *(optional)* Displays the value of one of the node's config-fields.\r\n- **function**: This actually contains the code of your flow-node. Ensure that you add the `async` keyword. The execution engine will always `await` the execution of your node. We have full Typescript support, please e.g. check the typings of the **cognigy** object as we don't have full documentation, yet.\r\n\r\n### createExtension\r\nWhereas the `createNodeDescriptor` method essentially just fills-up default-values for your flow-nodes, it's the `createExtension` methods job to bundle all nodes and connection definitions into one large object which will then be passed into the Cognigy.AI system.\r\n\r\nMake sure that you are using the `default export ` syntax for the createExtensions return-value as we need to be able to find the complete object.\r\n\r\nIt is highly recommended to always create a `module.ts` file which essentially looks like the one in `example/src/module.ts`. Please only import all nodes and connections into this file and assign them to the payload you pass into the create extension method.\r\n\r\n```typescript\r\nimport { createExtension } from \"@cognigy/extension-tools\";\r\n\r\n/* import all nodes */\r\nimport { reverseSay } from \"./nodes/reverseSay\";\r\nimport { executeCognigyApiRequest } from \"./nodes/executeCognigyApiRequest\";\r\n//if multiple nodes are in one script, import all of them\r\nimport { randomPath, randomPathLeft, randomPathRight } from \"./nodes/randomPath\";\r\nimport { fullExample } from \"./nodes/fullExample\";\r\n\r\n/* import all connections */\r\nimport { apiKeyConnection } from \"./connections/apiKeyConnection\";\r\n\r\nexport default createExtension({\r\n    //define the nodes to be exported\r\n\tnodes: [\r\n\t\treverseSay,\r\n\t\texecuteCognigyApiRequest,\r\n\r\n\t\trandomPath,\r\n\t\trandomPathLeft,\r\n\t\trandomPathRight,\r\n\t\tfullExample\r\n\t],\r\n\r\n    //define the nodes to be exported\r\n\tconnections: [\r\n\t\tapiKeyConnection\r\n\t]\r\n});\r\n```\r\n\r\n### Connections\r\nIn Cognigy 3 we have introduced the concept of `Secrets` which allow you to securely store configurations. Secrets do no longer exist in Cognigy 4, but were replaced with the `Connections`.\r\n\r\nExtension now have a stringer relationship with their cocrresponding flow-nodes. They can be assigned using configuration fields in the flow node.\r\n\r\nIf you want to use a connection within a node, you have to do the following:\r\n- add a **field** with **type: connection** to your flow-node, you can see this in 'example/src/nodes/executeCognigyApiRequest.ts'\r\n  ```typescript\r\n  {\r\n      key: \"connection\",\r\n      label: \"The api-key connection which should be used.\",\r\n      type: \"connection\",\r\n      params: {\r\n          connectionType: \"api-key\" // this needs to match the connections 'type' property\r\n      }\r\n  }\r\n  ```\r\n- create a connection definition, see 'example/src/connections/'\r\n- add the **connection** into your **createExtensions** call - if you miss it there, it will not be there.\r\n\r\nYou have to ensure that the `params.connectionType` in your flow-node field definition maps to a connection and a proper `type` of the connection. You can define multiple connections within a single extension and the `type` field is used to find the correct connections that satisfy the fields your node requires.","readmeFilename":"README.md"}