@hasna/connectors 0.9.2 → 0.9.3

package/connectors/connect-epo/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/connect-epo",
+  "version": "0.0.1",
+  "description": "EPO Open Patent Services (OPS) API connector - Search and retrieve European patent data",
+  "type": "module",
+  "bin": {
+    "connect-epo": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "epo",
+    "patent",
+    "european-patent-office",
+    "ops",
+    "open-patent-services",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connectors.git"
+  }
+}

package/connectors/connect-epo/src/api/classification.ts

@@ -0,0 +1,226 @@
+import type { EPOClient } from './client';
+import type {
+  CPCClassificationResponse,
+  CPCNode,
+} from '../types';
+
+/**
+ * Classification API - Access CPC classification data
+ */
+export class ClassificationApi {
+  constructor(private readonly client: EPOClient) {}
+
+  /**
+   * Get CPC classification hierarchy
+   * @param symbol - CPC symbol to look up (e.g., "H01L", "A01B1/00")
+   */
+  async getCPC(symbol: string): Promise<CPCClassificationResponse> {
+    try {
+      const path = `/classification/cpc/${encodeURIComponent(symbol)}`;
+      const xml = await this.client.get<string>(path, undefined, 'application/xml');
+      return this.parseCPCResponse(xml);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Get CPC classification with children
+   * @param symbol - CPC symbol to look up
+   */
+  async getCPCWithChildren(symbol: string): Promise<CPCClassificationResponse> {
+    try {
+      const path = `/classification/cpc/${encodeURIComponent(symbol)}`;
+      const xml = await this.client.get<string>(
+        path,
+        { children: 'true' },
+        'application/xml'
+      );
+      return this.parseCPCResponse(xml);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Get CPC classification with ancestors
+   * @param symbol - CPC symbol to look up
+   */
+  async getCPCWithAncestors(symbol: string): Promise<CPCClassificationResponse> {
+    try {
+      const path = `/classification/cpc/${encodeURIComponent(symbol)}`;
+      const xml = await this.client.get<string>(
+        path,
+        { ancestors: 'true' },
+        'application/xml'
+      );
+      return this.parseCPCResponse(xml);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Search CPC classifications by keyword
+   * @param query - Search query
+   */
+  async searchCPC(query: string): Promise<CPCClassificationResponse> {
+    try {
+      const path = `/classification/cpc`;
+      const xml = await this.client.get<string>(
+        path,
+        { q: query },
+        'application/xml'
+      );
+      return this.parseCPCResponse(xml);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  // ============================================
+  // Response Parsing
+  // ============================================
+
+  private parseCPCResponse(xml: string): CPCClassificationResponse {
+    const nodes: CPCNode[] = [];
+
+    // Extract classification items
+    const itemRegex = /<class-item[^>]*level="(\d+)"[^>]*>([\s\S]*?)<\/class-item>/gi;
+    let match;
+
+    while ((match = itemRegex.exec(xml)) !== null) {
+      const level = parseInt(match[1]);
+      const itemXml = match[2];
+
+      const symbol = this.extractElement(itemXml, 'classification-symbol') ||
+                     this.extractElement(itemXml, 'symbol');
+      const title = this.extractElement(itemXml, 'class-title') ||
+                    this.extractElement(itemXml, 'title-part');
+      const definition = this.extractElement(itemXml, 'definition-text') ||
+                         this.extractElement(itemXml, 'note');
+
+      // Extract references
+      const references = this.extractAllElements(itemXml, 'class-ref')
+        .concat(this.extractAllElements(itemXml, 'reference'));
+
+      if (symbol) {
+        const node: CPCNode = {
+          symbol,
+          level,
+          title,
+          definition,
+        };
+
+        if (references.length > 0) {
+          node.references = references;
+        }
+
+        nodes.push(node);
+      }
+    }
+
+    // If no class-item elements, try alternative format
+    if (nodes.length === 0) {
+      const altRegex = /<cpc-class[^>]*>([\s\S]*?)<\/cpc-class>/gi;
+
+      while ((match = altRegex.exec(xml)) !== null) {
+        const itemXml = match[1];
+
+        const symbol = this.extractElement(itemXml, 'symbol') ||
+                       this.extractElement(itemXml, 'classification-symbol');
+        const title = this.extractElement(itemXml, 'title') ||
+                      this.extractElement(itemXml, 'class-title');
+        const definition = this.extractElement(itemXml, 'definition');
+
+        if (symbol) {
+          nodes.push({
+            symbol,
+            level: this.inferLevel(symbol),
+            title,
+            definition,
+          });
+        }
+      }
+    }
+
+    // Try simple classification-item format
+    if (nodes.length === 0) {
+      const simpleRegex = /<classification-item[^>]*>([\s\S]*?)<\/classification-item>/gi;
+
+      while ((match = simpleRegex.exec(xml)) !== null) {
+        const itemXml = match[1];
+
+        const symbol = this.extractElement(itemXml, 'classification-symbol') ||
+                       itemXml.match(/<classification-symbol>([^<]+)/)?.[1];
+        const title = this.extractElement(itemXml, 'title-part') ||
+                      this.extractElement(itemXml, 'text');
+
+        if (symbol) {
+          nodes.push({
+            symbol: symbol.trim(),
+            level: this.inferLevel(symbol.trim()),
+            title,
+          });
+        }
+      }
+    }
+
+    return {
+      success: true,
+      data: nodes,
+    };
+  }
+
+  private extractElement(xml: string, tag: string): string | undefined {
+    const match = xml.match(new RegExp(`<${tag}[^>]*>([^<]+)</${tag}>`, 'i'));
+    return match ? match[1].trim() : undefined;
+  }
+
+  private extractAllElements(xml: string, tag: string): string[] {
+    const results: string[] = [];
+    const regex = new RegExp(`<${tag}[^>]*>([^<]+)</${tag}>`, 'gi');
+    let match;
+
+    while ((match = regex.exec(xml)) !== null) {
+      const text = match[1].trim();
+      if (text) results.push(text);
+    }
+
+    return results;
+  }
+
+  /**
+   * Infer the level of a CPC symbol based on its structure
+   */
+  private inferLevel(symbol: string): number {
+    // Section (e.g., "A")
+    if (/^[A-H]$/.test(symbol)) return 1;
+
+    // Class (e.g., "A01")
+    if (/^[A-H]\d{2}$/.test(symbol)) return 2;
+
+    // Subclass (e.g., "A01B")
+    if (/^[A-H]\d{2}[A-Z]$/.test(symbol)) return 3;
+
+    // Main group (e.g., "A01B1/00")
+    if (/^[A-H]\d{2}[A-Z]\d+\/00$/.test(symbol)) return 4;
+
+    // Subgroup (e.g., "A01B1/02")
+    if (/^[A-H]\d{2}[A-Z]\d+\/\d+$/.test(symbol)) return 5;
+
+    return 0;
+  }
+}

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

@@ -0,0 +1,233 @@
+import type { EPOConfig, OAuthToken, OAuthTokenResponse } from '../types';
+import { EPOApiError } from '../types';
+import { loadToken, saveToken, clearToken } from '../utils/config';
+
+const DEFAULT_BASE_URL = 'https://ops.epo.org/3.2/rest-services';
+const TOKEN_ENDPOINT = 'https://ops.epo.org/3.2/auth/accesstoken';
+
+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>;
+  accept?: string; // Accept header, defaults to application/json
+}
+
+export class EPOClient {
+  private readonly consumerKey: string;
+  private readonly consumerSecret: string;
+  private readonly baseUrl: string;
+  private token: OAuthToken | null = null;
+
+  constructor(config: EPOConfig) {
+    if (!config.consumerKey) {
+      throw new Error('Consumer key is required');
+    }
+    if (!config.consumerSecret) {
+      throw new Error('Consumer secret is required');
+    }
+    this.consumerKey = config.consumerKey;
+    this.consumerSecret = config.consumerSecret;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+
+    // Try to load cached token
+    this.loadCachedToken();
+  }
+
+  private loadCachedToken(): void {
+    const stored = loadToken();
+    if (stored && stored.expiresAt > Date.now()) {
+      this.token = {
+        accessToken: stored.accessToken,
+        tokenType: 'Bearer',
+        expiresIn: Math.floor((stored.expiresAt - Date.now()) / 1000),
+        expiresAt: stored.expiresAt,
+      };
+    }
+  }
+
+  /**
+   * Get an OAuth2 access token using client credentials grant
+   */
+  async authenticate(): Promise<void> {
+    // Check if current token is still valid (with 60 second buffer)
+    if (this.token && this.token.expiresAt > Date.now() + 60000) {
+      return;
+    }
+
+    const credentials = Buffer.from(`${this.consumerKey}:${this.consumerSecret}`).toString('base64');
+
+    const response = await fetch(TOKEN_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Basic ${credentials}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: 'grant_type=client_credentials',
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new EPOApiError(`Authentication failed: ${text}`, response.status);
+    }
+
+    const data = await response.json() as OAuthTokenResponse;
+
+    this.token = {
+      accessToken: data.access_token,
+      tokenType: data.token_type,
+      expiresIn: data.expires_in,
+      expiresAt: Date.now() + (data.expires_in * 1000),
+    };
+
+    // Cache the token
+    saveToken({
+      accessToken: this.token.accessToken,
+      expiresAt: this.token.expiresAt,
+    });
+  }
+
+  /**
+   * Clear the cached token (force re-authentication)
+   */
+  clearToken(): void {
+    this.token = null;
+    clearToken();
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.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 an authenticated request to the EPO OPS API
+   * Automatically handles OAuth2 token refresh
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    // Ensure we have a valid token
+    await this.authenticate();
+
+    const { method = 'GET', params, body, headers = {}, accept = 'application/json' } = options;
+
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      'Authorization': `Bearer ${this.token!.accessToken}`,
+      'Accept': accept,
+      ...headers,
+    };
+
+    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 401 - token might have expired, try to refresh
+    if (response.status === 401) {
+      this.clearToken();
+      await this.authenticate();
+      // Retry the request once
+      const retryHeaders = { ...requestHeaders, 'Authorization': `Bearer ${this.token!.accessToken}` };
+      const retryResponse = await fetch(url, { ...fetchOptions, headers: retryHeaders });
+
+      if (!retryResponse.ok) {
+        const text = await retryResponse.text();
+        throw new EPOApiError(text || retryResponse.statusText, retryResponse.status);
+      }
+
+      return this.parseResponse<T>(retryResponse);
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const text = await response.text();
+      throw new EPOApiError(text || response.statusText, response.status);
+    }
+
+    return this.parseResponse<T>(response);
+  }
+
+  private async parseResponse<T>(response: Response): Promise<T> {
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          return JSON.parse(text) as T;
+        } catch {
+          return text as unknown as T;
+        }
+      }
+      return {} as T;
+    }
+
+    if (contentType.includes('application/xml') || contentType.includes('text/xml')) {
+      // Return raw XML for parsing by the caller
+      return await response.text() as unknown as T;
+    }
+
+    return await response.text() as unknown as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, accept?: string): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params, accept });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  /**
+   * Get a preview of the consumer key (for display/debugging)
+   */
+  getConsumerKeyPreview(): string {
+    if (this.consumerKey.length > 10) {
+      return `${this.consumerKey.substring(0, 6)}...${this.consumerKey.substring(this.consumerKey.length - 4)}`;
+    }
+    return '***';
+  }
+
+  /**
+   * Check if we have a valid token
+   */
+  hasValidToken(): boolean {
+    return this.token !== null && this.token.expiresAt > Date.now();
+  }
+
+  /**
+   * Get token expiry time
+   */
+  getTokenExpiry(): Date | null {
+    return this.token ? new Date(this.token.expiresAt) : null;
+  }
+}