Overview

An integration point defines how MelodyArc connects and communicates with an external system, service, or data provider.
Each integration must be implemented in a structured, reusable, and self-contained way to ensure maintainability, reliability, and consistency across all environments.

Integrations typically include:

• A helper function point that wraps all reusable logic for the integration.
• Optional core code points that provide universal behaviors for that integration set.
• Organization-specific points or workflows that extend these helpers for custom use cases.

1️⃣ Core Principles

1. Single Source of Truth — Each integration should have one helper function file that contains all reusable logic for interacting with that system.
   This helper must be imported wherever the integration is needed.

2. Universal Helper — Only universal integration logic belongs in the helper (e.g., authentication, payload formatting, shared API calls).
   Code points that perform organization-specific or environment-specific logic should not be part of the integration’s core helper set.

3. Use _fetch for all HTTP requests — All network calls made within integration helpers must use the platform-standard _fetch function.
   This ensures observability, logging, and security consistency across all integrations.

4. Consistent Tagging — Every integration helper and related base point must include the tag:

   set:integration_<integration_name>

   Example:
   set:integration_unwrangle

   This enables discovery, organization, and deployment consistency across the platform.

5. Version Tracking — Each integration must include a value point in the set_versions partition that identifies its version.
   The value point should be named <integration_name>_version with the value as the version number "unwrangle_version": "1.0.0".

   This ensures that integrations can be versioned, tracked, and upgraded in a controlled manner.

2️⃣ Helper Function Standard

Each helper function point should follow this pattern:

• Define base values — including the API URL, integration name, and any required authentication tokens.
• Include small reusable functions — for building payloads, formatting URLs, or preparing headers.
• Perform API calls — using _fetch() with standard logging, time measurement, and error handling.
• Register functions — in the global namespace within execute_process().

/**
 * 🧩 Unwrangle API Helper
 * Provides reusable functions for querying product data from the Unwrangle API.
 */

const helperName = "unwrangle-api-helper";
const apiBaseUrl = "https://data.unwrangle.com/api/getter/";
const API_KEY = __unwrangle_api_key;

/** 
 * Constructs the full API URL with query parameters. 
 * Automatically includes the API key and `page=1` parameter.
 */
function buildQueryUrl(params) {
  const url = new URL(apiBaseUrl);
  Object.entries(params).forEach(([key, value]) => {
    if (value != null && value !== "") url.searchParams.append(key, value);
  });
  url.searchParams.append("page", "1");
  url.searchParams.append("api_key", API_KEY);
  return url.toString();
}

/**
 * Handles the API request with built-in logging and error propagation.
 * All calls are made via `_fetch`, ensuring standardized logging and redaction.
 */
async function callAPI(url) {
  const startTime = Date.now();
  try {
    const res = await _fetch(url, {
      method: "GET",
      options: {
        timeoutMs: 8000,
        logBody: false,
        logHeaders: true,
        logQueryValues: true,
        excludePatterns: [/api_key/i],
        excludeMode: "redact",
        metadata: { integration: "unwrangle" },
      },
    });

    if (!res.ok) {
      const errText = await res.text();
      throw new Error(`${helperName}: HTTP ${res.status} — ${errText}`);
    }

    const data = await res.json();
    logger.log(
      "unwrangle_api_success",
      {
        name: helperName,
        url,
        status: res.status,
        duration_ms: Date.now() - startTime,
      },
      "info"
    );

    return data;
  } catch (err) {
    logger.log(
      "unwrangle_api_error",
      {
        name: helperName,
        url,
        message: err.message,
        duration_ms: Date.now() - startTime,
      },
      "error"
    );
    throw err;
  }
}

/**
 * 🔍 Searches for items across platforms (e.g., Home Depot, Lowe’s, Walmart)
 * @param {string} platform - The retail platform to query (e.g., "homedepot", "lowes")
 * @param {string} text - The search text or keywords
 */
async function search(platform, text) {
  const url = buildQueryUrl({
    platform: `${platform}_search`,
    search: text,
  });
  return callAPI(url);
}

/**
 * 🛒 Retrieves a detailed product page for a specific item.
 * @param {string} item_id - The item identifier
 * @param {string} retailer - The retailer name (e.g., "homedepot", "lowes")
 */
async function getProductPage(item_id, retailer) {
  const url = buildQueryUrl({
    platform: `${retailer}_detail`,
    item_id,
  });
  return callAPI(url);
}

/**
 * Initializes the Unwrangle helper functions globally.
 * Makes the helper available as `_unwrangle` in the runtime context.
 */
async function execute_process() {
  global._unwrangle = {
    search,
    getProductPage,
  };
}

4️⃣ Helper Function Requirements

🧱 execute_process()

• Must initialize and register the integration globally under _integrationName.
  Example: _unwrangle, _shopify, _zendesk.
• Should only register reusable functions, not org-specific operations.

⚙️ Function Standards

5️⃣ Core vs. Org-Specific Integration Points

❗

Only universal helpers and base utilities belong to the integration’s tagged set (set:integration_<name>).
Organization-specific logic should live in separate operator or task-level code points.

6️⃣ Tagging Convention

Each integration helper and any shared base point must include a tag identifying its integration set.

set:integration_<integration_name>

Examples:

• set:integration_unwrangle
• set:integration_zendesk
• set:integration_shopify

This ensures the integration can be easily discovered, filtered, and deployed consistently.

7️⃣ Documentation Requirements

Every integration must include a supporting documentation file written in markdown that:

• Describes the integration’s purpose and dependencies.
• Lists each code point, helper, or base value included in the set.
• Explains how to configure environment variables and credentials.
• Includes examples for each helper function and key use cases.

Once completed, documentation must be:

1. Submitted to Platform Leads for review and approval.

const results = await _unwrangle.search("homedepot", "cordless drill");

const product = await _unwrangle.getProductPage("1005127722", "homedepot");

🧠 Summary

Integration points define how MelodyArc connects to external systems.
They must be modular, reusable, and consistently structured.

✅ One helper function point per integration.
✅ Use _fetch for all API calls.
✅ Keep org-specific logic separate.
✅ Register helpers globally.
✅ Tag with set:integration_<integration_name>.
✅ Include version value point and reviewed documentation.

Following these standards ensures integrations are consistent, traceable, and maintainable across all organizations and environments.

Maintained by: MelodyArc Platform Engineering
Version: 1.1