SKILL.md- the skill, written out in plain English

criteria:
  - name: api_imports_correctly
    kind: deterministic
    check: "The skill's implementation in state/lib/whatsapp.ts correctly imports and uses the Meta Cloud API for WhatsApp."
  - name: send_message_functional
    kind: judge
    check: "The sendMessage() function successfully sends a WhatsApp message as intended by the input sendMessage_input."
  - name: notify_robert_functional
    kind: judge
    check: "The notifyRobert() function successfully sends a WhatsApp notification to Robert as intended by the input notifyRobert_input."
  - name: log_pending_eval_row
    kind: deterministic
    check: "A new row is appended to state/log/pending-eval.ndjson for each execution of the skill."

AGENTS.md- what the AI loads when this skill comes up

root = WhatsAppPreview("<contact>", "<drafted message body>", true)

root = AuthRequiredCallout("WhatsApp", "", "WhatsApp is not connected yet. No registered Query exists for this service.")

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-whatsapp/api.ts -- WhatsApp messaging via Meta Cloud API for all snappy-* skills.
 *
 * Direct WhatsApp Cloud API calls -- no Xano middleware.
 * Phone numbers MUST be E.164 format (+14155551212).
 *
 * Required env vars (via snappy-settings/.env.cache):
 *   WHATSAPP_TOKEN    -- Meta Business API access token
 *   WHATSAPP_PHONE_ID -- WhatsApp Business phone number ID
 *   ROBERT_PHONE      -- Robert's phone for notifyRobert (E.164)
 *
 * Usage:
 *   npx tsx api.ts send "+14155551212" "Hey, quick update..."
 *   npx tsx api.ts media "+14155551212" "https://example.com/img.png" "Caption"
 *   npx tsx api.ts notify "Build completed"
 *
 * Or import as module:
 *   import { sendMessage, sendMedia, notifyRobert, getRecentWhatsAppMessages } from "./whatsapp.ts";
 */

import { env } from "./env.ts";
import { realpathSync } from "fs";

const GRAPH_API = "https://graph.facebook.com/v21.0";

const CONFIG_ERROR =
  "snappy-whatsapp not configured. Add WHATSAPP_TOKEN, WHATSAPP_PHONE_ID, ROBERT_PHONE to .env.cache";

function requireConfig(): { token: string; phoneId: string; robertPhone: string } {
  const t = env("WHATSAPP_TOKEN", false);
  const p = env("WHATSAPP_PHONE_ID", false);
  const r = env("ROBERT_PHONE", false);
  if (!t || !p || !r) throw new Error(CONFIG_ERROR);
  return { token: t, phoneId: p, robertPhone: r };
}

async function whatsappFetch(body: Record<string, unknown>) {
  const { token, phoneId } = requireConfig();
  const res = await fetch(`${GRAPH_API}/${phoneId}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ messaging_product: "whatsapp", ...body }),
  });
  const data = await res.json();
  if (!res.ok) {
    throw new Error(`WhatsApp Cloud API failed (${res.status}): ${JSON.stringify(data)}`);
  }
  return data;
}

// --- Public API ---

export async function sendMessage(to: string, message: string) {
  return whatsappFetch({
    to,
    type: "text",
    text: { body: message },
  });
}

export async function sendMedia(to: string, mediaUrl: string, caption?: string) {
  return whatsappFetch({
    to,
    type: "image",
    image: { link: mediaUrl, ...(caption ? { caption } : {}) },
  });
}

export async function notifyRobert(text: string) {
  const { robertPhone } = requireConfig();
  return sendMessage(robertPhone, text);
}

// --- Read operations (webhook-based) ---

/**
 * Fetch recent messages from the WhatsApp webhook log.
 * WhatsApp Cloud API doesn't support polling — messages arrive via webhook.
 * This reads from the local webhook log file if it exists.
 */
export async function getRecentWhatsAppMessages(limit = 20): Promise<Array<{
  from: string;
  text: string;
  timestamp: string;
  message_id: string;
  type: string;
}>> {
  const { existsSync, readFileSync } = await import("fs");
  const { join } = await import("path");
  const logPath = join(process.env.HOME!, ".claude/skills/snappy-whatsapp/webhook-log.jsonl");
  if (!existsSync(logPath)) return [];
  const lines = readFileSync(logPath, "utf-8").trim().split("\n").filter(Boolean);
  return lines.slice(-limit).map(line => {
    const entry = JSON.parse(line);
    return {
      from: entry.from || "unknown",
      text: entry.text || entry.caption || "[non-text]",
      timestamp: entry.timestamp || "",
      message_id: entry.message_id || "",
      type: entry.type || "text",
    };
  });
}

/**
 * Mark a message as read (sends read receipt).
 */
export async function markWhatsAppRead(messageId: string) {
  const { token, phoneId } = requireConfig();
  const res = await fetch(`${GRAPH_API}/${phoneId}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      status: "read",
      message_id: messageId,
    }),
  });
  return res.json();
}

/**
 * React to a message with an emoji.
 */
export async function reactToMessage(messageId: string, emoji: string) {
  return whatsappFetch({
    to: "", // not needed for reactions but required by schema
    type: "reaction",
    reaction: { message_id: messageId, emoji },
  });
}

/**
 * Log an incoming webhook message to the local log file.
 * Call this from the webhook handler to build the read log.
 */
export async function logIncomingMessage(payload: Record<string, unknown>) {
  const { appendFileSync, mkdirSync } = await import("fs");
  const { join, dirname } = await import("path");
  const logPath = join(process.env.HOME!, ".claude/skills/snappy-whatsapp/webhook-log.jsonl");
  mkdirSync(dirname(logPath), { recursive: true });
  appendFileSync(logPath, JSON.stringify({ ...payload, logged_at: new Date().toISOString() }) + "\n");
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "send": {
        const [to, ...msgParts] = args;
        if (!to || !msgParts.length) { console.error("Usage: api.ts send <+E.164> <message>"); process.exit(1); }
        const data = await sendMessage(to, msgParts.join(" "));
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "media": {
        const [to, mediaUrl, ...captionParts] = args;
        if (!to || !mediaUrl) { console.error("Usage: api.ts media <+E.164> <url> [caption]"); process.exit(1); }
        const data = await sendMedia(to, mediaUrl, captionParts.join(" ") || undefined);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "notify": {
        const text = args.join(" ");
        if (!text) { console.error("Usage: api.ts notify <text>"); process.exit(1); }
        const data = await notifyRobert(text);
        console.log(JSON.stringify(data, null, 2));
        break;
      }
      case "read": {
        const limit = args[0] ? parseInt(args[0], 10) : 20;
        const msgs = await getRecentWhatsAppMessages(limit);
        if (msgs.length === 0) {
          console.log("No messages in webhook log. Set up webhook handler to log incoming messages.");
        } else {
          for (const m of msgs) {
            console.log(`${m.timestamp}\t${m.from}\t${m.text.slice(0, 300)}`);
          }
        }
        break;
      }
      case "mark-read": {
        const [msgId] = args;
        if (!msgId) { console.error("Usage: api.ts mark-read <message_id>"); process.exit(1); }
        await markWhatsAppRead(msgId);
        console.log("marked read");
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [send|media|notify|read|mark-read] ...");
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet