@musallam/firefly-client

TypeScript client library for the Adobe Firefly API.

This package is part of the firefly-services-clients monorepo.

Features

• 🚀 Full TypeScript support with auto-generated types from OpenAPI spec
• 📦 Comprehensive API coverage for Firefly endpoints
• 🔄 Job polling utilities for long-running operations
• 🔐 Built-in authentication via IMS client
• 📝 Typed responses and strong intellisense

Installation

npm install @musallam/firefly-client
Copy

Quick start (recommended)

Use IMSClient and pass auth headers on each request (same pattern as the repo samples):

import { FireflyApiClient, pollGenerateImagesJob, IMSClient } from '@musallam/firefly-client';

const imsClient = new IMSClient({
  clientId: process.env.ADOBE_CLIENT_ID!,
  clientSecret: process.env.ADOBE_CLIENT_SECRET!,
  scopes: ['openid', 'AdobeID', 'firefly_api', 'ff_apis'],
});

const authHeaders = await imsClient.getAuthHeaders();

const job = await FireflyApiClient.generateImagesV3Async(
  { prompt: 'A red bicycle on a cobblestone street at golden hour' },
  { headers: authHeaders }
);

const result = await pollGenerateImagesJob(job, {
  axiosRequestConfig: { headers: authHeaders },
});

console.log(
  'Images:',
  result?.result.outputs.map((o) => o.image.url)
);
Copy

API surface (FireflyApiClient)

All functions are imported as FireflyApiClient from @musallam/firefly-client:

Area	Methods
Async image	generateImagesV3Async, generateSimilarImagesV3Async, expandImagesV3Async, fillImagesV3Async
Composites	generateObjectCompositeV3Async, preciseComposite, adaptiveComposite
Video	generateVideoV3
Custom models	getCustomModels
Upload	storageImageV2 (JPEG body; see spec for content type)
Job control	jobResultV3, cancelJobV4

Async POSTs return an acceptance payload (e.g. jobId, statusUrl). Poll using the helpers below.

Job polling

Async jobs return { statusUrl, ... }. Poll until completion:

import {
  FireflyApiClient,
  pollFireflyJob,
  pollGenerateImagesJob,
  pollGenerateSimilarJob,
  pollGenerateObjectCompositeJob,
  pollGenerateVideoJob,
  pollGenerateExpandJob,
  pollGenerateFillJob,
} from '@musallam/firefly-client';

// Generic — you supply the result type
const typed = await pollFireflyJob<YourResultType>(job, {
  axiosRequestConfig: { headers: authHeaders },
  intervalMs: 2000,
  maxAttempts: 60,
  onProgress: (status) => console.log(status.status, status.progress),
});

// Typed helpers (wrap pollFireflyJob with the right result type)
await pollGenerateImagesJob(job, { axiosRequestConfig: { headers: authHeaders } });
await pollGenerateSimilarJob(job, { axiosRequestConfig: { headers: authHeaders } });
await pollGenerateObjectCompositeJob(job, { axiosRequestConfig: { headers: authHeaders } });
await pollGenerateVideoJob(job, { axiosRequestConfig: { headers: authHeaders } });
await pollGenerateExpandJob(job, { axiosRequestConfig: { headers: authHeaders } });
await pollGenerateFillJob(job, { axiosRequestConfig: { headers: authHeaders } });
Copy

Object composite example

const job = await FireflyApiClient.generateObjectCompositeV3Async(
  {
    prompt: 'Your scene description',
    // ...see GenerateObjectCompositeRequestV3 / BodyGenerateObjectCompositeV3Async in generated types
  },
  { headers: authHeaders }
);

const result = await pollGenerateObjectCompositeJob(job, {
  axiosRequestConfig: { headers: authHeaders },
});
Copy

Custom models (sync GET)

const models = await FireflyApiClient.getCustomModels({ limit: 20 }, { headers: authHeaders });
Copy

Alternative: Axios interceptors

If you prefer a global interceptor on FIREFLY_AXIOS_INSTANCE:

import { FIREFLY_AXIOS_INSTANCE, FireflyApiClient, TokenIMSClient } from '@musallam/firefly-client';

const imsClient = new TokenIMSClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  scopes: ['openid', 'AdobeID', 'firefly_api', 'ff_apis'],
});

FIREFLY_AXIOS_INSTANCE.interceptors.request.use(async (config) => {
  const token = await imsClient.getAccessToken();
  config.headers.Authorization = `Bearer ${token}`;
  config.headers['x-api-key'] = 'YOUR_CLIENT_ID';
  return config;
});

await FireflyApiClient.getCustomModels();
Copy

Custom Axios / proxy

import { FIREFLY_AXIOS_INSTANCE } from '@musallam/firefly-client';

FIREFLY_AXIOS_INSTANCE.defaults.baseURL = 'https://your-proxy.example.com';
FIREFLY_AXIOS_INSTANCE.defaults.timeout = 60000;
Copy

Migrating from older @musallam/firefly-client (multiple clients)

Previously, the package exported separate namespaces such as ImageGenerationClient, CustomModelsClient, etc. Now everything is under FireflyApiClient.

Before	After
ImageGenerationClient.generateImagesV3Async(...)	FireflyApiClient.generateImagesV3Async(...)
CustomModelsClient.getCustomModels(...)	FireflyApiClient.getCustomModels(...)
UploadImageClient.storageImageV2(...)	FireflyApiClient.storageImageV2(...)

Polling helpers (pollGenerateImagesJob, etc.) still exist; ensure the job object includes statusUrl from the async response.

TypeDoc / reference

👉 Package API docs (when published)

License

MIT