🌊 Wavelength Client SDK

Build powerful plugins and interactive experiences for the Wavelength Hub platform.

🚀 Quick Start

<!-- Include the SDK in your plugin -->
<script src="https://hub.wavelength.com/sdk/wavelength-hub.js"></script>

<script>
  (async () => {
    // Check if Hub API is available
    if (!window.WavelengthHub) {
      console.error('WavelengthHub API not found');
      return;
    }

    // Get current tenant info
    const tenant = await WavelengthHub.tenant.current();
    console.log('Tenant:', tenant.name);

    // Detect narrative mode
    const isNarrative = await WavelengthHub.state.isNarrativeMode();
    if (isNarrative) {
      console.log('Narrative mode is active - adjusting UI');
    }

    // Listen for narrative changes
    WavelengthHub.state.onNarrativeChange((isActive, info) => {
      console.log('Narrative state changed:', isActive);
    });
  })();
</script>

📦 Installation

For Plugin Development

The SDK is automatically injected into your plugin pages. Just declare API access in your game.json:

{
  "type": "client-sdk-plugin",
  "apiAccess": ["tenant", "theme", "content", "chat", "state"]
}

For NPM Projects

npm install @wavelength/client-sdk

import WavelengthHub from '@wavelength/client-sdk';

// Use the SDK
const tenant = await WavelengthHub.tenant.current();

🎯 Core APIs

Tenant API

Access tenant information and configuration:

const tenant = await WavelengthHub.tenant.current();
// { id, name, slug, description, ... }

const settings = await WavelengthHub.tenant.settings();
// { theme, features, customization, ... }

State API

Detect and respond to application state changes:

// Check narrative mode
const isNarrative = await WavelengthHub.state.isNarrativeMode();

// Get narrative info
const info = await WavelengthHub.state.getNarrativeInfo();
// { id, title, chapter, ... }

// Subscribe to changes
const unsubscribe = WavelengthHub.state.onNarrativeChange((isActive, info) => {
  if (isActive) {
    // Hide non-essential UI during narrative
  } else {
    // Restore UI
  }
});

Content API

Detect and interact with current content:

const content = await WavelengthHub.content.detect();
// { type: 'character', id: 'lenny', title: 'Lenny', ... }

const details = await WavelengthHub.content.get('character', 'lenny');
// Full character details

Theme API

Access and respond to theme changes:

const theme = await WavelengthHub.theme.current();
// { primaryColor, secondaryColor, fontFamily, ... }

WavelengthHub.theme.onChange((newTheme) => {
  // Update plugin UI to match theme
});

Chat API

Integrate with the Hub's AI chat system:

const response = await WavelengthHub.chat.send(
  'Tell me about Lenny's conducting style'
);
console.log(response.response);

🎼 Example: Narrative-Aware Plugin

(async () => {
  'use strict';

  // Check narrative mode before initializing UI
  const isNarrative = await WavelengthHub.state.isNarrativeMode();
  
  if (isNarrative) {
    console.log('Narrative active - deferring plugin UI');
    
    // Wait for narrative to end
    WavelengthHub.state.onNarrativeChange((isActive) => {
      if (!isActive) {
        initializePlugin();
      }
    });
    
    return;
  }

  // Safe to show plugin UI
  initializePlugin();

  function initializePlugin() {
    // Create your plugin interface
    const widget = document.createElement('div');
    widget.innerHTML = '<h3>My Plugin</h3>';
    document.body.appendChild(widget);
  }
})();

📚 Documentation

• Complete API Reference - Detailed API documentation
• Quick Reference - Cheat sheet for common tasks
• Plugin Guide - How to build plugins
• Examples - Reference implementations

🎨 Example Plugins

Bernstein Lore Master

Educational overlay plugin demonstrating:

• Narrative mode detection
• Character connection system
• Interactive timeline
• YouTube integration

See examples/bernstein-lore-master for the complete implementation.

🏗️ Building Plugins

1. Create plugin structure:

my-plugin/
├── game.json       # Plugin metadata
├── plugin.json     # Additional config
├── index.js        # Entry point
└── assets/         # CSS, images, etc.

2. Configure API access in game.json:

{
  "name": "My Plugin",
  "type": "client-sdk-plugin",
  "apiAccess": ["tenant", "state", "content"],
  "entryPoint": "index.js"
}

3. Use the SDK in index.js:

(async () => {
  if (!window.WavelengthHub) return;
  
  const tenant = await WavelengthHub.tenant.current();
  // Build your experience
})();

4. Upload to /admin/games/sandbox

🔒 Making Repositories Private

To protect your plugin code:

# On GitHub, go to Settings > Danger Zone > Change visibility
# Or via GitHub CLI:
gh repo edit --visibility private

🤝 Contributing

This SDK is maintained by the Wavelength development team. For questions or feature requests, please contact [email protected].

📄 License

MIT License - See LICENSE for details.

🌟 Version History

• v0.2.0 - Added State API with narrative mode detection
• v0.1.0 - Initial release with Tenant, Theme, Content, and Chat APIs

Ready to build amazing experiences? Start with the Quick Reference or explore the examples! 🚀