@screencloud/studio-graphql-client

a micro package for querying the studio graphql api.

install

This project is exposed as a public npm package

Run npm i -S @screencloud/studio-graphql-client to add it to your project.

usage

StudioGraphQLClient-class

A minimalistic class for quick and easy graphql requests. Wraps around the popular graphql-request npm package.

Instantiate with StudioGraphQLClientOptions such as

const client = new StudioGraphQLClient({ 
  endpoint: '<your graphql endpoint>',
  token: '<your developer token>',
});

Notes:

• You may omit token or set it to undefined to run anonymous queries against the API.
• Your endpoint is shown on the "Developer"-tab in your studio account settings.
• You can also use 'eu' or 'us' as shorthands if you know your region.

executing queries

Use async request() to run queries against the API.

const client = new StudioGraphQLClient({ 
  endpoint: '<your graphql endpoint>',
  token: '<your developer token>',
});

client.request(`
  query { 
    currentOrg { 
      id 
      name
    }
  }
`).then((result) => {
  if (result.errors) {
    console.log('The request was unsuccessful', result.errors);
  } else {
    console.log('Your current org is ', result.data);
  }
});

getClient() singleton helper function

A function that exposes a shared instance (aka. singleton) to your package or script.

Run initClient() once during startup of your application.

import { initClient } from '@screencloud/studio-graphql-client';

initClient({
  endpoint: '<your graphql endpoint>',
  token: '<your developer token>',
});

Afterwards retrieve the singleton via getClient() in other files

import { getClient } from '@screencloud/studio-graphql-client';

const client = getClient();

client.request('<your graphql query>').then((result) => {
  console.log('query result', result);
});

nodejs and fetch()

The StudioGraphQLClient-class by default requires fetch to be a globally available function. This is always the case in modern browsers, but may not be the case in your local nodejs.

The package offers a polyfillFetch()-function to quickly help out.

import { polyfillFetch } from '@screencloud/studio-graphql-client';

polyfillFetch();

other functions

The package exposes most of its helper functions for various use-cases.

isStudioGraphQLToken(str: string): boolean

Returns true if a string is shaped like a valid studio graphql token;

This is used by StudioGraphQLCLient by default during construction.

parseGraphQLRequest(query: string): undefined

Attempts to parse the supplied query-argument as a graphql request. Throws if an invalid request is provided.

This is done by StudioGraphQLCLient by default when calling request().

mapStudioGraphQLEndpoint(endpoint: string): string | undefined

Maps a graphql endpoint such as 'eu' or 'us' to the full endpoint url of that region. Url-like strings will be returned as they are.

If the value can't be mapped otherwise, then undefined will be returned.

This is done by StudioGraphQLCLient by default during construction.