@poof-bg/js 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+/**
+ * Poof SDK Types
+ */
+/** Configuration options for the Poof client */
+interface PoofOptions {
+    /** Your Poof API key */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.poof.bg/v1) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/** Output image format */
+type ImageFormat = 'png' | 'jpg' | 'webp';
+/** Output color channels */
+type Channels = 'rgba' | 'rgb';
+/** Output image size preset */
+type ImageSize = 'full' | 'preview' | 'small' | 'medium' | 'large';
+/** Options for background removal */
+interface RemoveBackgroundOptions {
+    /** Output format (default: png) */
+    format?: ImageFormat;
+    /** Color channels - rgba for transparency, rgb for opaque (default: rgba) */
+    channels?: Channels;
+    /** Background color (hex, rgb, or color name). Only applies when channels is 'rgb' */
+    bgColor?: string;
+    /** Output size preset (default: full) */
+    size?: ImageSize;
+    /** Crop to subject bounds (default: false) */
+    crop?: boolean;
+}
+/** Metadata returned with processed images */
+interface ProcessingMetadata {
+    /** Unique request identifier */
+    requestId: string;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+    /** Output image width in pixels */
+    width: number;
+    /** Output image height in pixels */
+    height: number;
+    /** Content type of the result */
+    contentType: string;
+}
+/** Result of background removal including image data and metadata */
+interface RemoveBackgroundResult {
+    /** The processed image data */
+    data: ArrayBuffer;
+    /** Processing metadata */
+    metadata: ProcessingMetadata;
+}
+/** Account information */
+interface AccountInfo {
+    /** Your organization ID */
+    organizationId: string;
+    /** Current plan name */
+    plan: string;
+    /** Total credits available in billing cycle */
+    maxCredits: number;
+    /** Credits used in current billing cycle */
+    usedCredits: number;
+    /** Credit threshold for auto-recharge (if enabled) */
+    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';
+/** API error response structure */
+interface ApiErrorResponse {
+    code: ErrorCode;
+    message: string;
+    details?: string;
+    request_id: string;
+}
+/** Valid input types for image processing */
+type ImageInput = File | Blob | ArrayBuffer | Buffer | Uint8Array | string;
+
+/**
+ * Poof API client for background removal
+ *
+ * @example
+ * ```typescript
+ * import { Poof } from '@poof-bg/js';
+ *
+ * const poof = new Poof({ apiKey: 'your-api-key' });
+ * const result = await poof.removeBackground(imageFile);
+ * ```
+ */
+declare class Poof {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options: PoofOptions);
+    /**
+     * Remove background from an image
+     *
+     * @param input - Image input: File, Blob, Buffer, ArrayBuffer, Uint8Array, or file path (Node.js)
+     * @param options - Processing options
+     * @returns Processed image data and metadata
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * 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'
+     * });
+     *
+     * // Node.js: from file path
+     * const result = await poof.removeBackground('/path/to/image.png');
+     *
+     * // Node.js: save to file
+     * const fs = require('fs');
+     * fs.writeFileSync('output.png', Buffer.from(result.data));
+     * ```
+     */
+    removeBackground(input: ImageInput, options?: RemoveBackgroundOptions): Promise<RemoveBackgroundResult>;
+    /**
+     * Get account information
+     *
+     * @returns Account info including plan and credit usage
+     *
+     * @example
+     * ```typescript
+     * const account = await poof.me();
+     * console.log(`Plan: ${account.plan}`);
+     * console.log(`Credits: ${account.usedCredits}/${account.maxCredits}`);
+     * ```
+     */
+    me(): Promise<AccountInfo>;
+    /** Make a fetch request with auth and timeout */
+    private fetch;
+    /** Handle error response */
+    private handleError;
+}
+
+/**
+ * Base error class for all Poof SDK errors
+ */
+declare class PoofError extends Error {
+    /** Machine-readable error code */
+    readonly code: string;
+    /** HTTP status code */
+    readonly status?: number;
+    /** Unique request ID for support */
+    readonly requestId?: string;
+    /** Additional details */
+    readonly details?: string;
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+    /** Create error from API response */
+    static fromResponse(response: ApiErrorResponse, status: number): PoofError;
+}
+/**
+ * Thrown when the API key is invalid or missing
+ */
+declare class AuthenticationError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when the account doesn't have permission
+ */
+declare class PermissionError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when the account has insufficient credits
+ */
+declare class PaymentRequiredError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when request parameters are invalid
+ */
+declare class ValidationError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when a server error occurs
+ */
+declare class ServerError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+
+export { type AccountInfo, type ApiErrorResponse, AuthenticationError, type Channels, type ErrorCode, type ImageFormat, type ImageInput, type ImageSize, PaymentRequiredError, PermissionError, Poof, PoofError, type PoofOptions, type ProcessingMetadata, RateLimitError, type RemoveBackgroundOptions, type RemoveBackgroundResult, ServerError, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Poof SDK Types
+ */
+/** Configuration options for the Poof client */
+interface PoofOptions {
+    /** Your Poof API key */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.poof.bg/v1) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/** Output image format */
+type ImageFormat = 'png' | 'jpg' | 'webp';
+/** Output color channels */
+type Channels = 'rgba' | 'rgb';
+/** Output image size preset */
+type ImageSize = 'full' | 'preview' | 'small' | 'medium' | 'large';
+/** Options for background removal */
+interface RemoveBackgroundOptions {
+    /** Output format (default: png) */
+    format?: ImageFormat;
+    /** Color channels - rgba for transparency, rgb for opaque (default: rgba) */
+    channels?: Channels;
+    /** Background color (hex, rgb, or color name). Only applies when channels is 'rgb' */
+    bgColor?: string;
+    /** Output size preset (default: full) */
+    size?: ImageSize;
+    /** Crop to subject bounds (default: false) */
+    crop?: boolean;
+}
+/** Metadata returned with processed images */
+interface ProcessingMetadata {
+    /** Unique request identifier */
+    requestId: string;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+    /** Output image width in pixels */
+    width: number;
+    /** Output image height in pixels */
+    height: number;
+    /** Content type of the result */
+    contentType: string;
+}
+/** Result of background removal including image data and metadata */
+interface RemoveBackgroundResult {
+    /** The processed image data */
+    data: ArrayBuffer;
+    /** Processing metadata */
+    metadata: ProcessingMetadata;
+}
+/** Account information */
+interface AccountInfo {
+    /** Your organization ID */
+    organizationId: string;
+    /** Current plan name */
+    plan: string;
+    /** Total credits available in billing cycle */
+    maxCredits: number;
+    /** Credits used in current billing cycle */
+    usedCredits: number;
+    /** Credit threshold for auto-recharge (if enabled) */
+    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';
+/** API error response structure */
+interface ApiErrorResponse {
+    code: ErrorCode;
+    message: string;
+    details?: string;
+    request_id: string;
+}
+/** Valid input types for image processing */
+type ImageInput = File | Blob | ArrayBuffer | Buffer | Uint8Array | string;
+
+/**
+ * Poof API client for background removal
+ *
+ * @example
+ * ```typescript
+ * import { Poof } from '@poof-bg/js';
+ *
+ * const poof = new Poof({ apiKey: 'your-api-key' });
+ * const result = await poof.removeBackground(imageFile);
+ * ```
+ */
+declare class Poof {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options: PoofOptions);
+    /**
+     * Remove background from an image
+     *
+     * @param input - Image input: File, Blob, Buffer, ArrayBuffer, Uint8Array, or file path (Node.js)
+     * @param options - Processing options
+     * @returns Processed image data and metadata
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * 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'
+     * });
+     *
+     * // Node.js: from file path
+     * const result = await poof.removeBackground('/path/to/image.png');
+     *
+     * // Node.js: save to file
+     * const fs = require('fs');
+     * fs.writeFileSync('output.png', Buffer.from(result.data));
+     * ```
+     */
+    removeBackground(input: ImageInput, options?: RemoveBackgroundOptions): Promise<RemoveBackgroundResult>;
+    /**
+     * Get account information
+     *
+     * @returns Account info including plan and credit usage
+     *
+     * @example
+     * ```typescript
+     * const account = await poof.me();
+     * console.log(`Plan: ${account.plan}`);
+     * console.log(`Credits: ${account.usedCredits}/${account.maxCredits}`);
+     * ```
+     */
+    me(): Promise<AccountInfo>;
+    /** Make a fetch request with auth and timeout */
+    private fetch;
+    /** Handle error response */
+    private handleError;
+}
+
+/**
+ * Base error class for all Poof SDK errors
+ */
+declare class PoofError extends Error {
+    /** Machine-readable error code */
+    readonly code: string;
+    /** HTTP status code */
+    readonly status?: number;
+    /** Unique request ID for support */
+    readonly requestId?: string;
+    /** Additional details */
+    readonly details?: string;
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+    /** Create error from API response */
+    static fromResponse(response: ApiErrorResponse, status: number): PoofError;
+}
+/**
+ * Thrown when the API key is invalid or missing
+ */
+declare class AuthenticationError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when the account doesn't have permission
+ */
+declare class PermissionError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when the account has insufficient credits
+ */
+declare class PaymentRequiredError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when request parameters are invalid
+ */
+declare class ValidationError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+/**
+ * Thrown when a server error occurs
+ */
+declare class ServerError extends PoofError {
+    constructor(message: string, code: string, options?: {
+        status?: number;
+        requestId?: string;
+        details?: string;
+    });
+}
+
+export { type AccountInfo, type ApiErrorResponse, AuthenticationError, type Channels, type ErrorCode, type ImageFormat, type ImageInput, type ImageSize, PaymentRequiredError, PermissionError, Poof, PoofError, type PoofOptions, type ProcessingMetadata, RateLimitError, type RemoveBackgroundOptions, type RemoveBackgroundResult, ServerError, ValidationError };