askexperts
Version:
AskExperts SDK: build and use AI experts - ask them questions and pay with bitcoin on an open protocol
187 lines (186 loc) • 6.38 kB
TypeScript
/**
* Document store interfaces
*/
import { AuthRequest } from "../common/auth.js";
/**
* Document interface representing a stored document
*/
export interface Doc {
id: string;
docstore_id: string;
timestamp: number;
created_at: number;
type: string;
data: string;
embeddings: Float32Array[];
user_id?: string;
}
/**
* DocStore metadata
*/
export interface DocStore {
id: string;
name: string;
timestamp: number;
model: string;
vector_size: number;
options: string;
user_id?: string;
}
/**
* Subscription interface for handling document streams
*/
export interface Subscription {
/**
* Terminates the subscription
*/
close(): void;
}
/**
* DocStoreClient interface for interacting with document stores
* All methods are async to support both local and remote implementations
*/
export interface DocStoreClient {
/**
* Subscribe to documents in a docstore
* @param options - Subscription options
* @param options.docstore_id - ID of the docstore to subscribe to
* @param options.type - Optional type of documents to filter by
* @param options.since - Optional start timestamp for filtering documents
* @param options.until - Optional end timestamp for filtering documents
* @param onDoc - Async callback function to handle each document. When called with undefined doc, it signals end of feed (EOF)
* @returns Subscription object to manage the subscription
*/
subscribe(options: {
docstore_id: string;
type?: string;
since?: number;
until?: number;
}, onDoc: (doc?: Doc) => Promise<void>): Promise<Subscription>;
/**
* Upsert a document in the store
* @param doc - Document to upsert
* @returns Promise that resolves when the operation is complete
*/
upsert(doc: Doc): Promise<void>;
/**
* Get a document by ID
* @param docstore_id - ID of the docstore containing the document
* @param doc_id - ID of the document to get
* @returns Promise that resolves with the document if found, null otherwise
*/
get(docstore_id: string, doc_id: string): Promise<Doc | null>;
/**
* Delete a document from the store
* @param docstore_id - ID of the docstore containing the document
* @param doc_id - ID of the document to delete
* @returns Promise that resolves with true if document existed and was deleted, false otherwise
*/
delete(docstore_id: string, doc_id: string): Promise<boolean>;
/**
* Create a new docstore if one with the given name doesn't exist
* @param name - Name of the docstore to create
* @param model - Name of the embeddings model
* @param vector_size - Size of embedding vectors
* @param options - Options for the model, defaults to empty string
* @returns Promise that resolves with the ID of the created or existing docstore
*/
createDocstore(name: string, model?: string, vector_size?: number, options?: string): Promise<string>;
/**
* Get a docstore by ID
* @param id - ID of the docstore to get
* @returns Promise that resolves with the docstore if found, undefined otherwise
*/
getDocstore(id: string): Promise<DocStore | undefined>;
/**
* List all docstores
* @returns Promise that resolves with an array of docstore objects
*/
listDocstores(): Promise<DocStore[]>;
/**
* List docstores by specific IDs
* @param ids - Array of docstore IDs to retrieve
* @returns Promise that resolves with an array of docstore objects
*/
listDocStoresByIds(ids: string[]): Promise<DocStore[]>;
/**
* List documents by specific IDs
* @param docstore_id - ID of the docstore containing the documents
* @param ids - Array of document IDs to retrieve
* @returns Promise that resolves with an array of document objects
*/
listDocsByIds(docstore_id: string, ids: string[]): Promise<Doc[]>;
/**
* Delete a docstore and all its documents
* @param id - ID of the docstore to delete
* @returns Promise that resolves with true if docstore existed and was deleted, false otherwise
*/
deleteDocstore(id: string): Promise<boolean>;
/**
* Count documents in a docstore
* @param docstore_id - ID of the docstore to count documents for
* @returns Promise that resolves with the number of documents in the docstore
*/
countDocs(docstore_id: string): Promise<number>;
/**
* Symbol.dispose method for releasing resources
*/
[Symbol.dispose](): void;
}
/**
* Message types for WebSocket communication
*/
export declare enum MessageType {
REQUEST = "request",
RESPONSE = "response",
SUBSCRIPTION = "subscription",
DOCUMENT = "document",
END = "end",
AUTH = "auth"
}
/**
* Interface for WebSocket messages
*/
export interface WebSocketMessage {
id: string;
type: MessageType;
method: string;
params: Record<string, any>;
error?: {
code: string;
message: string;
};
perms?: {
listIds?: string[];
};
}
/**
* Interface for DocStore permissions
* Used to validate user authentication and permissions
*/
export interface DocStorePerms {
/**
* Check if a user is allowed to perform an operation
* @param user_id - The user ID
* @param message - The WebSocket message being processed
* @throws Error if the operation is not allowed with a custom error message
* @returns Promise that resolves with an optional object containing listIds if the operation is allowed
*/
checkPerms(user_id: string, message: WebSocketMessage): Promise<{
listIds?: string[];
} | void>;
/**
* Get the user ID associated with a public key
* @param pubkey - Public key of the user
* @throws Error if the user is not valid or doesn't exist
* @returns Promise that resolves with the user ID
*/
getUserId(pubkey: string): Promise<string>;
/**
* Parse and validate a NIP-98 authentication token
* @param origin - Origin URL for validation
* @param req - Request object with headers and other properties
* @returns Public key if token is valid, empty string otherwise
*/
parseAuthToken(origin: string, req: AuthRequest): Promise<string>;
}