@rool-dev/sdk 0.2.0-dev.f798776 → 0.3.0-dev.be25932

package/dist/channel.d.ts

@@ -0,0 +1,316 @@
+import { EventEmitter } from './event-emitter.js';
+import type { GraphQLClient } from './graphql.js';
+import type { MediaClient } from './media.js';
+import type { AuthManager } from './auth.js';
+import type { Logger } from './logger.js';
+import type { RoolObject, RoolObjectStat, ChannelEvents, RoolUserRole, PromptOptions, FindObjectsOptions, CreateObjectOptions, UpdateObjectOptions, MediaInfo, MediaResponse, Interaction, Channel, LinkAccess, SpaceSchema, CollectionDef, FieldDef } from './types.js';
+export declare function generateEntityId(): string;
+export interface ChannelConfig {
+    id: string;
+    name: string;
+    role: RoolUserRole;
+    linkAccess: LinkAccess;
+    /** Current user's ID (for identifying own interactions) */
+    userId: string;
+    /** Object IDs in the space (sorted by modifiedAt desc) */
+    objectIds: string[];
+    /** Object stats keyed by object ID */
+    objectStats: Record<string, RoolObjectStat>;
+    /** Collection schema */
+    schema: SpaceSchema;
+    /** Space metadata */
+    meta: Record<string, unknown>;
+    /** This channel's conversation data (undefined if new) */
+    channel: Channel | undefined;
+    /** Channel ID for this channel (required). */
+    channelId: string;
+    graphqlClient: GraphQLClient;
+    mediaClient: MediaClient;
+    graphqlUrl: string;
+    authManager: AuthManager;
+    logger: Logger;
+    onClose: (spaceId: string) => void;
+}
+/**
+ * A channel is a space + channelId pair.
+ *
+ * All object operations go through a channel. The channelId is fixed
+ * at open time and cannot be changed. To use a different channel,
+ * open a second one.
+ *
+ * Objects are fetched on demand from the server; only schema, metadata,
+ * and the channel's own conversation are cached locally. Object changes
+ * arrive via SSE semantic events and are emitted as SDK events.
+ *
+ * Features:
+ * - High-level object operations
+ * - Built-in undo/redo with checkpoints
+ * - Metadata management
+ * - Event emission for state changes
+ * - Real-time updates via space-specific subscription
+ */
+export declare class RoolChannel extends EventEmitter<ChannelEvents> {
+    private _id;
+    private _name;
+    private _role;
+    private _linkAccess;
+    private _userId;
+    private _channelId;
+    private _closed;
+    private graphqlClient;
+    private mediaClient;
+    private subscriptionManager;
+    private onCloseCallback;
+    private _subscriptionReady;
+    private logger;
+    private _meta;
+    private _schema;
+    private _conversation;
+    private _objectIds;
+    private _objectStats;
+    private _pendingMutations;
+    private _objectResolvers;
+    private _objectBuffer;
+    constructor(config: ChannelConfig);
+    /**
+     * Wait for the real-time subscription to be established.
+     * Called internally by openChannel/createSpace before returning the channel.
+     * @internal
+     */
+    _waitForSubscription(): Promise<void>;
+    get id(): string;
+    get name(): string;
+    get role(): RoolUserRole;
+    get linkAccess(): LinkAccess;
+    /** Current user's ID (for identifying own interactions) */
+    get userId(): string;
+    /**
+     * Get the channel ID for this channel.
+     * Fixed at open time — cannot be changed.
+     */
+    get channelId(): string;
+    get isReadOnly(): boolean;
+    /**
+     * Get interactions for this channel's conversation.
+     */
+    getInteractions(): Interaction[];
+    /**
+     * Close this channel and clean up resources.
+     * Stops real-time subscription and unregisters from client.
+     */
+    close(): void;
+    /**
+     * Create a checkpoint (seal current batch of changes).
+     * @returns The checkpoint ID
+     */
+    checkpoint(label?: string): Promise<string>;
+    /**
+     * Check if undo is available.
+     */
+    canUndo(): Promise<boolean>;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(): Promise<boolean>;
+    /**
+     * Undo the most recent batch of changes.
+     * Reverses your most recent batch (sealed or open).
+     * Conflicting patches (modified by others) are silently skipped.
+     * @returns true if undo was performed
+     */
+    undo(): Promise<boolean>;
+    /**
+     * Redo a previously undone batch of changes.
+     * @returns true if redo was performed
+     */
+    redo(): Promise<boolean>;
+    /**
+     * Clear checkpoint history for this conversation.
+     */
+    clearHistory(): Promise<void>;
+    /**
+     * Get an object's data by ID.
+     * Fetches from the server on each call.
+     */
+    getObject(objectId: string): Promise<RoolObject | undefined>;
+    /**
+     * Get an object's stat (audit information).
+     * Returns modification timestamp and author, or undefined if object not found.
+     */
+    stat(objectId: string): RoolObjectStat | undefined;
+    /**
+     * Find objects using structured filters and/or natural language.
+     *
+     * `where` provides exact-match filtering — values must match literally (no placeholders or operators).
+     * `prompt` enables AI-powered semantic queries. When both are provided, `where` and `objectIds`
+     * constrain the data set before the AI sees it.
+     *
+     * @param options.where - Exact-match field filter (e.g. `{ type: 'article' }`). Constrains which objects the AI can see when combined with `prompt`.
+     * @param options.prompt - Natural language query. Triggers AI evaluation (uses credits).
+     * @param options.limit - Maximum number of results to return (applies to structured filtering only; the AI controls its own result size).
+     * @param options.objectIds - Scope search to specific object IDs. Constrains the candidate set in both structured and AI queries.
+     * @param options.order - Sort order by modifiedAt: `'asc'` or `'desc'` (default: `'desc'`). Only applies to structured filtering (no `prompt`).
+     * @param options.ephemeral - If true, the query won't be recorded in conversation history.
+     * @returns The matching objects and a descriptive message.
+     */
+    findObjects(options: FindObjectsOptions): Promise<{
+        objects: RoolObject[];
+        message: string;
+    }>;
+    /**
+     * Get all object IDs (sync, from local cache).
+     * The list is loaded on open and kept current via SSE events.
+     * @param options.limit - Maximum number of IDs to return
+     * @param options.order - Sort order by modifiedAt ('asc' or 'desc', default: 'desc')
+     */
+    getObjectIds(options?: {
+        limit?: number;
+        order?: 'asc' | 'desc';
+    }): string[];
+    /**
+     * Create a new object with optional AI generation.
+     * @param options.data - Object data fields (any key-value pairs). Optionally include `id` to use a custom ID. Use {{placeholder}} for AI-generated content. Fields prefixed with _ are hidden from AI.
+     * @param options.ephemeral - If true, the operation won't be recorded in conversation history.
+     * @returns The created object (with AI-filled content) and message
+     */
+    createObject(options: CreateObjectOptions): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
+    /**
+     * Update an existing object.
+     * @param objectId - The ID of the object to update
+     * @param options.data - Fields to add or update. Pass null or undefined to delete a field. Use {{placeholder}} for AI-generated content. Fields prefixed with _ are hidden from AI.
+     * @param options.prompt - AI prompt for content editing (optional).
+     * @param options.ephemeral - If true, the operation won't be recorded in conversation history.
+     * @returns The updated object (with AI-filled content) and message
+     */
+    updateObject(objectId: string, options: UpdateObjectOptions): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
+    /**
+     * Delete objects by IDs.
+     * Other objects that reference deleted objects via data fields will retain stale ref values.
+     */
+    deleteObjects(objectIds: string[]): Promise<void>;
+    /**
+     * Get the current schema for this space.
+     * Returns a map of collection names to their definitions.
+     */
+    getSchema(): SpaceSchema;
+    /**
+     * Create a new collection schema.
+     * @param name - Collection name (must start with a letter, alphanumeric/hyphens/underscores only)
+     * @param fields - Field definitions for the collection
+     * @returns The created CollectionDef
+     */
+    createCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    /**
+     * Alter an existing collection schema, replacing its field definitions.
+     * @param name - Name of the collection to alter
+     * @param fields - New field definitions (replaces all existing fields)
+     * @returns The updated CollectionDef
+     */
+    alterCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    /**
+     * Drop a collection schema.
+     * @param name - Name of the collection to drop
+     */
+    dropCollection(name: string): Promise<void>;
+    /**
+     * Get the system instruction for this channel's conversation.
+     * Returns undefined if no system instruction is set.
+     */
+    getSystemInstruction(): string | undefined;
+    /**
+     * Set the system instruction for this channel's conversation.
+     * Pass null to clear the instruction.
+     */
+    setSystemInstruction(instruction: string | null): Promise<void>;
+    /**
+     * 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.
+     * @returns The message from the AI and the list of objects that were created or modified
+     */
+    prompt(prompt: string, options?: PromptOptions): Promise<{
+        message: string;
+        objects: RoolObject[];
+    }>;
+    /**
+     * Rename this channel (conversation).
+     */
+    rename(newName: string): Promise<void>;
+    /**
+     * List all media files for this space.
+     */
+    listMedia(): Promise<MediaInfo[]>;
+    /**
+     * Upload a file to this space. Returns the URL.
+     */
+    uploadMedia(file: File | Blob | {
+        data: string;
+        contentType: string;
+    }): Promise<string>;
+    /**
+     * Fetch any URL, returning headers and a blob() method (like fetch Response).
+     * Adds auth headers for backend media URLs, fetches external URLs via server proxy if CORS blocks.
+     */
+    fetchMedia(url: string): Promise<MediaResponse>;
+    /**
+     * Delete a media file by URL.
+     */
+    deleteMedia(url: string): Promise<void>;
+    /**
+     * Register a collector that resolves when the object arrives via SSE.
+     * If the object is already in the buffer (arrived before collector), resolves immediately.
+     * @internal
+     */
+    private _collectObject;
+    /**
+     * Cancel a pending object collector (e.g., on mutation error).
+     * @internal
+     */
+    private _cancelCollector;
+    /**
+     * Deliver an object to a pending collector, or buffer it for later collection.
+     * @internal
+     */
+    private _deliverObject;
+    /**
+     * Handle a channel event from the subscription.
+     * @internal
+     */
+    private handleChannelEvent;
+    /**
+     * Handle an object_created SSE event.
+     * Deduplicates against optimistic local creates.
+     * @internal
+     */
+    private _handleObjectCreated;
+    /**
+     * Handle an object_updated SSE event.
+     * Deduplicates against optimistic local updates.
+     * @internal
+     */
+    private _handleObjectUpdated;
+    /**
+     * Handle an object_deleted SSE event.
+     * Deduplicates against optimistic local deletes.
+     * @internal
+     */
+    private _handleObjectDeleted;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

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