Creating a Dropbox Integration Workflow

data-slots=heading, code

data-repeat=1

data-languages=JSON

package.json

{
  "name": "tutorial-node-express-api",
  "version": "1.0.0",
  "type": "module", // 👈 allows the use of JS modules (import syntax)
  "description": "Sample code for a Node-based Express API tutorial",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node index.js" // 👈 to run the script
  },
  "author": "Davide Barranca",
  "license": "ISC",
  "dependencies": {
    "dotenv": "^16.4.7",
    "dropbox": "^10.34.0",
    "papaparse": "^5.5.2"
  }
}

data-slots=heading, code

data-repeat=1

data-languages=bash

.env

EXPRESS_API_KEY="your_express_api_key"
EXPRESS_API_TOKEN="your_very_long_express_api_token_here"
DROPBOX_ACCESS_TOKEN="your_very_long_dropbox_access_token_here"

data-slots=heading, code

data-repeat=1

data-languages=javascript

index.js

async function main() {
  try {
    console.log("Main function starting...");
  } catch (error) {
    console.error("Ouch!", error);
  }
}

main();

data-slots=heading, code

data-repeat=1

data-languages=javascript

utils/helpers.js

/**
 * Creates a promise that resolves after the specified time
 * Used to introduce delays in the code for waiting between API calls
 *
 * @param {number} ms - Time to sleep in milliseconds
 */
export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * Verifies that a template has all required tags
 * This is important to ensure the template can be used for generating variations
 *
 * @param {Object} tagDetails - The tag details object from the Express API
 * @param {Array<string>} requiredTags - Array of required tag names
 * @returns {Array<string>} Array of tag names found in the template
 * @throws {Error} If no tagged elements are found or if a required tag is missing
 */
export const verifyTemplateTags = (tagDetails, requiredTags) => {
  /* ... */
};

/**
 * Checks the status of multiple Express API jobs
 * This function allows checking multiple job statuses in parallel
 *
 * @param {Array} jobIds - Array of job IDs to check
 * @param {Function} getStatusFn - Function to get job status
 * @returns {Promise<Array>} Array of job status objects
 *
 * @example
 * // Check status of variation jobs
 * const statuses = await checkExpressJobs(variationJobIds, getExpressStatus);
 */
export const checkExpressJobs = async (jobIds, getStatusFn) => {
  /* ... */
};

/**
 * Checks the status of multiple Dropbox jobs
 * This function enhances job status objects with helpful flags
 *
 * @param {Array} dropboxJobs - Array of objects containing asyncJobId and teacherName
 * @param {Function} checkStatusFn - Function to check job status
 * @returns {Promise<Array>} Array of job status objects with original job info
 *
 * @example
 * // Check status of Dropbox upload jobs
 * const jobStatuses = await checkDropboxJobs(asyncJobs, checkDropboxStatus);
 *
 * // Use the helpful flags
 * const completedJobs = jobStatuses.filter(job => job.isComplete);
 * const failedJobs = jobStatuses.filter(job => job.isFailed);
 * const inProgressJobs = jobStatuses.filter(job => job.isInProgress);
 */
export const checkDropboxJobs = async (dropboxJobs, checkStatusFn) => {
  /* ... */
};

data-slots=heading, code

data-repeat=1

data-languages=javascript

services/dropbox.js

import dotenv from "dotenv";
import { Dropbox } from "dropbox";
import Papa from "papaparse";

dotenv.config(); // loads .env
const dbx = new Dropbox({ accessToken: process.env.DROPBOX_ACCESS_TOKEN });

/**
 * Lists files and folders in a Dropbox directory
 *
 * @param {string} path - The path to list contents of
 * @returns {Promise<Array|undefined>} Array of file and folder entries or undefined on error
 */
export async function listDropboxFiles(path = "") {
  /* ... */
}

/**
 * Gets a pre-signed URL for a file in Dropbox
 * This is useful for accessing files temporarily without authentication
 *
 * @param {string} path - The path to the file in Dropbox
 * @returns {Promise<string|undefined>} The pre-signed URL or undefined on error
 */
export async function getPreSignedUrl(path) {
  /* ... */
}

/**
 * Creates a folder at the specified path in Dropbox
 * If the folder already exists, it returns success
 *
 * @param {string} path - The path where the folder should be created
 * @returns {Promise<Object>} The result of the folder creation
 */
export async function createFolder(path) {
  /* ... */
}

/**
 * Reads a CSV file from Dropbox and parses it into an array of objects
 * Used in index.js to read teacher data from HR.csv
 *
 * @param {string} path - The path to the CSV file in Dropbox
 * @returns {Promise<Array<Object>|undefined>} Array of objects representing CSV rows, or undefined on error
 */
export async function readCsvFile(path) {
  /* ... */
}

/**
 * Saves a URL to Dropbox
 * This initiates a server-side download of the URL content to Dropbox
 *
 * @param {string} url - The URL to download
 * @param {string} path - The path where to save the file in Dropbox
 * @returns {Promise<Object>} The result, which may contain an async job ID
 */
export async function saveUrlToDropbox(url, path) {
  /* ... */
}

/**
 * Checks the status of an async Dropbox job
 * Used to monitor the progress of saveUrlToDropbox operations
 *
 * @param {string} asyncJobId - The ID of the async job to check
 * @returns {Promise<Object>} The job status
 */
export async function checkDropboxStatus(asyncJobId) {
  /* ... */
}

/**
 * Alternative upload method that downloads a file and uploads it directly to Dropbox
 * This avoids using the async saveUrlToDropbox method and provides more direct control
 * Used in index.js as a fallback when saveUrlToDropbox is not suitable
 */
export async function downloadAndUploadFile(url, dropboxPath) {
  /* ... */
}

data-slots=heading, code

data-repeat=1

data-languages=javascript

index.js

import { listDropboxFiles, readCsvFile } from "./services/dropbox.js";
async function main() {
  try {
    // Fetch + log the CSV file with the teachers' data          👈
    const teachers = await readCsvFile("/HR.csv");
    console.log(teachers);

    // Fetch + log the list of files in the /pictures folder     👈
    const dropboxPictures = await listDropboxFiles("/pictures");
    console.log(dropboxPictures);
  } catch (error) {
    console.error("Ouch!", error);
  }
}

main();

data-slots=heading, code

data-repeat=1

data-languages=javascript

services/express-api.js

import dotenv from "dotenv";
dotenv.config();

// Uncomment this line if you're using Node.js v16 or earlier
// import fetch from "node-fetch";

const API_KEY = process.env.EXPRESS_API_KEY || "";
const EXPRESS_API_TOKEN = process.env.EXPRESS_API_TOKEN;
const EXPRESS_ENDPOINT = "https://express-api.adobe.io";

const headers = {
  "X-API-KEY": API_KEY,
  Authorization: `Bearer ${EXPRESS_API_TOKEN}`,
  "Content-Type": "application/json", // often needed for POST requests
};

/**
 * Gets the status of an Express API job
 * Used to monitor the progress of variation and export jobs
 *
 * @param {string} jobId - The ID of the job to check
 * @returns {Promise<Object>} The job status object
 */
export async function getExpressStatus(jobId) {
  /* ... */
}

/**
 * Exports a rendition of a document
 * This creates a downloadable version of the document
 *
 * @param {Object} requestBody - The export request parameters
 * @param {string} requestBody.id - The document ID to export
 * @param {string} requestBody.pages - The pages to export (e.g., "1")
 * @param {Object} requestBody.options - Export options like format and size (or PDF settings)
 * @returns {Promise<Object>} The export job information
 */
export async function exportRendition(requestBody) {
  /* ... */
}

/**
 * Generates variations of a document using tag mappings
 * This creates a new document with the specified tag values
 *
 * @param {Object} requestBody - The variation request parameters
 * @param {string} requestBody.id - The template document ID
 * @param {Object} requestBody.variationDetails - Details for the variation
 * @param {Object} requestBody.variationDetails.tagMappings - Values for each tag
 * @param {String} requestBody.variationDetails.pages - The pages to export (e.g., "1")
 * @param {String} requestBody.variationDetails.preferredDocumentName - The name of the document to save
 * @returns {Promise<Object>} The variation job information
 */
export async function generateVariations(requestBody) {
  /* ... */
}

/**
 * Retrieves tag details for a document
 * Used to verify that a template has the required tags
 *
 * @param {string} documentId - The ID of the document to check
 * @param {Object} queryParams - Additional query parameters
 * @returns {Promise<Object>} The document tag details
 */
export async function retrieveTagDetails(
  documentId,
  queryParams = { start: "1" }
) {
  /* ... */
}

data-slots=heading, code

data-repeat=1

data-languages=javascript

index.js

import { readCsvFile } from "./services/dropbox.js";
import { retrieveTagDetails } from "./services/express-api.js";
import { verifyTemplateTags } from "./utils/helpers.js";

// Constants for easier reference
const DOCUMENT_ID = "urn:aaid:sc:EU:cd9a3037-6583-56c4-b3e9-f393d95d43b9";
const TAGS = ["Picture", "Name", "Role", "Phone", "Email"];

async function main() {
  try {
    // STEP 1: Read teacher data from CSV file in Dropbox
    // ...
    // STEP 2: Verify that the Express template has all required tags
    console.log("Retrieving tag details from Express API:");
    const tagDetails = await retrieveTagDetails(DOCUMENT_ID);

    // Use the utility function to verify template tags
    const taggedElements = verifyTemplateTags(tagDetails, TAGS);
    console.log("Tagged elements are OK:", taggedElements);
  } catch (error) {
    console.error("Ouch!", error);
  }
}

data-slots=heading, code

data-repeat=1

data-languages=javascript

index.js

import { readCsvFile, getPreSignedUrl } from "./services/dropbox.js";
import {
  getExpressStatus,
  generateVariations,
  retrieveTagDetails,
} from "./services/express-api.js";
import {
  sleep,
  verifyTemplateTags,
  checkExpressJobs,
} from "./utils/helpers.js";

// Configuration
const DOCUMENT_ID = "urn:aaid:sc:EU:6e1f27db-4202-543d-83d8-2b9583a3865e";
const TAGS = ["Picture", "Name", "Role", "Phone", "Email"];

// Configuration for Dropbox API methods
const STATUS_CHECK_INTERVAL = 3000; // Time between status checks in milliseconds

async function main() {
  try {
    // STEP 1: Read teacher data from CSV file in Dropbox
    // ...
    // STEP 2: Verify that the Express template has all required tags
    // ...
    // STEP 3: Generate variations for each teacher
    console.log("Generating variations for each teacher...");
    let variationJobIds = [];
    let teacherNames = []; // Store names to use for file naming later

    // Iterate over the teachers and generate a variation for each one
    for (const teacher of teachers) {
      const { Name, Role, Phone, Email, Picture } = teacher;
      teacherNames.push(Name);

      // Get the teacher's profile picture
      const pictureURL = await getPreSignedUrl(`/pictures/${Picture}.jpg`);

      const variationResponse = await generateVariations({
        id: DOCUMENT_ID,
        variationDetails: {
          pages: "1",
          preferredDocumentName: `Business Card - ${Name}`,
          tagMappings: {
            Picture: pictureURL,
            Name,
            Role,
            Phone,
            Email,
          },
        },
      });

      // Collect the Job ID
      variationJobIds.push(variationResponse.jobId);
      console.log(
        `Submitted variation job for ${Name}, job ID: ${variationResponse.jobId}`
      );
    }
  } catch (error) {
    console.error("Error in main():", error);
  }
}

data-slots=heading, code

data-repeat=1

data-languages=javascript

index.js

// ...
async function main() {
  try {
    // STEP 1: Read teacher data from CSV file in Dropbox
    // ...
    // STEP 2: Verify that the Express template has all required tags
    // ...
    // STEP 3: Generate variations for each teacher
    // ...
    // STEP 4: Wait for all variation jobs to complete
    console.log("Checking variation job statuses...");
    let generationStatuses = await checkExpressJobs(
      variationJobIds,
      getExpressStatus
    );
    let runningCount = generationStatuses.filter(
      ({ status }) => status === "running"
    ).length;

    while (runningCount > 0) {
      console.log(`Waiting for ${runningCount} variation jobs to complete...`);
      await sleep(STATUS_CHECK_INTERVAL);
      generationStatuses = await checkExpressJobs(
        variationJobIds,
        getExpressStatus
      );
      runningCount = generationStatuses.filter(
        ({ status }) => status === "running"
      ).length;
    }

    console.log("All variation jobs completed!");

    // Check for any failed jobs
    const failedJobs = generationStatuses.filter(
      ({ status }) => status !== "succeeded"
    );
    if (failedJobs.length > 0) {
      console.warn(
        `Warning: ${failedJobs.length} variation jobs failed:`,
        failedJobs.map((status) => status.jobId)
      );
    }
  } catch (error) {
    console.error("Error in main():", error);
  }
}

data-slots=heading, code

data-repeat=4

data-languages=index.js, services/express.js, services/dropbox.js, utils/helpers.js

index.js

import {
  readCsvFile,
  getPreSignedUrl,
  saveUrlToDropbox,
  checkDropboxStatus,
  createFolder,
  downloadAndUploadFile,
} from "./services/dropbox.js";
import {
  getExpressStatus,
  exportRendition,
  generateVariations,
  retrieveTagDetails,
} from "./services/express-api.js";
import {
  sleep,
  verifyTemplateTags,
  checkExpressJobs,
  checkDropboxJobs,
} from "./utils/helpers.js";

// Configuration
const DOCUMENT_ID = "urn:aaid:sc:EU:6e1f27db-4202-543d-83d8-2b9583a3865e";
const TAGS = ["Picture", "Name", "Role", "Phone", "Email"];
const OUTPUT_FOLDER = "/Business Cards"; // Dropbox folder to save exported files

// Configuration for Dropbox API methods
const MAX_RETRIES = 3; // Number of retries for failed uploads
const STATUS_CHECK_INTERVAL = 3000; // Time between status checks in milliseconds
const INITIAL_WAIT_TIME = 10000; // Wait 5 seconds before starting Dropbox uploads

async function main() {
  try {
    // STEP 1: Read teacher data from CSV file in Dropbox
    console.log("Reading CSV file from Dropbox /HR.csv:");
    const teachers = await readCsvFile("/HR.csv");

    if (!teachers || !Array.isArray(teachers)) {
      throw new Error("Failed to read teachers from CSV or invalid format");
    }

    console.log(`Found ${teachers.length} records in CSV file`);

    // STEP 2: Verify that the Express template has all required tags
    console.log("Retrieving tag details from Express API:");
    const tagDetails = await retrieveTagDetails(DOCUMENT_ID);

    // Use the utility function to verify template tags
    const taggedElements = verifyTemplateTags(tagDetails, TAGS);
    console.log("Tagged elements are OK:", taggedElements);

    // STEP 3: Generate variations for each teacher
    console.log("Generating variations for each teacher...");
    let variationJobIds = [];
    let teacherNames = []; // Store names to use for file naming later

    // Iterate over the teachers and generate a variation for each one
    for (const teacher of teachers) {
      const { Name, Role, Phone, Email, Picture } = teacher;
      teacherNames.push(Name);

      const pictureURL = await getPreSignedUrl(`/pictures/${Picture}.jpg`);

      const variationResponse = await generateVariations({
        id: DOCUMENT_ID,
        variationDetails: {
          pages: "1",
          preferredDocumentName: `Business Card - ${Name}`,
          tagMappings: {
            Picture: pictureURL,
            Name,
            Role,
            Phone,
            Email,
          },
        },
      });

      // Collect the Job ID
      variationJobIds.push(variationResponse.jobId);
      console.log(
        `Submitted variation job for ${Name}, job ID: ${variationResponse.jobId}`
      );
    }

    // STEP 4: Wait for all variation jobs to complete
    console.log("Checking variation job statuses...");
    let generationStatuses = await checkExpressJobs(
      variationJobIds,
      getExpressStatus
    );
    let runningCount = generationStatuses.filter(
      ({ status }) => status === "running"
    ).length;

    while (runningCount > 0) {
      console.log(`Waiting for ${runningCount} variation jobs to complete...`);
      await sleep(STATUS_CHECK_INTERVAL);
      generationStatuses = await checkExpressJobs(
        variationJobIds,
        getExpressStatus
      );
      runningCount = generationStatuses.filter(
        ({ status }) => status === "running"
      ).length;
    }

    console.log("All variation jobs completed!");

    // Check for any failed jobs
    const failedJobs = generationStatuses.filter(
      ({ status }) => status !== "succeeded"
    );
    if (failedJobs.length > 0) {
      console.warn(
        `Warning: ${failedJobs.length} variation jobs failed:`,
        failedJobs.map((status) => status.jobId)
      );
    }
    // waiting before starting exports
    console.log(
      `Waiting ${
        INITIAL_WAIT_TIME / 1000
      } seconds before starting Exportation to ensure URLs are fully ready...`
    );
    await sleep(INITIAL_WAIT_TIME);

    // STEP 5: Export renditions for successful variations
    let exportationJobIds = [];
    let documentIds = []; // Store document IDs to match with teacher names

    console.log("Starting export jobs for successful variations...");
    for (let i = 0; i < generationStatuses.length; i++) {
      const status = generationStatuses[i];
      if (status.status !== "succeeded") {
        console.error(`Generation job failed for ${teacherNames[i]}:`, status);
        continue;
      }

      const exportResponse = await exportRendition({
        id: status.document.id,
        pages: "1",
        options: {
          format: "image/png",
          size: 1000,
        },
      });

      exportationJobIds.push(exportResponse.jobId);
      documentIds.push({
        jobId: exportResponse.jobId,
        teacherName: teacherNames[i],
        documentId: status.document.id,
      });

      console.log(
        `Submitted export job for ${teacherNames[i]}, job ID: ${exportResponse.jobId}`
      );
    }

    // STEP 6: Wait for all export jobs to complete
    console.log("Checking export job statuses...");
    let exportationStatuses = await checkExpressJobs(
      exportationJobIds,
      getExpressStatus
    );
    runningCount = exportationStatuses.filter(
      ({ status }) => status === "running"
    ).length;

    while (runningCount > 0) {
      console.log(`Waiting for ${runningCount} export jobs to complete...`);
      await sleep(STATUS_CHECK_INTERVAL);
      exportationStatuses = await checkExpressJobs(
        exportationJobIds,
        getExpressStatus
      );
      runningCount = exportationStatuses.filter(
        ({ status }) => status === "running"
      ).length;
    }

    console.log("All export jobs completed!");

    // Check for any failed export jobs
    const failedExports = exportationStatuses.filter(
      ({ status }) => status !== "succeeded"
    );
    if (failedExports.length > 0) {
      console.warn(
        `Warning: ${failedExports.length} export jobs failed:`,
        failedExports.map((status) => status.jobId)
      );
    }

    // STEP 7: Get rendition URLs for successful exports
    const renditionUrls = [];
    for (let i = 0; i < exportationStatuses.length; i++) {
      const status = exportationStatuses[i];
      if (
        status.status === "succeeded" &&
        status.pageRenditionsResult &&
        status.pageRenditionsResult.length > 0
      ) {
        const teacherInfo = documentIds.find(
          (doc) => doc.jobId === status.jobId
        );
        renditionUrls.push({
          url: status.pageRenditionsResult[0].renditionUrl,
          teacherName: teacherInfo ? teacherInfo.teacherName : `unknown-${i}`,
          jobId: status.jobId,
        });
      }
    }

    console.log(
      `Got ${renditionUrls.length} rendition URLs to upload to Dropbox`
    );

    // STEP 8: Wait before starting uploads to ensure URLs are ready
    console.log(
      `Waiting ${
        INITIAL_WAIT_TIME / 1000
      } seconds before starting uploads to ensure URLs are fully ready...`
    );
    await sleep(INITIAL_WAIT_TIME);
    console.log("Wait complete, starting upload process...");

    // STEP 9: Create Dropbox folder for uploads if it doesn't exist
    try {
      console.log(`Ensuring output folder exists: ${OUTPUT_FOLDER}`);
      const folderResult = await createFolder(OUTPUT_FOLDER);
      console.log(
        `Folder created or already exists at: ${folderResult.path_lower}`
      );
    } catch (error) {
      console.warn(`Warning: Could not create output folder: ${error.message}`);
      // Continue anyway
    }

    // STEP 10: Upload renditions to Dropbox
    console.log("Uploading renditions to Dropbox...");
    console.log(`Total renditions to upload: ${renditionUrls.length}`);

    const uploadPromises = renditionUrls.map(async (rendition) => {
      const { url, teacherName } = rendition;
      const dropboxPath = `${OUTPUT_FOLDER}/${teacherName}.png`;

      try {
        console.log(`Starting upload for ${teacherName}...`);
        const saveResult = await saveUrlToDropbox(url, dropboxPath);
        console.log(
          `Upload initiated for ${teacherName}, result type: ${
            saveResult[".tag"] || "unknown"
          }`
        );
        return {
          teacherName,
          path: dropboxPath,
          result: saveResult,
          jobId: rendition.jobId,
          url: rendition.url,
        };
      } catch (error) {
        console.error(
          `Failed to upload ${teacherName}'s business card:`,
          error.message || error
        );
        return {
          teacherName,
          error,
          jobId: rendition.jobId,
          url: rendition.url,
        };
      }
    });

    const allInitialResults = await Promise.all(uploadPromises);

    // STEP 11: Monitor async Dropbox jobs until completion
    // Filter out async jobs that need to be monitored
    let asyncJobs = [];
    for (const result of allInitialResults) {
      if (
        result.result &&
        typeof result.result === "object" &&
        ".tag" in result.result &&
        result.result[".tag"] === "async_job_id" &&
        "async_job_id" in result.result
      ) {
        asyncJobs.push({
          asyncJobId: result.result.async_job_id,
          teacherName: result.teacherName,
          path: result.path,
          originalJobId: result.jobId,
          url: result.url,
          retryCount: 0,
        });
      }
    }

    if (asyncJobs.length > 0) {
      console.log(
        `Monitoring ${asyncJobs.length} async Dropbox upload jobs...`
      );

      // Using the simplified checkDropboxJobs function for job monitoring
      let allJobsComplete = false;
      let retryCount = 0;

      while (!allJobsComplete && retryCount < MAX_RETRIES) {
        // Check all job statuses at once
        const jobStatuses = await checkDropboxJobs(
          asyncJobs,
          checkDropboxStatus
        );

        // Log the current status of each job
        jobStatuses.forEach((job) => {
          console.log(
            `Job for ${job.teacherName}: ${
              job.isComplete
                ? "Complete"
                : job.isFailed
                ? "Failed"
                : "In Progress"
            }`
          );
        });

        // Check if any jobs are still in progress
        const inProgressJobs = jobStatuses.filter((job) => job.isInProgress);

        if (inProgressJobs.length > 0) {
          console.log(
            `Still waiting for ${inProgressJobs.length} uploads to complete...`
          );
          // Wait before checking again
          await sleep(STATUS_CHECK_INTERVAL);
        } else {
          // All jobs are either complete or failed
          allJobsComplete = true;

          // Log the final results
          const successfulUploads = jobStatuses.filter((job) => job.isComplete);
          const failedUploads = jobStatuses.filter((job) => job.isFailed);

          console.log(
            `Upload results: ${successfulUploads.length} successful, ${failedUploads.length} failed`
          );

          if (failedUploads.length > 0 && retryCount < MAX_RETRIES - 1) {
            console.log(`Retrying ${failedUploads.length} failed uploads...`);
            retryCount++;

            // Update asyncJobs with only the failed jobs for retry
            asyncJobs = failedUploads.map((job) => ({
              ...job,
              retryCount: (job.retryCount || 0) + 1,
            }));

            allJobsComplete = false; // Continue the loop for retries
          } else if (failedUploads.length > 0) {
            console.warn(
              "Failed uploads after maximum retries:",
              failedUploads.map((job) => job.teacherName)
            );

            // STEP 11.5: Try alternative direct upload method for failed jobs
            console.log(
              `Attempting direct upload method for ${failedUploads.length} failed jobs...`
            );

            const directUploadPromises = failedUploads.map(async (job) => {
              try {
                console.log(`Starting direct upload for ${job.teacherName}...`);
                const result = await downloadAndUploadFile(
                  job.url,
                  job.path || `${OUTPUT_FOLDER}/${job.teacherName}.png`
                );
                console.log(`Direct upload successful for ${job.teacherName}`);
                return {
                  ...job,
                  directUploadSuccess: true,
                  directUploadResult: result,
                };
              } catch (error) {
                console.error(
                  `Direct upload failed for ${job.teacherName}:`,
                  error.message || error
                );
                return {
                  ...job,
                  directUploadSuccess: false,
                  directUploadError: error,
                };
              }
            });

            const directUploadResults = await Promise.all(directUploadPromises);

            // Log the results of direct uploads
            const successfulDirectUploads = directUploadResults.filter(
              (job) => job.directUploadSuccess
            );
            console.log(
              `Direct upload results: ${
                successfulDirectUploads.length
              } successful, ${
                directUploadResults.length - successfulDirectUploads.length
              } failed`
            );

            if (successfulDirectUploads.length > 0) {
              console.log(
                `Successfully uploaded ${successfulDirectUploads.length} files using direct upload method`
              );
            }

            if (successfulDirectUploads.length < directUploadResults.length) {
              console.error(
                `Failed to upload ${
                  directUploadResults.length - successfulDirectUploads.length
                } files even with direct upload method`
              );
            }
          }
        }
      }
    } else {
      console.log("No async jobs to monitor");
    }

    // STEP 12: Process completed
    console.log("Process completed!");
    console.log(
      `Generated and uploaded business cards to Dropbox folder: ${OUTPUT_FOLDER}`
    );
  } catch (error) {
    console.error("Error in main():", error);
  }
}

// Run the main function
main();

services/express.js

/**
 * Express API Service
 *
 * This file contains functions for interacting with the Adobe Express API.
 * It handles operations like generating variations, exporting renditions,
 * and checking job statuses.
 */

import dotenv from "dotenv";
dotenv.config();

import fetch from "node-fetch"; // or rely on Node 18+ global if you prefer

const API_KEY = process.env.EXPRESS_API_KEY || "";
const EXPRESS_API_TOKEN = process.env.EXPRESS_API_TOKEN;
const EXPRESS_ENDPOINT = "https://express-api.adobe.io";

const headers = {
  "X-API-KEY": API_KEY,
  Authorization: `Bearer ${EXPRESS_API_TOKEN}`,
  "Content-Type": "application/json", // often needed for POST requests
};

/**
 * Gets the status of an Express API job
 * Used to monitor the progress of variation and export jobs
 *
 * @param {string} jobId - The ID of the job to check
 * @returns {Promise<Object>} The job status object
 */
export async function getExpressStatus(jobId) {
  const resp = await fetch(`${EXPRESS_ENDPOINT}/status/${jobId}`, {
    method: "GET",
    headers,
  });
  const data = await resp.json();
  return data;
}

/**
 * Exports a rendition of a document
 * This creates a downloadable version of the document
 *
 * @param {Object} requestBody - The export request parameters
 * @param {string} requestBody.id - The document ID to export
 * @param {string} requestBody.pages - The pages to export (e.g., "1")
 * @param {Object} requestBody.options - Export options like format and size
 * @returns {Promise<Object>} The export job information
 */
export async function exportRendition(requestBody) {
  const resp = await fetch(`${EXPRESS_ENDPOINT}/beta/export-rendition`, {
    method: "POST",
    headers,
    body: JSON.stringify(requestBody),
  });
  const data = await resp.json();
  return data;
}

/**
 * Generates variations of a document using tag mappings
 * This creates a new document with the specified tag values
 *
 * @param {Object} requestBody - The variation request parameters
 * @param {string} requestBody.id - The template document ID
 * @param {Object} requestBody.variationDetails - Details for the variation
 * @param {Object} requestBody.variationDetails.tagMappings - Values for each tag
 * @param {String} requestBody.variationDetails.pages - The pages to export (e.g., "1")
 * @param {String} requestBody.variationDetails.preferredDocumentName - The name of the document to save
 * @returns {Promise<Object>} The variation job information
 */
export async function generateVariations(requestBody) {
  const resp = await fetch(`${EXPRESS_ENDPOINT}/beta/generate-variation`, {
    method: "POST",
    headers,
    body: JSON.stringify(requestBody),
  });
  const data = await resp.json();
  return data;
}

/**
 * Retrieves tag details for a document
 * Used to verify that a template has the required tags
 *
 * @param {string} documentId - The ID of the document to check
 * @param {Object} queryParams - Additional query parameters
 * @returns {Promise<Object>} The document tag details
 */
export async function retrieveTagDetails(
  documentId,
  queryParams = { start: "1" }
) {
  const queryString = new URLSearchParams(queryParams).toString();
  const resp = await fetch(
    `${EXPRESS_ENDPOINT}/beta/tagged-documents/${documentId}?${queryString}`,
    {
      method: "GET",
      headers,
    }
  );
  const data = await resp.json();
  return data;
}

services/dropbox.js

/**
 * Dropbox API Service
 *
 * This file contains functions for interacting with the Dropbox API.
 * It handles operations like reading files, creating folders, and uploading content.
 */

import dotenv from "dotenv";
import { Dropbox } from "dropbox";
import Papa from "papaparse";

dotenv.config(); // loads .env
const dbx = new Dropbox({ accessToken: process.env.DROPBOX_ACCESS_TOKEN });

/**
 * Lists files and folders in a Dropbox directory
 *
 * @param {string} path - The path to list contents of
 * @returns {Promise<Array|undefined>} Array of file and folder entries or undefined on error
 */
export async function listDropboxFiles(path = "") {
  try {
    const response = await dbx.filesListFolder({ path });
    return response.result.entries;
  } catch (error) {
    console.error("Error listing files:", error?.error || error);
    return undefined;
  }
}

/**
 * Gets a pre-signed URL for a file in Dropbox
 * This is useful for accessing files temporarily without authentication
 *
 * @param {string} path - The path to the file in Dropbox
 * @returns {Promise<string|undefined>} The pre-signed URL or undefined on error
 */
export async function getPreSignedUrl(path) {
  try {
    const response = await dbx.filesGetTemporaryLink({ path });
    // console.log("Pre-signed URL:", response);
    return response.result.link;
  } catch (error) {
    console.error("Error getting pre-signed URL:", error?.error || error);
    return undefined;
  }
}

/**
 * Creates a folder at the specified path in Dropbox
 * If the folder already exists, it returns success
 *
 * @param {string} path - The path where the folder should be created
 * @returns {Promise<Object>} The result of the folder creation
 */
export async function createFolder(path) {
  try {
    const response = await dbx.filesCreateFolderV2({
      path,
      autorename: false,
    });
    return response.result;
  } catch (error) {
    // If the folder already exists, just return success
    if (
      error?.error?.error?.[".tag"] === "path" &&
      error?.error?.error?.path?.[".tag"] === "conflict"
    ) {
      console.log(`Folder at path ${path} already exists`);
      return { success: true, path_lower: path };
    }
    console.error("Error creating folder:", error?.error || error);
    throw error;
  }
}

/**
 * Reads a CSV file from Dropbox and parses it into an array of objects
 * Used in index.js to read teacher data from HR.csv
 *
 * @param {string} path - The path to the CSV file in Dropbox
 * @returns {Promise<Array<Object>|undefined>} Array of objects representing CSV rows, or undefined on error
 */
export async function readCsvFile(path) {
  try {
    const response = await dbx.filesDownload({ path });
    const buffer = Buffer.from(response.result.fileBinary);
    const csvText = buffer.toString("utf8");

    const parsed = Papa.parse(csvText, { header: true });
    return parsed.data;
  } catch (error) {
    console.error("Error reading CSV file:", error?.error || error);
  }
}

/**
 * Saves a URL to Dropbox
 * This initiates a server-side download of the URL content to Dropbox
 *
 * @param {string} url - The URL to download
 * @param {string} path - The path where to save the file in Dropbox
 * @returns {Promise<Object>} The result, which may contain an async job ID
 */
export async function saveUrlToDropbox(url, path) {
  try {
    const response = await dbx.filesSaveUrl({
      url,
      path,
    });
    // Return the result, which contains the async job ID and other details
    return response.result;
  } catch (error) {
    console.error("Error saving URL to Dropbox:", error);
    throw error;
  }
}

/**
 * Checks the status of an async Dropbox job
 * Used to monitor the progress of saveUrlToDropbox operations
 *
 * @param {string} asyncJobId - The ID of the async job to check
 * @returns {Promise<Object>} The job status
 */
export async function checkDropboxStatus(asyncJobId) {
  try {
    console.log(`Checking status for job ID: ${asyncJobId}`);
    const response = await dbx.filesSaveUrlCheckJobStatus({
      async_job_id: asyncJobId,
    });

    // Log the full response for debugging
    console.log(`Raw job status response: ${JSON.stringify(response)}`);

    // If the job failed, try to get more details
    if (response.result && response.result[".tag"] === "failed") {
      console.error(`Job ${asyncJobId} failed:`, response.result);
    }

    return response.result;
  } catch (error) {
    console.error(`Error checking job status for ${asyncJobId}:`, error);
    throw error;
  }
}

/**
 * Alternative upload method that downloads a file and uploads it directly to Dropbox
 * This avoids using the async saveUrlToDropbox method and provides more direct control
 * Used in index.js as a fallback when saveUrlToDropbox is not suitable
 */
export async function downloadAndUploadFile(url, dropboxPath) {
  try {
    console.log(`Downloading file from ${url.substring(0, 50)}...`);

    // Download the file
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(
        `Failed to download file: ${response.status} ${response.statusText}`
      );
    }

    // Get the file content as an array buffer
    const fileBuffer = await response.arrayBuffer();

    console.log(
      `Downloaded ${fileBuffer.byteLength} bytes, uploading to ${dropboxPath}`
    );

    // Upload the file to Dropbox
    const uploadResponse = await dbx.filesUpload({
      path: dropboxPath,
      contents: Buffer.from(fileBuffer),
      mode: { ".tag": "overwrite" },
    });

    console.log(
      `Direct upload complete: ${JSON.stringify(uploadResponse.result)}`
    );
    return uploadResponse.result;
  } catch (error) {
    console.error(`Error in downloadAndUploadFile:`, error);
    throw error;
  }
}

utils/helpers.js

/**
 * Utility functions for the application
 *
 * This file contains helper functions used throughout the application
 * to handle common tasks like waiting, checking job statuses, and
 * verifying template tags.
 */

/**
 * Creates a promise that resolves after the specified time
 * Used to introduce delays in the code for waiting between API calls
 *
 * @param {number} ms - Time to sleep in milliseconds
 */
export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * Verifies that a template has all required tags
 * This is important to ensure the template can be used for generating variations
 *
 * @param {Object} tagDetails - The tag details object from the Express API
 * @param {Array<string>} requiredTags - Array of required tag names
 * @returns {Array<string>} Array of tag names found in the template
 * @throws {Error} If no tagged elements are found or if a required tag is missing
 */
export const verifyTemplateTags = (tagDetails, requiredTags) => {
  // Extracting only the names of the tagged elements
  const taggedElements = tagDetails?.documentPages[0].taggedElements.map(
    (element) => element.name
  );

  // Check if the tagged elements array is empty
  if (!taggedElements) {
    throw new Error("No tagged elements found in the Template.");
  }

  // Check if the tagged elements array contains all the required tags
  requiredTags.forEach((tag) => {
    if (!taggedElements.includes(tag)) {
      throw new Error(`Missing required tag: ${tag}`);
    }
  });

  return taggedElements;
};

/**
 * Checks the status of multiple Express API jobs
 * This function allows checking multiple job statuses in parallel
 *
 * @param {Array} jobIds - Array of job IDs to check
 * @param {Function} getStatusFn - Function to get job status
 * @returns {Promise<Array>} Array of job status objects
 *
 * @example
 * // Check status of variation jobs
 * const statuses = await checkExpressJobs(variationJobIds, getExpressStatus);
 */
export const checkExpressJobs = async (jobIds, getStatusFn) => {
  const statuses = await Promise.all(jobIds.map((jobId) => getStatusFn(jobId)));
  return statuses;
};

/**
 * Checks the status of multiple Dropbox jobs
 * This function enhances job status objects with helpful flags
 *
 * @param {Array} dropboxJobs - Array of objects containing asyncJobId and teacherName
 * @param {Function} checkStatusFn - Function to check job status
 * @returns {Promise<Array>} Array of job status objects with original job info
 *
 * @example
 * // Check status of Dropbox upload jobs
 * const jobStatuses = await checkDropboxJobs(asyncJobs, checkDropboxStatus);
 *
 * // Use the helpful flags
 * const completedJobs = jobStatuses.filter(job => job.isComplete);
 * const failedJobs = jobStatuses.filter(job => job.isFailed);
 * const inProgressJobs = jobStatuses.filter(job => job.isInProgress);
 */
export const checkDropboxJobs = async (dropboxJobs, checkStatusFn) => {
  const statusPromises = dropboxJobs.map(async (job) => {
    try {
      const status = await checkStatusFn(job.asyncJobId);
      return {
        ...job,
        status,
        // Add helpful flags for easier status checking
        isComplete: status && status[".tag"] === "complete",
        isFailed: status && status[".tag"] === "failed",
        isInProgress: status && status[".tag"] === "in_progress",
      };
    } catch (error) {
      return { ...job, error, isFailed: true };
    }
  });

  return Promise.all(statusPromises);
};