@tinify-dev/client 0.1.0

package/dist/types-D58KVL3U.d.ts

@@ -0,0 +1,219 @@
+/** Default API origin. Override with `baseUrl` or the `TINIFY_BASE_URL` env var. */
+declare const DEFAULT_BASE_URL = "https://api.tinify.dev";
+/** Maximum accepted image size in bytes (40 MiB), matching the server limit. */
+declare const MAX_FILE_BYTES = 41943040;
+/** Maximum number of files per batch. */
+declare const MAX_BATCH_FILES = 200;
+/** Batch statuses that will never change again. */
+declare const BATCH_TERMINAL_STATUSES: readonly ["succeeded", "partially_succeeded", "failed", "canceled", "expired"];
+
+/**
+ * Error codes the API is known to return. The union stays open (`string`)
+ * because the server may add codes without a client release.
+ */
+type KnownTinifyErrorCode = "missing_authorization" | "invalid_api_key" | "missing_identity" | "insufficient_scope" | "account_unavailable" | "invalid_request" | "invalid_idempotency_key" | "idempotency_conflict" | "validation_failed" | "file_too_large" | "unsupported_media_type" | "invalid_quality_mode" | "lossless_not_supported" | "invalid_resize" | "invalid_crop" | "invalid_operation" | "quota_exhausted" | "too_many_upload_sessions" | "upload_session_storage_limit" | "batch_not_found" | "batch_too_large" | "batch_plan_required" | "batch_not_complete" | "batch_has_no_results" | "uploads_incomplete" | "duplicate_client_id" | "invalid_target_format" | "same_format_conversion" | "invalid_target_size" | "target_size_conflict" | "internal_error";
+type TinifyErrorCode = KnownTinifyErrorCode | (string & {});
+type QualityMode = "balanced" | "best_quality" | "lossless";
+/**
+ * Output format for {@link TinifyClient.convert}.
+ *
+ * @beta The `/api/v1/images/convert` endpoint is rolling out server-side and
+ * may not be enabled for every account yet.
+ */
+type TargetFormat = "avif" | "webp" | "jpeg" | "png";
+type ImageOperation = "compress" | "resize" | "crop" | "convert";
+/** Values of the X-RateLimit-* response headers. `reset` is epoch seconds. */
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+}
+/** Envelope returned by every client call. */
+interface TinifyResponse<T> {
+    data: T;
+    /** Server request id (`request_id` body field or `X-Request-Id` header). */
+    requestId: string;
+    /** Parsed X-RateLimit-* headers, or `null` when the server omitted them. */
+    rateLimit: RateLimitInfo | null;
+}
+/** `data` object of a successful synchronous image operation. */
+interface ImageResultData {
+    job_id: string;
+    operation?: ImageOperation;
+    status: "succeeded";
+    /**
+     * `true` when the result is smaller than the input, `false` when the API
+     * returned the original bytes because it could not shrink them, `null`
+     * when the concept does not apply (resize/crop).
+     */
+    optimized: boolean | null;
+    /**
+     * Whether the result met the requested byte budget. Present only when
+     * compress ran with `target_size_bytes`.
+     */
+    target_size_achieved?: boolean;
+    quality_mode?: string;
+    original_format?: string;
+    result_format?: string;
+    original_bytes: number;
+    result_bytes: number;
+    /** Positive means the result grew. */
+    byte_change_percent?: number;
+    width: number | null;
+    height: number | null;
+    duration_ms?: number;
+    /** Expires two hours after the operation completes. */
+    download_url: string;
+    expires_at: string;
+}
+/** GET /api/v1/usage response body. */
+interface Usage {
+    plan: string;
+    period_start: string;
+    period_end: string;
+    included: number;
+    reserved: number;
+    used: number;
+    remaining: number;
+}
+interface CompressOptions {
+    quality_mode?: QualityMode;
+    /**
+     * Ask the encoder to aim for a result at or below this many bytes.
+     *
+     * @beta Depends on a server rollout; accounts without it receive
+     * `validation_failed` or the parameter is ignored.
+     */
+    target_size_bytes?: number;
+}
+interface ResizeOptions {
+    width?: number;
+    height?: number;
+    scale?: number;
+    keep_aspect_ratio?: boolean;
+    optimize?: boolean;
+}
+interface CropOptions {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Options for {@link TinifyClient.convert}.
+ *
+ * @beta The convert endpoint is rolling out server-side.
+ */
+interface ConvertOptions {
+    format: TargetFormat;
+    quality_mode?: QualityMode;
+}
+/** Per-call options accepted by every network method. */
+interface RequestOptions {
+    /**
+     * Override the auto-generated Idempotency-Key (8-160 chars). The same key
+     * is reused for every retry of the call.
+     */
+    idempotencyKey?: string;
+    /** Abort the call (including retries and waits). */
+    signal?: AbortSignal;
+    /** Multipart filename override for buffer/blob inputs. */
+    filename?: string;
+}
+type BatchOperation = "compress" | "resize" | "crop" | "convert";
+type BatchStatus = "awaiting_upload" | "queued" | "processing" | "succeeded" | "partially_succeeded" | "failed" | "canceled" | "expired";
+type BatchTerminalStatus = (typeof BATCH_TERMINAL_STATUSES)[number];
+type BatchContentType = "image/jpeg" | "image/png" | "image/webp" | "image/avif";
+/** One manifest entry sent to POST /api/v1/batches. */
+interface BatchFileManifestEntry {
+    /** Your identifier for the file; must be unique within the batch. */
+    client_id: string;
+    filename: string;
+    /** Exact size of the bytes you will PUT (1..41943040). */
+    size_bytes: number;
+    content_type: BatchContentType;
+}
+interface CreateBatchParams {
+    operation: BatchOperation;
+    /**
+     * Operation options, mirroring the synchronous endpoints:
+     *
+     * - `convert` requires {@link ConvertOptions.format}; files already in the
+     *   target format fail per job with `same_format_conversion`.
+     * - `compress` accepts `quality_mode` and `target_size_bytes`; the target
+     *   size is skipped per job when it is not smaller than that job's input.
+     */
+    options: CompressOptions | ResizeOptions | CropOptions | ConvertOptions | Record<string, unknown>;
+    files: BatchFileManifestEntry[];
+}
+/** Presigned upload slot returned when a batch is created. */
+interface BatchUpload {
+    file_id: string;
+    client_id: string;
+    upload_url: string;
+    /** Send these headers verbatim on the PUT. Do NOT add Authorization. */
+    headers: Record<string, string>;
+}
+interface BatchUploadSession {
+    id: string;
+    status: "awaiting_upload";
+    expires_at: string;
+    uploads: BatchUpload[];
+}
+interface BatchFileError {
+    code: TinifyErrorCode;
+}
+interface BatchFile {
+    id: string;
+    client_id: string;
+    filename: string;
+    status: string;
+    original_bytes: number | null;
+    result_bytes: number | null;
+    optimized: boolean | null;
+    duration_ms: number | null;
+    error: BatchFileError | null;
+    /** Signed download URL; present only once the batch reached a result state. */
+    download_url: string | null;
+}
+interface Batch {
+    id: string;
+    operation: BatchOperation;
+    status: BatchStatus;
+    expires_at: string;
+    files: BatchFile[];
+}
+/** POST /api/v1/batches/{id}/commit response body. */
+interface CommitBatchResult {
+    id: string;
+    status: BatchStatus;
+}
+interface UploadBatchFilesOptions {
+    /** Parallel presigned PUTs. Default 4. */
+    concurrency?: number;
+    signal?: AbortSignal;
+}
+interface WaitForBatchOptions {
+    /** First poll delay in milliseconds. Default 1000. */
+    pollIntervalMs?: number;
+    /** Poll delay ceiling in milliseconds. Default 10000. */
+    maxPollIntervalMs?: number;
+    /** Total waiting budget in milliseconds. Default 600000 (10 minutes). */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+type FetchFunction = (input: string | URL, init?: RequestInit) => Promise<Response>;
+interface TinifyClientOptions {
+    /** API key (`tnf_live_*` or `tnf_test_*`). Falls back to TINIFY_API_KEY. */
+    apiKey?: string;
+    /** API origin. Falls back to TINIFY_BASE_URL, then https://api.tinify.dev. */
+    baseUrl?: string;
+    /** Retries after the initial attempt for 429/503/network failures. Default 3. */
+    maxRetries?: number;
+    /** Per-attempt timeout in milliseconds. Default 60000. */
+    timeoutMs?: number;
+    /** Injectable fetch implementation (used for testing and custom agents). */
+    fetch?: FetchFunction;
+}
+
+export { type BatchUploadSession as B, type CompressOptions as C, DEFAULT_BASE_URL as D, type FetchFunction as F, type ImageResultData as I, type KnownTinifyErrorCode as K, MAX_BATCH_FILES as M, type QualityMode as Q, type RequestOptions as R, type TargetFormat as T, type Usage as U, type WaitForBatchOptions as W, type TinifyClientOptions as a, type TinifyResponse as b, type ResizeOptions as c, type CropOptions as d, type ConvertOptions as e, type CreateBatchParams as f, type UploadBatchFilesOptions as g, type CommitBatchResult as h, type Batch as i, type TinifyErrorCode as j, type BatchStatus as k, type BatchTerminalStatus as l, BATCH_TERMINAL_STATUSES as m, type BatchContentType as n, type BatchFile as o, type BatchFileError as p, type BatchFileManifestEntry as q, type BatchOperation as r, type BatchUpload as s, type ImageOperation as t, MAX_FILE_BYTES as u, type RateLimitInfo as v };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tinify-dev/client",
+  "version": "0.1.0",
+  "description": "Zero-dependency TypeScript client for the Tinify.dev image API: compress, resize, crop, convert, batches, and usage.",
+  "license": "MIT",
+  "author": "Stian Larsen",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "tinify-dev": "dist/cli.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "tinify",
+    "image",
+    "compression",
+    "resize",
+    "crop",
+    "avif",
+    "webp",
+    "png",
+    "jpeg",
+    "api-client"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check:publint": "publint",
+    "check:attw": "attw --pack ."
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.16.4",
+    "@types/node": "^20.17.9",
+    "publint": "^0.2.12",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "undici": "^6.21.0",
+    "vitest": "^2.1.8"
+  }
+}