@simpleapps-com/augur-api 0.1.0

package/dist/cjs/core/base-client.d.ts

@@ -0,0 +1,292 @@
+import { HTTPClient } from './client';
+import { z } from 'zod';
+/**
+ * HTTP method types for API operations
+ */
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * Configuration for API endpoint operations
+ */
+export interface EndpointConfig<TParams = unknown, TResponse = unknown> {
+    /** HTTP method for the request */
+    method: HTTPMethod;
+    /** Endpoint path (will be prefixed with baseUrl) */
+    path: string;
+    /** Zod schema for validating request parameters */
+    paramsSchema?: z.ZodSchema<TParams>;
+    /** Zod schema for validating response data */
+    responseSchema: z.ZodSchema<TResponse>;
+    /** Whether this endpoint requires authentication (default: true) */
+    requiresAuth?: boolean;
+}
+/**
+ * Standard pagination parameters with better type constraints
+ */
+export interface PaginationParams {
+    /** Number of items to return (1-1000) */
+    limit?: number;
+    /** Starting offset for pagination (>= 0) */
+    offset?: number;
+    /** Sort ordering in format: 'field|ASC' or 'field|DESC' */
+    orderBy?: string;
+}
+/**
+ * Standard search parameters extending pagination
+ */
+export interface SearchParams extends PaginationParams {
+    /** Search query string */
+    q?: string;
+}
+/**
+ * Edge caching parameters for Cloudflare integration
+ */
+export interface CacheParams {
+    /** Cache duration in hours (1, 2, 3, 4, 5, 8) */
+    edgeCache?: 1 | 2 | 3 | 4 | 5 | 8;
+}
+/**
+ * Standard GET request parameters combining pagination, search, and caching
+ */
+export interface StandardGetParams extends SearchParams, CacheParams {
+}
+/**
+ * Base structure for API responses - enforces consistency
+ */
+export interface StandardResponse<T> {
+    /** HTTP status code */
+    status: number;
+    /** Optional status message (omitted in health checks) */
+    message?: string;
+    /** Response data of type T */
+    data: T;
+    /** Total number of results (for paginated responses) */
+    totalResults?: number;
+    /** Number of items in current response */
+    count?: number;
+    /** Optional array of key-value pairs */
+    options?: Array<Record<string, unknown>>;
+}
+/**
+ * Result of a successful API operation
+ */
+export interface OperationResult<T> {
+    data: T;
+    status: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Abstract base class for all service clients
+ *
+ * Provides standardized error handling, validation, and request processing
+ * to eliminate boilerplate code across service implementations.
+ *
+ * @example
+ * ```typescript
+ * class MyServiceClient extends BaseServiceClient {
+ *   constructor(http: HTTPClient, baseUrl?: string) {
+ *     super('myservice', http, baseUrl || 'https://myservice.augur-api.com');
+ *   }
+ *
+ *   // Simple method using executeRequest
+ *   async getUser(id: number) {
+ *     return this.executeRequest({
+ *       method: 'GET',
+ *       path: `/users/${id}`,
+ *       responseSchema: UserResponseSchema
+ *     });
+ *   }
+ *
+ *   // Method with parameters
+ *   async listUsers(params?: UserListParams) {
+ *     return this.executeRequest({
+ *       method: 'GET',
+ *       path: '/users',
+ *       paramsSchema: UserListParamsSchema,
+ *       responseSchema: UserListResponseSchema
+ *     }, params);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseServiceClient {
+    protected readonly serviceName: string;
+    protected readonly http: HTTPClient;
+    protected readonly baseUrl: string;
+    /**
+     * Create a new service client instance
+     * @param serviceName Name of the service (used for error reporting)
+     * @param http Configured HTTPClient instance
+     * @param baseUrl Base URL for the service API
+     */
+    constructor(serviceName: string, http: HTTPClient, baseUrl: string);
+    /**
+     * Execute a standardized API request with automatic validation and error handling
+     *
+     * This method handles all the common patterns:
+     * - Parameter validation with Zod schemas
+     * - HTTP request execution
+     * - Response validation
+     * - Consistent error handling and reporting
+     *
+     * @param config Endpoint configuration including method, path, and schemas
+     * @param params Optional request parameters (query params for GET, body for POST/PUT)
+     * @param pathParams Optional path parameters for URL substitution
+     * @returns Promise resolving to the validated response data
+     * @throws ValidationError When parameters or response validation fails
+     * @throws AugurError For HTTP errors (handled by HTTPClient interceptors)
+     */
+    protected executeRequest<TParams = unknown, TResponse = unknown>(config: EndpointConfig<TParams, TResponse>, params?: TParams, pathParams?: Record<string, string | number>): Promise<TResponse>;
+    /**
+     * Create a standardized list method factory
+     *
+     * Generates a function that follows the standard list pattern with optional parameters,
+     * pagination support, and consistent error handling.
+     *
+     * @param endpoint The API endpoint path
+     * @param paramsSchema Zod schema for validating query parameters
+     * @param responseSchema Zod schema for validating the response
+     * @returns A function that executes the list operation
+     */
+    protected createListMethod<TParams extends StandardGetParams = StandardGetParams, TItem = unknown, TResponse extends StandardResponse<TItem[]> = StandardResponse<TItem[]>>(endpoint: string, paramsSchema: z.ZodSchema<TParams>, responseSchema: z.ZodSchema<TResponse>): (params?: TParams) => Promise<TResponse>;
+    /**
+     * Create a standardized get method factory
+     *
+     * Generates a function that retrieves a single item by ID with optional parameters.
+     *
+     * @param endpointTemplate The API endpoint template with {id} placeholder
+     * @param responseSchema Zod schema for validating the response
+     * @param paramsSchema Optional Zod schema for query parameters
+     * @returns A function that executes the get operation
+     */
+    protected createGetMethod<TParams extends CacheParams = CacheParams, TItem = unknown, TResponse extends StandardResponse<TItem> = StandardResponse<TItem>>(endpointTemplate: string, responseSchema: z.ZodSchema<TResponse>, paramsSchema?: z.ZodSchema<TParams>): (id: string | number, params?: TParams) => Promise<TResponse>;
+    /**
+     * Create a standardized create method factory
+     *
+     * Generates a function that creates a new resource via POST request.
+     *
+     * @param endpoint The API endpoint path
+     * @param requestSchema Zod schema for validating request data
+     * @param responseSchema Zod schema for validating the response
+     * @returns A function that executes the create operation
+     */
+    protected createCreateMethod<TRequest, TResponse>(endpoint: string, requestSchema: z.ZodSchema<TRequest>, responseSchema: z.ZodSchema<TResponse>): (data: TRequest) => Promise<TResponse>;
+    /**
+     * Create a standardized update method factory
+     *
+     * Generates a function that updates an existing resource via PUT request.
+     *
+     * @param endpointTemplate The API endpoint template with {id} placeholder
+     * @param requestSchema Zod schema for validating request data
+     * @param responseSchema Zod schema for validating the response
+     * @returns A function that executes the update operation
+     */
+    protected createUpdateMethod<TRequest, TResponse>(endpointTemplate: string, requestSchema: z.ZodSchema<TRequest>, responseSchema: z.ZodSchema<TResponse>): (id: string | number, data: TRequest) => Promise<TResponse>;
+    /**
+     * Create a standardized delete method factory
+     *
+     * Generates a function that deletes a resource via DELETE request.
+     *
+     * @param endpointTemplate The API endpoint template with {id} placeholder
+     * @param responseSchema Zod schema for validating the response
+     * @returns A function that executes the delete operation
+     */
+    protected createDeleteMethod<TResponse>(endpointTemplate: string, responseSchema: z.ZodSchema<TResponse>): (id: string | number) => Promise<TResponse>;
+    /**
+     * Create a health check method that follows the standard pattern
+     *
+     * @param responseSchema Zod schema for the health check response
+     * @returns A function that executes the health check
+     */
+    protected createHealthCheckMethod<TResponse>(responseSchema: z.ZodSchema<TResponse>): () => Promise<TResponse>;
+    /**
+     * Create a delete method that returns a boolean success indicator
+     *
+     * Common pattern for delete operations that don't return the deleted entity.
+     * The method always returns true if the request succeeds (no error thrown).
+     *
+     * @param endpointTemplate The API endpoint template with {id} placeholder
+     * @returns A function that executes the delete operation and returns true on success
+     */
+    protected createDeleteBooleanMethod(endpointTemplate: string): (id: string | number) => Promise<boolean>;
+    /**
+     * Create a search method with required query parameter
+     *
+     * Enforces that a search query is provided and handles the common search pattern.
+     *
+     * @param endpoint The API endpoint path
+     * @param paramsSchema Zod schema for validating search parameters (must include 'q')
+     * @param responseSchema Zod schema for validating the response
+     * @returns A function that executes the search operation
+     */
+    protected createSearchMethod<TParams extends SearchParams, TResponse>(endpoint: string, paramsSchema: z.ZodSchema<TParams>, responseSchema: z.ZodSchema<TResponse>): (params: TParams) => Promise<TResponse>;
+    /**
+     * Create a method that returns the first item from an array response
+     *
+     * Common pattern for endpoints that return an array but we only need the first item.
+     *
+     * @param endpoint The API endpoint path
+     * @param paramsSchema Zod schema for validating request parameters
+     * @param itemSchema Zod schema for validating individual items in the array
+     * @returns A function that executes the request and returns the first item or undefined
+     */
+    protected createSingleItemMethod<TParams, TItem>(endpoint: string, paramsSchema: z.ZodSchema<TParams>, itemSchema: z.ZodSchema<TItem>): (params: TParams) => Promise<TItem | undefined>;
+    /**
+     * Create an action method for operations like enable/disable
+     *
+     * Common pattern for POST/PUT endpoints that perform actions on resources.
+     *
+     * @param endpointTemplate The API endpoint template with placeholders
+     * @param method HTTP method (POST or PUT)
+     * @param responseSchema Zod schema for validating the response
+     * @param pathParams Additional path parameters beyond the id
+     * @returns A function that executes the action
+     */
+    protected createActionMethod<TResponse>(endpointTemplate: string, method: 'POST' | 'PUT', responseSchema: z.ZodSchema<TResponse>, pathParams?: Record<string, string>): (id: string | number) => Promise<TResponse>;
+    /**
+     * Create a void method that doesn't return meaningful data
+     *
+     * Common pattern for operations that succeed with empty or undefined responses.
+     *
+     * @param endpointTemplate The API endpoint template
+     * @param method HTTP method
+     * @returns A function that executes the operation
+     */
+    protected createVoidMethod(endpointTemplate: string, method: HTTPMethod): (id?: string | number) => Promise<void>;
+    /**
+     * Helper to create a standard array response schema
+     */
+    private createArrayResponseSchema;
+    /**
+     * Create a standardized document method for endpoints that return enhanced documentation
+     *
+     * Common pattern across services for endpoints like /content/{id}/doc, /users/{id}/doc, etc.
+     *
+     * @param endpointTemplate The API endpoint template with {id} placeholder
+     * @param responseSchema Zod schema for validating the document response
+     * @param paramsSchema Optional Zod schema for query parameters
+     * @returns A function that executes the document retrieval operation
+     */
+    protected createDocMethod<TParams, TResponse>(endpointTemplate: string, responseSchema: z.ZodSchema<TResponse>, paramsSchema?: z.ZodSchema<TParams>): (id: string | number, params?: TParams) => Promise<TResponse>;
+    /**
+     * Create a standardized ping method for service availability testing
+     *
+     * @param responseSchema Zod schema for the ping response (typically string or literal)
+     * @returns A function that executes the ping operation
+     */
+    protected createPingMethod<TResponse>(responseSchema: z.ZodSchema<TResponse>): () => Promise<TResponse>;
+    /**
+     * Build endpoint path with optional path parameter substitution
+     *
+     * @param pathTemplate Path template with {param} placeholders
+     * @param pathParams Object containing parameter values
+     * @returns Processed endpoint path
+     *
+     * @example
+     * ```typescript
+     * buildEndpointPath('/users/{id}', { id: '123' }) // returns '/users/123'
+     * buildEndpointPath('/health-check') // returns '/health-check'
+     * ```
+     */
+    private buildEndpointPath;
+}
+//# sourceMappingURL=base-client.d.ts.map

package/dist/cjs/core/base-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-client.d.ts","sourceRoot":"","sources":["../../../src/core/base-client.ts"],"names":[],"mappings":"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"}