@tinycloud/sdk-services 2.0.1 → 2.0.2

package/dist/{types.d.ts → BaseService-D9BFm_rV.d.cts}

@@ -21,7 +21,7 @@
  * }
  * ```
  */
-export type Result<T, E = ServiceError> = {
+type Result<T, E = ServiceError> = {
     ok: true;
     data: T;
 } | {
@@ -31,7 +31,7 @@ export type Result<T, E = ServiceError> = {
 /**
  * Service error with structured information.
  */
-export interface ServiceError {
+interface ServiceError {
     /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
     code: string;
     /** Human-readable error message */
@@ -46,7 +46,7 @@ export interface ServiceError {
 /**
  * Storage quota information returned with quota-related errors.
  */
-export interface StorageQuotaInfo {
+interface StorageQuotaInfo {
     usedBytes: number;
     limitBytes: number;
     service: string;
@@ -54,7 +54,7 @@ export interface StorageQuotaInfo {
 /**
  * Standard error codes used across services.
  */
-export declare const ErrorCodes: {
+declare const ErrorCodes: {
     readonly NOT_FOUND: "NOT_FOUND";
     readonly AUTH_EXPIRED: "AUTH_EXPIRED";
     readonly AUTH_REQUIRED: "AUTH_REQUIRED";
@@ -85,12 +85,12 @@ export declare const ErrorCodes: {
     readonly DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR";
     readonly DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION";
 };
-export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 /**
  * Session data required for authenticated service operations.
  * Both TinyCloudSession and web-sdk Session can be cast to this interface.
  */
-export interface ServiceSession {
+interface ServiceSession {
     /** The delegation header containing the UCAN */
     delegationHeader: {
         Authorization: string;
@@ -107,12 +107,12 @@ export interface ServiceSession {
 /**
  * Headers type - compatible with both browser and Node.js.
  */
-export type ServiceHeaders = Record<string, string> | [string, string][];
+type ServiceHeaders = Record<string, string> | [string, string][];
 /**
  * A single fact object to include in the UCAN invocation.
  * Facts are key-value objects that the server reads from the UCAN facts field.
  */
-export interface InvocationFact {
+interface InvocationFact {
     [key: string]: unknown;
 }
 /**
@@ -120,7 +120,7 @@ export interface InvocationFact {
  * This is an array of fact objects per the UCAN spec.
  * Used to pass additional parameters that the server reads from the UCAN facts field.
  */
-export type InvocationFacts = InvocationFact[];
+type InvocationFacts = InvocationFact[];
 /**
  * Invoke function signature - platform-specific implementation injected via DI.
  * Both node-sdk-wasm and web-sdk-wasm export this with identical signature.
@@ -132,11 +132,11 @@ export type InvocationFacts = InvocationFact[];
  * @param facts - Optional facts to include in the UCAN (e.g., for capabilities/read params)
  * @returns Headers to include in the request
  */
-export type InvokeFunction = (session: ServiceSession, service: string, path: string, action: string, facts?: InvocationFacts) => ServiceHeaders;
+type InvokeFunction = (session: ServiceSession, service: string, path: string, action: string, facts?: InvocationFacts) => ServiceHeaders;
 /**
  * Fetch request options - compatible with standard fetch API.
  */
-export interface FetchRequestInit {
+interface FetchRequestInit {
     method?: string;
     headers?: ServiceHeaders;
     body?: Blob | string;
@@ -145,7 +145,7 @@ export interface FetchRequestInit {
 /**
  * Fetch response interface - compatible with standard Response.
  */
-export interface FetchResponse {
+interface FetchResponse {
     ok: boolean;
     status: number;
     statusText: string;
@@ -161,11 +161,11 @@ export interface FetchResponse {
  * Fetch function signature - allows for custom fetch implementations.
  * Compatible with both browser fetch and Node.js fetch.
  */
-export type FetchFunction = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
+type FetchFunction = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
 /**
  * Configuration for automatic retry of failed requests.
  */
-export interface RetryPolicy {
+interface RetryPolicy {
     /** Maximum number of attempts (including initial) */
     maxAttempts: number;
     /** Backoff strategy between retries */
@@ -180,15 +180,15 @@ export interface RetryPolicy {
 /**
  * Default retry policy.
  */
-export declare const defaultRetryPolicy: RetryPolicy;
+declare const defaultRetryPolicy: RetryPolicy;
 /**
  * Event handler function type.
  */
-export type EventHandler = (data: unknown) => void;
+type EventHandler = (data: unknown) => void;
 /**
  * Service interface - base contract for all services.
  */
-export interface IService {
+interface IService {
     /** Initialize service with context */
     initialize(context: IServiceContext): void;
     /** Called when session changes (sign-in, sign-out, refresh) */
@@ -202,7 +202,7 @@ export interface IService {
  * Context provided to services for accessing platform dependencies.
  * The SDK creates this context and passes it to services during initialization.
  */
-export interface IServiceContext {
+interface IServiceContext {
     /** Current active session, or null if not authenticated */
     readonly session: ServiceSession | null;
     /** Whether there is an active authenticated session */
@@ -227,7 +227,7 @@ export interface IServiceContext {
 /**
  * Event emitted before a service request.
  */
-export interface ServiceRequestEvent {
+interface ServiceRequestEvent {
     service: string;
     action: string;
     key?: string;
@@ -236,7 +236,7 @@ export interface ServiceRequestEvent {
 /**
  * Event emitted after a service response.
  */
-export interface ServiceResponseEvent {
+interface ServiceResponseEvent {
     service: string;
     action: string;
     ok: boolean;
@@ -246,14 +246,14 @@ export interface ServiceResponseEvent {
 /**
  * Event emitted on service error.
  */
-export interface ServiceErrorEvent {
+interface ServiceErrorEvent {
     service: string;
     error: ServiceError;
 }
 /**
  * Event emitted on retry attempt.
  */
-export interface ServiceRetryEvent {
+interface ServiceRetryEvent {
     service: string;
     attempt: number;
     maxAttempts: number;
@@ -262,7 +262,7 @@ export interface ServiceRetryEvent {
 /**
  * Telemetry event names.
  */
-export declare const TelemetryEvents: {
+declare const TelemetryEvents: {
     readonly SERVICE_REQUEST: "service.request";
     readonly SERVICE_RESPONSE: "service.response";
     readonly SERVICE_ERROR: "service.error";
@@ -273,16 +273,168 @@ export declare const TelemetryEvents: {
 /**
  * Create a success result.
  */
-export declare function ok<T>(data: T): Result<T>;
+declare function ok<T>(data: T): Result<T>;
 /**
  * Create an error result.
  */
-export declare function err<E = ServiceError>(error: E): Result<never, E>;
+declare function err<E = ServiceError>(error: E): Result<never, E>;
 /**
  * Create a ServiceError.
  */
-export declare function serviceError(code: string, message: string, service: string, options?: {
+declare function serviceError(code: string, message: string, service: string, options?: {
     cause?: Error;
     meta?: Record<string, unknown>;
 }): ServiceError;
-//# sourceMappingURL=types.d.ts.map
+
+/**
+ * BaseService - Abstract base class for all TinyCloud services.
+ *
+ * Provides common functionality:
+ * - Context management
+ * - Session lifecycle hooks
+ * - Abort signal handling
+ * - Telemetry emission
+ */
+
+/**
+ * Abstract base class for TinyCloud services.
+ *
+ * Services extend this class to get common functionality like
+ * context management, session lifecycle, and abort handling.
+ *
+ * @example
+ * ```typescript
+ * class MyService extends BaseService implements IMyService {
+ *   static readonly serviceName = 'myservice';
+ *
+ *   constructor(config: MyServiceConfig = {}) {
+ *     super();
+ *     this._config = config;
+ *   }
+ *
+ *   async doSomething(): Promise<Result<Data>> {
+ *     if (!this.requireAuth()) {
+ *       return err(authRequiredError('myservice'));
+ *     }
+ *     // ... implementation
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseService implements IService {
+    /**
+     * Service identifier used for registration.
+     * Must be overridden by subclasses.
+     */
+    static readonly serviceName: string;
+    /**
+     * Service context providing access to platform dependencies.
+     * Set during initialize().
+     */
+    protected context: IServiceContext;
+    /**
+     * Abort controller for this service's operations.
+     * Reset on sign-out.
+     */
+    protected abortController: AbortController;
+    /**
+     * Service-specific configuration.
+     */
+    protected _config: Record<string, unknown>;
+    /**
+     * Get the service configuration.
+     */
+    get config(): Record<string, unknown>;
+    /**
+     * Initialize the service with context.
+     * Called by the SDK after instantiation.
+     *
+     * @param context - The service context
+     */
+    initialize(context: IServiceContext): void;
+    /**
+     * Called when session changes (sign-in, sign-out, refresh).
+     * Override in subclasses to handle session changes.
+     *
+     * @param session - The new session, or null if signed out
+     */
+    onSessionChange(session: ServiceSession | null): void;
+    /**
+     * Called when SDK signs out.
+     * Aborts all pending operations.
+     */
+    onSignOut(): void;
+    /**
+     * Get the abort signal for this service.
+     * Combines the service-level abort with context-level abort.
+     */
+    protected get abortSignal(): AbortSignal;
+    /**
+     * Check if the service is authenticated.
+     */
+    protected get isAuthenticated(): boolean;
+    /**
+     * Get the current session.
+     * Throws if not authenticated.
+     */
+    protected get session(): ServiceSession;
+    /**
+     * Check authentication and return error result if not authenticated.
+     * Use this at the start of methods that require authentication.
+     *
+     * @returns true if authenticated, false otherwise
+     */
+    protected requireAuth(): boolean;
+    /**
+     * Emit a telemetry event.
+     *
+     * @param event - Event name
+     * @param data - Event data
+     */
+    protected emit(event: string, data: unknown): void;
+    /**
+     * Emit a service request event.
+     *
+     * @param action - The action being performed
+     * @param key - Optional key/path being accessed
+     */
+    protected emitRequest(action: string, key?: string): void;
+    /**
+     * Emit a service response event.
+     *
+     * @param action - The action that was performed
+     * @param ok - Whether the request was successful
+     * @param startTime - Start time for duration calculation
+     * @param status - Optional HTTP status code
+     */
+    protected emitResponse(action: string, ok: boolean, startTime: number, status?: number): void;
+    /**
+     * Emit a service error event.
+     *
+     * @param error - The service error
+     */
+    protected emitError(error: ServiceError): void;
+    /**
+     * Get the service name from the static property.
+     * Subclasses must define static serviceName.
+     */
+    protected getServiceName(): string;
+    /**
+     * Create a combined abort signal from multiple sources.
+     *
+     * @param signals - Additional abort signals to combine
+     * @returns A combined abort signal
+     */
+    protected combineSignals(...signals: (AbortSignal | undefined)[]): AbortSignal;
+    /**
+     * Wrap an operation with error handling and telemetry.
+     *
+     * @param action - The action name for telemetry
+     * @param key - Optional key for telemetry
+     * @param operation - The operation to execute
+     * @returns Result of the operation
+     */
+    protected withTelemetry<T>(action: string, key: string | undefined, operation: () => Promise<Result<T>>): Promise<Result<T>>;
+}
+
+export { BaseService as B, type ErrorCode as E, type FetchFunction as F, type IServiceContext as I, type RetryPolicy as R, type ServiceSession as S, TelemetryEvents as T, type InvokeFunction as a, type IService as b, type ServiceError as c, type Result as d, type StorageQuotaInfo as e, ErrorCodes as f, type EventHandler as g, type FetchRequestInit as h, type FetchResponse as i, type InvocationFact as j, type InvocationFacts as k, type ServiceErrorEvent as l, type ServiceHeaders as m, type ServiceRequestEvent as n, type ServiceResponseEvent as o, type ServiceRetryEvent as p, defaultRetryPolicy as q, err as r, ok as s, serviceError as t };