@crosspost/sdk 0.1.2 → 0.1.3

package/README.md

@@ -2,126 +2,262 @@
 
 SDK for interacting with the Crosspost API.
 
-## Overview
-
-This package provides a client for interacting with the Crosspost API, allowing you to easily
-integrate social media posting capabilities into your applications. The SDK is designed to be
-flexible and easy to use, with support for multiple authentication methods and platforms.
-
-## Features
-
-- Unified client for all supported platforms
-- Flexible authentication:
-  - Direct `nearAuthData` injection
-  - Automatic cookie-based authentication (`__crosspost_auth`)
-  - Explicit authentication via `setAuthentication` method
-- Platform-specific clients (Twitter, with more to come)
-- Type-safe request/response handling using `@crosspost/types`
-- Comprehensive error handling with specific `ApiError` and `PlatformError` types
-- CSRF protection via Double Submit Cookie pattern
-
 ## Installation
 
 ```bash
 bun install @crosspost/sdk
 ```
 
-## Usage
-
-### Initializing the SDK
-
-The SDK can be initialized in several ways depending on how you manage authentication:
-
-**1. Cookie-Based Authentication (Recommended for Browsers)**
-
-If the user has previously authenticated via the API, the SDK can automatically use the
-authentication data stored in the `__crosspost_auth` cookie.
+## Quick Start
 
 ```typescript
-import { CrosspostClient } from '@crosspost/sdk';
+import { ApiError, CrosspostClient, isAuthError, PlatformError } from '@crosspost/sdk';
 
-// Client will automatically try to load auth from the cookie
+// Initialize the client with direct authentication
 const client = new CrosspostClient({
   baseUrl: 'https://your-crosspost-api.com', // Optional: Defaults to official API
+  nearAuthData: {
+    accountId: 'your-account.near',
+    publicKey: 'ed25519:...',
+    signature: '...',
+    message: '...',
+  },
 });
 
-// If the cookie exists and is valid, requests will be authenticated.
-// If not, authenticated requests will throw an ApiError.
-```
+// Or initialize with cookie-based authentication (will auto-load from cookie if available)
+const cookieClient = new CrosspostClient({
+  baseUrl: 'https://your-crosspost-api.com',
+  // No nearAuthData provided - will check for cookie
+});
 
-The cookie is stored with secure attributes:
+// Set authentication explicitly (also stores in secure cookie)
+await cookieClient.setAuthentication({
+  accountId: 'your-account.near',
+  publicKey: 'ed25519:...',
+  signature: '...',
+  message: '...',
+});
 
-- `secure: true` - Only sent over HTTPS
-- `sameSite: 'lax'` - Provides CSRF protection while allowing top-level navigation
-- `path: '/'` - Available across the entire domain
-- `expires: 30 days` - Persists for 30 days
+// Check if client is authenticated
+if (cookieClient.isAuthenticated()) {
+  console.log('Client is authenticated');
+}
 
-**2. Direct Authentication**
+// NEAR Account Authorization
+async function authorizeNearAccount() {
+  try {
+    // Authorize with NEAR account
+    const authResponse = await client.auth.authorizeNearAccount();
+    console.log('NEAR authorization successful');
+    console.log('Account ID:', authResponse.accountId);
+    console.log('Status:', authResponse.status);
+    console.log('Connected platforms:', authResponse.connectedPlatforms);
+    return true;
+  } catch (error) {
+    console.error('NEAR authorization failed');
+    if (error instanceof ApiError) {
+      console.error('Error code:', error.code);
+      console.error('Status:', error.status);
+      console.error('Details:', error.details);
+      console.error('Recoverable:', error.recoverable);
+    }
+    return false;
+  }
+}
 
-Provide the `nearAuthData` object directly if you have obtained it through other means (e.g.,
-server-side flow, manual signing).
+// Unauthorize NEAR Account
+async function unauthorizeNearAccount() {
+  try {
+    // Unauthorize NEAR account (removes all platform connections)
+    const response = await client.auth.unauthorizeNearAccount();
+    console.log('NEAR account unauthorized');
+    console.log('Status:', response.status);
+    console.log('Message:', response.message);
+    return true;
+  } catch (error) {
+    console.error('Failed to unauthorize NEAR account');
+    if (error instanceof ApiError) {
+      console.error('Error code:', error.code);
+      console.error('Status:', error.status);
+      console.error('Details:', error.details);
+    }
+    return false;
+  }
+}
 
-```typescript
-import { CrosspostClient } from '@crosspost/sdk';
-import type { NearAuthData } from 'near-sign-verify'; // Assuming this type exists
+// Revoke Platform Authorization
+async function revokePlatformAuth(platform) {
+  try {
+    // Revoke specific platform authorization
+    const response = await client.auth.revokeAuth(platform);
+    console.log(`${platform} authorization revoked`);
+    console.log('Status:', response.status);
+    console.log('Platform:', response.platform);
+    console.log('Message:', response.message);
+    return true;
+  } catch (error) {
+    console.error(`Failed to revoke ${platform} authorization`);
+    if (error instanceof ApiError) {
+      console.error('Error code:', error.code);
+      console.error('Status:', error.status);
+      console.error('Details:', error.details);
+    }
+    return false;
+  }
+}
 
-const nearAuthData: NearAuthData = {
-  account_id: 'example.near',
-  public_key: 'ed25519:...',
-  signature: '...',
-  message: '...',
-  nonce: '...',
-  recipient: 'crosspost-api.near',
-  // callback_url and state are optional
-};
+// Example usage
+async function createPost() {
+  try {
+    const response = await client.post.createPost({
+      content: {
+        text: 'Hello from Crosspost SDK!',
+      },
+    });
+    console.log('Post created successfully');
+    console.log('Post ID:', response.id);
+    console.log('Platform:', response.platform);
+    console.log('URL:', response.url);
+    console.log('Created at:', response.createdAt);
+  } catch (error) {
+    // Check if it's an authentication error
+    if (isAuthError(error)) {
+      console.error('Authentication required. Attempting to authorize...');
+      const authorized = await authorizeNearAccount();
+      if (authorized) {
+        // Retry the operation
+        return createPost();
+      }
+    } else {
+      // Handle other error types
+      console.error('Error creating post:', error);
+      if (error instanceof ApiError) {
+        console.error('Error code:', error.code);
+        console.error('Status:', error.status);
+        console.error('Details:', error.details);
+        console.error('Recoverable:', error.recoverable);
+      } else if (error instanceof PlatformError) {
+        console.error('Platform:', error.platform);
+        console.error('Error code:', error.code);
+        console.error('Original error:', error.originalError);
+      }
+    }
+  }
+}
+```
 
-const client = new CrosspostClient({
-  baseUrl: 'https://your-crosspost-api.com',
-  nearAuthData: nearAuthData,
-});
+## API Reference
+
+### CrosspostClient
+
+```typescript
+constructor(config?: {
+  baseUrl?: string;
+  nearAuthData?: NearAuthData;
+  timeout?: number;
+  retries?: number;
+})
 ```
 
-**3. Explicit Authentication**
+#### Methods
+
+- `setAuthentication(nearAuthData: NearAuthData): Promise<void>` - Sets authentication data
+- `isAuthenticated(): boolean` - Checks if client is authenticated
+
+### Auth API (client.auth)
+
+- `authorizeNearAccount(): Promise<NearAuthorizationResponse>` - Authorizes NEAR account
+- `unauthorizeNearAccount(): Promise<NearAuthorizationResponse>` - Unauthorizes NEAR account
+- `getNearAuthorizationStatus(): Promise<NearAuthorizationResponse>` - Checks authorization status
+- `loginToPlatform(platform, options?): Promise<EnhancedApiResponse<any>>` - Initiates OAuth flow
+- `refreshToken(platform): Promise<EnhancedApiResponse<any>>` - Refreshes platform token
+- `refreshProfile(platform): Promise<EnhancedApiResponse<any>>` - Refreshes user profile
+- `getAuthStatus(platform): Promise<AuthStatusResponse>` - Gets authentication status
+- `revokeAuth(platform): Promise<AuthRevokeResponse>` - Revokes platform access
+- `getConnectedAccounts(): Promise<ConnectedAccountsResponse>` - Lists connected accounts
+
+### Post API (client.post)
+
+- `createPost(request): Promise<CreatePostResponse>` - Creates a new post
+- `repost(request): Promise<RepostResponse>` - Reposts an existing post
+- `quotePost(request): Promise<QuotePostResponse>` - Quotes an existing post
+- `replyToPost(request): Promise<ReplyToPostResponse>` - Replies to a post
+- `likePost(request): Promise<LikePostResponse>` - Likes a post
+- `unlikePost(request): Promise<UnlikePostResponse>` - Unlikes a post
+- `deletePost(request): Promise<DeletePostResponse>` - Deletes a post
+
+### Activity API (client.activity)
+
+- `getLeaderboard(options): Promise<LeaderboardResponse>` - Gets activity leaderboard
+- `getAccountActivity(signerId, options): Promise<AccountActivityResponse>` - Gets account activity
+- `getAccountPosts(signerId, options): Promise<AccountPostsResponse>` - Gets account posts
 
-Initialize the client without authentication and set it later, for example, after a user logs in via
-a NEAR wallet connection. This method also stores the authentication data in the `__crosspost_auth`
-cookie for future use.
+### System API (client.system)
+
+- `getRateLimits(): Promise<RateLimitsResponse>` - Gets all rate limits
+- `getEndpointRateLimit(endpoint): Promise<EndpointRateLimitResponse>` - Gets endpoint rate limit
+- `getHealthStatus(): Promise<HealthStatusResponse>` - Gets API health status
+
+### Error Handling Utilities
 
 ```typescript
-import { CrosspostClient } from '@crosspost/sdk';
-import type { NearAuthData } from 'near-sign-verify';
+import {
+  apiWrapper,
+  enrichErrorWithContext,
+  getErrorDetails,
+  getErrorMessage,
+  isAuthError,
+  isContentError,
+  isMediaError,
+  isNetworkError,
+  isPlatformError,
+  isPostError,
+  isRateLimitError,
+  isRecoverableError,
+  isValidationError,
+} from '@crosspost/sdk';
+
+// Check error types
+if (isAuthError(error)) {
+  // Handle authentication errors
+}
 
-const client = new CrosspostClient({
-  baseUrl: 'https://your-crosspost-api.com',
+// Get user-friendly error message
+const message = getErrorMessage(error, 'Default message');
+
+// Get error details
+const details = getErrorDetails(error);
+
+// Add context to errors
+const enrichedError = enrichErrorWithContext(error, {
+  operation: 'createPost',
+  timestamp: Date.now(),
 });
 
-// Later, after obtaining the signature...
-async function handleAuthentication(nearAuthData: NearAuthData) {
-  try {
-    // This sets the auth data in the client and stores it in the cookie
-    await client.setAuthentication(nearAuthData);
-    console.log('Authentication successful and stored.');
-    // Client is now ready for authenticated requests
-  } catch (error) {
-    console.error('Authentication failed:', error);
-  }
-}
+// Wrap API calls with error handling
+const result = await apiWrapper(
+  async () => {
+    // API call implementation
+    return await fetch('/api/endpoint');
+  },
+  { operation: 'fetchData' }, // Optional context
+);
 ```
 
-### Making Authenticated Requests (Example: Twitter Client)
+## Usage Examples
+
+### Creating a Post
 
 ```typescript
-// Create a post
-const createPostResponse = await client.twitter.createPost({
+// Create a simple text post
+const textPostResponse = await client.post.createPost({
   content: {
     text: 'Hello from Crosspost SDK!',
   },
 });
 
-console.log(`Post created with ID: ${createPostResponse.id}`);
-
 // Create a post with media
-const createPostWithMediaResponse = await client.twitter.createPost({
+const mediaPostResponse = await client.post.createPost({
   content: {
     text: 'Check out this image!',
     media: [
@@ -132,19 +268,23 @@ const createPostWithMediaResponse = await client.twitter.createPost({
     ],
   },
 });
+```
+
+### Post Interactions
 
+```typescript
 // Like a post
-await client.twitter.likePost({
+await client.post.likePost({
   postId: '1234567890',
 });
 
-// Repost a post
-await client.twitter.repost({
+// Repost
+await client.post.repost({
   postId: '1234567890',
 });
 
 // Reply to a post
-await client.twitter.reply({
+await client.post.replyToPost({
   postId: '1234567890',
   content: {
     text: 'This is a reply!',
@@ -152,122 +292,93 @@ await client.twitter.reply({
 });
 
 // Delete a post
-await client.twitter.deletePost({
+await client.post.deletePost({
   postId: '1234567890',
 });
 ```
 
-### Error Handling
+### Getting Activity Data
 
 ```typescript
-import { ApiError, ApiErrorCode, CrosspostClient, PlatformError } from '@crosspost/sdk';
-
-try {
-  // Ensure client is authenticated (either via cookie or direct data)
-  const response = await client.post.createPost({ // Assuming a generic post API exists
-    targets: [{ platform: 'twitter', userId: 'twitter_user_id' }], // Example target
-    content: {
-      text: 'Hello from Crosspost SDK!',
-    },
-  });
-
-  console.log(`Post created with ID: ${response.id}`);
-} catch (error) {
-  if (error instanceof ApiError) {
-    // Handle authentication errors
-    if (error.code === ApiErrorCode.UNAUTHORIZED) {
-      console.error('Authentication required. Please sign in with your NEAR wallet.');
-      // Redirect to authentication flow or show login UI
-    } else {
-      console.error(`API Error: ${error.message}`);
-      console.error(`Error Code: ${error.code}`); // e.g., RATE_LIMITED
-      console.error(`Status: ${error.status}`); // HTTP status code
-      console.error(`Details:`, error.details); // Additional context
-      console.error(`Recoverable: ${error.recoverable}`);
-    }
-  } else if (error instanceof PlatformError) {
-    // Handle errors specific to a platform (e.g., Twitter API error)
-    console.error(`Platform Error (${error.platform}): ${error.message}`);
-    console.error(`Original Error:`, error.originalError);
-  } else {
-    console.error(`Unexpected error:`, error);
-  }
-}
-```
-
-## API Reference
+// Get leaderboard
+const leaderboard = await client.activity.getLeaderboard({
+  timeframe: 'week',
+  limit: 10,
+});
 
-### `CrosspostClient`
+// Get account activity
+const activity = await client.activity.getAccountActivity('user.near', {
+  timeframe: 'month',
+});
 
-The main client for interacting with the Crosspost API.
+// Get account posts
+const posts = await client.activity.getAccountPosts('user.near', {
+  limit: 20,
+  offset: 0,
+});
+```
 
-#### Constructor
+### Checking Rate Limits
 
 ```typescript
-constructor(config?: CrosspostClientConfig)
-```
+// Get all rate limits
+const rateLimits = await client.system.getRateLimits();
 
-`CrosspostClientConfig` Options:
+// Get rate limit for a specific endpoint
+const postRateLimit = await client.system.getEndpointRateLimit('post');
+```
 
-- `baseUrl?: string`: Base URL of the Crosspost API. Defaults to the official endpoint.
-- `nearAuthData?: NearAuthData`: NEAR authentication data object. If not provided, the client
-  attempts to load from the `__crosspost_auth` cookie.
-- `timeout?: number`: Request timeout in milliseconds (default: 30000).
-- `retries?: number`: Number of retries for failed requests (network/5xx errors) (default: 2).
+## Authentication and Security
 
-#### Methods
+### Authentication Strategies
 
-- `setAuthentication(nearAuthData: NearAuthData): Promise<void>`: Sets the provided `NearAuthData`
-  in the client and stores it in the `__crosspost_auth` cookie for future use.
+The SDK supports two authentication strategies:
 
-#### Properties
+1. **Direct Authentication**: Provide `nearAuthData` directly in the constructor.
+   ```typescript
+   const client = new CrosspostClient({
+     nearAuthData: {
+       accountId: 'your-account.near',
+       publicKey: 'ed25519:...',
+       signature: '...',
+       message: '...',
+     },
+   });
+   ```
 
-- `auth`: Instance of `AuthApi` for authentication-related operations.
-- `post`: Instance of `PostApi` for post-related operations.
+2. **Cookie-Based Authentication**: Automatically read/write authentication data from a secure
+   cookie.
+   ```typescript
+   // Initialize without auth data (will check for cookie)
+   const client = new CrosspostClient();
 
-### API Modules
+   // Set authentication (also stores in cookie)
+   client.setAuthentication(nearAuthData);
+   ```
 
-#### `AuthApi` (`client.auth`)
+### Cookie Security
 
-- `authorizeNearAccount(): Promise<NearAuthorizationResponse>`: Authorizes the current NEAR account
-  (requires `nearAuthData` to be set).
-- `getNearAuthorizationStatus(): Promise<NearAuthorizationResponse>`: Checks if the current NEAR
-  account is authorized.
-- `loginToPlatform(platform, options?): Promise<EnhancedApiResponse<any>>`: Initiates the OAuth
-  login flow for a platform.
-- `refreshToken(platform): Promise<EnhancedApiResponse<any>>`: Refreshes the platform token.
-- `refreshProfile(platform): Promise<EnhancedApiResponse<any>>`: Refreshes the user's profile from
-  the platform.
-- `getAuthStatus(platform): Promise<AuthStatusResponse>`: Gets the authentication status for a
-  specific platform.
-- `revokeAuth(platform): Promise<AuthRevokeResponse>`: Revokes access for a specific platform.
-- `getConnectedAccounts(): Promise<ConnectedAccountsResponse>`: Lists all platform accounts
-  connected to the NEAR account.
+When using cookie-based authentication, the SDK stores authentication data in a secure cookie with
+the following settings:
 
-#### `PostApi` (`client.post`)
-
-- `createPost(request: CreatePostRequest): Promise<CreatePostResponse>`: Creates a new post.
-- `repost(request: RepostRequest): Promise<RepostResponse>`: Reposts an existing post.
-- `quotePost(request: QuotePostRequest): Promise<QuotePostResponse>`: Quotes an existing post.
-- `replyToPost(request: ReplyToPostRequest): Promise<ReplyToPostResponse>`: Replies to an existing
-  post.
-- `likePost(request: LikePostRequest): Promise<LikePostResponse>`: Likes a post.
-- `unlikePost(request: UnlikePostRequest): Promise<UnlikePostResponse>`: Unlikes a post.
-- `deletePost(request: DeletePostRequest): Promise<DeletePostResponse>`: Deletes one or more posts.
+- **Name**: `__crosspost_auth`
+- **Secure**: `true` (only sent over HTTPS)
+- **SameSite**: `Lax` (sent with same-site requests and top-level navigations)
+- **Path**: `/` (available across the entire domain)
+- **Expires**: 30 days
 
 ### CSRF Protection
 
-The SDK supports the Double Submit Cookie pattern for CSRF protection:
-
-1. The backend API sets a CSRF token in a non-HttpOnly cookie named `XSRF-TOKEN`
-2. The SDK automatically reads this token and includes it in the `X-CSRF-Token` header for all
-   state-changing requests (non-GET)
-3. The backend API validates that the token in the header matches the token in the cookie
+The SDK implements CSRF protection for state-changing requests (non-GET) using the Double Submit
+Cookie pattern:
 
-This protection is automatically enabled when the backend API is configured to use CSRF tokens.
+1. The backend API sets a CSRF token in a non-HttpOnly cookie (`XSRF-TOKEN`)
+2. The SDK reads this token and includes it in the `X-CSRF-Token` header for all state-changing
+   requests
+3. The backend validates that the token in the header matches the token in the cookie
 
-_(Note: Specific platform clients like `client.twitter` might be deprecated in favor of using the
-generic `client.post` API with platform targets specified in the request body.)_
+This protection is automatically enabled when using cookie-based authentication and requires no
+additional configuration from the client side.
 
 ## License