robotrock 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,60 +1,114 @@
 import {
-  AskHumanExpiredError,
-  AskHumanTimeoutError,
   RobotRock,
   RobotRockError,
+  TaskExpiredError,
+  TaskTimeoutError,
+  attachWebhookToActions,
   createClient,
   resolveRobotRockClient,
   resolveRobotRockConfig,
-  taskContextSchema,
   toDiscriminatedApprovalResult
-} from "./chunk-TUQXDKV6.js";
+} from "./chunk-THVGHUTX.js";
+import {
+  assignToSchema,
+  createTaskBodySchema,
+  taskContextSchema
+} from "./chunk-7FVE6OYZ.js";
 
-// src/ask-human.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));
+// src/webhook.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { z } 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()
+  }),
+  handledBy: z.string().min(1).optional(),
+  handledAt: z.string().min(1),
+  handlerType: z.string().min(1)
+});
+var robotRockWebhookPayloadSchema = robotRockWebhookPayloadBodySchema.extend({
+  headers: z.record(z.string())
+});
+var RobotRockWebhookError = class extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "RobotRockWebhookError";
+  }
+};
+async function verifyRobotRockWebhook(request, options = {}) {
+  const signatureHeaderName = options.signatureHeader ?? ROBOTROCK_SIGNATURE_HEADER;
+  const signature = request.headers.get(signatureHeaderName);
+  const secret = options.secret ?? process.env.ROBOTROCK_WEBHOOK_SECRET;
+  if (!secret) {
+    throw new RobotRockWebhookError(
+      "Missing ROBOTROCK_WEBHOOK_SECRET for webhook verification",
+      "MISSING_WEBHOOK_SECRET"
+    );
+  }
+  if (!signature) {
+    throw new RobotRockWebhookError(
+      `Missing webhook signature header: ${signatureHeaderName}`,
+      "MISSING_SIGNATURE"
+    );
+  }
+  const rawBody = await request.text();
+  assertValidSignature(rawBody, signature, secret);
+  let parsedBody;
+  try {
+    parsedBody = JSON.parse(rawBody);
+  } catch (error) {
+    throw new RobotRockWebhookError("Webhook body is not valid JSON", "INVALID_JSON", {
+      cause: error instanceof Error ? error.message : String(error)
+    });
+  }
+  const payloadResult = robotRockWebhookPayloadBodySchema.safeParse(parsedBody);
+  if (!payloadResult.success) {
+    throw new RobotRockWebhookError(
+      "Webhook payload schema validation failed",
+      "INVALID_PAYLOAD",
+      payloadResult.error.flatten()
+    );
+  }
+  return {
+    ...payloadResult.data,
+    headers: normalizeHeaders(request.headers)
+  };
 }
-async function askHuman(params) {
-  const {
-    task,
-    client: explicitClient,
-    apiKey,
-    baseUrl,
-    pollInterval = DEFAULT_POLL_INTERVAL_MS,
-    timeout = DEFAULT_TIMEOUT_MS,
-    idempotencyKey
-  } = params;
-  const client = resolveRobotRockClient(explicitClient, { apiKey, baseUrl });
-  const response = await client.createTask(
-    task,
-    { idempotencyKey }
-  );
-  const streamId = response.task.streamId;
-  const deadline = Date.now() + timeout;
-  while (Date.now() < deadline) {
-    const existing = await client.getTask(streamId);
-    if (existing?.status === "handled" && existing.handled) {
-      return toDiscriminatedApprovalResult(task.actions, existing, streamId);
-    }
-    if (existing?.status === "expired") {
-      throw new AskHumanExpiredError("Task expired before a human completed it");
-    }
-    await sleep(pollInterval);
+function assertValidSignature(rawBody, signature, secret) {
+  const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+  const expectedBuffer = Buffer.from(expected);
+  const receivedBuffer = Buffer.from(signature);
+  if (expectedBuffer.length !== receivedBuffer.length || !timingSafeEqual(expectedBuffer, receivedBuffer)) {
+    throw new RobotRockWebhookError("Webhook signature verification failed", "INVALID_SIGNATURE");
   }
-  throw new AskHumanTimeoutError(`No human response within ${timeout}ms`);
+}
+function normalizeHeaders(headers) {
+  const result = {};
+  headers.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
 }
 export {
-  AskHumanExpiredError,
-  AskHumanTimeoutError,
   RobotRock,
   RobotRockError,
-  askHuman,
+  RobotRockWebhookError,
+  TaskExpiredError,
+  TaskTimeoutError,
+  assignToSchema,
+  attachWebhookToActions,
   createClient,
+  createTaskBodySchema,
   resolveRobotRockClient,
   resolveRobotRockConfig,
   taskContextSchema,
-  toDiscriminatedApprovalResult
+  toDiscriminatedApprovalResult,
+  verifyRobotRockWebhook
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ask-human.ts"],"sourcesContent":["import {\n  AskHumanExpiredError,\n  AskHumanTimeoutError,\n  toDiscriminatedApprovalResult,\n} from \"./approval-result.js\";\nimport type { RobotRock, RobotRockConfig, CreateTaskOptions } from \"./client.js\";\nimport { resolveRobotRockClient } from \"./env.js\";\nimport type {\n  DiscriminatedApprovalResult,\n  TaskAction,\n  TaskContextInput,\n} from \"@robotrock/core\";\n\nconst DEFAULT_POLL_INTERVAL_MS = 2_000;\nconst DEFAULT_TIMEOUT_MS = 24 * 60 * 60 * 1_000;\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/** Task payload for {@link askHuman}; `actions` must stay a literal tuple for inference. */\nexport type AskHumanTask<A extends readonly TaskAction[]> = Omit<TaskContextInput, \"actions\"> & {\n  readonly actions: A;\n};\n\nexport type AskHumanParams<A extends readonly TaskAction[]> = {\n  task: AskHumanTask<A>;\n  /** Pre-configured client; when omitted, one is created from env / `apiKey` / `baseUrl`. */\n  client?: RobotRock;\n  apiKey?: string;\n  baseUrl?: string;\n  /** Poll interval while waiting for a human (ms). @default 2000 */\n  pollInterval?: number;\n  /** Max wait time (ms). @default 86400000 (24h) */\n  timeout?: number;\n} & Pick<CreateTaskOptions, \"idempotencyKey\">;\n\n/**\n * Create a human-in-the-loop task and block until someone completes it.\n *\n * Uses polling against the RobotRock API. For durable waits inside Trigger.dev,\n * use `robotrock/trigger` instead.\n *\n * The return type is inferred from `task.actions`: `actionId` narrows `data`.\n */\nexport async function askHuman<const A extends readonly TaskAction[]>(\n  params: AskHumanParams<A>\n): Promise<DiscriminatedApprovalResult<A>> {\n  const {\n    task,\n    client: explicitClient,\n    apiKey,\n    baseUrl,\n    pollInterval = DEFAULT_POLL_INTERVAL_MS,\n    timeout = DEFAULT_TIMEOUT_MS,\n    idempotencyKey,\n  } = params;\n\n  const client = resolveRobotRockClient(explicitClient, { apiKey, baseUrl });\n  const response = await client.createTask(\n    task as unknown as TaskContextInput,\n    { idempotencyKey }\n  );\n  const streamId = response.task.streamId;\n  const deadline = Date.now() + timeout;\n\n  while (Date.now() < deadline) {\n    const existing = await client.getTask(streamId);\n\n    if (existing?.status === \"handled\" && existing.handled) {\n      return toDiscriminatedApprovalResult(task.actions, existing, streamId);\n    }\n\n    if (existing?.status === \"expired\") {\n      throw new AskHumanExpiredError(\"Task expired before a human completed it\");\n    }\n\n    await sleep(pollInterval);\n  }\n\n  throw new AskHumanTimeoutError(`No human response within ${timeout}ms`);\n}\n\nexport type { RobotRockConfig };\n"],"mappings":";;;;;;;;;;;;;AAaA,IAAM,2BAA2B;AACjC,IAAM,qBAAqB,KAAK,KAAK,KAAK;AAE1C,SAAS,MAAM,IAA2B;AACxC,SAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AACzD;AA2BA,eAAsB,SACpB,QACyC;AACzC,QAAM;AAAA,IACJ;AAAA,IACA,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,eAAe;AAAA,IACf,UAAU;AAAA,IACV;AAAA,EACF,IAAI;AAEJ,QAAM,SAAS,uBAAuB,gBAAgB,EAAE,QAAQ,QAAQ,CAAC;AACzE,QAAM,WAAW,MAAM,OAAO;AAAA,IAC5B;AAAA,IACA,EAAE,eAAe;AAAA,EACnB;AACA,QAAM,WAAW,SAAS,KAAK;AAC/B,QAAM,WAAW,KAAK,IAAI,IAAI;AAE9B,SAAO,KAAK,IAAI,IAAI,UAAU;AAC5B,UAAM,WAAW,MAAM,OAAO,QAAQ,QAAQ;AAE9C,QAAI,UAAU,WAAW,aAAa,SAAS,SAAS;AACtD,aAAO,8BAA8B,KAAK,SAAS,UAAU,QAAQ;AAAA,IACvE;AAEA,QAAI,UAAU,WAAW,WAAW;AAClC,YAAM,IAAI,qBAAqB,0CAA0C;AAAA,IAC3E;AAEA,UAAM,MAAM,YAAY;AAAA,EAC1B;AAEA,QAAM,IAAI,qBAAqB,4BAA4B,OAAO,IAAI;AACxE;","names":[]}
+{"version":3,"sources":["../src/webhook.ts"],"sourcesContent":["import { createHmac, timingSafeEqual } from \"node:crypto\";\nimport { z } from \"zod\";\n\nconst ROBOTROCK_SIGNATURE_HEADER = \"x-robotrock-signature\";\n\nconst robotRockWebhookPayloadBodySchema = z.object({\n  taskId: z.string().min(1),\n  action: z.object({\n    id: z.string().min(1),\n    title: z.string().min(1),\n    data: z.unknown(),\n  }),\n  handledBy: z.string().min(1).optional(),\n  handledAt: z.string().min(1),\n  handlerType: z.string().min(1),\n});\n\nconst robotRockWebhookPayloadSchema = robotRockWebhookPayloadBodySchema.extend({\n  headers: z.record(z.string()),\n});\n\nexport type RobotRockWebhookErrorCode =\n  | \"MISSING_WEBHOOK_SECRET\"\n  | \"MISSING_SIGNATURE\"\n  | \"INVALID_SIGNATURE\"\n  | \"INVALID_JSON\"\n  | \"INVALID_PAYLOAD\";\n\nexport class RobotRockWebhookError extends Error {\n  constructor(\n    message: string,\n    public readonly code: RobotRockWebhookErrorCode,\n    public readonly details?: unknown\n  ) {\n    super(message);\n    this.name = \"RobotRockWebhookError\";\n  }\n}\n\nexport type RobotRockWebhookPayload = z.infer<typeof robotRockWebhookPayloadSchema>;\n\nexport interface VerifyRobotRockWebhookOptions {\n  /**\n   * Override shared secret (defaults to ROBOTROCK_WEBHOOK_SECRET).\n   * Keep undefined in production to enforce the canonical env var.\n   */\n  secret?: string;\n  /** Signature header to read. @default \"x-robotrock-signature\" */\n  signatureHeader?: string;\n}\n\n/**\n * Verify a RobotRock webhook request and return a validated payload.\n * Throws RobotRockWebhookError with machine-readable `code` for audit logging.\n */\nexport async function verifyRobotRockWebhook(\n  request: Request,\n  options: VerifyRobotRockWebhookOptions = {}\n): Promise<RobotRockWebhookPayload> {\n  const signatureHeaderName = options.signatureHeader ?? ROBOTROCK_SIGNATURE_HEADER;\n  const signature = request.headers.get(signatureHeaderName);\n  const secret = options.secret ?? process.env.ROBOTROCK_WEBHOOK_SECRET;\n\n  if (!secret) {\n    throw new RobotRockWebhookError(\n      \"Missing ROBOTROCK_WEBHOOK_SECRET for webhook verification\",\n      \"MISSING_WEBHOOK_SECRET\"\n    );\n  }\n\n  if (!signature) {\n    throw new RobotRockWebhookError(\n      `Missing webhook signature header: ${signatureHeaderName}`,\n      \"MISSING_SIGNATURE\"\n    );\n  }\n\n  const rawBody = await request.text();\n  assertValidSignature(rawBody, signature, secret);\n\n  let parsedBody: unknown;\n  try {\n    parsedBody = JSON.parse(rawBody);\n  } catch (error) {\n    throw new RobotRockWebhookError(\"Webhook body is not valid JSON\", \"INVALID_JSON\", {\n      cause: error instanceof Error ? error.message : String(error),\n    });\n  }\n\n  const payloadResult = robotRockWebhookPayloadBodySchema.safeParse(parsedBody);\n  if (!payloadResult.success) {\n    throw new RobotRockWebhookError(\n      \"Webhook payload schema validation failed\",\n      \"INVALID_PAYLOAD\",\n      payloadResult.error.flatten()\n    );\n  }\n\n  return {\n    ...payloadResult.data,\n    headers: normalizeHeaders(request.headers),\n  };\n}\n\nfunction assertValidSignature(rawBody: string, signature: string, secret: string): void {\n  const expected = `sha256=${createHmac(\"sha256\", secret).update(rawBody).digest(\"hex\")}`;\n  const expectedBuffer = Buffer.from(expected);\n  const receivedBuffer = Buffer.from(signature);\n\n  if (\n    expectedBuffer.length !== receivedBuffer.length ||\n    !timingSafeEqual(expectedBuffer, receivedBuffer)\n  ) {\n    throw new RobotRockWebhookError(\"Webhook signature verification failed\", \"INVALID_SIGNATURE\");\n  }\n}\n\nfunction normalizeHeaders(headers: Headers): Record<string, string> {\n  const result: Record<string, string> = {};\n  headers.forEach((value, key) => {\n    result[key] = value;\n  });\n  return result;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA,SAAS,YAAY,uBAAuB;AAC5C,SAAS,SAAS;AAElB,IAAM,6BAA6B;AAEnC,IAAM,oCAAoC,EAAE,OAAO;AAAA,EACjD,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACxB,QAAQ,EAAE,OAAO;AAAA,IACf,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IACpB,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IACvB,MAAM,EAAE,QAAQ;AAAA,EAClB,CAAC;AAAA,EACD,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,EACtC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EAC3B,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC;AAC/B,CAAC;AAED,IAAM,gCAAgC,kCAAkC,OAAO;AAAA,EAC7E,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC;AAC9B,CAAC;AASM,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC/C,YACE,SACgB,MACA,SAChB;AACA,UAAM,OAAO;AAHG;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;AAkBA,eAAsB,uBACpB,SACA,UAAyC,CAAC,GACR;AAClC,QAAM,sBAAsB,QAAQ,mBAAmB;AACvD,QAAM,YAAY,QAAQ,QAAQ,IAAI,mBAAmB;AACzD,QAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI;AAE7C,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,WAAW;AACd,UAAM,IAAI;AAAA,MACR,qCAAqC,mBAAmB;AAAA,MACxD;AAAA,IACF;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,QAAQ,KAAK;AACnC,uBAAqB,SAAS,WAAW,MAAM;AAE/C,MAAI;AACJ,MAAI;AACF,iBAAa,KAAK,MAAM,OAAO;AAAA,EACjC,SAAS,OAAO;AACd,UAAM,IAAI,sBAAsB,kCAAkC,gBAAgB;AAAA,MAChF,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAC9D,CAAC;AAAA,EACH;AAEA,QAAM,gBAAgB,kCAAkC,UAAU,UAAU;AAC5E,MAAI,CAAC,cAAc,SAAS;AAC1B,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,MACA,cAAc,MAAM,QAAQ;AAAA,IAC9B;AAAA,EACF;AAEA,SAAO;AAAA,IACL,GAAG,cAAc;AAAA,IACjB,SAAS,iBAAiB,QAAQ,OAAO;AAAA,EAC3C;AACF;AAEA,SAAS,qBAAqB,SAAiB,WAAmB,QAAsB;AACtF,QAAM,WAAW,UAAU,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK,CAAC;AACrF,QAAM,iBAAiB,OAAO,KAAK,QAAQ;AAC3C,QAAM,iBAAiB,OAAO,KAAK,SAAS;AAE5C,MACE,eAAe,WAAW,eAAe,UACzC,CAAC,gBAAgB,gBAAgB,cAAc,GAC/C;AACA,UAAM,IAAI,sBAAsB,yCAAyC,mBAAmB;AAAA,EAC9F;AACF;AAEA,SAAS,iBAAiB,SAA0C;AAClE,QAAM,SAAiC,CAAC;AACxC,UAAQ,QAAQ,CAAC,OAAO,QAAQ;AAC9B,WAAO,GAAG,IAAI;AAAA,EAChB,CAAC;AACD,SAAO;AACT;","names":[]}