MongoDB JavaScript SDK Documentation

mongodb-stitch

3.1.0

Overview
Client
StitchClientFactory ▸
- Static members
- .create
StitchClient ▸
- Instance members
- #login
- #register
- #linkWithProvider
- #authenticate
- #logout
- #authError
- #userProfile
- #isAuthenticated
- #authedId
- #service
- #executeFunction
- #executeServiceFunction
- #getApiKeys
- #createApiKey
- #getApiKeyByID
- #deleteApiKeyByID
- #enableApiKeyByID
- #disableApiKeyByID
MongoDB Service
MongoDBService ▸
- Instance members
- #db
DB ▸
- Instance members
- #collection
Collection ▸
- Instance members
- #insertOne
- #insertMany
- #deleteOne
- #deleteMany
- #updateOne
- #updateMany
- #find
- #findOne
- #aggregate
- #count
Partner Services
S3Service ▸
- Instance members
- #put
- #signPolicy
SESService ▸
- Instance members
- #send
HTTPService ▸
- Instance members
- #get
- #post
- #put
- #patch
- #delete
- #head
TwilioService ▸
- Instance members
- #send
Authentication
userPassProvider ▸
- Instance members
- #emailConfirm
- #sendEmailConfirm
- #sendPasswordReset
- #passwordReset
- #register
Errors
StitchError

Overview

The MongoDB Stitch JavaScript SDK can be used to build web applications and Node.js applications that use MongoDB Stitch.

Links to Other Resources

MongoDB Stitch Users - Google Group

MongoDB Stitch Announcements - Google Group

MongoDB Stitch Documentation

JavaScript SDK GitHub Repository

Basic Usage

Construct a simple app-wide client

import { StitchClientFactory } from 'mongodb-stitch';
let appId = 'sample-app-ovmyj';
let stitchClientPromise = StitchClientFactory.create(appId);

The StitchClient only needs to be resolved once from StitchClientFactory.create() and it can be used for the lifetime of an application.

Authenticate anonymously

stitchClientPromise.then(stitchClient => stitchClient.login())
  .then(() => console.log('logged in as: ' + stitchClient.authedId()))
  .catch(e => console.log('error: ', e));

Access MongoDB APIs

stitchClientPromise.then(stitchClient => {
  // mongodb1 is the name of the mongodb service registered with the app.
  let db = stitchClient.service('mongodb', 'mongodb1').db('app-ovmyj');
  let itemsCollection = db.collection('items');

  // CRUD operations:
  const userId = stitchClient.authedId();
  return itemsCollection.insertMany(
    [
      { owner_id: userId, x: 'item1' },
      { owner_id: userId, x: 'item2' },
      { owner_id: userId, x: 'item3' }
    ]
  );
}).then(result => console.log('success: ', result))
  .catch(e => console.log('error: ', e));

Execute a function

stitchClientPromise.then(stitchClient => 
  stitchClient.executeFunction('myFunc', 1, 'arg2', {arg3: true})
).then(result => console.log('success: ', result))
  .catch(e => console.log('error: ', e));

Execute a service function

stitchClientPromise.then(stitchClient =>
  stitchClient.executeServiceFunction('http1', 'get', {url: 'https://domain.org'})
).then(result => console.log('success: ', result))
  .catch(e => console.log('error: ', e));

Client

These classes offer fundamental functionality for communicating with MongoDB Stitch.

StitchClientFactory

src/client.js

StitchClientFactory is a singleton factory class which can be used to asynchronously create instances of StitchClient. StitchClientFactory is not meant to be instantiated. Use the static create() method to build a new StitchClient.

new StitchClientFactory()

Static Members

▸ create(clientAppID, options)

src/client.js

Creates a new StitchClient.

create(clientAppID: String, options: Object)

Parameters

clientAppID (String) the app ID of the Stitch application, which can be found in the "Clients" page of the Stitch admin console.

options

(Object
            = {})

additional options for creating the StitchClient .

StitchClient

src/client.js

StitchClient is the fundamental way of communicating with MongoDB Stitch in your application. Use StitchClient to authenticate users and to access Stitch services. StitchClient is not meant to be instantiated directly. Use a StitchClientFactory to create one.

new StitchClient()

Instance Members

▸ login(email?, password?, options)

src/client.js

Login to Stitch instance, optionally providing a username and password. In the event that these are omitted, anonymous authentication is used.

Parameters

email (String?) the email address used for login

password (String?) the password for the provided email address

options

(Object
            = {})

additional authentication options

Returns

Promise: which resolve to a String value: the authenticated user ID.

▸ register(email, password, options)

src/client.js

Send a request to the server indicating the provided email would like to sign up for an account. This will trigger a confirmation email containing a token which must be used with the emailConfirm method of the userpass auth provider in order to complete registration. The user will not be able to log in until that flow has been completed.

Parameters

email (String) the email used to sign up for the app

password (String) the password used to sign up for the app

options

(Object
            = {})

additional authentication options

Returns

Promise:

▸ linkWithProvider(providerType, options)

src/client.js

Links the currently logged in user with another identity.

linkWithProvider(providerType: String, options: Object): Promise

Parameters

providerType (String) the provider of the other identity (e.g. 'userpass', 'facebook', 'google')

options

(Object
            = {})

additional authentication options

Returns

Promise: which resolves to a String value: the original user ID

▸ authenticate(providerType, options)

src/client.js

Submits an authentication request to the specified provider providing any included options (read: user data). If auth data already exists and the existing auth data has an access token, then these credentials are returned.

authenticate(providerType: String, options: Object): Promise

Parameters

providerType (String) the provider used for authentication (The possible options are 'anon', 'userpass', 'custom', 'facebook', 'google', and 'apiKey')

options

(Object
            = {})

additional authentication options

Returns

Promise: which resolves to a String value: the authenticated user ID

▸ logout()

src/client.js

Ends the session for the current user, and clears auth information from storage.

logout(): Promise

Returns

Promise:

▸ authError()

src/client.js

authError(): any

Returns

any: Returns any error from the Stitch authentication system.

▸ userProfile()

src/client.js

Returns profile information for the currently logged in user.

userProfile(): Promise

Returns

Promise: which resolves to a a JSON object containing user profile information.

▸ isAuthenticated()

src/client.js

isAuthenticated(): Boolean

Returns

Boolean: whether or not the current client is authenticated.

▸ authedId()

src/client.js

authedId(): String

Returns

String: a string of the currently authenticated user's ID.

▸ service(type, name)

src/client.js

Factory method for accessing Stitch services.

service(type: String, name: String): Object

Parameters

type (String) the service type (e.g. "mongodb", "aws-s3", "aws-ses", "twilio", "http", etc.)

name (String) the service name specified in the Stitch admin console.

Returns

Object: returns an instance of the specified service type.

▸ executeFunction(name, args)

src/client.js

Executes a function.

executeFunction(name: String, args: ...any)

Parameters

name (String) The name of the function.

args (...any) Arguments to pass to the function.

▸ executeServiceFunction(service, action, args)

src/client.js

Executes a service function.

executeServiceFunction(service: String, action: String, args: ...any)

Parameters

service (String) The name of the service.

action (String) The name of the service action.

args (...any) Arguments to pass to the service action.

▸ getApiKeys()

src/client.js

Returns the user API keys associated with the current user.

getApiKeys(): Promise

Returns

Promise: which resolves to an array of API key objects

▸ createApiKey(userApiKeyName)

src/client.js

Creates a user API key that can be used to authenticate as the current user.

createApiKey(userApiKeyName: String): Promise

Parameters

userApiKeyName (String) a unique name for the user API key

Returns

Promise: which resolves to an API key object containing the API key value

▸ getApiKeyByID(keyID)

src/client.js

Returns a user API key associated with the current user.

getApiKeyByID(keyID: String): Promise

Parameters

keyID (String) the ID of the key to fetch

Returns

Promise: which resolves to an API key object, although the API key value will be omitted

▸ deleteApiKeyByID(keyID)

src/client.js

Deletes a user API key associated with the current user.

deleteApiKeyByID(keyID: String): Promise

Parameters

keyID (String) the ID of the key to delete

Returns

Promise:

▸ enableApiKeyByID(keyID)

src/client.js

Enables a user API key associated with the current user.

enableApiKeyByID(keyID: String): Promise

Parameters

keyID (String) the ID of the key to enable

Returns

Promise:

▸ disableApiKeyByID(keyID)

src/client.js

Disables a user API key associated with the current user.

disableApiKeyByID(keyID: String): Promise

Parameters

keyID (String) the ID of the key to disable

Returns

Promise:

MongoDB Service

These classes offer functionality for communicating with a MongoDB instance via Stitch.

MongoDBService

src/services/mongodb/mongodb_service.js

Creates a new MongoDBService instance (not meant to be instantiated directly, use .service('mongodb', '<service-name>') on a StitchClient instance.

new MongoDBService(): MongoDBService

Returns

MongoDBService: a MongoDBService instance.

Instance Members

▸ db(databaseName, options = {})

src/services/mongodb/mongodb_service.js

Get a DB instance

db(databaseName: String, options: Object?): DB

Parameters

databaseName (String) The MongoDB database name

options

(Object?
            = {})

Additional options.

Returns

DB: returns a DB instance representing a MongoDB database.

DB

src/services/mongodb/db.js

Creates a new DB instance (not meant to be instantiated directly, use .db() on a MongoDBService instance).

new DB(): DB

Returns

DB: a DB instance.

Instance Members

▸ collection(name, options = {})

src/services/mongodb/db.js

Returns a Collection instance representing a MongoDB Collection object.

collection(name: String, options: Object?): Collection

Parameters

name (String) The collection name.

options

(Object?
            = {})

Additional options.

Returns

Collection: returns a Collection instance representing a MongoDb collection.

Collection

src/services/mongodb/collection.js

Creates a new Collection instance (not meant to be instantiated directly, use .collection() on a DB instance).

new Collection(): Collection

Returns

Collection: a Collection instance.

Instance Members

▸ insertOne(doc)

src/services/mongodb/collection.js

Inserts a single document.

insertOne(doc: Object): Promise<Object, Error>

Parameters

doc (Object) The document to insert.

Returns

Promise<Object, Error>: a Promise for the operation.

▸ insertMany(docs)

src/services/mongodb/collection.js

Inserts multiple documents.

insertMany(docs: Array): Promise<Object, Error>

Parameters

docs (Array) The documents to insert.

Returns

Promise<Object, Error>: Returns a Promise for the operation.

▸ deleteOne(query)

src/services/mongodb/collection.js

Deletes a single document.

deleteOne(query: Object): Promise<Object, Error>

Parameters

query (Object) The query used to match a single document.

Returns

Promise<Object, Error>: Returns a Promise for the operation.

▸ deleteMany(query)

src/services/mongodb/collection.js

Deletes all documents matching query.

deleteMany(query: Object): Promise<Object, Error>

Parameters

query (Object) The query used to match the documents to delete.

Returns

Promise<Object, Error>: Returns a Promise for the operation.

▸ updateOne(query, update, options = {})

src/services/mongodb/collection.js

Updates a single document.

updateOne(query: Object, update: Object, options: Object?): Promise<Object, Error>

Parameters

query (Object) The query used to match a single document.

update (Object) The update operations to perform on the matching document.

options

(Object?
            = {})

Additional options object.

Name	Description
options.upsert `Boolean` (default `false`)	Perform an upsert operation.

Returns

Promise<Object, Error>: A Promise for the operation.

▸ updateMany(query, update, options?)

src/services/mongodb/collection.js

Updates multiple documents.

updateMany(query: Object, update: Object, options: Object?): Promise<Object, Error>

Parameters

query (Object) The query used to match the documents.

update (Object) The update operations to perform on the matching documents.

options (Object?) Additional options object.

Name	Description
options.upsert `Boolean` (default `false`)	Perform an upsert operation.

Returns

Promise<Object, Error>: Returns a Promise for the operation.

▸ find(query, project?)

src/services/mongodb/collection.js

Finds documents.

find(query: Object, project: Object?): MongoQuery

Parameters

query (Object) The query used to match documents.

project (Object?) The query document projection.

Returns

MongoQuery: An object which allows for limit and sort parameters to be set. execute will return a {Promise} for the operation.

▸ findOne(query, project?)

src/services/mongodb/collection.js

Finds one document.

findOne(query: Object, project: Object?): Promise<Object, Error>

Parameters

query (Object) The query used to match documents.

project (Object?) The query document projection.

Returns

Promise<Object, Error>: Returns a Promise for the operation

▸ aggregate(pipeline)

src/services/mongodb/collection.js

Executes an aggregation pipeline.

aggregate(pipeline: Array): Array

Parameters

pipeline (Array) The aggregation pipeline.

Returns

Array: The results of the aggregation.

▸ count(query, options)

src/services/mongodb/collection.js

Gets the number of documents matching the filter.

count(query: Object, options: Object): Number

Parameters

query (Object) The query used to match documents.

options

(Object
            = {})

Additional count options.

Name	Description
options.limit `Number` (default `null`)	The maximum number of documents to return.

Returns

Number: The results of the count operation.

Partner Services

These classes provide access to the functionality of MongoDB Stitch partner services. They are not meant to be instantiated directly, since they can be instantiated by calling the service() method on the StitchClient.

S3Service

src/services/aws/s3_service.js

Convenience wrapper around AWS S3 service (not meant to be instantiated directly, use .service('aws-s3', '<service-name>') on a StitchClient instance).

new S3Service(stitchClient: any, serviceName: any): S3Service

Parameters

stitchClient (any)

serviceName (any)

Returns

S3Service: a S3Service instance.

Instance Members

▸ put(bucket, key, acl, contentType, body)

src/services/aws/s3_service.js

Put an object to S3 via Stitch. For small uploads

put(bucket: String, key: String, acl: String, contentType: String, body: (String | BSON.Binary)): Promise

Parameters

bucket (String) which S3 bucket to use

key (String) which key (filename) to use

acl (String) which policy to apply

contentType (String) content type of uploaded data

body ((String | BSON.Binary)) the content to put in the bucket

Returns

Promise: which resolves to an object containing a single field "location" which is the URL of the object that was put into the S3 bucket

▸ signPolicy(bucket, key, acl, contentType)

src/services/aws/s3_service.js

Sign a policy for putting via Stitch. For large uploads

signPolicy(bucket: String, key: String, acl: String, contentType: String): Promise

Parameters

bucket (String) which S3 bucket to use

key (String) which key (filename) to use

acl (String) which policy to apply

contentType (String) content type of uploaded data

Returns

Promise:

SESService

src/services/aws/ses_service.js

Convenience wrapper around AWS SES service (not meant to be instantiated directly, use .service('aws-ses', '<service-name>') on a StitchClient instance).

new SESService(stitchClient: any, serviceName: any): SESService

Parameters

stitchClient (any)

serviceName (any)

Returns

SESService: a SESService instance.

Instance Members

▸ send(fromAddress, toAddress, subject, body)

src/services/aws/ses_service.js

Send an email

send(fromAddress: String, toAddress: String, subject: String, body: String): Promise

Parameters

fromAddress (String) the email to send from

toAddress (String) the email to send to

subject (String) the subject of the email

body (String) the body of the email

Returns

Promise: resolving to an object which contains the single string field "messageId", which is the SES message ID for the email message.

HTTPService

src/services/http/http_service.js

Convenience wrapper for HTTP service (not meant to be instantiated directly, use .service('http', '<service-name>') on a StitchClient instance).

new HTTPService(client: any, serviceName: any): HTTPService

Parameters

client (any)

serviceName (any)

Returns

HTTPService: a HTTPService instance.

Instance Members

▸ get(urlOrOptions, options = {})

src/services/http/http_service.js

Send a GET request to a resource (result must be application/json)

get(urlOrOptions: (String | Object), options: Object?): Promise

Parameters

urlOrOptions ((String | Object)) the url to request, or an object of GET args

options

(Object?
            = {})

optional settings for the GET operation

Name	Description
options.authUrl `String?`	url that grants a cookie

Returns

Promise:

▸ post(urlOrOptions, options = {})

src/services/http/http_service.js

Send a POST request to a resource with payload

post(urlOrOptions: (String | Object), options: Object?): Promise

Parameters

urlOrOptions ((String | Object)) the url to request, or an object of POST args

options

(Object?
            = {})

optional settings for the POST operation

Name	Description
options.authUrl `String?`	url that grants a cookie

Returns

Promise:

▸ put(urlOrOptions, options = {})

src/services/http/http_service.js

Send a PUT request to a resource with payload

put(urlOrOptions: (String | Object), options: Object?): Promise

Parameters

urlOrOptions ((String | Object)) the url to request, or an object of PUT args

options

(Object?
            = {})

optional settings for the PUT operation

Name	Description
options.authUrl `String?`	url that grants a cookie

Returns

Promise:

▸ patch(urlOrOptions, options = {})

src/services/http/http_service.js

Send a PATCH request to a resource with payload

patch(urlOrOptions: (String | Object), options: Object?): Promise

Parameters

urlOrOptions ((String | Object)) the url to request, or an object of PATCH args

options

(Object?
            = {})

optional settings for the PATCH operation

Name	Description
options.authUrl `String?`	url that grants a cookie

Returns

Promise:

▸ delete(urlOrOptions, options = {})

src/services/http/http_service.js

Send a DELETE request to a resource

delete(urlOrOptions: (String | Object), options: Object?): Promise

Parameters

urlOrOptions ((String | Object)) the url to request, or an object of DELETE args

options

(Object?
            = {})

optional settings for the DELETE operation

Name	Description
options.authUrl `String?`	url that grants a cookie

Returns

Promise:

▸ head(urlOrOptions, options = {})

src/services/http/http_service.js

Send a HEAD request to a resource

head(urlOrOptions: (String | Object), options: Object?): Promise

Parameters

urlOrOptions ((String | Object)) the url to request, or an object of HEAD args

options

(Object?
            = {})

optional settings for the HEAD operation

Name	Description
options.authUrl `String?`	url that grants a cookie

Returns

Promise:

TwilioService

src/services/twilio/twilio_service.js

Create a new TwilioService instance (not meant to be instantiated directly, use .service('twilio', '<service-name>') on a StitchClient instance).

new TwilioService(stitchClient: any, serviceName: any): TwilioService

Parameters

stitchClient (any)

serviceName (any)

Returns

TwilioService: a TwilioService instance.

Instance Members

▸ send(from, to, body)

src/services/twilio/twilio_service.js

Send a text message to a number

send(from: String, to: String, body: String): Promise

Parameters

from (String) number to send from

to (String) number to send to

body (String) SMS body content

Returns

Promise: which resolves to 'null' when message is sent successfully, or is rejected when there is an error

Authentication

Although most authentication tasks can be performed by the StitchClient, some authentication providers offer additional functionality that can be accessed via the "auth" property on the StitchClient. The providers which offer additional functionality are documented here.

userPassProvider

src/auth/providers.js

userPassProvider offers several methods for completing certain tasks necessary for email/password authentication. userPassProvider cannot be instantiated directly. To instantiate, use .auth.providers('userpass') on a StitchClient.

userPassProvider

Parameters

auth (any)

Instance Members

▸ emailConfirm(tokenId, token)

src/auth/providers.js

Completes the email confirmation workflow from the Stitch server

emailConfirm(tokenId: String, token: String): Promise

Parameters

tokenId (String) the tokenId provided by the Stitch server

token (String) the token provided by the Stitch server

Returns

Promise:

▸ sendEmailConfirm(email)

src/auth/providers.js

Request that the stitch server send another email confirmation for account creation.

sendEmailConfirm(email: String): Promise

Parameters

email (String) the email address to send a confirmation email for

Returns

Promise:

▸ sendPasswordReset(email)

src/auth/providers.js

Sends a password reset request to the Stitch server

sendPasswordReset(email: String): Promise

Parameters

email (String) the email address of the account to reset the password for

Returns

Promise:

▸ passwordReset(tokenId, token, password)

src/auth/providers.js

Use information returned from the Stitch server to complete the password reset flow for a given email account, providing a new password for the account.

passwordReset(tokenId: String, token: String, password: String): Promise

Parameters

tokenId (String) the tokenId provided by the Stitch server

token (String) the token provided by the Stitch server

password (String) the new password requested for this account

Returns

Promise:

▸ register(email, password)

src/auth/providers.js

Will trigger an email to the requested account containing a link with the token and tokenId that must be returned to the server using emailConfirm() to activate the account.

Parameters

email (String) the requested email for the account

password (String) the requested password for the account

Returns

Promise:

Errors

Some functions in the MongoDB Stitch JavaScript SDK may result in an error. The types of errors that can be returned by the SDK are documented here.

StitchError

src/errors.js

Creates a new StitchError

new StitchError(message: String, code: Object): StitchError

Extends Error

Parameters

message (String) The error message.

code (Object) The error code.

Returns

StitchError: A StitchError instance.