protopedia-api-v2-client
v5.2.0
Published
TypeScript client for ProtoPedia API Ver 2.0
Maintainers
Readme
ProtoPedia API Ver 2.0 Client for JavaScript
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
- 作品一覧
GET https://protopedia.net/v2/api/prototype/list
- 作品一覧(TSV)
GET https://protopedia.net/v2/api/prototype/list/tsv
Installation
npm install protopedia-api-v2-clientGetting 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:
- 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:
- Errors:
ProtoPediaApiErrorResponseBodyReadError: reading the body of a successful response failed, and the request was not aborted. The original error is incause
- Requests and responses:
- Logging:
- Package entry point:
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' }); // overridePass 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
tokenorauth(case-insensitive) are masked as***. SeeheadersForLogging.
Timeouts and Abort
timeoutMsis 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 is60000 ms- If the time runs out, the call fails with a
DOMExceptionnamedTimeoutError. Iffetchitself 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: 0disables the SDK timer. Invalid values, such as a negative number orInfinity, fall back to the default- Pass an
AbortSignalper request to cancel it at any time. The call fails with the reason passed toabort(), or anAbortErrorif there is none timeoutMsis 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, andtimeoutMsdoes not change those limits. For example, Node.jsfetchhas its own connection, header, and body timeouts. These fail with aTypeErrorthat has the code inerror.cause.code. If the failure happens while reading an error response,ProtoPediaApiErrorkeeps the status, and thatTypeErroris inerror.cause. See #68- Both the timeout and the cancellation work by aborting the
signalpassed tofetch. A customfetchmust honorinit.signaluntil the body has been read; otherwise the request is not stopped andtimeoutMshas 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/jsoninternally for compatibility.
License
Distributed under CC0-1.0. See LICENSE.
