@promptbook/remote-client/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action

import type { SupabaseClient } from '@supabase/supabase-js';
import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
import type { string_book } from '../../../../book-2.0/agent-source/string_book';
import type { string_agent_name, string_agent_permanent_id } from '../../../../types/string_agent_name';
import type { AgentCollectionInSupabaseOptions } from './AgentCollectionInSupabaseOptions';
import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
import type { CreateAgentPersistenceRecordsOptions } from './createAgentPersistenceRecords';
/**
 * Options for creating a new agent entry.
 */
type CreateAgentOptions = CreateAgentPersistenceRecordsOptions;
/**
 * Optional controls for persisting one source update.
 */
type UpdateAgentSourceOptions = {
    /**
     * Optional human-readable history milestone name saved with the snapshot.
     */
    readonly versionName?: string | null;
};
/**
 * One saved Agent history row without the full source payload.
 */
type AgentHistoryMetadata = {
    readonly id: number;
    readonly createdAt: string;
    readonly agentName: string;
    readonly agentHash: string;
    readonly previousAgentHash: string | null;
    readonly promptbookEngineVersion: string;
    readonly versionName: string | null;
};
/**
 * One saved Agent history row including the full source snapshot.
 */
type AgentHistorySnapshot = AgentHistoryMetadata & {
    readonly agentSource: string;
};
/**
 * Agent collection stored in a Supabase table.
 *
 * This class provides a way to manage a collection of agents (pipelines) using Supabase
 * as the storage backend. It supports listing, creating, updating, and soft-deleting agents.
 *
 * Note: This object can work both from Node.js and browser environment depending on the Supabase client provided.
 *
 * TODO: [🐱‍🚀] Move to `@promptbook/supabase` package
 *
 * @public exported from `@promptbook/core`
 */
export declare class AgentCollectionInSupabase {
    private readonly supabaseClient;
    readonly options?: AgentCollectionInSupabaseOptions | undefined;
    /**
     * @param supabaseClient - The initialized Supabase client
     * @param options - Configuration options for the collection (e.g., table prefix, verbosity)
     */
    constructor(supabaseClient: SupabaseClient<AgentsDatabaseSchema>, options?: AgentCollectionInSupabaseOptions | undefined);
    /**
     * Gets all agents in the collection
     */
    listAgents(): Promise<ReadonlyArray<AgentBasicInformation>>;
    /**
     * Retrieves the permanent ID of an agent by its name or permanent ID.
     */
    getAgentPermanentId(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<string_agent_permanent_id>;
    /**
     * Retrieves the source code of an agent by its name or permanent ID.
     */
    getAgentSource(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<string_book>;
    /**
     * Creates a new agent in the collection
     *
     * Note: You can set 'PARENT' in the agent source to inherit from another agent in the collection.
     *
     * @param agentSource - Source content of the agent.
     * @param options - Optional folder placement and ordering data.
     */
    createAgent(agentSource: string_book, options?: CreateAgentOptions): Promise<AgentBasicInformation & Required<Pick<AgentBasicInformation, 'permanentId'>>>;
    /**
     * Updates an existing agent in the collection
     */
    updateAgentSource(permanentId: string_agent_permanent_id, agentSource: string_book, options?: UpdateAgentSourceOptions): Promise<void>;
    /**
     * List agents that are soft deleted (deletedAt IS NOT NULL)
     */
    listDeletedAgents(): Promise<ReadonlyArray<AgentBasicInformation>>;
    /**
     * List history of an agent
     */
    listAgentHistory(permanentId: string_agent_permanent_id): Promise<ReadonlyArray<AgentHistoryMetadata>>;
    /**
     * List history snapshots of an agent including full source snapshots.
     */
    listAgentHistorySnapshots(permanentId: string_agent_permanent_id): Promise<ReadonlyArray<AgentHistorySnapshot>>;
    /**
     * Restore a soft-deleted agent by setting deletedAt to NULL
     */
    restoreAgent(permanentId: string_agent_permanent_id): Promise<void>;
    /**
     * Restore an agent from a specific history entry
     *
     * This will update the current agent with the source from the history entry
     */
    restoreAgentFromHistory(historyId: number, expectedPermanentId?: string_agent_permanent_id): Promise<void>;
    /**
     * Soft delete an agent by setting deletedAt to current timestamp
     */
    deleteAgent(permanentId: string_agent_permanent_id): Promise<void>;
    /**
     * Get the Supabase table name with prefix
     *
     * @param tableName - The original table name
     * @returns The prefixed table name
     */
    private getTableName;
    /**
     * Persists one agent history row and throws when the insert fails.
     *
     * @param historyRow - Row to insert into `AgentHistory`.
     */
    private insertAgentHistoryRow;
    /**
     * Shared loader for Agent history rows.
     *
     * @param permanentId - Agent permanent identifier.
     * @param includeSource - Whether to include full source snapshots.
     * @returns Agent history rows sorted by creation time descending.
     */
    private listAgentHistoryInternal;
}
export {};