Unipile Node.js SDK

Common errors

• Error: connect ECONNREFUSED

  cause The Unipile API endpoint (DSN) is unreachable, possibly due to a network issue, incorrect DSN, or Unipile service outage.
  fix Verify your `UNIPIL_DSN` configuration. Check network connectivity and Unipile's service status page. Ensure your firewall isn't blocking outgoing connections.

• Error: Unauthorized

  cause The provided `UNIPIL_ACCESS_TOKEN` is missing, expired, or invalid, or the connected account is disconnected from the provider.
  fix Ensure your `UNIPIL_ACCESS_TOKEN` is correct and current. If an account is disconnected, prompt the user to re-authenticate via the hosted authentication flow.

• Error: Too Many Requests

  cause Your application has exceeded the API rate limits imposed by Unipile or the underlying social media platform (e.g., LinkedIn).
  fix Implement exponential back-off and retry logic for API calls. Review and adjust your application's usage patterns to stay within documented rate limits.

• TypeError: client.users.getCompanyProfile is not a function

  cause This typically occurs when `unipile-node-sdk` is imported using CommonJS `require()` syntax in an environment expecting ESM, or if the client object is not correctly initialized.
  fix Ensure you are using `import { UnipileClient } from 'unipile-node-sdk';` and that your `package.json` specifies `"type": "module"` or your file uses `.mjs` extension for ESM. Verify the client is initialized before calling methods.

• Error: Invalid account

  cause The `account_id` provided for an operation is incorrect, not found, or not associated with the requested feature or provider.
  fix Verify that the `account_id` used in the API call is valid and corresponds to an actively connected account for the specific provider (e.g., LinkedIn for `getCompanyProfile`). Double-check stored `account_id` values.

Warnings

• breaking The Unipile Node.js SDK requires Node.js version 18 or higher. Applications running on older Node.js versions will encounter compatibility issues or fail to run.
  Fix: Upgrade your Node.js runtime environment to version 18 or later.
• gotcha API Access Tokens and DSN (Data Source Name) are sensitive credentials. Exposing them in client-side code or committing them directly to version control poses a significant security risk.
  Fix: Store Unipile DSN and Access Tokens securely as environment variables (e.g., `process.env.UNIPIL_DSN`, `process.env.UNIPIL_ACCESS_TOKEN`) and access them only on the server-side.
• gotcha Interacting with social media APIs (LinkedIn, WhatsApp, Instagram) is subject to strict rate limits and terms of service. Excessive or automated activity can lead to temporary blocks or permanent account suspension.
  Fix: Implement robust rate-limiting and back-off strategies in your application. Monitor API usage and adhere to Unipile's and the underlying platforms' recommendations. Use real accounts, avoid suspicious behavior, and inform users about automated actions.
• gotcha Authentication processes for platforms like LinkedIn can be complex, involving hosted auth flows or direct username/password methods which may require handling 2FA/OTP checkpoints. Incorrect implementation can lead to connection failures or account lockouts.
  Fix: Carefully follow the Unipile documentation for each provider's authentication method. For automated methods (e.g., username/password), ensure robust error handling for 2FA/OTP challenges.
• gotcha The underlying APIs (LinkedIn, WhatsApp, etc.) frequently update, which may introduce breaking changes not immediately reflected in the SDK. This can lead to unexpected errors or outdated functionality.
  Fix: Regularly update the `unipile-node-sdk` to the latest version. Monitor Unipile's changelog and documentation for updates regarding provider API changes.

Install

• npm install unipile-node-sdk npm
• yarn add unipile-node-sdk yarn
• pnpm add unipile-node-sdk pnpm

Imports

• UnipileClient
  wrong:

  const UnipileClient = require('unipile-node-sdk')

  correct:

  import { UnipileClient } from 'unipile-node-sdk'

  The Unipile SDK is designed for ESM, though CJS support was added in previous versions. For new projects, ESM `import` is recommended.
• UnipileError

  import { UnipileError } from 'unipile-node-sdk'

  While not explicitly shown in the README, SDKs often export a custom error class for handling API-specific exceptions like authentication failures or rate limits, which typically inherit from `Error`.
• AccountConnectLinkedinInput

  import type { AccountConnectLinkedinInput } from 'unipile-node-sdk'

  Type imports are crucial for TypeScript projects to ensure correct parameter structures for API calls, like connecting a LinkedIn account.

Quickstart

This quickstart demonstrates how to initialize the Unipile client, generate a hosted authentication link for account connection, and retrieve a LinkedIn company profile using environment variables for secure credential management.

import { UnipileClient } from 'unipile-node-sdk';

// Initialize the Unipile client with your DSN and Access Token.
// Always use environment variables for sensitive credentials in production.
const client = new UnipileClient(
  process.env.UNIPIL_DSN ?? 'https://api.unipile.com', // Default or example DSN
  process.env.UNIPIL_ACCESS_TOKEN ?? '' // Your Unipile API Access Token
);

async function runUnipileExample() {
  try {
    console.log('Attempting to generate a Hosted Auth Link...');
    // Generates a link for users to connect their social accounts securely.
    const authLinkResponse = await client.account.createHostedAuthLink({
      type: 'create', // 'create' for new accounts, 'reconnect' for existing
      expiresOn: new Date(Date.now() + 3600 * 1000).toISOString(), // Link valid for 1 hour
      api_url: process.env.UNIPIL_API_URL ?? 'https://api.unipile.com', // Your Unipile API URL
      providers: '*', // '*' for all providers, or an array like ['LINKEDIN', 'WHATSAPP']
      success_redirect_url: 'https://your-app.com/auth-success', // Where to redirect after successful connection
      metadata: { userId: 'user-123', integrationType: 'onboarding' } // Optional metadata
    });
    console.log('Hosted Auth Link Generated:', authLinkResponse.url); 

    // Example: Retrieve a LinkedIn company profile (requires a connected LinkedIn account_id).
    // This account_id would typically be stored after a user successfully connects via the auth link.
    const linkedinAccountId = process.env.LINKEDIN_ACCOUNT_ID; // Example: 'acc_xyz123'
    if (linkedinAccountId) {
      console.log(`\nRetrieving LinkedIn company profile for account ${linkedinAccountId}...`);
      const companyProfile = await client.users.getCompanyProfile({
        account_id: linkedinAccountId,
        identifier: 'Unipile', // The company's name or LinkedIn ID
      });
      console.log('Retrieved Company Profile:', companyProfile);
    } else {
      console.warn('\nWarning: LINKEDIN_ACCOUNT_ID environment variable not set. Skipping company profile example.');
    }

  } catch (error) {
    console.error('\nAn error occurred during Unipile SDK operation:');
    if (error instanceof Error) {
      console.error('Error message:', error.message);
      // Log the full error object for debugging in development
      if (process.env.NODE_ENV !== 'production') {
        console.error(error);
      }
    } else {
      console.error(error);
    }
  }
}

runUnipileExample();