SDK Initialization

The Holyheld SDK requires two steps before use: constructing an instance with your SDK API key, then calling init() to connect to the Holyheld service.

Quick start

import HolyheldSDK from '@holyheld/sdk';

const holyheldSDK = new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
});

await holyheldSDK.init();

Constructor options

new HolyheldSDK(options: HolyheldSDKOptions)

Option	Type	Required	Description
apiKey	string	Yes	Your Holyheld SDK API key
logger	boolean | Logger	No	Enable internal SDK logging. true logs to console; pass a Logger function for custom routing. Disabled by default. See Logging.

What init() does

init() makes a network request to the Holyheld API to:

1. Validate the API key — if the key is invalid or revoked, init() throws an error.
2. Load internal SDK configuration — retrieves internal service config required for subsequent SDK calls.

// init() returns Promise<void>
await holyheldSDK.init();

Call init() before any other SDK method

No other SDK method will work before init() resolves. Calling methods before initialisation will throw a NotInitialized error (HSDK_NI). Call init() once at application startup, before rendering any UI that uses the SDK.

Error handling

try {
  await holyheldSDK.init();
} catch (error) {
  // Possible causes:
  // - Invalid or revoked API key
  // - Network error or Holyheld service unreachable
  // - Timeout
  console.error('SDK initialization failed:', error);
  // Show a fallback UI — do not attempt other SDK calls
}

If init() throws, do not attempt to call other SDK methods. Show appropriate fallback UI and retry init() when conditions improve (e.g. after a network reconnect).

Logging

IMPORTANT

Logs are disabled by default. If you're debugging an application, set the logger option to true.

new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
  logger: true,
})

You may also set a custom logger:

new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
  logger: (level, message, data) => {
    console.log(level, message, data);
  },
})

Types:

enum LogLevel {
  Warning = 'warning',
  Log = 'log',
  Info = 'info',
  Debug = 'debug',
}

type Logger = (
  level: LogLevel, // level of event to be logged
  message: string, // message to be logged
  data?: { [key: string]: any }, // optional structured payload to be logged
) => void;

Recommended setup pattern

Call init() once at application startup and share the instance across your app. Do not create multiple HolyheldSDK instances.

sdk.ts

import HolyheldSDK from '@holyheld/sdk';

const holyheldSDK = new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
});

async function initSDK(): Promise<void> {
  await holyheldSDK.init();
}

export { holyheldSDK, initSDK };

main.ts

import { initSDK, holyheldSDK } from './sdk';

await initSDK();

// SDK is ready — pass holyheldSDK to components or use directly