@hiai-gg/docsmint 0.3.0

package/packages/sdk/dist/client.js

@@ -0,0 +1,568 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class DocsApiError extends Error {
+    status;
+    body;
+    url;
+    requestId;
+    constructor(status, body, message, metadata) {
+        super(message ?? `hiai-docs API error ${status}`);
+        this.name = "DocsApiError";
+        this.status = status;
+        this.body = body;
+        this.url = metadata?.url;
+        this.requestId = metadata?.requestId;
+    }
+}
+export class DocsNetworkError extends Error {
+    requestId;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.name = "DocsNetworkError";
+        this.requestId = options?.requestId;
+    }
+}
+export class DocsTimeoutError extends DocsNetworkError {
+    timeout;
+    constructor(timeout, options) {
+        super(`hiai-docs request timed out after ${timeout}ms`, options);
+        this.name = "DocsTimeoutError";
+        this.timeout = timeout;
+    }
+}
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+export class DocsClient {
+    config;
+    constructor(config) {
+        if (!config.baseUrl) {
+            throw new Error("DocsClient: `baseUrl` is required");
+        }
+        this.config = {
+            baseUrl: config.baseUrl.replace(/\/+$/, ""),
+            apiKey: config.apiKey,
+            requestContext: config.requestContext,
+            fetch: config.fetch ?? fetch,
+            timeout: config.timeout ?? 10_000,
+            retries: config.retries ?? 3,
+            retryBackoffMs: config.retryBackoffMs ?? 250,
+        };
+    }
+    /** Return a client with a merged request context for an incoming request. */
+    withRequestContext(context) {
+        return new DocsClient({
+            ...this.config,
+            requestContext: this.mergeContext(this.config.requestContext, context),
+        });
+    }
+    // ── Documents ────────────────────────────────────────────────────────
+    async createDoc(input, context) {
+        return this.request("POST", "/api/documents", { json: input }, context);
+    }
+    async getDoc(id, context) {
+        return this.request("GET", `/api/documents/${encodeURIComponent(id)}`, undefined, context);
+    }
+    /**
+     * Fetch a document as raw markdown via the public export endpoint.
+     * Returns just the markdown body as a string.
+     */
+    async getDocMarkdown(id, context) {
+        const res = await this.fetchRaw("GET", `/api/documents/${encodeURIComponent(id)}/export`, undefined, context);
+        if (!res.ok) {
+            throw await this.toApiError(res);
+        }
+        return res.text();
+    }
+    async updateDoc(id, updates, context) {
+        return this.request("PATCH", `/api/documents/${encodeURIComponent(id)}`, {
+            json: updates,
+        }, context);
+    }
+    async deleteDoc(id, context) {
+        await this.request("DELETE", `/api/documents/${encodeURIComponent(id)}`, undefined, context);
+    }
+    async listDocs(options, context) {
+        return this.request("GET", "/api/documents", {
+            query: this.cleanQuery({
+                folderId: options?.folderId,
+                tag: options?.tag,
+                page: options?.page,
+                limit: options?.limit,
+            }),
+        }, context);
+    }
+    async duplicateDoc(id, context) {
+        return this.request("POST", `/api/documents/${encodeURIComponent(id)}/duplicate`, undefined, context);
+    }
+    async getDocumentPipeline(id, context) {
+        return this.request("GET", `/api/documents/${encodeURIComponent(id)}/pipeline`, undefined, context);
+    }
+    async publishDoc(id, context) {
+        return this.request("POST", `/api/documents/${encodeURIComponent(id)}/publish`, undefined, context);
+    }
+    async unpublishDoc(id, context) {
+        return this.request("POST", `/api/documents/${encodeURIComponent(id)}/unpublish`, undefined, context);
+    }
+    /**
+     * Convenience alias for `getDocMarkdown` — both go through the same
+     * `/api/documents/:id/export` endpoint on the backend.
+     */
+    async exportDoc(id, context) {
+        return this.getDocMarkdown(id, context);
+    }
+    /**
+     * Import a document from raw content. Posts JSON to
+     * `POST /api/documents/import`.
+     */
+    async importDoc(input, context) {
+        return this.request("POST", "/api/documents/import", { json: input }, context);
+    }
+    // ── Folders ──────────────────────────────────────────────────────────
+    async listFolders(parentId, context) {
+        return this.request("GET", "/api/folders", {
+            query: this.cleanQuery({ parentId }),
+        }, context);
+    }
+    async getFolder(id, context) {
+        return this.request("GET", `/api/folders/${encodeURIComponent(id)}`, undefined, context);
+    }
+    async createFolder(input, context) {
+        return this.request("POST", "/api/folders", {
+            json: input,
+        }, context);
+    }
+    async updateFolder(id, updates, context) {
+        return this.request("PATCH", `/api/folders/${encodeURIComponent(id)}`, {
+            json: updates,
+        }, context);
+    }
+    async deleteFolder(id, context) {
+        await this.request("DELETE", `/api/folders/${encodeURIComponent(id)}`, undefined, context);
+    }
+    // ── Tags ─────────────────────────────────────────────────────────────
+    async listTags(context) {
+        return this.request("GET", "/api/tags", undefined, context);
+    }
+    async createTag(input, context) {
+        return this.request("POST", "/api/tags", { json: input }, context);
+    }
+    async updateTag(id, updates, context) {
+        return this.request("PATCH", `/api/tags/${encodeURIComponent(id)}`, {
+            json: updates,
+        }, context);
+    }
+    async deleteTag(id, context) {
+        await this.request("DELETE", `/api/tags/${encodeURIComponent(id)}`, undefined, context);
+    }
+    async addTagToDoc(documentId, tagId, context) {
+        await this.request("POST", `/api/documents/${encodeURIComponent(documentId)}/tags`, { json: { tagId } }, context);
+    }
+    async removeTagFromDoc(documentId, tagId, context) {
+        await this.request("DELETE", `/api/documents/${encodeURIComponent(documentId)}/tags/${encodeURIComponent(tagId)}`, undefined, context);
+    }
+    // ── Categories ───────────────────────────────────────────────────────
+    async listCategories(context) {
+        return this.request("GET", "/api/categories", undefined, context);
+    }
+    async createCategory(input, context) {
+        return this.request("POST", "/api/categories", { json: input }, context);
+    }
+    async updateCategory(id, updates, context) {
+        return this.request("PATCH", `/api/categories/${encodeURIComponent(id)}`, { json: updates }, context);
+    }
+    async deleteCategory(id, context) {
+        await this.request("DELETE", `/api/categories/${encodeURIComponent(id)}`, undefined, context);
+    }
+    // API key lifecycle endpoints require a browser session. Pass one via
+    // requestContext.cookie or requestContext.authorization.
+    async createGlobalApiKey(name, context) {
+        return this.request("POST", "/api/keys/global", { json: name ? { name } : {} }, context);
+    }
+    async createCategoryApiKey(categoryId, name, context) {
+        return this.request("POST", `/api/categories/${encodeURIComponent(categoryId)}/keys`, { json: name ? { name } : {} }, context);
+    }
+    async listApiKeys(context) {
+        return this.request("GET", "/api/keys", undefined, context);
+    }
+    async revealCategoryApiKey(id, context) {
+        return this.request("GET", `/api/keys/${encodeURIComponent(id)}/secret`, undefined, context);
+    }
+    async revokeApiKey(id, context) {
+        return this.request("DELETE", `/api/keys/${encodeURIComponent(id)}`, undefined, context);
+    }
+    // ── Search ───────────────────────────────────────────────────────────
+    async search(query, options, context) {
+        return this.request("GET", "/api/search", {
+            query: this.cleanQuery({
+                q: query,
+                folder: options?.folder,
+                tags: options?.tags,
+                category: options?.category,
+                dateFrom: options?.dateFrom,
+                dateTo: options?.dateTo,
+                sort: options?.sort,
+                page: options?.page,
+                limit: options?.limit,
+                graph: options?.graph,
+                graphHops: options?.graphHops,
+                graphBoost: options?.graphBoost,
+                includeChunks: options?.includeChunks,
+            }),
+        }, context);
+    }
+    async suggest(query, context) {
+        return this.request("GET", "/api/search/suggest", {
+            query: this.cleanQuery({ q: query }),
+        }, context);
+    }
+    // ── Graph metadata ───────────────────────────────────────────────────
+    /** Return entities linked to a document through the AGE graph. */
+    async getGraphEntities(docId, context) {
+        return this.request("GET", "/api/graph/entities", {
+            query: this.cleanQuery({ docId }),
+        }, context);
+    }
+    async listGraphEntities(docId, context) {
+        return this.getGraphEntities(docId, context);
+    }
+    /** Return graph-related documents and their relation metadata. */
+    async getRelatedDocuments(docId, context) {
+        return this.request("GET", `/api/graph/related/${encodeURIComponent(docId)}`, undefined, context);
+    }
+    async listRelatedDocuments(docId, context) {
+        return this.getRelatedDocuments(docId, context);
+    }
+    /** Bulk graph lookup for agent and product integrations. */
+    async graphSearch(input, context) {
+        return this.request("POST", "/api/graph/search", {
+            json: input,
+        }, context);
+    }
+    /** Compatibility alias for callers that prefer verb-first naming. */
+    async searchGraph(input, context) {
+        return this.graphSearch(input, context);
+    }
+    // ── Share ────────────────────────────────────────────────────────────
+    async createShare(input, context) {
+        return this.request("POST", "/api/share", { json: input }, context);
+    }
+    async listShares(context) {
+        return this.request("GET", "/api/share", undefined, context);
+    }
+    async deleteShare(id, context) {
+        await this.request("DELETE", `/api/share/${encodeURIComponent(id)}`, undefined, context);
+    }
+    async updateShare(id, updates, context) {
+        return this.request("PATCH", `/api/share/${encodeURIComponent(id)}`, { json: updates }, context);
+    }
+    /**
+     * Public endpoint — still sends `Authorization` if configured, but
+     * the backend does not require it.
+     */
+    async getShareByToken(token, context) {
+        return this.request("GET", `/api/share/${encodeURIComponent(token)}`, undefined, context);
+    }
+    // ── Attachments ──────────────────────────────────────────────────────
+    async uploadAttachment(documentId, file, filename, mimeType, context) {
+        const form = new FormData();
+        const blob = this.toBlob(file, mimeType);
+        form.append("file", blob, filename);
+        const res = await this.fetchRaw("POST", `/api/documents/${encodeURIComponent(documentId)}/attachments`, { body: form }, context);
+        if (!res.ok) {
+            throw await this.toApiError(res);
+        }
+        return (await res.json());
+    }
+    async presignAttachment(documentId, input, context) {
+        return this.request("POST", `/api/documents/${encodeURIComponent(documentId)}/attachments/presign`, { json: input }, context);
+    }
+    async confirmAttachment(documentId, input, context) {
+        return this.request("POST", `/api/documents/${encodeURIComponent(documentId)}/attachments/confirm`, { json: input }, context);
+    }
+    async listAttachments(documentId, context) {
+        return this.request("GET", `/api/documents/${encodeURIComponent(documentId)}/attachments`, undefined, context);
+    }
+    async deleteAttachment(id, context) {
+        await this.request("DELETE", `/api/attachments/${encodeURIComponent(id)}`, undefined, context);
+    }
+    // ── Versions ─────────────────────────────────────────────────────────
+    async listVersions(documentId, options, context) {
+        return this.request("GET", `/api/documents/${encodeURIComponent(documentId)}/versions`, {
+            query: this.cleanQuery({
+                onlySnapshots: options?.onlySnapshots,
+                limit: options?.limit,
+            }),
+        }, context);
+    }
+    async getVersion(documentId, versionId, context) {
+        return this.request("GET", `/api/documents/${encodeURIComponent(documentId)}/versions/${encodeURIComponent(versionId)}`, undefined, context);
+    }
+    async createSnapshot(documentId, input, context) {
+        return this.request("POST", `/api/documents/${encodeURIComponent(documentId)}/versions`, { json: input }, context);
+    }
+    async restoreVersion(documentId, versionId, context) {
+        return this.request("POST", `/api/documents/${encodeURIComponent(documentId)}/versions/${encodeURIComponent(versionId)}/restore`, undefined, context);
+    }
+    async diffVersions(documentId, from, to, context) {
+        return this.request("GET", `/api/documents/${encodeURIComponent(documentId)}/versions/diff`, { query: { from, to } }, context);
+    }
+    // ── Health ───────────────────────────────────────────────────────────
+    async health(context) {
+        return this.request("GET", "/api/health", undefined, context);
+    }
+    // ─────────────────────────────────────────────────────────────────────
+    // Internal: HTTP plumbing
+    // ─────────────────────────────────────────────────────────────────────
+    async request(method, path, options, context) {
+        const res = await this.fetchRaw(method, path, {
+            json: options?.json,
+            query: options?.query,
+        }, context);
+        if (!res.ok) {
+            throw await this.toApiError(res);
+        }
+        // 204 / empty bodies: return undefined cast to T
+        const contentType = res.headers.get("content-type") ?? "";
+        if (res.status === 204 || res.body === null) {
+            return undefined;
+        }
+        if (contentType.includes("application/json")) {
+            return (await res.json());
+        }
+        // Fall back to text for non-JSON success responses (e.g. raw markdown export).
+        return (await res.text());
+    }
+    async fetchRaw(method, path, options, context) {
+        const url = this.buildUrl(path, options?.query);
+        const requestContext = this.mergeContext(this.config.requestContext, context);
+        const headers = new Headers(requestContext?.headers);
+        if (!headers.has("Authorization") && this.config.apiKey) {
+            headers.set("Authorization", `Bearer ${this.config.apiKey}`);
+        }
+        if (requestContext?.authorization)
+            headers.set("Authorization", requestContext.authorization);
+        if (requestContext?.cookie)
+            headers.set("Cookie", requestContext.cookie);
+        if (requestContext?.requestId)
+            headers.set("X-Request-Id", requestContext.requestId);
+        if (requestContext?.workspaceAssertion &&
+            requestContext?.externalTenantAssertion &&
+            requestContext.workspaceAssertion !== requestContext.externalTenantAssertion) {
+            throw new Error("Conflicting workspace assertions in request context");
+        }
+        const workspaceAssertion = requestContext?.workspaceAssertion ?? requestContext?.externalTenantAssertion;
+        if (workspaceAssertion)
+            headers.set("X-Docsmint-Workspace-Context", workspaceAssertion);
+        let body;
+        if (options?.body !== undefined) {
+            // Caller-supplied body (e.g. FormData) — set Content-Type if it's a Blob.
+            body = options.body;
+        }
+        else if (options?.json !== undefined) {
+            body = JSON.stringify(options.json);
+            headers.set("Content-Type", "application/json");
+        }
+        const init = { method, headers };
+        if (body !== undefined)
+            init.body = body;
+        let lastError = null;
+        const maxAttempts = Math.max(1, this.config.retries);
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const timeoutSignal = AbortSignal.timeout(this.config.timeout);
+            const signal = requestContext?.signal
+                ? AbortSignal.any([requestContext.signal, timeoutSignal])
+                : timeoutSignal;
+            try {
+                const res = await this.config.fetch(url, { ...init, signal });
+                if (this.shouldRetryStatus(res.status) && attempt < maxAttempts - 1) {
+                    await this.sleep(this.backoffDelay(attempt), requestContext?.signal);
+                    continue;
+                }
+                return res;
+            }
+            catch (err) {
+                lastError = err;
+                // A caller cancellation is authoritative. Do not retry it and do
+                // not turn it into a timeout merely because the internal timeout
+                // signal is also part of AbortSignal.any(). Preserving the original
+                // error keeps standard AbortController semantics for hosts.
+                if (requestContext?.signal?.aborted) {
+                    throw requestContext.signal.reason ?? err;
+                }
+                if (!this.isRetryableError(err) || attempt === maxAttempts - 1) {
+                    if (this.isTimeoutError(err)) {
+                        throw new DocsTimeoutError(this.config.timeout, {
+                            cause: err,
+                            requestId: requestContext?.requestId,
+                        });
+                    }
+                    throw this.wrapNetworkError(err, requestContext?.requestId);
+                }
+                await this.sleep(this.backoffDelay(attempt), requestContext?.signal);
+            }
+        }
+        // Should be unreachable — the loop above either returns or throws.
+        throw this.wrapNetworkError(lastError, requestContext?.requestId);
+    }
+    buildUrl(path, query) {
+        let url = `${this.config.baseUrl}${path}`;
+        if (query && Object.keys(query).length > 0) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined || value === null)
+                    continue;
+                params.append(key, String(value));
+            }
+            const qs = params.toString();
+            if (qs)
+                url += (url.includes("?") ? "&" : "?") + qs;
+        }
+        return url;
+    }
+    cleanQuery(query) {
+        const out = {};
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null)
+                continue;
+            out[key] = value;
+        }
+        return out;
+    }
+    shouldRetryStatus(status) {
+        return status === 502 || status === 503 || status === 504;
+    }
+    isRetryableError(err) {
+        if (!(err instanceof Error))
+            return false;
+        // AbortSignal.timeout surfaces as DOMException with name "TimeoutError"
+        // or as a plain Error with name "AbortError" in some runtimes.
+        if (err.name === "TimeoutError" || err.name === "AbortError")
+            return true;
+        // Connection resets / DNS failures etc. come through as TypeError
+        // wrapping a system error code.
+        const cause = err.cause;
+        if (cause?.code === "ECONNRESET")
+            return true;
+        if (cause?.code === "ECONNREFUSED")
+            return true;
+        if (cause?.code === "ETIMEDOUT")
+            return true;
+        return false;
+    }
+    backoffDelay(attempt) {
+        // Exponential backoff: 1x, 2x, 4x ... with light jitter.
+        const base = this.config.retryBackoffMs * 2 ** attempt;
+        const jitter = Math.random() * base * 0.25;
+        return Math.floor(base + jitter);
+    }
+    async sleep(ms, signal) {
+        if (signal?.aborted) {
+            throw (signal.reason ??
+                new DOMException("The operation was aborted", "AbortError"));
+        }
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                reject(signal?.reason ??
+                    new DOMException("The operation was aborted", "AbortError"));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    async toApiError(res) {
+        const contentType = res.headers.get("content-type") ?? "";
+        let body;
+        try {
+            body = contentType.includes("application/json")
+                ? await res.json()
+                : await res.text();
+        }
+        catch {
+            body = null;
+        }
+        const message = body &&
+            typeof body === "object" &&
+            "error" in body &&
+            typeof body.error === "string"
+            ? body.error
+            : body &&
+                typeof body === "object" &&
+                "message" in body &&
+                typeof body.message === "string"
+                ? body.message
+                : `hiai-docs API error ${res.status}`;
+        return new DocsApiError(res.status, body, message, {
+            url: res.url || undefined,
+            requestId: res.headers.get("x-request-id") ?? undefined,
+        });
+    }
+    wrapNetworkError(err, requestId) {
+        if (err instanceof Error) {
+            return new DocsNetworkError(`hiai-docs network error: ${err.message}`, {
+                cause: err,
+                requestId,
+            });
+        }
+        return new DocsNetworkError(`hiai-docs network error: ${String(err)}`, {
+            requestId,
+        });
+    }
+    isTimeoutError(err) {
+        return (err instanceof Error &&
+            (err.name === "TimeoutError" || err.name === "AbortError"));
+    }
+    mergeContext(base, override) {
+        if (!base && !override)
+            return undefined;
+        return {
+            ...base,
+            ...override,
+            headers: {
+                ...(base?.headers
+                    ? Object.fromEntries(new Headers(base.headers).entries())
+                    : {}),
+                ...(override?.headers
+                    ? Object.fromEntries(new Headers(override.headers).entries())
+                    : {}),
+            },
+        };
+    }
+    toBlob(file, mimeType) {
+        if (file instanceof Blob) {
+            // Re-wrap with explicit MIME if the caller passed one.
+            if (file.type && file.type !== mimeType) {
+                return new Blob([file], { type: mimeType });
+            }
+            return file;
+        }
+        if (file instanceof ArrayBuffer) {
+            return new Blob([file], { type: mimeType });
+        }
+        if (file instanceof Uint8Array) {
+            // TS 5.9 widened `Uint8Array<ArrayBufferLike>` which is not a
+            // direct `BlobPart`. Copy into a fresh `Uint8Array<ArrayBuffer>`
+            // to satisfy the Blob constructor.
+            const copy = new Uint8Array(file.byteLength);
+            copy.set(file);
+            return new Blob([copy], { type: mimeType });
+        }
+        // Unreachable — covered by the union — but TS strict requires it.
+        throw new Error("DocsClient.uploadAttachment: unsupported file type");
+    }
+}

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

@@ -0,0 +1,3 @@
+export type { DocsClientConfig } from "./client.js";
+export { DocsApiError, DocsClient, DocsNetworkError, DocsTimeoutError, } from "./client.js";
+export type * from "./types.js";

package/packages/sdk/dist/index.js

@@ -0,0 +1 @@
+export { DocsApiError, DocsClient, DocsNetworkError, DocsTimeoutError, } from "./client.js";