@prequist/lanyard

Lanyard TypeScript definitions, HTTP API wrapper, and real-time client.

Installation

bun i @prequist/lanyard

Usage

import {get} from '@prequist/lanyard';

const data = await get(snowflake);

data.active_on_discord_mobile; // boolean

Real-time client

LanyardClient maintains a single shared WebSocket connection per Lanyard host, with refcounted per-snowflake subscriptions and a shared presence snapshot. It is framework-agnostic — use-lanyard is a thin React binding over it.

import {getLanyardClient} from '@prequist/lanyard';

const client = getLanyardClient(); // or getLanyardClient({ hostname: 'my-lanyard.app', secure: true })

const unsubscribe = client.subscribe([snowflake]);

const stopListening = client.listen(() => {
	console.log(client.getSnapshot()[snowflake]?.discord_status);
});

// ...later: both are safe to call more than once
stopListening();
unsubscribe();

Subscribing to an id that another consumer already subscribed to reuses the existing subscription; new ids are added to the live connection incrementally, and the socket closes when the last subscriber leaves. For one-off requests over REST, use get.

KV

import {kv} from '@prequist/lanyard';

const store = await kv.get(snowflake); // Record<string, string>
const value = await kv.get(snowflake, 'location'); // string | undefined

// Writes need your Lanyard API key (get one via the Lanyard Discord bot),
// and default to the key's owner (`@me`)
await kv.put(apiKey, 'location', 'London');
await kv.merge(apiKey, {
	location: 'London',
	website: 'https://alistair.sh',
});
await kv.del(apiKey, 'location');

// Or target a user explicitly with a snowflake or '@me'
await kv.put(apiKey, snowflake, 'location', 'London');

You can also fetch your own presence with just an API key:

import {getMe} from '@prequist/lanyard';

const data = await getMe(apiKey);

TypeScript

All types are exported, and can be found in ./src/types.ts.

import type {Types} from '@prequist/lanyard';

// Example
export function isOnline(presence: Types.Presence) {
	return presence === 'online' || presence === 'idle';
}