@freelygive/canvas-jsonapi 0.0.0

package/src/update.js

@@ -0,0 +1,140 @@
+/* global process */
+/**
+ * Updates a content item from a local JSON file.
+ */
+import { authenticatedFetch, getEntityUrl } from './client.js';
+import {
+  displayEntitySummary,
+  fetchEntity,
+  getLabelField,
+  stringifyComponentInputs,
+} from './entity.js';
+import { readContent, saveContent } from './utils.js';
+import {
+  formatValidationErrors,
+  validateContentComponents,
+} from './validate.js';
+
+export async function updateContent(filePath) {
+  if (!filePath) {
+    console.error('Usage: canvas-jsonapi update <file-path>');
+    console.error('Example: canvas-jsonapi update content/page/abc-123.json');
+    process.exit(1);
+  }
+
+  try {
+    // Read local file
+    const data = readContent(filePath);
+
+    // Extract type and UUID from the data itself (more reliable)
+    const type = data.data?.type || data.type;
+    const uuid = data.data?.id || data.id;
+
+    if (!type || !uuid) {
+      throw new Error('File must contain data.type and data.id fields');
+    }
+
+    // Validate component inputs before sending to server
+    const validation = validateContentComponents(data);
+    if (!validation.valid) {
+      console.error(formatValidationErrors(validation.errors));
+      process.exit(1);
+    }
+    if (validation.warnings?.length > 0) {
+      for (const warning of validation.warnings) {
+        console.warn(`Warning: ${warning}`);
+      }
+    }
+
+    // Prepare update body - ensure proper JSON:API format
+    const attributes = data.data?.attributes || data.attributes;
+
+    // Strip read-only fields that the API won't accept on PATCH
+    const readOnlyFields = [
+      'changed',
+      'created',
+      'revision_created',
+      'default_langcode',
+      'revision_translation_affected',
+      'metatags',
+      'path',
+    ];
+    const writableAttributes = { ...attributes };
+    for (const field of readOnlyFields) {
+      delete writableAttributes[field];
+    }
+
+    const updateBody = {
+      data: {
+        type: type,
+        id: uuid,
+        attributes: stringifyComponentInputs(writableAttributes),
+      },
+    };
+
+    // Include writable relationships (e.g., brands, categories, banner_image)
+    const relationships = data.data?.relationships || data.relationships;
+    if (relationships) {
+      const readOnlyRelationships = [
+        'node_type',
+        'revision_uid',
+        'uid',
+        'vid',
+        'revision_user',
+        'parent',
+        'owner',
+      ];
+      const writableRelationships = {};
+      for (const [key, value] of Object.entries(relationships)) {
+        if (!readOnlyRelationships.includes(key) && value?.data !== undefined) {
+          writableRelationships[key] = { data: value.data };
+        }
+      }
+      if (Object.keys(writableRelationships).length > 0) {
+        updateBody.data.relationships = writableRelationships;
+      }
+    }
+
+    // Send update request using the correct endpoint from API root
+    const url = await getEntityUrl(type, uuid);
+    const response = await authenticatedFetch(url, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/vnd.api+json' },
+      body: JSON.stringify(updateBody),
+    });
+    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 updating ${type}/${uuid}:`);
+      console.error(JSON.stringify(result, null, 2));
+      process.exit(1);
+    }
+
+    // Fetch the full entity to get complete data
+    const fullEntity = await fetchEntity(type, uuid);
+
+    // Save the updated entity with label
+    const labelField = getLabelField(type);
+    const label = fullEntity.data?.attributes?.[labelField] || '(untitled)';
+    const savedPath = saveContent(type, uuid, fullEntity, label);
+
+    displayEntitySummary('Updated', type, uuid, fullEntity, savedPath);
+  } catch (error) {
+    console.error(`Error updating from ${filePath}:`, error.message);
+    process.exit(1);
+  }
+}

package/src/upload-document.js

@@ -0,0 +1,125 @@
+/* global process */
+/**
+ * Uploads a document file and creates a media entity.
+ */
+import { readFileSync } from 'fs';
+import { basename } from 'path';
+
+import { authenticatedFetch, getApiBaseUrl } from './client.js';
+import { displayEntitySummary, fetchEntity } from './entity.js';
+import { saveContent } from './utils.js';
+
+export async function uploadDocument(filePath, name) {
+  if (!filePath) {
+    console.error('Usage: canvas-jsonapi upload-document <file-path> [name]');
+    console.error(
+      'Example: canvas-jsonapi upload-document fonts/AbsaraSans.woff2 "AbsaraSans Regular"',
+    );
+    process.exit(1);
+  }
+
+  try {
+    const filename = basename(filePath);
+    const fileData = readFileSync(filePath);
+    const mediaName = name || filename;
+
+    console.log(`Uploading: ${filename}`);
+
+    // Step 1: Upload the file binary
+    const fileUploadUrl = `${getApiBaseUrl()}/media/document/media_file`;
+    const fileResponse = await authenticatedFetch(fileUploadUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/octet-stream',
+        'Content-Disposition': `file; filename="${filename}"`,
+        Accept: 'application/vnd.api+json',
+      },
+      body: fileData,
+    });
+
+    if (!fileResponse.ok) {
+      const text = await fileResponse.text();
+      console.error(`File upload failed: ${fileResponse.status}`);
+      console.error(text.slice(0, 1000));
+      process.exit(1);
+    }
+
+    const fileResult = await fileResponse.json();
+    const fileId = fileResult.data?.id;
+    const fileUrl = fileResult.data?.attributes?.uri?.url;
+
+    if (!fileId) {
+      throw new Error('No file ID returned from upload');
+    }
+
+    // Step 2: Create media entity
+    const mediaUrl = `${getApiBaseUrl()}/media/document`;
+    const mediaBody = {
+      data: {
+        type: 'media--document',
+        attributes: {
+          name: mediaName,
+          status: true,
+        },
+        relationships: {
+          media_file: {
+            data: {
+              type: 'file--file',
+              id: fileId,
+            },
+          },
+        },
+      },
+    };
+
+    const mediaResponse = await authenticatedFetch(mediaUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/vnd.api+json',
+        Accept: 'application/vnd.api+json',
+      },
+      body: JSON.stringify(mediaBody),
+    });
+
+    if (!mediaResponse.ok) {
+      const text = await mediaResponse.text();
+      console.error(`Media creation failed: ${mediaResponse.status}`);
+      console.error(text.slice(0, 1000));
+      process.exit(1);
+    }
+
+    const mediaResult = await mediaResponse.json();
+    const mediaUuid = mediaResult.data?.id;
+
+    if (!mediaUuid) {
+      throw new Error('No media UUID returned from API');
+    }
+
+    // Fetch the full media entity with file includes
+    const fullEntity = await fetchEntity('media--document', mediaUuid);
+
+    // Save locally with filename as label
+    const savedPath = saveContent(
+      'media--document',
+      mediaUuid,
+      fullEntity,
+      mediaName,
+    );
+
+    displayEntitySummary(
+      'Uploaded',
+      'media--document',
+      mediaUuid,
+      fullEntity,
+      savedPath,
+    );
+
+    // Return the file URL for programmatic use
+    const entityFileUrl =
+      fullEntity?.included?.[0]?.attributes?.uri?.url || fileUrl;
+    return { uuid: mediaUuid, fileUrl: entityFileUrl };
+  } catch (error) {
+    console.error(`Error uploading ${filePath}:`, error.message);
+    process.exit(1);
+  }
+}

package/src/upload-image.js

@@ -0,0 +1,122 @@
+/* global process */
+/**
+ * Uploads an image file and creates a media entity.
+ */
+import { readFileSync } from 'fs';
+import { basename } from 'path';
+
+import { authenticatedFetch, getApiBaseUrl } from './client.js';
+import { displayEntitySummary, fetchEntity } from './entity.js';
+import { saveContent } from './utils.js';
+
+export async function uploadImage(filePath, altText) {
+  if (!filePath) {
+    console.error('Usage: canvas-jsonapi upload-image <file-path> [alt-text]');
+    console.error(
+      'Example: canvas-jsonapi upload-image images/photo.jpg "Photo description"',
+    );
+    process.exit(1);
+  }
+
+  try {
+    const filename = basename(filePath);
+    const fileData = readFileSync(filePath);
+    const alt = altText || filename;
+
+    console.log(`Uploading: ${filename}`);
+
+    // Step 1: Upload the file binary
+    const fileUploadUrl = `${getApiBaseUrl()}/media/image/media_image`;
+    const fileResponse = await authenticatedFetch(fileUploadUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/octet-stream',
+        'Content-Disposition': `file; filename="${filename}"`,
+        Accept: 'application/vnd.api+json',
+      },
+      body: fileData,
+    });
+
+    if (!fileResponse.ok) {
+      const text = await fileResponse.text();
+      console.error(`File upload failed: ${fileResponse.status}`);
+      console.error(text.slice(0, 1000));
+      process.exit(1);
+    }
+
+    const fileResult = await fileResponse.json();
+    const fileId = fileResult.data?.id;
+
+    if (!fileId) {
+      throw new Error('No file ID returned from upload');
+    }
+
+    // Step 2: Create media entity
+    const mediaUrl = `${getApiBaseUrl()}/media/image`;
+    const mediaBody = {
+      data: {
+        type: 'media--image',
+        attributes: {
+          name: filename,
+          status: true,
+        },
+        relationships: {
+          media_image: {
+            data: {
+              type: 'file--file',
+              id: fileId,
+              meta: {
+                alt: alt,
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const mediaResponse = await authenticatedFetch(mediaUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/vnd.api+json',
+        Accept: 'application/vnd.api+json',
+      },
+      body: JSON.stringify(mediaBody),
+    });
+
+    if (!mediaResponse.ok) {
+      const text = await mediaResponse.text();
+      console.error(`Media creation failed: ${mediaResponse.status}`);
+      console.error(text.slice(0, 1000));
+      process.exit(1);
+    }
+
+    const mediaResult = await mediaResponse.json();
+    const mediaUuid = mediaResult.data?.id;
+
+    if (!mediaUuid) {
+      throw new Error('No media UUID returned from API');
+    }
+
+    // Fetch the full media entity with file includes
+    const fullEntity = await fetchEntity('media--image', mediaUuid);
+
+    // Save locally with filename as label
+    const savedPath = saveContent(
+      'media--image',
+      mediaUuid,
+      fullEntity,
+      filename,
+    );
+
+    displayEntitySummary(
+      'Uploaded',
+      'media--image',
+      mediaUuid,
+      fullEntity,
+      savedPath,
+    );
+  } catch (error) {
+    console.error(`Error uploading ${filePath}:`, error.message);
+    process.exit(1);
+  }
+}

package/src/upload-video.js

@@ -0,0 +1,127 @@
+/* global process */
+/**
+ * Uploads a video file and creates a media entity.
+ */
+import { readFileSync } from 'fs';
+import { basename } from 'path';
+
+import { authenticatedFetch, getApiBaseUrl } from './client.js';
+import { displayEntitySummary, fetchEntity } from './entity.js';
+import { saveContent } from './utils.js';
+
+export async function uploadVideo(filePath, name) {
+  if (!filePath) {
+    console.error('Usage: canvas-jsonapi upload-video <file-path> [name]');
+    console.error(
+      'Example: canvas-jsonapi upload-video videos/hero.mp4 "Hero background video"',
+    );
+    process.exit(1);
+  }
+
+  try {
+    const filename = basename(filePath);
+    const fileData = readFileSync(filePath);
+    const mediaName = name || filename;
+
+    console.log(
+      `Uploading: ${filename} (${(fileData.length / 1024 / 1024).toFixed(1)} MB)`,
+    );
+
+    // Step 1: Upload the file binary
+    const fileUploadUrl = `${getApiBaseUrl()}/media/video/media_video_file`;
+    const fileResponse = await authenticatedFetch(fileUploadUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/octet-stream',
+        'Content-Disposition': `file; filename="${filename}"`,
+        Accept: 'application/vnd.api+json',
+      },
+      body: fileData,
+    });
+
+    if (!fileResponse.ok) {
+      const text = await fileResponse.text();
+      console.error(`File upload failed: ${fileResponse.status}`);
+      console.error(text.slice(0, 1000));
+      process.exit(1);
+    }
+
+    const fileResult = await fileResponse.json();
+    const fileId = fileResult.data?.id;
+    const fileUrl = fileResult.data?.attributes?.uri?.url;
+
+    if (!fileId) {
+      throw new Error('No file ID returned from upload');
+    }
+
+    // Step 2: Create media entity
+    const mediaUrl = `${getApiBaseUrl()}/media/video`;
+    const mediaBody = {
+      data: {
+        type: 'media--video',
+        attributes: {
+          name: mediaName,
+          status: true,
+        },
+        relationships: {
+          media_video_file: {
+            data: {
+              type: 'file--file',
+              id: fileId,
+            },
+          },
+        },
+      },
+    };
+
+    const mediaResponse = await authenticatedFetch(mediaUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/vnd.api+json',
+        Accept: 'application/vnd.api+json',
+      },
+      body: JSON.stringify(mediaBody),
+    });
+
+    if (!mediaResponse.ok) {
+      const text = await mediaResponse.text();
+      console.error(`Media creation failed: ${mediaResponse.status}`);
+      console.error(text.slice(0, 1000));
+      process.exit(1);
+    }
+
+    const mediaResult = await mediaResponse.json();
+    const mediaUuid = mediaResult.data?.id;
+
+    if (!mediaUuid) {
+      throw new Error('No media UUID returned from API');
+    }
+
+    // Fetch the full media entity with file includes
+    const fullEntity = await fetchEntity('media--video', mediaUuid);
+
+    // Save locally
+    const savedPath = saveContent(
+      'media--video',
+      mediaUuid,
+      fullEntity,
+      mediaName,
+    );
+
+    displayEntitySummary(
+      'Uploaded',
+      'media--video',
+      mediaUuid,
+      fullEntity,
+      savedPath,
+    );
+
+    // Return the file URL for programmatic use
+    const entityFileUrl =
+      fullEntity?.included?.[0]?.attributes?.uri?.url || fileUrl;
+    return { uuid: mediaUuid, fileUrl: entityFileUrl };
+  } catch (error) {
+    console.error(`Error uploading ${filePath}:`, error.message);
+    process.exit(1);
+  }
+}

package/src/utils.js

@@ -0,0 +1,147 @@
+/* global process */
+/**
+ * Common utility functions for content management scripts.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { dirname, join } from 'path';
+
+export const CONTENT_DIR = join(process.cwd(), 'content');
+
+/**
+ * Converts a string to a safe filename slug
+ * @param {string} str - String to slugify
+ * @returns {string} Safe filename string
+ */
+export function slugify(str) {
+  return str
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '') // Remove diacritics
+    .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphens
+    .replace(/^-+|-+$/g, '') // Trim leading/trailing hyphens
+    .slice(0, 50); // Limit length
+}
+
+/**
+ * Ensures a directory exists, creating it recursively if needed
+ * @param {string} dirPath - Directory path to ensure
+ */
+export function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Gets the file path for a content item
+ * @param {string} type - Entity type (e.g., "page--landing")
+ * @param {string} uuid - Content UUID
+ * @param {string} [label] - Optional label to append to filename
+ * @returns {string} Full file path
+ */
+export function getContentPath(type, uuid, label) {
+  const filename = label ? `${uuid}.${slugify(label)}.json` : `${uuid}.json`;
+  return join(CONTENT_DIR, type, filename);
+}
+
+/**
+ * Gets the directory path for a content type
+ * @param {string} type - Entity type (e.g., "page--landing")
+ * @returns {string} Directory path
+ */
+export function getTypeDir(type) {
+  return join(CONTENT_DIR, type);
+}
+
+/**
+ * Finds a content file by UUID (ignoring the label part of filename)
+ * @param {string} type - Entity type
+ * @param {string} uuid - Content UUID
+ * @returns {string|null} Full file path or null if not found
+ */
+export function findContentByUuid(type, uuid) {
+  const typeDir = getTypeDir(type);
+  if (!existsSync(typeDir)) {
+    return null;
+  }
+  const files = readdirSync(typeDir);
+  const match = files.find(
+    (f) => f.startsWith(`${uuid}.`) && f.endsWith('.json'),
+  );
+  return match ? join(typeDir, match) : null;
+}
+
+/**
+ * Saves content data to a local JSON file
+ * @param {string} type - Entity type
+ * @param {string} uuid - Content UUID
+ * @param {object} data - Content data to save
+ * @param {string} [label] - Optional label to append to filename
+ * @returns {string} Path to saved file
+ */
+export function saveContent(type, uuid, data, label) {
+  // Remove old file if it exists with a different name
+  const existingFile = findContentByUuid(type, uuid);
+  const newFilePath = getContentPath(type, uuid, label);
+
+  if (existingFile && existingFile !== newFilePath) {
+    try {
+      unlinkSync(existingFile);
+    } catch {
+      // Ignore errors removing old file
+    }
+  }
+
+  ensureDir(dirname(newFilePath));
+  writeFileSync(newFilePath, JSON.stringify(data, null, 2));
+  return newFilePath;
+}
+
+/**
+ * Reads content data from a local JSON file
+ * @param {string} filePath - Path to JSON file
+ * @returns {object} Parsed content data
+ */
+export function readContent(filePath) {
+  if (!existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  const raw = readFileSync(filePath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Extracts type and UUID from a file path
+ * @param {string} filePath - Path to content file
+ * @returns {{type: string, uuid: string}} Extracted type and UUID
+ */
+export function parseContentPath(filePath) {
+  // Match pattern: content/<type>/<uuid>.<label>.json or content/<type>/<uuid>.json
+  const match = filePath.match(
+    /content\/([^/]+)\/([a-f0-9-]+)(?:\.[^/]+)?\.json$/i,
+  );
+  if (!match) {
+    throw new Error(`Invalid content file path: ${filePath}`);
+  }
+  return {
+    type: match[1],
+    uuid: match[2],
+  };
+}
+
+/**
+ * Generates a temporary filename for new content
+ * @param {string} type - Entity type
+ * @returns {string} Temporary file path with placeholder UUID
+ */
+export function getTempContentPath(type) {
+  const timestamp = Date.now();
+  return getContentPath(type, `new-${timestamp}`);
+}

package/src/uuid.js

@@ -0,0 +1,10 @@
+/**
+ * Generates random UUID v4 values.
+ */
+import { randomUUID } from 'crypto';
+
+export function generateUuids(count = 1) {
+  for (let i = 0; i < count; i++) {
+    console.log(randomUUID());
+  }
+}