Navigation and community data

Declare navigation to know which community and channel the user has open, and guild_data to read the name, roles and channels of communities they open. Both are read-only: nothing here changes Fluxer or sends anything.

Follow the open channel

const route = await api.navigation.current();
if (route.kind === "guild")
  api.logger.info("Community open", { guild: route.guildId ?? "" });

cleanup.push(
  await api.navigation.onChange((next) => {
    if (next.kind === "dm") api.logger.debug("Direct messages open");
  }),
);

A route has kind (guild, dm or other) and, when known, guildId and channelId. onChange calls the handler once with the current route, then after every change. Fluxer navigates without telling other code, so changes are noticed within about a quarter of a second. While your handler is busy, only the newest waiting route is delivered.

Read a community

const info = await api.guildData.info();
const roles = await api.guildData.roles();
const channels = await api.guildData.channels();
const categories = channels.filter((channel) => channel.type === 4);
api.logger.info("Community", {
  name: info.name,
  roles: roles.length,
  categories: categories.length,
});

cleanup.push(
  await api.guildData.onChange((change) => {
    if (change.kind === "channels") api.logger.debug("Channels changed");
  }),
);

Every call takes an optional community id and defaults to the open community.

Call	Result
info	id, name and icon, Fluxer’s icon hash when the community has one
roles	Highest position first: id, name, color, position, isDefault and permissions
channels	By position: id, name, type (0 text, 2 voice, 4 category, 998 link), parentId

Channels carry nothing else: topics, permission overwrites and settings are left out.

Which communities

Only communities the user opened during this session can be read. Asking about any other fails with guild_not_open, and so does asking for the open community on a direct message. A plugin can’t use the user’s account to look into communities they didn’t visit.

FluxPlugs fetches the data with the user’s account, caches it for 10 minutes and shares one copy between all plugins and role badges. Calls wait for the first fetch; later ones answer from the cache. onChange fires when a refetch finds different roles, channels or info.

Errors

Error	Meaning
guild_not_open	Not a community the user opened this session
guild_data_unavailable	Fluxer refused or returned something unreadable; tried again later
guild_data_rate_limited	Fluxer asked FluxPlugs to slow down; the cache waits before asking again
guild_data_timeout	Fluxer didn’t answer within 10 seconds
guild_data_busy	This plugin already has four requests waiting

The role list includes permission bitfields, which Fluxer’s own UI doesn’t show to everyone. Treat them as the user’s private view of the community.