registry/ts/interfaces/package.interfaces.ts

/**
 * Package and artifact interfaces
 */

import type { TRegistryProtocol } from './auth.interfaces.ts';

// =============================================================================
// Package Types
// =============================================================================

export interface IPackage {
  id: string; // {protocol}:{org}:{name}
  organizationId: string;
  repositoryId: string;
  protocol: TRegistryProtocol;
  name: string;
  description?: string;
  versions: Record<string, IPackageVersion>;
  distTags: Record<string, string>; // npm dist-tags, e.g., { latest: "1.0.0" }
  metadata: IProtocolMetadata;
  isPrivate: boolean;
  storageBytes: number;
  downloadCount: number;
  starCount: number;
  cacheExpiresAt?: Date;
  createdAt: Date;
  updatedAt: Date;
  createdById: string;
}

export interface IPackageVersion {
  version: string;
  digest?: string; // Content-addressable digest (sha256:...)
  size: number;
  publishedAt: Date;
  publishedById: string;
  deprecated?: boolean;
  deprecationMessage?: string;
  downloads: number;
  metadata: IVersionMetadata;
}

// =============================================================================
// Protocol-Specific Metadata
// =============================================================================

export type IProtocolMetadata =
  | INpmMetadata
  | IOciMetadata
  | IMavenMetadata
  | ICargoMetadata
  | IComposerMetadata
  | IPypiMetadata
  | IRubygemsMetadata;

export interface INpmMetadata {
  type: 'npm';
  scope?: string;
  keywords?: string[];
  license?: string;
  repository?: {
    type: string;
    url: string;
  };
  homepage?: string;
  bugs?: string;
  author?: string | { name: string; email?: string; url?: string };
  maintainers?: Array<{ name: string; email?: string }>;
}

export interface IOciMetadata {
  type: 'oci';
  mediaType: string;
  tags: string[];
  architecture?: string;
  os?: string;
  annotations?: Record<string, string>;
}

export interface IMavenMetadata {
  type: 'maven';
  groupId: string;
  artifactId: string;
  packaging: string;
  classifier?: string;
  parent?: {
    groupId: string;
    artifactId: string;
    version: string;
  };
}

export interface ICargoMetadata {
  type: 'cargo';
  features: Record<string, string[]>;
  dependencies: Array<{
    name: string;
    req: string;
    features: string[];
    optional: boolean;
    defaultFeatures: boolean;
    target?: string;
    kind: 'normal' | 'dev' | 'build';
  }>;
  keywords?: string[];
  categories?: string[];
  license?: string;
  links?: string;
}

export interface IComposerMetadata {
  type: 'composer';
  vendor: string;
  packageType?: string;
  license?: string | string[];
  require?: Record<string, string>;
  requireDev?: Record<string, string>;
  autoload?: Record<string, unknown>;
}

export interface IPypiMetadata {
  type: 'pypi';
  classifiers?: string[];
  requiresPython?: string;
  requiresDist?: string[];
  providesExtra?: string[];
  projectUrls?: Record<string, string>;
}

export interface IRubygemsMetadata {
  type: 'rubygems';
  platform?: string;
  requiredRubyVersion?: string;
  requiredRubygemsVersion?: string;
  dependencies?: Array<{
    name: string;
    requirements: string;
    type: 'runtime' | 'development';
  }>;
}

// =============================================================================
// Version Metadata
// =============================================================================

export interface IVersionMetadata {
  readme?: string;
  changelog?: string;
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  engines?: Record<string, string>;
  files?: string[];
  checksum?: {
    sha256?: string;
    sha512?: string;
    md5?: string;
  };
}

// =============================================================================
// Search Types
// =============================================================================

export interface IPackageSearchParams {
  query?: string;
  protocol?: TRegistryProtocol;
  organizationId?: string;
  visibility?: 'public' | 'private' | 'internal';
  sort?: 'downloads' | 'stars' | 'updated' | 'name';
  order?: 'asc' | 'desc';
  offset?: number;
  limit?: number;
}

export interface IPackageSearchResult {
  packages: IPackage[];
  total: number;
  offset: number;
  limit: number;
}

// =============================================================================
// Stats Types
// =============================================================================

export interface IPackageStats {
  packageId: string;
  totalDownloads: number;
  downloadsByVersion: Record<string, number>;
  downloadsByDay: Array<{ date: string; count: number }>;
  downloadsByCountry?: Record<string, number>;
}

export interface IOrganizationStats {
  organizationId: string;
  totalPackages: number;
  totalDownloads: number;
  storageUsedBytes: number;
  storageQuotaBytes: number;
  packagesByProtocol: Record<TRegistryProtocol, number>;
}