zotero-client-ts

zotero-client-ts

A lightweight, minimalistic TypeScript client for the Zotero API.

Test Coverage

✅ 159/159 Tests Passing (100%)

All unit and integration tests passing.

api.spec.ts - 84 tests

• Request parameter handling (13 tests)
• GET request construction (24 tests)
• Write request construction (13 tests)
• Attachment requests (7 tests)
• Meta requests (9 tests)
• Pretend calls (3 tests)
• Access validation (1 test)
• Invalid call handling (8 tests)
• Extension/plugin system (5 tests)

request.spec.ts - 69 tests

• Meta read requests (4 tests)
• Item read requests (17 tests)
• Misc read requests (16 tests)
• GET requests with extra params (4 tests)
• Failing/empty/raw responses (6 tests)
• Item write & delete requests (12 tests)
• Failing write & delete requests (3 tests)
• File upload (13 tests - 3-stage process, error handling)
• File download (2 tests)
• Configuration (1 test)

smoke.test.ts - 6 tests

• Basic functionality smoke tests

Test Commands

# Run all tests
bun test
# Result: 159 pass, 0 fail, 650 expect() calls

# Run specific test suite
bun test test/api.spec.ts
bun test test/request.spec.ts
bun test test/smoke.test.ts

Development Notes

Architecture

The library follows the original's three-layer architecture:

• API Layer (src/api.ts): Fluent chainable interface using closure-based state
• Request Layer (src/request.ts): HTTP communication, retry logic, file handling
• Response Layer (src/response.ts): Specialized response classes for different operations

Key Design Decisions

• 100% API Compatibility: Every method signature matches the original exactly
• Modern TypeScript: Leveraging TypeScript's type system for better DX
• Bun-first: Optimized for Bun runtime, but works in Node.js 18+

Testing Strategy

• Unit Tests: Each module tested in isolation
• Integration Tests: Full request/response cycles with mocks
• Compatibility Tests: Side-by-side with original library

Build Artifacts

dist/
├── index.js       - ESM bundle (31.4 KB)
├── index.cjs      - CommonJS bundle
└── *.d.ts         - TypeScript definitions

Quick Start

# Install dependencies
bun install

# Build the project
bun run build

# Run tests
bun test

# Type checking
bun run lint

Usage Example

import api from "zotero-client-ts";

// Initialize with API key
const zotero = api("YOUR_API_KEY").library("user", 12345).items().top();

// Fetch items
const response = await zotero.get();
console.log(response.getData());

// Chainable API
const item = await api("KEY").library("user", 123).items("ITEMKEY").version(42).get();

License

MIT License - see LICENSE file for details.