> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# NiftyImages plugin

> Read NiftyImages images, widgets, maps and Photoshop images with their open stats, manage Data Store records, map locations and widget or Bee Plugin users, move countdown timer dates, and edit Photoshop layers.

Use **NiftyImages** through Corsair: one client, typed API calls.

The API key comes from the NiftyImages account. NiftyImages sells the Developer API on its Enterprise plan; a free or Starter account has no key. The plugin sends the key in the `ApiKey` header, one of the transports the docs allow, so it never appears in a URL a proxy would log.

What each group does:

* **Images.** `images.list` pages through every personalized image and countdown timer, `images.stats` reports opens over a window, and `images.get` and `images.delete` take the image's URL.
* **Timers.** `timers.updateTargetDate` moves a countdown timer's deadline.
* **Data Store.** `store.fields` lists the fields, `store.addRecord` adds a record or updates the one whose unique fields match, and `store.deleteById` and `store.deleteRecord` remove one.
* **Maps.** `maps.list`, `maps.get` and `maps.searchLocations` read maps; `maps.addLocation`, `maps.updateLocation` and `maps.deleteLocation` change their locations, which NiftyImages geocodes in the background.
* **Photoshop images.** `psd.get` lists the variables and layers, and `psd.update` edits layers by `LayerName` (text, colours, images, visibility).
* **Widgets and Bee Plugin.** List widgets and their stats, users and images, and suspend or reinstate a widget or Bee Plugin user.

Things worth knowing:

* **Lists answer bare arrays.** `widgets.list` sends `[{ "Name": "...", "WidgetKey": "..." }]` with no envelope, so the plugin keys each list (`widgets`, `images`, `fields`, `locations`). A non-array body means an error rather than an empty page.
* **Property names are PascalCase**, as sent: `WidgetKey`, `Impressions`, `CreateDate`. Only the Data Store field list is lowercase (`name`, `type`, `unique`).
* **`Opens` is a string in lists and a number on one image.** Both are accepted.
* **Images, maps and Photoshop images are addressed by their image URL**, e.g. `https://img1.niftyimages.com/p/lop/m7w`, passed as `url`.
* **Deletes, suspends and Data Store deletes answer an empty 200.** The plugin reports `{ success: true }`.
* **Every date is ISO 8601**, e.g. `2016-03-12T08:00Z`. Stats windows default to the last 30 days.
* **A user or recipient goes in the path**, usually an email address, so the plugin percent-encodes it.
* **A wrong path can answer an HTML page rather than JSON**, which is reported as a path problem.

**What you get:**

* 27 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/niftyimages better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/niftyimages better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/niftyimages better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/niftyimages better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { niftyimages } from '@corsair-dev/niftyimages';

export const corsair = createCorsair({
	plugins: [
		niftyimages(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the NiftyImages API key before the first call: `pnpm corsair setup --plugin=niftyimages --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> niftyimages()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'niftyimages',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**Page through the account's images**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.niftyimages.api.images.list({ pageSize: 10 });
```

**Move a countdown timer**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.niftyimages.api.timers.updateTargetDate({ TimerImageUrl: 'https://img1.niftyimages.com/z/qwcd/ywcd', TargetDate: '2026-12-24T00:00:00Z' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/niftyimages/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/niftyimages/api.md)
>
> Every `niftyimages.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.