@tinycloudlabs/sdk-core 1.0.0

package/dist/spaces/SpaceService.d.ts

@@ -0,0 +1,271 @@
+/**
+ * SpaceService - Global singleton for managing spaces (owned and delegated).
+ *
+ * SpaceService provides a unified interface for discovering, creating,
+ * and accessing spaces. It handles both owned spaces (created by the user)
+ * and delegated spaces (shared by other users).
+ *
+ * @packageDocumentation
+ */
+import type { IKVService, Result, ServiceError, ServiceSession, FetchFunction, InvokeFunction } from "@tinycloudlabs/sdk-services";
+import type { SpaceInfo, Delegation, CreateDelegationParams } from "../delegations/types";
+import type { ICapabilityKeyRegistry } from "../authorization/CapabilityKeyRegistry";
+import type { ISharingService } from "../delegations/SharingService";
+import { type ISpace } from "./Space";
+/**
+ * Error codes for SpaceService operations.
+ */
+export declare const SpaceErrorCodes: {
+    /** Space not found */
+    readonly NOT_FOUND: "SPACE_NOT_FOUND";
+    /** Space already exists */
+    readonly ALREADY_EXISTS: "SPACE_ALREADY_EXISTS";
+    /** Creation failed */
+    readonly CREATION_FAILED: "SPACE_CREATION_FAILED";
+    /** Authentication required */
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    /** Invalid space name or URI */
+    readonly INVALID_NAME: "INVALID_SPACE_NAME";
+    /** Network error */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** Not initialized */
+    readonly NOT_INITIALIZED: "NOT_INITIALIZED";
+};
+export type SpaceErrorCode = (typeof SpaceErrorCodes)[keyof typeof SpaceErrorCodes];
+/**
+ * Parameters for creating a space-scoped delegation.
+ * Extends CreateDelegationParams with the spaceId.
+ */
+export interface SpaceDelegationParams extends Omit<CreateDelegationParams, "spaceId"> {
+    /** The space ID to create the delegation for */
+    spaceId: string;
+}
+/**
+ * Function type for creating delegations.
+ * Platform SDKs provide this to handle SIWE-based delegation creation.
+ */
+export type CreateDelegationFunction = (params: SpaceDelegationParams) => Promise<Result<Delegation, ServiceError>>;
+/**
+ * Configuration for SpaceService.
+ */
+export interface SpaceServiceConfig {
+    /** TinyCloud host URLs */
+    hosts: string[];
+    /** Active session for authentication */
+    session: ServiceSession;
+    /** Platform-specific invoke function */
+    invoke: InvokeFunction;
+    /** Optional custom fetch implementation */
+    fetch?: FetchFunction;
+    /** Optional capability key registry for delegated space discovery */
+    capabilityRegistry?: ICapabilityKeyRegistry;
+    /** Factory function to create a space-scoped KV service */
+    createKVService?: (spaceId: string) => IKVService;
+    /** User's PKH DID (derived from address or provided explicitly) */
+    userDid?: string;
+    /** Optional SharingService for v2 sharing links (client-side) */
+    sharingService?: ISharingService;
+    /**
+     * Factory function to create delegations using SIWE-based flow.
+     * Platform SDKs (web-sdk, node-sdk) provide this using their WASM bindings.
+     * Required for space.delegations.create() to work.
+     */
+    createDelegation?: CreateDelegationFunction;
+}
+/**
+ * Interface for SpaceService.
+ */
+export interface ISpaceService {
+    /**
+     * List all spaces the user has access to (owned + delegated).
+     */
+    list(): Promise<Result<SpaceInfo[], ServiceError>>;
+    /**
+     * Create a new space.
+     *
+     * @param name - The name for the new space
+     */
+    create(name: string): Promise<Result<SpaceInfo, ServiceError>>;
+    /**
+     * Get a Space object by name or full URI.
+     *
+     * For owned spaces, use the short name: `sdk.space('default')`
+     * For delegated spaces, use the full URI: `sdk.space('tinycloud:pkh:eip155:1:0x...:photos')`
+     *
+     * @param nameOrUri - Short name or full URI
+     */
+    get(nameOrUri: string): ISpace;
+    /**
+     * Check if a space exists and the user has access.
+     *
+     * @param nameOrUri - Short name or full URI
+     */
+    exists(nameOrUri: string): Promise<Result<boolean, ServiceError>>;
+    /**
+     * Get the current user's primary space ID.
+     */
+    getCurrentSpaceId(): string | undefined;
+    /**
+     * Update the service configuration.
+     */
+    updateConfig(config: Partial<SpaceServiceConfig>): void;
+}
+/**
+ * Parse a space URI to extract components.
+ *
+ * Full URI format: `tinycloud:pkh:eip155:{chainId}:{address}:{name}`
+ * Short name format: `{name}`
+ *
+ * @param uri - The space URI or short name
+ * @returns Parsed components or null if invalid
+ */
+export declare function parseSpaceUri(uri: string): {
+    owner: string;
+    name: string;
+    chainId?: string;
+    address?: string;
+} | null;
+/**
+ * Build a full space URI from components.
+ *
+ * @param owner - Owner DID (did:pkh:eip155:{chainId}:{address})
+ * @param name - Space name
+ * @returns Full space URI
+ */
+export declare function buildSpaceUri(owner: string, name: string): string;
+/**
+ * SpaceService - Global singleton for managing spaces.
+ *
+ * @example
+ * ```typescript
+ * const spaceService = new SpaceService({
+ *   hosts: ['https://node.tinycloud.xyz'],
+ *   session,
+ *   invoke,
+ * });
+ *
+ * // List all accessible spaces
+ * const result = await spaceService.list();
+ * if (result.ok) {
+ *   for (const space of result.data) {
+ *     console.log(`${space.name} (${space.type})`);
+ *   }
+ * }
+ *
+ * // Create a new space
+ * const createResult = await spaceService.create('photos');
+ *
+ * // Get a space object for operations
+ * const space = spaceService.get('photos');
+ * await space.kv.put('album/vacation', { photos: [...] });
+ * ```
+ */
+export declare class SpaceService implements ISpaceService {
+    private hosts;
+    private session;
+    private invoke;
+    private fetchFn;
+    private capabilityRegistry?;
+    private createKVServiceFn?;
+    private _userDid?;
+    private sharingService?;
+    private createDelegationFn?;
+    /** Cache of created Space objects */
+    private spaceCache;
+    /** Cache of space info */
+    private infoCache;
+    /** Cache TTL in milliseconds (5 minutes) */
+    private readonly cacheTTL;
+    /**
+     * Create a new SpaceService instance.
+     *
+     * @param config - Service configuration
+     */
+    constructor(config: SpaceServiceConfig);
+    /**
+     * Update the service configuration.
+     */
+    updateConfig(config: Partial<SpaceServiceConfig>): void;
+    /**
+     * Get the current user's primary space ID.
+     */
+    getCurrentSpaceId(): string | undefined;
+    /**
+     * Get the primary host URL.
+     */
+    private get host();
+    /**
+     * Get the current user's PKH DID.
+     */
+    private get userDid();
+    /**
+     * List all spaces the user has access to.
+     *
+     * Combines owned spaces (from the server) with delegated spaces
+     * (from the capability registry).
+     */
+    list(): Promise<Result<SpaceInfo[], ServiceError>>;
+    /**
+     * List owned spaces from the server.
+     */
+    private listOwnedSpaces;
+    /**
+     * Discover delegated spaces from the capability registry.
+     */
+    private discoverDelegatedSpaces;
+    /**
+     * Extract space name from a full space ID.
+     */
+    private extractNameFromId;
+    /**
+     * Deduplicate spaces, preferring owned over delegated.
+     */
+    private deduplicateSpaces;
+    /**
+     * Create a new space.
+     *
+     * @param name - The name for the new space
+     */
+    create(name: string): Promise<Result<SpaceInfo, ServiceError>>;
+    /**
+     * Get a Space object by name or full URI.
+     *
+     * @param nameOrUri - Short name or full URI
+     */
+    get(nameOrUri: string): ISpace;
+    /**
+     * Resolve a name or URI to a full space ID.
+     */
+    private resolveSpaceId;
+    /**
+     * Check if a space exists and the user has access.
+     */
+    exists(nameOrUri: string): Promise<Result<boolean, ServiceError>>;
+    /**
+     * Get space info from server or cache.
+     */
+    private getSpaceInfo;
+    /**
+     * Create a space-scoped KV service.
+     */
+    private createSpaceScopedKV;
+    /**
+     * Create space-scoped delegation operations.
+     */
+    private createSpaceScopedDelegations;
+    /**
+     * Create space-scoped sharing operations.
+     *
+     * When a SharingService is configured, delegates to client-side v2 sharing.
+     * V2 sharing links are self-contained with embedded private keys - no server tracking.
+     */
+    private createSpaceScopedSharing;
+}
+/**
+ * Create a new SpaceService instance.
+ *
+ * @param config - Service configuration
+ * @returns A new SpaceService instance
+ */
+export declare function createSpaceService(config: SpaceServiceConfig): ISpaceService;
+//# sourceMappingURL=SpaceService.d.ts.map

package/dist/spaces/SpaceService.d.ts.map

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