@immagin/client 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# @immagin/client
+
+Node.js and browser client for the [Immagin](https://immag.in) image processing API.
+
+Zero dependencies. Works everywhere `fetch` is available.
+
+## Install
+
+```bash
+npm install @immagin/client
+```
+
+## Quick start
+
+```ts
+import { Immagin } from '@immagin/client'
+
+const client = new Immagin({ apiKey: 'imk_...' })
+
+// Get a processed image URL
+const url = await client.images.url('photos/hero.jpg', {
+  size: [800, 600],
+})
+
+// Upload an image
+const file = new Blob([buffer], { type: 'image/jpeg' })
+await client.images.upload(file, { key: 'photos/hero.jpg' })
+```
+
+## Images
+
+### Get a processed URL
+
+Returns a signed URL that serves the image through Immagin's processing pipeline.
+
+```ts
+const url = await client.images.url('photo.jpg')
+```
+
+With transformations:
+
+```ts
+const url = await client.images.url('photo.jpg', {
+  size: [400],          // width only
+  size: [400, 300],     // width and height
+  text: {
+    text: 'Hello',
+    position: 'bottom-right', // top-left, top-right, bottom-left, bottom-right, center
+    fontSize: 24,
+    color: '#ffffff',
+    opacity: 0.8,
+  },
+})
+```
+
+### Get a pre-signed upload URL
+
+Returns a pre-signed S3 URL for direct upload. Useful when you need to handle the upload yourself (e.g. from a mobile app or with a custom upload flow).
+
+```ts
+const { uploadUrl, key } = await client.images.signUrl('photos/hero.jpg', 'image/jpeg')
+
+// Upload directly to S3 yourself
+await fetch(uploadUrl, { method: 'PUT', body: file })
+```
+
+### Upload
+
+Convenience method that gets a signed URL and uploads in one call. The file goes directly to S3 and never passes through the API.
+
+```ts
+// Browser
+const input = document.querySelector('input[type="file"]')
+await client.images.upload(input.files[0], {
+  key: 'uploads/photo.jpg',
+  contentType: 'image/jpeg',
+})
+
+// Node.js
+import { readFileSync } from 'node:fs'
+const buffer = readFileSync('photo.jpg')
+await client.images.upload(buffer, {
+  key: 'uploads/photo.jpg',
+  contentType: 'image/jpeg',
+})
+```
+
+### List
+
+```ts
+const result = await client.images.list()
+// { images: [{ key, size, lastModified }], nextCursor? }
+
+// With pagination
+const page = await client.images.list({
+  prefix: 'uploads/',
+  limit: 50,
+  cursor: result.nextCursor,
+})
+```
+
+### Delete
+
+```ts
+await client.images.delete('uploads/photo.jpg')
+```
+
+## API Keys
+
+Manage API keys programmatically. Useful for building admin tools or rotating keys.
+
+### Create
+
+```ts
+const result = await client.keys.create({ name: 'Production' })
+// { key: 'imk_...', prefix: 'imk_abcd', name: 'Production' }
+// Save the key - it won't be shown again
+```
+
+### List
+
+```ts
+const keys = await client.keys.list()
+// [{ id, name, keyPrefix, createdAt, lastUsedAt }]
+```
+
+### Revoke
+
+```ts
+await client.keys.revoke(keyId)
+```
+
+## Error handling
+
+All API errors throw `ImmaginError` with the HTTP status and response body.
+
+```ts
+import { Immagin, ImmaginError } from '@immagin/client'
+
+try {
+  await client.images.delete('missing.jpg')
+} catch (err) {
+  if (err instanceof ImmaginError) {
+    console.log(err.status)  // 404
+    console.log(err.message) // "Not found"
+  }
+}
+```
+
+## Configuration
+
+```ts
+const client = new Immagin({
+  apiKey: 'imk_...',       // Required
+  baseUrl: 'https://...',  // Optional, defaults to https://gateway.immag.in
+})
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,98 @@
+//#region src/types.d.ts
+type TextPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+interface TextOverlay {
+  text: string;
+  fontSize?: number;
+  color?: string;
+  opacity?: number;
+  position?: TextPosition;
+  padding?: number;
+}
+interface ImageEdits {
+  size?: [number] | [number, number];
+  text?: TextOverlay;
+}
+interface ImageUrlOptions extends ImageEdits {}
+interface UploadOptions {
+  key: string;
+  contentType?: string;
+}
+interface UploadResult {
+  uploadUrl: string;
+  key: string;
+}
+interface ImageEntry {
+  key: string;
+  size: number;
+  lastModified: string;
+}
+interface ListImagesResult {
+  images: ImageEntry[];
+  nextCursor?: string;
+}
+interface ListImagesOptions {
+  prefix?: string;
+  cursor?: string;
+  limit?: number;
+}
+interface ApiKey {
+  id: number;
+  name: string;
+  keyPrefix: string;
+  createdAt: string;
+  lastUsedAt: string | null;
+}
+interface CreateKeyResult {
+  key: string;
+  prefix: string;
+  name: string;
+}
+interface ImmaginConfig {
+  apiKey: string;
+  baseUrl?: string;
+}
+//#endregion
+//#region src/resources/images.d.ts
+declare class ImagesResource {
+  private client;
+  constructor(client: Immagin);
+  url(key: string, options?: ImageUrlOptions): Promise<string>;
+  signUrl(key: string, contentType?: string): Promise<UploadResult>;
+  upload(file: Blob | Buffer | ReadableStream, options: UploadOptions): Promise<UploadResult>;
+  list(options?: ListImagesOptions): Promise<ListImagesResult>;
+  delete(key: string): Promise<void>;
+}
+//#endregion
+//#region src/resources/keys.d.ts
+declare class KeysResource {
+  private client;
+  constructor(client: Immagin);
+  create(options: {
+    name: string;
+  }): Promise<CreateKeyResult>;
+  list(): Promise<ApiKey[]>;
+  revoke(keyId: number): Promise<void>;
+}
+//#endregion
+//#region src/client.d.ts
+declare class Immagin {
+  private apiKey;
+  private baseUrl;
+  images: ImagesResource;
+  keys: KeysResource;
+  constructor(config: ImmaginConfig);
+  /** @internal */
+  request<T>(method: string, path: string, options?: {
+    body?: unknown;
+    params?: Record<string, string>;
+  }): Promise<T>;
+}
+//#endregion
+//#region src/errors.d.ts
+declare class ImmaginError extends Error {
+  status: number;
+  body?: unknown | undefined;
+  constructor(message: string, status: number, body?: unknown | undefined);
+}
+//#endregion
+export { type ApiKey, type CreateKeyResult, type ImageEdits, type ImageEntry, type ImageUrlOptions, Immagin, type ImmaginConfig, ImmaginError, type ListImagesOptions, type ListImagesResult, type TextOverlay, type TextPosition, type UploadOptions, type UploadResult };

package/dist/index.mjs

@@ -0,0 +1,113 @@
+//#region src/resources/images.ts
+var ImagesResource = class {
+	constructor(client) {
+		this.client = client;
+	}
+	async url(key, options) {
+		const params = { key };
+		if (options?.size) {
+			params.width = String(options.size[0]);
+			if (options.size.length === 2) params.height = String(options.size[1]);
+		}
+		if (options?.text) {
+			params["text.text"] = options.text.text;
+			if (options.text.position) params["text.position"] = options.text.position;
+			if (options.text.fontSize) params["text.fontSize"] = String(options.text.fontSize);
+			if (options.text.opacity) params["text.opacity"] = String(options.text.opacity);
+			if (options.text.color) params["text.color"] = options.text.color;
+		}
+		return (await this.client.request("GET", "/v1/images/url", { params })).url;
+	}
+	async signUrl(key, contentType) {
+		return this.client.request("POST", "/v1/images/sign-url", { body: {
+			key,
+			contentType: contentType || "application/octet-stream"
+		} });
+	}
+	async upload(file, options) {
+		const { key, contentType } = options;
+		const signResult = await this.signUrl(key, contentType);
+		await fetch(signResult.uploadUrl, {
+			method: "PUT",
+			body: file,
+			headers: contentType ? { "content-type": contentType } : void 0
+		});
+		return signResult;
+	}
+	async list(options) {
+		const params = {};
+		if (options?.prefix) params.prefix = options.prefix;
+		if (options?.cursor) params.cursor = options.cursor;
+		if (options?.limit) params.limit = String(options.limit);
+		return this.client.request("GET", "/v1/images", { params });
+	}
+	async delete(key) {
+		await this.client.request("DELETE", `/v1/images/${key}`);
+	}
+};
+
+//#endregion
+//#region src/resources/keys.ts
+var KeysResource = class {
+	constructor(client) {
+		this.client = client;
+	}
+	async create(options) {
+		return this.client.request("POST", "/v1/keys", { body: options });
+	}
+	async list() {
+		return (await this.client.request("GET", "/v1/keys")).keys;
+	}
+	async revoke(keyId) {
+		await this.client.request("DELETE", `/v1/keys/${keyId}`);
+	}
+};
+
+//#endregion
+//#region src/errors.ts
+var ImmaginError = class extends Error {
+	constructor(message, status, body) {
+		super(message);
+		this.status = status;
+		this.body = body;
+		this.name = "ImmaginError";
+	}
+};
+
+//#endregion
+//#region src/client.ts
+const DEFAULT_BASE_URL = "https://gateway.immag.in";
+var Immagin = class {
+	apiKey;
+	baseUrl;
+	images;
+	keys;
+	constructor(config) {
+		this.apiKey = config.apiKey;
+		this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+		this.images = new ImagesResource(this);
+		this.keys = new KeysResource(this);
+	}
+	/** @internal */
+	async request(method, path, options) {
+		const url = new URL(path, this.baseUrl);
+		if (options?.params) {
+			for (const [key, value] of Object.entries(options.params)) if (value !== void 0) url.searchParams.set(key, value);
+		}
+		const headers = { authorization: `Bearer ${this.apiKey}` };
+		if (options?.body) headers["content-type"] = "application/json";
+		const response = await fetch(url.toString(), {
+			method,
+			headers,
+			body: options?.body ? JSON.stringify(options.body) : void 0
+		});
+		if (!response.ok) {
+			const body = await response.json().catch(() => null);
+			throw new ImmaginError(body?.error || `HTTP ${response.status}`, response.status, body);
+		}
+		return response.json();
+	}
+};
+
+//#endregion
+export { Immagin, ImmaginError };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@immagin/client",
+  "version": "0.1.0",
+  "description": "Node.js and browser client for the Immagin image processing API",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://immag.in",
+  "keywords": [
+    "immagin",
+    "image",
+    "image-processing",
+    "cdn",
+    "s3",
+    "upload",
+    "resize",
+    "api-client"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsdown": "^0.20.3",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run"
+  }
+}