@crosspost/sdk 0.1.2

package/mod.ts

@@ -0,0 +1,9 @@
+/**
+ * @crosspost/sdk
+ * SDK for interacting with the Crosspost API
+ *
+ * This is the Deno entry point for the package.
+ */
+
+// Export everything from the source directly
+export * from './src/index.ts';

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@crosspost/sdk",
+  "version": "0.1.2",
+  "description": "SDK for interacting with the Crosspost API",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "mod.ts"
+  ],
+  "scripts": {
+    "build": "npm run build:node",
+    "build:node": "tsup src/index.ts --format cjs,esm --dts",
+    "clean": "rimraf dist",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "crosspost",
+    "sdk",
+    "api",
+    "social-media"
+  ],
+  "author": "crosspost.near",
+  "license": "MIT",
+  "dependencies": {
+    "@types/js-cookie": "^3.0.6",
+    "js-cookie": "^3.0.5",
+    "near-sign-verify": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "eslint": "^8.56.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api/auth.ts

@@ -0,0 +1,132 @@
+import type {
+  AuthRevokeResponse,
+  AuthStatusResponse,
+  ConnectedAccountsResponse,
+  EnhancedApiResponse,
+  NearAuthorizationResponse,
+  Platform,
+} from '@crosspost/types';
+import { makeRequest, type RequestOptions } from '../core/request.ts';
+
+/**
+ * Authentication-related API operations
+ */
+export class AuthApi {
+  private options: RequestOptions;
+
+  /**
+   * Creates an instance of AuthApi
+   * @param options Request options
+   */
+  constructor(options: RequestOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Authorizes the NEAR account associated with the provided nearAuthData with the Crosspost service.
+   * @returns A promise resolving with the authorization response.
+   */
+  async authorizeNearAccount(): Promise<NearAuthorizationResponse> {
+    return makeRequest<NearAuthorizationResponse>(
+      'POST',
+      '/auth/authorize/near',
+      this.options,
+      {},
+    );
+  }
+
+  /**
+   * Checks the authorization status of the NEAR account with the Crosspost service.
+   * @returns A promise resolving with the authorization status response.
+   */
+  async getNearAuthorizationStatus(): Promise<NearAuthorizationResponse> {
+    return makeRequest<NearAuthorizationResponse>(
+      'GET',
+      '/auth/authorize/near/status',
+      this.options,
+    );
+  }
+
+  /**
+   * Initiates the login process for a specific platform.
+   * The service handles the OAuth flow; this method triggers it.
+   * @param platform The target platform.
+   * @param options Optional success and error redirect URLs.
+   * @returns A promise resolving with the response from the service (might indicate success/failure or redirect info).
+   */
+  async loginToPlatform(
+    platform: Platform,
+    options?: { successUrl?: string; errorUrl?: string },
+  ): Promise<EnhancedApiResponse<any>> { // TODO: Refine response type based on actual API
+    return makeRequest<EnhancedApiResponse<any>>(
+      'POST',
+      `/auth/${platform}/login`,
+      this.options,
+      options || {},
+    );
+  }
+
+  /**
+   * Refreshes the authentication token for the specified platform.
+   * @param platform The target platform.
+   * @returns A promise resolving with the refresh response.
+   */
+  async refreshToken(platform: Platform): Promise<EnhancedApiResponse<any>> { // TODO: Refine response type
+    return makeRequest<EnhancedApiResponse<any>>(
+      'POST',
+      `/auth/${platform}/refresh`,
+      this.options,
+    );
+  }
+
+  /**
+   * Refreshes the user's profile information from the specified platform.
+   * @param platform The target platform.
+   * @returns A promise resolving with the profile refresh response.
+   */
+  async refreshProfile(platform: Platform): Promise<EnhancedApiResponse<any>> { // TODO: Refine response type
+    return makeRequest<EnhancedApiResponse<any>>(
+      'POST',
+      `/auth/${platform}/refresh-profile`,
+      this.options,
+    );
+  }
+
+  /**
+   * Gets the authentication status for the specified platform.
+   * @param platform The target platform.
+   * @returns A promise resolving with the authentication status response.
+   */
+  async getAuthStatus(platform: Platform): Promise<AuthStatusResponse> {
+    return makeRequest<AuthStatusResponse>(
+      'GET',
+      `/auth/${platform}/status`,
+      this.options,
+    );
+  }
+
+  /**
+   * Revokes the authentication token for the specified platform.
+   * @param platform The target platform.
+   * @returns A promise resolving with the revocation response.
+   */
+  async revokeAuth(platform: Platform): Promise<AuthRevokeResponse> {
+    return makeRequest<AuthRevokeResponse>(
+      'DELETE',
+      `/auth/${platform}/revoke`,
+      this.options,
+    );
+  }
+
+  /**
+   * Lists all accounts connected to the NEAR account.
+   * @returns A promise resolving with the list of connected accounts.
+   */
+  async getConnectedAccounts(): Promise<ConnectedAccountsResponse> {
+    return makeRequest<ConnectedAccountsResponse>(
+      'GET',
+      '/auth/accounts',
+      this.options,
+    );
+  }
+}

package/src/api/post.ts

@@ -0,0 +1,142 @@
+import type {
+  CreatePostRequest,
+  CreatePostResponse,
+  DeletePostRequest,
+  DeletePostResponse,
+  LikePostRequest,
+  LikePostResponse,
+  QuotePostRequest,
+  QuotePostResponse,
+  ReplyToPostRequest,
+  ReplyToPostResponse,
+  RepostRequest,
+  RepostResponse,
+  UnlikePostRequest,
+  UnlikePostResponse,
+} from '@crosspost/types';
+import { ApiError, ApiErrorCode } from '@crosspost/types';
+import { makeRequest, type RequestOptions } from '../core/request.ts';
+
+/**
+ * Post-related API operations
+ */
+export class PostApi {
+  private options: RequestOptions;
+
+  /**
+   * Creates an instance of PostApi
+   * @param options Request options
+   */
+  constructor(options: RequestOptions) {
+    this.options = options;
+  }
+
+  /**
+   * 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.
+   */
+  async createPost(request: CreatePostRequest): Promise<CreatePostResponse> {
+    return makeRequest<CreatePostResponse>(
+      'POST',
+      '/api/post',
+      this.options,
+      request,
+    );
+  }
+
+  /**
+   * Reposts an existing post on the specified target platforms.
+   * @param request The repost request details.
+   * @returns A promise resolving with the repost response.
+   */
+  async repost(request: RepostRequest): Promise<RepostResponse> {
+    return makeRequest<RepostResponse>(
+      'POST',
+      '/api/post/repost',
+      this.options,
+      request,
+    );
+  }
+
+  /**
+   * 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.
+   */
+  async quotePost(request: QuotePostRequest): Promise<QuotePostResponse> {
+    return makeRequest<QuotePostResponse>(
+      'POST',
+      '/api/post/quote',
+      this.options,
+      request,
+    );
+  }
+
+  /**
+   * Replies to an existing post on the specified target platforms.
+   * @param request The reply request details.
+   * @returns A promise resolving with the reply response.
+   */
+  async replyToPost(request: ReplyToPostRequest): Promise<ReplyToPostResponse> {
+    return makeRequest<ReplyToPostResponse>(
+      'POST',
+      '/api/post/reply',
+      this.options,
+      request,
+    );
+  }
+
+  /**
+   * Likes a post on the specified target platforms.
+   * @param request The like request details.
+   * @returns A promise resolving with the like response.
+   */
+  async likePost(request: LikePostRequest): Promise<LikePostResponse> {
+    // API endpoint uses postId in the path
+    return makeRequest<LikePostResponse>(
+      'POST',
+      `/api/post/like/${request.postId}`,
+      this.options,
+      request,
+    );
+  }
+
+  /**
+   * Unlikes a post on the specified target platforms.
+   * @param request The unlike request details.
+   * @returns A promise resolving with the unlike response.
+   */
+  async unlikePost(request: UnlikePostRequest): Promise<UnlikePostResponse> {
+    // API endpoint uses postId in the path
+    return makeRequest<UnlikePostResponse>(
+      'DELETE',
+      `/api/post/like/${request.postId}`,
+      this.options,
+      request,
+    );
+  }
+
+  /**
+   * Deletes one or more posts.
+   * @param request The delete request details.
+   * @returns A promise resolving with the delete response.
+   */
+  async deletePost(request: DeletePostRequest): Promise<DeletePostResponse> {
+    // API endpoint uses postId in the path, assuming the first post ID for the URL
+    const postId = request.posts[0]?.postId || '';
+    if (!postId) {
+      throw new ApiError(
+        'Post ID is required for deletion path',
+        ApiErrorCode.VALIDATION_ERROR,
+        400,
+      );
+    }
+    return makeRequest<DeletePostResponse>(
+      'DELETE',
+      `/api/post/${postId}`,
+      this.options,
+      request,
+    );
+  }
+}

package/src/core/client.ts

@@ -0,0 +1,58 @@
+import type { NearAuthData as NearSignatureData } from 'near-sign-verify';
+import { AuthApi } from '../api/auth.ts';
+import { PostApi } from '../api/post.ts';
+import { type CrosspostClientConfig, DEFAULT_CONFIG } from './config.ts';
+import type { RequestOptions } from './request.ts';
+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;
+
+  private readonly options: RequestOptions;
+
+  /**
+   * Creates an instance of CrosspostClient.
+   * @param config Configuration options for the client.
+   */
+  constructor(config: CrosspostClientConfig = {}) {
+    const baseUrl = config.baseUrl || DEFAULT_CONFIG.baseUrl; // you can deploy your own
+    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();
+
+    this.options = {
+      baseUrl,
+      timeout,
+      retries,
+      signature,
+    };
+
+    this.auth = new AuthApi(this.options);
+    this.post = new PostApi(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;
+
+    // Store in cookie for persistence
+    storeAuthInCookie(signature);
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,35 @@
+import type { NearAuthData as NearSignatureData } from 'near-sign-verify';
+
+/**
+ * Configuration options for the CrosspostClient
+ */
+export interface CrosspostClientConfig {
+  /**
+   * Base URL for the Crosspost API
+   * @default 'https://api.opencrosspost.com'
+   */
+  baseUrl?: string;
+  /**
+   * NEAR authentication data obtained from near-sign-verify
+   */
+  signature?: NearSignatureData;
+  /**
+   * Request timeout in milliseconds
+   * @default 30000
+   */
+  timeout?: number;
+  /**
+   * Number of retries for failed requests (specifically for network errors or 5xx status codes)
+   * @default 2
+   */
+  retries?: number;
+}
+
+/**
+ * Default configuration values for the CrosspostClient
+ */
+export const DEFAULT_CONFIG: Required<Omit<CrosspostClientConfig, 'signature'>> = {
+  baseUrl: 'https://open-crosspost-proxy.deno.dev/',
+  timeout: 30000,
+  retries: 2,
+};

package/src/core/request.ts

@@ -0,0 +1,158 @@
+import { ApiError, ApiErrorCode } from '@crosspost/types';
+import { createAuthToken, type NearAuthData as NearSignatureData } from 'near-sign-verify';
+import { createNetworkError, handleErrorResponse } from '../utils/error.ts';
+import { CSRF_HEADER_NAME, getCsrfToken } from '../utils/cookie.ts';
+
+/**
+ * Options for making a request to the API
+ */
+export interface RequestOptions {
+  /**
+   * Base URL for the API
+   */
+  baseUrl: string;
+  /**
+   * NEAR authentication data for generating auth tokens
+   * Can be undefined if not authorize yet
+   */
+  signature?: NearSignatureData;
+  /**
+   * Request timeout in milliseconds
+   */
+  timeout: number;
+  /**
+   * Number of retries for failed requests
+   */
+  retries: number;
+}
+
+/**
+ * Makes a request to the API with retry and error handling
+ *
+ * @param method The HTTP method
+ * @param path The API path
+ * @param options The request options
+ * @param data Optional request data
+ * @returns A promise resolving with the response data
+ */
+export async function makeRequest<T>(
+  method: string,
+  path: string,
+  options: RequestOptions,
+  data?: any,
+): Promise<T> {
+  const url = `${options.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+  let lastError: Error | null = null;
+
+  // Check if authentication data is available
+  if (!options.signature) {
+    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;
+        }
+      }
+
+      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, // Or a more specific code
+            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
+        }
+        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) {
+          await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt))); // Exponential backoff
+          continue; // Retry
+        }
+        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);
+      }
+
+      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);
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @crosspost/sdk
+ * SDK for interacting with the Crosspost API
+ */
+
+// Export main client
+export { CrosspostClient } from './core/client.js';
+export { CrosspostClientConfig } from './core/config.js';
+
+// Export API modules for advanced usage
+export { AuthApi } from './api/auth.js';
+export { PostApi } from './api/post.js';
+
+// Export utility functions
+export { createNetworkError, handleErrorResponse } from './utils/error.js';
+export {
+  AUTH_COOKIE_NAME,
+  AUTH_COOKIE_OPTIONS,
+  clearAuthCookie,
+  CSRF_COOKIE_NAME,
+  CSRF_HEADER_NAME,
+  getAuthFromCookie,
+  getCsrfToken,
+  storeAuthInCookie,
+} from './utils/cookie.js';
+
+// Re-export types from @crosspost/types for convenience
+export * from '@crosspost/types';

package/src/utils/cookie.ts

@@ -0,0 +1,75 @@
+import Cookies from 'js-cookie';
+import type { NearAuthData } from 'near-sign-verify';
+
+export const AUTH_COOKIE_NAME = '__crosspost_auth';
+export const CSRF_COOKIE_NAME = 'XSRF-TOKEN';
+export const CSRF_HEADER_NAME = 'X-CSRF-Token';
+
+export const AUTH_COOKIE_OPTIONS: Cookies.CookieAttributes = {
+  secure: true,
+  sameSite: 'lax', // how could we make this none?
+  path: '/',
+  expires: 30, // 30 days
+};
+
+/**
+ * Gets authentication data from the cookie
+ * @returns The NearAuthData object or undefined if not found
+ */
+export function getAuthFromCookie(): NearAuthData | undefined {
+  try {
+    if (typeof document === 'undefined') {
+      return undefined;
+    }
+
+    const cookieValue = Cookies.get(AUTH_COOKIE_NAME);
+    if (!cookieValue) {
+      return undefined;
+    }
+
+    return JSON.parse(cookieValue) as NearAuthData;
+  } catch (error) {
+    console.error('Failed to parse auth cookie:', error);
+    return undefined;
+  }
+}
+
+/**
+ * Stores authentication data in a secure cookie
+ * @param authData The NearAuthData object to store
+ */
+export function storeAuthInCookie(authData: NearAuthData): void {
+  try {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    const cookieValue = JSON.stringify(authData);
+    Cookies.set(AUTH_COOKIE_NAME, cookieValue, AUTH_COOKIE_OPTIONS);
+  } catch (error) {
+    console.error('Failed to store auth cookie:', error);
+  }
+}
+
+/**
+ * Clears the authentication cookie
+ */
+export function clearAuthCookie(): void {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  Cookies.remove(AUTH_COOKIE_NAME, { path: AUTH_COOKIE_OPTIONS.path });
+}
+
+/**
+ * Gets the CSRF token from the cookie
+ * @returns The CSRF token or undefined if not found
+ */
+export function getCsrfToken(): string | undefined {
+  if (typeof document === 'undefined') {
+    return undefined;
+  }
+
+  return Cookies.get(CSRF_COOKIE_NAME);
+}