{"id":25933105,"url":"https://github.com/roam-ai/roam-js","last_synced_at":"2026-05-12T04:34:52.557Z","repository":{"id":48723018,"uuid":"337980475","full_name":"roam-ai/roam-js","owner":"roam-ai","description":"JavaScript Pub/Sub Library; JS library to subscribe to realtime location updates from Roam.ai's location SDKs.","archived":false,"fork":false,"pushed_at":"2021-10-12T10:22:40.000Z","size":305,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-01-25T13:05:34.566Z","etag":null,"topics":["gps","javasc","location","npm","pubsub","roam","roam-js"],"latest_commit_sha":null,"homepage":"https://roam.ai/","language":"JavaScript","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/roam-ai.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":null,"support":null}},"created_at":"2021-02-11T09:19:04.000Z","updated_at":"2024-01-25T13:05:34.567Z","dependencies_parsed_at":"2022-09-14T12:51:28.444Z","dependency_job_id":null,"html_url":"https://github.com/roam-ai/roam-js","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roam-ai","download_url":"https://codeload.github.com/roam-ai/roam-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241763740,"owners_count":20016162,"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":["gps","javasc","location","npm","pubsub","roam","roam-js"],"created_at":"2025-03-04T00:52:09.828Z","updated_at":"2025-12-03T11:04:30.031Z","avatar_url":"https://github.com/roam-ai.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://roam.ai\" target=\"_blank\" align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/roam-ai/roam-js/blob/master/logo.png?raw=true\" width=\"180\"\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n\u003c/p\u003e\n\n[![npm version](https://badge.fury.io/js/roam-js.svg)](https://badge.fury.io/js/roam-js)\n[![Npm Publish](https://github.com/roam-ai/roam-js/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/roam-ai/roam-js/actions/workflows/npm-publish.yml)\n\n# Official Roam Javascript SDK\n\nA Javascript library for Roam Location and Events Subscription. It is used to subscribe to user's locations and events at project level or location of a single user.\n\nroam-js supports subscription to the following location and events data:\n- Specific user \n- All users of a group\n- All users of project\n\nNote: Before you get started [signup to our dashboard](https://roam.ai/) to get your Publishable Keys.\n\n# Installation:\n\n## Via NPM\nYou can install our package using npm.\n```\nnpm install roam-js\n```\n\n## Via CDN\nroam-js bundle is available through http://unpkg.com, specifically at https://unpkg.com/roam-js/dist/roam.min.js. See http://unpkg.com for the full documentation on version ranges.\n\n# Usage\nYou can think this library as a wrapper around our REST API which needs your Publishable Key for authorization and it works as per project level. It is fairly simple to use:\n- `Initialize()` the package with the publishable key. This will return an instance of our client.\n- Define your custom callback function. `client.setCallback(fn)`\n- Create an instance of subscription. You can create subscription for project, user or group of users using the following methods on client:\n    - Location Subscriptions:\n        + `projectSubscription()` takes no parameters\n        + `groupSubscription(greoupID)` - takes in group ID as parameter\n        + `userSubscription(userID)` - takes in a single user ID or a array of user ids as parameter\n    - Events Subscription:\n        + `projectEventsSubscription()` takes no parameters\n        + `groupEventsSubscription(greoupID)` - takes in group ID as parameter\n        + `userEventsSubscription(userID)` - takes in a single user ID or a array of user ids as parameter\n- Use `subscribe()` method on the created subscription to start receiving realtime location data\n- To stop receiving data, call unsubscribe method. \n- To `disconnect()` call disconnect method on client.\nPlease find the example usage below:\n```\nvar roam = require(\"roam-js\")\n\nconst pk = process.env.roam_pk;\n\nroam.Initialize(pk)\n    .then((client)=\u003e{\n        client.setCallback(function(message, messageType, userID){console.log(message, messageType, userID)})\n        \n        client.projectSubscription()\n        .then((subscription)=\u003e{\n            subscription.subscribe()\n            .then((msg)=\u003e{\n                console.log(msg)\n                subscription.unsubscribe()\n                .then((msg)=\u003e{\n                    console.log(msg)\n                    client.disconnect().then((msg)=\u003e{\n                        console.log(msg)\n                    })\n                })\n                .catch((err)=\u003e{\n                   console.log(err)\n                })\n            }\n            )\n        })\n        .catch((err)=\u003e{\n           console.log(err)\n        })\n        \n})\n.catch((err)=\u003e{\n    console.log(err)\n})\n```\n\n# Methods\n\n## Initialize\nFirst order of process is initialization of the library.\nInitialize function takes in publishable key as parameter. You can get the publishable key from our dashboard once you have created a project.\nInitialize returns a promise of our client.  \n\n```\nclient = await roam.Initialize(\"\u003cYour publishable key\u003e\")\n```\n\n## Setting up callback function\nOnce initialized, we recommend setting up a callback function. This callback function will be called once you receive any data from our backend. We provide 3 parameters for callback function in the following order\n1. message : Actual message sent from the server\n2. messageType: locations or events message type\n3. userID: the userID to which the location or event belongs.\n```\nvar callback = function(message, messageType, userID){\n    console.log(message, messageType, userID)\n}\nclient.setCallback(callback)\n```\n\n## Subscription\nroam-js supports 3 types of subscriptions:\n - project subscription\n - user subscription\n - group subscription\n - project events subscription\n - user events subscription\n - group events subscription\n\n### Project Subscription\nTo create a subscription that allow you to subscribe to location data of all users within the project, you can use `projectSubscription()` method of client. It does not take in any parameter.\n```\nsubscription = await client.projectSubscription()\n```\n\n### Group Subscription\nTo create a subscription that allow you to subscribe to location data of all users within the group, you can use `groupSubscription(groupID)` method of client. It takes group ID as parameter.\n```\nsubscription = await client.groupSubscription('\u003cEnter group id\u003e')\n```\n\n### User Subscription\nTo create a subscription that allow you to subscribe to location data a user or multiple usesrs, you can use `userSubscription(user_1)` method of client. It takes user ID as parameter. \n```\nsubscription = await client.userSubscription('user_1')\n```\nTo subscribe to multiple users pass in user ids in an array as parameter\n```\nsubscription = await client.userSubscription(['user_1','user_2'])\n```\n### Project Events Subscription\nTo create a subscription that allow you to subscribe to location data of all users within the project, you can use `projectEventsSubscription()` method of client. It does not take in any parameter.\n```\nsubscription = await client.projectEventsSubscription()\n```\n\n### Group Events Subscription\nTo create a subscription that allow you to subscribe to location data of all users within the group, you can use `groupEventsSubscription(groupID)` method of client. It takes group ID as parameter.\n```\nsubscription = await client.groupEventsSubscription('\u003cEnter group id\u003e')\n```\n\n### User Events Subscription\nTo create a subscription that allow you to subscribe to location data a user or multiple usesrs, you can use `userEventsSubscription(groupID)` method of client. It takes user ID as parameter. \n```\nsubscription = await client.userEventsSubscription('user_1')\n```\nTo subscribe to multiple users pass in user ids in an array as parameter\n```\nsubscription = await client.userEventsSubscription(['user_1','user_2'])\n```\n### Subscribe to a subscription\nAll of the above methods will give you an subscription promise. You can subscribe to the subscription by using the following:\n```\nsubscription.subscribe()\n```\nThis will return a promise with a message whether subscription was subscribed successfully or throws an error.\n\n### Unsubscribe from a subscription\nTo stop getting location updates from a subscription you can use ubsubscribe method.\n```\nsubscription.unsubscribe()\n```\nThis will return a promise with a message whether unsubscribe was subscribed successfully or throws an error.\n\n## Disconnect\nTo disconnect from our server, call disconnect method on the client.\n```\nclient.disconnect()\n```\n\n## Example\nSee example codes in `examples/`.\nTo run the example, clone this repository, add your sdk key as environment veriable `pk` and run the app.\n\n## Need Help?\nIf you have any problems or issues over our SDK, feel free to create a github issue or submit a request on [Roam Help](https://geosparkai.atlassian.net/servicedesk/customer/portal/2).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froam-ai%2Froam-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-js/lists"}