@metorial/util-endpoint

HTTP endpoint utilities for Metorial. Provides a comprehensive HTTP client with request/response handling, query string management, error handling, and automatic retries.

Installation

npm install @metorial/util-endpoint
# or
yarn add @metorial/util-endpoint
# or
pnpm add @metorial/util-endpoint
# or
bun add @metorial/util-endpoint

Usage

Basic HTTP Client

import { MetorialEndpointManager } from '@metorial/util-endpoint';

// Create an endpoint manager
let endpointManager = new MetorialEndpointManager(
  { apiKey: 'your-api-key' }, // config
  'https://api.example.com', // apiHost
  config => ({
    // getHeaders function
    Authorization: `Bearer ${config.apiKey}`,
    'Content-Type': 'application/json'
  }),
  undefined, // fetchImpl (uses global fetch)
  { enableDebugLogging: false } // options
);

// Make requests
let user = await endpointManager
  ._get({
    path: ['users', '123'],
    query: { include: 'profile' }
  })
  .transform(userResource);

let newUser = await endpointManager
  ._post({
    path: 'users',
    body: { name: 'John Doe', email: '[email protected]' }
  })
  .transform(userResource);

Creating Custom Endpoint Classes

import { BaseMetorialEndpoint, MetorialEndpointManager } from '@metorial/util-endpoint';

class UsersEndpoint extends BaseMetorialEndpoint<{ apiKey: string }> {
  async getUser(id: string) {
    return this._get({
      path: ['users', id]
    }).transform(userResource);
  }

  async createUser(userData: { name: string; email: string }) {
    return this._post({
      path: 'users',
      body: userData
    }).transform(userResource);
  }

  async updateUser(id: string, updates: Partial<{ name: string; email: string }>) {
    return this._patch({
      path: ['users', id],
      body: updates
    }).transform(userResource);
  }

  async deleteUser(id: string) {
    return this._delete({
      path: ['users', id]
    });
  }

  async listUsers(params: { page?: number; limit?: number; search?: string }) {
    return this._get({
      path: 'users',
      query: params
    }).transform(paginatedUserResource);
  }
}

// Usage
let endpointManager = new MetorialEndpointManager(
  { apiKey: 'your-api-key' },
  'https://api.example.com',
  config => ({ Authorization: `Bearer ${config.apiKey}` }),
  undefined,
  { enableDebugLogging: true }
);

let usersEndpoint = new UsersEndpoint(endpointManager);

// Use the endpoint
let user = await usersEndpoint.getUser('123');
let users = await usersEndpoint.listUsers({ page: 1, limit: 10 });

Error Handling

import { MetorialSDKError } from '@metorial/util-endpoint';

try {
  let user = await endpointManager
    ._get({
      path: ['users', 'invalid-id']
    })
    .transform(userResource);
} catch (error) {
  if (error instanceof MetorialSDKError) {
    console.log('API Error:', error.message);
    console.log('Status:', error.status);
    console.log('Code:', error.code);

    if (error.status === 404) {
      console.log('User not found');
    } else if (error.status === 429) {
      console.log('Rate limited - retry later');
    }
  } else {
    console.log('Network error:', error.message);
  }
}

Query String Handling

// Complex query parameters are automatically serialized
let response = await endpointManager._get({
  path: 'search',
  query: {
    q: 'metorial',
    filters: {
      category: ['api', 'sdk'],
      status: 'active'
    },
    sort: {
      field: 'created_at',
      direction: 'desc'
    },
    page: 1,
    limit: 20
  }
});

// Results in: /search?q=metorial&filters[category][]=api&filters[category][]=sdk&filters[status]=active&sort[field]=created_at&sort[direction]=desc&page=1&limit=20

Custom Request Configuration

// Custom headers for specific requests
let response = await endpointManager._post({
  path: 'upload',
  headers: {
    'Content-Type': 'multipart/form-data',
    'X-Custom-Header': 'custom-value'
  },
  body: formData
});

// Custom host for specific requests
let response = await endpointManager._get({
  path: 'external-data',
  host: 'https://external-api.com',
  headers: {
    'X-API-Key': 'external-api-key'
  }
});

API Reference

MetorialEndpointManager<Config>

Constructor

new MetorialEndpointManager(
  config: Config,
  apiHost: string,
  getHeaders: (config: Config) => Record<string, string>,
  fetchImpl?: typeof fetch,
  options?: { enableDebugLogging: boolean }
)

Methods

• _get(request: MetorialRequest) - Make a GET request
• _post(request: MetorialRequest) - Make a POST request
• _put(request: MetorialRequest) - Make a PUT request
• _patch(request: MetorialRequest) - Make a PATCH request
• _delete(request: MetorialRequest) - Make a DELETE request

BaseMetorialEndpoint<Config>

Base class for creating typed endpoint classes.

MetorialRequest

interface MetorialRequest {
  path: string | string[];
  host?: string;
  query?: Record<string, any>;
  body?: Record<string, any> | FormData;
  headers?: Record<string, string>;
}

MetorialSDKError

Custom error class for API errors with additional properties:

• status: HTTP status code
• code: Error code
• message: Error message

License

MIT License - see LICENSE file for details.