@raidiant/notifai 0.3.0 → 0.4.0

package/src/client.ts

@@ -13,6 +13,7 @@ import type {
   SubmissionReceipt,
   SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
+import type { Logger } from './logging.js'
 
 export class ApiCallError extends Error {
   constructor(
@@ -28,6 +29,18 @@ export class ApiCallError extends Error {
 
 export class NetworkError extends Error {}
 
+/**
+ * Whether a replies-poll failure is temporary while the durable request stays
+ * live. Transport faults, throttling, request timeouts, and server failures
+ * can recover on a later poll; client errors cannot be repaired by retrying
+ * the same authenticated request.
+ */
+export function isRetryableReplyPollError(err: unknown): boolean {
+  if (err instanceof NetworkError) return true
+  if (!(err instanceof ApiCallError)) return false
+  return err.status >= 500 || err.status === 429 || err.status === 408
+}
+
 /**
  * A deadline that fired reads as an abort, which says nothing useful on its
  * own. Naming the timeout is what lets someone tell a hung server apart from a
@@ -57,8 +70,8 @@ export interface ApiClient {
     requestId: string,
     options: { waitSeconds: number; afterSeq: number },
   ): Promise<ListRepliesResponse>
-  /** Retire a question so a late device answer is rejected rather than lost. */
-  closeReplies(requestId: string): Promise<void>
+  /** Retire a question and return the replies committed before the close fence. */
+  closeReplies(requestId: string): Promise<ListRepliesResponse>
   createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>
   uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>
   health(): Promise<boolean>
@@ -71,6 +84,21 @@ export interface ClientOptions {
    * whole network path stays inside the budget the harness allows them.
    */
   timeoutMs?: number
+  /**
+   * Absolute wall-clock ceiling for the caller's whole operation. This is
+   * intentionally separate from `timeoutMs`: a late long poll must not get a
+   * fresh per-request allowance after its owning harness hook is nearly done.
+   */
+  deadlineAt?: number
+  /** Test seam for `deadlineAt`; production uses the wall clock. */
+  now?: () => number
+  /**
+   * Records each call locally. Worth having because the two failures that cost
+   * the most time — a server older than this CLI, and a network path that only
+   * fails inside a hook — both look identical from outside and are told apart
+   * instantly by a status code and a duration.
+   */
+  logger?: Pick<Logger, 'debug' | 'error'>
 }
 
 /** Generous enough for a slow link, short enough that nothing hangs for ever. */
@@ -83,6 +111,8 @@ export function createClient(
 ): ApiClient {
   const root = baseUrl.replace(/\/$/, '')
   const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const now = options.now ?? Date.now
+  const logger = options.logger
 
   async function call<T>(
     method: string,
@@ -90,12 +120,47 @@ export function createClient(
     body?: unknown,
     /** Seconds the server was asked to hold the connection open. */
     serverWaitSeconds = 0,
+  ): Promise<T> {
+    const startedAt = Date.now()
+    try {
+      const result = await callOnce<T>(method, apiPath, body, serverWaitSeconds)
+      logger?.debug('http.call', {
+        method,
+        path: apiPath,
+        ok: true,
+        duration_ms: Date.now() - startedAt,
+      })
+      return result
+    } catch (err) {
+      logger?.error('http.call', {
+        method,
+        path: apiPath,
+        ok: false,
+        duration_ms: Date.now() - startedAt,
+        ...(err instanceof ApiCallError
+          ? { status: err.status, code: err.code, message: err.message, details: err.details }
+          : { message: String(err) }),
+      })
+      throw err
+    }
+  }
+
+  async function callOnce<T>(
+    method: string,
+    apiPath: string,
+    body?: unknown,
+    serverWaitSeconds = 0,
   ): Promise<T> {
     // Without this, a server that accepts the connection and then never answers
     // hangs until the harness kills the whole hook — and the reply-poll deadline
     // cannot interrupt an individual fetch. The signal covers the
     // body read too, not just the response headers.
-    const limitMs = budgetMs + serverWaitSeconds * 1000
+    const requestBudgetMs = budgetMs + serverWaitSeconds * 1000
+    const remainingMs =
+      options.deadlineAt === undefined
+        ? requestBudgetMs
+        : Math.max(1, options.deadlineAt - now())
+    const limitMs = Math.max(1, Math.min(requestBudgetMs, remainingMs))
     const signal = AbortSignal.timeout(limitMs)
     let response: Response
     try {
@@ -154,7 +219,10 @@ export function createClient(
         waitSeconds,
       ),
     closeReplies: (requestId) =>
-      call('POST', `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`),
+      call<ListRepliesResponse>(
+        'POST',
+        `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`,
+      ),
     createMediaUpload: (body) => call('POST', '/api/v1/media', body),
     uploadMedia: async (grant, bytes) => {
       let response: Response