Symbol OpenAPI TypeScript Fetch Client

Common errors

• TypeError: fetch is not defined

  cause The client attempts to use the `fetch` API, but it's not available in the current JavaScript runtime, specifically in older Node.js versions (pre-18) or environments without a `fetch` polyfill.
  fix For Node.js environments, upgrade to Node.js 18 or newer, or install `node-fetch` and polyfill `globalThis.fetch`: ```typescript import fetch from 'node-fetch'; globalThis.fetch = fetch as any; ```

• Error: unable to verify the first certificate

  cause This error typically occurs when connecting to a Symbol node via HTTPS with a self-signed or untrusted SSL certificate, common in local development environments or private networks without proper certificate authority setup.
  fix For development, you can temporarily disable certificate verification by setting the `NODE_TLS_REJECT_UNAUTHORIZED='0'` environment variable (not recommended for production). Alternatively, configure your environment to trust the certificate or use an HTTP endpoint if available and appropriate for your security model.

Warnings

• breaking This package (version 1.0.3) was last published over 4 years ago (November 2021) and is considered abandoned. It reflects an outdated state of the Symbol OpenAPI specification and generator. Using it in new projects is highly discouraged due to potential incompatibilities and lack of updates.
  Fix: Migrate to the actively maintained `@symbol/symbol-sdk` package for interacting with the Symbol blockchain. If a generated client is strictly required, explore more recent OpenAPI client generators or a more up-to-date generated Symbol client if available.
• deprecated The README for this package explicitly directs users to `symbol-sdk-typescript-javascript` for client development. However, `symbol-sdk-typescript-javascript` itself has been deprecated as of January 2022. This further underscores the outdated nature of `symbol-openapi-typescript-fetch-client` and its recommendations.
  Fix: Disregard the README's recommendation to use `symbol-sdk-typescript-javascript`. Instead, use `@symbol/symbol-sdk` which is the current, actively supported SDK for Symbol.
• gotcha This is a *generated OpenAPI client*, not the comprehensive Symbol SDK. It provides raw API access based on the OpenAPI specification. It lacks higher-level abstractions, utility functions, and domain-specific logic that are present in the full `@symbol/symbol-sdk`.
  Fix: For complex Symbol application development requiring more than raw API calls, always prefer the `@symbol/symbol-sdk` package. Use this generated client only if you specifically need a minimalistic fetch-based client for an older API version and understand its limitations.
• gotcha The client relies on the global `fetch` API. In Node.js environments prior to version 18, `fetch` is not natively available. Running the client in such environments will result in a runtime error.
  Fix: For Node.js environments older than 18, install `node-fetch` (e.g., `npm install node-fetch`) and polyfill `globalThis.fetch` before making any API calls: ```typescript import fetch from 'node-fetch'; globalThis.fetch = fetch as any; // ... then use the generated client ```

Install

• npm install symbol-openapi-typescript-fetch-client npm
• yarn add symbol-openapi-typescript-fetch-client yarn
• pnpm add symbol-openapi-typescript-fetch-client pnpm

Imports

• Configuration
  wrong:

  const Configuration = require('symbol-openapi-typescript-fetch-client').Configuration;

  correct:

  import { Configuration } from 'symbol-openapi-typescript-fetch-client';

  The library primarily uses ES Module syntax and TypeScript definitions. CommonJS `require` might work for specific exports but is not the idiomatic way for this package.
• NodeRoutesApi
  wrong:

  import NodeRoutesApi from 'symbol-openapi-typescript-fetch-client/NodeRoutesApi';

  correct:

  import { NodeRoutesApi } from 'symbol-openapi-typescript-fetch-client';

  API client classes like `NodeRoutesApi` are named exports from the top-level package, not default exports from sub-paths.
• BlockRoutesApi

  import { BlockRoutesApi } from 'symbol-openapi-typescript-fetch-client';

  Other API classes (e.g., `BlockRoutesApi`, `TransactionRoutesApi`) follow the same named export pattern.

Quickstart

Demonstrates how to initialize the generated Symbol OpenAPI client and fetch basic information about a Symbol node, including its health status and general details.

import { Configuration, NodeRoutesApi } from 'symbol-openapi-typescript-fetch-client';

async function getNodeHealthStatus() {
  // For Node.js versions < 18, you might need a polyfill:
  // import fetch from 'node-fetch';
  // globalThis.fetch = fetch as any; 

  const nodeUrl = process.env.SYMBOL_NODE_URL ?? 'http://localhost:3000';

  try {
    const config = new Configuration({ 
      basePath: nodeUrl,
      // You can add headers, API keys, or other configurations here
      // For example, for a public node, no specific auth is usually needed for node info.
    });
    const nodeApi = new NodeRoutesApi(config);

    // Fetch the node info
    const nodeInfo = await nodeApi.getNodeInfo();
    console.log('Node Info:', nodeInfo);

    // Fetch the node health status
    const healthStatus = await nodeApi.getNodeHealth();
    console.log('Node Health Status:', healthStatus);

  } catch (error) {
    console.error('Error fetching Symbol node information:', error);
    if (error instanceof TypeError && error.message.includes('fetch is not defined')) {
      console.error('Hint: In Node.js environments, ensure `fetch` is available. For Node.js < 18, install `node-fetch` and polyfill `globalThis.fetch`.');
    }
  }
}

getNodeHealthStatus();