@pipedream/readwise 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,11 @@
 # Overview
 
-The Readwise API is an amazing resource for building powerful applications that
-use Readwise's unique data and insights. Using the Readwise API, you can build
-applications that:
+The Readwise API allows you to access and manipulate your Readwise data, which includes highlights, notes, and books from your reading list. With this API, you can automate the retrieval of your reading highlights, synchronize them across various platforms, or trigger custom actions based on new highlights added. Pipedream, as a serverless integration and compute platform, enables you to create workflows that leverage the Readwise API to build powerful automations, connecting your reading insights to countless other apps and services to enrich productivity and data management.
 
-- Retrieve annotations and highlights from any book or article you’ve read
-  using Readwise.
-- Analyze and visualize insights from your annotations and highlights.
-- Perfoerm sentiment analysis on the data to identify topics.
-- Create interactive books or articles to help you better understand what
-  you’ve read.
-- Permalink any highlight or annotation you’ve saved through Readwise.
-- Create reading lists and summaries.
-- Send custom alerts and notifications when certain topics or keywords appear
-  in your highlights and annotations.
-- Create summary and progress reports for books or articles you’re reading.
+# Example Use Cases
+
+- **Sync Highlights to Notion Database**: Automatically add new Readwise highlights to a Notion database. Upon detecting a new highlight via the Readwise API, Pipedream can trigger a workflow that creates or updates a corresponding page in Notion, allowing for seamless management and review of reading notes.
+
+- **Create Weekly Reading Digest Email**: Compile a weekly digest of your Readwise highlights and send it via email. Pipedream schedules a weekly workflow that fetches the latest highlights and uses an email service, such as SendGrid, to craft and send a personalized reading digest.
+
+- **Trigger Slack Notifications for New Highlights**: Receive immediate notifications in Slack whenever a new highlight is added to your Readwise account. Pipedream listens for new Readwise highlights and sends a formatted message to a specified Slack channel, keeping you and your team informed about new insights.

package/actions/get-highlight-details/get-highlight-details.mjs

@@ -0,0 +1,41 @@
+import readwise from "../../readwise.app.mjs";
+
+export default {
+  key: "readwise-get-highlight-details",
+  name: "Get Highlight Details",
+  description: "Get Highlight´s Details [See the docs here](https://readwise.io/api_deets)",
+  version: "0.0.4",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    readwise,
+    bookId: {
+      propDefinition: [
+        readwise,
+        "bookId",
+      ],
+    },
+    highlightId: {
+      propDefinition: [
+        readwise,
+        "highlightId",
+        (c) => ({
+          bookId: c.bookId,
+        }),
+      ],
+    },
+  },
+  async run({ $ }) {
+    const highlight = await this.readwise.getHighlight({
+      $,
+      highlightId: this.highlightId,
+    });
+
+    $.export("$summary", `Successfully returned highlight (${this.highlightId})`);
+    return highlight;
+  },
+};

package/actions/list-highlights/list-highlights.mjs

@@ -0,0 +1,55 @@
+import readwise from "../../readwise.app.mjs";
+
+export default {
+  key: "readwise-list-highlights",
+  name: "List Highlights",
+  description: "A list of highlights with a pagination metadata. The rate limit of this endpoint is restricted to 20 requests per minute. Each request returns 1000 items. [See the docs here](https://readwise.io/api_deets)",
+  version: "0.0.4",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    readwise,
+    bookId: {
+      propDefinition: [
+        readwise,
+        "bookId",
+      ],
+      optional: true,
+    },
+    limit: {
+      propDefinition: [
+        readwise,
+        "limit",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const params = {
+      page_size: 1000,
+      limit: this.limit,
+    };
+    if (this.bookId) params.book_id = this.bookId;
+
+    const items = [];
+
+    const paginator = this.readwise.paginate({
+      $,
+      fn: this.readwise.listHighlights,
+      params,
+    });
+    for await (const item of paginator) {
+      items.push(item);
+    }
+
+    const suffix = items.length === 1
+      ? ""
+      : "s";
+
+    $.export("$summary", `Successfully returned ${items.length} highlight${suffix}`);
+    return items;
+  },
+};

package/common/utils.mjs

@@ -0,0 +1,20 @@
+/* eslint-disable no-unused-vars */
+export const clearObj = (obj) => {
+  return Object.entries(obj)
+    .filter(([
+      _,
+      v,
+    ]) => v != null)
+    .reduce(
+      (acc, [
+        k,
+        v,
+      ]) => ({
+        ...acc,
+        [k]: v === Object(v)
+          ? clearObj(v)
+          : v,
+      }),
+      {},
+    );
+};

package/package.json

@@ -1,21 +1,18 @@
 {
   "name": "@pipedream/readwise",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pipedream Readwise Components",
-  "main": "dist/app/readwise.app.mjs",
+  "main": "readwise.app.mjs",
   "keywords": [
     "pipedream",
     "readwise"
   ],
-  "files": [
-    "dist"
-  ],
   "homepage": "https://pipedream.com/apps/readwise",
   "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@pipedream/platform": "^1.2.0"
+    "@pipedream/platform": "^1.6.8"
   }
 }

package/readwise.app.mjs

@@ -0,0 +1,147 @@
+import { axios } from "@pipedream/platform";
+import { clearObj } from "./common/utils.mjs";
+
+export default {
+  type: "app",
+  app: "readwise",
+  propDefinitions: {
+    bookId: {
+      type: "integer",
+      label: "Book Id",
+      description: "Id of the book to list highlights",
+      async options({ page }) {
+        const { results } = await this.listBooks({
+          params: {
+            page: page + 1,
+          },
+        });
+
+        return results.map(({
+          title, id,
+        }) => ({
+          label: title,
+          value: id,
+        })) || [];
+      },
+    },
+    limit: {
+      type: "integer",
+      label: "Limit",
+      description: "Specify number of results per page (default is 100, max is 1000)",
+      default: 100,
+    },
+    highlightId: {
+      type: "integer",
+      label: "Highlight Id",
+      description: "Id of the highlight to list details",
+      async options({
+        page, bookId: book_id,
+      }) {
+        const { results } = await this.listHighlights({
+          params: {
+            book_id,
+            page: page + 1,
+          },
+        });
+
+        return results.map(({
+          text, id,
+        }) => ({
+          label: `(${id}) ${text}`,
+          value: id,
+        })) || [];
+      },
+    },
+  },
+  methods: {
+    _getBaseUrl() {
+      return "https://readwise.io/api";
+    },
+    _getHeaders() {
+      return {
+        "Authorization": `Token ${this.$auth.access_token}`,
+      };
+    },
+    async _makeRequest({
+      $, path, ...otherConfig
+    }) {
+      const config = {
+        url: `${this._getBaseUrl()}/${path}`,
+        headers: this._getHeaders(),
+        ...otherConfig,
+      };
+
+      return axios($ || this, clearObj(config));
+    },
+    async listBooks({
+      $, params,
+    }) {
+      return this._makeRequest({
+        $,
+        path: "v2/books",
+        params,
+      });
+    },
+    async listHighlights({
+      $, params,
+    }) {
+      return this._makeRequest({
+        $,
+        path: "v2/highlights",
+        params,
+      });
+    },
+    async listDocuments({
+      $, params,
+    }) {
+      return this._makeRequest({
+        $,
+        path: "v3/list",
+        params,
+      });
+    },
+    async getHighlight({
+      $, highlightId,
+    }) {
+      return this._makeRequest({
+        $,
+        path: `v2/highlights/${highlightId}`,
+      });
+    },
+    async *paginate({
+      $, fn, params = {}, page,
+    }) {
+      const { limit } = params;
+      let count = 0;
+
+      do {
+        const {
+          results,
+          next,
+        } = await fn({
+          $,
+          params: {
+            ...params,
+            page,
+          },
+        });
+
+        for (const d of results) {
+          yield d;
+
+          if (limit && ++count === limit) {
+            return count;
+          }
+        }
+        page = null;
+
+        if (next) {
+          const regex = next.match(/page=([^&]+)/g);
+          const pageNumber = regex[0].split("=");
+          page = pageNumber[1];
+        }
+
+      } while (page);
+    },
+  },
+};

package/sources/new-documents/new-documents.mjs

@@ -0,0 +1,83 @@
+import readwise from "../../readwise.app.mjs";
+import { DEFAULT_POLLING_SOURCE_TIMER_INTERVAL } from "@pipedream/platform";
+
+export default {
+  key: "readwise-new-documents",
+  name: "New Documents",
+  description: "Emit new document [See the documentation](https://readwise.io/reader_api)",
+  version: "0.0.2",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    readwise,
+    timer: {
+      label: "Polling interval",
+      description: "Pipedream polls the Readwise API on this schedule",
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+      },
+    },
+    location: {
+      type: "string",
+      label: "Location",
+      description: "(Optional) The document's location. [See the documentation](https://readwise.io/reader_api).",
+      options: [
+        "new",
+        "later",
+        "shortlist",
+        "archive",
+        "feed",
+      ],
+      optional: true,
+    },
+    category: {
+      type: "string",
+      label: "Category",
+      description: "(Optional) The document's category. [See the documentation](https://readwise.io/reader_api).",
+      options: [
+        "article",
+        "email",
+        "rss",
+        "highlight",
+        "note",
+        "pdf",
+        "epub",
+        "tweet",
+        "video",
+      ],
+      optional: true,
+    },
+  },
+  hooks: {
+    async activate() {
+      await this.processEvent();
+    },
+  },
+  methods: {
+    async processDocuments(params) {
+      const { results: events } = await this.readwise.listDocuments({
+        params,
+      });
+      for (const event of events.slice(0, 100)) {
+        this.emitEvent(event);
+      }
+    },
+    async processEvent() {
+      await this.processDocuments({
+        location: this.location || "",
+        category: this.category || "",
+      });
+    },
+    emitEvent(event) {
+      this.$emit(event, {
+        id: event.id,
+        summary: `New Document: ${event.id}`,
+        ts: new Date(event.created_at),
+      });
+    },
+  },
+  async run() {
+    return this.processEvent();
+  },
+};

package/sources/new-highlights/new-highlights.mjs

@@ -0,0 +1,85 @@
+import readwise from "../../readwise.app.mjs";
+import { DEFAULT_POLLING_SOURCE_TIMER_INTERVAL } from "@pipedream/platform";
+
+export default {
+  key: "readwise-new-highlights",
+  name: "New Highlights",
+  description: "Emit new Highlight",
+  version: "0.0.5",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    readwise,
+    db: "$.service.db",
+    timer: {
+      label: "Polling interval",
+      description: "Pipedream will poll the Readwise API on this schedule",
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+      },
+    },
+    bookId: {
+      propDefinition: [
+        readwise,
+        "bookId",
+      ],
+      optional: true,
+    },
+  },
+  hooks: {
+    async activate() {
+      await this.processHighlighs({
+        book_id: this.bookId,
+        page_size: 25,
+      });
+    },
+  },
+  methods: {
+    _getLastHighlightedAt() {
+      return this.db.get("lastHighlightedAt");
+    },
+    _setLastHighlightedAt(lastHighlightedAt) {
+      this.db.set("lastHighlightedAt", lastHighlightedAt);
+    },
+    async retrieveTicket(id) {
+      return this.readwise.retrieveTicket({
+        id,
+      });
+    },
+    async processHighlighs(params) {
+      const { results: events } = await this.readwise.listHighlights({
+        params,
+      });
+      for (const event of events) {
+        this.emitEvent(await this.readwise.getHighlight({
+          highlightId: event.id,
+        }));
+      }
+    },
+    async processEvent() {
+      const lastHighlightedAt = this._getLastHighlightedAt();
+      await this.processHighlighs({
+        book_id: this.bookId,
+        highlighted_at__gt: lastHighlightedAt,
+      });
+    },
+    emitEvent(event, lastHighlightedAt = null) {
+      lastHighlightedAt = lastHighlightedAt || this._getLastHighlightedAt();
+
+      if (!lastHighlightedAt || (new Date(event.highlighted_at) > new Date(lastHighlightedAt)))
+        this._setLastHighlightedAt(event.highlighted_at);
+
+      const ts = Date.parse(event.highlighted_at);
+      this.$emit(event, {
+        id: `${event.id}_${ts}`,
+        ts,
+        summary: `New highlight: ${event.id}`,
+      });
+    },
+  },
+  async run() {
+    console.log("Raw received event:");
+    return this.processEvent();
+  },
+};