semanticpen/README.md

AI Article Writer & SEO Blog Generator SDK - Professional TypeScript/JavaScript library for automated content creation, AI-powered article generation, and SEO blog writing with SemanticPen

# 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](https://www.semanticpen.com/)** - AI-Powered Content Creation Platform  
📚 **[API Documentation](https://www.semanticpen.com/api-documentation)** - Complete API Reference

[![npm version](https://badge.fury.io/js/semanticpen.svg)](https://badge.fury.io/js/semanticpen)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
npm install semanticpen
```

Get started with AI-powered article writing in seconds!

## Quick Start

### Basic Usage - Submit Articles for Generation

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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:

```typescript
// 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

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

## Configuration Options

### Polling Presets

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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:

```bash
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
```

```typescript
// 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:

```html
<!-- 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:

```typescript
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:

```typescript
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:

```typescript
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](./examples/basic-usage.js)
- [Custom Polling](./examples/custom-polling.js)
- [Error Handling](./examples/error-handling.js)

## API Requirements

- Valid SemanticPen API key (get one at [SemanticPen.com](https://www.semanticpen.com))
- Active paid subscription (view pricing at [SemanticPen.com](https://www.semanticpen.com))
- Node.js 14+ or modern browser with fetch support
- For complete API reference, visit [API Documentation](https://www.semanticpen.com/api-documentation)

## License

MIT License - see [LICENSE](./LICENSE) file for details.

## Support

- 📖 [API Documentation](https://www.semanticpen.com/api-documentation) - Complete API Reference
- 🐛 [Issue Tracker](https://github.com/semanticpen/sdk/issues)
- 💬 [Support](mailto:contact@semanticpen.com)
- 🌐 [SemanticPen.com](https://www.semanticpen.com) - AI Article Writer Platform

## Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

---

Built with ❤️ by the SemanticPen team