khotan-data 0.0.1 → 0.1.1

package/dist/templates/plug.ts

@@ -0,0 +1,806 @@
+// ============================================================================
+// Plug — a self-contained fetch wrapper for external APIs
+// Generated by khotan CLI · https://github.com/khotan-data
+//
+// This file is yours. Edit anything — auth strategies, retry logic,
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const _khotanDebug =
+  typeof process !== "undefined" && process.env?.KHOTAN_DEBUG;
+function kd(scope: string, ...args: unknown[]) {
+  if (_khotanDebug) console.log(`[khotan:${scope}]`, ...args);
+}
+// pagination helpers, error handling. It has zero runtime dependencies
+// on khotan-data.
+// ============================================================================
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class PlugError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body: unknown,
+    public readonly url: string,
+    public readonly method: string,
+  ) {
+    super(message);
+    this.name = "PlugError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auth strategies
+// ---------------------------------------------------------------------------
+
+export interface AuthStrategy {
+  type: string;
+  apply(headers: Headers): void | Promise<void>;
+  onUnauthorized?: () => void | Promise<void>;
+  baseUrl?: string;
+}
+
+export function bearer(
+  token: string | (() => string | Promise<string>),
+): AuthStrategy {
+  return {
+    type: "bearer",
+    async apply(headers: Headers) {
+      const t = typeof token === "function" ? await token() : token;
+      headers.set("Authorization", `Bearer ${t}`);
+    },
+  };
+}
+
+export function basic(username: string, password: string): AuthStrategy {
+  return {
+    type: "basic",
+    apply(headers: Headers) {
+      const encoded = btoa(`${username}:${password}`);
+      headers.set("Authorization", `Basic ${encoded}`);
+    },
+  };
+}
+
+export function apiKey(
+  name: string,
+  value: string,
+  options?: { in?: "header" | "query" },
+): AuthStrategy {
+  const location = options?.in ?? "header";
+  return {
+    type: "apiKey",
+    apply(headers: Headers) {
+      if (location === "header") {
+        headers.set(name, value);
+      }
+    },
+    ...(location === "query" ? { queryParam: { name, value } } : {}),
+  } as AuthStrategy & { queryParam?: { name: string; value: string } };
+}
+
+export function custom(
+  fn: (headers: Headers) => void | Promise<void>,
+): AuthStrategy {
+  return {
+    type: "custom",
+    apply: fn,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Var fields — declare what runtime variables a plug needs
+// ---------------------------------------------------------------------------
+
+export interface VarField {
+  readonly key: string;
+  label: string;
+  type: "text" | "password" | "url";
+  secret?: boolean;
+  hidden?: boolean;
+  required?: boolean;
+  placeholder?: string;
+  defaultValue?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Type utilities for inferring var keys
+// ---------------------------------------------------------------------------
+
+type VarKeys<V extends readonly VarField[]> = V[number]["key"];
+type VarsRecord<V extends readonly VarField[]> = Record<VarKeys<V>, string>;
+
+// ---------------------------------------------------------------------------
+// Token exchange auth strategy
+// ---------------------------------------------------------------------------
+
+export interface TokenExchangeConfig {
+  getVariables: () => Promise<Record<string, string>> | Record<string, string>;
+  /** Full URL or path relative to the plug's baseUrl (e.g. "/token") */
+  tokenEndpoint: string;
+  buildTokenRequest: (vars: Record<string, string>) => {
+    headers?: Record<string, string>;
+    body?: unknown;
+    method?: string;
+  };
+  parseTokenResponse: (data: unknown) => {
+    accessToken: string;
+    expiresIn?: number;
+  };
+  extraHeaders?: (vars: Record<string, string>) => Record<string, string>;
+  refreshBufferSeconds?: number;
+}
+
+export function tokenExchange(config: TokenExchangeConfig): AuthStrategy {
+  let cachedToken: string | null = null;
+  let tokenExpiresAt = 0;
+  let _baseUrl = "";
+  const refreshBuffer = (config.refreshBufferSeconds ?? 60) * 1000;
+
+  function resolveEndpoint(): string {
+    const ep = config.tokenEndpoint;
+    if (ep.startsWith("http://") || ep.startsWith("https://")) return ep;
+    return `${_baseUrl.replace(/\/$/, "")}${ep.startsWith("/") ? "" : "/"}${ep}`;
+  }
+
+  function isExpired(): boolean {
+    if (!cachedToken) return true;
+    if (tokenExpiresAt === 0) return false;
+    return Date.now() >= tokenExpiresAt - refreshBuffer;
+  }
+
+  async function fetchToken(): Promise<string> {
+    const vars = await config.getVariables();
+    kd(
+      "auth",
+      "tokenExchange: fetching token, has variables:",
+      Object.keys(vars).join(", "),
+    );
+    const reqConfig = config.buildTokenRequest(vars);
+
+    const headers = new Headers(reqConfig.headers);
+    if (reqConfig.body && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+
+    const endpoint = resolveEndpoint();
+    kd("auth", "tokenExchange: POST", endpoint);
+    const res = await fetch(endpoint, {
+      method: reqConfig.method ?? "POST",
+      headers,
+      body: reqConfig.body ? JSON.stringify(reqConfig.body) : undefined,
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      kd("auth", "tokenExchange: FAILED", res.status, res.statusText, body);
+      throw new PlugError(
+        `Token exchange failed: ${res.status} ${res.statusText}`,
+        res.status,
+        res.statusText,
+        body,
+        endpoint,
+        reqConfig.method ?? "POST",
+      );
+    }
+
+    const data = await res.json();
+    kd(
+      "auth",
+      "tokenExchange: raw response keys:",
+      Object.keys(data as object),
+    );
+    const parsed = config.parseTokenResponse(data);
+    cachedToken = parsed.accessToken;
+    if (!cachedToken) {
+      kd(
+        "auth",
+        "tokenExchange: WARNING - accessToken is undefined/null, check parseTokenResponse",
+      );
+    }
+    if (parsed.expiresIn) {
+      tokenExpiresAt = Date.now() + parsed.expiresIn * 1000;
+    }
+    kd(
+      "auth",
+      "tokenExchange: got token, expires in",
+      parsed.expiresIn ?? "unknown",
+      "seconds",
+    );
+    return cachedToken;
+  }
+
+  return {
+    type: "tokenExchange",
+    async apply(headers: Headers) {
+      if (isExpired()) {
+        kd("auth", "tokenExchange: token expired or missing, refreshing");
+        await fetchToken();
+      }
+      headers.set("Authorization", `Bearer ${cachedToken}`);
+      kd(
+        "auth",
+        "tokenExchange: applied bearer token",
+        cachedToken ? `${cachedToken.slice(0, 8)}...` : "MISSING",
+      );
+
+      if (config.extraHeaders) {
+        const vars = await config.getVariables();
+        const extra = config.extraHeaders(vars);
+        for (const [key, value] of Object.entries(extra)) {
+          headers.set(key, value);
+          kd("auth", "tokenExchange: set extra header", key);
+        }
+      }
+    },
+    onUnauthorized() {
+      kd("auth", "tokenExchange: 401 received, clearing cached token");
+      cachedToken = null;
+      tokenExpiresAt = 0;
+    },
+    set baseUrl(url: string) {
+      _baseUrl = url;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pagination strategies
+// ---------------------------------------------------------------------------
+
+export interface PaginationStrategy {
+  type: string;
+  getNextParams(
+    response: Record<string, unknown>,
+    currentParams: Record<string, unknown>,
+  ): Record<string, unknown> | null;
+  getDataPath(): string;
+}
+
+function getByPath(obj: Record<string, unknown>, path: string): unknown {
+  return path.split(".").reduce<unknown>((acc, key) => {
+    if (acc != null && typeof acc === "object") {
+      return (acc as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, obj);
+}
+
+export function cursorPagination(config: {
+  cursorParam: string;
+  cursorPath: string;
+  dataPath: string;
+}): PaginationStrategy {
+  return {
+    type: "cursor",
+    getNextParams(response) {
+      const cursor = getByPath(response, config.cursorPath);
+      if (cursor == null || cursor === "") return null;
+      return { [config.cursorParam]: cursor };
+    },
+    getDataPath() {
+      return config.dataPath;
+    },
+  };
+}
+
+export function offsetPagination(config: {
+  limitParam?: string;
+  offsetParam?: string;
+  dataPath: string;
+  pageSize: number;
+}): PaginationStrategy {
+  const limitParam = config.limitParam ?? "limit";
+  const offsetParam = config.offsetParam ?? "offset";
+  return {
+    type: "offset",
+    getNextParams(_response, currentParams) {
+      const data = getByPath(_response, config.dataPath) as
+        | unknown[]
+        | undefined;
+      if (!data || data.length < config.pageSize) return null;
+      const currentOffset =
+        typeof currentParams[offsetParam] === "number"
+          ? (currentParams[offsetParam] as number)
+          : 0;
+      return {
+        [limitParam]: config.pageSize,
+        [offsetParam]: currentOffset + config.pageSize,
+      };
+    },
+    getDataPath() {
+      return config.dataPath;
+    },
+  };
+}
+
+export function keysetPagination(config: {
+  param: string;
+  idField: string;
+  dataPath: string;
+}): PaginationStrategy {
+  return {
+    type: "keyset",
+    getNextParams(response) {
+      const data = getByPath(response, config.dataPath) as
+        | Record<string, unknown>[]
+        | undefined;
+      if (!data || data.length === 0) return null;
+      const lastItem = data[data.length - 1];
+      const id = lastItem?.[config.idField];
+      if (id == null) return null;
+      return { [config.param]: id };
+    },
+    getDataPath() {
+      return config.dataPath;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Retry logic
+// ---------------------------------------------------------------------------
+
+interface RetryConfig {
+  attempts: number;
+  backoff?: number;
+  maxBackoff?: number;
+  retryableStatuses?: number[];
+}
+
+const DEFAULT_RETRY: RetryConfig = {
+  attempts: 3,
+  backoff: 1000,
+  maxBackoff: 30000,
+  retryableStatuses: [408, 429, 500, 502, 503, 504],
+};
+
+function computeDelay(attempt: number, config: RetryConfig): number {
+  const base = config.backoff ?? 1000;
+  const max = config.maxBackoff ?? 30000;
+  const exponential = base * Math.pow(2, attempt);
+  const jitter = Math.random() * exponential * 0.1;
+  return Math.min(exponential + jitter, max);
+}
+
+function parseRetryAfter(header: string | null): number | null {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (!Number.isNaN(seconds)) return seconds * 1000;
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+export interface HookContext<Vars = Record<string, string>> {
+  url: string;
+  path: string;
+  method: string;
+  headers: Headers;
+  body?: unknown;
+  vars: Vars;
+  setVars(updates: Partial<Vars>): Promise<void>;
+}
+
+export interface PlugHooks<Vars = Record<string, string>> {
+  beforeRequest?: (ctx: HookContext<Vars>) => void | Promise<void>;
+  afterResponse?: (
+    response: Response,
+    ctx: HookContext<Vars>,
+  ) => void | Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Wire configuration
+// ---------------------------------------------------------------------------
+
+export interface EndpointSchema {
+  parse(data: unknown): unknown;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _def?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  shape?: any;
+}
+
+export interface EndpointDef {
+  method: string;
+  path: string;
+  description?: string;
+  body?: EndpointSchema;
+  query?: EndpointSchema;
+  responses?: Record<number, EndpointSchema>;
+}
+
+export interface PlugConfig<V extends readonly VarField[] = VarField[]> {
+  name?: string;
+  baseUrl: string;
+  auth?: AuthStrategy;
+  vars?: V;
+  endpoints?: Record<string, EndpointDef>;
+  retry?: RetryConfig | false;
+  timeout?: number;
+  defaultHeaders?: Record<string, string>;
+  pagination?: PaginationStrategy;
+  hooks?: PlugHooks<VarsRecord<V>>;
+  parsers?: Record<string, (text: string) => unknown>;
+}
+
+export interface RequestOptions {
+  params?: Record<string, unknown>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  /** Injected vars available in hooks via ctx.vars */
+  vars?: Record<string, string>;
+  /** Function to persist var updates back to encrypted storage */
+  _setVars?: (updates: Record<string, string>) => Promise<void>;
+  /** @internal Skip hooks for this request (used to prevent recursion in beforeRequest) */
+  _skipHooks?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Plug class
+// ---------------------------------------------------------------------------
+
+export class Plug<V extends readonly VarField[] = VarField[]> {
+  private readonly config: PlugConfig<V>;
+
+  constructor(config: PlugConfig<V>) {
+    this.config = config;
+    if (config.auth) {
+      config.auth.baseUrl = config.baseUrl;
+    }
+  }
+
+  get name(): string {
+    return this.config.name ?? "unnamed";
+  }
+
+  get baseUrl(): string {
+    return this.config.baseUrl;
+  }
+
+  get authType(): string {
+    return this.config.auth?.type ?? "none";
+  }
+
+  get varFields(): readonly VarField[] {
+    return this.config.vars ?? [];
+  }
+
+  get endpoints(): Record<string, EndpointDef> {
+    return this.config.endpoints ?? {};
+  }
+
+  async get<T>(path: string, options?: RequestOptions): Promise<T> {
+    return this.request<T>("GET", path, options);
+  }
+
+  async post<T>(path: string, options?: RequestOptions): Promise<T> {
+    return this.request<T>("POST", path, options);
+  }
+
+  async put<T>(path: string, options?: RequestOptions): Promise<T> {
+    return this.request<T>("PUT", path, options);
+  }
+
+  async patch<T>(path: string, options?: RequestOptions): Promise<T> {
+    return this.request<T>("PATCH", path, options);
+  }
+
+  async delete<T>(path: string, options?: RequestOptions): Promise<T> {
+    return this.request<T>("DELETE", path, options);
+  }
+
+  async request<T>(
+    method: string,
+    path: string,
+    options?: RequestOptions,
+  ): Promise<T> {
+    const url = this.buildUrl(path, options?.params);
+    const headers = this.buildHeaders(options?.headers);
+
+    if (!options?._skipHooks && this.config.hooks?.beforeRequest) {
+      const setVars = options?._setVars ?? (async () => {});
+      await this.config.hooks.beforeRequest({
+        url,
+        path,
+        method,
+        headers,
+        body: options?.body,
+        vars: (options?.vars ?? {}) as VarsRecord<V>,
+        setVars: (updates) => setVars(updates as Record<string, string>),
+      });
+    }
+
+    if (this.config.auth) {
+      await this.config.auth.apply(headers);
+    }
+
+    const authWithQuery = this.config.auth as AuthStrategy & {
+      queryParam?: { name: string; value: string };
+    };
+    if (authWithQuery?.queryParam) {
+      const u = new URL(url);
+      u.searchParams.set(
+        authWithQuery.queryParam.name,
+        authWithQuery.queryParam.value,
+      );
+      return this._fetchWithAuthRetry<T>(
+        method,
+        u.toString(),
+        headers,
+        options,
+      );
+    }
+
+    return this._fetchWithAuthRetry<T>(method, url, headers, options);
+  }
+
+  async *paginate<T>(
+    path: string,
+    options?: RequestOptions,
+  ): AsyncIterable<T[]> {
+    const pagination = this.config.pagination;
+    if (!pagination) {
+      throw new Error(
+        "Pagination strategy must be configured to use paginate()",
+      );
+    }
+
+    let currentParams: Record<string, unknown> = { ...options?.params };
+
+    while (true) {
+      const response = await this.request<Record<string, unknown>>(
+        "GET",
+        path,
+        { ...options, params: currentParams },
+      );
+
+      const data = getByPath(response, pagination.getDataPath()) as
+        | T[]
+        | undefined;
+      if (!data || data.length === 0) break;
+
+      yield data;
+
+      const nextParams = pagination.getNextParams(response, currentParams);
+      if (!nextParams) break;
+
+      currentParams = { ...currentParams, ...nextParams };
+    }
+  }
+
+  with(overrides: Partial<PlugConfig<V>>): Plug<V> {
+    return new Plug({ ...this.config, ...overrides });
+  }
+
+  withAuth(auth: AuthStrategy): Plug<V> {
+    return this.with({ auth });
+  }
+
+  private buildUrl(path: string, params?: Record<string, unknown>): string {
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const url = new URL(`${base}${cleanPath}`);
+
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value != null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+
+    return url.toString();
+  }
+
+  private buildHeaders(extra?: Record<string, string>): Headers {
+    const headers = new Headers();
+
+    if (this.config.defaultHeaders) {
+      for (const [key, value] of Object.entries(this.config.defaultHeaders)) {
+        headers.set(key, value);
+      }
+    }
+
+    if (extra) {
+      for (const [key, value] of Object.entries(extra)) {
+        headers.set(key, value);
+      }
+    }
+
+    return headers;
+  }
+
+  private async _fetchWithAuthRetry<T>(
+    method: string,
+    url: string,
+    headers: Headers,
+    options?: RequestOptions,
+  ): Promise<T> {
+    try {
+      return await this._fetch<T>(method, url, headers, options);
+    } catch (error) {
+      if (
+        error instanceof PlugError &&
+        error.status === 401 &&
+        this.config.auth?.onUnauthorized
+      ) {
+        kd(
+          "request",
+          `${this.name}: 401 on ${method} ${url}, retrying with fresh auth`,
+        );
+        await this.config.auth.onUnauthorized();
+        const freshHeaders = this.buildHeaders(options?.headers);
+        await this.config.auth.apply(freshHeaders);
+        return this._fetch<T>(method, url, freshHeaders, options);
+      }
+      throw error;
+    }
+  }
+
+  private async _fetch<T>(
+    method: string,
+    url: string,
+    headers: Headers,
+    options?: RequestOptions,
+  ): Promise<T> {
+    kd("request", `${this.name}: ${method} ${url}`);
+    const retryConfig =
+      this.config.retry === false
+        ? null
+        : { ...DEFAULT_RETRY, ...this.config.retry };
+
+    const maxAttempts = retryConfig ? retryConfig.attempts : 1;
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        const controller = new AbortController();
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+        if (this.config.timeout) {
+          timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        }
+
+        const externalSignal = options?.signal;
+        if (externalSignal?.aborted) {
+          controller.abort(externalSignal.reason);
+        }
+        externalSignal?.addEventListener("abort", () =>
+          controller.abort(externalSignal.reason),
+        );
+
+        const init: globalThis.RequestInit = {
+          method,
+          headers,
+          signal: controller.signal,
+        };
+
+        if (options?.body !== undefined && method !== "GET") {
+          init.body = JSON.stringify(options.body);
+          headers.set("Content-Type", "application/json");
+        }
+
+        const response = await fetch(url, init);
+
+        if (timeoutId) clearTimeout(timeoutId);
+
+        if (this.config.hooks?.afterResponse && !options?._skipHooks) {
+          const setVars = options?._setVars ?? (async () => {});
+          await this.config.hooks.afterResponse(response.clone(), {
+            url,
+            path: url.replace(this.config.baseUrl.replace(/\/+$/, ""), ""),
+            method,
+            headers,
+            body: options?.body,
+            vars: (options?.vars ?? {}) as VarsRecord<V>,
+            setVars: (updates) => setVars(updates as Record<string, string>),
+          });
+        }
+
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          const plugError = new PlugError(
+            `${method} ${url} failed with ${response.status} ${response.statusText}`,
+            response.status,
+            response.statusText,
+            body,
+            url,
+            method,
+          );
+
+          if (
+            retryConfig &&
+            attempt < maxAttempts - 1 &&
+            (retryConfig.retryableStatuses?.includes(response.status) ?? false)
+          ) {
+            let delay = computeDelay(attempt, retryConfig);
+
+            if (response.status === 429) {
+              const retryAfter = parseRetryAfter(
+                response.headers.get("Retry-After"),
+              );
+              if (retryAfter !== null) {
+                delay = retryAfter;
+              }
+            }
+
+            lastError = plugError;
+            await sleep(delay);
+            continue;
+          }
+
+          throw plugError;
+        }
+
+        const contentType = response.headers.get("Content-Type") ?? "";
+        if (contentType.includes("application/json")) {
+          return (await response.json()) as T;
+        }
+
+        if (this.config.parsers) {
+          for (const [mime, parser] of Object.entries(this.config.parsers)) {
+            if (contentType.includes(mime)) {
+              const text = await response.text();
+              return parser(text) as T;
+            }
+          }
+        }
+
+        return (await response.text()) as unknown as T;
+      } catch (error) {
+        if (error instanceof PlugError) throw error;
+
+        if (
+          retryConfig &&
+          attempt < maxAttempts - 1 &&
+          !(error instanceof DOMException && error.name === "AbortError")
+        ) {
+          lastError = error as Error;
+          await sleep(computeDelay(attempt, retryConfig));
+          continue;
+        }
+
+        if (error instanceof DOMException && error.name === "AbortError") {
+          throw new Error(`Request timed out: ${method} ${url}`, {
+            cause: error,
+          });
+        }
+
+        throw error;
+      }
+    }
+
+    throw (
+      lastError ?? new Error(`Request failed after ${maxAttempts} attempts`)
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function plug<const V extends readonly VarField[]>(
+  config: PlugConfig<V>,
+): Plug<V> {
+  return new Plug(config);
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}