@torqlab/generate-activity-image 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TORQ Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+[![Publish](https://github.com/torqlab/generate-activity-image/actions/workflows/publish.yml/badge.svg)](https://github.com/torqlab/generate-activity-image/actions/workflows/publish.yml)
+
+# @torqlab/generate-activity-image
+
+AI-powered image generation for athletic activities using Pollinations.ai with automatic retry logic, fallback support, and comprehensive error handling.
+
+This package provides a robust interface for generating creative images from text prompts describing activities. It handles retries automatically, falls back to default prompts on failure, and returns images as base64-encoded data URLs for easy integration.
+
+## Install
+
+Published to NPM.
+
+```bash
+npm i @torqlab/generate-activity-image
+```
+
+Or with Bun:
+
+```bash
+bun add @torqlab/generate-activity-image
+```
+
+## Quick start
+
+```ts
+import generateActivityImage from '@torqlab/generate-activity-image';
+import type {
+  GenerateActivityImageInput,
+  GenerateActivityImageOutput,
+} from '@torqlab/generate-activity-image';
+
+const input: GenerateActivityImageInput = {
+  prompt: 'A runner on a mountain trail at sunset, dynamic motion, vibrant colors',
+  defaultPrompt: 'A person running outdoors',
+  provider: 'pollinations',
+};
+
+const result: GenerateActivityImageOutput = await generateActivityImage(input);
+
+console.log('Image generated successfully');
+console.log('Data URL:', result.imageData.substring(0, 50) + '...');
+console.log('Used fallback:', result.fallback);
+console.log('Attempts:', result.attempts);
+```
+
+## Features
+
+- **AIpowered Image Generation**: Uses Pollinations.ai for high-quality image generation from text prompts
+- **Automatic Retries**: Built-in retry logic with automatic fallback to default prompts
+- **Base64 Data URLs**: Returns images as base64-encoded `data:image/png;base64,...` URLs
+- **Provider Pattern**: Extensible provider architecture for adding new image generation services
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **Error Handling**: Graceful error handling with fallback mechanisms
+- **Zero Dependencies**: No external runtime dependencies
+- **Configurable**: Support for custom prompts, retry attempts, and provider selection
+
+## API Reference
+
+### `generateActivityImage(input)`
+
+Generate an image from a text prompt with automatic retry and fallback.
+
+#### Parameters
+
+```ts
+interface GenerateActivityImageInput {
+  // Text prompt for image generation (max 1000 characters)
+  prompt: string;
+
+  // Default/fallback prompt (used if main prompt fails)
+  defaultPrompt: string;
+
+  // Number of retry attempts (optional)
+  attempts?: number;
+
+  // Image generation provider (optional, defaults to 'pollinations')
+  provider?: GenerateActivityImageProviderName;
+
+  // API keys for providers (optional)
+  providerApiKeys?: GenerateActivityImageProviderApiKeys;
+}
+```
+
+#### Returns
+
+```ts
+interface GenerateActivityImageOutput {
+  // Base64-encoded image data URL
+  imageData: string;
+
+  // Whether fallback prompt was used
+  fallback: boolean;
+
+  // Number of retry attempts performed
+  attempts: number;
+}
+```
+
+#### Example
+
+```ts
+const result = await generateActivityImage({
+  prompt: 'A cyclist riding through a forest at golden hour',
+  defaultPrompt: 'A person cycling outdoors',
+  provider: 'pollinations',
+  attempts: 3,
+});
+
+if (result.fallback) {
+  console.log('Used fallback prompt after retries');
+}
+
+// Use result.imageData in an image element
+document.getElementById('activity-image').src = result.imageData;
+```
+
+## Providers
+
+### Pollinations (Default)
+
+Free, unlimited image generation via [Pollinations.ai](https://pollinations.ai).
+
+- **Model**: Flux (best for illustrations and balanced quality)
+- **Cost**: Free
+- **Rate Limiting**: None
+- **Authentication**: Optional API key
+
+#### Supported Models
+
+- `flux` (default, best for illustrations)
+- `seedream` (excellent prompt understanding)
+- `gpt-image-large` (photorealism)
+- `kontext` (context-aware)
+
+The model is configurable via code customization.
+
+## Constants
+
+```ts
+import {
+  GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH,
+  GENERATE_ACTIVITY_IMAGE_MAX_RETRIES,
+  } from '@torqlab/generate-activity-image';
+
+// Maximum prompt length in characters
+console.log(GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH); // 1000
+
+// Maximum number of retries
+console.log(GENERATE_ACTIVITY_IMAGE_MAX_RETRIES); // 2
+```
+
+## Type Definitions
+
+```ts
+// Supported provider names
+export type GenerateActivityImageProviderName = 'pollinations';
+
+// API keys configuration
+export interface GenerateActivityImageProviderApiKeys {
+  pollinations?: string;
+}
+
+// Input configuration
+export interface GenerateActivityImageInput {
+  prompt: string;
+  defaultPrompt: string;
+  attempts?: number;
+  provider?: GenerateActivityImageProviderName;
+  providerApiKeys?: GenerateActivityImageProviderApiKeys;
+}
+
+// Output result
+export interface GenerateActivityImageOutput {
+  imageData: string;
+  fallback: boolean;
+  attempts: number;
+}
+
+// Provider function type
+export type GenerateActivityImageProvider = (prompt: string, apiKey?: string) => Promise<string>;
+```
+
+## Error Handling
+
+The package provides comprehensive error handling with automatic fallback:
+
+```ts
+import generateActivityImage from '@torqlab/generate-activity-image';
+
+try {
+  const result = await generateActivityImage({
+    prompt: 'A runner on a scenic trail',
+    defaultPrompt: 'A person running',
+  });
+
+  if (result.fallback) {
+    console.log('Image generated using fallback prompt');
+    console.log('Prompt exceeded length or generation failed');
+  }
+} catch (error) {
+  console.error('Image generation failed:', error);
+  // Handle error appropriately
+}
+```
+
+## Behavior
+
+### Generation Flow
+
+1. Validate prompt length (max 1000 characters)
+2. Attempt generation with original prompt
+3. On failure, retry with default prompt (up to 2 retries)
+4. Return generated image as base64 data URL
+5. If all retries fail, use fallback prompt for final attempt
+6. Always returns a valid response (never throws if fallback succeeds)
+
+### Retry Logic
+
+- **Attempt 1**: Original prompt
+- **Attempt 2**: Default prompt (if original fails)
+- **Attempt 3**: Default prompt again (if Attempt 2 fails)
+- **Fallback**: Uses default prompt if all retries exhausted
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Issues and pull requests are welcome on [GitHub](https://github.com/torqlab/generate-activity-image).

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH = 1000;
+export declare const GENERATE_ACTIVITY_IMAGE_MAX_RETRIES = 2;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yCAAyC,OAAO,CAAC;AAE9D,eAAO,MAAM,mCAAmC,IAAI,CAAC"}

package/dist/generate-activity-image.d.ts

@@ -0,0 +1,35 @@
+import { GenerateActivityImageInput, GenerateActivityImageOutput } from './types';
+/**
+ * Generates activity image using configured AI provider.
+ *
+ * Provider is controlled by IMAGE_PROVIDER environment variable:
+ * - 'pollinations' (default): Free, unlimited Pollinations.ai
+ *
+ * Implements retry logic with prompt simplification and fallback mechanism.
+ * Attempts image generation up to GENERATE_ACTIVITY_IMAGE_MAX_RETRIES times, simplifying the prompt
+ * on each retry. If all retries fail, uses a safe fallback prompt. Images are
+ * downloaded from the provider and returned as base64-encoded data URLs.
+ *
+ * Generation process:
+ * 1. Get configured provider based on IMAGE_PROVIDER env var (defaults to Pollinations)
+ * 2. Validate prompt text length (max 600 characters)
+ * 3. Attempt generation with original prompt
+ * 4. On failure, retry with simplified prompt (max 2 retries)
+ * 5. If all retries fail, use fallback prompt
+ * 6. Images are downloaded from provider and returned as base64 data URLs
+ * 7. Always returns a valid base64-encoded image data URL
+ *
+ * @param {GenerateActivityImageInput} input - Image generation input with prompt
+ * @returns {Promise<GenerateActivityImageOutput>} Promise resolving to generated image data and metadata
+ * @throws {Error} Throws error if generation fails
+ *
+ * @example
+ * ```typescript
+ * const result = await generateImage({ prompt });
+ * console.log('Image data:', result.imageData);
+ * console.log('Used fallback:', result.fallback);
+ * ```
+ */
+declare const generateActivityImage: ({ prompt, defaultPrompt, provider, providerApiKeys, attempts, }: GenerateActivityImageInput) => Promise<GenerateActivityImageOutput>;
+export default generateActivityImage;
+//# sourceMappingURL=generate-activity-image.d.ts.map

package/dist/generate-activity-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-activity-image.d.ts","sourceRoot":"","sources":["../generate-activity-image.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC1B,2BAA2B,EAE5B,MAAM,SAAS,CAAC;AA4CjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,QAAA,MAAM,qBAAqB,GAAU,iEAMlC,0BAA0B,KAAG,OAAO,CAAC,2BAA2B,CAuClE,CAAC;AAEF,eAAe,qBAAqB,CAAC"}

package/dist/index.cjs

@@ -0,0 +1,162 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// providers/pollinations/constants.ts
+var BASE_URL = "https://gen.pollinations.ai/image/", MODEL = "flux", PROMPT_ENHANCER = "side view, natural human anatomy, natural and clear eyes, attractive face, proportional arms and legs, symmetrical joints, clean lines, soft natural lighting, professional illustration", NEGATIVE_PROMPT = "distorted or warped eyes, twisted joints, distorted feet, unrealistic pose, distorted or warped faces, warped or distorted eyes, extra limbs, malformed or distorted hands, blurry, low quality, pixelated, ugly, deformed body, disfigured, bad or broken anatomy, bad proportions, extra fingers, missing fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, noise, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, mutated hands, out of focus, long neck, long body, logo, watermark", BASE_64_PREFIX = "data:image/png;base64,", IMAGE_WIDTH = 1024, IMAGE_HEIGHT = 1024;
+
+// providers/pollinations/pollinations.ts
+var getSeed = () => String(Math.floor(Math.random() * 1e6)), getUrl = (prompt) => {
+  const promptEnhanced = `${PROMPT_ENHANCER}, ${prompt}`;
+  const url = new URL(`${BASE_URL}${encodeURIComponent(promptEnhanced)}`);
+  url.searchParams.set("width", String(IMAGE_WIDTH));
+  url.searchParams.set("height", String(IMAGE_HEIGHT));
+  url.searchParams.set("model", MODEL);
+  url.searchParams.set("nologo", "true");
+  url.searchParams.set("enhance", "true");
+  url.searchParams.set("negative", encodeURIComponent(NEGATIVE_PROMPT));
+  url.searchParams.set("seed", getSeed());
+  return url.toString();
+}, pollinations = async (prompt, apiKey) => {
+  const url = getUrl(prompt);
+  const response = await fetch(url, {
+    ...apiKey && {
+      headers: {
+        Authorization: `Bearer ${apiKey}`
+      }
+    }
+  });
+  if (response.ok) {
+    const imageBuffer = await response.arrayBuffer();
+    const base64 = Buffer.from(imageBuffer).toString("base64");
+    return `${BASE_64_PREFIX}${base64}`;
+  } else {
+    throw new Error(`Pollinations API error: ${response.statusText}`);
+  }
+}, pollinations_default;
+var init_pollinations = __esm(() => {
+  pollinations_default = pollinations;
+});
+
+// providers/pollinations/index.ts
+var exports_pollinations = {};
+__export(exports_pollinations, {
+  default: () => pollinations_default
+});
+var init_pollinations2 = __esm(() => {
+  init_pollinations();
+});
+
+// index.ts
+var exports_generate_activity_image = {};
+__export(exports_generate_activity_image, {
+  default: () => generate_activity_image_default,
+  GENERATE_ACTIVITY_IMAGE_MAX_RETRIES: () => GENERATE_ACTIVITY_IMAGE_MAX_RETRIES,
+  GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH: () => GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH
+});
+module.exports = __toCommonJS(exports_generate_activity_image);
+
+// providers/get-provider.ts
+var getProvider = (providerName = "pollinations", providerApiKeys) => {
+  switch (providerName) {
+    case "pollinations": {
+      return async (prompt) => {
+        const { default: pollinations2 } = await Promise.resolve().then(() => (init_pollinations2(), exports_pollinations));
+        return pollinations2(prompt, providerApiKeys?.pollinations);
+      };
+    }
+    default: {
+      throw new Error(`Unknown image generation provider: ${String(providerName)}.`);
+    }
+  }
+};
+var get_provider_default = getProvider;
+// constants.ts
+var GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH = 1000;
+var GENERATE_ACTIVITY_IMAGE_MAX_RETRIES = 2;
+
+// generate-activity-image.ts
+var attemptGeneration = async (prompt, defaultPrompt, attempt, maxAttempts, providerName, providerApiKeys) => {
+  const provider = get_provider_default(providerName, providerApiKeys);
+  try {
+    return await provider(prompt);
+  } catch (error) {
+    if (attempt < maxAttempts) {
+      const nextAttempt = attempt + 1;
+      return attemptGeneration(defaultPrompt, defaultPrompt, nextAttempt, maxAttempts, providerName, providerApiKeys);
+    } else {
+      throw error;
+    }
+  }
+};
+var generateActivityImage = async ({
+  prompt,
+  defaultPrompt,
+  provider,
+  providerApiKeys,
+  attempts
+}) => {
+  const isAllowedPromptLength = prompt.length <= GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH;
+  if (isAllowedPromptLength) {
+    try {
+      const imageData = await attemptGeneration(prompt, defaultPrompt, 0, GENERATE_ACTIVITY_IMAGE_MAX_RETRIES, provider, providerApiKeys);
+      return {
+        fallback: false,
+        attempts: attempts ?? 0,
+        imageData
+      };
+    } catch {
+      const run = get_provider_default(provider, providerApiKeys);
+      const fallbackImageData = await run(defaultPrompt);
+      return {
+        imageData: fallbackImageData,
+        fallback: true,
+        attempts: GENERATE_ACTIVITY_IMAGE_MAX_RETRIES
+      };
+    }
+  } else {
+    const run = get_provider_default(provider, providerApiKeys);
+    const fallbackImageData = await run(defaultPrompt);
+    return {
+      imageData: fallbackImageData,
+      fallback: true,
+      attempts: GENERATE_ACTIVITY_IMAGE_MAX_RETRIES
+    };
+  }
+};
+var generate_activity_image_default = generateActivityImage;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from './generate-activity-image';
+export { GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH, GENERATE_ACTIVITY_IMAGE_MAX_RETRIES, } from './constants';
+export type { GenerateActivityImageProvider, GenerateActivityImageProviderName, GenerateActivityImageProviderApiKeys, GenerateActivityImageInput, GenerateActivityImageOutput, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EACL,yCAAyC,EACzC,mCAAmC,GACpC,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,6BAA6B,EAC7B,iCAAiC,EACjC,oCAAoC,EACpC,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,SAAS,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,135 @@
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// providers/pollinations/constants.ts
+var BASE_URL = "https://gen.pollinations.ai/image/", MODEL = "flux", PROMPT_ENHANCER = "side view, natural human anatomy, natural and clear eyes, attractive face, proportional arms and legs, symmetrical joints, clean lines, soft natural lighting, professional illustration", NEGATIVE_PROMPT = "distorted or warped eyes, twisted joints, distorted feet, unrealistic pose, distorted or warped faces, warped or distorted eyes, extra limbs, malformed or distorted hands, blurry, low quality, pixelated, ugly, deformed body, disfigured, bad or broken anatomy, bad proportions, extra fingers, missing fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, noise, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, mutated hands, out of focus, long neck, long body, logo, watermark", BASE_64_PREFIX = "data:image/png;base64,", IMAGE_WIDTH = 1024, IMAGE_HEIGHT = 1024;
+
+// providers/pollinations/pollinations.ts
+var getSeed = () => String(Math.floor(Math.random() * 1e6)), getUrl = (prompt) => {
+  const promptEnhanced = `${PROMPT_ENHANCER}, ${prompt}`;
+  const url = new URL(`${BASE_URL}${encodeURIComponent(promptEnhanced)}`);
+  url.searchParams.set("width", String(IMAGE_WIDTH));
+  url.searchParams.set("height", String(IMAGE_HEIGHT));
+  url.searchParams.set("model", MODEL);
+  url.searchParams.set("nologo", "true");
+  url.searchParams.set("enhance", "true");
+  url.searchParams.set("negative", encodeURIComponent(NEGATIVE_PROMPT));
+  url.searchParams.set("seed", getSeed());
+  return url.toString();
+}, pollinations = async (prompt, apiKey) => {
+  const url = getUrl(prompt);
+  const response = await fetch(url, {
+    ...apiKey && {
+      headers: {
+        Authorization: `Bearer ${apiKey}`
+      }
+    }
+  });
+  if (response.ok) {
+    const imageBuffer = await response.arrayBuffer();
+    const base64 = Buffer.from(imageBuffer).toString("base64");
+    return `${BASE_64_PREFIX}${base64}`;
+  } else {
+    throw new Error(`Pollinations API error: ${response.statusText}`);
+  }
+}, pollinations_default;
+var init_pollinations = __esm(() => {
+  pollinations_default = pollinations;
+});
+
+// providers/pollinations/index.ts
+var exports_pollinations = {};
+__export(exports_pollinations, {
+  default: () => pollinations_default
+});
+var init_pollinations2 = __esm(() => {
+  init_pollinations();
+});
+
+// providers/get-provider.ts
+var getProvider = (providerName = "pollinations", providerApiKeys) => {
+  switch (providerName) {
+    case "pollinations": {
+      return async (prompt) => {
+        const { default: pollinations2 } = await Promise.resolve().then(() => (init_pollinations2(), exports_pollinations));
+        return pollinations2(prompt, providerApiKeys?.pollinations);
+      };
+    }
+    default: {
+      throw new Error(`Unknown image generation provider: ${String(providerName)}.`);
+    }
+  }
+};
+var get_provider_default = getProvider;
+// constants.ts
+var GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH = 1000;
+var GENERATE_ACTIVITY_IMAGE_MAX_RETRIES = 2;
+
+// generate-activity-image.ts
+var attemptGeneration = async (prompt, defaultPrompt, attempt, maxAttempts, providerName, providerApiKeys) => {
+  const provider = get_provider_default(providerName, providerApiKeys);
+  try {
+    return await provider(prompt);
+  } catch (error) {
+    if (attempt < maxAttempts) {
+      const nextAttempt = attempt + 1;
+      return attemptGeneration(defaultPrompt, defaultPrompt, nextAttempt, maxAttempts, providerName, providerApiKeys);
+    } else {
+      throw error;
+    }
+  }
+};
+var generateActivityImage = async ({
+  prompt,
+  defaultPrompt,
+  provider,
+  providerApiKeys,
+  attempts
+}) => {
+  const isAllowedPromptLength = prompt.length <= GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH;
+  if (isAllowedPromptLength) {
+    try {
+      const imageData = await attemptGeneration(prompt, defaultPrompt, 0, GENERATE_ACTIVITY_IMAGE_MAX_RETRIES, provider, providerApiKeys);
+      return {
+        fallback: false,
+        attempts: attempts ?? 0,
+        imageData
+      };
+    } catch {
+      const run = get_provider_default(provider, providerApiKeys);
+      const fallbackImageData = await run(defaultPrompt);
+      return {
+        imageData: fallbackImageData,
+        fallback: true,
+        attempts: GENERATE_ACTIVITY_IMAGE_MAX_RETRIES
+      };
+    }
+  } else {
+    const run = get_provider_default(provider, providerApiKeys);
+    const fallbackImageData = await run(defaultPrompt);
+    return {
+      imageData: fallbackImageData,
+      fallback: true,
+      attempts: GENERATE_ACTIVITY_IMAGE_MAX_RETRIES
+    };
+  }
+};
+var generate_activity_image_default = generateActivityImage;
+export {
+  generate_activity_image_default as default,
+  GENERATE_ACTIVITY_IMAGE_MAX_RETRIES,
+  GENERATE_ACTIVITY_IMAGE_MAX_PROMPT_LENGTH
+};

package/dist/providers/get-provider.d.ts

@@ -0,0 +1,20 @@
+import { GenerateActivityImageProvider, GenerateActivityImageProviderApiKeys, GenerateActivityImageProviderName } from '../types';
+/**
+ * Gets the configured image generation provider.
+ *
+ * Supported providers:
+ * - 'pollinations' (default): Free, unlimited, no authentication.
+ *
+ * @param {GenerateActivityImageProviderName} [providerName] - Image generation provider name (`pollinations` by default).
+ * @param {GenerateActivityImageProviderApiKeys} [providerApiKeys] - Optional provider API keys.
+ * @returns {GenerateActivityImageProvider} Image generation provider instance.
+ * @throws {Error} Throws if provider name is invalid.
+ *
+ * @example
+ * ```typescript
+ * const provider2 = getProvider('pollinations');
+ * ```
+ */
+declare const getProvider: (providerName?: GenerateActivityImageProviderName, providerApiKeys?: GenerateActivityImageProviderApiKeys) => GenerateActivityImageProvider;
+export default getProvider;
+//# sourceMappingURL=get-provider.d.ts.map

package/dist/providers/get-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-provider.d.ts","sourceRoot":"","sources":["../../providers/get-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,oCAAoC,EACpC,iCAAiC,EAClC,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,WAAW,GACf,eAAc,iCAAkD,EAChE,kBAAkB,oCAAoC,KACrD,6BAaF,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/providers/index.d.ts

@@ -0,0 +1,2 @@
+export { default as getProvider } from './get-provider';
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/providers/pollinations/constants.d.ts

@@ -0,0 +1,36 @@
+export declare const BASE_URL = "https://gen.pollinations.ai/image/";
+/**
+ * Pollinations model for image generation.
+ * Available models:
+ * - `flux` (best for illustrations, balanced quality).
+ * - `seedream` (excellent prompt understanding).
+ * - `gpt-image-large` (photorealism).
+ * - `kontext` (context-aware).
+ */
+export declare const MODEL = "flux";
+/**
+ * Prompt enhancer to improve image quality.
+ *
+ * Pollinations generates poor images by default.
+ * This enhancer helps achieve better results.
+ */
+export declare const PROMPT_ENHANCER = "side view, natural human anatomy, natural and clear eyes, attractive face, proportional arms and legs, symmetrical joints, clean lines, soft natural lighting, professional illustration";
+/**
+ * Negative prompt allows to avoid common image generation issues.
+ * Addresses: distorted faces, extra limbs, malformed hands, blurry images, low quality, and others.
+ * Pollinations generates poor images due to limited resources; negative prompts help mitigate this.
+ */
+export declare const NEGATIVE_PROMPT = "distorted or warped eyes, twisted joints, distorted feet, unrealistic pose, distorted or warped faces, warped or distorted eyes, extra limbs, malformed or distorted hands, blurry, low quality, pixelated, ugly, deformed body, disfigured, bad or broken anatomy, bad proportions, extra fingers, missing fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, noise, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, mutated hands, out of focus, long neck, long body, logo, watermark";
+/**
+ * Base64 prefix for PNG images.
+ */
+export declare const BASE_64_PREFIX = "data:image/png;base64,";
+/**
+ * Image width in pixels.
+ */
+export declare const IMAGE_WIDTH = 1024;
+/**
+ * Image height in pixels.
+ */
+export declare const IMAGE_HEIGHT = 1024;
+//# sourceMappingURL=constants.d.ts.map

package/dist/providers/pollinations/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../providers/pollinations/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ,uCAAuC,CAAC;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,SAAS,CAAC;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,eAAe,6LACgK,CAAC;AAE7L;;;;GAIG;AACH,eAAO,MAAM,eAAe,ikBACoiB,CAAC;AAEjkB;;GAEG;AACH,eAAO,MAAM,cAAc,2BAA2B,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;GAEG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC"}

package/dist/providers/pollinations/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './pollinations';
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/pollinations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../providers/pollinations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/providers/pollinations/pollinations.d.ts

@@ -0,0 +1,22 @@
+import { GenerateActivityImageProvider } from '../../types';
+/**
+ * Pollinations.ai image generation provider.
+ *
+ * Completely free, no authentication required.
+ * Uses negative prompts to avoid common image generation issues.
+ *
+ * Supports multiple models:
+ * - `flux` (default, best for illustrations)
+ * - `seedream`
+ * - `gpt-image-large`
+ * - `kontext`
+ *
+ * @param {string} prompt - Text prompt for image generation.
+ * @param {string} [apiKey] - Optional API key (not required for Pollinations).
+ * @returns {Promise<string>} Promise resolving to base64-encoded image data URL (`data:image/png;base64,...`).
+ * @throws {Error} Throws error if generation fails.
+ * @see {@link https://pollinations.ai | Pollinations.ai}
+ */
+declare const pollinations: GenerateActivityImageProvider;
+export default pollinations;
+//# sourceMappingURL=pollinations.d.ts.map

package/dist/providers/pollinations/pollinations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollinations.d.ts","sourceRoot":"","sources":["../../../providers/pollinations/pollinations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAwC5D;;;;;;;;;;;;;;;;;GAiBG;AACH,QAAA,MAAM,YAAY,EAAE,6BAqBnB,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Common interface for all image generation providers.
+ * Generates an image from a text prompt.
+ * @param {string} prompt - Text prompt for image generation.
+ * @param {string} [apiKey] - Optional API key for the provider (if required).
+ * @returns {Promise<string>} Promise resolving to base64-encoded image data URL (`data:image/png;base64,...`).
+ * @throws {Error} Throws error if generation fails.
+ */
+export type GenerateActivityImageProvider = (prompt: string, apiKey?: string) => Promise<string>;
+/**
+ * Supported image generation providers:
+ * - `pollinations`: Free, unlimited, no authentication.
+ */
+export type GenerateActivityImageProviderName = 'pollinations';
+export interface GenerateActivityImageProviderApiKeys {
+    pollinations?: string;
+}
+export interface GenerateActivityImageInput {
+    prompt: string;
+    defaultPrompt: string;
+    attempts?: number;
+    provider?: GenerateActivityImageProviderName;
+    providerApiKeys?: GenerateActivityImageProviderApiKeys;
+}
+export interface GenerateActivityImageOutput {
+    /** Base64-encoded image data URL. */
+    imageData: string;
+    /** Whether fallback was used. */
+    fallback: boolean;
+    /** Number of retry attempts performed. */
+    attempts: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAGjG;;;GAGG;AACH,MAAM,MAAM,iCAAiC,GAAG,cAAc,CAAC;AAE/D,MAAM,WAAW,oCAAoC;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,iCAAiC,CAAC;IAC7C,eAAe,CAAC,EAAE,oCAAoC,CAAC;CACxD;AAED,MAAM,WAAW,2BAA2B;IAC1C,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@torqlab/generate-activity-image",
+  "version": "1.0.0",
+  "description": "AI-powered image generator for athletic activities.",
+  "license": "MIT",
+  "author": {
+    "name": "Bohdan Balov",
+    "email": "balovbohdan@gmail.com",
+    "url": "https://balov.dev"
+  },
+  "keywords": [
+    "ai",
+    "pollinations",
+    "torq"
+  ],
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": "24.x"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/torqlab/generate-activity-image.git"
+  },
+  "homepage": "https://github.com/torqlab/generate-activity-image",
+  "bugs": {
+    "url": "https://github.com/torqlab/generate-activity-image/issues"
+  },
+  "scripts": {
+    "build:types": "bunx tsc -p tsconfig.build.json",
+    "build:esm": "bun build ./index.ts --outfile dist/index.mjs --target node",
+    "build:cjs": "bun build ./index.ts --outfile dist/index.cjs --target node --format cjs",
+    "build": "bun run clean && bun run build:types && bun run build:esm && bun run build:cjs",
+    "test": "bun test",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "prepublishOnly": "bun run build",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15.0",
+    "@types/bun": "^1.1.13",
+    "@types/node": "^25.3.3",
+    "bun": "^1.1.38",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jsdoc": "^50.5.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.15.0"
+  }
+}