docs: Update documentation to reflect new Notion authorization process (

#636)

* chore: Update license copyright to 2025

* docs: Update privacy policy to reflect new Notion authorization process

* docs: Update README to reflect new Notion authorization process

* docs(README): Specify correct `start:beta` command

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021–2022 David Hoff-Vanoni
+Copyright (c) 2021–2025 David Hoff-Vanoni
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

PRIVACY.md

@@ -1,18 +1,46 @@
 # Privacy Policy
 
-The Notero plugin collects only the data necessary to synchronize with Notion;
-specifically, this includes the user's Notion integration token and database ID.
-These values are stored on the user's local computer alongside Zotero's other
-preferences within the [Zotero profile directory][zotero-profile].
-These values are transmitted to Notion for purposes of synchronization.
-They are not transmitted anywhere else.
+Last updated: January 10, 2025
+
+The Notero plugin primarily interacts with the user's local Zotero client and
+the Notion API. This document describes the data that the plugin accesses and
+how it is used.
+
+## Notion Authorization
+
+The Notero plugin uses a Notion public integration to authorize access to the
+user's selected Notion workspace(s) and database(s). For details on the
+authorization process, see the [Notion authorization guide][].
+
+The authorization process follows the OAuth 2.0 protocol and uses a proxy
+service to keep the OAuth client secret secure. The OAuth proxy service is
+managed by the Notero developer and is [open source][notero-auth]. The proxy
+service does not store any user data other than logs of basic network request
+information (e.g., IP address and user agent) captured by the hosting provider,
+[Cloudflare][Cloudflare Trust Hub].
+
+When the user completes the Notion authorization flow, the Notero plugin
+receives a Notion access token and securely stores it using the
+[Zotero login manager][]. Data stored with the login manager is encrypted and
+stored on the user's local computer within the [Zotero profile directory][].
+
+## User Data
+
+The Notero plugin stores user-specific data, including Notion database IDs and
+page URLs, on the user's local computer within the [Zotero profile directory][].
+These values are transmitted to Notion for purposes of synchronization and are
+not transmitted anywhere else.
 
 As part of the synchronization process, user-generated Zotero item data may be
-transmitted to Notion.
-These may include but are not limited to: notes, tags, and custom fields.
-Data saved in Notion is subject to [Notion Terms and Privacy][notion-terms].
+transmitted to Notion. These may include but are not limited to notes, tags, and
+custom fields. Data saved in Notion is subject to [Notion terms and privacy][].
 
-The Notero plugin does not communicate with any services other than Notion.
+The Notero plugin does not communicate with any services other than Notion and
+the OAuth proxy service.
 
-[notion-terms]: https://www.notion.so/28ffdd083dc3473e9c2da6ec011b58ac
-[zotero-profile]: https://www.zotero.org/support/kb/profile_directory
+[notero-auth]: https://github.com/dvanoni/notero-auth
+[Cloudflare Trust Hub]: https://www.cloudflare.com/trust-hub/
+[Notion authorization guide]: https://developers.notion.com/docs/authorization
+[Notion terms and privacy]: https://www.notion.so/28ffdd083dc3473e9c2da6ec011b58ac
+[Zotero login manager]: https://udn.realityripple.com/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILoginManager/Using_nsILoginManager
+[Zotero profile directory]: https://www.zotero.org/support/kb/profile_directory

README.md

@@ -8,12 +8,15 @@
 Notero is a [Zotero plugin](https://www.zotero.org/support/plugins) for syncing
 items and notes into [Notion](https://www.notion.so/product). To use it:
 
-1. 📔 [Configure](#configure-notion) your Notion database.
-2. 💾 [Install](#install-and-configure-notero-plugin) the Notero plugin into Zotero.
+1. 💾 [Install][] the Notero plugin into Zotero.
+2. 📔 [Connect][] and configure your Notion database.
 3. 📁 Choose your Zotero collections to monitor.
 4. 📝 Add or update items in your collections.
 5. 🔄 Watch your items sync into Notion!
 
+[Install]: #install-and-configure-notero-plugin
+[Connect]: #connect-to-notion
+
 ![Notero in action](docs/notero.gif)
 
 Concept by [@arhoff](https://github.com/arhoff) 👩🏻‍🔬 |
@@ -101,49 +104,94 @@ extract them into a Zotero note:
 
 ## Installation and Setup
 
-Using Notero requires setting up a Notion database, connecting it to Notero, and
-installing the Notero plugin in Zotero. Detailed setup instructions are below.
+Using Notero involves installing the plugin in Zotero and connecting it to a
+Notion database. Detailed setup instructions are below.
+
+### Install and Configure Notero Plugin
+
+> [!IMPORTANT]
+>
+> - The latest release of Notero requires Zotero 7.0 or above.
+> - Support for Zotero 6.0.27 and above is available in Notero [v0.5.17][].
+> - See the [changelog](CHANGELOG.md) for all release notes.
 
-### Configure Notion
+1. [Download][] the latest release of the `.xpi` file.
+   - Alternatively, download the `.xpi` file from the **Assets** section of the
+     [latest release][] page.
+   - Firefox users: Right-click the download link and choose **Save Link As...**
+     to download the file.
+2. Open the Zotero Plugins Manager via the **Tools → Plugins** menu item.
+3. Install the `.xpi` file by either:
+   - dragging and dropping it into the Plugins Manager window _or_
+   - selecting it using the **Install Plugin From File...** option in the
+     gear menu in the top-right corner of the window
+4. Open the Notero preferences from either the **Tools → Notero Preferences...**
+   menu item or the sidebar in the main Zotero preferences window.
+5. Configure the Notero preferences as desired.
 
-1.  Create the Notion database that you would like to sync Zotero items into.
+[download]: https://download.notero.vanoni.dev
+[latest release]: https://github.com/dvanoni/notero/releases/latest
+[v0.5.17]: https://github.com/dvanoni/notero/releases/tag/v0.5.17
 
-    See [examples](#example-notion-databases) below that you can duplicate into
-    your Notion workspace.
+### Connect to Notion
 
-2.  Create a Notion [internal integration](https://developers.notion.com/docs/create-a-notion-integration)
-    at https://www.notion.com/my-integrations and enable _all_ of the
-    "content capabilities."
+> [!NOTE]
+>
+> Before version 1.0.0, Notero required you to create your own Notion internal
+> integration and manually set the integration secret in the Notero preferences.
+> This is no longer necessary as Notero now uses a public integration with an
+> authentication flow provided by Notion.
+>
+> If you previously set up Notero with an internal integration, you can click
+> the **Upgrade Connection** button in the Notero preferences to switch to the
+> public integration as described below. Once complete, you can delete your
+> internal integration from the [Notion integrations][] page.
+
+1. Start the Notion connection process by clicking the **Connect to Notion**
+   button in the Notero preferences. This will open the Notion connection page
+   in your default web browser.
+2. On the Notion connection page, select your desired workspace from the menu
+   at the top (if you have multiple). Then, click **Next**.
+3. On the next page, choose whether you want to use a template database or
+   connect to an existing database page.
+   - If you choose to use a template, the [basic example](#basic-example)
+     database will be duplicated into your workspace.
+   - If you choose to select an existing database, you can search for and select
+     your preferred database on the next page. You can also select no database
+     and connect one later in Notion.
+4. Click **Allow access** to give Notero access to your Notion workspace and
+   database. You will then be redirected to a page that prompts you to open
+   Zotero.
+5. Click the **Open Zotero** button (or equivalent, depending on your web
+   browser) to complete the connection process in Zotero. The Notero preferences
+   should show that you are connected to your Notion workspace.
 
-    <details>
-      <summary>Example of integration capabilities settings</summary>
-      <img
-        alt="Notion integration capabilities settings"
-        src="docs/notion-capabilities.png"
-      />
-    </details>
+<details>
+  <summary>Example of connecting to Notion</summary>
+  <video src="https://github.com/user-attachments/assets/6c759c9d-f032-4060-bfd0-8da285ce0c2a" />
+</details>
 
-3.  Take note of the "internal integration secret" from the previous step.
+[Notion integrations]: https://www.notion.so/profile/integrations
 
-4.  Give your integration access to your database.
+### Configure Notion Database
 
-    From the [Notion developer docs](https://developers.notion.com/docs/create-a-notion-integration#give-your-integration-page-permissions):
+If you choose not to use the template database during the Notion connection
+process, you will need to create your own database. See
+[examples](#example-notion-databases) below that you can duplicate into
+your workspace, or create one from scratch with properties described in the
+[database properties](#notion-database-properties) section below.
 
-    > 1. Go to the database page in your workspace.
-    > 2. Click on the **•••** More menu in the top-right corner of the page.
-    > 3. Scroll down to and click **Connect to**.
-    > 4. Search for and select your integration in the **Search for connections...** menu.
+To give Notero access to your database, follow these steps:
 
-      <details>
-        <summary>Example of connection settings from the Notion documentation</summary>
-        <img
-          alt="Share database with integration"
-          src="https://files.readme.io/3e5cb5b-share-database-with-integration.gif"
-        />
-      </details>
+1. Go to the database page in your workspace.
+2. Click on the **•••** More menu in the top-right corner of the page.
+3. Scroll down to and click **Connections**.
+4. Search for and select **Notero** in the **Search for connections...** menu.
 
-5.  Configure the database properties as desired. See the
-    [database properties](#notion-database-properties) section below for more details.
+<details>
+  <summary>Example of connecting database to Notero</summary>
+  <video src="https://github.com/user-attachments/assets/c4c25fbe-4d66-4985-a23f-1972762906a7" />
+</details>
 
 #### Notion Database Properties
 
@@ -187,42 +235,14 @@ see issue [#355](https://github.com/dvanoni/notero/issues/355).
 | `Year`              | Number        |                                                                                |
 | `Zotero URI`        | URL           | Opens items in web library if signed in to Zotero                              |
 
-### Install and Configure Notero Plugin
-
-> [!IMPORTANT]
->
-> - The latest release of Notero requires Zotero 7.0 or above.
-> - Support for Zotero 6.0.27 and above is available in Notero [v0.5.17][].
-> - See the [changelog](CHANGELOG.md) for all release notes.
-
-1. [Download][] the latest release of the `.xpi` file.
-   - Note for Firefox users: You'll need to right-click the above download link
-     and choose **Save Link As...** in order to properly download the file.
-   - If the above download link does not work, you can download the `.xpi` file
-     from the **Assets** section of the [latest release][] page.
-2. Open the Zotero Plugins Manager via the **Tools → Plugins** menu item.
-3. Install the `.xpi` file by either:
-   - dragging and dropping it into the Plugins Manager window _or_
-   - selecting it using the **Install Plugin From File...** option in the
-     gear menu in the top-right corner of the window
-4. Open the Notero preferences from the **Tools → Notero Preferences...** menu
-   item, and enter the required preferences.
-   - Note for Zotero 7 users: The Notero preferences have moved into a section
-     in the main Zotero preferences window.
-
-[download]: https://download.notero.vanoni.dev
-[latest release]: https://github.com/dvanoni/notero/releases/latest
-[v0.5.17]: https://github.com/dvanoni/notero/releases/tag/v0.5.17
-
 ## Usage Guides
 
 For more visual guides of setting up and using Notero, see the following
 resources made by wonderful members of the community.
 
 > [!NOTE]
->
-> Some aspects of these resources may be out of date, so be sure to refer to
-> this README for the latest information.
+> Some aspects of these resources may be outdated, so be sure to refer to this
+> README for the latest information.
 
 - [Using Notion and Zotero to build a literature tracker](https://sciquest.netlify.app/posts/notion_literature/)
   (blog post) by [Jewel Johnson](https://jeweljohnsonj.github.io/jewel_resume/)
@@ -280,14 +300,10 @@ If you receive the following error:
 > APIResponseError: Could not find database with ID: _xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_
 
 This most likely means you have not given Notero access to your Notion database.
-Ensure you follow all the steps from the [Configure Notion](#configure-notion)
-section. Clicking the **•••** button in the top-right corner of your database
-should show a connection for the integration you've created for Notero.
-
-<details>
-  <summary>Example of connection settings</summary>
-  <img alt="Share with Notero" src="docs/share-with-notero.png" style="max-height:636px;" />
-</details>
+Ensure you follow the steps in the
+[Configure Notion Database](#configure-notion-database) section. Clicking the
+**•••** button in the top-right corner of your database should show a connection
+for the Notero integration.
 
 #### Can't update a page that is archived
 
@@ -397,7 +413,7 @@ documentation and should allow you to build and run Notero yourself.
 
     Alternatively, you can start your desired beta version of Zotero:
 
-        npm run start-beta
+        npm run start:beta
 
     The `start` script performs a number of steps: