@tinycloud/sdk-core 1.0.0

package/dist/TinyCloud.js

@@ -0,0 +1,244 @@
+import { ServiceContext, KVService, } from "@tinycloud/sdk-services";
+/**
+ * TinyCloud SDK - Unified entry point for web and node.
+ *
+ * This class provides the main SDK interface. Platform-specific behavior
+ * is injected through the IUserAuthorization implementation:
+ * - WebUserAuthorization for browser environments
+ * - NodeUserAuthorization for Node.js environments
+ *
+ * @example
+ * ```typescript
+ * // Web usage
+ * import { TinyCloud } from '@tinycloud/sdk-core';
+ * import { WebUserAuthorization } from '@tinycloud/web-sdk';
+ *
+ * const auth = new WebUserAuthorization({ ... });
+ * const tc = new TinyCloud(auth);
+ * await tc.signIn();
+ * const result = await tc.kv.put('key', 'value');
+ *
+ * // Node usage
+ * import { TinyCloud } from '@tinycloud/sdk-core';
+ * import { NodeUserAuthorization, PrivateKeySigner } from '@tinycloud/node-sdk';
+ *
+ * const signer = new PrivateKeySigner(process.env.PRIVATE_KEY);
+ * const auth = new NodeUserAuthorization({
+ *   signStrategy: { type: 'auto-sign' },
+ *   signer,
+ *   domain: 'api.myapp.com'
+ * });
+ * const tc = new TinyCloud(auth);
+ * await tc.signIn();
+ * ```
+ */
+export class TinyCloud {
+    /**
+     * Create a new TinyCloud SDK instance.
+     *
+     * @param userAuthorization - Platform-specific authorization implementation
+     * @param config - Optional SDK configuration
+     */
+    constructor(userAuthorization, config) {
+        /**
+         * Registered extensions.
+         */
+        this.extensions = [];
+        /**
+         * Registered services by name.
+         */
+        this._services = new Map();
+        /**
+         * Whether services have been initialized.
+         */
+        this._servicesInitialized = false;
+        this.userAuthorization = userAuthorization;
+        this.config = config || {};
+    }
+    // === Service Management ===
+    /**
+     * Initialize services with platform dependencies.
+     * Must be called before using services.
+     *
+     * @param invoke - Platform-specific invoke function from WASM binding
+     * @param hosts - TinyCloud host URLs (optional, uses config.hosts)
+     * @param fetchFn - Custom fetch implementation (optional)
+     */
+    initializeServices(invoke, hosts, fetchFn) {
+        const effectiveInvoke = invoke ?? this.config.invoke;
+        const effectiveHosts = hosts ?? this.config.hosts;
+        if (!effectiveInvoke) {
+            throw new Error("invoke function is required to initialize services. " +
+                "Provide it via config.invoke or initializeServices().");
+        }
+        if (!effectiveHosts || effectiveHosts.length === 0) {
+            throw new Error("hosts are required to initialize services. " +
+                "Provide them via config.hosts or initializeServices().");
+        }
+        // Create service context
+        this._serviceContext = new ServiceContext({
+            invoke: effectiveInvoke,
+            fetch: fetchFn ?? this.config.fetch ?? globalThis.fetch.bind(globalThis),
+            hosts: effectiveHosts,
+            retryPolicy: this.config.retryPolicy,
+        });
+        // Register default services (can be overridden via config.services)
+        const serviceConstructors = {
+            kv: KVService,
+            ...this.config.services,
+        };
+        // Create and register services
+        for (const [name, ServiceClass] of Object.entries(serviceConstructors)) {
+            const serviceConfig = this.config.serviceConfigs?.[name] ?? {};
+            const service = new ServiceClass(serviceConfig);
+            service.initialize(this._serviceContext);
+            this._serviceContext.registerService(name, service);
+            this._services.set(name, service);
+        }
+        this._servicesInitialized = true;
+    }
+    /**
+     * Get the service context.
+     * @throws Error if services are not initialized
+     */
+    get serviceContext() {
+        if (!this._serviceContext) {
+            throw new Error("Services not initialized. Call initializeServices() first.");
+        }
+        return this._serviceContext;
+    }
+    /**
+     * Get a registered service by name.
+     *
+     * @param name - Service name (e.g., 'kv')
+     * @returns The service instance or undefined
+     */
+    getService(name) {
+        return this._services.get(name);
+    }
+    /**
+     * Get the KV service.
+     * @throws Error if services are not initialized
+     */
+    get kv() {
+        if (!this._servicesInitialized) {
+            throw new Error("Services not initialized. Call initializeServices() first, " +
+                "or use TinyCloudWeb/TinyCloudNode which handles this automatically.");
+        }
+        const service = this._services.get("kv");
+        if (!service) {
+            throw new Error("KV service is not registered.");
+        }
+        return service;
+    }
+    /**
+     * Notify services of session change.
+     * Called internally after sign-in and sign-out.
+     *
+     * @param session - The new session, or null if signed out
+     */
+    notifyServicesOfSessionChange(session) {
+        if (this._serviceContext) {
+            this._serviceContext.setSession(session);
+        }
+    }
+    /**
+     * Abort all pending service operations.
+     * Called internally before sign-out.
+     */
+    abortServiceOperations() {
+        if (this._serviceContext) {
+            this._serviceContext.abort();
+        }
+    }
+    /**
+     * Convert ClientSession to ServiceSession.
+     * Returns null if session lacks required fields.
+     */
+    toServiceSession(clientSession) {
+        if (!clientSession)
+            return null;
+        // TinyCloudSession contains the required fields
+        const tcSession = clientSession.tinycloudSession;
+        if (!tcSession)
+            return null;
+        return {
+            delegationHeader: tcSession.delegationHeader,
+            delegationCid: tcSession.delegationCid,
+            spaceId: tcSession.spaceId,
+            verificationMethod: tcSession.verificationMethod,
+            jwk: tcSession.jwk,
+        };
+    }
+    /**
+     * Add an extension to the SDK.
+     * Extensions can add capabilities and lifecycle hooks.
+     */
+    extend(extension) {
+        this.extensions.push(extension);
+        this.userAuthorization.extend(extension);
+    }
+    /**
+     * Check if an extension is enabled.
+     * @param namespace - The extension namespace to check
+     */
+    isExtensionEnabled(namespace) {
+        return this.extensions.some((ext) => ext.namespace === namespace);
+    }
+    // === Authentication Methods (delegate to userAuthorization) ===
+    /**
+     * Get the current session, if signed in.
+     */
+    get session() {
+        return this.userAuthorization.session;
+    }
+    /**
+     * Check if the user is signed in.
+     */
+    get isSignedIn() {
+        return !!this.userAuthorization.session;
+    }
+    /**
+     * Sign in and create a new session.
+     * Notifies services of the new session after successful sign-in.
+     * @returns The new session
+     */
+    async signIn() {
+        const session = await this.userAuthorization.signIn();
+        // Notify services of the new session
+        const serviceSession = this.toServiceSession(session);
+        this.notifyServicesOfSessionChange(serviceSession);
+        return session;
+    }
+    /**
+     * Sign out and clear the current session.
+     * Aborts pending service operations and notifies services.
+     */
+    async signOut() {
+        // Abort all pending operations before sign-out
+        this.abortServiceOperations();
+        await this.userAuthorization.signOut();
+        // Clear session from services
+        this.notifyServicesOfSessionChange(null);
+    }
+    /**
+     * Get the current wallet address.
+     */
+    address() {
+        return this.userAuthorization.address();
+    }
+    /**
+     * Get the current chain ID.
+     */
+    chainId() {
+        return this.userAuthorization.chainId();
+    }
+    /**
+     * Sign a message with the connected wallet.
+     * @param message - Message to sign
+     */
+    async signMessage(message) {
+        return this.userAuthorization.signMessage(message);
+    }
+}
+//# sourceMappingURL=TinyCloud.js.map

package/dist/TinyCloud.js.map

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

package/dist/TinyCloud.schema.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Zod schemas for TinyCloud SDK configuration types.
+ *
+ * These schemas provide runtime validation for TinyCloud configuration.
+ * Types are derived from schemas using z.infer<>.
+ *
+ * @packageDocumentation
+ */
+import { z } from "zod";
+import type { Result } from "./delegations/types.schema";
+import type { ValidationError } from "./storage.schema";
+import type { InvokeFunction, FetchFunction, ServiceConstructor } from "@tinycloud/sdk-services";
+/**
+ * Schema for backoff strategy.
+ */
+export declare const BackoffStrategySchema: z.ZodEnum<["none", "linear", "exponential"]>;
+export type BackoffStrategy = z.infer<typeof BackoffStrategySchema>;
+/**
+ * Schema for retry policy configuration.
+ */
+export declare const RetryPolicySchema: z.ZodObject<{
+    /** Maximum number of attempts (including initial) */
+    maxAttempts: z.ZodNumber;
+    /** Backoff strategy between retries */
+    backoff: z.ZodEnum<["none", "linear", "exponential"]>;
+    /** Base delay in milliseconds for backoff calculation */
+    baseDelayMs: z.ZodNumber;
+    /** Maximum delay in milliseconds between retries */
+    maxDelayMs: z.ZodNumber;
+    /** Error codes that should trigger a retry */
+    retryableErrors: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    maxAttempts: number;
+    backoff: "none" | "linear" | "exponential";
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableErrors: string[];
+}, {
+    maxAttempts: number;
+    backoff: "none" | "linear" | "exponential";
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableErrors: string[];
+}>;
+export type RetryPolicy = z.infer<typeof RetryPolicySchema>;
+/**
+ * Schema for partial retry policy (all fields optional).
+ */
+export declare const PartialRetryPolicySchema: z.ZodObject<{
+    maxAttempts: z.ZodOptional<z.ZodNumber>;
+    backoff: z.ZodOptional<z.ZodEnum<["none", "linear", "exponential"]>>;
+    baseDelayMs: z.ZodOptional<z.ZodNumber>;
+    maxDelayMs: z.ZodOptional<z.ZodNumber>;
+    retryableErrors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    maxAttempts?: number | undefined;
+    backoff?: "none" | "linear" | "exponential" | undefined;
+    baseDelayMs?: number | undefined;
+    maxDelayMs?: number | undefined;
+    retryableErrors?: string[] | undefined;
+}, {
+    maxAttempts?: number | undefined;
+    backoff?: "none" | "linear" | "exponential" | undefined;
+    baseDelayMs?: number | undefined;
+    maxDelayMs?: number | undefined;
+    retryableErrors?: string[] | undefined;
+}>;
+export type PartialRetryPolicy = z.infer<typeof PartialRetryPolicySchema>;
+/**
+ * Schema for TinyCloud SDK configuration.
+ */
+export declare const TinyCloudConfigSchema: z.ZodObject<{
+    /** Whether to automatically resolve ENS names */
+    resolveEns: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * TinyCloud host URLs.
+     * Required when using services.
+     */
+    hosts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Platform-specific invoke function from WASM binding.
+     * Required when using services.
+     */
+    invoke: z.ZodOptional<z.ZodEffects<z.ZodUnknown, InvokeFunction, unknown>>;
+    /**
+     * Custom fetch implementation.
+     * Defaults to globalThis.fetch.
+     */
+    fetch: z.ZodOptional<z.ZodEffects<z.ZodUnknown, FetchFunction, unknown>>;
+    /**
+     * Service constructors to register.
+     * Built-in services (like KVService) are registered by default unless overridden.
+     */
+    services: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodUnknown, ServiceConstructor<Record<string, unknown>, import("@tinycloud/sdk-services").IService>, unknown>>>;
+    /**
+     * Per-service configuration.
+     */
+    serviceConfigs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    /**
+     * Retry policy for service operations.
+     */
+    retryPolicy: z.ZodOptional<z.ZodObject<{
+        maxAttempts: z.ZodOptional<z.ZodNumber>;
+        backoff: z.ZodOptional<z.ZodEnum<["none", "linear", "exponential"]>>;
+        baseDelayMs: z.ZodOptional<z.ZodNumber>;
+        maxDelayMs: z.ZodOptional<z.ZodNumber>;
+        retryableErrors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        maxAttempts?: number | undefined;
+        backoff?: "none" | "linear" | "exponential" | undefined;
+        baseDelayMs?: number | undefined;
+        maxDelayMs?: number | undefined;
+        retryableErrors?: string[] | undefined;
+    }, {
+        maxAttempts?: number | undefined;
+        backoff?: "none" | "linear" | "exponential" | undefined;
+        baseDelayMs?: number | undefined;
+        maxDelayMs?: number | undefined;
+        retryableErrors?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    hosts?: string[] | undefined;
+    invoke?: InvokeFunction | undefined;
+    fetch?: FetchFunction | undefined;
+    resolveEns?: boolean | undefined;
+    services?: Record<string, ServiceConstructor<Record<string, unknown>, import("@tinycloud/sdk-services").IService>> | undefined;
+    serviceConfigs?: Record<string, Record<string, unknown>> | undefined;
+    retryPolicy?: {
+        maxAttempts?: number | undefined;
+        backoff?: "none" | "linear" | "exponential" | undefined;
+        baseDelayMs?: number | undefined;
+        maxDelayMs?: number | undefined;
+        retryableErrors?: string[] | undefined;
+    } | undefined;
+}, {
+    hosts?: string[] | undefined;
+    invoke?: unknown;
+    fetch?: unknown;
+    resolveEns?: boolean | undefined;
+    services?: Record<string, unknown> | undefined;
+    serviceConfigs?: Record<string, Record<string, unknown>> | undefined;
+    retryPolicy?: {
+        maxAttempts?: number | undefined;
+        backoff?: "none" | "linear" | "exponential" | undefined;
+        baseDelayMs?: number | undefined;
+        maxDelayMs?: number | undefined;
+        retryableErrors?: string[] | undefined;
+    } | undefined;
+}>;
+export type TinyCloudConfig = z.infer<typeof TinyCloudConfigSchema>;
+/**
+ * Validates a TinyCloudConfig object and returns a Result.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ *
+ * @example
+ * ```typescript
+ * const result = validateTinyCloudConfig(rawConfig);
+ * if (result.ok) {
+ *   // result.data is typed as TinyCloudConfig
+ *   console.log(result.data.hosts);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export declare function validateTinyCloudConfig(data: unknown): Result<TinyCloudConfig, ValidationError>;
+/**
+ * Validates a RetryPolicy object and returns a Result.
+ */
+export declare function validateRetryPolicy(data: unknown): Result<RetryPolicy, ValidationError>;
+//# sourceMappingURL=TinyCloud.schema.d.ts.map

package/dist/TinyCloud.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyCloud.schema.d.ts","sourceRoot":"","sources":["../src/TinyCloud.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAMjC;;GAEG;AACH,eAAO,MAAM,qBAAqB,8CAA4C,CAAC;AAC/E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,qDAAqD;;IAErD,uCAAuC;;IAEvC,yDAAyD;;IAEzD,oDAAoD;;IAEpD,8CAA8C;;;;;;;;;;;;;;EAE9C,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;EAA8B,CAAC;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM1E;;GAEG;AACH,eAAO,MAAM,qBAAqB;IAChC,iDAAiD;;IAKjD;;;OAGG;;IAGH;;;OAGG;;IAUH;;;OAGG;;IAUH;;;OAGG;;IAWH;;OAEG;;IAGH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAc1C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,WAAW,EAAE,eAAe,CAAC,CActC"}

package/dist/TinyCloud.schema.js

@@ -0,0 +1,136 @@
+/**
+ * Zod schemas for TinyCloud SDK configuration types.
+ *
+ * These schemas provide runtime validation for TinyCloud configuration.
+ * Types are derived from schemas using z.infer<>.
+ *
+ * @packageDocumentation
+ */
+import { z } from "zod";
+// =============================================================================
+// Retry Policy Schema
+// =============================================================================
+/**
+ * Schema for backoff strategy.
+ */
+export const BackoffStrategySchema = z.enum(["none", "linear", "exponential"]);
+/**
+ * Schema for retry policy configuration.
+ */
+export const RetryPolicySchema = z.object({
+    /** Maximum number of attempts (including initial) */
+    maxAttempts: z.number().int().positive(),
+    /** Backoff strategy between retries */
+    backoff: BackoffStrategySchema,
+    /** Base delay in milliseconds for backoff calculation */
+    baseDelayMs: z.number().int().nonnegative(),
+    /** Maximum delay in milliseconds between retries */
+    maxDelayMs: z.number().int().nonnegative(),
+    /** Error codes that should trigger a retry */
+    retryableErrors: z.array(z.string()),
+});
+/**
+ * Schema for partial retry policy (all fields optional).
+ */
+export const PartialRetryPolicySchema = RetryPolicySchema.partial();
+// =============================================================================
+// TinyCloud Config Schema
+// =============================================================================
+/**
+ * Schema for TinyCloud SDK configuration.
+ */
+export const TinyCloudConfigSchema = z.object({
+    /** Whether to automatically resolve ENS names */
+    resolveEns: z.boolean().optional(),
+    // === Service Configuration ===
+    /**
+     * TinyCloud host URLs.
+     * Required when using services.
+     */
+    hosts: z.array(z.string()).optional(),
+    /**
+     * Platform-specific invoke function from WASM binding.
+     * Required when using services.
+     */
+    invoke: z
+        .unknown()
+        .refine((val) => val === undefined || typeof val === "function", { message: "Expected an invoke function or undefined" })
+        .optional(),
+    /**
+     * Custom fetch implementation.
+     * Defaults to globalThis.fetch.
+     */
+    fetch: z
+        .unknown()
+        .refine((val) => val === undefined || typeof val === "function", { message: "Expected a fetch function or undefined" })
+        .optional(),
+    /**
+     * Service constructors to register.
+     * Built-in services (like KVService) are registered by default unless overridden.
+     */
+    services: z
+        .record(z.string(), z.unknown().refine((val) => typeof val === "function", { message: "Expected a service constructor" }))
+        .optional(),
+    /**
+     * Per-service configuration.
+     */
+    serviceConfigs: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+    /**
+     * Retry policy for service operations.
+     */
+    retryPolicy: PartialRetryPolicySchema.optional(),
+});
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+/**
+ * Validates a TinyCloudConfig object and returns a Result.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ *
+ * @example
+ * ```typescript
+ * const result = validateTinyCloudConfig(rawConfig);
+ * if (result.ok) {
+ *   // result.data is typed as TinyCloudConfig
+ *   console.log(result.data.hosts);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export function validateTinyCloudConfig(data) {
+    const result = TinyCloudConfigSchema.safeParse(data);
+    if (!result.success) {
+        return {
+            ok: false,
+            error: {
+                code: "VALIDATION_ERROR",
+                message: result.error.message,
+                service: "tinycloud",
+                meta: { issues: result.error.issues },
+            },
+        };
+    }
+    return { ok: true, data: result.data };
+}
+/**
+ * Validates a RetryPolicy object and returns a Result.
+ */
+export function validateRetryPolicy(data) {
+    const result = RetryPolicySchema.safeParse(data);
+    if (!result.success) {
+        return {
+            ok: false,
+            error: {
+                code: "VALIDATION_ERROR",
+                message: result.error.message,
+                service: "tinycloud",
+                meta: { issues: result.error.issues },
+            },
+        };
+    }
+    return { ok: true, data: result.data };
+}
+//# sourceMappingURL=TinyCloud.schema.js.map

package/dist/TinyCloud.schema.js.map

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

package/dist/TinyCloud.schema.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for TinyCloud configuration schemas.
+ */
+export {};
+//# sourceMappingURL=TinyCloud.schema.test.d.ts.map

package/dist/TinyCloud.schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyCloud.schema.test.d.ts","sourceRoot":"","sources":["../src/TinyCloud.schema.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}