@hasna/connectors 0.9.2 → 1.0.0

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

@@ -0,0 +1,210 @@
+import type { EPOClient } from './client';
+import type {
+  DocumentType,
+  DocumentFormat,
+  FamilyResponse,
+  FamilyData,
+  FamilyMember,
+} from '../types';
+
+/**
+ * Family API - Get INPADOC patent family data
+ */
+export class FamilyApi {
+  constructor(private readonly client: EPOClient) {}
+
+  /**
+   * Get patent family (INPADOC) for a document
+   * @param type - Document type (publication, application, priority)
+   * @param format - Document format (docdb, epodoc, original)
+   * @param number - Document number
+   */
+  async getFamily(
+    type: DocumentType,
+    format: DocumentFormat,
+    number: string
+  ): Promise<FamilyResponse> {
+    try {
+      const path = `/family/${type}/${format}/${encodeURIComponent(number)}`;
+      const xml = await this.client.get<string>(path, undefined, 'application/xml');
+      return this.parseFamilyResponse(xml);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Get patent family with bibliographic data
+   * @param type - Document type (publication, application, priority)
+   * @param format - Document format (docdb, epodoc, original)
+   * @param number - Document number
+   */
+  async getFamilyWithBiblio(
+    type: DocumentType,
+    format: DocumentFormat,
+    number: string
+  ): Promise<FamilyResponse> {
+    try {
+      const path = `/family/${type}/${format}/${encodeURIComponent(number)}/biblio`;
+      const xml = await this.client.get<string>(path, undefined, 'application/xml');
+      return this.parseFamilyResponse(xml);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  /**
+   * Get patent family with legal status
+   * @param type - Document type (publication, application, priority)
+   * @param format - Document format (docdb, epodoc, original)
+   * @param number - Document number
+   */
+  async getFamilyWithLegal(
+    type: DocumentType,
+    format: DocumentFormat,
+    number: string
+  ): Promise<FamilyResponse> {
+    try {
+      const path = `/family/${type}/${format}/${encodeURIComponent(number)}/legal`;
+      const xml = await this.client.get<string>(path, undefined, 'application/xml');
+      return this.parseFamilyResponse(xml);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  // ============================================
+  // Response Parsing
+  // ============================================
+
+  private parseFamilyResponse(xml: string): FamilyResponse {
+    const members: FamilyMember[] = [];
+
+    // Extract family ID if available
+    const familyIdMatch = xml.match(/family-id="([^"]*)"/);
+    const familyId = familyIdMatch ? familyIdMatch[1] : undefined;
+
+    // Extract family members from patent-family/family-member elements
+    const memberRegex = /<family-member[^>]*>([\s\S]*?)<\/family-member>/gi;
+    let match;
+    let sequence = 0;
+
+    while ((match = memberRegex.exec(xml)) !== null) {
+      sequence++;
+      const memberXml = match[1];
+
+      // Extract publication reference
+      const pubRefMatch = memberXml.match(/<publication-reference[^>]*>([\s\S]*?)<\/publication-reference>/i);
+      if (pubRefMatch) {
+        const pubRef = pubRefMatch[1];
+
+        const country = this.extractDocId(pubRef, 'country');
+        const docNumber = this.extractDocId(pubRef, 'doc-number');
+        const kind = this.extractDocId(pubRef, 'kind');
+        const date = this.extractDocId(pubRef, 'date');
+
+        // Extract application reference
+        const appRefMatch = memberXml.match(/<application-reference[^>]*>([\s\S]*?)<\/application-reference>/i);
+        let applicationRef: FamilyMember['applicationRef'] | undefined;
+        if (appRefMatch) {
+          const appRef = appRefMatch[1];
+          applicationRef = {
+            country: this.extractDocId(appRef, 'country') || '',
+            docNumber: this.extractDocId(appRef, 'doc-number') || '',
+            date: this.extractDocId(appRef, 'date'),
+          };
+        }
+
+        // Extract priority claims
+        const priorityClaims = this.extractPriorityClaims(memberXml);
+
+        members.push({
+          documentId: `${country || ''}${docNumber || ''}${kind || ''}`,
+          country: country || '',
+          docNumber: docNumber || '',
+          kind,
+          date,
+          familySequence: sequence,
+          applicationRef,
+          priorityClaims,
+        });
+      }
+    }
+
+    // If no family-member elements found, try to parse simple-family format
+    if (members.length === 0) {
+      const simpleRegex = /<exchange-document[^>]*>([\s\S]*?)<\/exchange-document>/gi;
+      while ((match = simpleRegex.exec(xml)) !== null) {
+        sequence++;
+        const docXml = match[0];
+
+        const country = this.extractAttribute(docXml, 'exchange-document', 'country');
+        const docNumber = this.extractAttribute(docXml, 'exchange-document', 'doc-number');
+        const kind = this.extractAttribute(docXml, 'exchange-document', 'kind');
+
+        members.push({
+          documentId: `${country || ''}${docNumber || ''}${kind || ''}`,
+          country: country || '',
+          docNumber: docNumber || '',
+          kind,
+          familySequence: sequence,
+        });
+      }
+    }
+
+    return {
+      success: true,
+      data: {
+        familyId,
+        members,
+        totalMembers: members.length,
+      },
+    };
+  }
+
+  private extractDocId(xml: string, field: string): string | undefined {
+    const match = xml.match(new RegExp(`<${field}[^>]*>([^<]*)</${field}>`, 'i'));
+    return match ? match[1].trim() : undefined;
+  }
+
+  private extractAttribute(xml: string, tag: string, attr: string): string | undefined {
+    const match = xml.match(new RegExp(`<${tag}[^>]*\\s${attr}="([^"]*)"`, 'i'));
+    return match ? match[1] : undefined;
+  }
+
+  private extractPriorityClaims(xml: string): FamilyMember['priorityClaims'] {
+    const claims: NonNullable<FamilyMember['priorityClaims']> = [];
+
+    const claimRegex = /<priority-claim[^>]*>([\s\S]*?)<\/priority-claim>/gi;
+    let match;
+
+    while ((match = claimRegex.exec(xml)) !== null) {
+      const claimXml = match[1];
+
+      const country = this.extractDocId(claimXml, 'country');
+      const docNumber = this.extractDocId(claimXml, 'doc-number');
+      const date = this.extractDocId(claimXml, 'date');
+      const kind = this.extractDocId(claimXml, 'kind');
+
+      if (country && docNumber && date) {
+        claims.push({
+          country,
+          docNumber,
+          date,
+          kind,
+        });
+      }
+    }
+
+    return claims.length > 0 ? claims : undefined;
+  }
+}

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

@@ -0,0 +1,97 @@
+import type { EPOConfig } from '../types';
+import { EPOClient } from './client';
+import { PublicationsApi } from './publications';
+import { FamilyApi } from './family';
+import { LegalApi } from './legal';
+import { RegisterApi } from './register';
+import { ClassificationApi } from './classification';
+
+/**
+ * Main EPO OPS connector class
+ */
+export class EPO {
+  private readonly client: EPOClient;
+
+  // API modules
+  public readonly publications: PublicationsApi;
+  public readonly family: FamilyApi;
+  public readonly legal: LegalApi;
+  public readonly register: RegisterApi;
+  public readonly classification: ClassificationApi;
+
+  constructor(config: EPOConfig) {
+    this.client = new EPOClient(config);
+    this.publications = new PublicationsApi(this.client);
+    this.family = new FamilyApi(this.client);
+    this.legal = new LegalApi(this.client);
+    this.register = new RegisterApi(this.client);
+    this.classification = new ClassificationApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for EPO_CONSUMER_KEY and EPO_CONSUMER_SECRET
+   */
+  static fromEnv(): EPO {
+    const consumerKey = process.env.EPO_CONSUMER_KEY;
+    const consumerSecret = process.env.EPO_CONSUMER_SECRET;
+    const baseUrl = process.env.EPO_BASE_URL;
+
+    if (!consumerKey) {
+      throw new Error('EPO_CONSUMER_KEY environment variable is required');
+    }
+    if (!consumerSecret) {
+      throw new Error('EPO_CONSUMER_SECRET environment variable is required');
+    }
+    return new EPO({ consumerKey, consumerSecret, baseUrl });
+  }
+
+  /**
+   * Get a preview of the consumer key (for debugging)
+   */
+  getConsumerKeyPreview(): string {
+    return this.client.getConsumerKeyPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): EPOClient {
+    return this.client;
+  }
+
+  /**
+   * Force authentication (get a new token)
+   */
+  async authenticate(): Promise<void> {
+    await this.client.authenticate();
+  }
+
+  /**
+   * Check if we have a valid token
+   */
+  hasValidToken(): boolean {
+    return this.client.hasValidToken();
+  }
+
+  /**
+   * Get token expiry time
+   */
+  getTokenExpiry(): Date | null {
+    return this.client.getTokenExpiry();
+  }
+
+  /**
+   * Clear the cached token
+   */
+  clearToken(): void {
+    this.client.clearToken();
+  }
+}
+
+export { EPOClient } from './client';
+export { PublicationsApi } from './publications';
+export { FamilyApi } from './family';
+export { LegalApi } from './legal';
+export { RegisterApi } from './register';
+export { ClassificationApi } from './classification';

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

@@ -0,0 +1,163 @@
+import type { EPOClient } from './client';
+import type {
+  DocumentType,
+  DocumentFormat,
+  LegalStatusResponse,
+  LegalStatusData,
+  LegalEvent,
+} from '../types';
+
+/**
+ * Legal Status API - Get legal status information for patents
+ */
+export class LegalApi {
+  constructor(private readonly client: EPOClient) {}
+
+  /**
+   * Get legal status for a document
+   * @param type - Document type (publication, application, priority)
+   * @param format - Document format (docdb, epodoc, original)
+   * @param number - Document number
+   */
+  async getLegalStatus(
+    type: DocumentType,
+    format: DocumentFormat,
+    number: string
+  ): Promise<LegalStatusResponse> {
+    try {
+      const path = `/legal/${type}/${format}/${encodeURIComponent(number)}`;
+      const xml = await this.client.get<string>(path, undefined, 'application/xml');
+      return this.parseLegalStatusResponse(xml, number);
+    } catch (error) {
+      return {
+        success: false,
+        error: String(error),
+      };
+    }
+  }
+
+  // ============================================
+  // Response Parsing
+  // ============================================
+
+  private parseLegalStatusResponse(xml: string, documentId: string): LegalStatusResponse {
+    const events: LegalEvent[] = [];
+
+    // Extract legal events
+    const eventRegex = /<ops:legal[^>]*>([\s\S]*?)<\/ops:legal>/gi;
+    let match;
+
+    while ((match = eventRegex.exec(xml)) !== null) {
+      const eventXml = match[1];
+
+      const code = this.extractAttribute(eventXml, 'ops:code', '') ||
+                   this.extractElement(eventXml, 'ops:code');
+      const date = this.extractAttribute(eventXml, 'ops:date', '') ||
+                   this.extractElement(eventXml, 'ops:date');
+      const country = this.extractAttribute(eventXml, 'ops:country', '') ||
+                      this.extractElement(eventXml, 'ops:country');
+      const desc = this.extractElement(eventXml, 'ops:text-desc') ||
+                   this.extractElement(eventXml, 'ops:description');
+
+      // Extract gazette info if available
+      const gazetteNum = this.extractElement(eventXml, 'ops:gazette-num');
+      const gazetteDate = this.extractElement(eventXml, 'ops:gazette-date');
+
+      if (code || date) {
+        const event: LegalEvent = {
+          code: code || '',
+          date: date || '',
+          country: country || undefined,
+          description: desc || undefined,
+        };
+
+        if (gazetteNum || gazetteDate) {
+          event.gazette = {
+            number: gazetteNum,
+            date: gazetteDate,
+          };
+        }
+
+        events.push(event);
+      }
+    }
+
+    // Try alternative format without ops: prefix
+    if (events.length === 0) {
+      const altEventRegex = /<legal-event[^>]*>([\s\S]*?)<\/legal-event>/gi;
+      while ((match = altEventRegex.exec(xml)) !== null) {
+        const eventXml = match[1];
+
+        const codeEl = this.extractElement(eventXml, 'code');
+        const dateEl = this.extractElement(eventXml, 'date');
+        const countryEl = this.extractElement(eventXml, 'country');
+        const descEl = this.extractElement(eventXml, 'description') ||
+                       this.extractElement(eventXml, 'text');
+
+        if (codeEl || dateEl) {
+          events.push({
+            code: codeEl || '',
+            date: dateEl || '',
+            country: countryEl || undefined,
+            description: descEl || undefined,
+          });
+        }
+      }
+    }
+
+    // Try to extract from register-documents format
+    if (events.length === 0) {
+      const regEventRegex = /<register-event[^>]*>([\s\S]*?)<\/register-event>/gi;
+      while ((match = regEventRegex.exec(xml)) !== null) {
+        const eventXml = match[1];
+
+        const code = this.extractElement(eventXml, 'event-code') ||
+                     this.extractAttribute(eventXml, 'register-event', 'code');
+        const date = this.extractElement(eventXml, 'event-date') ||
+                     this.extractAttribute(eventXml, 'register-event', 'date');
+        const desc = this.extractElement(eventXml, 'event-text');
+
+        if (code || date) {
+          events.push({
+            code: code || '',
+            date: date || '',
+            description: desc || undefined,
+          });
+        }
+      }
+    }
+
+    return {
+      success: true,
+      data: {
+        documentId,
+        events,
+      },
+    };
+  }
+
+  private extractElement(xml: string, tag: string): string | undefined {
+    // Handle both prefixed and non-prefixed tags
+    const colonIndex = tag.indexOf(':');
+    const localName = colonIndex >= 0 ? tag.substring(colonIndex + 1) : tag;
+
+    // Try with exact tag first
+    let match = xml.match(new RegExp(`<${tag}[^>]*>([^<]*)</${tag}>`, 'i'));
+    if (match) return match[1].trim();
+
+    // Try with just local name (no namespace prefix)
+    match = xml.match(new RegExp(`<${localName}[^>]*>([^<]*)</${localName}>`, 'i'));
+    if (match) return match[1].trim();
+
+    // Try with any namespace prefix
+    match = xml.match(new RegExp(`<[^:>]+:${localName}[^>]*>([^<]*)</[^:>]+:${localName}>`, 'i'));
+    if (match) return match[1].trim();
+
+    return undefined;
+  }
+
+  private extractAttribute(xml: string, tag: string, attr: string): string | undefined {
+    const match = xml.match(new RegExp(`<${tag}[^>]*\\s${attr}="([^"]*)"`, 'i'));
+    return match ? match[1] : undefined;
+  }
+}