@rool-dev/client 0.3.1 → 0.4.0-dev.22f8ef0

package/dist/space.d.ts

@@ -0,0 +1,256 @@
+import { EventEmitter } from './event-emitter.js';
+import type { GraphQLClient } from './graphql.js';
+import type { MediaClient } from './media.js';
+import type { RoolSpaceData, RoolObject, JSONPatchOp, SpaceEvents, RoolUserRole, RoolUser, PromptOptions, MediaItem } from './types.js';
+export declare function generateEntityId(): string;
+interface SpaceConfig {
+    id: string;
+    name: string;
+    role: RoolUserRole;
+    initialData: RoolSpaceData;
+    graphqlClient: GraphQLClient;
+    mediaClient: MediaClient;
+    onRegisterForEvents: (spaceId: string, space: RoolSpace) => void;
+    onUnregisterFromEvents: (spaceId: string) => void;
+}
+/**
+ * First-class Space object.
+ *
+ * Features:
+ * - High-level object/link operations
+ * - Built-in undo/redo with checkpoints
+ * - Metadata management
+ * - Event emission for state changes
+ * - Real-time subscription support
+ */
+export declare class RoolSpace extends EventEmitter<SpaceEvents> {
+    private _id;
+    private _name;
+    private _role;
+    private _data;
+    private graphqlClient;
+    private mediaClient;
+    private onRegisterForEvents;
+    private onUnregisterFromEvents;
+    private undoStack;
+    private redoStack;
+    private _isSubscribed;
+    constructor(config: SpaceConfig);
+    get id(): string;
+    get name(): string;
+    get role(): RoolUserRole;
+    get isReadOnly(): boolean;
+    get isSubscribed(): boolean;
+    /**
+     * Rename this space.
+     */
+    rename(newName: string): Promise<void>;
+    /**
+     * Subscribe to real-time updates for this space.
+     * Registers with the client for event routing.
+     */
+    subscribe(): void;
+    /**
+     * Unsubscribe from real-time updates.
+     */
+    unsubscribe(): void;
+    /**
+     * Close this space and clean up resources.
+     */
+    close(): void;
+    /**
+     * Create a checkpoint for undo.
+     * Call this before a user action to capture the current state.
+     */
+    checkpoint(label?: string): void;
+    /**
+     * Check if undo is available.
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(): boolean;
+    /**
+     * Undo to the previous checkpoint.
+     * @returns true if undo was performed
+     */
+    undo(): Promise<boolean>;
+    /**
+     * Redo a previously undone action.
+     * @returns true if redo was performed
+     */
+    redo(): Promise<boolean>;
+    /**
+     * Clear undo/redo history.
+     * Called when external changes invalidate local history.
+     */
+    clearHistory(): void;
+    /**
+     * Get an object's data by ID.
+     * Returns just the data portion (RoolObject), not the full entry with meta/links.
+     * @throws Error if object not found
+     */
+    getObject(objectId: string): RoolObject;
+    /**
+     * Get an object's data by ID, or undefined if not found.
+     */
+    getObjectOrUndefined(objectId: string): RoolObject | undefined;
+    /**
+     * Get an object's metadata (position, UI state, etc).
+     */
+    getObjectMeta(objectId: string): Record<string, unknown>;
+    /**
+     * Query objects by field values.
+     * Returns all objects where all specified fields match the given values.
+     *
+     * @example
+     * space.queryObjects({ type: 'article' })
+     * space.queryObjects({ type: 'task', status: 'done' })
+     */
+    queryObjects(where: Record<string, unknown>): RoolObject[];
+    /**
+     * Get all object IDs.
+     */
+    getObjectIds(): string[];
+    /**
+     * Create a new object with optional AI generation.
+     * @param options.data - Object data fields (any key-value pairs). Use {{placeholder}} for AI-generated content.
+     * @param options.meta - Client-private metadata (optional). Hidden from AI operations.
+     * @param options.prompt - AI prompt for content generation (optional).
+     * @returns The generated object ID
+     */
+    createObject(options: {
+        data: Record<string, unknown>;
+        meta?: Record<string, unknown>;
+        prompt?: string;
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+    /**
+     * Update an existing object.
+     * @param objectId - The ID of the object to update
+     * @param options.data - Fields to add or update. Use {{placeholder}} for AI-generated content.
+     * @param options.meta - Client-private metadata to merge. Hidden from AI operations.
+     * @param options.prompt - AI prompt for content editing (optional).
+     */
+    updateObject(objectId: string, options: {
+        data?: Record<string, unknown>;
+        meta?: Record<string, unknown>;
+        prompt?: string;
+    }): Promise<string>;
+    /**
+     * Delete objects by IDs.
+     * Outbound links are automatically deleted with the object.
+     * Inbound links become orphans (tolerated).
+     */
+    deleteObjects(objectIds: string[]): Promise<void>;
+    /**
+     * Create a link between objects.
+     * Links are stored on the source object.
+     */
+    link(sourceId: string, targetId: string, linkType: string): Promise<void>;
+    /**
+     * Remove a link between two objects.
+     * @param linkType - Optional: if provided, only removes that type; otherwise removes all links between the objects
+     * @returns true if any links were removed
+     */
+    unlink(sourceId: string, targetId: string, linkType?: string): Promise<boolean>;
+    /**
+     * Get parent object IDs (objects that have links pointing TO this object).
+     * @param linkType - Optional filter by link type
+     */
+    getParents(objectId: string, linkType?: string): string[];
+    /**
+     * Get child object IDs (objects that this object has links pointing TO).
+     * Filters out orphan targets (targets that don't exist).
+     * @param linkType - Optional filter by link type
+     */
+    getChildren(objectId: string, linkType?: string): string[];
+    /**
+     * Get all child object IDs including orphans (targets that may not exist).
+     * @param linkType - Optional filter by link type
+     */
+    getChildrenIncludingOrphans(objectId: string, linkType?: string): string[];
+    /**
+     * Set a space-level metadata value.
+     * Metadata is stored in meta and hidden from AI operations.
+     */
+    setMetadata(key: string, value: unknown): void;
+    /**
+     * Get a space-level metadata value.
+     */
+    getMetadata(key: string): unknown;
+    /**
+     * Get all space-level metadata.
+     */
+    getAllMetadata(): Record<string, unknown>;
+    /**
+     * Send a prompt to the AI agent for space manipulation.
+     */
+    prompt(prompt: string, options?: PromptOptions): Promise<string | null>;
+    /**
+     * List users with access to this space.
+     */
+    listUsers(): Promise<RoolUser[]>;
+    /**
+     * Add a user to this space with specified role.
+     */
+    addUser(userId: string, role: RoolUserRole): Promise<void>;
+    /**
+     * Remove a user from this space.
+     */
+    removeUser(userId: string): Promise<void>;
+    /**
+     * List all media files for this space.
+     */
+    listMedia(): Promise<MediaItem[]>;
+    /**
+     * Upload a file to this space.
+     */
+    uploadMedia(file: File | Blob | {
+        data: string;
+        contentType: string;
+    }): Promise<MediaItem>;
+    /**
+     * Get the URL for a media file.
+     */
+    getMediaUrl(uuid: string): string;
+    /**
+     * Download a media file as a Blob.
+     */
+    downloadMedia(uuid: string): Promise<Blob>;
+    /**
+     * Delete a media file.
+     */
+    deleteMedia(uuid: string): Promise<void>;
+    /**
+     * Get the full space data.
+     * Use sparingly - prefer specific operations.
+     */
+    getData(): RoolSpaceData;
+    /**
+     * Handle a patch event from another client.
+     * @internal
+     */
+    handleRemotePatch(patch: JSONPatchOp[], source?: 'user' | 'agent'): void;
+    /**
+     * Parse JSON patch operations and emit semantic events.
+     * @internal
+     */
+    private emitSemanticEventsFromPatch;
+    /**
+     * Handle a full reload from server.
+     * @internal
+     */
+    handleRemoteChange(newData: RoolSpaceData): void;
+    /**
+     * Update the name from external source.
+     * @internal
+     */
+    handleRemoteRename(newName: string): void;
+    private resyncFromServer;
+}
+export {};
+//# sourceMappingURL=space.d.ts.map

package/dist/space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space.d.ts","sourceRoot":"","sources":["../src/space.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EAEV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,SAAS,EAEV,MAAM,YAAY,CAAC;AAOpB,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAQD,UAAU,WAAW;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,aAAa,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,mBAAmB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACjE,sBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAU,SAAQ,YAAY,CAAC,WAAW,CAAC;IACtD,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,mBAAmB,CAA8C;IACzE,OAAO,CAAC,sBAAsB,CAA4B;IAG1D,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,SAAS,CAAsB;IAGvC,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,EAAE,WAAW;IAgB/B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,YAAY,CAEvB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAMD;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C;;;OAGG;IACH,SAAS,IAAI,IAAI;IAMjB;;OAEG;IACH,WAAW,IAAI,IAAI;IAMnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAWb;;;OAGG;IACH,UAAU,CAAC,KAAK,GAAE,MAAiB,GAAG,IAAI;IAkB1C;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IA2B9B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IA2B9B;;;OAGG;IACH,YAAY,IAAI,IAAI;IASpB;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAQvC;;OAEG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI9D;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQxD;;;;;;;OAOG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,EAAE;IAQ1D;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;;;;;OAMG;IACG,YAAY,CAAC,OAAO,EAAE;QAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IA0B5C;;;;;;OAMG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GACA,OAAO,CAAC,MAAM,CAAC;IA+BlB;;;;OAIG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDvD;;;OAGG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAyBhB;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0CrF;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAazD;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAkB1D;;;OAGG;IACH,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAiB1E;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAe9C;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQzC;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQ7E;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAItC;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIvC;;OAEG;IACG,WAAW,CACf,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GACxD,OAAO,CAAC,SAAS,CAAC;IAIrB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIjC;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C;;;OAGG;IACH,OAAO,IAAI,aAAa;IAQxB;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,MAAM,GAAE,MAAM,GAAG,OAAgB,GAAG,IAAI;IAehF;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAqEnC;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAKhD;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;YAQ3B,gBAAgB;CAc/B"}