Choose Your Integration Path

Eazip has four integration paths. They share the same job model, so you can start on the simplest one and move later without rewriting your interface.

The first question that decides everything: does the browser already have the file URLs? A gallery that renders images already holds usable URLs. An "export my account" button usually doesn't — the list exists only on your server.

The four paths

The browser already has the URLs

Pass them straight to the SDK. No account, key, or backend is needed:

import { createZip } from '@eazip/core';

const result = await createZip({
  files: imageUrls,
  zipName: 'photos.zip',
});

result.download();

When the archive outgrows the tab — multi-gigabyte totals, thousands of URLs, or a job that must survive a reload — keep the same call and add a strategy:

const result = await createZip({
  strategy: 'cloud',
  publicKey: 'pk_ez_...',
  files: imageUrls,
  zipName: 'photos.zip',
});

Get a public key and scope it to your origins and source hosts.

The browser doesn't have the URLs

The list exists on your server. You have two options, and the difference is how much travels over the network:

Option 1 — return a signed URL list. Your endpoint authorizes the user, signs each object, and returns { url, filename } entries for the browser to zip. This is the only option that works with the free Local strategy, and it is what the platform guides implement first. Its cost is structural: a 1,000-file export means signing and shipping 1,000 URLs to the browser before the job starts.

Option 2 — create the session on your backend. With Cloud, your endpoint can instead build the source list server-side and return only a small session handle:

const job = startZip({
  strategy: 'cloud',
  zipName: 'export.zip',
  createSession: async ({ signal, zipName, mode }) => {
    const response = await fetch('/api/exports/123/eazip-session', {
      method: 'POST',
      credentials: 'include',
      signal,
      body: JSON.stringify({ zipName, mode }),
    });
    if (!response.ok) throw new Error('Failed to create Eazip session');
    return response.json(); // { sessionId, clientSecret }
  },
});

The URL list never crosses the network, the browser never sees source URLs or keys, and the SDK still owns progress, resume, and the download UI. See Backend-created sessions for the server side.

No browser in the loop

Scheduled exports, pipelines, and "email the user a link" flows call the HTTP API directly with a secret zk_ key: create a job, receive a webhook when it finishes, and deliver the output URL however you like. No frontend SDK is involved.

How to decide

1. URLs already in the browser → Local, and add strategy: 'cloud' only when the job outgrows the tab.
2. URLs only on your server, staying on the free tier → signed URL list endpoint plus Local.
3. URLs only on your server, using Cloud → backend session; don't build a URL-list endpoint just to download.
4. No user waiting in a browser → HTTP API.

Each platform guide shows paths 1–2 in full and links back here when your situation calls for 3 or 4.