@freelygive/canvas-jsonapi 0.0.0

package/src/entity.js

@@ -0,0 +1,233 @@
+/**
+ * Shared entity utilities for content management scripts.
+ */
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+
+import { authenticatedFetch, getEntityUrl } from './client.js';
+import { saveContent } from './utils.js';
+
+/**
+ * Get the label field name for a given entity type.
+ * @param {string} type - The entity type
+ * @returns {string} The field name to use as label
+ */
+export function getLabelField(type) {
+  if (type.startsWith('media--')) {
+    return 'name';
+  } else if (type.startsWith('file--')) {
+    return 'filename';
+  } else if (type.startsWith('taxonomy_term--')) {
+    return 'name';
+  }
+  return 'title';
+}
+
+/**
+ * Parse component inputs from JSON strings to objects for easier editing.
+ * @param {object} data - The JSON:API response data
+ * @returns {object} Data with parsed component inputs
+ */
+export function parseComponentInputs(data) {
+  const components = data?.data?.attributes?.components;
+  if (Array.isArray(components)) {
+    for (const component of components) {
+      if (typeof component.inputs === 'string') {
+        try {
+          component.inputs = JSON.parse(component.inputs);
+        } catch {
+          // Keep as string if not valid JSON
+        }
+      }
+    }
+  }
+  return data;
+}
+
+/**
+ * Stringify component inputs if they are objects.
+ * Preserves strings that are already stringified.
+ * @param {object} attributes - The attributes object containing components
+ * @returns {object} Attributes with stringified component inputs
+ */
+export function stringifyComponentInputs(attributes) {
+  if (!attributes) return attributes;
+
+  const result = { ...attributes };
+  if (Array.isArray(result.components)) {
+    result.components = result.components.map((component) => {
+      const clean = { ...component };
+      delete clean.component_version;
+      if (clean.inputs && typeof clean.inputs !== 'string') {
+        return { ...clean, inputs: JSON.stringify(clean.inputs) };
+      }
+      return clean;
+    });
+  }
+  return result;
+}
+
+/**
+ * Extract thumbnail URL from media entity with included file.
+ * @param {object} result - The JSON:API response
+ * @returns {string|null} The thumbnail URL or null
+ */
+export function getThumbnailUrl(result) {
+  const included = result.included || [];
+  for (const item of included) {
+    if (item.type === 'file--file' && item.links?.thumbnail?.href) {
+      return item.links.thumbnail.href;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract file URL from media entity with included file.
+ * @param {object} result - The JSON:API response
+ * @returns {string|null} The file URL or null
+ */
+export function getFileUrl(result) {
+  const included = result.included || [];
+  for (const item of included) {
+    if (item.type === 'file--file' && item.attributes?.uri?.url) {
+      return item.attributes.uri.url;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract media internal ID from the response.
+ * The internal ID is in resourceVersion query param of the self link.
+ * @param {object} result - The JSON:API response
+ * @returns {string|null} The media internal ID or null
+ */
+export function getMediaInternalId(result) {
+  const selfHref = result.data?.links?.self?.href;
+  if (selfHref) {
+    const match = selfHref.match(/resourceVersion=id%3A(\d+)/);
+    if (match) {
+      return match[1];
+    }
+  }
+  return null;
+}
+
+/**
+ * Fetch an entity from the API.
+ * @param {string} type - The entity type
+ * @param {string} uuid - The entity UUID
+ * @param {string[]} include - Fields to include
+ * @returns {Promise<object>} The entity data
+ */
+export async function fetchEntity(type, uuid, include = []) {
+  const params = new DrupalJsonApiParams();
+
+  // For media entities, automatically include the file field to get file links
+  let includeFields = [...include];
+  if (type === 'media--image' && !include.includes('media_image')) {
+    includeFields.push('media_image');
+  } else if (type === 'media--document' && !include.includes('media_file')) {
+    includeFields.push('media_file');
+  }
+
+  if (includeFields.length > 0) {
+    params.addInclude(includeFields);
+  }
+
+  const queryString = params.getQueryString();
+  // Get the correct endpoint URL from the API root mapping
+  let url = await getEntityUrl(type, uuid);
+  if (queryString) {
+    url += `?${queryString}`;
+  }
+
+  const response = await authenticatedFetch(url);
+  const contentType = response.headers.get('content-type') || '';
+
+  if (
+    !contentType.includes('application/vnd.api+json') &&
+    !contentType.includes('application/json')
+  ) {
+    const text = await response.text();
+    throw new Error(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+  }
+
+  const result = await response.json();
+
+  if (!response.ok || result.errors) {
+    throw new Error(JSON.stringify(result.errors || result, null, 2));
+  }
+
+  return parseComponentInputs(result);
+}
+
+/**
+ * Fetch an entity, save it locally, and display a summary.
+ * @param {string} type - The entity type
+ * @param {string} uuid - The entity UUID
+ * @param {string[]} include - Fields to include
+ * @returns {Promise<{filePath: string, entity: object}>} The saved file path and entity
+ */
+export async function fetchAndSaveEntity(type, uuid, include = []) {
+  const entity = await fetchEntity(type, uuid, include);
+
+  const labelField = getLabelField(type);
+  const label = entity.data?.attributes?.[labelField] || '(untitled)';
+  const filePath = saveContent(type, uuid, entity, label);
+
+  console.log(`Saved: ${label}`);
+  console.log(`  File: ${filePath}`);
+
+  if (type === 'media--image') {
+    const thumbnail = getThumbnailUrl(entity);
+    if (thumbnail) {
+      console.log(`  Thumbnail: ${thumbnail}`);
+    }
+    const internalId = getMediaInternalId(entity);
+    if (internalId) {
+      console.log(`  target_id: ${internalId}`);
+    }
+  }
+
+  return { filePath, entity };
+}
+
+/**
+ * Display entity summary after create/update.
+ * @param {string} action - The action performed (Created, Updated)
+ * @param {string} type - The entity type
+ * @param {string} uuid - The entity UUID
+ * @param {object} entity - The entity data
+ * @param {string} filePath - The saved file path (optional)
+ */
+export function displayEntitySummary(action, type, uuid, entity, filePath) {
+  const labelField = getLabelField(type);
+  const label = entity.data?.attributes?.[labelField] || '(untitled)';
+
+  console.log(`${action}: ${label}`);
+  console.log(`  UUID: ${uuid}`);
+  if (filePath) {
+    console.log(`  File: ${filePath}`);
+  }
+
+  if (type === 'media--image') {
+    const thumbnail = getThumbnailUrl(entity);
+    if (thumbnail) {
+      console.log(`  Thumbnail: ${thumbnail}`);
+    }
+    const internalId = getMediaInternalId(entity);
+    if (internalId) {
+      console.log(`  target_id: ${internalId}`);
+    }
+  } else if (type === 'media--document') {
+    const fileUrl = getFileUrl(entity);
+    if (fileUrl) {
+      console.log(`  File URL: ${fileUrl}`);
+    }
+    const internalId = getMediaInternalId(entity);
+    if (internalId) {
+      console.log(`  target_id: ${internalId}`);
+    }
+  }
+}

package/src/get.js

@@ -0,0 +1,95 @@
+/* global process */
+/**
+ * Fetches content items and saves them locally.
+ */
+import { fetchAndSaveEntity } from './entity.js';
+import { parseContentPath } from './utils.js';
+
+/**
+ * Check if a string looks like a content file path.
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isContentPath(str) {
+  return str.endsWith('.json') && str.includes('/');
+}
+
+function parseArgs(args) {
+  const result = { type: null, uuids: [], include: [] };
+  let i = 0;
+
+  // Check if the first arg is a file path
+  if (args.length > 0 && isContentPath(args[0])) {
+    const { type, uuid } = parseContentPath(args[0]);
+    result.type = type;
+    result.uuids.push(uuid);
+    i++;
+    // Allow additional file paths
+    while (i < args.length && !args[i].startsWith('--')) {
+      if (isContentPath(args[i])) {
+        result.uuids.push(parseContentPath(args[i]).uuid);
+      } else {
+        result.uuids.push(args[i]);
+      }
+      i++;
+    }
+  } else {
+    // First positional arg is type
+    if (args.length > 0 && !args[0].startsWith('--')) {
+      result.type = args[0];
+      i++;
+    }
+
+    // Collect UUIDs until we hit a flag
+    while (i < args.length && !args[i].startsWith('--')) {
+      result.uuids.push(args[i]);
+      i++;
+    }
+  }
+
+  // Parse remaining args for --include
+  while (i < args.length) {
+    if (args[i] === '--include' && i + 1 < args.length) {
+      result.include = args[i + 1].split(',');
+      i += 2;
+    } else {
+      i++;
+    }
+  }
+
+  return result;
+}
+
+export async function getContent(args) {
+  const parsed = parseArgs(args);
+
+  if (!parsed.type || parsed.uuids.length === 0) {
+    console.error(
+      'Usage: canvas-jsonapi get <type> <uuid> [<uuid>...] [--include <fields>]',
+    );
+    console.error('       canvas-jsonapi get <file-path> [<file-path>...]');
+    console.error('Example: canvas-jsonapi get page abc-123-def');
+    console.error('Example: canvas-jsonapi get page abc-123 def-456 ghi-789');
+    console.error(
+      'Example: canvas-jsonapi get page abc-123-def --include image,owner',
+    );
+    console.error(
+      'Example: canvas-jsonapi get content/page--landing/abc-123.my-page.json',
+    );
+    process.exit(1);
+  }
+
+  let hasError = false;
+  for (const uuid of parsed.uuids) {
+    try {
+      await fetchAndSaveEntity(parsed.type, uuid, parsed.include);
+    } catch (error) {
+      console.error(`Error fetching ${parsed.type}/${uuid}:`, error.message);
+      hasError = true;
+    }
+  }
+
+  if (hasError) {
+    process.exit(1);
+  }
+}

package/src/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/* global process */
+/**
+ * Unified content management CLI for Drupal Canvas / Acquia Source.
+ *
+ * Usage: canvas-jsonapi <command> [args...]
+ *
+ * Commands:
+ *   list <type>                       List content items (use --types to discover types)
+ *   get <type> <uuid> [<uuid>...]     Fetch and save content items
+ *   get <file-path> [<file-path>...]  Refresh local content from file path
+ *   create <file-path>                Create content from JSON file
+ *   update <file-path>                Update content from JSON file
+ *   delete <type> <uuid> [<uuid>...]  Delete content items
+ *   upload-image <file-path> [alt]    Upload image and create media entity
+ *   upload-video <file-path> [name]   Upload video and create media entity
+ *   upload-document <file-path> [name] Upload document and create media entity
+ *   uuid [count]                      Generate random UUIDs
+ *   whoami                            Show OAuth authentication status
+ */
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+async function main() {
+  switch (command) {
+    case 'list': {
+      const { listContent } = await import('./list.js');
+      await listContent(args[0]);
+      break;
+    }
+    case 'get': {
+      const { getContent } = await import('./get.js');
+      await getContent(args);
+      break;
+    }
+    case 'create': {
+      const { createContent } = await import('./create.js');
+      await createContent(args[0]);
+      break;
+    }
+    case 'update': {
+      const { updateContent } = await import('./update.js');
+      await updateContent(args[0]);
+      break;
+    }
+    case 'delete': {
+      const { deleteContent } = await import('./delete.js');
+      await deleteContent(args);
+      break;
+    }
+    case 'upload-image': {
+      const { uploadImage } = await import('./upload-image.js');
+      await uploadImage(args[0], args[1]);
+      break;
+    }
+    case 'upload-video': {
+      const { uploadVideo } = await import('./upload-video.js');
+      await uploadVideo(args[0], args[1]);
+      break;
+    }
+    case 'upload-document': {
+      const { uploadDocument } = await import('./upload-document.js');
+      await uploadDocument(args[0], args[1]);
+      break;
+    }
+    case 'uuid': {
+      const { generateUuids } = await import('./uuid.js');
+      generateUuids(args[0] ? parseInt(args[0], 10) : 1);
+      break;
+    }
+    case 'whoami': {
+      const { whoami } = await import('./whoami.js');
+      await whoami();
+      break;
+    }
+    default:
+      console.error('Usage: canvas-jsonapi <command> [args...]');
+      console.error('');
+      console.error('Commands:');
+      console.error(
+        '  list <type>                        List content items (use --types to discover types)',
+      );
+      console.error(
+        '  get <type> <uuid> [<uuid>...]      Fetch and save content items',
+      );
+      console.error(
+        '  get <file-path> [<file-path>...]   Refresh local content from path',
+      );
+      console.error(
+        '  create <file-path>                 Create content from JSON file',
+      );
+      console.error(
+        '  update <file-path>                 Update content from JSON file',
+      );
+      console.error(
+        '  delete <type> <uuid> [<uuid>...]   Delete content items',
+      );
+      console.error(
+        '  upload-image <file-path> [alt]     Upload image and create media entity',
+      );
+      console.error(
+        '  upload-video <file-path> [name]    Upload video and create media entity',
+      );
+      console.error(
+        '  upload-document <file-path> [name] Upload document and create media entity',
+      );
+      console.error(
+        '  uuid [count]                       Generate random UUIDs',
+      );
+      console.error(
+        '  whoami                             Show OAuth authentication status',
+      );
+      process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/src/list.js

@@ -0,0 +1,197 @@
+/* global process */
+/**
+ * Lists content items of a specific type from Acquia Source.
+ */
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+
+import {
+  authenticatedFetch,
+  getApiBaseUrl,
+  getEntityEndpoint,
+} from './client.js';
+
+async function listTypes() {
+  try {
+    // Fetch the API index to get available types
+    const response = await authenticatedFetch(getApiBaseUrl());
+    const contentType = response.headers.get('content-type') || '';
+
+    // Handle non-JSON responses
+    if (
+      !contentType.includes('application/vnd.api+json') &&
+      !contentType.includes('application/json')
+    ) {
+      const text = await response.text();
+      console.error(`HTTP ${response.status}: ${response.statusText}`);
+      console.error(text.slice(0, 500));
+      process.exit(1);
+    }
+
+    const body = await response.json();
+
+    if (!response.ok) {
+      console.error(`HTTP ${response.status}: ${response.statusText}`);
+      console.error(JSON.stringify(body, null, 2));
+      process.exit(1);
+    }
+
+    console.log('Available types:');
+    Object.keys(body?.links || {})
+      .filter((key) => key !== 'self')
+      .sort()
+      .forEach((key) => console.log(`  ${key}`));
+  } catch (error) {
+    console.error('Error fetching types:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Get the file relationship field name for a media type, if applicable.
+ * @param {string} type - The entity type
+ * @returns {string|null} The file relationship field name or null
+ */
+function getMediaFileField(type) {
+  if (type === 'media--image') return 'media_image';
+  if (type === 'media--document') return 'media_file';
+  return null;
+}
+
+/**
+ * Build a map from media entity ID to filename from JSON:API included data.
+ * @param {object[]} included - The included array from JSON:API response
+ * @param {object[]} items - The data items from the response
+ * @param {string} fileField - The relationship field name
+ * @returns {Map<string, string>} Map of media entity ID to filename
+ */
+function buildFilenameMap(included, items, fileField) {
+  const map = new Map();
+  if (!included || !fileField) return map;
+
+  // Build a lookup from file UUID to filename
+  const fileLookup = new Map();
+  for (const inc of included) {
+    if (inc.type === 'file--file' && inc.attributes?.filename) {
+      fileLookup.set(inc.id, inc.attributes.filename);
+    }
+  }
+
+  // Map each media item to its file's filename
+  for (const item of items) {
+    const fileRef = item.relationships?.[fileField]?.data;
+    if (fileRef?.id && fileLookup.has(fileRef.id)) {
+      map.set(item.id, fileLookup.get(fileRef.id));
+    }
+  }
+
+  return map;
+}
+
+export async function listContent(type) {
+  if (!type) {
+    console.error('Usage: canvas-jsonapi list <type>');
+    console.error('Example: canvas-jsonapi list page');
+    console.error('');
+    console.error('To discover available types, use:');
+    console.error('  canvas-jsonapi list --types');
+    process.exit(1);
+  }
+
+  // Special case: list available types
+  if (type === '--types') {
+    await listTypes();
+    return;
+  }
+
+  try {
+    // Determine the label field based on entity type
+    let labelField = 'title';
+    if (type.startsWith('media--')) {
+      labelField = 'name';
+    } else if (type.startsWith('file--')) {
+      labelField = 'filename';
+    } else if (type.startsWith('taxonomy_term--')) {
+      labelField = 'name';
+    }
+
+    // Check if we should include file info for media types
+    const fileField = getMediaFileField(type);
+
+    // Build query to get essential fields only
+    const params = new DrupalJsonApiParams();
+    const fields = [labelField];
+    if (fileField) {
+      // Include the relationship field so it appears in the response
+      fields.push(fileField);
+      params.addInclude([fileField]);
+      params.addFields('file--file', ['filename']);
+    }
+    params.addFields(type, fields);
+    params.addPageLimit(50);
+
+    const queryString = params.getQueryString();
+    // Get the correct endpoint URL from the API root mapping
+    const endpoint = await getEntityEndpoint(type);
+    let url = `${endpoint}?${queryString}`;
+
+    const allItems = [];
+    let allIncluded = [];
+
+    // Paginate through all results
+    while (url) {
+      const response = await authenticatedFetch(url);
+      const contentType = response.headers.get('content-type') || '';
+
+      // Handle non-JSON responses
+      if (
+        !contentType.includes('application/vnd.api+json') &&
+        !contentType.includes('application/json')
+      ) {
+        const text = await response.text();
+        console.error(`HTTP ${response.status}: ${response.statusText}`);
+        console.error(text.slice(0, 500));
+        process.exit(1);
+      }
+
+      const result = await response.json();
+
+      // Check for errors in response
+      if (!response.ok || result.errors) {
+        console.error(`Error listing ${type}:`);
+        console.error(JSON.stringify(result, null, 2));
+        process.exit(1);
+      }
+
+      allItems.push(...(result.data || []));
+      if (result.included) {
+        allIncluded.push(...result.included);
+      }
+
+      // Follow next link for pagination
+      url = result.links?.next?.href || null;
+    }
+
+    // Build filename map for media types
+    const filenameMap = buildFilenameMap(allIncluded, allItems, fileField);
+
+    // Output summary: uuid - label [filename]
+    if (allItems.length === 0) {
+      console.log('No items found.');
+    } else {
+      for (const item of allItems) {
+        const label = item.attributes?.[labelField] || '(untitled)';
+        const filename = filenameMap.get(item.id);
+        if (filename) {
+          const title = filename === label ? '' : `  (Title: ${label})`;
+          console.log(`${item.id}  ${filename}${title}`);
+        } else {
+          console.log(`${item.id}  ${label}`);
+        }
+      }
+      console.log(`\n${allItems.length} item(s)`);
+    }
+  } catch (error) {
+    console.error(`Error listing ${type}:`, error.message);
+    process.exit(1);
+  }
+}