@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

``bash
npm install @metorial/util-endpoint


or

yarn add @metorial/util-endpoint

or

pnpm add @metorial/util-endpoint

or

bun add @metorial/util-endpoint
`

Usage

$3

`typescript
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: 'john@example.com' }
})
.transform(userResource);
`

$3

`typescript
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 });
`

$3

`typescript
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);
}
}
`

$3

`typescript
// 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
`

$3

`typescript
// 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

$3

#### Constructor

`typescript
new MetorialEndpointManager(
config: Config,
apiHost: string,
getHeaders: (config: Config) => Record,
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

$3

Base class for creating typed endpoint classes.

$3

`typescript
interface MetorialRequest {
path: string | string[];
host?: string;
query?: Record;
body?: Record | FormData;
headers?: Record;
}
`

$3

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.