npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

fluidghost

v2.1.0

Published

Official TypeScript/JavaScript client for the FluidGhost API. Spoof a photo, video, or carousel with your API key and get back distinct variants with device-authentic metadata — submit, poll, download.

Readme

fluidghost

Official TypeScript/JavaScript client for the FluidGhost API.

FluidGhost turns one photo or video into a set of distinct variants — each a fresh, standalone capture with its own metadata, its own pixels, and a device-authentic filename. This SDK spoofs media with your API key, over the submit → poll → download loop (a single photo, a video, or a whole carousel), and inspects metadata (read-only).

Install

npm install fluidghost

Authentication

Mint an API key in the dashboard (Settings → API keys at https://ghost.fluidvip.com). Keep it server-side — never ship it in client code. A secret API key can submit jobs, read and download their results, and inspect metadata (management keys only provision).

import { FluidGhost } from "fluidghost";

const fg = new FluidGhost({ apiKey: process.env.FLUIDGHOST_KEY! });

Spoof a photo or video

If your API key has a saved preset bound to it (pick it when you create the key in the dashboard), the key already carries the settings — the whole call is just the image:

const job = await fg.run({ image: { path: "photo.jpg" } });

Otherwise name the settings on the call, as below. Note that recipeId, recipeConfig and presetId override the key's bound preset.

run() submits a job and waits for it to finish. Results are one-time links: downloadVariant() streams the bytes and the object is deleted on a successful download (a second call throws 410). Photos and videos both go through the same call — the type is detected from the file.

import { FluidGhost } from "fluidghost";
import { writeFile } from "node:fs/promises";

const fg = new FluidGhost({ apiKey: process.env.FLUIDGHOST_KEY! });

const job = await fg.run({
  image: { path: "photo.jpg" },      // or a video: { path: "clip.mp4" }
  recipeId: "full-refresh",
  copies: 3,
  options: { noise: 35, ultraSafe: true },
});

for (const v of job.variants) {
  if (v.status !== "completed") continue;
  const bytes = await fg.downloadVariant(job.jobId, v.index);
  await writeFile(v.fileName ?? `variant-${v.index}.jpg`, bytes);
  console.log(`${v.fileName}  risk=${v.detectionRisk} (${v.riskBand})`);
}

Manual submit + poll

const { jobId } = await fg.createJob({ image: { path: "photo.jpg" }, recipeId: "full-refresh", copies: 5 });
const done = await fg.waitForJob(jobId, { onPoll: (j) => console.log(j.status, j.progress) });

You can also pass in-memory bytes instead of a path:

await fg.createJob({ image: { data: myUint8Array, filename: "photo.jpg" }, recipeId: "full-refresh" });

Spoof a carousel (matched set)

A carousel is a set of photos posted together. spoofCarousel() submits one linked job per file — sharing a session and a running filename sequence so the outputs read as a single cohesive post — and waits for all of them.

const jobs = await fg.spoofCarousel(
  [{ path: "slide1.jpg" }, { path: "slide2.jpg" }, { path: "slide3.jpg" }],
  { recipeId: "full-refresh" },
);

for (const job of jobs) {
  const v = job.variants[0];
  const bytes = await fg.downloadVariant(job.jobId, v.index);
  await writeFile(v.fileName!, bytes);
}

For a fully cohesive set (the same device across every slide), pass a recipeConfig or presetId that pins a device — otherwise each slide picks its own device family.

Inspect metadata

Read-only checks that need no job. They use the inspect:read scope (secret keys have it by default) and share one rate-limit bucket (60 requests/min per account). Each takes the same file input as the spoof calls: { path } or { data, filename }.

// Metadata grouped by container (EXIF, GPS, XMP, MakerNotes, ...)
const meta = await fg.inspect({ path: "photo.jpg" });
console.log(meta.format, meta.tagCount, meta.groups.IFD0?.Model);

// Deep forensic verdict: metadata, container structure, C2PA
const report = await fg.inspectForensics({ path: "photo.jpg" });
console.log(report.status, report.verdict, report.findings.length);

// Perceptual comparison of an original and a variant (no job is created)
const cmp = await fg.inspectCompare({ path: "original.jpg" }, { path: "variant.jpg" });
console.log(cmp.detectionRisk, cmp.band, cmp.matchThreshold);

// Metadata of one of your finished job's variants, read server-side
const resultMeta = await fg.inspectResult(job.jobId, 0);

A key without inspect:read gets a FluidGhostError with status 403 and code insufficient_scope.

Settings

Provide exactly one recipe source (or bind a default preset to your key and omit all three; any of the three you do send overrides the key's preset):

| Field | Meaning | | --- | --- | | recipeId | A bundled starter, e.g. "full-refresh". | | presetId | A saved preset created in the dashboard (e.g. "sys:full-refresh"). | | recipeConfig | A full recipe graph (advanced). | | copies | Number of variants, 1–50. | | strength | Global strength 0–100. | | options | Extra knobs merged onto the recipe, e.g. { noise: 35, ultraSafe: true }. |

Errors

Every non-2xx response throws a FluidGhostError mirroring the API's { error, message, details }:

import { FluidGhostError } from "fluidghost";

try {
  await fg.run({ image: { path: "photo.jpg" }, recipeId: "full-refresh", copies: 3 });
} catch (e) {
  if (e instanceof FluidGhostError) {
    console.error(e.status, e.code, e.message, e.details);
    if (e.code === "rate_limited") await sleep((e.retryAfter ?? 5) * 1000);
    if (e.code === "insufficient_balance") { /* top up in the dashboard */ }
  }
}

Configuration

new FluidGhost({
  apiKey: "fg_sk_live_…",
  baseUrl: "https://api-ghost.fluidvip.com", // default; override for a proxy
  fetch: customFetch,                         // optional
});

License

MIT