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

package/types/API/openai.com/video.d.ts

@@ -0,0 +1,409 @@
+/**
+ * JSON-compatible primitive value.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+/**
+ * JSON-compatible value accepted in OpenAI JSON request bodies.
+ */
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * JSON-compatible object accepted in OpenAI JSON request bodies.
+ */
+export type JsonObject = {
+    [key: string]: JsonValue | undefined;
+};
+/**
+ * JSON-compatible array accepted in OpenAI JSON request bodies.
+ */
+export type JsonArray = Array<JsonValue | undefined>;
+/**
+ * HTTP header map used for OpenAI requests.
+ */
+export type OpenAIHeaders = {
+    /**
+     * 'User-Agent'] - User-Agent header value.
+     */
+    ""?: string | undefined;
+    /**
+     * - Bearer token authorization header.
+     */
+    Authorization: string;
+};
+/**
+ * Common wrapper request options.
+ */
+export type RequestOptions = {
+    /**
+     * - User-Agent header value.
+     */
+    userAgent?: string | undefined;
+};
+/**
+ * Query parameters serialized onto an OpenAI request URL.
+ * Undefined and null values are skipped.
+ */
+export type QueryParams = {
+    [key: string]: string | number | boolean | null | undefined;
+};
+/**
+ * Parsed response body returned by fetch helpers.
+ */
+export type ParsedResponseBody = JsonValue | string | ArrayBuffer | Blob | undefined;
+/**
+ * Downloadable video content variant.
+ */
+export type VideoAssetVariant = "video" | "thumbnail" | "spritesheet";
+/**
+ * Supported OpenAI video model identifier.
+ */
+export type VideoModel = "sora-2" | "sora-2-pro" | "sora-2-2025-10-06" | "sora-2-pro-2025-10-06" | "sora-2-2025-12-08" | string;
+/**
+ * Supported base clip duration for video creation.
+ */
+export type VideoSeconds = "4" | "8" | "12" | 4 | 8 | 12 | number;
+/**
+ * Supported generated segment duration for video extensions.
+ */
+export type VideoExtensionSeconds = "4" | "8" | "12" | "16" | "20" | 4 | 8 | 12 | 16 | 20 | number;
+/**
+ * Supported generated video output resolution.
+ */
+export type VideoSize = "720x1280" | "1280x720" | "1024x1792" | "1792x1024";
+/**
+ * Lifecycle status of an OpenAI video job.
+ */
+export type VideoStatus = "queued" | "in_progress" | "completed" | "failed" | string;
+/**
+ * Error payload returned for a failed video generation job.
+ */
+export type VideoCreateError = {
+    /**
+     * - Machine-readable error code.
+     */
+    code: string;
+    /**
+     * - Human-readable error description.
+     */
+    message: string;
+};
+/**
+ * Optional image reference object used to guide video creation.
+ * Exactly one of `image_url` or `file_id` should be provided.
+ */
+export type VideoInputReference = {
+    /**
+     * - Fully-qualified image URL or base64 data URL.
+     */
+    image_url?: string | undefined;
+    /**
+     * - OpenAI file identifier for an uploaded image reference.
+     */
+    file_id?: string | undefined;
+};
+/**
+ * Reference to an existing generated video.
+ */
+export type VideoReference = {
+    /**
+     * - Identifier of the completed source video.
+     */
+    id: string;
+};
+/**
+ * Structured metadata for an OpenAI video generation job.
+ */
+export type VideoObject = {
+    /**
+     * - Unique identifier for the video job.
+     */
+    id: string;
+    /**
+     * - Unix timestamp in seconds for completion, when finished.
+     */
+    completed_at?: number | null | undefined;
+    /**
+     * - Unix timestamp in seconds when the job was created.
+     */
+    created_at?: number | undefined;
+    /**
+     * - Error payload when generation failed.
+     */
+    error?: VideoCreateError | null | undefined;
+    /**
+     * - Unix timestamp in seconds when downloadable assets expire.
+     */
+    expires_at?: number | null | undefined;
+    /**
+     * - Video generation model that produced the job.
+     */
+    model?: string | undefined;
+    /**
+     * - Object type marker for video job responses.
+     */
+    object?: "video" | undefined;
+    /**
+     * - Approximate completion percentage from 0 to 100.
+     */
+    progress?: number | undefined;
+    /**
+     * - Prompt used to generate, edit, extend, or remix the video.
+     */
+    prompt?: string | undefined;
+    /**
+     * - Source video id when this video is a remix.
+     */
+    remixed_from_video_id?: string | null | undefined;
+    /**
+     * - Duration of the generated clip, or stitched total duration for extensions.
+     */
+    seconds?: string | undefined;
+    /**
+     * - Output resolution.
+     */
+    size?: VideoSize | undefined;
+    /**
+     * - Current lifecycle status of the video job.
+     */
+    status: VideoStatus;
+    /**
+     * - Downloaded media data when a wrapper is called with download enabled.
+     */
+    content?: VideoDownloadResult | undefined;
+};
+/**
+ * Response returned after deleting a video.
+ */
+export type VideoDeleteResponse = {
+    /**
+     * - Identifier of the deleted video.
+     */
+    id: string;
+    /**
+     * - Whether the resource was deleted.
+     */
+    deleted: boolean;
+    /**
+     * - Object type marker for delete responses.
+     */
+    object: "video.deleted";
+};
+/**
+ * Query parameters for listing generated videos.
+ */
+export type VideoListQuery = {
+    /**
+     * - Pagination cursor from the previous response.
+     */
+    after?: string | undefined;
+    /**
+     * - Maximum number of videos to retrieve.
+     */
+    limit?: number | undefined;
+    /**
+     * - Sort order by timestamp.
+     */
+    order?: "desc" | "asc" | undefined;
+};
+/**
+ * Paginated list response for generated videos.
+ */
+export type VideoListResponse = {
+    /**
+     * - Page of video jobs.
+     */
+    data: VideoObject[];
+    /**
+     * - Identifier of the first item in the page.
+     */
+    first_id?: string | undefined;
+    /**
+     * - Whether more items are available.
+     */
+    has_more?: boolean | undefined;
+    /**
+     * - Identifier of the last item in the page.
+     */
+    last_id?: string | undefined;
+    /**
+     * - Object type marker for list responses.
+     */
+    object: "list";
+};
+/**
+ * Response returned for character creation and retrieval.
+ */
+export type VideoCharacter = {
+    /**
+     * - Identifier for the character cameo.
+     */
+    id: string;
+    /**
+     * - Unix timestamp in seconds when the character was created.
+     */
+    created_at: number;
+    /**
+     * - Display name for the character.
+     */
+    name: string;
+};
+/**
+ * Result returned by authenticated media download helpers.
+ */
+export type VideoDownloadResult = {
+    /**
+     * - Downloaded media bytes.
+     */
+    buffer: Buffer;
+    /**
+     * - Response content type.
+     */
+    contentType: string;
+    /**
+     * - Number of downloaded bytes.
+     */
+    bytes: number;
+    /**
+     * - Absolute local path when media was saved to disk.
+     */
+    local_path?: string | undefined;
+};
+/**
+ * Options for polling a video job until it reaches a terminal state.
+ */
+export type PollOptions = RequestOptions & Object;
+/**
+ * Options for submitting a create-video request.
+ */
+export type SubmitVideoOptions = RequestOptions & PollOptions & Object;
+/**
+ * Options for creating a video and optionally downloading the completed result.
+ */
+export type CreateVideoOptions = SubmitVideoOptions & Object;
+/**
+ * Options for emergency polling after a previous create/edit/extend/remix timeout.
+ */
+export type EmergencyPollVideoOptions = PollOptions & Object;
+/**
+ * Options for downloading generated video media or preview assets.
+ */
+export type DownloadVideoOptions = RequestOptions & Object;
+/**
+ * Options for edit, extension, and remix requests.
+ */
+export type VideoMutationOptions = RequestOptions & PollOptions & Object;
+/**
+ * Local or in-memory video input accepted by createCharacter().
+ */
+export type CharacterVideoInput = string | Buffer | Blob | ArrayBuffer;
+/**
+ * Blob conversion result used for multipart character upload.
+ */
+export type VideoBlobResult = {
+    /**
+     * - Blob ready to append to FormData.
+     */
+    blob: Blob;
+    /**
+     * - Filename sent with the multipart upload.
+     */
+    filename: string;
+};
+/**
+ * Create a video and wait until the job completes.
+ * @param {string} prompt - Prompt describing the video.
+ * @param {CreateVideoOptions} [options={}] - Create and polling options.
+ * @param {boolean} [options.download=false] - Download final video after completion.
+ * @returns {Promise<VideoObject>} Completed video response, optionally with `content`.
+ */
+export function createVideo(prompt: string, options?: CreateVideoOptions): Promise<VideoObject>;
+/**
+ * Retrieve the latest metadata for a generated video.
+ * @param {string} videoId - OpenAI video id.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoObject>} Video object.
+ */
+export function retrieveVideo(videoId: string, options?: RequestOptions): Promise<VideoObject>;
+/**
+ * List recently generated videos for the current project.
+ * @param {VideoListQuery} [query={}] - List query parameters.
+ * @param {string} [query.after] - Pagination cursor.
+ * @param {number} [query.limit] - Number of items to retrieve.
+ * @param {'asc'|'desc'} [query.order] - Sort order.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoListResponse>} List response.
+ */
+export function listVideos(query?: VideoListQuery, options?: RequestOptions): Promise<VideoListResponse>;
+/**
+ * Delete a completed or failed video and its stored assets.
+ * @param {string} videoId - OpenAI video id.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoDeleteResponse>} Delete response.
+ */
+export function deleteVideo(videoId: string, options?: RequestOptions): Promise<VideoDeleteResponse>;
+/**
+ * Download generated video bytes or a preview asset.
+ * @param {string} videoId - OpenAI video id.
+ * @param {DownloadVideoOptions} [options={}] - Download options.
+ * @param {VideoAssetVariant} [options.variant='video'] - Asset variant.
+ * @param {boolean} [options.save=false] - Save bytes to `.cache/openai/`.
+ * @param {string} [options.filenamePrefix='openai-video'] - Local filename prefix.
+ * @returns {Promise<VideoDownloadResult>}
+ */
+export function downloadVideoContent(videoId: string, options?: DownloadVideoOptions): Promise<VideoDownloadResult>;
+/**
+ * Emergency polling call for jobs that outlive a previous request timeout.
+ *
+ * Call this with the video id from a timed-out create/edit/extend/remix response
+ * or from the thrown timeout error's `videoId` property. Defaults are longer and
+ * less aggressive than normal polling.
+ *
+ * @param {string} videoId - OpenAI video id.
+ * @param {PollOptions} [options={}] - Polling options.
+ * @param {number} [options.maxWaitMs=3600000] - Maximum wait time in ms.
+ * @param {number} [options.pollIntervalMs=30000] - Delay between polls in ms.
+ * @param {boolean} [options.download=false] - Download final media when completed.
+ * @param {VideoAssetVariant} [options.variant='video'] - Asset variant to download.
+ * @param {string} [options.userAgent='@j-o-r/agents'] - User-Agent header value.
+ * @returns {Promise<VideoObject>} Completed video response, optionally with download data.
+ */
+export function emergencyPollVideo(videoId: string, options?: PollOptions): Promise<VideoObject>;
+/**
+ * Edit a video and wait until the job completes.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Edit prompt.
+ * @param {VideoMutationOptions} [options={}] - Request and polling options.
+ * @returns {Promise<VideoObject>} Completed video response.
+ */
+export function editVideo(videoId: string, prompt: string, options?: VideoMutationOptions): Promise<VideoObject>;
+/**
+ * Extend a video and wait until the job completes.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Extension prompt.
+ * @param {VideoExtensionSeconds} [seconds='4'] - New segment length.
+ * @param {VideoMutationOptions} [options={}] - Request and polling options.
+ * @returns {Promise<VideoObject>} Completed video response.
+ */
+export function extendVideo(videoId: string, prompt: string, seconds?: VideoExtensionSeconds, options?: VideoMutationOptions): Promise<VideoObject>;
+/**
+ * Remix a video and wait until the job completes.
+ * @param {string} videoId - Completed source video id.
+ * @param {string} prompt - Remix prompt.
+ * @param {VideoMutationOptions} [options={}] - Request and polling options.
+ * @returns {Promise<VideoObject>} Completed video response.
+ */
+export function remixVideo(videoId: string, prompt: string, options?: VideoMutationOptions): Promise<VideoObject>;
+/**
+ * Create a character from an uploaded video.
+ * @param {string} name - Display name for the character.
+ * @param {CharacterVideoInput} video - Local file path or video bytes.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoCharacter>} Character response.
+ */
+export function createCharacter(name: string, video: CharacterVideoInput, options?: RequestOptions): Promise<VideoCharacter>;
+/**
+ * Fetch a character by id.
+ * @param {string} characterId - Character id.
+ * @param {RequestOptions} [options={}] - Request options.
+ * @returns {Promise<VideoCharacter>} Character response.
+ */
+export function fetchCharacter(characterId: string, options?: RequestOptions): Promise<VideoCharacter>;

package/types/API/openai.com/videoToolset.d.ts

@@ -0,0 +1,24 @@
+export default tools;
+/**
+ * Supported downloadable video asset variants.
+ */
+export type VideoAssetVariant = "video" | "thumbnail" | "spritesheet";
+/**
+ * JSON-serializable summary returned for downloaded media content.
+ */
+export type DownloadSummary = {
+    /**
+     * - Response content type.
+     */
+    contentType: string;
+    /**
+     * - Number of downloaded bytes.
+     */
+    bytes: number;
+    /**
+     * - Local saved file path when available.
+     */
+    local_path?: string | undefined;
+};
+declare const tools: ToolSet;
+import ToolSet from '../../ToolSet.js';

package/types/API/stability.ai/audio.d.ts

@@ -20,7 +20,7 @@ export function getHeaders(acceptHeader?: string): Object;
  *        - base64 string: decoded
  *        - Blob/ArrayBuffer: converted
  * @param {string} [filenamePrefix='stability-audio'] - Prefix for the generated filename.
- * @param {string} [ext='mp3'] - File extension (`mp3` or `wav` recommended).
+ * @param {string} [ext='mp3'] - File extension (forced to 'mp3' in MP3-only mode).
  * @returns {Promise<string>} Absolute local file path of the saved audio.
  * @throws {Error} For unsupported formats or download failures.
  */
@@ -28,18 +28,7 @@ export function saveAudioToLocal(audioData: Buffer | string | Blob | ArrayBuffer
 /**
  * Generates high-quality audio from a text prompt using Stable Audio 3.
  *
- * This is the primary text-to-audio endpoint. It submits a prompt and optional
- * parameters, receives a generation ID (202), polls until ready, and returns
- * the generated audio saved locally plus metadata.
- *
- * **Constraints** (from Stable Audio 3 spec):
- * - Prompt: English only, max 10,000 characters, descriptive (instruments, mood, genre, style).
- * - Duration: 1–380 seconds (default 190).
- * - Steps: 4–8 (default 8).
- * - CFG Scale: 1–25 (default 1).
- * - Seed: 0 (random) or 0–4,294,967,294.
- * - Output: mp3 (default) or wav at 44.1 kHz stereo.
- * - Cost: Flat 26 credits per successful generation.
+ * **MP3 ONLY** — Output is always MP3. `output_format` is ignored and forced to 'mp3'.
  *
  * @async
  * @function textToAudio
@@ -50,43 +39,11 @@ export function saveAudioToLocal(audioData: Buffer | string | Blob | ArrayBuffer
  * @param {number} [options.seed=0] - Random seed for reproducibility (0 = random).
  * @param {number} [options.steps=8] - Number of sampling steps (4–8).
  * @param {number} [options.cfg_scale=1] - Prompt adherence strength (1–25).
- * @param {string} [options.output_format='mp3'] - `'mp3'` or `'wav'`.
- * @param {string} [options.accept='audio/*'] - Response format: `'audio/*'` (binary) or `'application/json'`.
+ * @param {string} [options.accept='audio/*'] - Response format.
  * @param {string} [options.filenamePrefix='stability-text-to-audio'] - Prefix for saved file.
- * @returns {Promise<Object>} Result object:
- *          ```js
- *          {
- *            local_path: '/path/to/.cache/stability/stability-text-to-audio-1234567890.mp3',
- *            finish_reason: 'SUCCESS',
- *            seed: 123456789,
- *            x_request_id: 'req_...',
- *            raw: { headers: {...} }   // or full JSON if accept=application/json
- *          }
- *          ```
+ * @returns {Promise<Object>} Result object (always .mp3).
  * @throws {Error} - 'Missing STABILITY_API_KEY', invalid prompt, unsupported model,
- *                   API errors (400/403/422/429/500), polling timeout, or download failures.
- *
- * @example
- * // Basic usage
- * const result = await textToAudio('upbeat electronic synthwave with driving bass');
- * console.log('Saved to:', result.local_path);
- *
- * @example
- * // Advanced with options
- * const result = await textToAudio(
- *   'cinematic orchestral music, epic brass, strings, choir, 120 BPM',
- *   {
- *     duration: 240,
- *     seed: 42,
- *     steps: 8,
- *     cfg_scale: 7,
- *     output_format: 'wav',
- *     accept: 'application/json'
- *   }
- * );
- * if (result.audio_base64) {
- *   // handle base64
- * }
+ *                   API errors, or non-MP3 input (if any reference audio were passed).
  */
 export function textToAudio(prompt: string, options?: {
     model?: string | undefined;
@@ -94,100 +51,54 @@ export function textToAudio(prompt: string, options?: {
     seed?: number | undefined;
     steps?: number | undefined;
     cfg_scale?: number | undefined;
-    output_format?: string | undefined;
     accept?: string | undefined;
     filenamePrefix?: string | undefined;
 }): Promise<Object>;
 /**
  * Transforms an existing audio sample using a text prompt (audio-to-audio / style transfer).
  *
- * Uploads a reference audio file (or URL) and applies the prompt to generate a new
- * composition that incorporates elements of the input while following the text description.
- *
- * **Additional Parameter**:
- * - `strength`: Denoising strength (0.0 = identical to input, 1.0 = no influence from input).
- *
- * All other constraints and behavior are identical to `textToAudio`.
+ * **MP3 ONLY** — Input must be MP3. Output is always MP3.
  *
  * @async
  * @function audioToAudio
  * @param {string} prompt - Descriptive text prompt (English, max 10k chars).
- * @param {string|Buffer|Blob} audioInput - Reference audio:
- *        - Local file path (string)
- *        - Remote HTTP/HTTPS URL (string) – auto-downloaded with proper MIME
- *        - Buffer (raw bytes)
- *        - Blob (with optional name/type)
- * @param {Object} [options={}] - Generation options (see textToAudio for common params).
+ * @param {string|Buffer|Blob} audioInput - Reference audio (**must be MP3**).
+ * @param {Object} [options={}] - Generation options.
  * @param {number} [options.strength=1] - Denoising strength (0–1).
- * @param {string} [options.filenamePrefix='stability-audio-to-audio']
- * @returns {Promise<Object>} Same structure as textToAudio result.
- * @throws {Error} Same as textToAudio plus audio input validation errors.
- *
- * @example
- * const result = await audioToAudio(
- *   'transform into orchestral version with strings and choir',
- *   './reference-track.mp3',
- *   { strength: 0.75, duration: 180 }
- * );
+ * @returns {Promise<Object>} Same structure as textToAudio result (always .mp3).
+ * @throws {Error} Same as textToAudio plus non-MP3 input validation errors.
  */
 export function audioToAudio(prompt: string, audioInput: string | Buffer | Blob, options?: {
     strength?: number | undefined;
-    filenamePrefix?: string | undefined;
 }): Promise<Object>;
 /**
  * Performs audio inpainting: replaces a specified time segment of an audio file
  * with new content generated from a text prompt.
  *
- * Uses `mask_start` and `mask_end` to define the region to inpaint (in seconds).
- * The model fills the masked section while preserving the rest of the audio.
- *
- * Default mask: 30s → 380s (inpaint most of a long track).
+ * **MP3 ONLY** — Input must be MP3. Output is always MP3.
  *
  * @async
  * @function inpaint
  * @param {string} prompt - Text prompt describing the desired replacement content.
- * @param {string|Buffer|Blob} audioInput - Reference audio (same as audioToAudio).
+ * @param {string|Buffer|Blob} audioInput - Reference audio (**must be MP3**).
  * @param {Object} [options={}] - Generation options.
  * @param {number} [options.mask_start=30] - Start time (seconds) of the inpaint mask (0–380).
  * @param {number} [options.mask_end=380] - End time (seconds) of the inpaint mask (0–380).
- * @param {string} [options.filenamePrefix='stability-inpaint']
- * @returns {Promise<Object>} Same result structure as other generation methods.
+ * @returns {Promise<Object>} Same result structure as other generation methods (always .mp3).
  * @throws {Error} Validation errors for mask ranges, audio input, etc.
- *
- * @example
- * // Inpaint the middle section
- * const result = await inpaint(
- *   'add a soaring guitar solo in this section',
- *   'full-track.mp3',
- *   { mask_start: 60, mask_end: 120, duration: 180 }
- * );
  */
 export function inpaint(prompt: string, audioInput: string | Buffer | Blob, options?: {
     mask_start?: number | undefined;
     mask_end?: number | undefined;
-    filenamePrefix?: string | undefined;
 }): Promise<Object>;
 /**
  * Manually fetches or checks the status of a generation using its ID.
- * Useful for custom polling logic or resuming after a previous submission.
  *
  * @async
  * @function fetchResult
  * @param {string} id - Generation ID (from a previous 202 response).
  * @param {string} [acceptHeader='audio/*'] - `'audio/*'` or `'application/json'`.
- * @returns {Promise<Object>} Either:
- *          - Completed result (same as processResult)
- *          - `{ status: 'in-progress', id, raw }` if still 202
+ * @returns {Promise<Object>} Either completed result or in-progress status.
  * @throws {Error} If ID missing, 404 (expired), or other API error.
- *
- * @example
- * // Manual polling example
- * const id = await submit...; // or from previous call
- * let result;
- * while (true) {
- *   result = await fetchResult(id);
- *   if (result.status !== 'in-progress') break;
- *   await new Promise(r => setTimeout(r, 5000));
- * }
  */
 export function fetchResult(id: string, acceptHeader?: string): Promise<Object>;

package/types/API/stability.ai/image.d.ts

@@ -79,7 +79,7 @@ export function generateUltra(prompt: string, options?: {
     aspect_ratio?: string | undefined;
     seed?: number | undefined;
     output_format?: string | undefined;
-    image?: string | Buffer | Blob;
+    image?: string | Blob | Buffer<ArrayBufferLike> | undefined;
     strength?: number | undefined;
     style_preset?: string | undefined;
     accept?: string | undefined;
@@ -157,7 +157,7 @@ export function upscaleConservative(imageInput: string | Buffer | Blob, prompt:
  * @returns {Promise<Object>} Result with edited image.
  */
 export function editErase(imageInput: string | Buffer | Blob, options?: {
-    mask?: string | Buffer | Blob;
+    mask?: string | Blob | Buffer<ArrayBufferLike> | undefined;
     grow_mask?: number | undefined;
     seed?: number | undefined;
     output_format?: string | undefined;