smartregistry/ts/npm/interfaces.npm.ts

/**
 * NPM Registry interfaces and types
 * Based on npm registry API specification
 */

/**
 * NPM package version metadata
 */
export interface INpmVersion {
  name: string;
  version: string;
  description?: string;
  main?: string;
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  optionalDependencies?: Record<string, string>;
  bundleDependencies?: string[];
  bin?: Record<string, string> | string;
  scripts?: Record<string, string>;
  engines?: Record<string, string>;
  keywords?: string[];
  author?: INpmPerson | string;
  maintainers?: INpmPerson[];
  contributors?: INpmPerson[];
  license?: string;
  repository?: INpmRepository;
  bugs?: string | { url?: string; email?: string };
  homepage?: string;
  readme?: string;
  dist: INpmDist;
  _id: string;
  _nodeVersion?: string;
  _npmVersion?: string;
  _npmUser?: INpmPerson;
  [key: string]: any; // Allow additional fields
}

/**
 * Distribution information for a version
 */
export interface INpmDist {
  /** URL to the tarball */
  tarball: string;
  /** SHA-1 hash */
  shasum: string;
  /** Subresource Integrity hash (SHA-512) */
  integrity?: string;
  /** Number of files in the package */
  fileCount?: number;
  /** Total size when unpacked */
  unpackedSize?: number;
  /** PGP signature */
  'npm-signature'?: string;
}

/**
 * Person (author, maintainer, contributor)
 */
export interface INpmPerson {
  name: string;
  email?: string;
  url?: string;
}

/**
 * Repository information
 */
export interface INpmRepository {
  type: string;
  url: string;
  directory?: string;
}

/**
 * Packument (package document) - the full package metadata
 */
export interface IPackument {
  _id: string;
  _rev?: string;
  name: string;
  description?: string;
  'dist-tags': Record<string, string>;
  versions: Record<string, INpmVersion>;
  time?: Record<string, string>; // created, modified, and version timestamps
  maintainers?: INpmPerson[];
  author?: INpmPerson | string;
  repository?: INpmRepository;
  readme?: string;
  readmeFilename?: string;
  homepage?: string;
  keywords?: string[];
  bugs?: string | { url?: string; email?: string };
  license?: string;
  users?: Record<string, boolean>; // Users who starred the package
  [key: string]: any;
}

/**
 * Abbreviated packument for npm install
 */
export interface IAbbreviatedPackument {
  name: string;
  'modified': string;
  'dist-tags': Record<string, string>;
  versions: Record<string, {
    name: string;
    version: string;
    dist: INpmDist;
    dependencies?: Record<string, string>;
    [key: string]: any;
  }>;
}

/**
 * Publish request body
 */
export interface IPublishRequest {
  _id: string;
  name: string;
  description?: string;
  'dist-tags': Record<string, string>;
  versions: Record<string, INpmVersion>;
  _attachments: Record<string, {
    content_type: string;
    data: string; // Base64 encoded
    length: number;
  }>;
  readme?: string;
  maintainers?: INpmPerson[];
  [key: string]: any;
}

/**
 * Search result item
 */
export interface ISearchResult {
  package: {
    name: string;
    version: string;
    description?: string;
    keywords?: string[];
    date?: string;
    links?: {
      npm?: string;
      homepage?: string;
      repository?: string;
      bugs?: string;
    };
    author?: INpmPerson;
    publisher?: INpmPerson;
    maintainers?: INpmPerson[];
  };
  score: {
    final: number;
    detail: {
      quality: number;
      popularity: number;
      maintenance: number;
    };
  };
  searchScore: number;
  flags?: {
    unstable?: boolean;
    insecure?: boolean;
  };
}

/**
 * Search response
 */
export interface ISearchResponse {
  objects: ISearchResult[];
  total: number;
  time: string;
}

/**
 * NPM token information
 */
export interface INpmToken {
  token: string; // UUID
  key: string; // SHA-512 hash for identification
  cidr_whitelist?: string[];
  readonly: boolean;
  created: string; // ISO-8601
  updated: string; // ISO-8601
}

/**
 * Token creation request
 */
export interface ITokenCreateRequest {
  password: string;
  readonly?: boolean;
  cidr_whitelist?: string[];
}

/**
 * Token list response
 */
export interface ITokenListResponse {
  objects: Array<{
    token: string; // Masked
    key: string;
    cidr_whitelist?: string[];
    readonly: boolean;
    created: string;
    updated: string;
  }>;
  total: number;
  urls: {
    next?: string;
  };
}

/**
 * User authentication request
 */
export interface IUserAuthRequest {
  name: string;
  password: string;
}

/**
 * User profile
 */
export interface IUserProfile {
  _id: string;
  name: string;
  email?: string;
  type: 'user';
  roles?: string[];
  date: string; // ISO-8601
}

/**
 * Dist-tag operations
 */
export interface IDistTagUpdate {
  [tag: string]: string; // tag -> version
}

/**
 * NPM error codes
 */
export type TNpmErrorCode =
  | 'ENOTFOUND'
  | 'E404'
  | 'EPUBLISHCONFLICT'
  | 'EUNAUTHORIZED'
  | 'EFORBIDDEN'
  | 'EINTERNAL'
  | 'EBADREQUEST';

/**
 * NPM error response
 */
export interface INpmError {
  error: string;
  reason?: string;
  statusCode?: number;
}