@hiai-gg/docsmint 0.3.0

package/packages/mcp-server/src/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared TypeScript types for hiai-docs REST API responses.
+ * Keep these minimal — only the fields consumed by MCP tools.
+ */
+
+export interface Tag {
+  id: string;
+  name: string;
+  color: string | null;
+}
+
+export interface DocumentSummary {
+  id: string;
+  title: string;
+  content?: string;
+  folderId: string | null;
+  createdAt: string;
+  updatedAt: string;
+  tags?: Tag[];
+}
+
+export interface DocumentDetail {
+  id: string;
+  ownerId: string;
+  folderId: string | null;
+  folderName?: string | null;
+  title: string;
+  content: string;
+  contentJson?: unknown;
+  createdAt: string;
+  updatedAt: string;
+  tags?: Tag[];
+}
+
+export interface SearchResultItem {
+  id: string;
+  title: string;
+  snippet: string;
+  score: number;
+  folder_id: string | null;
+  folder_name: string | null;
+  created_at: string;
+  updated_at: string;
+  tags?: Tag[];
+}
+
+export interface SearchResponse {
+  items: SearchResultItem[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface ListDocumentsResponse {
+  items: DocumentSummary[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface Folder {
+  id: string;
+  name: string;
+  parentId: string | null;
+  ownerId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Version {
+  id: string;
+  documentId: string;
+  content: string;
+  contentJson?: unknown;
+  createdBy: string;
+  createdAt: string;
+}
+
+export interface ExportResponse {
+  markdown: string;
+  filename?: string;
+}
+
+export interface CreateDocumentInput {
+  title: string;
+  content?: string;
+  folderId?: string;
+}
+
+export interface UpdateDocumentInput {
+  title?: string;
+  content?: string;
+}
+
+export interface CreateSnapshotInput {
+  label: string;
+  description?: string;
+}
+
+export interface CreateFolderInput {
+  name: string;
+  parentId?: string;
+}
+
+export interface SearchInput {
+  query: string;
+  folder?: string;
+  tags?: string[];
+  limit?: number;
+}
+
+export interface ListDocumentsInput {
+  folderId?: string;
+  tag?: string;
+  page?: number;
+  limit?: number;
+}
+
+export interface ListFoldersInput {
+  parentId?: string;
+}
+
+export interface VersionHistoryInput {
+  documentId: string;
+  onlySnapshots?: boolean;
+}

package/packages/sdk/dist/client.d.ts

@@ -0,0 +1,187 @@
+/**
+ * hiai-docs REST API client.
+ *
+ * Bun-native `fetch` wrapper. All authenticated requests send
+ * `Authorization: Bearer <apiKey>`. Non-OK responses throw
+ * `DocsApiError` carrying the HTTP status and parsed body. Transient
+ * failures (502 / 503 / 504 / timeout / network reset) are retried
+ * with exponential backoff up to `config.retries` attempts.
+ */
+import type { DocsApiKeyCreated, DocsApiKeyListResponse, DocsAttachment, DocsAttachmentConfirmInput, DocsAttachmentListResponse, DocsAttachmentPresignInput, DocsAttachmentPresignResponse, DocsCategory, DocsCategoryInput, DocsCategoryUpdate, DocsDocument, DocsDocumentCreateInput, DocsDocumentListResponse, DocsDocumentPipeline, DocsDocumentUpdateInput, DocsFolder, DocsFolderCreateInput, DocsFolderUpdateInput, DocsGraphEntitiesResponse, DocsGraphRelatedResponse, DocsGraphSearchResponse, DocsHealthResponse, DocsRequestContext, DocsSearchOptions, DocsSearchResponse, DocsSearchSuggestItem, DocsSharedContent, DocsShareLink, DocsShareListResponse, DocsShareRole, DocsTag, DocsVersion, DocsVersionDiff } from "./types.js";
+export interface DocsClientConfig {
+    /** Base URL of the hiai-docs API, e.g. `http://localhost:50700`. */
+    baseUrl: string;
+    /** Bearer token used as `Authorization: Bearer <apiKey>`. */
+    apiKey?: string;
+    /** Default request-scoped credentials forwarded to every request. */
+    requestContext?: DocsRequestContext;
+    /** Injectable fetch implementation for hosts and contract tests. */
+    fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds. Default: 10 000. */
+    timeout?: number;
+    /** Retry attempts for transient failures. Default: 3. */
+    retries?: number;
+    /** Initial backoff in milliseconds (doubles each attempt). Default: 250. */
+    retryBackoffMs?: number;
+}
+export declare class DocsApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly url?: string;
+    readonly requestId?: string;
+    constructor(status: number, body: unknown, message?: string, metadata?: {
+        url?: string;
+        requestId?: string;
+    });
+}
+export declare class DocsNetworkError extends Error {
+    readonly requestId?: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        requestId?: string;
+    });
+}
+export declare class DocsTimeoutError extends DocsNetworkError {
+    readonly timeout: number;
+    constructor(timeout: number, options?: {
+        cause?: unknown;
+        requestId?: string;
+    });
+}
+export declare class DocsClient {
+    private readonly config;
+    constructor(config: DocsClientConfig);
+    /** Return a client with a merged request context for an incoming request. */
+    withRequestContext(context: DocsRequestContext): DocsClient;
+    createDoc(input: DocsDocumentCreateInput, context?: DocsRequestContext): Promise<DocsDocument>;
+    getDoc(id: string, context?: DocsRequestContext): Promise<DocsDocument>;
+    /**
+     * Fetch a document as raw markdown via the public export endpoint.
+     * Returns just the markdown body as a string.
+     */
+    getDocMarkdown(id: string, context?: DocsRequestContext): Promise<string>;
+    updateDoc(id: string, updates: DocsDocumentUpdateInput, context?: DocsRequestContext): Promise<DocsDocument>;
+    deleteDoc(id: string, context?: DocsRequestContext): Promise<void>;
+    listDocs(options?: {
+        folderId?: string;
+        tag?: string;
+        page?: number;
+        limit?: number;
+    }, context?: DocsRequestContext): Promise<DocsDocumentListResponse>;
+    duplicateDoc(id: string, context?: DocsRequestContext): Promise<DocsDocument>;
+    getDocumentPipeline(id: string, context?: DocsRequestContext): Promise<DocsDocumentPipeline>;
+    publishDoc(id: string, context?: DocsRequestContext): Promise<DocsDocument>;
+    unpublishDoc(id: string, context?: DocsRequestContext): Promise<DocsDocument>;
+    /**
+     * Convenience alias for `getDocMarkdown` — both go through the same
+     * `/api/documents/:id/export` endpoint on the backend.
+     */
+    exportDoc(id: string, context?: DocsRequestContext): Promise<string>;
+    /**
+     * Import a document from raw content. Posts JSON to
+     * `POST /api/documents/import`.
+     */
+    importDoc(input: {
+        title?: string;
+        content: string;
+        folderId?: string;
+    }, context?: DocsRequestContext): Promise<DocsDocument>;
+    listFolders(parentId?: string, context?: DocsRequestContext): Promise<DocsFolder[]>;
+    getFolder(id: string, context?: DocsRequestContext): Promise<DocsFolder>;
+    createFolder(input: DocsFolderCreateInput, context?: DocsRequestContext): Promise<DocsFolder>;
+    updateFolder(id: string, updates: DocsFolderUpdateInput, context?: DocsRequestContext): Promise<DocsFolder>;
+    deleteFolder(id: string, context?: DocsRequestContext): Promise<void>;
+    listTags(context?: DocsRequestContext): Promise<DocsTag[]>;
+    createTag(input: {
+        name: string;
+        color?: string;
+    }, context?: DocsRequestContext): Promise<DocsTag>;
+    updateTag(id: string, updates: {
+        name?: string;
+        color?: string;
+    }, context?: DocsRequestContext): Promise<DocsTag>;
+    deleteTag(id: string, context?: DocsRequestContext): Promise<void>;
+    addTagToDoc(documentId: string, tagId: string, context?: DocsRequestContext): Promise<void>;
+    removeTagFromDoc(documentId: string, tagId: string, context?: DocsRequestContext): Promise<void>;
+    listCategories(context?: DocsRequestContext): Promise<DocsCategory[]>;
+    createCategory(input: DocsCategoryInput, context?: DocsRequestContext): Promise<DocsCategory>;
+    updateCategory(id: string, updates: DocsCategoryUpdate, context?: DocsRequestContext): Promise<DocsCategory>;
+    deleteCategory(id: string, context?: DocsRequestContext): Promise<void>;
+    createGlobalApiKey(name?: string, context?: DocsRequestContext): Promise<DocsApiKeyCreated>;
+    createCategoryApiKey(categoryId: string, name?: string, context?: DocsRequestContext): Promise<DocsApiKeyCreated>;
+    listApiKeys(context?: DocsRequestContext): Promise<DocsApiKeyListResponse>;
+    revealCategoryApiKey(id: string, context?: DocsRequestContext): Promise<{
+        key: string;
+    }>;
+    revokeApiKey(id: string, context?: DocsRequestContext): Promise<{
+        success: true;
+    }>;
+    search(query: string, options?: DocsSearchOptions, context?: DocsRequestContext): Promise<DocsSearchResponse>;
+    suggest(query: string, context?: DocsRequestContext): Promise<DocsSearchSuggestItem[]>;
+    /** Return entities linked to a document through the AGE graph. */
+    getGraphEntities(docId: string, context?: DocsRequestContext): Promise<DocsGraphEntitiesResponse>;
+    listGraphEntities(docId: string, context?: DocsRequestContext): Promise<DocsGraphEntitiesResponse>;
+    /** Return graph-related documents and their relation metadata. */
+    getRelatedDocuments(docId: string, context?: DocsRequestContext): Promise<DocsGraphRelatedResponse>;
+    listRelatedDocuments(docId: string, context?: DocsRequestContext): Promise<DocsGraphRelatedResponse>;
+    /** Bulk graph lookup for agent and product integrations. */
+    graphSearch(input: {
+        query?: string;
+        docIds: string[];
+        maxResults?: number;
+    }, context?: DocsRequestContext): Promise<DocsGraphSearchResponse>;
+    /** Compatibility alias for callers that prefer verb-first naming. */
+    searchGraph(input: {
+        query?: string;
+        docIds: string[];
+        maxResults?: number;
+    }, context?: DocsRequestContext): Promise<DocsGraphSearchResponse>;
+    createShare(input: {
+        documentId?: string;
+        folderId?: string;
+        password?: string;
+        expiresIn?: "1h" | "1d" | "7d" | "30d" | "never";
+        role?: DocsShareRole;
+    }, context?: DocsRequestContext): Promise<DocsShareLink>;
+    listShares(context?: DocsRequestContext): Promise<DocsShareListResponse>;
+    deleteShare(id: string, context?: DocsRequestContext): Promise<void>;
+    updateShare(id: string, updates: {
+        role?: DocsShareRole;
+        expiresIn?: "1h" | "1d" | "7d" | "30d" | "never";
+    }, context?: DocsRequestContext): Promise<DocsShareLink>;
+    /**
+     * Public endpoint — still sends `Authorization` if configured, but
+     * the backend does not require it.
+     */
+    getShareByToken(token: string, context?: DocsRequestContext): Promise<DocsSharedContent>;
+    uploadAttachment(documentId: string, file: Blob | ArrayBuffer | Uint8Array, filename: string, mimeType: string, context?: DocsRequestContext): Promise<DocsAttachment>;
+    presignAttachment(documentId: string, input: DocsAttachmentPresignInput, context?: DocsRequestContext): Promise<DocsAttachmentPresignResponse>;
+    confirmAttachment(documentId: string, input: DocsAttachmentConfirmInput, context?: DocsRequestContext): Promise<DocsAttachment>;
+    listAttachments(documentId: string, context?: DocsRequestContext): Promise<DocsAttachmentListResponse>;
+    deleteAttachment(id: string, context?: DocsRequestContext): Promise<void>;
+    listVersions(documentId: string, options?: {
+        onlySnapshots?: boolean;
+        limit?: number;
+    }, context?: DocsRequestContext): Promise<DocsVersion[]>;
+    getVersion(documentId: string, versionId: string, context?: DocsRequestContext): Promise<DocsVersion>;
+    createSnapshot(documentId: string, input: {
+        label: string;
+        description?: string;
+    }, context?: DocsRequestContext): Promise<DocsVersion>;
+    restoreVersion(documentId: string, versionId: string, context?: DocsRequestContext): Promise<DocsDocument>;
+    diffVersions(documentId: string, from: string, to: string, context?: DocsRequestContext): Promise<DocsVersionDiff>;
+    health(context?: DocsRequestContext): Promise<DocsHealthResponse>;
+    private request;
+    private fetchRaw;
+    private buildUrl;
+    private cleanQuery;
+    private shouldRetryStatus;
+    private isRetryableError;
+    private backoffDelay;
+    private sleep;
+    private toApiError;
+    private wrapNetworkError;
+    private isTimeoutError;
+    private mergeContext;
+    private toBlob;
+}