Popsicle User Agent Middleware

Common errors

• Cannot find module 'servie' or its corresponding type declarations.

  cause `servie` is a peer dependency of `popsicle-user-agent` and is required for the middleware composition (e.g., the `compose` function), but it has not been installed in your project.
  fix Install the `servie` package: `npm install servie`.

• TypeError: (0 , servie_1.compose) is not a function

  cause This typically occurs in a CommonJS environment or when bundlers struggle with ESM exports if `servie` is imported incorrectly. The `compose` function is a named export from `servie`.
  fix Ensure `servie` is imported correctly as `import { compose } from 'servie';` for ESM, or `const { compose } = require('servie');` for CommonJS, and that your build setup supports these imports.

Warnings

• breaking The `User-Agent` header setting functionality was extracted from the core `popsicle` library into this dedicated `popsicle-user-agent` package. Users upgrading `popsicle` who previously relied on this built-in behavior will find it missing.
  Fix: Install `popsicle-user-agent` (`npm install popsicle-user-agent`) and explicitly add `userAgent()` to your `popsicle` middleware composition chain.

Install

• npm install popsicle-user-agent npm
• yarn add popsicle-user-agent yarn
• pnpm add popsicle-user-agent pnpm

Imports

• userAgent
  wrong:

  const userAgent = require('popsicle-user-agent').userAgent;

  correct:

  import { userAgent } from 'popsicle-user-agent';

  The library primarily uses named ESM exports. While CommonJS `require` works, the TypeScript definitions and modern usage favor ESM.

Quickstart

This quickstart demonstrates how to apply the `userAgent` middleware to a `Popsicle` middleware stack, showing both the default and a custom User-Agent string being set on outgoing requests before they reach a mock transport layer.

import { userAgent } from 'popsicle-user-agent';
import { compose } from 'servie'; // 'servie' is the peer dep and typically provides 'compose'

// Mock transport function for demonstration.
// In a real application, you would typically import a transport like 'popsicle-transport-http'
// and use it with the actual 'popsicle' client.
const mockTransport = () => async (req: Request): Promise<Response> => {
  console.log(`[Mock Transport] Sending request to: ${req.url}`);
  console.log(`[Mock Transport] User-Agent header: ${req.headers.get('User-Agent')}`);
  // Simulate network delay and return a simple response
  await new Promise(resolve => setTimeout(resolve, 50));
  return new Response('{"message": "Request processed"}', {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
};

async function runExample() {
  // 1. Create a middleware stack with the default User-Agent
  const defaultStack = compose([
    userAgent(), // Defaults to "Popsicle"
    mockTransport()
  ]);

  console.log('--- Request with default User-Agent ---');
  const defaultRequest = new Request('https://api.example.com/data');
  await defaultStack(defaultRequest);

  // 2. Create a middleware stack with a custom User-Agent
  const customStack = compose([
    userAgent('MyAwesomeApp/1.2.3 (Node.js)'),
    mockTransport()
  ]);

  console.log('\n--- Request with custom User-Agent ---');
  const customRequest = new Request('https://api.example.com/status');
  await customStack(customRequest);

  // To integrate with an actual popsicle client (conceptual):
  // import * as popsicle from 'popsicle';
  // const client = popsicle.create({ baseUrl: 'https://api.example.com' }).use(customStack);
  // const response = await client.get('/some-path');
  // console.log('Actual Popsicle Client Response Status:', response.status);
}

runExample().catch(console.error);