metainsight-context-engine 0.0.1

package/dist/cos-operations.d.ts

@@ -0,0 +1,219 @@
+/**
+ * COS Operations — Unified CRUD Operations Layer
+ *
+ * Provides all data operations (upload / search / download / delete) for the
+ * Cloud Context Engine. Built on top of the bootstrap layer (`cos-bootstrap.ts`)
+ * and routes requests to the correct dataset / COS prefix based on `category`.
+ *
+ * Architecture:
+ *   cos-bootstrap.ts  →  cos-operations.ts  →  engine.ts / index.ts
+ *   (init + low-level)    (CRUD operations)     (business logic)
+ *
+ * The constructor accepts a `BootstrapOutcome`, so consumers only need to call
+ * `bootstrap()` once and pass the result here — no duplicate initialization.
+ *
+ * Multimodal retrieval:
+ *   - Text/memory queries route to DocSearch datasets (category="memory")
+ *   - Image queries route to ImageSearch datasets (category="image")
+ *   - The search template is automatically selected per-dataset based on
+ *     the dataset's `templateId` (Official:ImageSearch → "ImageSearch").
+ *
+ * Key improvements over the old `cloud-client.ts`:
+ *   - Upload path uses the dataset's `cosPrefix` (not hardcoded `uploads/`)
+ *   - Search routes to the correct dataset name based on category
+ *   - Automatic template selection for multimodal (DocSearch / ImageSearch)
+ *   - Download support (getObject from COS)
+ *   - Delete support (deleteObject from COS)
+ */
+import type { BootstrapOutcome, ResolvedCosConfig } from './cos-bootstrap.js';
+export interface CloudSearchResult {
+    snippet: string;
+    score: number;
+    docId?: string;
+    category?: 'memory' | 'document';
+    /** Signed HTTPS URL for image results (only present for ImageSearch results). */
+    imageUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CloudUploadResult {
+    docId: string;
+    key: string;
+    status: string;
+    /** Error message when status === 'error'. */
+    error?: string;
+}
+export interface CloudDownloadResult {
+    content: string;
+    key: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CloudSearchOptions {
+    category?: string;
+    maxResults?: number;
+    minScore?: number;
+}
+export interface CloudUploadOptions {
+    category?: string;
+    docId?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * When set, overrides the default COS key construction
+     * (`{cosPrefix}{docId}.md`) and uses this value as the full COS key.
+     *
+     * Useful for placing files outside the dataset's cosPrefix directory,
+     * e.g. workspace identity files that should live at
+     * `openclaw-{agentId}/agents.md` instead of
+     * `openclaw-{agentId}/workspace/agents.md`.
+     */
+    customKey?: string;
+}
+export interface CloudDownloadOptions {
+    category?: string;
+}
+export declare class CosOperations {
+    private readonly cos;
+    private readonly config;
+    /** Search template — DocSearch or ImageSearch. Default: DocSearch. */
+    private readonly template;
+    /** Default match threshold (0-100). CI recommends 80, we default to 60. */
+    private readonly matchThreshold;
+    /**
+     * Create a CosOperations instance from a successful bootstrap outcome.
+     *
+     * @throws if the bootstrap outcome indicates failure
+     */
+    constructor(outcome: BootstrapOutcome, opts?: {
+        template?: string;
+        matchThreshold?: number;
+    });
+    /**
+     * Resolve the dataset definition for a given category.
+     *
+     * Routing rules:
+     *   1. If a dataset's `cosPrefix` starts with `{category}/`, use it.
+     *      (legacy layout: cosPrefix="memory/" matches category="memory")
+     *   2. If a dataset's `cosPrefix` contains `/{category}/`, use it.
+     *      (multi-agent layout: cosPrefix="openclaw-xxx/workspace/memory/" matches category="memory")
+     *   3. If a dataset's `name` contains the category, use it.
+     *   4. Otherwise, fall back to the first dataset in config.
+     */
+    private resolveDataset;
+    /**
+     * Semantic / hybrid search against the CI dataset.
+     *
+     * Routing:
+     *   - Image datasets (Official:ImageSearch) → `POST /datasetquery/imagesearch`
+     *     with only `DatasetName` + `Mode: "text"` (simplified temporary API).
+     *   - All other datasets → `POST /datasetquery/hybridsearch` with full params.
+     *
+     * DocSearch: SearchText is truncated to 60 UTF-8 chars (CI API limit).
+     */
+    search(query: string, opts?: CloudSearchOptions): Promise<CloudSearchResult[]>;
+    /**
+     * Upload content to the COS bucket for CI indexing.
+     *
+     * Content is stored as a Markdown file under `{cosPrefix}{docId}.md`.
+     * CI will pick it up via the dataset binding and index it automatically.
+     * Metadata is stored in COS custom headers (`x-cos-meta-*`).
+     *
+     * The upload path is derived from the dataset's `cosPrefix` — not hardcoded.
+     * Category routing is handled by `resolveDataset()` which selects the
+     * correct dataset (and thus the correct cosPrefix). We do NOT append
+     * `{category}/` again — that would create nested directories like
+     * `memory/memory/`.
+     */
+    upload(content: string, opts?: CloudUploadOptions): Promise<CloudUploadResult>;
+    /**
+     * Batch upload multiple items in parallel (with concurrency limit).
+     *
+     * Individual upload failures are captured per-item (status='error')
+     * instead of aborting the entire batch — this prevents one bad item
+     * from causing all remaining items to be dropped.
+     */
+    uploadBatch(items: Array<{
+        content: string;
+        opts?: CloudUploadOptions;
+    }>, concurrency?: number): Promise<CloudUploadResult[]>;
+    /**
+     * Upload a binary file (e.g. image) to the COS bucket.
+     *
+     * Unlike `upload()` which stores text content as Markdown, this method
+     * accepts a Buffer and stores the file with its original content type.
+     * The file is placed under the provided COS key path.
+     *
+     * @param buffer    Raw file content as a Buffer.
+     * @param key       Full COS key (e.g. "openclaw-main/asset/photo.png").
+     * @param contentType  MIME type (e.g. "image/png"). Default: "application/octet-stream".
+     * @param metadata  Optional metadata to attach as COS custom headers.
+     * @returns Upload result with the COS key.
+     */
+    uploadBinary(buffer: Buffer, key: string, contentType?: string, metadata?: Record<string, unknown>): Promise<CloudUploadResult>;
+    /**
+     * Check whether a COS object exists at the given key.
+     *
+     * Uses `headObject` which returns metadata without downloading the body.
+     * Returns true if the object exists, false otherwise.
+     */
+    objectExists(key: string): Promise<boolean>;
+    /**
+     * Download a document from the COS bucket by its key.
+     *
+     * @param docKey  Full COS key (e.g. "memory/memory/abc.md") or a short docId.
+     *                If a short docId is provided, it will be resolved via the dataset cosPrefix.
+     */
+    download(docKey: string, opts?: CloudDownloadOptions): Promise<CloudDownloadResult>;
+    /**
+     * Delete a document from the COS bucket.
+     *
+     * @param docKey  Full COS key or short docId (resolved via dataset cosPrefix).
+     */
+    deleteDoc(docKey: string, opts?: CloudDownloadOptions): Promise<{
+        deleted: boolean;
+        key: string;
+    }>;
+    /** Get the resolved COS config (useful for diagnostics). */
+    getConfig(): ResolvedCosConfig;
+    /** Get all available dataset names. */
+    getDatasetNames(): string[];
+    /**
+     * Get the agent-level COS key prefix (without trailing "/workspace/").
+     *
+     * For multi-agent setups (agentId set), this returns `openclaw-{agentId}/`.
+     * For legacy setups (no agentId), this returns an empty string.
+     *
+     * Useful for placing files alongside the workspace directory rather than
+     * inside it. E.g. workspace files like AGENTS.md should go to
+     * `openclaw-{agentId}/agents.md` (agent root) instead of
+     * `openclaw-{agentId}/workspace/agents.md` (inside workspace).
+     */
+    getAgentPrefix(): string;
+    /**
+     * Generate a signed (temporary) download URL for a COS object.
+     *
+     * @param cosUri  Full COS URI (e.g. `cos://bucket-123/image/photo.jpg`)
+     *                or a plain COS key (e.g. `image/photo.jpg`).
+     * @param expiresInSeconds  URL validity duration. Default: 3600 (1 hour).
+     * @returns A signed HTTPS URL that can be used to access the object.
+     */
+    getSignedUrl(cosUri: string, expiresInSeconds?: number): string;
+    /**
+     * Map CI DocSearch results to CloudSearchResult[].
+     */
+    private mapDocResults;
+    /**
+     * Map CI ImageSearch results to CloudSearchResult[].
+     * Each result includes a signed URL for direct image access.
+     */
+    private mapImageResults;
+    /**
+     * Extract a short doc ID from a COS URI.
+     * e.g. `cos://bucket-123/memory/abc.md` → `abc.md`
+     * e.g. `cos://bucket-123/memory/IMAP__SMTP Email Tool.md`
+     *     → `IMAP/SMTP Email Tool.md`
+     *
+     * Note: docIds stored on COS have `/` replaced with `__` (see `sanitizeDocId`).
+     * This method reverses that transformation so callers see the original name.
+     */
+    private cosUriToDocId;
+}
+//# sourceMappingURL=cos-operations.d.ts.map

package/dist/cos-operations.d.ts.map

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