Skip to main content

​
Overview

The network utilities provide low-level functions for constructing authenticated API URLs and making HTTP requests. These are primarily used internally by the library but are exported for advanced use cases.

​
buildUrl()

Constructs authenticated API URLs with query parameters and optional API key injection.

​
Signature

buildUrl(endpoint: string, queryParams: Record<string, any>, useAuth?: boolean): URL

​
Parameters

​
endpoint
string
required
The API endpoint URL
​
queryParams
Record<string, any>
required
Query parameters to append to the URL
​
useAuth
boolean
default:"true"
Whether to include the API key in the query parameters

​
Returns

Returns a URL object with the endpoint, query parameters, and optional API key.

​
Example

import { buildUrl } from 'shamela';

const url = buildUrl('https://shamela.ws/api/books', {
  major_release: '1',
  minor_release: '0'
});

console.log(url.toString());
// https://shamela.ws/api/books?major_release=1&minor_release=0&key=YOUR_API_KEY
The API key is automatically included when useAuth is true (default) and will be read from the configuration.

​
httpsGet()

Makes HTTPS GET requests using the configured fetch implementation, automatically parsing JSON responses and returning binary data otherwise.

​
Signature

httpsGet<T extends Uint8Array | Record<string, any>>(
  url: string | URL, 
  options?: { fetchImpl?: typeof fetch }
): Promise<T>

​
Parameters

​
url
string | URL
required
The URL to fetch
​
options.fetchImpl
typeof fetch
Optional custom fetch implementation. Uses the configured fetch or global fetch if not provided.

​
Returns

Returns a Promise that resolves to:
  • Record<string, any> - If the response is JSON
  • Uint8Array - If the response is binary data

​
Example

import { httpsGet } from 'shamela';

// Fetch JSON data
const metadata = await httpsGet<{ version: number }>(
  'https://shamela.ws/api/master_patch?version=0'
);

console.log(metadata.version);

// Fetch binary data
const binaryData = await httpsGet<Uint8Array>(
  'https://shamela.ws/downloads/book.zip'
);

​
Custom Fetch Implementation

import { httpsGet } from 'shamela';

const data = await httpsGet('https://api.example.com/data', {
  fetchImpl: customFetch
});
Use the custom fetch implementation option when you need special request handling, such as adding custom headers or implementing retry logic.

​
Use Cases

These utilities are useful when:
  • Building custom API integrations with Shamela
  • Implementing custom caching or request middleware
  • Debugging API calls
  • Creating custom download managers