smartregistry/ts/pypi/interfaces.pypi.ts

/**
 * PyPI Registry Type Definitions
 * Compliant with PEP 503 (Simple API), PEP 691 (JSON API), and PyPI upload API
 */

/**
 * File information for a package distribution
 * Used in both PEP 503 HTML and PEP 691 JSON responses
 */
export interface IPypiFile {
  /** Filename (e.g., "package-1.0.0-py3-none-any.whl") */
  filename: string;
  /** Download URL (absolute or relative) */
  url: string;
  /** Hash digests (multiple algorithms supported in JSON) */
  hashes: Record<string, string>;
  /** Python version requirement (PEP 345 format) */
  'requires-python'?: string;
  /** Whether distribution info metadata is available (PEP 658) */
  'dist-info-metadata'?: boolean | { sha256: string };
  /** Whether GPG signature is available */
  'gpg-sig'?: boolean;
  /** Yank status: false or reason string */
  yanked?: boolean | string;
  /** File size in bytes */
  size?: number;
  /** Upload timestamp */
  'upload-time'?: string;
}

/**
 * Package metadata stored internally
 * Consolidated from multiple file uploads
 */
export interface IPypiPackageMetadata {
  /** Normalized package name */
  name: string;
  /** Map of version to file list */
  versions: Record<string, IPypiVersionMetadata>;
  /** Timestamp of last update */
  'last-modified'?: string;
}

/**
 * Metadata for a specific version
 */
export interface IPypiVersionMetadata {
  /** Version string */
  version: string;
  /** Files for this version (wheels, sdists) */
  files: IPypiFileMetadata[];
  /** Core metadata fields */
  metadata?: IPypiCoreMetadata;
  /** Whether entire version is yanked */
  yanked?: boolean | string;
  /** Upload timestamp */
  'upload-time'?: string;
}

/**
 * Internal file metadata
 */
export interface IPypiFileMetadata {
  filename: string;
  /** Storage key/path */
  path: string;
  /** File type: bdist_wheel or sdist */
  filetype: 'bdist_wheel' | 'sdist';
  /** Python version tag */
  python_version: string;
  /** Hash digests */
  hashes: Record<string, string>;
  /** File size in bytes */
  size: number;
  /** Python version requirement */
  'requires-python'?: string;
  /** Whether this file is yanked */
  yanked?: boolean | string;
  /** Upload timestamp */
  'upload-time': string;
  /** Uploader user ID */
  'uploaded-by': string;
}

/**
 * Core metadata fields (subset of PEP 566)
 * These are extracted from package uploads
 */
export interface IPypiCoreMetadata {
  /** Metadata version */
  'metadata-version': string;
  /** Package name */
  name: string;
  /** Version string */
  version: string;
  /** Platform compatibility */
  platform?: string;
  /** Supported platforms */
  'supported-platform'?: string;
  /** Summary/description */
  summary?: string;
  /** Long description */
  description?: string;
  /** Description content type (text/plain, text/markdown, text/x-rst) */
  'description-content-type'?: string;
  /** Keywords */
  keywords?: string;
  /** Homepage URL */
  'home-page'?: string;
  /** Download URL */
  'download-url'?: string;
  /** Author name */
  author?: string;
  /** Author email */
  'author-email'?: string;
  /** Maintainer name */
  maintainer?: string;
  /** Maintainer email */
  'maintainer-email'?: string;
  /** License */
  license?: string;
  /** Classifiers (Trove classifiers) */
  classifier?: string[];
  /** Python version requirement */
  'requires-python'?: string;
  /** Dist name requirement */
  'requires-dist'?: string[];
  /** External requirement */
  'requires-external'?: string[];
  /** Provides dist */
  'provides-dist'?: string[];
  /** Project URLs */
  'project-url'?: string[];
  /** Provides extra */
  'provides-extra'?: string[];
}

/**
 * PEP 503: Simple API root response (project list)
 */
export interface IPypiSimpleRootHtml {
  /** List of project names */
  projects: string[];
}

/**
 * PEP 503: Simple API project response (file list)
 */
export interface IPypiSimpleProjectHtml {
  /** Normalized project name */
  name: string;
  /** List of files */
  files: IPypiFile[];
}

/**
 * PEP 691: JSON API root response
 */
export interface IPypiJsonRoot {
  /** API metadata */
  meta: {
    /** API version (e.g., "1.0") */
    'api-version': string;
  };
  /** List of projects */
  projects: Array<{
    /** Project name */
    name: string;
  }>;
}

/**
 * PEP 691: JSON API project response
 */
export interface IPypiJsonProject {
  /** Normalized project name */
  name: string;
  /** API metadata */
  meta: {
    /** API version (e.g., "1.0") */
    'api-version': string;
  };
  /** List of files */
  files: IPypiFile[];
}

/**
 * Upload form data (multipart/form-data fields)
 * Based on PyPI legacy upload API
 */
export interface IPypiUploadForm {
  /** Action type (always "file_upload") */
  ':action': 'file_upload';
  /** Protocol version (always "1") */
  protocol_version: '1';
  /** File content (binary) */
  content: Buffer;
  /** File type */
  filetype: 'bdist_wheel' | 'sdist';
  /** Python version tag */
  pyversion: string;
  /** Package name */
  name: string;
  /** Version string */
  version: string;
  /** Metadata version */
  metadata_version: string;
  /** Hash digests (at least one required) */
  md5_digest?: string;
  sha256_digest?: string;
  blake2_256_digest?: string;
  /** Optional attestations */
  attestations?: string; // JSON array
  /** Optional core metadata fields */
  summary?: string;
  description?: string;
  description_content_type?: string;
  author?: string;
  author_email?: string;
  maintainer?: string;
  maintainer_email?: string;
  license?: string;
  keywords?: string;
  home_page?: string;
  download_url?: string;
  requires_python?: string;
  classifiers?: string[];
  platform?: string;
  [key: string]: any; // Allow additional metadata fields
}

/**
 * JSON API upload response
 */
export interface IPypiUploadResponse {
  /** Success message */
  message?: string;
  /** URL of uploaded file */
  url?: string;
}

/**
 * Error response structure
 */
export interface IPypiError {
  /** Error message */
  message: string;
  /** HTTP status code */
  status?: number;
  /** Additional error details */
  details?: string[];
}

/**
 * Search query parameters
 */
export interface IPypiSearchQuery {
  /** Search term */
  q?: string;
  /** Page number */
  page?: number;
  /** Results per page */
  per_page?: number;
}

/**
 * Search result for a single package
 */
export interface IPypiSearchResult {
  /** Package name */
  name: string;
  /** Latest version */
  version: string;
  /** Summary */
  summary: string;
  /** Description */
  description?: string;
}

/**
 * Search response structure
 */
export interface IPypiSearchResponse {
  /** Search results */
  results: IPypiSearchResult[];
  /** Result count */
  count: number;
  /** Current page */
  page: number;
  /** Total pages */
  pages: number;
}

/**
 * Yank request
 */
export interface IPypiYankRequest {
  /** Package name */
  name: string;
  /** Version to yank */
  version: string;
  /** Optional filename (specific file) */
  filename?: string;
  /** Reason for yanking */
  reason?: string;
}

/**
 * Yank response
 */
export interface IPypiYankResponse {
  /** Success indicator */
  success: boolean;
  /** Message */
  message?: string;
}