Utilities Reference

Reference for the non-component exports exposed by astro-gravatar.

URL and Profile Helpers

buildAvatarUrl

Build a Gravatar avatar URL from an email address.

import { buildAvatarUrl } from 'astro-gravatar';

const url = await buildAvatarUrl('user@example.com', {
  size: 200,
  rating: 'pg',
  default: 'identicon',
  forceDefault: true,
});

Options

Option	Type	Default	Description
size	number	80	Avatar size in pixels (1-2048)
rating	'g' | 'pg' | 'r' | 'x'	'g'	Maximum rating level
default	DefaultAvatar	'mp'	Default avatar type or custom URL
forceDefault	boolean	false	Force the default image even when a real avatar exists

Returns

• Promise<string>: Complete avatar URL

buildProfileUrl

Build the Gravatar API profile endpoint URL for an email address.

import { buildProfileUrl } from 'astro-gravatar';

const url = await buildProfileUrl('user@example.com', {
  baseUrl: 'https://api.gravatar.com/v3',
});

Options

Option	Type	Default	Description
baseUrl	string	https://api.gravatar.com/v3	Override the profile API base URL

buildQRCodeUrl

Build a Gravatar QR code URL from an email address.

import { buildQRCodeUrl } from 'astro-gravatar';

const url = await buildQRCodeUrl('user@example.com', {
  size: 160,
  version: 3,
  type: 'gravatar',
  utmMedium: 'docs',
  utmCampaign: 'launch',
});

Options

Option	Type	Default	Description
size	number	80	QR code size in pixels (1-1000)
version	1 | 3	1	QR style version
type	'user' | 'gravatar' | 'none'	'none'	Center icon
utmMedium	string	undefined	utm_medium query value
utmCampaign	string	undefined	utm_campaign query value

getProfile

Fetch a single Gravatar profile.

import { getProfile } from 'astro-gravatar';

const profile = await getProfile('user@example.com', {
  apiKey: import.meta.env.GRAVATAR_API_KEY,
});

Options

Option	Type	Default	Description
apiKey	string	undefined	Bearer token for richer profile access
baseUrl	string	https://api.gravatar.com/v3	Override API base URL
timeout	number	10000	Request timeout in milliseconds
headers	Record<string, string>	undefined	Extra request headers

Returns

• Promise<GravatarProfile>: Parsed profile payload

getProfiles

Fetch multiple profiles in parallel.

import { getProfiles } from 'astro-gravatar';

const profiles = await getProfiles(['alice@example.com', 'bob@example.com'], {
  apiKey: import.meta.env.GRAVATAR_API_KEY,
});

Returns

• Promise<GravatarProfile[]>: Array of successful profile results. Failed lookups are skipped unless every lookup fails, in which case the first GravatarError is re-thrown.

validateAvatarParams

Validate avatar sizing and rating before rendering or URL generation.

import { validateAvatarParams } from 'astro-gravatar';

validateAvatarParams(128, 'pg');

Throws GravatarError when the size or rating is invalid.

getDefaultAvatarConfig

Read the package’s default avatar settings.

import { getDefaultAvatarConfig } from 'astro-gravatar';

const defaults = getDefaultAvatarConfig();
// { size: 80, rating: 'g', default: 'mp', forceDefault: false }

Email and Hash Helpers

hashEmail

Hash an email address with SHA256 for Gravatar usage.

import { hashEmail } from 'astro-gravatar';

const hash = await hashEmail('user@example.com');

hashEmails

Hash multiple email addresses in one call.

import { hashEmails } from 'astro-gravatar';

const hashes = await hashEmails(['alice@example.com', 'bob@example.com']);

isValidEmail

Validate email syntax before attempting a request.

import { isValidEmail } from 'astro-gravatar';

if (isValidEmail('user@example.com')) {
  console.log('Looks valid');
}

normalizeEmail

Trim and lowercase an email address using the same normalization rules the package uses internally.

import { normalizeEmail } from 'astro-gravatar';

const normalized = normalizeEmail(' User@Example.com ');
// "user@example.com"

extractHash

Accept a Gravatar hash, a Gravatar profile URL, or an email address and resolve it to a SHA256 hash.

import { extractHash } from 'astro-gravatar';

const hashA = await extractHash('user@example.com');
const hashB = await extractHash(
  'https://gravatar.com/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109',
);

hashEmailWithCache

Hash an email address with the built-in in-memory cache enabled by default.

import { hashEmailWithCache } from 'astro-gravatar';

const hash = await hashEmailWithCache('user@example.com');

Pass false as the second argument to bypass the cache.

clearEmailHashCache

Clear the email hash cache.

import { clearEmailHashCache } from 'astro-gravatar';

clearEmailHashCache();

getEmailHashCacheStats

Inspect email hash cache size and limits.

import { getEmailHashCacheStats } from 'astro-gravatar';

const stats = getEmailHashCacheStats();
// { size, maxSize, ttl }

Client, Cache, and Errors

clearApiCache

Clear the simple in-memory API cache used by the top-level profile helpers.

import { clearApiCache } from 'astro-gravatar';

clearApiCache();

getApiCacheStats

Read API cache statistics for the top-level helpers.

import { getApiCacheStats } from 'astro-gravatar';

const stats = getApiCacheStats();
console.log(stats.size);
console.log(stats.entries);

The top-level helper cache reports its current size and entry expiration metadata.

GravatarClient

Use GravatarClient when you need advanced retry, cache, header, or rate-limit control beyond the top-level helpers.

import { GravatarClient } from 'astro-gravatar';

const client = new GravatarClient({
  apiKey: import.meta.env.GRAVATAR_API_KEY,
  timeout: 15000,
  cache: {
    enabled: true,
    ttl: 300,
    maxSize: 1000,
  },
});

const profile = await client.getProfile('user@example.com');

Common methods:

• client.getProfile(email, options?)
• client.getProfiles(emails, options?)
• client.clearCache()
• client.getCacheStats()
• client.getRequestStats()

GravatarError

GravatarError is thrown for invalid input, request failures, and API errors.

import { getProfile, GravatarError, GRAVATAR_ERROR_CODES } from 'astro-gravatar';

try {
  await getProfile('user@example.com');
} catch (error) {
  if (
    error instanceof GravatarError &&
    error.code === GRAVATAR_ERROR_CODES.RATE_LIMITED
  ) {
    console.log('Retry later', error.rateLimit);
  }
}

Available properties:

• message
• code
• status
• rateLimit

GRAVATAR_ERROR_CODES

The exported error code map is useful when you want stable comparisons instead of raw strings.

import { GRAVATAR_ERROR_CODES } from 'astro-gravatar';

console.log(GRAVATAR_ERROR_CODES.RATE_LIMITED);

Exported Constants

These constants are part of the public package surface:

Constant	Value
GRAVATAR_AVATAR_BASE	https://0.gravatar.com/avatar
GRAVATAR_API_BASE	https://api.gravatar.com/v3
GRAVATAR_QR_BASE	https://api.gravatar.com/v3/qr-code
DEFAULT_AVATAR_SIZE	80
DEFAULT_AVATAR_RATING	'g'
DEFAULT_AVATAR_IMAGE	'mp'
DEFAULT_TIMEOUT	10000

Type Notes

Representative public types from astro-gravatar/types:

interface VerifiedAccount {
  service_type: string;
  service_label: string;
  service_icon: string;
  url: string;
  is_hidden: boolean;
}

interface Link {
  label: string;
  url: string;
}

interface GravatarProfile {
  hash: string;
  profile_url: string;
  avatar_url: string;
  avatar_alt_text: string;
  display_name: string;
  verified_accounts?: VerifiedAccount[];
  links?: Link[];
  is_organization?: boolean;
  background_color?: string;
  number_verified_accounts?: number;
}

For the full exported type surface, import from:

import type { GravatarProfile, GravatarAvatarProps } from 'astro-gravatar';
import type { VerifiedAccount } from 'astro-gravatar/types';

CLI

The package also ships a CLI for offline URL generation. See the CLI guide for command usage and examples.

Next Steps

• Component Reference for component props and rendering patterns
• Authentication Guide for API key usage
• CLI Guide for command-line URL generation
• Performance Guide for cache and batching strategies