A TypeScript SDK for embedding HyHyve spaces in web applications using Web Components.
npm install @hyhyve/client-sdkimport { HyHyveComponent } from '@hyhyve/client-sdk';
const hyhyve = new HyHyveComponent();
hyhyve.attach('#my-container', {
spaceId: 'your-space-id',
embedded: true
});<!DOCTYPE html>
<html>
<head>
<script type="module">
import { HyHyveComponent } from 'https://unpkg.com/@hyhyve/client-sdk/dist/index.es.js';
const hyhyve = new HyHyveComponent();
hyhyve.attach('#hyhyve', {
spaceId: 'your-space-id',
embedded: true
});
</script>
</head>
<body>
<div id="hyhyve" style="width: 100%; height: 500px;"></div>
</body>
</html>interface HyHyveOptions {
spaceId?: string; // The HyHyve space ID to load
eventId?: string; // Optional event ID
embedded?: boolean; // Enable embedded mode
baseUrl?: string; // Custom base URL (default: https://app.hyhyve.com)
whitelabelSettings?: WhitelabelSettings; // Customization options
auth?: AuthOptions; // Pre-authentication options
}Authenticate users with a JWT token signed by your backend server:
const hyhyve = new HyHyveComponent();
hyhyve.attach('#container', {
spaceId: 'your-space-id',
auth: {
tag: "jwt",
token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', // JWT signed with your API key
clientId: 'your-client-id'
}
});The JWT should be signed by your backend using your HyHyve API key (HS256 algorithm) with the following payload:
{
"clientReferenceId": "your-user-id",
"profile": {
"name": "John Doe",
"color": "#007bff",
"picture": "https://example.com/avatar.jpg",
"socials": ["https://linkedin.com/in/johndoe"],
"headline": "Software Engineer",
"emoji": "👋",
"status": "Available"
},
"teamAdmin": false
}Required Fields:
clientReferenceId: Your unique user identifierprofile.name: User's display name (max 80 chars)
Optional Profile Fields:
profile.color: Hex color code (default: "#0eb3bc")profile.picture: URL to profile picture (max 1024 chars, default: "")profile.socials: Array of social URLs (max 5, default: [])profile.headline: User's headline/bio (max 240 chars, default: "")profile.emoji: User's emoji (max 32 chars, default: "👋")profile.status: Status message (max 100 chars, default: "Hi there, I'm using HyHyve!"
Optional Fields:
teamAdmin: Boolean (default:false). Set totrueto grant the user team admin privileges for the team associated with your API client. This adds the user to the team's members list.
**Backend Example (Node.js):**
```typescript
import jwt from 'jsonwebtoken';
// Generate JWT token for a user (on your backend)
function generateHyHyveToken(userId: string, userProfile: any) {
const payload = {
clientReferenceId: userId,
profile: {
name: userProfile.name, // Required
color: '#007bff',
picture: userProfile.avatarUrl,
socials: userProfile.socialLinks || [],
headline: userProfile.title || '',
emoji: '👋',
status: 'Available'
},
// Set to true to grant team admin privileges
teamAdmin: userProfile.isAdmin || false
};
// Sign with your HyHyve API key
return jwt.sign(payload, process.env.HYHYVE_API_KEY!, {
algorithm: 'HS256',
expiresIn: '5m' // Short expiry recommended
});
}
// API endpoint to get token
app.get('/api/hyhyve-token', authenticateUser, (req, res) => {
const token = generateHyHyveToken(req.user.id, req.user.profile);
res.json({ token, clientId: process.env.HYHYVE_CLIENT_ID });
});
Frontend Usage:
// Fetch token from your backend
const response = await fetch('/api/hyhyve-token');
const { token, clientId } = await response.json();
// Use token to authenticate with HyHyve
hyhyve.attach('#container', {
spaceId: 'your-space-id',
auth: { tag: "jwt", token, clientId }
});Alternatively, pass the user profile directly (client-side only):
const hyhyve = new HyHyveComponent();
hyhyve.attach('#container', {
spaceId: 'your-space-id',
auth: {
tag: "complete",
profile: {
name: 'John Doe', // Required
color: '#007bff', // Optional
picture: 'https://example.com/avatar.jpg',
socials: ['https://linkedin.com/in/johndoe'],
headline: 'Software Engineer',
emoji: '👋',
status: 'Available'
}
}
});The SDK provides comprehensive whitelabel customization options to integrate HyHyve seamlessly into your application with your own branding.
📖 Complete WhiteLabel Documentation
The SDK includes several preset configurations for common use cases:
import {
blankWhitelabelPreset,
basicConfig,
embeddedConfig,
corporateConfig
} from '@hyhyve/client-sdk';
// Complete branding removal
hyhyve.attach('#container', {
spaceId: 'your-space-id',
whitelabelSettings: blankWhitelabelPreset
});
// Corporate branding with full themes
hyhyve.attach('#container', {
spaceId: 'your-space-id',
whitelabelSettings: corporateConfig
});hyhyve.attach('#container', {
spaceId: 'your-space-id',
whitelabelSettings: {
hideLogo: true,
hidePrivacyLinks: true,
embedMode: true,
forceTheme: 'dark',
customBrand: {
brand: 'My Company',
themes: {
dark: {
primary: '#ff6b35',
shade1: '#0f172a', // slate-900
shade2: '#1e293b', // slate-800
shade3: '#334155', // slate-700
shade4: '#cbd5e1' // slate-300 (active state)
}
}
}
}
});For detailed configuration options, type definitions, and advanced examples, see the WhiteLabel Configuration Guide.
Attaches the HyHyve component to a DOM element.
// Using selector string
hyhyve.attach('#my-container', options);
// Using HTMLElement
const element = document.getElementById('my-container');
hyhyve.attach(element, options);
// Auto-attach to #hyhyve
hyhyve.attach(undefined, options);Destroys the component and cleans up resources.
hyhyve.destroy();The SDK is written in TypeScript and includes full type definitions. All types are exported for use in your applications:
import type {
HyHyveOptions,
WhitelabelSettings,
Language,
Theme
} from '@hyhyve/client-sdk';The SDK includes a working example.
- Start nix development shell
nix develop- Run the example dev server
just dev-exampleGet it! https://nixos.org/download/
Otherwise use Bun to run the bunx commands in the justfile yourself.
MIT