# Advanced : Event Hooks

{% hint style="danger" %}
**This is an early-stage feature**. Use at your own risk, and only if you're familiar with JavaScript programming.
{% endhint %}

The extension emits custom events when certain operations have taken place. These events use the prefix `zotero-roam:`, and the details they contain can provide a basis for automation.

## Events

<table data-header-hidden><thead><tr><th width="181.66666666666666">Event name</th><th>Triggered when...</th></tr></thead><tbody><tr><td><strong>metadata-added</strong></td><td>Metadata has been added to an item's page</td></tr><tr><td><strong>notes-added</strong></td><td>Notes have been added to an item's page</td></tr><tr><td><strong>tags-deleted</strong></td><td>Tags have been deleted from Zotero</td></tr><tr><td><strong>tags-modified</strong></td><td>Tags have been modified in Zotero</td></tr><tr><td><strong>update</strong></td><td>A data update request has completed</td></tr><tr><td><strong>update-collections</strong></td><td></td></tr><tr><td><strong>write</strong></td><td>A write request to Zotero has completed</td></tr></tbody></table>

## Schemas

### zotero-roam:metadata-added

{% code overflow="wrap" %}

```javascript
{
    args: {
        // The blocks received for insertion into the page.
        // Defined only if the default formatter or a JavaScript function was used.
        blocks?: [...],
        // The SmartBlock configuration received. 
        // Defined only if a SmartBlock was used.
        smartblock?: {
            param: "srcUid" | "srcName",
            paramValue: "some value"
        }
        uid: "some_uid",
    },
    error: null | Error, // The error thrown, if any
    page: {
        new: true | false, // Indicates if the Roam page was created during the operation
        title: "@citekey", // The title of the Roam page
        uid: "some_uid" // The UID of the Roam page
    },
    raw: {
        item: {...}, // The item's full Zotero metadata
        pdfs: [...], // The item's linked PDFs
        notes: [...] // The item's linked notes/annotations
    },
    success: null | true | false // The outcome of the operation
}
```

{% endcode %}

### zotero-roam:notes-added

{% code overflow="wrap" %}

```javascript
{
    args: {
        // The blocks received for insertion into the page.
        blocks: [...],
        uid: "some_uid",
    },
    error: null | Error, // The error thrown, if any
    page: {
        new: true | false, // Indicates if the Roam page was created during the operation
        title: "@citekey", // The title of the Roam page
        uid: "some_uid" // The UID of the Roam page
    },
    raw: {
        item: {...}, // The item's full Zotero metadata
        notes: [...] // The item's linked notes/annotations
    },
    success: null | true | false // The outcome of the operation
}
```

{% endcode %}

### zotero-roam:tags-deleted

{% code overflow="wrap" %}

```javascript
{
    data: *,
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456", // The path of the targeted library
    tags: ["a tag", "another tag"] // The tags provided to be deleted
}
```

{% endcode %}

### zotero-roam:tags-modified

{% code overflow="wrap" %}

```javascript
{
    args: {
        into: "new tag name", // The value provided to rename the tags with
        tags: ["a tag", "another tag"] // The list of tags provided to be renamed
    },
    data: {
        successful: [...], // The list of items successfully modified in Zotero
        failed: [...] // The failed requests' reason for failing
    },
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456" // The path of the targeted library
}
```

{% endcode %}

### zotero-roam:update

```javascript
{
    data: [...] | null, // The data received from the update
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456", // The path of the targeted library
    since: 0, // The version since which items were retrieved
    success: true | false // The outcome of the operation,
    type: "items"|"collections" // The type of data that was updated
}
```

### zotero-roam:write

{% code overflow="wrap" %}

```javascript
{
    args: {
        collections: [...], // The collections provided to be added to the items
        items: [...], // The items received to be added to Zotero
        tags: [...] // The tags provided to be added to the items
    },
    data: {
        successful: [...], // The items that were successfully added to Zotero
        failed: [...] // The items that could not be added to Zotero
    },
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456" // The path of the targeted library
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alix-lahuec.gitbook.io/zotero-roam/customization/custom-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.