{"_id":"urltm","_rev":"30-e3eb0d3cdf4ad409e726f9acd0499297","name":"urltm","dist-tags":{"latest":"1.4.0"},"versions":{"1.4.0":{"name":"urltm","version":"1.4.0","keywords":["realtime","abstraction","socket.io","pubnub","faye"],"author":{"name":"PubNub"},"license":"MIT","_id":"urltm@1.4.0","maintainers":[{"name":"ably","email":"support@ably.io"}],"homepage":"https://universal-realtime.github.io/urltm.js","bugs":{"url":"https://github.com/universal-realtime/urltm.js/issues"},"dist":{"shasum":"c972d7c81260d647a302fef45cce8db32418f3a2","tarball":"https://registry.npmjs.org/urltm/-/urltm-1.4.0.tgz","integrity":"sha512-5jpxHwOMeeo29lL3jcEDOQoEQRsMavMg/4WiHzBjHT7pOK77/puwViLf1jWUnvJgcZrn0LEov7E72mLArPgJzw==","signatures":[{"sig":"MEQCIG0iq+vX2wV5fR+3OFWaPo93URLoot5nDTuDNfaP5no4AiB1KTbSP0p/5GkqjA7zuJDfkEs9D2CTg+ynkbnoKSBdkw==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJh2/F5CRA9TVsSAnZWagAAFf8P/2OT+54yH6eY0dH83gLy\nOOFqR2YvMnnIYigZkDen0aFROKVNPddIPrHvXSAN7s/XcXfigtSOraLeX8V7\nrnj1pcB6PUDUnr6yEXzyrjEe9ZNOZ+LPqKHywCBwfFgsgzEWv8qtMw/tFSVA\nblMzlBKvPTNZYjPAZ3knPEwCv66xsU+5sIpJurbEHeJYuAfnw5bpIvmWv9Gz\nBDACqPh1SRsySXk4xGyv1MAkzxZleNJkGYro34I1uX41SM+mj5578rR3N4ak\nRAll2xUTf4AsFtXdoY1D38BDbsRpLioagoekZx6m+Zr9anCSRjrApHRA87QH\nEL0tSV5zzRZOfzygOUbQHfZXbKCTVDGyUWG0ZNneBhhQHwgDgnd7KiIehRyQ\nOoeqPisSEUXSjDU8cuuvbC7Taj+h/IVQpnuFUXHhw8DjZN3vdGvUXfn8bDy8\nRZk1yYnx6WXpa+2fQYJCq/gengwhYxdWwrBuVCSnrMMo/BZ34SpziEJAb73B\nWpgmVzkNbhVIrXdC5IGlSG2c5uFZQtNOBq+tJYsYxsNUf23aEUeyc0w0tfHb\nyFYwBgsFz6Nbduwj0OTAiu7Hk9YMkANhbyfZ9UBlz8rIgB44+ha6jwvcehxm\nge3HxMCn7Mo3FOeqDAf9LjqkjGGZx0XSyTiHmUtdljV9x1mkL7xoOk3kMDUB\nwb78\r\n=xPNh\r\n-----END PGP SIGNATURE-----\r\n"},"main":"src/index.js","_from":".","_shasum":"c972d7c81260d647a302fef45cce8db32418f3a2","gitHead":"7bd645bd272b3d25ae4cda4ce0455ddd955bd7c0","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"ably","email":"support@ably.io"},"repository":{"url":"git+https://github.com/universal-realtime/urltm.js.git","type":"git"},"_npmVersion":"3.10.8","description":"abstraction for realtime frameworks","directories":{},"_nodeVersion":"6.9.1","dependencies":{"ably":"^1.0.3","pubnub":"^4.0.13","socket.io":"^1.5.1","browserify":"^13.1.0","socket.io-client":"^1.5.1"},"devDependencies":{"chai":"^3.5.0","gulp":"^3.9.1","async":"^2.1.4","browserify":"^13.1.0","vinyl-source-stream":"^1.1.0"},"_npmOperationalInternal":{"tmp":"tmp/urltm-1.4.0.tgz_1495446922090_0.8248148423153907","host":"s3://npm-registry-packages"}}},"time":{"created":"2017-05-22T09:55:24.175Z","modified":"2026-03-18T18:54:49.322Z","1.4.0":"2017-05-22T09:55:24.175Z"},"bugs":{"url":"https://github.com/universal-realtime/urltm.js/issues"},"author":{"name":"PubNub"},"license":"MIT","homepage":"https://universal-realtime.github.io/urltm.js","keywords":["realtime","abstraction","socket.io","pubnub","faye"],"repository":{"url":"git+https://github.com/universal-realtime/urltm.js.git","type":"git"},"description":"abstraction for realtime frameworks","maintainers":[{"email":"mike@christensen.codes","name":"mschristensen"},{"email":"account.owners@ably.com","name":"ably-realtime"},{"email":"simon.woolf@ably.com","name":"simonw_ably"},{"email":"owen.pearson@ably.com","name":"owenpearson"},{"email":"khokhlov.e.n@gmail.com","name":"ttypic"},{"email":"lawrence.forooghian@ably.com","name":"lawrence.forooghian.ably"},{"email":"andrii.bulat@ably.com","name":"andrii.bulat.ably"},{"email":"andyford993@gmail.com","name":"andytwf"},{"email":"steven.lindsay@ably.com","name":"splind06"},{"email":"chris.bannister@ably.com","name":"zariel-ably"},{"email":"matthew.oriordan@gmail.com","name":"mattheworiordan"},{"email":"vlad.velici@ably.com","name":"vlad.velici.ably"}],"readme":"![](./assets/urltm.js-logo.png)\n\nUniversal API for realtime services. Integrate once and easily switch between Socket.io, Ably and PubNub.\n\nProvides handy methods for rooms, users, message history, and information about connected user.\n\nSupported realtime services:\n\n![https://www.ably.io/](./assets/ably.png)\n\n![](./assets/socketio.png)\n\n![](./assets/pubnub.png)\n\n# Setup\n\n## NPM\n\nInstall via NPM.\n\n```sh\nnpm install urltm --save\n```\n\nInclude library via require.\n\n```js\nconst urltm = require('urltm');\n```\n\n## Web\n\nInstall via bower or NPM\n\n```sh\nnpm install urltm --save\nbower install urltm --save\n```\n\nInclude library in HTML.\n\n```html\n\n```\n\n# Configure\n\nBoth the NodeJS and web libraries are configured with the ```urltm``` variable.\n\n```js\nlet user = urltm({\n service: 'pubnub',\n config: {\n // ...\n }\n});\n```\n\n* ```service``` is the name of the realtime service to use (```ably```, ```pubnub``` or ```socketio```)\n* ```config``` is a Javascript object with a config for that service.\n\n## PubNub or Socket.io\n\n#### [Set Up With Socket.io](/guides/socketio.md)\n\nSocket.io is an open source websocket framework. To use socket.io, you'll run\nyour own socket.io server on the back end.\n\n#### [Set Up With PubNub](/guides/pubnub.md)\n\nPubNub is a hosted realtime solution that doesn't require you to run or maintain any servers.\n\n#### [Set Up With Ably](/guides/ably.md)\n\nAbly is a hosted realtime solution that doesn't require you to run or maintain any servers.\n\n# Usage\n\n## Users\n\nEvery ```user``` connected to urltm.js has two properties:\n\n1. ```uuid``` - a unique way to identify this ```user```\n1. ```state``` - data associated with this ```user```\n\nYou can provide these as parameters during initialization.\n\n```js\nlet user = urltm({\n service: 'socketio',\n config: {\n endpoint: 'http://localhost:9000',\n uuid: 'MY_UNIQUE_ID',\n state: {admin: true}\n }\n});\n```\n\n## Rooms\n\nRealtime communication happens over ```room```s. ```room```s are like chat rooms, everybody in a ```room``` receives events sent by every other ```user```.\n\nA ```user``` can join a ```room``` by using the ```join()``` method and supplying a ```room``` identifier. ```user```s who provide the same identifier will be able to communicate with each other.\n\n```js\nroom = user.join('room-name');\n```\n\nThis returns a ```room``` object which we can use to communicate with other ```user```s.\n\n### Join Event\n\nA room can subscribe to the ```join``` event to find out when other ```user```s join the room.\n\n```js\nroom.on('join', (uuid, state) => {\n console.log('user with uuid', uuid, 'joined with state', state);\n});\n```\n\n## Messages\n\n### Message Event\n\nWhen another ```user``` sends a message to the ```room```, it will trigger the ```message``` event. The ```room``` can subscribe to that event with the ```on()``` method.\n\n```js\nroom.on('message', (uuid, data) => {\n console.log('message received from uuid', uuid, 'with data', data);\n});\n```\n\n### Publish\n\nTo send a message to the entire ```room```, use the ```message()``` method. Returns a promise.\n\n```js\nroom.message({hello: world}).then(() => {\n console.log('message published');\n});\n```\n\n## Online Users\n\n### Here Now\n\nA ```room``` can get a list of other ```user```s who have in the ```room``` by using the ```here()``` method. Returns a promise.\n\n```js\nroom.here().then((users) => {\n console.log('users online', users);\n});\n```\n\nSuccessful responses will return a object of ```user```s who are currently connected to the ```room```. The keys are the ```user```'s ```uuid```s and the values are their current ```state```.\n\n```js\n{\n uuid1: {\n username: 'ianjennings'\n },\n uuid2: {\n username: 'stephenblum'\n }\n}\n```\n\n### Leave Event\n\nA ```room``` can subscribe to the ```leave``` event to find out when a ```user``` leaves.\n\n```js\nroom.on('leave', (uuid) => {\n console.log('user with uuid', uuid, 'has left');\n});\n```\n\nA ```user``` can manually leave a ```room``` by using the ```leave()``` method. Returns a promise.\n\n```js\nroom.leave().then(() => {\n console.log('left the room.');\n});\n```\n\nThis will fire the ```leave``` event.\n\n### Disconnect\n\nIf a ```user``` gets disconnected without leaving the room, the ```disconnect``` event will fire.\n\n```js\nroom.on('disconnect', (uuid) => {\n console.log('user with uuid', uuid, 'has disconnected');\n});\n```\n\n## Set User State\n\nA ```user``` state can be updated at any time by using the ```state()``` method. Supply the new ```state``` as the only parameter. Return a promise.\n\n```js\nroom.state({idle: true}).then(() => {\n console.log('state set');\n});\n```\n\nThis will fire the ```state``` event which you can subscribe to with the ```room.on()``` method. When fired you will get the ```uuid``` of the ```user``` and the new ```state```.\n\n```js\nroom.on('state', (uuid, state) => {\n console.log('user with uuid', uuid, 'was given state', state);\n});\n```\n\n## Get Old Messages\n\nA ```user``` can retrieve previously published messages in the ```room``` by using the ```history()``` method. Returns a promise.\n\n```js\nroom.history().then((history) => {\n console.log('got array of all messages in channel', history);\n});\n```\n\nIt will return the last 100 messages as an array of objects containing the ```uuid``` and ```data``` of every message. The array is sorted newest to oldest.\n\n```js\n[\n {\n uuid: uuid2,\n data: {\n sentTime: '2pm',\n text: 'boy howdy'\n }\n },\n {\n uuid: uuid1,\n data: {\n sentTime: '1pm',\n text: 'hello there'\n }\n }\n]\n```\n\n## Test\n\nTests are run with mocha and chai.\n\n```sh\nnpm install mocha -g\nnpm install chai -g\n```\n\nSet environment variable ```CLIENT``` to test each service.\n\n```sh\nenv CLIENT=ably mocha\n```\n\n```sh\nenv CLIENT=pubnub mocha\n```\n\n```sh\nenv CLIENT=socketio mocha\n```\n","readmeFilename":"README.md"}