@providerprotocol/ai 0.0.27 → 0.0.28

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   aggregateUsage,
   createTurn,
   emptyUsage
-} from "./chunk-MKDLXV4O.js";
+} from "./chunk-NSE7QN3P.js";
 import {
   Image
 } from "./chunk-WAKD3OO5.js";
@@ -32,7 +32,7 @@ import {
   resolveEmbeddingHandler,
   resolveImageHandler,
   resolveLLMHandler
-} from "./chunk-6AZVUI6H.js";
+} from "./chunk-ILR2D5PN.js";
 import {
   ExponentialBackoff,
   LinearBackoff,
@@ -61,6 +61,8 @@ var ContentBlockType = {
   Reasoning: "reasoning",
   /** Image content */
   Image: "image",
+  /** Document content (PDFs, text files) */
+  Document: "document",
   /** Audio content */
   Audio: "audio",
   /** Video content */
@@ -76,6 +78,14 @@ var ImageSourceType = {
   /** Raw bytes image data */
   Bytes: "bytes"
 };
+var DocumentSourceType = {
+  /** Base64-encoded document data (for PDFs) */
+  Base64: "base64",
+  /** URL reference to document (for PDFs) */
+  Url: "url",
+  /** Plain text document content */
+  Text: "text"
+};
 function text(content) {
   return { type: ContentBlockType.Text, text: content };
 }
@@ -91,6 +101,9 @@ function isReasoningBlock(block) {
 function isImageBlock(block) {
   return block.type === ContentBlockType.Image;
 }
+function isDocumentBlock(block) {
+  return block.type === ContentBlockType.Document;
+}
 function isAudioBlock(block) {
   return block.type === ContentBlockType.Audio;
 }
@@ -243,7 +256,7 @@ function inputToMessage(input) {
   if (isTextBlock(block)) {
     return new UserMessage(block.text);
   }
-  if (isImageBlock(block) || isAudioBlock(block) || isVideoBlock(block) || isBinaryBlock(block)) {
+  if (isImageBlock(block) || isDocumentBlock(block) || isAudioBlock(block) || isVideoBlock(block) || isBinaryBlock(block)) {
     return new UserMessage([block]);
   }
   throw new Error("Invalid inference input");
@@ -597,6 +610,14 @@ function validateMediaCapabilities(messages, capabilities, providerName) {
           ModalityType.LLM
         );
       }
+      if (block.type === "document" && !capabilities.documentInput) {
+        throw new UPPError(
+          `Provider '${providerName}' does not support document input`,
+          ErrorCode.InvalidRequest,
+          providerName,
+          ModalityType.LLM
+        );
+      }
       if (block.type === "video" && !capabilities.videoInput) {
         throw new UPPError(
           `Provider '${providerName}' does not support video input`,
@@ -938,6 +959,604 @@ function normalizeInput(input) {
   return input.prompt;
 }
 
+// src/core/media/document.ts
+var Document = class _Document {
+  /** The underlying document source (base64, url, or text) */
+  source;
+  /** MIME type of the document ('application/pdf' or 'text/plain') */
+  mimeType;
+  /** Optional document title (used for citations) */
+  title;
+  constructor(source, mimeType, title) {
+    this.source = source;
+    this.mimeType = mimeType;
+    this.title = title;
+  }
+  /**
+   * Whether this document has data loaded in memory.
+   *
+   * Returns `false` for URL-sourced documents that reference external resources.
+   */
+  get hasData() {
+    return this.source.type !== "url";
+  }
+  /**
+   * Whether this document is a PDF.
+   */
+  get isPdf() {
+    return this.mimeType === "application/pdf";
+  }
+  /**
+   * Whether this document is plain text.
+   */
+  get isText() {
+    return this.mimeType === "text/plain";
+  }
+  /**
+   * Converts the document to a base64-encoded string.
+   *
+   * @returns The document data as a base64 string
+   * @throws {Error} When the source is a URL or plain text
+   */
+  toBase64() {
+    if (this.source.type === "base64") {
+      return this.source.data;
+    }
+    throw new Error("Cannot convert to base64. Only base64-sourced documents support this.");
+  }
+  /**
+   * Gets the plain text content for text documents.
+   *
+   * @returns The document text content
+   * @throws {Error} When the source is not plain text
+   */
+  toText() {
+    if (this.source.type === "text") {
+      return this.source.data;
+    }
+    throw new Error("Cannot get text content. Only text-sourced documents support this.");
+  }
+  /**
+   * Gets the URL for URL-sourced documents.
+   *
+   * @returns The document URL
+   * @throws {Error} When the source is not a URL
+   */
+  toUrl() {
+    if (this.source.type === "url") {
+      return this.source.url;
+    }
+    throw new Error("This document does not have a URL source.");
+  }
+  /**
+   * Converts this Document to a DocumentBlock for use in UPP messages.
+   *
+   * @returns A DocumentBlock that can be included in message content arrays
+   */
+  toBlock() {
+    return {
+      type: "document",
+      source: this.source,
+      mimeType: this.mimeType,
+      title: this.title
+    };
+  }
+  /**
+   * Creates a Document by reading a file from disk.
+   *
+   * The file is read into memory and base64-encoded. MIME type is automatically
+   * detected from the file extension.
+   *
+   * @param path - Path to the document file
+   * @param title - Optional document title
+   * @returns Promise resolving to a Document with the file contents
+   *
+   * @example
+   * ```typescript
+   * const doc = await Document.fromPath('./reports/annual.pdf');
+   * const docWithTitle = await Document.fromPath('./report.pdf', 'Annual Report 2024');
+   * ```
+   */
+  static async fromPath(path, title) {
+    const file = Bun.file(path);
+    const exists = await file.exists();
+    if (!exists) {
+      throw new Error(`Document file not found at path: ${path}`);
+    }
+    let data;
+    try {
+      data = await file.arrayBuffer();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`Failed to read document file at path: ${path}. ${message}`);
+    }
+    if (data.byteLength === 0) {
+      throw new Error(`Document file is empty at path: ${path}`);
+    }
+    const base64 = Buffer.from(data).toString("base64");
+    const mimeType = detectMimeType(path);
+    return new _Document(
+      { type: "base64", data: base64 },
+      mimeType,
+      title
+    );
+  }
+  /**
+   * Creates a Document from a URL reference.
+   *
+   * The URL is stored as a reference and not fetched. Providers will handle
+   * URL fetching if needed. Only PDF URLs are supported.
+   * URLs must use the http or https protocol.
+   *
+   * @param url - URL pointing to the PDF document
+   * @param title - Optional document title
+   * @returns A Document referencing the URL
+   *
+   * @example
+   * ```typescript
+   * const doc = Document.fromUrl('https://example.com/report.pdf');
+   * ```
+   */
+  static fromUrl(url, title) {
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(url);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Invalid URL";
+      throw new Error(`Invalid document URL: ${message}`);
+    }
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+      throw new Error(`Document URL must use http or https: ${url}`);
+    }
+    return new _Document(
+      { type: "url", url },
+      "application/pdf",
+      title
+    );
+  }
+  /**
+   * Creates a Document from base64-encoded data.
+   *
+   * @param base64 - The base64-encoded document data
+   * @param mimeType - The MIME type ('application/pdf' or 'text/plain')
+   * @param title - Optional document title
+   * @returns A Document containing the base64 data
+   *
+   * @example
+   * ```typescript
+   * const doc = Document.fromBase64(pdfBase64, 'application/pdf', 'Contract');
+   * ```
+   */
+  static fromBase64(base64, mimeType, title) {
+    return new _Document(
+      { type: "base64", data: base64 },
+      mimeType,
+      title
+    );
+  }
+  /**
+   * Creates a Document from plain text content.
+   *
+   * @param text - The document text content
+   * @param title - Optional document title
+   * @returns A Document containing the text
+   *
+   * @example
+   * ```typescript
+   * const doc = Document.fromText('This is the document content.', 'Notes');
+   * ```
+   */
+  static fromText(text2, title) {
+    return new _Document(
+      { type: "text", data: text2 },
+      "text/plain",
+      title
+    );
+  }
+  /**
+   * Creates a Document from an existing DocumentBlock.
+   *
+   * Useful for converting content blocks received from providers back
+   * into Document instances for further processing.
+   *
+   * @param block - A DocumentBlock from message content
+   * @returns A Document with the block's source and metadata
+   */
+  static fromBlock(block) {
+    return new _Document(
+      block.source,
+      block.mimeType,
+      block.title
+    );
+  }
+};
+function detectMimeType(path) {
+  const ext = path.split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "pdf":
+      return "application/pdf";
+    case "txt":
+    case "text":
+    case "md":
+    case "markdown":
+      return "text/plain";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+// src/core/media/Audio.ts
+var Audio = class _Audio {
+  /** The audio data as raw bytes */
+  data;
+  /** MIME type of the audio (e.g., 'audio/mp3', 'audio/wav') */
+  mimeType;
+  /** Duration in seconds, if known */
+  duration;
+  constructor(data, mimeType, duration) {
+    this.data = data;
+    this.mimeType = mimeType;
+    this.duration = duration;
+  }
+  /**
+   * Gets the size of the audio data in bytes.
+   */
+  get size() {
+    return this.data.length;
+  }
+  /**
+   * Converts the audio to a base64-encoded string.
+   *
+   * @returns The audio data as a base64 string
+   */
+  toBase64() {
+    return btoa(
+      Array.from(this.data).map((b) => String.fromCharCode(b)).join("")
+    );
+  }
+  /**
+   * Converts the audio to a data URL suitable for embedding.
+   *
+   * @returns A data URL in the format `data:{mimeType};base64,{data}`
+   */
+  toDataUrl() {
+    const base64 = this.toBase64();
+    return `data:${this.mimeType};base64,${base64}`;
+  }
+  /**
+   * Gets the audio data as raw bytes.
+   *
+   * @returns The audio data as a Uint8Array
+   */
+  toBytes() {
+    return this.data;
+  }
+  /**
+   * Converts this Audio to an AudioBlock for use in UPP messages.
+   *
+   * @returns An AudioBlock that can be included in message content arrays
+   */
+  toBlock() {
+    return {
+      type: "audio",
+      data: this.data,
+      mimeType: this.mimeType,
+      duration: this.duration
+    };
+  }
+  /**
+   * Creates an Audio by reading a file from disk.
+   *
+   * The file is read into memory as bytes. MIME type is automatically
+   * detected from the file extension.
+   *
+   * @param path - Path to the audio file
+   * @param duration - Optional duration in seconds
+   * @returns Promise resolving to an Audio with the file contents
+   *
+   * @example
+   * ```typescript
+   * const audio = await Audio.fromPath('./recordings/interview.mp3');
+   * ```
+   */
+  static async fromPath(path, duration) {
+    const file = Bun.file(path);
+    const exists = await file.exists();
+    if (!exists) {
+      throw new Error(`Audio file not found at path: ${path}`);
+    }
+    let arrayBuffer;
+    try {
+      arrayBuffer = await file.arrayBuffer();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`Failed to read audio file at path: ${path}. ${message}`);
+    }
+    if (arrayBuffer.byteLength === 0) {
+      throw new Error(`Audio file is empty at path: ${path}`);
+    }
+    const mimeType = detectMimeType2(path);
+    return new _Audio(
+      new Uint8Array(arrayBuffer),
+      mimeType,
+      duration
+    );
+  }
+  /**
+   * Creates an Audio from raw byte data.
+   *
+   * @param data - The audio data as a Uint8Array
+   * @param mimeType - The MIME type of the audio
+   * @param duration - Optional duration in seconds
+   * @returns An Audio containing the byte data
+   *
+   * @example
+   * ```typescript
+   * const audio = Audio.fromBytes(wavData, 'audio/wav');
+   * ```
+   */
+  static fromBytes(data, mimeType, duration) {
+    return new _Audio(data, mimeType, duration);
+  }
+  /**
+   * Creates an Audio from a base64-encoded string.
+   *
+   * @param base64 - The base64-encoded audio data (without data URL prefix)
+   * @param mimeType - The MIME type of the audio
+   * @param duration - Optional duration in seconds
+   * @returns An Audio containing the decoded data
+   *
+   * @example
+   * ```typescript
+   * const audio = Audio.fromBase64(base64String, 'audio/mp3');
+   * ```
+   */
+  static fromBase64(base64, mimeType, duration) {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return new _Audio(bytes, mimeType, duration);
+  }
+  /**
+   * Creates an Audio from an existing AudioBlock.
+   *
+   * Useful for converting content blocks received from providers back
+   * into Audio instances for further processing.
+   *
+   * @param block - An AudioBlock from message content
+   * @returns An Audio with the block's data and metadata
+   */
+  static fromBlock(block) {
+    return new _Audio(
+      block.data,
+      block.mimeType,
+      block.duration
+    );
+  }
+};
+function detectMimeType2(path) {
+  const ext = path.split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "mp3":
+      return "audio/mp3";
+    case "wav":
+      return "audio/wav";
+    case "ogg":
+    case "oga":
+      return "audio/ogg";
+    case "flac":
+      return "audio/flac";
+    case "aac":
+      return "audio/aac";
+    case "m4a":
+      return "audio/mp4";
+    case "webm":
+      return "audio/webm";
+    case "aiff":
+    case "aif":
+      return "audio/aiff";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+// src/core/media/Video.ts
+var Video = class _Video {
+  /** The video data as raw bytes */
+  data;
+  /** MIME type of the video (e.g., 'video/mp4', 'video/webm') */
+  mimeType;
+  /** Duration in seconds, if known */
+  duration;
+  /** Video width in pixels, if known */
+  width;
+  /** Video height in pixels, if known */
+  height;
+  constructor(data, mimeType, options) {
+    this.data = data;
+    this.mimeType = mimeType;
+    this.duration = options?.duration;
+    this.width = options?.width;
+    this.height = options?.height;
+  }
+  /**
+   * Gets the size of the video data in bytes.
+   */
+  get size() {
+    return this.data.length;
+  }
+  /**
+   * Converts the video to a base64-encoded string.
+   *
+   * @returns The video data as a base64 string
+   */
+  toBase64() {
+    return btoa(
+      Array.from(this.data).map((b) => String.fromCharCode(b)).join("")
+    );
+  }
+  /**
+   * Converts the video to a data URL suitable for embedding.
+   *
+   * @returns A data URL in the format `data:{mimeType};base64,{data}`
+   */
+  toDataUrl() {
+    const base64 = this.toBase64();
+    return `data:${this.mimeType};base64,${base64}`;
+  }
+  /**
+   * Gets the video data as raw bytes.
+   *
+   * @returns The video data as a Uint8Array
+   */
+  toBytes() {
+    return this.data;
+  }
+  /**
+   * Converts this Video to a VideoBlock for use in UPP messages.
+   *
+   * @returns A VideoBlock that can be included in message content arrays
+   */
+  toBlock() {
+    return {
+      type: "video",
+      data: this.data,
+      mimeType: this.mimeType,
+      duration: this.duration,
+      width: this.width,
+      height: this.height
+    };
+  }
+  /**
+   * Creates a Video by reading a file from disk.
+   *
+   * The file is read into memory as bytes. MIME type is automatically
+   * detected from the file extension.
+   *
+   * @param path - Path to the video file
+   * @param options - Optional metadata (duration, width, height)
+   * @returns Promise resolving to a Video with the file contents
+   *
+   * @example
+   * ```typescript
+   * const video = await Video.fromPath('./clips/demo.mp4');
+   * const videoWithMeta = await Video.fromPath('./clip.mp4', { duration: 30, width: 1920, height: 1080 });
+   * ```
+   */
+  static async fromPath(path, options) {
+    const file = Bun.file(path);
+    const exists = await file.exists();
+    if (!exists) {
+      throw new Error(`Video file not found at path: ${path}`);
+    }
+    let arrayBuffer;
+    try {
+      arrayBuffer = await file.arrayBuffer();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`Failed to read video file at path: ${path}. ${message}`);
+    }
+    if (arrayBuffer.byteLength === 0) {
+      throw new Error(`Video file is empty at path: ${path}`);
+    }
+    const mimeType = detectMimeType3(path);
+    return new _Video(
+      new Uint8Array(arrayBuffer),
+      mimeType,
+      options
+    );
+  }
+  /**
+   * Creates a Video from raw byte data.
+   *
+   * @param data - The video data as a Uint8Array
+   * @param mimeType - The MIME type of the video
+   * @param options - Optional metadata (duration, width, height)
+   * @returns A Video containing the byte data
+   *
+   * @example
+   * ```typescript
+   * const video = Video.fromBytes(mp4Data, 'video/mp4');
+   * const videoWithMeta = Video.fromBytes(data, 'video/mp4', { duration: 60 });
+   * ```
+   */
+  static fromBytes(data, mimeType, options) {
+    return new _Video(data, mimeType, options);
+  }
+  /**
+   * Creates a Video from a base64-encoded string.
+   *
+   * @param base64 - The base64-encoded video data (without data URL prefix)
+   * @param mimeType - The MIME type of the video
+   * @param options - Optional metadata (duration, width, height)
+   * @returns A Video containing the decoded data
+   *
+   * @example
+   * ```typescript
+   * const video = Video.fromBase64(base64String, 'video/mp4');
+   * ```
+   */
+  static fromBase64(base64, mimeType, options) {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return new _Video(bytes, mimeType, options);
+  }
+  /**
+   * Creates a Video from an existing VideoBlock.
+   *
+   * Useful for converting content blocks received from providers back
+   * into Video instances for further processing.
+   *
+   * @param block - A VideoBlock from message content
+   * @returns A Video with the block's data and metadata
+   */
+  static fromBlock(block) {
+    return new _Video(
+      block.data,
+      block.mimeType,
+      {
+        duration: block.duration,
+        width: block.width,
+        height: block.height
+      }
+    );
+  }
+};
+function detectMimeType3(path) {
+  const ext = path.split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "mp4":
+    case "m4v":
+      return "video/mp4";
+    case "webm":
+      return "video/webm";
+    case "ogv":
+    case "ogg":
+      return "video/ogg";
+    case "mov":
+      return "video/quicktime";
+    case "avi":
+      return "video/x-msvideo";
+    case "mpeg":
+    case "mpg":
+      return "video/mpeg";
+    case "wmv":
+      return "video/x-ms-wmv";
+    case "3gp":
+    case "3gpp":
+      return "video/3gpp";
+    case "flv":
+      return "video/x-flv";
+    default:
+      return "application/octet-stream";
+  }
+}
+
 // src/types/thread.ts
 var Thread = class _Thread {
   /** Unique thread identifier */
@@ -1202,7 +1821,10 @@ var ai = {
 };
 export {
   AssistantMessage,
+  Audio,
   ContentBlockType,
+  Document,
+  DocumentSourceType,
   DynamicKey,
   ErrorCode,
   ExponentialBackoff,
@@ -1221,6 +1843,7 @@ export {
   ToolResultMessage,
   UPPError,
   UserMessage,
+  Video,
   WeightedKeys,
   aggregateUsage,
   ai,
@@ -1235,6 +1858,7 @@ export {
   isAssistantMessage,
   isAudioBlock,
   isBinaryBlock,
+  isDocumentBlock,
   isImageBlock,
   isReasoningBlock,
   isTextBlock,