@hydrafetch/client-sdk

Company logo URLs for the browser, built from a Hydrafetch publishable key.

614 bytes gzipped, zero dependencies, no network calls. Logos bill against logo pulls, not credits.

Installation

npm install @hydrafetch/client-sdk

Quick start

import { createLogoClient } from '@hydrafetch/client-sdk';

const logos = createLogoClient('hf_pk_your_publishable_key');

document.querySelector('img')!.src = logos.url('stripe.com', { size: 64, theme: 'dark' });

Create a publishable key in your dashboard and restrict it to your domains.

Using React? @hydrafetch/react adds a provider and a <Logo> component on top of this package.

How it works

The logo endpoint returns image bytes, so there is nothing to fetch and nothing to await. This package builds a URL:

https://img.hydrafetch.com/logo/stripe.com?token=hf_pk_...&theme=dark&size=64

The browser sends Origin and Referer with the image request, which is how the domain restriction on your key is enforced.

Usage

createLogoClient(publishableKey, options?)

const logos = createLogoClient('hf_pk_...');

logos.url('stripe.com');
logos.url('stripe.com', { theme: 'dark', size: 64 });
logos.img('stripe.com', { size: 32 });

| Option | Values | Default | | --- | --- | --- | | theme | light, dark, auto | server default | | type | icon, wordmark | icon | | size | pixels, up to 512 | native | | fallback | monogram, 404, transparent | monogram |

fallback controls what a domain with no known logo returns: a generated monogram, a real 404, or a transparent pixel.

logos.img(domain, options?)

Returns props for an image element, including a retina srcSet when a size is given.

<img {...logos.img('stripe.com', { size: 32 })} />

{
  src: 'https://img.hydrafetch.com/logo/stripe.com?token=…&size=32',
  srcSet: '…size=32 1x, …size=64 2x',
  alt: 'stripe.com logo',
  width: 32,
  height: 32,
  loading: 'lazy',
  decoding: 'async',
  referrerPolicy: 'strict-origin-when-cross-origin',
}

logoUrl(domain, publishableKey, options?)

The same builder without a client, for one-off calls.

toDomain(input)

Normalises user input to a bare domain. https://www.stripe.com/pricing?a=1 becomes stripe.com. Applied automatically by every method.

Framework usage

// React, Preact
<img {...logos.img(domain, { size: 24 })} />

<!-- Vue -->
<img v-bind="logos.img(domain, { size: 24 })" />

<!-- Svelte -->
<img {...logos.img(domain, { size: 24 })} />

Publishable keys

A publishable key (hf_pk_…) is an identifier rather than a credential. It is designed to appear in page source and is restricted to the domains you list, so a copy is unusable elsewhere.

createLogoClient throws on any key that does not begin with hf_pk_, which prevents a secret key reaching a browser bundle.

Billing

Logos are metered against logoPullsPerCycle on your plan and never draw on your credit balance, so rendering logos on every page view does not consume the budget used for scraping.

Server-side use

This package covers logo URLs only. For a company's full brand record, or any other endpoint, use a server client with a secret key:

Node · Python · Go · Ruby · Rust · PHP

Links

• Documentation
• OpenAPI specification

License

MIT