robotrock 0.1.0 → 0.2.0

package/README.md

@@ -10,77 +10,234 @@ npm install robotrock
 bun add robotrock
 ```
 
+## Agent skill (Cursor, Claude Code, etc.)
+
+Install the RobotRock agent skill from [skills.sh](https://skills.sh/quintenb/robotrock-skills/robotrock) to teach coding agents how to integrate the SDK:
+
+```bash
+npx skills add quintenb/robotrock-skills --skill robotrock
+```
+
 For Trigger.dev, also install `@trigger.dev/sdk`.
 
 ## Quick Start
 
+Create a shared client in its own module (for example `lib/robotrock.ts`), then import it wherever you create tasks.
+
 ```typescript
-import { RobotRock, askHuman } from "robotrock";
+// lib/robotrock.ts
+import { createClient } from "robotrock";
+
+export const robotrock = createClient({
+  app: "budgeting-service",
+  webhook: {
+    url: "https://your-app.com/api/robotrock/webhook",
+    headers: {
+      // place your headers here
+    },
+  },
+});
+```
 
-// Or create a client explicitly
-const client = new RobotRock({ apiKey: process.env.ROBOTROCK_API_KEY! });
+```typescript
+import { robotrock } from "./lib/robotrock";
 
-const response = await client.createTask({
+const response = await robotrock.sendToHuman({
   type: "budget-approval",
   name: "Q1 Budget Approval",
+  description: "Please review and approve the Q1 budget",
   actions: [
     { id: "approve", title: "Approve" },
     { id: "reject", title: "Reject" },
   ],
+  idempotencyKey: "budget-q1-approval-v1",
 });
+
+console.log("Task created:", response.task.taskId);
 ```
 
-## Block until a human responds
+Set `ROBOTROCK_API_KEY` in your environment (create a named key in the RobotRock dashboard under Settings → API Keys). The client reads it when you omit `apiKey` on `createClient`.
+
+## Inbox routing
+
+Set `app` on `createClient` to control dashboard inbox grouping for every task from that client.
+
+When `app` is omitted on the client, the API uses your API key **name** as the inbox bucket.
+
+## Client webhook
+
+Configure a single webhook on the client. It is applied to every action when you call `sendToHuman`:
 
 ```typescript
-import { askHuman } from "robotrock";
-
-const result = await askHuman({
-  task: {
-    type: "approval",
-    name: "Review change",
-    actions: [
-      { id: "approve", title: "Approve" },
-      { id: "reject", title: "Reject" },
-    ] as const,
+export const robotrock = createClient({
+  webhook: {
+    url: "https://your-app.com/api/robotrock/webhook",
+    headers: {
+      // place your headers here
+    }, // optional, defaults to {}
   },
 });
 ```
 
-Uses `ROBOTROCK_API_KEY` from the environment when no `client` is passed.
+## Automatic fallback polling
+
+When the client has no `webhook`, `sendToHuman` polls until a human handles the task or throws `TaskExpiredError` / `TaskTimeoutError`. Configure `polling` on `createClient` (not on `sendToHuman`). Polling stops at the earlier of `polling.timeoutMs` and the task's `validUntil`. You cannot set both `webhook` and `polling` on the same client.
+
+```typescript
+import { createClient, TaskExpiredError, TaskTimeoutError } from "robotrock";
+
+const robotrock = createClient({
+  app: "my-service",
+  polling: {
+    intervalMs: 2_000,
+    timeoutMs: 5 * 60 * 1_000,
+  },
+});
+
+const actions = [
+  {
+    id: "approve",
+    title: "Approve",
+    schema: {
+      type: "object",
+      required: ["ticket"],
+      properties: {
+        ticket: { type: "string" },
+      },
+    },
+  },
+  {
+    id: "reject",
+    title: "Reject",
+    schema: {
+      type: "object",
+      required: ["reason"],
+      properties: {
+        reason: { type: "string" },
+      },
+    },
+  },
+] as const;
+
+const result = await robotrock.sendToHuman({
+  type: "approval",
+  name: "Review change",
+  actions,
+});
+
+if (result.mode === "created") {
+  console.log("Task created:", result.task.taskId);
+} else if (result.actionId === "approve") {
+  console.log("Approved with ticket", result.data.ticket);
+} else {
+  console.log("Rejected because", result.data.reason);
+}
+```
+
+## Other client methods
+
+```typescript
+await robotrock.getTask("task_...");
+await robotrock.cancelTask("task_...");
+```
+
+## Webhook verification helper
+
+```typescript
+import {
+  verifyRobotRockWebhook,
+  RobotRockWebhookError,
+  type RobotRockWebhookPayload,
+} from "robotrock";
+
+export async function POST(request: Request) {
+  try {
+    const payload: RobotRockWebhookPayload = await verifyRobotRockWebhook(request);
+    console.log(payload.action.id, payload.headers["x-request-id"]);
+    return Response.json({ ok: true });
+  } catch (error) {
+    if (error instanceof RobotRockWebhookError) {
+      return Response.json({ error: error.code }, { status: 401 });
+    }
+    return Response.json({ error: "Unknown error" }, { status: 500 });
+  }
+}
+```
 
 ## Trigger.dev
 
+Install `@trigger.dev/sdk`, re-export SDK tasks from your `trigger/` directory, and call them with `triggerAndWait()`:
+
+```typescript
+// trigger/robotrock.ts
+export { sendToHumanTask, approveByHumanTask } from "robotrock/trigger";
+```
+
 ```typescript
-import { task } from "@trigger.dev/sdk/v3";
-import { askHuman } from "robotrock/trigger";
+import { task } from "@trigger.dev/sdk";
+import { approveByHumanTask } from "./robotrock";
 
-export const deploymentApproval = task({
-  id: "deployment-approval",
+export const gate = task({
+  id: "gate",
   run: async () => {
-    const result = await askHuman({
-      task: {
-        type: "deployment",
-        name: "Deploy to production",
-        actions: [
-          { id: "approve", title: "Deploy" },
-          { id: "reject", title: "Cancel" },
-        ],
-      },
-      timeout: "1h",
+    const waitResult = await approveByHumanTask.triggerAndWait({
+      type: "release-gate",
+      name: "Ship this release?",
     });
 
-    return result.actionId === "approve";
+    if (!waitResult.ok) {
+      throw waitResult.error;
+    }
+
+    return waitResult.output.actionId === "approve";
+  },
+});
+```
+
+Set `ROBOTROCK_API_KEY` (and optionally `ROBOTROCK_APP`) in your Trigger worker environment.
+
+## Vercel AI SDK
+
+Install `ai` and use the optional `robotrock/ai` entry:
+
+```bash
+npm install ai
+```
+
+```typescript
+import { generateText, stepCountIs } from "ai";
+import { createClient } from "robotrock";
+import { approveByHumanTool, createSendToHumanTool } from "robotrock/ai";
+
+const robotrock = createClient({
+  app: "my-agent",
+  polling: { timeoutMs: 30 * 60_000 },
+});
+
+const result = await generateText({
+  model: "anthropic/claude-sonnet-4",
+  tools: {
+    approveByHuman: approveByHumanTool(robotrock),
   },
+  stopWhen: stepCountIs(10),
+  prompt: "Plan a release; get human approval before finalizing.",
 });
 ```
 
+For AI SDK tool execution approval (approve `deleteFile` before it runs), use `createRobotRockToolApproval`, `resolveToolApprovalsViaRobotRock`, and `runWithRobotRockApprovals` from `robotrock/ai`. See the [Vercel AI integration docs](https://github.com/robotrock/robotrock/blob/main/apps/docs/content/docs/integrations/vercel-ai.mdx) in this repo.
+
+Run long polls inside Trigger.dev or a worker — not short serverless HTTP handlers.
+
 ## Exports
 
 | Import | Description |
 |--------|-------------|
-| `robotrock` | Client, `askHuman` (poll), types, schemas |
-| `robotrock/trigger` | `askHuman` via Trigger waitpoint tokens |
+| `robotrock` | `createClient`, `RobotRock`, env helpers, types, schemas |
+| `robotrock/trigger` | `sendToHumanTask`, `approveByHumanTask` for Trigger.dev |
+| `robotrock/workflow` | `sendToHumanInWorkflow`, `approveByHumanInWorkflow` for Vercel Workflow |
+| `robotrock/ai` | Vercel AI SDK tools and `toolApproval` bridge (peer: `ai`) |
+| `robotrock/ai/trigger` | Same API, documented for `mode: "trigger"` in Trigger.dev workers |
+| `robotrock/ai/workflow` | Same API, documented for `mode: "workflow"` in Vercel Workflow |
 
 ## License
 

package/dist/ai/index.d.ts

@@ -0,0 +1,24 @@
+import { R as RobotRockToolCallInfo, F as FormatToolApprovalTaskOptions, H as HumanToolResult } from '../workflow-CHWiRPU9.js';
+export { A as APPROVE_BY_HUMAN_ACTIONS, d as ApproveByHumanToolDurableOptions, c as ApproveByHumanToolOptions, r as CreateRobotRockAiToolsOptions, f as CreateSendToHumanToolDurableOptions, C as CreateSendToHumanToolOptions, B as ResolveToolApprovalsOptions, i as RobotRockAiContext, j as RobotRockAiMode, k as RobotRockAiPollingContext, l as RobotRockAiTriggerContext, m as RobotRockAiWorkflowContext, D as RobotRockToolApprovalConfig, z as RobotRockToolApprovalDecision, E as RunWithRobotRockApprovalsOptions, T as ToolApprovalRequestPart, t as applyRobotRockToolApprovalToTools, g as approveByHumanForAi, b as approveByHumanInputSchema, a as approveByHumanTool, u as collectApprovalRequests, o as createRobotRockAiTools, p as createRobotRockAiTriggerContext, q as createRobotRockAiWorkflowContext, v as createRobotRockNeedsApproval, w as createRobotRockToolApproval, e as createSendToHumanTool, n as normalizeRobotRockAiContext, x as resolveToolApprovalsViaRobotRock, y as runWithRobotRockApprovals, h as sendToHumanForAi, s as sendToHumanToolInputSchema } from '../workflow-CHWiRPU9.js';
+import { a as SendToHumanInput } from '../client-agOgTJob.js';
+import { DiscriminatedApprovalResult } from '../schemas/index.js';
+import 'ai';
+import 'zod';
+
+declare const DEFAULT_APPROVE_ACTIONS: readonly [{
+    readonly id: "approve";
+    readonly title: "Approve execution";
+}, {
+    readonly id: "deny";
+    readonly title: "Deny";
+}];
+/**
+ * Build a RobotRock task payload for an AI SDK tool approval request.
+ */
+declare function defaultFormatToolApprovalTask(toolCall: RobotRockToolCallInfo, options?: FormatToolApprovalTaskOptions): SendToHumanInput;
+
+declare function toHumanToolResult(result: DiscriminatedApprovalResult<readonly {
+    id: string;
+}[]>): HumanToolResult;
+
+export { DEFAULT_APPROVE_ACTIONS, FormatToolApprovalTaskOptions, HumanToolResult, RobotRockToolCallInfo, defaultFormatToolApprovalTask, toHumanToolResult };

package/dist/ai/index.js

@@ -0,0 +1,46 @@
+import {
+  APPROVE_BY_HUMAN_ACTIONS,
+  DEFAULT_APPROVE_ACTIONS,
+  applyRobotRockToolApprovalToTools,
+  approveByHumanForAi,
+  approveByHumanInputSchema,
+  approveByHumanTool,
+  collectApprovalRequests,
+  createRobotRockAiTools,
+  createRobotRockAiTriggerContext,
+  createRobotRockAiWorkflowContext,
+  createRobotRockNeedsApproval,
+  createRobotRockToolApproval,
+  createSendToHumanTool,
+  defaultFormatToolApprovalTask,
+  normalizeRobotRockAiContext,
+  resolveToolApprovalsViaRobotRock,
+  runWithRobotRockApprovals,
+  sendToHumanForAi,
+  sendToHumanToolInputSchema,
+  toHumanToolResult
+} from "../chunk-OJ57M3RW.js";
+import "../chunk-7FVE6OYZ.js";
+export {
+  APPROVE_BY_HUMAN_ACTIONS,
+  DEFAULT_APPROVE_ACTIONS,
+  applyRobotRockToolApprovalToTools,
+  approveByHumanForAi,
+  approveByHumanInputSchema,
+  approveByHumanTool,
+  collectApprovalRequests,
+  createRobotRockAiTools,
+  createRobotRockAiTriggerContext,
+  createRobotRockAiWorkflowContext,
+  createRobotRockNeedsApproval,
+  createRobotRockToolApproval,
+  createSendToHumanTool,
+  defaultFormatToolApprovalTask,
+  normalizeRobotRockAiContext,
+  resolveToolApprovalsViaRobotRock,
+  runWithRobotRockApprovals,
+  sendToHumanForAi,
+  sendToHumanToolInputSchema,
+  toHumanToolResult
+};
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/ai/trigger.d.ts

@@ -0,0 +1,5 @@
+export { i as RobotRockAiContext, j as RobotRockAiMode, k as RobotRockAiPollingContext, l as RobotRockAiTriggerContext, t as applyRobotRockToolApprovalToTools, a as approveByHumanTool, o as createRobotRockAiTools, p as createRobotRockAiTriggerContext, v as createRobotRockNeedsApproval, w as createRobotRockToolApproval, e as createSendToHumanTool, x as resolveToolApprovalsViaRobotRock, y as runWithRobotRockApprovals } from '../workflow-CHWiRPU9.js';
+import 'ai';
+import 'zod';
+import '../client-agOgTJob.js';
+import '../schemas/index.js';

package/dist/ai/trigger.js

@@ -0,0 +1,24 @@
+import {
+  applyRobotRockToolApprovalToTools,
+  approveByHumanTool,
+  createRobotRockAiTools,
+  createRobotRockAiTriggerContext,
+  createRobotRockNeedsApproval,
+  createRobotRockToolApproval,
+  createSendToHumanTool,
+  resolveToolApprovalsViaRobotRock,
+  runWithRobotRockApprovals
+} from "../chunk-OJ57M3RW.js";
+import "../chunk-7FVE6OYZ.js";
+export {
+  applyRobotRockToolApprovalToTools,
+  approveByHumanTool,
+  createRobotRockAiTools,
+  createRobotRockAiTriggerContext,
+  createRobotRockNeedsApproval,
+  createRobotRockToolApproval,
+  createSendToHumanTool,
+  resolveToolApprovalsViaRobotRock,
+  runWithRobotRockApprovals
+};
+//# sourceMappingURL=trigger.js.map

package/dist/ai/trigger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/ai/workflow.d.ts

@@ -0,0 +1,5 @@
+export { i as RobotRockAiContext, j as RobotRockAiMode, k as RobotRockAiPollingContext, l as RobotRockAiTriggerContext, m as RobotRockAiWorkflowContext, t as applyRobotRockToolApprovalToTools, a as approveByHumanTool, o as createRobotRockAiTools, q as createRobotRockAiWorkflowContext, v as createRobotRockNeedsApproval, w as createRobotRockToolApproval, e as createSendToHumanTool, x as resolveToolApprovalsViaRobotRock, y as runWithRobotRockApprovals } from '../workflow-CHWiRPU9.js';
+import 'ai';
+import 'zod';
+import '../client-agOgTJob.js';
+import '../schemas/index.js';

package/dist/ai/workflow.js

@@ -0,0 +1,24 @@
+import {
+  applyRobotRockToolApprovalToTools,
+  approveByHumanTool,
+  createRobotRockAiTools,
+  createRobotRockAiWorkflowContext,
+  createRobotRockNeedsApproval,
+  createRobotRockToolApproval,
+  createSendToHumanTool,
+  resolveToolApprovalsViaRobotRock,
+  runWithRobotRockApprovals
+} from "../chunk-OJ57M3RW.js";
+import "../chunk-7FVE6OYZ.js";
+export {
+  applyRobotRockToolApprovalToTools,
+  approveByHumanTool,
+  createRobotRockAiTools,
+  createRobotRockAiWorkflowContext,
+  createRobotRockNeedsApproval,
+  createRobotRockToolApproval,
+  createSendToHumanTool,
+  resolveToolApprovalsViaRobotRock,
+  runWithRobotRockApprovals
+};
+//# sourceMappingURL=workflow.js.map

package/dist/ai/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-7FVE6OYZ.js

@@ -0,0 +1,124 @@
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (async) dispose = value[__knownSymbol("asyncDispose")];
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+      if (async) inner = dispose;
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  } else if (async) {
+    stack.push([async]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
+
+// src/schemas/index.ts
+import { z } from "zod";
+var safeUrlSchema = z.string().refine((url) => url.startsWith("http://") || url.startsWith("https://"), {
+  message: "URL must start with http:// or https://"
+});
+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())
+});
+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.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.unknown()).optional(),
+  items: z.lazy(() => z.record(uiFieldSchemaSchema)).optional()
+}).passthrough();
+var contextUiSchema = z.record(uiFieldSchemaSchema).optional();
+var contextDataSchema = z.object({
+  data: z.record(z.unknown()),
+  ui: contextUiSchema
+}).optional();
+var taskContextSchema = 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")
+});
+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 createTaskBodySchema = taskContextSchema.extend({
+  assignTo: assignToSchema.optional()
+});
+
+export {
+  __using,
+  __callDispose,
+  taskContextSchema,
+  assignToSchema,
+  createTaskBodySchema
+};
+//# sourceMappingURL=chunk-7FVE6OYZ.js.map

package/dist/chunk-7FVE6OYZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schemas/index.ts"],"sourcesContent":["import { z } from \"zod\";\n\nexport interface JSONSchema7 {\n  $id?: string;\n  $ref?: string;\n  $schema?: string;\n  $comment?: string;\n  type?: JSONSchema7TypeName | JSONSchema7TypeName[];\n  enum?: unknown[];\n  const?: unknown;\n  multipleOf?: number;\n  maximum?: number;\n  exclusiveMaximum?: number;\n  minimum?: number;\n  exclusiveMinimum?: number;\n  maxLength?: number;\n  minLength?: number;\n  pattern?: string;\n  format?: string;\n  items?: JSONSchema7 | JSONSchema7[];\n  additionalItems?: JSONSchema7 | boolean;\n  maxItems?: number;\n  minItems?: number;\n  uniqueItems?: boolean;\n  contains?: JSONSchema7;\n  maxProperties?: number;\n  minProperties?: number;\n  required?: string[];\n  properties?: Record<string, JSONSchema7>;\n  patternProperties?: Record<string, JSONSchema7>;\n  additionalProperties?: JSONSchema7 | boolean;\n  dependencies?: Record<string, JSONSchema7 | string[]>;\n  propertyNames?: JSONSchema7;\n  if?: JSONSchema7;\n  then?: JSONSchema7;\n  else?: JSONSchema7;\n  allOf?: JSONSchema7[];\n  anyOf?: JSONSchema7[];\n  oneOf?: JSONSchema7[];\n  not?: JSONSchema7;\n  title?: string;\n  description?: string;\n  default?: unknown;\n  readOnly?: boolean;\n  writeOnly?: boolean;\n  examples?: unknown[];\n}\n\nexport type JSONSchema7TypeName =\n  | \"string\"\n  | \"number\"\n  | \"integer\"\n  | \"boolean\"\n  | \"object\"\n  | \"array\"\n  | \"null\";\n\nexport type ExtendedJSONSchema7 = JSONSchema7 & {\n  enumNames?: string[];\n  [key: string]: unknown;\n};\n\nexport type UiSchema = {\n  \"ui:widget\"?: string;\n  \"ui:title\"?: string;\n  \"ui:description\"?: string;\n  \"ui:placeholder\"?: string;\n  \"ui:options\"?: Record<string, unknown>;\n  [key: string]: unknown;\n};\n\nconst safeUrlSchema = z\n  .string()\n  .refine((url) => url.startsWith(\"http://\") || url.startsWith(\"https://\"), {\n    message: \"URL must start with http:// or https://\",\n  });\n\nconst jsonSchema7Schema = z.custom<ExtendedJSONSchema7>(\n  (val) => typeof val === \"object\" && val !== null,\n  { message: \"Must be a valid JSON Schema object\" }\n);\n\nconst uiSchemaSchema = z.custom<UiSchema>((val) => typeof val === \"object\" && val !== null, {\n  message: \"Must be a valid UiSchema object\",\n});\n\nconst webhookHandlerSchema = z.object({\n  type: z.literal(\"webhook\"),\n  url: safeUrlSchema,\n  headers: z.record(z.string()),\n});\n\nconst triggerHandlerSchema = webhookHandlerSchema.extend({\n  type: z.literal(\"trigger\"),\n  tokenId: z.string().min(1),\n});\n\nconst handlerSchema = z.discriminatedUnion(\"type\", [webhookHandlerSchema, triggerHandlerSchema]);\n\nconst taskActionSchema = z.object({\n  id: z.string().min(1),\n  title: z.string().min(1),\n  description: z.string().optional(),\n  schema: jsonSchema7Schema.optional(),\n  ui: uiSchemaSchema.optional(),\n  data: z.record(z.unknown()).optional(),\n  handlers: z.array(handlerSchema).min(1).optional(),\n});\n\nconst uiFieldSchemaSchema: z.ZodType<Record<string, unknown>> = z\n  .object({\n    \"ui:widget\": z.string().optional(),\n    \"ui:title\": z.string().optional(),\n    \"ui:description\": z.string().optional(),\n    \"ui:options\": z.record(z.unknown()).optional(),\n    items: z.lazy(() => z.record(uiFieldSchemaSchema)).optional(),\n  })\n  .passthrough();\n\nconst contextUiSchema = z.record(uiFieldSchemaSchema).optional();\n\nconst contextDataSchema = z\n  .object({\n    data: z.record(z.unknown()),\n    ui: contextUiSchema,\n  })\n  .optional();\n\nexport const taskContextSchema = z.object({\n  app: z.string().min(1).optional(),\n  type: z.string().min(1),\n  name: z.string().min(1),\n  description: z.string().optional(),\n  validUntil: z.string().optional(),\n  context: contextDataSchema,\n  version: z.literal(2).optional(),\n  actions: z.array(taskActionSchema).min(1, \"At least one action is required\"),\n});\n\n/** Assignment targets at task create (not stored in task context JSON). */\nexport const assignToSchema = z\n  .object({\n    users: z.array(z.string().email()).optional(),\n    groups: z.array(z.string().min(1)).optional(),\n  })\n  .refine(\n    (data) => {\n      const groups = data.groups ?? [];\n      if (groups.includes(\"all\") && groups.length > 1) {\n        return false;\n      }\n      return true;\n    },\n    { message: 'Cannot combine \"all\" with other group slugs' }\n  );\n\nexport const createTaskBodySchema = taskContextSchema.extend({\n  assignTo: assignToSchema.optional(),\n});\n\nexport type AssignToInput = z.infer<typeof assignToSchema>;\nexport type CreateTaskBodyInput = z.input<typeof createTaskBodySchema>;\nexport type CreateTaskBody = z.output<typeof createTaskBodySchema>;\nexport type TaskContextInput = z.input<typeof taskContextSchema>;\nexport type TaskContextOutput = z.output<typeof taskContextSchema>;\nexport type TaskContext = TaskContextOutput;\nexport type TaskAction = z.infer<typeof taskActionSchema>;\nexport type WebhookHandler = z.infer<typeof webhookHandlerSchema>;\nexport type TriggerHandler = z.infer<typeof triggerHandlerSchema>;\nexport type Handler = z.infer<typeof handlerSchema>;\n\ntype InferObjectProperties<\n  Props,\n  Req extends PropertyKey,\n> = Props extends Record<string, unknown>\n  ? ({\n      [K in keyof Props as K extends Req ? K : never]-?: InferJsonSchema7<Props[K]>;\n    } & {\n      [K in keyof Props as K extends Req ? never : K]?: InferJsonSchema7<Props[K]>;\n    } extends infer O\n      ? { [K in keyof O]: O[K] }\n      : never)\n  : Record<string, unknown>;\n\ntype RequiredKeys<S> =\n  S extends { readonly required: readonly string[] } ? S[\"required\"][number] : never;\n\nexport type InferJsonSchema7<S> = [S] extends [undefined]\n  ? Record<string, never>\n  : S extends { readonly const: infer C }\n    ? C\n    : S extends {\n          readonly enum: readonly (infer E)[];\n        }\n      ? E\n      : S extends {\n            readonly type: \"object\";\n            readonly properties?: infer Props;\n          }\n        ? InferObjectProperties<Props, RequiredKeys<S>>\n        : S extends {\n              readonly type: \"object\";\n              readonly properties?: undefined;\n            }\n          ? Record<string, unknown>\n          : S extends {\n                readonly type: \"array\";\n                readonly items?: infer Items;\n              }\n            ? Items extends readonly unknown[]\n              ? InferJsonSchema7<Items[number]>[]\n              : Items extends object\n                ? InferJsonSchema7<Items>[]\n                : unknown[]\n            : S extends { readonly type: \"string\" }\n              ? string\n              : S extends { readonly type: \"number\" } | { readonly type: \"integer\" }\n                ? number\n                : S extends { readonly type: \"boolean\" }\n                  ? boolean\n                  : unknown;\n\nexport type TaskStatus = \"pending\" | \"open\" | \"handled\" | \"expired\";\n\nexport interface TaskResponse {\n  success: boolean;\n  task: {\n    taskId: string;\n    status: \"pending\" | \"open\";\n    context: TaskContext;\n    validUntil: string;\n    submittedAt: string;\n  };\n  message: string;\n}\n\nexport interface Task {\n  id: string;\n  createdAt: Date;\n  status: TaskStatus;\n  context: TaskContext;\n  validUntil: number;\n  handledAt?: number;\n  handled?: {\n    action: {\n      id: string;\n      data: unknown;\n    };\n    handledBy?: string;\n    userId?: string;\n    token?: string;\n  };\n}\n\nexport type InferActionData<T extends { schema?: unknown }> = [\n  Exclude<T[\"schema\"], undefined>,\n] extends [\n  never,\n]\n  ? Record<string, never>\n  : Exclude<T[\"schema\"], undefined> extends infer S\n    ? InferJsonSchema7<S>\n    : Record<string, never>;\n\nexport type TupleElementIndices<T extends readonly unknown[]> = T extends readonly [\n  unknown,\n  ...unknown[],\n]\n  ? Exclude<keyof T, keyof unknown[]>\n  : number;\n\nexport interface TaskResult<T = Record<string, unknown>> {\n  actionId: string;\n  data: T;\n  handledBy?: string;\n  handledAt: Date;\n}\n\nexport interface ApprovalResult<T = Record<string, unknown>> extends TaskResult<T> {\n  taskId: string;\n}\n\nexport type DiscriminatedApprovalResult<\n  TActions extends readonly { id: string; schema?: unknown }[],\n> = {\n  [I in TupleElementIndices<TActions>]: TActions[I] extends { id: string; schema?: unknown }\n    ? Omit<ApprovalResult<InferActionData<TActions[I]>>, \"actionId\" | \"data\"> & {\n        actionId: TActions[I][\"id\"];\n        data: InferActionData<TActions[I]>;\n      }\n    : never\n}[TupleElementIndices<TActions>];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,SAAS,SAAS;AAuElB,IAAM,gBAAgB,EACnB,OAAO,EACP,OAAO,CAAC,QAAQ,IAAI,WAAW,SAAS,KAAK,IAAI,WAAW,UAAU,GAAG;AAAA,EACxE,SAAS;AACX,CAAC;AAEH,IAAM,oBAAoB,EAAE;AAAA,EAC1B,CAAC,QAAQ,OAAO,QAAQ,YAAY,QAAQ;AAAA,EAC5C,EAAE,SAAS,qCAAqC;AAClD;AAEA,IAAM,iBAAiB,EAAE,OAAiB,CAAC,QAAQ,OAAO,QAAQ,YAAY,QAAQ,MAAM;AAAA,EAC1F,SAAS;AACX,CAAC;AAED,IAAM,uBAAuB,EAAE,OAAO;AAAA,EACpC,MAAM,EAAE,QAAQ,SAAS;AAAA,EACzB,KAAK;AAAA,EACL,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC;AAC9B,CAAC;AAED,IAAM,uBAAuB,qBAAqB,OAAO;AAAA,EACvD,MAAM,EAAE,QAAQ,SAAS;AAAA,EACzB,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC;AAC3B,CAAC;AAED,IAAM,gBAAgB,EAAE,mBAAmB,QAAQ,CAAC,sBAAsB,oBAAoB,CAAC;AAE/F,IAAM,mBAAmB,EAAE,OAAO;AAAA,EAChC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACpB,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACvB,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,EACjC,QAAQ,kBAAkB,SAAS;AAAA,EACnC,IAAI,eAAe,SAAS;AAAA,EAC5B,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;AAAA,EACrC,UAAU,EAAE,MAAM,aAAa,EAAE,IAAI,CAAC,EAAE,SAAS;AACnD,CAAC;AAED,IAAM,sBAA0D,EAC7D,OAAO;AAAA,EACN,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,EACjC,YAAY,EAAE,OAAO,EAAE,SAAS;AAAA,EAChC,kBAAkB,EAAE,OAAO,EAAE,SAAS;AAAA,EACtC,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;AAAA,EAC7C,OAAO,EAAE,KAAK,MAAM,EAAE,OAAO,mBAAmB,CAAC,EAAE,SAAS;AAC9D,CAAC,EACA,YAAY;AAEf,IAAM,kBAAkB,EAAE,OAAO,mBAAmB,EAAE,SAAS;AAE/D,IAAM,oBAAoB,EACvB,OAAO;AAAA,EACN,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;AAAA,EAC1B,IAAI;AACN,CAAC,EACA,SAAS;AAEL,IAAM,oBAAoB,EAAE,OAAO;AAAA,EACxC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,EAChC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACtB,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACtB,aAAa,EAAE,OAAO,EAAE,SAAS;AAAA,EACjC,YAAY,EAAE,OAAO,EAAE,SAAS;AAAA,EAChC,SAAS;AAAA,EACT,SAAS,EAAE,QAAQ,CAAC,EAAE,SAAS;AAAA,EAC/B,SAAS,EAAE,MAAM,gBAAgB,EAAE,IAAI,GAAG,iCAAiC;AAC7E,CAAC;AAGM,IAAM,iBAAiB,EAC3B,OAAO;AAAA,EACN,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,SAAS;AAAA,EAC5C,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,EAAE,SAAS;AAC9C,CAAC,EACA;AAAA,EACC,CAAC,SAAS;AACR,UAAM,SAAS,KAAK,UAAU,CAAC;AAC/B,QAAI,OAAO,SAAS,KAAK,KAAK,OAAO,SAAS,GAAG;AAC/C,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AAAA,EACA,EAAE,SAAS,8CAA8C;AAC3D;AAEK,IAAM,uBAAuB,kBAAkB,OAAO;AAAA,EAC3D,UAAU,eAAe,SAAS;AACpC,CAAC;","names":[]}

package/dist/chunk-D2FBSEZK.js

@@ -0,0 +1,67 @@
+// src/handler-webhook.ts
+function isRobotRockHandlerWebhookPayload(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value;
+  if (typeof v.taskId !== "string" || typeof v.handledAt !== "string") {
+    return false;
+  }
+  const action = v.action;
+  if (typeof action !== "object" || action === null) {
+    return false;
+  }
+  const a = action;
+  return typeof a.id === "string" && "data" in a;
+}
+
+// src/wait-timing.ts
+var DEFAULT_WAIT_DURATION_MS = 7 * 24 * 60 * 60 * 1e3;
+function resolveWaitTiming(validUntilInput) {
+  const validUntilMs = validUntilInput !== void 0 ? parseValidUntilMs(validUntilInput) : Date.now() + DEFAULT_WAIT_DURATION_MS;
+  const durationMs = validUntilMs - Date.now();
+  if (durationMs <= 0) {
+    throw new Error("validUntil must be in the future");
+  }
+  return {
+    validUntil: validUntilInput ?? new Date(validUntilMs),
+    timeout: durationMsToTimeout(durationMs)
+  };
+}
+function parseValidUntilMs(value) {
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) {
+      throw new Error("Invalid validUntil: Date is invalid");
+    }
+    return ms;
+  }
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) {
+    throw new Error("Invalid validUntil: expected a parseable date string");
+  }
+  return parsed;
+}
+function durationMsToTimeout(durationMs) {
+  const seconds = Math.ceil(durationMs / 1e3);
+  if (seconds <= 0) {
+    throw new Error("validUntil must be in the future");
+  }
+  if (seconds >= 86400) {
+    return `${Math.ceil(seconds / 86400)}d`;
+  }
+  if (seconds >= 3600) {
+    return `${Math.ceil(seconds / 3600)}h`;
+  }
+  if (seconds >= 60) {
+    return `${Math.ceil(seconds / 60)}m`;
+  }
+  return `${seconds}s`;
+}
+
+export {
+  isRobotRockHandlerWebhookPayload,
+  resolveWaitTiming,
+  parseValidUntilMs
+};
+//# sourceMappingURL=chunk-D2FBSEZK.js.map

package/dist/chunk-D2FBSEZK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/handler-webhook.ts","../src/wait-timing.ts"],"sourcesContent":["/**\n * JSON body posted when a RobotRock action handler runs (webhook or Trigger wait token).\n */\nexport interface RobotRockHandlerWebhookPayload {\n  taskId: string;\n  action: {\n    id: string;\n    title: string;\n    data: unknown;\n  };\n  handledBy?: string;\n  handledAt: string;\n  handlerType: string;\n}\n\nexport function isRobotRockHandlerWebhookPayload(\n  value: unknown\n): value is RobotRockHandlerWebhookPayload {\n  if (typeof value !== \"object\" || value === null) {\n    return false;\n  }\n  const v = value as Record<string, unknown>;\n  if (typeof v.taskId !== \"string\" || typeof v.handledAt !== \"string\") {\n    return false;\n  }\n  const action = v.action;\n  if (typeof action !== \"object\" || action === null) {\n    return false;\n  }\n  const a = action as Record<string, unknown>;\n  return typeof a.id === \"string\" && \"data\" in a;\n}\n","/** Default wait when `validUntil` is omitted. */\nexport const DEFAULT_WAIT_DURATION_MS = 7 * 24 * 60 * 60 * 1000;\n\nexport function resolveWaitTiming(validUntilInput?: Date | string): {\n  validUntil: Date | string;\n  timeout: string;\n} {\n  const validUntilMs =\n    validUntilInput !== undefined\n      ? parseValidUntilMs(validUntilInput)\n      : Date.now() + DEFAULT_WAIT_DURATION_MS;\n\n  const durationMs = validUntilMs - Date.now();\n  if (durationMs <= 0) {\n    throw new Error(\"validUntil must be in the future\");\n  }\n\n  return {\n    validUntil: validUntilInput ?? new Date(validUntilMs),\n    timeout: durationMsToTimeout(durationMs),\n  };\n}\n\nexport function parseValidUntilMs(value: Date | string): number {\n  if (value instanceof Date) {\n    const ms = value.getTime();\n    if (Number.isNaN(ms)) {\n      throw new Error(\"Invalid validUntil: Date is invalid\");\n    }\n    return ms;\n  }\n\n  const parsed = Date.parse(value);\n  if (Number.isNaN(parsed)) {\n    throw new Error(\"Invalid validUntil: expected a parseable date string\");\n  }\n\n  return parsed;\n}\n\n/** Duration string for Trigger.dev `wait.createToken` and Workflow `sleep`. */\nexport function durationMsToTimeout(durationMs: number): string {\n  const seconds = Math.ceil(durationMs / 1000);\n  if (seconds <= 0) {\n    throw new Error(\"validUntil must be in the future\");\n  }\n\n  if (seconds >= 86_400) {\n    return `${Math.ceil(seconds / 86_400)}d`;\n  }\n  if (seconds >= 3_600) {\n    return `${Math.ceil(seconds / 3_600)}h`;\n  }\n  if (seconds >= 60) {\n    return `${Math.ceil(seconds / 60)}m`;\n  }\n\n  return `${seconds}s`;\n}\n"],"mappings":";AAeO,SAAS,iCACd,OACyC;AACzC,MAAI,OAAO,UAAU,YAAY,UAAU,MAAM;AAC/C,WAAO;AAAA,EACT;AACA,QAAM,IAAI;AACV,MAAI,OAAO,EAAE,WAAW,YAAY,OAAO,EAAE,cAAc,UAAU;AACnE,WAAO;AAAA,EACT;AACA,QAAM,SAAS,EAAE;AACjB,MAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AACjD,WAAO;AAAA,EACT;AACA,QAAM,IAAI;AACV,SAAO,OAAO,EAAE,OAAO,YAAY,UAAU;AAC/C;;;AC9BO,IAAM,2BAA2B,IAAI,KAAK,KAAK,KAAK;AAEpD,SAAS,kBAAkB,iBAGhC;AACA,QAAM,eACJ,oBAAoB,SAChB,kBAAkB,eAAe,IACjC,KAAK,IAAI,IAAI;AAEnB,QAAM,aAAa,eAAe,KAAK,IAAI;AAC3C,MAAI,cAAc,GAAG;AACnB,UAAM,IAAI,MAAM,kCAAkC;AAAA,EACpD;AAEA,SAAO;AAAA,IACL,YAAY,mBAAmB,IAAI,KAAK,YAAY;AAAA,IACpD,SAAS,oBAAoB,UAAU;AAAA,EACzC;AACF;AAEO,SAAS,kBAAkB,OAA8B;AAC9D,MAAI,iBAAiB,MAAM;AACzB,UAAM,KAAK,MAAM,QAAQ;AACzB,QAAI,OAAO,MAAM,EAAE,GAAG;AACpB,YAAM,IAAI,MAAM,qCAAqC;AAAA,IACvD;AACA,WAAO;AAAA,EACT;AAEA,QAAM,SAAS,KAAK,MAAM,KAAK;AAC/B,MAAI,OAAO,MAAM,MAAM,GAAG;AACxB,UAAM,IAAI,MAAM,sDAAsD;AAAA,EACxE;AAEA,SAAO;AACT;AAGO,SAAS,oBAAoB,YAA4B;AAC9D,QAAM,UAAU,KAAK,KAAK,aAAa,GAAI;AAC3C,MAAI,WAAW,GAAG;AAChB,UAAM,IAAI,MAAM,kCAAkC;AAAA,EACpD;AAEA,MAAI,WAAW,OAAQ;AACrB,WAAO,GAAG,KAAK,KAAK,UAAU,KAAM,CAAC;AAAA,EACvC;AACA,MAAI,WAAW,MAAO;AACpB,WAAO,GAAG,KAAK,KAAK,UAAU,IAAK,CAAC;AAAA,EACtC;AACA,MAAI,WAAW,IAAI;AACjB,WAAO,GAAG,KAAK,KAAK,UAAU,EAAE,CAAC;AAAA,EACnC;AAEA,SAAO,GAAG,OAAO;AACnB;","names":[]}