@heysummon/consumer-sdk 0.1.1

package/src/client.ts

@@ -0,0 +1,117 @@
+import type {
+  SubmitRequestOptions,
+  SubmitRequestResult,
+  PendingEvent,
+  Message,
+  WhoamiResult,
+  HeySummonClientOptions,
+  RequestStatusResponse,
+} from "./types.js";
+
+/** HTTP error with status code for callers to inspect */
+export class HeySummonHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body: string
+  ) {
+    super(`HTTP ${status}: ${statusText} — ${body}`);
+    this.name = "HeySummonHttpError";
+  }
+
+  get isAuthError(): boolean {
+    return this.status === 401 || this.status === 403 || this.status === 404;
+  }
+}
+
+/**
+ * Typed HTTP client for the HeySummon consumer API.
+ * Each method is a thin wrapper around fetch that includes the x-api-key header.
+ */
+export class HeySummonClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+
+  constructor(opts: HeySummonClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, ""); // trim trailing slash
+    this.apiKey = opts.apiKey;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey,
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "(no body)");
+      throw new HeySummonHttpError(res.status, res.statusText, text);
+    }
+
+    return res.json() as Promise<T>;
+  }
+
+  /** Identify which provider this API key is linked to */
+  async whoami(): Promise<WhoamiResult> {
+    return this.request<WhoamiResult>("GET", "/api/v1/whoami");
+  }
+
+  /** Submit a help request */
+  async submitRequest(opts: SubmitRequestOptions): Promise<SubmitRequestResult> {
+    return this.request<SubmitRequestResult>("POST", "/api/v1/help", {
+      apiKey: this.apiKey,
+      question: opts.question,
+      messages: opts.messages,
+      signPublicKey: opts.signPublicKey,
+      encryptPublicKey: opts.encryptPublicKey,
+      providerName: opts.providerName,
+      requiresApproval: opts.requiresApproval,
+    });
+  }
+
+  /** Poll for pending events (writes lastPollAt heartbeat on the server) */
+  async getPendingEvents(): Promise<{ events: PendingEvent[] }> {
+    return this.request<{ events: PendingEvent[] }>("GET", "/api/v1/events/pending");
+  }
+
+  /** Acknowledge a specific event */
+  async ackEvent(requestId: string): Promise<void> {
+    await this.request<unknown>("POST", `/api/v1/events/ack/${requestId}`, {});
+  }
+
+  /** Fetch the full message history for a request */
+  async getMessages(requestId: string): Promise<{ messages: Message[] }> {
+    return this.request<{ messages: Message[] }>(
+      "GET",
+      `/api/v1/messages/${requestId}`
+    );
+  }
+
+  /** Get the current status of a help request */
+  async getRequestStatus(
+    requestId: string
+  ): Promise<RequestStatusResponse> {
+    return this.request<RequestStatusResponse>(
+      "GET",
+      `/api/v1/help/${requestId}`
+    );
+  }
+
+  /** Look up a request by its ref code */
+  async getRequestByRef(
+    refCode: string
+  ): Promise<RequestStatusResponse> {
+    return this.request<RequestStatusResponse>(
+      "GET",
+      `/api/v1/requests/by-ref/${refCode}`
+    );
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,205 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export interface KeyPair {
+  signPublicKey: string;
+  encryptPublicKey: string;
+}
+
+/**
+ * Generate ephemeral Ed25519 + X25519 key pairs in memory.
+ * Returns hex-encoded DER public keys for the HeySummon API.
+ * Used by Claude Code (no file I/O needed).
+ */
+export function generateEphemeralKeys(): KeyPair {
+  const signKeys = crypto.generateKeyPairSync("ed25519");
+  const encKeys = crypto.generateKeyPairSync("x25519");
+
+  return {
+    signPublicKey: signKeys.publicKey
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+    encryptPublicKey: encKeys.publicKey
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+  };
+}
+
+/**
+ * Generate persistent Ed25519 + X25519 key pairs, writing PEM files to dir.
+ * Returns hex-encoded DER public keys for the HeySummon API.
+ * Used by OpenClaw (keys survive restarts).
+ */
+export function generatePersistentKeys(dir: string): KeyPair {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const ed = crypto.generateKeyPairSync("ed25519", {
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  });
+  fs.writeFileSync(path.join(dir, "sign_public.pem"), ed.publicKey);
+  fs.writeFileSync(path.join(dir, "sign_private.pem"), ed.privateKey);
+
+  const x = crypto.generateKeyPairSync("x25519", {
+    publicKeyEncoding: { type: "spki", format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  });
+  fs.writeFileSync(path.join(dir, "encrypt_public.pem"), x.publicKey);
+  fs.writeFileSync(path.join(dir, "encrypt_private.pem"), x.privateKey);
+
+  // Convert PEM to hex DER for the API
+  return {
+    signPublicKey: crypto
+      .createPublicKey(ed.publicKey)
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+    encryptPublicKey: crypto
+      .createPublicKey(x.publicKey)
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+  };
+}
+
+/**
+ * Load existing public keys from PEM files without regenerating.
+ * Returns hex-encoded DER public keys for the HeySummon API.
+ */
+export function loadPublicKeys(dir: string): KeyPair {
+  const signPem = fs.readFileSync(path.join(dir, "sign_public.pem"), "utf8");
+  const encPem = fs.readFileSync(
+    path.join(dir, "encrypt_public.pem"),
+    "utf8"
+  );
+
+  return {
+    signPublicKey: crypto
+      .createPublicKey(signPem)
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+    encryptPublicKey: crypto
+      .createPublicKey(encPem)
+      .export({ type: "spki", format: "der" })
+      .toString("hex"),
+  };
+}
+
+/**
+ * Encrypt a plaintext message using X25519 DH + AES-256-GCM + Ed25519 signing.
+ */
+export function encrypt(
+  plaintext: string,
+  recipientX25519PubPath: string,
+  ownSignPrivPath: string,
+  ownEncPrivPath: string,
+  messageId?: string
+): {
+  ciphertext: string;
+  iv: string;
+  authTag: string;
+  signature: string;
+  messageId: string;
+} {
+  const recipientPub = crypto.createPublicKey(
+    fs.readFileSync(recipientX25519PubPath)
+  );
+  const ownEncPriv = crypto.createPrivateKey(fs.readFileSync(ownEncPrivPath));
+  const signPriv = crypto.createPrivateKey(fs.readFileSync(ownSignPrivPath));
+
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: ownEncPriv,
+    publicKey: recipientPub,
+  });
+
+  const msgId = messageId || crypto.randomUUID();
+
+  const messageKey = crypto.hkdfSync(
+    "sha256",
+    sharedSecret,
+    msgId,
+    "heysummon-msg",
+    32
+  );
+
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(
+    "aes-256-gcm",
+    Buffer.from(messageKey),
+    iv
+  );
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final(),
+  ]);
+  const authTag = cipher.getAuthTag();
+
+  const signature = crypto.sign(null, encrypted, signPriv);
+
+  return {
+    ciphertext: encrypted.toString("base64"),
+    iv: iv.toString("base64"),
+    authTag: authTag.toString("base64"),
+    signature: signature.toString("base64"),
+    messageId: msgId,
+  };
+}
+
+/**
+ * Decrypt an encrypted message, verifying the Ed25519 signature first.
+ */
+export function decrypt(
+  payload: {
+    ciphertext: string;
+    iv: string;
+    authTag: string;
+    signature: string;
+    messageId: string;
+  },
+  senderX25519PubPath: string,
+  senderSignPubPath: string,
+  ownEncPrivPath: string
+): string {
+  const senderPub = crypto.createPublicKey(
+    fs.readFileSync(senderX25519PubPath)
+  );
+  const senderSignPub = crypto.createPublicKey(
+    fs.readFileSync(senderSignPubPath)
+  );
+  const ownPriv = crypto.createPrivateKey(fs.readFileSync(ownEncPrivPath));
+
+  const ciphertextBuf = Buffer.from(payload.ciphertext, "base64");
+  const valid = crypto.verify(
+    null,
+    ciphertextBuf,
+    senderSignPub,
+    Buffer.from(payload.signature, "base64")
+  );
+
+  if (!valid) {
+    throw new Error("Signature verification failed");
+  }
+
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: ownPriv,
+    publicKey: senderPub,
+  });
+
+  const messageKey = crypto.hkdfSync(
+    "sha256",
+    sharedSecret,
+    payload.messageId,
+    "heysummon-msg",
+    32
+  );
+
+  const decipher = crypto.createDecipheriv(
+    "aes-256-gcm",
+    Buffer.from(messageKey),
+    Buffer.from(payload.iv, "base64")
+  );
+  decipher.setAuthTag(Buffer.from(payload.authTag, "base64"));
+
+  return Buffer.concat([decipher.update(ciphertextBuf), decipher.final()]).toString("utf8");
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { HeySummonClient, HeySummonHttpError } from "./client.js";
+export { PollingWatcher } from "./poller.js";
+export { ProviderStore } from "./provider-store.js";
+export { RequestTracker } from "./request-tracker.js";
+export {
+  generateEphemeralKeys,
+  generatePersistentKeys,
+  loadPublicKeys,
+  encrypt,
+  decrypt,
+} from "./crypto.js";
+export type {
+  Provider,
+  SubmitRequestOptions,
+  SubmitRequestResult,
+  PendingEvent,
+  Message,
+  RequestStatusResponse,
+  WhoamiResult,
+  HeySummonClientOptions,
+} from "./types.js";
+export type { PollingWatcherOptions } from "./poller.js";
+export type { KeyPair } from "./crypto.js";

package/src/poller.ts

@@ -0,0 +1,72 @@
+import type { HeySummonClient } from "./client.js";
+import type { PendingEvent } from "./types.js";
+
+export interface PollingWatcherOptions {
+  client: HeySummonClient;
+  /** Interval between polls in ms (default: 5000) */
+  pollIntervalMs?: number;
+  /** Called for each new event received */
+  onEvent: (event: PendingEvent) => Promise<void>;
+  /** Called on network/poll errors — must not throw */
+  onError?: (err: Error) => void;
+}
+
+/**
+ * Polls /api/v1/events/pending on an interval and fires onEvent for each result.
+ * Replaces the 286-line platform-watcher.sh with a testable TypeScript class.
+ *
+ * Deduplication: tracks seen requestIds in memory to avoid double-processing.
+ */
+export class PollingWatcher {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private seen = new Set<string>();
+
+  constructor(private readonly opts: PollingWatcherOptions) {}
+
+  start(): void {
+    if (this.timer !== null) return; // already running
+
+    const interval = this.opts.pollIntervalMs ?? 5_000;
+
+    this.timer = setInterval(async () => {
+      try {
+        const { events } = await this.opts.client.getPendingEvents();
+
+        for (const event of events) {
+          const eventKey = `${event.requestId}:${event.type}:${event.latestMessageAt ?? ""}`;
+          if (this.seen.has(eventKey)) continue;
+          this.seen.add(eventKey);
+
+          try {
+            await this.opts.onEvent(event);
+          } catch (err) {
+            this.opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+          }
+
+          // Ack the event (best-effort, non-blocking)
+          if (event.requestId) {
+            this.opts.client.ackEvent(event.requestId).catch(() => {});
+          }
+        }
+      } catch (err) {
+        this.opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+      }
+    }, interval);
+  }
+
+  stop(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  isRunning(): boolean {
+    return this.timer !== null;
+  }
+
+  /** Reset the deduplication set (useful in tests) */
+  resetSeen(): void {
+    this.seen.clear();
+  }
+}

package/src/provider-store.ts

@@ -0,0 +1,88 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import type { Provider } from "./types.js";
+
+interface ProvidersFile {
+  providers: Provider[];
+}
+
+/**
+ * Typed replacement for the inline `node -e` JSON manipulation in the bash scripts.
+ * Reads/writes providers.json with deduplication by API key and case-insensitive name.
+ */
+export class ProviderStore {
+  private readonly filePath: string;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  load(): Provider[] {
+    if (!existsSync(this.filePath)) return [];
+    try {
+      const data = JSON.parse(readFileSync(this.filePath, "utf8")) as ProvidersFile;
+      return Array.isArray(data.providers) ? data.providers : [];
+    } catch {
+      return [];
+    }
+  }
+
+  save(providers: Provider[]): void {
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(this.filePath, JSON.stringify({ providers }, null, 2));
+  }
+
+  /**
+   * Add or update a provider entry.
+   * Deduplicates by API key and case-insensitive name (same logic as the bash script).
+   */
+  add(entry: Omit<Provider, "addedAt" | "nameLower"> & { addedAt?: string }): Provider {
+    const providers = this.load();
+    const nameLower = entry.name.toLowerCase();
+
+    // Remove existing entries with same key or name (case-insensitive)
+    const filtered = providers.filter(
+      (p) => p.apiKey !== entry.apiKey && p.nameLower !== nameLower
+    );
+
+    const newEntry: Provider = {
+      name: entry.name,
+      nameLower,
+      apiKey: entry.apiKey,
+      providerId: entry.providerId,
+      providerName: entry.providerName,
+      addedAt: entry.addedAt ?? new Date().toISOString(),
+    };
+
+    filtered.push(newEntry);
+    this.save(filtered);
+    return newEntry;
+  }
+
+  /** Case-insensitive lookup by name or alias */
+  findByName(name: string): Provider | undefined {
+    const lower = name.toLowerCase();
+    return this.load().find((p) => p.nameLower === lower || p.name.toLowerCase() === lower);
+  }
+
+  /** Look up by exact API key */
+  findByKey(apiKey: string): Provider | undefined {
+    return this.load().find((p) => p.apiKey === apiKey);
+  }
+
+  /** Returns the first provider (default when only one is registered) */
+  getDefault(): Provider | undefined {
+    return this.load()[0];
+  }
+
+  remove(apiKey: string): boolean {
+    const providers = this.load();
+    const filtered = providers.filter((p) => p.apiKey !== apiKey);
+    if (filtered.length === providers.length) return false;
+    this.save(filtered);
+    return true;
+  }
+}

package/src/request-tracker.ts

@@ -0,0 +1,72 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+interface TrackedRequest {
+  requestId: string;
+  refCode: string;
+  provider?: string;
+}
+
+/**
+ * File-based request tracker. Each request is stored as a file:
+ *   {dir}/{requestId}          — contains the refCode
+ *   {dir}/{requestId}.provider — contains the provider name (optional)
+ *
+ * Compatible with the existing OpenClaw .requests/ directory format.
+ */
+export class RequestTracker {
+  constructor(private readonly dir: string) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  track(requestId: string, refCode: string, providerName?: string): void {
+    writeFileSync(join(this.dir, requestId), refCode);
+    if (providerName) {
+      writeFileSync(join(this.dir, `${requestId}.provider`), providerName);
+    }
+  }
+
+  getRefCode(requestId: string): string | null {
+    const file = join(this.dir, requestId);
+    if (!existsSync(file)) return null;
+    return readFileSync(file, "utf8").trim();
+  }
+
+  getProvider(requestId: string): string | null {
+    const file = join(this.dir, `${requestId}.provider`);
+    if (!existsSync(file)) return null;
+    return readFileSync(file, "utf8").trim();
+  }
+
+  remove(requestId: string): void {
+    const refFile = join(this.dir, requestId);
+    const provFile = join(this.dir, `${requestId}.provider`);
+    if (existsSync(refFile)) unlinkSync(refFile);
+    if (existsSync(provFile)) unlinkSync(provFile);
+  }
+
+  listActive(): TrackedRequest[] {
+    if (!existsSync(this.dir)) return [];
+    const files = readdirSync(this.dir);
+    const result: TrackedRequest[] = [];
+
+    for (const file of files) {
+      // Skip .provider files, .watcher.pid, hidden files
+      if (file.includes(".")) continue;
+
+      const requestId = file;
+      const refCode = this.getRefCode(requestId);
+      if (!refCode) continue;
+
+      result.push({
+        requestId,
+        refCode,
+        provider: this.getProvider(requestId) ?? undefined,
+      });
+    }
+
+    return result;
+  }
+}

package/src/types.ts

@@ -0,0 +1,92 @@
+export interface Provider {
+  name: string;
+  nameLower: string;
+  apiKey: string;
+  providerId: string;
+  providerName: string;
+  addedAt: string;
+}
+
+export interface SubmitRequestOptions {
+  question: string;
+  messages?: Array<{ role: string; content: string }>;
+  signPublicKey?: string;
+  encryptPublicKey?: string;
+  providerName?: string;
+  requiresApproval?: boolean;
+}
+
+export interface SubmitRequestResult {
+  requestId: string;
+  refCode: string;
+  status: string;
+  expiresAt: string;
+  providerUnavailable?: boolean;
+  nextAvailableAt?: string;
+  serverPublicKey?: string;
+}
+
+export interface PendingEvent {
+  type:
+    | "new_request"
+    | "new_message"
+    | "keys_exchanged"
+    | "responded"
+    | "closed" 
+    | "cancelled";
+  requestId: string;
+  refCode: string | null;
+  from?: "provider" | "consumer";
+  messageCount?: number;
+  respondedAt?: string | null;
+  latestMessageAt?: string | null;
+  cancelledAt?: string | null;
+  question?: string | null;
+  requiresApproval?: boolean;
+  createdAt?: string;
+  expiresAt?: string;
+}
+
+export interface Message {
+  id: string;
+  from: "provider" | "consumer";
+  ciphertext: string;
+  iv: string;
+  authTag: string;
+  signature: string;
+  messageId: string;
+  createdAt: string;
+  plaintext?: string;
+}
+
+export interface RequestStatusResponse {
+  requestId: string;
+  refCode: string | null;
+  status: string;
+  response?: string;
+  lastMessage?: string;
+  question?: string;
+  providerName?: string;
+  provider?: { id: string; name: string };
+  createdAt?: string;
+  expiresAt?: string;
+}
+
+export interface HeySummonClientOptions {
+  baseUrl: string;
+  apiKey: string;
+}
+
+export interface WhoamiResult {
+  keyId: string;
+  keyName: string | null;
+  provider: {
+    id: string;
+    name: string;
+    isActive: boolean;
+  };
+  expert: {
+    id: string;
+    name: string | null;
+  };
+}