Commit 09e817c2 authored by timkinnane's avatar timkinnane
Browse files

docs(readme): Update and regenerate docs

Includes some changes for temporary publishing outside org scope
parent 665a0d5c
[asteroid]: https://www.npmjs.com/package/asteroid
[lru]: https://www.npmjs.com/package/lru
# Rocket.Chat Node.js SDK
......@@ -32,9 +33,9 @@ Currently, there are two modules exported by the SDK:
Access these modules by importing them from SDK, e.g:
ES6 `import { driver, methodCache } from '@rocket.chat/sdk'`
ES6 `import { driver, methodCache } from 'rocketchat-sdk'`
ES5 `const { driver, methodCache } = require('@rocket.chat/sdk')`
ES5 `const { driver, methodCache } = require('rocketchat-sdk')`
See [Asteroid][asteroid] docs for methods that can be called from that API.
......@@ -42,6 +43,18 @@ Any Rocket.Chat server method can be called via `driver.callMethod`,
`driver.cacheCall` or `driver.asyncCall`. Server methods are not fully
documented, most require searching the Rocket.Chat codebase.
#### MESSAGE OBJECTS
The Rocket.Chat message schema can be found here:
https://rocket.chat/docs/developer-guides/schema-definition/
The structure for messages in this package matches that schema, with a
TypeScript interface defined here: https://github.com/RocketChat/Rocket.Chat.js.SDK/blob/master/src/config/messageInterfaces.ts
The `driver.prepareMessage` method (documented below) provides a helper for
simple message creation and the `message` module can also be imported to create
new `Message` class instances directly if detailed attributes are required.
#### DRIVER METHODS
---
......@@ -98,12 +111,18 @@ Shortcut to subscribe to user's message stream
### `driver.reactToMessages(callback)`
Once a subscription is created, using `driver.subscribeToMessages()` this method
can be used to attach a callback to changes in the message stream.
Fires callback with every change in subscriptions
- Subscribe must be called first
- Uses error-first callback pattern
- Second argument is the changed item
- Third argument is additional attributes, such as `roomType`
For example usage, see the Rocket.Chat Hubot adapter's receive function, which
is bound as a callback to this method:
https://github.com/RocketChat/hubot-rocketchat/blob/convert-es6/index.js#L97-L193
### `driver.asyncCall(method, params)`
Wraps server method calls to always be async
......@@ -193,6 +212,10 @@ Send a prepared message object (with pre-defined room ID)
### METHOD CACHE
[LRU][lru] is used to cache results from the server, to reduce unnecessary calls
for data that is unlikely to change, such as room IDs. Utility methods and env
vars allow configuring, creating and resetting caches for specific methods.
---
### `methodCache.use(instance)`
......@@ -249,12 +272,12 @@ interactions (i.e. bots) locally while in development.
## Use as Dependency
`yarn add @rocket.chat/sdk` or `npm install --save @rocket.chat/sdk`
`yarn add rocketchat-sdk` or `npm install --save rocketchat-sdk`
ES6 module, using async
```
import * as rocketchat from '@rocket.chat/sdk'
import * as rocketchat from 'rocketchat-sdk'
const asteroid = await rocketchat.driver.connect({ host: 'localhost:3000' })
console.log('connected', asteroid)
......@@ -263,7 +286,7 @@ console.log('connected', asteroid)
ES5 module, using callback
```
const rocketchat = require('@rocket.chat/sdk')
const rocketchat = require('rocketchat-sdk')
rocketchat.driver.connect({ host: 'localhost:3000' }, function (err, asteroid) {
if (err) console.error(err)
......
......@@ -7,7 +7,7 @@ import { IMessage } from '../config/messageInterfaces';
/**
* Event Emitter for listening to connection.
* @example
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect()
* driver.events.on('connected', () => console.log('driver connected'))
*/
......@@ -36,13 +36,13 @@ export declare function useLog(externalLog: ILogger): void;
* error-first-pattern. Error returned or promise rejected on timeout.
* Removes http/s protocol to get connection hostname if taken from URL.
* @example <caption>Use with callback</caption>
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect({}, (err) => {
* if (err) throw err
* else console.log('connected')
* })
* @example <caption>Using promise</caption>
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect()
* .then(() => console.log('connected'))
* .catch((err) => console.error(err))
......
......@@ -52,7 +52,7 @@ const integrationId = process.env.INTEGRATION_ID || 'js.SDK';
/**
* Event Emitter for listening to connection.
* @example
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect()
* driver.events.on('connected', () => console.log('driver connected'))
*/
......@@ -75,13 +75,13 @@ exports.useLog = useLog;
* error-first-pattern. Error returned or promise rejected on timeout.
* Removes http/s protocol to get connection hostname if taken from URL.
* @example <caption>Use with callback</caption>
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect({}, (err) => {
* if (err) throw err
* else console.log('connected')
* })
* @example <caption>Using promise</caption>
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect()
* .then(() => console.log('connected'))
* .catch((err) => console.error(err))
......
This diff is collapsed.
{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/utils/interfaces.ts"],"names":[],"mappings":"","sourcesContent":["/** Result object from an API login */\nexport interface ILoginResultAPI {\n status: boolean\n data: { authToken: string, userId: string }\n}\n\n/** Payload structure for `postMessage` endpoint */\nexport interface IMessageAPI {\n roomId: string, // The room id of where the message is to be sent\n channel: string, // The channel name with the prefix in front of it\n text?: string, // The text of the message to send, is optional because of attachments\n alias?: string, // This will cause the messenger name to appear as the given alias, but username will still display\n emoji?: string, // If provided, this will make the avatar on this message be an emoji\n avatar?: string, // If provided, this will make the avatar use the provided image url\n attachments?: IAttachmentAPI[] // See attachment interface below\n}\n\n/** Payload structure for message attachments */\nexport interface IAttachmentAPI {\n color?: string, // The color you want the order on the left side to be, any value background-css supports\n text?: string, // The text to display for this attachment, it is different than the message text\n ts?: string, // ISO timestamp, displays the time next to the text portion\n thumb_url?: string, // An image that displays to the left of the text, looks better when this is relatively small\n message_link?: string, // Only applicable if the ts is provided, as it makes the time clickable to this link\n collapsed?: boolean, // Causes the image, audio, and video sections to be hidding when collapsed is true\n author_name?: string, // Name of the author\n author_link?: string, // Providing this makes the author name clickable and points to this link\n author_icon?: string, // Displays a tiny icon to the left of the Author’s name\n title?: string, // Title to display for this attachment, displays under the author\n title_link?: string, // Providing this makes the title clickable, pointing to this link\n title_link_download_true?: string, // When this is true, a download icon appears and clicking this saves the link to file\n image_url?: string, // The image to display, will be “big” and easy to see\n audio_url?: string, // Audio file to play, only supports what html audio does\n video_url?: string, // Video file to play, only supports what html video does\n fields?: IAttachmentFieldAPI[] // An array of Attachment Field Objects\n}\n\n/**\n * Payload structure for attachment field object\n * The field property of the attachments allows for “tables” or “columns” to be displayed on messages\n */\nexport interface IAttachmentFieldAPI {\n short?: boolean, // Whether this field should be a short field\n title: string, // The title of this field\n value: string // The value of this field, displayed underneath the title value\n}\n\n/** Result structure for message endpoints */\nexport interface IMessageResultAPI {\n ts: number, // Seconds since unix epoch\n channel: string, // Name of channel without prefix\n message: IMessageAPI, // The sent message object\n success: boolean // Send status\n}\n\n/** User object structure for creation endpoints */\nexport interface INewUserAPI {\n email?: string, // Email address\n name?: string, // Full name\n password: string, // User pass\n username: string, // Username\n active?: true, // Subscription is active\n roles?: string[], // Role IDs\n joinDefaultChannels?: boolean, // Auto join channels marked as default\n requirePasswordChange?: boolean, // Direct to password form on next login\n sendWelcomeEmail?: boolean, // Send new credentials in email\n verified?: true // Email address verification status\n}\n\n/** User object structure for queries (not including admin access level) */\nexport interface IUserAPI {\n _id: string, // MongoDB user doc ID\n type: string, // user / bot ?\n status: string, // online | offline\n active: boolean, // Subscription is active\n name: string, // Full name\n utcOffset: number, // Hours off UTC/GMT\n username: string // Username\n}\n\n/** Result structure for user data request (by non-admin) */\nexport interface IUserResultAPI {\n user: IUserAPI, // The requested user\n success: boolean // Status of request\n}\n"]}
\ No newline at end of file
{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/utils/interfaces.ts"],"names":[],"mappings":"","sourcesContent":["/** Result object from an API login */\nexport interface ILoginResultAPI {\n status: boolean\n data: { authToken: string, userId: string }\n}\n\n/** Payload structure for `postMessage` endpoint */\nexport interface IMessageAPI {\n roomId: string, // The room id of where the message is to be sent\n channel: string, // The channel name with the prefix in front of it\n text?: string, // The text of the message to send, is optional because of attachments\n alias?: string, // This will cause the messenger name to appear as the given alias, but username will still display\n emoji?: string, // If provided, this will make the avatar on this message be an emoji\n avatar?: string, // If provided, this will make the avatar use the provided image url\n attachments?: IAttachmentAPI[] // See attachment interface below\n}\n\n/** Payload structure for message attachments */\nexport interface IAttachmentAPI {\n color?: string, // The color you want the order on the left side to be, any value background-css supports\n text?: string, // The text to display for this attachment, it is different than the message text\n ts?: string, // ISO timestamp, displays the time next to the text portion\n thumb_url?: string, // An image that displays to the left of the text, looks better when this is relatively small\n message_link?: string, // Only applicable if the ts is provided, as it makes the time clickable to this link\n collapsed?: boolean, // Causes the image, audio, and video sections to be hiding when collapsed is true\n author_name?: string, // Name of the author\n author_link?: string, // Providing this makes the author name clickable and points to this link\n author_icon?: string, // Displays a tiny icon to the left of the author's name\n title?: string, // Title to display for this attachment, displays under the author\n title_link?: string, // Providing this makes the title clickable, pointing to this link\n title_link_download_true?: string, // When this is true, a download icon appears and clicking this saves the link to file\n image_url?: string, // The image to display, will be “big” and easy to see\n audio_url?: string, // Audio file to play, only supports what html audio does\n video_url?: string, // Video file to play, only supports what html video does\n fields?: IAttachmentFieldAPI[] // An array of Attachment Field Objects\n}\n\n/**\n * Payload structure for attachment field object\n * The field property of the attachments allows for “tables” or “columns” to be displayed on messages\n */\nexport interface IAttachmentFieldAPI {\n short?: boolean, // Whether this field should be a short field\n title: string, // The title of this field\n value: string // The value of this field, displayed underneath the title value\n}\n\n/** Result structure for message endpoints */\nexport interface IMessageResultAPI {\n ts: number, // Seconds since unix epoch\n channel: string, // Name of channel without prefix\n message: IMessageAPI, // The sent message object\n success: boolean // Send status\n}\n\n/** User object structure for creation endpoints */\nexport interface INewUserAPI {\n email?: string, // Email address\n name?: string, // Full name\n password: string, // User pass\n username: string, // Username\n active?: true, // Subscription is active\n roles?: string[], // Role IDs\n joinDefaultChannels?: boolean, // Auto join channels marked as default\n requirePasswordChange?: boolean, // Direct to password form on next login\n sendWelcomeEmail?: boolean, // Send new credentials in email\n verified?: true // Email address verification status\n}\n\n/** User object structure for queries (not including admin access level) */\nexport interface IUserAPI {\n _id: string, // MongoDB user doc ID\n type: string, // user / bot ?\n status: string, // online | offline\n active: boolean, // Subscription is active\n name: string, // Full name\n utcOffset: number, // Hours off UTC/GMT\n username: string // Username\n}\n\n/** Result structure for user data request (by non-admin) */\nexport interface IUserResultAPI {\n user: IUserAPI, // The requested user\n success: boolean // Status of request\n}\n"]}
\ No newline at end of file
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
{
"name": "@rocket.chat/sdk",
"name": "rocketchat-sdk",
"version": "0.0.0-develop",
"description": "Node.js SDK for Rocket.Chat. Application interface for server methods and message streams.",
"main": "dist/index.js",
......@@ -30,7 +30,7 @@
"test:hook": "mocha --opts ./mocha.opts './**/*.spec.ts'",
"test:debug": "mocha --opts ./mocha.opts --inspect --debug-brk 'src/**/*.spec.ts'",
"test:package": "preview && mocha --opts ./mocha.opts 'src/index.spec.ts'",
"docs": "rimraf ./docs/*; typedoc --options ./typedoc.json ./src",
"docs": "rimraf ./docs/*; typedoc --options ./typedoc.json ./src/lib",
"prebuild": "npm run test",
"build": "rimraf ./dist/* && tsc && npm run test:package && npm run docs"
},
......@@ -53,12 +53,12 @@
"package-preview": "^1.0.5",
"rimraf": "^2.6.2",
"sinon": "^4.4.2",
"sinon-chai": "^3.0.0",
"source-map-support": "^0.5.3",
"ts-node": "^5.0.1",
"tslint": "^5.9.1",
"tslint-config-standard": "^7.0.0",
"typedoc": "0.8.0",
"typedoc-plugin-external-module-name": "^1.1.1",
"typescript": "^2.7.2"
},
"dependencies": {
......
import { expect } from 'chai'
import * as rocketchat from '@rocket.chat/sdk'
import * as rocketchat from 'rocketchat-sdk'
describe('index:', () => {
it('exports all lib members', () => {
......
......@@ -49,7 +49,7 @@ const integrationId = process.env.INTEGRATION_ID || 'js.SDK'
/**
* Event Emitter for listening to connection.
* @example
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect()
* driver.events.on('connected', () => console.log('driver connected'))
*/
......@@ -85,13 +85,13 @@ export function useLog (externalLog: ILogger) {
* error-first-pattern. Error returned or promise rejected on timeout.
* Removes http/s protocol to get connection hostname if taken from URL.
* @example <caption>Use with callback</caption>
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect({}, (err) => {
* if (err) throw err
* else console.log('connected')
* })
* @example <caption>Using promise</caption>
* import { driver } from '@rocket.chat/sdk'
* import { driver } from 'rocketchat-sdk'
* driver.connect()
* .then(() => console.log('connected'))
* .catch((err) => console.error(err))
......
......@@ -22,10 +22,10 @@ export interface IAttachmentAPI {
ts?: string, // ISO timestamp, displays the time next to the text portion
thumb_url?: string, // An image that displays to the left of the text, looks better when this is relatively small
message_link?: string, // Only applicable if the ts is provided, as it makes the time clickable to this link
collapsed?: boolean, // Causes the image, audio, and video sections to be hidding when collapsed is true
collapsed?: boolean, // Causes the image, audio, and video sections to be hiding when collapsed is true
author_name?: string, // Name of the author
author_link?: string, // Providing this makes the author name clickable and points to this link
author_icon?: string, // Displays a tiny icon to the left of the Authors name
author_icon?: string, // Displays a tiny icon to the left of the author's name
title?: string, // Title to display for this attachment, displays under the author
title_link?: string, // Providing this makes the title clickable, pointing to this link
title_link_download_true?: string, // When this is true, a download icon appears and clicking this saves the link to file
......
......@@ -5,5 +5,6 @@
"module": "commonjs",
"target": "ES6",
"out": "./docs",
"theme": "minimal"
"theme": "default",
"exclude": "**/*.spec.ts"
}
\ No newline at end of file
module.exports = function (wallaby) {
return {
name: 'Rokcet.Chat Bot Driver',
name: 'Rocket.Chat.js.SDK',
files: [
"src/**/*.ts",
{ pattern: "src/**/*.spec.ts", ignore: true },
......
......@@ -2117,10 +2117,6 @@ signal-exit@^3.0.0, signal-exit@^3.0.1, signal-exit@^3.0.2:
version "3.0.2"
resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.2.tgz#b5fdc08f1287ea1178628e415e25132b73646c6d"
sinon-chai@^3.0.0:
version "3.0.0"
resolved "https://registry.yarnpkg.com/sinon-chai/-/sinon-chai-3.0.0.tgz#d5cbd70fa71031edd96b528e0eed4038fcc99f29"
sinon@^4.4.2:
version "4.4.2"
resolved "https://registry.yarnpkg.com/sinon/-/sinon-4.4.2.tgz#c4c41d4bd346e1d33594daec2d5df0548334fc65"
......@@ -2440,6 +2436,10 @@ typedoc-default-themes@^0.5.0:
version "0.5.0"
resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.5.0.tgz#6dc2433e78ed8bea8e887a3acde2f31785bd6227"
typedoc-plugin-external-module-name@^1.1.1:
version "1.1.1"
resolved "https://registry.yarnpkg.com/typedoc-plugin-external-module-name/-/typedoc-plugin-external-module-name-1.1.1.tgz#0ef2d6a760b42c703519c474258b6f062983aa83"
typedoc@0.8.0:
version "0.8.0"
resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.8.0.tgz#d7172bc6a29964f451b7609c005beadadefe2361"
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment