{"id":19140970,"url":"https://github.com/gridscale/gsclient-js","last_synced_at":"2025-05-06T23:18:14.874Z","repository":{"id":40940761,"uuid":"179497541","full_name":"gridscale/gsclient-js","owner":"gridscale","description":"The official gridscale API client written in TypeScript / JavaScript","archived":false,"fork":false,"pushed_at":"2025-02-17T07:07:22.000Z","size":6792,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-06T23:18:04.969Z","etag":null,"topics":["async","backup","gridscale","kubernetes","nodejs","npm","paas","server","snapshot","storage","typescript"],"latest_commit_sha":null,"homepage":"https://gridscale.io","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/gridscale.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-04T12:56:47.000Z","updated_at":"2025-02-17T07:07:18.000Z","dependencies_parsed_at":"2023-10-23T13:34:15.242Z","dependency_job_id":"16939f6b-ef62-4d30-82bf-f69e6568135b","html_url":"https://github.com/gridscale/gsclient-js","commit_stats":{"total_commits":505,"total_committers":8,"mean_commits":63.125,"dds":"0.43168316831683173","last_synced_commit":"bd7ce5965940bcc8a5e046741f31ee1a12461c8e"},"previous_names":[],"tags_count":163,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gridscale%2Fgsclient-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gridscale%2Fgsclient-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gridscale%2Fgsclient-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gridscale%2Fgsclient-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gridscale","download_url":"https://codeload.github.com/gridscale/gsclient-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252782835,"owners_count":21803410,"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":["async","backup","gridscale","kubernetes","nodejs","npm","paas","server","snapshot","storage","typescript"],"created_at":"2024-11-09T07:19:38.173Z","updated_at":"2025-05-06T23:18:14.859Z","avatar_url":"https://github.com/gridscale.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/%40gridscale%2Fgsclient-js.svg)](https://badge.fury.io/js/%40gridscale%2Fgsclient-js) [![gridscale API version](apiversion.png)](https://gridscale.io/en/api-documentation/index.html)\n\n# gridscale JavaScript client library\n\nThis is the JavaScript library for our public API. We developed this package for our [Panels](https://my.gridscale.io) and want to share it with you.\n\n## Prerequisites\nTo be able to use this client, a number of steps need to be taken. First a gridscale account will be required, which can be created [here](https://my.gridscale.io/signup/). Then an API-token [should be created](https://my.gridscale.io/APIs/).\n\n## Installation\n\nInstall the package by npm running\n```sh\nnpm i @gridscale/gsclient-js --save\n```\n\nor clone this repo and run\n```sh\nnpm i\nnpm run build\n```\nThis will build the client into the `dist` directory.\n\n## Using the client\n### In a browser\n\nAfter installing, generate the library for browsers by running\n```sh\nnpm run build-browser\n```\n\nThis will create the `dist/client.js` file which you will need.\n\nThen in your HTML you use\n```html\n  \u003chtml\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"utf-8\" /\u003e\n    \u003cscript type=\"text/javascript\" src=\"client.js\"\u003e\u003c/script\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e...\u003c/body\u003e\n  \u003cscript type=\"text/javascript\"\u003e\n    var client = new gridscale.Client('[API-Token]', '[User-UUID]')\n    //client.Server.list()...\n    \u003c/script\u003e\n  \u003c/html\u003e\n```\n\n### In Node.js\n```js\nconst gridscale = require(\"@gridscale/gsclient-js\").gridscale;\nconst client = new gridscale.Client(\"[API-Token]\", \"[User-UUID]\");\n```\n\n### In Node.js with module format\n```js\nimport * as gsclient from '@gridscale/gsclient-js';\nconst client = new gsclient.gridscale.Client(\"[API-Token]\", \"[User-UUID]\");\n```\n\n## API Documentation \nFor details to all API endpoints and their methods, you should refer to the **official API documentation** here - https://gridscale.io/en/api-documentation/index.html\n\n## Demo \nTest basic functionality in our [Demo](https://gridscale.github.io/gsclient-js/example/index.html)\n\n## Types \u0026 Schemas\nSince version 1.0.0 the typescript type definitions of all API parameters and responses are bundled with this package. \n**Developer note:** This client is not (yet) automatically updated on changes to the gridscale public API. To update the types from the official API spec, run `npm run updateFromSpec`.\n\nThere are also additional **schemas** bundled with this package, containing additional formatting hints on the types (e.g. special string formats etc.). The schemas are named like the types, prefixed by a `$`.\n\nExample:\n```js\nimport { ServerCreate, $ServerCreate }\n\nconst createServerForm: ServerCreate = {\n  name: \"test\",\n  cores: 1,\n  memory: 1\n};\n\nonUserInput(formData) {\n  // @TODO: perform additional user input checking\n  console.log($ServerCreate.properties);\n  /*\n  {\n    name: {\n        type: 'string',\n        isRequired: true,\n    },\n    cores: {\n        type: 'number',\n        isRequired: true,\n    },\n    memory: {\n        type: 'number',\n        isRequired: true,\n    },\n    labels: {\n        type: 'array',\n        contains: {\n            type: 'string',\n        },\n    },\n    status: {\n        type: 'string',\n    },\n    availability_zone: {\n        type: 'string',\n    },\n    auto_recovery: {\n        type: 'string',\n    },\n    hardware_profile: {\n        type: 'Enum',\n    },\n  }\n  */\n}\n```\n\n## Client settings\n\n### Global options\n\nYou can set global options, which apply on every object type when creating the client. The third parameter of the constructor can be used for options\n\n#### global mode\nBy default, multiple client instances share token and settings. So if you create a new client instance, all the settings you apply there, will also be applied to all other instance. Even if you instanciate a new client instance with a different token, all the other instances will use the new token. This is due to historical reasonls.\n\n**Example**\n\n```js\nconst client = new gridscale.Client(\"[API-Token]\", \"[User-UUID]\", {\n  limit: 25, // Default page-size for list response\n  watchdelay: 100, // Delay between the single requests when watching a job (RequestID)\n});\n```\n\nYou can also set the options only for specific object types by using the `setDefaults` function for an object. This will override the global settings\n\n**Example**\n\n```js\nclient.Server.setDefaults({\n    page  : 0,    // Index of Page\n    limit : 25,   // Number of Objects per page\n    offset: 0,    // Offset from start,\n    sort  : [-name,+object_uuid], // Sort by fileds\n    fields : [name,object_uuid,...], // Fields that should get included into the Response\n    filter : [name='name',capacity\u003c=30] //  Only return data that matches the filter\n});\n```\n\nYou can also set the options for a single request to filter your objects. This will override global and per-object-type settings\n\n#### isolated mode\nThe isolated mode behaves more common; each `Client` instance uses it's own settings. So you can have multiple instances with, for example, different tokens. Just set the 4th constructor property to `true`\n\n**Example**\n\n```js\nconst client = new gridscale.Client(\"[API-Token]\", \"[User-UUID]\", {}, true);\n//                                                                    ^^^^\n```\n\n### Filters \n**Example**\n\n```js\nclient.Server.list({\n  page: 0,\n  limit: 10,\n  sort: \"name\",\n  fields: [\"name\", \"object_uuid\"],\n  filter: [\"memory\u003e16\"],\n}).then(_callback);\n```\n\nIn this example the result will be the first 10 servers with more then 16GB of memory. Sorted by name and only returning the `name` and the `object_uuid`.\n\n#### Available filter operators:\n\nHere you find an overview of the filter operators available when using the `filter` option.\n\n\"=\" String or value comparison: exact match  \n\"\u003c\u003e\" String or value comparison: does not match  \n\"\u003c\" Value less than  \n\"\u003e\" Value greater than  \n\"\u003c=\" Value less or equal  \n\"\u003e=\" Value greater or equal\n\n### Callback Functions and Promises\n\nAll requests and actions for the objects return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). You are also free to use a callback style for each action. The last parameter of each method accepts a callback function. Both, Promise and callback receive the same result object that gets passed to the function\n\n**Example with Promise**\n\n```js\nclient.Server.list().then(\n  function (result) {\n    // do something when the request succeeded. result is the result object described below\n    console.log(result);\n  },\n  (error) =\u003e {\n    // handle when the request is failed, error.result contains the result object described below\n    console.error(error.result);\n  }\n);\n```\n\n**Example with callback**\n\n```js\nclient.Server.list({}, (response, result) =\u003e {\n  // for historical reasons, the callbacks first parameter is the raw Response from Javascript fetch(), second parameter is the result object described below\n\n  if (result.success) {\n    // do something when the request succeeded. result is the result object described below\n    console.log(result);\n  } else {\n    // handle when the request is failed, error.result contains the result object described below\n    console.error(result);\n  }\n});\n```\n\n## Asynchronous requests\nSome requests are processed in an aynchronous way, meaning that sending the requests starts a job in the background. The request returns (with HTTP Code `202 - Accepted`) but the operation itself may not be finished. This requests return a `X-Request-Id` header, which corresponds to the background job and allows querying the status by sending this ID to the `/request` endpoint.\n### Watching asynchronous request with the client\n\nWhen a client method starts an asynchronous request, the response object contains a `watch` property, which is a function which - once called - will start watching the background job your request just started (for example creating a large storage). The Promise that is returned by the `watch`-function will get resolved when the background job is done, or rejected when the job failed in the background.\n\n**Example**\n\n```js\n// Creating a new Storage with 1TB Size\nclient.Storage.create({\n  name: \"Storage1\",\n  capacity: 1024,\n  location_uuid: \"39a7d783-3873-4b2f-915b-4c86c28344e5\",\n}).then(function (_result) {\n  console.log(\n    \"Storage with UUID: \" + _result.result.object_uuid + \" is provisioning...\"\n  );\n\n  // Watching the Storage until it is ready to work with\n  _result.watch().then(function () {\n    console.log(\"Storage is ready to use!\");\n  })\n  .catch(e =\u003e {\n    console.error('Provisioning the storage failed', e));\n  });\n});\n```\n\nYou can also directly query a job status with a request-ID (`X-Request-Id` header) by using\n```js\nclient.watchRequest( \"[x-request-uuid]\" ).then(function () {\n  console.log(\"Storage is ready to use!\");\n})\n.catch(e =\u003e {\n  console.error('Provisioning the storage failed', e));\n});\n```\n\n\n## Global error handling\n\nWhile you can handle errors per request by handling rejected promises or checking the `success` property of the result in callbacks, you can also set a global error handler for the API.\n\nTo do that you register a handler function with the `addLogger` method of the API client. You can also register more handlers by multiple calling `addLogger`. All your error handlers will get executed on each error.\n\n**Example**\n\n```js\nconst client = new gridscale.Client(API - Token, User - UUID);\n\nclient.addLogger((error) =\u003e {\n  // error object described below\n  console.error(\"API ERROR OCCURED\", error.id, error.result);\n});\n```\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgridscale%2Fgsclient-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgridscale%2Fgsclient-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgridscale%2Fgsclient-js/lists"}