@hasna/connectors 0.9.2 → 1.0.0

package/connectors/connect-envoy/src/utils/storage.ts

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir } from './config';
+
+// ============================================
+// Generic Data Storage Utility
+// ============================================
+
+/**
+ * Base interface for storable entities
+ * All stored entities should have an id field
+ */
+export interface Storable {
+  id: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * Get the storage directory for an entity type
+ */
+function getStorageDir(entityType: string): string {
+  const dir = join(getConfigDir(), 'data', entityType);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Convert an ID to a safe filename
+ */
+function idToFilename(id: string): string {
+  return id.toLowerCase().replace(/[^a-z0-9]/g, '_') + '.json';
+}
+
+/**
+ * Get the file path for an entity
+ */
+function getEntityPath(entityType: string, id: string): string {
+  return join(getStorageDir(entityType), idToFilename(id));
+}
+
+/**
+ * Save an entity to storage
+ */
+export function saveEntity<T extends Storable>(entityType: string, entity: T): void {
+  const filepath = getEntityPath(entityType, entity.id);
+  const now = new Date().toISOString();
+
+  const existing = getEntity<T>(entityType, entity.id);
+
+  const data: T = {
+    ...entity,
+    createdAt: existing?.createdAt || now,
+    updatedAt: now,
+  };
+
+  writeFileSync(filepath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Get an entity by ID
+ */
+export function getEntity<T extends Storable>(entityType: string, id: string): T | null {
+  const filepath = getEntityPath(entityType, id);
+
+  if (!existsSync(filepath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filepath, 'utf-8');
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if an entity exists
+ */
+export function entityExists(entityType: string, id: string): boolean {
+  return existsSync(getEntityPath(entityType, id));
+}
+
+/**
+ * Get all entities of a type
+ */
+export function getAllEntities<T extends Storable>(entityType: string): T[] {
+  const storageDir = getStorageDir(entityType);
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+
+  const entities: T[] = [];
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(storageDir, file), 'utf-8');
+      entities.push(JSON.parse(content) as T);
+    } catch {
+      // Skip invalid files
+    }
+  }
+
+  return entities.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Delete an entity
+ */
+export function deleteEntity(entityType: string, id: string): boolean {
+  const filepath = getEntityPath(entityType, id);
+
+  if (existsSync(filepath)) {
+    unlinkSync(filepath);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Search entities by a predicate function
+ */
+export function searchEntities<T extends Storable>(
+  entityType: string,
+  predicate: (entity: T) => boolean
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  return all.filter(predicate);
+}
+
+/**
+ * Search entities by text match across all string fields
+ */
+export function searchEntitiesByText<T extends Storable>(
+  entityType: string,
+  query: string,
+  fields?: (keyof T)[]
+): T[] {
+  const all = getAllEntities<T>(entityType);
+  const q = query.toLowerCase();
+
+  return all.filter(entity => {
+    const searchFields = fields || (Object.keys(entity) as (keyof T)[]);
+    return searchFields.some(field => {
+      const value = entity[field];
+      if (typeof value === 'string') {
+        return value.toLowerCase().includes(q);
+      }
+      return false;
+    });
+  });
+}
+
+/**
+ * Count entities of a type
+ */
+export function countEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+  return readdirSync(storageDir).filter(f => f.endsWith('.json')).length;
+}
+
+/**
+ * Clear all entities of a type
+ */
+export function clearEntities(entityType: string): number {
+  const storageDir = getStorageDir(entityType);
+  if (!existsSync(storageDir)) {
+    return 0;
+  }
+
+  const files = readdirSync(storageDir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    unlinkSync(join(storageDir, file));
+  }
+
+  return files.length;
+}
+
+/**
+ * Create a typed storage helper for a specific entity type
+ * This provides a cleaner API for working with a single entity type
+ */
+export function createStorage<T extends Storable>(entityType: string) {
+  return {
+    save: (entity: T) => saveEntity<T>(entityType, entity),
+    get: (id: string) => getEntity<T>(entityType, id),
+    exists: (id: string) => entityExists(entityType, id),
+    getAll: () => getAllEntities<T>(entityType),
+    delete: (id: string) => deleteEntity(entityType, id),
+    search: (predicate: (entity: T) => boolean) => searchEntities<T>(entityType, predicate),
+    searchByText: (query: string, fields?: (keyof T)[]) => searchEntitiesByText<T>(entityType, query, fields),
+    count: () => countEntities(entityType),
+    clear: () => clearEntities(entityType),
+  };
+}

package/connectors/connect-envoy/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}

package/connectors/connect-epo/.env.example

@@ -0,0 +1,8 @@
+# EPO Open Patent Services (OPS) Credentials
+# Register at https://developers.epo.org/ to get your Consumer Key and Secret
+
+EPO_CONSUMER_KEY=your-consumer-key-here
+EPO_CONSUMER_SECRET=your-consumer-secret-here
+
+# Optional: Custom base URL (if using different API version)
+# EPO_BASE_URL=https://ops.epo.org/3.2/rest-services

package/connectors/connect-epo/CLAUDE.md

@@ -0,0 +1,225 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+connect-epo is a TypeScript connector for the EPO Open Patent Services (OPS) API. It provides a CLI and programmatic interface to search and retrieve European patent data including publications, patent families, legal status, and register information.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+
+# Run specific commands
+bun run dev search "ti=solar AND pa=tesla"
+bun run dev publication biblio EP1000000
+bun run dev family get EP1000000
+bun run dev legal EP1000000
+bun run dev register search "pa=siemens"
+bun run dev classification get H01L
+bun run dev profile list
+bun run dev config show
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Use async/await for all async operations
+- Minimal dependencies: commander, chalk only
+- Type annotations required everywhere
+- Use interfaces for all API types
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts         # HTTP client with OAuth2 authentication
+│   ├── publications.ts   # Published data search and retrieval
+│   ├── family.ts         # Patent family (INPADOC) data
+│   ├── legal.ts          # Legal status information
+│   ├── register.ts       # EP Register data
+│   ├── classification.ts # CPC classification
+│   └── index.ts          # Main EPO class
+├── cli/
+│   └── index.ts          # CLI commands
+├── types/
+│   └── index.ts          # Type definitions
+├── utils/
+│   ├── config.ts         # Multi-profile configuration
+│   └── output.ts         # CLI output formatting
+└── index.ts              # Library exports
+```
+
+## API Modules
+
+### Publications API (`/published-data`)
+- Search published patents using CQL queries
+- Get publication by document number
+- Retrieve bibliographic data, abstracts, descriptions, claims
+- Get images metadata
+
+### Family API (`/family`)
+- Get INPADOC patent family data
+- Retrieve family with bibliographic data
+- Get family with legal status
+
+### Legal Status API (`/legal`)
+- Get legal status events for a patent
+- Track patent lifecycle (grant, expiry, opposition, etc.)
+
+### Register API (`/register`)
+- Search EP Register
+- Get detailed register data for applications
+- Retrieve procedural steps
+
+### Classification API (`/classification/cpc`)
+- Look up CPC classification symbols
+- Get classification hierarchy with children/ancestors
+- Search classifications by keyword
+
+## Authentication
+
+The EPO OPS API uses OAuth2 with client credentials grant:
+- Register at https://developers.epo.org/ to get Consumer Key and Secret
+- Token endpoint: https://ops.epo.org/3.2/auth/accesstoken
+- Tokens are automatically cached and refreshed
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `EPO_CONSUMER_KEY` | Consumer key from EPO developer portal (required) |
+| `EPO_CONSUMER_SECRET` | Consumer secret from EPO developer portal (required) |
+| `EPO_BASE_URL` | Override base URL (default: https://ops.epo.org/3.2/rest-services) |
+
+## Data Storage
+
+```
+~/.connect/connect-epo/
+├── current_profile   # Active profile name
+├── token.json        # Cached OAuth token
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+Profile JSON structure:
+```json
+{
+  "consumerKey": "xxx",
+  "consumerSecret": "xxx",
+  "baseUrl": "optional-custom-url"
+}
+```
+
+## CLI Usage
+
+```bash
+# Search patents
+connect-epo search "ti=solar AND pa=tesla"
+connect-epo search "pa=siemens" --range 1-50
+
+# Get publication data
+connect-epo publication get EP1000000
+connect-epo publication biblio EP1000000
+connect-epo publication abstract EP1000000
+connect-epo publication claims EP1000000
+
+# Get patent family
+connect-epo family get EP1000000
+connect-epo family biblio EP1000000
+
+# Get legal status
+connect-epo legal EP1000000
+
+# Search EP Register
+connect-epo register search "pa=nokia"
+connect-epo register get EP1000000
+
+# CPC Classification
+connect-epo classification get H01L
+connect-epo classification get H01L --children
+connect-epo classification search "semiconductor"
+
+# Authentication
+connect-epo auth test
+connect-epo auth clear-token
+
+# Configuration
+connect-epo config set-credentials <key> <secret>
+connect-epo config show
+connect-epo profile create work --consumer-key xxx --consumer-secret xxx --use
+connect-epo profile list
+```
+
+## Programmatic Usage
+
+```typescript
+import { EPO } from '@hasna/connect-epo';
+
+// Create client
+const epo = new EPO({
+  consumerKey: 'your-key',
+  consumerSecret: 'your-secret',
+});
+
+// Search patents
+const results = await epo.publications.search('ti=solar AND pa=tesla');
+
+// Get bibliographic data
+const biblio = await epo.publications.getBiblio('publication', 'epodoc', 'EP1000000');
+
+// Get patent family
+const family = await epo.family.getFamily('publication', 'epodoc', 'EP1000000');
+
+// Get legal status
+const legal = await epo.legal.getLegalStatus('publication', 'epodoc', 'EP1000000');
+
+// Search EP Register
+const registerResults = await epo.register.search('pa=siemens');
+
+// Get CPC classification
+const cpc = await epo.classification.getCPC('H01L');
+```
+
+## Document Reference Formats
+
+- **docdb**: Country code + number + kind (e.g., EP1000000A1)
+- **epodoc**: Simplified format (e.g., EP1000000)
+- **original**: Original application number format
+
+## CQL Query Syntax
+
+Common search fields:
+- `ti=` - Title
+- `ab=` - Abstract
+- `pa=` - Applicant
+- `in=` - Inventor
+- `pn=` - Publication number
+- `ap=` - Application number
+- `pr=` - Priority number
+- `pd=` - Publication date
+- `ic=` - IPC classification
+
+Example queries:
+- `ti=solar AND pa=tesla` - Solar patents by Tesla
+- `pa=siemens AND pd>=2020` - Siemens patents from 2020+
+- `ic=H01L AND ti=transistor` - Transistor patents in H01L class
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-epo/README.md

@@ -0,0 +1,259 @@
+# connect-epo
+
+A TypeScript connector for the EPO Open Patent Services (OPS) API. Search and retrieve European patent data including publications, patent families, legal status, and register information.
+
+## Features
+
+- OAuth2 authentication with automatic token refresh
+- Multi-profile configuration (switch between different API credentials)
+- Full EPO OPS API coverage:
+  - Published data search and retrieval
+  - Patent family (INPADOC) data
+  - Legal status information
+  - EP Register access
+  - CPC classification lookup
+- Clean CLI with JSON/pretty output
+- TypeScript with full type definitions
+
+## Installation
+
+```bash
+# Install globally
+bun install -g @hasna/connect-epo
+
+# Or use with npx
+npx @hasna/connect-epo
+```
+
+## Quick Start
+
+### 1. Get EPO Credentials
+
+Register at [EPO Developer Portal](https://developers.epo.org/) to get your Consumer Key and Secret.
+
+### 2. Configure Credentials
+
+```bash
+connect-epo config set-credentials <consumer-key> <consumer-secret>
+```
+
+Or set environment variables:
+```bash
+export EPO_CONSUMER_KEY=your-key
+export EPO_CONSUMER_SECRET=your-secret
+```
+
+### 3. Search Patents
+
+```bash
+# Search by title and applicant
+connect-epo search "ti=solar AND pa=tesla"
+
+# Get publication data
+connect-epo publication biblio EP1000000
+
+# Get patent family
+connect-epo family get EP1000000
+```
+
+## CLI Usage
+
+### Search
+
+```bash
+# Search published patents using CQL query
+connect-epo search "ti=electric vehicle"
+connect-epo search "pa=siemens AND pd>=2020" --range 1-50
+```
+
+### Publications
+
+```bash
+# Get publication by number
+connect-epo publication get EP1000000
+
+# Get specific data
+connect-epo pub biblio EP1000000
+connect-epo pub abstract EP1000000
+connect-epo pub claims EP1000000
+connect-epo pub description EP1000000
+connect-epo pub images EP1000000
+```
+
+### Patent Family
+
+```bash
+# Get INPADOC family
+connect-epo family get EP1000000
+
+# With bibliographic data
+connect-epo family biblio EP1000000
+
+# With legal status
+connect-epo family legal EP1000000
+```
+
+### Legal Status
+
+```bash
+connect-epo legal EP1000000
+```
+
+### EP Register
+
+```bash
+# Search register
+connect-epo register search "pa=nokia"
+
+# Get register data
+connect-epo register get EP1000000
+
+# Get procedural steps
+connect-epo register steps EP1000000
+```
+
+### CPC Classification
+
+```bash
+# Look up classification
+connect-epo classification get H01L
+
+# With children
+connect-epo class get H01L --children
+
+# Search by keyword
+connect-epo class search "semiconductor"
+```
+
+### Configuration
+
+```bash
+# Set credentials
+connect-epo config set-credentials <key> <secret>
+
+# Show current config
+connect-epo config show
+
+# Test authentication
+connect-epo auth test
+
+# Manage profiles
+connect-epo profile create work --consumer-key xxx --consumer-secret xxx --use
+connect-epo profile list
+connect-epo profile use work
+```
+
+## Programmatic Usage
+
+```typescript
+import { EPO } from '@hasna/connect-epo';
+
+// Create client
+const epo = new EPO({
+  consumerKey: 'your-key',
+  consumerSecret: 'your-secret',
+});
+
+// Or from environment
+const epo = EPO.fromEnv();
+
+// Search patents
+const results = await epo.publications.search('ti=solar', {
+  rangeBegin: 1,
+  rangeEnd: 25,
+});
+
+// Get bibliographic data
+const biblio = await epo.publications.getBiblio('publication', 'epodoc', 'EP1000000');
+
+// Get patent family
+const family = await epo.family.getFamily('publication', 'epodoc', 'EP1000000');
+
+// Get legal status
+const legal = await epo.legal.getLegalStatus('publication', 'epodoc', 'EP1000000');
+
+// Search EP Register
+const register = await epo.register.search('pa=siemens');
+
+// Get CPC classification
+const cpc = await epo.classification.getCPC('H01L');
+```
+
+## CQL Query Syntax
+
+The EPO OPS API uses CQL (Contextual Query Language) for searches.
+
+### Common Fields
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `ti` | Title | `ti=solar cell` |
+| `ab` | Abstract | `ab=semiconductor` |
+| `pa` | Applicant | `pa=tesla` |
+| `in` | Inventor | `in=musk` |
+| `pn` | Publication number | `pn=EP1000000` |
+| `ap` | Application number | `ap=EP99123456` |
+| `pr` | Priority number | `pr=US2019123456` |
+| `pd` | Publication date | `pd=2020` or `pd>=20200101` |
+| `ic` | IPC classification | `ic=H01L` |
+| `cpc` | CPC classification | `cpc=H01L21` |
+
+### Operators
+
+- `AND` - Both conditions must match
+- `OR` - Either condition matches
+- `NOT` - Exclude matches
+- `=` - Equals
+- `>=`, `<=` - Date comparisons
+
+### Examples
+
+```bash
+# Solar patents by Tesla
+connect-epo search "ti=solar AND pa=tesla"
+
+# Electric vehicle patents since 2020
+connect-epo search "ti=electric vehicle AND pd>=2020"
+
+# Patents in semiconductor classification
+connect-epo search "ic=H01L AND ti=transistor"
+```
+
+## Document Reference Formats
+
+- **epodoc**: Simplified format (e.g., `EP1000000`) - recommended
+- **docdb**: Full format with kind code (e.g., `EP.1000000.A1`)
+- **original**: Original application format
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `EPO_CONSUMER_KEY` | Consumer key from EPO developer portal |
+| `EPO_CONSUMER_SECRET` | Consumer secret from EPO developer portal |
+| `EPO_BASE_URL` | Override API base URL (optional) |
+
+## Data Storage
+
+Configuration and tokens are stored in `~/.connect/connect-epo/`:
+
+```
+~/.connect/connect-epo/
+├── current_profile   # Active profile name
+├── token.json        # Cached OAuth token
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## API Rate Limits
+
+The EPO OPS API has usage limits based on your subscription:
+- Anonymous: 25 requests/week
+- Registered: Varies by plan
+
+See [EPO OPS documentation](https://www.epo.org/searching-for-patents/data/web-services/ops.html) for details.
+
+## License
+
+Apache-2.0