ProtoPedia API Ver 2.0 Client for Javascript

ProtoPedia API Ver 2.0 Client for Javascript

Description

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

• Node.js 20+ with native fetch
• Fully typed request/response models
• Pluggable logging with level control
• Abortable requests and configurable timeout
• Minimal, dependency-light

Requirements

• Node.js >= 20
• 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

• 作品一覧
  • GET https://protopedia.net/v2/api/prototype/list
• 作品一覧（TSV）
  • GET https://protopedia.net/v2/api/prototype/list/tsv

Installation

npm install protopedia-api-v2-client

Getting Started

Set your API token:

export PROTOPEDIA_API_V2_TOKEN=your-token

Or create a .env file (see .env.example):

PROTOPEDIA_API_V2_TOKEN=your-token
PROTOPEDIA_API_LOG_LEVEL=info

Create a client

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

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

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:

• F88/promidas: Snapshot-based in-memory store for ProtoPedia prototypes with TTL management
  • promidas/lib/fetcher - Full-featured integration example

API Surface

• Client and factories:
  • ProtoPediaApiClient
  • createProtoPediaClient
• Errors:
  • ProtoPediaApiError
• Requests and responses:
  • ListPrototypesParams
  • ListPrototypesApiResponse
• Package entry points:
  • src/index.ts
  • types/index.ts

Logging

Supported levels: silent, error, warn, info, debug.

Configure at client creation time or per request:

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

Headers are sanitized for logging (token-like headers are masked). See headersForLogging.

Timeouts and Abort

• Default timeout: 15000 ms
• Override with timeoutMs in client options
• Pass an AbortSignal per request

const controller = new AbortController();
const promise = client.listPrototypes({}, { signal: controller.signal });
controller.abort(new DOMException('User cancel', 'AbortError'));

TypeScript

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

• types/index.ts
• types/protopedia-api-v2

Notes

• This client mirrors the current public API behavior and may need updates if the API changes.
• TSV download currently uses Accept: application/json internally for compatibility.

License

Distributed under CC0-1.0. See LICENSE.