instapaper-api 0.1.0

package/dist/index.js

@@ -0,0 +1,664 @@
+// src/errors.ts
+var InstapaperError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "InstapaperError";
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (options && "cause" in options && this.cause === void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var APIError = class extends InstapaperError {
+  /** HTTP status code. */
+  status;
+  /** The parsed JSON body, the raw text if it wasn't JSON, or `undefined` if empty. */
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "APIError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var BadRequestError = class extends APIError {
+  constructor(message, status = 400, body) {
+    super(message, status, body);
+    this.name = "BadRequestError";
+  }
+};
+var AuthenticationError = class extends APIError {
+  constructor(message, status = 401, body) {
+    super(message, status, body);
+    this.name = "AuthenticationError";
+  }
+};
+var QuotaExceededError = class extends APIError {
+  constructor(message, status = 402, body) {
+    super(message, status, body);
+    this.name = "QuotaExceededError";
+  }
+};
+var PermissionDeniedError = class extends APIError {
+  constructor(message, status = 403, body) {
+    super(message, status, body);
+    this.name = "PermissionDeniedError";
+  }
+};
+var NotFoundError = class extends APIError {
+  constructor(message, status = 404, body) {
+    super(message, status, body);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends APIError {
+  constructor(message, status = 429, body) {
+    super(message, status, body);
+    this.name = "RateLimitError";
+  }
+};
+var ServerError = class extends APIError {
+  constructor(message, status = 500, body) {
+    super(message, status, body);
+    this.name = "ServerError";
+  }
+};
+var OAuthError = class extends InstapaperError {
+  status;
+  /** The OAuth error code, e.g. `invalid_grant`. */
+  error;
+  description;
+  constructor(status, error, description) {
+    super(`${error}: ${description}`);
+    this.name = "OAuthError";
+    this.status = status;
+    this.error = error;
+    this.description = description;
+  }
+};
+var InstapaperConnectionError = class extends InstapaperError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "InstapaperConnectionError";
+  }
+};
+var DEFAULT_MESSAGES = {
+  400: "Bad request",
+  401: "Authentication failed",
+  402: "Quota exceeded",
+  403: "Permission denied",
+  404: "Not found",
+  429: "Rate limit exceeded"
+};
+function apiErrorFor(status, body) {
+  const message = errorMessage(body) ?? defaultMessage(status);
+  switch (status) {
+    case 400:
+      return new BadRequestError(message, status, body);
+    case 401:
+      return new AuthenticationError(message, status, body);
+    case 402:
+      return new QuotaExceededError(message, status, body);
+    case 403:
+      return new PermissionDeniedError(message, status, body);
+    case 404:
+      return new NotFoundError(message, status, body);
+    case 429:
+      return new RateLimitError(message, status, body);
+    default:
+      if (status >= 500) return new ServerError(message, status, body);
+      return new APIError(message, status, body);
+  }
+}
+function defaultMessage(status) {
+  if (DEFAULT_MESSAGES[status]) return DEFAULT_MESSAGES[status];
+  if (status >= 500) return "Server error";
+  return `Request failed with status ${status}`;
+}
+function errorMessage(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const error = body.error;
+  if (error && typeof error === "object") {
+    const message = error.message;
+    if (typeof message === "string" && message) return message;
+  }
+  return void 0;
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://www.instapaper.com";
+var DEFAULT_TIMEOUT = 3e4;
+var Transport = class {
+  baseUrl;
+  timeout;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const globalFetch = globalThis.fetch;
+    const fetchImpl = options.fetch ?? (globalFetch ? globalFetch.bind(globalThis) : void 0);
+    if (!fetchImpl) {
+      throw new InstapaperError(
+        "No fetch implementation is available. Use Node 18 or newer, or pass options.fetch."
+      );
+    }
+    this.fetchImpl = fetchImpl;
+  }
+  url(path, query) {
+    let url = `${this.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0 || value === null) continue;
+        params.append(key, String(value));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    return url;
+  }
+  async send(method, path, options = {}) {
+    const headers = { Accept: "application/json", ...options.headers };
+    if (canSetUserAgent()) headers["User-Agent"] = `instapaper-api-js/${VERSION}`;
+    const controller = this.timeout > 0 ? new AbortController() : void 0;
+    let timedOut = false;
+    const timer = controller ? setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.timeout) : void 0;
+    try {
+      const init = { method, headers, redirect: "manual" };
+      if (options.body !== void 0) init.body = options.body;
+      if (controller) init.signal = controller.signal;
+      const response = await this.fetchImpl(this.url(path, options.query), init);
+      const text = await response.text();
+      return { status: response.status, ok: response.ok, text };
+    } catch (err) {
+      if (timedOut) {
+        throw new InstapaperConnectionError(`Request timed out after ${this.timeout}ms`, {
+          cause: err
+        });
+      }
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new InstapaperConnectionError(`Network error: ${detail}`, { cause: err });
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
+};
+function parseBody(text) {
+  if (!text.trim()) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+var ApiClient = class {
+  constructor(transport, accessToken) {
+    this.transport = transport;
+    this.accessToken = accessToken;
+  }
+  transport;
+  accessToken;
+  async request(method, path, options = {}) {
+    const headers = { Authorization: `Bearer ${this.accessToken}` };
+    let body;
+    if (options.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(options.json);
+    }
+    const response = await this.transport.send(method, `/api/2${path}`, {
+      query: options.query,
+      headers,
+      body
+    });
+    const parsed = parseBody(response.text);
+    if (isRedirect(response.status)) {
+      throw new APIError(
+        `Unexpected redirect (status ${response.status}); the request was not followed`,
+        response.status,
+        parsed
+      );
+    }
+    if (!response.ok) throw apiErrorFor(response.status, parsed);
+    if (options.expectJson === false) return void 0;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new APIError("Expected a JSON object in the response", response.status, parsed);
+    }
+    return parsed;
+  }
+};
+function isRedirect(status) {
+  return status === 0 || status >= 300 && status < 400;
+}
+function canSetUserAgent() {
+  return typeof globalThis.document === "undefined";
+}
+
+// src/resources/bookmarks.ts
+var MAX_PAGE_SIZE = 500;
+var SECTIONS = ["home", "archive", "liked", "folder", "tag"];
+var Bookmarks = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  /** One page of bookmarks from a section. */
+  async list(options = {}) {
+    checkSection(options);
+    if (options.limit !== void 0) checkPageSize(options.limit, "limit");
+    return this.api.request("GET", "/bookmarks", {
+      query: {
+        section: options.section,
+        folder_id: options.folderId,
+        tag: options.tag,
+        limit: options.limit,
+        offset: options.offset
+      }
+    });
+  }
+  /** Every bookmark in a section, fetching pages as you go. */
+  async *iterate(options = {}) {
+    const pageSize = options.pageSize ?? 100;
+    checkPageSize(pageSize, "pageSize");
+    checkSection(options);
+    let offset = 0;
+    for (; ; ) {
+      const page = await this.list({
+        section: options.section,
+        folderId: options.folderId,
+        tag: options.tag,
+        limit: pageSize,
+        offset
+      });
+      yield* page.bookmarks;
+      offset += page.bookmarks.length;
+      if (page.bookmarks.length < pageSize) return;
+    }
+  }
+  /** One page of bookmarks changed since a time, across every section, plus deleted IDs. */
+  async changes(since, options = {}) {
+    const limit = options.limit ?? MAX_PAGE_SIZE;
+    checkPageSize(limit, "limit");
+    const response = await this.api.request("GET", "/bookmarks", {
+      query: { since: toTimestamp(since), limit, offset: options.offset }
+    });
+    return {
+      bookmarks: response.bookmarks,
+      deleted_ids: response.deleted_ids ?? [],
+      total: response.total
+    };
+  }
+  /**
+   * Everything changed since a time, fetching every page. Record when you
+   * started the sync and pass it as `since` next time.
+   */
+  async sync(since, options = {}) {
+    const pageSize = options.pageSize ?? MAX_PAGE_SIZE;
+    checkPageSize(pageSize, "pageSize");
+    const result = { bookmarks: [], deleted_ids: [], total: 0 };
+    let offset = 0;
+    for (; ; ) {
+      const page = await this.changes(since, { limit: pageSize, offset });
+      result.bookmarks.push(...page.bookmarks);
+      result.deleted_ids.push(...page.deleted_ids);
+      result.total = page.total;
+      const received = page.bookmarks.length + page.deleted_ids.length;
+      offset += received;
+      if (received < pageSize) return result;
+    }
+  }
+  /** Save a URL, or private content. Saving a URL twice updates the existing bookmark. */
+  async save(options) {
+    if (options.url === void 0 && options.privateSource === void 0) {
+      throw new TypeError("url is required unless privateSource is set");
+    }
+    if (options.url !== void 0 && options.privateSource !== void 0) {
+      throw new TypeError("url and privateSource cannot be used together");
+    }
+    if (options.privateSource !== void 0 && options.content === void 0) {
+      throw new TypeError("privateSource requires content");
+    }
+    return this.api.request("POST", "/bookmarks", {
+      json: compact({
+        url: options.url,
+        title: options.title,
+        description: options.description,
+        folder_id: options.folderId,
+        archived: options.archived,
+        canonicalize: options.canonicalize,
+        tags: options.tags?.map((name) => ({ name })),
+        content: options.content,
+        private_source: options.privateSource
+      })
+    });
+  }
+  /** Change a bookmark's title, description, or reading progress. */
+  async update(bookmarkId, options) {
+    if (options.title === void 0 && options.description === void 0 && options.progress === void 0 && options.progressTimestamp === void 0) {
+      throw new TypeError("update needs a title, description, or progress");
+    }
+    if (options.progress === void 0 && options.progressTimestamp !== void 0) {
+      throw new TypeError("progressTimestamp requires progress");
+    }
+    let progress;
+    if (options.progress !== void 0) {
+      if (!(options.progress >= 0 && options.progress <= 1)) {
+        throw new RangeError("progress must be between 0 and 1");
+      }
+      progress = {
+        percentage: options.progress,
+        timestamp: options.progressTimestamp ?? Math.floor(Date.now() / 1e3)
+      };
+    }
+    return this.api.request("POST", `/bookmarks/${id(bookmarkId)}`, {
+      json: compact({ title: options.title, description: options.description, progress })
+    });
+  }
+  /** Permanently delete a bookmark. This is not the same as archiving. */
+  async delete(bookmarkId) {
+    await this.api.request("DELETE", `/bookmarks/${id(bookmarkId)}`, { expectJson: false });
+  }
+  archive(bookmarkId) {
+    return this.move(bookmarkId, "archive");
+  }
+  /** Move a bookmark back to the home list. */
+  unarchive(bookmarkId) {
+    return this.move(bookmarkId, "home");
+  }
+  moveToFolder(bookmarkId, folderId) {
+    return this.move(bookmarkId, String(id(folderId)));
+  }
+  like(bookmarkId) {
+    return this.api.request("POST", `/bookmarks/${id(bookmarkId)}/like`);
+  }
+  unlike(bookmarkId) {
+    return this.api.request("DELETE", `/bookmarks/${id(bookmarkId)}/like`);
+  }
+  /** Add tags (by name or ID) to a bookmark and remove tags (by ID) from it. */
+  async updateTags(bookmarkId, options) {
+    const add = options.add ?? [];
+    const remove = options.remove ?? [];
+    if (add.length === 0 && remove.length === 0) {
+      throw new TypeError("updateTags needs at least one tag to add or remove");
+    }
+    for (const tag of add) {
+      const validName = typeof tag === "string" && tag.trim() !== "";
+      if (!validName && !isPositiveInteger(tag)) {
+        throw new TypeError("Tags to add must be non-empty names or positive integer IDs");
+      }
+    }
+    if (!remove.every(isPositiveInteger)) {
+      throw new TypeError("Tags to remove must be positive integer IDs");
+    }
+    return this.api.request("POST", `/bookmarks/${id(bookmarkId)}/tags`, {
+      json: {
+        add_tags: add.map((tag) => typeof tag === "number" ? { id: tag } : { name: tag }),
+        remove_tags: remove.map((tagId) => ({ id: tagId }))
+      }
+    });
+  }
+  /** Instapaper's parsed, reader-ready version of a saved article. */
+  async parse(bookmarkId, options = {}) {
+    const path = `/bookmarks/${id(bookmarkId)}/parse`;
+    const useCache = options.useCache ?? true;
+    const force = options.force ?? false;
+    if (options.content !== void 0) {
+      return this.api.request("POST", path, {
+        json: compact({
+          use_cache: useCache,
+          force,
+          content: options.content,
+          instaparser_api_key: options.instaparserApiKey
+        })
+      });
+    }
+    return this.api.request("GET", path, {
+      query: {
+        use_cache: useCache ? void 0 : "0",
+        force: force ? "1" : void 0,
+        instaparser_api_key: options.instaparserApiKey
+      }
+    });
+  }
+  move(bookmarkId, section) {
+    return this.api.request("POST", `/bookmarks/${id(bookmarkId)}/move`, {
+      json: { section }
+    });
+  }
+};
+function checkSection(options) {
+  const { section, folderId, tag } = options;
+  if (folderId !== void 0 && tag !== void 0) {
+    throw new TypeError("folderId and tag cannot be used together");
+  }
+  if (section === void 0) return;
+  if (!SECTIONS.includes(section)) {
+    throw new TypeError(`section must be one of: ${SECTIONS.join(", ")}`);
+  }
+  if (folderId !== void 0 && section !== "folder") {
+    throw new TypeError(`folderId can't be used with section "${section}"`);
+  }
+  if (tag !== void 0 && section !== "tag") {
+    throw new TypeError(`tag can't be used with section "${section}"`);
+  }
+}
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function checkPageSize(value, name) {
+  if (!Number.isInteger(value) || value < 1 || value > MAX_PAGE_SIZE) {
+    throw new RangeError(`${name} must be an integer from 1 to ${MAX_PAGE_SIZE}`);
+  }
+}
+function toTimestamp(since) {
+  const value = since instanceof Date ? Math.floor(since.getTime() / 1e3) : since;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError("since must be a positive Unix timestamp or a Date");
+  }
+  return value;
+}
+function id(value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError(`Expected a positive integer ID, got ${String(value)}`);
+  }
+  return value;
+}
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0));
+}
+
+// src/resources/folders.ts
+var Folders = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  /** The user's folders, in their own order. */
+  async list() {
+    const response = await this.api.request("GET", "/folders");
+    return response.folders;
+  }
+  create(title) {
+    return this.api.request("POST", "/folders", { json: { title } });
+  }
+  /** Delete a folder. Its bookmarks move back to the home list. */
+  async delete(folderId) {
+    await this.api.request("DELETE", `/folders/${id(folderId)}`, { expectJson: false });
+  }
+  /**
+   * Set folder positions, as a `{ folderId: position }` map or a list. Folders
+   * you leave out keep their positions. Returns every folder in its new order.
+   */
+  async reorder(positions) {
+    const entries = Array.isArray(positions) ? positions : Object.entries(positions).map(([folderId, position]) => ({
+      folderId: Number(folderId),
+      position
+    }));
+    if (entries.length === 0) throw new TypeError("reorder needs at least one folder");
+    const order = entries.map(({ folderId, position }) => {
+      if (!Number.isInteger(position) || position < 1) {
+        throw new RangeError("Folder positions must be positive integers");
+      }
+      return { folder_id: id(folderId), position };
+    });
+    const response = await this.api.request("POST", "/folders/reorder", {
+      json: { order }
+    });
+    return response.folders;
+  }
+};
+
+// src/resources/highlights.ts
+var Highlights = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  async list(bookmarkId) {
+    const response = await this.api.request(
+      "GET",
+      `/bookmarks/${id(bookmarkId)}/highlights`
+    );
+    return response.highlights;
+  }
+  /**
+   * Create a highlight. Accounts without Premium can create five per month;
+   * past that this throws a `PermissionDeniedError`.
+   */
+  async create(bookmarkId, options) {
+    if (typeof options?.text !== "string" || options.text.trim() === "") {
+      throw new TypeError("Highlight text cannot be blank");
+    }
+    return this.api.request("POST", `/bookmarks/${id(bookmarkId)}/highlights`, {
+      json: compact({ text: options.text, note: options.note, position: options.position })
+    });
+  }
+  /**
+   * Delete a highlight. Throws `BadRequestError` if the highlight doesn't
+   * exist, belongs to someone else, or was already deleted.
+   */
+  async delete(highlightId) {
+    await this.api.request("DELETE", `/highlights/${id(highlightId)}`, {
+      expectJson: false
+    });
+  }
+};
+
+// src/resources/tags.ts
+var Tags = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  async list() {
+    const response = await this.api.request("GET", "/tags");
+    return response.tags;
+  }
+  create(name) {
+    return this.api.request("POST", "/tags", { json: { name } });
+  }
+  rename(tagId, name) {
+    return this.api.request("POST", `/tags/${id(tagId)}`, { json: { name } });
+  }
+};
+
+// src/client.ts
+var Instapaper = class {
+  bookmarks;
+  folders;
+  tags;
+  highlights;
+  api;
+  constructor(options) {
+    if (!options || typeof options.accessToken !== "string" || !options.accessToken) {
+      throw new TypeError("accessToken is required");
+    }
+    this.api = new ApiClient(new Transport(options), options.accessToken);
+    this.bookmarks = new Bookmarks(this.api);
+    this.folders = new Folders(this.api);
+    this.tags = new Tags(this.api);
+    this.highlights = new Highlights(this.api);
+  }
+  /** The account the access token belongs to. */
+  me() {
+    return this.api.request("GET", "/me");
+  }
+};
+
+// src/oauth.ts
+var OAuth = class {
+  clientId;
+  redirectUri;
+  clientSecret;
+  transport;
+  constructor(options) {
+    for (const key of ["clientId", "clientSecret", "redirectUri"]) {
+      if (!options || typeof options[key] !== "string" || !options[key]) {
+        throw new TypeError(`${key} is required`);
+      }
+    }
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
+    this.redirectUri = options.redirectUri;
+    this.transport = new Transport(options);
+  }
+  /** The URL to send the user to so they can authorize your application. */
+  authorizationUrl(options = {}) {
+    return this.transport.url("/oauth2/authorize", {
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      response_type: "code",
+      state: options.state
+    });
+  }
+  /** Exchange the code from your redirect URI for an access token. Codes work once. */
+  async exchangeCode(code) {
+    if (typeof code !== "string" || !code) throw new TypeError("code is required");
+    const response = await this.transport.send("POST", "/oauth2/token", {
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        client_id: this.clientId,
+        client_secret: this.clientSecret,
+        redirect_uri: this.redirectUri,
+        code
+      }).toString()
+    });
+    const body = parseBody(response.text);
+    if (isRedirect(response.status)) {
+      throw new OAuthError(
+        response.status,
+        "unexpected_redirect",
+        `The token endpoint redirected (status ${response.status}); the request was not followed`
+      );
+    }
+    if (!response.ok) {
+      const fields = body && typeof body === "object" ? body : {};
+      const error = typeof fields.error === "string" ? fields.error : "unknown_error";
+      const description = typeof fields.error_description === "string" ? fields.error_description : `Token request failed with status ${response.status}`;
+      throw new OAuthError(response.status, error, description);
+    }
+    const token = body;
+    if (!token || typeof token !== "object" || typeof token.access_token !== "string") {
+      throw new InstapaperError("The token response did not include an access_token");
+    }
+    return token;
+  }
+};
+
+// src/types.ts
+var BookmarkCategory = {
+  Article: 0,
+  Email: 1,
+  Video: 2,
+  PDF: 3,
+  Social: 4
+};
+
+export { APIError, AuthenticationError, BadRequestError, BookmarkCategory, Instapaper, InstapaperConnectionError, InstapaperError, NotFoundError, OAuth, OAuthError, PermissionDeniedError, QuotaExceededError, RateLimitError, ServerError, VERSION };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map