Bitly Node.js API Wrapper

Common errors

• Error: Invalid access token

  cause The provided Bitly API access token is missing, expired, incorrectly formatted, or lacks the necessary scopes. This is a common API authentication failure.
  fix Ensure `process.env.BITLY_USER_TOKEN` is set correctly with a valid, active Bitly API access token obtained from your Bitly account. Verify the token on the Bitly developer portal and confirm it has the required permissions for the operations you are performing.

• TypeError: bitly.bitlinks.create is not a function

  cause The `bitly` object or its nested `bitlinks` property was not correctly initialized, or the `create` method itself is undefined. This can happen if the library is not properly configured or if the Bitly API structure has changed significantly, rendering the wrapper incompatible.
  fix Double-check the client initialization steps, ensuring `new BitlyAPI()` for TypeScript/ESM or `require('bitly-node-api')` for CommonJS is called and the token is set. Given the package's abandoned status, this error might also indicate a fundamental incompatibility with the current Bitly API structure.

• API Error: BAD_REQUEST (400) - Missing long_url parameter

  cause The `long_url` property was either not provided or was null/empty in the payload object passed to a Bitlink creation method (e.g., `bitly.bitlinks.create`).
  fix Ensure the `payload` object passed to `bitly.bitlinks.create` or similar methods contains a valid `long_url` string, for example: `{ long_url: 'https://www.your-website.com/page' }`.

Warnings

• breaking The package `bitly-node-api` is effectively abandoned, with its last update in March 2019. This means it is highly unlikely to be compatible with recent Bitly API versions (v4 has seen updates since 2019) or support newer features. It is susceptible to breaking changes in the upstream Bitly API without corresponding updates.
  Fix: Consider migrating to a more actively maintained Bitly API client library or interacting directly with the Bitly API using a generic HTTP client (e.g., `axios`, `node-fetch`). Always verify against the official Bitly API documentation for current best practices.
• gotcha The package is at version 0.0.6, indicating it was pre-1.0 and likely considered unstable even during its active development phase. It has never reached a stable major release, implying potential for unannounced breaking changes if it were still maintained.
  Fix: Due to abandonment, there is no direct fix for version instability. Projects using this package should thoroughly test all integrations and be prepared for manual API interaction or library replacement.
• gotcha Initialization patterns differ significantly between CommonJS and TypeScript/ESM. CommonJS allows direct token passing to `require('bitly-node-api')(token)`, while TypeScript typically requires `new BitlyAPI()` followed by `bitly.setUserToken(token)`.
  Fix: For TypeScript/ESM, consistently use `import * as BitlyAPI from 'bitly-node-api'; const bitly = new BitlyAPI(); bitly.setUserToken(token);`. For CommonJS, choose `const bitly = require('bitly-node-api')(token)` for concise initialization or `const bitly = require('bitly-node-api'); bitly.setUserToken(token)` for more granular control.
• deprecated The README describes obtaining an OAuth token via `bitly.application.getOAuthToken(options)` using a username and password. This method of obtaining an access token is highly likely to be deprecated or removed by Bitly for security reasons, favoring more secure OAuth 2.0 grant types (e.g., client credentials, authorization code).
  Fix: Refer to the official Bitly API documentation (dev.bitly.com) for the current, recommended method of obtaining OAuth 2.0 access tokens. Avoid hardcoding usernames and passwords or relying on potentially insecure legacy authentication flows.

Install

• npm install bitly-node-api npm
• yarn add bitly-node-api yarn
• pnpm add bitly-node-api pnpm

Imports

• BitlyAPI (TypeScript/ESM)
  wrong:

  import BitlyAPI from 'bitly-node-api'; // Not a default export

  correct:

  import * as BitlyAPI from 'bitly-node-api';
  const bitly = new BitlyAPI();

  For TypeScript and modern ESM usage, import the entire module as a namespace and then instantiate the `BitlyAPI` class. The package does not provide a default export.
• bitly (CommonJS - direct token init)
  wrong:

  const bitly = new (require('bitly-node-api'))(process.env.BITLY_USER_TOKEN || 'YOUR_ACCESS_TOKEN'); // Incorrect new operator usage with require call

  correct:

  const bitly = require('bitly-node-api')(process.env.BITLY_USER_TOKEN || 'YOUR_ACCESS_TOKEN');

  In CommonJS, the module can be called directly with an access token as an argument, which acts as a factory function to create and initialize the API client.
• bitly (CommonJS - deferred token init)
  wrong:

  const bitly = require('bitly-node-api').BitlyAPI; // BitlyAPI is not a named export from CJS require

  correct:

  const bitly = require('bitly-node-api');
  bitly.setUserToken(process.env.BITLY_USER_TOKEN || 'YOUR_ACCESS_TOKEN');

  If you need to configure the access token after initial `require`, or obtain it dynamically, use the `setUserToken` method on the returned object.

Quickstart

This quickstart demonstrates how to initialize the `bitly-node-api` client with an access token (preferably from environment variables), then use it to create a new short Bitlink, expand it to retrieve its details, and finally fetch its click count.

import * as BitlyAPI from 'bitly-node-api';

const BITLY_USER_TOKEN = process.env.BITLY_USER_TOKEN ?? 'YOUR_BITLY_ACCESS_TOKEN_HERE';

// Ensure a token is available
if (!BITLY_USER_TOKEN || BITLY_USER_TOKEN === 'YOUR_BITLY_ACCESS_TOKEN_HERE') {
  console.error('ERROR: Please set BITLY_USER_TOKEN environment variable or replace placeholder.');
  process.exit(1);
}

const bitly = new BitlyAPI();
bitly.setUserToken(BITLY_USER_TOKEN);

async function createAndExpandBitlink() {
  try {
    const longUrl = 'https://www.example.com/a-very-long-url-for-testing-bitly-api-wrapper-' + Date.now();
    const payload = {
      long_url: longUrl,
      domain: 'bit.ly' // Specify a custom domain if you have one, otherwise omit.
    };
    console.log('Attempting to create a Bitlink for:', longUrl);

    // Create a new Bitlink
    const createResponse = await bitly.bitlinks.create(payload);
    console.log('Successfully created Bitlink:', createResponse.link);
    console.log('Original URL:', createResponse.long_url);

    // Expand the created Bitlink to retrieve full details
    console.log('\nAttempting to expand the Bitlink...');
    const expandResponse = await bitly.bitlinks.expand(createResponse.link);
    console.log('Expanded Bitlink details:', expandResponse);

    // Example: Get clicks for the Bitlink (assuming the API supports this and token has scope)
    console.log('\nAttempting to get click count for the Bitlink...');
    const clicksResponse = await bitly.bitlinks.getClicks(createResponse.link);
    console.log('Total clicks:', clicksResponse.total_clicks);

  } catch (error: any) {
    console.error('An error occurred during Bitlink operations:', error.message || error);
    if (error.response && error.response.data) {
      console.error('Bitly API Error Details:', error.response.data);
    }
  }
}

createAndExpandBitlink();