@immagin/client 0.1.0 → 0.2.1

package/README.md

@@ -17,19 +17,23 @@ import { Immagin } from '@immagin/client'
 
 const client = new Immagin({ apiKey: 'imk_...' })
 
-// Get a processed image URL
+// Get a processed image URL (via API)
 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' })
+import { readFileSync } from 'node:fs'
+const buffer = readFileSync('photo.jpg')
+await client.images.upload(buffer, {
+  key: 'photos/hero.jpg',
+  contentType: 'image/jpeg',
+})
 ```
 
 ## Images
 
-### Get a processed URL
+### Get a processed URL (via API)
 
 Returns a signed URL that serves the image through Immagin's processing pipeline.
 
@@ -41,8 +45,7 @@ With transformations:
 
 ```ts
 const url = await client.images.url('photo.jpg', {
-  size: [400],          // width only
-  size: [400, 300],     // width and height
+  size: [400, 300],
   text: {
     text: 'Hello',
     position: 'bottom-right', // top-left, top-right, bottom-left, bottom-right, center
@@ -53,31 +56,53 @@ const url = await client.images.url('photo.jpg', {
 })
 ```
 
+### 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 },
+})
+```
+
+> **Note:** This uses `node:crypto` and is intended for server-side use only. Never expose your tenant secret in client-side code.
+
 ### 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).
+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.
 
 ```ts
+// Server: get the presigned URL
 const { uploadUrl, key } = await client.images.signUrl('photos/hero.jpg', 'image/jpeg')
+// Return uploadUrl to the browser
 
-// Upload directly to S3 yourself
-await fetch(uploadUrl, { method: 'PUT', body: file })
+// Browser: upload directly to S3
+await fetch(uploadUrl, {
+  method: 'PUT',
+  body: file,
+  headers: { 'content-type': 'image/jpeg' },
+})
 ```
 
-### Upload
+### 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.
 
 ```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',
@@ -107,7 +132,7 @@ await client.images.delete('uploads/photo.jpg')
 
 ## API Keys
 
-Manage API keys programmatically. Useful for building admin tools or rotating keys.
+Manage API keys programmatically.
 
 ### Create
 
@@ -151,8 +176,10 @@ try {
 
 ```ts
 const client = new Immagin({
-  apiKey: 'imk_...',       // Required
-  baseUrl: 'https://...',  // Optional, defaults to https://gateway.immag.in
+  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

@@ -50,12 +50,15 @@ interface CreateKeyResult {
 interface ImmaginConfig {
   apiKey: string;
   baseUrl?: string;
+  tenantId?: string;
+  tenantSecret?: string;
 }
 //#endregion
 //#region src/resources/images.d.ts
 declare class ImagesResource {
   private client;
   constructor(client: Immagin);
+  signedUrl(key: string, edits?: ImageEdits): string;
   url(key: string, options?: ImageUrlOptions): Promise<string>;
   signUrl(key: string, contentType?: string): Promise<UploadResult>;
   upload(file: Blob | Buffer | ReadableStream, options: UploadOptions): Promise<UploadResult>;
@@ -78,6 +81,10 @@ declare class KeysResource {
 declare class Immagin {
   private apiKey;
   private baseUrl;
+  /** @internal */
+  tenantId?: string;
+  /** @internal */
+  tenantSecret?: string;
   images: ImagesResource;
   keys: KeysResource;
   constructor(config: ImmaginConfig);

package/dist/index.mjs

@@ -1,8 +1,18 @@
+import { createHmac } from "node:crypto";
+
 //#region src/resources/images.ts
 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.");
+		const payload = { key };
+		if (edits && Object.keys(edits).length > 0) payload.edits = edits;
+		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) {
@@ -80,11 +90,17 @@ const DEFAULT_BASE_URL = "https://gateway.immag.in";
 var Immagin = class {
 	apiKey;
 	baseUrl;
+	/** @internal */
+	tenantId;
+	/** @internal */
+	tenantSecret;
 	images;
 	keys;
 	constructor(config) {
 		this.apiKey = config.apiKey;
 		this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+		this.tenantId = config.tenantId;
+		this.tenantSecret = config.tenantSecret;
 		this.images = new ImagesResource(this);
 		this.keys = new KeysResource(this);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immagin/client",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Node.js and browser client for the Immagin image processing API",
   "type": "module",
   "license": "MIT",
@@ -34,14 +34,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "prepublishOnly": "tsdown"
+  },
   "devDependencies": {
     "tsdown": "^0.20.3",
     "typescript": "^5.7.2",
     "vitest": "^3.0.5"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run"
   }
-}
+}