Skip to main content

TypeScript

The @giveitsmaller/sdk package is a Node.js client for the GISL (Give It Smaller) file compression and processing API. Upload a file, apply operations (compress, convert, thumbnail, merge, archive), and retrieve the results.

Install​

npm install @giveitsmaller/sdk

Requires Node.js 18+.

Authenticate​

Every request is authenticated with an API key sent as a Bearer token. Get a key from the dashboard at giveitsmaller.com. Pass it when you create the client — the SDK sets the Authorization header on every request for you. The base URL defaults to https://api.giveitsmaller.com; the key can also come from the GISL_API_KEY environment variable or ~/.gisl/credentials.

import { gisl } from '@giveitsmaller/sdk';

const client = await gisl.create({ apiKey: 'REPLACE_ME_API_KEY' });

Quickstart​

The SDK is file-first: you start from a file (.file(path) for one, .files([paths]) for many) and call operations on it — upload, workflow creation, and waiting are handled for you in one chain.

import { gisl, OptimizeFor } from '@giveitsmaller/sdk';

const client = await gisl.create({ apiKey: 'REPLACE_ME_API_KEY' });

// One file: upload → compress → wait → resolve the download URL, in one chain.
const result = await client
  .file('./photo.jpg')
  .compress(OptimizeFor.Balanced)
  .run({ maxWait: '5m' });

console.log('Compressed file:', result.url); // pre-signed download URL

// Many files (fan-out) — the same chain over a list:
const many = await client
  .files(['./a.jpg', './b.png'])
  .compress(OptimizeFor.Balanced)
  .run();

for (const artifact of many.artifacts) console.log(artifact.url);

That is the full round trip. Worth knowing:

  • Presets express intent. OptimizeFor.Size, .Balanced, and .Quality pick sensible options for the input's media type. See Compress for per-call options.
  • run() waits up to 10 minutes by default — override with maxWait. For live progress instead of polling, subscribe to progress events.
  • Failures throw typed errors (GislApiError, GislValidationError, GislTimeoutError, …). See Errors.
Low-level escape hatch

File-first is the recommended path. For full control over the workflow payload — hand-built job DAGs with uploadSource / OperationType and explicit uploadFile / waitForWorkflow / getWorkflowDownloads — the raw wire client is available via client.createWorkflow({ jobs: [...] }).

Where next​

  • Installation — every language, side by side.
  • Quickstart — the end-to-end walkthrough.
  • Operations — compress, convert, thumbnail, merge, archive.
  • Workflows — how jobs, sources, and outputs fit together.
  • Errors — the error taxonomy and retry guidance.