Zotero-TS-API

Introduction

Zotero-TS-API is a TypeScript library that provides an intuitive interface for interacting with the Zotero API. Zotero is a reference management platform used by researchers, students, and professionals to organize their sources. This library allows you to manage libraries, collections, items, tags, and creators directly via API calls.

Key Features:

Connect to a Zotero library (user or group). Manage collections: create, update, delete, and retrieve. Manage items: create, update, delete, and retrieve. Manipulate metadata: creators and tags. Quick Start

Installation

Ensure you have Node.js installed, then install the library via npm:

npm install zotero-ts-api

Configuration

Create a .env file at the root of your project to store your Zotero credentials:

ZOTERO_API_KEY=your_api_key
ZOTERO_GROUP_ID=your_group_id

Example Usage

Here is a simple example to connect to a Zotero library and retrieve collections and items:

import { config } from 'dotenv';
import { Library } from 'zotero-ts-api';

// Load environment variables
config();

const apiKey = process.env.ZOTERO_API_KEY;
const groupId = process.env.ZOTERO_GROUP_ID;
const libraryType = 'groups'; // or 'users', then use a user API Key

(async () => {
  const library = new Library(apiKey, id, type);
  await library.connect();

  console.log(`Connected to library: ${library.name}`);

  const collections = await library.getCollections();
  console.log(`Found ${collections.length} collections`);

  const items = await library.getAllItems();
  console.log(`Found ${items.length} items`);

  items.forEach(item => {
    console.log(`Item Key: ${item.key}`);
    console.log(`Title: ${item.title}`);
    console.log(`Item Type: ${item.itemType}`);
    // item.delete(); // Suppression de l'élément    
  });
})();

References

Main Classes

Library

Represents a Zotero library.

• Constructor :

constructor(apiKey: string, libId: string, libraryType: 'users' | 'groups')

• Methods:
  • connect(): Promise: Connect to the library.
  • getCollections(): Promise<ZCollection[]>: Retrieve all collections.
  • getAllItems(): Promise<Item[]>: Retrieve all items.
  • createCollection(name: string, parentCollection?: string): Promise: - Create a new collection.
  • createItem(itemData: Partial): Promise: Create a new item.

ZCollection

Represents a collection in Zotero.

• Constructor

constructor(data: ICollectionData, apiKey: string, id: string, type: 'users' | 'groups')

• Methods:
  • getItems(): Promise<Item[]>: Retrieve items in the collection.
  • update(): Promise: Update the collection.
  • delete(): Promise: Delete the collection.

Item

Represents an item (bibliographic reference).

• Constructor

constructor(data: IItemData, apiKey: string, id: string, type: 'users' | 'groups')

• Methods:
  • update(): Promise: Update the item.
  • delete(): Promise: Delete the item.
  • addCreator(creator: ZCreator): void: Add a creator.
  • addTag(tag: ZTag): void: Add a tag.

ZCreator

Represents a creator (author, editor, etc.).

• Constructor :

constructor(data: ICreatorData)

ZTag

Represents a tag associated with an item.

• Constructor :

constructor(data: ITagData)

Below is a diagram illustrating the relationships between the main entities:

classDiagram
    class Library {
        +connect(): Promise<void>
        +getCollections(): Promise<ZCollection[]>
        +getAllItems(): Promise<Item[]>
        +createCollection(name: string, parentCollection?: string): Promise<ZCollection>
        +createItem(itemData: Partial<IItemData>): Promise<Item>
    }

    class ZCollection {
        +getItems(): Promise<Item[]>
        +update(): Promise<void>
        +delete(): Promise<void>
    }

    class Item {
        +update(): Promise<void>
        +delete(): Promise<void>
        +addCreator(creator: ZCreator): void
        +addTag(tag: ZTag): void
    }

    class ZCreator {
        +creatorType: string
        +firstName: string
        +lastName: string
    }

    class ZTag {
        +tag: string
        +type: number
    }

    Library --> ZCollection : "has many"
    ZCollection --> Item : "contains"
    Item --> ZCreator : "has many"
    Item --> ZTag : "has many"