Creating HTTP Clients

Overview

This skill documents how to create shared HTTP clients for Output SDK workflows. Clients are stored in src/shared/clients/ and shared across all workflows to ensure consistent error handling, retry logic, and API integration patterns.

When to Use This Skill

• Integrating a new external API service
• Creating a reusable HTTP wrapper for a service
• Standardizing error handling for API calls
• Moving inline HTTP logic to a shared client

Location Convention

HTTP clients are stored in the shared clients folder:

src/shared/clients/
├── gemini_client.ts     # Google Gemini API client
├── jina_client.ts       # Jina AI client
├── perplexity_client.ts # Perplexity API client
└── {service}_client.ts  # Your new client

Important: Clients are shared across ALL workflows. Do NOT create per-workflow HTTP clients.

Other Shared Code Locations

src/shared/
├── clients/     # API clients (this skill)
├── utils/       # Utility functions & helpers
├── services/    # Business logic services
├── steps/       # Shared step definitions (optional)
└── evaluators/  # Shared evaluators (optional)

Import Pattern in Workflows

Use relative imports from workflow files to shared clients:

// CORRECT - Relative path from workflow steps.ts
import { GeminiImageService } from '../../shared/clients/gemini_client.js';
import { parseResumeWithJina } from '../../shared/clients/jina_client.js';

// From shared steps (if used)
import { JinaClient } from '../clients/jina_client.js';

Critical Import Rules

HTTP Client Import

// CORRECT - Use @outputai/http wrapper
import { createKyClient } from '@outputai/http';

// WRONG - Never use axios directly
import axios from 'axios';

Error Types Import

// CORRECT - Import error types from @outputai/core
import { FatalError, ValidationError } from '@outputai/core';

// WRONG - Custom error classes
class MyCustomError extends Error { ... }

Credentials Import

// CORRECT - Use @outputai/credentials for secrets
import { credentials } from '@outputai/credentials';
const apiKey = credentials.require('service.api_key');

// WRONG - Never use process.env for secrets
const apiKey = process.env.SERVICE_API_KEY;

Cost Tracking Import

// CORRECT - Attach spend to paid API calls with @outputai/http
import { addRequestCost, createKyClient } from '@outputai/http';

// WRONG - Tracking cost yourself in a side table, or skipping it for paid APIs

Basic Client Structure

Simple Function-Based Client

import { FatalError, ValidationError } from '@outputai/core';
import { createKyClient } from '@outputai/http';
import { credentials } from '@outputai/credentials';

const API_KEY = credentials.require('service.api_key');
const BASE_URL = 'https://api.service.com';

const client = createKyClient({
  prefix: BASE_URL,
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    Accept: 'application/json'
  },
  timeout: 30000,
  retry: {
    limit: 3,
    statusCodes: [408, 429, 500, 502, 503, 504]
  }
});

/**
 * Fetch data from the service
 *
 * @param query - Search query string
 * @returns Processed response data
 * @throws {FatalError} If authentication fails or resource not found
 * @throws {ValidationError} If temporary error occurs
 */
export async function fetchServiceData(query: string): Promise<ServiceResponse> {
  const response = await client.get('endpoint', {
    searchParams: { q: query }
  });

  const data = await response.json();

  if (!data.results) {
    throw new FatalError('No results returned from service');
  }

  return data;
}

Class-Based Client

import { FatalError, ValidationError } from '@outputai/core';
import { createKyClient } from '@outputai/http';
import { credentials } from '@outputai/credentials';

export interface ServiceOptions {
  model?: string;
  timeout?: number;
}

export class ServiceClient {
  private readonly client: ReturnType<typeof createKyClient>;
  private readonly model: string;

  constructor(apiKey?: string) {
    const key = apiKey ?? credentials.require('service.api_key');

    this.client = createKyClient({
      prefix: 'https://api.service.com',
      headers: {
        Authorization: `Bearer ${key}`,
        'Content-Type': 'application/json'
      },
      timeout: 30000,
      retry: {
        limit: 3,
        statusCodes: [408, 429, 500, 502, 503, 504]
      }
    });

    this.model = 'default-model';
  }

  async process(input: ProcessInput): Promise<ProcessOutput> {
    try {
      const response = await this.client.post('process', {
        json: {
          model: this.model,
          input
        }
      });

      return await response.json();
    } catch (error: unknown) {
      const err = error as { status?: number; message?: string };

      if (err.status === 429) {
        throw new ValidationError(`Rate limit exceeded: ${err.message}`);
      }

      if (err.status === 401 || err.status === 403) {
        throw new FatalError(`Authentication failed: ${err.message}`);
      }

      throw new ValidationError(`Service call failed: ${err.message}`);
    }
  }
}

Real-World Examples

Example 1: Jina Client (Function-Based)

import { FatalError } from '@outputai/core';
import { createKyClient } from '@outputai/http';
import { credentials } from '@outputai/credentials';

const JINA_API_KEY = credentials.require('jina.api_key');
const JINA_BASE_URL = 'https://r.jina.ai';

const client = createKyClient({
  prefix: JINA_BASE_URL,
  headers: {
    Authorization: `Bearer ${JINA_API_KEY}`,
    Accept: 'application/json'
  },
  timeout: 30000,
  retry: {
    limit: 3,
    statusCodes: [408, 413, 429, 500, 502, 503, 504]
  }
});

/**
 * Parse PDF resume using Jina Reader API
 */
export async function parseResumeWithJina(base64Pdf: string): Promise<string> {
  const response = await client.post('', {
    json: { pdf: base64Pdf },
    headers: {
      'Content-Type': 'application/json'
    }
  });

  const data: {
    data: {
      content: string;
      title?: string;
    };
  } = await response.json();

  if (!data.data?.content) {
    throw new FatalError('No content returned from Jina PDF parser');
  }

  return data.data.content;
}

/**
 * Scrape text content from URL using Jina Reader
 */
export async function scrapeTextWithJina(url: string): Promise<string> {
  const response = await client.get(url, {
    headers: {
      'X-Return-Format': 'text',
      'X-No-Cache': 'true',
      'X-Timeout': '30'
    }
  });

  const data: {
    data: {
      text?: string;
      content?: string;
    };
  } = await response.json();

  const textContent = data.data?.text || data.data?.content;

  if (!textContent) {
    throw new FatalError(`No text content returned from URL: ${url}`);
  }

  return textContent;
}

Example 2: Gemini Client (Class-Based)

import { GoogleGenerativeAI } from '@google/generative-ai';
import { FatalError, ValidationError } from '@outputai/core';
import { credentials } from '@outputai/credentials';

export interface GeminiImageGenerationOptions {
  prompt: string;
  referenceImages?: Array<{
    inlineData: {
      mimeType: string;
      data: string;
    };
  }>;
  aspectRatio?: string;
  resolution?: string;
  numberOfImages?: number;
}

export class GeminiImageService {
  private readonly client: GoogleGenerativeAI;
  // current as of 2026-05-04 — run output-dev-model-selection for the latest
  private readonly model: string = 'gemini-3-pro-image';

  constructor(apiKey = credentials.require('google.api_key')) {
    if (!apiKey) {
      throw new FatalError(
        'GeminiImageService: No API Key provided (google.api_key credential).'
      );
    }
    this.client = new GoogleGenerativeAI(apiKey);
  }

  async generateImage(options: GeminiImageGenerationOptions): Promise<string[]> {
    const { prompt, referenceImages = [], aspectRatio = '1:1', resolution = '1K', numberOfImages = 1 } = options;

    try {
      const model = this.client.getGenerativeModel({ model: this.model });

      const parts: Array<{ text: string } | { inlineData: { mimeType: string; data: string } }> = [];

      if (referenceImages.length > 0) {
        referenceImages.forEach(img => parts.push(img));
      }

      const finalPrompt = `${prompt}\n\nGenerate this as a ${aspectRatio} aspect ratio image at ${resolution} resolution.`;
      parts.push({ text: finalPrompt });

      const result = await model.generateContent({
        contents: [{ role: 'user', parts }],
        generationConfig: {
          temperature: 1.0,
          topP: 0.95,
          candidateCount: numberOfImages,
          maxOutputTokens: 8192
        }
      });

      const images: string[] = [];
      const candidates = result.response.candidates || [];

      for (const candidate of candidates) {
        if (candidate.content?.parts) {
          for (const part of candidate.content.parts) {
            if (part.inlineData?.data) {
              images.push(part.inlineData.data);
            }
          }
        }
      }

      if (images.length === 0) {
        throw new ValidationError('No images were generated by Gemini');
      }

      return images;
    } catch (error: unknown) {
      const err = error as { status?: number; message?: string };

      if (err.status === 429) {
        throw new ValidationError(`Gemini rate limit exceeded: ${err.message}`);
      }

      if (err.status === 401 || err.status === 403) {
        throw new FatalError(`Gemini authentication failed: ${err.message}`);
      }

      throw new ValidationError(`Gemini image generation failed: ${err.message}`);
    }
  }
}

Error Handling Patterns

HTTP Status Code Handling

const RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
const FATAL_STATUS_CODES = [401, 403, 404];

const client = createKyClient({
  retry: {
    limit: 3,
    statusCodes: RETRY_STATUS_CODES
  },
  hooks: {
    beforeError: [
      ( { error } ) => {
        const status = error.response?.status;
        const message = error.message;

        if (status && FATAL_STATUS_CODES.includes(status)) {
          throw new FatalError(`HTTP ${status} error: ${message}`);
        }

        throw new ValidationError(`HTTP request failed: ${message}`);
      }
    ]
  }
});

Error Type Guidelines

Status Code	Error Type	Reason
401, 403	FatalError	Auth failures won't succeed on retry
404	FatalError	Resource doesn't exist
408	ValidationError	Timeout, may succeed on retry
429	ValidationError	Rate limit, will succeed after wait
500+	ValidationError	Server errors may be temporary

Attaching Request Cost (Paid APIs)

If the service a client wraps charges money per request, attach that cost to the request's trace so it shows up in npx output workflow cost (see output-dev-workflow-cost) and in any cost:http:request hook handlers (see output-dev-cost-hooks).

Do this on the client itself, in an afterResponse hook — not at each call site. That way every function or method that goes through the client is costed automatically, and nobody integrating with the client later has to remember to do it.

addRequestCost(response, totalUsd) only works on a response that came from outputFetch or createKyClient — including a response.clone() of one, so it's safe to call from inside an afterResponse hook (ky passes hooks a clone). If the response didn't originate from @outputai/http, addRequestCost no-ops with a console warning.

There are two common pricing shapes for paid third-party APIs:

Metered APIs (cost is in the response)

Some APIs report what a specific call cost — in a response header or a JSON field (credits used, units billed, etc). Read that field and pass it straight to addRequestCost. Guard against free or cached responses that legitimately report zero cost.

import { addRequestCost, createKyClient } from '@outputai/http';
import { credentials } from '@outputai/credentials';

const API_KEY = credentials.require('service.api_key');

const client = createKyClient({
  prefix: 'https://api.service.com',
  headers: { Authorization: `Bearer ${API_KEY}` },
  timeout: 30000,
  retry: { limit: 3, statusCodes: [408, 429, 500, 502, 503, 504] },
  hooks: {
    afterResponse: [
      async (_request, _options, response) => {
        // Errored responses (4xx/5xx) and retried attempts aren't billed the
        // same as a successful call — skip them rather than over-counting.
        if (!response.ok) {
          return;
        }

        try {
          const body = await response.clone().json() as { creditsUsed?: number; cached?: boolean };

          // Skip cached or free responses that legitimately cost nothing.
          if (body.cached || !body.creditsUsed) {
            return;
          }

          const usdPerCredit = 0.01;
          addRequestCost(response, body.creditsUsed * usdPerCredit);
        } catch {
          // Never let cost tracking break the request.
        }
      }
    ]
  }
});

Flat-rate / subscription APIs (assign a notional cost)

When a service is billed as a flat monthly fee or subscription tier, there's no true marginal cost per call — but recording some per-call figure keeps spend comparable across services in workflow cost and any cost dashboards. Assign a notional per-call USD rate as a constant, overridable by a non-secret environment variable so it can be tuned without a code change.

import { addRequestCost, createKyClient } from '@outputai/http';
import { credentials } from '@outputai/credentials';

const API_KEY = credentials.require('service.api_key');

// Notional per-call cost for a flat-rate subscription. Not a secret, so a
// plain env var is fine here — unlike API keys, which must go through
// @outputai/credentials.
const NOTIONAL_COST_USD = Number(process.env.SERVICE_NOTIONAL_COST_USD ?? 0.005);

const client = createKyClient({
  prefix: 'https://api.service.com',
  headers: { Authorization: `Bearer ${API_KEY}` },
  timeout: 30000,
  retry: { limit: 3, statusCodes: [408, 429, 500, 502, 503, 504] },
  hooks: {
    afterResponse: [
      (_request, _options, response) => {
        // Errored responses (4xx/5xx) and retried attempts aren't billed the
        // same as a successful call — skip them rather than over-counting.
        if (!response.ok) {
          return;
        }

        addRequestCost(response, NOTIONAL_COST_USD);
      }
    ]
  }
});

The constant above is a placeholder — config/costs.yml (see output-dev-workflow-cost) can override the actual dollar figure per service afterward, without another code change. Add a services.<name> entry with type: request, a matching url_pattern, and an endpoints.<name> block giving pattern + price for the call. (default_price only applies inside a models/model_path entry, for picking a fallback price when the request's model isn't in models — it does nothing paired with a bare url_pattern.) Prefer that file over inventing more env vars once you have more than one or two notional rates to tune.

Rules:

• Never throw from an afterResponse cost hook — a throw there fails the request itself. Wrap body parsing in try/catch and silently skip on parse failure.
• The hook fires once per attempt, including retries — skip !response.ok attempts unless you know the API bills failed requests too (the framework itself does count a recorded cost event "regardless of HTTP status" once one exists — the event is proof of a charge). When in doubt, check the provider's billing docs before adding the guard.
• Only do this for paid third-party APIs. Free or internal services don't need it.
• Skip this pattern for LLM providers — those costs are computed automatically from token usage via llm:generation:metering. addRequestCost is for non-LLM HTTP calls only.
• To consume these costs elsewhere (forward to your own observability system, log them, alert on them), see output-dev-cost-hooks.

Best Practices

1. Use Credentials for API Keys

Prefer @outputai/credentials over process.env for secrets management. See output-dev-credentials skill for details.

import { credentials } from '@outputai/credentials';

// credentials.require() throws MissingCredentialError if not found
const apiKey = credentials.require('service.api_key');

// credentials.get() returns undefined or default if not found
const region = credentials.get('aws.region', 'us-east-1');

2. Document Functions with JSDoc

/**
 * Fetch user profile from external service
 *
 * @param userId - Unique user identifier
 * @returns User profile data
 * @throws {FatalError} If user not found or auth fails
 * @throws {ValidationError} If temporary error occurs
 *
 * @example
 * const profile = await fetchUserProfile('user-123');
 */
export async function fetchUserProfile(userId: string): Promise<UserProfile> {
  // ...
}

3. Use Consistent Timeouts

// Standard timeout: 30 seconds
timeout: 30000

// Long-running operations: 60 seconds
timeout: 60000

4. Consume or Cancel Response Bodies

createKyClient follows Fetch response-body semantics: callers own returned response bodies. Prefer body readers like .json() or .text() when the payload is needed. If a request only reads metadata such as response.url, response.status, or headers, cancel the unused body in a finally block.

const response = await client.get( url );

try {
  return response.url;
} finally {
  await response.body?.cancel();
}

HEAD requests do not have response bodies, so this is only needed for methods that can return one.

5. Export TypeScript Interfaces

// Export interfaces for consumers
export interface ServiceResponse {
  data: {
    id: string;
    content: string;
  };
  metadata: {
    processedAt: string;
  };
}

Verification Checklist

• [ ] Client file located in src/shared/clients/ directory
• [ ] File named {service}_client.ts
• [ ] createKyClient imported from @outputai/http (not axios)
• [ ] FatalError and ValidationError imported from @outputai/core
• [ ] API key validation in constructor/initialization
• [ ] Retry configuration for appropriate status codes
• [ ] FatalError used for 401, 403, 404 responses
• [ ] ValidationError used for 429, 5xx responses
• [ ] Non-HEAD responses are consumed or cancelled when only metadata is used
• [ ] JSDoc documentation for exported functions
• [ ] TypeScript interfaces exported for response types
• [ ] Paid third-party API calls attach cost via addRequestCost in an afterResponse hook

Related Skills

• output-dev-step-function - Using clients in step functions
• output-dev-evaluator-function - Using clients in evaluators
• output-dev-folder-structure - Understanding project layout
• output-dev-credentials - Encrypted secrets management
• output-dev-cost-hooks - Subscribing to cost events (cost:http:request, llm:generation:metering) for observability
• output-error-http-client - Troubleshooting HTTP issues
• output-error-try-catch - Proper error handling patterns