npm package: @feedlog-ai/core
Description: Core SDK for Feedlog Toolkit
Latest version: 0.0.51

# @feedlog-ai/core

Core SDK package providing shared utilities, types, and functionality used across all Feedlog Toolkit packages.

## Features

- **TypeScript-based SDK**: Fully typed for better developer experience
- **Shared types and interfaces**: Consistent type definitions across packages
- **Utility functions**: HTML sanitization and other utilities
- **Core Feedlog SDK class**: Main API client for interacting with Feedlog services
- **Error handling**: Comprehensive error types and handling
- **Pagination support**: Built-in support for paginated API responses

## Installation

```bash
npm install @feedlog-ai/core
```

## Usage

### Initializing the SDK

```typescript
import { FeedlogSDK } from '@feedlog-ai/core';

// Initialize with required configuration
const sdk = new FeedlogSDK({
  apiKey: 'your-api-key', // Required: API key for authentication
});

// Or initialize with custom configuration
const customSdk = new FeedlogSDK({
  apiKey: 'your-api-key', // Required: API key for authentication
  endpoint: 'https://api.feedlog.app', // Custom API endpoint (optional)
  timeout: 30000, // Request timeout in milliseconds (optional)
});
```

The SDK defaults `credentials` to `'include'` so cookies (for example anonymous user/session) are sent on cross-origin requests to the API. Pass `credentials: 'same-origin'` or `'omit'` if you need to avoid that.

### Fetching Issues

```typescript
// Fetch issues with default parameters
const response = await sdk.fetchIssues();

// Optional: offset-based pagination (when the API supports it)
await sdk.fetchIssues({ offset: 0, limit: 10 });

// Fetch issues with filters
const filteredResponse = await sdk.fetchIssues({
  type: 'bug', // 'bug' or 'enhancement'
  sortBy: 'updatedAt', // optional: 'createdAt' | 'updatedAt'
  limit: 20, // Maximum number of issues (1-100)
  cursor: 'next-page-cursor', // For pagination
});

// Fetch issues from specific repositories
const repoResponse = await sdk.fetchIssues({
  repositoryIds: ['repo-id-1', 'repo-id-2'], // Array of repository IDs (or a single string)
  type: 'enhancement',
  limit: 10,
});
```

### Upvoting Issues

```typescript
// Toggle upvote on an issue
const upvoteResult = await sdk.toggleUpvote('issue-id');

console.log(upvoteResult.upvoted); // true if upvoted, false if unvoted
console.log(upvoteResult.upvoteCount); // Updated upvote count
console.log(upvoteResult.anonymousUserId); // User's anonymous ID
```

## API Reference

### FeedlogSDK

The main SDK class for interacting with the Feedlog API.

#### Constructor

```typescript
new FeedlogSDK(config: FeedlogSDKConfig)
```

#### Methods

- `fetchIssues(params?: FetchIssuesParams): Promise<FetchIssuesResponse>`
- `toggleUpvote(issueId: string): Promise<UpvoteResponse>`
- `getEndpoint(): string` - Get current API endpoint
- `getTimeout(): number` - Get current timeout setting

### Types

#### Core Types

- `FeedlogIssue` - GitHub issue data structure
- `Repository` - Repository information
- `FetchIssuesParams` - Parameters for fetching issues (includes optional `sortBy`, `offset`, `cursor`, etc.)
- `SortBy` - `'createdAt' | 'updatedAt'`
- `FetchIssuesResponse` - Response from fetching issues
- `UpvoteResponse` - Response from upvoting an issue
- `FeedlogSDKConfig` - SDK configuration options

#### Error Types

- `FeedlogError` - Base error class
- `FeedlogNetworkError` - Network-related errors
- `FeedlogTimeoutError` - Timeout errors
- `FeedlogValidationError` - Validation errors

### Utilities

- `sanitizeHtml(html: string): string` - Sanitize HTML content to prevent XSS

## Custom changelog UI (core-only)

To render your own markup with `FeedlogSDK` only—no React, Vue, or web component UI packages—see [BUILD_FEEDLOG_SDK_ONLY.md](./BUILD_FEEDLOG_SDK_ONLY.md). For an overview of all integration tiers, see [Build Feedlog](../../README.md#build-feedlog).

## Error Handling

The SDK provides specific error types for different failure scenarios:

```typescript
import {
  FeedlogError,
  FeedlogNetworkError,
  FeedlogTimeoutError,
  FeedlogValidationError,
} from '@feedlog-ai/core';

try {
  const issues = await sdk.fetchIssues();
} catch (error) {
  if (error instanceof FeedlogNetworkError) {
    console.error('Network error:', error.statusCode);
  } else if (error instanceof FeedlogTimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof FeedlogValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof FeedlogError) {
    console.error('Feedlog error:', error.message);
  }
}
```

## Requirements

- Node.js >= 18.0.0
- TypeScript >= 5.3.3 (for type definitions)

## License

MIT