Adobe Local Dev Loop

Overview

Set up a fast local development workflow for Adobe integrations using the aio CLI for App Builder projects, or a standalone Node.js setup for direct API usage (Firefly Services, PDF Services).

Prerequisites

• Completed adobe-install-auth setup
• Node.js 18+ with npm/pnpm
• Adobe Developer Console project configured
• @adobe/aio-cli installed globally (for App Builder projects)

Instructions

Step 1: Choose Your Project Type

Option A — App Builder (serverless Runtime actions):

# Install Adobe I/O CLI
npm install -g @adobe/aio-cli

# Login (opens browser for IMS auth)
aio login

# Create new App Builder project
aio app init my-adobe-app
# Select: Firefly Services, Adobe I/O Events, etc.

# Run locally with hot reload
aio app run
# Serves at https://localhost:9080 with live Runtime action emulation

Option B — Standalone SDK project:

mkdir my-adobe-project && cd my-adobe-project
npm init -y
npm install @adobe/pdfservices-node-sdk @adobe/firefly-apis dotenv
npm install -D typescript tsx vitest @types/node

Step 2: Project Structure

my-adobe-project/
├── src/
│   ├── adobe/
│   │   ├── auth.ts           # OAuth token management (from install-auth)
│   │   ├── firefly.ts        # Firefly API client wrapper
│   │   ├── pdf-services.ts   # PDF Services client wrapper
│   │   └── photoshop.ts      # Photoshop API client wrapper
│   └── index.ts
├── tests/
│   ├── fixtures/
│   │   └── sample.pdf        # Test PDF for extraction tests
│   ├── adobe-auth.test.ts
│   └── firefly.test.ts
├── .env.local                # Local secrets (git-ignored)
├── .env.example              # Template for team
├── tsconfig.json
└── package.json

Step 3: Configure Hot Reload and Scripts

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "test:integration": "vitest --config vitest.integration.config.ts",
    "typecheck": "tsc --noEmit"
  }
}

Step 4: Mock Adobe APIs for Unit Tests

// tests/adobe-auth.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';

// Mock the global fetch for token endpoint
const mockFetch = vi.fn();
global.fetch = mockFetch;

import { getAdobeAccessToken } from '../src/adobe/auth';

describe('Adobe OAuth Auth', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    process.env.ADOBE_CLIENT_ID = 'test-client-id';
    process.env.ADOBE_CLIENT_SECRET = 'test-secret';
    process.env.ADOBE_SCOPES = &#

Adobe Migration Deep Dive

Overview

Comprehensive guide for three major migration scenarios: (1) legacy Adobe API consolidation into Firefly Services, (2) migrating from competitor document/image APIs to Adobe, and (3) JWT credential migration to OAuth Server-to-Server.

Prerequisites

• Current system documentation with API inventory
• Adobe Developer Console project with target APIs
• Feature flag infrastructure
• Rollback strategy tested in staging

Instructions

Migration Type Assessment

Scenario 1: Consolidate to Firefly Services SDK

The Photoshop and Lightroom APIs were previously separate. They are now part of Firefly Services with a unified SDK:

// BEFORE: Separate clients for each API
import { PhotoshopAPI } from 'some-old-photoshop-client';
import { LightroomAPI } from 'some-old-lightroom-client';

// AFTER: Unified Firefly Services SDK
import { PhotoshopClient } from '@adobe/photoshop-apis';
import { LightroomClient } from '@adobe/lightroom-apis';
import { FireflyClient } from '@adobe/firefly-apis';

// All use the same OAuth credentials
const config = {
  clientId: process.env.ADOBE_CLIENT_ID!,
  accessToken: await getAccessToken(),
};

const photoshop = new PhotoshopClient(config);
const lightroom = new LightroomClient(config);
const firefly = new FireflyClient(config);

Scenario 2: Migrate from Competitor to Adobe PDF Services

// src/adapters/document-adapter.ts
// Adapter pattern for gradual migration from PDFTron/other to Adobe

interface DocumentAdapter {
  extractText(pdfPath: string): Promise<string>;
  createPdf(htmlContent: string): Promise<Buffer>;
  mergePdfs(pdfPaths: string[]): Promise<Buffer>;
}

// Old implementation
class PdfTronAdapter implements DocumentAdapter {
  async extractText(pdfPath: string): Promise<string> {
    // ... existing PDFTron code
  }
  // ...
}

// New Adobe implementation
class AdobePdfAdapter implements DocumentAdapter {
  private pdfServices: PDFServices;

  constructor() {
    const credentials = new ServicePrincipalCredentials({
      clientId: process.env.ADOBE_CLIENT_ID!,
      clientSecret: process.en

Adobe Multi-Environment Setup

Overview

Configure Adobe APIs across development, staging, and production environments using separate Developer Console projects, environment-specific OAuth credentials, and cloud-native secret management.

Prerequisites

• Adobe Developer Console access (admin or developer role)
• Secret management solution (GCP Secret Manager, AWS Secrets Manager, or Vault)
• CI/CD pipeline with environment variable injection

Instructions

Step 1: Create Separate Developer Console Projects

Adobe best practice: one Developer Console project per environment with separate OAuth credentials.

Step 2: Environment Configuration Files

// src/config/adobe.ts
interface AdobeEnvConfig {
  imsEndpoint: string;       // Same across all envs
  fireflyEndpoint: string;   // Same across all envs
  photoshopEndpoint: string; // Same across all envs
  scopes: string;            // Different per env (least privilege)
  retries: number;
  timeoutMs: number;
  cache: { enabled: boolean; ttlMs: number };
}

const configs: Record<string, AdobeEnvConfig> = {
  development: {
    imsEndpoint: 'https://ims-na1.adobelogin.com',
    fireflyEndpoint: 'https://firefly-api.adobe.io',
    photoshopEndpoint: 'https://image.adobe.io',
    scopes: 'openid,AdobeID',        // Minimal scopes for dev
    retries: 1,                       // Fast failure in dev
    timeoutMs: 15_000,
    cache: { enabled: false, ttlMs: 0 },  // No cache in dev
  },
  staging: {
    imsEndpoint: 'https://ims-na1.adobelogin.com',
    fireflyEndpoint: 'https://firefly-api.adobe.io',
    photoshopEndpoint: 'https://image.adobe.io',
    scopes: 'openid,AdobeID,firefly_api',
    retries: 3,
    timeoutMs: 30_000,
    cache: { enabled: true, ttlMs: 60_000 },
  },
  production: {
    imsEndpoint: 'https://ims-na1.adobelogin.com',
    fireflyEndpoint: 'https://firefly-api.adobe.io',
    photoshopEndpoint: 'https://image.adobe.io',
    scopes: 'openid,AdobeID,firefly_api,ff_apis',
    retries: 5,
    timeoutMs: 60_000,
    cache: { enabled: true, ttlMs: 300_000 },
  },
};

export function getAdobeConfig(): AdobeEnvConfig & { clientId: string; clientSecret: string } {
  const env = process.env.N

Adobe Observability

Overview

Set up comprehensive observability for Adobe API integrations covering four pillars: metrics (Prometheus), traces (OpenTelemetry), logs (structured JSON), and alerts. Each Adobe API has different latency profiles requiring specific monitoring.

Prerequisites

• Prometheus or compatible metrics backend
• OpenTelemetry SDK (@opentelemetry/api)
• Grafana or similar dashboarding tool
• AlertManager or PagerDuty for alerts

Instructions

Step 1: Define Key Metrics by API

Step 2: Instrumented Adobe Client

import { Counter, Histogram, Gauge, Registry } from 'prom-client';

const registry = new Registry();

const apiRequests = new Counter({
  name: 'adobe_api_requests_total',
  help: 'Total Adobe API requests',
  labelNames: ['api', 'operation', 'status'] as const,
  registers: [registry],
});

const apiDuration = new Histogram({
  name: 'adobe_api_duration_seconds',
  help: 'Adobe API request duration in seconds',
  labelNames: ['api', 'operation'] as const,
  buckets: [0.5, 1, 2, 5, 10, 20, 30, 60], // Adobe APIs are slow
  registers: [registry],
});

const apiErrors = new Counter({
  name: 'adobe_api_errors_total',
  help: 'Adobe API errors by code',
  labelNames: ['api', 'error_code'] as const,
  registers: [registry],
});

export async function instrumentedAdobeCall<T>(
  api: string,
  operation: string,
  fn: () => Promise<T>
): Promise<T> {
  const timer = apiDuration.startTimer({ api, operation });
  try {
    const result = await fn();
    apiRequests.inc({ api, operation, status: 'success' }

Adobe Performance Tuning

Overview

Optimize Adobe API performance across Firefly Services, PDF Services, and Photoshop APIs. Key bottlenecks include IMS token generation, async job polling overhead, and cold-start latency on serverless platforms.

Prerequisites

• Adobe SDK installed and functional
• Understanding of which APIs your app uses most
• Redis or in-memory cache available (optional)
• Performance monitoring in place

Latency Benchmarks (Real-World)

Instructions

Optimization 1: Cache IMS Access Tokens (Biggest Win)

The IMS token endpoint returns tokens valid for 24 hours. Never re-generate per request:

// WRONG: generates new token every call (adds 200-500ms each time)
async function makeRequest() {
  const token = await getAccessToken(); // hits IMS every time
}

// RIGHT: cache token and only refresh when expiring
let tokenCache: { token: string; expiresAt: number } | null = null;

async function getCachedToken(): Promise<string> {
  if (tokenCache && tokenCache.expiresAt > Date.now() + 300_000) {
    return tokenCache.token; // Cache hit — 0ms
  }
  const res = await fetch('https://ims-na1.adobelogin.com/ims/token/v3', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.ADOBE_CLIENT_ID!,
      client_secret: process.env.ADOBE_CLIENT_SECRET!,
      grant_type: 'client_credentials',
      scope: process.env.ADOBE_SCOPES!,
    }),
  });
  const data = await res.json();
  tokenCache = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return tokenCache.token;
}

Optimization 2: Parallel Async Job Submission

Firefly and Photoshop APIs are async — submit all jobs first, then poll all:

// SLOW: sequential (total = sum of all job times)
for (const prompt of prompts) {
  const result = await generateImageSync(prompt); // 5-20s each
}

// FAST: parallel submit + parallel poll (total = max job time)
async function batchFireflyGenerate(prompts: string[]) {
  const token = awa

Adobe Policy & Guardrails

Overview

Automated policy enforcement for Adobe integrations: credential pattern scanning (Adobe OAuth secrets use p8_ prefix), Firefly content policy pre-screening, PDF Services quota guardrails, and OAuth scope validation.

Prerequisites

• ESLint configured in project
• CI/CD pipeline (GitHub Actions)
• Understanding of Adobe credential patterns

Instructions

Guardrail 1: Adobe Credential Pattern Scanner

Adobe OAuth Server-to-Server secrets follow the p8_ prefix pattern:

# .github/workflows/adobe-security.yml
name: Adobe Security Scan
on: [push, pull_request]
jobs:
  credential-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan for Adobe credential patterns
        run: |
          EXIT_CODE=0

          # Adobe OAuth client secrets (p8_ prefix)
          if grep -rE "p8_[A-Za-z0-9_-]{20,}" --include="*.ts" --include="*.js" --include="*.py" --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | grep -v node_modules | grep -v '.git'; then
            echo "::error::Adobe client_secret pattern (p8_) found in source code"
            EXIT_CODE=1
          fi

          # Adobe IMS access tokens (JWT format)
          if grep -rE "eyJ[A-Za-z0-9_-]{100,}\.[A-Za-z0-9_-]{100,}" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | grep -v '.git' | grep -v '\.test\.' | grep -v '__mock'; then
            echo "::warning::Potential Adobe access token found in source (may be test fixture)"
          fi

          # Org IDs (format: HEXSTRING@AdobeOrg)
          if grep -rE "[A-F0-9]{24}@AdobeOrg" --include="*.ts" --include="*.js" --include="*.json" . 2>/dev/null | grep -v node_modules | grep -v '.git' | grep -v '.env.example'; then
            echo "::warning::Adobe Org ID found in source — consider using env var"
          fi

          exit $EXIT_CODE

Guardrail 2: Firefly Content Policy Pre-Screener

// src/adobe/guardrails/content-policy.ts
// Pre-screen prompts before sending to Firefly API to avoid wasted credits

interface ContentPolicyResult {
  allowed: boolean;
  violations: string[];
  suggestions: string[];
}

const CONTENT_RULES = [
  {
    name: 'real-people',
    pattern: /\b(photo of|portrait of|picture of)\s+(a\s+)?(real|actual|specific)\s+(person|man|woman|child)/i,
    message: 'Firefly cannot generate images of specific real people',
    suggestion: 'Use generic descriptions like "a professional in a business suit"',
  },
  {
    name: 'trademarks',
    pattern: /\b(nik

Adobe Production Checklist

Overview

Complete checklist for deploying Adobe API integrations to production, covering credential security, health monitoring, graceful degradation, and rollback procedures.

Prerequisites

• Staging environment tested and verified
• Production OAuth credentials created in Developer Console
• Deployment pipeline with secret injection
• Monitoring and alerting infrastructure ready

Instructions

Pre-Deployment: Credentials & Configuration

• [ ] Production OAuth Server-to-Server credentials created (separate from staging)
• [ ] ADOBECLIENTID and ADOBECLIENTSECRET stored in secret manager (not env files)
• [ ] Scopes are minimal: only APIs actually used in production
• [ ] Token caching implemented (avoid re-generating per request)
• [ ] I/O Events webhook endpoints use HTTPS with valid TLS cert
• [ ] Webhook challenge response handler implemented (for registration)

Pre-Deployment: Code Quality

• [ ] All tests passing (npm test)
• [ ] No hardcoded credentials (grep for p8_ prefix patterns)
• [ ] Error handling covers: 401, 403, 429, 500, 503
• [ ] Rate limiting/backoff with Retry-After header support
• [ ] Webhook signature verification using RSA-SHA256
• [ ] Logging redacts credentials and PII
• [ ] API response validation (Zod or equivalent)

Pre-Deployment: Infrastructure

• [ ] Health check endpoint verifies Adobe IMS token generation:

// api/health.ts
export async function adobeHealthCheck() {
  const start = Date.now();
  try {
    // Test token generation (validates credentials are still valid)
    const token = await getAccessToken();
    return {
      status: 'healthy',
      latencyMs: Date.now() - start,
      tokenValid: !!token,
    };
  } catch (error: any) {
    return {
      status: 'unhealthy',
      latencyMs: Date.now() - start,
      error: error.message,
    };
  }
}

• [ ] Circuit breaker configured for Adobe API calls
• [ ] Graceful degradation: app works (degraded) if Adobe is down
• [ ] PDF Services monthly quota tracking (if on free tier)

Deploy: Gradual Rollout

# 1. Pre-flight checks
curl -sf https://staging.example.com/health | jq '.services.adobe'
curl -s https://status.adobe.com | head -5

# 2. Verify production credentials work
curl -s -o /dev/null -w "%{http_code}" -X POST \
  'https://ims-na1.adobelogin.com/ims/token/v3' \
  -d "client_id=${ADOBE_CLIENT_ID}&client_secret=${ADOBE_CLIENT_SECRET}&grant_type=client_credentials&scope=${ADOBE_S

Adobe Rate Limits

Overview

Handle Adobe API rate limits gracefully with exponential backoff, Retry-After header support, and proactive quota management. Each Adobe API has different rate limits.

Prerequisites

• Adobe SDK installed and authenticated
• Understanding of async/await patterns
• Awareness of your API tier and entitlements

Instructions

Step 1: Know Your Rate Limits by API

Step 2: Implement Retry-After Aware Backoff

// src/adobe/rate-limiter.ts
import { AdobeApiError } from './client';

export async function withAdobeBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 60_000 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;

      // Only retry on 429 and 5xx
      const status = error.status || error.response?.status;
      if (status && status !== 429 && (status < 500 || status >= 600)) throw error;

      // Honor Adobe's Retry-After header (seconds)
      let delay: number;
      if (error.retryAfter) {
        delay = error.retryAfter * 1000;
      } else {
        // Exponential backoff with jitter
        const exponential = config.baseDelayMs * Math.pow(2, attempt);
        const jitter = Math.random() * config.baseDelayMs;
        delay = Math.min(exponential + jitter, config.maxDelayMs);
      }

      console.warn(
        `Adobe rate limited (attempt ${attempt + 1}/${config.maxRetries}). ` +
        `Waiting ${(delay / 

Adobe Reference Architecture

Overview

Production-ready architecture patterns for Adobe API integrations, designed around the three main API families: Firefly Services (creative AI), PDF Services (document automation), and I/O Events (event-driven).

Prerequisites

• Understanding of layered architecture
• TypeScript project setup
• Decision on which Adobe APIs to integrate

Instructions

Step 1: Project Structure

my-adobe-project/
├── src/
│   ├── adobe/                     # Adobe client layer
│   │   ├── auth.ts                # OAuth Server-to-Server token management
│   │   ├── firefly-client.ts      # Firefly API wrapper (generate, fill, expand)
│   │   ├── pdf-client.ts          # PDF Services wrapper (create, extract, merge)
│   │   ├── photoshop-client.ts    # Photoshop API wrapper (cutout, actions)
│   │   ├── events-client.ts       # I/O Events registration and verification
│   │   ├── types.ts               # Shared Adobe types
│   │   └── errors.ts              # Error classification (retryable vs permanent)
│   ├── services/                  # Business logic layer
│   │   ├── image-generation.ts    # Orchestrates Firefly + Photoshop workflows
│   │   ├── document-pipeline.ts   # Orchestrates PDF create/extract/merge
│   │   └── event-processor.ts     # Routes and processes I/O Events
│   ├── api/                       # API layer (routes, controllers)
│   │   ├── health.ts              # Health check including Adobe IMS
│   │   ├── webhooks/adobe.ts      # I/O Events webhook endpoint
│   │   └── routes/
│   │       ├── images.ts          # Image generation endpoints
│   │       └── documents.ts       # Document processing endpoints
│   ├── jobs/                      # Background job layer
│   │   ├── firefly-batch.ts       # Batch image generation queue
│   │   └── pdf-extraction.ts      # Async PDF extraction worker
│   └── index.ts
├── tests/
│   ├── unit/
│   │   ├── adobe/auth.test.ts
│   │   └── services/
│   └── integration/
│       └── adobe/
│           ├── firefly.test.ts
│           └── pdf-services.test.ts
├── config/
│   ├── adobe.development.json
│   ├── adobe.staging.json
│   └── adobe.production.json
└── package.json

Step 2: Layer Architecture

┌─────────────────────────────────────────────────────┐
│                    API Layer                         │
│   Routes, Controllers, Webhook Endpoints            │
├─────────────────────────────────────────────────────┤
│                  Service Layer                       │
│   Business Logic, Workflow Orchestration             │
│   (image-generation.ts, document-pipeline.ts)       │
├─────────────────────────────────────────────────────┤
│                Adobe Client Layer                    │
│   auth.ts, firefly-client.ts, pdf-client.ts         │
│   Token caching, retry, error classification        │
├──────────────────────────────────────────

Adobe Reliability Patterns

Overview

Production-grade reliability patterns for Adobe API integrations. Adobe APIs present unique challenges: IMS tokens expire after 24h, Firefly/Photoshop jobs are async with variable completion times, and rate limits vary by API. These patterns address each failure mode.

Prerequisites

• Understanding of circuit breaker pattern
• opossum installed for circuit breaker (npm install opossum)
• Queue infrastructure (BullMQ/Redis) for dead letter queue
• Caching layer for fallback data

Instructions

Pattern 1: Circuit Breaker per Adobe API

Different Adobe APIs fail independently — use separate circuit breakers:

import CircuitBreaker from 'opossum';

// IMS circuit breaker (auth failures cascade to everything)
const imsBreaker = new CircuitBreaker(
  async () => {
    const res = await fetch('https://ims-na1.adobelogin.com/ims/token/v3', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        client_id: process.env.ADOBE_CLIENT_ID!,
        client_secret: process.env.ADOBE_CLIENT_SECRET!,
        grant_type: 'client_credentials',
        scope: process.env.ADOBE_SCOPES!,
      }),
    });
    if (!res.ok) throw new Error(`IMS ${res.status}`);
    return res.json();
  },
  {
    timeout: 10_000,              // IMS should respond in 10s
    errorThresholdPercentage: 30, // Open after 30% errors
    resetTimeout: 60_000,         // Try again after 1 min
    volumeThreshold: 3,           // Minimum calls before tripping
  }
);

// Firefly circuit breaker (higher tolerance for latency)
const fireflyBreaker = new CircuitBreaker(
  async (fn: () => Promise<any>) => fn(),
  {
    timeout: 60_000,              // Firefly jobs can take up to 60s
    errorThresholdPercentage: 50,
    resetTimeout: 30_000,
    volumeThreshold: 5,
  }
);

// PDF Services circuit breaker
const pdfBreaker = new CircuitBreaker(
  async (fn: () => Promise<any>) => fn(),
  {
    timeout: 30_000,
    errorThresholdPercentage: 40,
    resetTimeout: 30_000,
    volumeThreshold: 5,
  }
);

// Monitor circuit state
for (const [name, breaker] of [['ims', imsBreaker], ['firefly', fireflyBreaker], ['pdf', pdfBreaker]] as const) {
  breaker.on('open', () => console.warn(`Circuit ${name} OPEN — failing fast`));
  breaker.on('halfOpen', () => console.info(`Circuit ${name} HALF-OPEN — testing recovery`));
  breaker.on('close', () => console.info(`Circuit ${name} CLOSED — normal`));
}

Pattern 2: Graceful Degradation with Fallback

// When Adobe is down, return cached/default data instead of failing

interface FallbackResult<T> {
  data: T;

Adobe SDK Patterns

Overview

Production-ready patterns for Adobe SDK usage across Firefly Services (@adobe/firefly-apis, @adobe/photoshop-apis, @adobe/lightroom-apis), PDF Services (@adobe/pdfservices-node-sdk), and direct REST API calls.

Prerequisites

• Completed adobe-install-auth setup
• Familiarity with async/await patterns
• Understanding of the Adobe API you are integrating

Instructions

Pattern 1: Singleton Auth Client with Token Caching

// src/adobe/client.ts
import { ServicePrincipalCredentials, PDFServices } from '@adobe/pdfservices-node-sdk';

let pdfServicesInstance: PDFServices | null = null;
let tokenCache: { token: string; expiresAt: number } | null = null;

export function getPDFServices(): PDFServices {
  if (!pdfServicesInstance) {
    const credentials = new ServicePrincipalCredentials({
      clientId: process.env.ADOBE_CLIENT_ID!,
      clientSecret: process.env.ADOBE_CLIENT_SECRET!,
    });
    pdfServicesInstance = new PDFServices({ credentials });
  }
  return pdfServicesInstance;
}

export async function getAccessToken(): Promise<string> {
  if (tokenCache && tokenCache.expiresAt > Date.now() + 300_000) {
    return tokenCache.token;
  }

  const res = await fetch('https://ims-na1.adobelogin.com/ims/token/v3', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.ADOBE_CLIENT_ID!,
      client_secret: process.env.ADOBE_CLIENT_SECRET!,
      grant_type: 'client_credentials',
      scope: process.env.ADOBE_SCOPES!,
    }),
  });

  if (!res.ok) throw new Error(`Adobe IMS token error: ${res.status}`);
  const data = await res.json();
  tokenCache = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return tokenCache.token;
}

Pattern 2: Typed API Wrapper with Error Classification

// src/adobe/firefly-client.ts
export class AdobeApiError extends Error {
  constructor(
    message: string,
    public readonly status: number,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly retryAfter?: number
  ) {
    super(message);
    this.name = 'AdobeApiError';
  }
}

export async function adobeApiFetch<T>(
  url: string,
  options: RequestInit & { apiKey?: string }
): Promise<T> {
  const token = await getAccessToken();
  const { apiKey, ...fetchOptions } = options;

  const response = await fetch(url, {
    ...fetchOptions,
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-api-key': apiKey || process.env.ADOBE_CLIENT_ID!,
      'Content-Type': 'application/json',
      ...fetchOptions.headers,
   

Adobe Security Basics

Overview

Security best practices for Adobe OAuth Server-to-Server credentials, I/O Events webhook signature verification, and least-privilege access control across Adobe APIs.

Prerequisites

• Adobe Developer Console access
• Understanding of OAuth 2.0 client_credentials flow
• Access to secret management solution (Vault, AWS Secrets Manager, GCP Secret Manager)

Instructions

Step 1: Secure Credential Storage

# .env (NEVER commit to git)
ADOBE_CLIENT_ID=abc123def456
ADOBE_CLIENT_SECRET=p8_XYZ_your_secret_here
ADOBE_SCOPES=openid,AdobeID,firefly_api

# .gitignore — MUST include these
.env
.env.local
.env.*.local
*.pem
*.key

# Production: use your cloud provider's secret manager
# AWS Secrets Manager
aws secretsmanager create-secret \
  --name adobe/production/credentials \
  --secret-string '{"client_id":"...","client_secret":"..."}'

# GCP Secret Manager
echo -n "your-client-secret" | gcloud secrets create adobe-client-secret --data-file=-

# HashiCorp Vault
vault kv put secret/adobe/prod client_id="..." client_secret="..."

Step 2: Credential Rotation

Adobe OAuth Server-to-Server credentials support multiple client secrets simultaneously, enabling zero-downtime rotation:

# 1. In Adobe Developer Console, generate a NEW client_secret
#    (old secret remains valid)

# 2. Update your secret manager with the new secret
aws secretsmanager update-secret \
  --secret-id adobe/production/credentials \
  --secret-string '{"client_id":"...","client_secret":"NEW_SECRET"}'

# 3. Deploy application with new secret

# 4. Verify new secret works
curl -X POST 'https://ims-na1.adobelogin.com/ims/token/v3' \
  -d "client_id=${ADOBE_CLIENT_ID}&client_secret=${NEW_SECRET}&grant_type=client_credentials&scope=${ADOBE_SCOPES}"

# 5. Delete old client_secret in Developer Console

Step 3: Least-Privilege Scope Selection

// Per-environment scope restriction
const SCOPES_BY_ENV: Record<string, string> = {
  d

Adobe Upgrade & Migration

Overview

Guide for the most critical Adobe migrations: JWT to OAuth Server-to-Server, PDF Services SDK v3 to v4, Photoshop API v1 to v2 endpoints, and general SDK version upgrades.

Prerequisites

• Current Adobe SDK installed
• Git for version control
• Test suite covering Adobe integration points
• Staging environment for validation

Instructions

Migration 1: JWT to OAuth Server-to-Server (CRITICAL)

Deadline passed: JWT (Service Account) credentials reached EOL June 2025. If you are still using JWT, migrate immediately.

// BEFORE (JWT — no longer works)
import jwt from 'jsonwebtoken';
const jwtToken = jwt.sign({
  exp: Math.round(Date.now() / 1000) + 60 * 60 * 24,
  iss: orgId,
  sub: technicalAccountId,
  aud: `https://ims-na1.adobelogin.com/c/${clientId}`,
  'https://ims-na1.adobelogin.com/s/ent_firefly_sdk': true,
}, privateKey, { algorithm: 'RS256' });

// AFTER (OAuth Server-to-Server — current standard)
const tokenResponse = await fetch('https://ims-na1.adobelogin.com/ims/token/v3', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: process.env.ADOBE_CLIENT_ID!,
    client_secret: process.env.ADOBE_CLIENT_SECRET!,
    grant_type: 'client_credentials',
    scope: process.env.ADOBE_SCOPES!,
  }),
});

Migration steps:

1. In Developer Console, open your project
2. Click Add credential > OAuth Server-to-Server
3. Assign same product profiles as your JWT credential
4. Update application code to use client_credentials grant
5. Remove jsonwebtoken dependency and private key files
6. Test in staging
7. Deploy to production
8. Delete the old JWT credential in Developer Console

Migration 2: PDF Services SDK v3 to v4

# Check current version
npm list @adobe/pdfservices-node-sdk

# Upgrade
npm install @adobe/pdfservices-node-sdk@latest

Key breaking changes v3 -> v4:

// BEFORE (v3)
import PDFServicesSdk from '@adobe/pdfservices-node-sdk';
const credentials = PDFServicesSdk.Credentials
  .serviceAccountCredentialsBuilder()
  .fromFile('pdfservices-api-credentials.json')
  .build();
const executionContext = PDFServicesSdk.ExecutionContext.create(credentials);
const extractPDFOperation = PDFServicesSdk.ExtractPDF.Operation.createNew();

// AFTER (v4)
import {
  ServicePrincipalCredentials,
  PDFServices,
  ExtractPDFJob,
  ExtractPDFParams,
  ExtractElementType,
} from '@adobe/pdfservices-node-sdk';
const credentials = new ServicePrincipalCredentials({
  cl

Adobe Webhooks & Events

Overview

Implement Adobe I/O Events webhook endpoints with proper challenge-response handshake, RSA-SHA256 digital signature verification, and event routing for Creative Cloud Libraries, Experience Platform, and Firefly Services events.

Prerequisites

• Adobe Developer Console project with Events API enabled
• HTTPS endpoint accessible from the internet
• @adobe/aio-lib-events installed (optional, for SDK approach)
• Understanding of Adobe I/O Events architecture

Instructions

Step 1: Register Webhook via Adobe I/O Events API

// Register a webhook endpoint programmatically
import { getAccessToken } from '../adobe/client';

interface EventRegistration {
  name: string;
  description: string;
  webhookUrl: string;
  eventsOfInterest: Array<{
    provider_id: string;   // Event provider (e.g., Creative Cloud)
    event_code: string;    // Specific event type
  }>;
  deliveryType: 'webhook' | 'webhook_batch';
}

export async function registerWebhook(reg: EventRegistration): Promise<any> {
  const token = await getAccessToken();

  const response = await fetch(
    `https://api.adobe.io/events/${process.env.ADOBE_IMS_ORG_ID}/integrations/${process.env.ADOBE_INTEGRATION_ID}/registrations`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'x-api-key': process.env.ADOBE_CLIENT_ID!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        client_id: process.env.ADOBE_CLIENT_ID,
        name: reg.name,
        description: reg.description,
        webhook_url: reg.webhookUrl,
        events_of_interest: reg.eventsOfInterest,
        delivery_type: reg.deliveryType || 'webhook',
      }),
    }
  );

  if (!response.ok) throw new Error(`Registration failed: ${await response.text()}`);
  return response.json();
}

// Example: Register for Creative Cloud Library events
await registerWebhook({
  name: 'CC Library Updates',
  description: 'Track Creative Cloud Library changes',
  webhookUrl: 'https://api.yourapp.com/webhooks/adobe',
  eventsOfInterest: [
    { provider_id: 'ccstorage', event_code: 'library_create' },
    { provider_id: 'ccstorage', event_code: 'library_update' },
    { provider_id: 'ccstorage', event_code: 'library_delete' },
  ],
  deliveryType: 'webhook',
});

Step 2: Implement Challenge-Response Handshake

When registering a webhook, Adobe sends a GET request with a challenge query parameter. Your endpoint must respond with the challenge value:

import express from 'express';
const app = express();

app.get('/webhooks/adobe', (req, res) =>