@crosspost/types 0.1.2

package/mod.ts

@@ -0,0 +1,9 @@
+/**
+ * @crosspost/types
+ * Shared type definitions for 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,51 @@
+{
+  "name": "@crosspost/types",
+  "version": "0.1.2",
+  "description": "Shared type definitions for 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 --tsconfig tsconfig.node.json",
+    "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",
+    "types",
+    "api",
+    "social-media"
+  ],
+  "author": "crosspost.near",
+  "license": "MIT",
+  "devDependencies": {
+    "eslint": "^8.56.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "hono": "^4.7.6",
+    "zod": "^3.24.2"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,121 @@
+/**
+ * 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',
+  ),
+  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');
+
+// 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');
+
+// 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'),
+    }),
+  }),
+).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');
+
+// Connected account schema
+export const ConnectedAccountSchema = z.object({
+  platform: PlatformSchema,
+  userId: z.string().describe('User ID on the platform'),
+  username: z.string().optional().describe('Username on the platform (if available)'),
+  profileUrl: z.string().optional().describe('URL to the user profile'),
+  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');
+
+// 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');
+
+// 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');
+
+// 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>;
+export type AuthCallbackQuery = z.infer<typeof AuthCallbackQuerySchema>;
+export type AuthCallbackResponse = z.infer<typeof AuthCallbackResponseSchema>;
+export type AuthStatusResponse = z.infer<typeof AuthStatusResponseSchema>;
+export type AuthRevokeResponse = z.infer<typeof AuthRevokeResponseSchema>;
+export type ConnectedAccount = z.infer<typeof ConnectedAccountSchema>;
+export type ConnectedAccountsResponse = z.infer<typeof ConnectedAccountsResponseSchema>;
+export type NearAuthorizationRequest = z.infer<typeof NearAuthorizationRequestSchema>;
+export type NearAuthorizationResponse = z.infer<typeof NearAuthorizationResponseSchema>;
+export type NearAuthorizationStatusResponse = z.infer<typeof NearAuthorizationStatusResponseSchema>;

package/src/common.ts

@@ -0,0 +1,33 @@
+/**
+ * Common Schemas and Types
+ * Defines common Zod schemas and derived TypeScript types used across the API
+ */
+
+import { z } from 'zod';
+
+/**
+ * Platform schema
+ */
+export const PlatformSchema = z.enum([
+  'unknown',
+  'twitter',
+  // Add more platforms as they're implemented
+  // 'linkedin',
+  // 'facebook',
+  // 'instagram',
+]).describe('Social media platform');
+
+// Derive TypeScript types from Zod schemas
+export type PlatformName = z.infer<typeof PlatformSchema>;
+
+/**
+ * Enum for supported platforms (for backward compatibility)
+ */
+export enum Platform {
+  UNKNOWN = 'unknown',
+  TWITTER = 'twitter',
+  // Add more platforms as they're implemented
+  // LINKEDIN = 'linkedin',
+  // FACEBOOK = 'facebook',
+  // INSTAGRAM = 'instagram',
+}

package/src/errors/api-error.ts

@@ -0,0 +1,153 @@
+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',
+}
+
+/**
+ * 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

@@ -0,0 +1,13 @@
+/**
+ * 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/index.ts

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

package/src/errors/platform-error.ts

@@ -0,0 +1,34 @@
+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;
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @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 './auth.ts';
+export * from './post.ts';
+export * from './rate-limit.ts';
+export * from './leaderboard.ts';
+export * from './user-profile.ts';

package/src/leaderboard.ts

@@ -0,0 +1,179 @@
+/**
+ * Leaderboard Schemas and Types
+ * Defines Zod schemas for leaderboard-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';
+
+/**
+ * Leaderboard query schema
+ */
+export const LeaderboardQuerySchema = z.object({
+  timeframe: z.enum(['day', 'week', 'month', 'all']).optional().describe(
+    'Timeframe for the leaderboard',
+  ),
+  limit: z.string().optional()
+    .transform((val) => val ? parseInt(val, 10) : undefined)
+    .pipe(z.number().min(1).max(100).optional())
+    .describe('Maximum number of results to return (1-100)'),
+  offset: z.string().optional()
+    .transform((val) => val ? parseInt(val, 10) : undefined)
+    .pipe(z.number().min(0).optional())
+    .describe('Offset for pagination'),
+}).describe('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'),
+  totalLikes: z.number().describe('Total number of likes'),
+  totalReposts: z.number().describe('Total number of reposts'),
+  totalReplies: z.number().describe('Total number of replies'),
+  totalQuotes: z.number().describe('Total number of quote posts'),
+  totalScore: z.number().describe('Total activity score'),
+  rank: z.number().describe('Rank on the leaderboard'),
+  lastActive: z.string().datetime().describe('Timestamp of last activity'),
+}).describe('Account activity entry');
+
+/**
+ * Leaderboard response schema
+ */
+export const LeaderboardResponseSchema = EnhancedResponseSchema(
+  z.object({
+    timeframe: z.enum(['day', 'week', 'month', 'all']).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('Leaderboard response');
+
+/**
+ * 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.enum(['day', 'week', 'month', 'all']).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'),
+  likes: z.number().describe('Number of likes on this platform'),
+  reposts: z.number().describe('Number of reposts on this platform'),
+  replies: z.number().describe('Number of replies on this platform'),
+  quotes: z.number().describe('Number of quote posts on this platform'),
+  score: z.number().describe('Activity score on this platform'),
+  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.enum(['day', 'week', 'month', 'all']).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');
+
+/**
+ * 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()
+    .transform((val) => val ? parseInt(val, 10) : undefined)
+    .pipe(z.number().min(1).max(100).optional())
+    .describe('Maximum number of results to return (1-100)'),
+  offset: z.string().optional()
+    .transform((val) => val ? parseInt(val, 10) : undefined)
+    .pipe(z.number().min(0).optional())
+    .describe('Offset for pagination'),
+  type: z.enum(['post', 'repost', 'reply', 'quote', 'like', 'all']).optional().describe(
+    'Filter by post type (optional)',
+  ),
+}).describe('Account posts query');
+
+/**
+ * Account post schema
+ */
+export const AccountPostSchema = z.object({
+  id: z.string().describe('Post ID'),
+  platform: PlatformSchema,
+  type: z.enum(['post', 'repost', 'reply', 'quote', 'like']).describe('Type of post'),
+  content: z.string().optional().describe('Post content (if available)'),
+  url: z.string().url().optional().describe('URL to the post on the platform (if available)'),
+  createdAt: z.string().datetime().describe('Timestamp when the post was created'),
+  metrics: z.object({
+    likes: z.number().optional().describe('Number of likes (if available)'),
+    reposts: z.number().optional().describe('Number of reposts (if available)'),
+    replies: z.number().optional().describe('Number of replies (if available)'),
+    quotes: z.number().optional().describe('Number of quotes (if available)'),
+  }).optional().describe('Post metrics (if available)'),
+  inReplyToId: z.string().optional().describe('ID of the post this is a reply to (if applicable)'),
+  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');
+
+// Derive TypeScript types from Zod schemas
+export type LeaderboardQuery = z.infer<typeof LeaderboardQuerySchema>;
+export type AccountActivityEntry = z.infer<typeof AccountActivityEntrySchema>;
+export type LeaderboardResponse = z.infer<typeof LeaderboardResponseSchema>;
+export type AccountActivityParams = z.infer<typeof AccountActivityParamsSchema>;
+export type AccountActivityQuery = z.infer<typeof AccountActivityQuerySchema>;
+export type PlatformActivity = z.infer<typeof PlatformActivitySchema>;
+export type AccountActivityResponse = z.infer<typeof AccountActivityResponseSchema>;
+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>;