hazo_images 1.1.0 → 1.2.0

package/CHANGE_LOG.md

@@ -1,5 +1,20 @@
 # hazo_images Change Log
 
+## 1.2.0 — 2026-05-30
+
+### Added
+- New `hazo_images/runware` sub-export wrapping the Runware REST API.
+  - `createRunwareClient(opts?)` factory — `generateImage(params)` and `getBalance()`.
+  - `assemblePrompts(input)` helper for the prefix + character + image + suffix pattern.
+  - Four `HazoError` subclasses: `RunwareApiError`, `RunwareAuthError`, `RunwareRateLimitError` (carries `retryAfter`), `RunwareValidationError`. All codes are `HAZO_IMAGES_RUNWARE_*`.
+  - API key resolution: `opts.apiKey` → `HAZO_IMAGES_RUNWARE_API_KEY` → `RUNWARE_API_KEY` (legacy).
+  - Outbound HTTP goes through `fetchWithRequestId` from `hazo_core` (first outbound HTTP in this package).
+  - Configurable `baseUrl`, `defaultModel`, `timeoutMs` (default 60s), `fetch` (override for tests), `logger`.
+
+### Migration
+- Extracted verbatim from `14.seo_monitor/lib/runware/{client,resolve-params}.ts`.
+- seo_monitor migrated to consume `hazo_images/runware` in the same release; seo_monitor's old `lib/runware/client.ts` deleted.
+
 ## 1.1.0 (2026-05-29) — Wave 2 standardisation
 
 ### Changed

package/README.md

@@ -153,6 +153,50 @@ interface ProcessImageOptions {
 }
 ```
 
+## Runware (AI image generation)
+
+`hazo_images/runware` wraps the Runware REST API behind a factory client.
+
+```ts
+import { createRunwareClient } from 'hazo_images/runware';
+
+const client = createRunwareClient({
+  // apiKey?: defaults to HAZO_IMAGES_RUNWARE_API_KEY then RUNWARE_API_KEY
+  defaultModel: 'runware:z-image@turbo',
+  timeoutMs: 60_000,
+});
+
+const { imageURL, cost, taskUUID } = await client.generateImage({
+  positivePrompt: 'a chibi explorer with a stopwatch',
+  width: 1024,
+  height: 1024,
+});
+```
+
+### Error classes
+
+| Class | Triggered by | Code(s) |
+|---|---|---|
+| `RunwareApiError` | network fail, 5xx, abort, empty result | `HAZO_IMAGES_RUNWARE_HTTP_FAILURE`, `HAZO_IMAGES_RUNWARE_TIMEOUT`, `HAZO_IMAGES_RUNWARE_EMPTY_RESULT` |
+| `RunwareAuthError` | missing key, 401, 403 | `HAZO_IMAGES_RUNWARE_MISSING_KEY`, `HAZO_IMAGES_RUNWARE_AUTH_FAILED` |
+| `RunwareRateLimitError` | 429 — exposes `retryAfter: number \| null` | `HAZO_IMAGES_RUNWARE_RATE_LIMITED` |
+| `RunwareValidationError` | 400 or `errors[]` in body | upstream code or `HAZO_IMAGES_RUNWARE_BAD_REQUEST` |
+
+### `assemblePrompts`
+
+Generic helper for the prefix + character + image + suffix pattern:
+
+```ts
+import { assemblePrompts } from 'hazo_images/runware';
+
+const { positive, negative } = assemblePrompts({
+  imagePrompt: 'astronaut on mars',
+  masterStylePrefix: 'cinematic,',
+  characterPositive: 'red spacesuit',
+  masterNegative: 'low quality, blurry',
+});
+```
+
 ## Roadmap
 
 | Version | Scope |

package/SETUP_CHECKLIST.md

@@ -58,7 +58,14 @@ const nextConfig = {
 module.exports = nextConfig;
 ```
 
-## 6. (Optional) Drop in `hazo_images_config.ini`
+## 6. (Optional) Environment variables for hazo_images/runware
+
+Only needed if using the `hazo_images/runware` sub-export (Runware REST API client):
+
+- `HAZO_IMAGES_RUNWARE_API_KEY` (preferred) — API key from [runware.ai](https://runware.ai)
+- `RUNWARE_API_KEY` (legacy fallback) — older projects may use this; new code should prefer `HAZO_IMAGES_RUNWARE_API_KEY`
+
+## 7. (Optional) Drop in `hazo_images_config.ini`
 
 The package ships `config/hazo_images_config.ini.sample` with sections
 for `[general]`, `[log.overrides]`, and `[processing]` defaults. Copy
@@ -71,7 +78,7 @@ Per `D-020`, a per-environment overlay file at
 `config/hazo_images_config.<HAZO_ENV>.ini` is layered on top of the
 base file when `HAZO_ENV` is set.
 
-## 7. Verify
+## 8. Verify
 
 ```ts
 import { processImage } from 'hazo_images/server';

package/dist/runware/index.d.ts

@@ -0,0 +1,83 @@
+import { HazoCoreLogger, HazoError } from 'hazo_core';
+
+interface CreateRunwareClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    defaultModel?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    logger?: HazoCoreLogger;
+}
+interface GenerateImageParams {
+    positivePrompt: string;
+    negativePrompt?: string;
+    model?: string;
+    width: number;
+    height: number;
+    numberResults?: number;
+    outputFormat?: 'PNG' | 'JPEG' | 'WEBP';
+    outputType?: 'URL' | 'base64Data';
+}
+interface GenerateImageResult {
+    imageURL?: string;
+    imageBase64Data?: string;
+    cost: number | null;
+    taskUUID: string;
+}
+interface RunwareClient {
+    generateImage(params: GenerateImageParams): Promise<GenerateImageResult>;
+    getBalance(): Promise<number>;
+}
+interface AssemblePromptsInput {
+    imagePrompt: string;
+    masterStylePrefix?: string | null;
+    masterStyleSuffix?: string | null;
+    characterPositive?: string | null;
+    masterNegative?: string | null;
+    characterNegative?: string | null;
+    callNegative?: string | null;
+}
+interface ResolvedPrompts {
+    positive: string;
+    negative: string | undefined;
+}
+
+declare function createRunwareClient(opts?: CreateRunwareClientOptions): RunwareClient;
+
+declare function assemblePrompts(input: AssemblePromptsInput): ResolvedPrompts;
+
+declare const RUNWARE_ERROR_CODES: {
+    readonly MISSING_KEY: "HAZO_IMAGES_RUNWARE_MISSING_KEY";
+    readonly AUTH_FAILED: "HAZO_IMAGES_RUNWARE_AUTH_FAILED";
+    readonly RATE_LIMITED: "HAZO_IMAGES_RUNWARE_RATE_LIMITED";
+    readonly HTTP_FAILURE: "HAZO_IMAGES_RUNWARE_HTTP_FAILURE";
+    readonly TIMEOUT: "HAZO_IMAGES_RUNWARE_TIMEOUT";
+    readonly EMPTY_RESULT: "HAZO_IMAGES_RUNWARE_EMPTY_RESULT";
+    readonly BAD_REQUEST: "HAZO_IMAGES_RUNWARE_BAD_REQUEST";
+    readonly MISSING_MODEL: "HAZO_IMAGES_RUNWARE_MISSING_MODEL";
+};
+type RunwareErrorCode = (typeof RUNWARE_ERROR_CODES)[keyof typeof RUNWARE_ERROR_CODES];
+interface RunwareErrorContext {
+    status?: number;
+    body?: unknown;
+    taskUUID?: string;
+    code?: string;
+    cause?: unknown;
+}
+declare class RunwareApiError extends HazoError {
+    constructor(code: string, message: string, context?: RunwareErrorContext);
+}
+declare class RunwareAuthError extends HazoError {
+    constructor(code: string, message: string, context?: RunwareErrorContext);
+}
+declare class RunwareRateLimitError extends HazoError {
+    retryAfter: number | null;
+    constructor(message: string, context: RunwareErrorContext & {
+        retryAfter: number | null;
+    });
+}
+declare class RunwareValidationError extends HazoError {
+    constructor(code: string, message: string, context?: RunwareErrorContext);
+}
+
+export { type AssemblePromptsInput, type CreateRunwareClientOptions, type GenerateImageParams, type GenerateImageResult, RUNWARE_ERROR_CODES, type ResolvedPrompts, RunwareApiError, RunwareAuthError, type RunwareClient, type RunwareErrorCode, RunwareRateLimitError, RunwareValidationError, assemblePrompts, createRunwareClient };

package/dist/runware/index.js

@@ -0,0 +1,371 @@
+// src/runware/client.ts
+import { fetchWithRequestId, generateRequestId } from "hazo_core";
+
+// src/utils/logger.ts
+import { createLogger } from "hazo_core";
+var console_logger = {
+  info: (m, d) => d ? console.log(`[hazo_images] ${m}`, d) : console.log(`[hazo_images] ${m}`),
+  debug: (m, d) => d ? console.debug(`[hazo_images] ${m}`, d) : console.debug(`[hazo_images] ${m}`),
+  warn: (m, d) => d ? console.warn(`[hazo_images] ${m}`, d) : console.warn(`[hazo_images] ${m}`),
+  error: (m, d) => d ? console.error(`[hazo_images] ${m}`, d) : console.error(`[hazo_images] ${m}`)
+};
+function build_default_logger() {
+  try {
+    return createLogger("hazo_images");
+  } catch {
+    return console_logger;
+  }
+}
+var current_logger = null;
+function get_logger() {
+  if (!current_logger) {
+    current_logger = build_default_logger();
+  }
+  return current_logger;
+}
+
+// src/runware/errors.ts
+import { HazoError } from "hazo_core";
+var RUNWARE_ERROR_CODES = {
+  MISSING_KEY: "HAZO_IMAGES_RUNWARE_MISSING_KEY",
+  AUTH_FAILED: "HAZO_IMAGES_RUNWARE_AUTH_FAILED",
+  RATE_LIMITED: "HAZO_IMAGES_RUNWARE_RATE_LIMITED",
+  HTTP_FAILURE: "HAZO_IMAGES_RUNWARE_HTTP_FAILURE",
+  TIMEOUT: "HAZO_IMAGES_RUNWARE_TIMEOUT",
+  EMPTY_RESULT: "HAZO_IMAGES_RUNWARE_EMPTY_RESULT",
+  BAD_REQUEST: "HAZO_IMAGES_RUNWARE_BAD_REQUEST",
+  MISSING_MODEL: "HAZO_IMAGES_RUNWARE_MISSING_MODEL"
+};
+var RunwareApiError = class extends HazoError {
+  constructor(code, message, context = {}) {
+    super({ code, pkg: "hazo_images", message, context });
+    this.name = "RunwareApiError";
+  }
+};
+var RunwareAuthError = class extends HazoError {
+  constructor(code, message, context = {}) {
+    super({ code, pkg: "hazo_images", message, context });
+    this.name = "RunwareAuthError";
+  }
+};
+var RunwareRateLimitError = class extends HazoError {
+  retryAfter;
+  constructor(message, context) {
+    const { retryAfter, ...rest } = context;
+    super({
+      code: RUNWARE_ERROR_CODES.RATE_LIMITED,
+      pkg: "hazo_images",
+      message,
+      context: { ...rest, retryAfter }
+    });
+    this.name = "RunwareRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var RunwareValidationError = class extends HazoError {
+  constructor(code, message, context = {}) {
+    super({ code, pkg: "hazo_images", message, context });
+    this.name = "RunwareValidationError";
+  }
+};
+
+// src/runware/client.ts
+var DEFAULT_BASE_URL = "https://api.runware.ai/v1";
+var DEFAULT_TIMEOUT_MS = 6e4;
+function resolveApiKey(optsApiKey) {
+  if (optsApiKey) return optsApiKey;
+  if (process.env.HAZO_IMAGES_RUNWARE_API_KEY) return process.env.HAZO_IMAGES_RUNWARE_API_KEY;
+  if (process.env.RUNWARE_API_KEY) return process.env.RUNWARE_API_KEY;
+  throw new RunwareAuthError(
+    RUNWARE_ERROR_CODES.MISSING_KEY,
+    "Runware API key not found. Set HAZO_IMAGES_RUNWARE_API_KEY or RUNWARE_API_KEY, or pass apiKey to createRunwareClient."
+  );
+}
+function createRunwareClient(opts = {}) {
+  const logger = opts.logger ?? get_logger();
+  const cfg = {
+    baseUrl: opts.baseUrl ?? DEFAULT_BASE_URL,
+    defaultModel: opts.defaultModel,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    fetchImpl: opts.fetch ?? fetchWithRequestId,
+    optsApiKey: opts.apiKey,
+    logger
+  };
+  logger.info("runware.client.created", {
+    baseUrl: cfg.baseUrl,
+    defaultModel: cfg.defaultModel ?? null,
+    timeoutMs: cfg.timeoutMs
+  });
+  return {
+    async generateImage(params) {
+      const start = Date.now();
+      const apiKey = resolveApiKey(cfg.optsApiKey);
+      const model = params.model ?? cfg.defaultModel;
+      if (!model) {
+        const err = new RunwareValidationError(
+          RUNWARE_ERROR_CODES.MISSING_MODEL,
+          "Runware generateImage requires a `model` (pass per-call or as defaultModel to createRunwareClient).",
+          { taskUUID: "pre-task" }
+        );
+        cfg.logger.error("runware.generate_image.failed", {
+          errorCode: err.code,
+          errorClass: err.name,
+          durationMs: Date.now() - start
+        });
+        throw err;
+      }
+      const taskUUID = generateRequestId();
+      cfg.logger.info("runware.generate_image.started", { model, taskUUID });
+      const task = {
+        taskType: "imageInference",
+        taskUUID,
+        positivePrompt: params.positivePrompt,
+        ...params.negativePrompt ? { negativePrompt: params.negativePrompt } : {},
+        model,
+        width: params.width,
+        height: params.height,
+        numberResults: params.numberResults ?? 1,
+        outputFormat: params.outputFormat ?? "PNG",
+        outputType: params.outputType ?? "URL"
+      };
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), cfg.timeoutMs);
+      let res;
+      try {
+        res = await cfg.fetchImpl(cfg.baseUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`
+          },
+          body: JSON.stringify([task]),
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        let thrownErr;
+        if (err instanceof DOMException && err.name === "AbortError") {
+          thrownErr = new RunwareApiError(
+            RUNWARE_ERROR_CODES.TIMEOUT,
+            `Runware request timed out after ${cfg.timeoutMs}ms`,
+            { taskUUID }
+          );
+        } else {
+          thrownErr = new RunwareApiError(
+            RUNWARE_ERROR_CODES.HTTP_FAILURE,
+            "Runware network error",
+            { taskUUID }
+          );
+        }
+        cfg.logger.error("runware.generate_image.failed", {
+          taskUUID,
+          model,
+          errorCode: thrownErr.code,
+          errorClass: thrownErr.name,
+          durationMs: Date.now() - start
+        });
+        throw thrownErr;
+      }
+      clearTimeout(timer);
+      if (!res.ok) {
+        let bodyText;
+        let bodyJson;
+        try {
+          bodyText = await res.clone().text();
+          bodyJson = JSON.parse(bodyText);
+        } catch {
+          bodyJson = bodyText;
+        }
+        const errorRecord = bodyJson?.errors?.[0];
+        let thrownErr;
+        if (res.status === 401 || res.status === 403) {
+          thrownErr = new RunwareAuthError(
+            RUNWARE_ERROR_CODES.AUTH_FAILED,
+            `Runware auth failed (HTTP ${res.status})`,
+            { status: res.status, body: bodyJson, taskUUID }
+          );
+        } else if (res.status === 429) {
+          const ra = res.headers.get("retry-after");
+          const retryAfter = ra && /^\d+$/.test(ra) ? parseInt(ra, 10) : null;
+          thrownErr = new RunwareRateLimitError(`Runware rate limited (HTTP 429)`, {
+            status: 429,
+            body: bodyJson,
+            taskUUID,
+            retryAfter
+          });
+        } else if (res.status === 400 || errorRecord) {
+          thrownErr = new RunwareValidationError(
+            errorRecord?.code ? `HAZO_IMAGES_RUNWARE_${errorRecord.code.toUpperCase()}` : RUNWARE_ERROR_CODES.BAD_REQUEST,
+            errorRecord?.message ?? `Runware validation failed (HTTP ${res.status})`,
+            { status: res.status, body: bodyJson, taskUUID, code: errorRecord?.code }
+          );
+        } else {
+          thrownErr = new RunwareApiError(
+            RUNWARE_ERROR_CODES.HTTP_FAILURE,
+            `Runware HTTP ${res.status}`,
+            { status: res.status, body: bodyJson, taskUUID }
+          );
+        }
+        cfg.logger.error("runware.generate_image.failed", {
+          taskUUID,
+          model,
+          errorCode: thrownErr.code,
+          errorClass: thrownErr.name,
+          durationMs: Date.now() - start
+        });
+        throw thrownErr;
+      }
+      const body = await res.json();
+      const apiErrors = body.errors;
+      if (apiErrors && apiErrors.length > 0) {
+        const firstErr = apiErrors[0];
+        const thrownErr = new RunwareValidationError(
+          firstErr.code ? `HAZO_IMAGES_RUNWARE_${firstErr.code.toUpperCase()}` : RUNWARE_ERROR_CODES.BAD_REQUEST,
+          firstErr.message ?? "Runware returned an API error",
+          { body, taskUUID, code: firstErr.code }
+        );
+        cfg.logger.error("runware.generate_image.failed", {
+          taskUUID,
+          model,
+          errorCode: thrownErr.code,
+          errorClass: thrownErr.name,
+          durationMs: Date.now() - start
+        });
+        throw thrownErr;
+      }
+      const first = body.data?.[0];
+      if (!first?.imageURL && !first?.imageBase64Data) {
+        const thrownErr = new RunwareApiError(
+          RUNWARE_ERROR_CODES.EMPTY_RESULT,
+          "Runware returned no image data",
+          { body, taskUUID }
+        );
+        cfg.logger.error("runware.generate_image.failed", {
+          taskUUID,
+          model,
+          errorCode: thrownErr.code,
+          errorClass: thrownErr.name,
+          durationMs: Date.now() - start
+        });
+        throw thrownErr;
+      }
+      const result = {
+        imageURL: first.imageURL,
+        imageBase64Data: first.imageBase64Data,
+        cost: typeof first.cost === "number" ? first.cost : null,
+        taskUUID
+      };
+      cfg.logger.info("runware.generate_image.completed", {
+        taskUUID,
+        model,
+        cost: result.cost,
+        durationMs: Date.now() - start
+      });
+      return result;
+    },
+    async getBalance() {
+      const start = Date.now();
+      const apiKey = resolveApiKey(cfg.optsApiKey);
+      const taskUUID = generateRequestId();
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), cfg.timeoutMs);
+      let res;
+      try {
+        res = await cfg.fetchImpl(cfg.baseUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`
+          },
+          body: JSON.stringify([{ taskType: "getUser", taskUUID }]),
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof DOMException && err.name === "AbortError") {
+          const thrownErr2 = new RunwareApiError(
+            RUNWARE_ERROR_CODES.TIMEOUT,
+            `Runware getBalance timed out`,
+            { taskUUID }
+          );
+          cfg.logger.error("runware.get_balance.failed", {
+            taskUUID,
+            errorCode: thrownErr2.code,
+            errorClass: thrownErr2.name,
+            durationMs: Date.now() - start
+          });
+          throw thrownErr2;
+        }
+        const thrownErr = new RunwareApiError(
+          RUNWARE_ERROR_CODES.HTTP_FAILURE,
+          "Runware getBalance network error",
+          { taskUUID }
+        );
+        cfg.logger.error("runware.get_balance.failed", {
+          taskUUID,
+          errorCode: thrownErr.code,
+          errorClass: thrownErr.name,
+          durationMs: Date.now() - start
+        });
+        throw thrownErr;
+      }
+      clearTimeout(timer);
+      if (!res.ok) {
+        const thrownErr = new RunwareApiError(
+          RUNWARE_ERROR_CODES.HTTP_FAILURE,
+          `Runware getBalance HTTP ${res.status}`,
+          { status: res.status, taskUUID }
+        );
+        cfg.logger.error("runware.get_balance.failed", {
+          taskUUID,
+          errorCode: thrownErr.code,
+          errorClass: thrownErr.name,
+          durationMs: Date.now() - start
+        });
+        throw thrownErr;
+      }
+      const body = await res.json();
+      const balance = body.data?.[0]?.balance ?? 0;
+      cfg.logger.info("runware.get_balance.completed", {
+        taskUUID,
+        balance,
+        durationMs: Date.now() - start
+      });
+      return balance;
+    }
+  };
+}
+
+// src/runware/prompt.ts
+function assemblePrompts(input) {
+  const {
+    imagePrompt,
+    masterStylePrefix,
+    masterStyleSuffix,
+    characterPositive,
+    masterNegative,
+    characterNegative,
+    callNegative
+  } = input;
+  const positiveParts = [];
+  if (masterStylePrefix) positiveParts.push(masterStylePrefix);
+  if (characterPositive) positiveParts.push(characterPositive);
+  positiveParts.push(imagePrompt);
+  if (masterStyleSuffix) positiveParts.push(masterStyleSuffix);
+  const positive = positiveParts.join(" ");
+  const negativeParts = [];
+  if (masterNegative) negativeParts.push(masterNegative);
+  if (characterNegative) negativeParts.push(characterNegative);
+  if (callNegative) negativeParts.push(callNegative);
+  const negative = negativeParts.length > 0 ? negativeParts.join(", ") : void 0;
+  return { positive, negative };
+}
+export {
+  RUNWARE_ERROR_CODES,
+  RunwareApiError,
+  RunwareAuthError,
+  RunwareRateLimitError,
+  RunwareValidationError,
+  assemblePrompts,
+  createRunwareClient
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_images",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Image processing pipeline for the hazo ecosystem — Sharp wrapper, thumbnail generation, EXIF handling, and hazo_files integration helper",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,11 @@
       "types": "./dist/ui/index.d.ts",
       "import": "./dist/ui/index.js",
       "default": "./dist/ui/index.js"
+    },
+    "./runware": {
+      "types": "./dist/runware/index.d.ts",
+      "import": "./dist/runware/index.js",
+      "default": "./dist/runware/index.js"
     }
   },
   "files": [
@@ -35,7 +40,9 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "test": "node --experimental-vm-modules ../node_modules/jest/bin/jest.js --config jest.config.cjs",
+    "test:watch": "node --experimental-vm-modules ../node_modules/jest/bin/jest.js --config jest.config.cjs --watch"
   },
   "dependencies": {
     "ini": "^4.1.0",
@@ -63,9 +70,13 @@
     }
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.10.0",
     "@types/react": "^19.0.0",
     "hazo_core": "^1.0.0",
+    "jest": "^30.2.0",
+    "jest-environment-node": "^30.2.0",
+    "ts-jest": "^29.4.5",
     "tsup": "^8.0.0",
     "typescript": "^5.7.2"
   },