@hasna/connectors 0.0.1

package/connectors/connect-uspto/src/api/client.ts

@@ -0,0 +1,186 @@
+import type { USPTOConfig } from '../types';
+import { USPTOApiError } from '../types';
+
+// USPTO has multiple API endpoints
+const API_ENDPOINTS = {
+  ODP: 'https://data.uspto.gov/api/v1',
+  PEDS: 'https://ped.uspto.gov/api',
+  PTAB: 'https://developer.uspto.gov/ptab-api/proceedings',
+  PATENT_ASSIGNMENT: 'https://assignment-api.uspto.gov/patent/lookup',
+  TRADEMARK_ASSIGNMENT: 'https://assignment-api.uspto.gov/trademark/lookup',
+  TSDR: 'https://tsdrapi.uspto.gov',
+};
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+  responseType?: 'json' | 'xml' | 'text' | 'arraybuffer';
+}
+
+export class USPTOClient {
+  private readonly apiKey?: string;
+  private readonly baseUrl: string;
+
+  constructor(config: USPTOConfig = {}) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || API_ENDPOINTS.ODP;
+  }
+
+  private buildUrl(
+    baseUrl: string,
+    path: string,
+    params?: Record<string, string | number | boolean | undefined>
+  ): string {
+    const url = new URL(`${baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make a request to a USPTO API endpoint
+   */
+  async request<T>(
+    endpoint: keyof typeof API_ENDPOINTS | string,
+    path: string,
+    options: RequestOptions = {}
+  ): Promise<T> {
+    const { method = 'GET', params, body, headers = {}, responseType = 'json' } = options;
+
+    const baseUrl = typeof endpoint === 'string' && endpoint.startsWith('http')
+      ? endpoint
+      : API_ENDPOINTS[endpoint as keyof typeof API_ENDPOINTS] || this.baseUrl;
+
+    const url = this.buildUrl(baseUrl, path, params);
+
+    const requestHeaders: Record<string, string> = {
+      'Accept': responseType === 'xml' ? 'application/xml' : 'application/json',
+      ...headers,
+    };
+
+    // Add API key if available
+    if (this.apiKey) {
+      requestHeaders['X-Api-Key'] = this.apiKey;
+    }
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Handle different response types
+    if (responseType === 'arraybuffer') {
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new USPTOApiError(errorText, response.status);
+      }
+      return (await response.arrayBuffer()) as unknown as T;
+    }
+
+    if (responseType === 'text' || responseType === 'xml') {
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new USPTOApiError(errorText, response.status);
+      }
+      return (await response.text()) as unknown as T;
+    }
+
+    // Parse JSON response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else if (contentType.includes('application/xml') || contentType.includes('text/xml')) {
+      data = await response.text();
+    } else {
+      data = await response.text();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorMessage = typeof data === 'object' && data !== null
+        ? JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new USPTOApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  // Convenience methods for specific endpoints
+  async odpGet<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('ODP', path, { method: 'GET', params });
+  }
+
+  async pedsGet<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('PEDS', path, { method: 'GET', params });
+  }
+
+  async ptabGet<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('PTAB', path, { method: 'GET', params });
+  }
+
+  async tsdrGet<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('TSDR', path, { method: 'GET', params });
+  }
+
+  async patentAssignmentGet<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('PATENT_ASSIGNMENT', path, { method: 'GET', params });
+  }
+
+  async trademarkAssignmentGet<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>('TRADEMARK_ASSIGNMENT', path, { method: 'GET', params });
+  }
+
+  /**
+   * Get a preview of the API key (for display/debugging)
+   */
+  getApiKeyPreview(): string {
+    if (!this.apiKey) {
+      return '(no key)';
+    }
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+
+  /**
+   * Get available API endpoints
+   */
+  static getEndpoints(): Record<string, string> {
+    return { ...API_ENDPOINTS };
+  }
+}

package/connectors/connect-uspto/src/api/index.ts

@@ -0,0 +1,104 @@
+import type { USPTOConfig } from '../types';
+import { USPTOClient } from './client';
+import { PatentsApi } from './patents';
+import { TrademarksApi } from './trademarks';
+import { PTABApi } from './ptab';
+import { BrowserApi } from './browser';
+
+/**
+ * Main USPTO connector class
+ */
+export class USPTO {
+  private readonly client: USPTOClient;
+  private readonly config: USPTOConfig;
+
+  // API modules
+  public readonly patents: PatentsApi;
+  public readonly trademarks: TrademarksApi;
+  public readonly ptab: PTABApi;
+  public readonly browser: BrowserApi;
+
+  constructor(config: USPTOConfig = {}) {
+    this.config = config;
+    this.client = new USPTOClient(config);
+    this.patents = new PatentsApi(this.client);
+    this.trademarks = new TrademarksApi(this.client);
+    this.ptab = new PTABApi(this.client);
+    this.browser = new BrowserApi(config);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for USPTO_API_KEY or USPTO_TOKEN
+   */
+  static fromEnv(): USPTO {
+    const apiKey = process.env.USPTO_API_KEY || process.env.USPTO_TOKEN;
+    const headless = process.env.USPTO_HEADLESS !== 'false';
+    const browser = process.env.USPTO_BROWSER as USPTOConfig['browser'];
+
+    return new USPTO({ apiKey, headless, browser });
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): USPTOClient {
+    return this.client;
+  }
+
+  /**
+   * Close browser resources
+   */
+  async close(): Promise<void> {
+    await this.browser.close();
+  }
+
+  /**
+   * Quick patent search
+   */
+  async searchPatents(query: string, rows = 25) {
+    return this.patents.search({ query, rows });
+  }
+
+  /**
+   * Quick trademark search
+   */
+  async searchTrademarks(query: string, rows = 25) {
+    return this.trademarks.search({ query, rows });
+  }
+
+  /**
+   * Check trademark availability (API + TESS)
+   */
+  async checkTrademarkAvailability(markText: string): Promise<{
+    apiCheck: { available: boolean; conflicts: unknown[] };
+    tessCheck?: { available: boolean; conflicts: unknown[] };
+  }> {
+    const apiCheck = await this.trademarks.checkAvailability(markText);
+
+    let tessCheck;
+    try {
+      tessCheck = await this.browser.checkTrademarkAvailability(markText);
+    } catch {
+      // TESS may fail if browser not available
+    }
+
+    return {
+      apiCheck,
+      tessCheck,
+    };
+  }
+}
+
+export { USPTOClient } from './client';
+export { PatentsApi } from './patents';
+export { TrademarksApi } from './trademarks';
+export { PTABApi } from './ptab';
+export { BrowserApi } from './browser';

package/connectors/connect-uspto/src/api/patents.ts

@@ -0,0 +1,290 @@
+import type {
+  PatentSearchParams,
+  PatentSearchResponse,
+  Patent,
+  PatentFileWrapper,
+  PatentAssignment,
+  PatentDocument,
+} from '../types';
+import { USPTOClient } from './client';
+
+/**
+ * Patents API - Search patents, get file wrappers, assignments
+ */
+export class PatentsApi {
+  constructor(private readonly client: USPTOClient) {}
+
+  /**
+   * Search patents using Open Data Portal
+   */
+  async search(params: PatentSearchParams): Promise<PatentSearchResponse> {
+    const queryParams: Record<string, string | number | boolean | undefined> = {
+      q: params.query,
+      start: params.start || 0,
+      rows: params.rows || 25,
+    };
+
+    if (params.sort) queryParams.sort = params.sort;
+    if (params.facet !== undefined) queryParams.facet = params.facet;
+    if (params.fl) queryParams.fl = params.fl.join(',');
+
+    const response = await this.client.odpGet<{
+      response?: {
+        numFound?: number;
+        start?: number;
+        docs?: unknown[];
+      };
+      results?: unknown[];
+      total?: number;
+    }>('/patents/search', queryParams);
+
+    // Handle different response formats
+    const docs = response.response?.docs || response.results || [];
+    const total = response.response?.numFound || response.total || 0;
+    const start = response.response?.start || params.start || 0;
+
+    return {
+      total,
+      start,
+      rows: params.rows || 25,
+      patents: docs.map(this.mapPatent),
+    };
+  }
+
+  /**
+   * Get patent by number
+   */
+  async getByNumber(patentNumber: string): Promise<Patent | null> {
+    const cleanNumber = patentNumber.replace(/[^0-9]/g, '');
+
+    const response = await this.client.odpGet<{
+      response?: { docs?: unknown[] };
+      patent?: unknown;
+    }>(`/patents/${cleanNumber}`);
+
+    const doc = response.response?.docs?.[0] || response.patent;
+    if (!doc) return null;
+
+    return this.mapPatent(doc);
+  }
+
+  /**
+   * Get patent file wrapper (PEDS - Patent Examination Data System)
+   */
+  async getFileWrapper(applicationNumber: string): Promise<PatentFileWrapper | null> {
+    const cleanNumber = applicationNumber.replace(/[^0-9]/g, '');
+
+    try {
+      const response = await this.client.pedsGet<{
+        queryResults?: {
+          searchResponse?: {
+            response?: {
+              docs?: Array<{
+                appFilingDate?: string;
+                appStatus?: string;
+                appType?: string;
+                continuityData?: unknown[];
+                transactionHistory?: unknown[];
+              }>;
+            };
+          };
+        };
+      }>('/queries', {
+        searchText: `applId:${cleanNumber}`,
+        df: 'patentTitle',
+        facet: false,
+        sort: 'applId asc',
+        fl: '*',
+      });
+
+      const doc = response.queryResults?.searchResponse?.response?.docs?.[0];
+      if (!doc) return null;
+
+      return {
+        applicationNumber: cleanNumber,
+        filingDate: doc.appFilingDate || '',
+        status: doc.appStatus || '',
+        applicationType: doc.appType || '',
+        documents: [],
+        continuity: (doc.continuityData || []).map((c: unknown) => {
+          const cont = c as Record<string, unknown>;
+          return {
+            parentApplicationNumber: String(cont.parentApplicationId || ''),
+            parentFilingDate: String(cont.parentFilingDate || ''),
+            claimType: String(cont.claimType || ''),
+            description: String(cont.description || ''),
+          };
+        }),
+        transactions: (doc.transactionHistory || []).map((t: unknown) => {
+          const trans = t as Record<string, unknown>;
+          return {
+            date: String(trans.recordDate || ''),
+            code: String(trans.code || ''),
+            description: String(trans.description || ''),
+          };
+        }),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get documents for a patent application
+   */
+  async getDocuments(applicationNumber: string): Promise<PatentDocument[]> {
+    const cleanNumber = applicationNumber.replace(/[^0-9]/g, '');
+
+    try {
+      const response = await this.client.odpGet<{
+        documents?: Array<{
+          documentIdentifier?: string;
+          documentCategory?: string;
+          mailRoomDate?: string;
+          pageCount?: number;
+        }>;
+      }>(`/patent-file-wrapper/documents/${cleanNumber}`);
+
+      return (response.documents || []).map(doc => ({
+        documentId: doc.documentIdentifier || '',
+        documentType: doc.documentCategory || '',
+        mailDate: doc.mailRoomDate,
+        pageCount: doc.pageCount,
+        downloadUrl: `https://data.uspto.gov/api/v1/patent-file-wrapper/documents/${cleanNumber}/${doc.documentIdentifier}/download`,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Search patent assignments
+   */
+  async searchAssignments(params: {
+    patentNumber?: string;
+    assignee?: string;
+    assignor?: string;
+  }): Promise<PatentAssignment[]> {
+    const queryParams: Record<string, string | undefined> = {};
+
+    if (params.patentNumber) {
+      queryParams.filter = `PatentNumber:${params.patentNumber}`;
+    } else if (params.assignee) {
+      queryParams.filter = `AssigneeName:${params.assignee}`;
+    } else if (params.assignor) {
+      queryParams.filter = `AssignorName:${params.assignor}`;
+    }
+
+    try {
+      const response = await this.client.patentAssignmentGet<{
+        results?: Array<{
+          reelFrame?: string;
+          recordedDate?: string;
+          executionDate?: string;
+          assignorName?: string;
+          assigneeName?: string;
+          conveyanceText?: string;
+          patentNumbers?: string[];
+          applicationNumbers?: string[];
+        }>;
+      }>('', queryParams);
+
+      return (response.results || []).map(r => ({
+        reelFrame: r.reelFrame || '',
+        recordDate: r.recordedDate || '',
+        executionDate: r.executionDate,
+        assignor: r.assignorName || '',
+        assignee: r.assigneeName || '',
+        conveyanceText: r.conveyanceText,
+        patentNumbers: r.patentNumbers,
+        applicationNumbers: r.applicationNumbers,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Get patent claims
+   */
+  async getClaims(patentNumber: string): Promise<string[]> {
+    const patent = await this.getByNumber(patentNumber);
+    return patent?.claims || [];
+  }
+
+  /**
+   * Get patent citations
+   */
+  async getCitations(patentNumber: string): Promise<Patent['citations']> {
+    const patent = await this.getByNumber(patentNumber);
+    return patent?.citations || [];
+  }
+
+  private mapPatent(doc: unknown): Patent {
+    const d = doc as Record<string, unknown>;
+    return {
+      patentNumber: String(d.patentNumber || d.patent_number || d.documentId || ''),
+      publicationNumber: d.publicationNumber as string | undefined,
+      applicationNumber: String(d.applicationNumber || d.app_number || ''),
+      title: String(d.patentTitle || d.title || d.inventionTitle || ''),
+      abstract: d.abstract as string | undefined,
+      inventors: Array.isArray(d.inventors)
+        ? d.inventors.map(String)
+        : d.inventorName
+          ? [String(d.inventorName)]
+          : undefined,
+      assignees: Array.isArray(d.assignees)
+        ? d.assignees.map(String)
+        : d.assigneeName
+          ? [String(d.assigneeName)]
+          : undefined,
+      filingDate: d.filingDate as string | undefined,
+      publicationDate: d.publicationDate as string | undefined,
+      grantDate: d.grantDate as string | undefined,
+      claims: Array.isArray(d.claims) ? d.claims.map(String) : undefined,
+      classifications: this.mapClassifications(d),
+      citations: this.mapCitations(d),
+      status: d.status as string | undefined,
+      type: d.patentType as Patent['type'],
+    };
+  }
+
+  private mapClassifications(d: Record<string, unknown>): Patent['classifications'] {
+    const classifications: Patent['classifications'] = [];
+
+    if (Array.isArray(d.cpcCodes)) {
+      d.cpcCodes.forEach((code: unknown) => {
+        classifications.push({ type: 'CPC', code: String(code) });
+      });
+    }
+
+    if (Array.isArray(d.ipcCodes)) {
+      d.ipcCodes.forEach((code: unknown) => {
+        classifications.push({ type: 'IPC', code: String(code) });
+      });
+    }
+
+    if (Array.isArray(d.uspcCodes)) {
+      d.uspcCodes.forEach((code: unknown) => {
+        classifications.push({ type: 'USPC', code: String(code) });
+      });
+    }
+
+    return classifications.length > 0 ? classifications : undefined;
+  }
+
+  private mapCitations(d: Record<string, unknown>): Patent['citations'] {
+    if (!Array.isArray(d.citations)) return undefined;
+
+    return d.citations.map((c: unknown) => {
+      const cit = c as Record<string, unknown>;
+      return {
+        patentNumber: cit.patentNumber as string | undefined,
+        publicationNumber: cit.publicationNumber as string | undefined,
+        date: cit.date as string | undefined,
+        name: cit.name as string | undefined,
+        category: (cit.category as 'patent' | 'non-patent') || 'patent',
+      };
+    });
+  }
+}