@crosspost/types 0.1.6 → 0.1.8

package/src/response.ts

@@ -1,297 +1,57 @@
-/**
- * Enhanced Response Schemas and Types
- * Defines schemas and types for the enhanced API response format
- */
-
 import { z } from 'zod';
-import type { PlatformName } from './common.ts';
-
-/**
- * Standard API response schema
- */
-export const ApiResponseSchema = z.object({
-  data: z.any().describe('Response data'),
-  meta: z.object({
-    rateLimit: z.object({
-      remaining: z.number().describe('Number of requests remaining in the current window'),
-      limit: z.number().describe('Total number of requests allowed in the window'),
-      reset: z.number().describe('Timestamp when the rate limit resets (in seconds since epoch)'),
-    }).optional().describe('Rate limit information'),
-    pagination: z.object({
-      page: z.number().describe('Current page number'),
-      perPage: z.number().describe('Number of items per page'),
-      total: z.number().describe('Total number of items'),
-      totalPages: z.number().describe('Total number of pages'),
-      nextCursor: z.string().optional().describe('Next page cursor (if applicable)'),
-      prevCursor: z.string().optional().describe('Previous page cursor (if applicable)'),
-    }).optional().describe('Pagination information'),
-  }).optional().describe('Response metadata'),
-}).describe('Standard API response');
+import { type ErrorDetail, ErrorDetailSchema } from './errors.ts';
 
-/**
- * Error response schema
- */
-export const ErrorResponseSchema = z.object({
-  error: z.object({
-    type: z.string().describe('Error type'),
-    message: z.string().describe('Error message'),
-    code: z.string().optional().describe('Error code (if applicable)'),
-    details: z.any().optional().describe('Additional error details'),
-  }).describe('Error information'),
-}).describe('Error response');
-
-/**
- * Schema for enhanced response metadata
- */
-export const EnhancedResponseMetaSchema = z.object({
-  requestId: z.string().optional().describe('Unique request identifier'),
-  timestamp: z.string().optional().describe('Request timestamp'),
+export const ResponseMetaSchema = z.object({
+  requestId: z.string().uuid().describe('Unique identifier for the request'),
+  timestamp: z.string().datetime().describe('ISO timestamp of response generation'),
   rateLimit: z.object({
-    remaining: z.number().describe('Number of requests remaining in the current window'),
-    limit: z.number().describe('Total number of requests allowed in the window'),
-    reset: z.number().describe('Timestamp when the rate limit resets (in seconds since epoch)'),
-  }).optional().describe('Rate limit information'),
+    remaining: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+    reset: z.number().int().positive().describe('Unix timestamp (seconds)'),
+  }).optional().describe('Rate limit information if applicable'),
   pagination: z.object({
-    page: z.number().describe('Current page number'),
-    perPage: z.number().describe('Number of items per page'),
-    total: z.number().describe('Total number of items'),
-    totalPages: z.number().describe('Total number of pages'),
-    nextCursor: z.string().optional().describe('Next page cursor (if applicable)'),
-    prevCursor: z.string().optional().describe('Previous page cursor (if applicable)'),
-  }).optional().describe('Pagination information'),
-}).optional().describe('Response metadata');
-
-/**
- * Schema for error details
- */
-export const ErrorDetailSchema = z.object({
-  platform: z.string().optional().describe('Platform associated with the error (if applicable)'),
-  userId: z.string().optional().describe('User ID associated with the error (if applicable)'),
-  status: z.literal('error').describe('Error status'),
-  error: z.string().describe('Human-readable error message'),
-  errorCode: z.string().describe('Machine-readable error code'),
-  recoverable: z.boolean().describe('Whether the error is recoverable (can be retried)'),
-  details: z.record(z.any()).optional().describe('Additional error details (platform-specific)'),
-}).describe('Error detail');
+    page: z.number().int().positive().optional(),
+    perPage: z.number().int().positive().optional(),
+    total: z.number().int().nonnegative().optional(),
+    limit: z.number().int().nonnegative().optional(),
+    offset: z.number().int().nonnegative().optional(),
+    totalPages: z.number().int().nonnegative().optional(),
+    nextCursor: z.string().optional(),
+    prevCursor: z.string().optional(),
+  }).optional().describe('Pagination information if applicable'),
+});
 
-/**
- * Schema for enhanced error response
- */
-export const EnhancedErrorResponseSchema = z.object({
-  success: z.literal(false).describe('Success indicator (always false for error responses)'),
-  errors: z.array(ErrorDetailSchema).describe('Error information'),
-}).describe('Enhanced error response');
-
-/**
- * Schema for success details
- */
 export const SuccessDetailSchema = z.object({
-  platform: z.string().describe('Platform associated with the success'),
-  userId: z.string().describe('User ID associated with the success'),
-  status: z.literal('success').describe('Success status'),
-  postId: z.string().optional().describe('Post ID (if applicable)'),
-  postUrl: z.string().optional().describe('Post URL (if applicable)'),
-}).catchall(z.any()).describe('Success detail');
-
-/**
- * Schema for multi-status response
- */
-export const MultiStatusResponseSchema = z.object({
-  success: z.boolean().describe('Success indicator (true if at least one operation succeeded)'),
-  data: z.object({
-    summary: z.object({
-      total: z.number().describe('Total number of operations'),
-      succeeded: z.number().describe('Number of successful operations'),
-      failed: z.number().describe('Number of failed operations'),
-    }).describe('Summary of operations'),
-    results: z.array(SuccessDetailSchema).describe('Successful results'),
-    errors: z.array(ErrorDetailSchema).describe('Failed results'),
-  }).describe('Response data'),
-}).describe('Multi-status response');
-
-/**
- * Function to create an enhanced response schema
- * @param schema The schema to wrap
- * @returns A schema for an enhanced response
- */
-export function EnhancedResponseSchema<T extends z.ZodTypeAny>(schema: T) {
-  return z.object({
-    success: z.boolean().describe('Whether the request was successful'),
-    data: schema,
-    meta: EnhancedResponseMetaSchema,
-  });
-}
-
-// Derive TypeScript types from Zod schemas
-export type EnhancedResponseMeta = z.infer<typeof EnhancedResponseMetaSchema>;
-export type ErrorDetail = z.infer<typeof ErrorDetailSchema>;
-export type EnhancedErrorResponse = z.infer<typeof EnhancedErrorResponseSchema>;
-export type SuccessDetail = z.infer<typeof SuccessDetailSchema>;
-export type MultiStatusResponse = z.infer<typeof MultiStatusResponseSchema>;
-export type ApiResponse<T> = {
-  data: T;
-  meta?: {
-    rateLimit?: { remaining: number; limit: number; reset: number };
-    pagination?: {
-      page: number;
-      perPage: number;
-      total: number;
-      totalPages: number;
-      nextCursor?: string;
-      prevCursor?: string;
-    };
-  };
-};
-export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
-
-/**
- * Enhanced API response type
- */
-export interface EnhancedApiResponse<T> {
+  platform: z.string(),
+  userId: z.string(),
+  additionalData: z.any().optional(),
+  status: z.literal('success'),
+}).catchall(z.any());
+
+export const HealthStatusSchema = z.object({
+  status: z.string().describe('Health status of the API'),
+  version: z.string().optional().describe('API version'),
+  timestamp: z.string().datetime().describe('Current server time'),
+}).describe('Health status response');
+
+export const MultiStatusDataSchema = z.object({
+  summary: z.object({
+    total: z.number().int().nonnegative(),
+    succeeded: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+  }),
+  results: z.array(SuccessDetailSchema),
+  errors: z.array(ErrorDetailSchema),
+});
+
+export interface ApiResponse<T> {
   success: boolean;
-  data: T;
-  meta?: EnhancedResponseMeta;
-}
-
-/**
- * Helper function to create an enhanced API response
- * @param data The response data
- * @param meta Optional metadata
- * @returns An enhanced API response
- */
-export function createEnhancedApiResponse<T>(
-  data: T,
-  meta?: EnhancedResponseMeta,
-): EnhancedApiResponse<T> {
-  return {
-    success: true,
-    data,
-    meta,
-  };
+  data?: T | MultiStatusData | null; // Allow null for success without data
+  errors?: ErrorDetail[] | null; // Allow null for success
+  meta: ResponseMeta; // Mandatory, holds request id
 }
 
-/**
- * Create a standard API response
- * @param data The response data
- * @param meta The response metadata
- * @returns A standard API response
- */
-export function createApiResponse<T>(data: T, meta?: ApiResponse<T>['meta']): ApiResponse<T> {
-  return {
-    data,
-    meta,
-  };
-}
-
-/**
- * Create an error response
- * @param type The error type
- * @param message The error message
- * @param code The error code (if applicable)
- * @param details Additional error details
- * @returns An error response
- */
-export function createErrorResponse(
-  type: string,
-  message: string,
-  code?: string,
-  details?: any,
-): ErrorResponse {
-  return {
-    error: {
-      type,
-      message,
-      ...(code ? { code } : {}),
-      ...(details ? { details } : {}),
-    },
-  };
-}
-
-/**
- * Helper function to create an enhanced error response
- * @param errors Array of error details
- * @returns An enhanced error response
- */
-export function createEnhancedErrorResponse(errors: ErrorDetail[]): EnhancedErrorResponse {
-  return {
-    success: false,
-    errors,
-  };
-}
-
-/**
- * Helper function to create an error detail
- * @param error Error message
- * @param errorCode Error code
- * @param recoverable Whether the error is recoverable
- * @param platform Optional platform
- * @param userId Optional user ID
- * @param details Optional additional details
- * @returns An error detail
- */
-export function createErrorDetail(
-  error: string,
-  errorCode: string,
-  recoverable: boolean,
-  platform?: PlatformName,
-  userId?: string,
-  details?: Record<string, any>,
-): ErrorDetail {
-  return {
-    platform,
-    userId,
-    status: 'error',
-    error,
-    errorCode,
-    recoverable,
-    details,
-  };
-}
-
-/**
- * Helper function to create a success detail
- * @param platform Platform
- * @param userId User ID
- * @param additionalData Additional data
- * @returns A success detail
- */
-export function createSuccessDetail(
-  platform: PlatformName,
-  userId: string,
-  additionalData?: Record<string, any>,
-): SuccessDetail {
-  return {
-    platform,
-    userId,
-    status: 'success',
-    ...additionalData,
-  };
-}
-
-/**
- * Helper function to create a multi-status response
- * @param results Successful results
- * @param errors Failed results
- * @returns A multi-status response
- */
-export function createMultiStatusResponse(
-  results: SuccessDetail[],
-  errors: ErrorDetail[],
-): MultiStatusResponse {
-  const total = results.length + errors.length;
-  const succeeded = results.length;
-  const failed = errors.length;
-
-  return {
-    success: succeeded > 0,
-    data: {
-      summary: {
-        total,
-        succeeded,
-        failed,
-      },
-      results,
-      errors,
-    },
-  };
-}
+export type ResponseMeta = z.infer<typeof ResponseMetaSchema>;
+export type SuccessDetail = z.infer<typeof SuccessDetailSchema>;
+export type MultiStatusData = z.infer<typeof MultiStatusDataSchema>;
+export type HealthStatus = z.infer<typeof HealthStatusSchema>;

package/src/user-profile.ts

@@ -1,16 +1,6 @@
-/**
- * User Profile Schemas and Types
- * Defines Zod schemas for user profile-related data
- * TypeScript types are derived from Zod schemas for type safety
- */
-
 import { z } from 'zod';
 import { PlatformSchema } from './common.ts';
-import { EnhancedResponseSchema } from './response.ts';
 
-/**
- * User profile schema
- */
 export const UserProfileSchema = z.object({
   userId: z.string().describe('User ID on the platform'),
   username: z.string().describe('Username on the platform'),
@@ -21,23 +11,9 @@ export const UserProfileSchema = z.object({
   lastUpdated: z.number().describe('Timestamp when the profile was last updated'),
 }).describe('User profile');
 
-/**
- * Profile refresh result schema
- */
-export const ProfileRefreshResultSchema = z.object({
-  success: z.boolean().describe('Whether the profile refresh was successful'),
+export const ProfileRefreshResponseSchema = z.object({
   profile: UserProfileSchema.optional().describe('The refreshed user profile (if successful)'),
-  error: z.string().optional().describe('Error message (if unsuccessful)'),
-}).describe('Profile refresh result');
-
-/**
- * Profile refresh response schema
- */
-export const ProfileRefreshResponseSchema = EnhancedResponseSchema(
-  ProfileRefreshResultSchema,
-).describe('Profile refresh response');
+}).describe('Profile refresh response');
 
-// Derive TypeScript types from Zod schemas
 export type UserProfile = z.infer<typeof UserProfileSchema>;
-export type ProfileRefreshResult = z.infer<typeof ProfileRefreshResultSchema>;
 export type ProfileRefreshResponse = z.infer<typeof ProfileRefreshResponseSchema>;

package/src/errors/api-error.ts

@@ -1,155 +0,0 @@
-import type { StatusCode } from 'hono/utils/http-status';
-import { BaseError } from './base-error.ts';
-
-/**
- * API Error codes for standardized error identification
- */
-export enum ApiErrorCode {
-  // General errors
-  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
-  INTERNAL_ERROR = 'INTERNAL_ERROR',
-
-  // Authentication/Authorization errors
-  UNAUTHORIZED = 'UNAUTHORIZED',
-  FORBIDDEN = 'FORBIDDEN',
-
-  // Validation errors
-  VALIDATION_ERROR = 'VALIDATION_ERROR',
-  INVALID_REQUEST = 'INVALID_REQUEST',
-
-  // Rate limiting
-  RATE_LIMITED = 'RATE_LIMITED',
-
-  // Resource errors
-  NOT_FOUND = 'NOT_FOUND',
-
-  // Platform-specific errors
-  PLATFORM_ERROR = 'PLATFORM_ERROR',
-  PLATFORM_UNAVAILABLE = 'PLATFORM_UNAVAILABLE',
-
-  // Content errors
-  CONTENT_POLICY_VIOLATION = 'CONTENT_POLICY_VIOLATION',
-  DUPLICATE_CONTENT = 'DUPLICATE_CONTENT',
-
-  // Media errors
-  MEDIA_UPLOAD_FAILED = 'MEDIA_UPLOAD_FAILED',
-
-  // Post errors
-  POST_CREATION_FAILED = 'POST_CREATION_FAILED',
-  THREAD_CREATION_FAILED = 'THREAD_CREATION_FAILED',
-  POST_DELETION_FAILED = 'POST_DELETION_FAILED',
-  POST_INTERACTION_FAILED = 'POST_INTERACTION_FAILED',
-
-  // Network errors
-  NETWORK_ERROR = 'NETWORK_ERROR',
-
-  MULTI_STATUS = 'MULTI_STATUS',
-}
-
-/**
- * API Error class for application-level errors
- */
-export class ApiError extends BaseError {
-  public readonly code: ApiErrorCode;
-  public readonly status: StatusCode;
-  public readonly details?: Record<string, any>;
-  public readonly recoverable: boolean;
-
-  constructor(
-    message: string,
-    code: ApiErrorCode = ApiErrorCode.INTERNAL_ERROR,
-    status: StatusCode = 500,
-    details?: Record<string, any>,
-    recoverable: boolean = false,
-  ) {
-    super(message);
-    this.code = code;
-    this.status = status;
-    this.details = details;
-    this.recoverable = recoverable;
-  }
-
-  /**
-   * Create a validation error
-   */
-  static validation(message: string, details?: Record<string, any>): ApiError {
-    return new ApiError(
-      message,
-      ApiErrorCode.VALIDATION_ERROR,
-      400,
-      details,
-      true,
-    );
-  }
-
-  /**
-   * Create an unauthorized error
-   */
-  static unauthorized(message: string = 'Unauthorized'): ApiError {
-    return new ApiError(
-      message,
-      ApiErrorCode.UNAUTHORIZED,
-      401,
-      undefined,
-      true,
-    );
-  }
-
-  /**
-   * Create a forbidden error
-   */
-  static forbidden(message: string = 'Forbidden'): ApiError {
-    return new ApiError(
-      message,
-      ApiErrorCode.FORBIDDEN,
-      403,
-      undefined,
-      false,
-    );
-  }
-
-  /**
-   * Create a not found error
-   */
-  static notFound(message: string = 'Resource not found'): ApiError {
-    return new ApiError(
-      message,
-      ApiErrorCode.NOT_FOUND,
-      404,
-      undefined,
-      false,
-    );
-  }
-
-  /**
-   * Create a rate limit error
-   */
-  static rateLimited(
-    message: string = 'Rate limit exceeded',
-    details?: Record<string, any>,
-  ): ApiError {
-    return new ApiError(
-      message,
-      ApiErrorCode.RATE_LIMITED,
-      429,
-      details,
-      true,
-    );
-  }
-
-  /**
-   * Create an internal server error
-   */
-  static internal(
-    message: string = 'Internal server error',
-    details?: Record<string, any>,
-  ): ApiError {
-    return new ApiError(
-      message,
-      ApiErrorCode.INTERNAL_ERROR,
-      500,
-      details,
-      false,
-    );
-  }
-}

package/src/errors/base-error.ts

@@ -1,13 +0,0 @@
-/**
- * Base Error class for all application errors
- */
-export class BaseError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = this.constructor.name;
-    // Maintains proper stack trace for where our error was thrown
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-}

package/src/errors/composite-api-error.ts

@@ -1,33 +0,0 @@
-import { ApiError, ApiErrorCode } from './api-error.ts';
-import type { ErrorDetail } from '../response.ts';
-import type { StatusCode } from 'hono/utils/http-status';
-
-/**
- * CompositeApiError represents a collection of multiple errors that occurred during an API operation.
- * This is particularly useful for handling multi-status responses (HTTP 207) where multiple operations
- * may have different outcomes.
- */
-export class CompositeApiError extends ApiError {
-  /**
-   * Array of individual error details
-   */
-  readonly errors: ErrorDetail[];
-
-  constructor(
-    message: string,
-    errors: ErrorDetail[],
-    status: StatusCode = 207,
-    details?: Record<string, any>,
-    recoverable: boolean = false,
-  ) {
-    super(
-      message,
-      ApiErrorCode.MULTI_STATUS,
-      status,
-      { ...details, errors },
-      recoverable,
-    );
-
-    this.errors = errors;
-  }
-}

package/src/errors/index.ts

@@ -1,8 +0,0 @@
-/**
- * Error types for the Crosspost API
- */
-
-export * from './base-error.ts';
-export * from './api-error.ts';
-export * from './platform-error.ts';
-export * from './composite-api-error.ts';

package/src/errors/platform-error.ts

@@ -1,34 +0,0 @@
-import { ApiErrorCode } from './api-error.ts';
-import type { PlatformName } from '../common.ts';
-import type { StatusCode } from 'hono/utils/http-status';
-
-/**
- * Platform Error
- * Custom error class for platform-specific errors
- */
-export class PlatformError extends Error {
-  public readonly code: ApiErrorCode;
-  public readonly recoverable: boolean;
-  public readonly platform: PlatformName;
-  public readonly userId?: string;
-  public readonly details?: Record<string, any>;
-
-  constructor(
-    message: string,
-    platform: PlatformName,
-    code: ApiErrorCode = ApiErrorCode.PLATFORM_ERROR,
-    recoverable: boolean = false,
-    public originalError?: unknown,
-    public status?: StatusCode,
-    userId?: string,
-    details?: Record<string, any>,
-  ) {
-    super(message);
-    this.name = 'PlatformError';
-    this.code = code;
-    this.recoverable = recoverable;
-    this.platform = platform;
-    this.userId = userId;
-    this.details = details;
-  }
-}