Unipile Wrapper

Overview

A lightweight TypeScript wrapper for Unipile's social network automation platform. This wrapper simplifies the interaction with Unipile's API, currently focusing on LinkedIn automation features. The wrapper provides a modular, type-safe interface for common LinkedIn operations.

Features

• Full TypeScript support with type definitions
• Modular architecture with domain-based services
• Easy account connection using li_at cookies
• Streamlined search capabilities (URL-based and parameter-based)
• Profile management (retrieve, edit, add experience)
• Company information retrieval
• Built-in pagination support
• Centralized validation and error handling
• Promise-based async/await interface

Prerequisites

• Node.js 16+
• An active Unipile account
• Unipile API token
• Access to a Unipile subdomain and port

Installation

npm install @entergreat/unipile-wrapper

Configuration

Initialize the wrapper with your Unipile credentials:

import { LinkedinService } from '@entergreat/unipile-wrapper';

// With default accountId (recommended for single-account usage)
const linkedin = new LinkedinService({
  unipileToken: 'your-unipile-token',
  subdomain: 'your-subdomain',
  port: 443,
  accountId: 'your-account-id'  // Optional: set default accountId
});

// Without default accountId (for multi-account usage)
const linkedin = new LinkedinService({
  unipileToken: 'your-unipile-token',
  subdomain: 'your-subdomain',
  port: 443
});

When accountId is set in config, you don't need to pass it to each method. You can still override it per-call:

// Uses default accountId from config
await linkedin.search.byParams({ params: { keywords: 'developer' } });

// Override with different accountId
await linkedin.search.byParams({
  accountId: 'different-account-id',
  params: { keywords: 'developer' }
});

Architecture

The wrapper is organized into domain-based services:

LinkedinService
├── account   → Account connection
├── search    → LinkedIn search operations
├── profile   → Profile management
└── company   → Company information

Usage

Connect LinkedIn Account

Add a LinkedIn account to Unipile using a li_at cookie:

const account = await linkedin.account.connect({
  loginCookie: 'your-li-at-cookie'
});

Search LinkedIn

Using Parameters

const results = await linkedin.search.byParams({
  accountId: 'your-unipile-account-id',
  params: {
    keywords: 'software engineer',
    location: 'United States'
  },
  cursor: '', // for pagination
  limit: 10
});

Using LinkedIn URL

const results = await linkedin.search.byUrl({
  accountId: 'your-unipile-account-id',
  searchUrl: 'https://www.linkedin.com/search/results/people/?keywords=developer',
  cursor: '',
  limit: 10
});

Retrieve Search Parameters

const suggestions = await linkedin.search.retrieveParameters({
  accountId: 'your-unipile-account-id',
  type: 'LOCATION',
  keywords: 'new york',
  limit: 5
});

Profile Management

Retrieve Profile

const profile = await linkedin.profile.retrieve({
  accountId: 'your-unipile-account-id',
  profileId: 'john-doe-123',
  linkedinSections: ['experience', 'education'],
  notify: false
});

Edit Profile

const result = await linkedin.profile.edit({
  accountId: 'your-unipile-account-id',
  profileData: {
    headline: 'Senior Software Engineer | Node.js Expert',
    summary: 'Passionate developer with 10+ years of experience...',
    location: { id: '105015875' }
  }
});

Add Experience

const result = await linkedin.profile.addExperience({
  accountId: 'your-unipile-account-id',
  experience: {
    role: 'Software Engineer',
    company: 'Acme Corp',
    company_id: '123456',
    description: 'Building awesome products',
    location: 'Tel Aviv, Israel',
    start_month: 3,
    start_year: 2024,
    skills: ['TypeScript', 'Node.js', 'React'],
    notify_network: false
  }
});

Company Information

// By company ID
const company = await linkedin.company.retrieve({
  accountId: 'your-unipile-account-id',
  companyId: '123456'
});

// By company URL
const company = await linkedin.company.retrieve({
  accountId: 'your-unipile-account-id',
  companyUrl: 'https://www.linkedin.com/company/acme-corp'
});

API Reference

LinkedinService

Constructor

new LinkedinService({
  unipileToken: string,   // Your Unipile API token
  subdomain: string,      // Your Unipile subdomain
  port: number | string,  // Unipile port number
  accountId?: string      // Optional: default account ID for all methods
})

AccountService (linkedin.account)

connect({ loginCookie })

Connects a LinkedIn account to Unipile using a li_at cookie.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | loginCookie | string | Yes | LinkedIn li_at cookie value |

SearchService (linkedin.search)

byParams({ accountId, params, cursor, limit })

Performs a LinkedIn search using specified parameters.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | accountId | string | No* | config.accountId | Unipile account ID | | params | object | No | {} | LinkedIn search parameters | | cursor | string | No | - | Pagination cursor | | limit | number | No | 10 | Results per page |

byUrl({ accountId, searchUrl, cursor, limit })

Performs a LinkedIn search using a LinkedIn search URL.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | accountId | string | No* | config.accountId | Unipile account ID | | searchUrl | string | Yes | - | LinkedIn search URL | | cursor | string | No | - | Pagination cursor | | limit | number | No | 10 | Results per page |

retrieveParameters({ accountId, type, keywords, limit })

Retrieves LinkedIn search parameter suggestions.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | accountId | string | No* | config.accountId | Unipile account ID | | type | string | Yes | - | Parameter type (e.g., LOCATION) | | keywords | string | No | "" | Search keywords | | limit | number | No | 3 | Number of suggestions |

*Required if not set in constructor config.

ProfileService (linkedin.profile)

retrieve({ accountId, profileId, linkedinSections, notify })

Retrieves a LinkedIn user profile.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | accountId | string | No* | config.accountId | Unipile account ID | | profileId | string | Yes | - | LinkedIn profile ID or URL | | linkedinSections | string[] | No | [] | Sections to retrieve | | notify | boolean | No | false | Notify profile owner |

edit({ accountId, profileData })

Edits the LinkedIn profile of the account owner.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | accountId | string | No* | config.accountId | Unipile account ID | | profileData | object | Yes | - | Profile fields to update |

ProfileData fields:

• headline: string - Professional headline
• summary: string - Profile bio/summary
• location: { id: string } - Location object
• picture: object - Profile/cover picture settings
• experience: object - Experience data
• education: object - Education entries

addExperience({ accountId, experience })

Adds a work experience position to the profile.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | accountId | string | No* | config.accountId | Unipile account ID | | experience | ExperienceData | Yes | - | Experience details |

*Required if not set in constructor config.

ExperienceData fields:

| Field | Type | Required | Description | |-------|------|----------|-------------| | role | string | Yes | Job title | | company | string | Yes | Company name | | company_id | string | No | LinkedIn company ID | | description | string | No | Role description | | location | string | No | Job location | | start_month | number | No | Start month (1-12) | | start_year | number | No | Start year | | end_month | number | No | End month (1-12) | | end_year | number | No | End year | | skills | string[] | No | Associated skills | | notify_network | boolean | No | Notify connections |

CompanyService (linkedin.company)

retrieve({ accountId, companyId, companyUrl })

Retrieves LinkedIn company information.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | accountId | string | No** | config.accountId | Unipile account ID | | companyId | string | No* | - | LinkedIn company ID | | companyUrl | string | No* | - | LinkedIn company URL |

*Either companyId or companyUrl must be provided.

**Required if not set in constructor config.

Error Handling

The wrapper throws ValidationError for invalid inputs:

import { ValidationError } from '@entergreat/unipile-wrapper';

try {
  await linkedin.profile.retrieve({ accountId: '', profileId: 'test' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  }
}

Dependencies

• axios - HTTP client
• form-data - Multipart form handling

Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details