Add TypeScript toolchain: signing helper, tests, husky + CI

- src/onsight.ts: typed helper for the wallet-signature owner-action scheme
  (signOwnerActionHeaders / ownerActionMessage / missionOrderUrl), so agent
  authors don't reimplement replay-safe signing.
- src/onsight.test.ts: jest unit tests that mirror the server's WalletSigGuard
  message construction, so they fail if the client ever drifts.
- Convert the x402 example to TS, importing the helper.
- eslint + prettier + tsc + jest, run in parallel as a husky pre-commit hook
  and as four parallel PR/push CI jobs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ktamas77

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Four independent jobs → GitHub runs them in parallel.
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm }
+      - run: npm ci
+      - run: npm run lint
+
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm }
+      - run: npm ci
+      - run: npm run format:check
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm }
+      - run: npm ci
+      - run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm }
+      - run: npm ci
+      - run: npm test

.husky/pre-commit

@@ -0,0 +1,11 @@
+# Run the four checks in parallel; fail the commit if any one fails.
+npm run lint & p1=$!
+npm run format:check & p2=$!
+npm run typecheck & p3=$!
+npm test & p4=$!
+
+fail=0
+for p in $p1 $p2 $p3 $p4; do
+  wait "$p" || fail=1
+done
+exit $fail

.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+package-lock.json

README.md

@@ -13,17 +13,17 @@ Live at **[onsight.photo](https://onsight.photo)**.
 
 Onsight is a crowdsourced ground-truth photography marketplace:
 
-- A **requester** posts a *mission* — "photograph the queue outside this address,
+- A **requester** posts a _mission_ — "photograph the queue outside this address,
   today, from the street" — and funds a reward in USDC.
 - Local **photographers** nearby fulfill it and submit photos.
 - The requester picks a winner; the escrowed reward pays out on-chain.
 
 There are **two front doors onto the same rail**:
 
-| Requester | How they order | How they pay |
-|---|---|---|
-| **Human** | web UI at [onsight.photo](https://onsight.photo) | direct USDC deposit (card on-ramp available) |
-| **AI agent** | `POST /agent/missions` | **[x402](https://x402.org)** — pays USDC per call, no account, no key |
+| Requester    | How they order                                   | How they pay                                                          |
+| ------------ | ------------------------------------------------ | --------------------------------------------------------------------- |
+| **Human**    | web UI at [onsight.photo](https://onsight.photo) | direct USDC deposit (card on-ramp available)                          |
+| **AI agent** | `POST /agent/missions`                           | **[x402](https://x402.org)** — pays USDC per call, no account, no key |
 
 Same escrow, same photographer supply, same payout. Only how the order is placed
 and paid differs.
@@ -63,13 +63,13 @@ payments, since the money is already escrowed.
 
 Base URL: `https://onsight.photo`
 
-| Agent action | Endpoint | Auth |
-|---|---|---|
-| Post + fund a mission (place a photo order) | `POST /agent/missions?rewardUsd=N` | **x402** (payment = escrow funding) |
-| Read a mission + submitted photos | `GET /agent/missions/:id` | public |
-| Update brief / extend dates | `PATCH /agent/missions/:id` | wallet signature |
-| Pick + pay a winner | `POST /agent/missions/:id/select` `{ photoId }` | wallet signature |
-| Refund / cancel | `POST /agent/missions/:id/refund` | wallet signature |
+| Agent action                                | Endpoint                                        | Auth                                |
+| ------------------------------------------- | ----------------------------------------------- | ----------------------------------- |
+| Post + fund a mission (place a photo order) | `POST /agent/missions?rewardUsd=N`              | **x402** (payment = escrow funding) |
+| Read a mission + submitted photos           | `GET /agent/missions/:id`                       | public                              |
+| Update brief / extend dates                 | `PATCH /agent/missions/:id`                     | wallet signature                    |
+| Pick + pay a winner                         | `POST /agent/missions/:id/select` `{ photoId }` | wallet signature                    |
+| Refund / cancel                             | `POST /agent/missions/:id/refund`               | wallet signature                    |
 
 **Wallet-signature auth** (owner actions): send `X-Wallet-Address`,
 `X-Wallet-Signature`, and `X-Wallet-Timestamp`, signing the message
@@ -102,16 +102,34 @@ curl -i -X POST "https://onsight.photo/agent/missions?rewardUsd=20" \
 To actually place and fund the order, an agent signs the payment and retries with an
 `X-PAYMENT` header. The full runnable flow — using [`x402-fetch`](https://www.npmjs.com/package/x402-fetch)
 so payment is handled automatically — is in
-**[`examples/x402-agent-order.js`](examples/x402-agent-order.js)**.
+**[`examples/x402-agent-order.ts`](examples/x402-agent-order.ts)**:
+
+```bash
+npm install
+AGENT_PRIVATE_KEY=0x... npm run example
+```
 
 Buying as a human? See **[`examples/human-order.md`](examples/human-order.md)**.
 
 ## Examples
 
-- [`examples/x402-agent-order.js`](examples/x402-agent-order.js) — an agent places and
-  funds a photo order via x402, then reads it back.
+- [`examples/x402-agent-order.ts`](examples/x402-agent-order.ts) — an agent places and
+  funds a photo order via x402, reads it back, then picks a winner with a signed
+  owner action.
 - [`examples/human-order.md`](examples/human-order.md) — walkthrough for human buyers.
 
+## Signing helper
+
+Owner actions (pick a winner, refund, edit a brief) are authorized by signing a
+canonical, body-bound message — get the format wrong and the server rejects you, or
+you sign something you didn't mean to. [`src/onsight.ts`](src/onsight.ts) encodes it
+once (`signOwnerActionHeaders`, `ownerActionMessage`, `missionOrderUrl`), and its
+tests mirror the server guard so they break loudly if the scheme ever drifts.
+
+```bash
+npm run lint && npm run typecheck && npm test   # or all four via the pre-commit hook
+```
+
 ## Status
 
 The USDC escrow rail is live on Base mainnet; the x402 agent channel is rolling out.

eslint.config.js

@@ -0,0 +1,13 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  { ignores: ["node_modules", "dist"] },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: { process: "readonly", console: "readonly", fetch: "readonly" },
+    },
+  },
+);

examples/human-order.md

@@ -7,9 +7,9 @@ The web app wraps the same escrow rail the agent API uses.
 
 1. **Go to [onsight.photo](https://onsight.photo)** and start a new mission.
 2. **Describe what you need.** A good brief is specific:
-   - *What* to photograph (a storefront, a line, a shelf, a view).
-   - *Where* — an address or a dropped map pin, plus how far around it is acceptable.
-   - *When* — "today", "during business hours", a specific date/time window.
+   - _What_ to photograph (a storefront, a line, a shelf, a view).
+   - _Where_ — an address or a dropped map pin, plus how far around it is acceptable.
+   - _When_ — "today", "during business hours", a specific date/time window.
    - Any constraints — daylight, no faces, a particular angle.
 3. **Set the reward.** This is what the winning photographer earns. Higher rewards
    and tighter deadlines get filled faster.

examples/package.json

@@ -0,0 +1,82 @@
+// Place and fund a ground-truth photo order on Onsight, paid via x402 —
+// then (optionally) pick the winning photo with a wallet-signed owner action.
+//
+// An AI agent can't photograph a real place; this commissions a real person to.
+// x402 handles payment inline: the first request comes back 402, `x402-fetch`
+// signs a USDC payment on Base and retries automatically. The agent's wallet IS
+// the account — no signup, no API key.
+//
+// Run (from the repo root):
+//   npm install
+//   AGENT_PRIVATE_KEY=0x... npm run example
+//
+// The wallet needs USDC on Base (or Base Sepolia for testing) plus a little ETH
+// for the on-chain settlement.
+
+import { wrapFetchWithPayment } from "x402-fetch";
+import { privateKeyToAccount } from "viem/accounts";
+import { missionOrderUrl, signOwnerActionHeaders } from "../src/onsight.js";
+
+const BASE_URL = process.env.ONSIGHT_URL ?? "https://onsight.photo";
+const REWARD_USD = 20;
+
+const key = process.env.AGENT_PRIVATE_KEY;
+if (!key)
+  throw new Error("Set AGENT_PRIVATE_KEY to a wallet holding USDC on Base");
+
+const account = privateKeyToAccount(key as `0x${string}`);
+// fetch that transparently answers a 402 by paying and retrying:
+const fetchWithPay = wrapFetchWithPayment(fetch, account);
+
+const mission = {
+  title: "Storefront at 123 Market St",
+  description: "Street-level photo of the entrance, taken today in daylight.",
+  lat: 37.7897,
+  lng: -122.3972,
+  radiusMeters: 150,
+};
+
+// 1. Post + fund the mission. First call → 402; x402-fetch pays and retries.
+const res = await fetchWithPay(missionOrderUrl(REWARD_USD, BASE_URL), {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(mission),
+});
+if (!res.ok) throw new Error(`Order failed: ${res.status} ${await res.text()}`);
+
+const created = (await res.json()) as {
+  id: string;
+  txHash?: string;
+  paymentTxHash?: string;
+};
+console.log("Mission funded:", created.id);
+console.log("Settlement tx:", created.txHash ?? created.paymentTxHash);
+
+// 2. Read it back (public — no payment, no signature) to poll for submitted photos.
+const check = await fetch(`${BASE_URL}/agent/missions/${created.id}`);
+const state = (await check.json()) as {
+  status?: string;
+  paymentStatus?: string;
+  photos?: unknown[];
+};
+console.log(
+  `Status: ${state.status ?? state.paymentStatus} — ${(state.photos ?? []).length} photo(s) so far`,
+);
+
+// 3. Pick + pay a winner. This is an OWNER action — no more x402, just prove
+//    control of the funding wallet by signing the request. Guarded behind an env
+//    var so running the example doesn't accidentally pay out.
+const photoId = process.env.SELECTED_PHOTO_ID;
+if (photoId) {
+  const path = `/agent/missions/${created.id}/select`;
+  const body = { photoId };
+  const headers = await signOwnerActionHeaders(account, "POST", path, body);
+  const pick = await fetchWithPay(`${BASE_URL}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify(body),
+  });
+  console.log(
+    pick.ok ? `Paid out to photo ${photoId}` : `Select failed: ${pick.status}`,
+  );
+}

examples/x402-agent-order.js

@@ -0,0 +1,7 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+export default {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  moduleNameMapper: { "^(\\.{1,2}/.*)\\.js$": "$1" },
+  testMatch: ["**/*.test.ts"],
+};