@juspay/neurolink 8.35.2 → 8.37.0

package/dist/lib/utils/parameterValidation.js

@@ -603,6 +603,232 @@ export function validateVideoGenerationInput(options) {
     return { isValid: errors.length === 0, errors, warnings, suggestions };
 }
 // ============================================================================
+// PPT VALIDATION (Presentation Generation)
+// ============================================================================
+/**
+ * Valid PPT generation options
+ */
+const VALID_PPT_THEMES = [
+    "modern",
+    "corporate",
+    "creative",
+    "minimal",
+    "dark",
+];
+const VALID_PPT_AUDIENCES = [
+    "business",
+    "students",
+    "technical",
+    "general",
+];
+const VALID_PPT_TONES = [
+    "professional",
+    "casual",
+    "educational",
+    "persuasive",
+];
+const VALID_PPT_ASPECT_RATIOS = ["16:9", "4:3"];
+const VALID_PPT_FORMATS = ["pptx"];
+export const MIN_PPT_PAGES = 5;
+export const MAX_PPT_PAGES = 50;
+export const MIN_PPT_PROMPT_LENGTH = 10;
+export const MAX_PPT_PROMPT_LENGTH = 1000;
+/**
+ * Validate PPT output options (pages, theme, audience, tone, etc.)
+ *
+ * @param options - PPTOutputOptions to validate
+ * @returns NeuroLinkError if invalid, null if valid
+ *
+ * @example
+ * ```typescript
+ * const error = validatePPTOutputOptions({ pages: 100, theme: "invalid" });
+ * // error.code === "INVALID_PPT_PAGES"
+ * ```
+ */
+export function validatePPTOutputOptions(options) {
+    // Validate pages (slide count) - REQUIRED FIELD
+    if (options.pages === undefined || options.pages === null) {
+        return ErrorFactory.missingPPTProperty("output.ppt.pages", [
+            "Provide the number of slides: output.ppt.pages = 10",
+            "Valid range: 5 to 50 slides",
+            "Recommended: 10 slides for most presentations",
+        ]);
+    }
+    if (typeof options.pages !== "number") {
+        return ErrorFactory.invalidPPTPages(options.pages, "not a number");
+    }
+    if (!Number.isInteger(options.pages)) {
+        return ErrorFactory.invalidPPTPages(options.pages, "not an integer");
+    }
+    if (options.pages < MIN_PPT_PAGES || options.pages > MAX_PPT_PAGES) {
+        return ErrorFactory.invalidPPTPages(options.pages, `out of range (${MIN_PPT_PAGES}-${MAX_PPT_PAGES})`);
+    }
+    // Validate format
+    if (options.format !== undefined &&
+        !VALID_PPT_FORMATS.includes(options.format)) {
+        return ErrorFactory.invalidPPTFormat(options.format);
+    }
+    // Validate theme
+    if (options.theme !== undefined &&
+        !VALID_PPT_THEMES.includes(options.theme)) {
+        return ErrorFactory.invalidPPTOutputOptions("theme", options.theme, Array.from(VALID_PPT_THEMES));
+    }
+    // Validate audience
+    if (options.audience !== undefined &&
+        !VALID_PPT_AUDIENCES.includes(options.audience)) {
+        return ErrorFactory.invalidPPTOutputOptions("audience", options.audience, Array.from(VALID_PPT_AUDIENCES));
+    }
+    // Validate tone
+    if (options.tone !== undefined && !VALID_PPT_TONES.includes(options.tone)) {
+        return ErrorFactory.invalidPPTOutputOptions("tone", options.tone, Array.from(VALID_PPT_TONES));
+    }
+    // Validate aspectRatio
+    if (options.aspectRatio !== undefined &&
+        !VALID_PPT_ASPECT_RATIOS.includes(options.aspectRatio)) {
+        return ErrorFactory.invalidPPTOutputOptions("aspectRatio", options.aspectRatio, Array.from(VALID_PPT_ASPECT_RATIOS));
+    }
+    // Validate includeImages (must be boolean if provided)
+    if (options.includeImages !== undefined &&
+        typeof options.includeImages !== "boolean") {
+        return ErrorFactory.invalidPPTOutputOptions("includeImages", options.includeImages, ["true", "false"]);
+    }
+    // Validate logoPath (string path, Buffer, or ImageWithAltText)
+    if (options.logoPath !== undefined) {
+        if (typeof options.logoPath === "string") {
+            if (options.logoPath.trim().length === 0) {
+                return ErrorFactory.invalidPPTLogoPath(options.logoPath, "empty string");
+            }
+        }
+        else if (Buffer.isBuffer(options.logoPath)) {
+            // ok
+        }
+        else if (typeof options.logoPath === "object" &&
+            "data" in options.logoPath) {
+            const data = options.logoPath.data;
+            if (typeof data === "string") {
+                if (data.trim().length === 0) {
+                    return ErrorFactory.invalidPPTLogoPath(options.logoPath, "empty string");
+                }
+            }
+            else if (!Buffer.isBuffer(data)) {
+                return ErrorFactory.invalidPPTLogoPath(options.logoPath, "invalid data type");
+            }
+        }
+        else {
+            return ErrorFactory.invalidPPTLogoPath(options.logoPath, "invalid type");
+        }
+    }
+    // Validate outputPath (must be non-empty string if provided)
+    if (options.outputPath !== undefined) {
+        if (typeof options.outputPath !== "string") {
+            return ErrorFactory.invalidPPTOutputPath(options.outputPath, "not a string");
+        }
+        if (options.outputPath.trim().length === 0) {
+            return ErrorFactory.invalidPPTOutputPath(options.outputPath, "empty string");
+        }
+    }
+    return null;
+}
+function validatePPTProvider(provider) {
+    // PPT generation supported providers (subset of all AIProviderName values)
+    // Supports major LLM providers with structured output capabilities
+    const validProviders = [
+        "vertex",
+        "openai",
+        "azure",
+        "anthropic",
+        "google-ai",
+        "bedrock",
+    ];
+    // Convert enum or string to lowercase string for comparison
+    const providerString = String(provider).toLowerCase();
+    if (!validProviders.includes(providerString)) {
+        return ErrorFactory.invalidPPTProvider(provider);
+    }
+    return null;
+}
+/**
+ * Validate complete PPT generation input
+ *
+ * Validates all requirements for presentation generation:
+ * - output.mode must be "ppt"
+ * - Prompt must be within length limits
+ * - PPT output options must be valid
+ *
+ * @param options - GenerateOptions to validate for PPT generation
+ * @returns EnhancedValidationResult with errors, warnings, and suggestions
+ *
+ * @example
+ * ```typescript
+ * const validation = validatePPTGenerationInput({
+ *   input: { text: "Introducing Our New Product" },
+ *   output: { mode: "ppt", ppt: { pages: 10, theme: "modern" } }
+ * });
+ * if (!validation.isValid) {
+ *   console.error(validation.errors);
+ * }
+ * ```
+ */
+export function validatePPTGenerationInput(options) {
+    const errors = [];
+    const warnings = [];
+    const suggestions = [];
+    // Validate prompt/text - trim once for consistency
+    const trimmedPrompt = options.input.text.trim();
+    if (trimmedPrompt === "") {
+        errors.push(toValidationError(ErrorFactory.invalidPPTPrompt("empty prompt")));
+    }
+    else if (trimmedPrompt.length < MIN_PPT_PROMPT_LENGTH) {
+        errors.push(toValidationError(ErrorFactory.invalidPPTPrompt(`prompt too short (${trimmedPrompt.length} characters, min ${MIN_PPT_PROMPT_LENGTH})`)));
+    }
+    else if (trimmedPrompt.length > MAX_PPT_PROMPT_LENGTH) {
+        errors.push(toValidationError(ErrorFactory.invalidPPTPrompt(`prompt too long (${trimmedPrompt.length} characters, max ${MAX_PPT_PROMPT_LENGTH})`)));
+    }
+    // image PPT options if provided
+    if (options.input.images && options.input.images.length > 0) {
+        warnings.push("Images can be unused in PPT generation due to fail in quality standards and can lead to longer generation times.");
+        suggestions.push("Only provide high-quality, relevant images for PPT generation.");
+    }
+    // Validate provider (optional - only validate if explicitly provided)
+    if (options.provider !== undefined) {
+        const providerError = validatePPTProvider(options.provider);
+        if (providerError) {
+            errors.push(toValidationError(providerError));
+        }
+    }
+    // Mode is optional, but if provided must be "ppt"
+    if (options.output?.mode !== undefined && options.output.mode !== "ppt") {
+        errors.push(toValidationError(ErrorFactory.invalidPPTMode()));
+    }
+    // Validate PPT output options
+    if (options.output?.ppt) {
+        const pptError = validatePPTOutputOptions(options.output.ppt);
+        if (pptError) {
+            errors.push(toValidationError(pptError));
+        }
+        // Add specific warnings
+        const pages = options.output.ppt.pages;
+        if (pages > 30) {
+            warnings.push(`Generating ${pages} slides may take significant time (estimated: ${Math.ceil(pages * 3)}-${Math.ceil(pages * 5)} seconds)`);
+        }
+        if (options.output.ppt.includeImages === undefined ||
+            options.output.ppt.includeImages === true) {
+            suggestions.push("Image generation is enabled. Each slide with images will take additional time (~2-5 seconds per image).");
+        }
+    }
+    else {
+        errors.push(toValidationError(ErrorFactory.missingPPTProperty("output.ppt", [
+            "Provide PPT generation options under output.ppt",
+            "Specify number of slides, theme, and other preferences",
+        ])));
+    }
+    // Add helpful suggestions
+    if (errors.length === 0 && warnings.length === 0) {
+        suggestions.push("PPT generation typically takes 30-120 seconds depending on slide count and image generation.");
+    }
+    return { isValid: errors.length === 0, errors, warnings, suggestions };
+}
+// ============================================================================
 // HELPER FUNCTIONS
 // ============================================================================
 /**

package/dist/lib/utils/rateLimiter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Token Bucket Rate Limiter for URL Downloads
+ *
+ * Implements a token bucket algorithm to limit concurrent URL downloads.
+ * This prevents DoS attacks from rapid URL download requests.
+ *
+ * Default configuration: 10 downloads per second
+ */
+/**
+ * Configuration options for the rate limiter
+ */
+export interface RateLimiterConfig {
+    /** Maximum tokens (downloads) allowed per interval */
+    maxTokens: number;
+    /** Refill interval in milliseconds */
+    refillIntervalMs: number;
+    /** Number of tokens to add per refill interval */
+    tokensPerRefill: number;
+    /** Maximum queue size for pending requests */
+    maxQueueSize: number;
+    /** Timeout for queued requests in milliseconds */
+    queueTimeoutMs: number;
+}
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Uses a token bucket algorithm where:
+ * - Tokens are consumed when a download is requested
+ * - Tokens are refilled at a fixed rate
+ * - Requests that exceed the limit are queued
+ */
+export declare class TokenBucketRateLimiter {
+    private tokens;
+    private config;
+    private queue;
+    private refillTimer;
+    private lastRefillTime;
+    constructor(config?: Partial<RateLimiterConfig>);
+    /**
+     * Start the token refill timer
+     */
+    private startRefillTimer;
+    /**
+     * Refill tokens based on elapsed time
+     */
+    private refillTokens;
+    /**
+     * Process queued requests when tokens become available
+     */
+    private processQueue;
+    /**
+     * Acquire a token for a download
+     * Returns immediately if token is available, otherwise queues the request
+     *
+     * @throws NeuroLinkError if queue is full or request times out
+     */
+    acquire(): Promise<void>;
+    /**
+     * Get current rate limiter statistics
+     */
+    getStats(): {
+        availableTokens: number;
+        queueLength: number;
+        maxTokens: number;
+        maxQueueSize: number;
+    };
+    /**
+     * Reset the rate limiter to initial state
+     */
+    reset(): void;
+    /**
+     * Stop the rate limiter and clean up resources
+     */
+    stop(): void;
+}
+/**
+ * Global rate limiter instance for URL downloads
+ * Default: 10 downloads per second
+ */
+export declare const urlDownloadRateLimiter: TokenBucketRateLimiter;
+/**
+ * Rate-limited wrapper for async functions
+ * Ensures the function is rate-limited using the provided rate limiter
+ *
+ * @param fn - The async function to wrap
+ * @param rateLimiter - The rate limiter to use (defaults to urlDownloadRateLimiter)
+ * @returns A rate-limited version of the function
+ */
+export declare function withRateLimit<T extends unknown[], R>(fn: (...args: T) => Promise<R>, rateLimiter?: TokenBucketRateLimiter): (...args: T) => Promise<R>;

package/dist/lib/utils/rateLimiter.js

@@ -0,0 +1,201 @@
+/**
+ * Token Bucket Rate Limiter for URL Downloads
+ *
+ * Implements a token bucket algorithm to limit concurrent URL downloads.
+ * This prevents DoS attacks from rapid URL download requests.
+ *
+ * Default configuration: 10 downloads per second
+ */
+import { logger } from "./logger.js";
+import { ErrorFactory } from "./errorHandling.js";
+/**
+ * Default configuration: 10 downloads per second
+ */
+const DEFAULT_CONFIG = {
+    maxTokens: 10,
+    refillIntervalMs: 1000,
+    tokensPerRefill: 10,
+    maxQueueSize: 100,
+    queueTimeoutMs: 30000,
+};
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Uses a token bucket algorithm where:
+ * - Tokens are consumed when a download is requested
+ * - Tokens are refilled at a fixed rate
+ * - Requests that exceed the limit are queued
+ */
+export class TokenBucketRateLimiter {
+    tokens;
+    config;
+    queue = [];
+    refillTimer = null;
+    lastRefillTime;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.tokens = this.config.maxTokens;
+        this.lastRefillTime = Date.now();
+        this.startRefillTimer();
+    }
+    /**
+     * Start the token refill timer
+     */
+    startRefillTimer() {
+        if (this.refillTimer) {
+            return;
+        }
+        this.refillTimer = setInterval(() => {
+            this.refillTokens();
+            this.processQueue();
+        }, this.config.refillIntervalMs);
+        // Unref to prevent keeping the process alive
+        this.refillTimer.unref();
+    }
+    /**
+     * Refill tokens based on elapsed time
+     */
+    refillTokens() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefillTime;
+        const intervalsElapsed = Math.floor(elapsed / this.config.refillIntervalMs);
+        if (intervalsElapsed > 0) {
+            const tokensToAdd = intervalsElapsed * this.config.tokensPerRefill;
+            this.tokens = Math.min(this.config.maxTokens, this.tokens + tokensToAdd);
+            this.lastRefillTime = now;
+        }
+    }
+    /**
+     * Process queued requests when tokens become available
+     */
+    processQueue() {
+        const now = Date.now();
+        // Remove timed out requests
+        while (this.queue.length > 0) {
+            const request = this.queue[0];
+            if (now - request.timestamp > this.config.queueTimeoutMs) {
+                this.queue.shift();
+                if (request.timeoutTimer) {
+                    clearTimeout(request.timeoutTimer);
+                }
+                request.reject(ErrorFactory.rateLimiterQueueTimeout(this.config.queueTimeoutMs));
+            }
+            else {
+                break;
+            }
+        }
+        // Process requests while we have tokens
+        while (this.tokens > 0 && this.queue.length > 0) {
+            const request = this.queue.shift();
+            if (request) {
+                if (request.timeoutTimer) {
+                    clearTimeout(request.timeoutTimer);
+                }
+                this.tokens--;
+                request.resolve();
+            }
+        }
+    }
+    /**
+     * Acquire a token for a download
+     * Returns immediately if token is available, otherwise queues the request
+     *
+     * @throws NeuroLinkError if queue is full or request times out
+     */
+    async acquire() {
+        // Refill tokens based on elapsed time
+        this.refillTokens();
+        // If token available, consume it immediately
+        if (this.tokens > 0) {
+            this.tokens--;
+            return;
+        }
+        // Check queue size limit
+        if (this.queue.length >= this.config.maxQueueSize) {
+            logger.warn(`Rate limiter queue full (${this.config.maxQueueSize} requests pending)`);
+            throw ErrorFactory.rateLimiterQueueFull(this.config.maxQueueSize);
+        }
+        // Queue the request with per-request timeout handling
+        return new Promise((resolve, reject) => {
+            // Create per-request timeout timer for robust timeout handling
+            const timeoutTimer = setTimeout(() => {
+                // Remove from queue if still present
+                const index = this.queue.findIndex((req) => req.timeoutTimer === timeoutTimer);
+                if (index !== -1) {
+                    this.queue.splice(index, 1);
+                    reject(ErrorFactory.rateLimiterQueueTimeout(this.config.queueTimeoutMs));
+                }
+            }, this.config.queueTimeoutMs);
+            this.queue.push({
+                resolve,
+                reject,
+                timestamp: Date.now(),
+                timeoutTimer,
+            });
+        });
+    }
+    /**
+     * Get current rate limiter statistics
+     */
+    getStats() {
+        return {
+            availableTokens: this.tokens,
+            queueLength: this.queue.length,
+            maxTokens: this.config.maxTokens,
+            maxQueueSize: this.config.maxQueueSize,
+        };
+    }
+    /**
+     * Reset the rate limiter to initial state
+     */
+    reset() {
+        this.tokens = this.config.maxTokens;
+        this.lastRefillTime = Date.now();
+        // Reject all queued requests and clear timeout timers
+        while (this.queue.length > 0) {
+            const request = this.queue.shift();
+            if (request) {
+                if (request.timeoutTimer) {
+                    clearTimeout(request.timeoutTimer);
+                }
+                request.reject(ErrorFactory.rateLimiterReset());
+            }
+        }
+    }
+    /**
+     * Stop the rate limiter and clean up resources
+     */
+    stop() {
+        if (this.refillTimer) {
+            clearInterval(this.refillTimer);
+            this.refillTimer = null;
+        }
+        this.reset();
+    }
+}
+/**
+ * Global rate limiter instance for URL downloads
+ * Default: 10 downloads per second
+ */
+export const urlDownloadRateLimiter = new TokenBucketRateLimiter({
+    maxTokens: 10,
+    refillIntervalMs: 1000,
+    tokensPerRefill: 10,
+    maxQueueSize: 100,
+    queueTimeoutMs: 30000,
+});
+/**
+ * Rate-limited wrapper for async functions
+ * Ensures the function is rate-limited using the provided rate limiter
+ *
+ * @param fn - The async function to wrap
+ * @param rateLimiter - The rate limiter to use (defaults to urlDownloadRateLimiter)
+ * @returns A rate-limited version of the function
+ */
+export function withRateLimit(fn, rateLimiter = urlDownloadRateLimiter) {
+    return async (...args) => {
+        await rateLimiter.acquire();
+        return fn(...args);
+    };
+}
+//# sourceMappingURL=rateLimiter.js.map

package/dist/types/generateTypes.d.ts

@@ -8,6 +8,7 @@ import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
 import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { TTSOptions, TTSResult } from "./ttsTypes.js";
+import type { PPTOutputOptions, PPTGenerationResult } from "./pptTypes.js";
 import type { VideoOutputOptions, VideoGenerationResult } from "./multimodal.js";
 /**
  * Generate function options type - Primary method for content generation
@@ -68,13 +69,19 @@ export type GenerateOptions = {
          * Output mode - determines the type of content generated
          * - "text": Standard text generation (default)
          * - "video": Video generation using models like Veo 3.1
+         * - "ppt": PowerPoint presentation generation
          */
-        mode?: "text" | "video";
+        mode?: "text" | "video" | "ppt";
         /**
          * Video generation configuration (used when mode is "video")
          * Requires an input image and text prompt
          */
         video?: VideoOutputOptions;
+        /**
+         * PowerPoint generation configuration (used when mode is "ppt")
+         * Generates slides based on text prompt
+         */
+        ppt?: PPTOutputOptions;
     };
     csvOptions?: {
         maxRows?: number;
@@ -312,6 +319,24 @@ export type GenerateResult = {
      * ```
      */
     video?: VideoGenerationResult;
+    /**
+     * PowerPoint generation result (present when output.mode is "ppt")
+     *
+     * @example
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Introducing Our New Product" },
+     *   model: "gemini-pro",
+     *   output: { mode: "ppt", ppt: { pages: 10, theme: "modern" } }
+     * });
+     *
+     * if (result.ppt) {
+     *   console.log(`Generated ${result.ppt.slides.length} slides`);
+     *   console.log(`Title: ${result.ppt.slides[0].title}`);
+     * }
+     * ```
+     */
+    ppt?: PPTGenerationResult;
     imageOutput?: {
         base64: string;
     } | null;
@@ -434,12 +459,17 @@ export type TextGenerationOptions = {
          * Output mode - determines the type of content generated
          * - "text": Standard text generation (default)
          * - "video": Video generation using models like Veo 3.1
+         * - "ppt": PowerPoint presentation generation
          */
-        mode?: "text" | "video";
+        mode?: "text" | "video" | "ppt";
         /**
          * Video generation configuration (used when mode is "video")
          */
         video?: VideoOutputOptions;
+        /**
+         * PowerPoint generation configuration (used when mode is "ppt")
+         */
+        ppt?: PPTOutputOptions;
     };
     tools?: Record<string, Tool>;
     timeout?: number | string;
@@ -612,6 +642,8 @@ export type TextGenerationResult = {
     audio?: TTSResult;
     /** Video generation result */
     video?: VideoGenerationResult;
+    /** PowerPoint generation result */
+    ppt?: PPTGenerationResult;
     /** Image generation output */
     imageOutput?: {
         base64: string;

package/dist/types/pptTypes.d.ts

@@ -0,0 +1,69 @@
+import type { ImageWithAltText } from "./content.js";
+type ThemeOption = "modern" | "corporate" | "creative" | "minimal" | "dark";
+type AudienceOption = "business" | "students" | "technical" | "general";
+type ToneOption = "professional" | "casual" | "educational" | "persuasive";
+type OutputFormatOption = "pptx";
+type AspectRatioOption = "16:9" | "4:3";
+export type PPTOutputOptions = {
+    /** Number of slides to generate (required, range: 5-50) */
+    pages: number;
+    /** Output format - only PPTX supported currently (default: "pptx") */
+    format?: OutputFormatOption;
+    /** Presentation theme/style (default: "modern") */
+    theme?: ThemeOption;
+    /** Target audience for content customization */
+    audience?: AudienceOption;
+    /** Presentation tone/style */
+    tone?: ToneOption;
+    /** Whether to generate AI images for slides (default: true) */
+    includeImages?: boolean;
+    /** Custom output file path (default: auto-generated in ./output/) */
+    outputPath?: string;
+    /** Aspect ratio for slides (default: "16:9") */
+    aspectRatio?: AspectRatioOption;
+    /** Path to logo image to include in slides */
+    logoPath?: Buffer | string | ImageWithAltText;
+};
+/**
+ * Result type for generated presentation content
+ *
+ * Returned in `GenerateResult.ppt` when presentation generation is successful.
+ * Contains the file path and metadata about the generated presentation.
+ *
+ * @example
+ * ```typescript
+ * const result = await neurolink.generate({
+ *   input: { text: "Introducing Our New Product" },
+ *   provider: "vertex",
+ *   output: { mode: "ppt", ppt: { pages: 10, theme: "modern" } }
+ * });
+ *
+ * if (result.ppt) {
+ *   console.log(`Presentation saved: ${result.ppt.filePath}`);
+ *   console.log(`Total slides: ${result.ppt.totalSlides}`);
+ *   console.log(`Theme: ${result.ppt.metadata?.theme}`);
+ * }
+ * ```
+ */
+export type PPTGenerationResult = {
+    /** Path to the generated PPTX file */
+    filePath: string;
+    /** Total number of slides in the presentation */
+    totalSlides: number;
+    /** Output format (always "pptx" currently) */
+    format: OutputFormatOption;
+    /** Presentation metadata */
+    metadata?: {
+        /** Theme/style used */
+        theme?: string;
+        /** Target audience */
+        audience?: string;
+        /** Presentation tone */
+        tone?: string;
+        /** Model used for image generation */
+        imageModel?: string;
+        /** File size in bytes */
+        fileSize?: number;
+    };
+};
+export {};

package/dist/types/pptTypes.js

@@ -0,0 +1 @@
+export {};