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:

1npm install zotero-ts-api

Configuration

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

1ZOTERO_API_KEY=your_api_key
2ZOTERO_GROUP_ID=your_group_id

Example Usage

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

1import { config } from 'dotenv';
2import { Library } from 'zotero-ts-api';
3
4// Load environment variables
5config();
6
7const apiKey = process.env.ZOTERO_API_KEY;
8const groupId = process.env.ZOTERO_GROUP_ID;
9const libraryType = 'groups'; // or 'users', then use a user API Key
10
11(async () => {
12  const library = new Library(apiKey, id, type);
13  await library.connect();
14
15  console.log(`Connected to library: ${library.name}`);
16
17  const collections = await library.getCollections();
18  console.log(`Found ${collections.length} collections`);
19
20  const items = await library.getAllItems();
21  console.log(`Found ${items.length} items`);
22
23  items.forEach(item => {
24    console.log(`Item Key: ${item.key}`);
25    console.log(`Title: ${item.title}`);
26    console.log(`Item Type: ${item.itemType}`);
27    // item.delete(); // Suppression de l'élément    
28  });
29})();

References

Main Classes

Library

Represents a Zotero library.

• Constructor :

1constructor(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

1constructor(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

1constructor(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 :

1constructor(data: ICreatorData)

---

ZTag

Represents a tag associated with an item.

• Constructor :

1constructor(data: ITagData)

---

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

1classDiagram
2    class Library {
3        +connect(): Promise<void>
4        +getCollections(): Promise<ZCollection[]>
5        +getAllItems(): Promise<Item[]>
6        +createCollection(name: string, parentCollection?: string): Promise<ZCollection>
7        +createItem(itemData: Partial<IItemData>): Promise<Item>
8    }
9
10    class ZCollection {
11        +getItems(): Promise<Item[]>
12        +update(): Promise<void>
13        +delete(): Promise<void>
14    }
15
16    class Item {
17        +update(): Promise<void>
18        +delete(): Promise<void>
19        +addCreator(creator: ZCreator): void
20        +addTag(tag: ZTag): void
21    }
22
23    class ZCreator {
24        +creatorType: string
25        +firstName: string
26        +lastName: string
27    }
28
29    class ZTag {
30        +tag: string
31        +type: number
32    }
33
34    Library --> ZCollection : "has many"
35    ZCollection --> Item : "contains"
36    Item --> ZCreator : "has many"
37    Item --> ZTag : "has many"