@outposted/node 0.1.0

package/src/transport.ts

@@ -0,0 +1,198 @@
+// ────────────────────────────────────────────────────────────────────────────
+// @outposted/node/transport — HTTP client used by every resource.
+//
+// Responsibilities:
+//   - Sign requests (Authorization: Bearer <apiKey>)
+//   - Generate a per-request X-Outposted-Request-ID for correlation
+//   - Parse 2xx JSON responses
+//   - Convert 4xx/5xx into the right OutpostedError subclass
+//   - Retry transient failures (5xx, NetworkError) with exponential backoff
+//
+// Retry policy mirrors what we tell users in docs:
+//   - 3 attempts total (initial + 2 retries)
+//   - Backoff: 250ms, 500ms, 1000ms
+//   - NEVER retry on 4xx (caller bug — retry won't fix it)
+//   - ALWAYS retry on network errors and 5xx
+//
+// Fetch is injected so consumers can polyfill (Node <18) or stub in tests.
+// ────────────────────────────────────────────────────────────────────────────
+
+import { OutpostedError, OutpostedNetworkError, type OutpostedErrorBody } from './errors';
+
+export type FetchLike = typeof globalThis.fetch;
+
+export interface HttpClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+  fetch?: FetchLike;
+}
+
+export interface RequestOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  body?: unknown;
+  query?: Record<string, string | number | boolean | undefined | null>;
+}
+
+const DEFAULT_BASE_URL = 'https://api.outposted.one';
+const MAX_ATTEMPTS = 3;
+const BACKOFFS_MS = [250, 500, 1000];
+
+export class HttpClient {
+  private readonly apiKey: string;
+  /**
+   * Resolved base URL (no trailing slash). Exposed so resources that build
+   * non-HTTP URLs (e.g. OAuth start redirects) can reuse the same origin the
+   * client was configured with.
+   */
+  public readonly baseUrl: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(options: HttpClientOptions) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new Error(
+        'HttpClient: fetch is not available. Provide options.fetch or run on Node >=18.',
+      );
+    }
+    this.fetchImpl = fetchImpl.bind(globalThis);
+  }
+
+  async request<T>(options: RequestOptions): Promise<T> {
+    const url = this.buildUrl(options.path, options.query);
+    const hasBody = options.body !== undefined;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: 'application/json',
+      'X-Outposted-Request-ID': generateRequestId(),
+    };
+    if (hasBody) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    const init: RequestInit = {
+      method: options.method,
+      headers,
+      body: hasBody ? JSON.stringify(options.body) : undefined,
+    };
+
+    let lastError: unknown;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      try {
+        const response = await this.fetchImpl(url, init);
+        const responseHeaders = readHeaders(response);
+        const requestId = responseHeaders['x-outposted-request-id'] ?? headers['X-Outposted-Request-ID'];
+
+        if (response.status >= 200 && response.status < 300) {
+          return await parseJsonOrEmpty<T>(response);
+        }
+
+        const body = await parseErrorBody(response);
+        const error = OutpostedError.fromResponse(response.status, body, responseHeaders, requestId);
+
+        if (response.status >= 500 && attempt < MAX_ATTEMPTS - 1) {
+          lastError = error;
+          await sleep(getBackoff(attempt));
+          continue;
+        }
+        throw error;
+      } catch (err) {
+        if (err instanceof OutpostedError && (err.status === undefined || err.status < 500)) {
+          // 4xx — never retry.
+          throw err;
+        }
+        if (err instanceof OutpostedError) {
+          // 5xx already handled in the 5xx branch above. Reaching here means
+          // we exhausted retries — rethrow.
+          throw err;
+        }
+        // Network-layer failure.
+        const networkError = wrapNetworkError(err);
+        if (attempt < MAX_ATTEMPTS - 1) {
+          lastError = networkError;
+          await sleep(getBackoff(attempt));
+          continue;
+        }
+        throw networkError;
+      }
+    }
+
+    // Should be unreachable — the loop always throws or returns.
+    throw lastError instanceof Error
+      ? lastError
+      : new OutpostedNetworkError('Outposted SDK: exhausted retries without a definitive error');
+  }
+
+  private buildUrl(path: string, query?: RequestOptions['query']): string {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${this.baseUrl}${normalizedPath}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) continue;
+        url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function generateRequestId(): string {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj && typeof cryptoObj.randomUUID === 'function') {
+    return cryptoObj.randomUUID();
+  }
+  // Fallback — shouldn't be hit on Node 20+ or any modern runtime.
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function readHeaders(response: Response): Record<string, string> {
+  const out: Record<string, string> = {};
+  response.headers.forEach((value, key) => {
+    out[key.toLowerCase()] = value;
+  });
+  return out;
+}
+
+async function parseJsonOrEmpty<T>(response: Response): Promise<T> {
+  const text = await response.text();
+  if (!text) {
+    return undefined as T;
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return undefined as T;
+  }
+}
+
+async function parseErrorBody(response: Response): Promise<OutpostedErrorBody | null> {
+  const text = await response.text().catch(() => '');
+  if (!text) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed === 'object' && parsed !== null) {
+      return parsed as OutpostedErrorBody;
+    }
+    return { message: String(parsed) };
+  } catch {
+    return { message: text };
+  }
+}
+
+function wrapNetworkError(err: unknown): OutpostedNetworkError {
+  const message =
+    err instanceof Error ? `Outposted SDK: network error — ${err.message}` : 'Outposted SDK: network error';
+  return new OutpostedNetworkError(message, err);
+}
+
+function getBackoff(attempt: number): number {
+  return BACKOFFS_MS[attempt] ?? BACKOFFS_MS[BACKOFFS_MS.length - 1] ?? 1000;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}