# 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 %}