@freelygive/canvas-jsonapi 0.0.0

package/README.md

@@ -0,0 +1,157 @@
+# @freelygive/canvas-jsonapi
+
+CLI for managing content in Drupal Canvas / Acquia Source via JSON:API.
+
+List, fetch, create, update, and delete pages, media, and other content
+entities. Upload images, videos, and documents. Validate component inputs
+against local `component.yml` definitions before sending to the server.
+
+## Quick start
+
+Run directly with `npx` (no install required):
+
+```bash
+npx @freelygive/canvas-jsonapi <command> [args...]
+```
+
+Or inside a DDEV environment:
+
+```bash
+ddev npx @freelygive/canvas-jsonapi <command> [args...]
+```
+
+## Setup
+
+### Component directory
+
+Create a `canvas.config.json` in your project root (shared with
+`@drupal-canvas/cli`):
+
+```json
+{
+  "componentDir": "./src/components"
+}
+```
+
+This tells the CLI where to find `component.yml` files for input validation.
+
+### API credentials
+
+Create a `.env` file in your project root:
+
+```env
+CANVAS_SITE_URL=https://your-site.acquia.site
+CANVAS_JSONAPI_PREFIX=api
+CANVAS_CLIENT_ID=cli
+CANVAS_CLIENT_SECRET=your-secret
+```
+
+| Variable                | Required | Default   | Description                          |
+| ----------------------- | -------- | --------- | ------------------------------------ |
+| `CANVAS_SITE_URL`       | Yes      |           | Base URL of Acquia Source site       |
+| `CANVAS_JSONAPI_PREFIX` | No       | `jsonapi` | API path prefix                      |
+| `CANVAS_CLIENT_ID`      | No       |           | OAuth client ID                      |
+| `CANVAS_CLIENT_SECRET`  | No       |           | OAuth client secret                  |
+| `CONTENT_OAUTH_SCOPE`   | No       |           | OAuth scope override                 |
+| `CONTENT_NO_AUTH`       | No       |           | Set to `true` to skip authentication |
+
+The component directory is resolved in this order:
+
+1. `componentDir` in `canvas.config.json`
+2. `CANVAS_COMPONENT_DIR` env var (legacy fallback)
+3. `./src/components` (default)
+
+## Commands
+
+### List content
+
+```bash
+npx @freelygive/canvas-jsonapi list <type>
+npx @freelygive/canvas-jsonapi list --types  # Discover available types
+```
+
+### Get content
+
+Fetch and save content items locally to `content/<type>/<uuid>.json`:
+
+```bash
+npx @freelygive/canvas-jsonapi get <type> <uuid> [<uuid>...]
+npx @freelygive/canvas-jsonapi get <type> <uuid> --include <relationships>
+npx @freelygive/canvas-jsonapi get <file-path>  # Refresh from existing file
+```
+
+### Create content
+
+```bash
+npx @freelygive/canvas-jsonapi create <file-path>
+```
+
+### Update content
+
+```bash
+npx @freelygive/canvas-jsonapi update <file-path>
+```
+
+### Delete content
+
+```bash
+npx @freelygive/canvas-jsonapi delete <type> <uuid> [<uuid>...]
+```
+
+### Upload media
+
+```bash
+npx @freelygive/canvas-jsonapi upload-image <file-path> [alt-text]
+npx @freelygive/canvas-jsonapi upload-video <file-path> [name]
+npx @freelygive/canvas-jsonapi upload-document <file-path> [name]
+```
+
+### Utilities
+
+```bash
+npx @freelygive/canvas-jsonapi uuid [count]   # Generate random UUIDs
+npx @freelygive/canvas-jsonapi whoami          # Check OAuth status
+```
+
+## Local content storage
+
+Content is saved to `content/` in the current working directory:
+
+```
+content/
+  page/
+    <uuid>.<title-slug>.json
+  media--image/
+    <uuid>.<filename>.json
+  media--document/
+    <uuid>.<name>.json
+```
+
+Add `content/` to your `.gitignore`.
+
+## Component validation
+
+Before creating or updating pages, component inputs are validated against
+`component.yml` files found via `canvas.config.json`. This catches type errors
+and missing required props before the API returns a generic 503.
+
+## AI assistant usage
+
+When using this tool with an AI assistant (e.g., Claude Code), add the following
+to your `CLAUDE.md` or equivalent instructions file:
+
+```markdown
+## Content Management
+
+Use `npx @freelygive/canvas-jsonapi` (or `ddev npx @freelygive/canvas-jsonapi`
+in DDEV) to manage content in Acquia Source.
+
+Available commands: list, get, create, update, delete, upload-image,
+upload-video, upload-document, uuid, whoami.
+
+Run `npx @freelygive/canvas-jsonapi` with no arguments for full usage.
+```
+
+## License
+
+GPL-2.0-or-later

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@freelygive/canvas-jsonapi",
+  "version": "0.0.0",
+  "description": "CLI for managing content in Drupal Canvas / Acquia Source via JSON:API.",
+  "type": "module",
+  "bin": {
+    "canvas-jsonapi": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "dotenv": "^16.0.0",
+    "drupal-jsonapi-params": "^3.0.0",
+    "js-yaml": "^4.1.1"
+  },
+  "keywords": [
+    "drupal",
+    "canvas",
+    "acquia",
+    "jsonapi",
+    "cms",
+    "content-management"
+  ],
+  "license": "GPL-2.0-or-later"
+}

package/src/client.js

@@ -0,0 +1,181 @@
+/* global process */
+/**
+ * API client utilities for JSON:API access.
+ * Uses environment variables from .env file.
+ *
+ * Required env vars:
+ * - CANVAS_SITE_URL: Base URL of Acquia Source site
+ *
+ * Optional env vars:
+ * - CANVAS_JSONAPI_PREFIX: API prefix (default: "jsonapi")
+ * - CANVAS_CLIENT_ID: OAuth client ID (if authentication required)
+ * - CANVAS_CLIENT_SECRET: OAuth client secret (if authentication required)
+ * - CONTENT_OAUTH_SCOPE: OAuth scope for content access
+ * - CONTENT_NO_AUTH: Set to "true" to disable authentication
+ */
+import { config } from 'dotenv';
+
+// Load environment variables
+config();
+
+// Cache for OAuth token
+let tokenCache = null;
+
+// Cache for JSON:API endpoint mapping
+let endpointMapCache = null;
+
+/**
+ * Get the site base URL
+ * @returns {string} Site base URL
+ */
+export function getSiteUrl() {
+  const baseUrl = process.env.CANVAS_SITE_URL;
+  if (!baseUrl) {
+    throw new Error('Missing required environment variable: CANVAS_SITE_URL');
+  }
+  return baseUrl.replace(/\/$/, '');
+}
+
+/**
+ * Get the API base URL with prefix
+ * @returns {string} Full API base URL
+ */
+export function getApiBaseUrl() {
+  const apiPrefix = process.env.CANVAS_JSONAPI_PREFIX || 'jsonapi';
+  return `${getSiteUrl()}/${apiPrefix}`;
+}
+
+/**
+ * Get OAuth access token using client credentials flow
+ * @returns {Promise<string|null>} Access token or null if auth disabled
+ */
+async function getAccessToken() {
+  const noAuth = process.env.CONTENT_NO_AUTH === 'true';
+  if (noAuth) {
+    return null;
+  }
+
+  const clientId = process.env.CANVAS_CLIENT_ID;
+  const clientSecret = process.env.CANVAS_CLIENT_SECRET;
+
+  if (!clientId || !clientSecret) {
+    return null;
+  }
+
+  // Check cache
+  if (tokenCache && tokenCache.expiresAt > Date.now()) {
+    return tokenCache.accessToken;
+  }
+
+  // Request new token
+  const tokenUrl = `${getSiteUrl()}/oauth/token`;
+  const params = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: clientId,
+    client_secret: clientSecret,
+  });
+
+  const scope = process.env.CONTENT_OAUTH_SCOPE;
+  if (scope) {
+    params.append('scope', scope);
+  }
+
+  const response = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params,
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`OAuth token request failed: ${response.status} ${text}`);
+  }
+
+  const data = await response.json();
+
+  // Cache token with 60 second buffer before expiry
+  tokenCache = {
+    accessToken: data.access_token,
+    expiresAt: Date.now() + (data.expires_in - 60) * 1000,
+  };
+
+  return tokenCache.accessToken;
+}
+
+/**
+ * Fetch with OAuth authentication
+ * @param {string} url - URL to fetch
+ * @param {RequestInit} [init] - Fetch options
+ * @returns {Promise<Response>} Fetch response
+ */
+export async function authenticatedFetch(url, init = {}) {
+  const token = await getAccessToken();
+
+  const headers = { ...init.headers };
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  return fetch(url, { ...init, headers });
+}
+
+/**
+ * Fetch and cache the JSON:API endpoint mapping from the API root.
+ * The mapping provides the correct URL for each entity type.
+ * @returns {Promise<Map<string, string>>} Map of type names to endpoint URLs
+ */
+export async function getEndpointMap() {
+  if (endpointMapCache) {
+    return endpointMapCache;
+  }
+
+  const response = await authenticatedFetch(getApiBaseUrl());
+  if (!response.ok) {
+    throw new Error(`Failed to fetch API root: ${response.status}`);
+  }
+
+  const data = await response.json();
+  const links = data.links || {};
+
+  // Build map from type name to endpoint URL
+  endpointMapCache = new Map();
+  for (const [typeName, linkInfo] of Object.entries(links)) {
+    if (typeName === 'self') continue;
+    const href = typeof linkInfo === 'string' ? linkInfo : linkInfo?.href;
+    if (href) {
+      endpointMapCache.set(typeName, href);
+    }
+  }
+
+  return endpointMapCache;
+}
+
+/**
+ * Get the API endpoint URL for an entity type.
+ * Fetches the endpoint mapping from the API root if not cached.
+ * @param {string} type - Entity type (e.g., "node--news_article", "taxonomy_term--categories")
+ * @returns {Promise<string>} The endpoint URL for the entity type
+ */
+export async function getEntityEndpoint(type) {
+  const map = await getEndpointMap();
+  const url = map.get(type);
+
+  if (!url) {
+    throw new Error(
+      `Unknown entity type: ${type}. Use 'canvas-jsonapi list --types' to see available types.`,
+    );
+  }
+
+  return url;
+}
+
+/**
+ * Get the API URL for a specific entity by type and UUID.
+ * @param {string} type - Entity type (e.g., "node--news_article")
+ * @param {string} uuid - Entity UUID
+ * @returns {Promise<string>} The full URL for the entity
+ */
+export async function getEntityUrl(type, uuid) {
+  const endpoint = await getEntityEndpoint(type);
+  return `${endpoint}/${uuid}`;
+}

package/src/create.js

@@ -0,0 +1,120 @@
+/* global process */
+/**
+ * Creates a new content item from a local JSON file.
+ */
+import { unlinkSync } from 'fs';
+
+import { authenticatedFetch, getEntityEndpoint } 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 createContent(filePath) {
+  if (!filePath) {
+    console.error('Usage: canvas-jsonapi create <file-path>');
+    console.error('Example: canvas-jsonapi create content/page/new-123.json');
+    process.exit(1);
+  }
+
+  try {
+    // Read local file
+    const data = readContent(filePath);
+
+    // Extract type from the data
+    const type = data.data?.type || data.type;
+
+    if (!type) {
+      throw new Error('File must contain data.type field');
+    }
+
+    // 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 create body - remove any existing id
+    const attributes = data.data?.attributes || data.attributes;
+    const createBody = {
+      data: {
+        type: type,
+        attributes: stringifyComponentInputs(attributes),
+        relationships: data.data?.relationships || data.relationships,
+      },
+    };
+
+    // Remove id if present (API will generate one)
+    delete createBody.data.id;
+
+    // Send create request using the correct endpoint from API root
+    const url = await getEntityEndpoint(type);
+    const response = await authenticatedFetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/vnd.api+json' },
+      body: JSON.stringify(createBody),
+    });
+    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 creating ${type}:`);
+      console.error(JSON.stringify(result, null, 2));
+      process.exit(1);
+    }
+
+    // Extract the new UUID from the response
+    const newUuid = result.data?.id || result.id;
+
+    if (!newUuid) {
+      throw new Error('No UUID returned from API');
+    }
+
+    // Remove the original temp file
+    try {
+      unlinkSync(filePath);
+      console.log(`Removed temporary file: ${filePath}`);
+    } catch {
+      // Ignore if file already gone
+    }
+
+    // Fetch the full entity
+    const fullEntity = await fetchEntity(type, newUuid);
+
+    // Save with the new UUID and label
+    const labelField = getLabelField(type);
+    const label = fullEntity.data?.attributes?.[labelField] || '(untitled)';
+    const newFilePath = saveContent(type, newUuid, fullEntity, label);
+
+    displayEntitySummary('Created', type, newUuid, fullEntity, newFilePath);
+  } catch (error) {
+    console.error(`Error creating from ${filePath}:`, error.message);
+    process.exit(1);
+  }
+}

package/src/delete.js

@@ -0,0 +1,68 @@
+/* global process */
+/**
+ * Deletes content items from Acquia Source.
+ */
+import { unlinkSync } from 'fs';
+
+import { authenticatedFetch, getEntityUrl } from './client.js';
+import { findContentByUuid } from './utils.js';
+
+export async function deleteContent(args) {
+  if (!args || args.length < 2) {
+    console.error('Usage: canvas-jsonapi delete <type> <uuid> [<uuid>...]');
+    console.error('Example: canvas-jsonapi delete page abc-123-def');
+    console.error('Example: canvas-jsonapi delete media--image uuid1 uuid2');
+    process.exit(1);
+  }
+
+  const type = args[0];
+  const uuids = args.slice(1);
+
+  let hasError = false;
+  for (const uuid of uuids) {
+    try {
+      await deleteSingleContent(type, uuid);
+    } catch (error) {
+      console.error(`Error deleting ${type}/${uuid}:`, error.message);
+      hasError = true;
+    }
+  }
+
+  if (hasError) {
+    process.exit(1);
+  }
+}
+
+async function deleteSingleContent(type, uuid) {
+  // Get the correct endpoint URL from the API root mapping
+  const url = await getEntityUrl(type, uuid);
+
+  const response = await authenticatedFetch(url, {
+    method: 'DELETE',
+  });
+
+  if (!response.ok) {
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('json')) {
+      const result = await response.json();
+      throw new Error(JSON.stringify(result.errors || result, null, 2));
+    } else {
+      const text = await response.text();
+      throw new Error(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+    }
+  }
+
+  // Try to remove local file if it exists
+  const localFile = findContentByUuid(type, uuid);
+  if (localFile) {
+    try {
+      unlinkSync(localFile);
+      console.log(`Deleted: ${uuid}`);
+      console.log(`  Removed local file: ${localFile}`);
+    } catch {
+      console.log(`Deleted: ${uuid}`);
+    }
+  } else {
+    console.log(`Deleted: ${uuid}`);
+  }
+}