@23blocks/contracts

Core type definitions and interfaces for the 23blocks SDK.

Installation

npm install @23blocks/contracts

Overview

This package provides the foundational types and interfaces used throughout the 23blocks SDK ecosystem. It includes:

• Transport interfaces - Abstract communication layer
• Error handling - Standardized error types and codes
• Pagination - Common pagination types and utilities
• Identity - Base entity interfaces
• Block configuration - Standard block configuration types
• Logging - Logger interface and utilities for debugging

Usage

Error Handling

import {
  BlockErrorException,
  isBlockErrorException,
  ErrorCodes,
  type BlockError,
} from '@23blocks/contracts';

try {
  await someOperation();
} catch (error) {
  if (isBlockErrorException(error)) {
    console.log('Error code:', error.code);
    console.log('Message:', error.message);
    console.log('Request ID:', error.requestId);  // For support tickets
    console.log('Duration:', error.duration);      // Request timing

    switch (error.code) {
      case ErrorCodes.INVALID_CREDENTIALS:
        // Handle invalid credentials
        break;
      case ErrorCodes.NOT_FOUND:
        // Handle not found
        break;
      case ErrorCodes.NETWORK_ERROR:
        // Handle network error
        break;
    }
  }
}

Logging

The package provides a standard Logger interface and implementations:

import {
  type Logger,
  consoleLogger,
  noopLogger,
  generateRequestId,
  maskSensitiveData,
} from '@23blocks/contracts';

// Use the built-in console logger
consoleLogger.info('User signed in', { userId: '123' });
// Output: [23blocks] User signed in { userId: '123' }

// Use noopLogger in production to silence logs
const logger = process.env.NODE_ENV === 'production' ? noopLogger : consoleLogger;

// Generate unique request IDs
const requestId = generateRequestId();
// Output: "req_m5abc_xyz123"

// Mask sensitive data before logging
const safeData = maskSensitiveData({
  email: '[email protected]',
  password: 'secret123',
  apiKey: 'sk-xxx',
});
// Output: { email: '[email protected]', password: '***', apiKey: '***' }

Custom Logger

Implement the Logger interface for custom logging solutions:

import type { Logger } from '@23blocks/contracts';

const customLogger: Logger = {
  debug: (message, meta) => winston.debug(message, meta),
  info: (message, meta) => winston.info(message, meta),
  warn: (message, meta) => winston.warn(message, meta),
  error: (message, meta) => winston.error(message, meta),
};

Pagination

import type { PageResult, ListParams, PageMeta } from '@23blocks/contracts';
import { emptyPageResult } from '@23blocks/contracts';

// Define list parameters
const params: ListParams = {
  limit: 20,
  offset: 0,
  sort: { field: 'createdAt', direction: 'desc' },
};

// Handle paginated results
function handleResults<T>(result: PageResult<T>) {
  console.log('Items:', result.data);
  console.log('Total:', result.meta.total);
  console.log('Has more:', result.meta.hasMore);
}

// Create empty result
const empty = emptyPageResult<MyType>();

Transport Interface

import type { Transport, TransportConfig, Interceptors } from '@23blocks/contracts';

// Configure transport with new options
const config: TransportConfig = {
  baseUrl: 'https://api.example.com',
  timeout: 30000,
  debug: true,  // Enable debug logging
  retry: {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    backoffMultiplier: 2,
  },
  interceptors: {
    onError: (error, context) => {
      console.error(`Request ${context.requestId} failed`);
      throw error;
    },
  },
};

Block Configuration

import type { BlockConfig } from '@23blocks/contracts';

const config: BlockConfig = {
  apiKey: 'your-api-key',
  tenantId: 'optional-tenant-id',
};

API Reference

Error Types

| Export | Type | Description | |--------|------|-------------| | BlockError | interface | Error object structure | | BlockErrorException | class | Throwable error with code and message | | isBlockError | function | Type guard for BlockError | | isBlockErrorException | function | Type guard for BlockErrorException | | ErrorCodes | const | Standard error code constants | | ErrorCode | type | Union type of all error codes |

BlockError Properties

| Property | Type | Description | |----------|------|-------------| | code | string | Error code identifier | | message | string | Human-readable error message | | status | number | HTTP status code | | source | string? | Source pointer (e.g., '/data/attributes/email') | | meta | Record<string, unknown>? | Additional metadata | | requestId | string? | Unique request ID for tracing | | duration | number? | Request duration in milliseconds |

Logger Types

| Export | Type | Description | |--------|------|-------------| | Logger | interface | Logger interface with debug/info/warn/error | | consoleLogger | const | Console logger with [23blocks] prefix | | noopLogger | const | Silent no-op logger | | generateRequestId | function | Generate unique request IDs | | maskSensitiveData | function | Mask sensitive values in objects |

Pagination Types

| Export | Type | Description | |--------|------|-------------| | PageMeta | interface | Pagination metadata (total, hasMore, etc.) | | PageResult<T> | interface | Paginated response with data and meta | | PaginationParams | interface | Basic pagination parameters | | ListParams | interface | Extended params with sorting | | SortParam | interface | Sort field and direction | | SortDirection | type | 'asc' | 'desc' | | emptyPageResult | function | Creates empty PageResult |

Identity Types

| Export | Type | Description | |--------|------|-------------| | IdentityCore | interface | Base entity with id | | EntityStatus | type | 'active' | 'inactive' | 'pending' | | Timestamps | interface | createdAt, updatedAt fields | | SoftDeletable | interface | deletedAt field | | Auditable | interface | createdBy, updatedBy fields |

Transport Types

| Export | Type | Description | |--------|------|-------------| | Transport | interface | Abstract transport interface | | RequestConfig | interface | Request configuration | | RequestOptions | interface | Additional request options | | HeadersProvider | type | Function returning headers | | TransportConfig | interface | Transport configuration | | RetryConfig | interface | Retry configuration | | Interceptors | interface | Request/response interceptors |

Block Types

| Export | Type | Description | |--------|------|-------------| | BlockConfig | interface | Standard block configuration | | BlockFactory | type | Factory function type | | BlockMetadata | interface | Block metadata | | BlockRegistration | interface | Block registration info |

TypeScript Support

This package is written in TypeScript and provides full type definitions. All types are exported and can be used directly:

import type {
  Transport,
  TransportConfig,
  BlockConfig,
  PageResult,
  BlockError,
  Logger,
  Interceptors,
} from '@23blocks/contracts';

Related Packages

• @23blocks/transport-http - HTTP transport implementation
• @23blocks/jsonapi-codec - JSON:API encoder/decoder
• @23blocks/sdk - Full SDK package

License

MIT - Copyright (c) 2024 23blocks