SemanticPen - AI Article Writer & SEO Blog Generator SDK

Professional AI Article Writer SDK for automated content creation, SEO blog writing, and AI-powered article generation. Build applications with intelligent content automation using TypeScript/JavaScript.

🔗 SemanticPen.com - AI-Powered Content Creation Platform
📚 API Documentation - Complete API Reference

Features

• 🤖 AI Article Writer: Generate high-quality, SEO-optimized articles from keywords using advanced AI
• 📊 SEO Blog Generator: Create SEO-friendly blog content with automated optimization
• 🚀 Content Automation: Streamline your content creation workflow with AI-powered writing
• ⚡ Fast Article Generation: Modern async/await API for quick content creation
• 🎯 TypeScript & JavaScript: Full TypeScript support with comprehensive type definitions
• 🔄 Real-time Status: Monitor article generation progress with automatic polling
• 🛠️ Zero Configuration: Works out of the box with intelligent defaults
• 🔒 Enterprise Security: Built-in API key management and secure authentication
• 📝 Multiple Formats: Support for various content types and article structures
• 🌐 Scalable: Handle single articles or bulk content generation

Installation

npm install semanticpen

Get started with AI-powered article writing in seconds!

Quick Start

Basic Usage - Submit Articles for Generation

import { SemanticPenClient } from 'semanticpen';

// Initialize the client with just your API key
const client = SemanticPenClient.create('your-api-key');

// Step 1: Submit article for generation (returns immediately)
const result = await client.generateArticle('Future of artificial intelligence');
console.log(`Article generation started with ID: ${result.articleIds[0]}`);
console.log(`Project ID: ${result.projectId}`);

// Step 2: Check article status
const status = await client.getArticleStatus(result.articleIds[0]);
console.log(`Current status: ${status.status}`); // 'queued', 'processing', 'finished', or 'failed'

// Step 3: Wait for completion and retrieve article
const isReady = await client.isArticleComplete(result.articleIds[0]);
if (isReady) {
  const article = await client.getArticle(result.articleIds[0]);
  console.log(`Title: ${article.title}`);
  console.log(`Content: ${article.article_html}`);
}

Multiple Article Generation

// Submit multiple articles at once
const keywords = [
  'Machine learning in healthcare',
  'AI-powered diagnosis tools',
  'Future of telemedicine'
];

const result = await client.generateArticles(keywords);
console.log(`Started generating ${result.successful.length} articles`);

// Check status of all articles
result.successful.forEach(async (item) => {
  const status = await client.getArticleStatus(item.articleId);
  console.log(`Article "${item.keyword}": ${status.status}`);
});

API Reference

Client Initialization

// Simple initialization (recommended)
const client = SemanticPenClient.create('your-api-key');

// Advanced configuration (optional)
const client = new SemanticPenClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://www.semanticpen.com', // default: https://www.semanticpen.com
  timeout: 30000, // default: 30 seconds
  debug: false // default: false, set to true for debug logging
});

Article Generation

Generate Single Article

// Basic generation
const result = await client.generateArticle('keyword');

// With options (Note: only basic options are supported)
const result = await client.generateArticle('keyword', {
  projectName: 'My Project'
});

// Advanced: Generate and wait for completion (blocking operation)
const article = await client.generateArticleAndWait('keyword', {
  generation: {
    projectName: 'My Project'
  },
  polling: {
    interval: 5000, // poll every 5 seconds
    maxAttempts: 60 // max 5 minutes
  },
  callbacks: {
    onProgress: (attempt, status) => {
      console.log(`Attempt ${attempt}: ${status}`);
    }
  }
});

Generate Multiple Articles

// Multiple article IDs from generation
const keywords = ['keyword1', 'keyword2', 'keyword3'];
const result = await client.generateArticles(keywords);

// Access results
result.successful.forEach(item => {
  console.log(`Generated article ${item.articleId} for "${item.keyword}"`);
});

result.failed.forEach(item => {
  console.log(`Failed to generate article for "${item.item}": ${item.error}`);
});

Article Retrieval

// Get single article
const article = await client.getArticle('article-id');

// Get multiple articles
const result = await client.getArticles(['id1', 'id2', 'id3']);

// Check article status
const status = await client.getArticleStatus('article-id');
console.log(status.isComplete, status.hasError);

// Check if article is complete
const isComplete = await client.isArticleComplete('article-id');

Status Polling

// Wait for article completion
const article = await client.waitForArticle('article-id');

// Wait with custom polling configuration
const article = await client.waitForArticle('article-id', {
  polling: {
    interval: 3000, // 3 seconds
    maxAttempts: 100, // ~5 minutes
    backoffMultiplier: 1.1 // slight backoff
  },
  callbacks: {
    onProgress: (attempt, status) => {
      console.log(`Polling attempt ${attempt}: ${status}`);
    },
    onComplete: (article) => {
      console.log('Article completed!', article.title);
    }
  }
});

// Wait for multiple articles
const result = await client.waitForArticles(['id1', 'id2']);
console.log(`${result.successful.length} articles completed successfully`);

Advanced Usage

One-Step Generation (Blocking Operation)

For simpler workflows, you can generate and wait for completion in one call:

// Generate article and wait for completion (blocking)
const article = await client.generateArticleAndWait('AI in healthcare', {
  generation: {
    projectName: 'Healthcare Articles'
  },
  polling: {
    interval: 3000, // poll every 3 seconds
    maxAttempts: 100 // max ~5 minutes
  },
  callbacks: {
    onProgress: (attempt, status) => {
      console.log(`Polling attempt ${attempt}: ${status}`);
    },
    onComplete: (article) => {
      console.log(`Article completed: ${article.title}`);
    }
  }
});

console.log(article.title);
console.log(article.article_html);

Request Builder Pattern

const article = await client
  .createRequestBuilder()
  .keyword('AI in healthcare')
  .projectName('Healthcare Articles')
  .parameter('customField', 'customValue')
  .generateArticleAndWait();

Configuration Options

Polling Presets

import { PollingPresets } from 'semanticpen';

// Fast polling (2s intervals, 2 minutes max)
await client.waitForArticle('id', { polling: PollingPresets.FAST });

// Standard polling (5s intervals, 5 minutes max)
await client.waitForArticle('id', { polling: PollingPresets.STANDARD });

// Patient polling (10s intervals, 10 minutes max)
await client.waitForArticle('id', { polling: PollingPresets.PATIENT });

// Background polling (30s intervals, 30 minutes max)
await client.waitForArticle('id', { polling: PollingPresets.BACKGROUND });

Custom Polling Configuration

import { createPollingConfig } from 'semanticpen';

const customPolling = createPollingConfig(
  3, // interval in seconds
  10, // max minutes
  1.5 // backoff multiplier
);

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { 
  AuthenticationError, 
  ValidationError, 
  RateLimitError, 
  NetworkError,
  TimeoutError 
} from 'semanticpen';

try {
  const article = await client.generateAndWait('keyword');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key or authentication failed');
  } else if (error instanceof ValidationError) {
    console.log('Invalid input:', error.field, error.value);
  } else if (error instanceof RateLimitError) {
    console.log('Rate limit exceeded, retry after:', error.retryAfter);
  } else if (error instanceof NetworkError) {
    console.log('Network error:', error.statusCode);
  } else if (error instanceof TimeoutError) {
    console.log('Operation timed out after:', error.timeoutMs);
  }
}

TypeScript Support

The SDK is built with TypeScript and provides comprehensive type definitions:

import type { 
  Article, 
  ArticleGenerationRequest, 
  ArticleStatusInfo,
  PollingConfig,
  BulkOperationResult 
} from 'semanticpen';

// All methods are fully typed
const request: ArticleGenerationRequest = {
  targetKeyword: 'AI trends',
  projectName: 'Tech Articles'
};

const article: Article = await client.generateArticleAndWait('keyword');
const status: ArticleStatusEnum = article.status;

Environment Variables

You can optionally configure the SDK using environment variables. Only the API key is required:

SEMANTICPEN_API_KEY=your-api-key
# Optional - the following have sensible defaults:
SEMANTICPEN_BASE_URL=https://www.semanticpen.com
SEMANTICPEN_TIMEOUT=30000
SEMANTICPEN_DEBUG=false

// The SDK will automatically pick up environment variables
const client = SemanticPenClient.create(
  process.env.SEMANTICPEN_API_KEY!
);

Browser Support

The SDK works in both Node.js and modern browsers:

<!-- Browser usage via CDN -->
<script src="https://unpkg.com/semanticpen@latest/dist/index.esm.js"></script>
<script>
  const client = SemanticPenSDK.SemanticPenClient.create('your-api-key');
  // Use client...
</script>

Complete Parameter Reference

Article Generation Parameters

All generation methods accept these optional parameters:

interface ArticleGenerationRequest {
  targetKeyword: string;           // Required: The main keyword for article generation
  projectName?: string;           // Optional: Name for organizing articles
  // Note: Advanced parameters like gptVersion, integrationId are handled server-side
}

Polling Configuration

Control how the SDK waits for article completion:

interface PollingConfig {
  interval: number;              // Milliseconds between status checks (default: 5000)
  maxAttempts: number;          // Maximum polling attempts (default: 60)
  backoffMultiplier: number;    // Exponential backoff multiplier (default: 1.0)
  maxInterval: number;          // Maximum interval between polls (default: 30000)
}

Client Configuration

Available options when creating the client:

interface SemanticPenConfig {
  apiKey: string;               // Required: Your SemanticPen API key
  baseUrl?: string;            // Optional: API base URL (default: 'https://www.semanticpen.com')
  timeout?: number;            // Optional: Request timeout in ms (default: 30000)
  debug?: boolean;             // Optional: Enable debug logging (default: false)
}

Article Status Values

Articles go through these status stages during generation:

• queued: Article is waiting to be processed
• processing: Article is currently being generated
• finished: Article generation completed successfully
• failed: Article generation failed with an error

Error Types

The SDK provides specific error types for better error handling:

• AuthenticationError: Invalid API key or authentication issues
• ValidationError: Invalid input parameters
• RateLimitError: API rate limit exceeded
• NetworkError: Network or HTTP errors
• TimeoutError: Request or operation timeout

Examples

Check the /examples directory for comprehensive examples:

• Basic Usage
• Custom Polling
• Error Handling

API Requirements

• Valid SemanticPen API key (get one at SemanticPen.com)
• Active paid subscription (view pricing at SemanticPen.com)
• Node.js 14+ or modern browser with fetch support
• For complete API reference, visit API Documentation

License

MIT License - see LICENSE file for details.

Support

• 📖 API Documentation - Complete API Reference
• 🐛 Issue Tracker
• 💬 Support
• 🌐 SemanticPen.com - AI Article Writer Platform

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Built with ❤️ by the SemanticPen team