@hasna/connectors 1.1.0 → 1.1.1

package/connectors/connect-wikipedia/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-wikipedia/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-wipo/.env.example

@@ -0,0 +1,13 @@
+# WIPO API Key (optional - many APIs are open)
+# Get your API key from: https://www.wipo.int/web-services/
+WIPO_API_KEY=your_api_key_here
+
+# Alternative env var name
+# WIPO_TOKEN=your_api_key_here
+
+# Optional: Browser automation settings
+# WIPO_HEADLESS=true
+# WIPO_BROWSER=chromium
+
+# Optional: Default output directory
+# WIPO_OUTPUT_DIR=./output

package/connectors/connect-wipo/CLAUDE.md

@@ -0,0 +1,234 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+connect-wipo is a TypeScript connector for WIPO (World Intellectual Property Organization) APIs with browser automation support via Playwright. It provides both API integration and browser automation for features not available through APIs.
+
+### API Features
+- **Patentscope** - PCT (Patent Cooperation Treaty) international patent application search
+- **Madrid System** - International trademark registrations (Madrid Monitor)
+- **WIPO Pearl** - Multilingual patent terminology and concept search
+
+### Browser Automation (Playwright)
+- **Patentscope Web** - PCT application search via browser
+- **Madrid Monitor** - International trademark search via browser
+- **Global Brand Database** - Trademark, appellation, and emblem search
+- **Document Downloads** - Download PCT documents and trademark images
+
+## 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 patentscope search "machine learning"
+bun run dev madrid search --mark "APPLE"
+bun run dev pearl search "semiconductor"
+bun run dev browser patentscope "AI technology"
+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, playwright
+- Type annotations required everywhere
+- Use interfaces for all API types
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts       # HTTP client for WIPO APIs
+│   ├── patentscope.ts  # Patentscope API (PCT applications)
+│   ├── madrid.ts       # Madrid System API (international trademarks)
+│   ├── pearl.ts        # WIPO Pearl API (terminology)
+│   ├── browser.ts      # Playwright browser automation
+│   └── index.ts        # Main WIPO 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 Endpoints
+
+| Endpoint | Base URL | Purpose |
+|----------|----------|---------|
+| Patentscope | https://patentscope.wipo.int/search/api | PCT application search |
+| Patentscope WS | https://patentscope.wipo.int/wapps/ws | Web services |
+| Madrid | https://www3.wipo.int/madrid/monitor/api | Madrid trademark system |
+| Madrid Gazette | https://www.wipo.int/madrid/gazette/api | Gazette publications |
+| WIPO Pearl | https://wipopearl.wipo.int/api/v1 | Terminology database |
+| Global Brand | https://www3.wipo.int/branddb/api | Global brand database |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WIPO_API_KEY` | API key (optional for most APIs) |
+| `WIPO_TOKEN` | Alternative API key variable |
+| `WIPO_HEADLESS` | Run browser in headless mode (default: true) |
+| `WIPO_BROWSER` | Browser to use: chromium, firefox, webkit |
+| `WIPO_OUTPUT_DIR` | Output directory for downloads |
+
+## Data Storage
+
+```
+~/.connect/connect-wipo/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+Profile JSON structure:
+```json
+{
+  "apiKey": "optional-key",
+  "headless": true,
+  "browser": "chromium",
+  "outputDir": "./output"
+}
+```
+
+## CLI Usage
+
+```bash
+# Patentscope operations (PCT applications)
+connect-wipo patentscope search "artificial intelligence"
+connect-wipo patentscope get PCT/US2024/123456
+connect-wipo patentscope publication WO/2024/123456
+connect-wipo patentscope documents PCT/US2024/123456
+connect-wipo patentscope family PCT/US2024/123456
+connect-wipo patentscope by-applicant "Google LLC"
+connect-wipo patentscope by-inventor "John Smith"
+connect-wipo patentscope recent
+
+# Madrid System operations (international trademarks)
+connect-wipo madrid search --mark "APPLE"
+connect-wipo madrid get 1234567
+connect-wipo madrid status 1234567
+connect-wipo madrid documents 1234567
+connect-wipo madrid check "MY BRAND"
+connect-wipo madrid by-holder "Apple Inc"
+connect-wipo madrid by-country US
+connect-wipo madrid expiring --days 90
+
+# WIPO Pearl operations (terminology)
+connect-wipo pearl search "semiconductor"
+connect-wipo pearl translate "patent" --source en --target de,fr,zh
+connect-wipo pearl concept C12345
+connect-wipo pearl concepts "machine learning"
+connect-wipo pearl synonyms "patent" --language en
+connect-wipo pearl languages
+connect-wipo pearl domains
+
+# Browser automation
+connect-wipo browser patentscope "drone technology"
+connect-wipo browser madrid "TECH BRAND"
+connect-wipo browser global-brand "BRAND NAME"
+connect-wipo browser download-pct PCT/US2024/123456 ./document.pdf
+connect-wipo browser download-trademark-image 1234567 ./trademark.png
+connect-wipo browser check-trademark "MY BRAND NAME"
+
+# Configuration
+connect-wipo config set-key your-api-key
+connect-wipo config set-headless true
+connect-wipo config set-browser chromium
+connect-wipo config show
+connect-wipo profile create work --api-key xxx --use
+connect-wipo profile list
+```
+
+## Programmatic Usage
+
+```typescript
+import { WIPO } from '@hasnaxyz/connect-wipo';
+
+// Create client (API key optional for most operations)
+const wipo = new WIPO({ headless: true });
+
+// Or from environment
+const wipo = WIPO.fromEnv();
+
+// Search PCT applications
+const pctResults = await wipo.patentscope.search({
+  query: 'machine learning',
+  rows: 25
+});
+
+// Get specific PCT application
+const app = await wipo.patentscope.getByApplicationNumber('PCT/US2024/123456');
+
+// Search international trademarks
+const marks = await wipo.madrid.search({
+  markName: 'APPLE',
+  status: 'active'
+});
+
+// Check trademark availability
+const { available, conflicts } = await wipo.madrid.checkAvailability('MY BRAND');
+
+// Get mark status
+const status = await wipo.madrid.getStatus('1234567');
+
+// Search terminology
+const terms = await wipo.pearl.searchTerms({
+  term: 'semiconductor',
+  sourceLanguage: 'en',
+  targetLanguages: ['de', 'fr', 'zh']
+});
+
+// Translate a term
+const translation = await wipo.pearl.translate('patent', 'en', ['de', 'fr']);
+
+// Browser automation - Patentscope search
+const browserResults = await wipo.browser.searchPatentscope({
+  query: 'TECH BRAND',
+  searchType: 'simple',
+});
+
+// Check trademark via browser
+const browserCheck = await wipo.browser.checkTrademarkAvailability('MY BRAND');
+
+// Download PCT document
+await wipo.browser.downloadPCTDocument('PCT/US2024/123456', './document.pdf');
+
+// Always close browser resources when done
+await wipo.close();
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling
+- playwright: Browser automation
+
+## Notes
+
+- Most WIPO APIs don't require authentication for read operations
+- Browser automation requires Playwright browsers to be installed (`bunx playwright install chromium`)
+- Patentscope contains 100M+ patent documents from PCT and national collections
+- Madrid System covers international trademark registrations under the Madrid Protocol
+- WIPO Pearl provides multilingual patent terminology across major languages

package/connectors/connect-wipo/README.md

@@ -0,0 +1,207 @@
+# connect-wipo
+
+WIPO (World Intellectual Property Organization) API connector CLI and SDK with browser automation.
+
+## Features
+
+- **Patentscope** - PCT international patent application search (100M+ documents)
+- **Madrid System** - International trademark registrations (Madrid Monitor)
+- **WIPO Pearl** - Multilingual patent terminology and concept search
+- **Browser Automation** - Playwright-based automation for web features
+- **Multi-profile Support** - Switch between different configurations
+
+## Quick Start
+
+```bash
+# Install globally
+bun install -g @hasna/connect-wipo
+
+# Or run locally
+bun run dev --help
+
+# Search PCT applications
+connect-wipo patentscope search "machine learning"
+
+# Search international trademarks
+connect-wipo madrid search --mark "APPLE"
+
+# Search terminology
+connect-wipo pearl search "semiconductor"
+
+# Browser automation (requires Playwright)
+bunx playwright install chromium
+connect-wipo browser patentscope "AI technology"
+```
+
+## Installation
+
+```bash
+# Install package
+bun add @hasna/connect-wipo
+
+# Install Playwright browsers for automation features
+bunx playwright install chromium
+```
+
+## CLI Commands
+
+### Patentscope (PCT Applications)
+
+```bash
+connect-wipo patentscope search <query>              # Search PCT applications
+connect-wipo patentscope get <applicationNumber>     # Get by PCT number
+connect-wipo patentscope publication <woNumber>      # Get by WO number
+connect-wipo patentscope documents <applicationNum>  # List documents
+connect-wipo patentscope family <applicationNum>     # Get family members
+connect-wipo patentscope by-applicant <name>         # Search by applicant
+connect-wipo patentscope by-inventor <name>          # Search by inventor
+connect-wipo patentscope recent                      # Recent applications
+```
+
+### Madrid System (International Trademarks)
+
+```bash
+connect-wipo madrid search                           # Search with options
+connect-wipo madrid get <registrationNumber>         # Get by IRN
+connect-wipo madrid status <registrationNumber>      # Get status
+connect-wipo madrid documents <registrationNumber>   # List documents
+connect-wipo madrid check <mark>                     # Check availability
+connect-wipo madrid by-holder <name>                 # Search by holder
+connect-wipo madrid by-country <code>                # Search by country
+connect-wipo madrid expiring                         # Marks expiring soon
+```
+
+### WIPO Pearl (Terminology)
+
+```bash
+connect-wipo pearl search <term>                     # Search terms
+connect-wipo pearl translate <term> -s en -t de,fr   # Translate term
+connect-wipo pearl concept <conceptId>               # Get concept
+connect-wipo pearl concepts <query>                  # Search concepts
+connect-wipo pearl synonyms <term> -l en             # Find synonyms
+connect-wipo pearl languages                         # List languages
+connect-wipo pearl domains                           # List domains
+```
+
+### Browser Automation
+
+```bash
+connect-wipo browser patentscope <query>             # Search Patentscope
+connect-wipo browser madrid <markName>               # Search Madrid Monitor
+connect-wipo browser global-brand <query>            # Search Global Brand DB
+connect-wipo browser download-pct <num> <output>     # Download PCT doc
+connect-wipo browser download-trademark-image <irn> <output>
+connect-wipo browser check-trademark <mark>          # Check via browser
+```
+
+### Configuration
+
+```bash
+connect-wipo config set-key <apiKey>                 # Set API key (optional)
+connect-wipo config set-headless true|false          # Browser visibility
+connect-wipo config set-browser chromium             # chromium|firefox|webkit
+connect-wipo config show                             # Show config
+connect-wipo profile list                            # List profiles
+connect-wipo profile create <name>                   # Create profile
+connect-wipo profile use <name>                      # Switch profile
+```
+
+## SDK Usage
+
+```typescript
+import { WIPO } from '@hasna/connect-wipo';
+
+// Create client
+const wipo = new WIPO({ headless: true });
+
+// Search PCT applications
+const pct = await wipo.patentscope.search({
+  query: 'artificial intelligence',
+  rows: 25
+});
+
+// Get specific PCT application
+const app = await wipo.patentscope.getByApplicationNumber('PCT/US2024/123456');
+
+// Search international trademarks
+const marks = await wipo.madrid.search({
+  markName: 'APPLE',
+  status: 'active'
+});
+
+// Check trademark availability
+const { available, conflicts } = await wipo.madrid.checkAvailability('MY BRAND');
+
+// Search terminology
+const terms = await wipo.pearl.searchTerms({
+  term: 'semiconductor',
+  sourceLanguage: 'en'
+});
+
+// Translate a term
+const translation = await wipo.pearl.translate('patent', 'en', ['de', 'fr']);
+
+// Browser automation - Patentscope search
+const results = await wipo.browser.searchPatentscope({
+  query: 'TECH',
+  searchType: 'simple',
+});
+
+// Download PCT document
+await wipo.browser.downloadPCTDocument('PCT/US2024/123456', './doc.pdf');
+
+// Always close when done
+await wipo.close();
+```
+
+## API Modules
+
+- `wipo.patentscope` - PCT application search, documents, family
+- `wipo.madrid` - International trademark search, status, documents
+- `wipo.pearl` - Terminology search, translation, concepts
+- `wipo.browser` - Playwright automation for web features
+
+## Configuration
+
+Configuration stored in `~/.connect/connect-wipo/`:
+
+```
+~/.connect/connect-wipo/
+├── current_profile
+└── profiles/
+    ├── default.json
+    └── {name}.json
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WIPO_API_KEY` | API key (optional for most operations) |
+| `WIPO_HEADLESS` | Browser headless mode (default: true) |
+| `WIPO_BROWSER` | Browser: chromium, firefox, webkit |
+
+## Development
+
+```bash
+bun install          # Install dependencies
+bun run typecheck    # Type check
+bun run build        # Build for production
+bun run dev          # Run CLI in development mode
+```
+
+## Output Formats
+
+Use `-f json` for JSON output:
+
+```bash
+connect-wipo patentscope search "AI" -f json | jq '.applications[0].title'
+```
+
+## Notes
+
+- Most WIPO APIs don't require authentication
+- Browser automation requires Playwright browsers
+- Patentscope contains 100M+ patent documents
+- Madrid System covers international trademark registrations
+- WIPO Pearl provides multilingual patent terminology