@hasna/connectors 1.3.43 → 1.3.44

package/connectors/unpaywall/src/cli/index.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env bun
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { Unpaywall } from '../api';
+import { getEmail, setEmail, clearConfig, getEmailPreview } from '../utils/config';
+import type { OutputFormat } from '../types';
+import { success, error, info, print } from '../utils/output';
+
+const CONNECTOR_NAME = 'connect-unpaywall';
+const VERSION = '0.1.0';
+
+const program = new Command();
+
+program
+  .name(CONNECTOR_NAME)
+  .description('Unpaywall open-access DOI lookup and search CLI')
+  .version(VERSION)
+  .option('-f, --format <format>', 'Output format (json, pretty)', 'pretty');
+
+function getFormat(cmd: Command): OutputFormat {
+  const parent = cmd.parent;
+  return (parent?.opts().format || cmd.opts().format || 'pretty') as OutputFormat;
+}
+
+const configCmd = program.command('config').description('Manage CLI configuration');
+
+configCmd.command('set-email <email>')
+  .description('Set email for Unpaywall API authentication')
+  .action((email: string) => {
+    setEmail(email);
+    success(`Email set to: ${getEmailPreview()}`);
+  });
+
+configCmd.command('show')
+  .description('Show current configuration')
+  .action(() => {
+    const preview = getEmailPreview();
+    console.log(chalk.bold('Unpaywall Configuration:'));
+    info(`Email: ${preview || chalk.gray('not set')}`);
+    info(`Set via UNPAYWALL_EMAIL env var or "config set-email <email>"`);
+  });
+
+configCmd.command('clear')
+  .description('Clear saved configuration')
+  .action(() => {
+    clearConfig();
+    success('Configuration cleared');
+  });
+
+program.command('get <doi>')
+  .description('Get OA status and bibliographic info for a DOI (e.g., 10.1038/nature12373)')
+  .action(async (doi: string) => {
+    try {
+      const unpaywall = new Unpaywall();
+      const result = await unpaywall.getDoi(doi);
+
+      if (getFormat(program) === 'json') {
+        print(result, 'json');
+      } else {
+        console.log(chalk.bold(result.title || result.doi));
+        console.log();
+        console.log(chalk.cyan(`DOI:        ${result.doi}`));
+        console.log(chalk.cyan(`OA Status:  ${result.oa_status} (is_oa: ${result.is_oa})`));
+        if (result.journal_name) console.log(chalk.cyan(`Journal:    ${result.journal_name}`));
+        if (result.publisher) console.log(chalk.cyan(`Publisher:  ${result.publisher}`));
+        if (result.published_date) console.log(chalk.cyan(`Published:  ${result.published_date}`));
+        if (result.year) console.log(chalk.cyan(`Year:       ${result.year}`));
+        if (result.best_oa_location?.url) {
+          console.log(chalk.blue(`Best OA:    ${result.best_oa_location.url}`));
+        }
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+program.command('search <query>')
+  .description('Search articles by title query')
+  .option('--oa <value>', 'Filter by OA status (true or false)')
+  .option('--page <number>', 'Page number (50 results per page)', '1')
+  .action(async (query: string, opts) => {
+    try {
+      const unpaywall = new Unpaywall();
+      const isOa = opts.oa !== undefined ? opts.oa === 'true' : undefined;
+      const page = parseInt(opts.page, 10);
+
+      const result = await unpaywall.search(query, { isOa, page });
+
+      if (getFormat(program) === 'json') {
+        print(result, 'json');
+      } else {
+        info(`Found ${result.results.length} results (page ${page})`);
+        for (const match of result.results) {
+          console.log();
+          const title = match.response.title || match.response.doi;
+          console.log(chalk.bold(title));
+          console.log(chalk.gray(`  score: ${match.score.toFixed(2)} | ${match.response.oa_status} | ${match.response.doi}`));
+          if (match.response.best_oa_location?.url) {
+            console.log(chalk.blue(`  ${match.response.best_oa_location.url}`));
+          }
+        }
+      }
+    } catch (err) {
+      error(String(err));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/connectors/unpaywall/src/index.ts

@@ -0,0 +1,11 @@
+// Unpaywall Open Access API Connector
+export { Unpaywall, UnpaywallClient, Connector } from './api';
+export * from './types';
+export {
+  loadConfig,
+  saveConfig,
+  getEmail,
+  setEmail,
+  clearConfig,
+  getEmailPreview,
+} from './utils/config';

package/connectors/unpaywall/src/types/index.ts

@@ -0,0 +1,62 @@
+export type OutputFormat = 'json' | 'pretty' | 'table';
+
+export type OaStatus = 'gold' | 'hybrid' | 'bronze' | 'green' | 'closed';
+
+export interface OaLocation {
+  url?: string;
+  url_for_pdf?: string;
+  url_for_landing_page?: string;
+  host_type?: string;
+  license?: string;
+  version?: string;
+  updated?: string;
+  evidence?: string;
+  is_best?: boolean;
+}
+
+export interface DoiObject {
+  doi: string;
+  doi_url?: string;
+  title?: string;
+  genre?: string;
+  is_paratext?: boolean;
+  published_date?: string;
+  year?: number;
+  journal_name?: string;
+  journal_issns?: string;
+  journal_is_oa?: boolean;
+  journal_is_in_doaj?: boolean;
+  publisher?: string;
+  is_oa: boolean;
+  oa_status: OaStatus;
+  has_repository_copy?: boolean;
+  best_oa_location?: OaLocation | null;
+  first_oa_location?: OaLocation | null;
+  oa_locations?: OaLocation[];
+  updated?: string;
+  data_standard?: number;
+  z_authors?: Array<{ given?: string; family?: string; sequence?: string }>;
+}
+
+export interface SearchMatch {
+  snippet: string;
+  score: number;
+  response: DoiObject;
+}
+
+export interface SearchOptions {
+  query: string;
+  isOa?: boolean;
+  page?: number;
+}
+
+export interface SearchResult {
+  results: SearchMatch[];
+}
+
+export class UnpaywallApiError extends Error {
+  constructor(message: string, public statusCode?: number, public responseBody?: string) {
+    super(message);
+    this.name = 'UnpaywallApiError';
+  }
+}

package/connectors/unpaywall/src/utils/config.ts

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONFIG_DIR = join(homedir(), '.hasna', 'connectors', 'connect-unpaywall');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export interface CliConfig {
+  email?: string;
+}
+
+function ensureConfigDir(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+export function loadConfig(): CliConfig {
+  ensureConfigDir();
+  if (!existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config: CliConfig): void {
+  ensureConfigDir();
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+export function getEmail(): string | undefined {
+  return process.env.UNPAYWALL_EMAIL || loadConfig().email;
+}
+
+export function setEmail(email: string): void {
+  const config = loadConfig();
+  config.email = email;
+  saveConfig(config);
+}
+
+export function clearConfig(): void {
+  saveConfig({});
+}
+
+export function getEmailPreview(): string | undefined {
+  const email = getEmail();
+  if (!email) return undefined;
+  const [local, domain] = email.split('@');
+  if (!domain) return '***';
+  if (local.length <= 2) return `***@${domain}`;
+  return `${local.slice(0, 2)}...@${domain}`;
+}

package/connectors/unpaywall/src/utils/output.ts

@@ -0,0 +1,28 @@
+import chalk from 'chalk';
+import type { OutputFormat } from '../types';
+
+export function success(message: string): void {
+  console.log(chalk.green('\u2713'), message);
+}
+
+export function error(message: string): void {
+  console.error(chalk.red('\u2717'), message);
+}
+
+export function warn(message: string): void {
+  console.log(chalk.yellow('\u26a0'), message);
+}
+
+export function info(message: string): void {
+  console.log(chalk.blue('\u2139'), message);
+}
+
+export function print(data: unknown, format: OutputFormat = 'pretty'): void {
+  if (format === 'json') {
+    console.log(JSON.stringify(data, null, 2));
+  } else if (format === 'table' && Array.isArray(data)) {
+    console.table(data);
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}

package/connectors/unpaywall/tsconfig.json

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

package/connectors/upcloud/.env.example

@@ -0,0 +1,5 @@
+# UpCloud API credentials
+# Create API credentials at https://hub.upcloud.com/account/people
+
+UPCLOUD_USERNAME=your-api-username
+UPCLOUD_PASSWORD=your-api-password

package/connectors/upcloud/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+connect-upcloud is a TypeScript connector for UpCloud's REST API (v1.3). It provides a CLI and programmatic interface for managing cloud servers, storage, and networking.
+
+## Build & Run Commands
+
+```bash
+bun install           # Install dependencies
+bun run dev           # Run CLI in development
+bun run build         # Build for distribution
+bun run typecheck     # Type check
+bun test              # Run tests
+```
+
+## Authentication
+
+UpCloud uses HTTP Basic authentication with API username and password.
+
+Get credentials from: https://hub.upcloud.com/account/people
+
+| Variable | Description |
+|----------|-------------|
+| `UPCLOUD_USERNAME` | API username (overrides profile) |
+| `UPCLOUD_PASSWORD` | API password (overrides profile) |
+
+Profile JSON structure:
+```json
+{
+  "apiKey": "api-username",
+  "apiSecret": "api-password"
+}
+```
+
+## Data Storage
+
+```
+~/.hasna/connectors/connect-upcloud/
+├── current_profile
+└── profiles/
+    └── default.json
+```
+
+## API Base URL
+
+`https://api.upcloud.com/1.3`
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # HTTP client with Basic auth
+│   ├── account.ts    # Account, plans, zones
+│   ├── servers.ts    # Server lifecycle
+│   ├── storage.ts    # Storage operations
+│   ├── network.ts    # IP addresses, firewall, networks
+│   └── index.ts      # UpCloud API wrapper
+├── 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
+```
+
+## Error Handling
+
+UpCloud returns errors in `{ error: { error_code, error_message } }` format. The client throws `UpCloudApiError` with the parsed message.

package/connectors/upcloud/README.md

@@ -0,0 +1,80 @@
+# connect-upcloud
+
+UpCloud connector - Manage cloud servers, storage, and networking via the UpCloud API.
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-upcloud
+```
+
+## Quick Start
+
+```bash
+# Set credentials
+connect-upcloud config set-username YOUR_API_USERNAME
+connect-upcloud config set-password YOUR_API_PASSWORD
+
+# Or use environment variables
+export UPCLOUD_USERNAME=YOUR_API_USERNAME
+export UPCLOUD_PASSWORD=YOUR_API_PASSWORD
+```
+
+Create API credentials at https://hub.upcloud.com/account/people
+
+## CLI Commands
+
+### Account
+```bash
+connect-upcloud account          # Get account info
+connect-upcloud plans            # List server plans
+connect-upcloud zones            # List zones
+connect-upcloud prices           # List prices
+```
+
+### Servers
+```bash
+connect-upcloud server list
+connect-upcloud server get <uuid>
+connect-upcloud server create -n <hostname> -z <zone>
+connect-upcloud server start <uuid>
+connect-upcloud server stop <uuid>
+connect-upcloud server restart <uuid>
+connect-upcloud server delete <uuid>
+```
+
+### Storage
+```bash
+connect-upcloud storage list
+connect-upcloud storage get <uuid>
+connect-upcloud storage create -n <title> -s <size> -z <zone>
+connect-upcloud storage attach <serverUuid> <storageUuid>
+connect-upcloud storage detach <serverUuid> <address>
+connect-upcloud storage delete <uuid>
+```
+
+### Network
+```bash
+connect-upcloud network ip-list
+connect-upcloud network ip-get <ip>
+connect-upcloud network firewall-list <serverUuid>
+connect-upcloud network list
+```
+
+## Programmatic Usage
+
+```typescript
+import { UpCloud } from '@hasna/connect-upcloud';
+
+const client = new UpCloud({
+  apiKey: process.env.UPCLOUD_USERNAME!,
+  apiSecret: process.env.UPCLOUD_PASSWORD!,
+});
+
+const { account } = await client.account.getAccount();
+const { servers } = await client.servers.listServers();
+```
+
+## License
+
+Apache-2.0

package/connectors/upcloud/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@hasna/connect-upcloud",
+  "version": "0.0.1",
+  "description": "UpCloud connector - Manage cloud servers, storage, and networking",
+  "type": "module",
+  "bin": {
+    "connect-upcloud": "./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",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "upcloud",
+    "cloud",
+    "vps",
+    "servers",
+    "storage",
+    "network",
+    "infrastructure",
+    "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/upcloud/src/api/account.ts

@@ -0,0 +1,50 @@
+import type { UpCloudClient } from './client';
+import type { Account, Plan, Zone } from '../types';
+
+export class AccountApi {
+  constructor(private client: UpCloudClient) {}
+
+  async getAccount(): Promise<{ account: Account }> {
+    return this.client.get<{ account: Account }>('/account');
+  }
+
+  async getAccountDetails(): Promise<unknown> {
+    return this.client.get('/account/details');
+  }
+
+  async listSubAccounts(): Promise<unknown> {
+    return this.client.get('/account/sub');
+  }
+
+  async listPrices(): Promise<unknown> {
+    return this.client.get('/price');
+  }
+
+  async listPlans(): Promise<{ plans: { plan: Plan[] } }> {
+    return this.client.get<{ plans: { plan: Plan[] } }>('/plan');
+  }
+
+  async listZones(): Promise<{ zones: { zone: Zone[] } }> {
+    return this.client.get<{ zones: { zone: Zone[] } }>('/zone');
+  }
+
+  async listTimezones(): Promise<unknown> {
+    return this.client.get('/timezone');
+  }
+
+  async listTags(): Promise<unknown> {
+    return this.client.get('/tag');
+  }
+
+  async listHosts(): Promise<unknown> {
+    return this.client.get('/host');
+  }
+
+  async getHost(id: number): Promise<unknown> {
+    return this.client.get(`/host/${id}`);
+  }
+
+  async listPermissions(): Promise<unknown> {
+    return this.client.get('/permission');
+  }
+}

package/connectors/upcloud/src/api/client.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from 'bun:test';
+import { UpCloudClient } from './client';
+import { UpCloudApiError } from '../types';
+
+describe('UpCloudClient', () => {
+  const mockConfig = {
+    apiKey: 'testuser99',
+    apiSecret: 'testpass123',
+  };
+
+  describe('constructor', () => {
+    test('throws error when username is missing', () => {
+      expect(() => new UpCloudClient({ apiKey: '', apiSecret: 'pass' })).toThrow('API username and password are required');
+    });
+
+    test('throws error when password is missing', () => {
+      expect(() => new UpCloudClient({ apiKey: 'user', apiSecret: '' })).toThrow('API username and password are required');
+    });
+
+    test('creates client with valid config', () => {
+      const client = new UpCloudClient(mockConfig);
+      expect(client).toBeInstanceOf(UpCloudClient);
+    });
+  });
+
+  describe('getUsernamePreview', () => {
+    test('returns masked username for long usernames', () => {
+      const client = new UpCloudClient(mockConfig);
+      const preview = client.getUsernamePreview();
+      expect(preview).toBe('test...er99');
+    });
+
+    test('returns *** for short usernames', () => {
+      const client = new UpCloudClient({ apiKey: 'short', apiSecret: 'pass' });
+      expect(client.getUsernamePreview()).toBe('***');
+    });
+  });
+
+  describe('request', () => {
+    let client: UpCloudClient;
+    let originalFetch: typeof global.fetch;
+
+    beforeEach(() => {
+      client = new UpCloudClient(mockConfig);
+      originalFetch = global.fetch;
+    });
+
+    afterEach(() => {
+      global.fetch = originalFetch;
+    });
+
+    test('sends Basic auth header', async () => {
+      const expectedAuth = `Basic ${Buffer.from('testuser99:testpass123').toString('base64')}`;
+      global.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Headers({ 'content-type': 'application/json' }),
+          text: () => Promise.resolve(JSON.stringify({ account: {} })),
+        } as Response)
+      );
+
+      await client.get('/account');
+
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+      const [, options] = (global.fetch as ReturnType<typeof mock>).mock.calls[0];
+      expect((options as RequestInit).headers).toMatchObject({
+        Authorization: expectedAuth,
+        Accept: 'application/json',
+      });
+    });
+
+    test('parses UpCloud error envelope', async () => {
+      global.fetch = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 401,
+          headers: new Headers({ 'content-type': 'application/json' }),
+          text: () => Promise.resolve(JSON.stringify({
+            error: { error_code: 'UNAUTHORIZED', error_message: 'Invalid credentials' },
+          })),
+        } as Response)
+      );
+
+      await expect(client.get('/account')).rejects.toThrow(UpCloudApiError);
+      await expect(client.get('/account')).rejects.toThrow('Invalid credentials');
+    });
+
+    test('handles 204 No Content', async () => {
+      global.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 204,
+          headers: new Headers(),
+          text: () => Promise.resolve(''),
+        } as Response)
+      );
+
+      const result = await client.delete('/server/test-uuid');
+      expect(result).toEqual({});
+    });
+  });
+});