{"id":22663440,"url":"https://github.com/stevanfreeborn/onspring-api-sdk-javascript","last_synced_at":"2026-04-05T20:32:49.004Z","repository":{"id":65499437,"uuid":"593478576","full_name":"StevanFreeborn/onspring-api-sdk-javascript","owner":"StevanFreeborn","description":"A javascript SDK for interacting with the Onspring API.","archived":false,"fork":false,"pushed_at":"2024-03-23T21:03:48.000Z","size":703,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-03-24T20:38:30.606Z","etag":null,"topics":["javascript","npm","npm-package","onspring","sdk","typescript"],"latest_commit_sha":null,"homepage":"https://stevanfreeborn.github.io/onspring-api-sdk-javascript/","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/StevanFreeborn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","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":"2023-01-26T04:52:48.000Z","updated_at":"2024-07-19T09:51:24.280Z","dependencies_parsed_at":"2023-02-26T09:46:01.806Z","dependency_job_id":"27797630-25d8-4066-9627-af900fa7931e","html_url":"https://github.com/StevanFreeborn/onspring-api-sdk-javascript","commit_stats":{"total_commits":242,"total_committers":4,"mean_commits":60.5,"dds":0.4049586776859504,"last_synced_commit":"e937d05490a64f6280b11a1570ab004673d548ae"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevanFreeborn%2Fonspring-api-sdk-javascript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevanFreeborn%2Fonspring-api-sdk-javascript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevanFreeborn%2Fonspring-api-sdk-javascript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevanFreeborn%2Fonspring-api-sdk-javascript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StevanFreeborn","download_url":"https://codeload.github.com/StevanFreeborn/onspring-api-sdk-javascript/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246162150,"owners_count":20733357,"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":["javascript","npm","npm-package","onspring","sdk","typescript"],"created_at":"2024-12-09T12:19:15.577Z","updated_at":"2025-12-30T23:19:31.053Z","avatar_url":"https://github.com/StevanFreeborn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Onspring API Javascript SDK\n\n[![lint_format_test](https://github.com/StevanFreeborn/onspring-api-sdk-javascript/actions/workflows/lint_format_test.yaml/badge.svg?branch=master)](https://github.com/StevanFreeborn/onspring-api-sdk-javascript/actions/workflows/lint_format_test.yaml)\n[![codecov](https://codecov.io/github/StevanFreeborn/onspring-api-sdk-javascript/branch/master/graph/badge.svg?token=G1L3GKE0LV)](https://codecov.io/github/StevanFreeborn/onspring-api-sdk-javascript)\n[![build_publish](https://github.com/StevanFreeborn/onspring-api-sdk-javascript/actions/workflows/build_publish.yml/badge.svg?branch=master)](https://github.com/StevanFreeborn/onspring-api-sdk-javascript/actions/workflows/build_publish.yml)\n[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)\n[![NPM](https://img.shields.io/npm/l/onspring-api-sdk)](License.txt)\n![npm](https://img.shields.io/npm/v/onspring-api-sdk)\n![npm](https://img.shields.io/npm/dt/onspring-api-sdk)\n\nThe Javascript SDK for the Onspring API is meant to simplify development in Javascript for Onspring customers who want to build integrations with their Onspring instance.\n\n**Note:** This is an unofficial SDK for the Onspring API. It was not built in consultation with Onspring Technologies LLC or a member of their development team.\n\nThis SDK was developed independently using Onspring's existing [C# SDK](https://github.com/onspring-technologies/onspring-api-sdk), the Onspring API's [swagger page](https://api.onspring.com/swagger/index.html), and [api documentation](https://software.onspring.com/hubfs/Training/Admin%20Guide%20-%20v2%20API.pdf) as the starting point with the intention of making development of integrations done in Javascript with an Onspring instance quicker and more convenient.\n\n## 🛠️ Dependencies\n\n### Node.js\n\n![node-current](https://img.shields.io/node/v/onspring-api-sdk)\n\nRequires use of [Node.js](https://nodejs.org/en/) 14.x or later.\n\n### Axios\n\n![npm (prod) dependency version](https://img.shields.io/npm/dependency-version/onspring-api-sdk/axios)\n\nAll methods for the `OnspringClient` make use of the [Axios](https://axios-http.com/) http client to interact with the Onspring API.\n\n### Form-Data\n\n![npm (prod) dependency version](https://img.shields.io/npm/dependency-version/onspring-api-sdk/form-data)\n\nWhen it is necessary to send requests to the Onspring API using `multi-part/form-data` the [Form-Data](https://www.npmjs.com/package/form-data) package is used.\n\n## 💾 Installation\n\nInstall the SDK using [npm](https://www.npmjs.com/):\n\n`npm install onspring-api-sdk`\n\n## 🔑 API Key\n\nIn order to successfully interact with the Onspring Api you will need an API key. API keys are obtained by an Onspring user with permissions to at least **Read** API Keys for your instance via the following steps:\n\n1. Login to the Onspring instance.\n2. Navigate to **Administration** \u003e **Security** \u003e **API Keys**\n3. On the list page, add a new API Key - this will require **Create** permissions - or click an existing API key to view its details.\n4. Click on the **Developer Information** tab.\n5. Copy the **X-ApiKey Header** value from this tab.\n\n**Important:**\n\n- An API Key must have a status of `Enabled` in order to make authorized requests.\n- Each API Key must have an assigned Role. This role controls the permissions for requests made. If the API Key used does not have sufficient permissions the requests made won't be successful.\n\n### 🔒 Permission Considerations\n\nYou can think of any API Key as another user in your Onspring instance and therefore it is subject to all the same permission considerations as any other user when it comes to its ability to access data in your instance. The API Key you use needs to have all the correct permissions within your instance to access the data requested. Things to think about in this context are `role security`, `content security`, and `field security`.\n\n## 🧑🏻‍💻 Start Coding\n\n### `OnspringClient`\n\nThe most common way to use the SDK is to create an `OnspringClient` instance and call its methods. Its constructor requires two parameters:\n\n- `baseUrl` - currently this should always be: `https://api.onspring.com`\n- `apiKey` - the value obtained by following the steps in the **API Key** section\n\nIt is best practice to read these values in from a configuration file for both flexibility and security purposes.\n\nExample `.env` file:\n\n```env\nAPI_KEY=000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000\nBASE_URL=https://api.onspring.com\n```\n\nExample constructing `OnspringClient`:\n\n`CommonJS`\n\n```js\nconst { OnspringClient } = require('onspring-api-sdk');\nconst dotenv = require('dotenv');\ndotenv.config();\n\nconst client = new OnspringClient(process.env.BASE_URL, process.env.API_KEY);\n```\n\n`ES Module`\n\n```js\nimport dotenv from 'dotenv';\nimport { OnspringClient } from 'onspring-api-sdk';\ndotenv.config();\n\nconst client = new OnspringClient(process.env.BASE_URL, process.env.API_KEY);\n```\n\n### `Axios` Instance Configuration\n\nBy default when you construct an instance of the `OnspringClient` a new `Axios` instance will also be created. Its `baseURL` property will always be set to the `baseUrl` parameter based to the `OnspringClient`'s constructor and its headers will always contain the proper `x-api-key` header.\n\nYou can though pass a third optional argument to the `OnspringClient` constructor that specifies additional configuration options for the `Axios` instance used to make requests.\n\n```js\nimport dotenv from 'dotenv';\nimport { OnspringClient } from 'onspring-api-sdk';\ndotenv.config();\n\nconst configs = {\n  timeout: 5000,\n};\n\nconst client = new OnspringClient(\n  process.env.BASE_URL,\n  process.env.API_KEY,\n  configs\n);\n```\n\n### `ApiResponse`\n\nEach `OnspringClient` method - aside from `canConnect` - returns an `ApiResponse` object which will have the following properties:\n\n- `statusCode` - The http status code of the response.\n- `isSuccessful` - Indicates whether the request succeeded.\n- `data` - If the request was successful will contain the response data deserialized to custom classes.\n- `message` - A message that may provide more detail about the request when no successful\n\n### CommonJS or ES Modules\n\nThere is support for using either CommonJS or ES Modules depending upon your preference. This documentation will use the later in the usage examples.\n\n### Types\n\nThe package is written in typescript and all types are exported and available for you to use.\n\n### Full API Documentation\n\nYou may wish to refer to the full [Onspring API documentation](https://software.onspring.com/hubfs/Training/Admin%20Guide%20-%20v2%20API.pdf) when determining which values to pass as parameters to some of the `OnspringClient` methods. There is also a [swagger page](https://api.onspring.com/swagger/index.html) that you can use for making exploratory requests.\n\n## 📋 Examples\n\nNote the following code snippets assume you've already instantiated an `OnspringClient` as shown in the [OnspringClient](#onspringclient) section.\n\n### Connectivity\n\n#### Verify connectivity\n\n```js\nconst res = await client.canConnect();\nconsole.log(res); // true or false\n```\n\n### Apps\n\n#### Get Apps\n\nReturns a paged collection of apps and/or surveys that can be paged through. By default the page size is 50 and page number is 1.\n\n```js\nconst res = await client.getApps();\nconst apps = res.data.items;\n\nfor (const app of apps) {\n  console.log(app);\n}\n```\n\nYou can set your own page size and page number (max is 1,000) as well.\n\n```js\nimport { PagingRequest } from 'onspring-api-sdk';\n\nconst res = await client.getApps(new PagingRequest(1, 1));\nconst apps = res.data.items;\n\nfor (const app of apps) {\n  console.log(app);\n}\n```\n\n#### Get App By Id\n\nReturns an Onspring app or survey according to provided id.\n\n```js\nconst res = await client.getAppById(130);\nconst app = res.data;\n\nconsole.log(app);\n```\n\n#### Get Apps By Ids\n\nReturns a collection of Onspring apps and/or surveys according to provided ids.\n\n```js\nconst res = await client.getAppsByIds([130, 131]);\nconst apps = res.data.items;\n\nfor (const app of apps) {\n  console.log(app);\n}\n```\n\n### Fields\n\n#### Get Field By Id\n\nReturns an Onspring field according to provided id.\n\n```js\nconst res = await client.getFieldById(4793);\nconst field = res.data;\n\nconsole.log(field);\n```\n\n#### Get Fields By Ids\n\nReturns a collection of Onspring fields according to provided ids.\n\n```js\nconst res = await client.getFieldsByIds([4793, 4801]);\nconst fields = res.data.items;\n\nfor (const field of fields) {\n  console.log(field);\n}\n```\n\n#### Get Fields By App Id\n\nReturns a paged collection of fields that can be paged through. By default the page size is 50 and page number is 1.\n\n```js\nconst res = await client.getFieldsByAppId(132);\nconst fields = res.data.items;\n\nfor (const field of fields) {\n  console.log(field);\n}\n```\n\nYou can set your own page size and page number (max is 1,000) as well.\n\n```js\nimport { PagingRequest } from 'onspring-api-sdk';\n\nconst res = await client.getFieldsByAppId(132, new PagingRequest(1, 1));\nconst fields = res.data.items;\n\nfor (const field of fields) {\n  console.log(field);\n}\n```\n\n### Files\n\n#### Get File Info By Id\n\nReturns the Onspring file's metadata.\n\n```js\nconst res = await client.getFileInfoById(1, 4806, 909);\nconst fileInfo = res.data;\n\nconsole.log(fileInfo);\n```\n\n#### Get File By Id\n\nReturns the file itself.\n\n```js\nimport fs from 'fs';\n\nconst res = await client.getFileById(1, 4806, 909);\nconst file = res.data;\n\nconsole.log(file.contentLength);\nconsole.log(file.contentType);\nconsole.log(file.fileName);\nfile.stream.pipe(fs.createWriteStream(file.fileName));\n```\n\n#### Save File\n\n```js\nimport fs from 'fs';\nimport { SaveFileRequest } from 'onspring-api-sdk';\n\nconst request = new SaveFileRequest(\n  1,\n  4806,\n  'notes',\n  new Date(),\n  'test-attachment.txt',\n  'text/plain',\n  fs.createReadStream('test-attachment.txt')\n);\n\nconst res = await client.saveFile(request);\nconst fileId = res.data.id;\n\nconsole.log(fileId);\n```\n\n#### Delete File By Id\n\n```js\nconst res = await client.deleteFileById(1, 4806, 1505);\n\nres.statusCode === 204\n  ? console.log('File deleted')\n  : console.log('Error deleting file');\n```\n\n### Lists\n\n#### Add Or Update List Value\n\nTo add a list value don't provide an id value.\n\n```js\nimport { ListItemRequest } from 'onspring-api-sdk';\n\nconst request = new ListItemRequest(638, null, 'New Value', 1, '#000000');\nconst res = await client.addOrUpdateListItem(request);\nconst itemId = res.data.id;\n\nconsole.log(itemId);\n```\n\nTo update a list value provide an id value.\n\n```js\nimport { ListItemRequest } from 'onspring-api-sdk';\n\nconst request = new ListItemRequest(\n  638,\n  '35c79a46-04b8-4069-bbc1-161a175f962c',\n  'Updated Value',\n  1,\n  '#000000'\n);\n\nconst res = await client.addOrUpdateListItem(request);\nconst itemId = res.data.id;\n\nconsole.log(itemId);\n```\n\n#### Delete List Value\n\n```js\nconst res = await client.deleteListItemById(\n  638,\n  '35c79a46-04b8-4069-bbc1-161a175f962c'\n);\n\nres.statusCode === 204\n  ? console.log('List item deleted')\n  : console.log('Error deleting list item');\n```\n\n### Records\n\n#### Get Records By App Id\n\nReturns a paged collection of records that can be paged through. By default the page size is 50 and page number is 1.\n\n```js\nimport { GetRecordsByAppIdRequest } from 'onspring-api-sdk';\n\nconst request = new GetRecordsByAppIdRequest(130);\nconst res = await client.getRecordsByAppId(request);\nconst records = res.data.items;\n\nfor (const record of records) {\n  console.log(record);\n}\n```\n\nYou can set your own page size and page number (max is 1,000) as well. In addition to specifying what field values to return and in what format (Raw vs. Formatted) to return them.\n\n```js\nimport {\n  DataFormat,\n  GetRecordsByAppIdRequest,\n  PagingRequest,\n} from 'onspring-api-sdk';\n\nconst request = new GetRecordsByAppIdRequest(\n  130,\n  [4804],\n  DataFormat.Raw,\n  new PagingRequest(1, 1)\n);\n\nconst res = await client.getRecordsByAppId(request);\nconst records = res.data.items;\n\nfor (const record of records) {\n  console.log(record);\n}\n```\n\n#### Get Record By Id\n\nReturns an onspring record based on the provided app and record ids.\n\n```js\nimport { GetRecordRequest } from 'onspring-api-sdk';\n\nconst request = new GetRecordRequest(130, 1);\nconst res = await client.getRecordById(request);\nconst record = res.data;\n\nconsole.log(record);\n```\n\nYou can also specify what field values to return and in what format (Raw vs. Formatted) to return them.\n\n```js\nimport { DataFormat, GetRecordRequest } from 'onspring-api-sdk';\n\nconst request = new GetRecordRequest(130, 1, [4804], DataFormat.Raw);\nconst res = await client.getRecordById(request);\nconst record = res.data;\n\nconsole.log(record);\n```\n\n#### Get Records By Ids\n\nReturns a collection of Onspring records based on the provided appId and recordIds.\n\n```js\nimport { GetRecordsRequest } from 'onspring-api-sdk';\n\nconst request = new GetRecordsRequest(130, [1]);\nconst res = await client.getRecordsByIds(request);\nconst records = res.data.items;\n\nfor (const record of records) {\n  console.log(record);\n}\n```\n\nYou can also specify what field values to return and in what format (Raw vs. Formatted) to return them.\n\n```js\nimport { DataFormat, GetRecordsRequest } from 'onspring-api-sdk';\n\nconst request = new GetRecordsRequest(130, [1], [4804], DataFormat.Formatted);\nconst res = await client.getRecordsByIds(request);\nconst records = res.data.items;\n\nfor (const record of records) {\n  console.log(record);\n}\n```\n\n#### Query Records\n\nReturns a paged collection of records based on a criteria that can be paged through. By default the page size is 50 and page number is 1.\n\n```js\nimport {\n  FilterOperators,\n  QueryFilter,\n  QueryRecordsRequest,\n} from 'onspring-api-sdk';\n\nconst filter = new QueryFilter(4745, FilterOperators.GreaterThan, 0);\nconst request = new QueryRecordsRequest(130, filter);\nconst res = await client.queryRecords(request);\nconst records = res.data.items;\n\nfor (const record of records) {\n  console.log(record);\n}\n```\n\nYou can set your own page size and page number (max is 1,000) as well. In addition to specifying what field values to return and in what format (Raw vs. Formatted) to return them.\n\n```js\nimport {\n  DataFormat,\n  FilterOperators,\n  PagingRequest,\n  QueryFilter,\n  QueryRecordsRequest,\n} from 'onspring-api-sdk';\n\nconst filter = new QueryFilter(4745, FilterOperators.GreaterThan, 0);\nconst request = new QueryRecordsRequest(\n  130,\n  filter,\n  [4804],\n  DataFormat.Formatted,\n  new PagingRequest(1, 1)\n);\n\nconst res = await client.queryRecords(request);\nconst records = res.data.items;\n\nfor (const record of records) {\n  console.log(record);\n}\n```\n\nFor further details on constructing the `filter` parameter please refer to the [documentation](https://software.onspring.com/hubfs/Training/Admin%20Guide%20-%20v2%20API.pdf) for the Onspring API.\n\n#### Add or Update A Record\n\nYou can add a record by not providing a record id value. If successful will return the id of the added record.\n\n```js\nimport { Record, StringRecordValue } from 'onspring-api-sdk';\n\nconst record = new Record(130, null);\nconst fieldValue = new StringRecordValue(4804, 'Test');\nrecord.addValue(fieldValue);\n\nconst res = await client.saveRecord(record);\nconst newRecordId = res.data.id;\n\nconsole.log(newRecordId);\n```\n\nYou can update a record by providing its id. If successful will return the id of record updated.\n\n```js\nimport { Record, StringRecordValue } from 'onspring-api-sdk';\n\nconst record = new Record(130, 607);\nconst fieldValue = new StringRecordValue(4804, 'Updated');\nrecord.addValue(fieldValue);\n\nconst res = await client.saveRecord(record);\nconst updatedRecordId = res.data.id;\n\nconsole.log(updatedRecordId);\n```\n\n#### Delete Record By Id\n\nDelete an individual record based upon its id.\n\n```js\nconst res = await client.deleteRecordById(130, 607);\n\nres.statusCode === 204\n  ? console.log('Record deleted')\n  : console.log('Error deleting record');\n```\n\n#### Delete Records By Ids\n\nDelete a batch of records based upon their ids.\n\n```js\nconst res = await client.deleteRecordsByIds(130, [608, 609]);\n\nres.statusCode === 204\n  ? console.log('Records deleted')\n  : console.log('Error deleting records');\n```\n\n### Reports\n\n#### Get Report By Id\n\nReturns the report for the provided id.\n\n```js\nconst res = await client.getReportById(408);\nconst report = res.data;\n\nconsole.log(report);\n```\n\nYou can also specify the format of the data in the report as well as whether you are requesting the report's data or its chart data.\n\n```js\nimport { DataFormat, ReportDataType } from 'onspring-api-sdk';\n\nconst res = await client.getReportById(\n  409,\n  DataFormat.Formatted,\n  ReportDataType.ChartData\n);\nconst report = res.data;\n\nconsole.log(report);\n```\n\n#### Get Reports By App Id\n\nReturns a paged collection of reports that can be paged through. By default the page size is 50 and page number is 1.\n\n```js\nconst res = await client.getReportsByAppId(130);\nconst reports = res.data.items;\n\nfor (const report of reports) {\n  console.log(report);\n}\n```\n\nYou can set your own page size and page number (max is 1,000) as well.\n\n```js\nimport { PagingRequest } from 'onspring-api-sdk';\n\nconst res = await client.getReportsByAppId(130, new PagingRequest(1, 1));\nconst reports = res.data.items;\n\nfor (const report of reports) {\n  console.log(report);\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevanfreeborn%2Fonspring-api-sdk-javascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstevanfreeborn%2Fonspring-api-sdk-javascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevanfreeborn%2Fonspring-api-sdk-javascript/lists"}