Javascript Client SDK

Class: Client

Client

Provides initial setup and subsequent access to the SDK

new Client(options)

Parameters:
Name Type Description
options ClientOptions

Options for the Client.
Properties:
Name Type Description
transport Transport

a stored transport instance used for fetching
session Session

a stored session to query the current users' authentication state with
registry Registry

a stored registry reference to query
Source:
Tutorials:
Requires:
Examples
import Client from '@pikselpalette/sequoia-js-client-sdk/lib/client';
import { where, field } from '@pikselpalette/sequoia-js-client-sdk/lib/query';

// Create a client:
const client = new Client({ directory: 'piksel',
                          registry: 'https://registry-sandbox.sequoia.piksel.com' });

client.login('username', 'password').then(session => {
  // You can now query the session provided as the first argument (or
  // client.session); e.g. `session.isActive()`

  // Get a service::
  client.service('metadata').then(service => {
    // Get a resourceful endpoint (this is synchronous as the service passed
    // all the necessary data):
    const contents = service.resourcefulEndpoint('contents');

    contents.browse(where().fields('title', 'mediumSynopsis','duration', 'ref')
                    .include('assets').page(1).perPage(24).orderByUpdatedAt().desc().count())
            .then(json => {
              // Do something with the json returned
            });
  });
}).catch(error => {
  // Not logged in, inspect `error` to see why
});
// Adding a tenant argument to the Client means you can skip setting the tenant later on.
const client = new Client({ directory: 'piksel',
                            registry: 'https://registry-sandbox.sequoia.piksel.com',
                            tenant: 'demo' });
// Adding a token argument to the Client means you do not need to call generate()
// in a separate step.
const client = new Client({ directory: 'piksel',
                            registry: 'https://registry-sandbox.sequoia.piksel.com',
                            token: 'yourGeneratedToken' });

Requires

Methods

cachedServiceDescriptors(serviceNames)

Get a list of ServiceDescriptors from the SDK cache, falling back to the service endpoint

Parameters:
Name Type Argument Description
serviceNames string <repeatable>

service names
Source:
See:
Returns:
Type
Promise

changePassword()

Changes the password of a user

Source:
Returns:

null

generate(token)

Generate a Session from an existing bearer token.

It is also useful to use this if you acquire an access token via other means, i.e. an existing oauth mechanism for Sequoia

Call this method without a token parameter to instantiate the client for anonymous usage. Note: currently the Sequoia registry does not provide anonymous access. See the below example for how to handle this currently.

Parameters:
Name Type Argument Description
token string <nullable>

an existing bearer token for an end user
Source:
Returns:
  • First argument to the resolved Promise is the Session object that has been updated
Type
Promise
Examples
client.generate('some token').then(doSomething);
// Anonymous usage:
client.generate().catch((err) => {
  if (err.response && err.response.status === 401) {
    client.registry.tenant = SQ_DIRECTORY;

    client.registry.services.push({
      owner: 'root',
      name: 'identity',
      title: 'Identity Service',
      location: SQ_IDENTITY_URL
    });

    client.registry.services.push({
      owner: 'root',
      name: 'gateway',
      title: 'Gateway Service',
      location: client.registry.registryUri.replace('registry', 'gateway')
    });
  }
}).then(doSomething);

login(username, password, options)

Log an end user in with username and password credentials

Parameters:
Name Type Argument Description
username string <nullable>

the end user's username
password string <nullable>

the end user's password
options AuthenticationOptions <nullable>
Source:
See:
Returns:
  • First argument to the resolved Promise is the Session object that has been updatedc
Type
Promise
Examples
// Standard 'pauth' login
client.login('test_username', 'test_password').then((session) => {
  // Do something with the session
});

// 'pauth' style login to a custom endpoint
client.login('test_username', 'test_password', {
  url: 'https://example.com/custom/pauth'
}).then((session) => {
  // Custom url should return a json response of { 'access_token': <token> }
  // Do something with the session
});
// Standard 'oauth' login (password grant)
const secret = 'somebase64secret==';
client.login('test_username', 'test_password', {
  strategy: 'oauth',
  secret
}).then((session) => {
  // Do something with the session
});
// Client oauth (client credentials grant)
const secret = 'somebase64secret==';
client.login(null, null, {
  strategy: 'oauth',
  secret
}).then((session) => {
  // Do something with the session
});
// login will reject when not passing a secret
client.login('test_username', 'test_password', {
  strategy: 'oauth'
}).catch((err) => {
  // Inspect `err`
});

logout()

Log out an end user

Source:
Returns:
Type
Session

onExpiryWarning(callback, threshold)

Set callback for when the Token is about to expire, will be called before expiry based on the provided threshold

Call with null to cancel the callback.

Parameters:
Name Type Default Description
callback function

Will be called with the current session.access
threshold Number 60000

Number of milliseconds before expiry when callback will be invoked. Defaults to 60000 (1 minute)
Source:

resetPassword()

Reset the password of a user

Source:
Returns:

Object

service()

Get a ServiceDescriptor from the Registry

Deprecated:
Source:
See:
Returns:
Type
Promise

serviceDescriptors(serviceNames)

Get a list of ServiceDescriptors from the service endpoint

Parameters:
Name Type Argument Description
serviceNames string <repeatable>

service names
Source:
See:
Returns:
Type
Promise

setDirectory()

Set the current directory

This will only affect new authentications, if the client is already authenticated, it will not do anything.

Source:

setTenancy(tenantName)

Set the current tenancy for the user

When switching tenancies, this.registry will be repopulated with the services available in that tenancy.

Note: existing instances of ServiceDescriptors, ResourcefulEndpoints etc will not have the 'owner' updated when switching to a new tenancy. See the below example for more info.

Parameters:
Name Type Description
tenantName string

the name of the tenancy to use
Source:
Returns:
Type
Promise.<Session>
Example

Switching a tenancy

await client.generate(some_token);
await client.setTenancy('test');

let identity = await client.service('identity');
let usersEndpoint = identity.resourcefulEndpoint('users');
await usersEndpoint.browse() // https://<endpoint>/data/users?owner=test

await client.setTenancy('production');
// At this point `identity` and `usersEndpoint` will still be doing
// `fetch`es with `?owner=test`. You will need to repopulate them
// as below
await usersEndpoint.browse() // https://<endpoint>/data/users?owner=test

identity = await client.service('identity');
usersEndpoint = identity.resourcefulEndpoint('users');
await usersEndpoint.browse() // https://<endpoint>/data/users?owner=production