@crosspost/types 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crosspost/types",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Shared type definitions for Crosspost API",
   "type": "module",
   "main": "dist/index.cjs",

package/src/activity.ts

@@ -1,16 +1,6 @@
-/**
- * Activity Schemas and Types
- * Defines Zod schemas for activity-related requests and responses
- * TypeScript types are derived from Zod schemas for type safety
- */
-
 import { z } from 'zod';
-import { EnhancedResponseSchema } from './response.ts';
 import { PlatformSchema } from './common.ts';
 
-/**
- * Time periods for activity filtering
- */
 export enum TimePeriod {
   ALL = 'all',
   YEARLY = 'year',
@@ -19,9 +9,6 @@ export enum TimePeriod {
   DAILY = 'day',
 }
 
-/**
- * Activity leaderboard query schema
- */
 export const ActivityLeaderboardQuerySchema = z.object({
   timeframe: z.nativeEnum(TimePeriod).optional().describe(
     'Timeframe for the leaderboard',
@@ -36,9 +23,6 @@ export const ActivityLeaderboardQuerySchema = z.object({
     .describe('Offset for pagination'),
 }).describe('Activity leaderboard query');
 
-/**
- * Account activity entry schema
- */
 export const AccountActivityEntrySchema = z.object({
   signerId: z.string().describe('NEAR account ID'),
   totalPosts: z.number().describe('Total number of posts'),
@@ -51,39 +35,23 @@ export const AccountActivityEntrySchema = z.object({
   lastActive: z.string().datetime().describe('Timestamp of last activity'),
 }).describe('Account activity entry');
 
-/**
- * Activity leaderboard response schema
- */
-export const ActivityLeaderboardResponseSchema = EnhancedResponseSchema(
-  z.object({
-    timeframe: z.nativeEnum(TimePeriod).describe('Timeframe for the leaderboard'),
-    entries: z.array(AccountActivityEntrySchema).describe('Leaderboard entries'),
-    total: z.number().describe('Total number of entries in the leaderboard'),
-    limit: z.number().describe('Maximum number of results returned'),
-    offset: z.number().describe('Offset for pagination'),
-    generatedAt: z.string().datetime().describe('Timestamp when the leaderboard was generated'),
-  }),
-).describe('Activity leaderboard response');
+const ActivityLeaderboardResponseSchema = z.object({
+  timeframe: z.nativeEnum(TimePeriod).describe('Timeframe for the leaderboard'),
+  entries: z.array(AccountActivityEntrySchema).describe('Leaderboard entries'),
+  generatedAt: z.string().datetime().describe('Timestamp when the leaderboard was generated'),
+  platform: PlatformSchema.optional().describe('Platform filter (if applied)'),
+});
 
-/**
- * Account activity params schema
- */
 export const AccountActivityParamsSchema = z.object({
   signerId: z.string().describe('NEAR account ID'),
 }).describe('Account activity params');
 
-/**
- * Account activity query schema
- */
 export const AccountActivityQuerySchema = z.object({
   timeframe: z.nativeEnum(TimePeriod).optional().describe(
     'Timeframe for the activity',
   ),
 }).describe('Account activity query');
 
-/**
- * Platform activity schema
- */
 export const PlatformActivitySchema = z.object({
   platform: PlatformSchema,
   posts: z.number().describe('Number of posts on this platform'),
@@ -95,35 +63,24 @@ export const PlatformActivitySchema = z.object({
   lastActive: z.string().datetime().describe('Timestamp of last activity on this platform'),
 }).describe('Platform activity');
 
-/**
- * Account activity response schema
- */
-export const AccountActivityResponseSchema = EnhancedResponseSchema(
-  z.object({
-    signerId: z.string().describe('NEAR account ID'),
-    timeframe: z.nativeEnum(TimePeriod).describe('Timeframe for the activity'),
-    totalPosts: z.number().describe('Total number of posts across all platforms'),
-    totalLikes: z.number().describe('Total number of likes across all platforms'),
-    totalReposts: z.number().describe('Total number of reposts across all platforms'),
-    totalReplies: z.number().describe('Total number of replies across all platforms'),
-    totalQuotes: z.number().describe('Total number of quote posts across all platforms'),
-    totalScore: z.number().describe('Total activity score across all platforms'),
-    rank: z.number().describe('Rank on the leaderboard'),
-    lastActive: z.string().datetime().describe('Timestamp of last activity across all platforms'),
-    platforms: z.array(PlatformActivitySchema).describe('Activity breakdown by platform'),
-  }),
-).describe('Account activity response');
+const AccountActivityResponseSchema = z.object({
+  signerId: z.string().describe('NEAR account ID'),
+  timeframe: z.nativeEnum(TimePeriod).describe('Timeframe for the activity'),
+  totalPosts: z.number().describe('Total number of posts across all platforms'),
+  totalLikes: z.number().describe('Total number of likes across all platforms'),
+  totalReposts: z.number().describe('Total number of reposts across all platforms'),
+  totalReplies: z.number().describe('Total number of replies across all platforms'),
+  totalQuotes: z.number().describe('Total number of quote posts across all platforms'),
+  totalScore: z.number().describe('Total activity score across all platforms'),
+  rank: z.number().describe('Rank on the leaderboard'),
+  lastActive: z.string().datetime().describe('Timestamp of last activity across all platforms'),
+  platforms: z.array(PlatformActivitySchema).describe('Activity breakdown by platform'),
+});
 
-/**
- * Account posts params schema
- */
 export const AccountPostsParamsSchema = z.object({
   signerId: z.string().describe('NEAR account ID'),
 }).describe('Account posts params');
 
-/**
- * Account posts query schema
- */
 export const AccountPostsQuerySchema = z.object({
   platform: z.string().optional().describe('Filter by platform (optional)'),
   limit: z.string().optional()
@@ -139,9 +96,6 @@ export const AccountPostsQuerySchema = z.object({
   ),
 }).describe('Account posts query');
 
-/**
- * Account post schema
- */
 export const AccountPostSchema = z.object({
   id: z.string().describe('Post ID'),
   platform: PlatformSchema,
@@ -159,25 +113,17 @@ export const AccountPostSchema = z.object({
   quotedPostId: z.string().optional().describe('ID of the post this is quoting (if applicable)'),
 }).describe('Account post');
 
-/**
- * Account posts response schema
- */
-export const AccountPostsResponseSchema = EnhancedResponseSchema(
-  z.object({
-    signerId: z.string().describe('NEAR account ID'),
-    posts: z.array(AccountPostSchema).describe('List of posts'),
-    total: z.number().describe('Total number of posts matching the query'),
-    limit: z.number().describe('Maximum number of results returned'),
-    offset: z.number().describe('Offset for pagination'),
-    platform: z.string().optional().describe('Platform filter (if applied)'),
-    type: z.enum(['post', 'repost', 'reply', 'quote', 'like', 'all']).optional().describe(
-      'Post type filter (if applied)',
-    ),
-  }),
-).describe('Account posts response');
+const AccountPostsResponseSchema = z.object({
+  signerId: z.string().describe('NEAR account ID'),
+  posts: z.array(AccountPostSchema).describe('List of posts'),
+  platform: z.string().optional().describe('Platform filter (if applied)'),
+  type: z.enum(['post', 'repost', 'reply', 'quote', 'like', 'all']).optional().describe(
+    'Post type filter (if applied)',
+  ),
+});
 
 /**
- * Interface for account activity data
+ * Interface for account activity Response
  */
 export interface AccountActivity {
   signerId: string;
@@ -187,14 +133,14 @@ export interface AccountActivity {
 }
 
 /**
- * Interface for platform-specific account activity data
+ * Interface for platform-specific account activity Response
  */
 export interface PlatformAccountActivity extends AccountActivity {
   platform: string;
 }
 
 /**
- * Interface for post record data (storage optimized)
+ * Interface for post record Response (storage optimized)
  */
 export interface PostRecord {
   id: string; // postId
@@ -203,33 +149,6 @@ export interface PostRecord {
   u: string; // userId
 }
 
-/**
- * Interface for post record data (API response)
- */
-export interface PostRecordResponse {
-  postId: string;
-  platform: string;
-  timestamp: string;
-  userId: string;
-}
-
-/**
- * Interface for leaderboard entry
- */
-export interface LeaderboardEntry {
-  signerId: string;
-  postCount: number;
-  lastPostTimestamp: number;
-}
-
-/**
- * Interface for platform-specific leaderboard entry
- */
-export interface PlatformLeaderboardEntry extends LeaderboardEntry {
-  platform: string;
-}
-
-// Derive TypeScript types from Zod schemas
 export type ActivityLeaderboardQuery = z.infer<typeof ActivityLeaderboardQuerySchema>;
 export type AccountActivityEntry = z.infer<typeof AccountActivityEntrySchema>;
 export type ActivityLeaderboardResponse = z.infer<typeof ActivityLeaderboardResponseSchema>;
@@ -241,7 +160,3 @@ export type AccountPostsParams = z.infer<typeof AccountPostsParamsSchema>;
 export type AccountPostsQuery = z.infer<typeof AccountPostsQuerySchema>;
 export type AccountPost = z.infer<typeof AccountPostSchema>;
 export type AccountPostsResponse = z.infer<typeof AccountPostsResponseSchema>;
-
-// Legacy type aliases for backward compatibility
-export type LeaderboardQuery = ActivityLeaderboardQuery;
-export type LeaderboardResponse = ActivityLeaderboardResponse;

package/src/auth.ts

@@ -1,19 +1,10 @@
-/**
- * Auth Schemas and Types
- * Defines Zod schemas for authentication-related requests and responses
- * TypeScript types are derived from Zod schemas for type safety
- */
-
 import { z } from 'zod';
-import { EnhancedResponseSchema } from './response.ts';
 import { PlatformSchema } from './common.ts';
 
-// Platform parameter schema
 export const PlatformParamSchema = z.object({
   platform: z.string().describe('Social media platform'),
 }).describe('Platform parameter');
 
-// Auth initialization request schema
 export const AuthInitRequestSchema = z.object({
   successUrl: z.string().url().optional().describe(
     'URL to redirect to on successful authentication',
@@ -21,55 +12,43 @@ export const AuthInitRequestSchema = z.object({
   errorUrl: z.string().url().optional().describe('URL to redirect to on authentication error'),
 }).describe('Auth initialization request');
 
-// Auth URL response schema
-export const AuthUrlResponseSchema = EnhancedResponseSchema(
-  z.object({
-    url: z.string().describe('Authentication URL to redirect the user to'),
-    state: z.string().describe('State parameter for CSRF protection'),
-    platform: PlatformSchema,
-  }),
-).describe('Auth URL response');
+export const AuthUrlResponseSchema = z.object({
+  url: z.string().describe('Authentication URL to redirect the user to'),
+  state: z.string().describe('State parameter for CSRF protection'),
+  platform: PlatformSchema,
+}).describe('Auth URL response');
 
-// Auth callback query schema
 export const AuthCallbackQuerySchema = z.object({
   code: z.string().describe('Authorization code from OAuth provider'),
   state: z.string().describe('State parameter for CSRF protection'),
 }).describe('Auth callback query');
 
-// Auth callback response schema
-export const AuthCallbackResponseSchema = EnhancedResponseSchema(
-  z.object({
-    success: z.boolean().describe('Whether the authentication was successful'),
-    platform: PlatformSchema,
-    userId: z.string().describe('User ID'),
-    redirectUrl: z.string().optional().describe('URL to redirect the user to after authentication'),
-  }),
-).describe('Auth callback response');
+export const AuthCallbackResponseSchema = z.object({
+  platform: PlatformSchema,
+  userId: z.string().describe('User ID'),
+  redirectUrl: z.string().optional().describe('URL to redirect the user to after authentication'),
+}).describe('Auth callback response');
 
-// Auth status response schema
-export const AuthStatusResponseSchema = EnhancedResponseSchema(
-  z.object({
-    platform: PlatformSchema,
-    userId: z.string().describe('User ID'),
-    authenticated: z.boolean().describe('Whether the user is authenticated'),
-    tokenStatus: z.object({
-      valid: z.boolean().describe('Whether the token is valid'),
-      expired: z.boolean().describe('Whether the token is expired'),
-      expiresAt: z.string().optional().describe('When the token expires'),
-    }),
+export const AuthStatusResponseSchema = z.object({
+  platform: PlatformSchema,
+  userId: z.string().describe('User ID'),
+  authenticated: z.boolean().describe('Whether the user is authenticated'),
+  tokenStatus: z.object({
+    valid: z.boolean().describe('Whether the token is valid'),
+    expired: z.boolean().describe('Whether the token is expired'),
+    expiresAt: z.string().optional().describe('When the token expires'),
   }),
-).describe('Auth status response');
+}).describe('Auth status response');
 
-// Auth revoke response schema
-export const AuthRevokeResponseSchema = EnhancedResponseSchema(
-  z.object({
-    success: z.boolean().describe('Whether the revocation was successful'),
-    platform: PlatformSchema,
-    userId: z.string().describe('User ID'),
-  }),
-).describe('Auth revoke response');
+export const AuthTokenRequestSchema = z.object({
+  userId: z.string().describe('User ID on the platform'),
+}).describe('Auth token request');
+
+export const AuthRevokeResponseSchema = z.object({
+  platform: PlatformSchema,
+  userId: z.string().describe('User ID'),
+}).describe('Auth revoke response');
 
-// Connected account schema
 export const ConnectedAccountSchema = z.object({
   platform: PlatformSchema,
   userId: z.string().describe('User ID on the platform'),
@@ -78,35 +57,25 @@ export const ConnectedAccountSchema = z.object({
   connectedAt: z.string().optional().describe('When the account was connected'),
 }).describe('Connected account');
 
-// Connected accounts response schema
-export const ConnectedAccountsResponseSchema = EnhancedResponseSchema(
-  z.array(ConnectedAccountSchema),
-).describe('Connected accounts response');
+export const ConnectedAccountsResponseSchema = z.array(ConnectedAccountSchema).describe(
+  'Connected accounts response',
+);
 
-// NEAR authorization request schema
 export const NearAuthorizationRequestSchema = z.object({
   // No additional parameters needed, as the NEAR account ID is extracted from the signature
 }).describe('NEAR authorization request');
 
-// NEAR authorization response schema
-export const NearAuthorizationResponseSchema = EnhancedResponseSchema(
-  z.object({
-    success: z.boolean().describe('Whether the authorization was successful'),
-    nearAccount: z.string().describe('NEAR account ID'),
-    authorized: z.boolean().describe('Whether the account is authorized'),
-  }),
-).describe('NEAR authorization response');
+export const NearAuthorizationResponseSchema = z.object({
+  nearAccount: z.string().describe('NEAR account ID'),
+  authorized: z.boolean().describe('Whether the account is authorized'),
+}).describe('NEAR authorization response');
 
-// NEAR authorization status response schema
-export const NearAuthorizationStatusResponseSchema = EnhancedResponseSchema(
-  z.object({
-    nearAccount: z.string().describe('NEAR account ID'),
-    authorized: z.boolean().describe('Whether the account is authorized'),
-    authorizedAt: z.string().optional().describe('When the account was authorized'),
-  }),
-).describe('NEAR authorization status response');
+export const NearAuthorizationStatusResponseSchema = z.object({
+  nearAccount: z.string().describe('NEAR account ID'),
+  authorized: z.boolean().describe('Whether the account is authorized'),
+  authorizedAt: z.string().optional().describe('When the account was authorized'),
+}).describe('NEAR authorization status response');
 
-// Derive TypeScript types from Zod schemas
 export type PlatformParam = z.infer<typeof PlatformParamSchema>;
 export type AuthInitRequest = z.infer<typeof AuthInitRequestSchema>;
 export type AuthUrlResponse = z.infer<typeof AuthUrlResponseSchema>;
@@ -119,3 +88,4 @@ export type ConnectedAccountsResponse = z.infer<typeof ConnectedAccountsResponse
 export type NearAuthorizationRequest = z.infer<typeof NearAuthorizationRequestSchema>;
 export type NearAuthorizationResponse = z.infer<typeof NearAuthorizationResponseSchema>;
 export type NearAuthorizationStatusResponse = z.infer<typeof NearAuthorizationStatusResponseSchema>;
+export type AuthTokenRequest = z.infer<typeof AuthTokenRequestSchema>;

package/src/common.ts

@@ -1,12 +1,7 @@
-/**
- * Common Schemas and Types
- * Defines common Zod schemas and derived TypeScript types used across the API
- */
-
 import { z } from 'zod';
 
 /**
- * Platform enum - All platforms (including planned ones)
+ * Platform enum
  */
 export enum Platform {
   UNKNOWN = 'unknown',
@@ -17,14 +12,14 @@ export enum Platform {
   // INSTAGRAM = 'instagram',
 }
 
-export const PlatformSchema = z.nativeEnum(Platform)
-  .describe('Social media platform');
-
 /**
- * Platform type - Derived from the Platform enum
+ * PlatformName type - Derived from the Platform enum
  */
 export type PlatformName = Platform;
 
+export const PlatformSchema = z.nativeEnum(Platform)
+  .describe('Social media platform');
+
 /**
  * Array of currently supported platforms
  */
@@ -47,3 +42,6 @@ SupportedPlatformSchema.describe('Currently supported social media platforms');
 export function isPlatformSupported(platform: Platform): platform is SupportedPlatformName {
   return (SUPPORTED_PLATFORMS as readonly Platform[]).includes(platform);
 }
+
+// Re-export StatusCode from hono
+export type { StatusCode } from 'hono/utils/http-status';

package/src/errors.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import type { ResponseMeta } from './response.ts';
+import type { PlatformName } from './common.ts';
+import type { StatusCode } from './index.ts';
+
+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
+  MULTI_STATUS = 'MULTI_STATUS',
+  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',
+}
+
+export const ApiErrorCodeSchema = z.enum(Object.values(ApiErrorCode) as [string, ...string[]]);
+
+/**
+ * Map of API error codes to HTTP status codes
+ * This ensures consistent HTTP status codes across the application
+ */
+export const errorCodeToStatusCode: Record<ApiErrorCode, StatusCode> = {
+  [ApiErrorCode.MULTI_STATUS]: 207,
+  [ApiErrorCode.UNKNOWN_ERROR]: 500,
+  [ApiErrorCode.INTERNAL_ERROR]: 500,
+  [ApiErrorCode.VALIDATION_ERROR]: 400,
+  [ApiErrorCode.INVALID_REQUEST]: 400,
+  [ApiErrorCode.NOT_FOUND]: 404,
+  [ApiErrorCode.UNAUTHORIZED]: 401,
+  [ApiErrorCode.FORBIDDEN]: 403,
+  [ApiErrorCode.RATE_LIMITED]: 429,
+  [ApiErrorCode.PLATFORM_ERROR]: 502,
+  [ApiErrorCode.PLATFORM_UNAVAILABLE]: 503,
+  [ApiErrorCode.CONTENT_POLICY_VIOLATION]: 400,
+  [ApiErrorCode.DUPLICATE_CONTENT]: 400,
+  [ApiErrorCode.MEDIA_UPLOAD_FAILED]: 400,
+  [ApiErrorCode.POST_CREATION_FAILED]: 500,
+  [ApiErrorCode.THREAD_CREATION_FAILED]: 500,
+  [ApiErrorCode.POST_DELETION_FAILED]: 500,
+  [ApiErrorCode.POST_INTERACTION_FAILED]: 500,
+  [ApiErrorCode.NETWORK_ERROR]: 503,
+};
+
+/**
+ * Common error details that can be included in any error
+ */
+export interface ErrorDetails {
+  platform?: PlatformName;
+  userId?: string;
+  [key: string]: unknown;
+}
+
+export const ErrorDetailSchema = z.object({
+  message: z.string().describe('Human-readable error message'),
+  code: ApiErrorCodeSchema.describe('Machine-readable error code'),
+  recoverable: z.boolean().describe('Whether the error can be recovered from'),
+  details: z.record(z.unknown()).optional().describe('Additional error details'),
+});
+
+export type ErrorDetail = z.infer<typeof ErrorDetailSchema>;
+
+export interface ApiErrorResponse {
+  success: false;
+  errors: ErrorDetail[];
+  meta: ResponseMeta;
+}

package/src/index.ts

@@ -1,18 +1,6 @@
-/**
- * @crosspost/types
- * Shared TypeScript type definitions and Zod schemas for the Crosspost API ecosystem
- */
-
-// Export common types and schemas
 export * from './common.ts';
-
-// Export enhanced response types and schemas
 export * from './response.ts';
-
-// Export error types
-export * from './errors/index.ts';
-
-// Export domain-specific types and schemas
+export * from './errors.ts';
 export * from './auth.ts';
 export * from './post.ts';
 export * from './rate-limit.ts';