NameGraph SDK

A TypeScript SDK for interacting with the NameGraph APIs, providing access to the world's largest collection of names. This SDK enables easy integration with the NameGraph API endpoints for name and collection suggestions.

Installation

npm install namegraph-sdk
# or
yarn add namegraph-sdk

Quick Start

import { createNameGraphClient } from "namegraph-sdk";

// Create a client instance
const client = createNameGraphClient();

// Or use the default client
import { namegraph } from "namegraph-sdk";

// Get name suggestions grouped by category
const suggestions = await namegraph.groupedByCategory("zeus");

Features

• Category-based Suggestions: Get name suggestions organized by various categories including related terms, wordplay, alternates, and more
• Collection Management: Find, count, and analyze collections of names
• Smart Sampling: Sample and fetch top members from collections
• Advanced Search: Search collections by string or by collection ID

API Reference

Client Configuration

const client = createNameGraphClient({
  namegraphEndpoint: "https://custom-api.endpoint.com", // Optional, defaults to https://api.namegraph.dev/
});

Core Methods

Group Names by Category

const response = await client.groupedByCategory("zeus");

Get Suggestions by Category

const suggestions = await client.suggestionsByCategory("zeus");

Sample Collection Members

const members = await client.sampleCollectionMembers("collection_id");

Fetch Top Collection Members

const topMembers = await client.fetchTopCollectionMembers("collection_id");

Find Collections

// By string
const collections = await client.findCollectionsByString("zeus god");

// By collection ID
const related = await client.findCollectionsByCollection("collection_id");

// By member
const memberCollections = await client.findCollectionsByMember("zeus");

Count Collections

// By string
const stringCount = await client.countCollectionsByString("zeus god");

// By member
const memberCount = await client.countCollectionsByMember("zeus");

Response Types

The SDK provides TypeScript types for all API responses. Key types include:

• NameGraphSuggestion
• NameGraphCategory
• NameGraphCollection
• NameGraphGroupedByCategoryResponse
• NameGraphFetchTopCollectionMembersResponse
• NameGraphCountCollectionsResponse

Error Handling

The SDK throws NameGraphError for API-related errors. Handle them appropriately:

try {
  const suggestions = await client.groupedByCategory("example");
} catch (error) {
  if (error instanceof NameGraphError) {
    console.error(`API Error ${error.status}: ${error.message}`);
  }
}

Request Cancellation

Cancel ongoing requests using the abortAllRequests method:

client.abortAllRequests();

Categories

The SDK supports various grouping categories for name suggestions:

• related: Related terms and concepts
• wordplay: Creative word variations
• alternates: Alternative versions
• emojify: Emoji-enhanced variations
• community: Community-suggested names
• expand: Expanded versions
• gowild: Creative variations
• other: Additional suggestions