{"id":18174555,"url":"https://github.com/superfaceai/one-sdk-js","last_synced_at":"2025-04-05T23:07:28.656Z","repository":{"id":37711449,"uuid":"264875841","full_name":"superfaceai/one-sdk-js","owner":"superfaceai","description":"1️⃣ One Node.js SDK for all the APIs you want to integrate with","archived":false,"fork":false,"pushed_at":"2025-01-31T15:23:30.000Z","size":4186,"stargazers_count":48,"open_issues_count":17,"forks_count":2,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-29T22:07:37.978Z","etag":null,"topics":["api","integration","javascript","nodejs","rest","rest-api","superface","typescript"],"latest_commit_sha":null,"homepage":"https://superface.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/superfaceai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-18T08:26:10.000Z","updated_at":"2025-01-31T15:23:33.000Z","dependencies_parsed_at":"2024-06-18T19:50:34.728Z","dependency_job_id":"6adac8b5-8452-40f8-9dc8-c5ce58065955","html_url":"https://github.com/superfaceai/one-sdk-js","commit_stats":{"total_commits":1138,"total_committers":19,"mean_commits":59.89473684210526,"dds":0.7724077328646749,"last_synced_commit":"210a706d7bce1dc863cf9528745feb20961377ed"},"previous_names":[],"tags_count":162,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superfaceai%2Fone-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superfaceai%2Fone-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superfaceai%2Fone-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superfaceai%2Fone-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/superfaceai","download_url":"https://codeload.github.com/superfaceai/one-sdk-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411231,"owners_count":20934653,"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":["api","integration","javascript","nodejs","rest","rest-api","superface","typescript"],"created_at":"2024-11-02T16:03:34.404Z","updated_at":"2025-04-05T23:07:28.622Z","avatar_url":"https://github.com/superfaceai.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[Website](https://superface.ai) | [Get Started](https://superface.ai/docs/getting-started) | [Documentation](https://superface.ai/docs) | [GitHub Discussions](https://sfc.is/discussions) | [Twitter](https://twitter.com/superfaceai) | [Support](https://superface.ai/support)\n\n\u003cimg src=\"https://github.com/superfaceai/one-sdk-js/raw/main/docs/LogoGreen.png\" alt=\"Superface\" width=\"100\" height=\"100\"\u003e\n\n# Superface OneSDK\n\n**One SDK for all the APIs you want to integrate with.**\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/superfaceai/one-sdk-js/main.yml)](https://github.com/superfaceai/one-sdk-js/actions/workflows/main.yml)\n[![npm](https://img.shields.io/npm/v/@superfaceai/one-sdk)](https://www.npmjs.com/package/@superfaceai/one-sdk)\n[![license](https://img.shields.io/npm/l/@superfaceai/one-sdk)](LICENSE)\n![TypeScript](https://img.shields.io/static/v1?message=TypeScript\u0026\u0026logoColor=ffffff\u0026color=007acc\u0026labelColor=5c5c5c\u0026label=built%20with)\n[![GitHub Discussions](https://img.shields.io/github/discussions/superfaceai/.github?logo=github\u0026logoColor=fff)](https://github.com/orgs/superfaceai/discussions)\n\nOneSDK is a universal API client which provides an unparalleled developer experience for every HTTP API. It enhances resiliency to API changes, and comes with built-in integration monitoring and provider failover.\n\nFor more details about Superface, visit [How it Works](https://superface.ai/how-it-works) and [Get Started](https://superface.ai/docs/getting-started).\n\n## Important Links\n\n- [Superface website](https://superface.ai)\n- [Get Started](https://superface.ai/docs/getting-started)\n- [Documentation](https://superface.ai/docs)\n- [Support](https://superface.ai/support)\n\n## Install\n\nTo install OneSDK into a Node.js project, run:\n\n```shell\nnpm install @superfaceai/one-sdk\n```\n\nor Yarn:\n\n```shell\nyarn add @superfaceai/one-sdk\n```\n\n## Usage\n\n### First time use\n\n💡 **For a quick usage example, check out [Get Started](https://superface.ai/docs/getting-started).**\n\nSuperface is all about use cases. You can start with one of the publically available use cases from the [Superface Catalog](https://superface.ai/catalog).\n\nOnce you've got your use case, you need to provide OneSDK with:\n\n- profile name and version\n- use case name\n- provider name\n- input parameters\n- (if necessary) provider-specific integration parameters\n- (if necessary) provider-specific security values\n\nThese can be found on the profile page (e.g. [vcs/user-repos](https://superface.ai/vcs/user-repos)). Security values need to be obtained through the relevant provider (e.g. on their website, in your account settings, by contacting them, etc.).\n\n```js\nconst { SuperfaceClient } = require('@superfaceai/one-sdk');\n\nconst sdk = new SuperfaceClient();\n\nasync function run() {\n  const profile = await sdk.getProfile({\n    id: '\u003cprofileName\u003e',\n    version: '\u003cprofileVersion\u003e',\n  });\n\n  const result = await profile.getUseCase('\u003cusecaseName\u003e').perform(\n    {\n      // Input parameters in format:\n      '\u003ckey\u003e': '\u003cvalue\u003e',\n    },\n    {\n      provider: '\u003cproviderName\u003e',\n      parameters: {\n        // Provider specific integration parameters in format:\n        '\u003cintegrationParameterName\u003e': '\u003cintegrationParameterValue\u003e',\n      },\n      security: {\n        // Provider specific security values in format:\n        '\u003csecurityValueId\u003e': {\n          // Security values as described on profile page\n        },\n      },\n    }\n  );\n\n  console.log(result.unwrap());\n}\n\nrun();\n```\n\nIf you are missing a use case, [let us know](#support)! You can also always [add your own use-case or API provider](https://superface.ai/docs/guides/how-to-create).\n\n### Advanced usage\n\nAs your project grows in size and complexity, you may find it useful to have a central location for configuring details concerning your API integrations. There are also some features that cannot be used with the simple approach described above, namely:\n\n- Using [locally stored profiles, maps and providers](https://superface.ai/docs/advanced-usage#local); e.g. (yet) unpublished integrations, or integrations with APIs internal to your organization.\n- Configuring [provider failover](https://superface.ai/docs/guides/using-multiple-providers#failover).\n\nFor these cases, there's Superface configuration.\nTo find out more, visit [Advanced Usage](https://superface.ai/docs/advanced-usage).\n\n## Security\n\nSuperface is not a proxy. The calls are always going directly from your application to API providers. Their contents are **never** sent anywhere else but to the selected provider's API.\n\nOneSDK accesses `superface/super.json` file if instructed to, and accesses cache in `node_modules/superface/.cache` directory. It also accesses local maps, profiles, and provider configuration as per configuration. Non-local maps, profiles and providers are loaded from the Superface remote registry at runtime, and cached locally. OneSDK also sends diagnostic usage report to Superface as described [below](#metrics-reporting).\n\nMore about how OneSDK handles secrets can be found in [SECURITY](SECURITY.md).\n\n## Metrics Reporting\n\nSuperface allows you to [monitor your integrations](https://superface.ai/docs/guides/integrations-monitoring) and display the metrics on a dashboard. There are three kinds of metrics reported:\n\n1. When an OneSDK instance is created\n2. After each perform - reporting success or failure of a given use case\n3. When provider failover is triggered - what provider failed and which one was switched to\n\nThese metrics contain no personal information nor the contents of the API calls and are rate limited as to not impact performance.\n\nUtilizing this functionality requires you to obtain and set a `SUPERFACE_SDK_TOKEN`. For more information, see [Integrations Monitoring](https://superface.ai/docs/guides/integrations-monitoring).\n\nHowever, even without an `SUPERFACE_SDK_TOKEN` set, this data is sent anonymized to Superface services for diagnostic purposes. All metrics reporting can be disabled by setting an environment variable:\n\n```shell\nSUPERFACE_DISABLE_METRIC_REPORTING=true\n```\n\nFor metrics to be successfuly sent, the application needs to exit properly, i.e. there should be no unhandled `Promise` rejections or exceptions.\n\n## Support\n\nIf you have any questions, want to report a bug, request a feature or you just want to talk, feel free to [open an issue](https://github.com/superfaceai/one-sdk-js/issues/new/choose) or reach us in other ways through the [Support page](https://superface.ai/support).\n\n## Public API\n\nOnly functions and APIs of entities below are a part of the public API, and can be safely relied upon not to break between semver-compatible releases.\n\nUsing other parts of this package is at your own risk.\n\n- SuperfaceClient API\n- Profile API\n- UseCase API\n- SuperJsonDocument Object\n- Result API\n\nUse of public APIs is described in the [reference](https://superface.ai/docs/reference/one-sdk).\n\n## Contributing\n\nWe welcome all kinds of contributions! Please see the [Contribution Guide](CONTRIBUTING.md) to learn how to participate.\n\n## License\n\nOneSDK is licensed under the [MIT License](LICENSE).\n\n© 2023 Superface s.r.o.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperfaceai%2Fone-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuperfaceai%2Fone-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperfaceai%2Fone-sdk-js/lists"}