Harmonix Everywhere

A lightweight JavaScript library for integrating with the Harmonix Chrome extension.

Installation

npm install harmonix-everywhere

Usage

import { Harmonix } from 'harmonix-everywhere';

// Basic usage
function basicExample() {
  // Create a Harmonix client
  const harmonix = new Harmonix({ debug: true });

  // Initialize the client with default retry settings (30 attempts, 1 second interval)
  harmonix.initialize().then(isInitialized => {
    if (isInitialized) {
      console.log('Harmonix extension is available and initialized');
      
      // Open a contact in the extension
      harmonix.openContact(
        'ext-123', // External ID for the contact
        'Contact', // Object type ('Contact' or 'Company')
        {
          first_name: 'John',
          last_name: 'Doe',
          email: 'john@example.com',
          phone_number: '+1234567890',
          job_role: 'Sales Manager',
          company_name: 'ACME Inc'
        }
      )
      .then(result => {
        console.log('Contact opened:', result);
      })
      .catch(error => {
        console.error('Failed to open contact:', error);
      });
    } else {
      console.log('Harmonix extension is not available');
    }
  });
}

// Using auto-initialization
function autoInitExample() {
  // Create a Harmonix client with auto-initialization
  const harmonix = new Harmonix({ 
    debug: true,
    autoInitialize: true,  // Start initialization immediately
    maxRetries: 30,        // Try for 30 seconds
    retryInterval: 1000    // Check every second
  });
  
  // The initialization process is already running in the background
  // Later, when you need to use the extension, you can just call your methods
  // The library will ensure initialization is complete before proceeding
  
  // Example: When the user clicks a button to open a contact
  document.getElementById('openContactButton').addEventListener('click', async () => {
    try {
      const result = await harmonix.openContact(
        'ext-123',
        'Contact',
        {
          first_name: 'John',
          last_name: 'Doe',
          email: 'john@example.com'
        }
      );
      
      console.log('Contact opened:', result);
    } catch (error) {
      console.error('Failed to open contact:', error);
    }
  });
}

API

new Harmonix(options)

Creates a new instance of the Harmonix client.

Options:

• debug (boolean): Enables debug logging. Default: false
• autoInitialize (boolean): Automatically initialize the client upon creation. Default: false
• maxRetries (number): Maximum number of retry attempts when initializing. Default: 30
• retryInterval (number): Interval between retry attempts in milliseconds. Default: 1000 (1 second)

harmonix.isExtensionAvailable()

Checks if the Harmonix extension is installed and available.

Returns: Promise resolving to a boolean indicating availability.

harmonix.initialize(maxRetries, retryInterval)

Initializes the Harmonix client and establishes a connection with the extension. The method will retry connecting to the extension if it's not immediately available.

Parameters:

• maxRetries (number, optional): Maximum number of retry attempts. Default: 30
• retryInterval (number, optional): Interval between retry attempts in milliseconds. Default: 1000 (1 second)

Returns: Promise resolving to a boolean indicating success.

Example with retries:

// Try to initialize with 60 attempts, retrying every 500ms
harmonix.initialize(60, 500).then(success => {
  if (success) {
    console.log('Successfully connected to Harmonix extension');
  } else {
    console.log('Failed to connect to Harmonix extension after 60 attempts');
  }
});

harmonix.openContact(objectId, objectType, objectData)

Opens a contact or company in the Harmonix extension.

Parameters:

• objectId (string): Unique identifier for the object in your system
• objectType (string): Type of object, either 'Contact' or 'Company'
• objectData (object): Contact or company information

Contact Data Fields:

• first_name (string, required): Contact's first name
• last_name (string, required): Contact's last name
• email (string): Primary email address
• secondary_email (string): Secondary email address
• phone_number (string): Primary phone number
• secondary_phone_number (string): Secondary phone number
• job_role (string): Contact's job role or title
• company_name (string): Company name where the contact works
• linkedin_url (string): LinkedIn profile URL
• address (string): Physical address
• city (string): City
• country (string): Country
• website (string): Website URL

Company Data Fields:

• name (string, required): Company name
• industry (string): Industry or sector
• size (string): Company size (number of employees)
• revenue (string): Annual revenue
• email (string): Primary email address
• phone_number (string): Primary phone number
• linkedin_url (string): LinkedIn profile URL
• address (string): Physical address
• city (string): City
• country (string): Country
• website (string): Website URL

Returns: Promise resolving to an object with:

• success (boolean): Whether the operation was successful
• objectId (string): ID of the created/updated object in Harmonix

harmonix.sendCommand(command, params)

Sends a custom command to the Harmonix extension.

Parameters:

• command (string): The command to send
• params (any): Parameters for the command

Returns: Promise resolving to the command result.

Running the Examples

The package includes a set of example implementations showing how to integrate the Harmonix library in different scenarios.

To run the examples:

# Install dependencies
npm install

# Start the development server
npm run dev

Then open your browser to http://localhost:3001 to view the examples.

The examples include:

• A mockup CRM dashboard
• A contact detail page with "Open in Harmonix" button
• A company detail page with "Open in Harmonix" button

Note: You need to have the Harmonix Chrome extension installed in your browser for the examples to work properly.

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Lint the code
npm run lint

# Start the development server
npm run dev

License

MIT