{"id":13809825,"url":"https://github.com/recombee/node-api-client","last_synced_at":"2026-03-05T23:42:31.117Z","repository":{"id":57349243,"uuid":"92761789","full_name":"recombee/node-api-client","owner":"recombee","description":"Node.js client for easy use of the Recombee recommendation API","archived":false,"fork":false,"pushed_at":"2025-03-11T18:19:33.000Z","size":936,"stargazers_count":26,"open_issues_count":1,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-01T16:28:28.198Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/recombee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-05-29T17:37:24.000Z","updated_at":"2025-04-03T16:35:11.000Z","dependencies_parsed_at":"2023-02-08T19:31:31.115Z","dependency_job_id":"3680dbe2-a3be-467d-97dd-9e3aab9873f7","html_url":"https://github.com/recombee/node-api-client","commit_stats":{"total_commits":19,"total_committers":3,"mean_commits":6.333333333333333,"dds":"0.10526315789473684","last_synced_commit":"d062549a148ccf7a1caaf90bf95da34f7cac0a0f"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recombee%2Fnode-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recombee%2Fnode-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recombee%2Fnode-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recombee%2Fnode-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/recombee","download_url":"https://codeload.github.com/recombee/node-api-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253421423,"owners_count":21905747,"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-08-04T02:00:36.907Z","updated_at":"2026-03-05T23:42:26.076Z","avatar_url":"https://github.com/recombee.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Recombee API Client\n\nA Node.js client (SDK) for easy use of the [Recombee](https://www.recombee.com/) recommendation API.\nIf you don't have an account at Recombee yet, you can create a free account [here](https://www.recombee.com/).\n\nDocumentation of the API can be found at [docs.recombee.com](https://docs.recombee.com/).\n\nFor client side (browser, mobile apps ...) .js library please see [this repository](https://github.com/recombee/js-api-client).\n\n## Installation\n\n```sh\nnpm install recombee-api-client\n# or\nyarn add recombee-api-client\n# or\npnpm add recombee-api-client\n# or\nbun add recombee-api-client\n```\n\nThe library ships with types, so you should get autocomplete in your IDE out of the box.\nIf you're using TypeScript, it should recognize these correctly and warn you about any type errors.\n\n## Examples\n\n### Basic examples\n\n```javascript\nimport { ApiClient, requests } from \"recombee-api-client\";\n\nconst client = new ApiClient(\n\t\"[RECOMBEE_DATABASE_ID]\",\n\t\"[RECOMBEE_DATABASE_PRIVATE_TOKEN]\",\n\t{ region: \"us-west\" }\n);\n\nconst request = new requests.ListUsers({ count: 10 });\n\nclient\n\t.send(request)\n\t.then((result) =\u003e {\n\t\tconsole.log(result);\n\t})\n\t.catch((error) =\u003e {\n\t\tconsole.error(error);\n\t});\n```\n\n```javascript\nimport { ApiClient, requests } from \"recombee-api-client\";\n\nconst client = new ApiClient(\n\t\"[RECOMBEE_DATABASE_ID]\",\n\t\"[RECOMBEE_DATABASE_PRIVATE_TOKEN]\",\n\t{ region: \"us-west\" }\n);\n\nasync function example() {\n\t// Prepare some userIDs and itemIDs\n\tconst NUM = 100;\n\tconst userIds = Array.from({ length: NUM }).map((_, i) =\u003e {\n\t\treturn `user-${i}`;\n\t});\n\tconst itemIds = Array.from({ length: NUM }).map((_, i) =\u003e {\n\t\treturn `item-${i}`;\n\t});\n\n\t// Generate some random purchases of items by users\n\tconst PROBABILITY_PURCHASED = 0.1;\n\tconst purchases = [];\n\tuserIds.forEach((userId) =\u003e {\n\t\tconst purchased = itemIds.filter(\n\t\t\t() =\u003e Math.random() \u003c PROBABILITY_PURCHASED\n\t\t);\n\t\tpurchased.forEach((itemId) =\u003e {\n\t\t\tpurchases.push(\n\t\t\t\tnew requests.AddPurchase(userId, itemId, {\n\t\t\t\t\tcascadeCreate: true,\n\t\t\t\t})\n\t\t\t);\n\t\t});\n\t});\n\n\t// Send the data to Recombee, use Batch for faster processing of larger data\n\tawait client.send(new requests.Batch(purchases));\n\n\t//Get 5 recommended items for user 'user-25'\n\tconst response = await client.send(\n\t\tnew requests.RecommendItemsToUser(\"user-25\", 5)\n\t);\n\tconsole.log(\"Recommended items for user-25: %j\", response.recomms);\n\t// User scrolled down - get next 3 recommended items\n\tconst response2 = await client.send(\n\t\tnew requests.RecommendNextItems(response.recommId, 3)\n\t);\n\tconsole.log(\"Next recommended items for user-25: %j\", response2.recomms);\n}\n\nexample();\n```\n\n### Using property values\n\n```javascript\nconst recombee = require(\"recombee-api-client\");\nconst rqs = recombee.requests;\n\nconst client = new recombee.ApiClient(\n\t\"--my-database-id--\",\n\t\"--db-private-token--\",\n\t{ region: \"ap-se\" }\n);\nconst NUM = 100;\n\n// We will use computers as items in this example\n// Computers have four properties\n//   - price (floating point number)\n//   - number of processor cores (integer number)\n//   - description (string)\n//   - image (url of computer's photo)\n\n// Add properties of items\nclient\n\t.send(\n\t\tnew rqs.Batch([\n\t\t\tnew rqs.AddItemProperty(\"price\", \"double\"),\n\t\t\tnew rqs.AddItemProperty(\"num-cores\", \"int\"),\n\t\t\tnew rqs.AddItemProperty(\"description\", \"string\"),\n\t\t\tnew rqs.AddItemProperty(\"time\", \"timestamp\"),\n\t\t\tnew rqs.AddItemProperty(\"image\", \"image\"),\n\t\t])\n\t)\n\t.then((responses) =\u003e {\n\t\t//Prepare requests for setting a catalog of computers\n\n\t\tvar requests = Array.apply(0, Array(NUM)).map((_, i) =\u003e {\n\t\t\treturn new rqs.SetItemValues(\n\t\t\t\t`computer-${i}`, //itemId\n\t\t\t\t//values:\n\t\t\t\t{\n\t\t\t\t\tprice: 600 + 400 * Math.random(),\n\t\t\t\t\t\"num-cores\": Math.floor(Math.random() * 8) + 1,\n\t\t\t\t\tdescription: \"Great computer\",\n\t\t\t\t\ttime: new Date().toISOString(),\n\t\t\t\t\timage: `http://examplesite.com/products/computer-${i}.jpg`,\n\t\t\t\t},\n\t\t\t\t//optional parameters:\n\t\t\t\t{\n\t\t\t\t\tcascadeCreate: true, // Use cascadeCreate for creating item\n\t\t\t\t\t// with given itemId, if it doesn't exist\n\t\t\t\t}\n\t\t\t);\n\t\t});\n\t\t//Send catalog to the recommender system\n\t\treturn client.send(new rqs.Batch(requests));\n\t})\n\t.then((responses) =\u003e {\n\t\t// Generate some random purchases of items by users\n\t\tconst userIds = Array.apply(0, Array(NUM)).map((_, i) =\u003e {\n\t\t\treturn `user-${i}`;\n\t\t});\n\t\tconst itemIds = Array.apply(0, Array(NUM)).map((_, i) =\u003e {\n\t\t\treturn `computer-${i}`;\n\t\t});\n\n\t\t// Generate some random purchases of items by users\n\t\tconst PROBABILITY_PURCHASED = 0.1;\n\t\tconst purchases = [];\n\t\tuserIds.forEach((userId) =\u003e {\n\t\t\tconst purchased = itemIds.filter(\n\t\t\t\t() =\u003e Math.random() \u003c PROBABILITY_PURCHASED\n\t\t\t);\n\t\t\tpurchased.forEach((itemId) =\u003e {\n\t\t\t\tpurchases.push(\n\t\t\t\t\tnew rqs.AddPurchase(userId, itemId, { cascadeCreate: true })\n\t\t\t\t);\n\t\t\t});\n\t\t});\n\t\t// Send purchases to the recommender system\n\t\treturn client.send(new rqs.Batch(purchases));\n\t})\n\t.then((responses) =\u003e {\n\t\t// Get 5 recommendations for user-42, who is currently viewing computer-6\n\t\t// Recommend only computers that have at least 3 cores\n\t\treturn client.send(\n\t\t\tnew rqs.RecommendItemsToItem(\"computer-6\", \"user-42\", 5, {\n\t\t\t\tfilter: \"'num-cores' \u003e= 3\",\n\t\t\t})\n\t\t);\n\t})\n\t.then((recommended) =\u003e {\n\t\tconsole.log(\n\t\t\t\"Recommended items with at least 3 processor cores: %j\",\n\t\t\trecommended\n\t\t);\n\n\t\t// Recommend only items that are more expensive then currently viewed item (up-sell)\n\t\treturn client.send(\n\t\t\tnew rqs.RecommendItemsToItem(\"computer-6\", \"user-42\", 5, {\n\t\t\t\tfilter: \" 'price' \u003e context_item[\\\"price\\\"] \",\n\t\t\t\treturnProperties: true,\n\t\t\t})\n\t\t);\n\t})\n\t.then((recommended) =\u003e {\n\t\tconsole.log(\"Recommended up-sell items: %j\", recommended);\n\n\t\t// Filters, boosters and other settings can be set also in the Admin UI (admin.recombee.com)\n\t\t// when scenario is specified\n\t\treturn client.send(\n\t\t\tnew rqs.RecommendItemsToItem(\"computer-6\", \"user-42\", 5, {\n\t\t\t\tscenario: \"product_detail\",\n\t\t\t})\n\t\t);\n\t})\n\t.then((recommended) =\u003e {\n\t\t// Perform personalized full-text search with a user's search query (e.g. \"computers\")\n\t\treturn client.send(\n\t\t\tnew rqs.SearchItems(\"user-42\", \"computers\", 5, {\n\t\t\t\tscenario: \"search_top\",\n\t\t\t})\n\t\t);\n\t})\n\t.then((matched) =\u003e {\n\t\tconsole.log(\"Matched items: %j\", matched);\n\t})\n\t.catch((error) =\u003e {\n\t\tconsole.error(error);\n\t\t// Use fallback\n\t});\n```\n\n## Promises / callbacks\n\nThe SDK supports both Promises and callbacks, so you can choose the way which suits your coding style and conventions of your project:\n\n```javascript\n// Using Promises\nawait client.send(new ListUsers());\n// or\nclient\n\t.send(new ListUsers())\n\t.then((response) =\u003e {\n\t\t// handle response\n\t})\n\t.catch((error) =\u003e {\n\t\t// handle error\n\t});\n\n// Using callbacks\nclient.send(new ListUsers(), (error, response) =\u003e {\n\t// handle result\n});\n```\n\n## Errors handling\n\nVarious errors can occur while processing request, for example because of adding an already existing item or submitting interaction of nonexistent user without _cascadeCreate_ set to true. These errors lead to the _ResponseError_, which is thrown or put to callback function by the _send_ method of the client (depending on using Promises or callbacks). Another reason for errorneous request is a timeout. _ApiError_ is the base class of both _ResponseError_ and _TimeoutError_.\n\nWe are doing our best to provide the fastest and most reliable service, but production-level applications must implement a fallback solution since problems can always happen. The fallback might be, for example, showing the most popular items from the current category, or not displaying recommendations at all.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecombee%2Fnode-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecombee%2Fnode-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecombee%2Fnode-api-client/lists"}