Data Models

This document describes all data structures returned by the NPM Skills API.

Model Overview

Package is the aggregate root: it maps version numbers to many Version objects, each holding a Dist (distribution/checksums) and dependency tables. Search, stats and registry info are independent top-level models:

Search and scoring model composition:

How SDK parses JSON from NPM Registry into Go structs:

Package Information

Package

Complete package metadata including all versions and distribution tags.

type Package struct {
    ID             string                 `json:"_id"`
    Rev            string                 `json:"_rev"`
    Name           string                 `json:"name"`
    Description    string                 `json:"description"`
    DistTags       map[string]string      `json:"dist-tags"`
    Versions       map[string]Version     `json:"versions"`
    Maintainers    []Maintainer           `json:"maintainers"`
    Time           map[string]string      `json:"time"`
    Repository     Repository             `json:"repository"`
    ReadMe         string                 `json:"readme"`
    ReadMeFilename string                 `json:"readmeFilename"`
    Homepage       string                 `json:"homepage"`
    Bugs           *Bugs                  `json:"bugs"`
    License        string                 `json:"license"`
    Users          map[string]bool        `json:"users"`
    Keywords       []string               `json:"keywords"`
    Author         Author                 `json:"author"`
    Contributors   []Contributor          `json:"contributors"`
    Deprecated     interface{}            `json:"deprecated"`
    Funding        interface{}            `json:"funding"`
    Attachments    map[string]Attachment  `json:"_attachments"`
}

Fields:

ID - Package identifier (usually same as name)
Name - Package name
Description - Package description
DistTags - Distribution tags (e.g., "latest", "beta")
Versions - Map of all package versions
Maintainers - List of package maintainers
Time - Creation/modification timestamps
Repository - Source repository information
ReadMe - Package README content
Homepage - Package homepage URL
Bugs - Bug reporting information
License - Package license
Keywords - Package keywords for discovery
Author - Package author
Contributors - List of contributors
Deprecated - Deprecation notice (string / bool / nil)

Version

Information about a specific package version.

type Version struct {
    Name            string               `json:"name"`
    Version         string               `json:"version"`
    Description     string               `json:"description"`
    Main            string               `json:"main"`
    Module          string               `json:"module"`
    Types           string               `json:"types"`
    Scripts         Script               `json:"scripts"`
    Repository      *Repository          `json:"repository"`
    Keywords        []string             `json:"keywords"`
    Author          *User                `json:"author"`
    License         string               `json:"license"`
    Bugs            *Bugs                `json:"bugs"`
    Homepage        string               `json:"homepage"`
    Dependencies    map[string]string    `json:"dependencies"`
    DevDependencies map[string]string    `json:"devDependencies"`
    PeerDependencies map[string]string   `json:"peerDependencies"`
    OptionalDependencies map[string]string `json:"optionalDependencies"`
    Engines         map[string]string    `json:"engines"`
    Dist            *Dist                `json:"dist"`
    Deprecated      interface{}          `json:"deprecated"`
}

Fields:

Name - Package name
Version - Specific version string
Description - Version description
Main - Main entry point file
Module - ES module entry point
Types - TypeScript type declaration entry
Scripts - NPM scripts (a Script struct, supports arbitrary keys)
Repository - Repository information
Author - Package author
License - Package license
Bugs - Bug reporting information
Homepage - Package homepage
Dependencies - Runtime dependencies
DevDependencies - Development dependencies
PeerDependencies - Peer dependencies
OptionalDependencies - Optional dependencies
Engines - Engine version constraints (e.g. {"node": ">=14"})
Dist - Distribution information (tarball URL, checksums)
Deprecated - Deprecation notice (string / bool / nil)

Supporting Structures

Author

Author or maintainer information.

type Author struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Url   string `json:"url"`
}

Repository

Source repository information.

type Repository struct {
    Type      string `json:"type"`
    URL       string `json:"url"`
    Directory string `json:"directory"`
}

Bugs

Bug reporting information.

type Bugs struct {
    URL string `json:"url"`
}

Dist

Package distribution information.

type Dist struct {
    Shasum       string       `json:"shasum"`
    Tarball      string       `json:"tarball"`
    Integrity    string       `json:"integrity"`
    Signatures   []*Signature `json:"signatures"`
    FileCount    int          `json:"fileCount"`
    UnpackedSize int64        `json:"unpackedSize"`
    NpmSignature string       `json:"npm-signature"`
}

type Signature struct {
    Keyid string `json:"keyid"`
    Sig   string `json:"sig"`
}

Maintainer

A package maintainer (Package.Maintainers).

type Maintainer struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Url   string `json:"url"`
}

Contributor

A package contributor (Package.Contributors).

type Contributor struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Url   string `json:"url"`
}

Attachment

A tarball attachment carried when publishing (Package.Attachments).

type Attachment struct {
    ContentType string `json:"content_type"`
    Data        string `json:"data"`   // base64-encoded tarball data
    Length      int    `json:"length"` // size in bytes
}

Script

NPM script commands. Defined as a map[string]string type alias to support arbitrary script keys in package.json (e.g. build, lint, dev):

type Script map[string]string

// version.Scripts is of type Script (map[string]string)
for name, cmd := range version.Scripts {
    fmt.Printf("%s: %s\n", name, cmd)
}
// common keys: "test" / "start" / "build" / "lint" / "dev"

Search Results

SearchResult

Results from package search operations.

type SearchResult struct {
    Objects []SearchObject `json:"objects"`
    Total   int           `json:"total"`
    Time    string        `json:"time"`
}

Fields:

Objects - Array of search result objects
Total - Total number of matching packages
Time - Search execution time

SearchObject

Individual search result item.

type SearchObject struct {
    Package     SearchPackage `json:"package"`
    Score       Score         `json:"score"`
    SearchScore float64       `json:"searchScore"`
}

SearchPackage

Package information in search results.

type SearchPackage struct {
    Name        string   `json:"name"`
    Scope       string   `json:"scope"`
    Version     string   `json:"version"`
    Description string   `json:"description"`
    Keywords    []string `json:"keywords"`
    Date        string   `json:"date"`
    Links       Links    `json:"links"`
    Author      *User    `json:"author"`
    Publisher   *User    `json:"publisher"`
    Maintainers []*User  `json:"maintainers"`
    ExactName   string   `json:"exactName"`
}

Score

Scoring information for search results.

type Score struct {
    Final  float64     `json:"final"`
    Detail ScoreDetail `json:"detail"`
}

type ScoreDetail struct {
    Quality     float64 `json:"quality"`
    Popularity  float64 `json:"popularity"`
    Maintenance float64 `json:"maintenance"`
}

Final is a weighted composite of three sub-dimensions; at search time you can tune each weight via --quality / --popularity / --maintenance:

Links

Links associated with search results.

type Links struct {
    NPM        string `json:"npm"`
    Homepage   string `json:"homepage"`
    Repository string `json:"repository"`
    Bugs       string `json:"bugs"`
}

User

A user / author / publisher (referenced by SearchPackage, Version, etc.).

type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    URL   string `json:"url"`
}

Statistics

DownloadStats

Package download statistics.

type DownloadStats struct {
    Downloads int    `json:"downloads"`
    Start     string `json:"start"`
    End       string `json:"end"`
    Package   string `json:"package"`
}

Fields:

Downloads - Number of downloads in the period
Start - Period start date
End - Period end date
Package - Package name

Registry Information

RegistryInformation

Information about the registry itself.

type RegistryInformation struct {
    DbName            string `json:"db_name"`
    DocCount          int    `json:"doc_count"`
    DocDelCount       int    `json:"doc_del_count"`
    UpdateSeq         int    `json:"update_seq"`
    PurgeSeq          int    `json:"purge_seq"`
    CompactRunning    bool   `json:"compact_running"`
    DiskSize          int    `json:"disk_size"`
    DataSize          int    `json:"data_size"`
    InstanceStartTime string `json:"instance_start_time"`
    DiskFormatVersion int    `json:"disk_format_version"`
    CommittedUpdateSeq int   `json:"committed_update_seq"`
}

Fields:

DbName - Database name
DocCount - Total number of documents (packages)
DocDelCount - Number of deleted documents
UpdateSeq - Update sequence number
PurgeSeq - Purge sequence number
CompactRunning - Whether compaction is running
DiskSize - Total disk usage in bytes
DataSize - Data size in bytes
InstanceStartTime - Registry instance start time
DiskFormatVersion - Disk format version
CommittedUpdateSeq - Committed update sequence

Additional Types

Types returned by access-control, audit, hooks, tokens, orgs, and auth methods.

DownloadRangeStats

Daily download trend for a package (GetDownloadRangeStats / GetDownloadRangeStatsByDateRange).

type DownloadRangeStats struct {
    Start     string           `json:"start"`
    End       string           `json:"end"`
    Package   string           `json:"package"`
    Downloads []DailyDownloads `json:"downloads"`
}

type DailyDownloads struct {
    Day       string `json:"day"`
    Downloads int    `json:"downloads"`
}

Advisory

A security advisory (GetAdvisory / ListAdvisories / QuickAudit / BulkAudit).

type Advisory struct {
    ID             int             `json:"id"`
    Created        string          `json:"created"`
    Updated        string          `json:"updated"`
    Title          string          `json:"title"`
    Severity       string          `json:"severity"` // "low" / "moderate" / "high" / "critical"
    CVE            string          `json:"cve,omitempty"`
    CWE            string          `json:"cwe,omitempty"`
    ModuleName     string          `json:"module_name"`
    Vulnerable     string          `json:"vulnerable_versions"`
    Patched        string          `json:"patched_versions"`
    URL            string          `json:"url"`
    Overview       string          `json:"overview,omitempty"`
    Recommendation string          `json:"recommendation,omitempty"`
    References     json.RawMessage `json:"references,omitempty"`
    Access         string          `json:"access,omitempty"`
}

Hook

An NPM webhook (ListHooks / GetHook / CreateHook / UpdateHook).

type Hook struct {
    ID       string   `json:"id"`
    Type     string   `json:"type"`
    Name     string   `json:"name"`
    Endpoint string   `json:"endpoint"`
    Secret   string   `json:"secret,omitempty"`
    Created  string   `json:"created"`
    Updated  string   `json:"updated"`
    Events   []string `json:"events"`
    Package  string   `json:"package,omitempty"`
    Active   bool     `json:"active"`
    Deleted  bool     `json:"deleted,omitempty"`
}

Token

An API access token (ListTokens / GetToken / CreateToken / DeleteToken).

type Token struct {
    ID       string    `json:"id"`
    Token    string    `json:"token"`     // full value, only returned on creation
    Key      string    `json:"key"`
    Created  time.Time `json:"created"`
    Updated  time.Time `json:"updated"`
    Readonly bool      `json:"readonly"`
    CIDR     []string  `json:"cidr_whitelist,omitempty"`
}

Token safety

The Token field holds the plaintext token and is only returned on creation. Store it securely — never log it or commit it. Prefer Readonly: true with a CIDR whitelist for everyday use.

Organization

An NPM organization (GetOrg / CreateOrg).

type Organization struct {
    Name  string `json:"name"`
    Scope string `json:"scope,omitempty"` // org scope, e.g. "@my-org"
}

Team

A team within an organization (ListTeams / CreateTeam).

type Team struct {
    ID          string `json:"id"`
    Name        string `json:"name"`
    DisplayName string `json:"display_name,omitempty"`
    Description string `json:"description,omitempty"`
}

Collaborator

A package collaborator (ListCollaborators).

type Collaborator struct {
    Name        string `json:"name"`
    Email       string `json:"email,omitempty"`
    Permissions string `json:"permissions"` // "read" or "write"
}

PackageAccess

Package access settings (GetPackageAccess / SetPackageAccess).

type PackageAccess struct {
    Package string            `json:"package"`
    Access  map[string]string `json:"access"` // e.g. {"read": "public", "write": "restricted"}
}

UserProfile

User profile (GetUser).

type UserProfile struct {
    ID            string `json:"_id"`            // "org.couchdb.user:<name>"
    Rev           string `json:"_rev"`
    Name          string `json:"name"`
    Email         string `json:"email"`
    Type          string `json:"type"`           // usually "user"
    EmailVerified bool   `json:"email_verified"`
    Avatar        string `json:"avatar,omitempty"`
    GitHub        string `json:"github,omitempty"`
    Created       string `json:"created,omitempty"`
    Updated       string `json:"updated,omitempty"`
}

LoginResult

type LoginResult struct {
    ID    string `json:"id"`
    Rev   string `json:"rev"`
    Token string `json:"token"` // auth token for subsequent writes
    Ok    OkBool `json:"ok"`
}

JSON Examples

Package Information Example

json

{
    "_id": "react",
    "name": "react",
    "description": "React is a JavaScript library for building user interfaces.",
    "dist-tags": {
        "latest": "18.2.0",
        "beta": "18.3.0-beta"
    },
    "versions": {
        "18.2.0": {
            "name": "react",
            "version": "18.2.0",
            "description": "React is a JavaScript library for building user interfaces.",
            "main": "index.js",
            "dependencies": {
                "loose-envify": "^1.1.0"
            },
            "license": "MIT"
        }
    },
    "author": {
        "name": "React Team",
        "email": "react@meta.com"
    },
    "license": "MIT",
    "homepage": "https://reactjs.org/"
}

Search Result Example

json

{
    "objects": [
        {
            "package": {
                "name": "react",
                "version": "18.2.0",
                "description": "React is a JavaScript library for building user interfaces.",
                "keywords": ["react", "javascript", "ui"],
                "links": {
                    "npm": "https://www.npmjs.com/package/react",
                    "homepage": "https://reactjs.org/"
                }
            },
            "score": {
                "final": 0.95,
                "detail": {
                    "quality": 0.98,
                    "popularity": 0.99,
                    "maintenance": 0.88
                }
            }
        }
    ],
    "total": 1,
    "time": "Wed Jan 01 2024 12:00:00 GMT+0000 (UTC)"
}

Download Stats Example

json

{
    "downloads": 18500000,
    "start": "2024-01-01",
    "end": "2024-01-31",
    "package": "react"
}

Usage Examples

Accessing Package Information

pkg, err := client.GetPackageInformation(ctx, "react")
if err != nil {
    return err
}

// Access basic information
fmt.Printf("Name: %s\n", pkg.Name)
fmt.Printf("Latest version: %s\n", pkg.DistTags["latest"])
fmt.Printf("Description: %s\n", pkg.Description)

// Access author information
if pkg.Author.Name != "" {
    fmt.Printf("Author: %s <%s>\n", pkg.Author.Name, pkg.Author.Email)
}

// List all versions
for version := range pkg.Versions {
    fmt.Printf("Version: %s\n", version)
}

Working with Search Results

results, err := client.SearchPackages(ctx, "react ui", 5)
if err != nil {
    return err
}

fmt.Printf("Found %d packages\n", results.Total)

for _, obj := range results.Objects {
    pkg := obj.Package
    score := obj.Score
    
    fmt.Printf("Package: %s (score: %.2f)\n", pkg.Name, score.Final)
    fmt.Printf("  Description: %s\n", pkg.Description)
    fmt.Printf("  Quality: %.2f, Popularity: %.2f, Maintenance: %.2f\n",
        score.Detail.Quality, score.Detail.Popularity, score.Detail.Maintenance)
}

Analyzing Dependencies

version, err := client.GetPackageVersion(ctx, "react", "18.2.0")
if err != nil {
    return err
}

fmt.Printf("Dependencies for %s@%s:\n", version.Name, version.Version)

if len(version.Dependencies) > 0 {
    fmt.Println("Runtime dependencies:")
    for dep, ver := range version.Dependencies {
        fmt.Printf("  %s: %s\n", dep, ver)
    }
}

if len(version.DevDependencies) > 0 {
    fmt.Println("Dev dependencies:")
    for dep, ver := range version.DevDependencies {
        fmt.Printf("  %s: %s\n", dep, ver)
    }
}

Next Steps

Review Registry API for method documentation
Check Configuration Options for client setup
Explore Examples for practical usage patterns

Data Models ​

Model Overview ​

Package Information ​

Package ​

Version ​

Supporting Structures ​

Author ​

Repository ​

Bugs ​

Dist ​

Maintainer ​

Contributor ​

Attachment ​

Script ​

Search Results ​

SearchResult ​

SearchObject ​

SearchPackage ​

Score ​

Links ​

User ​

Statistics ​

DownloadStats ​

Registry Information ​

RegistryInformation ​

Additional Types ​

DownloadRangeStats ​

Advisory ​

Hook ​

Token ​

Organization ​

Team ​

Collaborator ​

PackageAccess ​

UserProfile ​

LoginResult ​

JSON Examples ​

Package Information Example ​

Search Result Example ​

Download Stats Example ​

Usage Examples ​

Accessing Package Information ​

Working with Search Results ​

Analyzing Dependencies ​

Next Steps ​

Data Models

Model Overview

Package Information

Package

Version

Supporting Structures

Author

Repository

Bugs

Dist

Maintainer

Contributor

Attachment

Script

Search Results

SearchResult

SearchObject

SearchPackage

Score

Links

User

Statistics

DownloadStats

Registry Information

RegistryInformation

Additional Types

DownloadRangeStats

Advisory

Hook

Token

Organization

Team

Collaborator

PackageAccess

UserProfile

LoginResult

JSON Examples

Package Information Example

Search Result Example

Download Stats Example

Usage Examples

Accessing Package Information

Working with Search Results

Analyzing Dependencies

Next Steps