Documentation Index
Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
Use this file to discover all available pages before exploring further.
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
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: "api-user@example.com",
password: "your-secure-password",
grantType: "password",
});
// Use the token for subsequent calls
const authenticatedGo = new Go({
customerAccess: tokenResult.accessToken,
});
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:
const go = new Go({
serverURL: "https://eu.platform.go.gbgplc.com/v2/captain",
customerAccess: process.env.GO_CUSTOMER_ACCESS,
});
const go = new Go({
serverURL: "https://us.platform.go.gbgplc.com/v2/captain",
customerAccess: process.env.GO_CUSTOMER_ACCESS,
});
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:
