instapaper-ts 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+type User = {
+    type: "user";
+    user_id: number;
+    username: string;
+};
+type Bookmark = {
+    type: "bookmark";
+    hash: string;
+    description: string;
+    tags: Array<Tag>;
+    bookmark_id: number;
+    private_source: string;
+    title: string;
+    url: string;
+    progress_timestamp: number;
+    time: number;
+    progress: number;
+    starred: "0" | "1";
+};
+type Folder = {
+    type: "folder";
+    position: number;
+    folder_id: number;
+    title: string;
+    display_title: string;
+    slug: string;
+    sync_to_mobile: 0 | 1;
+    public: false | 1;
+};
+type Tag = {
+    id: number;
+    name: string;
+};
+type Highlight = {
+    type: "highlight";
+    highlight_id: number;
+    text: string;
+    note: string | null;
+    bookmark_id: Bookmark["bookmark_id"];
+    time: number;
+    position: number;
+};
+type Error = {
+    type: "error";
+    error_code: number;
+    message: string;
+};
+type Meta = {
+    type: "meta";
+};
+type ListParams = Partial<{
+    limit: number;
+    folder_id: "unread" | "starred" | "archive" | (string & {});
+    have: string;
+    highlights: string;
+}>;
+type UpdateReadProgressParams = {
+    bookmark_id: string;
+    progress: number;
+    progress_timestamp: number;
+};
+type AddBookmarkParams = {
+    url: string;
+    title?: string;
+    description?: string;
+    folder_id?: number;
+    resolve_final_url?: 0 | 1;
+    archived?: 0 | 1;
+    tags?: Array<{
+        name: string;
+    }>;
+    is_private_from_source?: string;
+    content?: string;
+};
+type AddHighlightParams = {
+    bookmark_id: string;
+    text: string;
+    position?: number;
+};
+
+declare class Instapaper {
+    private baseUrl;
+    private authUrl;
+    private oauth;
+    private username?;
+    private password?;
+    private token?;
+    constructor(consumerKey: string, consumerSecret: string);
+    setCredentials: (username: string, password: string) => void;
+    private makeRequest;
+    private getAccessToken;
+    private request;
+    bookmarks: {
+        list: (params?: ListParams) => Promise<(Bookmark | Folder | User | Error | Meta)[]>;
+        updateReadProgress: (params: UpdateReadProgressParams) => Promise<[Bookmark]>;
+        add: (params: AddBookmarkParams) => Promise<[Bookmark]>;
+        delete: (bookmark_id: Bookmark["bookmark_id"]) => Promise<never[]>;
+        star: (bookmark_id: Bookmark["bookmark_id"]) => Promise<[Bookmark]>;
+        unstar: (bookmark_id: Bookmark["bookmark_id"]) => Promise<[Bookmark]>;
+        archive: (bookmark_id: Bookmark["bookmark_id"]) => Promise<[Bookmark]>;
+        unarchive: (bookmark_id: Bookmark["bookmark_id"]) => Promise<[Bookmark]>;
+        move: (bookmark_id: Bookmark["bookmark_id"], folder_id: Folder["folder_id"]) => Promise<[Bookmark]>;
+        getText: (bookmark_id: Bookmark["bookmark_id"]) => Promise<string>;
+    };
+    folders: {
+        list: () => Promise<Folder[]>;
+        add: (title: string) => Promise<[Folder]>;
+        delete: (folder_id: Folder["folder_id"]) => Promise<never[]>;
+        setOrder: (order: string) => Promise<Folder[]>;
+    };
+    highlights: {
+        list: (bookmark_id: Bookmark["bookmark_id"]) => Promise<Highlight[]>;
+        add: (params: AddHighlightParams) => Promise<Highlight>;
+        delete: (highlight_id: string) => Promise<never[]>;
+    };
+}
+
+export { Instapaper };

package/dist/index.js

@@ -0,0 +1,132 @@
+// src/index.ts
+import assert from "node:assert";
+import crypto from "node:crypto";
+import OAuth from "oauth-1.0a";
+var Instapaper = class {
+  baseUrl = "https://www.instapaper.com/api";
+  authUrl = this.baseUrl + "/1/oauth/access_token";
+  oauth;
+  username;
+  password;
+  token;
+  constructor(consumerKey, consumerSecret) {
+    this.oauth = new OAuth({
+      consumer: {
+        key: consumerKey,
+        secret: consumerSecret
+      },
+      signature_method: "HMAC-SHA1",
+      hash_function: (base_string, key) => crypto.createHmac("sha1", key).update(base_string).digest("base64")
+    });
+  }
+  setCredentials = (username, password) => {
+    this.username = username;
+    this.password = password;
+  };
+  makeRequest = async (url, method = "POST", params = {}, token) => {
+    const form = new URLSearchParams();
+    for (const [key, val] of Object.entries(params)) {
+      form.append(key, String(val));
+    }
+    const headers = this.oauth.toHeader(
+      this.oauth.authorize(
+        {
+          url,
+          method,
+          data: params
+        },
+        token
+      )
+    );
+    const response = await fetch(url, {
+      method,
+      headers: new Headers({ ...headers }),
+      body: form
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API error: ${response.status} ${errorText}`);
+    }
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      return response.json();
+    } else {
+      return response.text();
+    }
+  };
+  getAccessToken = async () => {
+    assert(
+      this.username && this.password,
+      "Please set username and password with setCredentials()."
+    );
+    const params = {
+      x_auth_username: this.username,
+      x_auth_password: this.password,
+      x_auth_mode: "client_auth"
+    };
+    const responseText = await this.makeRequest(
+      this.authUrl,
+      "POST",
+      params
+    );
+    const data = new URLSearchParams(responseText);
+    const key = data.get("oauth_token");
+    const secret = data.get("oauth_token_secret");
+    assert(
+      key && secret,
+      "There was an error fetching the token. One or both of key and secret is null."
+    );
+    this.token = { key, secret };
+    return this.token;
+  };
+  request = async (endpoint, params = {}) => {
+    if (!this.token) {
+      this.token = await this.getAccessToken();
+    }
+    const url = this.baseUrl + endpoint;
+    return this.makeRequest(url, "POST", params, this.token);
+  };
+  bookmarks = {
+    list: (params = {}) => this.request(
+      "/1/bookmarks/list",
+      params
+    ),
+    updateReadProgress: (params) => this.request(
+      "/1/bookmarks/update_read_progress",
+      params
+    ),
+    add: (params) => this.request("/1/bookmarks/add", params),
+    delete: (bookmark_id) => this.request("/1/bookmarks/delete", { bookmark_id }),
+    star: (bookmark_id) => this.request("/1/bookmarks/star", { bookmark_id }),
+    unstar: (bookmark_id) => this.request("/1/bookmarks/unstar", { bookmark_id }),
+    archive: (bookmark_id) => this.request("/1/bookmarks/archive", { bookmark_id }),
+    unarchive: (bookmark_id) => this.request("/1/bookmarks/unarchive", { bookmark_id }),
+    move: (bookmark_id, folder_id) => this.request("/1/bookmarks/move", {
+      bookmark_id,
+      folder_id
+    }),
+    getText: (bookmark_id) => this.request("/1/bookmarks/get_text", { bookmark_id })
+  };
+  folders = {
+    list: () => this.request("/1/folders/list"),
+    add: (title) => this.request("/1/folders/add", { title }),
+    delete: (folder_id) => this.request("/1/folders/delete", { folder_id }),
+    setOrder: (order) => this.request("/1/folders/set_order", { order })
+  };
+  highlights = {
+    list: (bookmark_id) => this.request(
+      `/1.1/bookmarks/${bookmark_id}/highlights`
+    ),
+    add: (params) => this.request(
+      `/1.1/bookmarks/${params.bookmark_id}/highlight`,
+      {
+        text: params.text,
+        position: params.position
+      }
+    ),
+    delete: (highlight_id) => this.request(`/1.1/highlights/${highlight_id}/delete`)
+  };
+};
+export {
+  Instapaper
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "instapaper-ts",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "A type-safe API client for Instapaper.",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"/dist"
+	],
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch"
+	},
+	"keywords": [
+		"instapaper",
+		"read",
+		"later",
+		"typescript",
+		"library"
+	],
+	"author": "Ben Silverman (bensilverman.co.uk)",
+	"homepage": "https://github.com/benslv/instapaper-ts",
+	"bugs": {
+		"url": "https://github.com/benslv/instapaper-ts/issues"
+	},
+	"license": "MIT",
+	"packageManager": "pnpm@10.4.1",
+	"dependencies": {
+		"oauth-1.0a": "^2.2.6"
+	},
+	"devDependencies": {
+		"@types/node": "^22.13.5",
+		"tsup": "^8.4.0",
+		"typescript": "^5.8.2"
+	}
+}