@answerloops/agent-sdk 0.5.1 → 0.6.2

package/README.md

@@ -1,8 +1,32 @@
 # @answerloops/agent-sdk
 
-Typed Node/browser client for the [answerLoops Agent API](https://answerloops.com/docs/integrations/agent-api) — search the knowledge base, read the FAQ digest, list/create tickets, and generate grounded answers.
+Typed Node/browser client for the [answerLoops Agent API](https://answerloops.com/docs/integrations/agent-api) — search the knowledge base, read the FAQ digest, list/create tickets, and generate grounded answers. Also ships a CLI (`answerloops`) that bootstraps a self-hosted instance or installs the [Claude Code agent skills](https://answerloops.com/docs/integrations/agent-skills).
 
-## Install
+## Getting started
+
+Don't have a running answerLoops instance yet? Bootstrap one:
+
+```bash
+npx @answerloops/agent-sdk setup
+```
+
+Clones the repo if needed, checks Docker + git are present, generates
+`AUTH_SECRET`/`ENCRYPTION_KEY`, starts the published image via Docker
+Compose, and polls `/api/health` until it's actually up. It never invents a
+real credential — if `DATABASE_URL`, `AUTH_URL`, or the Google OAuth pair are
+missing, it tells you exactly what to add to `.env` and exits, rather than
+guessing.
+
+Already have a workspace (hosted or self-hosted) and just want an agent
+connected to it? Install the Claude Code skills instead:
+
+```bash
+npx @answerloops/agent-sdk skills answerloops-setup answerloops-operate
+```
+
+Writes both into `.claude/skills/` — install just one by naming it alone.
+
+Building against the API directly instead? Install the library:
 
 ```bash
 npm install @answerloops/agent-sdk
@@ -24,7 +48,9 @@ const answer = await client.generateAnswer({ question: "How do I reset my API ke
 
 const ticket = await client.createTicket({ content: "My webhook stopped firing." });
 
-const { tickets } = await client.getTickets({ status: "open", limit: 10 });
+const { tickets, next_cursor } = await client.getTickets({ status: "open", limit: 10 });
+// next_cursor is non-null while more tickets remain — pass it back as `cursor` to keep paging:
+// await client.getTickets({ status: "open", limit: 10, cursor: next_cursor });
 ```
 
 Every key carries least-privilege scopes (`kb:read`, `faq:read`, `tickets:read`, `tickets:write`, `answers:write`) set in **Settings → API Keys**. A call against a scope the key doesn't have throws `AgentApiError` with `status === 403`.
@@ -40,7 +66,14 @@ try {
   await client.generateAnswer({ question: "..." });
 } catch (err) {
   if (err instanceof AgentApiError) {
-    console.error(err.status, err.body);
+    console.error(err.status, err.message);
+    // On a 429, err.code tells apart the per-minute rate limit from either
+    // monthly quota — "rate_limited" (retry shortly) vs.
+    // "deflection_limit_reached" / "call_limit_reached" (upgrade, or wait
+    // for the next billing cycle; retrying immediately won't help).
+    if (err.code === "rate_limited") {
+      // back off and retry
+    }
   }
 }
 ```

package/dist/cli/index.cjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/index.ts
+var import_node_util = require("util");
+
+// src/cli/setup.ts
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
+
+// src/cli/util.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+function log(msg) {
+  console.log(msg);
+}
+function fail(msg) {
+  console.error(`\u2717 ${msg}`);
+  process.exit(1);
+}
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process.spawn)(cmd, args, {
+      cwd: opts.cwd,
+      env: opts.env ?? process.env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+}
+function commandExists(cmd, args) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.spawn)(cmd, args, { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}
+function fileExists(path) {
+  return (0, import_node_fs.existsSync)(path);
+}
+
+// src/cli/prereqs.ts
+async function checkPrereqs() {
+  const missing = [];
+  if (!await commandExists("git", ["--version"])) {
+    missing.push("git \u2014 https://git-scm.com/downloads");
+  }
+  if (!await commandExists("docker", ["--version"])) {
+    missing.push("Docker \u2014 https://docs.docker.com/get-docker/");
+  } else if (!await commandExists("docker", ["compose", "version"])) {
+    missing.push("Docker Compose v2 \u2014 update Docker Desktop or install the compose plugin");
+  }
+  if (missing.length > 0) {
+    for (const m of missing) console.error(`\u2717 ${m}`);
+    fail("Missing prerequisites. Install the above, then re-run.");
+  }
+  log("\u2713 git and Docker (with Compose v2) found");
+}
+
+// src/cli/repo.ts
+var import_node_path = require("path");
+var REPO_URL = "https://github.com/answerLoops/answerLoops.git";
+var MARKER = "docker-compose.ghcr.yml";
+async function ensureRepo(targetDir) {
+  if (fileExists((0, import_node_path.join)(process.cwd(), MARKER))) {
+    return process.cwd();
+  }
+  if (fileExists((0, import_node_path.join)(targetDir, MARKER))) {
+    log(`\u2713 using existing checkout at ${targetDir}`);
+    return targetDir;
+  }
+  log(`Cloning ${REPO_URL} into ${targetDir}...`);
+  const code = await run("git", ["clone", REPO_URL, targetDir]);
+  if (code !== 0) fail(`git clone failed (exit ${code})`);
+  return targetDir;
+}
+
+// src/cli/env.ts
+var import_node_crypto = require("crypto");
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var REQUIRED_VARS = ["DATABASE_URL", "AUTH_URL", "AUTH_GOOGLE_ID", "AUTH_GOOGLE_SECRET"];
+var HOW_TO_GET = {
+  DATABASE_URL: "a Postgres connection string you run and control, e.g. postgresql://user:pass@host:5432/db",
+  AUTH_URL: "the public URL this instance will be reachable at, e.g. http://localhost:3000",
+  AUTH_GOOGLE_ID: "a Google OAuth client ID \u2014 console.cloud.google.com, register callback {AUTH_URL}/api/auth/callback/google",
+  AUTH_GOOGLE_SECRET: "the matching Google OAuth client secret from the same client"
+};
+function parseEnvFile(path) {
+  if (!(0, import_node_fs2.existsSync)(path)) return {};
+  const out = {};
+  for (const line of (0, import_node_fs2.readFileSync)(path, "utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    out[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return out;
+}
+function genSecret() {
+  return (0, import_node_crypto.randomBytes)(32).toString("hex");
+}
+function ensureEnv(repoDir) {
+  const envPath = (0, import_node_path2.join)(repoDir, ".env");
+  const existing = parseEnvFile(envPath);
+  const toAppend = [];
+  for (const secretVar of ["AUTH_SECRET", "ENCRYPTION_KEY"]) {
+    if (!existing[secretVar] && !process.env[secretVar]) {
+      const value = genSecret();
+      toAppend.push(`${secretVar}=${value}`);
+      log(`\u2713 generated ${secretVar}`);
+    }
+  }
+  if (toAppend.length > 0) {
+    (0, import_node_fs2.appendFileSync)(envPath, ((0, import_node_fs2.existsSync)(envPath) ? "\n" : "") + toAppend.join("\n") + "\n");
+  } else if (!(0, import_node_fs2.existsSync)(envPath)) {
+    (0, import_node_fs2.writeFileSync)(envPath, "");
+  }
+  const missing = REQUIRED_VARS.filter((v) => !existing[v] && !process.env[v]);
+  if (missing.length > 0) {
+    console.error(`Missing required configuration in ${envPath}:`);
+    for (const v of missing) console.error(`  ${v} \u2014 ${HOW_TO_GET[v]}`);
+    console.error(
+      `
+Add these to ${envPath} (or export them before running this command), then re-run.`
+    );
+    fail("Required environment variables not set.");
+  }
+  log(`\u2713 ${envPath} has everything required`);
+}
+
+// src/cli/health.ts
+async function waitForHealth(url, timeoutSeconds = 120) {
+  const intervalMs = 3e3;
+  const deadline = Date.now() + timeoutSeconds * 1e3;
+  log(`Waiting for ${url} to become healthy (timeout ${timeoutSeconds}s)...`);
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) {
+        log(`\u2713 healthy`);
+        return;
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  fail(
+    `${url} still unhealthy after ${timeoutSeconds}s. Check logs: docker compose -f docker-compose.ghcr.yml logs app -f`
+  );
+}
+
+// src/cli/skills.ts
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
+var RAW_BASE = "https://raw.githubusercontent.com/answerLoops/answerLoops/main";
+var SKILLS = {
+  "answerloops-setup": ["skills/setup/SKILL.md"],
+  "answerloops-operate": ["skills/operate/SKILL.md"]
+};
+async function installSkills(names) {
+  for (const name of names) {
+    const files = SKILLS[name];
+    if (!files) fail(`Unknown skill "${name}". Known: ${Object.keys(SKILLS).join(", ")}`);
+    const destDir = (0, import_node_path3.join)(".claude", "skills", name);
+    (0, import_node_fs3.mkdirSync)(destDir, { recursive: true });
+    for (const relPath of files) {
+      const url = `${RAW_BASE}/${relPath}`;
+      const res = await fetch(url);
+      if (!res.ok) fail(`Could not fetch ${url} (${res.status})`);
+      const body = await res.text();
+      const destPath = (0, import_node_path3.join)(destDir, relPath.split("/").pop());
+      (0, import_node_fs3.writeFileSync)(destPath, body);
+    }
+    log(`\u2713 installed ${name} -> ${destDir}`);
+  }
+}
+
+// src/cli/setup.ts
+async function runSetup(opts) {
+  await checkPrereqs();
+  const repoDir = await ensureRepo(opts.targetDir);
+  ensureEnv(repoDir);
+  log("Starting the stack (docker compose -f docker-compose.ghcr.yml up -d)...");
+  const code = await run("docker", ["compose", "-f", "docker-compose.ghcr.yml", "up", "-d"], {
+    cwd: repoDir
+  });
+  if (code !== 0) fail(`docker compose up failed (exit ${code})`);
+  const authUrl = readAuthUrl(repoDir) ?? "http://localhost:3000";
+  await waitForHealth(`${authUrl.replace(/\/+$/, "")}/api/health`);
+  if (opts.withSkills) {
+    await installSkills(["answerloops-setup", "answerloops-operate"]);
+  }
+  log(`
+Your instance is live at ${authUrl}. Sign in with Google and complete onboarding.`);
+}
+function readAuthUrl(repoDir) {
+  try {
+    const text = (0, import_node_fs4.readFileSync)((0, import_node_path4.join)(repoDir, ".env"), "utf8");
+    const line = text.split("\n").find((l) => l.trim().startsWith("AUTH_URL="));
+    return line?.slice(line.indexOf("=") + 1).trim();
+  } catch {
+    return void 0;
+  }
+}
+
+// src/cli/index.ts
+var USAGE = `Usage: answerloops <command> [options]
+
+Commands:
+  setup                Bootstrap a self-hosted answerLoops instance (Docker,
+                        the published image). Requires Docker + git.
+    --dir <path>          Directory to clone into if not already in a
+                           checkout (default: ./answerLoops)
+    --with-skills          Also install the Claude Code setup + operate
+                           skills into ./.claude/skills/
+
+  skills <name...>     Install one or more Claude Code skills into
+                        ./.claude/skills/. Names: answerloops-setup,
+                        answerloops-operate
+
+  help                 Show this message
+`;
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "setup": {
+      const { values } = (0, import_node_util.parseArgs)({
+        args: rest,
+        options: {
+          dir: { type: "string", default: "answerLoops" },
+          "with-skills": { type: "boolean", default: false }
+        }
+      });
+      await runSetup({ targetDir: values.dir, withSkills: values["with-skills"] });
+      break;
+    }
+    case "skills": {
+      if (rest.length === 0) {
+        console.error("Usage: answerloops skills <name...>");
+        process.exit(1);
+      }
+      await installSkills(rest);
+      break;
+    }
+    case "help":
+    case void 0:
+    case "--help":
+    case "-h":
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`Unknown command "${command}"
+`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/dist/cli/index.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { parseArgs } from "util";
+
+// src/cli/setup.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join4 } from "path";
+
+// src/cli/util.ts
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+function log(msg) {
+  console.log(msg);
+}
+function fail(msg) {
+  console.error(`\u2717 ${msg}`);
+  process.exit(1);
+}
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd: opts.cwd,
+      env: opts.env ?? process.env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+}
+function commandExists(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+}
+function fileExists(path) {
+  return existsSync(path);
+}
+
+// src/cli/prereqs.ts
+async function checkPrereqs() {
+  const missing = [];
+  if (!await commandExists("git", ["--version"])) {
+    missing.push("git \u2014 https://git-scm.com/downloads");
+  }
+  if (!await commandExists("docker", ["--version"])) {
+    missing.push("Docker \u2014 https://docs.docker.com/get-docker/");
+  } else if (!await commandExists("docker", ["compose", "version"])) {
+    missing.push("Docker Compose v2 \u2014 update Docker Desktop or install the compose plugin");
+  }
+  if (missing.length > 0) {
+    for (const m of missing) console.error(`\u2717 ${m}`);
+    fail("Missing prerequisites. Install the above, then re-run.");
+  }
+  log("\u2713 git and Docker (with Compose v2) found");
+}
+
+// src/cli/repo.ts
+import { join } from "path";
+var REPO_URL = "https://github.com/answerLoops/answerLoops.git";
+var MARKER = "docker-compose.ghcr.yml";
+async function ensureRepo(targetDir) {
+  if (fileExists(join(process.cwd(), MARKER))) {
+    return process.cwd();
+  }
+  if (fileExists(join(targetDir, MARKER))) {
+    log(`\u2713 using existing checkout at ${targetDir}`);
+    return targetDir;
+  }
+  log(`Cloning ${REPO_URL} into ${targetDir}...`);
+  const code = await run("git", ["clone", REPO_URL, targetDir]);
+  if (code !== 0) fail(`git clone failed (exit ${code})`);
+  return targetDir;
+}
+
+// src/cli/env.ts
+import { randomBytes } from "crypto";
+import { existsSync as existsSync2, readFileSync, appendFileSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+var REQUIRED_VARS = ["DATABASE_URL", "AUTH_URL", "AUTH_GOOGLE_ID", "AUTH_GOOGLE_SECRET"];
+var HOW_TO_GET = {
+  DATABASE_URL: "a Postgres connection string you run and control, e.g. postgresql://user:pass@host:5432/db",
+  AUTH_URL: "the public URL this instance will be reachable at, e.g. http://localhost:3000",
+  AUTH_GOOGLE_ID: "a Google OAuth client ID \u2014 console.cloud.google.com, register callback {AUTH_URL}/api/auth/callback/google",
+  AUTH_GOOGLE_SECRET: "the matching Google OAuth client secret from the same client"
+};
+function parseEnvFile(path) {
+  if (!existsSync2(path)) return {};
+  const out = {};
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    out[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return out;
+}
+function genSecret() {
+  return randomBytes(32).toString("hex");
+}
+function ensureEnv(repoDir) {
+  const envPath = join2(repoDir, ".env");
+  const existing = parseEnvFile(envPath);
+  const toAppend = [];
+  for (const secretVar of ["AUTH_SECRET", "ENCRYPTION_KEY"]) {
+    if (!existing[secretVar] && !process.env[secretVar]) {
+      const value = genSecret();
+      toAppend.push(`${secretVar}=${value}`);
+      log(`\u2713 generated ${secretVar}`);
+    }
+  }
+  if (toAppend.length > 0) {
+    appendFileSync(envPath, (existsSync2(envPath) ? "\n" : "") + toAppend.join("\n") + "\n");
+  } else if (!existsSync2(envPath)) {
+    writeFileSync(envPath, "");
+  }
+  const missing = REQUIRED_VARS.filter((v) => !existing[v] && !process.env[v]);
+  if (missing.length > 0) {
+    console.error(`Missing required configuration in ${envPath}:`);
+    for (const v of missing) console.error(`  ${v} \u2014 ${HOW_TO_GET[v]}`);
+    console.error(
+      `
+Add these to ${envPath} (or export them before running this command), then re-run.`
+    );
+    fail("Required environment variables not set.");
+  }
+  log(`\u2713 ${envPath} has everything required`);
+}
+
+// src/cli/health.ts
+async function waitForHealth(url, timeoutSeconds = 120) {
+  const intervalMs = 3e3;
+  const deadline = Date.now() + timeoutSeconds * 1e3;
+  log(`Waiting for ${url} to become healthy (timeout ${timeoutSeconds}s)...`);
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) {
+        log(`\u2713 healthy`);
+        return;
+      }
+    } catch {
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  fail(
+    `${url} still unhealthy after ${timeoutSeconds}s. Check logs: docker compose -f docker-compose.ghcr.yml logs app -f`
+  );
+}
+
+// src/cli/skills.ts
+import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
+var RAW_BASE = "https://raw.githubusercontent.com/answerLoops/answerLoops/main";
+var SKILLS = {
+  "answerloops-setup": ["skills/setup/SKILL.md"],
+  "answerloops-operate": ["skills/operate/SKILL.md"]
+};
+async function installSkills(names) {
+  for (const name of names) {
+    const files = SKILLS[name];
+    if (!files) fail(`Unknown skill "${name}". Known: ${Object.keys(SKILLS).join(", ")}`);
+    const destDir = join3(".claude", "skills", name);
+    mkdirSync(destDir, { recursive: true });
+    for (const relPath of files) {
+      const url = `${RAW_BASE}/${relPath}`;
+      const res = await fetch(url);
+      if (!res.ok) fail(`Could not fetch ${url} (${res.status})`);
+      const body = await res.text();
+      const destPath = join3(destDir, relPath.split("/").pop());
+      writeFileSync2(destPath, body);
+    }
+    log(`\u2713 installed ${name} -> ${destDir}`);
+  }
+}
+
+// src/cli/setup.ts
+async function runSetup(opts) {
+  await checkPrereqs();
+  const repoDir = await ensureRepo(opts.targetDir);
+  ensureEnv(repoDir);
+  log("Starting the stack (docker compose -f docker-compose.ghcr.yml up -d)...");
+  const code = await run("docker", ["compose", "-f", "docker-compose.ghcr.yml", "up", "-d"], {
+    cwd: repoDir
+  });
+  if (code !== 0) fail(`docker compose up failed (exit ${code})`);
+  const authUrl = readAuthUrl(repoDir) ?? "http://localhost:3000";
+  await waitForHealth(`${authUrl.replace(/\/+$/, "")}/api/health`);
+  if (opts.withSkills) {
+    await installSkills(["answerloops-setup", "answerloops-operate"]);
+  }
+  log(`
+Your instance is live at ${authUrl}. Sign in with Google and complete onboarding.`);
+}
+function readAuthUrl(repoDir) {
+  try {
+    const text = readFileSync2(join4(repoDir, ".env"), "utf8");
+    const line = text.split("\n").find((l) => l.trim().startsWith("AUTH_URL="));
+    return line?.slice(line.indexOf("=") + 1).trim();
+  } catch {
+    return void 0;
+  }
+}
+
+// src/cli/index.ts
+var USAGE = `Usage: answerloops <command> [options]
+
+Commands:
+  setup                Bootstrap a self-hosted answerLoops instance (Docker,
+                        the published image). Requires Docker + git.
+    --dir <path>          Directory to clone into if not already in a
+                           checkout (default: ./answerLoops)
+    --with-skills          Also install the Claude Code setup + operate
+                           skills into ./.claude/skills/
+
+  skills <name...>     Install one or more Claude Code skills into
+                        ./.claude/skills/. Names: answerloops-setup,
+                        answerloops-operate
+
+  help                 Show this message
+`;
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "setup": {
+      const { values } = parseArgs({
+        args: rest,
+        options: {
+          dir: { type: "string", default: "answerLoops" },
+          "with-skills": { type: "boolean", default: false }
+        }
+      });
+      await runSetup({ targetDir: values.dir, withSkills: values["with-skills"] });
+      break;
+    }
+    case "skills": {
+      if (rest.length === 0) {
+        console.error("Usage: answerloops skills <name...>");
+        process.exit(1);
+      }
+      await installSkills(rest);
+      break;
+    }
+    case "help":
+    case void 0:
+    case "--help":
+    case "-h":
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`Unknown command "${command}"
+`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/dist/index.cjs

@@ -29,11 +29,14 @@ module.exports = __toCommonJS(index_exports);
 var AgentApiError = class extends Error {
   status;
   body;
+  /** Only ever set on a 429 — see AgentApiErrorCode. */
+  code;
   constructor(status, body, message) {
     super(message);
     this.name = "AgentApiError";
     this.status = status;
     this.body = body;
+    this.code = body?.error?.code;
   }
 };
 var DEFAULT_BASE_URL = "https://answerloops.com";
@@ -49,54 +52,64 @@ var AgentClient = class {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.fetchImpl = options.fetch ?? fetch;
   }
-  /** GET /api/agent/kb/search — requires the `kb:read` scope. */
+  /** GET /api/v1/agent/kb/search — requires the `kb:read` scope. */
   searchKb(params) {
     const query = new URLSearchParams({ query: params.query });
     if (params.limit !== void 0) query.set("limit", String(params.limit));
-    return this.request("GET", `/api/agent/kb/search?${query}`);
+    return this.request("GET", `/api/v1/agent/kb/search?${query}`);
   }
-  /** GET /api/agent/faq — requires the `faq:read` scope. */
+  /** GET /api/v1/agent/faq — requires the `faq:read` scope. */
   getFaq() {
-    return this.request("GET", "/api/agent/faq");
+    return this.request("GET", "/api/v1/agent/faq");
   }
-  /** GET /api/agent/tickets — requires the `tickets:read` scope. */
+  /** GET /api/v1/agent/tickets — requires the `tickets:read` scope. */
   getTickets(params = {}) {
     const query = new URLSearchParams();
     if (params.status) query.set("status", params.status);
     if (params.priority) query.set("priority", params.priority);
     if (params.category) query.set("category", params.category);
     if (params.limit !== void 0) query.set("limit", String(params.limit));
+    if (params.cursor !== void 0) query.set("cursor", params.cursor);
     const qs = query.toString();
-    return this.request("GET", `/api/agent/tickets${qs ? `?${qs}` : ""}`);
+    return this.request("GET", `/api/v1/agent/tickets${qs ? `?${qs}` : ""}`);
   }
-  /** POST /api/agent/tickets — requires the `tickets:write` scope. */
+  /**
+   * POST /api/v1/agent/tickets — requires the `tickets:write` scope.
+   * `idempotencyKey`, when given, is sent as the standard `Idempotency-Key`
+   * header (what most HTTP clients/SDKs attach automatically) rather than a
+   * body field — the server accepts either, but the header is what it
+   * prefers when both are present.
+   */
   createTicket(params) {
-    return this.request("POST", "/api/agent/tickets", {
-      content: params.content,
-      authorName: params.authorName,
-      idempotencyKey: params.idempotencyKey
-    });
+    return this.request(
+      "POST",
+      "/api/v1/agent/tickets",
+      { content: params.content, authorName: params.authorName },
+      params.idempotencyKey ? { "Idempotency-Key": params.idempotencyKey } : void 0
+    );
   }
-  /** POST /api/agent/answers — requires the `answers:write` scope. */
+  /** POST /api/v1/agent/answers — requires the `answers:write` scope. */
   generateAnswer(params) {
-    return this.request("POST", "/api/agent/answers", { question: params.question });
+    return this.request("POST", "/api/v1/agent/answers", { question: params.question });
   }
-  async request(method, path, body) {
+  async request(method, path, body, extraHeaders) {
     const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
       method,
       headers: {
         Authorization: `Bearer ${this.apiKey}`,
-        ...body ? { "Content-Type": "application/json" } : {}
+        ...body ? { "Content-Type": "application/json" } : {},
+        ...extraHeaders
       },
       body: body ? JSON.stringify(body) : void 0
     });
     const text = await res.text();
     const data = text ? JSON.parse(text) : void 0;
     if (!res.ok) {
+      const errorBody = data;
       throw new AgentApiError(
         res.status,
-        data,
-        data?.error ?? `Agent API request failed: ${res.status}`
+        errorBody,
+        errorBody?.error?.message ?? `Agent API request failed: ${res.status}`
       );
     }
     return data;

package/dist/index.d.cts

@@ -22,11 +22,15 @@ interface GetTicketsParams {
     status?: TicketStatus;
     priority?: TicketPriority;
     category?: TicketCategory;
-    /** 1-20, defaults to 10 */
+    /** Max results per page, 1-20, defaults to 10 */
     limit?: number;
+    /** Opaque value from a previous response's `next_cursor`. Omit for the first page. */
+    cursor?: string;
 }
 interface GetTicketsResponse {
     tickets: Ticket[];
+    /** Pass as `cursor` on the next call to keep paging; null once there's nothing left. */
+    next_cursor: string | null;
 }
 interface CreateTicketParams {
     /** The user's question or issue, verbatim. Max 4000 characters. */
@@ -36,6 +40,19 @@ interface CreateTicketParams {
     /** Retrying with the same key returns the original ticket instead of opening a duplicate. */
     idempotencyKey?: string;
 }
+interface CreateTicketResponse {
+    ticket_id: number;
+    /** True if this call matched an existing idempotency key instead of opening a new ticket. */
+    duplicate: boolean;
+}
+interface FaqResult {
+    /** Present only when no FAQ has been generated for the org yet. */
+    message?: string;
+    week_start?: string;
+    week_end?: string;
+    ticket_count?: number;
+    content?: string;
+}
 interface GenerateAnswerParams {
     /** Max 2000 characters. */
     question: string;
@@ -52,10 +69,19 @@ interface SearchKbParams {
     /** 1-20, defaults to 5 */
     limit?: number;
 }
+/**
+ * `code` is only ever present on a 429 — it's how a caller tells apart the
+ * three independent ceilings this API can hit (rate limit vs. either
+ * monthly quota) without pattern-matching `message`. See the `Error` schema
+ * in the OpenAPI spec (lib/agent/openapi-spec.ts) for the source of truth.
+ */
+type AgentApiErrorCode = "rate_limited" | "deflection_limit_reached" | "call_limit_reached";
 /** Shape of the `Error` schema returned on 400/401/403/429 responses. */
 interface AgentApiErrorBody {
-    error: string;
-    [key: string]: unknown;
+    error: {
+        message: string;
+        code?: AgentApiErrorCode;
+    };
 }
 
 interface AgentClientOptions {
@@ -72,6 +98,8 @@ interface AgentClientOptions {
 declare class AgentApiError extends Error {
     readonly status: number;
     readonly body: AgentApiErrorBody | undefined;
+    /** Only ever set on a 429 — see AgentApiErrorCode. */
+    readonly code: AgentApiErrorCode | undefined;
     constructor(status: number, body: AgentApiErrorBody | undefined, message: string);
 }
 declare class AgentClient {
@@ -79,17 +107,23 @@ declare class AgentClient {
     private readonly baseUrl;
     private readonly fetchImpl;
     constructor(options: AgentClientOptions);
-    /** GET /api/agent/kb/search — requires the `kb:read` scope. */
+    /** GET /api/v1/agent/kb/search — requires the `kb:read` scope. */
     searchKb(params: SearchKbParams): Promise<KbSearchResponse>;
-    /** GET /api/agent/faq — requires the `faq:read` scope. */
-    getFaq(): Promise<unknown>;
-    /** GET /api/agent/tickets — requires the `tickets:read` scope. */
+    /** GET /api/v1/agent/faq — requires the `faq:read` scope. */
+    getFaq(): Promise<FaqResult>;
+    /** GET /api/v1/agent/tickets — requires the `tickets:read` scope. */
     getTickets(params?: GetTicketsParams): Promise<GetTicketsResponse>;
-    /** POST /api/agent/tickets — requires the `tickets:write` scope. */
-    createTicket(params: CreateTicketParams): Promise<Ticket>;
-    /** POST /api/agent/answers — requires the `answers:write` scope. */
+    /**
+     * POST /api/v1/agent/tickets — requires the `tickets:write` scope.
+     * `idempotencyKey`, when given, is sent as the standard `Idempotency-Key`
+     * header (what most HTTP clients/SDKs attach automatically) rather than a
+     * body field — the server accepts either, but the header is what it
+     * prefers when both are present.
+     */
+    createTicket(params: CreateTicketParams): Promise<CreateTicketResponse>;
+    /** POST /api/v1/agent/answers — requires the `answers:write` scope. */
     generateAnswer(params: GenerateAnswerParams): Promise<GenerateAnswerResponse>;
     private request;
 }
 
-export { AgentApiError, type AgentApiErrorBody, AgentClient, type AgentClientOptions, type CreateTicketParams, type GenerateAnswerParams, type GenerateAnswerResponse, type GetTicketsParams, type GetTicketsResponse, type KbSearchResponse, type KbSearchResult, type SearchKbParams, type Ticket, type TicketCategory, type TicketPriority, type TicketStatus };
+export { AgentApiError, type AgentApiErrorBody, type AgentApiErrorCode, AgentClient, type AgentClientOptions, type CreateTicketParams, type CreateTicketResponse, type FaqResult, type GenerateAnswerParams, type GenerateAnswerResponse, type GetTicketsParams, type GetTicketsResponse, type KbSearchResponse, type KbSearchResult, type SearchKbParams, type Ticket, type TicketCategory, type TicketPriority, type TicketStatus };

package/dist/index.d.ts

@@ -22,11 +22,15 @@ interface GetTicketsParams {
     status?: TicketStatus;
     priority?: TicketPriority;
     category?: TicketCategory;
-    /** 1-20, defaults to 10 */
+    /** Max results per page, 1-20, defaults to 10 */
     limit?: number;
+    /** Opaque value from a previous response's `next_cursor`. Omit for the first page. */
+    cursor?: string;
 }
 interface GetTicketsResponse {
     tickets: Ticket[];
+    /** Pass as `cursor` on the next call to keep paging; null once there's nothing left. */
+    next_cursor: string | null;
 }
 interface CreateTicketParams {
     /** The user's question or issue, verbatim. Max 4000 characters. */
@@ -36,6 +40,19 @@ interface CreateTicketParams {
     /** Retrying with the same key returns the original ticket instead of opening a duplicate. */
     idempotencyKey?: string;
 }
+interface CreateTicketResponse {
+    ticket_id: number;
+    /** True if this call matched an existing idempotency key instead of opening a new ticket. */
+    duplicate: boolean;
+}
+interface FaqResult {
+    /** Present only when no FAQ has been generated for the org yet. */
+    message?: string;
+    week_start?: string;
+    week_end?: string;
+    ticket_count?: number;
+    content?: string;
+}
 interface GenerateAnswerParams {
     /** Max 2000 characters. */
     question: string;
@@ -52,10 +69,19 @@ interface SearchKbParams {
     /** 1-20, defaults to 5 */
     limit?: number;
 }
+/**
+ * `code` is only ever present on a 429 — it's how a caller tells apart the
+ * three independent ceilings this API can hit (rate limit vs. either
+ * monthly quota) without pattern-matching `message`. See the `Error` schema
+ * in the OpenAPI spec (lib/agent/openapi-spec.ts) for the source of truth.
+ */
+type AgentApiErrorCode = "rate_limited" | "deflection_limit_reached" | "call_limit_reached";
 /** Shape of the `Error` schema returned on 400/401/403/429 responses. */
 interface AgentApiErrorBody {
-    error: string;
-    [key: string]: unknown;
+    error: {
+        message: string;
+        code?: AgentApiErrorCode;
+    };
 }
 
 interface AgentClientOptions {
@@ -72,6 +98,8 @@ interface AgentClientOptions {
 declare class AgentApiError extends Error {
     readonly status: number;
     readonly body: AgentApiErrorBody | undefined;
+    /** Only ever set on a 429 — see AgentApiErrorCode. */
+    readonly code: AgentApiErrorCode | undefined;
     constructor(status: number, body: AgentApiErrorBody | undefined, message: string);
 }
 declare class AgentClient {
@@ -79,17 +107,23 @@ declare class AgentClient {
     private readonly baseUrl;
     private readonly fetchImpl;
     constructor(options: AgentClientOptions);
-    /** GET /api/agent/kb/search — requires the `kb:read` scope. */
+    /** GET /api/v1/agent/kb/search — requires the `kb:read` scope. */
     searchKb(params: SearchKbParams): Promise<KbSearchResponse>;
-    /** GET /api/agent/faq — requires the `faq:read` scope. */
-    getFaq(): Promise<unknown>;
-    /** GET /api/agent/tickets — requires the `tickets:read` scope. */
+    /** GET /api/v1/agent/faq — requires the `faq:read` scope. */
+    getFaq(): Promise<FaqResult>;
+    /** GET /api/v1/agent/tickets — requires the `tickets:read` scope. */
     getTickets(params?: GetTicketsParams): Promise<GetTicketsResponse>;
-    /** POST /api/agent/tickets — requires the `tickets:write` scope. */
-    createTicket(params: CreateTicketParams): Promise<Ticket>;
-    /** POST /api/agent/answers — requires the `answers:write` scope. */
+    /**
+     * POST /api/v1/agent/tickets — requires the `tickets:write` scope.
+     * `idempotencyKey`, when given, is sent as the standard `Idempotency-Key`
+     * header (what most HTTP clients/SDKs attach automatically) rather than a
+     * body field — the server accepts either, but the header is what it
+     * prefers when both are present.
+     */
+    createTicket(params: CreateTicketParams): Promise<CreateTicketResponse>;
+    /** POST /api/v1/agent/answers — requires the `answers:write` scope. */
     generateAnswer(params: GenerateAnswerParams): Promise<GenerateAnswerResponse>;
     private request;
 }
 
-export { AgentApiError, type AgentApiErrorBody, AgentClient, type AgentClientOptions, type CreateTicketParams, type GenerateAnswerParams, type GenerateAnswerResponse, type GetTicketsParams, type GetTicketsResponse, type KbSearchResponse, type KbSearchResult, type SearchKbParams, type Ticket, type TicketCategory, type TicketPriority, type TicketStatus };
+export { AgentApiError, type AgentApiErrorBody, type AgentApiErrorCode, AgentClient, type AgentClientOptions, type CreateTicketParams, type CreateTicketResponse, type FaqResult, type GenerateAnswerParams, type GenerateAnswerResponse, type GetTicketsParams, type GetTicketsResponse, type KbSearchResponse, type KbSearchResult, type SearchKbParams, type Ticket, type TicketCategory, type TicketPriority, type TicketStatus };

package/dist/index.js

@@ -2,11 +2,14 @@
 var AgentApiError = class extends Error {
   status;
   body;
+  /** Only ever set on a 429 — see AgentApiErrorCode. */
+  code;
   constructor(status, body, message) {
     super(message);
     this.name = "AgentApiError";
     this.status = status;
     this.body = body;
+    this.code = body?.error?.code;
   }
 };
 var DEFAULT_BASE_URL = "https://answerloops.com";
@@ -22,54 +25,64 @@ var AgentClient = class {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.fetchImpl = options.fetch ?? fetch;
   }
-  /** GET /api/agent/kb/search — requires the `kb:read` scope. */
+  /** GET /api/v1/agent/kb/search — requires the `kb:read` scope. */
   searchKb(params) {
     const query = new URLSearchParams({ query: params.query });
     if (params.limit !== void 0) query.set("limit", String(params.limit));
-    return this.request("GET", `/api/agent/kb/search?${query}`);
+    return this.request("GET", `/api/v1/agent/kb/search?${query}`);
   }
-  /** GET /api/agent/faq — requires the `faq:read` scope. */
+  /** GET /api/v1/agent/faq — requires the `faq:read` scope. */
   getFaq() {
-    return this.request("GET", "/api/agent/faq");
+    return this.request("GET", "/api/v1/agent/faq");
   }
-  /** GET /api/agent/tickets — requires the `tickets:read` scope. */
+  /** GET /api/v1/agent/tickets — requires the `tickets:read` scope. */
   getTickets(params = {}) {
     const query = new URLSearchParams();
     if (params.status) query.set("status", params.status);
     if (params.priority) query.set("priority", params.priority);
     if (params.category) query.set("category", params.category);
     if (params.limit !== void 0) query.set("limit", String(params.limit));
+    if (params.cursor !== void 0) query.set("cursor", params.cursor);
     const qs = query.toString();
-    return this.request("GET", `/api/agent/tickets${qs ? `?${qs}` : ""}`);
+    return this.request("GET", `/api/v1/agent/tickets${qs ? `?${qs}` : ""}`);
   }
-  /** POST /api/agent/tickets — requires the `tickets:write` scope. */
+  /**
+   * POST /api/v1/agent/tickets — requires the `tickets:write` scope.
+   * `idempotencyKey`, when given, is sent as the standard `Idempotency-Key`
+   * header (what most HTTP clients/SDKs attach automatically) rather than a
+   * body field — the server accepts either, but the header is what it
+   * prefers when both are present.
+   */
   createTicket(params) {
-    return this.request("POST", "/api/agent/tickets", {
-      content: params.content,
-      authorName: params.authorName,
-      idempotencyKey: params.idempotencyKey
-    });
+    return this.request(
+      "POST",
+      "/api/v1/agent/tickets",
+      { content: params.content, authorName: params.authorName },
+      params.idempotencyKey ? { "Idempotency-Key": params.idempotencyKey } : void 0
+    );
   }
-  /** POST /api/agent/answers — requires the `answers:write` scope. */
+  /** POST /api/v1/agent/answers — requires the `answers:write` scope. */
   generateAnswer(params) {
-    return this.request("POST", "/api/agent/answers", { question: params.question });
+    return this.request("POST", "/api/v1/agent/answers", { question: params.question });
   }
-  async request(method, path, body) {
+  async request(method, path, body, extraHeaders) {
     const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
       method,
       headers: {
         Authorization: `Bearer ${this.apiKey}`,
-        ...body ? { "Content-Type": "application/json" } : {}
+        ...body ? { "Content-Type": "application/json" } : {},
+        ...extraHeaders
       },
       body: body ? JSON.stringify(body) : void 0
     });
     const text = await res.text();
     const data = text ? JSON.parse(text) : void 0;
     if (!res.ok) {
+      const errorBody = data;
       throw new AgentApiError(
         res.status,
-        data,
-        data?.error ?? `Agent API request failed: ${res.status}`
+        errorBody,
+        errorBody?.error?.message ?? `Agent API request failed: ${res.status}`
       );
     }
     return data;

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@answerloops/agent-sdk",
-  "version": "0.5.1",
-  "description": "Typed client for the answerLoops Agent API (knowledge base search, FAQ, tickets, grounded answers).",
+  "version": "0.6.2",
+  "description": "Typed client for the answerLoops Agent API (knowledge base search, FAQ, tickets, grounded answers) and a CLI to self-host answerLoops or install its Claude Code skills.",
   "license": "AGPL-3.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "answerloops": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -38,7 +41,7 @@
     "knowledge-base"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/cli/index.ts --format esm,cjs --dts --clean && chmod +x dist/cli/index.js",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {