npm package: @puzzlex/core
Description: Environment-agnostic NFT trading logic for PuzzleX — order management, matching execution, config validation, and WebSocket utilities.
Author: PuzzleX Team
Latest version: 1.1.0

# @puzzlex/core

Environment-agnostic NFT trading logic for the PuzzleX platform. Provides order management, match execution, configuration validation, Merkle tree utilities, and WebSocket helpers.

## Installation

```bash
npm install @puzzlex/core
```

## Quick Start

All runtime configuration is injected via `initCoreConfig()` — no hardcoded addresses or secrets.

```ts
import { initCoreConfig, OrderManager } from '@puzzlex/core';

initCoreConfig({
  contracts: {
    seaportAddress: process.env.SEAPORT_ADDRESS!,
    zoneContractAddress: process.env.ZONE_ADDRESS!,
    nftContractAddress: process.env.NFT_ADDRESS!,
    erc20ContractAddress: process.env.ERC20_ADDRESS!,
    platformContractAddress: process.env.PLATFORM_ADDRESS!,
    royaltyContractAddress: process.env.ROYALTY_ADDRESS!,
    platformFeePercentage: Number(process.env.PLATFORM_FEE ?? 150),
    royaltyFeePercentage: Number(process.env.ROYALTY_FEE ?? 750),
  },
  network: {
    chainId: Number(process.env.CHAIN_ID),
    rpcUrl: process.env.RPC_URL!,
  },
  api: {
    apiBaseUrl: process.env.API_BASE_URL!,
    apiPath: process.env.API_PATH ?? '/api',
    wsBaseUrl: process.env.WS_BASE_URL!,
    cablePath: process.env.CABLE_PATH ?? '/cable',
  },
});

const orderManager = new OrderManager();
```

## Entry Points

| Import path | Use case |
|-------------|----------|
| `@puzzlex/core` | Full API — Node.js services, executors, SSR |
| `@puzzlex/core/browser` | Browser-safe subset — no Node.js dependencies (Redis, fs, etc.) |

### Main entry (`@puzzlex/core`)

```ts
import {
  OrderManager,
  OrderService,
  initCoreConfig,
  getCoreConfig,
  validateCoreConfig,
  WebSocketClient,
  createLogger,
  VERSION,
} from '@puzzlex/core';
```

### Browser entry (`@puzzlex/core/browser`)

```ts
import {
  OrderManager,
  OrderService,
  initCoreConfig,
  WebSocketClient,
  VERSION,
} from '@puzzlex/core/browser';
```

## Configuration Schema

`initCoreConfig()` accepts a `CoreEnvironmentConfig` object validated by Zod at runtime:

```ts
interface CoreEnvironmentConfig {
  contracts: {
    seaportAddress: string;        // Seaport contract address
    zoneContractAddress: string;   // Zone contract address
    nftContractAddress: string;    // NFT contract address
    erc20ContractAddress: string;  // ERC20 token address
    platformContractAddress: string;
    royaltyContractAddress: string;
    platformFeePercentage: number;
    royaltyFeePercentage: number;
    conduitKey?: string;
    conduitAddress?: string;
    defaultGasLimit?: number;
  };
  network: {
    chainId: number;
    rpcUrl: string;
    defaultGasLimit?: number;
    defaultGasLimitBuffer?: number;
    defaultGasLimitCap?: number;
  };
  api: {
    apiBaseUrl: string;
    apiPath: string;
    wsBaseUrl: string;
    cablePath: string;
  };
}
```

Use `validateCoreConfig()` and `assertValidConfig()` for pre-flight validation with detailed error reports.

## License

[Apache-2.0](./LICENSE)

## Third-Party Notices

This package depends on OpenSea Seaport tooling. See
[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for upstream attribution and
license references.