{"id":19924367,"url":"https://github.com/kontent-ai/management-sdk-js","last_synced_at":"2025-04-09T13:04:35.513Z","repository":{"id":35399699,"uuid":"213578031","full_name":"kontent-ai/management-sdk-js","owner":"kontent-ai","description":"SDK for Kontent.ai Management API","archived":false,"fork":false,"pushed_at":"2025-03-10T11:42:09.000Z","size":2601,"stargazers_count":9,"open_issues_count":0,"forks_count":15,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-02T12:08:44.809Z","etag":null,"topics":["kontent-ai","kontent-ai-tool","kontent-api","kontent-sdk","management-sdk"],"latest_commit_sha":null,"homepage":"https://docs.kontent.ai/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kontent-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-08T07:38:33.000Z","updated_at":"2025-03-10T11:42:12.000Z","dependencies_parsed_at":"2023-01-15T20:15:41.456Z","dependency_job_id":"c3d4281a-cb36-4a70-a74f-05f5db965501","html_url":"https://github.com/kontent-ai/management-sdk-js","commit_stats":{"total_commits":420,"total_committers":18,"mean_commits":"23.333333333333332","dds":0.09047619047619049,"last_synced_commit":"2829aedc4f0403ca380b91d7235ad62b844dbe76"},"previous_names":["kentico/kontent-management-sdk-js"],"tags_count":106,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fmanagement-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fmanagement-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fmanagement-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fmanagement-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kontent-ai","download_url":"https://codeload.github.com/kontent-ai/management-sdk-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045230,"owners_count":21038553,"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":["kontent-ai","kontent-ai-tool","kontent-api","kontent-sdk","management-sdk"],"created_at":"2024-11-12T22:17:10.228Z","updated_at":"2025-04-09T13:04:35.488Z","avatar_url":"https://github.com/kontent-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kontent.ai Management Javascript SDK\n\n\u003e Javascript SDK for the\n\u003e [Management API](https://kontent.ai/learn/reference/kontent-apis-overview/#content-management-api-v2). Helps you manage\n\u003e content in your [Kontent.ai](https://kontent.ai/) projects. Supports both `node.js` and `browsers`.\n\n[![npm version](https://badge.fury.io/js/%40kontent-ai%2Fmanagement-sdk.svg)](https://badge.fury.io/js/%40kontent-ai%2Fmanagement-sdk)\n[![Build \u0026 Test](https://github.com/kontent-ai/management-sdk-js/actions/workflows/integrate.yml/badge.svg)](https://github.com/kontent-ai/management-sdk-js/actions/workflows/integrate.yml)\n[![npm](https://img.shields.io/npm/dt/@kontent-ai/management-sdk.svg)](https://www.npmjs.com/package/@kontent-ai/management-sdk)\n[![Known Vulnerabilities](https://snyk.io/test/github/kontent-ai/management-sdk-js/badge.svg)](https://snyk.io/test/github/kontent-ai/management-sdk-js)\n[![GitHub license](https://img.shields.io/github/license/kontent-ai/management-sdk-js.svg)](https://github.com/kontent-ai/management-sdk-js)\n![Gzip bundle](https://img.badgesize.io/https:/cdn.jsdelivr.net/npm/@kontent-ai/management-sdk/dist/bundles/kontent-management.umd.min.js?compression=gzip)\n[![](https://data.jsdelivr.com/v1/package/npm/@kontent-ai/management-sdk/badge)](https://www.jsdelivr.com/package/npm/@kontent-ai/management-sdk)\n\n## Getting started\n\nTo get started, you'll first need to have access to your [Kontent.ai](https://kontent.ai/) project where you need to enable Content management API and generate `access token` that will be used to authenticate all requests made by this library.\n\n## Installation\n\n```\nnpm i @kontent-ai/management-sdk --save\n```\n\n### Using a standalone version in browsers\n\nIf you'd like to use this library directly in browser, place following script tags to your html page. You may of course\ndownload it and refer to local versions of scripts.\n\n```javascript\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@kontent-ai/management-sdk@latest/dist/bundles/kontent-management.umd.js\"\u003e\u003c/script\u003e\n```\n\n### Making the first request\n\nThe following code example shows how to create new content item in your Kontent.ai environment.\n\n```javascript\nimport { createManagementClient } from '@kontent-ai/management-sdk';\n\nconst client = createManagementClient({\n    environmentId: 'xxx', // id of your Kontent.ai environment\n    subscriptionId: 'zzz' // optional, but required for Subscription related endpoints\n    apiKey: 'yyy' // Content management API token\n});\n\nclient\n    .addContentItem()\n    .withData({\n        name: 'New article',\n        type: {\n            codename: 'article' // codename of content type\n        }\n    })\n    .toPromise()\n    .then(response =\u003e {\n        console.log(response);\n    });\n```\n\nIf you are using `UMD` bundles directly in browsers, you can find this library under `KontentManagement` global\nvariable.\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eKontent.ai management | jsdelivr cdn\u003c/title\u003e\n        \u003cscript src=\"https://cdn.jsdelivr.net/npm/@kontent-ai/management-sdk/dist/bundles/kontent-management.umd.min.js\"\u003e\u003c/script\u003e\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003cscript type=\"text/javascript\"\u003e\n            var KontentManagement = window['kontentManagement'];\n\n            var client = new KontentManagement.ManagementClient({\n                environmentId: 'xxx',\n                // using CM API key in browser is NOT safe. If you need to use SDK in browsers\n                // you should use proxy server and set authorization header there rather than here\n                apiKey: 'yyy',\n                subscriptionId: 'zzz' // optional, but required for Subscription related endpoints\n            });\n\n            client\n                .addContentItem()\n                .withData({\n                    name: 'New article',\n                    type: {\n                        codename: 'article'\n                    }\n                })\n                .toPromise()\n                .then(response =\u003e {\n                    console.log(response);\n                });\n        \u003c/script\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Configuration\n\nThe `ManagementClient` contains several configuration options:\n\n```javascript\nimport { createManagementClient } from '@kontent-ai/management-sdk';\n\nconst client = createManagementClient({\n    // configuration options\n});\n```\n\n| Option          | Default                               | Description                                                                                                                                                         |\n| --------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `API Key`        | N/A                                   | **Required** - Management or Subscription API Key. Subscription API Key also works for Management requests            |\n| `environmentId`     | N/A                                   | **Required for Management API** - Environment Id                                                                                                   \n| `subscriptionId`       | N/A  | **Required for Subscription API** - Subscription Id\n| `baseUrl`       | https://manage.kontent.ai/v2 | Base URL of REST api. Can be useful if you are using custom proxy or for testing purposes                                                                          \n| `retryStrategy` | undefined                             | Retry strategy configuration. If not set, default strategy is used.                                                                                                 |\n| `httpService`   | HttpService                           | Used to inject implementation of `IHttpService` used to make HTTP request across network. Can also be useful for testing purposes by returning specified responses. |\n\n### Handling API Management Errors\n\nSee the [error section in Management API reference](https://kontent.ai/learn/reference/management-api-v2#section/Guidelines-on-handling-changes) for infofmation about status codes and error messages.\n\n```typescript\ntry {\n    const client = createManagementClient({\n        environmentId: 'x',\n        apiKey: 'y'\n    });\n    await client.viewContentItem().byItemCodename('invalid codename').toPromise();\n} catch (err) {\n    if (err instanceof SharedModels.ContentManagementBaseKontentError) {\n        // Error message provided by API response and mapped by SDK\n        const message = err.message;\n        // In case you need more specific information about the request error.\n        // Structure of the error depends on HttpService.\n        const error = error.originalError;\n    } else {\n        // handle generic error however you need\n    }\n}\n```\n\n### Cancelling Requests\n\n```typescript\nconst client = {\n    environmentId: 'x',\n    apiKey: 'y'\n});\n\n// prepare cancel token\nconst cancelTokenRequest = client.createCancelToken();\n\nclient\n    .listContentItems()\n    .withCancelToken(cancelTokenRequest)\n    .toPromise()\n    .then((x) =\u003e {\n        // will not be executed as request was cancelled before network\n        // request got a chance to finish\n    })\n    .catch((err) =\u003e {\n        // error with your custom message 'Request manually cancelled'\n    });\n\n// cancel request right away\ncancelTokenRequest.cancel('Request manually cancelled');\n```\n\n### Sample scenario\n\nFollowing is a sample scenario consisting of:\n\n1. Initializing client\n2. Getting default language of environment\n3. Creating new taxonomy with terms\n4. Creating new content type\n5. Creating content item\n6. Creating binary file \u0026 asset from URL\n7. Upserting language variant of the newly created content item in default language\n\n#### Initializing client\n\n```typescript \nimport { createManagementClient } from '@kontent-ai/management-sdk';\n\nconst client = createManagementClient({\n    environmentId: 'x',\n    apiKey: 'y'\n});\n```\n\n#### Getting default language of environment\n\n```typescript \nconst languages = await client.listLanguages().toPromise();\nconst defaultLanguage = languages.data.items.find((m) =\u003e m.isDefault);\n```\n\n####  Creating new taxonomy with terms\n\n```typescript \nconst movieTaxonomy = await client\n    .addTaxonomy()\n    .withData({\n        name: 'Genre',\n        codename: 'genre',\n        terms: [\n            {\n                name: 'Comedy',\n                codename: 'comedy',\n                terms: []\n            },\n            {\n                name: 'Action',\n                codename: 'action',\n                terms: []\n            },\n            {\n                name: 'Anime',\n                codename: 'anime',\n                terms: []\n            }\n        ]\n    })\n    .toPromise();\n```\n\n#### Creating new content type\n\n```typescript \nconst movieType = await client\n    .addContentType()\n    .withData((builder) =\u003e {\n        return {\n            name: 'Movie',\n            codename: 'movie',\n            elements: [\n                builder.textElement({\n                    name: 'Title',\n                    codename: 'title',\n                    type: 'text',\n                    is_required: true,\n                    maximum_text_length: {\n                        applies_to: 'characters',\n                        value: 50\n                    }\n                }),\n                builder.dateTimeElement({\n                    name: 'ReleaseDate',\n                    codename: 'release_date',\n                    type: 'date_time',\n                    is_required: true\n                }),\n                builder.richTextElement({\n                    name: 'Description',\n                    codename: 'description',\n                    type: 'rich_text',\n                    is_required: true,\n                    allowed_table_formatting: ['unstyled', 'bold', 'italic'],\n                    allowed_blocks: ['text', 'tables'],\n                    maximum_text_length: {\n                        applies_to: 'words',\n                        value: 500\n                    }\n                }),\n                builder.assetElement({\n                    name: 'Cover',\n                    codename: 'cover',\n                    type: 'asset',\n                    allowed_file_types: 'adjustable',\n                    asset_count_limit: {\n                        condition: 'exactly',\n                        value: 1\n                    },\n                    is_required: true\n                }),\n                builder.taxonomyElement({\n                    type: 'taxonomy',\n                    codename: 'genre',\n                    is_required: true,\n                    taxonomy_group: {\n                        id: movieTaxonomy.data.id\n                    }\n                })\n            ]\n        };\n    })\n    .toPromise();\n```\n\n#### Creating content item\n\n```typescript \nconst contentItem = await client\n    .addContentItem()\n    .withData({\n        name: 'Warrior',\n        type: {\n            codename: 'movie'\n        }\n    })\n    .toPromise();\n```\n\n####  Creating binary file \u0026 asset from URL\n\n```typescript \nconst imageAsset = await client\n    .uploadAssetFromUrl()\n    .withData({\n        asset: {\n            descriptions: [{ description: 'Image poster for warrior', language: { id: defaultLanguage?.id ?? '' } }],\n            title: 'Warrior cover'\n        },\n        binaryFile: {\n            filename: 'warrior.jpg'\n        },\n        fileUrl: 'https://upload.wikimedia.org/wikipedia/en/e/e3/Warrior_Poster.jpg'\n    })\n    .toPromise();\n```\n\n#### Upserting language variant of the newly created content item in default language\n```typescript \nconst languageVariant = await client\n    .upsertLanguageVariant()\n    .byItemId(contentItem.data.id)\n    .byLanguageId(defaultLanguage?.id ?? '')\n    .withData((builder) =\u003e {\n        return {\n            elements: [\n                builder.textElement({\n                    element: {\n                        codename: 'title'\n                    },\n                    value: 'Warrior'\n                }),\n                builder.dateTimeElement({\n                    element: {\n                        codename: 'release_date'\n                    },\n                    value: '2011-09-09'\n                }),\n                builder.richTextElement({\n                    element: {\n                        codename: 'description'\n                    },\n                    value: '\u003cp\u003ePath that puts the fighter on a collision course with his estranged, older brother.\u003c/p\u003e'\n                }),\n                builder.assetElement({\n                    element: {\n                        codename: 'cover'\n                    },\n                    value: [\n                        {\n                            id: imageAsset.data.id\n                        }\n                    ]\n                }),\n                builder.taxonomyElement({\n                    element: {\n                        codename: 'genre'\n                    },\n                    value: [\n                        {\n                            codename: 'action'\n                        }\n                    ]\n                })\n            ]\n        }\n    })\n    .toPromise();\n```\n\n### Testing\n\n\u003e If you want to mock http responses, it is possible to use\n\u003e [external implementation of configurable Http Service](../core/README.md#testing) as a part of the\n\u003e [client configuration](#configuration).\n\n### Troubleshooting \u0026 feedback\n\nIf you have any issues or want to share your feedback, please feel free to\n[create an issue](https://github.com/kontent-ai/management-sdk-js/issues/new/choose) in this GitHub repository.\n\n### Contributions\n\nContributions are welcomed. If you have an idea of what you would like to implement, let us know and lets discuss\ndetails of your PR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fmanagement-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkontent-ai%2Fmanagement-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fmanagement-sdk-js/lists"}