{"id":23139041,"url":"https://github.com/circuit/circuit-sdk","last_synced_at":"2025-08-17T11:33:27.280Z","repository":{"id":23316649,"uuid":"98701529","full_name":"circuit/circuit-sdk","owner":"circuit","description":"JavaScript and Node.js SDK for Circuit","archived":false,"fork":false,"pushed_at":"2022-12-30T20:41:26.000Z","size":9302,"stargazers_count":17,"open_issues_count":11,"forks_count":6,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-08-09T02:38:51.339Z","etag":null,"topics":["bot","circuit","collaboration","sdk","unify","webrtc"],"latest_commit_sha":null,"homepage":"https://www.circuit.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/circuit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-29T02:02:14.000Z","updated_at":"2023-02-14T18:14:22.000Z","dependencies_parsed_at":"2023-01-13T23:07:17.971Z","dependency_job_id":null,"html_url":"https://github.com/circuit/circuit-sdk","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circuit%2Fcircuit-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circuit%2Fcircuit-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circuit%2Fcircuit-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circuit%2Fcircuit-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circuit","download_url":"https://codeload.github.com/circuit/circuit-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230121628,"owners_count":18176477,"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":["bot","circuit","collaboration","sdk","unify","webrtc"],"created_at":"2024-12-17T13:13:09.360Z","updated_at":"2024-12-17T13:13:10.129Z","avatar_url":"https://github.com/circuit.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Circuit JavaScript and Node.js SDK\n==================================\n\n[![GitHub release](https://img.shields.io/github/release/circuit/circuit-sdk.svg)](https://github.com/circuit/circuit-sdk)\n[![Build Status](https://travis-ci.org/circuit/circuit-sdk.svg?branch=master)](https://travis-ci.org/circuit/circuit-sdk)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n\n### Prerequisites\n* Register for a free developer account and create your own OAuth app to get a `client_id`. See [Getting Started](https://circuit.github.io/) for details.\n\n### API Reference\nhttps://circuitsandbox.net/sdk/ with most APIs described in the [Client](https://circuitsandbox.net/sdk/classes/Client.html) class.\n\n### Usage\n\n#### JavaScript\nAdd the the line below to the HTML file of your app. This will include the latest version of Circuit SDK and make the `Circuit` object available.\n```html\n\u003cscript type=\"text/javascript\" src=\"https://unpkg.com/circuit-sdk\"\u003e\u003c/script\u003e\n```\n\nJS SDK can also be imported via CommonJS or AMD. View the repo [UMD](https://github.com/circuit/umd) for the different types of usage, or [circuit-ionic-start](https://github.com/circuit/circuit-ionic-starter) for example how import the SDK via `require` using webpack.\n\n#### Node.js\n```bash\nnpm install --save circuit-sdk\n```\n\n### Application Types\nThe majority of apps fall in one of the three types below. Each type uses a different OAuth 2.0 Grant.\n\n1. **Client-side web applications** use the JavaScript SDK with the [OAuth 2.0 Implicit Grant](https://circuit.github.io/oauth.html#implicit).\n   ```javascript\n   // No client_secret needed for Implicit Grant. SDK will obtain access token.\n   const client = new Circuit.Client({\n     client_id: '\u003cyour client_id\u003e',\n     domain: 'circuitsandbox.net'\n   });\n   client.logon()\n     .then(user =\u003e console.log('Logged on as ' + user.displayName))\n   ```\n\n2. **Server-side web applications** use the JavaScript SDK (or [REST API](https://circuitsandbox.net/rest/v2/swagger/ui/index.html)) on the client, but handle the authentication flow on the server using the [OAuth 2.0 Authorization Code Grant](https://circuit.github.io/oauth.html#authorization_code). The access token is obtained on the server and then passed to the client to use in the Circuit JavaScript SDK. These apps may also use the Node.js SDK on the server side to act on behalf of the user.\u003cbr\u003e\nExample apps: [node-linkify](https://github.com/circuit/node-linkify) or [circuit-google-assistant](https://github.com/circuit/circuit-google-assistant)\n   ```javascript\n   // access token is obtained and managed by server-side app\n   const client = new Circuit.Client({\n     client_id: '\u003cyour client_id\u003e',\n     domain: 'circuitsandbox.net'\n   });\n   client.logon({accessToken: '\u003caccess_token\u003e'})\n     .then(user =\u003e console.log('Logged on as ' + user.displayName))\n   ```\n\n3. **Bots** use the [Node.js SDK](https://www.npmjs.com/package/circuit-sdk) or the [REST API](https://circuitsandbox.net/rest/v2/swagger/ui/index.html) and use the [OAuth 2.0 Client Credentials Grant](https://circuit.github.io/oauth.html#client_credentials). Bots are a special type of user; they don't login on behalf of a regular user, hence no OAuth popup asking for a user`s credentials and permissions.\u003cbr\u003e\nExample bots: [xlator-bot](https://github.com/circuit/xlator-bot) or [node-sdk-example](https://github.com/circuit/node-sdk-example)\u003cbr\u003e\nExample electron bots: [webrtc-bot-example](https://github.com/circuit/webrtc-bot-example) or [live-cam-bot](https://github.com/circuit/live-cam-bot)\n   ```javascript\n   const Circuit = require('circuit-sdk');\n   const client = new Circuit.Client({\n     client_id: '\u003cclient_id\u003e',\n     client_secret: '\u003cclient_secret\u003e',\n     domain: 'circuitsandbox.net'\n   });\n   client.logon()\n     .then(user =\u003e console.log('Logged on as bot: ' + user.emailAddress))\n   ```\n\n\n\n### Examples\n\n\u003e JavaScript examples are located at [/examples/js](/examples/js) with more examples on [jsbin](https://circuit.github.io/jssdk.html#jsbin).\n\n\u003e Node.js example apps are on [github](https://github.com/circuit). A summary is listed [here](https://circuit.github.io/nodejs.html). Runkit allows playing with Node.js modules live, similar to jsbin or jsfiddle on the client. [Try it on runkit](https://runkit.com/rogeru/circuit-sdk)\n\nHere are some snippets to get you started.\n\n#### Create Group Conversation and send text message\nLogon as bot, create a group conversation with two users and send a text message.\n```javascript\nclient.logon()\n  .then(user =\u003e console.log(`Logged on as ${user.displayName}`, user))\n  .then(() =\u003e client.getUsersByEmail(['kim.jackson@mailinator.com', 'maeva.barnaby@mailinator.com']))\n  .then(users =\u003e users.map(user =\u003e user.userId))\n  .then(userIds =\u003e client.createGroupConversation(userIds, 'runkit example'))\n  .then(conv =\u003e client.addTextItem(conv.convId, 'I am test bot. What can I do for you?'))\n  .then(client.logout)\n  .catch(console.error)\n```\n\n#### Get Conversations\nGet 10 newest conversations of logged on user.\n```javascript\nclient.getConversations({numberOfConversations: 10})\n  .then(conversations =\u003e console.log(`Retrieved ${conversations.length} conversations`))\n```\n\n#### Video call with another Circuit user\nStart a video call with another user. Create conversation if not yet existing.\n\u003e Only applicable to JavaScript SDK and only on browsers supporting WebRTC\n```javascript\nclient.makeCall('bob@company.com', {audio: true, video: true}, true)\n  .then(call =\u003e console.log('New call: ', call));\n```\n\n#### Listen for events\n```javascript\n// Register new items added to the feed of this user. E.g. incoming text message\nclient.addEventListener('itemAdded', item =\u003e\n  console.log('itemAdded event received:', item));\n\n// Register for connection state changes\nclient.addEventListener('connectionStateChanged', evt =\u003e {\n  console.log(`New state is ${evt.state}`);\n});\n\n// Register and log all events\nCircuit.supportedEvents.forEach(e =\u003e client.addEventListener(e, console.log));\n```\n\n#### Create an injector\nInjectors allow extending the conversation, item and user objects within the SDK.\nIn this example a new attribute `teaser` is created on the item object. This `teaser` will be added to item objects in any reponse or event from the SDK.\n```javascript\nCircuit.Injectors.itemInjector = function (item) {\n  if (item.type === Circuit.Enums.ConversationItemType.TEXT) {\n    // Create item.teaser attribute with replacing br and hr tags with a space\n    item.teaser = item.text.content.replace(/\u003c(br[\\/]?|\\/li|hr[\\/]?)\u003e/gi, ' ');\n  } else {\n    item.teaser = item.type;\n  }\n};\n```\n\n### Supported Browsers\nChrome and Firefox are officially supported.\n\n### Help us improve the SDK\nHelp us improve the SDK or examples by sending us a pull-request or opening a [GitHub Issue](https://github.com/circuit/circuit-sdk/issues/new). \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircuit%2Fcircuit-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcircuit%2Fcircuit-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircuit%2Fcircuit-sdk/lists"}