{"id":20119578,"url":"https://github.com/box/box-skills-kit-nodejs","last_synced_at":"2025-05-06T14:32:28.400Z","repository":{"id":33852512,"uuid":"148523199","full_name":"box/box-skills-kit-nodejs","owner":"box","description":"Official toolkit library and boilerplate code for developing Box Skills.","archived":false,"fork":false,"pushed_at":"2022-12-31T02:02:24.000Z","size":2130,"stargazers_count":30,"open_issues_count":14,"forks_count":22,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-09T13:46:55.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://developer.box.com/docs/box-skills","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/box.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-12T18:22:08.000Z","updated_at":"2024-10-10T17:29:44.000Z","dependencies_parsed_at":"2023-01-15T03:00:19.820Z","dependency_job_id":null,"html_url":"https://github.com/box/box-skills-kit-nodejs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-skills-kit-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-skills-kit-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-skills-kit-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fbox-skills-kit-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/box","download_url":"https://codeload.github.com/box/box-skills-kit-nodejs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252703454,"owners_count":21790887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T19:16:09.526Z","updated_at":"2025-05-06T14:32:28.030Z","avatar_url":"https://github.com/box.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Box Skills Kit for Node.js \n\nThis is the official toolkit provided by [Box](https://box.com) for creating custom [Box Skills](https://developer.box.com/docs/box-skills) written in Node.js.\n\n* [What is a Box Skill?](#WhatisaBoxSkill)\n* [How does a Box Skill work?](#HowdoesaBoxSkillwork)\n* [What is this toolkit for?](#Whatisthistoolkitfor)\n* [Where can I learn more?](#WherecanIlearnmore)\n* [Installation](#Installation)\n* [Basic usage](#Basicusage)\n\t* [1. Reading the webhook payload](#Readingthewebhookpayload)\n\t* [2. Processing the file using a ML provider](#ProcessingthefileusingaMLprovider)\n\t* [3. Write Metadata to File](#WriteMetadatatoFile)\n\t* [(Optional) Deal with errors](#OptionalDealwitherrors)\n\n## What is a Box Skill?\n\nA Box Skill is a type of application that performs custom processing for files uploaded to Box.\n\nOften, Box Skills leverage **third-party AI or machine learning providers** to automatically extract information from files upon upload to Box. For example, a Box Skill could automatically label objects in images using a computer vision service.\n\nThe resulting data can then be written back to the file on Box as **rich metadata** cards.\n\n![Metadata on a Video](docs/metadata.png)\n\n## How does a Box Skill work?\n\nAt a basic level, a Box Skill follows the following steps.\n\n1. A file is uploaded to Box\n1. Box triggers a webhook to your (serverless) endpoint\n1. Your server (using the Box Skills kit) processes the webhook's event payload\n1. Your server downloads the file, or passes a reference to the file to your machine learning provider\n1. Your machine learning provider processes the file and provides some data to your server\n1. Your server (using the Box Skills kit) writes rick metadata to the file on Box\n1. Your users will now have new metadata available to them in the Box web app, including while searching for files.\n\n## What is this toolkit for?\n\nThis toolkit helps to simplify building a custom skill in Node.js. It simplifies processing the skill event from Box, accessing your file, and writing the metadata back. \n\nYou will still need to hook things up to your own **Machine Learning provider**, including creating an account with them. This toolkit helps you with all the interactions with Box but does not help you with the API calls to your machine learning provider.\n\n## Where can I learn more?\n\nFor more information on Box Skills, what kind of metadata you can write back to Box, as well as visual instructions on configuring your skills code with Box, visit the [box skills developer documentation](https://developer.box.com/docs/box-skills).\n\nAdditionally, have a look at:\n\n* More documentation on the [library's API](skills-kit-library)\n* A quick start on [deploying your first skills service](boilerplate-skills)\n* [More samples](https://github.com/box-community) of Box Custom Skills using various ML providers\n\n## Installation\n\nAs the Skills Kit is currently not available through NPM the easiest way to use the library is by downloading it and linking it in your project.\n\n```sh\n# Clone the project\ngit clone https://github.com/box/box-skills-kit-nodejs.git\n# Change into your own project\ncd your_project\n# Copy the skills kit library and the package.json\n# with its dependencies into your project\ncp -r ../box-skills-kit-nodejs/skills-kit-library .\n# Link the library into your project, and download its dependencies\nnpm link ./skills-kit-library\n```\n\nThen, in your own code, you can include parts of the library as follows.\n\n```js\n// For more examples of the modules available within the\n// library, see the rest of the documentation\nconst { FilesReader } = require('./skills-kit-library/skills-kit-2.0.js')\n```\n\n## Basic usage\n\nWriting your own Custom Box Skill will change depending on your data and the machine learning provider used. A generic example would look something like this.\n\n\n### \u003ca name='Readingthewebhookpayload'\u003e\u003c/a\u003e1. Reading the webhook payload\n\nThe way your request data (`event` in this example) comes in \nwill differ depending on the web service you are using,\nthough in our example we are assuming you are using the Serverless framework\n\n```js\n// import the FilesReader from the kit\nconst { FilesReader  } = require('./skills-kit-library/skills-kit-2.0.js');\n// Here, event is the webhook data received at your endpoint.\nconst reader = new FilesReader(event.body);  \n\n// the ID of the file\nconst fileId = reader.getFileContext().fileId;\n// the read-only download URL of the file\nconst fileURL = reader.getFileContext().fileDownloadURL;\n```\n\n### \u003ca name='ProcessingthefileusingaMLprovider'\u003e\u003c/a\u003e2. Processing the file using a ML provider\n\nThis part will heavily depend on your machine learning provider. In this example we use a\ntheoretical provider called `MLProvider`.\n\n```js\nconst { MLProvider } = require('your-ml-provider');\n// import the SkillsWriter and SkillsErrorEnum from the kit\nconst { SkillsWriter, SkillsErrorEnum } = require('./skills-kit-library/skills-kit-2.0.js');\n\n// initialize the writer with the FilesReader instance,\n// informing the writer how to and where to write any metadata\nconst writer = new SkillsWriter(reader.getFileContext());\n\n// Write a \"Processing\"-card as metadata to the file on Box, \n// informing a user of the skill in process.\nawait writer.saveProcessingCard();\n\n// Finally, kick off your theoretical machine learning provider\ntry {\n  // (this code is pseudo code)\n  const data = await new MLProvider(fileUrl).process()\n} catch {\n  // Write an \"Error\"-card as metadata to your file if the processing failed\n  await writer.saveErrorCard(SkillsErrorEnum.FILE_PROCESSING_ERROR);\n}\n```\n\n### \u003ca name='WriteMetadatatoFile'\u003e\u003c/a\u003e3. Write Metadata to File\n\nFinally, once your machine learning provider has processed your file, you can write the data received from them as various forms of **metadata** to a file.\n\n```js\n// In this case we assume your data is some kind of array of objects with keywords\n// e.g.:\n// [\n//   { keyword: 'Keyword 1' },\n//   { keyword: 'Keyword 2' },\n//   { keyword: 'Keyword 1' },\n//   ...\n// ]\nlet entries = [];\ndata.forEach(entry =\u003e {\n  entries.push({\n    type: 'text',\n    text: entry.keyword\n  })\n});\n\n// Convert the entries into a Keyword Card\nconst card = writer.createTopicsCard(entries);\n\n// Write the card as metadata to the file\nawait writer.saveDataCards([card]);\n```\n\n### \u003ca name='OptionalDealwitherrors'\u003e\u003c/a\u003e(Optional) Deal with errors\n\nIn any of these steps a failure, either when reading the file, processing the file, or writing the metadata to the file.\n\nThe skills kit makes it simple to write powerful error messages to your file as metadata cards.\n\n```js\nconst { SkillsErrorEnum } = require('./skills-kit-library/skills-kit-2.0.js');\nawait writer.saveErrorCard(SkillsErrorEnum.FILE_PROCESSING_ERROR);\n```\n\nSee the Skills Kit API documentation for a [full list of available errors](skills-kit-library#error-enum).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbox%2Fbox-skills-kit-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbox%2Fbox-skills-kit-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbox%2Fbox-skills-kit-nodejs/lists"}