@j-o-r/hello-dave 0.1.1 → 0.1.5

package/lib/API/x.ai/image.js

@@ -1,40 +1,68 @@
+import { request as doRequest } from '@j-o-r/apiserver';
+import fs from 'fs/promises';
+import path from 'path';
+
 /**
  * @file lib/API/x.ai/image.js
  * @module x.ai/image
- * @description Pure HTTP wrapper for the xAI Grok Imagine API.
+ * @description Pure HTTP wrapper for the xAI Grok Imagine API (v1).
+ *
+ * Provides a clean, minimal, and robust interface for:
+ * - Text-to-image generation via `generateImage()`
+ * - Natural language image editing (with up to 3 reference images) via `editImage()`
+ * - Image-to-video generation via `generateVideo()` — fully automatic with internal polling
+ *
+ * All public functions handle:
+ * - Authentication via the `XAIKEY` environment variable (Bearer token)
+ * - Request formatting and validation
+ * - Automatic local file saving to `.cache/xai/` (with timestamped filenames)
+ * - Robust error handling and propagation
+ *
+ * Video generation is asynchronous on the xAI server side. The `generateVideo()` function
+ * submits the request and internally polls `/videos/{request_id}` until the result is ready
+ * (or times out). The helper `pollVideoResult()` is exported for advanced control.
  *
- * Provides a clean, minimal interface for:
- * - Text-to-image generation
- * - Natural language image editing (supports up to 3 reference images)
- * - Image-to-video generation (fully automatic with internal polling)
+ * **Supported Models** (current as of June 2026):
+ * - Image generation & editing: `grok-imagine-image-quality`, `grok-imagine-image`
+ * - Video generation: `grok-imagine-video`
  *
- * All functions handle authentication, request formatting, local file saving,
- * and error handling. Video generation waits internally until the result is ready.
+ * **Source Documentation**: Derived from the official xAI Imagine API documentation in the
+ * accompanying Markdown files:
+ * - `image.md` (overview, pricing, capabilities, supported models)
+ * - `image.to.generation.md` (text-to-image details, aspect ratios, resolution, n, response_format)
+ * - `image.editing.md` (image editing, multi-image support, compositing)
+ * - `image.to.video.md` (image-to-video specifics, duration, motion prompts)
  *
- * @see ./image.md for the full API specification and examples
+ * @see ./image.md
+ * @see ./image.to.generation.md
+ * @see ./image.editing.md
+ * @see ./image.to.video.md
  */
 
 /**
  * @constant {string} BASE_URL
- * @description Base URL for the xAI API.
+ * @description Base URL for the xAI API (version 1). All endpoints are relative to this.
+ * @type {string}
  */
 const BASE_URL = 'https://api.x.ai/v1';
 
 /**
  * @constant {string} TMP_DIR
- * @description Local directory where generated images and videos are saved.
+ * @description Absolute path to the local directory where generated images and videos are saved.
+ * The directory is created automatically (recursively) if it does not exist.
+ * Location: `<process.cwd()>/.cache/xai/`
+ * @type {string}
  */
 const TMP_DIR = path.join(process.cwd(), '.cache', 'xai');
 
-import { request as doRequest } from '@j-o-r/apiserver';
-import fs from 'fs/promises';
-import path from 'path';
-
 /**
  * Builds authenticated headers for xAI requests.
  *
- * @returns {Object} Headers containing Authorization Bearer token.
- * @throws {Error} If `XAI_API_KEY` environment variable is not set.
+ * Requires the `XAIKEY` environment variable to be set.
+ * Throws a descriptive error if the key is missing.
+ *
+ * @returns {Object} Headers object containing `Authorization: Bearer <key>` and `Content-Type: application/json`.
+ * @throws {Error} If `process.env.XAIKEY` is not set.
  */
 const getHeaders = () => {
   if (!process.env.XAIKEY) {
@@ -47,23 +75,35 @@ const getHeaders = () => {
 };
 
 /**
- * Ensures the temporary directory for media files exists.
+ * Ensures the temporary directory (`TMP_DIR`) for media files exists.
+ *
+ * Creates the directory recursively if needed. Safe to call multiple times.
  *
  * @async
- * @returns {Promise<void>}
+ * @returns {Promise<void>} Resolves when the directory is guaranteed to exist.
  */
 async function ensureTmpDir() {
   await fs.mkdir(TMP_DIR, { recursive: true });
 }
 
 /**
- * Saves image or video data (URL, base64, Buffer, etc.) to a local file.
+ * Saves image or video data to a local file in `TMP_DIR`.
+ *
+ * Supports multiple input formats:
+ * - Remote HTTP(S) URL (auto-downloads)
+ * - Base64 string (plain or data URI)
+ * - Node.js `Buffer`
+ * - `Blob` or `ArrayBuffer`
+ *
+ * Automatically creates the target directory if necessary.
+ * Filenames are timestamped to avoid collisions.
  *
  * @async
  * @param {string|Buffer|Blob|ArrayBuffer} data - Media content to save.
- * @param {string} [filenamePrefix='xai-media'] - Prefix for the saved file.
- * @param {string} [ext='png'] - File extension.
+ * @param {string} [filenamePrefix='xai-media'] - Prefix for the generated filename.
+ * @param {string} [ext='png'] - File extension (e.g. 'png', 'jpg', 'mp4').
  * @returns {Promise<string>} Absolute path to the saved file.
+ * @throws {Error} On unsupported data type, download failure, or write error.
  */
 async function saveMediaToLocal(data, filenamePrefix = 'xai-media', ext = 'png') {
   await ensureTmpDir();
@@ -95,12 +135,20 @@ async function saveMediaToLocal(data, filenamePrefix = 'xai-media', ext = 'png')
 }
 
 /**
- * Prepares an image input into the format expected by xAI.
- * Accepts URLs, base64 data URIs, local file paths, Buffers, or Blobs.
+ * Prepares an image input into the format expected by the xAI API:
+ * `{ url: string, type: 'image_url' }`
+ *
+ * Accepts a wide variety of inputs and normalizes them:
+ * - Public HTTP(S) URL → passed through
+ * - Base64 data URI (`data:image/...`) → passed through
+ * - Local filesystem path → read and converted to base64 data URI
+ * - `Buffer` → converted to PNG base64 data URI
+ * - `Blob` → converted to PNG base64 data URI
  *
  * @async
- * @param {string|Buffer|Blob} imageInput - Image source.
- * @returns {Promise<Object>} Object with `url` and `type`.
+ * @param {string|Buffer|Blob} imageInput - Image source (URL, path, base64, Buffer, or Blob).
+ * @returns {Promise<Object>} Object with `url` (string) and `type: 'image_url'`.
+ * @throws {Error} If input is missing or of an unsupported type.
  */
 async function prepareImageInput(imageInput) {
   if (!imageInput) throw new Error('Image input is required');
@@ -145,21 +193,56 @@ async function prepareImageInput(imageInput) {
    ============================================================ */
 
 /**
- * Generates one or more images from a text prompt using Grok Imagine.
+ * Generates one or more images from a text prompt using Grok Imagine models.
+ *
+ * **Supported models** (current):
+ * - `grok-imagine-image-quality` — Recommended primary model.
+ * - `grok-imagine-image` — Alternative image model.
+ *
+ * Default: `grok-imagine-image-quality`.
+ *
+ * Supported features:
+ * - Up to 10 images per request (`n`)
+ * - Custom aspect ratios (see `image.to.generation.md` for the full table)
+ * - Resolutions: `1k` or `2k`
+ * - Response formats: `url` (temporary public URL) or `b64_json` (base64)
+ *
+ * All generated images are automatically saved to the local `.cache/xai/` directory.
+ * The function returns both the local path and the original API response data.
  *
  * @async
  * @function generateImage
- * @param {string} prompt - Detailed text prompt describing the desired image.
+ * @param {string} prompt - Detailed text prompt describing the desired image(s). Required.
  * @param {Object} [options={}] - Optional generation parameters.
- * @param {string} [options.model='grok-imagine-image-quality'] - Model to use.
- * @param {number} [options.n=1] - Number of images to generate (1–10).
- * @param {string} [options.response_format='url'] - `'url'` or `'b64_json'`.
- * @returns {Promise<Object>} Result containing `local_path`, `url` (or `base64`), and metadata.
- * @throws {Error} On missing prompt or API errors.
+ * @param {string} [options.model='grok-imagine-image-quality'] - Model identifier. Supported values: `grok-imagine-image-quality` (recommended) or `grok-imagine-image`.
+ * @param {number} [options.n=1] - Number of images to generate. Range: 1–10. Default: 1.
+ * @param {string} [options.response_format='url'] - `'url'` (default) or `'b64_json'`.
+ * @param {string} [options.aspect_ratio] - Desired aspect ratio (e.g. `'16:9'`, `'1:1'`, `'auto'`).
+ * @param {string} [options.resolution] - Output resolution (`'1k'` or `'2k'`).
+ * @returns {Promise<Object>} Result object containing:
+ *   - `local_path` (string) – absolute path to the saved file
+ *   - `url` (string, if response_format=url) – temporary public URL
+ *   - `base64` (string, if response_format=b64_json)
+ *   - `revised_prompt` (string) – model-revised version of the prompt (if provided)
+ *   - `raw` (Object) – full original API response
+ * @throws {Error} If `prompt` is missing/invalid, or on any API/network error.
  *
  * @example
+ * // Basic usage (uses recommended model)
  * const result = await generateImage("A futuristic city at night");
  * console.log(result.local_path);
+ *
+ * @example
+ * // Multiple images with custom aspect ratio and resolution
+ * const results = await generateImage("Mountain landscape at sunrise", {
+ *   n: 4,
+ *   aspect_ratio: "16:9",
+ *   resolution: "2k"
+ * });
+ *
+ * @example
+ * // Using the alternative model
+ * const result = await generateImage("...", { model: "grok-imagine-image" });
  */
 async function generateImage(prompt, options = {}) {
   if (!prompt || typeof prompt !== 'string') {
@@ -174,6 +257,10 @@ async function generateImage(prompt, options = {}) {
     // Note: "size" is not supported by the xAI Grok Imagine API
   };
 
+  // Add optional params if provided
+  if (options.aspect_ratio) body.aspect_ratio = options.aspect_ratio;
+  if (options.resolution) body.resolution = options.resolution;
+
   const headers = getHeaders();
   const res = await doRequest(`${BASE_URL}/images/generations`, 'POST', headers, body);
 
@@ -213,27 +300,49 @@ async function generateImage(prompt, options = {}) {
 
 /**
  * Edits one or more images using a natural language prompt.
- * Supports up to 3 reference images for compositing, style transfer, or multi-subject scenes.
+ *
+ * Supports up to 3 reference images for advanced compositing, style transfer,
+ * multi-subject scenes, or object insertion/removal.
+ *
+ * The model analyzes the provided image(s) and applies the edits described in the prompt.
+ *
+ * **Official API payload (per current xAI Inference API spec)**:
+ * - Single image: `"image": { "url": "...", "type": "image_url" }`
+ * - Multiple images (up to 3): `"images": [ { "url": "...", "type": "image_url" }, ... ]`
+ *   (array of objects — **not** `image_urls`)
+ *
+ * When using multiple images, refer to them in the prompt as <IMAGE_0>, <IMAGE_1>, <IMAGE_2>, etc.
+ *
+ * **Supported models** (same as generation):
+ * - `grok-imagine-image-quality` (recommended)
+ * - `grok-imagine-image`
+ *
+ * All output images are automatically saved locally.
  *
  * @async
  * @function editImage
- * @param {string} prompt - Description of the desired edit.
- * @param {string|Buffer|Blob|Array<string|Buffer|Blob>} imageInputs - One or more images (URL, path, base64, Buffer, or Blob).
+ * @param {string} prompt - Natural language description of the desired edit(s). Required.
+ * @param {string|Buffer|Blob|Array<string|Buffer|Blob>} imageInputs - One or more reference images.
+ *        Accepts URLs, local paths, base64, Buffers, or Blobs. **Maximum: 3 images**.
  * @param {Object} [options={}] - Optional parameters.
- * @param {string} [options.model='grok-imagine-image-quality']
- * @param {number} [options.n=1]
- * @param {string} [options.response_format='url']
- * @returns {Promise<Object>} Result with edited image.
- * @throws {Error} If more than 3 images are provided or on API error.
+ * @param {string} [options.model='grok-imagine-image-quality'] - Model identifier. Supported values: `grok-imagine-image-quality` (recommended) or `grok-imagine-image`.
+ * @param {number} [options.n=1] - Number of output images. Range: 1–10. Default: 1.
+ * @param {string} [options.response_format='url'] - `'url'` or `'b64_json'`.
+ * @param {string} [options.aspect_ratio] - Desired aspect ratio for output.
+ * @param {string} [options.resolution] - Output resolution (`'1k'` or `'2k'`).
+ * @returns {Promise<Object>} Result object (same shape as `generateImage`):
+ *   - `local_path`, `url`/`base64`, `revised_prompt`, `raw`
+ * @throws {Error} If prompt or imageInputs are missing, more than 3 images are supplied,
+ *                 or on API/network error.
  *
  * @example
- * // Single image edit
+ * // Single-image edit (recommended model)
  * const result = await editImage("Make this a pencil sketch", "./photo.png");
  *
  * @example
  * // Multi-image editing (up to 3)
  * const result = await editImage(
- *   "Combine these two people into one scene",
+ *   "Combine <IMAGE_0> and <IMAGE_1> into one scene with a city background",
  *   ["./person1.png", "./person2.png"]
  * );
  */
@@ -252,11 +361,22 @@ async function editImage(prompt, imageInputs, options = {}) {
   const body = {
     model: options.model || 'grok-imagine-image-quality',
     prompt,
-    image: preparedImages.length === 1 ? preparedImages[0] : preparedImages,
     n: options.n || 1,
     response_format: options.response_format || 'url'
   };
 
+  if (preparedImages.length === 1) {
+    // Single image: object form (official docs example)
+    body.image = preparedImages[0];
+  } else {
+    // Multi-image (2–3): array of objects under the official `images` field
+    // (per current Inference API spec — not `image_urls`)
+    body.images = preparedImages;
+  }
+
+  if (options.aspect_ratio) body.aspect_ratio = options.aspect_ratio;
+  if (options.resolution) body.resolution = options.resolution;
+
   const headers = getHeaders();
   const res = await doRequest(`${BASE_URL}/images/edits`, 'POST', headers, body);
 
@@ -294,7 +414,32 @@ async function editImage(prompt, imageInputs, options = {}) {
    INTERNAL: Poll video result
    ============================================================ */
 
-async function _pollVideoResult(requestId, maxAttempts = 60, intervalMs = 5000) {
+/**
+ * Polls the xAI video status endpoint until generation completes or fails.
+ *
+ * This is an internal helper used by `generateVideo()`, but it is exported for
+ * advanced use cases where you want manual control over polling parameters.
+ *
+ * The xAI video endpoint returns `status: 'done'`, `'failed'`, or `'expired'`.
+ * On success it also provides `video.url`.
+ *
+ * **Timeout note**: Video generation can be slow. The default `intervalMs` was
+ * increased (and the function exported) to give callers more flexibility.
+ * Recommended values: `intervalMs` 15000–30000, `maxAttempts` 60+ for longer videos.
+ *
+ * @async
+ * @function pollVideoResult
+ * @param {string} requestId - The `request_id` returned from a `/videos/generations` call. Required.
+ * @param {number} [maxAttempts=60] - Maximum number of polling attempts. Default: 60.
+ * @param {number} [intervalMs=15000] - Milliseconds to wait between polls. Default: 15000.
+ * @returns {Promise<Object>} Result containing:
+ *   - `local_path` (string) – path to the saved MP4
+ *   - `url` (string) – public video URL
+ *   - `status: 'done'`
+ *   - `raw` (Object) – full response
+ * @throws {Error} On failure/expiration status, missing request_id, or polling timeout.
+ */
+async function pollVideoResult(requestId, maxAttempts = 60, intervalMs = 15000) {
   if (!requestId) throw new Error('Video request_id is required');
 
   const headers = getHeaders();
@@ -316,14 +461,14 @@ async function _pollVideoResult(requestId, maxAttempts = 60, intervalMs = 5000)
       }
 
       if (data.status === 'failed' || data.status === 'expired') {
-        throw new Error(`Video generation ${data.status}: ${JSON.stringify(data)}`);
+        throw new Error(`Video generation ${data.status}: ${JSON.stringify(data)} request: ${requestId}`);
       }
     }
 
     await new Promise(resolve => setTimeout(resolve, intervalMs));
   }
 
-  throw new Error(`Timeout polling video request ${requestId}`);
+  throw new Error(`Timeout polling video request: ${requestId}`);
 }
 
 /* ============================================================
@@ -331,28 +476,52 @@ async function _pollVideoResult(requestId, maxAttempts = 60, intervalMs = 5000)
    ============================================================ */
 
 /**
- * Generates a video from a still image and text prompt.
- * This function is fully automatic — it submits the request and polls internally
- * until the video is ready before returning.
+ * Generates a video from a still image + text motion prompt.
+ *
+ * This function is **fully automatic**: it posts to `/videos/generations` and then
+ * internally calls `pollVideoResult()` until the video is ready.
+ *
+ * **Supported model**: Only `grok-imagine-video` (the sole model for image-to-video generation).
+ *
+ * The provided image becomes the first frame; the prompt describes the desired motion/animation.
+ * Supports public URLs or base64 data URIs for the source image.
+ *
+ * Video parameters (from official docs):
+ * - `duration`: 1–15 seconds (affects pricing)
+ * - `aspect_ratio`, `resolution`
+ *
+ * **Important**: Video generation can take a long time and is prone to polling timeouts.
+ * Use the exported `pollVideoResult()` directly with higher `intervalMs`/`maxAttempts`
+ * if you encounter frequent timeouts.
  *
  * @async
  * @function generateVideo
- * @param {string} prompt - Description of the desired motion or animation.
- * @param {string|Buffer|Blob} imageInput - Source image (URL, path, base64, Buffer, or Blob).
+ * @param {string} prompt - Description of the desired motion or animation. Required.
+ * @param {string|Buffer|Blob} imageInput - Source image (URL, local path, base64, Buffer, or Blob). Required.
  * @param {Object} [options={}] - Optional video parameters.
- * @param {number} [options.duration=8] - Video duration in seconds.
- * @param {string} [options.aspect_ratio='16:9'] - Aspect ratio.
+ * @param {string} [options.model='grok-imagine-video'] - Model identifier (only `grok-imagine-video` is supported).
+ * @param {number} [options.duration=8] - Video length in seconds (1–15). Default: 8.
+ * @param {string} [options.aspect_ratio='16:9'] - Aspect ratio for the video.
  * @param {string} [options.resolution='720p'] - Output resolution.
- * @returns {Promise<Object>} Result containing `local_path` and `url` of the generated video.
- * @throws {Error} On missing inputs or generation failure.
+ * @returns {Promise<Object>} Result containing `local_path`, `url`, `status: 'done'`, and `raw`.
+ * @throws {Error} If prompt or imageInput is missing, or on generation failure/timeout.
  *
  * @example
+ * // Basic usage with public image URL
  * const result = await generateVideo(
  *   "Make the water crash down and slowly pan out",
  *   "https://example.com/waterfall.png",
  *   { duration: 12 }
  * );
  * console.log(result.local_path);
+ *
+ * @example
+ * // Using a local file with custom aspect ratio
+ * const result = await generateVideo(
+ *   "Animate the character walking forward",
+ *   "./character.png",
+ *   { duration: 10, aspect_ratio: "9:16" }
+ * );
  */
 async function generateVideo(prompt, imageInput, options = {}) {
   if (!prompt) throw new Error('generateVideo() requires a prompt');
@@ -382,12 +551,13 @@ async function generateVideo(prompt, imageInput, options = {}) {
     throw new Error('No request_id returned from video generation');
   }
 
-  // Automatically poll until ready
-  return await _pollVideoResult(request_id);
+  // Automatically poll until ready (uses updated defaults in pollVideoResult)
+  return await pollVideoResult(request_id);
 }
 
 export {
   generateImage,
   editImage,
-  generateVideo
-};
+  generateVideo,
+  pollVideoResult
+};