LeadConduit Integration Utilities

Common errors

• TypeError: require is not a function

  cause Attempting to use `require()` in an ECMAScript Module (ESM) context without proper transpilation or a Node.js wrapper.
  fix Use ESM `import { HttpError, test } from 'leadconduit-integration';` instead of `require()`. Ensure your Node.js project is configured for ESM (e.g., `"type": "module"` in `package.json`) or use a bundler that handles CommonJS interoperability.

• TypeError: HttpError is not a constructor

  cause Incorrectly importing `HttpError` as a default export, or not accessing it as a named property from the `require()` result.
  fix Use named import `import { HttpError } from 'leadconduit-integration';` for ESM, or destructure from `require`: `const { HttpError } = require('leadconduit-integration');` for CommonJS.

• TypeError: Cannot read properties of undefined (reading 'parser')

  cause Attempting to access `parser` from an `undefined` `test` object, often due to incorrect import or destructuring of the `test` utility.
  fix Ensure `test` is correctly imported as a named export (`import { test } from 'leadconduit-integration';`) or accessed as a property of the main CommonJS `require` object (`const parser = require('leadconduit-integration').test.parser;`). Then, access `parser` via `test.parser`.

Warnings

• breaking This package is currently in a pre-1.0 release phase (v0.6.3). Breaking changes may be introduced in minor version updates without strictly adhering to semantic versioning for major increments. Always review the release notes carefully when upgrading.
  Fix: Always pin to exact versions or test thoroughly before deploying new minor versions in production environments. Refer to the GitHub repository for release notes and detailed changes.
• gotcha The documentation and examples primarily feature CommonJS (`require`) syntax. While the package supports ESM `import` statements, users integrating into pure ESM projects should ensure their build setup correctly handles named exports, especially for nested utilities like `test.parser`.
  Fix: For ESM, use named imports: `import { HttpError, test } from 'leadconduit-integration';`. For nested properties, access them directly: `const parser = test.parser;`.
• gotcha This is a highly specialized utility module designed for LeadConduit integrations. Its concepts (e.g., 'request vars', 'type parser') are specific to the LeadConduit platform. Developers unfamiliar with LeadConduit's integration patterns might find it difficult to use without prior context.
  Fix: Refer to the official LeadConduit documentation for context on integration development and data structures before implementing with this library.

Install

• npm install leadconduit-integration npm
• yarn add leadconduit-integration yarn
• pnpm add leadconduit-integration pnpm

Imports

• HttpError
  wrong:

  import HttpError from 'leadconduit-integration';
  const HttpError = require('leadconduit-integration');

  correct:

  import { HttpError } from 'leadconduit-integration';

  HttpError is a named export. The README shows CommonJS `require('leadconduit-integration').HttpError`, which is also a correct way to access it in CJS projects.
• test.parser
  wrong:

  import { parser } from 'leadconduit-integration';
  const parser = require('leadconduit-integration').parser;

  correct:

  import { test } from 'leadconduit-integration';
  const parser = test.parser;

  The `parser` function is a nested utility under the `test` object. Access it via `test.parser` from the named ESM export, or `require('leadconduit-integration').test.parser` in CommonJS.
• CommonJS named exports
  wrong:

  const lcIntegration = require('leadconduit-integration'); // then expect lcIntegration.HttpError to be a class directly without destructuring

  correct:

  const { HttpError, test } = require('leadconduit-integration');

  This is the idiomatic way to destructure named exports in CommonJS, providing direct access to `HttpError` and the `test` utility object.

Quickstart

Demonstrates how to handle immediate HTTP responses using `HttpError` in an inbound integration, and how to use `test.parser` to simulate and parse richly typed LeadConduit data for unit testing purposes.

import { HttpError, test } from 'leadconduit-integration';

// Example 1: Handling immediate HTTP responses in an inbound integration
function handleIncomingRequest(req: { method?: string }): { status: number; body: string; headers?: Record<string, string> } {
  const method = req.method?.toLowerCase();
  if (method !== 'get' && method !== 'post') {
    throw new HttpError(
      415,
      { 'Content-Type': 'text/plain', Allow: 'GET, POST' },
      `The ${method?.toUpperCase() || 'UNKNOWN'} method is not allowed`
    );
  }
  console.log(`Processing ${method?.toUpperCase()} request...`);
  // ... actual request processing logic ...
  return { status: 200, body: 'Request handled successfully!' };
}

try {
  handleIncomingRequest({ method: 'PUT' }); // Simulate an unsupported method
} catch (e) {
  if (e instanceof HttpError) {
    console.log(`\nCaught HttpError: Status ${e.status}, Body: '${e.body}'`);
  } else {
    console.error(`\nAn unexpected error occurred: ${e instanceof Error ? e.message : String(e)}`);
  }
}

// Example 2: Using test.parser to simulate and parse richly typed data for tests
const requestVariables = [
  { name: 'zip_code', type: 'postal_code' },
  { name: 'contact_phone', type: 'phone' },
  { name: 'age_years', type: 'integer' },
  { name: 'enrollment_date', type: 'date' }
];

const parseLeadData = test.parser(requestVariables);

const rawLeadInput = {
  first_name: 'Alice',
  zip_code: '90210',
  contact_phone: '1-800-555-0199',
  age_years: '25',
  enrollment_date: '2023-11-15'
};

const parsedLeadData = parseLeadData(rawLeadInput);
console.log('\nParsed Lead Data for Testing:');
console.log(JSON.stringify(parsedLeadData, null, 2));