@poof-bg/js 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -12,6 +12,8 @@ interface PoofOptions {
 }
 /** Output image format */
 type ImageFormat = 'png' | 'jpg' | 'webp';
+/** Output video format: VP9 WebM (alpha or opaque), ProRes MOV (alpha or opaque) or H.264 MP4 (opaque) */
+type VideoFormat = 'webm' | 'mov' | 'mp4';
 /** Output color channels */
 type Channels = 'rgba' | 'rgb' | 'alpha';
 /** Output image size preset */
@@ -23,10 +25,19 @@ type ImageSize = 'full' | 'preview' | 'medium' | 'hd';
  * enlarging a smaller image.
  */
 type FitMode = 'contain' | 'cover' | 'scale-down';
+/** Options for waiting on a video job */
+interface WaitForJobOptions {
+    /** Delay between status polls in milliseconds (default: 3000) */
+    pollIntervalMs?: number;
+    /** Give up after this many milliseconds (default: 600000, i.e. 10 minutes) */
+    timeoutMs?: number;
+    /** Called after every poll with the latest job state */
+    onProgress?: (job: Job) => void;
+}
 /** Options for background removal */
 interface RemoveBackgroundOptions {
-    /** Output format (default: png) */
-    format?: ImageFormat;
+    /** Output format: png, jpg or webp for images (default: png); webm, mov or mp4 for videos (default: webm) */
+    format?: ImageFormat | VideoFormat;
     /** Color channels - rgba for transparency, rgb for opaque, alpha for the grayscale mask only (default: rgba) */
     channels?: Channels;
     /** Background color (hex, rgb, or color name). Applies when channels is 'rgb' or 'rgba' */
@@ -43,6 +54,11 @@ interface RemoveBackgroundOptions {
     height?: number;
     /** How to fit into width x height without stretching (default: contain) */
     fit?: FitMode;
+    /**
+     * Videos only: wait for the job to finish and return the completed Job
+     * instead of the queued one. Pass an object to tune polling.
+     */
+    wait?: boolean | WaitForJobOptions;
 }
 /** Metadata returned with processed images */
 interface ProcessingMetadata {
@@ -74,6 +90,59 @@ interface RemoveBackgroundResult {
     /** Processing metadata */
     metadata: ProcessingMetadata;
 }
+/** State of a video job */
+type JobStatus = 'queued' | 'processing' | 'completed' | 'failed';
+/** Why a video job failed */
+interface JobError {
+    /** Machine-readable error code, e.g. processing_failed */
+    code: string;
+    /** Human-readable description */
+    message: string;
+}
+/**
+ * A video background removal job. Returned with status 'queued' when a video
+ * is submitted; poll with getJob() or waitForJob() until it is 'completed'.
+ */
+interface Job {
+    /** Job ID, prefixed with job_ */
+    id: string;
+    /** queued and processing are transient; completed and failed are terminal */
+    status: JobStatus;
+    /** Fraction of the video processed so far, 0 to 1 */
+    progress: number;
+    /** When the job was accepted (ISO 8601) */
+    createdAt: string;
+    /** When processing began; null while queued */
+    startedAt: string | null;
+    /** When the job reached completed or failed; null until then */
+    completedAt: string | null;
+    /** Source video duration in seconds */
+    durationSeconds: number;
+    /** Source frame rate */
+    fps: number;
+    /** Source video width in pixels */
+    width: number;
+    /** Source video height in pixels */
+    height: number;
+    /** Number of frames in the source video */
+    frames: number;
+    /** Credits charged for this job (5 per second of video, 10 above 30 fps); refunded if it fails */
+    credits: number;
+    /** Requested output format */
+    format: VideoFormat;
+    /** Requested output channels */
+    channels: Channels;
+    /** URL of the job; GET it to poll for progress */
+    statusUrl: string;
+    /** Direct download URL of the result on the Poof CDN once completed, null before that. No API key needed */
+    resultUrl: string | null;
+    /** When the result is deleted, 24 hours after completion; null until completed */
+    expiresAt: string | null;
+    /** Set when status is failed, null otherwise */
+    error: JobError | null;
+    /** Processing statistics once completed (output_width, output_height, processing_seconds, ...), null before */
+    stats: Record<string, unknown> | null;
+}
 /** Account information */
 interface AccountInfo {
     /** Your organization ID */
@@ -88,7 +157,7 @@ interface AccountInfo {
     autoRechargeThreshold: number | null;
 }
 /** Error codes returned by the API */
-type ErrorCode = 'authentication_error' | 'permission_denied' | 'payment_required' | 'rate_limit_exceeded' | 'validation_error' | 'missing_image' | 'image_too_large' | 'upstream_error' | 'internal_server_error';
+type ErrorCode = 'authentication_error' | 'permission_denied' | 'payment_required' | 'rate_limit_exceeded' | 'validation_error' | 'missing_image' | 'image_too_large' | 'invalid_image' | 'video_too_large' | 'video_too_long' | 'invalid_video' | 'job_not_found' | 'job_failed' | 'upstream_error' | 'internal_server_error';
 /** API error response structure */
 interface ApiErrorResponse {
     code: ErrorCode;
@@ -96,8 +165,14 @@ interface ApiErrorResponse {
     details?: string;
     request_id: string;
 }
-/** Valid input types for image processing */
+/** Valid input types for image and video processing: file contents, or a file path in Node.js */
 type ImageInput = File | Blob | ArrayBuffer | Buffer | Uint8Array | string;
+/** A publicly reachable https URL that Poof downloads instead of an upload (images up to 20 MB, videos up to 500 MB) */
+interface UrlInput {
+    url: string;
+}
+/** Anything removeBackground() accepts: file contents, a file path (Node.js) or `{ url }` */
+type MediaInput = ImageInput | UrlInput;
 
 /**
  * Poof API client for background removal
@@ -116,37 +191,71 @@ declare class Poof {
     private readonly timeout;
     constructor(options: PoofOptions);
     /**
-     * Remove background from an image
+     * Remove the background from an image or a video.
      *
-     * @param input - Image input: File, Blob, Buffer, ArrayBuffer, Uint8Array, or file path (Node.js)
+     * Images are processed synchronously and come back as bytes. Videos are
+     * processed as a job: the call returns a queued {@link Job}; poll it with
+     * {@link getJob} / {@link waitForJob}, or pass `wait: true` to get the
+     * completed job (with `resultUrl`) directly. Use {@link isJob} to tell the
+     * two apart.
+     *
+     * @param input - File, Blob, Buffer, ArrayBuffer, Uint8Array, file path (Node.js), or `{ url }`
      * @param options - Processing options
-     * @returns Processed image data and metadata
+     * @returns Processed image data and metadata, or a video Job
      *
      * @example
      * ```typescript
-     * // Basic usage
+     * // Image
      * const result = await poof.removeBackground(file);
      * const imageBlob = new Blob([result.data], { type: result.metadata.contentType });
      *
      * // With options
-     * const result = await poof.removeBackground(file, {
-     *   format: 'webp',
-     *   crop: true,
-     *   size: 'medium'
-     * });
+     * const result = await poof.removeBackground(file, { format: 'webp', crop: true, size: 'medium' });
      *
      * // Exact 500x500 output, subject cropped and centred, never stretched
      * const result = await poof.removeBackground(file, { crop: true, width: 500, height: 500 });
      *
-     * // Node.js: from file path
-     * const result = await poof.removeBackground('/path/to/image.png');
+     * // Video: submit, then wait for the result
+     * const job = await poof.removeBackground('./clip.mp4', { format: 'webm' });
+     * const done = await poof.waitForJob(job);
+     * console.log(done.resultUrl);
+     *
+     * // Video from a public URL, waiting inline
+     * const done = await poof.removeBackground({ url: 'https://example.com/clip.mp4' }, { wait: true });
+     * ```
+     */
+    removeBackground(input: MediaInput, options?: RemoveBackgroundOptions): Promise<RemoveBackgroundResult | Job>;
+    /**
+     * Get the current state of a video job. Polling is free and does not count
+     * against your rate limit.
+     *
+     * @param jobId - The job ID returned by removeBackground()
      *
-     * // Node.js: save to file
-     * const fs = require('fs');
-     * fs.writeFileSync('output.png', Buffer.from(result.data));
+     * @example
+     * ```typescript
+     * const job = await poof.getJob('job_8f3a1c2e9b7d4a10');
+     * console.log(job.status, job.progress);
      * ```
      */
-    removeBackground(input: ImageInput, options?: RemoveBackgroundOptions): Promise<RemoveBackgroundResult>;
+    getJob(jobId: string): Promise<Job>;
+    /**
+     * Poll a video job until it is completed.
+     *
+     * @param job - A Job or a job ID
+     * @param options - Poll interval, timeout and progress callback
+     * @returns The completed job; `resultUrl` is a direct download link valid for 24 hours
+     * @throws PoofError with code `job_failed` if the job fails (credits are refunded),
+     *   or code `timeout` if `timeoutMs` elapses first
+     *
+     * @example
+     * ```typescript
+     * const done = await poof.waitForJob(job, {
+     *   onProgress: (j) => console.log(`${Math.round(j.progress * 100)}%`),
+     * });
+     * const video = await fetch(done.resultUrl!);
+     * ```
+     */
+    waitForJob(job: Job | string, options?: WaitForJobOptions): Promise<Job>;
     /**
      * Get account information
      *
@@ -165,6 +274,20 @@ declare class Poof {
     /** Handle error response */
     private handleError;
 }
+/**
+ * Type guard: did removeBackground() return a video Job rather than image bytes?
+ *
+ * @example
+ * ```typescript
+ * const result = await poof.removeBackground(input);
+ * if (isJob(result)) {
+ *   const done = await poof.waitForJob(result);
+ * } else {
+ *   fs.writeFileSync('output.png', Buffer.from(result.data));
+ * }
+ * ```
+ */
+declare function isJob(value: RemoveBackgroundResult | Job): value is Job;
 
 /**
  * Base error class for all Poof SDK errors
@@ -247,4 +370,4 @@ declare class ServerError extends PoofError {
     });
 }
 
-export { type AccountInfo, type ApiErrorResponse, AuthenticationError, type Channels, type ErrorCode, type FitMode, type ImageFormat, type ImageInput, type ImageSize, PaymentRequiredError, PermissionError, Poof, PoofError, type PoofOptions, type ProcessingMetadata, RateLimitError, type RemoveBackgroundOptions, type RemoveBackgroundResult, ServerError, ValidationError };
+export { type AccountInfo, type ApiErrorResponse, AuthenticationError, type Channels, type ErrorCode, type FitMode, type ImageFormat, type ImageInput, type ImageSize, type Job, type JobError, type JobStatus, type MediaInput, PaymentRequiredError, PermissionError, Poof, PoofError, type PoofOptions, type ProcessingMetadata, RateLimitError, type RemoveBackgroundOptions, type RemoveBackgroundResult, ServerError, type UrlInput, ValidationError, type VideoFormat, type WaitForJobOptions, isJob };

package/dist/index.d.ts

@@ -12,6 +12,8 @@ interface PoofOptions {
 }
 /** Output image format */
 type ImageFormat = 'png' | 'jpg' | 'webp';
+/** Output video format: VP9 WebM (alpha or opaque), ProRes MOV (alpha or opaque) or H.264 MP4 (opaque) */
+type VideoFormat = 'webm' | 'mov' | 'mp4';
 /** Output color channels */
 type Channels = 'rgba' | 'rgb' | 'alpha';
 /** Output image size preset */
@@ -23,10 +25,19 @@ type ImageSize = 'full' | 'preview' | 'medium' | 'hd';
  * enlarging a smaller image.
  */
 type FitMode = 'contain' | 'cover' | 'scale-down';
+/** Options for waiting on a video job */
+interface WaitForJobOptions {
+    /** Delay between status polls in milliseconds (default: 3000) */
+    pollIntervalMs?: number;
+    /** Give up after this many milliseconds (default: 600000, i.e. 10 minutes) */
+    timeoutMs?: number;
+    /** Called after every poll with the latest job state */
+    onProgress?: (job: Job) => void;
+}
 /** Options for background removal */
 interface RemoveBackgroundOptions {
-    /** Output format (default: png) */
-    format?: ImageFormat;
+    /** Output format: png, jpg or webp for images (default: png); webm, mov or mp4 for videos (default: webm) */
+    format?: ImageFormat | VideoFormat;
     /** Color channels - rgba for transparency, rgb for opaque, alpha for the grayscale mask only (default: rgba) */
     channels?: Channels;
     /** Background color (hex, rgb, or color name). Applies when channels is 'rgb' or 'rgba' */
@@ -43,6 +54,11 @@ interface RemoveBackgroundOptions {
     height?: number;
     /** How to fit into width x height without stretching (default: contain) */
     fit?: FitMode;
+    /**
+     * Videos only: wait for the job to finish and return the completed Job
+     * instead of the queued one. Pass an object to tune polling.
+     */
+    wait?: boolean | WaitForJobOptions;
 }
 /** Metadata returned with processed images */
 interface ProcessingMetadata {
@@ -74,6 +90,59 @@ interface RemoveBackgroundResult {
     /** Processing metadata */
     metadata: ProcessingMetadata;
 }
+/** State of a video job */
+type JobStatus = 'queued' | 'processing' | 'completed' | 'failed';
+/** Why a video job failed */
+interface JobError {
+    /** Machine-readable error code, e.g. processing_failed */
+    code: string;
+    /** Human-readable description */
+    message: string;
+}
+/**
+ * A video background removal job. Returned with status 'queued' when a video
+ * is submitted; poll with getJob() or waitForJob() until it is 'completed'.
+ */
+interface Job {
+    /** Job ID, prefixed with job_ */
+    id: string;
+    /** queued and processing are transient; completed and failed are terminal */
+    status: JobStatus;
+    /** Fraction of the video processed so far, 0 to 1 */
+    progress: number;
+    /** When the job was accepted (ISO 8601) */
+    createdAt: string;
+    /** When processing began; null while queued */
+    startedAt: string | null;
+    /** When the job reached completed or failed; null until then */
+    completedAt: string | null;
+    /** Source video duration in seconds */
+    durationSeconds: number;
+    /** Source frame rate */
+    fps: number;
+    /** Source video width in pixels */
+    width: number;
+    /** Source video height in pixels */
+    height: number;
+    /** Number of frames in the source video */
+    frames: number;
+    /** Credits charged for this job (5 per second of video, 10 above 30 fps); refunded if it fails */
+    credits: number;
+    /** Requested output format */
+    format: VideoFormat;
+    /** Requested output channels */
+    channels: Channels;
+    /** URL of the job; GET it to poll for progress */
+    statusUrl: string;
+    /** Direct download URL of the result on the Poof CDN once completed, null before that. No API key needed */
+    resultUrl: string | null;
+    /** When the result is deleted, 24 hours after completion; null until completed */
+    expiresAt: string | null;
+    /** Set when status is failed, null otherwise */
+    error: JobError | null;
+    /** Processing statistics once completed (output_width, output_height, processing_seconds, ...), null before */
+    stats: Record<string, unknown> | null;
+}
 /** Account information */
 interface AccountInfo {
     /** Your organization ID */
@@ -88,7 +157,7 @@ interface AccountInfo {
     autoRechargeThreshold: number | null;
 }
 /** Error codes returned by the API */
-type ErrorCode = 'authentication_error' | 'permission_denied' | 'payment_required' | 'rate_limit_exceeded' | 'validation_error' | 'missing_image' | 'image_too_large' | 'upstream_error' | 'internal_server_error';
+type ErrorCode = 'authentication_error' | 'permission_denied' | 'payment_required' | 'rate_limit_exceeded' | 'validation_error' | 'missing_image' | 'image_too_large' | 'invalid_image' | 'video_too_large' | 'video_too_long' | 'invalid_video' | 'job_not_found' | 'job_failed' | 'upstream_error' | 'internal_server_error';
 /** API error response structure */
 interface ApiErrorResponse {
     code: ErrorCode;
@@ -96,8 +165,14 @@ interface ApiErrorResponse {
     details?: string;
     request_id: string;
 }
-/** Valid input types for image processing */
+/** Valid input types for image and video processing: file contents, or a file path in Node.js */
 type ImageInput = File | Blob | ArrayBuffer | Buffer | Uint8Array | string;
+/** A publicly reachable https URL that Poof downloads instead of an upload (images up to 20 MB, videos up to 500 MB) */
+interface UrlInput {
+    url: string;
+}
+/** Anything removeBackground() accepts: file contents, a file path (Node.js) or `{ url }` */
+type MediaInput = ImageInput | UrlInput;
 
 /**
  * Poof API client for background removal
@@ -116,37 +191,71 @@ declare class Poof {
     private readonly timeout;
     constructor(options: PoofOptions);
     /**
-     * Remove background from an image
+     * Remove the background from an image or a video.
      *
-     * @param input - Image input: File, Blob, Buffer, ArrayBuffer, Uint8Array, or file path (Node.js)
+     * Images are processed synchronously and come back as bytes. Videos are
+     * processed as a job: the call returns a queued {@link Job}; poll it with
+     * {@link getJob} / {@link waitForJob}, or pass `wait: true` to get the
+     * completed job (with `resultUrl`) directly. Use {@link isJob} to tell the
+     * two apart.
+     *
+     * @param input - File, Blob, Buffer, ArrayBuffer, Uint8Array, file path (Node.js), or `{ url }`
      * @param options - Processing options
-     * @returns Processed image data and metadata
+     * @returns Processed image data and metadata, or a video Job
      *
      * @example
      * ```typescript
-     * // Basic usage
+     * // Image
      * const result = await poof.removeBackground(file);
      * const imageBlob = new Blob([result.data], { type: result.metadata.contentType });
      *
      * // With options
-     * const result = await poof.removeBackground(file, {
-     *   format: 'webp',
-     *   crop: true,
-     *   size: 'medium'
-     * });
+     * const result = await poof.removeBackground(file, { format: 'webp', crop: true, size: 'medium' });
      *
      * // Exact 500x500 output, subject cropped and centred, never stretched
      * const result = await poof.removeBackground(file, { crop: true, width: 500, height: 500 });
      *
-     * // Node.js: from file path
-     * const result = await poof.removeBackground('/path/to/image.png');
+     * // Video: submit, then wait for the result
+     * const job = await poof.removeBackground('./clip.mp4', { format: 'webm' });
+     * const done = await poof.waitForJob(job);
+     * console.log(done.resultUrl);
+     *
+     * // Video from a public URL, waiting inline
+     * const done = await poof.removeBackground({ url: 'https://example.com/clip.mp4' }, { wait: true });
+     * ```
+     */
+    removeBackground(input: MediaInput, options?: RemoveBackgroundOptions): Promise<RemoveBackgroundResult | Job>;
+    /**
+     * Get the current state of a video job. Polling is free and does not count
+     * against your rate limit.
+     *
+     * @param jobId - The job ID returned by removeBackground()
      *
-     * // Node.js: save to file
-     * const fs = require('fs');
-     * fs.writeFileSync('output.png', Buffer.from(result.data));
+     * @example
+     * ```typescript
+     * const job = await poof.getJob('job_8f3a1c2e9b7d4a10');
+     * console.log(job.status, job.progress);
      * ```
      */
-    removeBackground(input: ImageInput, options?: RemoveBackgroundOptions): Promise<RemoveBackgroundResult>;
+    getJob(jobId: string): Promise<Job>;
+    /**
+     * Poll a video job until it is completed.
+     *
+     * @param job - A Job or a job ID
+     * @param options - Poll interval, timeout and progress callback
+     * @returns The completed job; `resultUrl` is a direct download link valid for 24 hours
+     * @throws PoofError with code `job_failed` if the job fails (credits are refunded),
+     *   or code `timeout` if `timeoutMs` elapses first
+     *
+     * @example
+     * ```typescript
+     * const done = await poof.waitForJob(job, {
+     *   onProgress: (j) => console.log(`${Math.round(j.progress * 100)}%`),
+     * });
+     * const video = await fetch(done.resultUrl!);
+     * ```
+     */
+    waitForJob(job: Job | string, options?: WaitForJobOptions): Promise<Job>;
     /**
      * Get account information
      *
@@ -165,6 +274,20 @@ declare class Poof {
     /** Handle error response */
     private handleError;
 }
+/**
+ * Type guard: did removeBackground() return a video Job rather than image bytes?
+ *
+ * @example
+ * ```typescript
+ * const result = await poof.removeBackground(input);
+ * if (isJob(result)) {
+ *   const done = await poof.waitForJob(result);
+ * } else {
+ *   fs.writeFileSync('output.png', Buffer.from(result.data));
+ * }
+ * ```
+ */
+declare function isJob(value: RemoveBackgroundResult | Job): value is Job;
 
 /**
  * Base error class for all Poof SDK errors
@@ -247,4 +370,4 @@ declare class ServerError extends PoofError {
     });
 }
 
-export { type AccountInfo, type ApiErrorResponse, AuthenticationError, type Channels, type ErrorCode, type FitMode, type ImageFormat, type ImageInput, type ImageSize, PaymentRequiredError, PermissionError, Poof, PoofError, type PoofOptions, type ProcessingMetadata, RateLimitError, type RemoveBackgroundOptions, type RemoveBackgroundResult, ServerError, ValidationError };
+export { type AccountInfo, type ApiErrorResponse, AuthenticationError, type Channels, type ErrorCode, type FitMode, type ImageFormat, type ImageInput, type ImageSize, type Job, type JobError, type JobStatus, type MediaInput, PaymentRequiredError, PermissionError, Poof, PoofError, type PoofOptions, type ProcessingMetadata, RateLimitError, type RemoveBackgroundOptions, type RemoveBackgroundResult, ServerError, type UrlInput, ValidationError, type VideoFormat, type WaitForJobOptions, isJob };