@verdaccio/types 11.0.0-6-next.12 → 11.0.0-6-next.13

package/build/plugins/storage.d.ts

@@ -0,0 +1,80 @@
+/// <reference types="node" />
+import { Readable, Writable } from 'stream';
+import { Callback, CallbackAction } from '../commons';
+import { Config, Logger } from '../configuration';
+import { Manifest, Token } from '../manifest';
+import { IPlugin } from './commons';
+export declare type StorageList = string[];
+export interface LocalStorage {
+    list: any;
+    secret: string;
+}
+export interface ILocalStorage {
+    add(name: string): void;
+    remove(name: string): void;
+    get(): StorageList;
+    sync(): void;
+}
+export interface TokenFilter {
+    user: string;
+}
+export interface ITokenActions {
+    saveToken(token: Token): Promise<any>;
+    deleteToken(user: string, tokenKey: string): Promise<any>;
+    readTokens(filter: TokenFilter): Promise<Token[]>;
+}
+/**
+ * This method expect return a Package object
+ * eg:
+ * {
+ *   name: string;
+ *   time: number;
+ *   ... and other props
+ * }
+ *
+ * The `cb` callback object will be executed if:
+ *  - it might return object (truly)
+ *  - it might reutrn null
+ */
+export declare type onSearchPackage = (item: Manifest, cb: CallbackAction) => void;
+export declare type onEndSearchPackage = (error?: any) => void;
+export declare type onValidatePackage = (name: string) => boolean;
+export declare type StorageUpdateCallback = (data: Manifest, cb: CallbackAction) => void;
+export declare type StorageWriteCallback = (name: string, json: Manifest, callback: Callback) => void;
+export declare type PackageTransformer = (pkg: Manifest) => Manifest;
+export declare type ReadPackageCallback = (err: any | null, data?: Manifest) => void;
+export interface ILocalPackageManager {
+    logger: Logger;
+    deletePackage(fileName: string): Promise<void>;
+    removePackage(): Promise<void>;
+    updatePackage(packageName: string, handleUpdate: (manifest: Manifest) => Promise<Manifest>): Promise<Manifest>;
+    readPackage(name: string): Promise<Manifest>;
+    savePackage(pkgName: string, value: Manifest): Promise<void>;
+    readTarball(pkgName: string, { signal }: {
+        signal: any;
+    }): Promise<Readable>;
+    createPackage(name: string, manifest: Manifest): Promise<void>;
+    writeTarball(tarballName: string, { signal }: {
+        signal: any;
+    }): Promise<Writable>;
+    hasTarball(fileName: string): Promise<boolean>;
+    hasPackage(): Promise<boolean>;
+}
+export declare type IPackageStorage = ILocalPackageManager | void;
+export declare type IPluginStorage<T> = ILocalData<T>;
+export declare type IPackageStorageManager = ILocalPackageManager;
+/**
+ * @deprecated use @verdaccio/core pluginUtils instead
+ */
+interface ILocalData<T> extends IPlugin<T>, ITokenActions {
+    logger: Logger;
+    config: T & Config;
+    add(name: string): Promise<void>;
+    remove(name: string): Promise<void>;
+    get(): Promise<any>;
+    init(): Promise<void>;
+    getSecret(): Promise<string>;
+    setSecret(secret: string): Promise<any>;
+    getPackageStorage(packageInfo: string): IPackageStorage;
+}
+export {};

package/build/search.d.ts

@@ -0,0 +1,26 @@
+export declare type PublisherMaintainer = {
+    username: string;
+    email: string;
+};
+export declare type SearchPackageBody = {
+    name: string;
+    scope: string;
+    description: string;
+    author: string | PublisherMaintainer;
+    version: string;
+    keywords: string | string[] | undefined;
+    date: string;
+    links?: {
+        npm: string;
+        homepage?: string;
+        repository?: string;
+        bugs?: string;
+    };
+    publisher?: any;
+    maintainers?: PublisherMaintainer[];
+};
+export declare type SearchResultWeb = {
+    name: string;
+    version: string;
+    description: string;
+};

package/build/types.d.ts

@@ -0,0 +1,5 @@
+export * from './plugins';
+export * from './manifest';
+export * from './search';
+export * from './commons';
+export * from './configuration';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verdaccio/types",
-  "version": "11.0.0-6-next.12",
+  "version": "11.0.0-6-next.13",
   "description": "verdaccio types definitions",
   "keywords": [
     "private",
@@ -31,18 +31,28 @@
   "publishConfig": {
     "access": "public"
   },
-  "main": "index.d.ts",
-  "types": "index.d.ts",
-  "scripts": {
-    "test": "exit 0",
-    "build": "exit 0"
-  },
+  "main": "build/types.d.ts",
+  "types": "build/types.d.ts",
   "devDependencies": {
-    "@types/node": "16.11.21",
-    "tsd": "0.19.1"
+    "@types/node": "16.11.47",
+    "typedoc": "beta",
+    "typedoc-plugin-missing-exports": "1.0.0"
+  },
+  "typedoc": {
+    "entryPoint": "./src/types.ts",
+    "readmeFile": "./README.md",
+    "displayName": "@verdaccio/types"
   },
   "funding": {
     "type": "opencollective",
     "url": "https://opencollective.com/verdaccio"
-  }
-}
+  },
+  "scripts": {
+    "clean": "rimraf ./build",
+    "test": "pnpm type-check",
+    "build:docs": "typedoc --options ./typedoc.json --excludeExternals --tsconfig tsconfig.build.json",
+    "type-check": "tsc --noEmit -p tsconfig.build.json",
+    "build": "tsc --emitDeclarationOnly -p tsconfig.build.json"
+  },
+  "readme": "# @verdaccio/types\n\nTypeScript definitions for Verdaccio plugins and internal code.\n\n### Usage\n\n```ts\nimport type {ILocalData, LocalStorage, Logger, Config} from '@verdaccio/types';\n\nclass LocalData implements ILocalData {\n  path: string;\n  logger: Logger;\n  data: LocalStorage;\n  config: Config;\n  locked: boolean;\n  ...\n}\n```\n\n### Run docs\n\nGenerate the package types documentation at `./docs` folder.\n\n```bash\n pnpm build:docs\n```\n"
+}

package/src/commons.ts

@@ -0,0 +1,37 @@
+// @deprecated add proper type fot the callback
+export type Callback = Function;
+// FIXME: err should be something flexible enough for any implementation
+export type CallbackAction = (err: any | null) => void;
+// eslint-disable-next-line no-undef
+export type CallbackError = (err: NodeJS.ErrnoException) => void;
+
+export interface RemoteUser {
+  real_groups: string[];
+  groups: string[];
+  name: string | void;
+  error?: string;
+}
+
+export type StringValue = string | void | null;
+
+// FIXME: error should be export type `VerdaccioError = HttpError & { code: number };`
+// instead of AuthError
+// but this type is on @verdaccio/core and cannot be used here yet (I don't know why)
+export interface HttpError extends Error {
+  status: number;
+  statusCode: number;
+  expose: boolean;
+  headers?: {
+    [key: string]: string;
+  };
+  [key: string]: any;
+}
+
+export type URLPrefix = {
+  // if is false, it would be relative by default
+  absolute: boolean;
+  // base path
+  // eg: absolute: true, https://somedomain.com/xxx/
+  // eg: absolute: false, /xxx/ (default) if url_prefix is an string instead an object
+  basePath: string;
+};

package/src/configuration.ts

@@ -0,0 +1,296 @@
+import { PackageAccess, PackageList } from './manifest';
+
+export type TypeToken = 'Bearer' | 'Basic';
+
+export interface Logger {
+  child: (conf: any) => any;
+  debug: (conf: any, template?: string) => void;
+  error: (conf: any, template?: string) => void;
+  http: (conf: any, template?: string) => void;
+  trace: (conf: any, template?: string) => void;
+  warn: (conf: any, template?: string) => void;
+  info: (conf: any, template?: string) => void;
+}
+
+export type LoggerType = 'stdout' | 'file';
+export type LoggerFormat = 'pretty' | 'pretty-timestamped' | 'json';
+export type LoggerLevel = 'http' | 'fatal' | 'warn' | 'info' | 'debug' | 'trace';
+
+export type LoggerConfigItem = {
+  type?: LoggerType;
+  /**
+   * The format
+   */
+  format?: LoggerFormat;
+  path?: string;
+  level?: string;
+  colors?: boolean;
+  async?: boolean;
+};
+
+export interface ConfigWithHttps extends Config {
+  https: HttpsConf;
+}
+
+export interface PackageAccessYaml {
+  storage?: string;
+  publish?: string;
+  proxy?: string;
+  access?: string;
+  unpublish?: string;
+}
+
+export interface LoggerConfItem {
+  type: LoggerType;
+  format: LoggerFormat;
+  level: LoggerLevel;
+}
+
+export interface Headers {
+  [key: string]: string;
+}
+
+export interface UpLinkTokenConf {
+  type: TypeToken;
+  token?: string;
+  token_env?: boolean | string;
+}
+
+export interface UpLinkConf {
+  url: string;
+  ca?: string;
+  cache?: boolean;
+  timeout?: string | void;
+  maxage?: string | void;
+  max_fails?: number | void;
+  fail_timeout?: string | void;
+  headers?: Headers;
+  auth?: UpLinkTokenConf;
+  strict_ssl?: boolean | void;
+  _autogenerated?: boolean;
+}
+
+export type RateLimit = {
+  windowMs?: number;
+  max?: number;
+};
+
+// export interface WebConf {
+//   enable?: boolean;
+//   title?: string;
+//   logo?: string;
+//   favicon?: string;
+//   gravatar?: boolean;
+//   sort_packages?: string;
+//   rateLimit?: RateLimit;
+// }
+
+export type FlagsConfig = {
+  searchRemote?: boolean;
+  changePassword?: boolean;
+};
+
+export type PackageManagers = 'pnpm' | 'yarn' | 'npm';
+
+// FUTURE: WebConf and TemplateUIOptions should be merged .
+export type CommonWebConf = {
+  title?: string;
+  logo?: string;
+  favicon?: string;
+  gravatar?: boolean;
+  sort_packages?: string;
+  darkMode?: boolean;
+  url_prefix?: string;
+  language?: string;
+  login?: boolean;
+  scope?: string;
+  pkgManagers?: PackageManagers[];
+};
+
+/**
+ * Options are passed to the index.html
+ */
+export type TemplateUIOptions = {
+  uri?: string;
+  darkMode?: boolean;
+  protocol?: string;
+  host?: string;
+  // deprecated
+  basename?: string;
+  scope?: string;
+  showInfo?: boolean;
+  showSettings?: boolean;
+  showSearch?: boolean;
+  showFooter?: boolean;
+  showThemeSwitch?: boolean;
+  showDownloadTarball?: boolean;
+  showRaw?: boolean;
+  base: string;
+  primaryColor?: string;
+  version?: string;
+  logoURI?: string;
+  flags: FlagsConfig;
+} & CommonWebConf;
+
+/**
+ * Options on config.yaml for web
+ */
+export type WebConf = {
+  // FIXME: rename to primaryColor and move it to CommonWebConf
+  primary_color?: string;
+  enable?: boolean;
+  scriptsHead?: string[];
+  scriptsBodyAfter?: string[];
+  metaScripts?: string[];
+  bodyBefore?: string[];
+  bodyAfter?: string[];
+} & CommonWebConf;
+
+export interface UpLinksConfList {
+  [key: string]: UpLinkConf;
+}
+
+export interface AuthHtpasswd {
+  file: string;
+  max_users: number;
+}
+
+export type AuthConf = any | AuthHtpasswd;
+
+export interface JWTOptions {
+  sign: JWTSignOptions;
+  verify: JWTVerifyOptions;
+}
+
+export interface JWTSignOptions {
+  algorithm?: string;
+  expiresIn?: string;
+  notBefore?: string;
+  ignoreExpiration?: boolean;
+  maxAge?: string | number;
+  clockTimestamp?: number;
+}
+
+export interface JWTVerifyOptions {
+  algorithm?: string;
+  expiresIn?: string;
+  notBefore?: string | number;
+  ignoreExpiration?: boolean;
+  maxAge?: string | number;
+  clockTimestamp?: number;
+}
+
+export interface APITokenOptions {
+  legacy: boolean;
+  jwt?: JWTOptions;
+}
+
+export interface Security {
+  web: JWTOptions;
+  api: APITokenOptions;
+}
+
+export interface PublishOptions {
+  allow_offline: boolean;
+}
+
+export interface ListenAddress {
+  [key: string]: string;
+}
+
+export interface HttpsConfKeyCert {
+  key: string;
+  cert: string;
+  ca?: string;
+}
+
+export interface HttpsConfPfx {
+  pfx: string;
+  passphrase?: string;
+}
+
+export type HttpsConf = HttpsConfKeyCert | HttpsConfPfx;
+
+export interface Notifications {
+  method: string;
+  packagePattern: RegExp;
+  packagePatternFlags: string;
+  endpoint: string;
+  content: string;
+  headers: Headers;
+}
+
+export type Notification = Notifications;
+
+export type ServerSettingsConf = {
+  // express-rate-limit settings
+  rateLimit: RateLimit;
+  keepAliveTimeout?: number;
+};
+
+/**
+ * YAML configuration file available options.
+ */
+export interface ConfigYaml {
+  _debug?: boolean;
+  storage?: string | void;
+  packages: PackageList;
+  uplinks: UpLinksConfList;
+  log?: LoggerConfItem;
+  web?: WebConf;
+  auth?: AuthConf;
+  security: Security;
+  publish?: PublishOptions;
+  store?: any;
+  listen?: ListenAddress;
+  https?: HttpsConf;
+  http_proxy?: string;
+  plugins?: string | void;
+  https_proxy?: string;
+  no_proxy?: string;
+  max_body_size?: string;
+  notifications?: Notifications;
+  notify?: Notifications | Notifications[];
+  middlewares?: any;
+  filters?: any;
+  url_prefix?: string;
+  server?: ServerSettingsConf;
+  flags?: FlagsConfig;
+  // internal objects, added by internal yaml to JS config parser
+  // @deprecated use configPath instead
+  config_path?: string;
+  // save the configuration file path
+  configPath?: string;
+}
+
+/**
+ * Configuration object with additonal methods for configuration, includes yaml and internal medatada.
+ * @interface Config
+ * @extends {ConfigYaml}
+ */
+export interface Config extends Omit<ConfigYaml, 'packages' | 'security' | 'configPath'> {
+  user_agent: string;
+  server_id: string;
+  secret: string;
+  // save the configuration file path, it's fails without thi configPath
+  configPath: string;
+  // packages from yaml file looks different from packages inside the config file
+  packages: PackageList;
+  // security object defaults is added by the config file but optional in the yaml file
+  security: Security;
+  // @deprecated (pending adding the replacement)
+  checkSecretKey(token: string): string;
+  getMatchedPackagesSpec(storage: string): PackageAccess | void;
+  // TODO: verify how to handle this in the future
+  [key: string]: any;
+}
+
+export interface AllowAccess {
+  name: string;
+  version?: string;
+  tag?: string;
+}
+
+// info passed to the auth plugin when a package is package is being published
+
+export interface AuthPackageAllow extends PackageAccess, AllowAccess {}

package/src/manifest.ts

@@ -0,0 +1,217 @@
+export interface PackageAccess {
+  storage?: string;
+  publish?: string[];
+  proxy?: string[];
+  access?: string[];
+  unpublish: string[];
+}
+
+export interface PackageList {
+  [key: string]: PackageAccess;
+}
+
+export interface MergeTags {
+  [key: string]: string;
+}
+
+export interface DistFile {
+  url: string;
+  sha: string;
+  registry?: string;
+}
+
+export interface DistFiles {
+  [key: string]: DistFile;
+}
+
+export interface Token {
+  user: string;
+  token: string;
+  key: string;
+  cidr?: string[];
+  readonly: boolean;
+  created: number | string;
+  updated?: number | string;
+}
+
+export interface AttachMents {
+  [key: string]: AttachMentsItem;
+}
+
+export interface AttachMentsItem {
+  content_type?: string;
+  data?: string;
+  length?: number;
+  shasum?: string;
+  version?: string;
+}
+
+export interface GenericBody {
+  [key: string]: string;
+}
+
+export interface UpLinkMetadata {
+  etag: string;
+  fetched: number;
+}
+
+export interface UpLinks {
+  [key: string]: UpLinkMetadata;
+}
+
+export interface Signatures {
+  keyid: string;
+  sig: string;
+}
+
+export interface Dist {
+  'npm-signature'?: string;
+  signatures?: Signatures[];
+  fileCount?: number;
+  integrity?: string;
+  shasum: string;
+  unpackedSize?: number;
+  tarball: string;
+}
+
+export interface Author {
+  username?: string;
+  name: string;
+  email?: string;
+  url?: string;
+}
+
+export interface PackageUsers {
+  [key: string]: boolean;
+}
+
+export interface Tags {
+  [key: string]: Version;
+}
+
+export interface Version {
+  name: string;
+  version: string;
+  devDependencies?: string;
+  directories?: any;
+  dist: Dist;
+  author: string | Author;
+  main: string;
+  homemage?: string;
+  license?: string;
+  readme: string;
+  readmeFileName?: string;
+  readmeFilename?: string;
+  description: string;
+  bin?: string;
+  bugs?: any;
+  files?: string[];
+  gitHead?: string;
+  maintainers?: Author[];
+  contributors?: Author[];
+  repository?: string | any;
+  scripts?: any;
+  homepage?: string;
+  etag?: string;
+  dependencies: any;
+  keywords?: string | string[];
+  nodeVersion?: string;
+  _id: string;
+  _npmVersion?: string;
+  _npmUser: Author;
+  _hasShrinkwrap?: boolean;
+  deprecated?: string;
+}
+
+export interface Versions {
+  [key: string]: Version;
+}
+
+/**
+ * @deprecated use Manifest instead
+ */
+export interface Package {
+  _id?: string;
+  name: string;
+  versions: Versions;
+  'dist-tags': GenericBody;
+  time: GenericBody;
+  readme?: string;
+  users?: PackageUsers;
+  _distfiles: DistFiles;
+  _attachments: AttachMents;
+  _uplinks: UpLinks;
+  _rev: string;
+}
+
+/**
+ * Represents upstream manifest from another registry
+ */
+export interface FullRemoteManifest {
+  _id?: string;
+  _rev?: string;
+  name: string;
+  description?: string;
+  'dist-tags': GenericBody;
+  time: GenericBody;
+  versions: Versions;
+  maintainers?: Author[];
+  /** store the latest readme **/
+  readme?: string;
+  /** store star assigned to this packages by users */
+  users?: PackageUsers;
+  // TODO: not clear what access exactly means
+  access?: any;
+  bugs?: { url: string };
+  license?: string;
+  homepage?: string;
+  repository?: string | { type?: string; url: string; directory?: string };
+  keywords?: string[];
+}
+
+export interface Manifest extends FullRemoteManifest, PublishManifest {
+  // private fields only used by verdaccio
+  /**
+   * store fast access to the dist url of an specific tarball, instead search version
+   * by id, just the tarball id is faster.
+   *
+   * The _distfiles is created only when a package is being sync from an upstream.
+   * also used to fetch tarballs from upstream, the private publish tarballs are not stored in
+   * this object because they are not published in the upstream registry.
+   */
+  _distfiles: DistFiles;
+  /**
+   * Store access cache metadata, to avoid to fetch the same metadata multiple times.
+   *
+   * The key represents the uplink id which is composed of a etag and a fetched timestamp.
+   *
+   * The fetched timestamp is the time when the metadata was fetched, used to avoid to fetch the
+   * same metadata until the metadata is older than the last fetch.
+   */
+  _uplinks: UpLinks;
+  /**
+   * store the revision of the manifest
+   */
+  _rev: string;
+}
+export interface PublishManifest {
+  /**
+   * The `_attachments` object has different usages:
+   *
+   * - When a package is published, it contains the tarball as an string, this string is used to be
+   * converted as a tarball, usually attached to the package but not stored in the database.
+   * - If user runs `npm star` the _attachments will be at the manifest body but empty.
+   *
+   * It has also an internal usage:
+   *
+   * - Used as a cache for the tarball, quick access to the tarball shasum, etc. Instead
+   * iterate versions and find the right one, just using the tarball as a key which is what
+   * the package manager sends to the registry.
+   *
+   * - A `_attachments` object is added every time a private tarball is published, upstream cached tarballs are
+   * not being part of this object, only for published private packages.
+   *
+   * Note: This field is removed when the package is accesed through the web user interface.
+   * */
+  _attachments: AttachMents;
+}