waitless-api SDK

Initialize with your API key and show games or ads during loading.

Test locally

Option 1 – Hosting app (uses local SDK)
From the repo root:

1. Build the SDK: cd sdk && npm run build
2. Start the hosting app: cd hosting && npm run dev
3. Open the app in the browser and use the Try It Live demo (it calls init('demo') and showGame).

Option 2 – Standalone test page
From the sdk folder:

1. Build: npm run build
2. Serve the folder (e.g. npx serve . or npx http-server . -p 5000)
3. Open http://localhost:5000/test-local.html and click Run test to run init('demo') and a 3-second showGame.

Install

npm install waitless-api

Initialize

Call init(apiKey) once. If you do not pass config, the SDK fetches the saved config for your API key from the server. If you pass config, that config is used and no fetch is made.

Invalid API keys: The SDK validates with the server. If the key is invalid (401/404), showGame/showAd throw and config fetch fails. Use initAsync(apiKey) and await it to fail at startup when the key is invalid instead of on first use.

import { init, initAsync } from 'waitless-api';

// Sync init (invalid key will fail on first showGame/showAd)
const client = init('your-api-key');

// Async init: validate key with server first (recommended when not passing config)
const client = await initAsync('your-api-key');

// Or pass your own config (no server fetch)
const client = init('your-api-key', {
  config: {
    strategy: { preset: 'balanced', behavior: 'auto' },
    frequency: { minInterval: 300, maxAdsPerSession: 4, maxAdsPerHour: 6 },
    duration: { adMaxDuration: 15, enableGames: true },
    batch: { enabled: true, showAdOnce: true }
  }
});

Client methods

• client.showGame(processingFn, options) – Show a game (tetris, snake, breakout) while your async function runs. Options: game, theme, message, container, width, height, showAds, etc.
• client.showAd(processingFn, options) – Show ad and/or game based on your config, then run the function. Options: estimatedDuration, batchId, message, overrideConfig.
• client.getConfig() – Return current config (for debugging).
• client.refreshConfig() – Clear cache and reload config from the server.

Standalone usage

You can also use the client returned by init(), or call the standalone functions after init:

import { init, showGame, showAd } from 'waitless-api';

init('your-api-key');

// Use standalone functions (they use the instance set by init)
const result = await showGame(
  async () => fetch('/api/data').then(r => r.json()),
  { game: 'tetris', message: 'Loading...' }
);

Types

Export types: WaitlessClient, ShowAdOptions, GameOptions, GameType, ThemeType, WaitlessConfig, AdPlayer, AdConfig.