@hasna/connectors 1.3.45 → 1.4.0

package/connectors/zotero/README.md

@@ -0,0 +1,91 @@
+# @hasna/connect-zotero
+
+Zotero Web API v3 connector with CLI and library support. Manage bibliography items, collections, and file attachments via the official Zotero REST API.
+
+## Installation
+
+```bash
+bun add @hasna/connect-zotero
+```
+
+For CLI usage:
+
+```bash
+bun install -g @hasna/connect-zotero
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export ZOTERO_API_KEY="your-api-key"
+export ZOTERO_LIBRARY_ID="your-library-id"
+export ZOTERO_LIBRARY_TYPE="users"   # or groups
+# export ZOTERO_BASE_URL="https://api.zotero.org"
+```
+
+### CLI Configuration
+
+```bash
+connect-zotero config set-api-key <key>
+connect-zotero config set-library-id <id>
+connect-zotero config set-library-type users
+connect-zotero config show
+```
+
+Configuration is stored in `~/.hasna/connectors/connect-zotero/`.
+
+## CLI Usage
+
+```bash
+# Test authentication
+connect-zotero test
+
+# List items
+connect-zotero items list
+connect-zotero items list --collection <key> --limit 25
+
+# Search items
+connect-zotero items search "machine learning"
+
+# Get, create, update, delete items
+connect-zotero items get <itemKey>
+connect-zotero items create --json ./item.json
+connect-zotero items update <itemKey> --json ./patch.json --version 12
+connect-zotero items delete <itemKey> --version 12
+
+# Collections
+connect-zotero collections list
+connect-zotero collections create --json ./collection.json
+
+# Attachments
+connect-zotero attachments create --json ./attachment.json
+connect-zotero attachments upload --file ./paper.pdf --parent <itemKey>
+
+# Raw API escape hatch
+connect-zotero raw /users/1234567/items -X GET
+```
+
+## Library Usage
+
+```typescript
+import { Zotero } from '@hasna/connect-zotero';
+
+const zotero = new Zotero({
+  apiKey: process.env.ZOTERO_API_KEY!,
+  libraryId: process.env.ZOTERO_LIBRARY_ID!,
+  libraryType: 'users',
+});
+
+const items = await zotero.items.list({ limit: 10 });
+const results = await zotero.items.search('neural networks');
+```
+
+## API Reference
+
+- [Zotero Web API v3](https://www.zotero.org/support/dev/web_api/v3/start)
+
+## License
+
+Apache-2.0

package/connectors/zotero/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hasna/connect-zotero",
+  "version": "0.0.1",
+  "description": "Zotero Web API v3 connector with CLI and library support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "connect-zotero": "bin/index.js"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "zotero",
+    "api",
+    "cli",
+    "connector",
+    "bibliography",
+    "citations"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "CLAUDE.md"
+  ]
+}

package/connectors/zotero/src/api/attachments.ts

@@ -0,0 +1,130 @@
+import { createHash } from 'node:crypto';
+import type {
+  CreateAttachmentInput,
+  CreateItemsResponse,
+  UploadAuthResponse,
+  UploadFileInput,
+} from '../types';
+import { ZoteroApiError } from '../types';
+import { encodePathSegment, ZoteroClient } from './client';
+import { ItemsApi } from './items';
+
+export class AttachmentsApi {
+  private readonly items: ItemsApi;
+
+  constructor(private readonly client: ZoteroClient) {
+    this.items = new ItemsApi(client);
+  }
+
+  async create(input: CreateAttachmentInput): Promise<CreateItemsResponse> {
+    const attachment = {
+      itemType: 'attachment',
+      linkMode: input.linkMode ?? 'imported_url',
+      parentItem: input.parentItem,
+      title: input.title ?? input.filename ?? input.url,
+      url: input.url,
+      accessDate: input.accessDate,
+      contentType: input.contentType,
+      filename: input.filename,
+      tags: input.tags ?? [],
+      collections: input.collections,
+      relations: input.relations ?? {},
+    };
+
+    return this.items.create(attachment);
+  }
+
+  async uploadFile(input: UploadFileInput): Promise<{
+    attachmentKey: string;
+    filename: string;
+    uploaded?: boolean;
+    exists?: boolean;
+    md5?: string;
+  }> {
+    const filename = input.filename;
+    const contentType = input.contentType ?? 'application/octet-stream';
+    const file = Buffer.from(input.content);
+    const mtime = String(input.mtime ?? Date.now());
+    const md5 = createHash('md5').update(file).digest('hex');
+
+    let attachmentKey = input.attachmentKey ?? '';
+
+    if (!attachmentKey) {
+      if (!input.parentItem) {
+        throw new ZoteroApiError('parentItem is required when attachmentKey is not provided', 'missing_parent');
+      }
+
+      const created = await this.create({
+        parentItem: input.parentItem,
+        linkMode: 'imported_file',
+        contentType,
+        filename,
+        title: filename,
+      });
+
+      attachmentKey = created.success?.['0'] ?? created.successful?.['0'] ?? '';
+      if (!attachmentKey) {
+        throw new ZoteroApiError('Attachment item was not created', 'create_failed');
+      }
+    }
+
+    const prefix = this.client.libraryPrefix();
+    const filePath = `${prefix}/items/${encodePathSegment(attachmentKey)}/file`;
+
+    const uploadAuthText = await this.client.requestText(filePath, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'If-None-Match': '*',
+      },
+      body: new URLSearchParams({
+        md5,
+        filename,
+        filesize: String(file.byteLength),
+        mtime,
+      }),
+    });
+
+    const uploadAuth = JSON.parse(uploadAuthText || '{}') as UploadAuthResponse;
+
+    if (uploadAuth.exists) {
+      return { attachmentKey, filename, exists: true };
+    }
+
+    if (!uploadAuth.url || !uploadAuth.contentType || !uploadAuth.uploadKey) {
+      throw new ZoteroApiError('File upload authorization response was incomplete', 'upload_auth_incomplete');
+    }
+
+    const uploadBody = Buffer.concat([
+      Buffer.from(uploadAuth.prefix ?? ''),
+      file,
+      Buffer.from(uploadAuth.suffix ?? ''),
+    ]);
+
+    const uploadResponse = await fetch(uploadAuth.url, {
+      method: 'POST',
+      headers: { 'Content-Type': uploadAuth.contentType },
+      body: uploadBody,
+    });
+
+    if (!uploadResponse.ok) {
+      const text = await uploadResponse.text();
+      throw new ZoteroApiError(
+        `File upload failed (${uploadResponse.status}): ${text.slice(0, 500)}`,
+        'upload_failed',
+        uploadResponse.status
+      );
+    }
+
+    await this.client.requestText(filePath, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'If-None-Match': '*',
+      },
+      body: new URLSearchParams({ upload: uploadAuth.uploadKey }),
+    });
+
+    return { attachmentKey, filename, uploaded: true, md5 };
+  }
+}

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

@@ -0,0 +1,166 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from 'bun:test';
+import {
+  ZoteroClient,
+  normalizeLibraryType,
+  buildLibraryPrefix,
+  buildZoteroUrl,
+  DEFAULT_BASE_URL,
+} from './client';
+import { ZoteroApiError } from '../types';
+
+describe('ZoteroClient helpers', () => {
+  test('normalizeLibraryType maps group to groups', () => {
+    expect(normalizeLibraryType('users')).toBe('users');
+    expect(normalizeLibraryType('groups')).toBe('groups');
+    expect(normalizeLibraryType('group')).toBe('groups');
+    expect(normalizeLibraryType(undefined)).toBe('users');
+  });
+
+  test('buildLibraryPrefix encodes library id and type', () => {
+    expect(buildLibraryPrefix('12345', 'users')).toBe('/users/12345');
+    expect(buildLibraryPrefix('abc/def', 'groups')).toBe('/groups/abc%2Fdef');
+  });
+
+  test('buildZoteroUrl appends query params and strips trailing slash', () => {
+    const url = buildZoteroUrl(`${DEFAULT_BASE_URL}/`, '/users/1/items', {
+      limit: 10,
+      q: 'test query',
+      empty: '',
+      skip: undefined,
+    });
+    expect(url).toBe('https://api.zotero.org/users/1/items?limit=10&q=test+query');
+  });
+});
+
+describe('ZoteroClient', () => {
+  const mockConfig = {
+    apiKey: 'test-api-key',
+    libraryId: '1234567',
+    libraryType: 'users' as const,
+    baseUrl: 'https://api.zotero.org',
+  };
+
+  describe('constructor', () => {
+    test('throws when api key is missing', () => {
+      expect(() => new ZoteroClient({ apiKey: '', libraryId: '1' })).toThrow('Zotero API key is required');
+    });
+
+    test('throws when library id is missing', () => {
+      expect(() => new ZoteroClient({ apiKey: 'key', libraryId: '' })).toThrow('Zotero library ID is required');
+    });
+
+    test('creates client with valid config', () => {
+      const client = new ZoteroClient(mockConfig);
+      expect(client.libraryPrefix()).toBe('/users/1234567');
+    });
+
+    test('normalizes group library type', () => {
+      const client = new ZoteroClient({ ...mockConfig, libraryType: 'group' });
+      expect(client.libraryPrefix()).toBe('/groups/1234567');
+    });
+  });
+
+  describe('request', () => {
+    let client: ZoteroClient;
+    let originalFetch: typeof global.fetch;
+    let fetchMock: ReturnType<typeof mock>;
+
+    beforeEach(() => {
+      client = new ZoteroClient(mockConfig);
+      originalFetch = global.fetch;
+    });
+
+    afterEach(() => {
+      global.fetch = originalFetch;
+    });
+
+    test('sends required Zotero headers on GET', async () => {
+      fetchMock = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Headers({ 'content-type': 'application/json' }),
+          text: () => Promise.resolve('[]'),
+        } as Response)
+      );
+      global.fetch = fetchMock as unknown as typeof fetch;
+
+      await client.get('/users/1234567/items', { limit: 1 });
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const [url, options] = fetchMock.mock.calls[0];
+      expect(url).toBe('https://api.zotero.org/users/1234567/items?limit=1');
+      expect(options.method).toBe('GET');
+      expect(options.headers['Zotero-API-Key']).toBe('test-api-key');
+      expect(options.headers['Zotero-API-Version']).toBe('3');
+      expect(options.headers.Accept).toBe('application/json');
+    });
+
+    test('includes version header on PATCH', async () => {
+      fetchMock = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Headers({ 'content-type': 'application/json' }),
+          text: () => Promise.resolve('{}'),
+        } as Response)
+      );
+      global.fetch = fetchMock as unknown as typeof fetch;
+
+      await client.patch('/users/1234567/items/ABC123', { title: 'Updated' }, { version: 42 });
+
+      const [, options] = fetchMock.mock.calls[0];
+      expect(options.method).toBe('PATCH');
+      expect(options.headers['If-Unmodified-Since-Version']).toBe('42');
+    });
+
+    test('includes version header on DELETE', async () => {
+      fetchMock = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 204,
+          headers: new Headers({}),
+          text: () => Promise.resolve(''),
+        } as Response)
+      );
+      global.fetch = fetchMock as unknown as typeof fetch;
+
+      await client.delete('/users/1234567/items/ABC123', { version: 7 });
+
+      const [, options] = fetchMock.mock.calls[0];
+      expect(options.method).toBe('DELETE');
+      expect(options.headers['If-Unmodified-Since-Version']).toBe('7');
+    });
+
+    test('throws ZoteroApiError on failed response', async () => {
+      fetchMock = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 403,
+          statusText: 'Forbidden',
+          headers: new Headers({ 'content-type': 'application/json' }),
+          text: () => Promise.resolve(JSON.stringify({ message: 'Invalid key' })),
+        } as Response)
+      );
+      global.fetch = fetchMock as unknown as typeof fetch;
+
+      await expect(client.get('/users/1234567/items')).rejects.toThrow(ZoteroApiError);
+    });
+  });
+});
+
+describe('upload auth parsing', () => {
+  test('parses upload authorization response shape', () => {
+    const response = {
+      url: 'https://upload.example.com/',
+      contentType: 'multipart/form-data',
+      uploadKey: 'abc123',
+      prefix: '--boundary\r\n',
+      suffix: '\r\n--boundary--',
+    };
+
+    expect(response.url).toBeTruthy();
+    expect(response.contentType).toBeTruthy();
+    expect(response.uploadKey).toBeTruthy();
+  });
+});

package/connectors/zotero/src/api/client.ts

@@ -0,0 +1,169 @@
+import type { LibraryType, RequestOptions, ZoteroConfig } from '../types';
+import { ZoteroApiError } from '../types';
+
+export const DEFAULT_BASE_URL = 'https://api.zotero.org';
+export const ZOTERO_API_VERSION = '3';
+
+export function normalizeLibraryType(libraryType?: LibraryType | 'group'): LibraryType {
+  return libraryType === 'groups' || libraryType === 'group' ? 'groups' : 'users';
+}
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value);
+}
+
+export function buildLibraryPrefix(libraryId: string, libraryType?: LibraryType | 'group'): string {
+  const normalizedType = normalizeLibraryType(libraryType);
+  return `/${normalizedType}/${encodePathSegment(libraryId)}`;
+}
+
+export function buildZoteroUrl(
+  baseUrl: string,
+  path: string,
+  params?: Record<string, string | number | boolean | undefined>
+): string {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  const url = new URL(`${baseUrl.replace(/\/$/, '')}${normalizedPath}`);
+
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null && value !== '') {
+        url.searchParams.append(key, String(value));
+      }
+    }
+  }
+
+  return url.toString();
+}
+
+export class ZoteroClient {
+  private readonly apiKey: string;
+  private readonly libraryId: string;
+  private readonly libraryType: LibraryType;
+  private readonly baseUrl: string;
+
+  constructor(config: ZoteroConfig) {
+    if (!config.apiKey) {
+      throw new Error('Zotero API key is required');
+    }
+    if (!config.libraryId) {
+      throw new Error('Zotero library ID is required');
+    }
+
+    this.apiKey = config.apiKey;
+    this.libraryId = config.libraryId;
+    this.libraryType = normalizeLibraryType(config.libraryType);
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  libraryPrefix(): string {
+    return buildLibraryPrefix(this.libraryId, this.libraryType);
+  }
+
+  buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    return buildZoteroUrl(this.baseUrl, path, params);
+  }
+
+  defaultHeaders(extra?: Record<string, string>): Record<string, string> {
+    return {
+      'Zotero-API-Key': this.apiKey,
+      'Zotero-API-Version': ZOTERO_API_VERSION,
+      Accept: 'application/json',
+      ...extra,
+    };
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {}, version } = options;
+
+    const url = this.buildUrl(path, params);
+    const requestHeaders = this.defaultHeaders(headers);
+
+    if (version !== undefined) {
+      requestHeaders['If-Unmodified-Since-Version'] = String(version);
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body !== undefined && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      if (body instanceof URLSearchParams) {
+        fetchOptions.body = body;
+      } else if (body instanceof Buffer || body instanceof Uint8Array) {
+        fetchOptions.body = body as BodyInit;
+      } else if (typeof body === 'string') {
+        fetchOptions.body = body;
+      } else {
+        requestHeaders['Content-Type'] = requestHeaders['Content-Type'] || 'application/json';
+        fetchOptions.body = JSON.stringify(body);
+      }
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    const contentType = response.headers.get('content-type') || '';
+    let data: unknown;
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      data = text ? JSON.parse(text) : undefined;
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      const message = typeof data === 'string'
+        ? data.slice(0, 500)
+        : (data as { message?: string })?.message || response.statusText;
+      throw new ZoteroApiError(
+        `HTTP ${response.status}: ${message}`,
+        'http_error',
+        response.status
+      );
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(
+    path: string,
+    body?: unknown,
+    options: Omit<RequestOptions, 'method' | 'body'> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: 'POST', body });
+  }
+
+  async patch<T>(
+    path: string,
+    body?: unknown,
+    options: Omit<RequestOptions, 'method' | 'body'> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: 'PATCH', body });
+  }
+
+  async delete<T>(
+    path: string,
+    options: Omit<RequestOptions, 'method'> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: 'DELETE' });
+  }
+
+  async requestText(path: string, options: RequestOptions = {}): Promise<string> {
+    const result = await this.request<string>(path, options);
+    return typeof result === 'string' ? result : JSON.stringify(result);
+  }
+}

package/connectors/zotero/src/api/collections.ts

@@ -0,0 +1,26 @@
+import type { CreateCollectionInput, ZoteroCollection } from '../types';
+import { encodePathSegment, ZoteroClient } from './client';
+
+export class CollectionsApi {
+  constructor(private readonly client: ZoteroClient) {}
+
+  private collectionsPath(): string {
+    return `${this.client.libraryPrefix()}/collections`;
+  }
+
+  async list(): Promise<ZoteroCollection[]> {
+    return this.client.get<ZoteroCollection[]>(this.collectionsPath());
+  }
+
+  async get(collectionKey: string): Promise<ZoteroCollection> {
+    const prefix = this.client.libraryPrefix();
+    return this.client.get<ZoteroCollection>(
+      `${prefix}/collections/${encodePathSegment(collectionKey)}`
+    );
+  }
+
+  async create(collections: CreateCollectionInput | CreateCollectionInput[]): Promise<unknown> {
+    const payload = Array.isArray(collections) ? collections : [collections];
+    return this.client.post(this.collectionsPath(), payload);
+  }
+}

package/connectors/zotero/src/api/index.ts

@@ -0,0 +1,45 @@
+import type { ZoteroConfig, RequestOptions } from '../types';
+import { ZoteroClient } from './client';
+import { ItemsApi } from './items';
+import { CollectionsApi } from './collections';
+import { AttachmentsApi } from './attachments';
+
+export {
+  ZoteroClient,
+  DEFAULT_BASE_URL,
+  ZOTERO_API_VERSION,
+  normalizeLibraryType,
+  buildLibraryPrefix,
+  buildZoteroUrl,
+} from './client';
+export { ItemsApi } from './items';
+export { CollectionsApi } from './collections';
+export { AttachmentsApi } from './attachments';
+
+export class Zotero {
+  private readonly client: ZoteroClient;
+
+  public readonly items: ItemsApi;
+  public readonly collections: CollectionsApi;
+  public readonly attachments: AttachmentsApi;
+
+  constructor(config: ZoteroConfig) {
+    this.client = new ZoteroClient(config);
+    this.items = new ItemsApi(this.client);
+    this.collections = new CollectionsApi(this.client);
+    this.attachments = new AttachmentsApi(this.client);
+  }
+
+  async test(): Promise<unknown[]> {
+    const prefix = this.client.libraryPrefix();
+    return this.client.get(`${prefix}/items`, { limit: 1 });
+  }
+
+  async rawRequest<T = unknown>(path: string, options: RequestOptions = {}): Promise<T> {
+    return this.client.request<T>(path, options);
+  }
+
+  getClient(): ZoteroClient {
+    return this.client;
+  }
+}