@plyaz/types 1.9.2 → 1.9.3

package/dist/api/index.d.ts

@@ -38,6 +38,7 @@ export type * from './config/types';
 export type * from './utils/types';
 export type * from './pubsub/types';
 export type * from './hooks/types';
+export type * from './services/types';
 export type * from './endpoints/types';
 export type * from './endpoints/health/types';
 export type * from './endpoints/campaigns/types';

package/dist/api/services/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Service Layer Types
+ * Core types for service functions and configuration
+ */
+import type { ApiClientWithEvents, UpdateConfigOptions } from '../client/types';
+import type { ApiConfig } from '../config';
+/**
+ * Options for service functions
+ * Allows overriding the API client instance, temporary config updates, and update strategy
+ *
+ * By default, services use a shared client instance with all available endpoints.
+ * This interface allows customization of the client behavior per-request or permanently.
+ *
+ * @template TEndpoints - The endpoints type for the API client
+ *
+ * @example
+ * ```typescript
+ * // Use default client (has access to all endpoints internally)
+ * const campaign = await fetchCampaign('123');
+ *
+ * // Override timeout temporarily (uses temporary config mode by default)
+ * const campaign = await fetchCampaign('123', {
+ *   apiConfig: { timeout: 5000 }
+ * });
+ *
+ * // Override with different update strategy
+ * const campaign = await fetchCampaign('123', {
+ *   apiConfig: { timeout: 5000 },
+ *   updateConfigOptions: { strategy: 'merge', scope: 'client' }
+ * });
+ *
+ * // Use custom client instance (rare - usually for testing)
+ * const customClient = await createApiClient({ baseURL: 'https://staging.api.com' });
+ * const campaign = await fetchCampaign('123', {
+ *   apiClient: customClient,
+ *   apiConfig: { retry: { attempts: 5 } }
+ * });
+ * ```
+ */
+export interface ServiceOptions<TEndpoints = unknown, TEventManager = unknown> {
+    /**
+     * Optional API client instance override
+     * Use this when you need a different client configuration
+     * The client should have all required endpoints for the service
+     */
+    apiClient?: ApiClientWithEvents<TEventManager, TEndpoints>;
+    /**
+     * Optional API configuration updates
+     * By default applied with { strategy: 'temporary' } mode (affects only this request)
+     * Can be overridden via updateConfigOptions
+     */
+    apiConfig?: Partial<ApiConfig>;
+    /**
+     * Optional update config options
+     * Controls how apiConfig is applied to the client
+     *
+     * Defaults to: { strategy: 'temporary' }
+     * - 'temporary': Only affects this request (highest priority)
+     * - 'merge': Merges with client config (persists)
+     * - 'replace': Replaces client config (persists)
+     */
+    updateConfigOptions?: UpdateConfigOptions;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",