JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1703
  • Score
    100M100P100Q107469F
  • License MIT

Core type definitions and interfaces for the 23blocks SDK

Package Exports

  • @23blocks/contracts
  • @23blocks/contracts/package.json

Readme

@23blocks/contracts

Core type definitions and interfaces for the 23blocks SDK.

npm version License: MIT

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: 'user@example.com',
  password: 'secret123',
  apiKey: 'sk-xxx',
});
// Output: { email: 'user@example.com', 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';

License

MIT - Copyright (c) 2024 23blocks