@immagin/client 0.2.2 → 0.2.5

package/README.md

@@ -17,12 +17,12 @@ import { Immagin } from '@immagin/client'
 
 const client = new Immagin({ apiKey: 'imk_...' })
 
-// Get a processed image URL (via API)
-const url = await client.images.url('photos/hero.jpg', {
-  size: [800, 600],
-})
+// Generate a signed image URL (auto-fetches tenant credentials)
+const url = await client.images.url('photos/hero.jpg', [
+  { resize: { width: 800, height: 600 } },
+])
 
-// Upload an image
+// Upload an image (auto-detects MIME type)
 import { readFileSync } from 'node:fs'
 const buffer = readFileSync('photo.jpg')
 await client.images.upload(buffer, 'photos/hero.jpg')
@@ -30,62 +30,65 @@ await client.images.upload(buffer, 'photos/hero.jpg')
 
 ## Images
 
-### Get a processed URL (via API)
+### Generate image URLs
 
-Returns a signed URL that serves the image through Immagin's processing pipeline.
+Generate signed image URLs for serving processed images. All URLs are automatically signed — the signature locks transformation parameters so they can't be tampered with.
 
 ```ts
+// Original image
 const url = await client.images.url('photo.jpg')
-```
-
-With transformations:
-
-```ts
-const url = await client.images.url('photo.jpg', {
-  size: [400, 300],
-  text: {
-    text: 'Hello',
-    position: 'bottom-right', // top-left, top-right, bottom-left, bottom-right, center
-    fontSize: 24,
-    color: '#ffffff',
-    opacity: 0.8,
-  },
-})
-```
-
-### Sign URLs locally (without API call)
-
-Generate signed image URLs on the server without making an API request. Requires `tenantId` and `tenantSecret` in the constructor.
-
-```ts
-const client = new Immagin({
-  apiKey: 'imk_...',
-  tenantId: 'your-tenant-id',
-  tenantSecret: 'your-tenant-secret',
-})
-
-// Synchronous - no network request
-const url = client.images.signedUrl('photo.jpg')
 
 // With transformations
-const thumb = client.images.signedUrl('photo.jpg', {
-  size: [800, 600],
-  text: { text: '© My Company', position: 'bottom-right', opacity: 0.5 },
-})
+const thumb = await client.images.url('photo.jpg', [
+  { resize: { width: 800, height: 600 } },
+  { text: { text: '© My Company', position: 'bottom-right', opacity: 0.5 } },
+])
+
+// Rotate, blur, grayscale
+const edited = await client.images.url('photo.jpg', [
+  { rotate: { angle: 90 } },
+  { blur: 3 },
+  { grayscale: true },
+])
+
+// Crop a region
+const cropped = await client.images.url('photo.jpg', [
+  { crop: { left: 100, top: 50, width: 400, height: 300 } },
+])
+
+// Flip, sharpen, adjust colors
+const adjusted = await client.images.url('photo.jpg', [
+  { flip: true },
+  { sharpen: 2 },
+  { modulate: { brightness: 1.2, saturation: 0.8 } },
+])
+
+// Disable auto-orient (enabled by default)
+const raw = await client.images.url('photo.jpg', [
+  { autoOrient: false },
+  { resize: { width: 800 } },
+])
+
+// Custom output format (default is WebP at quality 90)
+const jpeg = await client.images.url(
+  'photo.jpg',
+  [{ resize: { width: 800 } }],
+  { format: 'jpeg', quality: 85 },
+)
 ```
 
-> **Note:** This uses `node:crypto` and is intended for server-side use only. Never expose your tenant secret in client-side code.
+> **Note:** `url()` uses `node:crypto` for signing and is intended for server-side use only. Tenant credentials are auto-fetched and cached on initialization.
 
-### Get a pre-signed upload URL
+### Get a signed upload URL
 
-Returns a pre-signed S3 URL for direct upload (expires in 5 minutes). Useful for browser uploads where you don't want to expose your API key.
+Returns a CloudFront signed URL for direct upload (expires in 5 minutes). Useful for browser uploads where you don't want to expose your API key. The URL points to a CloudFront distribution (not S3 directly), so the underlying infrastructure is not exposed.
 
 ```ts
-// Server: get the presigned URL
+// Server: get the signed upload URL
 const { uploadUrl, key } = await client.images.signUrl('photos/hero.jpg')
 // Return uploadUrl to the browser
 
-// Browser: upload directly to S3
+// Browser: upload directly
 await fetch(uploadUrl, {
   method: 'PUT',
   body: file,
@@ -94,7 +97,7 @@ await fetch(uploadUrl, {
 
 ### Upload (Node.js)
 
-Convenience method that gets a signed URL and uploads in one call. The file goes directly to S3 and never passes through the API.
+Convenience method that gets a signed URL and uploads in one call. The file goes directly to CloudFront/S3 and never passes through the API. MIME type is auto-detected from file bytes (magic bytes for JPEG, PNG, GIF, WebP, BMP, AVIF, HEIC, HEIF) or file extension.
 
 ```ts
 import { readFileSync } from 'node:fs'
@@ -123,6 +126,27 @@ const page = await client.images.list({
 await client.images.delete('uploads/photo.jpg')
 ```
 
+### Metadata
+
+Inspect image properties (dimensions, format, color space, etc.) without downloading the full image. The request goes through Luna, which extracts metadata using Sharp.
+
+```ts
+const meta = await client.images.metadata('photo.jpg')
+// {
+//   width: 1920,
+//   height: 1080,
+//   format: 'jpeg',
+//   space: 'srgb',
+//   channels: 3,
+//   hasAlpha: false,
+//   density: 72,
+//   isProgressive: false,
+//   size: 204800,
+// }
+```
+
+> **Note:** `metadata()` uses `node:crypto` for signing and is intended for server-side use only.
+
 ## API Keys
 
 Manage API keys programmatically.
@@ -171,8 +195,6 @@ try {
 const client = new Immagin({
   apiKey: 'imk_...',              // Required
   baseUrl: 'https://...',         // Optional, defaults to https://gateway.immag.in
-  tenantId: 'your-tenant-id',     // Optional, required for signedUrl()
-  tenantSecret: 'your-secret',    // Optional, required for signedUrl()
 })
 ```
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 //#region src/types.d.ts
-type TextPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+type TextPosition = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 interface TextOverlay {
   text: string;
   fontSize?: number;
@@ -8,11 +8,113 @@ interface TextOverlay {
   position?: TextPosition;
   padding?: number;
 }
-interface ImageEdits {
-  size?: [number] | [number, number];
-  text?: TextOverlay;
+type ResizeFit = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+type ResizePosition = 'top' | 'right top' | 'right' | 'right bottom' | 'bottom' | 'left bottom' | 'left' | 'left top' | 'centre' | 'center' | 'entropy' | 'attention';
+type ResizeKernel = 'nearest' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3';
+interface ResizeOptions {
+  width: number;
+  height?: number;
+  fit?: ResizeFit;
+  position?: ResizePosition;
+  kernel?: ResizeKernel;
+  background?: string;
+  upscale?: boolean;
+  downscale?: boolean;
+}
+interface RotateOptions {
+  angle: number;
+  background?: string;
+}
+interface CropOptions {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+interface ExtendOptions {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+  background?: string;
+}
+interface ModulateOptions {
+  brightness?: number;
+  saturation?: number;
+  hue?: number;
+  lightness?: number;
+}
+interface FlattenOptions {
+  background?: string;
+}
+interface TintOptions {
+  r: number;
+  g: number;
+  b: number;
+}
+interface NormalizeOptions {
+  lower?: number;
+  upper?: number;
+}
+interface TrimOptions {
+  background?: string;
+  threshold?: number;
+}
+type ImageOperation = {
+  resize: ResizeOptions;
+} | {
+  text: TextOverlay;
+} | {
+  rotate: RotateOptions;
+} | {
+  flip: true;
+} | {
+  flop: true;
+} | {
+  blur: number;
+} | {
+  sharpen: number;
+} | {
+  grayscale: true;
+} | {
+  crop: CropOptions;
+} | {
+  extend: ExtendOptions;
+} | {
+  modulate: ModulateOptions;
+} | {
+  flatten: FlattenOptions;
+} | {
+  tint: TintOptions;
+} | {
+  invert: boolean;
+} | {
+  normalize: NormalizeOptions;
+} | {
+  trim: TrimOptions;
+} | {
+  autoOrient: boolean;
+};
+type OutputFormat = 'webp' | 'jpeg' | 'png' | 'gif' | 'jp2' | 'tiff' | 'avif' | 'heif';
+interface OutputOptions {
+  format?: OutputFormat;
+  quality?: number;
+  progressive?: boolean;
+  lossless?: boolean;
+}
+interface ImageMetadata {
+  width: number;
+  height: number;
+  format: string;
+  space: string;
+  channels: number;
+  hasAlpha: boolean;
+  orientation?: number;
+  density?: number;
+  isProgressive?: boolean;
+  pages?: number;
+  size: number;
 }
-interface ImageUrlOptions extends ImageEdits {}
 interface UploadResult {
   uploadUrl: string;
   key: string;
@@ -43,6 +145,10 @@ interface CreateKeyResult {
   prefix: string;
   name: string;
 }
+interface ProjectInfo {
+  tenantId: string;
+  tenantSecret: string;
+}
 interface ImmaginConfig {
   apiKey: string;
   baseUrl?: string;
@@ -54,12 +160,12 @@ interface ImmaginConfig {
 declare class ImagesResource {
   private client;
   constructor(client: Immagin);
-  signedUrl(key: string, edits?: ImageEdits): string;
-  url(key: string, options?: ImageUrlOptions): Promise<string>;
+  url(key: string, edits?: ImageOperation | ImageOperation[], output?: OutputOptions): Promise<string>;
   signUrl(key: string): Promise<UploadResult>;
   upload(file: Blob | Buffer | ReadableStream, key: string): Promise<UploadResult>;
   list(options?: ListImagesOptions): Promise<ListImagesResult>;
   delete(key: string): Promise<void>;
+  metadata(key: string): Promise<ImageMetadata>;
 }
 //#endregion
 //#region src/resources/keys.d.ts
@@ -81,10 +187,16 @@ declare class Immagin {
   tenantId?: string;
   /** @internal */
   tenantSecret?: string;
+  private _tenantInfoPromise?;
   images: ImagesResource;
   keys: KeysResource;
   constructor(config: ImmaginConfig);
   /** @internal */
+  resolveTenantInfo(): Promise<{
+    tenantId: string;
+    tenantSecret: string;
+  }>;
+  /** @internal */
   request<T>(method: string, path: string, options?: {
     body?: unknown;
     params?: Record<string, string>;
@@ -98,4 +210,4 @@ declare class ImmaginError extends Error {
   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 UploadResult };
+export { type ApiKey, type CreateKeyResult, type CropOptions, type ExtendOptions, type FlattenOptions, type ImageEntry, type ImageMetadata, type ImageOperation, Immagin, type ImmaginConfig, ImmaginError, type ListImagesOptions, type ListImagesResult, type ModulateOptions, type NormalizeOptions, type OutputFormat, type OutputOptions, type ProjectInfo, type ResizeFit, type ResizeKernel, type ResizeOptions, type ResizePosition, type RotateOptions, type TextOverlay, type TextPosition, type TintOptions, type TrimOptions, type UploadResult };

package/dist/index.mjs

@@ -1,5 +1,16 @@
 import { createHmac } from "node:crypto";
 
+//#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/resources/images.ts
 const MIME_TYPES = {
 	jpg: "image/jpeg",
@@ -42,29 +53,17 @@ var ImagesResource = class {
 	constructor(client) {
 		this.client = client;
 	}
-	signedUrl(key, edits) {
-		const { tenantId, tenantSecret } = this.client;
-		if (!tenantId || !tenantSecret) throw new Error("tenantId and tenantSecret are required for signedUrl(). Pass them in the Immagin constructor.");
+	async url(key, edits, output) {
+		const { tenantId, tenantSecret } = await this.client.resolveTenantInfo();
 		const payload = { key };
-		if (edits && Object.keys(edits).length > 0) payload.edits = edits;
+		if (edits) {
+			const editsArray = Array.isArray(edits) ? edits : [edits];
+			if (editsArray.length > 0) payload.edits = editsArray;
+		}
+		if (output) payload.output = output;
 		const base64 = Buffer.from(JSON.stringify(payload)).toString("base64");
 		return `https://${tenantId}.immag.in/${base64}?sig=${createHmac("sha256", tenantSecret).update(base64).digest("hex").slice(0, 16)}`;
 	}
-	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) {
 		const contentType = mimeFromKey(key);
 		return this.client.request("POST", "/v1/images/sign-url", { body: contentType ? {
@@ -95,6 +94,21 @@ var ImagesResource = class {
 	async delete(key) {
 		await this.client.request("DELETE", `/v1/images/${key}`);
 	}
+	async metadata(key) {
+		const { tenantId, tenantSecret } = await this.client.resolveTenantInfo();
+		const payload = JSON.stringify({
+			key,
+			metadata: true
+		});
+		const base64 = Buffer.from(payload).toString("base64");
+		const url = `https://${tenantId}.immag.in/${base64}?sig=${createHmac("sha256", tenantSecret).update(base64).digest("hex").slice(0, 16)}`;
+		const response = await fetch(url);
+		if (!response.ok) {
+			const body = await response.text();
+			throw new ImmaginError(`HTTP ${response.status}`, response.status, body);
+		}
+		return response.json();
+	}
 };
 
 //#endregion
@@ -114,17 +128,6 @@ var KeysResource = class {
 	}
 };
 
-//#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";
@@ -135,6 +138,7 @@ var Immagin = class {
 	tenantId;
 	/** @internal */
 	tenantSecret;
+	_tenantInfoPromise;
 	images;
 	keys;
 	constructor(config) {
@@ -144,6 +148,23 @@ var Immagin = class {
 		this.tenantSecret = config.tenantSecret;
 		this.images = new ImagesResource(this);
 		this.keys = new KeysResource(this);
+		if (!this.tenantId || !this.tenantSecret) this.resolveTenantInfo().catch(() => {});
+	}
+	/** @internal */
+	async resolveTenantInfo() {
+		if (this.tenantId && this.tenantSecret) return {
+			tenantId: this.tenantId,
+			tenantSecret: this.tenantSecret
+		};
+		if (!this._tenantInfoPromise) this._tenantInfoPromise = this.request("GET", "/v1/project").then((info) => {
+			this.tenantId = info.tenantId;
+			this.tenantSecret = info.tenantSecret;
+			return info;
+		}).catch((err) => {
+			this._tenantInfoPromise = void 0;
+			throw err;
+		});
+		return this._tenantInfoPromise;
 	}
 	/** @internal */
 	async request(method, path, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immagin/client",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "Node.js and browser client for the Immagin image processing API",
   "type": "module",
   "license": "MIT",