codai-sdk 0.5.0 → 0.6.0

package/README.md

@@ -198,6 +198,34 @@ 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

package/dist/index.d.ts

@@ -11075,6 +11075,12 @@ type components = {
          * @description `200` body — triage declined the issue. The job is persisted with `status: declined` and is never billed.
          */
         readonly ResolveDeclined: {
+            /**
+             * @description Present only when the intake carried `callback_url` (a `job.declined` event is sent
+             *     too). HMAC-SHA256 key for webhook signatures. **Returned once** — store it now.
+             * @example whsec_3q2-7wQ1d0X9mZk4Vb8yTnR5sLpA6cEe
+             */
+            readonly callback_secret?: string;
             /**
              * @example feature request, no testable behavior
              * @example triage unavailable, please retry
@@ -11132,6 +11138,15 @@ type components = {
          * @description Body of `POST /v1/resolve/jobs`. Provide `issue_url` or `issue_text` (at least one).
          */
         readonly ResolveIntake: {
+            /**
+             * Format: uri
+             * @description Optional webhook target. Must be `https`, carry no credentials and point at a public
+             *     host (no localhost, private, link-local or metadata addresses; every DNS answer is
+             *     re-checked at delivery). Events are signed with the per-job `callback_secret`
+             *     returned in the intake response. Redirects are not followed.
+             * @example https://ci.example.com/hooks/codai-resolve
+             */
+            readonly callback_url?: string;
             /** @description Inline issue description. Takes precedence over `issue_url`. Only the first 20 000 characters reach triage. */
             readonly issue_text?: string;
             /**
@@ -11203,6 +11218,12 @@ type components = {
          * @description `201` body — the job was quoted (`quoted`) or auto-accepted on the free tier (`accepted`).
          */
         readonly ResolveQuote: {
+            /**
+             * @description Present only when the intake carried `callback_url`. HMAC-SHA256 key for verifying
+             *     webhook signatures. **Returned once** — it is never shown again, store it now.
+             * @example whsec_3q2-7wQ1d0X9mZk4Vb8yTnR5sLpA6cEe
+             */
+            readonly callback_secret?: string;
             /** @description Free resolves left for this user after this submission. */
             readonly free_tier_remaining: number;
             /** Format: uuid */
@@ -11252,6 +11273,53 @@ type components = {
             /** @description Errors on the whole object, e.g. `one of issue_url or issue_text is required`. */
             readonly formErrors: readonly string[];
         };
+        /**
+         * Webhook event payload
+         * @description JSON body POSTed to `callback_url`. Verify `x-codai-signature` over the raw bytes before trusting it.
+         */
+        readonly ResolveWebhookEvent: {
+            readonly event: components['schemas']['ResolveWebhookEventName'];
+            readonly job: components['schemas']['ResolveWebhookJob'];
+            /**
+             * Format: date-time
+             * @description When this delivery attempt was built (UTC).
+             */
+            readonly sent_at: string;
+        };
+        /**
+         * Webhook event
+         * @description `job.quoted` (paid quote ready), `job.declined` (triage refused), `job.resolved` (verified fix + attestation), `job.failed` (no verified fix, hold refunded), `job.error` (infrastructure failure, hold refunded).
+         * @enum {string}
+         */
+        readonly ResolveWebhookEventName: 'job.quoted' | 'job.declined' | 'job.resolved' | 'job.failed' | 'job.error';
+        /**
+         * Webhook job snapshot
+         * @description Snapshot of the job at send time. Nullable fields are `null` until the corresponding stage has run.
+         */
+        readonly ResolveWebhookJob: {
+            /** Format: uuid */
+            readonly attestation_id: string | null;
+            /**
+             * Format: uri
+             * @description Absolute URL of the public attestation (unlike the relative path on `GET /v1/resolve/jobs/{id}`).
+             * @example https://resolve.codai.ro/v1/resolve/attestations/1f2c1a3e-8d4b-4f8e-9a1b-0c2d3e4f5a6b
+             */
+            readonly attestation_url: string | null;
+            /** Format: date-time */
+            readonly completed_at: string | null;
+            /** @description Upstream inference spend attributed to this job, USD micros (informational). */
+            readonly cost_micro_usd: number;
+            readonly decline_reason: string | null;
+            readonly fail_reason: string | null;
+            /** Format: uuid */
+            readonly id: string;
+            /** @description Quoted price in USD micros; `0` on the free tier. */
+            readonly quote_micro_usd: number | null;
+            /** Format: uri */
+            readonly repo_url: string;
+            readonly status: components['schemas']['ResolveJobStatus'];
+            readonly tier: components['schemas']['ResolveTier'] | null;
+        };
     };
     responses: {
         /**
@@ -11473,6 +11541,35 @@ interface operations {
             readonly 409: components['responses']['ResolveConflict'];
         };
     };
+    readonly resolveJobWebhook: {
+        readonly parameters: {
+            readonly query?: never;
+            readonly header: {
+                /** @description Idempotency key `<jobId>:<event>`, identical on every retry. */
+                readonly 'x-codai-delivery': string;
+                /** @description Event name, same as `event` in the body. */
+                readonly 'x-codai-event': components['schemas']['ResolveWebhookEventName'];
+                /** @description `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`. */
+                readonly 'x-codai-signature': string;
+            };
+            readonly path?: never;
+            readonly cookie?: never;
+        };
+        readonly requestBody: {
+            readonly content: {
+                readonly 'application/json': components['schemas']['ResolveWebhookEvent'];
+            };
+        };
+        readonly responses: {
+            /** @description Any 2xx acknowledges the delivery; the body is ignored. */
+            readonly 200: {
+                headers: {
+                    readonly [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
 }
 
 /**
@@ -11499,6 +11596,27 @@ type ResolveReproTest = ResolveSchemas['ResolveReproTest'];
 type ResolveHealth = ResolveSchemas['ResolveHealth'];
 type ResolveValidationDetails = ResolveSchemas['ResolveValidationDetails'];
 type ResolveInsufficientFunds = ResolveSchemas['ResolveInsufficientFunds'];
+/** Body POSTed to `callback_url` (verify with `verifyResolveWebhook` first). */
+type ResolveWebhookEvent = ResolveSchemas['ResolveWebhookEvent'];
+type ResolveWebhookEventName = ResolveSchemas['ResolveWebhookEventName'];
+type ResolveWebhookJob = ResolveSchemas['ResolveWebhookJob'];
+interface VerifyResolveWebhookOptions {
+    /** Maximum age (and future skew) of `t`, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** Current unix time in seconds (tests). Default `Date.now() / 1000`. */
+    nowSeconds?: number;
+}
+/**
+ * Verify a Resolve webhook delivery: `x-codai-signature: t=<unix>,v1=<hex>`
+ * with `v1 = HMAC-SHA256(callback_secret, "<t>.<rawBody>")`. Pass the RAW
+ * request body (before JSON parsing). Constant-time compare; rejects a
+ * timestamp outside `toleranceSeconds`. Returns `false` for any bad input.
+ *
+ * Server-side only: uses `node:crypto` (Node 20.16+/22.3+, Bun, Deno), loaded
+ * lazily so the rest of the SDK still bundles for browsers and edge runtimes.
+ * Throws only when `node:crypto` is unavailable in the current runtime.
+ */
+declare function verifyResolveWebhook(secret: string, rawBody: string | Uint8Array, signatureHeader: string | null | undefined, opts?: VerifyResolveWebhookOptions): boolean;
 /** Statuses after which a job never changes again. */
 declare const RESOLVE_TERMINAL_STATUSES: ReadonlySet<ResolveJobStatus>;
 /** Any non-2xx answer from the Resolve service (flat `{ error }` body). */
@@ -12068,4 +12186,4 @@ declare class Codai {
     private legacyExt;
 }
 
-export { Account, type AccountPatchRequest, type AccountPatchResponse, type AccountView, type AgentRun, type AgentRunAccepted, type AgentRunCreateRequest, type AgentRunRequest, type AgentRunResult, type AgentRunStats, type AgentRunStatus, type AgentRunStep, type AgentRunStreamEvent, AgentRuns, type AgentSyncResult, Agents, Audio, Chat, type ChatCallOptions, type ChatCompletionChunk, type ChatCompletionInput, type ChatCompletionRequest, type ChatCompletionResponse, ChatCompletions, type ChatMessage, type ChatOptions, type ChatResult, type ChatStream, type ChatStreamResult, type ChatTool, type ChatToolCall, type ChatUsage, Codai, type CodaiClientOptions, CodaiError, type CodaiRequestExtensions, type Device, type DevicePatch, type DevicePatched, Devices, type DispatchInbox, Embeddings, type EmbeddingsOptions, type EmbeddingsRequest, type EmbeddingsResponse, type EmbeddingsResult, type Environment, type EnvironmentAddMemberBody, type EnvironmentCreateBody, type EnvironmentDetail, type EnvironmentEnrollBody, type EnvironmentEnrollToken, type EnvironmentEnrolled, type EnvironmentMember, type EnvironmentMemberCreated, EnvironmentMembers, type EnvironmentPatchBody, type EnvironmentPort, type EnvironmentPortBody, EnvironmentPorts, type EnvironmentProvider, type EnvironmentRole, type EnvironmentSecret, type EnvironmentSecretSet, EnvironmentSecrets, type EnvironmentSshCa, type EnvironmentSshCert, type EnvironmentSshCertBody, type EnvironmentState, type EnvironmentTaskCreateBody, type EnvironmentTaskCreated, type EnvironmentTaskDetail, type EnvironmentTaskList, EnvironmentTasks, type EnvironmentTransition, Environments, type EphemeralScope, type EphemeralToken, type EphemeralTokenResponse, type ErrorCode, Feedback, type FeedbackRequest, type FeedbackResponse, Health, type HealthReadyResponse, type HealthResponse, type HostExecBody, type HostExecRequest, type HostExecResponse, type HostExecResultBody, type HostOp, type HostPresence, type HostStreamEvent, Hosts, HttpClient, type ListEnvironmentsQuery, type MessageCallOptions, type MessageInput, type MessageRequest, type MessageResponse, type MessageResult, type MessageStream, type MessageStreamEvent, type MessageStreamResult, Messages, type Model, type ModelList, Models, type NotificationList, Notifications, type NotificationsDeleted, type NotificationsRead, OPERATION_METHODS, type Org, type OrgAddMemberBody, type OrgMember, OrgMembers, type OrgRole, Orgs, type PhoneModel, PhoneModels, type Project, type ProjectCreateBody, type ProjectDetail, type ProjectIsolation, type ProjectPatchBody, Projects, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, type Receipt, Receipts, type RequestOptions, Resolve, type ResolveAccepted, type ResolveAttestation, type components as ResolveComponents, type ResolveDeclined, ResolveError, type ResolveHealth, type ResolveInsufficientFunds, ResolveInsufficientFundsError, type ResolveIntake, type ResolveJob, type ResolveJobStatus, type operations as ResolveOperations, type paths as ResolvePaths, type ResolveQuote, type ResolveReproTest, type ResolveSubmitResult, type ResolveTier, type ResolveValidationDetails, type ResolveWaitOptions, Responses, type ResponsesCallOptions, type ResponsesInput, type ResponsesRequest, type ResponsesResponse, type ResponsesResult, type ResponsesStream, type ResponsesStreamEvent, type ResponsesStreamResult, STREAMING_OPERATIONS, type Session, type SessionControl, type SessionControlAccepted, type SessionControlRequest, SessionControls, type SessionCreateRequest, type SessionDetail, type SessionDispatchRequest, type SessionDispatchResponse, type SessionEvent, SessionEvents, type SessionEventsAppendRequest, type SessionEventsAppendResponse, type SessionEventsPage, type SessionIncomingEvent, SessionLease, type SessionLeaseClaimRequest, type SessionLeaseResponse, type SessionListItem, type SessionPatchRequest, type SessionShare, type SessionShareCreateRequest, type SessionShareCreated, SessionShares, type SessionStreamEvent, Sessions, type SharedSession, type SpeechRequest, type SpeechResult, type SseFrame, type StatusResponse, type Task, type TaskConfirmRequest, type TaskConfirmResponse, type TaskListPage, type TaskListQuery, type TaskOutcome, type TaskStats, Tasks, type TokenUsage, Tokens, type ToolFetchRequest, type ToolFetchResponse, type ToolSearchRequest, type ToolSearchResponse, Tools, type TranscriptionOptions, type TranscriptionResponse, type TranscriptionResult, type TriggerCreateRequest, type TriggerCreated, type TriggerEvents, type TriggerList, type TriggerPatch, type TriggerTestRequest, type TriggerTestResult, type TriggerUpdated, Triggers, type components$1 as components, Codai as default, extensionHeaders, frameJson, mergeToolCall, type operations$1 as operations, type paths$1 as paths, readSse };
+export { Account, type AccountPatchRequest, type AccountPatchResponse, type AccountView, type AgentRun, type AgentRunAccepted, type AgentRunCreateRequest, type AgentRunRequest, type AgentRunResult, type AgentRunStats, type AgentRunStatus, type AgentRunStep, type AgentRunStreamEvent, AgentRuns, type AgentSyncResult, Agents, Audio, Chat, type ChatCallOptions, type ChatCompletionChunk, type ChatCompletionInput, type ChatCompletionRequest, type ChatCompletionResponse, ChatCompletions, type ChatMessage, type ChatOptions, type ChatResult, type ChatStream, type ChatStreamResult, type ChatTool, type ChatToolCall, type ChatUsage, Codai, type CodaiClientOptions, CodaiError, type CodaiRequestExtensions, type Device, type DevicePatch, type DevicePatched, Devices, type DispatchInbox, Embeddings, type EmbeddingsOptions, type EmbeddingsRequest, type EmbeddingsResponse, type EmbeddingsResult, type Environment, type EnvironmentAddMemberBody, type EnvironmentCreateBody, type EnvironmentDetail, type EnvironmentEnrollBody, type EnvironmentEnrollToken, type EnvironmentEnrolled, type EnvironmentMember, type EnvironmentMemberCreated, EnvironmentMembers, type EnvironmentPatchBody, type EnvironmentPort, type EnvironmentPortBody, EnvironmentPorts, type EnvironmentProvider, type EnvironmentRole, type EnvironmentSecret, type EnvironmentSecretSet, EnvironmentSecrets, type EnvironmentSshCa, type EnvironmentSshCert, type EnvironmentSshCertBody, type EnvironmentState, type EnvironmentTaskCreateBody, type EnvironmentTaskCreated, type EnvironmentTaskDetail, type EnvironmentTaskList, EnvironmentTasks, type EnvironmentTransition, Environments, type EphemeralScope, type EphemeralToken, type EphemeralTokenResponse, type ErrorCode, Feedback, type FeedbackRequest, type FeedbackResponse, Health, type HealthReadyResponse, type HealthResponse, type HostExecBody, type HostExecRequest, type HostExecResponse, type HostExecResultBody, type HostOp, type HostPresence, type HostStreamEvent, Hosts, HttpClient, type ListEnvironmentsQuery, type MessageCallOptions, type MessageInput, type MessageRequest, type MessageResponse, type MessageResult, type MessageStream, type MessageStreamEvent, type MessageStreamResult, Messages, type Model, type ModelList, Models, type NotificationList, Notifications, type NotificationsDeleted, type NotificationsRead, OPERATION_METHODS, type Org, type OrgAddMemberBody, type OrgMember, OrgMembers, type OrgRole, Orgs, type PhoneModel, PhoneModels, type Project, type ProjectCreateBody, type ProjectDetail, type ProjectIsolation, type ProjectPatchBody, Projects, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, type Receipt, Receipts, type RequestOptions, Resolve, type ResolveAccepted, type ResolveAttestation, type components as ResolveComponents, type ResolveDeclined, ResolveError, type ResolveHealth, type ResolveInsufficientFunds, ResolveInsufficientFundsError, type ResolveIntake, type ResolveJob, type ResolveJobStatus, type operations as ResolveOperations, type paths as ResolvePaths, type ResolveQuote, type ResolveReproTest, type ResolveSubmitResult, type ResolveTier, type ResolveValidationDetails, type ResolveWaitOptions, type ResolveWebhookEvent, type ResolveWebhookEventName, type ResolveWebhookJob, Responses, type ResponsesCallOptions, type ResponsesInput, type ResponsesRequest, type ResponsesResponse, type ResponsesResult, type ResponsesStream, type ResponsesStreamEvent, type ResponsesStreamResult, STREAMING_OPERATIONS, type Session, type SessionControl, type SessionControlAccepted, type SessionControlRequest, SessionControls, type SessionCreateRequest, type SessionDetail, type SessionDispatchRequest, type SessionDispatchResponse, type SessionEvent, SessionEvents, type SessionEventsAppendRequest, type SessionEventsAppendResponse, type SessionEventsPage, type SessionIncomingEvent, SessionLease, type SessionLeaseClaimRequest, type SessionLeaseResponse, type SessionListItem, type SessionPatchRequest, type SessionShare, type SessionShareCreateRequest, type SessionShareCreated, SessionShares, type SessionStreamEvent, Sessions, type SharedSession, type SpeechRequest, type SpeechResult, type SseFrame, type StatusResponse, type Task, type TaskConfirmRequest, type TaskConfirmResponse, type TaskListPage, type TaskListQuery, type TaskOutcome, type TaskStats, Tasks, type TokenUsage, Tokens, type ToolFetchRequest, type ToolFetchResponse, type ToolSearchRequest, type ToolSearchResponse, Tools, type TranscriptionOptions, type TranscriptionResponse, type TranscriptionResult, type TriggerCreateRequest, type TriggerCreated, type TriggerEvents, type TriggerList, type TriggerPatch, type TriggerTestRequest, type TriggerTestResult, type TriggerUpdated, Triggers, type VerifyResolveWebhookOptions, type components$1 as components, Codai as default, extensionHeaders, frameJson, mergeToolCall, type operations$1 as operations, type paths$1 as paths, readSse, verifyResolveWebhook };

package/dist/index.js

@@ -1220,6 +1220,46 @@ var Projects = class {
 };
 
 // src/resources/resolve.ts
+function verifyResolveWebhook(secret, rawBody, signatureHeader, opts = {}) {
+  if (!secret || !signatureHeader) return false;
+  let t;
+  const v1s = [];
+  for (const part of signatureHeader.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const k = part.slice(0, eq).trim();
+    const v = part.slice(eq + 1).trim();
+    if (k === "t") t = v;
+    else if (k === "v1") v1s.push(v.toLowerCase());
+  }
+  if (!t || !/^\d+$/.test(t) || v1s.length === 0) return false;
+  const tolerance = opts.toleranceSeconds ?? 300;
+  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - Number(t)) > tolerance) return false;
+  const { createHmac, timingSafeEqual } = nodeCrypto();
+  const enc2 = new TextEncoder();
+  const body = typeof rawBody === "string" ? enc2.encode(rawBody) : rawBody;
+  const expected = createHmac("sha256", secret).update(enc2.encode(`${t}.`)).update(body).digest();
+  return v1s.some((v1) => {
+    if (!/^[0-9a-f]{64}$/.test(v1)) return false;
+    return timingSafeEqual(hexToBytes(v1), expected);
+  });
+}
+function nodeCrypto() {
+  const proc = globalThis.process;
+  const mod = proc?.getBuiltinModule?.("node:crypto");
+  if (!mod) {
+    throw new Error(
+      "verifyResolveWebhook needs node:crypto (Node 20.16+/22.3+, Bun or Deno); run it server-side"
+    );
+  }
+  return mod;
+}
+function hexToBytes(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
 var RESOLVE_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "resolved",
   "failed",
@@ -2187,6 +2227,6 @@ function allKeys(obj) {
 }
 var index_default = Codai;
 
-export { Account, AgentRuns, Agents, Audio, Chat, ChatCompletions, Codai, CodaiError, Devices, Embeddings, EnvironmentMembers, EnvironmentPorts, EnvironmentSecrets, EnvironmentTasks, Environments, Feedback, Health, Hosts, HttpClient, Messages, Models, Notifications, OPERATION_METHODS, OrgMembers, Orgs, PhoneModels, Projects, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, Receipts, Resolve, ResolveError, ResolveInsufficientFundsError, Responses, STREAMING_OPERATIONS, SessionControls, SessionEvents, SessionLease, SessionShares, Sessions, Tasks, Tokens, Tools, Triggers, index_default as default, extensionHeaders, frameJson, mergeToolCall, readSse };
+export { Account, AgentRuns, Agents, Audio, Chat, ChatCompletions, Codai, CodaiError, Devices, Embeddings, EnvironmentMembers, EnvironmentPorts, EnvironmentSecrets, EnvironmentTasks, Environments, Feedback, Health, Hosts, HttpClient, Messages, Models, Notifications, OPERATION_METHODS, OrgMembers, Orgs, PhoneModels, Projects, RESOLVE_OPERATION_METHODS, RESOLVE_TERMINAL_STATUSES, Receipts, Resolve, ResolveError, ResolveInsufficientFundsError, Responses, STREAMING_OPERATIONS, SessionControls, SessionEvents, SessionLease, SessionShares, Sessions, Tasks, Tokens, Tools, Triggers, index_default as default, extensionHeaders, frameJson, mergeToolCall, readSse, verifyResolveWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map