Pear API Base Class (Holepunch)

Common errors

• TypeError: Class constructor PearAPI cannot be invoked without 'new'

  cause Attempting to call `PearAPI()` directly instead of instantiating it with the `new` keyword.
  fix Always instantiate the `PearAPI` class (or its subclasses) using `new`, e.g., `const api = new PearAPI();` or `class MyAPI extends PearAPI { ... }` then `new MyAPI();`.

• ReferenceError: PearAPI is not defined

  cause This typically occurs in a CommonJS environment when an ESM-only version of `pear-api` is used, or the `PearAPI` class was not correctly imported.
  fix Verify that your module import statement is correct (`import { PearAPI } from 'pear-api';`). If you are in a CommonJS context and need an ESM-only module, consider migrating your project to ESM or using dynamic `import()` within an `async` function.

• Error: Authentication failed: Invalid API key or token

  cause The base `PearAPI` or its derived classes often require an authentication token or key, which was either missing, expired, or invalid during initialization or an API call.
  fix Ensure that your API key or token is correctly provided during the `PearAPI` constructor or connection method. Double-check its validity, expiration, and required permissions according to your Pear API provider's documentation. Use environment variables for sensitive credentials.

Warnings

• breaking Migrating from Pear v1 to v2 involves significant breaking changes. Specifically, many UI-related methods have been moved or renamed, and the application entrypoint has changed from supporting HTML in v1 to only JavaScript in v2.
  Fix: Refer to the official Pear v2 Migration Guide (https://docs.pears.com/api/migration) for detailed steps, including updating your `package.json` entrypoint and adapting to new module structures like `pear-electron` and `pear-bridge`.
• deprecated The `pear run` CLI command has been deprecated in favor of using the `pear-runtime` module for embeddable runtimes with P2P Over-The-Air (OTA) updates.
  Fix: Transition to using the `pear-runtime` module in your application code for starting and managing the Pear runtime, or consult documentation for the appropriate CLI alternatives for development and deployment.
• gotcha Future major versions of Pear modules, including `pear-api`, are increasingly adopting an ESM-only (ECMAScript Modules) export strategy. Projects using CommonJS (`require()`) might encounter `ERR_REQUIRE_ESM`.
  Fix: Ensure your project is configured for ESM. This often means setting `"type": "module"` in your `package.json`, using `.mjs` file extensions, and updating all `require()` statements to `import` statements. For TypeScript, configure `"module": "NodeNext"` or `"moduleResolution": "NodeNext"` in `tsconfig.json`.
• gotcha The `pear-api` package, as a base class for P2P applications, requires careful handling of resource cleanup (e.g., network connections, database instances) during application teardown to prevent hanging processes or resource locks.
  Fix: Implement proper teardown logic using `Pear.teardown(cb)` and ensure all long-lived resources like Hyperswarm instances (`swarm.destroy()`) or worker pipes (`pipe.end()`) are gracefully closed to prevent resource leaks or application hangs. Refer to Pear troubleshooting documentation for common patterns.

Install

• npm install pear-api npm
• yarn add pear-api yarn
• pnpm add pear-api pnpm

Imports

• PearAPI
  wrong:

  const PearAPI = require('pear-api');

  correct:

  import { PearAPI } from 'pear-api';

  The primary API base class is typically imported as a named export. While v1 supports CommonJS, future major versions (v2+) are moving towards ESM-only.
• Config
  wrong:

  import Config from 'pear-api/config';

  correct:

  import { Config } from 'pear-api';

  Configuration utilities are often named exports from the main package or a subpath. Avoid direct subpath imports unless explicitly documented.
• PearError
  wrong:

  const { PearError } = require('pear-api');

  correct:

  import { PearError } from 'pear-api';

  Custom error classes or types related to the API are usually named exports. Ensure you're using ESM syntax for modern applications.

Quickstart

This quickstart demonstrates how to extend the `PearAPI` base class to create a custom P2P application API, handle connection, and publish data, including error handling and simulated asynchronous operations.

import { PearAPI } from 'pear-api';

interface MyApiOptions {
  authToken: string;
  appId: string;
}

interface MyP2PData {
  id: string;
  message: string;
  timestamp: number;
}

class MyPearAppAPI extends PearAPI {
  private token: string;
  private appId: string;

  constructor(options: MyApiOptions) {
    super(); // Initialize the base PearAPI class
    this.token = options.authToken;
    this.appId = options.appId;
    console.log(`MyPearAppAPI initialized for app: ${this.appId}`);
  }

  async connect(): Promise<boolean> {
    console.log('Attempting to connect to Pear network...');
    // Simulate P2P network connection logic
    await new Promise(resolve => setTimeout(resolve, 1000));
    if (!this.token) {
      console.error('Authentication token is missing.');
      return false;
    }
    console.log('Successfully connected to Pear network.');
    return true;
  }

  async publishData(data: MyP2PData): Promise<void> {
    if (!(await this.connect())) {
      throw new Error('Failed to connect, cannot publish data.');
    }
    console.log(`Publishing data [${data.id}]: ${data.message} at ${new Date(data.timestamp).toISOString()}`);
    // Simulate data publishing to the P2P network
    await new Promise(resolve => setTimeout(resolve, 500));
    console.log('Data published.');
  }

  static async createAndRun(token: string): Promise<MyPearAppAPI> {
    const api = new MyPearAppAPI({ authToken: token, appId: 'my-p2p-app' });
    const connected = await api.connect();
    if (connected) {
      await api.publishData({ id: 'msg-1', message: 'Hello P2P world!', timestamp: Date.now() });
    }
    return api;
  }
}

// Example usage with a dummy token
MyPearAppAPI.createAndRun(process.env.PEAR_AUTH_TOKEN ?? 'dummy_auth_token_123')
  .then(() => console.log('Pear application flow completed.'))
  .catch(error => console.error('Pear application error:', error.message));