robotrock 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,47 +1,533 @@
+// src/schemas/index.ts
+import { z } from "zod";
 import {
-  RobotRock,
-  RobotRockError,
-  TaskExpiredError,
-  TaskTimeoutError,
-  attachWebhookToActions,
-  createClient,
-  resolveRobotRockClient,
-  resolveRobotRockConfig,
-  toDiscriminatedApprovalResult
-} from "./chunk-ZCMXX7IG.js";
-import {
-  DEFAULT_TASK_PRIORITY,
-  DEFAULT_THREAD_UPDATE_STATUS,
-  LOWEST_TASK_PRIORITY,
-  TASK_PRIORITY_RANK,
-  assignToSchema,
-  createTaskBodySchema,
-  taskContextSchema,
-  taskPriorities,
-  taskPrioritySchema,
-  threadUpdateBodySchema,
-  threadUpdateInputSchema,
-  threadUpdateStatusSchema,
-  threadUpdateStatuses
-} from "./chunk-TAWMIQAM.js";
+  isPublicHttpUrl,
+  PUBLIC_HTTP_URL_ERROR
+} from "@robotrock/core/utils";
+import { validateContextPublicUrls } from "@robotrock/core/schemas";
+var safeUrlSchema = z.string().refine((url) => isPublicHttpUrl(url), {
+  message: PUBLIC_HTTP_URL_ERROR
+});
+var jsonSchema7Schema = z.custom(
+  (val) => typeof val === "object" && val !== null,
+  { message: "Must be a valid JSON Schema object" }
+);
+var uiSchemaSchema = z.custom((val) => typeof val === "object" && val !== null, {
+  message: "Must be a valid UiSchema object"
+});
+var webhookHandlerSchema = z.object({
+  type: z.literal("webhook"),
+  url: safeUrlSchema,
+  headers: z.record(z.string(), z.string())
+});
+var triggerHandlerSchema = webhookHandlerSchema.extend({
+  type: z.literal("trigger"),
+  tokenId: z.string().min(1)
+});
+var handlerSchema = z.discriminatedUnion("type", [webhookHandlerSchema, triggerHandlerSchema]);
+var taskActionSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  schema: jsonSchema7Schema.optional(),
+  ui: uiSchemaSchema.optional(),
+  data: z.record(z.string(), z.unknown()).optional(),
+  handlers: z.array(handlerSchema).min(1).optional()
+});
+var uiFieldSchemaSchema = z.object({
+  "ui:widget": z.string().optional(),
+  "ui:title": z.string().optional(),
+  "ui:description": z.string().optional(),
+  "ui:options": z.record(z.string(), z.unknown()).optional(),
+  items: z.lazy(() => z.record(z.string(), uiFieldSchemaSchema)).optional()
+}).passthrough();
+var contextUiSchema = z.record(z.string(), uiFieldSchemaSchema).optional();
+var contextDataSchema = z.object({
+  data: z.record(z.string(), z.unknown()),
+  ui: contextUiSchema
+}).optional();
+var taskContextObjectSchema = z.object({
+  app: z.string().min(1).optional(),
+  type: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  validUntil: z.string().optional(),
+  context: contextDataSchema,
+  version: z.literal(2).optional(),
+  actions: z.array(taskActionSchema).min(1, "At least one action is required")
+});
+function refineContextPublicUrls(data, ctx) {
+  const error = validateContextPublicUrls(data.context);
+  if (error) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: error,
+      path: ["context"]
+    });
+  }
+}
+var taskContextSchema = taskContextObjectSchema.superRefine(
+  refineContextPublicUrls
+);
+var assignToSchema = z.object({
+  users: z.array(z.string().email()).optional(),
+  groups: z.array(z.string().min(1)).optional()
+}).refine(
+  (data) => {
+    const groups = data.groups ?? [];
+    if (groups.includes("all") && groups.length > 1) {
+      return false;
+    }
+    return true;
+  },
+  { message: 'Cannot combine "all" with other group slugs' }
+);
+var threadUpdateMessageSchema = z.string().min(1).max(500);
+var threadUpdateStatuses = [
+  "info",
+  "queued",
+  "running",
+  "waiting",
+  "succeeded",
+  "failed",
+  "cancelled"
+];
+var threadUpdateStatusSchema = z.enum(threadUpdateStatuses);
+var DEFAULT_THREAD_UPDATE_STATUS = "info";
+var threadUpdateInputSchema = z.object({
+  message: threadUpdateMessageSchema,
+  status: threadUpdateStatusSchema.optional()
+});
+var taskPriorities = ["low", "normal", "high", "urgent"];
+var taskPrioritySchema = z.enum(taskPriorities);
+var DEFAULT_TASK_PRIORITY = "normal";
+var LOWEST_TASK_PRIORITY = "low";
+var TASK_PRIORITY_RANK = {
+  low: 1,
+  normal: 2,
+  high: 3,
+  urgent: 4
+};
+var nonNegativeInt = z.number().int().nonnegative();
+var agentCostTokensSchema = z.object({
+  input: nonNegativeInt.optional(),
+  output: nonNegativeInt.optional(),
+  total: nonNegativeInt.optional()
+});
+var agentCostSchema = z.object({
+  tokens: agentCostTokensSchema.optional(),
+  eur: z.number().nonnegative().optional(),
+  usd: z.number().nonnegative().optional()
+});
+var AGENT_INFO_MAX_KEYS = 32;
+var agentTelemetrySchema = z.object({
+  version: z.string().min(1).optional(),
+  toolCallCount: nonNegativeInt.optional(),
+  cost: agentCostSchema.optional(),
+  info: z.record(z.string(), z.unknown()).optional()
+}).refine(
+  (data) => {
+    const keys = data.info ? Object.keys(data.info) : [];
+    return keys.length <= AGENT_INFO_MAX_KEYS;
+  },
+  { message: `agent.info may contain at most ${AGENT_INFO_MAX_KEYS} keys` }
+);
+var createTaskBodySchema = taskContextObjectSchema.extend({
+  assignTo: assignToSchema.optional(),
+  /**
+   * Groups related tasks together. When omitted, the server generates one and
+   * returns it so the caller can reuse it on later tasks in the same thread.
+   */
+  threadId: z.string().min(1).optional(),
+  /**
+   * Optional thread priority. When set, applies to the whole thread and
+   * overwrites any previous priority. Omit on later tasks to leave unchanged.
+   */
+  priority: taskPrioritySchema.optional(),
+  /**
+   * Optional initial status update logged against the task's thread. Shows in
+   * the inbox status bar and the thread update log.
+   */
+  update: threadUpdateInputSchema.optional(),
+  agent: agentTelemetrySchema.optional()
+}).superRefine(refineContextPublicUrls);
+var threadUpdateBodySchema = threadUpdateInputSchema;
+
+// src/approval-result.ts
+var TaskTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TaskTimeoutError";
+  }
+};
+var TaskExpiredError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TaskExpiredError";
+  }
+};
+function toDiscriminatedApprovalResult(actions, task) {
+  void actions;
+  if (!task.handled) {
+    throw new Error("Task has no handled result");
+  }
+  return {
+    actionId: task.handled.action.id,
+    data: task.handled.action.data,
+    handledBy: task.handled.handledBy,
+    handledAt: new Date(task.handledAt ?? Date.now()),
+    taskId: task.id
+  };
+}
+
+// src/client.ts
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var DEFAULT_TIMEOUT_MS = 24 * 60 * 60 * 1e3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseValidUntilMs(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    return Number.isNaN(ms) ? void 0 : ms;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : void 0;
+  }
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? void 0 : parsed;
+}
+function serializeValidUntil(value) {
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) {
+      throw new RobotRockError("Invalid validUntil: Date is invalid", 400);
+    }
+    return value.toISOString();
+  }
+  if (typeof value === "string" && !Number.isNaN(Date.parse(value))) {
+    return new Date(value).toISOString();
+  }
+  throw new RobotRockError("Invalid validUntil: expected a Date or parseable date string", 400);
+}
+var RobotRockError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "RobotRockError";
+  }
+};
+var RobotRock = class {
+  apiKey;
+  baseUrl;
+  app;
+  version;
+  webhook;
+  polling;
+  constructor(config) {
+    if (config.webhook && config.polling) {
+      throw new Error(
+        "RobotRock client cannot configure both webhook and polling. Use webhook for callbacks or polling to block until handled."
+      );
+    }
+    const apiKey = config.apiKey ?? process.env.ROBOTROCK_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "RobotRock API key is required. Set ROBOTROCK_API_KEY or pass apiKey when creating the client."
+      );
+    }
+    this.apiKey = apiKey;
+    const rawBase = config.baseUrl ?? "https://api.robotrock.io/v1";
+    this.baseUrl = rawBase.replace(/\/+$/, "");
+    this.app = config.app;
+    this.version = config.version ?? 2;
+    this.webhook = config.webhook;
+    this.polling = config.polling ?? {};
+  }
+  /**
+   * Create a task via POST /v1 without waiting for a human response.
+   */
+  async createTask(task) {
+    const normalizedTask = normalizeSendToHumanInput(task, {
+      webhook: this.webhook,
+      app: this.app,
+      version: this.version
+    });
+    const bodyPayload = {
+      ...normalizedTask,
+      ...task.assignTo !== void 0 ? { assignTo: task.assignTo } : {},
+      ...task.threadId !== void 0 ? { threadId: task.threadId } : {},
+      ...task.priority !== void 0 ? { priority: task.priority } : {},
+      ...task.update !== void 0 ? { update: task.update } : {},
+      ...task.agent !== void 0 ? { agent: task.agent } : {}
+    };
+    const validation = createTaskBodySchema.safeParse(bodyPayload);
+    if (!validation.success) {
+      throw new RobotRockError(
+        `Invalid task: ${validation.error.issues[0]?.message}`,
+        400,
+        validation.error.issues
+      );
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Api-Key": this.apiKey
+    };
+    if (task.idempotencyKey) {
+      headers["Idempotency-Key"] = task.idempotencyKey;
+    }
+    const response = await fetch(`${this.baseUrl}/`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(validation.data)
+    });
+    const data = await parseResponseBody(response);
+    if (!response.ok) {
+      throw new RobotRockError(
+        getErrorMessage(data, "Failed to create task"),
+        response.status,
+        data
+      );
+    }
+    return data.task;
+  }
+  async sendToHuman(task) {
+    const normalizedTask = normalizeSendToHumanInput(task, {
+      webhook: this.webhook,
+      app: this.app,
+      version: this.version
+    });
+    const createdTaskTask = await this.createTask(task);
+    const hasHandlers = normalizedTask.actions.some(
+      (action) => Array.isArray(action.handlers) && action.handlers.length > 0
+    );
+    if (hasHandlers) {
+      return {
+        mode: "created",
+        task: createdTaskTask
+      };
+    }
+    const timeoutMs = this.polling.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollIntervalMs = this.polling.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const pollingDeadline = Date.now() + timeoutMs;
+    const validUntilMs = parseValidUntilMs(createdTaskTask.validUntil);
+    const deadline = validUntilMs !== void 0 ? Math.min(pollingDeadline, validUntilMs) : pollingDeadline;
+    const taskId = createdTaskTask.taskId;
+    while (Date.now() < deadline) {
+      const existing = await this.getTask(taskId);
+      if (existing?.status === "handled" && existing.handled) {
+        return {
+          mode: "handled",
+          task: createdTaskTask,
+          ...toDiscriminatedApprovalResult(
+            normalizedTask.actions,
+            existing
+          )
+        };
+      }
+      if (existing?.status === "expired" || existing && Date.now() >= existing.validUntil) {
+        throw new TaskExpiredError("Task reached validUntil before a human completed it");
+      }
+      const remainingMs = deadline - Date.now();
+      await sleep(Math.min(pollIntervalMs, Math.max(0, remainingMs)));
+    }
+    if (validUntilMs !== void 0 && Date.now() >= validUntilMs) {
+      throw new TaskExpiredError("Task reached validUntil before a human completed it");
+    }
+    throw new TaskTimeoutError(`No human response within ${timeoutMs}ms`);
+  }
+  /**
+   * Get a task by public task id (returned as `task.taskId` from {@link sendToHuman}).
+   */
+  async getTask(taskId) {
+    const response = await fetch(`${this.baseUrl}/tasks/${taskId}`, {
+      method: "GET",
+      headers: {
+        "X-Api-Key": this.apiKey
+      }
+    });
+    if (response.status === 404) {
+      return null;
+    }
+    const data = await parseResponseBody(response);
+    if (!response.ok) {
+      throw new RobotRockError(
+        getErrorMessage(data, "Failed to get task"),
+        response.status,
+        data
+      );
+    }
+    return data;
+  }
+  /**
+   * Log a status update against a thread. The update shows in the inbox status
+   * bar and thread update log for every task in the thread.
+   */
+  async sendUpdate({ threadId, message, status }) {
+    if (!threadId) {
+      throw new RobotRockError("threadId is required to send an update", 400);
+    }
+    const validation = threadUpdateBodySchema.safeParse({ message, status });
+    if (!validation.success) {
+      throw new RobotRockError(
+        `Invalid update: ${validation.error.issues[0]?.message}`,
+        400,
+        validation.error.issues
+      );
+    }
+    const response = await fetch(
+      `${this.baseUrl}/threads/${encodeURIComponent(threadId)}/updates`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Api-Key": this.apiKey
+        },
+        body: JSON.stringify(validation.data)
+      }
+    );
+    const data = await parseResponseBody(response);
+    if (!response.ok) {
+      throw new RobotRockError(
+        getErrorMessage(data, "Failed to send update"),
+        response.status,
+        data
+      );
+    }
+    return data.update;
+  }
+  async cancelTask(taskId) {
+    const response = await fetch(`${this.baseUrl}/tasks/${taskId}/cancel`, {
+      method: "POST",
+      headers: {
+        "X-Api-Key": this.apiKey
+      }
+    });
+    if (!response.ok) {
+      const data = await parseResponseBody(response);
+      throw new RobotRockError(
+        getErrorMessage(data, "Failed to cancel task"),
+        response.status,
+        data
+      );
+    }
+  }
+};
+function createClient(config) {
+  return new RobotRock(config);
+}
+function attachWebhookToActions(actions, webhook) {
+  return actions.map((action) => ({
+    ...action,
+    handlers: webhookToHandlers(webhook)
+  }));
+}
+function webhookToHandlers(webhook) {
+  return [
+    {
+      type: "webhook",
+      url: webhook.url,
+      headers: webhook.headers ?? {}
+    }
+  ];
+}
+function normalizeSendToHumanInput(task, clientDefaults) {
+  const {
+    actions,
+    idempotencyKey: _idempotencyKey,
+    assignTo: _assignTo,
+    threadId: _threadId,
+    priority: _priority,
+    update: _update,
+    validUntil,
+    app: taskApp,
+    ...rest
+  } = task;
+  const webhook = clientDefaults.webhook;
+  const normalizedActions = webhook ? attachWebhookToActions(actions, webhook) : actions;
+  const app = taskApp ?? clientDefaults.app;
+  return {
+    ...rest,
+    version: clientDefaults.version,
+    ...app ? { app } : {},
+    ...validUntil !== void 0 ? { validUntil: serializeValidUntil(validUntil) } : {},
+    actions: normalizedActions
+  };
+}
+async function parseResponseBody(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  const bodyText = await response.text();
+  if (!bodyText) {
+    return null;
+  }
+  if (contentType.toLowerCase().includes("application/json")) {
+    try {
+      return JSON.parse(bodyText);
+    } catch {
+    }
+  }
+  try {
+    return JSON.parse(bodyText);
+  } catch {
+    return bodyText;
+  }
+}
+function getErrorMessage(data, fallback) {
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const maybeMessage = data.message;
+    if (typeof maybeMessage === "string" && maybeMessage.trim()) {
+      return maybeMessage;
+    }
+  }
+  if (typeof data === "string" && data.trim()) {
+    const compact = data.replace(/\s+/g, " ").trim();
+    const snippet = compact.length > 180 ? `${compact.slice(0, 180)}...` : compact;
+    return `${fallback}. Server returned non-JSON response: ${snippet}`;
+  }
+  return fallback;
+}
+
+// src/env.ts
+var DEFAULT_BASE_URL = "https://api.robotrock.io/v1";
+function resolveRobotRockConfig(overrides) {
+  const apiKey = overrides?.apiKey ?? process.env.ROBOTROCK_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "RobotRock API key is required. Set ROBOTROCK_API_KEY or pass apiKey when creating the client."
+    );
+  }
+  const baseUrl = overrides?.baseUrl ?? process.env.ROBOTROCK_BASE_URL ?? process.env.ROBOTROCK_API_URL ?? DEFAULT_BASE_URL;
+  const app = overrides?.app ?? process.env.ROBOTROCK_APP;
+  return app ? { apiKey, baseUrl, app } : { apiKey, baseUrl };
+}
+function resolveRobotRockClient(client, configOverrides) {
+  if (client) {
+    return client;
+  }
+  return createClient(resolveRobotRockConfig(configOverrides));
+}
 
 // src/webhook.ts
 import { createHmac, timingSafeEqual } from "crypto";
-import { z } from "zod";
+import { z as z2 } from "zod";
 var ROBOTROCK_SIGNATURE_HEADER = "x-robotrock-signature";
-var robotRockWebhookPayloadBodySchema = z.object({
-  taskId: z.string().min(1),
-  action: z.object({
-    id: z.string().min(1),
-    title: z.string().min(1),
-    data: z.unknown()
+var robotRockWebhookPayloadBodySchema = z2.object({
+  taskId: z2.string().min(1),
+  action: z2.object({
+    id: z2.string().min(1),
+    title: z2.string().min(1),
+    data: z2.unknown()
   }),
-  handledBy: z.string().min(1).optional(),
-  handledAt: z.string().min(1),
-  handlerType: z.string().min(1)
+  handledBy: z2.string().min(1).optional(),
+  handledAt: z2.string().min(1),
+  handlerType: z2.string().min(1)
 });
 var robotRockWebhookPayloadSchema = robotRockWebhookPayloadBodySchema.extend({
-  headers: z.record(z.string())
+  headers: z2.record(z2.string(), z2.string())
 });
 var RobotRockWebhookError = class extends Error {
   constructor(message, code, details) {
@@ -140,6 +626,9 @@ export {
   TASK_PRIORITY_RANK,
   TaskExpiredError,
   TaskTimeoutError,
+  agentCostSchema,
+  agentCostTokensSchema,
+  agentTelemetrySchema,
   assignToSchema,
   attachWebhookToActions,
   createClient,