imagekit-developer · imagekitio · Oct 6, 2025 · Oct 3, 2025 · Oct 3, 2025 · Oct 3, 2025
diff --git a/.eslintcache b/.eslintcache
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "7.1.0"
+  ".": "7.1.1"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 42
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-01aef94bd928f40b7209dc21df71e2312d4bee430119b30ee05d75cf5e1b4801.yml
-openapi_spec_hash: 054c332db88b23d362f72583dd24b2aa
-config_hash: e42d7fc3a8c92c35099cc283f9a4467a
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-c7ad6f552b38f2145781847f8b390fa1ec43068d64e45a33012a97a9299edc10.yml
+openapi_spec_hash: 50f281e91210ad5018ac7e4eee216f56
+config_hash: 74a8263b80c732a2b016177e7d56bb9c
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,39 @@
 # Changelog
 
+## 7.1.1 (2025-10-06)
+
+Full Changelog: [v7.1.0...v7.1.1](https://github.com/imagekit-developer/imagekit-nodejs/compare/v7.1.0...v7.1.1)
+
+### Features
+
+* **api:** use scoped package for mcp server ([af9b0f4](https://github.com/imagekit-developer/imagekit-nodejs/commit/af9b0f4abeeef59418ae6fc2dabf65d6270c9bb1))
+
+
+### Bug Fixes
+
+* add missing 'color' parameter mapping for subtitle overlays transformation. ([2c4a6d2](https://github.com/imagekit-developer/imagekit-nodejs/commit/2c4a6d20aec544c01fb29e7b2d64513527a11ccc))
+* lint error ([b320d6f](https://github.com/imagekit-developer/imagekit-nodejs/commit/b320d6f9a03f1aefd1d9edad23618953b29d100c))
+* linting issues ([3794fe5](https://github.com/imagekit-developer/imagekit-nodejs/commit/3794fe565330087cae39bb5e35c77b0ecc6c2a2a))
+* update raw parameter example in README for clarity ([e86beab](https://github.com/imagekit-developer/imagekit-nodejs/commit/e86beabfa77291baaf3cd3bf6be7f1336170e51d))
+* update serverConfig to include valid URLs and improve label descriptions ([49d048f](https://github.com/imagekit-developer/imagekit-nodejs/commit/49d048fba3d9ede0e3e92991e8829d51c04c1229))
+
+
+### Chores
+
+* configure new SDK language ([33d1237](https://github.com/imagekit-developer/imagekit-nodejs/commit/33d12370088d062a282f81625c63522a5d961308))
+* **internal:** remove .eslintcache ([ec12af7](https://github.com/imagekit-developer/imagekit-nodejs/commit/ec12af7ecad37e8f7a227b356acd0d0cc1c52255))
+* **jsdoc:** fix [@link](https://github.com/link) annotations to refer only to parts of the package‘s public interface ([4332a7e](https://github.com/imagekit-developer/imagekit-nodejs/commit/4332a7e3680d596f508b6d2c83b1e9faab6af878))
+
+
+### Documentation
+
+* update README to enhance Table of Contents and add raw transformations parameter ([892d31c](https://github.com/imagekit-developer/imagekit-nodejs/commit/892d31c9105c1c8c9bbd08983c2a0c9a62aee883))
+
+
+### Refactors
+
+* streamline transformation string handling in URL construction ([6e99777](https://github.com/imagekit-developer/imagekit-nodejs/commit/6e99777260db5c7fe833d4e71abe5abafb95156d))
+
 ## 7.1.0 (2025-09-30)
 
 Full Changelog: [v7.0.1...v7.1.0](https://github.com/imagekit-developer/imagekit-nodejs/compare/v7.0.1...v7.1.0)

diff --git a/README.md b/README.md
@@ -10,6 +10,36 @@ For additional details, refer to the [ImageKit REST API documentation](https://i
 
 If you are looking to integrate file uploads in browsers, use one of our [frontend SDKs](https://imagekit.io/docs/quick-start-guides#front-end).
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Request & Response types](#request--response-types)
+- [File uploads](#file-uploads)
+- [URL generation](#url-generation)
+  - [Basic URL generation](#basic-url-generation)
+  - [URL generation with transformations](#url-generation-with-transformations)
+  - [URL generation with image overlay](#url-generation-with-image-overlay)
+  - [URL generation with text overlay](#url-generation-with-text-overlay)
+  - [URL generation with multiple overlays](#url-generation-with-multiple-overlays)
+  - [Signed URLs for secure delivery](#signed-urls-for-secure-delivery)
+  - [Using Raw parameter for custom transformations](#using-raw-parameter-for-custom-transformations)
+- [Authentication parameters for client-side uploads](#authentication-parameters-for-client-side-uploads)
+- [Webhook verification](#webhook-verification)
+  - [Verifying webhook signatures](#verifying-webhook-signatures)
+- [Handling errors](#handling-errors)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+- [Advanced Usage](#advanced-usage)
+  - [Accessing raw Response data (e.g., headers)](#accessing-raw-response-data-eg-headers)
+  - [Logging](#logging)
+  - [Making custom/undocumented requests](#making-customundocumented-requests)
+  - [Customizing the fetch client](#customizing-the-fetch-client)
+  - [Fetch options](#fetch-options)
+- [Semantic versioning](#semantic-versioning)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+
 ## Installation
 
 ```sh
@@ -98,7 +128,7 @@ Generate a simple URL without any transformations:
 import ImageKit from '@imagekit/nodejs';
 
 const client = new ImageKit({
-  privateKey: process.env['IMAGEKIT_PRIVATE_KEY']
+  privateKey: process.env['IMAGEKIT_PRIVATE_KEY'],
 });
 
 // Basic URL without transformations
@@ -264,6 +294,26 @@ const permanentSignedUrl = client.helper.buildSrc({
 // Result: URL with signature parameter (?ik-s=signature)
 ```
 
+### Using Raw parameter for custom transformations
+
+ImageKit frequently adds new transformation parameters that might not yet be documented in the SDK. You can use the `raw` parameter to access these features or create custom transformation strings:
+
+```ts
+// Using raw parameter for custom transformations
+const customTransformUrl = client.helper.buildSrc({
+  urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
+  src: '/path/to/image.jpg',
+  transformation: [
+    {
+      width: 400,
+      height: 300,
+      raw: 'something-new',
+    },
+  ],
+});
+// Result: https://ik.imagekit.io/your_imagekit_id/path/to/image.jpg?tr=w-400,h-300,something-new
+```
+
 ## Authentication parameters for client-side uploads
 
 Generate authentication parameters for secure client-side file uploads:
@@ -300,11 +350,11 @@ try {
   // Verify and unwrap webhook payload
   const event = client.webhooks.unwrap(
     webhookBody, // Raw webhook payload (string)
-    { 
+    {
       headers: webhookHeaders, // Request headers containing signature
-    }
+    },
   );
-  
+
   console.log('Webhook signature is valid');
   console.log('Event type:', event.type);
   console.log('Event data:', event.data);
@@ -595,8 +645,6 @@ const client = new ImageKit({
 });
 ```
 
-## Frequently Asked Questions
-
 ## Semantic versioning
 
 This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@imagekit/nodejs",
-  "version": "7.1.0",
+  "version": "7.1.1",
   "description": "Offical NodeJS SDK for ImageKit.io integration",
   "author": "Image Kit <[email protected]>",
   "types": "dist/index.d.ts",

diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md
@@ -10,7 +10,7 @@ You can run the MCP Server directly via `npx`:
 export IMAGEKIT_PRIVATE_KEY="My Private Key"
 export OPTIONAL_IMAGEKIT_IGNORES_THIS="My Password"
 export IMAGEKIT_WEBHOOK_SECRET="My Webhook Secret"
-npx -y imagekit-api-mcp@latest
+npx -y @imagekit/api-mcp@latest
 ```
 
 ### Via MCP Client
@@ -25,7 +25,7 @@ For clients with a configuration JSON, it might look something like this:
   "mcpServers": {
     "imagekit_nodejs_api": {
       "command": "npx",
-      "args": ["-y", "imagekit-api-mcp", "--client=claude", "--tools=dynamic"],
+      "args": ["-y", "@imagekit/api-mcp", "--client=claude", "--tools=dynamic"],
       "env": {
         "IMAGEKIT_PRIVATE_KEY": "My Private Key",
         "OPTIONAL_IMAGEKIT_IGNORES_THIS": "My Password",
@@ -172,10 +172,10 @@ http://localhost:3000?client=cursor&capability=tool-name-length%3D40
 
 ```js
 // Import the server, generated endpoints, or the init function
-import { server, endpoints, init } from "imagekit-api-mcp/server";
+import { server, endpoints, init } from "@imagekit/api-mcp/server";
 
 // import a specific tool
-import createCustomMetadataFields from "imagekit-api-mcp/tools/custom-metadata-fields/create-custom-metadata-fields";
+import createCustomMetadataFields from "@imagekit/api-mcp/tools/custom-metadata-fields/create-custom-metadata-fields";
 
 // initialize the server and all endpoints
 init({ server, endpoints });

diff --git a/packages/mcp-server/build b/packages/mcp-server/build
@@ -29,7 +29,7 @@ cp tsconfig.dist-src.json dist/src/tsconfig.json
 
 chmod +x dist/index.js
 
-DIST_PATH=./dist PKG_IMPORT_PATH=imagekit-api-mcp/ node ../../scripts/utils/postprocess-files.cjs
+DIST_PATH=./dist PKG_IMPORT_PATH=@imagekit/api-mcp/ node ../../scripts/utils/postprocess-files.cjs
 
 # mcp bundle
 rm -rf dist-bundle imagekit_nodejs_api.mcpb; mkdir dist-bundle

diff --git a/packages/mcp-server/cloudflare-worker/package.json b/packages/mcp-server/cloudflare-worker/package.json
@@ -21,7 +21,7 @@
     "@modelcontextprotocol/sdk": "^1.11.4",
     "agents": "^0.0.88",
     "hono": "^4.7.9",
-    "imagekit-api-mcp": "latest",
+    "@imagekit/api-mcp": "latest",
     "zod": "^3.24.4"
   }
 }
diff --git a/packages/mcp-server/cloudflare-worker/src/app.ts b/packages/mcp-server/cloudflare-worker/src/app.ts
@@ -8,7 +8,7 @@ import {
   renderAuthorizationRejectedContent,
 } from './utils';
 import type { OAuthHelpers } from '@cloudflare/workers-oauth-provider';
-import { McpOptions } from 'imagekit-api-mcp/server';
+import { McpOptions } from '@imagekit/api-mcp/server';
 import { ServerConfig } from '.';
 
 export type Bindings = Env & {

diff --git a/packages/mcp-server/cloudflare-worker/src/index.ts b/packages/mcp-server/cloudflare-worker/src/index.ts
@@ -1,7 +1,7 @@
 import { makeOAuthConsent } from './app';
 import { McpAgent } from 'agents/mcp';
 import OAuthProvider from '@cloudflare/workers-oauth-provider';
-import { McpOptions, initMcpServer, server, ClientOptions } from 'imagekit-api-mcp/server';
+import { McpOptions, initMcpServer, server, ClientOptions } from '@imagekit/api-mcp/server';
 
 type MCPProps = {
   clientProps: ClientOptions;
@@ -13,39 +13,39 @@ type MCPProps = {
  */
 const serverConfig: ServerConfig = {
   orgName: 'ImageKit',
-  instructionsUrl: undefined, // Set a url for where you show users how to get an API key
-  logoUrl: undefined, // Set a custom logo url to appear during the OAuth flow
+  instructionsUrl: 'https://imagekit.io/docs/mcp-server', // Set a url for where you show users how to get an API key
+  logoUrl: 'https://ik.imagekit.io/ikmedia/logo/light_T4buIzohVH.svg', // Set a custom logo url to appear during the OAuth flow
   clientProperties: [
     {
       key: 'privateKey',
-      label: 'Private Key',
+      label: 'ImageKit Private Key',
       description:
         'Your ImageKit private API key (starts with `private_`).\nYou can find this in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).\n',
       required: true,
       default: undefined,
-      placeholder: 'My Private Key',
+      placeholder: 'ImageKit Private Key',
       type: 'password',
     },
-    {
-      key: 'password',
-      label: 'Password',
-      description:
-        'ImageKit uses your API key as username and ignores the password. \nThe SDK sets a dummy value. You can ignore this field.\n',
-      required: false,
-      default: 'do_not_set',
-      placeholder: 'My Password',
-      type: 'password',
-    },
-    {
-      key: 'webhookSecret',
-      label: 'Webhook Secret',
-      description:
-        "Your ImageKit webhook secret for verifying webhook signatures (starts with `whsec_`).\nYou can find this in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks).\nOnly required if you're using webhooks.\n",
-      required: false,
-      default: null,
-      placeholder: 'My Webhook Secret',
-      type: 'string',
-    },
+    // {
+    //   key: 'password',
+    //   label: 'Password',
+    //   description:
+    //     'ImageKit uses your API key as username and ignores the password. \nThe SDK sets a dummy value. You can ignore this field.\n',
+    //   required: false,
+    //   default: 'do_not_set',
+    //   placeholder: 'My Password',
+    //   type: 'password',
+    // },
+    // {
+    //   key: 'webhookSecret',
+    //   label: 'Webhook Secret',
+    //   description:
+    //     "Your ImageKit webhook secret for verifying webhook signatures (starts with `whsec_`).\nYou can find this in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/webhooks).\nOnly required if you're using webhooks.\n",
+    //   required: false,
+    //   default: null,
+    //   placeholder: 'My Webhook Secret',
+    //   type: 'string',
+    // },
   ],
 };
 

diff --git a/packages/mcp-server/cloudflare-worker/src/utils.ts b/packages/mcp-server/cloudflare-worker/src/utils.ts
@@ -4,7 +4,7 @@ import type { HtmlEscapedString } from 'hono/utils/html';
 import { marked } from 'marked';
 import type { AuthRequest } from '@cloudflare/workers-oauth-provider';
 import { env } from 'cloudflare:workers';
-import { ServerConfig, McpOptions, ClientType, Filter, ClientProperty } from 'imagekit-api-mcp/server';
+import { ServerConfig, McpOptions, ClientType, Filter, ClientProperty } from '@imagekit/api-mcp/server';
 
 export const layout = (content: HtmlEscapedString | string, title: string, config: ServerConfig) => html`
   <!doctype html>

diff --git a/packages/mcp-server/jest.config.ts b/packages/mcp-server/jest.config.ts
@@ -7,8 +7,8 @@ const config: JestConfigWithTsJest = {
     '^.+\\.(t|j)sx?$': ['@swc/jest', { sourceMaps: 'inline' }],
   },
   moduleNameMapper: {
-    '^imagekit-api-mcp$': '<rootDir>/src/index.ts',
-    '^imagekit-api-mcp/(.*)$': '<rootDir>/src/$1',
+    '^@imagekit/api-mcp$': '<rootDir>/src/index.ts',
+    '^@imagekit/api-mcp/(.*)$': '<rootDir>/src/$1',
   },
   modulePathIgnorePatterns: ['<rootDir>/dist/'],
   testPathIgnorePatterns: ['scripts'],

diff --git a/packages/mcp-server/manifest.json b/packages/mcp-server/manifest.json
@@ -1,6 +1,6 @@
 {
   "dxt_version": "0.2",
-  "name": "imagekit-api-mcp",
+  "name": "@imagekit/api-mcp",
   "version": "0.0.1-alpha.0",
   "description": "The official MCP Server for the Image Kit API",
   "author": {

diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "imagekit-api-mcp",
-  "version": "7.1.0",
+  "name": "@imagekit/api-mcp",
+  "version": "7.1.1",
   "description": "The official MCP Server for the Image Kit API",
   "author": "Image Kit <[email protected]>",
   "types": "dist/index.d.ts",
@@ -68,8 +68,8 @@
     "typescript": "5.8.3"
   },
   "imports": {
-    "imagekit-api-mcp": ".",
-    "imagekit-api-mcp/*": "./src/*"
+    "@imagekit/api-mcp": ".",
+    "@imagekit/api-mcp/*": "./src/*"
   },
   "exports": {
     ".": {

diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
@@ -34,7 +34,7 @@ export const newMcpServer = () =>
   new McpServer(
     {
       name: 'imagekit_nodejs_api',
-      version: '7.1.0',
+      version: '7.1.1',
     },
     { capabilities: { tools: {}, logging: {} } },
   );

diff --git a/packages/mcp-server/src/tools/accounts/origins/create-accounts-origins.ts b/packages/mcp-server/src/tools/accounts/origins/create-accounts-origins.ts
@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, asTextContentResult } from 'imagekit-api-mcp/tools/types';
+import { Metadata, asTextContentResult } from '@imagekit/api-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import ImageKit from '@imagekit/nodejs';

diff --git a/packages/mcp-server/src/tools/accounts/origins/delete-accounts-origins.ts b/packages/mcp-server/src/tools/accounts/origins/delete-accounts-origins.ts
@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, asTextContentResult } from 'imagekit-api-mcp/tools/types';
+import { Metadata, asTextContentResult } from '@imagekit/api-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import ImageKit from '@imagekit/nodejs';

diff --git a/packages/mcp-server/src/tools/accounts/origins/get-accounts-origins.ts b/packages/mcp-server/src/tools/accounts/origins/get-accounts-origins.ts
@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, asTextContentResult } from 'imagekit-api-mcp/tools/types';
+import { Metadata, asTextContentResult } from '@imagekit/api-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import ImageKit from '@imagekit/nodejs';

diff --git a/packages/mcp-server/src/tools/accounts/origins/list-accounts-origins.ts b/packages/mcp-server/src/tools/accounts/origins/list-accounts-origins.ts
@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, asTextContentResult } from 'imagekit-api-mcp/tools/types';
+import { Metadata, asTextContentResult } from '@imagekit/api-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import ImageKit from '@imagekit/nodejs';

diff --git a/packages/mcp-server/src/tools/accounts/origins/update-accounts-origins.ts b/packages/mcp-server/src/tools/accounts/origins/update-accounts-origins.ts
@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, asTextContentResult } from 'imagekit-api-mcp/tools/types';
+import { Metadata, asTextContentResult } from '@imagekit/api-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import ImageKit from '@imagekit/nodejs';

diff --git a/packages/mcp-server/src/tools/accounts/url-endpoints/create-accounts-url-endpoints.ts b/packages/mcp-server/src/tools/accounts/url-endpoints/create-accounts-url-endpoints.ts
@@ -1,7 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { maybeFilter } from 'imagekit-api-mcp/filtering';
-import { Metadata, asTextContentResult } from 'imagekit-api-mcp/tools/types';
+import { maybeFilter } from '@imagekit/api-mcp/filtering';
+import { Metadata, asTextContentResult } from '@imagekit/api-mcp/tools/types';
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import ImageKit from '@imagekit/nodejs';