CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-aws-sdk--util-user-agent-node

An internal AWS SDK utility for generating Node.js user agent strings with runtime environment information

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@aws-sdk/util-user-agent-node

An internal AWS SDK utility for generating Node.js user agent strings with runtime environment information.

Package Information

  • Name: @aws-sdk/util-user-agent-node
  • Type: Node.js TypeScript utility library
  • Language: TypeScript
  • Installation: npm install @aws-sdk/util-user-agent-node

Core Imports

// ESM import
import { 
  createDefaultUserAgentProvider,
  defaultUserAgent,
  crtAvailability,
  DefaultUserAgentOptions,
  PreviouslyResolved,
  UA_APP_ID_ENV_NAME,
  UA_APP_ID_INI_NAME,
  NODE_APP_ID_CONFIG_OPTIONS
} from "@aws-sdk/util-user-agent-node";

// CommonJS import
const { 
  createDefaultUserAgentProvider,
  defaultUserAgent,
  crtAvailability,
  DefaultUserAgentOptions,
  PreviouslyResolved,
  UA_APP_ID_ENV_NAME,
  UA_APP_ID_INI_NAME,
  NODE_APP_ID_CONFIG_OPTIONS
} = require("@aws-sdk/util-user-agent-node");

Basic Usage

import { createDefaultUserAgentProvider } from "@aws-sdk/util-user-agent-node";

// Create a user agent provider for a specific AWS service
const userAgentProvider = createDefaultUserAgentProvider({
  serviceId: "s3",
  clientVersion: "3.879.0"
});

// Generate user agent with optional app ID configuration
const userAgent = await userAgentProvider({
  userAgentAppId: async () => "my-application-id"
});
// Returns: [["aws-sdk-js", "3.879.0"], ["ua", "2.1"], ["os/linux", "5.4.0"], ...]

User Agent Provider

The primary functionality for creating user agent strings with runtime metadata.

function createDefaultUserAgentProvider(options: DefaultUserAgentOptions): (config?: PreviouslyResolved) => Promise<UserAgent>;

interface DefaultUserAgentOptions {
  serviceId?: string;
  clientVersion: string;
}

interface PreviouslyResolved {
  userAgentAppId: Provider<string | undefined>;
}

Usage Examples

Basic service user agent:

const provider = createDefaultUserAgentProvider({
  serviceId: "dynamodb",
  clientVersion: "3.879.0"
});

const userAgent = await provider();
// Generates: [["aws-sdk-js", "3.879.0"], ["ua", "2.1"], ["os/darwin", "22.1.0"], ["lang/js"], ["md/nodejs", "18.19.0"], ["api/dynamodb", "3.879.0"]]

With application ID:

const provider = createDefaultUserAgentProvider({
  serviceId: "s3",
  clientVersion: "3.879.0"
});

const userAgent = await provider({
  userAgentAppId: async () => "my-app-v1.0"
});
// Adds: ["app/my-app-v1.0"] to the user agent array

Without service ID (generic client):

const provider = createDefaultUserAgentProvider({
  clientVersion: "3.879.0"
});

const userAgent = await provider();
// Excludes the ["api/{serviceId}", clientVersion] section

Generated User Agent Structure

The user agent is returned as an array of string pairs (UserAgent type from @smithy/types):

  • ["aws-sdk-js", clientVersion] - SDK identification
  • ["ua", "2.1"] - User agent version
  • ["os/{platform}", release] - Operating system info (e.g., ["os/linux", "5.4.0"])
  • ["lang/js"] - Language identification
  • ["md/nodejs", nodeVersion] - Runtime metadata
  • ["md/crt-avail"] - Added if AWS CRT is available
  • ["api/{serviceId}", clientVersion] - Service API (if serviceId provided)
  • ["exec-env/{AWS_EXECUTION_ENV}"] - Execution environment (if env var set)
  • ["app/{appId}"] - Application ID (if provided via config)

CRT Availability Detection

Utilities for detecting AWS Common Runtime (CRT) availability.

const crtAvailability: {
  isCrtAvailable: boolean;
};

CRT Availability Object:

import { crtAvailability } from "@aws-sdk/util-user-agent-node";

// Check if CRT is available
if (crtAvailability.isCrtAvailable) {
  console.log("AWS CRT is available");
}

// This object is mutated by aws-crt package when loaded
// Default value: { isCrtAvailable: false }

Configuration Options

Constants and configuration selectors for user agent app ID loading.

const UA_APP_ID_ENV_NAME: string;
const UA_APP_ID_INI_NAME: string;
const NODE_APP_ID_CONFIG_OPTIONS: LoadedConfigSelectors<string | undefined>;

Environment Variable Names

import { UA_APP_ID_ENV_NAME, UA_APP_ID_INI_NAME } from "@aws-sdk/util-user-agent-node";

console.log(UA_APP_ID_ENV_NAME); // "AWS_SDK_UA_APP_ID"
console.log(UA_APP_ID_INI_NAME);  // "sdk_ua_app_id"

Configuration Selectors

import { NODE_APP_ID_CONFIG_OPTIONS } from "@aws-sdk/util-user-agent-node";

// Used internally by AWS SDK for loading app ID from:
// 1. Environment variable: AWS_SDK_UA_APP_ID
// 2. INI config file: sdk_ua_app_id (or deprecated sdk-ua-app-id)
// 3. Default fallback value

// The configuration object provides standardized loading behavior
// for the @smithy/node-config-provider system

Deprecated API

function defaultUserAgent(options: DefaultUserAgentOptions): (config?: PreviouslyResolved) => Promise<UserAgent>;

Deprecated alias:

import { defaultUserAgent } from "@aws-sdk/util-user-agent-node";

// ⚠️ Deprecated - use createDefaultUserAgentProvider instead
const provider = defaultUserAgent({
  serviceId: "s3",
  clientVersion: "3.879.0"
});

Type Dependencies

Required external types from dependencies:

// From @smithy/types
type UserAgent = UserAgentPair[];
type UserAgentPair = [string, string];
type Provider<T> = () => Promise<T> | T;

// From @smithy/node-config-provider  
interface LoadedConfigSelectors<T> {
  environmentVariableSelector: (env: NodeJS.ProcessEnv) => T | undefined;
  configFileSelector: (profile: any) => T | undefined;
  default: T;
}

Runtime Requirements

  • Node.js: >= 18.0.0
  • Peer Dependency: aws-crt (optional) - When installed, enables CRT availability detection
  • Environment Variables:
    • AWS_SDK_UA_APP_ID - Optional application identifier
    • AWS_EXECUTION_ENV - Optional execution environment identifier

Internal Usage Notes

This package is designed for internal AWS SDK usage. All exports are marked @internal in the source code, indicating they are not intended for direct external consumption. The package automatically collects runtime metadata including:

  • Operating system and version
  • Node.js runtime version
  • AWS execution environment detection
  • CRT availability status
  • Application and service identification

docs

index.md

tile.json