@power-seo/integrations

@power-seo/integrations

Query keyword data, domain overviews, backlinks, and keyword difficulty from Semrush and Ahrefs APIs with a shared HTTP client that handles rate limiting and pagination automatically.

@power-seo/integrations wraps the Semrush and Ahrefs REST APIs with a consistent TypeScript interface. Both clients are built on a shared createHttpClient() base that enforces configurable rate limits (requests per window), handles pagination automatically, and normalizes errors into IntegrationApiError with status codes and messages. Import only the client you need — tree-shaking ensures unused API code never ends up in your bundle.

Zero runtime dependencies beyond fetch — runs in Node.js 18+, Deno, Bun, and modern edge runtimes.

⚠️ Network Access — This package makes HTTPS requests to Semrush and Ahrefs APIs. Network access is functionally required and intentional. All requests use your API credentials and are sent only to the configured service endpoints.

Why @power-seo/integrations?

	Without	With
Semrush API	❌ Write raw HTTP client	✅ Typed client with auto-pagination
Ahrefs API	❌ Manual SDK setup	✅ Typed client with rate limiting
Rate limiting	❌ Manual throttle	✅ Built-in configurable window rate limiter
Pagination	❌ Manual offset tracking	✅ Automatic — receive a flat result array
Error handling	❌ Raw HTTP errors	✅ IntegrationApiError with status, provider, retryable
TypeScript types	❌ any everywhere	✅ Full type coverage for all endpoints
Bundle size	❌ Full SDK in bundle	✅ Tree-shakeable — import only what you use

Features

• Semrush API client — domain overview (traffic, organic/paid keywords, backlinks), keyword data (volume, CPC, competition), backlink profile, keyword difficulty, and related keyword suggestions
• Ahrefs API client — site overview (Domain Rating, organic traffic), organic keywords with positions, backlink data with anchor text, keyword difficulty, and referring domain list
• Shared HTTP client — createHttpClient() provides configurable rate limiting (max requests per time window), automatic retry on 429, and JSON response parsing
• Auto-pagination — both clients handle multi-page results automatically; callers receive a flat array without manual offset tracking
• Full TypeScript types — every request parameter and response field is typed; no any in your code
• Consistent error handling — IntegrationApiError with status, provider, message, and retryable flag from both APIs
• Tree-shakeable — createSemrushClient and createAhrefsClient are separate exports; import only what you use

Comparison

Feature	@power-seo/integrations	semrush-sdk	ahrefs-client	Custom fetch
Semrush API client	✅	✅	❌	Manual
Ahrefs API client	✅	❌	Partial	Manual
Rate limiting	✅	Partial	❌	Manual
Auto-pagination	✅	❌	❌	Manual
Shared HTTP client	✅	❌	❌	—
Consistent error handling	✅	Partial	❌	Manual
TypeScript-first	✅	❌	❌	—
Tree-shakeable	✅	❌	❌	—

Installation

npm install @power-seo/integrations

yarn add @power-seo/integrations

pnpm add @power-seo/integrations

Quick Start

import { createSemrushClient, createAhrefsClient } from '@power-seo/integrations';

// Semrush
const semrush = createSemrushClient({ apiKey: process.env.SEMRUSH_API_KEY! });
const overview = await semrush.getDomainOverview({ domain: 'example.com' });
console.log(overview.organicTraffic); // 12_400
console.log(overview.organicKeywords); // 834

// Ahrefs
const ahrefs = createAhrefsClient({ apiKey: process.env.AHREFS_API_KEY! });
const site = await ahrefs.getSiteOverview({ target: 'example.com' });
console.log(site.domainRating); // 47
console.log(site.organicTraffic); // 9_800

Usage

Semrush Client

import { createSemrushClient } from '@power-seo/integrations';
import type { SemrushDomainOverview, SemrushKeywordData } from '@power-seo/integrations';

const semrush = createSemrushClient(
  process.env.SEMRUSH_API_KEY!,
  { rateLimitPerMinute: 10, maxRetries: 3 }, // optional
);

// Domain overview — traffic, keywords, backlinks
const overview: SemrushDomainOverview = await semrush.getDomainOverview('example.com', 'us');
// { domain, organicTraffic, paidTraffic, organicKeywords, paidKeywords, backlinks, authorityScore }

// Organic keywords
const keywords = await semrush.getOrganicKeywords('example.com', { limit: 100, offset: 0 });
// { data: SemrushKeywordData[], total, offset, limit, hasMore }

// Backlinks
const backlinks = await semrush.getBacklinks('example.com', { limit: 100, offset: 0 });
// { data: SemrushBacklinkData[], total, offset, limit, hasMore }

// Keyword difficulty
const difficulty = await semrush.getKeywordDifficulty(['react seo'], 'us');
// [{ keyword, difficulty, searchVolume, cpc, competition, results }]

// Related keywords
const related = await semrush.getRelatedKeywords('react seo', 'us');
// [{ keyword, searchVolume, cpc, competition, results, relatedTo }]

Ahrefs Client

import { createAhrefsClient } from '@power-seo/integrations';
import type { AhrefsSiteOverview, AhrefsOrganicKeyword } from '@power-seo/integrations';

const ahrefs = createAhrefsClient(
  process.env.AHREFS_API_TOKEN!,
  { rateLimitPerMinute: 5, maxRetries: 3 }, // optional
);

// Site overview — DR, organic traffic, backlinks
const overview: AhrefsSiteOverview = await ahrefs.getSiteOverview('example.com');
// { domain, domainRating, urlRating, organicTraffic, organicKeywords, backlinks, referringDomains, trafficValue }

// Organic keywords with positions
const keywords = await ahrefs.getOrganicKeywords('example.com', { limit: 200, offset: 0 });
// { data: AhrefsOrganicKeyword[], total, offset, limit, hasMore }

// Backlinks with anchor text
const backlinks = await ahrefs.getBacklinks('example.com', { limit: 100, offset: 0 });
// { data: AhrefsBacklink[], total, offset, limit, hasMore }

// Keyword difficulty
const kd = await ahrefs.getKeywordDifficulty(['react seo']);
// [{ keyword, difficulty, searchVolume, cpc, clicks, globalVolume }]

// Referring domains
const domains = await ahrefs.getReferringDomains('example.com', { limit: 50, offset: 0 });
// { data: AhrefsReferringDomain[], total, offset, limit, hasMore }

Shared HTTP Client

Use the underlying HTTP client directly to call any REST API with rate limiting and pagination:

import { createHttpClient } from '@power-seo/integrations';

const http = createHttpClient({
  baseUrl: 'https://api.example.com',
  auth: { type: 'bearer', token },
  rateLimitPerMinute: 60, // max requests per minute
  maxRetries: 3,
  timeoutMs: 30_000,
});

const data = await http.get<MyResponseType>('/endpoint', { query: 'param' });

Error Handling

Both clients throw IntegrationApiError for non-2xx responses:

import { createSemrushClient, IntegrationApiError } from '@power-seo/integrations';

const semrush = createSemrushClient({ apiKey: 'your-key' });

try {
  const data = await semrush.getDomainOverview('example.com');
} catch (err) {
  if (err instanceof IntegrationApiError) {
    console.error(`API error ${err.status}: ${err.message}`);
    console.error('Provider:', err.provider);
    console.error('Retryable:', err.retryable);
  } else {
    throw err;
  }
}

API Reference

Semrush

function createSemrushClient(
  apiKey: string,
  config?: Partial<Omit<HttpClientConfig, 'baseUrl' | 'auth'>>,
): SemrushClient;

SemrushClient methods

Method	Parameters	Returns	Description
getDomainOverview	(domain, database?)	SemrushDomainOverview	Traffic, keywords, backlinks summary
getOrganicKeywords	(domain, options?)	PaginatedResponse<SemrushKeywordData>	Keywords with rankings
getBacklinks	(domain, options?)	PaginatedResponse<SemrushBacklinkData>	Backlinks with source/target URLs
getKeywordDifficulty	(keywords[], database?)	SemrushKeywordDifficulty[]	KD scores with volume/CPC
getRelatedKeywords	(keyword, database?)	SemrushRelatedKeyword[]	Related keyword suggestions

Ahrefs

function createAhrefsClient(
  apiToken: string,
  config?: Partial<Omit<HttpClientConfig, 'baseUrl' | 'auth'>>,
): AhrefsClient;

AhrefsClient methods

Method	Parameters	Returns	Description
getSiteOverview	(domain)	AhrefsSiteOverview	DR, organic traffic, backlinks
getOrganicKeywords	(domain, options?)	PaginatedResponse<AhrefsOrganicKeyword>	Ranking keywords with positions
getBacklinks	(domain, options?)	PaginatedResponse<AhrefsBacklink>	Backlinks with anchor text
getKeywordDifficulty	(keywords[])	AhrefsKeywordDifficulty[]	KD scores with volume/CPC
getReferringDomains	(domain, options?)	PaginatedResponse<AhrefsReferringDomain>	Referring domains by DR

Shared

function createHttpClient(config: HttpClientConfig): HttpClient;

HttpClientConfig

Prop	Type	Default	Description
baseUrl	string	—	Base URL for all requests
auth	AuthStrategy	—	Authentication: bearer token or query
rateLimitPerMinute	number	—	Optional: max requests per minute
maxRetries	number	—	Optional: retry failed requests (default: 3)
timeoutMs	number	—	Optional: request timeout in milliseconds

AuthStrategy is one of:

• { type: 'bearer', token: string } — Authorization header
• { type: 'query', paramName: string, value: string } — Query parameter auth

Types

import type {
  HttpClientConfig,
  HttpClient,
  PaginatedResponse,
  SemrushConfig,
  SemrushDomainOverview,
  SemrushKeywordData,
  SemrushBacklinkData,
  SemrushRelatedKeyword,
  SemrushClient,
  AhrefsConfig,
  AhrefsSiteOverview,
  AhrefsOrganicKeyword,
  AhrefsBacklink,
  AhrefsReferringDomain,
  AhrefsClient,
} from '@power-seo/integrations';

Use Cases

• Keyword research pipelines — pull volume and difficulty from Semrush to prioritize content creation
• Backlink monitoring — automate periodic Ahrefs backlink snapshots for link building tracking
• Competitor analysis — use domain overview data to compare your metrics against competitors
• Content brief generation — combine keyword difficulty and volume to prioritize blog topics
• SEO reporting dashboards — pull live Semrush/Ahrefs data into internal analytics tools built with @power-seo/analytics

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Minimal runtime dependencies — only native fetch (available in Node 18+, Deno, Bun, and all Edge runtimes)
• Framework-agnostic — works in Next.js API routes, Remix loaders, Express, Cloudflare Workers
• SSR compatible — safe for server-side use; no browser-specific APIs
• Edge runtime safe — uses only fetch; runs in Cloudflare Workers, Vercel Edge, Deno
• Tree-shakeable — createSemrushClient and createAhrefsClient are separate named exports
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access beyond explicit API calls you initiate
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

Package	Install	Description
@power-seo/core	npm i @power-seo/core	Framework-agnostic utilities, types, validators, and constants
@power-seo/react	npm i @power-seo/react	React SEO components — meta, Open Graph, Twitter Card, breadcrumbs
@power-seo/meta	npm i @power-seo/meta	SSR meta helpers for Next.js App Router, Remix v2, and generic SSR
@power-seo/schema	npm i @power-seo/schema	Type-safe JSON-LD structured data — 23 builders + 22 React components
@power-seo/content-analysis	npm i @power-seo/content-analysis	Yoast-style SEO content scoring engine with React components
@power-seo/readability	npm i @power-seo/readability	Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI
@power-seo/preview	npm i @power-seo/preview	SERP, Open Graph, and Twitter/X Card preview generators
@power-seo/sitemap	npm i @power-seo/sitemap	XML sitemap generation, streaming, index splitting, and validation
@power-seo/redirects	npm i @power-seo/redirects	Redirect engine with Next.js, Remix, and Express adapters
@power-seo/links	npm i @power-seo/links	Link graph analysis — orphan detection, suggestions, equity scoring
@power-seo/audit	npm i @power-seo/audit	Full SEO audit engine — meta, content, structure, performance rules
@power-seo/images	npm i @power-seo/images	Image SEO — alt text, lazy loading, format analysis, image sitemaps
@power-seo/ai	npm i @power-seo/ai	LLM-agnostic AI prompt templates and parsers for SEO tasks
@power-seo/analytics	npm i @power-seo/analytics	Merge GSC + audit data, trend analysis, ranking insights, dashboard
@power-seo/search-console	npm i @power-seo/search-console	Google Search Console API — OAuth2, service account, URL inspection
@power-seo/integrations	npm i @power-seo/integrations	Semrush and Ahrefs API clients with rate limiting and pagination
@power-seo/tracking	npm i @power-seo/tracking	GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License