Feat/public api

.cspell.json

@@ -16,6 +16,7 @@
   "useGitignore": true,
   "language": "en",
   "words": [
+    "workerd",
     "dataurl",
     "devpool",
     "knip",

.github/knip.ts

@@ -6,7 +6,7 @@ const config: KnipConfig = {
   ignore: ["src/types/config.ts", "**/__mocks__/**", "**/__fixtures__/**", "src/worker.ts", "dist/**"],
   ignoreExportsUsedInFile: true,
   // eslint can also be safely ignored as per the docs: https://knip.dev/guides/handling-issues#eslint--jest
-  ignoreDependencies: ["eslint-config-prettier", "eslint-plugin-prettier", "ts-node", "@octokit/rest"],
+  ignoreDependencies: ["eslint-config-prettier", "eslint-plugin-prettier", "ts-node"],
   eslint: true,
 };
 

README.md

@@ -9,7 +9,9 @@ This plugin allows a hunter to begin a task as well as gracefully stop a task wi
 - Built as a UbiquityOS plugin using TypeScript
 - Reads wallet addresses for users
 - Implements a webhook-based event system for GitHub interactions
+- Provides a REST API for programmatic access to task operations
 - Runs as a Cloudflare Worker using Hono for HTTP handling
+- Supports JWT authentication and rate limiting for API access
 
 ### Core Components
 
@@ -59,6 +61,16 @@ Two main commands with complex validation:
 - Wallet verification when required
 - Review authority validation
 
+#### 6. Public API
+
+The plugin exposes a REST API for external integrations:
+
+- **Authentication**: JWT-based authentication using Supabase tokens
+- **Rate Limiting**: Per-user limits using Cloudflare KV or Deno KV storage
+- **CORS Support**: Configurable cross-origin resource sharing
+- **Dual Modes**: Validate-only (GET) and execute (POST) operations
+- **Error Handling**: Structured JSON responses with detailed error messages
+
 ## Usage
 
 ### Start a task
@@ -69,7 +81,9 @@ To start a task, a hunter should use the `/start` command. This will assign them
 - The issue is not already assigned
 - The hunter has not reached the maximum number of concurrent tasks
 - The command is not disabled at the repository or organization level
-- The contributor meets any configured account age and XP requirements
+- The contributor's GitHub account meets the minimum age requirement (default: 365.25 days)
+- The contributor has sufficient XP for the task's priority level (if configured)
+- The contributor has set their wallet address (if required)
 
 ### Stop a task
 
@@ -79,6 +93,120 @@ To stop a task, a hunter should use the `/stop` command. This will unassign them
 - The command is not disabled at the repository or organization level
 - The command is called on the issue, not the associated pull request
 
+## Public API
+
+The plugin provides a REST API endpoint for programmatic access to task eligibility checking and assignment functionality. This allows external applications to integrate with the start/stop workflow.
+
+### Endpoint
+
+**Base URL**: `/start`
+
+### Authentication
+
+All API requests require JWT authentication via the `Authorization` header:
+
+```
+Authorization: Bearer <jwt_token>
+```
+
+The JWT token should be obtained from Supabase authentication.
+
+### Response
+
+**Example Response:**
+
+```json
+{
+  ok: boolean;
+  errors: LogReturn[] | null;
+  warnings: LogReturn[] | null;
+  computed: {
+    deadline: string | null;
+    isTaskStale: boolean | null;
+    wallet: string | null;
+    toAssign: string[];
+    assignedIssues: AssignedIssue[];
+    consideredCount: number;
+    senderRole: ReturnType<typeof getTransformedRole>;
+  };
+};
+```
+
+### Methods
+
+#### GET `/start` (Validate Mode)
+
+Validates task eligibility without performing assignment.
+
+**Query Parameters:**
+
+- `userId` (required): GitHub user ID (numeric)
+- `issueUrl` (required): Full GitHub issue URL
+
+**Example Request:**
+
+```bash
+GET /start?userId=123456&issueUrl=https://github.com/owner/repo/issues/1
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...
+```
+
+#### POST `/start` (Execute Mode)
+
+Validates eligibility and performs task assignment.
+
+**Request Body:**
+
+```json
+{
+  "userId": 123456,
+  "issueUrl": "https://github.com/owner/repo/issues/1"
+}
+```
+
+**Example Request:**
+
+```bash
+POST /start
+Content-Type: application/json
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...
+
+{
+  "userId": 123456,
+  "issueUrl": "https://github.com/owner/repo/issues/1"
+}
+```
+
+### Rate Limiting
+
+- **Validate mode (GET)**: 10 requests per minute per user
+- **Execute mode (POST)**: 3 requests per minute per user
+
+Rate limited responses include:
+
+```json
+{
+  "ok": false,
+  "reasons": ["RateLimit: exceeded"],
+  "resetAt": 1703123456789
+}
+```
+
+### CORS Support
+
+The API supports CORS for cross-origin requests. Configure allowed origins via the `PUBLIC_API_ALLOWED_ORIGINS` environment variable.
+
+### Development and Testing Notes
+
+Contributors working on this API are likely to also be working on `work.ubq.fi`. If so, they should set up their own `devpool-directory` and integrate it properly. Otherwise, the system will attempt to create an Octokit instance through their GitHub app (kernel app) using ubiquity/partner issues, which will fail since the app is not installed on those repositories.
+
+To successfully QA this API as a contributor:
+
+- Only use `issueUrl` parameters that belong to repositories where your GitHub app is installed
+- This can be achieved by hardcoding URLs on the client side or when creating request payloads
+- Use repositories within your own organizations or test repositories where the app has been properly installed
+
+Failure to use properly accessible repositories will result in `repoOctokit` instantiation failures. While this doesn't block functionality in development environments (as long as appropriate workarounds are implemented), it prevents proper testing of the full integration workflow.
+
 ### [Configuration](./src/types/plugin-input.ts)
 
 #### Note: The command name is `"start"` when configuring your `.ubiquity-os.config.yml` file.
@@ -104,15 +232,23 @@ To configure your Ubiquity Kernel to run this plugin, add the following to the `
     taskAccessControl:
       usdPriceMax:
         collaborator: 5000
-        contributor: 1000 # Set to -1 to disable collaborator tasks (only allow core operations)
+        contributor: 1000 # Set to -1 to disable contributor tasks (only allow core operations)
       accountRequiredAge:
-        minimumDays: 30
+        minimumDays: 365.25 # Default: 365.25 days (1 year)
       experience:
         priorityThresholds:
+          - label: "Priority: 0 (Regression)"
+            minimumXp: -2000
+          - label: "Priority: 1 (Normal)"
+            minimumXp: -1000
+          - label: "Priority: 2 (Medium)"
+            minimumXp: 0
           - label: "Priority: 3 (High)"
-            minimumXp: 500
-          - label: "Priority: 4 (Urgent)"
             minimumXp: 1000
+          - label: "Priority: 4 (Urgent)"
+            minimumXp: 2000
+          - label: "Priority: 5 (Emergency)"
+            minimumXp: 3000
 ```
 
 ## Development
@@ -157,6 +293,25 @@ Run all formatting:
 bun run format
 ```
 
+## Environment Variables
+
+### Required
+
+- `APP_ID`: GitHub App ID
+- `APP_PRIVATE_KEY`: GitHub App private key
+- `SUPABASE_URL`: Supabase project URL
+- `SUPABASE_KEY`: Supabase service role key
+- `BOT_USER_ID`: Bot's GitHub user ID
+- `KERNEL_PUBLIC_KEY`: Public key for webhook signature verification
+
+### Optional
+
+- `LOG_LEVEL`: Logging level (default: INFO)
+- `XP_SERVICE_BASE_URL`: XP service URL (default: https://os-daemon-xp.ubq.fi)
+- `PUBLIC_API_ALLOWED_ORIGINS`: Comma-separated list of allowed origins for CORS (default: localhost in dev)
+- `RATE_LIMIT_KV`: Cloudflare KV namespace binding for rate limiting (optional, falls back to in-memory)
+- `NODE_ENV`: Environment mode (development, production, test)
+
 ## Technical Dependencies
 
 ### Core