npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

protopedia-api-v2-client

v5.2.0

Published

TypeScript client for ProtoPedia API Ver 2.0

Readme

ProtoPedia API Ver 2.0 Client for JavaScript

npm version codecov CodeQL CI

Ask DeepWiki View Code Wiki

Description

Type-safe, ESM-first client for the ProtoPedia API Ver 2.0. Built with TypeScript, tested with Vitest, and ready for Node.js 22+.

  • Node.js 22+ with native fetch
  • Fully typed request/response models (response types are inferred from observed responses; see Notes)
  • Pluggable logging with level control
  • Abortable requests and configurable timeout
  • No runtime dependencies

Requirements

  • Node.js >= 22
  • ESM environment

ProtoPedia API Ver 2.0

ProtoPedia API Ver 2.0 · Apiary https://protopediav2.docs.apiary.io

Features

The JavaScript client library supports ProtoPedia API Ver 2.0 · Apiary

Supported APIs

Installation

npm install protopedia-api-v2-client

Getting Started

Create a client

Pass your API token when creating a client:

import { createProtoPediaClient } from 'protopedia-api-v2-client';

const client = createProtoPediaClient({
    token: 'your-token',
});

The client does not read environment variables by itself. To keep the token out of your source code (recommended when sharing or committing it), read it from an environment variable in your code and pass it explicitly:

const client = createProtoPediaClient({
    token: process.env.PROTOPEDIA_API_V2_TOKEN,
});

Client options

| Option | Default | Description | | ----------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | token | (required) | API token, sent as Authorization: Bearer <token> | | baseUrl | https://protopedia.net/v2/api | Base URL of the API | | fetch | globalThis.fetch | Custom fetch implementation (must honor init.signal) | | userAgent | none | Sent as the User-Agent header. Browsers may block a request that sets it, because of CORS | | timeoutMs | 60000 | Maximum time in milliseconds from the start of a request until the response is received (0 disables it). See Timeouts and Abort | | logger | console | Custom logger. See Logging | | logLevel | error | Log level. See Logging |

Usage

List prototypes:

import { ProtoPediaApiError } from 'protopedia-api-v2-client';
import type { ListPrototypesParams } from 'protopedia-api-v2-client';

const params: ListPrototypesParams = {
    tagNm: 'IoT',
    limit: 10,
    offset: 0,
};

try {
    const res = await client.listPrototypes(params, {
        headers: { 'X-Custom': 'value' },
        // Per-request log level override:
        logLevel: 'info',
    });
    console.log(res.count, res.results?.[0]);
} catch (err) {
    if (err instanceof ProtoPediaApiError) {
        console.error(
            'API error',
            err.status,
            err.statusText,
            err.req.url,
            err.body,
        );
    } else {
        console.error('Unexpected error', err);
    }
}

Download TSV:

const tsv = await client.downloadPrototypesTsv(
    { limit: 100 },
    { logLevel: 'debug' },
);
console.log(tsv);

Examples

For a comprehensive implementation example using this client, see:

API Surface

Logging

Supported levels: silent, error, warn, info, debug (default: error).

Configure at client creation time or per request:

const client = createProtoPediaClient({
    token: 'your-token',
    logLevel: 'warn',
});
await client.listPrototypes({}, { logLevel: 'debug' }); // override

Pass your own logger with the logger option. It needs error, warn, info and debug methods that take (message, metadata?):

import type { Logger } from 'protopedia-api-v2-client';

const logger: Logger = {
    error: (message, metadata) => myLogger.error(message, metadata),
    warn: (message, metadata) => myLogger.warn(message, metadata),
    info: (message, metadata) => myLogger.info(message, metadata),
    debug: (message, metadata) => myLogger.debug(message, metadata),
};

const client = createProtoPediaClient({
    token: 'your-token',
    logger,
    logLevel: 'info',
});
  • Exceptions thrown by the logger are ignored, so logging never changes the result of a request.
  • Headers are sanitized for logging: values of headers whose name contains token or auth (case-insensitive) are masked as ***. See headersForLogging.

Timeouts and Abort

  • timeoutMs is the maximum time from the start of a request until the response is received, including the response body. Converting the response to JSON is not included. The default is 60000 ms
  • If the time runs out, the call fails with a DOMException named TimeoutError. If fetch itself fails with a different error at that moment, such as a network error, that error is thrown as is. Set a larger value for large downloads or slow networks
  • The ProtoPedia API can take several seconds to respond, even for a small request. Avoid setting a very short timeoutMs
  • timeoutMs: 0 disables the SDK timer. Invalid values, such as a negative number or Infinity, fall back to the default
  • Pass an AbortSignal per request to cancel it at any time. The call fails with the reason passed to abort(), or an AbortError if there is none
  • timeoutMs is an upper limit. It does not guarantee that the SDK waits that long: a request can fail earlier because of the runtime or the network, and timeoutMs does not change those limits. For example, Node.js fetch has its own connection, header, and body timeouts. These fail with a TypeError that has the code in error.cause.code. If the failure happens while reading an error response, ProtoPediaApiError keeps the status, and that TypeError is in error.cause. See #68
  • Both the timeout and the cancellation work by aborting the signal passed to fetch. A custom fetch must honor init.signal until the body has been read; otherwise the request is not stopped and timeoutMs has no effect
const controller = new AbortController();
const promise = client.listPrototypes({}, { signal: controller.signal });
controller.abort(new DOMException('User cancel', 'AbortError'));

try {
    await promise;
} catch (err) {
    // With Node.js fetch, err is the reason passed to controller.abort()
}

TypeScript

Types are emitted to lib/types. Public type exports are available via the package root. See:

Notes

  • This client mirrors the current public API behavior and may need updates if the API changes.
  • ProtoPedia API Ver 2.0 does not publish response schemas; its documentation only shows an example response. The response types are inferred from observed responses, so actual responses may not always match them (e.g. attributes typed as required may be missing).
  • TSV download currently uses Accept: application/json internally for compatibility.

License

Distributed under CC0-1.0. See LICENSE.