🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

@power-seo/integrations

Package Overview
Dependencies
Maintainers
1
Versions
10
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@power-seo/integrations - npm Package Compare versions

Comparing version
1.0.11
 to
1.0.12
+9
-3
package.json
{
"name": "@power-seo/integrations",
"version": "1.0.11",
"version": "1.0.12",
"description": "Third-party SEO tool API clients for Semrush and Ahrefs with shared HTTP client",

@@ -40,6 +40,12 @@ "keywords": [

"files": [
"dist"
"dist",
"LICENSE"
],
"engines": {
"node": ">=18.0.0",
"npm": ">=9.0.0",
"pnpm": ">=8.0.0"
},
"dependencies": {
"@power-seo/core": "1.0.11"
"@power-seo/core": "1.0.12"
},

@@ -46,0 +52,0 @@ "devDependencies": {

+95
-107
README.md
# @power-seo/integrations
![integrations banner](../../image/integrations/banner.svg)
![integrations banner](https://raw.githubusercontent.com/CyberCraftBD/power-seo/main/image/integrations/banner.svg)

@@ -10,3 +10,2 @@ 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.

[![Socket](https://socket.dev/api/badge/npm/package/@power-seo/integrations)](https://socket.dev/npm/package/@power-seo/integrations)
[![npm provenance](https://img.shields.io/badge/npm-provenance-enabled-blue)](https://github.com/CyberCraftBD/power-seo/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

@@ -19,2 +18,4 @@ [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)

> **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.

@@ -25,14 +26,20 @@ ---

| | 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 `statusCode` |
| TypeScript types | ❌ `any` everywhere | ✅ Full type coverage for all endpoints |
| Bundle size | ❌ Full SDK in bundle | ✅ Tree-shakeable — import only what you use |
| | 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 |
![Integrations Comparison](../../image/integrations/comparison.svg)
![Integrations Comparison](https://raw.githubusercontent.com/CyberCraftBD/power-seo/main/image/integrations/comparison.svg)
<p align="left">
<a href="https://www.buymeacoffee.com/ccbd.dev" target="_blank">
<img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=ccbd.dev&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff" />
</a>
</p>
---

@@ -47,6 +54,6 @@

- **Full TypeScript types** — every request parameter and response field is typed; no `any` in your code
- **Consistent error handling** — `IntegrationApiError` with `statusCode`, `message`, and raw `response` payload from both APIs
- **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
![SEO Research UI](../../image/integrations/seo-research-ui.svg)
![SEO Research UI](https://raw.githubusercontent.com/CyberCraftBD/power-seo/main/image/integrations/seo-research-ui.svg)

@@ -68,3 +75,3 @@ ---

![Rate Limit Accuracy](../../image/integrations/rate-limit-accuracy.svg)
![Rate Limit Accuracy](https://raw.githubusercontent.com/CyberCraftBD/power-seo/main/image/integrations/rate-limit-accuracy.svg)

@@ -107,3 +114,3 @@ ---

![Unification Benefit](../../image/integrations/unification-benefit.svg)
![Unification Benefit](https://raw.githubusercontent.com/CyberCraftBD/power-seo/main/image/integrations/unification-benefit.svg)

@@ -120,35 +127,26 @@ ---

const semrush = createSemrushClient({
apiKey: process.env.SEMRUSH_API_KEY!,
database: 'us', // default: 'us'
rateLimiting: { maxRequests: 10, windowMs: 60_000 }, // optional
});
const semrush = createSemrushClient(
process.env.SEMRUSH_API_KEY!,
{ rateLimitPerMinute: 10, maxRetries: 3 }, // optional
);
// Domain overview — traffic, keywords, backlinks
const overview: SemrushDomainOverview = await semrush.getDomainOverview({
domain: 'example.com',
});
// { organicTraffic, paidTraffic, organicKeywords, paidKeywords, backlinks, referringDomains }
const overview: SemrushDomainOverview = await semrush.getDomainOverview('example.com', 'us');
// { domain, organicTraffic, paidTraffic, organicKeywords, paidKeywords, backlinks, authorityScore }
// Keyword data — volume, CPC, competition, SERP features
const keyword: SemrushKeywordData = await semrush.getKeywordData({
keyword: 'react seo',
database: 'us',
});
// { keyword, volume, cpc, competition, results, trend, serpFeatures }
// 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({
domain: 'example.com',
limit: 100,
});
// [{ sourcePage, targetPage, type, anchorText, firstSeen, lastSeen }]
const backlinks = await semrush.getBacklinks('example.com', { limit: 100, offset: 0 });
// { data: SemrushBacklinkData[], total, offset, limit, hasMore }
// Keyword difficulty
const difficulty = await semrush.getKeywordDifficulty({ keyword: 'react seo' });
// { keyword, difficulty } // difficulty 0–100
const difficulty = await semrush.getKeywordDifficulty(['react seo'], 'us');
// [{ keyword, difficulty, searchVolume, cpc, competition, results }]
// Related keywords
const related = await semrush.getRelatedKeywords({ keyword: 'react seo', limit: 20 });
// [{ keyword, volume, cpc, competition, relatedRelevance }]
const related = await semrush.getRelatedKeywords('react seo', 'us');
// [{ keyword, searchVolume, cpc, competition, results, relatedTo }]
```

@@ -162,41 +160,26 @@

const ahrefs = createAhrefsClient({
apiKey: process.env.AHREFS_API_KEY!,
rateLimiting: { maxRequests: 5, windowMs: 60_000 }, // optional
});
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({
target: 'example.com',
mode: 'domain', // 'domain' | 'subdomains' | 'exact'
});
// { domainRating, urlRating, organicTraffic, organicKeywords, backlinks, referringDomains }
const overview: AhrefsSiteOverview = await ahrefs.getSiteOverview('example.com');
// { domain, domainRating, urlRating, organicTraffic, organicKeywords, backlinks, referringDomains, trafficValue }
// Organic keywords with positions
const keywords: AhrefsOrganicKeyword[] = await ahrefs.getOrganicKeywords({
target: 'example.com',
limit: 200,
orderBy: 'traffic:desc',
});
// [{ keyword, position, volume, traffic, url, cpc }]
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({
target: 'example.com',
limit: 100,
mode: 'domain',
});
// [{ anchorText, domainRating, urlFrom, urlTo, firstSeen, linkType }]
const backlinks = await ahrefs.getBacklinks('example.com', { limit: 100, offset: 0 });
// { data: AhrefsBacklink[], total, offset, limit, hasMore }
// Keyword difficulty
const kd = await ahrefs.getKeywordDifficulty({ keyword: 'react seo' });
// { keyword, difficulty } // difficulty 0–100
const kd = await ahrefs.getKeywordDifficulty(['react seo']);
// [{ keyword, difficulty, searchVolume, cpc, clicks, globalVolume }]
// Referring domains
const domains = await ahrefs.getReferringDomains({
target: 'example.com',
limit: 50,
orderBy: 'domain_rating:desc',
});
// [{ domain, domainRating, backlinks, linkedDomains }]
const domains = await ahrefs.getReferringDomains('example.com', { limit: 50, offset: 0 });
// { data: AhrefsReferringDomain[], total, offset, limit, hasMore }
```

@@ -213,11 +196,9 @@

baseUrl: 'https://api.example.com',
headers: { Authorization: `Bearer ${token}` },
rateLimiting: {
maxRequests: 10, // max requests allowed
windowMs: 60_000, // per this window in ms
},
auth: { type: 'bearer', token },
rateLimitPerMinute: 60, // max requests per minute
maxRetries: 3,
timeoutMs: 30_000,
});
const data = await http.get<MyResponseType>('/endpoint', { query: 'param' });
const list = await http.getPaginated<MyItem>('/items', { page: 1, limit: 100 });
```

@@ -235,7 +216,8 @@

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

@@ -254,3 +236,6 @@ throw err;

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

@@ -260,9 +245,9 @@

| Method | Parameters | Returns | Description |
| ---------------------- | ------------------------ | ------------------------- | ------------------------------------ |
| `getDomainOverview` | `{ domain }` | `SemrushDomainOverview` | Traffic, keywords, backlinks summary |
| `getKeywordData` | `{ keyword, database? }` | `SemrushKeywordData` | Volume, CPC, competition, trend |
| `getBacklinks` | `{ domain, limit? }` | `SemrushBacklinkData[]` | Backlink list with follow/nofollow |
| `getKeywordDifficulty` | `{ keyword }` | `{ keyword, difficulty }` | KD score 0–100 |
| `getRelatedKeywords` | `{ keyword, limit? }` | `SemrushRelatedKeyword[]` | Related keyword suggestions |
| 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 |

@@ -272,3 +257,6 @@ ### Ahrefs

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

@@ -278,9 +266,9 @@

| Method | Parameters | Returns | Description |
| ---------------------- | ------------------------------ | ------------------------- | ------------------------------- |
| `getSiteOverview` | `{ target, mode? }` | `AhrefsSiteOverview` | DR, organic traffic, backlinks |
| `getOrganicKeywords` | `{ target, limit?, orderBy? }` | `AhrefsOrganicKeyword[]` | Ranking keywords with positions |
| `getBacklinks` | `{ target, limit?, mode? }` | `AhrefsBacklink[]` | Backlinks with anchor text |
| `getKeywordDifficulty` | `{ keyword }` | `{ keyword, difficulty }` | KD score 0–100 |
| `getReferringDomains` | `{ target, limit?, orderBy? }` | `AhrefsReferringDomain[]` | Referring domains by DR |
| 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 |

@@ -295,8 +283,15 @@ ### Shared

| Prop | Type | Default | Description |
| -------------- | --------------------------- | ------- | ----------------------------- |
| `baseUrl` | `string` | — | Base URL for all requests |
| `headers` | `Record<string, string>` | `{}` | Default request headers |
| `rateLimiting` | `{ maxRequests, windowMs }` | — | Optional rate limiting config |
| 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

@@ -353,3 +348,2 @@

- No `eval` or dynamic code execution
- npm provenance enabled — every release is signed via Sigstore through GitHub Actions
- CI-signed builds — all releases published via verified `github.com/CyberCraftBD/power-seo` workflow

@@ -369,3 +363,3 @@ - Safe for SSR, Edge, and server environments

| [`@power-seo/meta`](https://www.npmjs.com/package/@power-seo/meta) | `npm i @power-seo/meta` | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR |
| [`@power-seo/schema`](https://www.npmjs.com/package/@power-seo/schema) | `npm i @power-seo/schema` | Type-safe JSON-LD structured data — 23 builders + 21 React components |
| [`@power-seo/schema`](https://www.npmjs.com/package/@power-seo/schema) | `npm i @power-seo/schema` | Type-safe JSON-LD structured data — 23 builders + 22 React components |
| [`@power-seo/content-analysis`](https://www.npmjs.com/package/@power-seo/content-analysis) | `npm i @power-seo/content-analysis` | Yoast-style SEO content scoring engine with React components |

@@ -387,8 +381,2 @@ | [`@power-seo/readability`](https://www.npmjs.com/package/@power-seo/readability) | `npm i @power-seo/readability` | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI |

## Keywords
seo · semrush · semrush api · ahrefs · ahrefs api · keyword research · backlink api · domain overview · keyword difficulty · seo api · rate limiting · keyword volume · paginated api · seo data · third party seo · typescript · integrations · seo api client · api wrapper · seo data fetching
---
## About [CyberCraft Bangladesh](https://ccbd.dev)

@@ -395,0 +383,0 @@