File Handling

/**
 * Downloads files from Drupal and creates local file nodes
 * @param gatsbyApi - Gatsby API functions for node and cache management
 * @param pluginOptions - Plugin configuration including auth and URL settings
 * @returns Promise that resolves when file download is complete
 */
function downloadFile(
  gatsbyApi: {
    node: GatsbyNode;
    cache: Cache;
    createNode: Function;
    createNodeId: Function;
    getCache: Function;
  },
  pluginOptions: {
    basicAuth?: BasicAuth;
    baseUrl: string;
    typePrefix?: string;
  }
): Promise<void>;

// Files are automatically downloaded during the build process
// Access downloaded files in GraphQL queries:

{
  allFile {
    nodes {
      name
      extension
      publicURL
      childImageSharp {
        gatsbyImageData(width: 300)
      }
    }
  }
}

// Access files through content relationships:
{
  allArticle {
    nodes {
      title
      featuredImage {
        localFile {
          childImageSharp {
            gatsbyImageData(width: 800)
          }
        }
      }
    }
  }
}

/**
 * Checks if a node is a file node type
 * @param node - Gatsby node to check
 * @param typePrefix - Optional type prefix for custom naming
 * @returns Boolean indicating if the node represents a file
 */
function isFileNode(node: GatsbyNode, typePrefix?: string): boolean;

/**
 * Generates Gatsby Image CDN fields for image nodes
 * @param options - Configuration for Image CDN field generation
 * @returns Promise resolving to Image CDN fields or empty object
 */
function getGatsbyImageCdnFields(options: {
  node: DrupalEntity;
  type: string;
  pluginOptions: PluginOptions;
  fileNodesExtendedData: Map<string, any>;
  reporter: Reporter;
}): Promise<ImageCDNFields | {}>;

interface ImageCDNFields {
  filename: string;
  url: string;
  placeholderUrl: string;
  width: number;
  height: number;
  mimeType: string;
}

// When Image CDN is enabled, query using the gatsbyImage field:
{
  allFile(filter: { mimeType: { regex: "/image/" } }) {
    nodes {
      gatsbyImage(width: 800, height: 600)
      filename
      url
    }
  }
}

// In React components:
import { GatsbyImage, getImage } from "gatsby-plugin-image";

const MyComponent = ({ data }) => {
  const image = getImage(data.file);
  return <GatsbyImage image={image} alt="Description" />;
};

/**
 * Resolves Drupal file URIs to absolute URLs
 * @param node - File node attributes from Drupal
 * @param baseUrl - Base URL of the Drupal site
 * @returns URL object with resolved file location
 */
function getFileUrl(node: FileAttributes, baseUrl: string): URL;

interface FileAttributes {
  url?: string;
  uri?: string | { url: string; value: string };
}

interface ImageCDNState {
  foundPlaceholderStyle: boolean;
  hasLoggedNoPlaceholderStyle: boolean;
}

/**
 * Global state tracking for Image CDN placeholder discovery
 */
const imageCDNState: ImageCDNState;

// Configure placeholder style in plugin options:
{
  resolve: `gatsby-source-drupal`,
  options: {
    baseUrl: `https://your-site.com/`,
    skipFileDownloads: true,
    imageCDN: true,
    placeholderStyleName: 'placeholder', // Default
    // Or use custom style:
    // placeholderStyleName: 'custom_placeholder',
  },
}

interface FileAuthOptions {
  htaccess_user?: string;
  htaccess_pass?: string;
}

{
  resolve: `gatsby-source-drupal`,
  options: {
    baseUrl: `https://protected-site.com/`,
    basicAuth: {
      username: process.env.BASIC_AUTH_USERNAME,
      password: process.env.BASIC_AUTH_PASSWORD,
    },
    // Files in public://, private://, temporary:// will use basic auth
  },
}

{
  resolve: `gatsby-source-drupal`,
  options: {
    baseUrl: `https://your-site.com/`,
    skipFileDownloads: true, // Required for Image CDN
    imageCDN: true, // Default, but can be explicit
  },
}

// Extended file data extracted from relationships:
{
  width: 1920,
  height: 1080,
  imageDerivatives: {
    links: {
      placeholder: { href: "/files/styles/placeholder/image.jpg" },
      thumbnail: { href: "/files/styles/thumbnail/image.jpg" },
      large: { href: "/files/styles/large/image.jpg" }
    }
  }
}

// 404 errors are handled gracefully with limited warnings
if (e.message.includes('404') && four04WarningCount < 10) {
  four04WarningCount++;
  reporter.warn(`[gatsby-source-drupal] file returns 404: ${url}`);
  return {};
}

// Corrupt file detection
if (e.message.includes('unrecognized file format') && corruptFileWarningCount < 10) {
  corruptFileWarningCount++;
  reporter.warn(`[gatsby-source-drupal] Encountered corrupt file: ${url}`);
  return {};
}

interface BasicAuth {
  username: string;
  password: string;
}

interface FileNode extends GatsbyNode {
  filename: string;
  filemime: string;
  filesize: number;
  uri: string | { url: string; value: string };
  url: string;
  localFile___NODE?: string;
}

interface ImageCDNFields {
  filename: string;
  url: string;
  placeholderUrl: string;
  width: number;
  height: number;
  mimeType: string;
}