@tinycloudlabs/sdk-services 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,259 @@
+/**
+ * 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);
+ * }
+ * ```
+ */
+export type Result<T, E = ServiceError> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Service error with structured information.
+ */
+export 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>;
+}
+/**
+ * Standard error codes used across services.
+ */
+export declare const ErrorCodes: {
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    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";
+};
+export 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 {
+    /** 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.
+ */
+export 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 {
+    [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.
+ */
+export 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
+ */
+export type InvokeFunction = (session: ServiceSession, service: string, path: string, action: string, facts?: InvocationFacts) => ServiceHeaders;
+/**
+ * Fetch request options - compatible with standard fetch API.
+ */
+export interface FetchRequestInit {
+    method?: string;
+    headers?: ServiceHeaders;
+    body?: Blob | string;
+    signal?: AbortSignal;
+}
+/**
+ * Fetch response interface - compatible with standard Response.
+ */
+export interface FetchResponse {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/**
+ * 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>;
+/**
+ * Configuration for automatic retry of failed requests.
+ */
+export 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.
+ */
+export declare const defaultRetryPolicy: RetryPolicy;
+/**
+ * Event handler function type.
+ */
+export type EventHandler = (data: unknown) => void;
+/**
+ * Service interface - base contract for all services.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface ServiceRequestEvent {
+    service: string;
+    action: string;
+    key?: string;
+    timestamp: number;
+}
+/**
+ * Event emitted after a service response.
+ */
+export interface ServiceResponseEvent {
+    service: string;
+    action: string;
+    ok: boolean;
+    duration: number;
+    status?: number;
+}
+/**
+ * Event emitted on service error.
+ */
+export interface ServiceErrorEvent {
+    service: string;
+    error: ServiceError;
+}
+/**
+ * Event emitted on retry attempt.
+ */
+export interface ServiceRetryEvent {
+    service: string;
+    attempt: number;
+    maxAttempts: number;
+    error: ServiceError;
+}
+/**
+ * Telemetry event names.
+ */
+export 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.
+ */
+export declare function ok<T>(data: T): Result<T>;
+/**
+ * Create an error result.
+ */
+export declare function err<E = ServiceError>(error: E): Result<never, E>;
+/**
+ * Create a ServiceError.
+ */
+export declare function serviceError(code: string, message: string, service: string, options?: {
+    cause?: Error;
+    meta?: Record<string, unknown>;
+}): ServiceError;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,IAClC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;CAcb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAMrE;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,gBAAgB,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,yBAAyB;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAMD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,EAAE,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,eAAe,KACpB,cAAc,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE;QACP,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;KAClC,CAAC;IACF,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,gBAAgB,KACpB,OAAO,CAAC,aAAa,CAAC,CAAC;AAM5B;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC3C,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAMhC,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAE3C,+DAA+D;IAC/D,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC;IAEtD,kEAAkE;IAClE,SAAS,IAAI,IAAI,CAAC;IAElB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAE9B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAGlC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAGzB,6CAA6C;IAC7C,UAAU,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAG5D,6BAA6B;IAC7B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,0BAA0B;IAC1B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAAC;IAGrD,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAGlC,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAMX;;GAEG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAExC;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEhE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC1D,YAAY,CAQd"}

package/dist/types.js

@@ -0,0 +1,72 @@
+/**
+ * SDK Services - Core Types
+ *
+ * These types define the service architecture for TinyCloud SDK.
+ * Services use dependency injection via IServiceContext for platform independence.
+ */
+/**
+ * Standard error codes used across services.
+ */
+export const ErrorCodes = {
+    // Common errors
+    NOT_FOUND: "NOT_FOUND",
+    AUTH_EXPIRED: "AUTH_EXPIRED",
+    AUTH_REQUIRED: "AUTH_REQUIRED",
+    NETWORK_ERROR: "NETWORK_ERROR",
+    TIMEOUT: "TIMEOUT",
+    ABORTED: "ABORTED",
+    INVALID_INPUT: "INVALID_INPUT",
+    PERMISSION_DENIED: "PERMISSION_DENIED",
+    // KV-specific errors
+    KV_NOT_FOUND: "KV_NOT_FOUND",
+    KV_WRITE_FAILED: "KV_WRITE_FAILED",
+};
+/**
+ * Default retry policy.
+ */
+export const defaultRetryPolicy = {
+    maxAttempts: 3,
+    backoff: "exponential",
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+    retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT],
+};
+/**
+ * Telemetry event names.
+ */
+export const TelemetryEvents = {
+    SERVICE_REQUEST: "service.request",
+    SERVICE_RESPONSE: "service.response",
+    SERVICE_ERROR: "service.error",
+    SERVICE_RETRY: "service.retry",
+    SESSION_CHANGED: "session.changed",
+    SESSION_EXPIRED: "session.expired",
+};
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Create a success result.
+ */
+export function ok(data) {
+    return { ok: true, data };
+}
+/**
+ * Create an error result.
+ */
+export function err(error) {
+    return { ok: false, error };
+}
+/**
+ * Create a ServiceError.
+ */
+export function serviceError(code, message, service, options) {
+    return {
+        code,
+        message,
+        service,
+        cause: options?.cause,
+        meta: options?.meta,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2CH;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,gBAAgB;IAChB,SAAS,EAAE,WAAW;IACtB,YAAY,EAAE,cAAc;IAC5B,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,aAAa,EAAE,eAAe;IAC9B,iBAAiB,EAAE,mBAAmB;IAEtC,qBAAqB;IACrB,YAAY,EAAE,cAAc;IAC5B,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAyHX;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAgB;IAC7C,WAAW,EAAE,CAAC;IACd,OAAO,EAAE,aAAa;IACtB,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,KAAK;IACjB,eAAe,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,UAAU,CAAC,OAAO,CAAC;CAChE,CAAC;AA6GF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,eAAe,EAAE,iBAAiB;IAClC,gBAAgB,EAAE,kBAAkB;IACpC,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,iBAAiB;IAClC,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAEX,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,EAAE,CAAI,IAAO;IAC3B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG,CAAmB,KAAQ;IAC5C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,OAAe,EACf,OAAe,EACf,OAA2D;IAE3D,OAAO;QACL,IAAI;QACJ,OAAO;QACP,OAAO;QACP,KAAK,EAAE,OAAO,EAAE,KAAK;QACrB,IAAI,EAAE,OAAO,EAAE,IAAI;KACpB,CAAC;AACJ,CAAC"}