@crosspost/sdk 0.2.0 → 0.2.2

package/README.md

@@ -147,6 +147,103 @@ async function createPost() {
 
 ## API Reference
 
+### Pagination
+
+The SDK supports offset-based pagination for endpoints that return large collections:
+
+```typescript
+// Get paginated results with specific limit and offset
+const response = await client.activity.getLeaderboard({
+  limit: 10, // Number of items per page
+  offset: 20, // Skip the first 20 items
+});
+
+// Access pagination metadata
+console.log(`Total items: ${response.meta.pagination?.total}`);
+console.log(`Current page size: ${response.meta.pagination?.limit}`);
+console.log(`Current offset: ${response.meta.pagination?.offset}`);
+```
+
+### Multi-Status Responses
+
+Some operations that target multiple platforms may result in partial success. The SDK handles these
+cases with multi-status responses:
+
+```typescript
+// Operation targeting multiple platforms
+const response = await client.post.createPost({
+  targets: [
+    { platform: 'twitter', userId: 'user1' },
+    { platform: 'facebook', userId: 'user2' },
+  ],
+  content: [{ text: 'Hello world!' }],
+});
+
+// Check multi-status summary
+console.log(`Total operations: ${response.data.summary.total}`);
+console.log(`Successful: ${response.data.summary.succeeded}`);
+console.log(`Failed: ${response.data.summary.failed}`);
+
+// Access successful results
+response.data.results.forEach((result) => {
+  console.log(`Success on ${result.platform}: ${result.details.id}`);
+});
+
+// Access errors (if any)
+if (response.data.errors && response.data.errors.length > 0) {
+  // Error structure is identical to error.details.errors when all operations fail
+  response.data.errors.forEach((error) => {
+    console.log(`Error on ${error.details.platform}: ${error.message}`);
+    console.log(`Error code: ${error.code}`);
+    console.log(`Recoverable: ${error.recoverable}`);
+  });
+}
+```
+
+If all operations fail, the SDK throws a `CrosspostError` with the same error structure in
+`details.errors`:
+
+```typescript
+try {
+  await client.post.createPost({...});
+} catch (error) {
+  if (error instanceof CrosspostError && error.details?.errors) {
+    // Error structure is identical to response.data.errors in partial success case
+    error.details.errors.forEach(err => {
+      console.log(`Error on ${err.details.platform}: ${err.message}`);
+      console.log(`Error code: ${err.code}`);
+      console.log(`Recoverable: ${err.recoverable}`);
+    });
+  }
+}
+```
+
+This consistent error structure allows you to use the same error handling logic regardless of
+whether you're dealing with partial failures in a multi-status response or complete failure.
+
+### Validation Error Handling
+
+The SDK provides detailed validation error information:
+
+```typescript
+try {
+  await client.post.createPost({
+    // Invalid or missing required fields
+  });
+} catch (error) {
+  if (isValidationError(error)) {
+    console.error('Validation failed:');
+
+    // Access validation error details
+    if (error.details?.validationErrors) {
+      Object.entries(error.details.validationErrors).forEach(([field, issues]) => {
+        console.error(`Field '${field}': ${issues.join(', ')}`);
+      });
+    }
+  }
+}
+```
+
 ### CrosspostClient
 
 ```typescript

package/dist/index.cjs

@@ -265,18 +265,13 @@ function createNetworkError(error, url, timeout) {
 
 // src/core/request.ts
 async function makeRequest(method, path, options, data, query) {
-  let url = `${options.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  const url = new URL(path, options.baseUrl);
   if (query && typeof query === "object" && Object.keys(query).length > 0) {
-    const queryParams = new URLSearchParams();
     for (const [key, value] of Object.entries(query)) {
       if (value !== void 0 && value !== null) {
-        queryParams.append(key, String(value));
+        url.searchParams.append(key, String(value));
       }
     }
-    const queryString = queryParams.toString();
-    if (queryString) {
-      url += `?${queryString}`;
-    }
   }
   const context = {
     method,
@@ -341,24 +336,16 @@ async function makeRequest(method, path, options, data, query) {
     if (!response.ok) {
       throw handleErrorResponse(responseData, response.status);
     }
-    if (!responseData || typeof responseData !== "object" || !("success" in responseData)) {
+    if (!responseData || typeof responseData !== "object" || !("success" in responseData) || !("meta" in responseData)) {
       throw new CrosspostError(
-        "Invalid success response format from API",
+        "Invalid response format from API",
         import_types2.ApiErrorCode.INVALID_RESPONSE,
         response.status,
         { responseData }
       );
     }
     if (responseData.success) {
-      if (!responseData.data) {
-        throw new CrosspostError(
-          "API returned success but no data",
-          import_types2.ApiErrorCode.INVALID_RESPONSE,
-          response.status,
-          { responseData }
-        );
-      }
-      return responseData.data;
+      return responseData;
     }
     throw handleErrorResponse(responseData, response.status);
   } catch (error) {
@@ -367,7 +354,10 @@ async function makeRequest(method, path, options, data, query) {
       throw enrichErrorWithContext(error, context);
     }
     if (error instanceof TypeError || error instanceof DOMException && error.name === "AbortError") {
-      throw enrichErrorWithContext(createNetworkError(error, url, options.timeout), context);
+      throw enrichErrorWithContext(
+        createNetworkError(error, url.toString(), options.timeout),
+        context
+      );
     }
     throw enrichErrorWithContext(
       new CrosspostError(
@@ -543,13 +533,20 @@ var AuthApi = class {
    * @throws Error if popups are blocked or if running in a non-browser environment.
    */
   async loginToPlatform(platform, options) {
-    const { url } = await makeRequest(
+    const requestOptions = options || { redirect: false };
+    const response = await makeRequest(
       "POST",
       `/auth/${platform}/login`,
       this.options,
-      options || { redirect: false }
+      requestOptions
     );
-    const result = await openAuthPopup(url);
+    if (requestOptions.redirect) {
+      return response;
+    }
+    if (!response.data || !("url" in response.data)) {
+      throw new Error("Invalid authentication URL response");
+    }
+    const result = await openAuthPopup(response.data.url);
     if (!result.success || !result.userId) {
       throw new Error(result.error || "Authentication failed");
     }
@@ -790,7 +787,7 @@ var SystemApi = class {
 
 // src/core/config.ts
 var DEFAULT_CONFIG = {
-  baseUrl: "https://open-crosspost-proxy.deno.dev/",
+  baseUrl: new URL("https://open-crosspost-proxy.deno.dev/"),
   timeout: 3e4
 };
 
@@ -805,7 +802,7 @@ var CrosspostClient = class {
     const timeout = config.timeout || DEFAULT_CONFIG.timeout;
     const nearAuthData = config.nearAuthData;
     this.options = {
-      baseUrl,
+      baseUrl: baseUrl instanceof URL ? baseUrl : new URL(baseUrl),
       timeout,
       nearAuthData
     };

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { NearAuthData } from 'near-sign-verify';
-import { ActivityLeaderboardQuery, ActivityLeaderboardResponse, AccountActivityQuery, AccountActivityResponse, AccountPostsQuery, AccountPostsResponse, NearAuthorizationResponse, Platform, AuthInitRequest, AuthCallbackResponse, ConnectedAccount, AuthStatusResponse, NearUnauthorizationResponse, AuthRevokeResponse, ConnectedAccountsResponse, CreatePostRequest, CreatePostResponse, RepostRequest, RepostResponse, QuotePostRequest, QuotePostResponse, ReplyToPostRequest, ReplyToPostResponse, LikePostRequest, LikePostResponse, UnlikePostRequest, UnlikePostResponse, DeletePostRequest, DeletePostResponse, RateLimitResponse, EndpointRateLimitResponse, HealthStatus, ApiErrorCode, StatusCode, ErrorDetails } from '@crosspost/types';
+import { ActivityLeaderboardQuery, ApiResponse, ActivityLeaderboardResponse, AccountActivityQuery, AccountActivityResponse, AccountPostsQuery, AccountPostsResponse, NearAuthorizationResponse, Platform, AuthInitRequest, AuthCallbackResponse, AuthUrlResponse, ConnectedAccount, AuthStatusResponse, NearUnauthorizationResponse, AuthRevokeResponse, ConnectedAccountsResponse, CreatePostRequest, CreatePostResponse, RepostRequest, RepostResponse, QuotePostRequest, QuotePostResponse, ReplyToPostRequest, ReplyToPostResponse, LikePostRequest, LikePostResponse, UnlikePostRequest, UnlikePostResponse, DeletePostRequest, DeletePostResponse, RateLimitResponse, EndpointRateLimitResponse, HealthStatus, ApiErrorCode, StatusCode, ErrorDetails } from '@crosspost/types';
 export * from '@crosspost/types';
 
 /**
@@ -9,7 +9,7 @@ interface RequestOptions {
     /**
      * Base URL for the API
      */
-    baseUrl: string;
+    baseUrl: URL;
     /**
      * NEAR authentication data for generating auth tokens
      * Required for non-GET requests, optional for GET requests
@@ -41,21 +41,21 @@ declare class ActivityApi {
      * @param query Optional query parameters
      * @returns A promise resolving with the leaderboard response
      */
-    getLeaderboard(query?: ActivityLeaderboardQuery): Promise<ActivityLeaderboardResponse>;
+    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<AccountActivityResponse>;
+    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<AccountPostsResponse>;
+    getAccountPosts(signerId: string, query?: AccountPostsQuery): Promise<ApiResponse<AccountPostsResponse>>;
 }
 
 /**
@@ -72,12 +72,12 @@ declare class AuthApi {
      * Authorizes the NEAR account associated with the provided nearAuthData with the Crosspost service.
      * @returns A promise resolving with the authorization response.
      */
-    authorizeNearAccount(): Promise<NearAuthorizationResponse>;
+    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<NearAuthorizationResponse>;
+    getNearAuthorizationStatus(): Promise<ApiResponse<NearAuthorizationResponse>>;
     /**
      * Initiates the login process for a specific platform using a popup window.
      * @param platform The target platform.
@@ -85,43 +85,43 @@ declare class AuthApi {
      * @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>;
+    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<AuthCallbackResponse>;
+    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<ConnectedAccount>;
+    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<AuthStatusResponse>;
+    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<NearUnauthorizationResponse>;
+    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<AuthRevokeResponse>;
+    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<ConnectedAccountsResponse>;
+    getConnectedAccounts(): Promise<ApiResponse<ConnectedAccountsResponse>>;
 }
 
 /**
@@ -139,43 +139,43 @@ declare class PostApi {
      * @param request The post creation request details.
      * @returns A promise resolving with the post creation response.
      */
-    createPost(request: CreatePostRequest): Promise<CreatePostResponse>;
+    createPost(request: CreatePostRequest): Promise<ApiResponse<CreatePostResponse>>;
     /**
      * 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<RepostResponse>;
+    repost(request: RepostRequest): Promise<ApiResponse<RepostResponse>>;
     /**
      * 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<QuotePostResponse>;
+    quotePost(request: QuotePostRequest): Promise<ApiResponse<QuotePostResponse>>;
     /**
      * 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<ReplyToPostResponse>;
+    replyToPost(request: ReplyToPostRequest): Promise<ApiResponse<ReplyToPostResponse>>;
     /**
      * 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<LikePostResponse>;
+    likePost(request: LikePostRequest): Promise<ApiResponse<LikePostResponse>>;
     /**
      * 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<UnlikePostResponse>;
+    unlikePost(request: UnlikePostRequest): Promise<ApiResponse<UnlikePostResponse>>;
     /**
      * Deletes one or more posts.
      * @param request The delete request details.
      * @returns A promise resolving with the delete response.
      */
-    deletePost(request: DeletePostRequest): Promise<DeletePostResponse>;
+    deletePost(request: DeletePostRequest): Promise<ApiResponse<DeletePostResponse>>;
 }
 
 /**
@@ -193,18 +193,18 @@ declare class SystemApi {
      * Gets the current rate limit status
      * @returns A promise resolving with the rate limit response
      */
-    getRateLimits(): Promise<RateLimitResponse>;
+    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<EndpointRateLimitResponse>;
+    getEndpointRateLimit(endpoint: string): Promise<ApiResponse<EndpointRateLimitResponse>>;
     /**
      * Gets the health status of the API
      * @returns A promise resolving with the health status
      */
-    getHealthStatus(): Promise<HealthStatus>;
+    getHealthStatus(): Promise<ApiResponse<HealthStatus>>;
 }
 
 /**
@@ -215,7 +215,7 @@ interface CrosspostClientConfig {
      * Base URL for the Crosspost API
      * @default 'https://open-crosspost-proxy.deno.dev'
      */
-    baseUrl?: string;
+    baseUrl?: string | URL;
     /**
      * NEAR authentication data obtained from near-sign-verify
      */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { NearAuthData } from 'near-sign-verify';
-import { ActivityLeaderboardQuery, ActivityLeaderboardResponse, AccountActivityQuery, AccountActivityResponse, AccountPostsQuery, AccountPostsResponse, NearAuthorizationResponse, Platform, AuthInitRequest, AuthCallbackResponse, ConnectedAccount, AuthStatusResponse, NearUnauthorizationResponse, AuthRevokeResponse, ConnectedAccountsResponse, CreatePostRequest, CreatePostResponse, RepostRequest, RepostResponse, QuotePostRequest, QuotePostResponse, ReplyToPostRequest, ReplyToPostResponse, LikePostRequest, LikePostResponse, UnlikePostRequest, UnlikePostResponse, DeletePostRequest, DeletePostResponse, RateLimitResponse, EndpointRateLimitResponse, HealthStatus, ApiErrorCode, StatusCode, ErrorDetails } from '@crosspost/types';
+import { ActivityLeaderboardQuery, ApiResponse, ActivityLeaderboardResponse, AccountActivityQuery, AccountActivityResponse, AccountPostsQuery, AccountPostsResponse, NearAuthorizationResponse, Platform, AuthInitRequest, AuthCallbackResponse, AuthUrlResponse, ConnectedAccount, AuthStatusResponse, NearUnauthorizationResponse, AuthRevokeResponse, ConnectedAccountsResponse, CreatePostRequest, CreatePostResponse, RepostRequest, RepostResponse, QuotePostRequest, QuotePostResponse, ReplyToPostRequest, ReplyToPostResponse, LikePostRequest, LikePostResponse, UnlikePostRequest, UnlikePostResponse, DeletePostRequest, DeletePostResponse, RateLimitResponse, EndpointRateLimitResponse, HealthStatus, ApiErrorCode, StatusCode, ErrorDetails } from '@crosspost/types';
 export * from '@crosspost/types';
 
 /**
@@ -9,7 +9,7 @@ interface RequestOptions {
     /**
      * Base URL for the API
      */
-    baseUrl: string;
+    baseUrl: URL;
     /**
      * NEAR authentication data for generating auth tokens
      * Required for non-GET requests, optional for GET requests
@@ -41,21 +41,21 @@ declare class ActivityApi {
      * @param query Optional query parameters
      * @returns A promise resolving with the leaderboard response
      */
-    getLeaderboard(query?: ActivityLeaderboardQuery): Promise<ActivityLeaderboardResponse>;
+    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<AccountActivityResponse>;
+    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<AccountPostsResponse>;
+    getAccountPosts(signerId: string, query?: AccountPostsQuery): Promise<ApiResponse<AccountPostsResponse>>;
 }
 
 /**
@@ -72,12 +72,12 @@ declare class AuthApi {
      * Authorizes the NEAR account associated with the provided nearAuthData with the Crosspost service.
      * @returns A promise resolving with the authorization response.
      */
-    authorizeNearAccount(): Promise<NearAuthorizationResponse>;
+    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<NearAuthorizationResponse>;
+    getNearAuthorizationStatus(): Promise<ApiResponse<NearAuthorizationResponse>>;
     /**
      * Initiates the login process for a specific platform using a popup window.
      * @param platform The target platform.
@@ -85,43 +85,43 @@ declare class AuthApi {
      * @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>;
+    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<AuthCallbackResponse>;
+    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<ConnectedAccount>;
+    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<AuthStatusResponse>;
+    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<NearUnauthorizationResponse>;
+    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<AuthRevokeResponse>;
+    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<ConnectedAccountsResponse>;
+    getConnectedAccounts(): Promise<ApiResponse<ConnectedAccountsResponse>>;
 }
 
 /**
@@ -139,43 +139,43 @@ declare class PostApi {
      * @param request The post creation request details.
      * @returns A promise resolving with the post creation response.
      */
-    createPost(request: CreatePostRequest): Promise<CreatePostResponse>;
+    createPost(request: CreatePostRequest): Promise<ApiResponse<CreatePostResponse>>;
     /**
      * 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<RepostResponse>;
+    repost(request: RepostRequest): Promise<ApiResponse<RepostResponse>>;
     /**
      * 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<QuotePostResponse>;
+    quotePost(request: QuotePostRequest): Promise<ApiResponse<QuotePostResponse>>;
     /**
      * 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<ReplyToPostResponse>;
+    replyToPost(request: ReplyToPostRequest): Promise<ApiResponse<ReplyToPostResponse>>;
     /**
      * 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<LikePostResponse>;
+    likePost(request: LikePostRequest): Promise<ApiResponse<LikePostResponse>>;
     /**
      * 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<UnlikePostResponse>;
+    unlikePost(request: UnlikePostRequest): Promise<ApiResponse<UnlikePostResponse>>;
     /**
      * Deletes one or more posts.
      * @param request The delete request details.
      * @returns A promise resolving with the delete response.
      */
-    deletePost(request: DeletePostRequest): Promise<DeletePostResponse>;
+    deletePost(request: DeletePostRequest): Promise<ApiResponse<DeletePostResponse>>;
 }
 
 /**
@@ -193,18 +193,18 @@ declare class SystemApi {
      * Gets the current rate limit status
      * @returns A promise resolving with the rate limit response
      */
-    getRateLimits(): Promise<RateLimitResponse>;
+    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<EndpointRateLimitResponse>;
+    getEndpointRateLimit(endpoint: string): Promise<ApiResponse<EndpointRateLimitResponse>>;
     /**
      * Gets the health status of the API
      * @returns A promise resolving with the health status
      */
-    getHealthStatus(): Promise<HealthStatus>;
+    getHealthStatus(): Promise<ApiResponse<HealthStatus>>;
 }
 
 /**
@@ -215,7 +215,7 @@ interface CrosspostClientConfig {
      * Base URL for the Crosspost API
      * @default 'https://open-crosspost-proxy.deno.dev'
      */
-    baseUrl?: string;
+    baseUrl?: string | URL;
     /**
      * NEAR authentication data obtained from near-sign-verify
      */

package/dist/index.js

@@ -219,18 +219,13 @@ function createNetworkError(error, url, timeout) {
 
 // src/core/request.ts
 async function makeRequest(method, path, options, data, query) {
-  let url = `${options.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  const url = new URL(path, options.baseUrl);
   if (query && typeof query === "object" && Object.keys(query).length > 0) {
-    const queryParams = new URLSearchParams();
     for (const [key, value] of Object.entries(query)) {
       if (value !== void 0 && value !== null) {
-        queryParams.append(key, String(value));
+        url.searchParams.append(key, String(value));
       }
     }
-    const queryString = queryParams.toString();
-    if (queryString) {
-      url += `?${queryString}`;
-    }
   }
   const context = {
     method,
@@ -295,24 +290,16 @@ async function makeRequest(method, path, options, data, query) {
     if (!response.ok) {
       throw handleErrorResponse(responseData, response.status);
     }
-    if (!responseData || typeof responseData !== "object" || !("success" in responseData)) {
+    if (!responseData || typeof responseData !== "object" || !("success" in responseData) || !("meta" in responseData)) {
       throw new CrosspostError(
-        "Invalid success response format from API",
+        "Invalid response format from API",
         ApiErrorCode2.INVALID_RESPONSE,
         response.status,
         { responseData }
       );
     }
     if (responseData.success) {
-      if (!responseData.data) {
-        throw new CrosspostError(
-          "API returned success but no data",
-          ApiErrorCode2.INVALID_RESPONSE,
-          response.status,
-          { responseData }
-        );
-      }
-      return responseData.data;
+      return responseData;
     }
     throw handleErrorResponse(responseData, response.status);
   } catch (error) {
@@ -321,7 +308,10 @@ async function makeRequest(method, path, options, data, query) {
       throw enrichErrorWithContext(error, context);
     }
     if (error instanceof TypeError || error instanceof DOMException && error.name === "AbortError") {
-      throw enrichErrorWithContext(createNetworkError(error, url, options.timeout), context);
+      throw enrichErrorWithContext(
+        createNetworkError(error, url.toString(), options.timeout),
+        context
+      );
     }
     throw enrichErrorWithContext(
       new CrosspostError(
@@ -497,13 +487,20 @@ var AuthApi = class {
    * @throws Error if popups are blocked or if running in a non-browser environment.
    */
   async loginToPlatform(platform, options) {
-    const { url } = await makeRequest(
+    const requestOptions = options || { redirect: false };
+    const response = await makeRequest(
       "POST",
       `/auth/${platform}/login`,
       this.options,
-      options || { redirect: false }
+      requestOptions
     );
-    const result = await openAuthPopup(url);
+    if (requestOptions.redirect) {
+      return response;
+    }
+    if (!response.data || !("url" in response.data)) {
+      throw new Error("Invalid authentication URL response");
+    }
+    const result = await openAuthPopup(response.data.url);
     if (!result.success || !result.userId) {
       throw new Error(result.error || "Authentication failed");
     }
@@ -744,7 +741,7 @@ var SystemApi = class {
 
 // src/core/config.ts
 var DEFAULT_CONFIG = {
-  baseUrl: "https://open-crosspost-proxy.deno.dev/",
+  baseUrl: new URL("https://open-crosspost-proxy.deno.dev/"),
   timeout: 3e4
 };
 
@@ -759,7 +756,7 @@ var CrosspostClient = class {
     const timeout = config.timeout || DEFAULT_CONFIG.timeout;
     const nearAuthData = config.nearAuthData;
     this.options = {
-      baseUrl,
+      baseUrl: baseUrl instanceof URL ? baseUrl : new URL(baseUrl),
       timeout,
       nearAuthData
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crosspost/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "SDK for interacting with the Crosspost API",
   "type": "module",
   "main": "dist/index.cjs",

package/src/api/activity.ts

@@ -5,6 +5,7 @@ import type {
   AccountPostsResponse,
   ActivityLeaderboardQuery,
   ActivityLeaderboardResponse,
+  ApiResponse,
 } from '@crosspost/types';
 import { makeRequest, type RequestOptions } from '../core/request.ts';
 
@@ -27,7 +28,9 @@ export class ActivityApi {
    * @param query Optional query parameters
    * @returns A promise resolving with the leaderboard response
    */
-  async getLeaderboard(query?: ActivityLeaderboardQuery): Promise<ActivityLeaderboardResponse> {
+  async getLeaderboard(
+    query?: ActivityLeaderboardQuery,
+  ): Promise<ApiResponse<ActivityLeaderboardResponse>> {
     return makeRequest<ActivityLeaderboardResponse, never, ActivityLeaderboardQuery>(
       'GET',
       '/api/activity',
@@ -46,7 +49,7 @@ export class ActivityApi {
   async getAccountActivity(
     signerId: string,
     query?: AccountActivityQuery,
-  ): Promise<AccountActivityResponse> {
+  ): Promise<ApiResponse<AccountActivityResponse>> {
     return makeRequest<AccountActivityResponse, never, AccountActivityQuery>(
       'GET',
       `/api/activity/${signerId}`,
@@ -65,7 +68,7 @@ export class ActivityApi {
   async getAccountPosts(
     signerId: string,
     query?: AccountPostsQuery,
-  ): Promise<AccountPostsResponse> {
+  ): Promise<ApiResponse<AccountPostsResponse>> {
     return makeRequest<AccountPostsResponse, never, AccountPostsQuery>(
       'GET',
       `/api/activity/${signerId}/posts`,

package/src/api/auth.ts

@@ -1,4 +1,5 @@
 import type {
+  ApiResponse,
   AuthCallbackResponse,
   AuthInitRequest,
   AuthRevokeResponse,
@@ -34,7 +35,7 @@ export class AuthApi {
    * 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> {
+  async authorizeNearAccount(): Promise<ApiResponse<NearAuthorizationResponse>> {
     return makeRequest<NearAuthorizationResponse, NearAuthorizationRequest>(
       'POST',
       '/auth/authorize/near',
@@ -47,7 +48,7 @@ export class AuthApi {
    * 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> {
+  async getNearAuthorizationStatus(): Promise<ApiResponse<NearAuthorizationResponse>> {
     return makeRequest<NearAuthorizationResponse, never>(
       'GET',
       '/auth/authorize/near/status',
@@ -65,17 +66,30 @@ export class AuthApi {
   async loginToPlatform(
     platform: Platform,
     options?: AuthInitRequest,
-  ): Promise<AuthCallbackResponse> {
+  ): Promise<AuthCallbackResponse | ApiResponse<AuthUrlResponse>> {
+    // Use provided options or default to redirect: false
+    const requestOptions = options || { redirect: false };
+
     // Make POST request to get auth URL
-    const { url } = await makeRequest<AuthUrlResponse, AuthInitRequest>(
+    const response = await makeRequest<AuthUrlResponse, AuthInitRequest>(
       'POST',
       `/auth/${platform}/login`,
       this.options,
-      options || { redirect: false },
+      requestOptions,
     );
 
-    // Open the popup with the auth URL
-    const result = await openAuthPopup(url);
+    // If redirect is true, return the auth URL response directly
+    if (requestOptions.redirect) {
+      return response; // Return the full ApiResponse<AuthUrlResponse>
+    }
+
+    // Check if response.data exists and has the url property
+    if (!response.data || !('url' in response.data)) {
+      throw new Error('Invalid authentication URL response');
+    }
+
+    // Otherwise, continue with popup flow
+    const result = await openAuthPopup(response.data.url);
 
     if (!result.success || !result.userId) {
       throw new Error(result.error || 'Authentication failed');
@@ -94,7 +108,10 @@ export class AuthApi {
    * @param platform The target platform.
    * @returns A promise resolving with the refresh response containing updated auth details.
    */
-  async refreshToken(platform: Platform, userId: string): Promise<AuthCallbackResponse> {
+  async refreshToken(
+    platform: Platform,
+    userId: string,
+  ): Promise<ApiResponse<AuthCallbackResponse>> {
     return makeRequest<AuthCallbackResponse, AuthTokenRequest>(
       'POST',
       `/auth/${platform}/refresh`,
@@ -109,7 +126,7 @@ export class AuthApi {
    * @param userId The user ID on the platform
    * @returns A promise resolving with the updated account profile information.
    */
-  async refreshProfile(platform: Platform, userId: string): Promise<ConnectedAccount> {
+  async refreshProfile(platform: Platform, userId: string): Promise<ApiResponse<ConnectedAccount>> {
     return makeRequest<ConnectedAccount, AuthTokenRequest>(
       'POST',
       `/auth/${platform}/refresh-profile`,
@@ -123,7 +140,10 @@ export class AuthApi {
    * @param platform The target platform.
    * @returns A promise resolving with the authentication status response.
    */
-  async getAuthStatus(platform: Platform, userId: string): Promise<AuthStatusResponse> {
+  async getAuthStatus(
+    platform: Platform,
+    userId: string,
+  ): Promise<ApiResponse<AuthStatusResponse>> {
     return makeRequest<AuthStatusResponse, never, AuthStatusParams>(
       'GET',
       `/auth/${platform}/status/${userId}`,
@@ -137,7 +157,7 @@ export class AuthApi {
    * Unauthorizes a NEAR account from using the service
    * @returns A promise resolving with the unauthorized response
    */
-  async unauthorizeNear(): Promise<NearUnauthorizationResponse> {
+  async unauthorizeNear(): Promise<ApiResponse<NearUnauthorizationResponse>> {
     return makeRequest<NearUnauthorizationResponse, NearAuthorizationRequest>(
       'DELETE',
       '/auth/unauthorize/near',
@@ -151,7 +171,7 @@ export class AuthApi {
    * @param platform The target platform.
    * @returns A promise resolving with the revocation response.
    */
-  async revokeAuth(platform: Platform, userId: string): Promise<AuthRevokeResponse> {
+  async revokeAuth(platform: Platform, userId: string): Promise<ApiResponse<AuthRevokeResponse>> {
     return makeRequest<AuthRevokeResponse, AuthTokenRequest>(
       'DELETE',
       `/auth/${platform}/revoke`,
@@ -165,7 +185,7 @@ export class AuthApi {
    * @returns A promise resolving with the connected accounts response containing an array of accounts.
    * @throws {CrosspostError} If the request fails or returns invalid data.
    */
-  async getConnectedAccounts(): Promise<ConnectedAccountsResponse> {
+  async getConnectedAccounts(): Promise<ApiResponse<ConnectedAccountsResponse>> {
     return makeRequest<ConnectedAccountsResponse, never>(
       'GET',
       '/auth/accounts',

package/src/api/post.ts

@@ -1,4 +1,5 @@
 import type {
+  ApiResponse,
   CreatePostRequest,
   CreatePostResponse,
   DeletePostRequest,
@@ -35,7 +36,7 @@ export class PostApi {
    * @param request The post creation request details.
    * @returns A promise resolving with the post creation response.
    */
-  async createPost(request: CreatePostRequest): Promise<CreatePostResponse> {
+  async createPost(request: CreatePostRequest): Promise<ApiResponse<CreatePostResponse>> {
     return makeRequest<CreatePostResponse, CreatePostRequest>(
       'POST',
       '/api/post',
@@ -49,7 +50,7 @@ export class PostApi {
    * @param request The repost request details.
    * @returns A promise resolving with the repost response.
    */
-  async repost(request: RepostRequest): Promise<RepostResponse> {
+  async repost(request: RepostRequest): Promise<ApiResponse<RepostResponse>> {
     return makeRequest<RepostResponse, RepostRequest>(
       'POST',
       '/api/post/repost',
@@ -63,7 +64,7 @@ export class PostApi {
    * @param request The quote post request details.
    * @returns A promise resolving with the quote post response.
    */
-  async quotePost(request: QuotePostRequest): Promise<QuotePostResponse> {
+  async quotePost(request: QuotePostRequest): Promise<ApiResponse<QuotePostResponse>> {
     return makeRequest<QuotePostResponse, QuotePostRequest>(
       'POST',
       '/api/post/quote',
@@ -77,7 +78,7 @@ export class PostApi {
    * @param request The reply request details.
    * @returns A promise resolving with the reply response.
    */
-  async replyToPost(request: ReplyToPostRequest): Promise<ReplyToPostResponse> {
+  async replyToPost(request: ReplyToPostRequest): Promise<ApiResponse<ReplyToPostResponse>> {
     return makeRequest<ReplyToPostResponse, ReplyToPostRequest>(
       'POST',
       '/api/post/reply',
@@ -91,7 +92,7 @@ export class PostApi {
    * @param request The like request details.
    * @returns A promise resolving with the like response.
    */
-  async likePost(request: LikePostRequest): Promise<LikePostResponse> {
+  async likePost(request: LikePostRequest): Promise<ApiResponse<LikePostResponse>> {
     return makeRequest<LikePostResponse, LikePostRequest>(
       'POST',
       `/api/post/like`,
@@ -105,7 +106,7 @@ export class PostApi {
    * @param request The unlike request details.
    * @returns A promise resolving with the unlike response.
    */
-  async unlikePost(request: UnlikePostRequest): Promise<UnlikePostResponse> {
+  async unlikePost(request: UnlikePostRequest): Promise<ApiResponse<UnlikePostResponse>> {
     return makeRequest<UnlikePostResponse, UnlikePostRequest>(
       'DELETE',
       `/api/post/like`,
@@ -119,7 +120,7 @@ export class PostApi {
    * @param request The delete request details.
    * @returns A promise resolving with the delete response.
    */
-  async deletePost(request: DeletePostRequest): Promise<DeletePostResponse> {
+  async deletePost(request: DeletePostRequest): Promise<ApiResponse<DeletePostResponse>> {
     return makeRequest<DeletePostResponse, DeletePostRequest>(
       'DELETE',
       `/api/post`,

package/src/api/system.ts

@@ -1,4 +1,5 @@
 import type {
+  ApiResponse,
   EndpointRateLimitResponse,
   HealthStatus,
   RateLimitEndpointParam,
@@ -25,7 +26,7 @@ export class SystemApi {
    * Gets the current rate limit status
    * @returns A promise resolving with the rate limit response
    */
-  async getRateLimits(): Promise<RateLimitResponse> {
+  async getRateLimits(): Promise<ApiResponse<RateLimitResponse>> {
     return makeRequest<RateLimitResponse, never>(
       'GET',
       '/api/rate-limit',
@@ -38,7 +39,7 @@ export class SystemApi {
    * @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> {
+  async getEndpointRateLimit(endpoint: string): Promise<ApiResponse<EndpointRateLimitResponse>> {
     return makeRequest<EndpointRateLimitResponse, never, RateLimitEndpointParam>(
       'GET',
       `/api/rate-limit/${endpoint}`,
@@ -52,7 +53,7 @@ export class SystemApi {
    * Gets the health status of the API
    * @returns A promise resolving with the health status
    */
-  async getHealthStatus(): Promise<HealthStatus> {
+  async getHealthStatus(): Promise<ApiResponse<HealthStatus>> {
     return makeRequest<HealthStatus, never>(
       'GET',
       '/health',

package/src/core/client.ts

@@ -28,7 +28,7 @@ export class CrosspostClient {
     const nearAuthData = config.nearAuthData;
 
     this.options = {
-      baseUrl,
+      baseUrl: baseUrl instanceof URL ? baseUrl : new URL(baseUrl),
       timeout,
       nearAuthData,
     };

package/src/core/config.ts

@@ -8,7 +8,7 @@ export interface CrosspostClientConfig {
    * Base URL for the Crosspost API
    * @default 'https://open-crosspost-proxy.deno.dev'
    */
-  baseUrl?: string;
+  baseUrl?: string | URL;
   /**
    * NEAR authentication data obtained from near-sign-verify
    */
@@ -24,6 +24,6 @@ export interface CrosspostClientConfig {
  * Default configuration values for the CrosspostClient
  */
 export const DEFAULT_CONFIG: Required<Omit<CrosspostClientConfig, 'nearAuthData'>> = {
-  baseUrl: 'https://open-crosspost-proxy.deno.dev/',
+  baseUrl: new URL('https://open-crosspost-proxy.deno.dev/'),
   timeout: 30000,
 };

package/src/core/request.ts

@@ -1,4 +1,4 @@
-import { ApiErrorCode, type StatusCode } from '@crosspost/types';
+import { ApiErrorCode, type ApiResponse, type StatusCode } from '@crosspost/types';
 import { createAuthToken, type NearAuthData } from 'near-sign-verify';
 import {
   createNetworkError,
@@ -14,7 +14,7 @@ export interface RequestOptions {
   /**
    * Base URL for the API
    */
-  baseUrl: string;
+  baseUrl: URL;
   /**
    * NEAR authentication data for generating auth tokens
    * Required for non-GET requests, optional for GET requests
@@ -39,7 +39,7 @@ export interface RequestOptions {
  * @param options The request options
  * @param data Optional request data
  * @param query Optional query parameters
- * @returns A promise resolving with the data field from the API response
+ * @returns A promise resolving with the API response object
  * @throws {CrosspostError}
  *  - If the request fails (network error, timeout)
  *  - If the response is not valid JSON
@@ -57,21 +57,16 @@ export async function makeRequest<
   options: RequestOptions,
   data?: TRequest,
   query?: TQuery,
-): Promise<TResponse> {
-  let url = `${options.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+): Promise<ApiResponse<TResponse>> {
+  const url = new URL(path, options.baseUrl);
 
   // Add query parameters if provided
   if (query && typeof query === 'object' && 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));
+        url.searchParams.append(key, String(value));
       }
     }
-    const queryString = queryParams.toString();
-    if (queryString) {
-      url += `?${queryString}`;
-    }
   }
 
   // Create a context object for error enrichment
@@ -123,7 +118,7 @@ export async function makeRequest<
     const response = await fetch(url, requestOptions);
     clearTimeout(timeoutId);
 
-    let responseData: any;
+    let responseData: ApiResponse<TResponse>;
     try {
       responseData = await response.json();
     } catch (jsonError) {
@@ -151,9 +146,12 @@ export async function makeRequest<
     }
 
     // Validate success response structure
-    if (!responseData || typeof responseData !== 'object' || !('success' in responseData)) {
+    if (
+      !responseData || typeof responseData !== 'object' || !('success' in responseData) ||
+      !('meta' in responseData)
+    ) {
       throw new CrosspostError(
-        'Invalid success response format from API',
+        'Invalid response format from API',
         ApiErrorCode.INVALID_RESPONSE,
         response.status as StatusCode,
         { responseData },
@@ -161,15 +159,7 @@ export async function makeRequest<
     }
 
     if (responseData.success) {
-      if (!responseData.data) {
-        throw new CrosspostError(
-          'API returned success but no data',
-          ApiErrorCode.INVALID_RESPONSE,
-          response.status as StatusCode,
-          { responseData },
-        );
-      }
-      return responseData.data as TResponse;
+      return responseData as ApiResponse<TResponse>;
     }
 
     // If we get here, we have response.ok but success: false
@@ -187,7 +177,10 @@ export async function makeRequest<
     if (
       error instanceof TypeError || (error instanceof DOMException && error.name === 'AbortError')
     ) {
-      throw enrichErrorWithContext(createNetworkError(error, url, options.timeout), context);
+      throw enrichErrorWithContext(
+        createNetworkError(error, url.toString(), options.timeout),
+        context,
+      );
     }
 
     // For any other errors, wrap them with context