@hardlydifficult/social 1.0.2 → 1.0.4

package/README.md

@@ -12,13 +12,163 @@ This package is intentionally read-only for now:
 
 Write operations (posting, liking, reposting) are intentionally not included yet.
 
-## Install
+## Installation
 
 ```bash
 npm install @hardlydifficult/social
 ```
 
-## Usage
+## Quick Start
+
+```typescript
+import { createXClient } from '@hardlydifficult/social';
+
+const client = createXClient({
+  bearerToken: process.env.X_BEARER_TOKEN!,
+});
+
+const timeline = await client.getTimeline();
+console.log(`Retrieved ${timeline.length} posts`);
+```
+
+## Core Client
+
+### Social Client
+
+The `SocialClient` wraps a `SocialProviderClient` implementation to provide a platform-agnostic interface for social operations.
+
+```typescript
+import { createXClient } from '@hardlydifficult/social';
+
+const client = createXClient({ bearerToken: 'your-token' });
+
+// Get timeline posts
+const posts = await client.getTimeline();
+
+// Get posts where the user was liked (via polling-like interface)
+const likedPosts = await client.getLikedPosts();
+```
+
+### Social Provider Interface
+
+All provider implementations must implement `SocialProviderClient`, which requires:
+
+- `getTimeline()`: Fetch recent posts
+- `getLikedPosts()`: Fetch posts the authenticated user has liked
+- `getPost(postId: string)`: Fetch a specific post
+
+```typescript
+import type { SocialProviderClient } from '@hardlydifficult/social';
+
+// Example interface contract
+interface MyProvider implements SocialProviderClient {
+  getTimeline(): Promise<SocialPost[]>;
+  getLikedPosts(): Promise<SocialPost[]>;
+  getPost(id: string): Promise<SocialPost | undefined>;
+}
+```
+
+## Types
+
+### SocialPost
+
+Standardized post type used across platforms:
+
+```typescript
+import type { SocialPost } from '@hardlydifficult/social';
+
+interface SocialPost {
+  id: string;
+  text: string;
+  createdAt: Date;
+  author: {
+    username: string;
+    displayName?: string;
+    avatarUrl?: string;
+  };
+  media?: { url: string; type: 'image' | 'video' }[];
+}
+```
+
+## X (Twitter) Client
+
+The `XSocialClient` implements the provider interface against the X/Twitter API.
+
+### Constructor Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `bearerToken` | `string` | ✅ | Twitter API bearer token |
+| `userId` | `string` | ❌ | User ID; falls back to `/2/users/me` if not provided |
+
+### Example Usage
+
+```typescript
+import { createXClient } from '@hardlydifficult/social';
+
+const client = createXClient({
+  bearerToken: process.env.X_BEARER_TOKEN!,
+});
+
+// Fetch timeline
+const posts = await client.getTimeline();
+
+// Fetch liked posts for this user
+const likedPosts = await client.getLikedPosts();
+```
+
+## Like Watching
+
+`SocialLikeWatcher` polls the provider for new liked posts and emits events when new ones are detected.
+
+### Constructor Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `client` | `SocialProviderClient` | ✅ | — | Provider client instance |
+| `pollIntervalMs` | `number` | ❌ | `60_000` | Polling interval in milliseconds |
+| `initialLikeIds` | `string[]` | ❌ | `[]` | Pre-known liked post IDs (for resume) |
+
+### Event Emitter API
+
+```typescript
+import { createXClient, SocialLikeWatcher } from '@hardlydifficult/social';
+
+const client = createXClient({ bearerToken: process.env.X_BEARER_TOKEN! });
+const watcher = new SocialLikeWatcher(client, { pollIntervalMs: 30_000 });
+
+watcher.on('newLike', (post) => {
+  console.log(`New like detected: ${post.text}`);
+});
+
+watcher.on('error', (err) => {
+  console.error('Watcher error:', err);
+});
+
+watcher.start();
+// Wait for likes...
+// watcher.stop();
+```
+
+## Factory Functions
+
+The package exports convenience factory functions to construct platform-specific clients:
+
+| Function | Returns | Description |
+|---------|---------|-------------|
+| `createXClient(options)` | `SocialClient` | Constructs X/Twitter client with default implementation |
+| `createMastodonClient(options)` | `never` | Currently throws "not implemented" error |
+
+```typescript
+import { createXClient } from '@hardlydifficult/social';
+
+// X client
+const xClient = createXClient({ bearerToken: '...' });
+```
+
+## Usage with High-Level API
+
+For a more opinionated interface, use `createSocial`:
 
 ```typescript
 import { createSocial } from "@hardlydifficult/social";
@@ -38,7 +188,7 @@ const watcher = social.watchLikes({
 watcher.start();
 ```
 
-## X configuration
+### X configuration
 
 Set environment variables, or pass explicit config through `createSocialClient`.
 
@@ -53,3 +203,29 @@ const social = createSocialClient({
   bearerToken: process.env.X_BEARER_TOKEN,
 });
 ```
+
+## Testing
+
+Unit tests cover:
+
+- Factory initialization
+- Timeline retrieval via provider-agnostic interface
+- Like watcher polling and stateful detection
+
+Run tests with:
+
+```bash
+npm test
+```
+
+## Appendix
+
+### Platform Support
+
+| Feature | X (Twitter) | Mastodon |
+|---------|-------------|----------|
+| Timeline | ✅ | ❌ (stub) |
+| Liked Posts | ✅ | ❌ (stub) |
+| Like Watching | ✅ | ❌ (stub) |
+
+Mastodon support is currently unimplemented and will throw errors on usage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/social",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -21,7 +21,7 @@
   },
   "type": "commonjs",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.19.0"
   },
   "exports": {
     ".": {