@lincoln504/pi-research 0.0.0

package/src/stackexchange/queries.ts

@@ -0,0 +1,168 @@
+/**
+ * Stack Exchange API Query Builders
+ */
+
+import type { SortOrder, SortActivity, SortReputation } from './types.ts';
+
+export interface SearchParams {
+  query?: string;
+  title?: string;
+  tagged?: string | string[];
+  nottagged?: string | string[];
+  intitle?: string;
+  accepted?: boolean;
+  answers?: number;
+  body?: string;
+  closed?: boolean;
+  migrated?: boolean;
+  notice?: string;
+  user?: number;
+  url?: string;
+  views?: number;
+  wiki?: boolean;
+  page?: number;
+  pagesize?: number;
+  sort?: SortActivity;
+  order?: SortOrder;
+  site?: string;
+  filter?: string;
+}
+
+export interface QuestionParams {
+  ids: string | number | (string | number)[];
+  site?: string;
+  filter?: string;
+  sort?: SortActivity;
+  order?: SortOrder;
+  page?: number;
+  pagesize?: number;
+}
+
+export interface UserParams {
+  ids: string | number | (string | number)[];
+  site?: string;
+  filter?: string;
+  sort?: SortReputation;
+  order?: SortOrder;
+  page?: number;
+  pagesize?: number;
+}
+
+export interface SitesParams {
+  page?: number;
+  pagesize?: number;
+}
+
+/**
+ * Build URL search parameters from object
+ */
+export function buildSearchParams(params: SearchParams): URLSearchParams {
+  const searchParams = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+
+    if (typeof value === 'boolean') {
+      searchParams.set(key, value ? 'true' : 'false');
+    } else if (Array.isArray(value)) {
+      searchParams.set(key, value.join(';')); // Stack Exchange uses semicolons for arrays
+    } else {
+      searchParams.set(key, String(value));
+    }
+  }
+
+  return searchParams;
+}
+
+/**
+ * Build search/advanced query
+ */
+export function buildSearchQuery(params: SearchParams): URLSearchParams {
+  return buildSearchParams(params);
+}
+
+/**
+ * Build questions query
+ */
+export function buildQuestionsQuery(params: QuestionParams): URLSearchParams {
+  const searchParams = new URLSearchParams();
+
+  searchParams.set('order', params.order ?? 'desc');
+  searchParams.set('sort', params.sort ?? 'activity');
+  searchParams.set('site', params.site ?? 'stackoverflow.com');
+  if (params.filter) {
+    searchParams.set('filter', params.filter);
+  }
+  if (params.page) {
+    searchParams.set('page', String(params.page));
+  }
+  if (params.pagesize) {
+    searchParams.set('pagesize', String(params.pagesize));
+  }
+
+  return searchParams;
+}
+
+/**
+ * Build user query
+ */
+export function buildUserQuery(params: UserParams): URLSearchParams {
+  const searchParams = new URLSearchParams();
+
+  searchParams.set('site', params.site ?? 'stackoverflow.com');
+  searchParams.set('order', params.order ?? 'desc');
+  searchParams.set('sort', params.sort ?? 'reputation');
+  if (params.filter) {
+    searchParams.set('filter', params.filter);
+  }
+  if (params.page) {
+    searchParams.set('page', String(params.page));
+  }
+  if (params.pagesize) {
+    searchParams.set('pagesize', String(params.pagesize));
+  }
+
+  return searchParams;
+}
+
+/**
+ * Build sites query
+ */
+export function buildSitesQuery(params?: SitesParams): URLSearchParams {
+  const searchParams = new URLSearchParams();
+
+  if (params?.page) {
+    searchParams.set('page', String(params.page));
+  }
+  if (params?.pagesize) {
+    searchParams.set('pagesize', String(params.pagesize));
+  }
+
+  return searchParams;
+}
+
+/**
+ * Pre-defined filters for common use cases
+ */
+export const Filters = {
+  // Get question body and answers with body
+  WITH_BODY: '!9_bDDxJY5',
+  // Minimal info - just title and score
+  MINIMAL: '!-*f(6rL6Wq', // Minimal info - title, score, tags, owner
+  // Full details including comments
+  FULL: '!*S15IVPvS5',
+  // Get answers with body
+  ANSWERS_WITH_BODY: '!9_bDE(fI5',
+};
+
+/**
+ * Parse IDs from query string (handle both single IDs and comma/semicolon separated)
+ */
+export function parseIds(ids: string | number | (string | number)[]): string {
+  if (Array.isArray(ids)) {
+    return ids.join(';');
+  }
+  return String(ids);
+}

package/src/stackexchange/rest-client.ts

@@ -0,0 +1,127 @@
+/**
+ * Stack Exchange REST API v2.3 Client
+ * Handles API requests with rate limiting, quota tracking, and backoff handling
+ */
+
+import type { StackExchangeWrapper } from './types.ts';
+import { logger } from '../logger.ts';
+
+const API_BASE = 'https://api.stackexchange.com/2.3';
+
+export interface RequestOptions {
+  method: string;
+  endpoint: string;
+  params: URLSearchParams;
+}
+
+export class StackExchangeClient {
+  private readonly _apiKey: string | null;
+  private readonly _timeout: number;
+  private quotaRemaining = 300;
+  private quotaMax = 300;
+  private requestCount = 0;
+  private lastBackoff: number | null = null;
+
+  constructor(
+    apiKey: string | null,
+    timeout: number,
+  ) {
+    this._apiKey = apiKey;
+    this._timeout = timeout;
+  }
+
+  async request<T>(options: RequestOptions, signal?: AbortSignal): Promise<StackExchangeWrapper<T>> {
+    // Check for backoff from previous requests
+    if (this.lastBackoff && this.lastBackoff > Date.now()) {
+      const waitTime = Math.ceil((this.lastBackoff - Date.now()) / 1000);
+      throw new Error(
+        `Rate limited. Please wait ${waitTime} seconds before making more requests.`,
+      );
+    }
+
+    const url = new URL(`${API_BASE}${options.endpoint}`);
+    url.search = options.params.toString();
+
+    // Add API key if provided
+    if (this._apiKey) {
+      url.searchParams.set('key', this._apiKey);
+    }
+
+    // Add site parameter if not already present (for methods that need it)
+    if (!url.searchParams.has('site') && !options.endpoint.startsWith('/sites')) {
+      url.searchParams.set('site', 'stackoverflow.com');
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, this._timeout);
+
+    // Chain the signal if provided
+    if (signal) {
+      signal.addEventListener('abort', () => {
+        clearTimeout(timeoutId);
+        controller.abort();
+      });
+    }
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: options.method,
+        signal: controller.signal,
+        headers: {
+          'Accept': 'application/json',
+        },
+      });
+
+      clearTimeout(timeoutId);
+
+      const data = await response.json() as StackExchangeWrapper<T>;
+
+      // Handle API errors
+      if (data.error_id) {
+        throw new Error(
+          `Stack Exchange API Error (${data.error_id} - ${data.error_name}): ${data.error_message}`,
+        );
+      }
+
+      // Update quota tracking
+      this.quotaRemaining = data.quota_remaining;
+      this.quotaMax = data.quota_max;
+      this.requestCount++;
+
+      // Handle backoff
+      if (data.backoff) {
+        this.lastBackoff = Date.now() + (data.backoff * 1000);
+        logger.warn(`[StackExchange] Backoff required: ${data.backoff} seconds`);
+      }
+
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this._timeout}ms`, { cause: error });
+      }
+
+      throw error;
+    }
+  }
+
+  getQuotaInfo(): { remaining: number; max: number; requestCount: number; lastBackoff: number | null } {
+    return {
+      remaining: this.quotaRemaining,
+      max: this.quotaMax,
+      requestCount: this.requestCount,
+      lastBackoff: this.lastBackoff,
+    };
+  }
+
+  isQuotaExhausted(): boolean {
+    return this.quotaRemaining <= 0;
+  }
+
+  isQuotaLow(): boolean {
+    return this.quotaRemaining < 30; // Warn when less than 30 requests remain
+  }
+}

package/src/stackexchange/types.ts

@@ -0,0 +1,129 @@
+/**
+ * Stack Exchange API v2.3 Types
+ */
+
+export interface StackExchangeConfig {
+  defaultSite: string;
+  apiKey: string | null;
+  requestTimeout: number;  // milliseconds
+}
+
+export interface StackExchangeWrapper<T> {
+  items: T[];
+  has_more: boolean;
+  quota_max: number;
+  quota_remaining: number;
+  backoff?: number;
+  error_id?: number;
+  error_name?: string;
+  error_message?: string;
+}
+
+export type SortOrder = 'desc' | 'asc';
+export type SortActivity = 'activity' | 'creation' | 'votes' | 'relevance';
+export type SortReputation = 'reputation' | 'creation' | 'name' | 'modified';
+
+// Question types
+export interface Question {
+  tags: string[];
+  owner?: {
+    account_id: number;
+    reputation: number;
+    user_id: number;
+    user_type: string;
+    profile_image: string;
+    display_name: string;
+    link: string;
+  };
+  is_answered: boolean;
+  view_count: number;
+  accepted_answer_id?: number;
+  answer_count: number;
+  score: number;
+  last_activity_date: number;
+  creation_date: number;
+  last_edit_date?: number;
+  question_id: number;
+  content_license: string;
+  link: string;
+  title: string;
+  body?: string;
+  body_markdown?: string;
+}
+
+export interface QuestionWithAnswers extends Question {
+  answers?: Answer[];
+}
+
+export interface Answer {
+  owner?: {
+    account_id: number;
+    reputation: number;
+    user_id: number;
+    user_type: string;
+    profile_image: string;
+    display_name: string;
+    link: string;
+  };
+  is_accepted: boolean;
+  score: number;
+  last_activity_date: number;
+  creation_date: number;
+  last_edit_date?: number;
+  answer_id: number;
+  question_id: number;
+  content_license: string;
+  body?: string;
+  body_markdown?: string;
+}
+
+// User types
+export interface User {
+  badge_counts: {
+    bronze: number;
+    silver: number;
+    gold: number;
+  };
+  account_id: number;
+  is_employee: boolean;
+  last_modified_date?: number;
+  last_access_date?: number;
+  reputation_change_year: number;
+  reputation_change_quarter: number;
+  reputation_change_month: number;
+  reputation_change_week: number;
+  reputation_change_day: number;
+  reputation: number;
+  creation_date: number;
+  user_type: string;
+  user_id: number;
+  accept_rate?: number;
+  location?: string;
+  website_url?: string;
+  link: string;
+  profile_image: string;
+  display_name: string;
+}
+
+// Site types
+export interface Site {
+  name: string;
+  api_site_parameter: string;
+  site_url: string;
+  audience: string;
+  icon_url?: string;
+}
+
+// Command parameters
+export interface CommandParams {
+  command: 'search' | 'get' | 'user' | 'site';
+  query?: string;
+  id?: string | number;
+  site: string;
+  limit: number;
+  format: 'table' | 'json' | 'compact';
+  tags?: string | null;
+  full: boolean;
+  minimal: boolean;
+}
+