@crosspost/sdk/dist/index.d.ts

SDK for interacting with the Crosspost API

import { ActivityLeaderboardQuery, ApiResponse, ActivityLeaderboardResponse, AccountActivityQuery, AccountActivityResponse, AccountPostsQuery, AccountPostsResponse, NearAuthorizationResponse, Platform, AuthInitRequest, AuthCallbackResponse, AuthUrlResponse, ConnectedAccount, AuthStatusResponse, NearUnauthorizationResponse, AuthRevokeResponse, ConnectedAccountsResponse, CreatePostRequest, MultiStatusData, RepostRequest, QuotePostRequest, ReplyToPostRequest, LikePostRequest, UnlikePostRequest, DeletePostRequest, RateLimitResponse, EndpointRateLimitResponse, HealthStatus, ApiErrorCode, StatusCode, ErrorDetails } from '@crosspost/types';

/**
 * Options for making a request to the API
 */
interface RequestOptions {
    /**
     * Base URL for the API
     */
    baseUrl: URL;
    /**
     * Auth token from near-sign-verify
     */
    authToken?: string;
    /**
     * NEAR account ID for simple GET request authentication
     */
    accountId?: string;
    /**
     * Request timeout in milliseconds
     */
    timeout: number;
}

/**
 * Activity-related API operations
 */
declare class ActivityApi {
    private options;
    /**
     * Creates an instance of ActivityApi
     * @param options Request options
     */
    constructor(options: RequestOptions);
    /**
     * Gets the global activity leaderboard
     * @param query Optional query parameters
     * @returns A promise resolving with the leaderboard response
     */
    getLeaderboard(query?: ActivityLeaderboardQuery): Promise<ApiResponse<ActivityLeaderboardResponse>>;
    /**
     * Gets activity for a specific account
     * @param signerId The NEAR account ID
     * @param query Optional query parameters
     * @returns A promise resolving with the account activity response
     */
    getAccountActivity(signerId: string, query?: AccountActivityQuery): Promise<ApiResponse<AccountActivityResponse>>;
    /**
     * Gets posts for a specific account
     * @param signerId The NEAR account ID
     * @param query Optional query parameters
     * @returns A promise resolving with the account posts response
     */
    getAccountPosts(signerId: string, query?: AccountPostsQuery): Promise<ApiResponse<AccountPostsResponse>>;
}

/**
 * Authentication-related API operations
 */
declare class AuthApi {
    private options;
    /**
     * Creates an instance of AuthApi
     * @param options Request options
     */
    constructor(options: RequestOptions);
    /**
     * Authorizes the NEAR account associated with the provided authToken with the Crosspost service.
     * @returns A promise resolving with the authorization response.
     */
    authorizeNearAccount(): Promise<ApiResponse<NearAuthorizationResponse>>;
    /**
     * Checks the authorization status of the NEAR account with the Crosspost service.
     * @returns A promise resolving with the authorization status response.
     */
    getNearAuthorizationStatus(): Promise<ApiResponse<NearAuthorizationResponse>>;
    /**
     * Initiates the login process for a specific platform using a popup window.
     * @param platform The target platform.
     * @param options Optional success and error redirect URLs.
     * @returns Promise that resolves with the authentication result when the popup completes.
     * @throws Error if popups are blocked or if running in a non-browser environment.
     */
    loginToPlatform(platform: Platform, options?: AuthInitRequest): Promise<AuthCallbackResponse | ApiResponse<AuthUrlResponse>>;
    /**
     * Refreshes the authentication token for the specified platform.
     * @param platform The target platform.
     * @returns A promise resolving with the refresh response containing updated auth details.
     */
    refreshToken(platform: Platform, userId: string): Promise<ApiResponse<AuthCallbackResponse>>;
    /**
     * Refreshes the user's profile information from the specified platform.
     * @param platform The target platform.
     * @param userId The user ID on the platform
     * @returns A promise resolving with the updated account profile information.
     */
    refreshProfile(platform: Platform, userId: string): Promise<ApiResponse<ConnectedAccount>>;
    /**
     * Gets the authentication status for the specified platform.
     * @param platform The target platform.
     * @returns A promise resolving with the authentication status response.
     */
    getAuthStatus(platform: Platform, userId: string): Promise<ApiResponse<AuthStatusResponse>>;
    /**
     * Unauthorizes a NEAR account from using the service
     * @returns A promise resolving with the unauthorized response
     */
    unauthorizeNear(): Promise<ApiResponse<NearUnauthorizationResponse>>;
    /**
     * Revokes the authentication token for the specified platform.
     * @param platform The target platform.
     * @returns A promise resolving with the revocation response.
     */
    revokeAuth(platform: Platform, userId: string): Promise<ApiResponse<AuthRevokeResponse>>;
    /**
     * Lists all accounts connected to the NEAR account.
     * @returns A promise resolving with the connected accounts response containing an array of accounts.
     * @throws {CrosspostError} If the request fails or returns invalid data.
     */
    getConnectedAccounts(): Promise<ApiResponse<ConnectedAccountsResponse>>;
}

/**
 * Post-related API operations
 */
declare class PostApi {
    private options;
    /**
     * Creates an instance of PostApi
     * @param options Request options
     */
    constructor(options: RequestOptions);
    /**
     * Creates a new post on the specified target platforms.
     * @param request The post creation request details.
     * @returns A promise resolving with the post creation response.
     */
    createPost(request: CreatePostRequest): Promise<ApiResponse<MultiStatusData>>;
    /**
     * Reposts an existing post on the specified target platforms.
     * @param request The repost request details.
     * @returns A promise resolving with the repost response.
     */
    repost(request: RepostRequest): Promise<ApiResponse<MultiStatusData>>;
    /**
     * Quotes an existing post on the specified target platforms.
     * @param request The quote post request details.
     * @returns A promise resolving with the quote post response.
     */
    quotePost(request: QuotePostRequest): Promise<ApiResponse<MultiStatusData>>;
    /**
     * Replies to an existing post on the specified target platforms.
     * @param request The reply request details.
     * @returns A promise resolving with the reply response.
     */
    replyToPost(request: ReplyToPostRequest): Promise<ApiResponse<MultiStatusData>>;
    /**
     * Likes a post on the specified target platforms.
     * @param request The like request details.
     * @returns A promise resolving with the like response.
     */
    likePost(request: LikePostRequest): Promise<ApiResponse<MultiStatusData>>;
    /**
     * Unlikes a post on the specified target platforms.
     * @param request The unlike request details.
     * @returns A promise resolving with the unlike response.
     */
    unlikePost(request: UnlikePostRequest): Promise<ApiResponse<MultiStatusData>>;
    /**
     * Deletes one or more posts.
     * @param request The delete request details.
     * @returns A promise resolving with the delete response.
     */
    deletePost(request: DeletePostRequest): Promise<ApiResponse<MultiStatusData>>;
}

/**
 * System-related API operations
 * Includes rate limits, health checks, and other system-related functionality
 */
declare class SystemApi {
    private options;
    /**
     * Creates an instance of SystemApi
     * @param options Request options
     */
    constructor(options: RequestOptions);
    /**
     * Gets the current rate limit status
     * @returns A promise resolving with the rate limit response
     */
    getRateLimits(): Promise<ApiResponse<RateLimitResponse>>;
    /**
     * Gets the rate limit status for a specific endpoint
     * @param endpoint The endpoint to get rate limit for
     * @returns A promise resolving with the endpoint rate limit response
     */
    getEndpointRateLimit(endpoint: string): Promise<ApiResponse<EndpointRateLimitResponse>>;
    /**
     * Gets the health status of the API
     * @returns A promise resolving with the health status
     */
    getHealthStatus(): Promise<ApiResponse<HealthStatus>>;
}

/**
 * Configuration options for the CrosspostClient
 */
interface CrosspostClientConfig {
    /**
     * Base URL for the Crosspost API
     * @default 'https://api.opencrosspost.com/'
     */
    baseUrl?: string | URL;
    /**
     * Auth token, obtained by near-sign-verify
     */
    authToken?: string;
    /**
     * Request timeout in milliseconds
     * @default 30000
     */
    timeout?: number;
}

/**
 * Main client for interacting with the Crosspost API service.
 */
declare class CrosspostClient {
    readonly auth: AuthApi;
    readonly post: PostApi;
    readonly activity: ActivityApi;
    readonly system: SystemApi;
    private readonly options;
    /**
     * Creates an instance of CrosspostClient.
     * @param config Configuration options for the client.
     */
    constructor(config?: CrosspostClientConfig);
    /**
     * Sets the authentication data (signature) for the client
     * Required for non-GET requests
     * @param authToken The NEAR authentication data
     */
    setAuthentication(authToken: string): void;
    /**
     * Sets the NEAR account ID for simplified GET request authentication
     * @param accountId The NEAR account ID
     */
    setAccountHeader(accountId: string): void;
    /**
     * Checks if authentication data (signature) exists on client
     * @returns true if authToken is set (required for non-GET requests)
     */
    isAuthenticated(): boolean;
    /**
     * Clears all authentication data from the client
     * This will prevent all requests from working until new authentication is set
     */
    clear(): void;
}

/**
 * CrosspostError class for SDK error handling
 */
declare class CrosspostError extends Error {
    readonly code: ApiErrorCode;
    readonly status: StatusCode;
    readonly details?: ErrorDetails;
    readonly recoverable: boolean;
    constructor(message: string, code: ApiErrorCode, status: StatusCode, details?: ErrorDetails, recoverable?: boolean);
    /**
     * Get platform from details if available
     */
    get platform(): string | undefined;
    /**
     * Get userId from details if available
     */
    get userId(): string | undefined;
}
/**
 * Check if an error is an authentication error
 */
declare function isAuthError(error: unknown): boolean;
/**
 * Check if an error is a validation error
 */
declare function isValidationError(error: unknown): boolean;
/**
 * Check if an error is a network error
 */
declare function isNetworkError(error: unknown): boolean;
/**
 * Check if an error is a platform error
 */
declare function isPlatformError(error: unknown): boolean;
/**
 * Check if an error is a content policy error
 */
declare function isContentError(error: unknown): boolean;
/**
 * Check if an error is a rate limit error
 */
declare function isRateLimitError(error: unknown): boolean;
/**
 * Check if an error is a post-related error
 */
declare function isPostError(error: unknown): boolean;
/**
 * Check if an error is a media-related error
 */
declare function isMediaError(error: unknown): boolean;
/**
 * Check if an error is recoverable
 */
declare function isRecoverableError(error: unknown): boolean;
/**
 * Get a user-friendly error message
 */
declare function getErrorMessage(error: unknown, defaultMessage?: string): string;
/**
 * Get error details if available
 */
declare function getErrorDetails(error: unknown): ErrorDetails | undefined;

export { ActivityApi, AuthApi, CrosspostClient, type CrosspostClientConfig, CrosspostError, PostApi, SystemApi, getErrorDetails, getErrorMessage, isAuthError, isContentError, isMediaError, isNetworkError, isPlatformError, isPostError, isRateLimitError, isRecoverableError, isValidationError };