Core SDK

Type-safe TypeScript client for the GBG GO API

The Core SDK (@gbg/go-core) provides a type-safe TypeScript client for the GBG GO Captain API. Use it on your server to authenticate, start journeys, manage tasks, connect devices, and generate the tokens and URLs needed to embed web journeys in your apps.

The Core SDK is in beta. Pin to a specific version to avoid breaking changes between releases.

Installation

npm

npm install @gbg/go-core

pnpm

pnpm add @gbg/go-core

yarn

yarn add @gbg/go-core

The package ships with both CommonJS and ES module builds, and includes TypeScript declarations.

Supported runtimes: Node.js 18+, Bun 1+, Deno 1.39+, modern browsers.

Authentication

Generate an access token, then pass it to the SDK:

import { Go } from "@gbg/go-core";

// Generate a token
const go = new Go();
const tokenResult = await go.tokens.generate({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  username: "[e-mail]",
  password: "your-secure-password",
  grantType: "password",
});

// Use the token for subsequent calls
const authenticatedGo = new Go({
  customerAccess: tokenResult.accessToken,
});

You can also set the GO_CUSTOMER_ACCESS environment variable instead of passing the token directly.

Region selection

GBG GO is deployed across three regions. Set your region when initializing the SDK:

EU

const go = new Go({
  serverURL: "https://eu.platform.go.gbgplc.com/v2/captain",
  customerAccess: process.env.GO_CUSTOMER_ACCESS,
});

US

const go = new Go({
  serverURL: "https://us.platform.go.gbgplc.com/v2/captain",
  customerAccess: process.env.GO_CUSTOMER_ACCESS,
});

AU

const go = new Go({
  serverURL: "https://au.platform.go.gbgplc.com/v2/captain",
  customerAccess: process.env.GO_CUSTOMER_ACCESS,
});

Available operations

These are the resources and methods exposed by the SDK:

Resource	Method	Description
tokens	generate()	Generate an access token
journeys	start()	Start a journey instance
journeys	getState()	Get journey state
tasks	list()	Get end-user tasks
tasks	update()	Submit end-user data
tasks	getSchema()	Get a task’s schema
tasks	listSchema()	Get all tasks with schemas
devices	add()	Create a connect secret
devices	connect()	Connect or refresh an end-user device
interactions	submit()	Submit an interaction
interactions	fetch()	Fetch an interaction
instances	delete()	Delete a journey instance
health	get()	Check service health

Start a journey

Pass the resource ID of the journey template you want to run. The response includes the instanceId you’ll use to track the journey:

const result = await go.journeys.start({
  resourceId: "your-journey-resource-id",
  context: {
    subject: {},
    config: { delivery: "page" },
  },
});

console.log(result.instanceId); // Use this to track the journey

Connect an end-user device

Generate a connect token on your server, then pass it to the end user’s device:

// Server: create a connect secret
const connectResult = await go.devices.add({
  instanceId: "PiIuACmx8Q8R7qPnAkLAqBAT",
  scope: ["mobile"],
});

// Device: exchange the connect token for an end-user token
const deviceResult = await go.devices.connect(
  { deviceConnect: connectResult.connectToken },
  {
    connectToken: connectResult.connectToken,
    deviceInfo: {
      deviceId: "device-uuid",
      deviceName: "iPhone 15",
      deviceType: "iOS",
    },
  }
);

Error handling

Catch GoError to inspect the HTTP status code and response body when an API call fails:

import { Go } from "@gbg/go-core";
import * as errors from "@gbg/go-core/models/errors";

try {
  const result = await go.journeys.start({ resourceId: "..." });
} catch (error) {
  if (error instanceof errors.GoError) {
    console.error(`API error ${error.statusCode}: ${error.message}`);
    console.error("Response body:", error.body);
  }
}

Retries

Configure retry behaviour globally or per-request:

const go = new Go({
  customerAccess: process.env.GO_CUSTOMER_ACCESS,
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

Further reading

For the complete API reference, standalone functions for tree-shaking, custom HTTP client configuration, and debugging options, see the full SDK documentation on GitHub:

• SDK documentation
• Standalone functions
• Runtime support