gologin 2.1.19 → 2.1.21

package/.eslintrc.json

@@ -102,7 +102,7 @@
     ],
     "max-lines": [
       "warn",
-      1500
+      2000
     ],
     "no-else-return": [
       "warn",

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+Combined changelog for GoLogin node.js SDK
+
+## [2.1.21] 2025-04-23
+
+
+### Miscellaneous Chores
+
+* Deleted old exmaples and added new one that up to date
+* Added changelog to track changes

package/README.md

@@ -1,103 +1,179 @@
-# class GoLogin - class for working with <a href="https://gologin.com" target="_blank">gologin.com</a> API
-# Official Package
+# GoLogin Node.js SDK
+ This package provides functionality to run and stop GoLogin profiles with node.js and then connect the profiles to automation tools like Selenium, Puppetteer, Playwright etc.
 
-## Getting Started
-
-GoLogin supports Linux, MacOS and Windows platforms.
+# How does it work?
+ 1. You give SDK your dev token and profile id that you want to run
+ 2. SDK takes care of downloading, preparing your profile and starts the browser
+ 3. SDK gives you websocket url for automation tools
+ 4. You take this websocker url and connect it to the automation tool on your choice: Puppetteer, Selenium, Playwright etc
+ 5. Automation tool connects to browser and you can manage it through code
 
-### Installation
-
-`npm i gologin`
+## Getting Started
 
-for running example.js install puppeteer-core
+Where is token? API token is <a href="https://app.gologin.com/#/personalArea/TokenApi" target="_blank">here</a>.
 
-`npm i puppeteer-core`
+![Token API in Settings](https://user-images.githubusercontent.com/12957968/146891933-c3b60b4d-c850-47a5-8adf-bc8c37372664.gif)
 
-### Usage
 
-Where is token? API token is <a href="https://app.gologin.com/#/personalArea/TokenApi" target="_blank">here</a>.
-To have an access to the page below you need <a href="https://app.gologin.com/#/createUser" target="_blank">register</a> GoLogin account.
+### Installation
 
-![Token API in Settings](https://user-images.githubusercontent.com/12957968/146891933-c3b60b4d-c850-47a5-8adf-bc8c37372664.gif)
+`npm i gologin`
 
 ### Example
 
 ```js
-import puppeteer from 'puppeteer-core';
+import { GologinApi } from './src/gologin-api.js';
 
-import GoLogin from '../src/gologin.js';
+const GL = GologinApi({
+  token: 'your token',
+});
 
-const { connect } = puppeteer;
+const profile = await GL.createProfileRandomFingerprint('some name');
+const profileId = profile.id;
 
-(async () => {
-  const GL = new GoLogin({
-    token: 'yU0token',
-    profile_id: 'yU0Pr0f1leiD',
-  });
-
-  const { status, wsUrl } = await GL.start().catch((e) => {
-    console.trace(e);
+await GL.addGologinProxyToProfile(profileId, 'us');
+const browser = await GL.launch({ profileId });
+const page = await browser.newPage();
+await page.goto('https://linkedin.com');
+await new Promise((resolve) => setTimeout(resolve, 5000));
+await browser.close();
+await GL.stop();
+```
 
-    return { status: 'failure' };
-  });
+###
+### Methods
+#### constructor
 
-  if (status !== 'success') {
-    console.log('Invalid status');
+Required options:
+- `token` <[string]> **Required** - your API <a href="https://gologin.com/#/personalArea/TokenApi" target="_blank">token</a>
 
-    return;
-  }
+Optional options:
+- `profile_id` <[string]> - profile ID (NOT PROFILE NAME) will be generated if not specified
+- `executablePath` <[string]> path to executable Orbita file. Orbita will be downloaded automatically if not specified
+- `extra_params` arrayof <[string]> additional flags for browser start. For example: '--headles', '--load-extentions=path/to/extension'
+- `uploadCookiesToServer` <[boolean]> upload cookies to server after profile stopping (default false). It allows you to export cookies from api later.
+- `writeCookesFromServer` <[boolean]> if you have predefined cookies and you want browser to import it (default true).
+- `tmpdir` <[string]> absolute path to the directtory where you want to store user-data-dir. Default path in tmp folder will be picked if no specified
+- `vncPort` <[integer]> port of VNC server if you using it
 
-  const browser = await connect({
-    browserWSEndpoint: wsUrl.toString(),
-    ignoreHTTPSErrors: true,
-  });
+```js
+const GL = new GoLogin({
+    token: 'your token',
+    profile_id: 'profile id',
+    extra_params: ["--headless", "--load-extentions=path/to/extension"]
+});
+```
 
-  const page = await browser.newPage();
-  await page.goto('https://myip.link/mini');
-  console.log(await page.content());
-  await browser.close();
-  await GL.stop();
-})();
+#### createProfileRandomFingerprint - you pass os ('lin', 'win', 'mac') and profile name and we give you brand new shiny profile
+```js
+const GL = new GoLogin({
+    token: 'your token',
+    profile_id: 'profile id',
+    extra_params: ["--headless", "--load-extentions=path/to/extension"]
+});
+const profile = await gl.createProfileRandomFingerprint("some name")
+const profileId = profile.id
 ```
 
-### Running example:
 
-`DEBUG=gologin* node example.js`
+#### createProfileWithCustomParams - This method creates a profile and you can pass any particular params to it. Full list of params you can find here - https://api.gologin.com/docs
+```js
+const GL = GoLogin({
+	"token": "your token",
+	})
+const profile = await gl.createProfileWithCustomParams({
+    "os": "lin",
+    "name": "some name",
+    "navigator": {
+        "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
+        "resolution": "1920x1080",
+        "language": "en-US",
+        "platform": "Linux x86_64",
+        "hardwareConcurrency": 8,
+        "deviceMemory": 8,
+        "maxTouchPoints": 0
+    }
+})
+const profileId = profile.id
+```
 
-###
-### Methods
-#### constructor
+#### updateUserAgentToLatestBrowser - user agent is one of the most important thing in your fingerprint. It decides which browser version to run. This method help you to keep useragent up to date.
+```js
+const GL = GoLogin({
+	"token": "your token",
+	})
+await GL.updateUserAgentToLatestBrowser(["profineId1", "profileId2"], "workspceId(optional)")
+```
 
-- `options` <[Object]> Options for profile
-    - `autoUpdateBrowser` <[boolean]> do not ask whether download new browser version (default false)
-    - `token` <[string]> your API <a href="https://gologin.com/#/personalArea/TokenApi" target="_blank">token</a>
-    - `profile_id` <[string]> profile ID
-    - `executablePath` <[string]> path to executable Orbita file. Orbita will be downloaded automatically if not specified.
-    - `remote_debugging_port` <[int]> port for remote debugging
-    - `vncPort` <[integer]> port of VNC server if you using it
-    - `tmpdir` <[string]> path to temporary directore for saving profiles
-    - `extra_params` arrayof <[string]> extra params for browser orbita (ex. extentions etc.)
-    - `uploadCookiesToServer` <[boolean]> upload cookies to server after profile stopping (default false)
-    - `writeCookesFromServer` <[boolean]> download cookies from server and write to profile cookies file (default true)
-    - `skipOrbitaHashChecking` <[boolean]> skip hash checking for Orbita after downloading process (default false)
+#### addGologinProxyToProfile - Gologin provides high quality proxies with free traffic for paid users. Here you can add gologin proxy to profile, just pass country code
+```js
+const GL = GoLogin({
+	"token": "your token",
+	})
+await GL.addGologinProxyToProfile("profileId", "us")
+```
 
+#### addCookiesToProfile - You can pass cookies to the profile and browser will import it before starting
 ```js
-import GoLogin from '../src/gologin.js';
-const GL = new GoLogin({
-    token: 'yU0token',
-    profile_id: 'yU0Pr0f1leiD',
-});
+const GL = GoLogin({
+	"token": "your token",
+	})
+
+await GL.addCookiesToProfile("profileId", [
+    {
+        "name": "session_id",
+        "value": "abc123",
+        "domain": "example.com",
+        "path": "/",
+        "expirationDate": 1719161018.307793,
+        "httpOnly": True,
+        "secure": True
+    },
+    {
+        "name": "user_preferences",
+        "value": "dark_mode",
+        "domain": "example.com",
+        "path": "/settings",
+        "sameSite": "lax"
+    }
+])
+```
+
+#### refreshProfilesFingerprint - Replaces your profile fingerprint with a new one
+```js
+const GL = GoLogin({
+	"token": "your token",
+	})
+
+await GL.refreshProfilesFingerprint(["profileId1", "profileId2"])
 ```
 
-#### start()  
+#### changeProfileProxy - allows you to set a proxy to a profile
+```js
+const GL = GoLogin({
+	"token": "your token",
+	})
+await GL.changeProfileProxy("profileId", { "mode": "http", "host": "somehost.com", "port": 109, "username": "someusername", "password": "somepassword"})
+```
 
-- returns: <[object]> { status, wsUrl } 
+#### launch() - starts browser with profile id, returning WebSocket url for puppeteer
+```js
+const GL = GoLogin({
+	"token": "your token",
+	})
+await GL.launch({ profileId: 'some profileId' })
+```
 
-start browser with profile id, returning WebSocket url for puppeteer
 
-#### stop()  
+#### exit() stops browser and uploads it to the storage
+```js
+const GL = GoLogin({
+	"token": "your token",
+	})
+await GL.launch({ profileId: 'some profileId' })
+await GL.exit()
+```
 
-stop browser with profile id
 
 ### DEBUG
 

package/examples/puppeter/cloud-browser.js

@@ -0,0 +1,30 @@
+// Gologin provides a cloud browser that can be used to run puppeteer aytomation.
+// It will handle the browser start and close management - you just need to control the browser with pupputter
+import { GologinApi } from 'gologin';
+
+const token = process.env.GL_API_TOKEN || 'your dev token here';
+const gologin = GologinApi({
+  token,
+});
+
+async function main() {
+  const { browser } = await gologin.launch({
+    cloud: true,
+    // pass profileId parameter if you want to run particular profile
+    // profileId: 'your profileId here',
+  });
+
+  const page = await browser.newPage();
+
+  await page.goto('https://iphey.com/', { waitUntil: 'networkidle2' });
+  const status = await page.$eval('.trustworthy:not(.hide)',
+    (elt) => elt?.innerText?.trim(),
+  );
+
+  console.log('status', status);
+
+  return status;
+}
+
+main().catch(console.error)
+  .finally(gologin.exit);

package/examples/puppeter/headless.js

@@ -0,0 +1,30 @@
+// SDK will prepare the browser and will start it on your machine then you can control it with puppeteer
+import { GologinApi } from 'gologin';
+
+const token = process.env.GL_API_TOKEN || 'your dev token here';
+const gologin = GologinApi({
+  token,
+});
+
+async function main() {
+  const { browser } = await gologin.launch({
+    extra_params: ['--headless'],
+    // pass profileId parameter if you want to run particular profile
+    // profileId: 'your profileId here',
+  });
+
+  const page = await browser.newPage();
+
+  await page.goto('https://iphey.com/', { waitUntil: 'networkidle2' });
+  const status = await page.$eval('.trustworthy:not(.hide)',
+    (elt) => elt?.innerText?.trim(),
+  );
+
+  await new Promise((resolve) => setTimeout(resolve, 10000));
+  console.log('status', status);
+
+  return status;
+}
+
+main().catch(console.error)
+  .finally(gologin.exit);

package/examples/puppeter/local-browser.js

@@ -0,0 +1,29 @@
+// SDK will prepare the browser and will start it on your machine then you can control it with puppeteer
+import { GologinApi } from 'gologin';
+
+const token = process.env.GL_API_TOKEN || 'your dev token here';
+const gologin = GologinApi({
+  token,
+});
+
+async function main() {
+  const { browser } = await gologin.launch({
+    // pass profileId parameter if you want to run particular profile
+    // profileId: 'your profileId here',
+  });
+
+  const page = await browser.newPage();
+
+  await page.goto('https://iphey.com/', { waitUntil: 'networkidle2' });
+  const status = await page.$eval('.trustworthy:not(.hide)',
+    (elt) => elt?.innerText?.trim(),
+  );
+
+  await new Promise((resolve) => setTimeout(resolve, 10000));
+  console.log('status', status);
+
+  return status;
+}
+
+main().catch(console.error)
+  .finally(gologin.exit);

package/examples/puppeter/one-time-use-profile.js

@@ -0,0 +1,31 @@
+// You need to create profile add proxy, use it with puppetter and then delete it
+import { GologinApi } from '../../src/gologin-api.js';
+
+const token = process.env.GL_API_TOKEN || 'your dev token here';
+const gologin = GologinApi({
+  token,
+});
+
+async function main() {
+  const profile = await gologin.createProfileRandomFingerprint();
+  const profileId = profile.id;
+  await gologin.addGologinProxyToProfile(profileId, 'US');
+
+  const { browser } = await gologin.launch({ profileId });
+  const page = await browser.newPage();
+
+  await page.goto('https://iphey.com/', { waitUntil: 'networkidle2' });
+  const status = await page.$eval('.trustworthy:not(.hide)',
+    (elt) => elt?.innerText?.trim(),
+  );
+
+  await new Promise((resolve) => setTimeout(resolve, 10000));
+  console.log('status', status);
+
+  await gologin.deleteProfile(profileId);
+
+  return status;
+}
+
+main().catch(console.error)
+  .finally(gologin.exit);

package/index.d.ts

@@ -1,5 +1,7 @@
 import { type Browser } from 'puppeteer-core/lib/Browser';
 
+import { CreateCustomBrowserValidation, BrowserProxyCreateValidation } from './types/profile-params';
+
 export const OPERATING_SYSTEMS = {
   win: 'win',
   lin: 'lin',
@@ -45,12 +47,29 @@ type LaunchParams =
     os: OsType;
   };
 
-type LaunchFn = (params?: LaunchParams) => Promise<{ browser: Browser }>;
+type Cookie = {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expirationDate?: number;
+  creationDate?: number;
+  hostOnly?: boolean;
+  httpOnly?: boolean;
+  sameSite?: 'no_restriction' | 'lax' | 'strict';
+  secure?: boolean;
+  session?: boolean;
+  url?: string;
+};
 
 type GologinApiType = {
-  launch: LaunchFn;
+  launch: (params?: LaunchParams) => Promise<{ browser: Browser }>;
   exit: (status = 0) => Promise<void>;
-  delay: (ms: number) => Promise<void>;
+  createCustom: (params: CreateCustomBrowserValidation) => Promise<string>;
+  updateProfileFingerprint: (profileId: string[]) => Promise<void>;
+  updateUserAgentToLatestBrowser: (profileIds: string[], workspaceId?: string) => Promise<void>;
+  updateProfileProxy: (profileId: string, proxyData: BrowserProxyCreateValidation) => Promise<void>;
+  addCookiesToProfile: (profileId: string, cookies: Cookie[]) => Promise<void>;
 };
 
 type GologinApiParams = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gologin",
-  "version": "2.1.19",
+  "version": "2.1.21",
   "description": "A high-level API to control Orbita browser over GoLogin API",
   "types": "./index.d.ts",
   "main": "./src/gologin.js",
@@ -46,4 +46,4 @@
     "format": "npx prettier --single-quote src/* --write",
     "iphey": "GOLOGIN_PROFILE_ID= GOLOGIN_API_TOKEN= node examples/example-iphey "
   }
-}
+}