@crosspost/sdk 0.1.2 → 0.1.3

package/src/api/activity.ts

@@ -0,0 +1,77 @@
+import type {
+  AccountActivityQuery,
+  AccountActivityResponse,
+  AccountPostsQuery,
+  AccountPostsResponse,
+  ActivityLeaderboardQuery,
+  ActivityLeaderboardResponse,
+} from '@crosspost/types';
+import { makeRequest, type RequestOptions } from '../core/request.ts';
+
+/**
+ * Activity-related API operations
+ */
+export class ActivityApi {
+  private options: RequestOptions;
+
+  /**
+   * Creates an instance of ActivityApi
+   * @param options Request options
+   */
+  constructor(options: RequestOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Gets the global activity leaderboard
+   * @param query Optional query parameters
+   * @returns A promise resolving with the leaderboard response
+   */
+  async getLeaderboard(query?: ActivityLeaderboardQuery): Promise<ActivityLeaderboardResponse> {
+    return makeRequest<ActivityLeaderboardResponse>(
+      'GET',
+      '/api/activity',
+      this.options,
+      undefined,
+      query,
+    );
+  }
+
+  /**
+   * 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
+   */
+  async getAccountActivity(
+    signerId: string,
+    query?: AccountActivityQuery,
+  ): Promise<AccountActivityResponse> {
+    return makeRequest<AccountActivityResponse>(
+      'GET',
+      `/api/activity/${signerId}`,
+      this.options,
+      undefined,
+      query,
+    );
+  }
+
+  /**
+   * 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
+   */
+  async getAccountPosts(
+    signerId: string,
+    query?: AccountPostsQuery,
+  ): Promise<AccountPostsResponse> {
+    return makeRequest<AccountPostsResponse>(
+      'GET',
+      `/api/activity/${signerId}/posts`,
+      this.options,
+      undefined,
+      query,
+    );
+  }
+}

package/src/api/system.ts

@@ -0,0 +1,55 @@
+import type { EndpointRateLimitResponse, RateLimitResponse } from '@crosspost/types';
+import { makeRequest, type RequestOptions } from '../core/request.ts';
+
+/**
+ * System-related API operations
+ * Includes rate limits, health checks, and other system-related functionality
+ */
+export class SystemApi {
+  private options: RequestOptions;
+
+  /**
+   * Creates an instance of SystemApi
+   * @param options Request options
+   */
+  constructor(options: RequestOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Gets the current rate limit status
+   * @returns A promise resolving with the rate limit response
+   */
+  async getRateLimits(): Promise<RateLimitResponse> {
+    return makeRequest<RateLimitResponse>(
+      'GET',
+      '/api/rate-limit',
+      this.options,
+    );
+  }
+
+  /**
+   * 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
+   */
+  async getEndpointRateLimit(endpoint: string): Promise<EndpointRateLimitResponse> {
+    return makeRequest<EndpointRateLimitResponse>(
+      'GET',
+      `/api/rate-limit/${endpoint}`,
+      this.options,
+    );
+  }
+
+  /**
+   * Gets the health status of the API
+   * @returns A promise resolving with the health status
+   */
+  async getHealthStatus(): Promise<{ status: string }> {
+    return makeRequest<{ status: string }>(
+      'GET',
+      '/health',
+      this.options,
+    );
+  }
+}

package/src/core/client.ts

@@ -1,6 +1,8 @@
-import type { NearAuthData as NearSignatureData } from 'near-sign-verify';
+import type { NearAuthData } from 'near-sign-verify';
+import { ActivityApi } from '../api/activity.ts';
 import { AuthApi } from '../api/auth.ts';
 import { PostApi } from '../api/post.ts';
+import { SystemApi } from '../api/system.ts';
 import { type CrosspostClientConfig, DEFAULT_CONFIG } from './config.ts';
 import type { RequestOptions } from './request.ts';
 import { getAuthFromCookie, storeAuthInCookie } from '../utils/cookie.ts';
@@ -9,15 +11,10 @@ import { getAuthFromCookie, storeAuthInCookie } from '../utils/cookie.ts';
  * Main client for interacting with the Crosspost API service.
  */
 export class CrosspostClient {
-  /**
-   * Authentication-related API operations
-   */
   public readonly auth: AuthApi;
-
-  /**
-   * Post-related API operations
-   */
   public readonly post: PostApi;
+  public readonly activity: ActivityApi;
+  public readonly system: SystemApi;
 
   private readonly options: RequestOptions;
 
@@ -30,29 +27,35 @@ export class CrosspostClient {
     const timeout = config.timeout || DEFAULT_CONFIG.timeout;
     const retries = config.retries ?? DEFAULT_CONFIG.retries;
 
-    // Try to get auth data from config or cookie
-    const signature = config.signature || getAuthFromCookie();
+    const nearAuthData = config.nearAuthData || getAuthFromCookie();
 
     this.options = {
       baseUrl,
       timeout,
       retries,
-      signature,
+      nearAuthData,
     };
 
     this.auth = new AuthApi(this.options);
     this.post = new PostApi(this.options);
+    this.activity = new ActivityApi(this.options);
+    this.system = new SystemApi(this.options);
   }
 
   /**
    * Sets the authentication data (signature) for the client and stores it in a cookie
    * @param signature The NEAR authentication data
    */
-  public async setAuthentication(signature: NearSignatureData): Promise<void> {
-    // Update the client's auth data
-    this.options.signature = signature;
+  public setAuthentication(nearAuthData: NearAuthData): void {
+    this.options.nearAuthData = nearAuthData;
+    storeAuthInCookie(nearAuthData);
+  }
 
-    // Store in cookie for persistence
-    storeAuthInCookie(signature);
+  /**
+   * Checks if authentication data (signature) exists on client
+   * @param signature The NEAR authentication data
+   */
+  public isAuthenticated(): boolean {
+    return !!this.options.nearAuthData;
   }
 }

package/src/core/config.ts

@@ -1,4 +1,4 @@
-import type { NearAuthData as NearSignatureData } from 'near-sign-verify';
+import type { NearAuthData } from 'near-sign-verify';
 
 /**
  * Configuration options for the CrosspostClient
@@ -6,13 +6,13 @@ import type { NearAuthData as NearSignatureData } from 'near-sign-verify';
 export interface CrosspostClientConfig {
   /**
    * Base URL for the Crosspost API
-   * @default 'https://api.opencrosspost.com'
+   * @default 'https://open-crosspost-proxy.deno.dev'
    */
   baseUrl?: string;
   /**
    * NEAR authentication data obtained from near-sign-verify
    */
-  signature?: NearSignatureData;
+  nearAuthData?: NearAuthData;
   /**
    * Request timeout in milliseconds
    * @default 30000
@@ -28,7 +28,7 @@ export interface CrosspostClientConfig {
 /**
  * Default configuration values for the CrosspostClient
  */
-export const DEFAULT_CONFIG: Required<Omit<CrosspostClientConfig, 'signature'>> = {
+export const DEFAULT_CONFIG: Required<Omit<CrosspostClientConfig, 'nearAuthData'>> = {
   baseUrl: 'https://open-crosspost-proxy.deno.dev/',
   timeout: 30000,
   retries: 2,

package/src/core/request.ts

@@ -1,6 +1,7 @@
 import { ApiError, ApiErrorCode } from '@crosspost/types';
-import { createAuthToken, type NearAuthData as NearSignatureData } from 'near-sign-verify';
+import { createAuthToken, type NearAuthData } from 'near-sign-verify';
 import { createNetworkError, handleErrorResponse } from '../utils/error.ts';
+import { apiWrapper, enrichErrorWithContext } from '../utils/error-utils.ts';
 import { CSRF_HEADER_NAME, getCsrfToken } from '../utils/cookie.ts';
 
 /**
@@ -15,7 +16,7 @@ export interface RequestOptions {
    * NEAR authentication data for generating auth tokens
    * Can be undefined if not authorize yet
    */
-  signature?: NearSignatureData;
+  nearAuthData?: NearAuthData;
   /**
    * Request timeout in milliseconds
    */
@@ -40,119 +41,144 @@ export async function makeRequest<T>(
   path: string,
   options: RequestOptions,
   data?: any,
+  query?: Record<string, any>,
 ): Promise<T> {
-  const url = `${options.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-  let lastError: Error | null = null;
-
+  let url = `${options.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+
+  // Add query parameters if provided
+  if (query && Object.keys(query).length > 0) {
+    const queryParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) {
+        queryParams.append(key, String(value));
+      }
+    }
+    const queryString = queryParams.toString();
+    if (queryString) {
+      url += `?${queryString}`;
+    }
+  }
   // Check if authentication data is available
-  if (!options.signature) {
+  if (!options.nearAuthData) {
     throw ApiError.unauthorized('Authentication required. Please provide NEAR signature.');
   }
 
-  for (let attempt = 0; attempt <= options.retries; attempt++) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), options.timeout);
-
-    try {
-      const headers: Record<string, string> = {
-        'Content-Type': 'application/json',
-        'Accept': 'application/json',
-        'Authorization': `Bearer ${createAuthToken(options.signature)}`,
-      };
-
-      // Add CSRF token for state-changing requests (non-GET)
-      if (method !== 'GET') {
-        const csrfToken = getCsrfToken();
-        if (csrfToken) {
-          headers[CSRF_HEADER_NAME] = csrfToken;
-        }
-      }
+  // Create a context object for error enrichment
+  const context = {
+    method,
+    path,
+    url,
+    retries: options.retries,
+  };
 
-      const requestOptions: RequestInit = {
-        method,
-        headers,
-        body: method !== 'GET' && data ? JSON.stringify(data) : undefined,
-        signal: controller.signal,
-      };
+  return apiWrapper(async () => {
+    let lastError: Error | null = null;
 
-      const response = await fetch(url, requestOptions);
-      clearTimeout(timeoutId); // Clear timeout if fetch completes
+    for (let attempt = 0; attempt <= options.retries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), options.timeout);
 
-      let responseData: any;
       try {
-        responseData = await response.json();
-      } catch (jsonError) {
-        // If JSON parsing fails, throw a specific error or handle based on status
-        if (!response.ok) {
+        const headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+          'Authorization': `Bearer ${createAuthToken(options.nearAuthData!)}`,
+        };
+
+        // Add CSRF token for state-changing requests (non-GET)
+        if (method !== 'GET') {
+          const csrfToken = getCsrfToken();
+          if (csrfToken) {
+            headers[CSRF_HEADER_NAME] = csrfToken;
+          }
+        }
+
+        const requestOptions: RequestInit = {
+          method,
+          headers,
+          body: method !== 'GET' && data ? JSON.stringify(data) : undefined,
+          signal: controller.signal,
+        };
+
+        const response = await fetch(url, requestOptions);
+        clearTimeout(timeoutId); // Clear timeout if fetch completes
+
+        let responseData: any;
+        try {
+          responseData = await response.json();
+        } catch (jsonError) {
+          // If JSON parsing fails, throw a specific error or handle based on status
+          if (!response.ok) {
+            throw new ApiError(
+              `API request failed with status ${response.status} and non-JSON response`,
+              ApiErrorCode.NETWORK_ERROR,
+              response.status as any,
+              { originalStatusText: response.statusText },
+            );
+          }
+          // If response was ok but JSON failed, maybe it was an empty 204 response?
+          if (response.status === 204) return {} as T; // Handle No Content
+          // Otherwise, throw a custom error
           throw new ApiError(
-            `API request failed with status ${response.status} and non-JSON response`,
-            ApiErrorCode.NETWORK_ERROR, // Or a more specific code
+            `Failed to parse JSON response: ${
+              jsonError instanceof Error ? jsonError.message : String(jsonError)
+            }`,
+            ApiErrorCode.INTERNAL_ERROR,
             response.status as any,
-            { originalStatusText: response.statusText },
           );
         }
-        // If response was ok but JSON failed, maybe it was an empty 204 response?
-        if (response.status === 204) return {} as T; // Handle No Content
-        // Otherwise, rethrow JSON parse error or a custom error
-        throw new ApiError(
-          `Failed to parse JSON response: ${
-            jsonError instanceof Error ? jsonError.message : String(jsonError)
-          }`,
-          ApiErrorCode.INTERNAL_ERROR, // Or NETWORK_ERROR?
-          response.status as any,
-        );
-      }
 
-      if (!response.ok) {
-        lastError = handleErrorResponse(responseData, response.status);
-        // Retry only on 5xx errors or potentially recoverable errors if defined
-        const shouldRetry = response.status >= 500 ||
-          (lastError instanceof ApiError && lastError.recoverable);
-        if (shouldRetry && attempt < options.retries) {
-          await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt))); // Exponential backoff
-          continue; // Retry
+        if (!response.ok) {
+          lastError = handleErrorResponse(responseData, response.status);
+          // Retry only on 5xx errors or potentially recoverable errors if defined
+          const shouldRetry = response.status >= 500 ||
+            (lastError instanceof ApiError && lastError.recoverable);
+          if (shouldRetry && attempt < options.retries) {
+            await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt))); // Exponential backoff
+            continue; // Retry
+          }
+          throw lastError; // Throw error if not retrying or retries exhausted
         }
-        throw lastError; // Throw error if not retrying or retries exhausted
-      }
 
-      // Handle cases where API indicates failure within a 2xx response
-      if (
-        responseData && typeof responseData === 'object' && 'success' in responseData &&
-        !responseData.success && responseData.error
-      ) {
-        lastError = handleErrorResponse(responseData, response.status);
-        // Decide if this specific type of "successful" response with an error payload should be retried
-        const shouldRetry = lastError instanceof ApiError && lastError.recoverable;
-        if (shouldRetry && attempt < options.retries) {
+        // Handle cases where API indicates failure within a 2xx response
+        if (
+          responseData && typeof responseData === 'object' && 'success' in responseData &&
+          !responseData.success && responseData.error
+        ) {
+          lastError = handleErrorResponse(responseData, response.status);
+          // Decide if this specific type of "successful" response with an error payload should be retried
+          const shouldRetry = lastError instanceof ApiError && lastError.recoverable;
+          if (shouldRetry && attempt < options.retries) {
+            await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt))); // Exponential backoff
+            continue; // Retry
+          }
+          throw lastError;
+        }
+
+        return responseData as T;
+      } catch (error) {
+        clearTimeout(timeoutId); // Clear timeout on error
+        lastError = error instanceof Error ? error : new Error(String(error)); // Store the error
+
+        // Handle fetch/network errors specifically for retries
+        const isNetworkError = error instanceof TypeError ||
+          (error instanceof DOMException && error.name === 'AbortError');
+        if (isNetworkError && attempt < options.retries) {
           await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt))); // Exponential backoff
-          continue; // Retry
+          continue; // Retry network error
         }
-        throw lastError;
-      }
 
-      return responseData as T; // Success
-    } catch (error) {
-      clearTimeout(timeoutId); // Clear timeout on error
-      lastError = error as Error; // Store the error
-
-      // Handle fetch/network errors specifically for retries
-      const isNetworkError = error instanceof TypeError ||
-        (error instanceof DOMException && error.name === 'AbortError');
-      if (isNetworkError && attempt < options.retries) {
-        await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt))); // Exponential backoff
-        continue; // Retry network error
-      }
+        // If it's not a known ApiError/PlatformError, wrap it
+        if (!(error instanceof ApiError)) {
+          throw createNetworkError(error, url, options.timeout);
+        }
 
-      // If it's not a known ApiError/PlatformError, wrap it
-      if (!(error instanceof ApiError)) {
-        throw createNetworkError(error, url, options.timeout);
+        throw error; // Re-throw known ApiError or final network error
       }
-
-      throw error; // Re-throw known ApiError or final network error
     }
-  }
 
-  // Should not be reachable if retries >= 0, but needed for type safety
-  throw lastError ||
-    new ApiError('Request failed after multiple retries', ApiErrorCode.INTERNAL_ERROR, 500);
+    // Should not be reachable if retries >= 0, but needed for type safety
+    throw lastError ||
+      new ApiError('Request failed after multiple retries', ApiErrorCode.INTERNAL_ERROR, 500);
+  }, context);
 }

package/src/index.ts

@@ -4,15 +4,34 @@
  */
 
 // Export main client
-export { CrosspostClient } from './core/client.js';
-export { CrosspostClientConfig } from './core/config.js';
+export { CrosspostClient } from './core/client.ts';
+export type { CrosspostClientConfig } from './core/config.ts';
 
 // Export API modules for advanced usage
-export { AuthApi } from './api/auth.js';
-export { PostApi } from './api/post.js';
+export { ActivityApi } from './api/activity.ts';
+export { AuthApi } from './api/auth.ts';
+export { PostApi } from './api/post.ts';
+export { SystemApi } from './api/system.ts';
 
 // Export utility functions
-export { createNetworkError, handleErrorResponse } from './utils/error.js';
+export { createNetworkError, handleErrorResponse } from './utils/error.ts';
+export {
+  apiWrapper,
+  enrichErrorWithContext,
+  ERROR_CATEGORIES,
+  getErrorDetails,
+  getErrorMessage,
+  isAuthError,
+  isContentError,
+  isErrorOfCategory,
+  isMediaError,
+  isNetworkError,
+  isPlatformError,
+  isPostError,
+  isRateLimitError,
+  isRecoverableError,
+  isValidationError,
+} from './utils/error-utils.ts';
 export {
   AUTH_COOKIE_NAME,
   AUTH_COOKIE_OPTIONS,
@@ -22,7 +41,7 @@ export {
   getAuthFromCookie,
   getCsrfToken,
   storeAuthInCookie,
-} from './utils/cookie.js';
+} from './utils/cookie.ts';
 
 // Re-export types from @crosspost/types for convenience
 export * from '@crosspost/types';

package/src/utils/cookie.ts

@@ -5,9 +5,25 @@ export const AUTH_COOKIE_NAME = '__crosspost_auth';
 export const CSRF_COOKIE_NAME = 'XSRF-TOKEN';
 export const CSRF_HEADER_NAME = 'X-CSRF-Token';
 
+/**
+ * Checks if the code is running in a Deno environment
+ */
+export const isDeno = (): boolean => { // monorepo builds primarily for Deno
+  // we could expect that frontends in Deno environment will use this package,
+  // and then we can determine auth solution there (ValTown, Smallweb, etc)
+  return typeof (globalThis as any).Deno !== 'undefined';
+};
+
+/**
+ * Checks if the code is running in a browser environment
+ */
+export const isBrowser = (): boolean => {
+  return !isDeno() && typeof globalThis.window !== 'undefined';
+};
+
 export const AUTH_COOKIE_OPTIONS: Cookies.CookieAttributes = {
   secure: true,
-  sameSite: 'lax', // how could we make this none?
+  sameSite: 'lax', // Restrict to same-site and top-level navigation
   path: '/',
   expires: 30, // 30 days
 };
@@ -18,7 +34,7 @@ export const AUTH_COOKIE_OPTIONS: Cookies.CookieAttributes = {
  */
 export function getAuthFromCookie(): NearAuthData | undefined {
   try {
-    if (typeof document === 'undefined') {
+    if (!isBrowser()) {
       return undefined;
     }
 
@@ -40,7 +56,7 @@ export function getAuthFromCookie(): NearAuthData | undefined {
  */
 export function storeAuthInCookie(authData: NearAuthData): void {
   try {
-    if (typeof document === 'undefined') {
+    if (!isBrowser()) {
       return;
     }
 
@@ -55,7 +71,7 @@ export function storeAuthInCookie(authData: NearAuthData): void {
  * Clears the authentication cookie
  */
 export function clearAuthCookie(): void {
-  if (typeof document === 'undefined') {
+  if (!isBrowser()) {
     return;
   }
 
@@ -67,7 +83,7 @@ export function clearAuthCookie(): void {
  * @returns The CSRF token or undefined if not found
  */
 export function getCsrfToken(): string | undefined {
-  if (typeof document === 'undefined') {
+  if (!isBrowser()) {
     return undefined;
   }