codai-sdk 0.4.0 → 0.6.0

package/README.md

@@ -65,6 +65,7 @@ surface.
 | `receipt`          | `get`                                                                                                                                                                                                | `GET /v1/receipt`                                        |
 | `feedback`         | `submit`                                                                                                                                                                                             | `POST /v1/feedback`                                      |
 | `phoneModels`      | `list`                                                                                                                                                                                               | `GET /v1/phone/models`                                   |
+| `resolve`          | `submit`, `get`, `accept`, `attestation`, `health`, `waitFor`                                                                                                                                        | `https://resolve.codai.ro/v1/resolve/*` (own host)       |
 
 Every method takes an optional last argument `{ ext, signal }` where `ext` is a
 typed bag of `X-Codai-*` extension headers (see below).
@@ -158,6 +159,73 @@ const receipt = await codai.receipt.get({ sessionId: 'my-project' });
 receipt.cost_usd;
 ```
 
+## Resolve — verified bug fixes
+
+`client.resolve` talks to the separate Resolve service (`https://resolve.codai.ro`,
+override with `resolveBaseUrl`) with the same API key. You submit a public GitHub
+repo + issue, triage quotes a tier (or declines), you accept, and only a verified
+fix is billed — with a public attestation. Amounts are USD micros.
+
+```ts
+import { ResolveInsufficientFundsError } from 'codai-sdk';
+
+const q = await codai.resolve.submit({
+  repo_url: 'https://github.com/psf/requests',
+  issue_url: 'https://github.com/psf/requests/issues/6000', // or issue_text
+  test_command: 'python -m pytest -q tests/test_x.py::test_y', // optional
+});
+if (q.status === 'declined') throw new Error(q.decline_reason);
+
+if (q.status === 'quoted') {
+  try {
+    await codai.resolve.accept(q.id); // free-tier jobs are auto-accepted
+  } catch (err) {
+    if (err instanceof ResolveInsufficientFundsError) console.log('top up:', err.topupUrl);
+    throw err;
+  }
+}
+
+const job = await codai.resolve.waitFor(q.id, { intervalMs: 5_000, timeoutMs: 30 * 60_000 });
+if (job.status === 'resolved' && job.attestation_url) {
+  const proof = await codai.resolve.attestation(job.attestation_url);
+  console.log(proof.patch);
+}
+```
+
+Errors are `ResolveError` (a `CodaiError` with `status` and `detail` = the flat
+`error` string or Zod details); a `402` on `accept` is `ResolveInsufficientFundsError`
+with `balance`, `required`, `currency: 'micro_eur'` and `topupUrl`. `submit` and
+`accept` are never retried. `waitFor` stops at `resolved | failed | declined | error`
+(or `until`), and throws `ResolveError` with `status: 0` on timeout.
+
+### Webhooks instead of polling
+
+Pass `callback_url` (https, public host) on `submit`; the response carries
+`callback_secret` **once** — store it. Resolve then POSTs `job.quoted`,
+`job.declined`, `job.resolved`, `job.failed` and `job.error` events signed with
+`x-codai-signature: t=<unix>,v1=<hex HMAC-SHA256>`. Verify against the raw body
+with `verifyResolveWebhook` (server-side, uses `node:crypto`; 300 s tolerance by
+default). Up to 3 attempts on `5xx`/`429`/network errors; deduplicate on
+`x-codai-delivery`; delivery never changes job state — `get(id)` stays the truth.
+
+```ts
+import { verifyResolveWebhook, type ResolveWebhookEvent } from 'codai-sdk';
+
+const q = await codai.resolve.submit({
+  repo_url: 'https://github.com/psf/requests',
+  issue_url: 'https://github.com/psf/requests/issues/6000',
+  callback_url: 'https://ci.example.com/hooks/codai-resolve',
+});
+await saveSecret(q.id, q.callback_secret!); // shown once
+
+// in your webhook handler (Hono / Next route / express.raw):
+const raw = await req.text();
+if (!verifyResolveWebhook(secret, raw, req.headers.get('x-codai-signature'))) {
+  return new Response('bad signature', { status: 401 });
+}
+const evt = JSON.parse(raw) as ResolveWebhookEvent; // evt.event, evt.job.attestation_url
+```
+
 ## Shared sessions, devices and hosts
 
 Shared-sessions and hosts calls need a device UUID (`x-codai-device`). Set it once
@@ -240,6 +308,7 @@ const models = await codai.models();
 const codai = new Codai({
   apiKey: process.env.CODAI_API_KEY!,
   baseUrl: 'https://ai.codai.ro', // default
+  resolveBaseUrl: 'https://resolve.codai.ro', // default (client.resolve)
   sessionId: 'my-project', // enables session memory + stickiness
   device: '<uuid>', // shared sessions / hosts (x-codai-device)
   client: 'my-app/1.2.0', // x-codai-client surface tag
@@ -287,8 +356,12 @@ import type { components, Task, SessionStreamEvent } from 'codai-sdk';
 type Receipt = components['schemas']['AccountReceipt'];
 ```
 
-Regenerate after a spec change with `pnpm gen`; `operations.test.ts` fails when
-the spec and the client drift.
+Resolve types are exported as `ResolvePaths`, `ResolveComponents` and
+`ResolveOperations` (plus aliases such as `ResolveJob`, `ResolveQuote`).
+
+Regenerate after a spec change with `pnpm gen` (gateway + resolve);
+`operations.test.ts` and `operations.resolve.test.ts` fail when a spec and the
+client drift.
 
 ## Migrating from the OpenAI SDK