talisik-shortener
Version:
JavaScript/TypeScript client for Talisik URL Shortener - A privacy-focused URL shortening service
336 lines (328 loc) • 9.62 kB
TypeScript
/**
* Error classes for Talisik URL Shortener client
*/
/**
* Custom error class for Talisik-specific errors
*/
declare class TalisikError extends Error {
readonly status?: number;
readonly code?: string;
readonly details?: unknown;
constructor(message: string, status?: number, code?: string, details?: unknown);
/**
* Check if this is a network-related error
*/
isNetworkError(): boolean;
/**
* Check if this is a client error (4xx)
*/
isClientError(): boolean;
/**
* Check if this is a server error (5xx)
*/
isServerError(): boolean;
/**
* Check if this error indicates the resource was not found
*/
isNotFound(): boolean;
/**
* Check if this error indicates a timeout
*/
isTimeout(): boolean;
/**
* Convert error to JSON-serializable object
*/
toJSON(): {
name: string;
message: string;
status: number | undefined;
code: string | undefined;
details: unknown;
};
}
/**
* Error thrown when the Talisik client is not properly configured
*/
declare class TalisikConfigError extends TalisikError {
constructor(message: string);
}
/**
* Error thrown when a URL validation fails
*/
declare class TalisikValidationError extends TalisikError {
constructor(message: string);
}
/**
* TypeScript type definitions for Talisik URL Shortener
*/
interface TalisikConfig {
/** Base URL of the Talisik API server */
baseUrl: string;
/** API key for authentication (if required) */
apiKey?: string;
/** Custom headers to include with requests */
headers?: Record<string, string>;
/** Request timeout in milliseconds (default: 10000) */
timeout?: number;
}
interface ShortenRequest {
/** The URL to shorten */
url: string;
/** Custom short code (optional) */
customCode?: string | null;
/** Expiration time in hours (optional) */
expiresHours?: number | null;
}
interface ShortenResponse {
/** The generated short URL */
shortUrl: string;
/** The original URL that was shortened */
originalUrl: string;
/** The short code used */
shortCode: string;
/** Expiration date in ISO format (if set) */
expiresAt?: string | null;
}
interface UrlInfo {
/** The short code */
shortCode: string;
/** The original URL */
originalUrl: string;
/** Creation timestamp in ISO format */
createdAt: string;
/** Expiration timestamp in ISO format (if set) */
expiresAt?: string | null;
/** Number of times this URL has been clicked */
clickCount: number;
/** Whether the URL is active */
isActive: boolean;
/** Whether the URL has expired */
isExpired: boolean;
}
interface Stats {
/** Total number of URLs created */
totalUrls: number;
/** Number of active URLs */
activeUrls: number;
/** Total number of clicks across all URLs */
totalClicks: number;
}
interface RequestOptions {
/** Override the default timeout for this request */
timeout?: number;
/** Additional headers for this request */
headers?: Record<string, string>;
/** AbortController signal for request cancellation */
signal?: AbortSignal;
}
type TalisikMethod = "GET" | "POST" | "PUT" | "DELETE";
interface APIResponse<T = unknown> {
data: T;
success: boolean;
error?: TalisikError;
}
interface UseTalisikResult {
shortenUrl: (request: ShortenRequest) => Promise<ShortenResponse>;
getUrlInfo: (shortCode: string) => Promise<UrlInfo | null>;
getStats: () => Promise<Stats>;
loading: boolean;
error: TalisikError | null;
}
interface UseTalisikOptions extends Partial<TalisikConfig> {
/** Whether to automatically retry failed requests */
retry?: boolean;
/** Number of retry attempts (default: 3) */
retryAttempts?: number;
}
/**
* Main client class for interacting with Talisik URL Shortener API
*
* @example
* ```typescript
* const client = new TalisikClient({
* baseUrl: 'https://api.talisik.com'
* });
*
* // Shorten a URL
* const result = await client.shorten({
* url: 'https://example.com',
* customCode: 'my-link'
* });
*
* // Get URL info
* const info = await client.getUrlInfo('my-link');
* ```
*/
declare class TalisikClient {
private config;
constructor(config: TalisikConfig);
/**
* Shorten a URL
*
* @param request - The URL shortening request
* @param options - Additional request options
* @returns Promise that resolves to the shortened URL information
*
* @example
* ```typescript
* const result = await client.shorten({
* url: 'https://example.com',
* customCode: 'my-custom-code',
* expiresHours: 24
* });
* ```
*/
shorten(request: ShortenRequest, options?: RequestOptions): Promise<ShortenResponse>;
/**
* Get information about a shortened URL
*
* @param shortCode - The short code to look up
* @param options - Additional request options
* @returns Promise that resolves to URL info or null if not found
*
* @example
* ```typescript
* const info = await client.getUrlInfo('abc123');
* if (info) {
* console.log(`URL has been clicked ${info.clickCount} times`);
* }
* ```
*/
getUrlInfo(shortCode: string, options?: RequestOptions): Promise<UrlInfo | null>;
/**
* Get overall statistics
*
* @param options - Additional request options
* @returns Promise that resolves to usage statistics
*
* @example
* ```typescript
* const stats = await client.getStats();
* console.log(`Total URLs: ${stats.totalUrls}`);
* ```
*/
getStats(options?: RequestOptions): Promise<Stats>;
/**
* Get all shortened URLs for table display
*
* @param options - Additional request options
* @returns Promise that resolves to array of URL records
*
* @example
* ```typescript
* const urls = await client.getAllUrls();
* console.log(`Found ${urls.length} URLs`);
* ```
*/
getAllUrls(options?: RequestOptions): Promise<any[]>;
/**
* Get the redirect URL for a short code (without following the redirect)
*
* @param shortCode - The short code
* @returns The full redirect URL
*
* @example
* ```typescript
* const redirectUrl = client.getRedirectUrl('abc123');
* // Returns: https://api.talisik.com/abc123
* ```
*/
getRedirectUrl(shortCode: string): string;
/**
* Expand a short code to get the original URL (follows redirect)
*
* @param shortCode - The short code to expand
* @param options - Additional request options
* @returns Promise that resolves to the original URL or null if not found
*
* @example
* ```typescript
* const originalUrl = await client.expand('abc123');
* // Returns: https://example.com
* ```
*/
expand(shortCode: string, options?: RequestOptions): Promise<string | null>;
/**
* Low-level request method
*/
private request;
}
/**
* Factory function to create a new Talisik client instance
*
* @param config - Client configuration
* @returns A new TalisikClient instance
*
* @example
* ```typescript
* import { createTalisikClient } from 'talisik-shortener';
*
* const client = createTalisikClient({
* baseUrl: 'https://api.talisik.com'
* });
* ```
*/
declare function createTalisikClient(config: TalisikConfig): TalisikClient;
/**
* React hooks for Talisik URL Shortener
*
* These hooks are optional and only available if React is installed.
* They provide an easy way to integrate Talisik with React applications.
*
* @example
* ```typescript
* import { useTalisik } from 'talisik-shortener';
*
* function MyComponent() {
* const { shortenUrl, loading, error } = useTalisik({
* baseUrl: 'https://api.talisik.com'
* });
*
* const handleShorten = async () => {
* const result = await shortenUrl({ url: 'https://example.com' });
* console.log(result.shortUrl);
* };
*
* return (
* <button onClick={handleShorten} disabled={loading}>
* {loading ? 'Shortening...' : 'Shorten URL'}
* </button>
* );
* }
* ```
*/
/**
* React hook for using Talisik URL Shortener
*
* @param options - Configuration options
* @returns Object with shortening functions, loading state, and errors
*/
declare function useTalisik(options: UseTalisikOptions): UseTalisikResult | undefined;
/**
* React hook for creating a Talisik client instance
*
* @param config - Client configuration
* @returns Memoized TalisikClient instance
*
* @example
* ```typescript
* function MyComponent() {
* const client = useTalisikClient({
* baseUrl: 'https://api.talisik.com'
* });
*
* const handleShorten = async () => {
* const result = await client.shorten({ url: 'https://example.com' });
* };
*
* return <button onClick={handleShorten}>Shorten</button>;
* }
* ```
*/
declare function useTalisikClient(config: TalisikConfig): TalisikClient | undefined;
declare const hooks: {
useTalisik: typeof useTalisik;
useTalisikClient: typeof useTalisikClient;
};
export { TalisikClient, TalisikConfigError, TalisikError, TalisikValidationError, createTalisikClient, TalisikClient as default, hooks, useTalisik, useTalisikClient };
export type { APIResponse, RequestOptions, ShortenRequest, ShortenResponse, Stats, TalisikConfig, TalisikMethod, UrlInfo, UseTalisikOptions, UseTalisikResult };