@hasna/connectors 0.9.2 → 1.0.0

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

@@ -0,0 +1,25 @@
+// EPO OPS Connector
+// A TypeScript wrapper for the European Patent Office Open Patent Services API
+
+export { EPO } from './api';
+export * from './types';
+
+// Re-export individual API classes for advanced usage
+export { EPOClient, PublicationsApi, FamilyApi, LegalApi, RegisterApi, ClassificationApi } from './api';
+
+// Export config utilities
+export {
+  getConsumerKey,
+  getConsumerSecret,
+  setCredentials,
+  getBaseUrl,
+  setBaseUrl,
+  getCurrentProfile,
+  setCurrentProfile,
+  listProfiles,
+  createProfile,
+  deleteProfile,
+  loadProfile,
+  saveProfile,
+  clearConfig,
+} from './utils/config';

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

@@ -0,0 +1,372 @@
+// EPO Open Patent Services (OPS) Connector Types
+
+// ============================================
+// Configuration
+// ============================================
+
+export interface EPOConfig {
+  consumerKey: string;
+  consumerSecret: string;
+  baseUrl?: string; // Override default base URL (https://ops.epo.org/3.2/rest-services)
+}
+
+// ============================================
+// Common Types
+// ============================================
+
+export type OutputFormat = 'json' | 'pretty';
+
+/** Document type for EPO API queries */
+export type DocumentType = 'publication' | 'application' | 'priority';
+
+/** Document format for EPO API queries */
+export type DocumentFormat = 'docdb' | 'epodoc' | 'original';
+
+/** Reference type combining type and format */
+export interface DocumentReference {
+  type: DocumentType;
+  format: DocumentFormat;
+  number: string;
+  country?: string;
+  kind?: string;
+}
+
+// ============================================
+// OAuth Token Types
+// ============================================
+
+export interface OAuthToken {
+  accessToken: string;
+  tokenType: string;
+  expiresIn: number;
+  expiresAt: number; // Unix timestamp
+}
+
+export interface OAuthTokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+}
+
+// ============================================
+// Publication Types
+// ============================================
+
+export interface PublicationSearchRequest {
+  query: string; // CQL query string
+  rangeBegin?: number;
+  rangeEnd?: number;
+}
+
+export interface PublicationSearchResponse {
+  success: boolean;
+  totalResults?: number;
+  results?: PublicationResult[];
+  error?: string;
+}
+
+export interface PublicationResult {
+  documentId: string;
+  country?: string;
+  docNumber?: string;
+  kind?: string;
+  date?: string;
+  title?: string;
+  applicants?: string[];
+  inventors?: string[];
+  classifications?: string[];
+}
+
+export interface BiblioResponse {
+  success: boolean;
+  data?: BibliographicData;
+  error?: string;
+}
+
+export interface BibliographicData {
+  documentId: string;
+  country?: string;
+  docNumber?: string;
+  kind?: string;
+  date?: string;
+  title?: string;
+  titles?: { lang: string; text: string }[];
+  abstract?: string;
+  abstracts?: { lang: string; text: string }[];
+  applicants?: Applicant[];
+  inventors?: Inventor[];
+  classifications?: Classification[];
+  priorities?: PriorityData[];
+  citations?: Citation[];
+  applicationRef?: DocumentReference;
+  publicationRef?: DocumentReference;
+}
+
+export interface Applicant {
+  name: string;
+  country?: string;
+  sequence?: number;
+}
+
+export interface Inventor {
+  name: string;
+  country?: string;
+  sequence?: number;
+}
+
+export interface Classification {
+  scheme: string; // IPC, CPC, etc.
+  symbol: string;
+  section?: string;
+  class?: string;
+  subclass?: string;
+  mainGroup?: string;
+  subgroup?: string;
+  position?: string;
+  value?: string;
+}
+
+export interface PriorityData {
+  country: string;
+  docNumber: string;
+  date: string;
+  kind?: string;
+}
+
+export interface Citation {
+  type: 'patcit' | 'nplcit';
+  phase?: string;
+  category?: string;
+  documentId?: string;
+  text?: string;
+}
+
+export interface AbstractResponse {
+  success: boolean;
+  data?: {
+    documentId: string;
+    abstracts: { lang: string; text: string }[];
+  };
+  error?: string;
+}
+
+export interface DescriptionResponse {
+  success: boolean;
+  data?: {
+    documentId: string;
+    description: string;
+    lang?: string;
+  };
+  error?: string;
+}
+
+export interface ClaimsResponse {
+  success: boolean;
+  data?: {
+    documentId: string;
+    claims: Claim[];
+  };
+  error?: string;
+}
+
+export interface Claim {
+  number: number;
+  text: string;
+  type?: 'independent' | 'dependent';
+  dependsOn?: number[];
+  lang?: string;
+}
+
+export interface ImagesResponse {
+  success: boolean;
+  data?: {
+    documentId: string;
+    images: ImageInfo[];
+  };
+  error?: string;
+}
+
+export interface ImageInfo {
+  type: string; // 'DRAWINGS', 'FIRST_PAGE', etc.
+  format: string;
+  pages: number;
+  url?: string;
+}
+
+// ============================================
+// Family Types (INPADOC)
+// ============================================
+
+export interface FamilyResponse {
+  success: boolean;
+  data?: FamilyData;
+  error?: string;
+}
+
+export interface FamilyData {
+  familyId?: string;
+  members: FamilyMember[];
+  totalMembers?: number;
+}
+
+export interface FamilyMember {
+  documentId: string;
+  country: string;
+  docNumber: string;
+  kind?: string;
+  date?: string;
+  familySequence?: number;
+  applicationRef?: {
+    country: string;
+    docNumber: string;
+    date?: string;
+  };
+  priorityClaims?: PriorityData[];
+}
+
+// ============================================
+// Legal Status Types
+// ============================================
+
+export interface LegalStatusResponse {
+  success: boolean;
+  data?: LegalStatusData;
+  error?: string;
+}
+
+export interface LegalStatusData {
+  documentId: string;
+  events: LegalEvent[];
+}
+
+export interface LegalEvent {
+  code: string;
+  date: string;
+  country?: string;
+  description?: string;
+  category?: string;
+  gazette?: {
+    number?: string;
+    date?: string;
+  };
+  correspondingEvents?: {
+    country: string;
+    code: string;
+    date: string;
+  }[];
+}
+
+// ============================================
+// Register Types (EP Register)
+// ============================================
+
+export interface RegisterSearchRequest {
+  query: string;
+  rangeBegin?: number;
+  rangeEnd?: number;
+}
+
+export interface RegisterSearchResponse {
+  success: boolean;
+  totalResults?: number;
+  results?: RegisterResult[];
+  error?: string;
+}
+
+export interface RegisterResult {
+  applicationNumber: string;
+  publicationNumber?: string;
+  status?: string;
+  title?: string;
+  applicants?: string[];
+  filingDate?: string;
+}
+
+export interface RegisterDataResponse {
+  success: boolean;
+  data?: RegisterData;
+  error?: string;
+}
+
+export interface RegisterData {
+  applicationNumber: string;
+  publicationNumber?: string;
+  status?: string;
+  procedureType?: string;
+  title?: string;
+  applicants?: Applicant[];
+  inventors?: Inventor[];
+  representatives?: Representative[];
+  filingDate?: string;
+  publicationDate?: string;
+  grantDate?: string;
+  oppositionDeadline?: string;
+  designatedStates?: string[];
+  classifications?: Classification[];
+  priorities?: PriorityData[];
+  citations?: Citation[];
+  events?: RegisterEvent[];
+  documents?: RegisterDocument[];
+}
+
+export interface Representative {
+  name: string;
+  address?: string;
+  country?: string;
+}
+
+export interface RegisterEvent {
+  date: string;
+  code?: string;
+  description?: string;
+  details?: string;
+}
+
+export interface RegisterDocument {
+  type: string;
+  date: string;
+  format?: string;
+  pages?: number;
+  url?: string;
+}
+
+// ============================================
+// Classification Types
+// ============================================
+
+export interface CPCClassificationResponse {
+  success: boolean;
+  data?: CPCNode[];
+  error?: string;
+}
+
+export interface CPCNode {
+  symbol: string;
+  level: number;
+  title?: string;
+  definition?: string;
+  children?: CPCNode[];
+  references?: string[];
+}
+
+// ============================================
+// API Error Types
+// ============================================
+
+export interface ApiErrorDetail {
+  code: string;
+  message: string;
+  field?: string;
+}
+
+export class EPOApiError extends Error {
+  public readonly statusCode: number;
+  public readonly errors?: ApiErrorDetail[];
+
+  constructor(message: string, statusCode: number, errors?: ApiErrorDetail[]) {
+    super(message);
+    this.name = 'EPOApiError';
+    this.statusCode = statusCode;
+    this.errors = errors;
+  }
+}

package/connectors/connect-epo/src/utils/config.ts

@@ -0,0 +1,251 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONNECTOR_NAME = 'connect-epo';
+const DEFAULT_PROFILE = 'default';
+
+export interface ProfileConfig {
+  consumerKey?: string;
+  consumerSecret?: string;
+  baseUrl?: string;
+}
+
+// Store for --profile flag override (set by CLI before commands run)
+let profileOverride: string | undefined;
+
+// Config directory: ~/.connect/{connector-name}/
+const CONFIG_DIR = join(homedir(), '.connect', CONNECTOR_NAME);
+const PROFILES_DIR = join(CONFIG_DIR, 'profiles');
+const CURRENT_PROFILE_FILE = join(CONFIG_DIR, 'current_profile');
+const TOKEN_FILE = join(CONFIG_DIR, 'token.json');
+
+// ============================================
+// Profile Management
+// ============================================
+
+export function setProfileOverride(profile: string | undefined): void {
+  profileOverride = profile;
+}
+
+export function ensureConfigDir(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  if (!existsSync(PROFILES_DIR)) {
+    mkdirSync(PROFILES_DIR, { recursive: true });
+  }
+}
+
+function getProfilePath(profile: string): string {
+  return join(PROFILES_DIR, `${profile}.json`);
+}
+
+/**
+ * Get the current active profile name
+ */
+export function getCurrentProfile(): string {
+  if (profileOverride) {
+    return profileOverride;
+  }
+
+  ensureConfigDir();
+
+  if (existsSync(CURRENT_PROFILE_FILE)) {
+    try {
+      const profile = readFileSync(CURRENT_PROFILE_FILE, 'utf-8').trim();
+      if (profile && profileExists(profile)) {
+        return profile;
+      }
+    } catch {
+      // Fall through to default
+    }
+  }
+
+  return DEFAULT_PROFILE;
+}
+
+/**
+ * Set the current active profile
+ */
+export function setCurrentProfile(profile: string): void {
+  ensureConfigDir();
+
+  if (!profileExists(profile) && profile !== DEFAULT_PROFILE) {
+    throw new Error(`Profile "${profile}" does not exist`);
+  }
+
+  writeFileSync(CURRENT_PROFILE_FILE, profile);
+}
+
+/**
+ * Check if a profile exists
+ */
+export function profileExists(profile: string): boolean {
+  return existsSync(getProfilePath(profile));
+}
+
+/**
+ * List all available profiles
+ */
+export function listProfiles(): string[] {
+  ensureConfigDir();
+
+  if (!existsSync(PROFILES_DIR)) {
+    return [];
+  }
+
+  return readdirSync(PROFILES_DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace('.json', ''))
+    .sort();
+}
+
+/**
+ * Create a new profile
+ */
+export function createProfile(profile: string, config: ProfileConfig = {}): boolean {
+  ensureConfigDir();
+
+  if (profileExists(profile)) {
+    return false;
+  }
+
+  // Validate profile name
+  if (!/^[a-zA-Z0-9_-]+$/.test(profile)) {
+    throw new Error('Profile name can only contain letters, numbers, hyphens, and underscores');
+  }
+
+  writeFileSync(getProfilePath(profile), JSON.stringify(config, null, 2));
+  return true;
+}
+
+/**
+ * Delete a profile
+ */
+export function deleteProfile(profile: string): boolean {
+  if (profile === DEFAULT_PROFILE) {
+    return false;
+  }
+
+  if (!profileExists(profile)) {
+    return false;
+  }
+
+  // Switch to default if deleting current profile
+  if (getCurrentProfile() === profile) {
+    setCurrentProfile(DEFAULT_PROFILE);
+  }
+
+  rmSync(getProfilePath(profile));
+  return true;
+}
+
+/**
+ * Load profile config
+ */
+export function loadProfile(profile?: string): ProfileConfig {
+  ensureConfigDir();
+  const profileName = profile || getCurrentProfile();
+  const profilePath = getProfilePath(profileName);
+
+  if (!existsSync(profilePath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(readFileSync(profilePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save profile config
+ */
+export function saveProfile(config: ProfileConfig, profile?: string): void {
+  ensureConfigDir();
+  const profileName = profile || getCurrentProfile();
+  writeFileSync(getProfilePath(profileName), JSON.stringify(config, null, 2));
+}
+
+// ============================================
+// Credentials Management
+// ============================================
+
+export function getConsumerKey(): string | undefined {
+  return process.env.EPO_CONSUMER_KEY || loadProfile().consumerKey;
+}
+
+export function getConsumerSecret(): string | undefined {
+  return process.env.EPO_CONSUMER_SECRET || loadProfile().consumerSecret;
+}
+
+export function setCredentials(consumerKey: string, consumerSecret: string): void {
+  const config = loadProfile();
+  config.consumerKey = consumerKey;
+  config.consumerSecret = consumerSecret;
+  saveProfile(config);
+}
+
+export function getBaseUrl(): string | undefined {
+  return process.env.EPO_BASE_URL || loadProfile().baseUrl;
+}
+
+export function setBaseUrl(baseUrl: string): void {
+  const config = loadProfile();
+  config.baseUrl = baseUrl;
+  saveProfile(config);
+}
+
+// ============================================
+// Token Management
+// ============================================
+
+export interface StoredToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+export function loadToken(): StoredToken | null {
+  ensureConfigDir();
+
+  if (!existsSync(TOKEN_FILE)) {
+    return null;
+  }
+
+  try {
+    const data = JSON.parse(readFileSync(TOKEN_FILE, 'utf-8'));
+    return data as StoredToken;
+  } catch {
+    return null;
+  }
+}
+
+export function saveToken(token: StoredToken): void {
+  ensureConfigDir();
+  writeFileSync(TOKEN_FILE, JSON.stringify(token, null, 2));
+}
+
+export function clearToken(): void {
+  if (existsSync(TOKEN_FILE)) {
+    rmSync(TOKEN_FILE);
+  }
+}
+
+// ============================================
+// Utility Functions
+// ============================================
+
+export function clearConfig(): void {
+  saveProfile({});
+  clearToken();
+}
+
+export function getConfigDir(): string {
+  return CONFIG_DIR;
+}
+
+export function getActiveProfileName(): string {
+  return getCurrentProfile();
+}