@crosspost/sdk 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Open Crosspost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,273 +2,376 @@
 
 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 (authentication can be provided later)
 const client = new CrosspostClient({
   baseUrl: 'https://your-crosspost-api.com', // Optional: Defaults to official API
 });
 
-// If the cookie exists and is valid, requests will be authenticated.
-// If not, authenticated requests will throw an ApiError.
-```
+// Set authentication with fresh signature for the request
+client.setAuthentication({
+  accountId: 'your-account.near',
+  publicKey: 'ed25519:...',
+  signature: '...',
+  message: '...',
+});
+
+// Check if client has authentication data set
+if (client.isAuthenticated()) {
+  console.log('Client has authentication data');
+}
 
-The cookie is stored with secure attributes:
+// 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;
+  }
+}
+
+// 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;
+  }
+}
+
+// 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;
+  }
+}
 
-- `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
+// Example usage
+async function createPost() {
+  try {
+    const response = await client.post.createPost({
+      targets: [{ platform: 'twitter', userId: 'your-twitter-id' }],
+      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);
+      }
+    }
+  }
+}
+```
 
-**2. Direct Authentication**
+## API Reference
 
-Provide the `nearAuthData` object directly if you have obtained it through other means (e.g.,
-server-side flow, manual signing).
+### CrosspostClient
 
 ```typescript
-import { CrosspostClient } from '@crosspost/sdk';
-import type { NearAuthData } from 'near-sign-verify'; // Assuming this type exists
+constructor(config?: {
+  baseUrl?: string;
+  nearAuthData?: NearAuthData;
+  timeout?: number;
+  retries?: number;
+})
+```
 
-const nearAuthData: NearAuthData = {
-  account_id: 'example.near',
-  public_key: 'ed25519:...',
-  signature: '...',
-  message: '...',
-  nonce: '...',
-  recipient: 'crosspost-api.near',
-  // callback_url and state are optional
-};
+#### Methods
 
-const client = new CrosspostClient({
-  baseUrl: 'https://your-crosspost-api.com',
-  nearAuthData: nearAuthData,
-});
-```
+- `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)
+
+Each post operation accepts a request object that includes:
+
+- `targets`: Array of `{ platform: string, userId: string }` specifying where to perform the action
+- Additional parameters specific to each operation
+
+Available methods:
+
+- `createPost(request: CreatePostRequest): Promise<CreatePostResponse>` - Creates posts on specified
+  platforms
+- `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 a post
+- `likePost(request: LikePostRequest): Promise<LikePostResponse>` - Likes a post
+- `unlikePost(request: UnlikePostRequest): Promise<UnlikePostResponse>` - Unlikes a post
+- `deletePost(request: DeletePostRequest): Promise<DeletePostResponse>` - Deletes posts
+
+### Activity API (client.activity)
 
-**3. Explicit Authentication**
+- `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({
-  content: {
+// Create a text post on Twitter
+const textPostResponse = await client.post.createPost({
+  targets: [{
+    platform: 'twitter',
+    userId: 'your-twitter-id',
+  }],
+  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({
-  content: {
+// Create a post with media on multiple platforms
+const mediaPostResponse = await client.post.createPost({
+  targets: [
+    { platform: 'twitter', userId: 'your-twitter-id' },
+    { platform: 'facebook', userId: 'your-facebook-id' },
+  ],
+  content: [{
     text: 'Check out this image!',
-    media: [
-      {
-        type: 'image',
-        url: 'https://example.com/image.jpg',
-      },
-    ],
-  },
+    media: [{
+      data: imageBlob,
+      mimeType: 'image/jpeg',
+      altText: 'A beautiful sunset',
+    }],
+  }],
 });
+```
 
-// Like a post
-await client.twitter.likePost({
+### Post Interactions
+
+```typescript
+// Like a post on Twitter
+await client.post.likePost({
+  targets: [{
+    platform: 'twitter',
+    userId: 'your-twitter-id',
+  }],
+  platform: 'twitter',
   postId: '1234567890',
 });
 
-// Repost a post
-await client.twitter.repost({
+// Repost on multiple platforms
+await client.post.repost({
+  targets: [
+    { platform: 'twitter', userId: 'your-twitter-id' },
+    { platform: 'facebook', userId: 'your-facebook-id' },
+  ],
+  platform: 'twitter',
   postId: '1234567890',
 });
 
 // Reply to a post
-await client.twitter.reply({
+await client.post.replyToPost({
+  targets: [{
+    platform: 'twitter',
+    userId: 'your-twitter-id',
+  }],
+  platform: 'twitter',
   postId: '1234567890',
-  content: {
+  content: [{
     text: 'This is a reply!',
-  },
+  }],
 });
 
-// Delete a post
-await client.twitter.deletePost({
-  postId: '1234567890',
+// Delete posts
+await client.post.deletePost({
+  targets: [{
+    platform: 'twitter',
+    userId: 'your-twitter-id',
+  }],
+  posts: [{
+    platform: 'twitter',
+    userId: 'your-twitter-id',
+    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
-
-### `CrosspostClient`
-
-The main client for interacting with the Crosspost API.
+// Get leaderboard
+const leaderboard = await client.activity.getLeaderboard({
+  timeframe: 'week',
+  limit: 10,
+});
 
-#### Constructor
+// Get account activity
+const activity = await client.activity.getAccountActivity('user.near', {
+  timeframe: 'month',
+});
 
-```typescript
-constructor(config?: CrosspostClientConfig)
+// Get account posts
+const posts = await client.activity.getAccountPosts('user.near', {
+  limit: 20,
+  offset: 0,
+});
 ```
 
-`CrosspostClientConfig` Options:
-
-- `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).
-
-#### Methods
-
-- `setAuthentication(nearAuthData: NearAuthData): Promise<void>`: Sets the provided `NearAuthData`
-  in the client and stores it in the `__crosspost_auth` cookie for future use.
-
-#### Properties
-
-- `auth`: Instance of `AuthApi` for authentication-related operations.
-- `post`: Instance of `PostApi` for post-related operations.
-
-### API Modules
+### Checking Rate Limits
 
-#### `AuthApi` (`client.auth`)
-
-- `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.
-
-#### `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.
-
-### CSRF Protection
+```typescript
+// Get all rate limits
+const rateLimits = await client.system.getRateLimits();
 
-The SDK supports the Double Submit Cookie pattern for CSRF protection:
+// Get rate limit for a specific endpoint
+const postRateLimit = await client.system.getEndpointRateLimit('post');
+```
 
-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
+## Authentication and Security
 
-This protection is automatically enabled when the backend API is configured to use CSRF tokens.
+### Authentication Strategy
 
-_(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.)_
+The SDK uses direct authentication with per-request signatures:
 
-## License
+```typescript
+// Initialize the client
+const client = new CrosspostClient({
+  baseUrl: 'https://your-crosspost-api.com',
+});
 
-MIT
+// Before making authenticated requests, set fresh signature
+client.setAuthentication({
+  accountId: 'your-account.near',
+  publicKey: 'ed25519:...',
+  signature: '...',
+  message: '...',
+});
+```