HTTP endpoint utilities for Metorial. Provides a comprehensive HTTP client with request/response handling, query string management, error handling, and automatic retries.
npm install @metorial/util-endpointHTTP endpoint utilities for Metorial. Provides a comprehensive HTTP client with request/response handling, query string management, error handling, and automatic retries.
``bash`
npm install @metorial/util-endpointor
yarn add @metorial/util-endpointor
pnpm add @metorial/util-endpointor
bun add @metorial/util-endpoint
`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);
`
`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 });
`
`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);
}
}
`
`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
`
`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'
}
});
`
#### 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
Base class for creating typed endpoint classes.
`typescript`
interface MetorialRequest {
path: string | string[];
host?: string;
query?: Record
body?: Record
headers?: Record
}
Custom error class for API errors with additional properties:
- status: HTTP status codecode
- : Error codemessage`: Error message
-
MIT License - see LICENSE file for details.