@dukebot/instagram-scraper-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dukebot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# instagram-scraper-api
+
+Reusable wrapper for extracting Instagram profile and post data using modern `import/export` syntax and the `instagram-scraper-api2` provider from RapidAPI.
+
+## Installation
+
+```bash
+npm install @dukebot/instagram-scraper-api
+```
+
+## Usage
+
+```js
+ import { InstagramScraperAPI } from "@dukebot/instagram-scraper-api";
+
+const scraper = new InstagramScraperAPI({
+  apiHost: "instagram-scraper-api2.p.rapidapi.com",
+  apiKey: process.env.RAPIDAPI_KEY,
+});
+
+const user = await scraper.getUserInfo("instagram");
+const posts = await scraper.getUserPosts("instagram", 5);
+
+console.log(user.username);
+console.log(posts.length);
+```
+
+## API
+
+### `new InstagramScraperAPI({ apiHost, apiKey, logInfoFn })`
+
+- `apiHost`: provider host in RapidAPI.
+- `apiKey`: RapidAPI API key.
+- `logInfoFn`: optional function for logging traces.
+
+### `getUserInfo(usernameOrId)`
+
+Returns a `User` instance.
+
+### `getUserPosts(usernameOrId, numPosts)`
+
+Returns an array of `Post`. If `numPosts` is provided, the result is limited to that number.
+
+## Publish To npm
+
+1. Run `npm login`.
+2. Run `npm publish --access public`.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dukebot/instagram-scraper-api",
+  "version": "0.1.0",
+  "description": "Reusable Instagram data scraper wrapper for RapidAPI with modern ESM imports.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "instagram",
+    "scraper",
+    "rapidapi",
+    "esm",
+    "api"
+  ],
+  "author": "Dukebot",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dukebot/instagram-scraper-api.git"
+  },
+  "homepage": "https://github.com/Dukebot/instagram-scraper-api#readme",
+  "bugs": {
+    "url": "https://github.com/Dukebot/instagram-scraper-api/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "user:info": "node ./scripts/get-user-info.js",
+    "user:posts": "node ./scripts/get-user-posts.js"
+  },
+  "dependencies": {
+  }
+}

package/src/entities/index.js

@@ -0,0 +1,3 @@
+export { default as Location } from "./location.js";
+export { default as Post } from "./post.js";
+export { default as User } from "./user.js";

package/src/entities/location.js

@@ -0,0 +1,32 @@
+/**
+ * Instagram location metadata attached to a post.
+ */
+export default class Location {
+  /**
+   * @param {Object} [data={}] Raw location data.
+   * @param {string|number|null} [data.pk]
+   * @param {string|null} [data.shortName]
+   * @param {string|number|null} [data.facebookPlacesId]
+   * @param {string|null} [data.externalSource]
+   * @param {string|null} [data.name]
+   * @param {string|null} [data.address]
+   * @param {string|null} [data.city]
+   * @param {boolean|null} [data.hasViewerSaved]
+   * @param {number|null} [data.lng]
+   * @param {number|null} [data.lat]
+   * @param {boolean|null} [data.isEligibleForGuides]
+   */
+  constructor(data = {}) {
+    this.pk = data.pk ?? null;
+    this.shortName = data.shortName ?? null;
+    this.facebookPlacesId = data.facebookPlacesId ?? null;
+    this.externalSource = data.externalSource ?? null;
+    this.name = data.name ?? null;
+    this.address = data.address ?? null;
+    this.city = data.city ?? null;
+    this.hasViewerSaved = data.hasViewerSaved ?? null;
+    this.lng = data.lng ?? null;
+    this.lat = data.lat ?? null;
+    this.isEligibleForGuides = data.isEligibleForGuides ?? null;
+  }
+}

package/src/entities/post.js

@@ -0,0 +1,50 @@
+import Location from "./location.js";
+
+/**
+ * Normalized Instagram post entity.
+ */
+export default class Post {
+  /**
+   * @param {Object} [data={}] Raw post data.
+   * @param {string|number|null} [data.pk]
+   * @param {string|number|null} [data.id]
+   * @param {string|number|null} [data.fbId]
+   * @param {string|number|null} [data.mediaId]
+   * @param {string|null} [data.code]
+   * @param {string|null} [data.title]
+   * @param {string|null} [data.text]
+   * @param {string|null} [data.externalUrl]
+   * @param {number|null} [data.takenAt]
+   * @param {string|null} [data.date]
+   * @param {string|null} [data.time]
+   * @param {Object|Location|null} [data.location]
+   * @param {string|null} [data.socialNetwork]
+   * @param {string|null} [data.accountUsername]
+   * @param {string|number|null} [data.accountId]
+   * @param {number|null} [data.likeCount]
+   * @param {number|null} [data.commentCount]
+   * @param {{url: string, caption: string|null}[]} [data.images]
+   * @param {{url: string, caption: string|null}[]} [data.videos]
+   */
+  constructor(data = {}) {
+    this.pk = data.pk ?? null;
+    this.id = data.id ?? null;
+    this.fbId = data.fbId ?? null;
+    this.mediaId = data.mediaId ?? null;
+    this.code = data.code ?? null;
+    this.title = data.title ?? null;
+    this.text = data.text ?? null;
+    this.externalUrl = data.externalUrl ?? null;
+    this.takenAt = data.takenAt ?? null;
+    this.date = data.date ?? null;
+    this.time = data.time ?? null;
+    this.location = data.location ? new Location(data.location) : null;
+    this.socialNetwork = data.socialNetwork ?? "Instagram";
+    this.accountUsername = data.accountUsername ?? null;
+    this.accountId = data.accountId ?? null;
+    this.likeCount = data.likeCount ?? null;
+    this.commentCount = data.commentCount ?? null;
+    this.images = data.images ?? [];
+    this.videos = data.videos ?? [];
+  }
+}

package/src/entities/user.js

@@ -0,0 +1,26 @@
+import Post from "./post.js";
+
+/**
+ * Normalized Instagram user entity.
+ */
+export default class User {
+  /**
+   * @param {Object} [data={}] Raw user data.
+   * @param {string|number|null} [data.otherId]
+   * @param {string|null} [data.name]
+   * @param {string|null} [data.username]
+   * @param {string|null} [data.biography]
+   * @param {string|null} [data.externalUrl]
+   * @param {string|null} [data.socialNetwork]
+   * @param {Object[]|Post[]} [data.posts]
+   */
+  constructor(data = {}) {
+    this.otherId = data.otherId ?? null;
+    this.name = data.name ?? null;
+    this.username = data.username ?? null;
+    this.biography = data.biography ?? null;
+    this.externalUrl = data.externalUrl ?? null;
+    this.socialNetwork = data.socialNetwork ?? "Instagram";
+    this.posts = (data.posts ?? []).map((post) => new Post(post));
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+/**
+ * Public entry point for the package.
+ */
+export { default as InstagramScraperAPI } from "./instagram_scraper_api.js";
+export * from "./entities/index.js";

package/src/instagram_scraper_api.js

@@ -0,0 +1,40 @@
+import { InstagramScraperAPI2Service } from "./instagram_scraper_api2/index.js";
+
+/**
+ * High-level API for retrieving Instagram profile data and posts.
+ */
+export default class InstagramScraperAPI {
+  /**
+   * @param {Object} [data={}] Configuration object.
+   * @param {string} [data.apiHost] RapidAPI host.
+   * @param {string} [data.apiKey] RapidAPI key.
+   */
+  constructor({ apiHost, apiKey } = {}) {
+    this.service = new InstagramScraperAPI2Service({ apiHost, apiKey });
+  }
+
+  /**
+   * Fetches Instagram profile information for a user.
+   *
+   * @param {string} usernameOrId Instagram username or account id.
+   * @returns {Promise<import("./entities/user.js").default>}
+   */
+  async getUserInfo(usernameOrId) {
+    return this.service.getUserInfo(usernameOrId);
+  }
+
+  /**
+   * Fetches Instagram posts for a user.
+   *
+   * @param {string} usernameOrId Instagram username or account id.
+   * @param {number} [numPosts] Maximum number of posts to return.
+   * @returns {Promise<import("./entities/post.js").default[]>}
+   */
+  async getUserPosts(usernameOrId, numPosts) {
+    const posts = await this.service.getUserPosts(usernameOrId);
+    if (!numPosts || numPosts < 1) {
+      return posts;
+    }
+    return posts.slice(0, numPosts);
+  }
+}

package/src/instagram_scraper_api2/client.js

@@ -0,0 +1,92 @@
+/**
+ * Low-level client for interacting with the RapidAPI provider.
+ */
+export default class InstagramScraperAPI2Client {
+  /**
+   * @param {Object} [data={}] Client configuration.
+   * @param {string} [data.apiHost] RapidAPI host.
+   * @param {string} [data.apiKey] RapidAPI key.
+   */
+  constructor({ apiHost, apiKey } = {}) {
+    if (!apiHost) throw new Error("apiHost is required");
+    if (!apiKey) throw new Error("apiKey is required");
+
+    this.baseURL = "https://instagram-scraper-api2.p.rapidapi.com/";
+    this.apiHost = apiHost;
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Performs a GET request against the provider.
+   *
+   * @param {string} url Relative API path.
+   * @param {{ params?: Record<string, string | number | boolean | null | undefined> }} [options]
+   * @returns {Promise<any>}
+   */
+  async get(url, options) {
+    try {
+      const requestUrl = new URL(url, this.baseURL);
+      const params = options?.params ?? {};
+
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          requestUrl.searchParams.set(key, value);
+        }
+      });
+
+      const response = await fetch(requestUrl, {
+        method: "GET",
+        headers: {
+          "x-rapidapi-host": this.apiHost,
+          "x-rapidapi-key": this.apiKey,
+        },
+      });
+
+      const data = await response.json();
+
+      if (!response.ok) {
+        throw new Error(data?.message ?? `Request failed with status ${response.status}`);
+      }
+
+      if (data.status === "error") {
+        throw new Error(data.message);
+      }
+
+      return data;
+    } catch (error) {
+      throw new Error(error.message);
+    }
+  }
+
+  /**
+   * Fetches profile information.
+   *
+   * @param {string} usernameOrIdOrUrl Instagram username, id, or profile URL.
+   * @returns {Promise<any>}
+   */
+  async getUserInfo(usernameOrIdOrUrl) {
+    if (!usernameOrIdOrUrl) {
+      throw new Error("usernameOrIdOrUrl is required");
+    }
+
+    return this.get("/v1/info", {
+      params: { username_or_id_or_url: usernameOrIdOrUrl },
+    });
+  }
+
+  /**
+   * Fetches posts for a profile.
+   *
+   * @param {string} usernameOrIdOrUrl Instagram username, id, or profile URL.
+   * @returns {Promise<any>}
+   */
+  async getUserPosts(usernameOrIdOrUrl) {
+    if (!usernameOrIdOrUrl) {
+      throw new Error("usernameOrIdOrUrl is required");
+    }
+
+    return this.get("/v1.2/posts", {
+      params: { username_or_id_or_url: usernameOrIdOrUrl },
+    });
+  }
+}

package/src/instagram_scraper_api2/index.js

@@ -0,0 +1 @@
+export { default as InstagramScraperAPI2Service } from "./service.js";

package/src/instagram_scraper_api2/response-processor.js

@@ -0,0 +1,112 @@
+import { Post, User } from "../entities/index.js";
+
+/**
+ * Maps provider responses into the package's normalized entities.
+ */
+export default class InstagramScraperAPI2ResponseProcessor {
+  /**
+   * @param {{ data: any }} response Provider response payload.
+   * @returns {User}
+   */
+  static processUserInfoResponse(response) {
+    return transformUser(response.data);
+  }
+
+  /**
+   * @param {{ data: { items: any[] } }} response Provider response payload.
+   * @returns {Post[]}
+   */
+  static processUserPostsResponse(response) {
+    return response.data.items.map(transformPost);
+  }
+}
+
+/**
+ * @param {any} user
+ * @returns {User}
+ */
+function transformUser(user) {
+  return new User({
+    otherId: user.id,
+    name: user.full_name,
+    username: user.username,
+    biography: user.biography,
+    externalUrl: user.external_url,
+  });
+}
+
+/**
+ * @param {any} post
+ * @returns {Post}
+ */
+function transformPost(post) {
+  const getImageUrlFromImageVersions = () => post.image_versions?.items?.[0]?.url ?? null;
+  const getVideoUrlFromVideoVersions = () => post.video_versions?.[0]?.url ?? null;
+  const urlToMediaObject = (url) => ({ url, caption: null });
+
+  function transformLocation() {
+    const location = post.location;
+    if (!location) {
+      return null;
+    }
+
+    return {
+      pk: location.id,
+      name: location.name,
+      lat: location.lat,
+      lng: location.lng,
+    };
+  }
+
+  function getDate() {
+    if (!post.taken_at) return null;
+    const dateTime = timestampToDateString(post.taken_at);
+    return dateTime.split(" ")[0];
+  }
+
+  function getTime() {
+    if (!post.taken_at) return null;
+    const dateTime = timestampToDateString(post.taken_at);
+    return dateTime.split(" ")[1];
+  }
+
+  return new Post({
+    pk: post.id,
+    id: post.id,
+    fbId: post.fbid,
+    code: post.code,
+    text: post.caption?.text ?? null,
+    takenAt: post.taken_at ? Number(post.taken_at) : null,
+    date: getDate(),
+    time: getTime(),
+    location: transformLocation(),
+    accountUsername: post.user?.username ?? null,
+    accountId: post.user?.id ?? null,
+    likeCount: post.like_count ?? null,
+    commentCount: post.comment_count ?? null,
+    images: [getImageUrlFromImageVersions()].filter(Boolean).map(urlToMediaObject),
+    videos: [getVideoUrlFromVideoVersions()].filter(Boolean).map(urlToMediaObject),
+  });
+}
+
+/**
+ * Formats a Unix timestamp using the same token pattern previously used by Moment.
+ *
+ * @param {number|string} timestamp Unix timestamp in seconds.
+ * @param {string} [format="YYYY-MM-DD HH:mm:ss"] Output pattern.
+ * @returns {string}
+ */
+function timestampToDateString(timestamp, format = "YYYY-MM-DD HH:mm:ss") {
+  const date = new Date(Number(timestamp) * 1000);
+
+  const parts = {
+    YYYY: String(date.getFullYear()),
+    MM: String(date.getMonth() + 1).padStart(2, "0"),
+    DD: String(date.getDate()).padStart(2, "0"),
+    HH: String(date.getHours()).padStart(2, "0"),
+    mm: String(date.getMinutes()).padStart(2, "0"),
+    ss: String(date.getSeconds()).padStart(2, "0"),
+  };
+
+  return format.replace(/YYYY|MM|DD|HH|mm|ss/g, (token) => parts[token]);
+}

package/src/instagram_scraper_api2/service.js

@@ -0,0 +1,39 @@
+import InstagramScraperAPI2Client from "./client.js";
+import InstagramScraperAPI2ResponseProcessor from "./response-processor.js";
+
+/**
+ * Internal service that coordinates the provider client and response mapping.
+ */
+export default class InstagramScraperAPI2Service {
+  /**
+   * @param {Object} [data={}] Service configuration.
+   * @param {string} [data.apiHost] RapidAPI host.
+   * @param {string} [data.apiKey] RapidAPI key.
+   */
+  constructor({ apiHost, apiKey } = {}) {
+    this.client = new InstagramScraperAPI2Client({ apiHost, apiKey });
+    this.responseProcessor = InstagramScraperAPI2ResponseProcessor;
+  }
+
+  /**
+   * Fetches and maps profile data into a normalized user entity.
+   *
+   * @param {string} usernameOrIdOrUrl Instagram username, id, or profile URL.
+   * @returns {Promise<import("../entities/user.js").default>}
+   */
+  async getUserInfo(usernameOrIdOrUrl) {
+    const response = await this.client.getUserInfo(usernameOrIdOrUrl);
+    return this.responseProcessor.processUserInfoResponse(response);
+  }
+
+  /**
+   * Fetches and maps profile posts into normalized post entities.
+   *
+   * @param {string} usernameOrIdOrUrl Instagram username, id, or profile URL.
+   * @returns {Promise<import("../entities/post.js").default[]>}
+   */
+  async getUserPosts(usernameOrIdOrUrl) {
+    const response = await this.client.getUserPosts(usernameOrIdOrUrl);
+    return this.responseProcessor.processUserPostsResponse(response);
+  }
+}