Card bot

import {
  Client,
  CloakEmbedError,
  CLOAK_MEDIA_ORIGIN,
  embedFallbackText,
} from '@cloak-software/bot-sdk';

// Media on a card must be Cloak-hosted. Put a real https://media.cloak.chat URL
// here (an asset uploaded through the Cloak app, the bot's avatar, a room icon)
// to see the thumbnail render.
const logoUrl = process.env.CLOAK_LOGO_URL;

const client = new Client({
  token: process.env.CLOAK_TOKEN!,
  // Keep this file. The bot's identity is published to the server once, so a
  // bot with no keystore works on its first run and fails on every one after.
  keystorePath: './card-bot.cloak-keystore.json',
  // That is the whole list. A card is an ordinary message.
  requiredPermissions: ['message_send'],
  debug: process.env.DEBUG === '1',
});

function buildStatusCard(run: number, withLogo: boolean) {
  return {
    title: `Build #${run} passed`,
    // Put everything a reader must actually SEE in `description`. `fields`
    // render on desktop only today, and mobile drops the rows silently.
    description: ['42 tests, 0 failures', 'main @ 9f2a1c, 1m 12s', 'deployed to staging'].join('\n'),
    // Either a "#rrggbb" string or a decimal int (0x22c55e). Both render.
    color: '#22c55e',
    // A LINK slot: any http(s) URL. Nothing is fetched for it.
    url: `https://ci.example.com/runs/${run}`,
    footer: { text: 'card-bot' },
    timestamp: new Date().toISOString(),
    // A MEDIA slot: Cloak-hosted only, or sendCard() throws before sending.
    ...(withLogo && logoUrl ? { thumbnail: { url: logoUrl } } : {}),
  };
}

client.on('ready', () => {
  console.log(`Logged in as bot ${client.user?.id}`);
  console.log(logoUrl ? 'CLOAK_LOGO_URL is set, !logo will render a thumbnail' : 'no CLOAK_LOGO_URL');
});

client.on('messageCreate', async (msg) => {
  if (msg.authorId === client.user?.id) return; // ignore our own messages
  // Cards are a server-lane feature in v1: a DM has a null serverId, and the
  // DM card path is deliberately not shipped.
  if (msg.isDM || !msg.serverId) return;

  const cmd = msg.content.trim().split(/\s+/)[0];
  const run = 4800 + Math.floor(Math.random() * 100);

  try {
    if (cmd === '!build' || cmd === '!logo') {
      const embed = buildStatusCard(run, cmd === '!logo');
      await client.sendCard(msg.serverId, msg.channelId, {
        // `content` is REQUIRED and must be genuine human-readable text. It is
        // what search indexes, what push notifications and channel previews are
        // built from, and what a reply quoting this card renders.
        // embedFallbackText() derives one line from the embed, and throws on an
        // image-only embed rather than inventing something.
        content: embedFallbackText(embed),
        embed,
        // Full SendOptions parity: a card can be a real reply, and can ping.
        replyTo: msg,
      });
    } else if (cmd === '!bad') {
      // A third-party media URL throws LOCALLY, before anything reaches the
      // wire, with reason 'media-host' and the exact field path.
      await client.sendCard(msg.serverId, msg.channelId, {
        content: 'this never sends',
        embed: { title: 'Nope', image: { url: 'https://example.com/banner.png' } },
      });
    }
  } catch (e) {
    if (e instanceof CloakEmbedError) {
      // reason: 'media-host' | 'cap' | 'shape' | 'content' | 'empty' | 'wire-cap'
      console.error(`card refused (${e.reason}) at ${e.field ?? 'the payload'}: ${e.message}`);
      await msg
        .reply(
          `card refused: ${e.reason} at ${e.field ?? 'the payload'}. ` +
            `Media must be ${CLOAK_MEDIA_ORIGIN}-hosted.`,
        )
        .catch(() => undefined);
      return;
    }
    console.error(`${cmd} failed`, e);
    await msg.reply(`${cmd} failed: ${(e as Error).message}`).catch(() => undefined);
  }
});

client.on('error', (e) => console.error('sdk error', e));
client.on('disconnect', (e) => console.warn('disconnected', e));

client.login().catch((e) => {
  console.error('login failed', e);
  process.exit(1);
});