@tinycloud/sdk-services 1.7.0 → 2.0.2-beta.0

package/dist/BaseService-D9BFm_rV.d.ts

@@ -0,0 +1,440 @@
+/**
+ * SDK Services - Core Types
+ *
+ * These types define the service architecture for TinyCloud SDK.
+ * Services use dependency injection via IServiceContext for platform independence.
+ */
+/**
+ * Result type for service operations.
+ * Services return Result instead of throwing, making error handling explicit.
+ *
+ * @template T - The success data type
+ * @template E - The error type (defaults to ServiceError)
+ *
+ * @example
+ * ```typescript
+ * const result = await kv.get('key');
+ * if (result.ok) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.error.code);
+ * }
+ * ```
+ */
+type Result<T, E = ServiceError> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Service error with structured information.
+ */
+interface ServiceError {
+    /** Error code for programmatic handling (e.g., 'KV_NOT_FOUND', 'AUTH_EXPIRED') */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Service that produced the error (e.g., 'kv', 'sql') */
+    service: string;
+    /** Original error if this wraps another error */
+    cause?: Error;
+    /** Additional metadata about the error */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Storage quota information returned with quota-related errors.
+ */
+interface StorageQuotaInfo {
+    usedBytes: number;
+    limitBytes: number;
+    service: string;
+}
+/**
+ * Standard error codes used across services.
+ */
+declare const ErrorCodes: {
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly ABORTED: "ABORTED";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly KV_NOT_FOUND: "KV_NOT_FOUND";
+    readonly KV_WRITE_FAILED: "KV_WRITE_FAILED";
+    readonly SQL_ERROR: "SQL_ERROR";
+    readonly SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED";
+    readonly SQL_DATABASE_NOT_FOUND: "SQL_DATABASE_NOT_FOUND";
+    readonly SQL_RESPONSE_TOO_LARGE: "SQL_RESPONSE_TOO_LARGE";
+    readonly SQL_QUOTA_EXCEEDED: "SQL_QUOTA_EXCEEDED";
+    readonly SQL_INVALID_STATEMENT: "SQL_INVALID_STATEMENT";
+    readonly SQL_SCHEMA_ERROR: "SQL_SCHEMA_ERROR";
+    readonly SQL_READONLY_VIOLATION: "SQL_READONLY_VIOLATION";
+    readonly STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED";
+    readonly STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED";
+    readonly DUCKDB_ERROR: "DUCKDB_ERROR";
+    readonly DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED";
+    readonly DUCKDB_DATABASE_NOT_FOUND: "DUCKDB_DATABASE_NOT_FOUND";
+    readonly DUCKDB_RESPONSE_TOO_LARGE: "DUCKDB_RESPONSE_TOO_LARGE";
+    readonly DUCKDB_QUOTA_EXCEEDED: "DUCKDB_QUOTA_EXCEEDED";
+    readonly DUCKDB_INVALID_STATEMENT: "DUCKDB_INVALID_STATEMENT";
+    readonly DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR";
+    readonly DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION";
+};
+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.
+ */
+interface ServiceSession {
+    /** The delegation header containing the UCAN */
+    delegationHeader: {
+        Authorization: string;
+    };
+    /** The delegation CID */
+    delegationCid: string;
+    /** The space ID for this session */
+    spaceId: string;
+    /** The verification method DID */
+    verificationMethod: string;
+    /** The session key JWK (required for invoke) */
+    jwk: object;
+}
+/**
+ * Headers type - compatible with both browser and Node.js.
+ */
+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.
+ */
+interface InvocationFact {
+    [key: string]: unknown;
+}
+/**
+ * Facts to include in the UCAN invocation.
+ * 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.
+ */
+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.
+ *
+ * @param session - The service session with delegation data
+ * @param service - Service name (e.g., "kv")
+ * @param path - Resource path or key
+ * @param action - Action to perform (e.g., "tinycloud.kv/get")
+ * @param facts - Optional facts to include in the UCAN (e.g., for capabilities/read params)
+ * @returns Headers to include in the request
+ */
+type InvokeFunction = (session: ServiceSession, service: string, path: string, action: string, facts?: InvocationFacts) => ServiceHeaders;
+/**
+ * Fetch request options - compatible with standard fetch API.
+ */
+interface FetchRequestInit {
+    method?: string;
+    headers?: ServiceHeaders;
+    body?: Blob | string;
+    signal?: AbortSignal;
+}
+/**
+ * Fetch response interface - compatible with standard Response.
+ */
+interface FetchResponse {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+}
+/**
+ * Fetch function signature - allows for custom fetch implementations.
+ * Compatible with both browser fetch and Node.js fetch.
+ */
+type FetchFunction = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
+/**
+ * Configuration for automatic retry of failed requests.
+ */
+interface RetryPolicy {
+    /** Maximum number of attempts (including initial) */
+    maxAttempts: number;
+    /** Backoff strategy between retries */
+    backoff: "none" | "linear" | "exponential";
+    /** Base delay in milliseconds for backoff calculation */
+    baseDelayMs: number;
+    /** Maximum delay in milliseconds between retries */
+    maxDelayMs: number;
+    /** Error codes that should trigger a retry */
+    retryableErrors: string[];
+}
+/**
+ * Default retry policy.
+ */
+declare const defaultRetryPolicy: RetryPolicy;
+/**
+ * Event handler function type.
+ */
+type EventHandler = (data: unknown) => void;
+/**
+ * Service interface - base contract for all services.
+ */
+interface IService {
+    /** Initialize service with context */
+    initialize(context: IServiceContext): void;
+    /** Called when session changes (sign-in, sign-out, refresh) */
+    onSessionChange(session: ServiceSession | null): void;
+    /** Called when SDK signs out - should abort pending operations */
+    onSignOut(): void;
+    /** Service-specific configuration */
+    readonly config: Record<string, unknown>;
+}
+/**
+ * Context provided to services for accessing platform dependencies.
+ * The SDK creates this context and passes it to services during initialization.
+ */
+interface IServiceContext {
+    /** Current active session, or null if not authenticated */
+    readonly session: ServiceSession | null;
+    /** Whether there is an active authenticated session */
+    readonly isAuthenticated: boolean;
+    /** Platform-specific invoke function from WASM binding */
+    readonly invoke: InvokeFunction;
+    /** Fetch function (defaults to globalThis.fetch) */
+    readonly fetch: FetchFunction;
+    /** Available TinyCloud host URLs */
+    readonly hosts: string[];
+    /** Get another registered service by name */
+    getService<T extends IService>(name: string): T | undefined;
+    /** Emit a telemetry event */
+    emit(event: string, data: unknown): void;
+    /** Subscribe to events */
+    on(event: string, handler: EventHandler): () => void;
+    /** Abort signal that fires when SDK signs out */
+    readonly abortSignal: AbortSignal;
+    /** Retry policy for failed requests */
+    readonly retryPolicy: RetryPolicy;
+}
+/**
+ * Event emitted before a service request.
+ */
+interface ServiceRequestEvent {
+    service: string;
+    action: string;
+    key?: string;
+    timestamp: number;
+}
+/**
+ * Event emitted after a service response.
+ */
+interface ServiceResponseEvent {
+    service: string;
+    action: string;
+    ok: boolean;
+    duration: number;
+    status?: number;
+}
+/**
+ * Event emitted on service error.
+ */
+interface ServiceErrorEvent {
+    service: string;
+    error: ServiceError;
+}
+/**
+ * Event emitted on retry attempt.
+ */
+interface ServiceRetryEvent {
+    service: string;
+    attempt: number;
+    maxAttempts: number;
+    error: ServiceError;
+}
+/**
+ * Telemetry event names.
+ */
+declare const TelemetryEvents: {
+    readonly SERVICE_REQUEST: "service.request";
+    readonly SERVICE_RESPONSE: "service.response";
+    readonly SERVICE_ERROR: "service.error";
+    readonly SERVICE_RETRY: "service.retry";
+    readonly SESSION_CHANGED: "session.changed";
+    readonly SESSION_EXPIRED: "session.expired";
+};
+/**
+ * Create a success result.
+ */
+declare function ok<T>(data: T): Result<T>;
+/**
+ * Create an error result.
+ */
+declare function err<E = ServiceError>(error: E): Result<never, E>;
+/**
+ * Create a ServiceError.
+ */
+declare function serviceError(code: string, message: string, service: string, options?: {
+    cause?: Error;
+    meta?: Record<string, unknown>;
+}): ServiceError;
+
+/**
+ * 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 };