@tinify-dev/client 0.1.0

package/dist/index.cjs

@@ -0,0 +1,586 @@
+'use strict';
+
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://api.tinify.dev";
+var ENV_API_KEY = "TINIFY_API_KEY";
+var ENV_BASE_URL = "TINIFY_BASE_URL";
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_TIMEOUT_MS = 6e4;
+var BACKOFF_BASE_MS = 500;
+var BACKOFF_CAP_MS = 8e3;
+var MAX_FILE_BYTES = 41943040;
+var MAX_BATCH_FILES = 200;
+var DEFAULT_UPLOAD_CONCURRENCY = 4;
+var DEFAULT_POLL_INTERVAL_MS = 1e3;
+var DEFAULT_POLL_GROWTH = 1.5;
+var DEFAULT_MAX_POLL_INTERVAL_MS = 1e4;
+var DEFAULT_WAIT_TIMEOUT_MS = 6e5;
+var BATCH_TERMINAL_STATUSES = [
+  "succeeded",
+  "partially_succeeded",
+  "failed",
+  "canceled",
+  "expired"
+];
+var IDEMPOTENCY_KEY_MIN_LENGTH = 8;
+var IDEMPOTENCY_KEY_MAX_LENGTH = 160;
+
+// src/errors.ts
+var TinifyError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TinifyError";
+  }
+};
+var TinifyApiError = class extends TinifyError {
+  status;
+  code;
+  requestId;
+  details;
+  retryAfter;
+  constructor(init) {
+    super(`${init.code} (HTTP ${init.status}): ${init.message} [request_id: ${init.requestId}]`);
+    this.name = "TinifyApiError";
+    this.status = init.status;
+    this.code = init.code;
+    this.requestId = init.requestId;
+    this.details = init.details ?? {};
+    if (init.retryAfter !== void 0) this.retryAfter = init.retryAfter;
+  }
+};
+var TinifyNetworkError = class extends TinifyError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TinifyNetworkError";
+  }
+};
+var TinifyTimeoutError = class extends TinifyError {
+  timeoutMs;
+  constructor(message, timeoutMs) {
+    super(message);
+    this.name = "TinifyTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+
+// src/inputs.ts
+var DEFAULT_FILENAME = "image";
+async function normalizeInput(input, filename) {
+  if (typeof input === "string") {
+    let fs;
+    let path;
+    try {
+      fs = await import('fs/promises');
+      path = await import('path');
+    } catch {
+      throw new TinifyError(
+        "File path inputs are only supported in Node.js. Pass a Blob or File instead."
+      );
+    }
+    const bytes = await fs.readFile(input);
+    return {
+      blob: new Blob([bytesToView(bytes)]),
+      filename: filename ?? path.basename(input)
+    };
+  }
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    const name = filename ?? (typeof File !== "undefined" && input instanceof File && input.name ? input.name : DEFAULT_FILENAME);
+    return { blob: input, filename: name };
+  }
+  if (input instanceof ArrayBuffer) {
+    return { blob: new Blob([input]), filename: filename ?? DEFAULT_FILENAME };
+  }
+  if (ArrayBuffer.isView(input)) {
+    return {
+      blob: new Blob([bytesToView(input)]),
+      filename: filename ?? DEFAULT_FILENAME
+    };
+  }
+  throw new TypeError(
+    "Unsupported input: expected a file path, Uint8Array, ArrayBuffer, Blob, or File."
+  );
+}
+function bytesToView(view) {
+  const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+  if (bytes.buffer instanceof ArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+    return bytes;
+  }
+  const copy = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+  copy.set(bytes);
+  return copy;
+}
+
+// src/batches.ts
+var TERMINAL = new Set(BATCH_TERMINAL_STATUSES);
+function isTerminalBatchStatus(status) {
+  return TERMINAL.has(status);
+}
+async function uploadBatchFiles(fetchImpl, session, files, options = {}) {
+  const missing = session.uploads.map((upload) => upload.client_id).filter((clientId) => !(clientId in files));
+  if (missing.length > 0) {
+    throw new TinifyError(
+      `Missing input for batch client_id(s): ${missing.join(", ")}. Pass a { client_id: input } record covering every file in the session.`
+    );
+  }
+  const queue = [...session.uploads];
+  const concurrency = Math.max(
+    1,
+    Math.min(options.concurrency ?? DEFAULT_UPLOAD_CONCURRENCY, queue.length)
+  );
+  const workers = Array.from({ length: concurrency }, async () => {
+    for (; ; ) {
+      const upload = queue.shift();
+      if (upload === void 0) return;
+      options.signal?.throwIfAborted();
+      await putOne(fetchImpl, upload, files[upload.client_id], options.signal);
+    }
+  });
+  await Promise.all(workers);
+}
+async function putOne(fetchImpl, upload, input, signal) {
+  const { blob } = await normalizeInput(input);
+  let response;
+  try {
+    response = await fetchImpl(upload.upload_url, {
+      method: "PUT",
+      headers: upload.headers,
+      body: blob,
+      ...signal !== void 0 ? { signal } : {}
+    });
+  } catch (error) {
+    throw new TinifyNetworkError(
+      `Upload for client_id "${upload.client_id}" failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new TinifyError(
+      `Upload for client_id "${upload.client_id}" was rejected with HTTP ${response.status}` + (text ? `: ${text.slice(0, 200)}` : ".")
+    );
+  }
+  await response.arrayBuffer().catch(() => void 0);
+}
+
+// src/http.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 503]);
+function generateIdempotencyKey() {
+  return globalThis.crypto.randomUUID();
+}
+function validateIdempotencyKey(key) {
+  if (key.length < IDEMPOTENCY_KEY_MIN_LENGTH || key.length > IDEMPOTENCY_KEY_MAX_LENGTH) {
+    throw new TinifyError(
+      `Idempotency keys must be ${IDEMPOTENCY_KEY_MIN_LENGTH}-${IDEMPOTENCY_KEY_MAX_LENGTH} characters (got ${key.length}).`
+    );
+  }
+}
+function parseRetryAfterMs(header) {
+  if (header === null || header.trim() === "") return void 0;
+  const value = header.trim();
+  if (/^\d+$/.test(value)) return Number(value) * 1e3;
+  const date = Date.parse(value);
+  if (Number.isNaN(date)) return void 0;
+  return Math.max(0, date - Date.now());
+}
+function backoffMs(attempt) {
+  const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
+  return Math.random() * ceiling;
+}
+function rateLimitFromHeaders(headers) {
+  const limit = headers.get("x-ratelimit-limit");
+  const remaining = headers.get("x-ratelimit-remaining");
+  const reset = headers.get("x-ratelimit-reset");
+  if (limit === null || remaining === null || reset === null) return null;
+  return { limit: Number(limit), remaining: Number(remaining), reset: Number(reset) };
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function abortReason(signal) {
+  return signal.reason ?? new TinifyError("The operation was aborted.");
+}
+async function throwApiError(response) {
+  const text = await response.text().catch(() => "");
+  let body;
+  try {
+    body = text ? JSON.parse(text) : void 0;
+  } catch {
+    body = void 0;
+  }
+  const envelope = body ?? {};
+  const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+  throw new TinifyApiError({
+    status: response.status,
+    code: envelope.error?.code ?? "unknown_error",
+    message: envelope.error?.message ?? `Unexpected HTTP ${response.status} response.`,
+    requestId: envelope.request_id ?? response.headers.get("x-request-id") ?? "unavailable",
+    details: envelope.error?.details ?? {},
+    ...retryAfterMs !== void 0 ? { retryAfter: retryAfterMs / 1e3 } : {}
+  });
+}
+var HttpClient = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  get baseUrl() {
+    return this.config.baseUrl;
+  }
+  get fetchImpl() {
+    return this.config.fetchImpl;
+  }
+  /**
+   * Performs a request with retry semantics:
+   * - retries 429/503 (honoring Retry-After) and network failures,
+   * - never retries any other 4xx/5xx,
+   * - reuses one Idempotency-Key across every attempt of the call.
+   */
+  async request(options) {
+    const url = new URL(options.path, `${this.config.baseUrl}/`).toString();
+    let idempotencyKey;
+    if (options.idempotencyKey === "auto") {
+      idempotencyKey = generateIdempotencyKey();
+    } else if (options.idempotencyKey !== void 0) {
+      validateIdempotencyKey(options.idempotencyKey);
+      idempotencyKey = options.idempotencyKey;
+    }
+    let attempt = 0;
+    for (; ; ) {
+      options.signal?.throwIfAborted();
+      const headers = {
+        authorization: `Bearer ${this.config.apiKey}`,
+        accept: "application/json",
+        "user-agent": "@tinify-dev/client/0.1.0"
+      };
+      if (idempotencyKey !== void 0) headers["idempotency-key"] = idempotencyKey;
+      if (options.contentType !== void 0) headers["content-type"] = options.contentType;
+      let response;
+      try {
+        response = await this.fetchWithTimeout(
+          url,
+          {
+            method: options.method,
+            headers,
+            ...options.body !== void 0 ? { body: options.body() } : {}
+          },
+          options.signal
+        );
+      } catch (error) {
+        if (error instanceof TinifyTimeoutError) throw error;
+        if (options.signal?.aborted) throw error;
+        if (attempt < this.config.maxRetries) {
+          await sleep(backoffMs(attempt), options.signal);
+          attempt += 1;
+          continue;
+        }
+        throw new TinifyNetworkError(
+          `Request to ${url} failed: ${error instanceof Error ? error.message : String(error)}`,
+          { cause: error }
+        );
+      }
+      if (RETRYABLE_STATUSES.has(response.status) && attempt < this.config.maxRetries) {
+        const retryAfter = parseRetryAfterMs(response.headers.get("retry-after"));
+        await response.arrayBuffer().catch(() => void 0);
+        await sleep(retryAfter ?? backoffMs(attempt), options.signal);
+        attempt += 1;
+        continue;
+      }
+      if (!response.ok) await throwApiError(response);
+      return {
+        response,
+        requestIdHeader: response.headers.get("x-request-id"),
+        rateLimit: rateLimitFromHeaders(response.headers)
+      };
+    }
+  }
+  /** JSON-parsing wrapper around {@link request}. */
+  async requestJson(options) {
+    const result = await this.request(options);
+    let body;
+    if (result.response.status === 204) {
+      body = void 0;
+    } else {
+      body = await result.response.json();
+    }
+    const bodyRequestId = body?.request_id;
+    return {
+      body,
+      requestId: bodyRequestId ?? result.requestIdHeader ?? "unavailable",
+      rateLimit: result.rateLimit
+    };
+  }
+  async fetchWithTimeout(url, init, signal) {
+    const controller = new AbortController();
+    const timeoutError = new TinifyTimeoutError(
+      `Request timed out after ${this.config.timeoutMs} ms.`,
+      this.config.timeoutMs
+    );
+    const timer = setTimeout(() => controller.abort(timeoutError), this.config.timeoutMs);
+    const onAbort = () => controller.abort(abortReason(signal));
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      return await this.config.fetchImpl(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (error === timeoutError) throw error;
+      if (controller.signal.aborted && controller.signal.reason === timeoutError) {
+        throw timeoutError;
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+};
+
+// src/client.ts
+var TinifyClient = class {
+  http;
+  constructor(options = {}) {
+    const env = typeof process !== "undefined" && process.env !== void 0 ? process.env : {};
+    const apiKey = options.apiKey ?? env[ENV_API_KEY];
+    if (apiKey === void 0 || apiKey === "") {
+      throw new TinifyError(
+        `Missing API key. Pass { apiKey } or set ${ENV_API_KEY}. Keys are created at https://tinify.dev/developers.`
+      );
+    }
+    const baseUrl = (options.baseUrl ?? env[ENV_BASE_URL] ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    const fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    this.http = new HttpClient({
+      apiKey,
+      baseUrl,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      fetchImpl
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Synchronous image operations
+  // -------------------------------------------------------------------------
+  /** Compresses an image. Never returns more bytes than the input. */
+  compress(input, options = {}) {
+    return this.imageOperation(
+      "compress",
+      input,
+      {
+        quality_mode: options.quality_mode,
+        target_size_bytes: options.target_size_bytes
+      },
+      options
+    );
+  }
+  /** Resizes an image by width/height/scale. */
+  resize(input, options = {}) {
+    return this.imageOperation(
+      "resize",
+      input,
+      {
+        width: options.width,
+        height: options.height,
+        scale: options.scale,
+        keep_aspect_ratio: options.keep_aspect_ratio,
+        optimize: options.optimize
+      },
+      options
+    );
+  }
+  /** Crops an image to the given rectangle. */
+  crop(input, options) {
+    return this.imageOperation(
+      "crop",
+      input,
+      {
+        x: options.x,
+        y: options.y,
+        width: options.width,
+        height: options.height
+      },
+      options
+    );
+  }
+  /**
+   * Converts an image to another format (AVIF, WebP, JPEG, or PNG).
+   *
+   * @beta The `/api/v1/images/convert` endpoint is rolling out server-side
+   * and may not be available on every account yet.
+   */
+  convert(input, options) {
+    return this.imageOperation(
+      "convert",
+      input,
+      {
+        format: options.format,
+        quality_mode: options.quality_mode
+      },
+      options
+    );
+  }
+  /** Returns the account's current billing-period usage. */
+  async usage(options = {}) {
+    const { body, requestId, rateLimit } = await this.http.requestJson({
+      method: "GET",
+      path: "/api/v1/usage",
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return { data: body, requestId, rateLimit };
+  }
+  /**
+   * Downloads a result as a `Blob`. Accepts a result object, a response
+   * envelope, or a download URL. Download URLs are unauthenticated and
+   * expire two hours after the operation.
+   */
+  async download(resultOrUrl, options = {}) {
+    const raw = typeof resultOrUrl === "string" ? resultOrUrl : "download_url" in resultOrUrl ? resultOrUrl.download_url : resultOrUrl.data.download_url;
+    const url = new URL(raw, `${this.http.baseUrl}/`).toString();
+    const response = await this.http.fetchImpl(url, {
+      method: "GET",
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    if (!response.ok) await throwApiError(response);
+    return response.blob();
+  }
+  // -------------------------------------------------------------------------
+  // Batches
+  // -------------------------------------------------------------------------
+  /**
+   * Creates a durable batch. Returns one presigned upload slot per file;
+   * upload the bytes, then {@link commitBatch}. Requires a paid plan.
+   */
+  async createBatch(params, options = {}) {
+    const { body, requestId, rateLimit } = await this.http.requestJson({
+      method: "POST",
+      path: "/api/v1/batches",
+      contentType: "application/json",
+      body: () => JSON.stringify(params),
+      idempotencyKey: options.idempotencyKey ?? "auto",
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return { data: body, requestId, rateLimit };
+  }
+  /**
+   * Uploads file bytes to the presigned URLs of an upload session, keyed by
+   * `client_id`. Runs up to `concurrency` (default 4) PUTs in parallel.
+   */
+  uploadBatchFiles(session, files, options = {}) {
+    return uploadBatchFiles(this.http.fetchImpl, session, files, options);
+  }
+  /** Commits an uploaded batch for processing. */
+  async commitBatch(batchId, options = {}) {
+    const { body, requestId, rateLimit } = await this.http.requestJson({
+      method: "POST",
+      path: `/api/v1/batches/${encodeURIComponent(batchId)}/commit`,
+      idempotencyKey: options.idempotencyKey ?? "auto",
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return { data: body, requestId, rateLimit };
+  }
+  /** Fetches a batch with per-file state. */
+  async getBatch(batchId, options = {}) {
+    const { body, requestId, rateLimit } = await this.http.requestJson({
+      method: "GET",
+      path: `/api/v1/batches/${encodeURIComponent(batchId)}`,
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return { data: body, requestId, rateLimit };
+  }
+  /** Cancels a batch. Idempotent: canceling a terminal batch is a no-op. */
+  async cancelBatch(batchId, options = {}) {
+    await this.http.request({
+      method: "DELETE",
+      path: `/api/v1/batches/${encodeURIComponent(batchId)}`,
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+  }
+  /**
+   * Polls {@link getBatch} until the batch reaches a terminal status
+   * (`succeeded`, `partially_succeeded`, `failed`, `canceled`, `expired`).
+   * Polls start at 1s and grow x1.5 up to 10s; gives up after `timeoutMs`
+   * (default 10 minutes) with a {@link TinifyTimeoutError}.
+   */
+  async waitForBatch(batchId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+    const maxInterval = options.maxPollIntervalMs ?? DEFAULT_MAX_POLL_INTERVAL_MS;
+    let interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const startedAt = Date.now();
+    for (; ; ) {
+      const result = await this.getBatch(batchId, options);
+      if (isTerminalBatchStatus(result.data.status)) return result;
+      const elapsed = Date.now() - startedAt;
+      if (elapsed + interval > timeoutMs) {
+        throw new TinifyTimeoutError(
+          `Batch ${batchId} did not reach a terminal status within ${timeoutMs} ms (last status: ${result.data.status}).`,
+          timeoutMs
+        );
+      }
+      await sleep(interval, options.signal);
+      interval = Math.min(interval * DEFAULT_POLL_GROWTH, maxInterval);
+    }
+  }
+  /**
+   * Downloads the ZIP archive of a completed batch's successful results.
+   * The batch must be in `succeeded`, `partially_succeeded`, or `failed`
+   * state and contain at least one successful file.
+   */
+  async downloadBatchArchive(batchId, options = {}) {
+    const result = await this.http.request({
+      method: "GET",
+      path: `/api/v1/batches/${encodeURIComponent(batchId)}/archive`,
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return result.response.blob();
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  async imageOperation(operation, input, fields, options) {
+    const { blob, filename } = await normalizeInput(input, options.filename);
+    const makeForm = () => {
+      const form = new FormData();
+      form.append("file", blob, filename);
+      for (const [key, value] of Object.entries(fields)) {
+        if (value !== void 0) form.append(key, String(value));
+      }
+      return form;
+    };
+    const { body, requestId, rateLimit } = await this.http.requestJson({
+      method: "POST",
+      path: `/api/v1/images/${operation}`,
+      body: makeForm,
+      idempotencyKey: options.idempotencyKey ?? "auto",
+      ...options.signal !== void 0 ? { signal: options.signal } : {}
+    });
+    return { data: body.data, requestId, rateLimit };
+  }
+};
+
+exports.BATCH_TERMINAL_STATUSES = BATCH_TERMINAL_STATUSES;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.MAX_BATCH_FILES = MAX_BATCH_FILES;
+exports.MAX_FILE_BYTES = MAX_FILE_BYTES;
+exports.TinifyApiError = TinifyApiError;
+exports.TinifyClient = TinifyClient;
+exports.TinifyError = TinifyError;
+exports.TinifyNetworkError = TinifyNetworkError;
+exports.TinifyTimeoutError = TinifyTimeoutError;
+exports.isTerminalBatchStatus = isTerminalBatchStatus;
+exports.normalizeInput = normalizeInput;
+exports.uploadBatchFiles = uploadBatchFiles;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map