@hasna/connectors 1.0.5 → 1.0.6

package/connectors/connect-patentsview/src/api/cpc.ts

@@ -0,0 +1,191 @@
+import type { PatentsViewClient } from './client';
+import type {
+  CPCSubgroup,
+  CPCSearchResponse,
+  CPCGetResponse,
+  QueryObject,
+  QueryOptions,
+  SearchRequest,
+} from '../types';
+import { DEFAULT_CPC_FIELDS } from '../types';
+
+/**
+ * CPC API - Search and retrieve CPC (Cooperative Patent Classification) data
+ */
+export class CPCApi {
+  constructor(private readonly client: PatentsViewClient) {}
+
+  /**
+   * Search CPC subgroups with filters
+   * @param query - Query object with filters
+   * @param fields - Fields to return (defaults to common fields)
+   * @param options - Pagination and sorting options
+   */
+  async search(
+    query?: QueryObject,
+    fields?: string[],
+    options?: QueryOptions
+  ): Promise<CPCSearchResponse> {
+    const body: SearchRequest = {};
+
+    if (query) {
+      body.q = query;
+    }
+
+    body.f = fields || DEFAULT_CPC_FIELDS;
+
+    if (options) {
+      body.o = options;
+    }
+
+    return this.client.post<CPCSearchResponse>('/cpc_subgroup/', body);
+  }
+
+  /**
+   * Get a single CPC subgroup by ID
+   * @param cpcSubgroupId - The CPC subgroup ID (e.g., "G06F3/01")
+   * @param fields - Fields to return
+   */
+  async get(cpcSubgroupId: string, fields?: string[]): Promise<CPCSubgroup | null> {
+    const response = await this.client.get<CPCGetResponse>(
+      `/cpc_subgroup/${encodeURIComponent(cpcSubgroupId)}/`,
+      fields ? { f: fields.join(',') } : undefined
+    );
+    return response.cpc_subgroups?.[0] || null;
+  }
+
+  /**
+   * Search CPC by title text
+   * @param title - Text to search in CPC titles
+   * @param options - Pagination options
+   */
+  async searchByTitle(title: string, options?: QueryOptions): Promise<CPCSearchResponse> {
+    return this.search(
+      { cpc_subgroup_title: { _text_any: title } },
+      undefined,
+      options
+    );
+  }
+
+  /**
+   * Search CPC by section
+   * @param sectionId - CPC section ID (e.g., "A", "B", "C", "G", "H")
+   * @param options - Pagination options
+   */
+  async searchBySection(sectionId: string, options?: QueryOptions): Promise<CPCSearchResponse> {
+    return this.search(
+      { cpc_section_id: { _eq: sectionId.toUpperCase() } },
+      [...DEFAULT_CPC_FIELDS, 'cpc_section_title'],
+      options
+    );
+  }
+
+  /**
+   * Search CPC by class
+   * @param classId - CPC class ID (e.g., "G06")
+   * @param options - Pagination options
+   */
+  async searchByClass(classId: string, options?: QueryOptions): Promise<CPCSearchResponse> {
+    return this.search(
+      { cpc_class_id: { _eq: classId.toUpperCase() } },
+      [...DEFAULT_CPC_FIELDS, 'cpc_class_title'],
+      options
+    );
+  }
+
+  /**
+   * Search CPC by subclass
+   * @param subclassId - CPC subclass ID (e.g., "G06F")
+   * @param options - Pagination options
+   */
+  async searchBySubclass(subclassId: string, options?: QueryOptions): Promise<CPCSearchResponse> {
+    return this.search(
+      { cpc_subclass_id: { _eq: subclassId.toUpperCase() } },
+      [...DEFAULT_CPC_FIELDS, 'cpc_subclass_title'],
+      options
+    );
+  }
+
+  /**
+   * Search CPC by group
+   * @param groupId - CPC group ID (e.g., "G06F3/00")
+   * @param options - Pagination options
+   */
+  async searchByGroup(groupId: string, options?: QueryOptions): Promise<CPCSearchResponse> {
+    return this.search(
+      { cpc_group_id: { _eq: groupId } },
+      [...DEFAULT_CPC_FIELDS, 'cpc_group_title'],
+      options
+    );
+  }
+
+  /**
+   * Get top CPC subgroups by patent count
+   * @param limit - Number of subgroups to return
+   */
+  async getTopByPatentCount(limit = 25): Promise<CPCSearchResponse> {
+    return this.search(
+      undefined,
+      [...DEFAULT_CPC_FIELDS, 'cpc_num_patents'],
+      {
+        per_page: limit,
+        sort: [{ cpc_num_patents: 'desc' }],
+      }
+    );
+  }
+
+  /**
+   * Search CPC subgroups by ID prefix
+   * @param prefix - ID prefix (e.g., "G06F" to find all G06F classifications)
+   * @param options - Pagination options
+   */
+  async searchByIdPrefix(prefix: string, options?: QueryOptions): Promise<CPCSearchResponse> {
+    return this.search(
+      { cpc_subgroup_id: { _begins: prefix.toUpperCase() } },
+      undefined,
+      options
+    );
+  }
+
+  /**
+   * Get all CPC sections
+   * This returns subgroups grouped by their section, useful for understanding the hierarchy
+   */
+  async getSections(): Promise<CPCSearchResponse> {
+    // Search for one representative from each section
+    const sections = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'Y'];
+    const results: CPCSubgroup[] = [];
+
+    for (const section of sections) {
+      const response = await this.search(
+        { cpc_section_id: { _eq: section } },
+        ['cpc_section_id', 'cpc_section_title'],
+        { per_page: 1 }
+      );
+      if (response.cpc_subgroups?.[0]) {
+        results.push(response.cpc_subgroups[0]);
+      }
+    }
+
+    return {
+      cpc_subgroups: results,
+      count: results.length,
+      total_hits: results.length,
+    };
+  }
+
+  /**
+   * CPC Section descriptions for reference
+   */
+  static readonly CPC_SECTIONS: Record<string, string> = {
+    'A': 'Human Necessities',
+    'B': 'Performing Operations; Transporting',
+    'C': 'Chemistry; Metallurgy',
+    'D': 'Textiles; Paper',
+    'E': 'Fixed Constructions',
+    'F': 'Mechanical Engineering; Lighting; Heating; Weapons; Blasting',
+    'G': 'Physics',
+    'H': 'Electricity',
+    'Y': 'General Tagging of New Technological Developments',
+  };
+}

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

@@ -0,0 +1,73 @@
+import type { PatentsViewConfig } from '../types';
+import { PatentsViewClient } from './client';
+import { PatentsApi } from './patents';
+import { AssigneesApi } from './assignees';
+import { InventorsApi } from './inventors';
+import { CPCApi } from './cpc';
+import { LocationsApi } from './locations';
+
+/**
+ * Main PatentsView connector class
+ * Provides access to USPTO patent data via the PatentsView API
+ */
+export class PatentsView {
+  private readonly client: PatentsViewClient;
+
+  // API modules
+  public readonly patents: PatentsApi;
+  public readonly assignees: AssigneesApi;
+  public readonly inventors: InventorsApi;
+  public readonly cpc: CPCApi;
+  public readonly locations: LocationsApi;
+
+  constructor(config: PatentsViewConfig = {}) {
+    this.client = new PatentsViewClient(config);
+    this.patents = new PatentsApi(this.client);
+    this.assignees = new AssigneesApi(this.client);
+    this.inventors = new InventorsApi(this.client);
+    this.cpc = new CPCApi(this.client);
+    this.locations = new LocationsApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for PATENTSVIEW_API_KEY and optionally PATENTSVIEW_BASE_URL
+   */
+  static fromEnv(): PatentsView {
+    const apiKey = process.env.PATENTSVIEW_API_KEY;
+    const baseUrl = process.env.PATENTSVIEW_BASE_URL;
+
+    if (!apiKey) {
+      throw new Error('PATENTSVIEW_API_KEY environment variable is required');
+    }
+    return new PatentsView({ apiKey, baseUrl });
+  }
+
+  /**
+   * Get the base URL (for debugging)
+   */
+  getBaseUrl(): string {
+    return this.client.getBaseUrl();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): PatentsViewClient {
+    return this.client;
+  }
+
+  /**
+   * Get a preview of the API key (for debugging)
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+}
+
+export { PatentsViewClient } from './client';
+export { PatentsApi } from './patents';
+export { AssigneesApi } from './assignees';
+export { InventorsApi } from './inventors';
+export { CPCApi } from './cpc';
+export { LocationsApi } from './locations';

package/connectors/connect-patentsview/src/api/inventors.ts

@@ -0,0 +1,176 @@
+import type { PatentsViewClient } from './client';
+import type {
+  Inventor,
+  InventorSearchResponse,
+  InventorGetResponse,
+  QueryObject,
+  QueryOptions,
+  SearchRequest,
+} from '../types';
+import { DEFAULT_INVENTOR_FIELDS } from '../types';
+
+/**
+ * Inventors API - Search and retrieve inventor data
+ */
+export class InventorsApi {
+  constructor(private readonly client: PatentsViewClient) {}
+
+  /**
+   * Search inventors with filters
+   * @param query - Query object with filters
+   * @param fields - Fields to return (defaults to common fields)
+   * @param options - Pagination and sorting options
+   */
+  async search(
+    query?: QueryObject,
+    fields?: string[],
+    options?: QueryOptions
+  ): Promise<InventorSearchResponse> {
+    const body: SearchRequest = {};
+
+    if (query) {
+      body.q = query;
+    }
+
+    body.f = fields || DEFAULT_INVENTOR_FIELDS;
+
+    if (options) {
+      body.o = options;
+    }
+
+    return this.client.post<InventorSearchResponse>('/inventor/', body);
+  }
+
+  /**
+   * Get a single inventor by ID
+   * @param inventorId - The inventor ID
+   * @param fields - Fields to return
+   */
+  async get(inventorId: string, fields?: string[]): Promise<Inventor | null> {
+    const response = await this.client.get<InventorGetResponse>(
+      `/inventor/${inventorId}/`,
+      fields ? { f: fields.join(',') } : undefined
+    );
+    return response.inventors?.[0] || null;
+  }
+
+  /**
+   * Search inventors by name
+   * @param lastName - Last name
+   * @param firstName - First name (optional)
+   * @param options - Pagination options
+   */
+  async searchByName(
+    lastName: string,
+    firstName?: string,
+    options?: QueryOptions
+  ): Promise<InventorSearchResponse> {
+    const query: QueryObject = {
+      inventor_name_last: { _eq: lastName },
+    };
+
+    if (firstName) {
+      query.inventor_name_first = { _eq: firstName };
+    }
+
+    return this.search(query, undefined, options);
+  }
+
+  /**
+   * Search inventors by location
+   * @param country - Country code
+   * @param state - State (optional)
+   * @param city - City (optional)
+   * @param options - Pagination options
+   */
+  async searchByLocation(
+    country: string,
+    state?: string,
+    city?: string,
+    options?: QueryOptions
+  ): Promise<InventorSearchResponse> {
+    const conditions: QueryObject[] = [
+      { inventor_country: { _eq: country } },
+    ];
+
+    if (state) {
+      conditions.push({ inventor_state: { _eq: state } });
+    }
+
+    if (city) {
+      conditions.push({ inventor_city: { _eq: city } });
+    }
+
+    return this.search(
+      conditions.length > 1 ? { _and: conditions } : conditions[0],
+      undefined,
+      options
+    );
+  }
+
+  /**
+   * Get top inventors by patent count
+   * @param limit - Number of inventors to return
+   */
+  async getTopByPatentCount(limit = 25): Promise<InventorSearchResponse> {
+    return this.search(
+      undefined,
+      [...DEFAULT_INVENTOR_FIELDS, 'inventor_num_patents'],
+      {
+        per_page: limit,
+        sort: [{ inventor_num_patents: 'desc' }],
+      }
+    );
+  }
+
+  /**
+   * Get prolific inventors (more than N patents)
+   * @param minPatents - Minimum number of patents
+   * @param options - Pagination options
+   */
+  async getProlific(minPatents = 100, options?: QueryOptions): Promise<InventorSearchResponse> {
+    return this.search(
+      { inventor_num_patents: { _gte: minPatents } },
+      [...DEFAULT_INVENTOR_FIELDS, 'inventor_num_patents'],
+      {
+        ...options,
+        sort: [{ inventor_num_patents: 'desc' }],
+      }
+    );
+  }
+
+  /**
+   * Search inventors by years active
+   * @param minYears - Minimum years active
+   * @param options - Pagination options
+   */
+  async searchByYearsActive(minYears: number, options?: QueryOptions): Promise<InventorSearchResponse> {
+    return this.search(
+      { inventor_years_active: { _gte: minYears } },
+      [...DEFAULT_INVENTOR_FIELDS, 'inventor_years_active', 'inventor_first_seen_date', 'inventor_last_seen_date'],
+      options
+    );
+  }
+
+  /**
+   * Search inventors by last name prefix
+   * @param prefix - Name prefix
+   * @param options - Pagination options
+   */
+  async searchByNamePrefix(prefix: string, options?: QueryOptions): Promise<InventorSearchResponse> {
+    return this.search(
+      { inventor_name_last: { _begins: prefix } },
+      undefined,
+      options
+    );
+  }
+
+  /**
+   * Get inventors from US
+   * @param state - State filter (optional)
+   * @param options - Pagination options
+   */
+  async getUSInventors(state?: string, options?: QueryOptions): Promise<InventorSearchResponse> {
+    return this.searchByLocation('US', state, undefined, options);
+  }
+}

package/connectors/connect-patentsview/src/api/locations.ts

@@ -0,0 +1,200 @@
+import type { PatentsViewClient } from './client';
+import type {
+  Location,
+  LocationSearchResponse,
+  QueryObject,
+  QueryOptions,
+  SearchRequest,
+} from '../types';
+import { DEFAULT_LOCATION_FIELDS } from '../types';
+
+/**
+ * Locations API - Search and retrieve location data
+ */
+export class LocationsApi {
+  constructor(private readonly client: PatentsViewClient) {}
+
+  /**
+   * Search locations with filters
+   * @param query - Query object with filters
+   * @param fields - Fields to return (defaults to common fields)
+   * @param options - Pagination and sorting options
+   */
+  async search(
+    query?: QueryObject,
+    fields?: string[],
+    options?: QueryOptions
+  ): Promise<LocationSearchResponse> {
+    const body: SearchRequest = {};
+
+    if (query) {
+      body.q = query;
+    }
+
+    body.f = fields || DEFAULT_LOCATION_FIELDS;
+
+    if (options) {
+      body.o = options;
+    }
+
+    return this.client.post<LocationSearchResponse>('/location/', body);
+  }
+
+  /**
+   * Search locations by country
+   * @param country - Country code (e.g., "US", "JP", "DE")
+   * @param options - Pagination options
+   */
+  async searchByCountry(country: string, options?: QueryOptions): Promise<LocationSearchResponse> {
+    return this.search(
+      { location_country: { _eq: country.toUpperCase() } },
+      undefined,
+      options
+    );
+  }
+
+  /**
+   * Search locations by state (US only)
+   * @param state - State code (e.g., "CA", "NY", "TX")
+   * @param options - Pagination options
+   */
+  async searchByState(state: string, options?: QueryOptions): Promise<LocationSearchResponse> {
+    return this.search(
+      {
+        _and: [
+          { location_country: { _eq: 'US' } },
+          { location_state: { _eq: state.toUpperCase() } },
+        ],
+      },
+      undefined,
+      options
+    );
+  }
+
+  /**
+   * Search locations by city
+   * @param city - City name
+   * @param country - Country code (optional)
+   * @param state - State code (optional, for US)
+   * @param options - Pagination options
+   */
+  async searchByCity(
+    city: string,
+    country?: string,
+    state?: string,
+    options?: QueryOptions
+  ): Promise<LocationSearchResponse> {
+    const conditions: QueryObject[] = [
+      { location_city: { _contains: city } },
+    ];
+
+    if (country) {
+      conditions.push({ location_country: { _eq: country.toUpperCase() } });
+    }
+
+    if (state) {
+      conditions.push({ location_state: { _eq: state.toUpperCase() } });
+    }
+
+    return this.search(
+      conditions.length > 1 ? { _and: conditions } : conditions[0],
+      undefined,
+      options
+    );
+  }
+
+  /**
+   * Get top locations by patent count
+   * @param limit - Number of locations to return
+   */
+  async getTopByPatentCount(limit = 25): Promise<LocationSearchResponse> {
+    return this.search(
+      undefined,
+      [...DEFAULT_LOCATION_FIELDS, 'location_latitude', 'location_longitude'],
+      {
+        per_page: limit,
+        sort: [{ location_num_patents: 'desc' }],
+      }
+    );
+  }
+
+  /**
+   * Get top locations by inventor count
+   * @param limit - Number of locations to return
+   */
+  async getTopByInventorCount(limit = 25): Promise<LocationSearchResponse> {
+    return this.search(
+      undefined,
+      [...DEFAULT_LOCATION_FIELDS, 'location_latitude', 'location_longitude'],
+      {
+        per_page: limit,
+        sort: [{ location_num_inventors: 'desc' }],
+      }
+    );
+  }
+
+  /**
+   * Get top US cities by patent count
+   * @param limit - Number of cities to return
+   */
+  async getTopUSCities(limit = 25): Promise<LocationSearchResponse> {
+    return this.search(
+      { location_country: { _eq: 'US' } },
+      DEFAULT_LOCATION_FIELDS,
+      {
+        per_page: limit,
+        sort: [{ location_num_patents: 'desc' }],
+      }
+    );
+  }
+
+  /**
+   * Get locations in a specific US state, sorted by patent count
+   * @param state - State code
+   * @param limit - Number of locations to return
+   */
+  async getTopCitiesInState(state: string, limit = 25): Promise<LocationSearchResponse> {
+    return this.search(
+      {
+        _and: [
+          { location_country: { _eq: 'US' } },
+          { location_state: { _eq: state.toUpperCase() } },
+        ],
+      },
+      DEFAULT_LOCATION_FIELDS,
+      {
+        per_page: limit,
+        sort: [{ location_num_patents: 'desc' }],
+      }
+    );
+  }
+
+  /**
+   * Search locations by coordinates (bounding box)
+   * @param minLat - Minimum latitude
+   * @param maxLat - Maximum latitude
+   * @param minLon - Minimum longitude
+   * @param maxLon - Maximum longitude
+   * @param options - Pagination options
+   */
+  async searchByBoundingBox(
+    minLat: number,
+    maxLat: number,
+    minLon: number,
+    maxLon: number,
+    options?: QueryOptions
+  ): Promise<LocationSearchResponse> {
+    return this.search(
+      {
+        _and: [
+          { location_latitude: { _gte: minLat } },
+          { location_latitude: { _lte: maxLat } },
+          { location_longitude: { _gte: minLon } },
+          { location_longitude: { _lte: maxLon } },
+        ],
+      },
+      [...DEFAULT_LOCATION_FIELDS, 'location_latitude', 'location_longitude'],
+      options
+    );
+  }
+}