@knowzai/api-client 0.1.0 → 0.2.0

package/dist/resources/files.d.ts

@@ -0,0 +1,72 @@
+import type { RawCoreClient } from '../contracts.js';
+/** Progress for one chunk of one file. `bytesSent` is cumulative for the file. */
+export interface UploadProgress {
+    fileName: string;
+    chunkIndex: number;
+    totalChunks: number;
+    bytesSent: number;
+    totalBytes: number;
+}
+export interface UploadedFile {
+    fileRecordId: string;
+    fileName: string;
+    size: number;
+    contentType: string;
+}
+export interface UploadInput {
+    /** Local file path. Only its basename crosses the wire (R12). */
+    path: string;
+    /**
+     * An ALREADY-OPEN, already-approved descriptor for `path`.
+     *
+     * H7 (TOCTOU) — a caller that gated the file (`openSafeFile`: `O_NOFOLLOW`
+     * + `fstat` policy) hands the descriptor itself over rather than the path, and
+     * the uploader `fstat`s and reads THAT descriptor. Without this the uploader
+     * re-opens `path` after `initialize` has round-tripped, so the file that was
+     * judged and the file whose bytes are sent can differ — a path swapped for a
+     * symlink to a credential file in that window would be uploaded instead.
+     *
+     * The descriptor is BORROWED: the caller opened it and the caller closes it.
+     * `path` is still used, for its basename and content type only.
+     */
+    fd?: number;
+    /** Overrides the extension-derived content type (R11). */
+    contentType?: string;
+    /** Omit for a Standalone upload — required when attaching to an existing item (R2). */
+    createAs?: 'knowledge' | 'inbox';
+    /** Required when `createAs === 'knowledge'`. */
+    vaultId?: string;
+    title?: string;
+    /** Slides the parent's AwaitingAttachments TTL window forward across a multi-file run (R3). */
+    parentKnowledgeId?: string;
+    onProgress?: (progress: UploadProgress) => void;
+    signal?: AbortSignal;
+    /** Bounded per-chunk retry for retryable failures (R8). Default 2. */
+    chunkRetries?: number;
+    /** Base backoff between chunk retries, doubling each attempt. Default 250ms. */
+    chunkRetryDelayMs?: number;
+}
+/** Infer a content type from a file name (R11). Unknown → `application/octet-stream`. */
+export declare function contentTypeForFile(fileName: string): string;
+export declare class FilesApi {
+    private readonly core;
+    constructor(core: RawCoreClient);
+    /**
+     * Upload a local file with the platform's three-call chunked protocol (R1):
+     * `initialize` → N× `streaming` → `complete`. Bytes are streamed from disk one
+     * server-sized chunk at a time, so file size is bounded by the platform's
+     * ingestion limits rather than by client memory.
+     */
+    upload(input: UploadInput): Promise<UploadedFile>;
+    /**
+     * PUT one chunk. Retries only what is worth retrying (R8): a 404 means the
+     * session expired or is not ours, so retrying is pointless and misleading —
+     * it propagates immediately and fails the whole file.
+     *
+     * `X-Chunk-Hash` is deliberately NOT sent: the server compares it as base64
+     * MD5 (`ChunkedUploadService.UploadChunkAsync`), not the SHA-256 hex used for
+     * `X-File-Hash`, and it is optional. Whole-file integrity is covered on complete.
+     */
+    private sendChunk;
+}
+//# sourceMappingURL=files.d.ts.map

package/dist/resources/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/resources/files.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;OAYG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IACjC,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;IAChD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAwDD,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAuBD,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAEhD;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IA0FvD;;;;;;;;OAQG;YACW,SAAS;CA4BxB"}

package/dist/resources/files.js

@@ -0,0 +1,205 @@
+import { createHash } from 'node:crypto';
+import { fstat as fstatCb, read as readCb } from 'node:fs';
+import { open, stat } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { z } from 'zod';
+import { ApiError } from '@knowzai/types';
+const SessionSchema = z.object({
+    uploadId: z.string(),
+    fileRecordId: z.string(),
+    totalChunks: z.number().int().nonnegative(),
+    chunkSize: z.number().int().positive(),
+    expiresAt: z.string().optional(),
+});
+const CompletedSchema = z.object({
+    fileRecordId: z.string(),
+    fileName: z.string().optional(),
+    fileSize: z.number().optional(),
+    contentType: z.string().optional(),
+});
+/**
+ * Extension → content type. Node has no built-in MIME table and the CLI takes no
+ * runtime dependencies for this; unknown extensions fall through to
+ * `application/octet-stream`, which the platform handles (R11).
+ */
+const CONTENT_TYPES = {
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.csv': 'text/csv',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.yaml': 'application/yaml',
+    '.yml': 'application/yaml',
+    '.pdf': 'application/pdf',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.ppt': 'application/vnd.ms-powerpoint',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.heic': 'image/heic',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.m4a': 'audio/mp4',
+    '.ogg': 'audio/ogg',
+    '.webm': 'video/webm',
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.zip': 'application/zip',
+};
+/** Infer a content type from a file name (R11). Unknown → `application/octet-stream`. */
+export function contentTypeForFile(fileName) {
+    return CONTENT_TYPES[extname(fileName).toLowerCase()] ?? 'application/octet-stream';
+}
+/** A chunk failure worth another attempt: upstream 5xx/429, or a transport error. */
+function isRetryableChunkError(e) {
+    if (!(e instanceof ApiError))
+        return false;
+    return e.status === 0 || e.status === 429 || e.status >= 500;
+}
+const delay = (ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms));
+/** `fstat` of a borrowed descriptor — promisified so the upload loop stays async. */
+function fstatFd(fd) {
+    return new Promise((resolve, reject) => fstatCb(fd, (e, s) => (e ? reject(e) : resolve(s))));
+}
+/** Positional read from a borrowed descriptor. Does not move the file offset. */
+function readFd(fd, buffer, position) {
+    return new Promise((resolve, reject) => readCb(fd, buffer, 0, buffer.length, position, (e, bytesRead) => (e ? reject(e) : resolve(bytesRead))));
+}
+export class FilesApi {
+    core;
+    constructor(core) {
+        this.core = core;
+    }
+    /**
+     * Upload a local file with the platform's three-call chunked protocol (R1):
+     * `initialize` → N× `streaming` → `complete`. Bytes are streamed from disk one
+     * server-sized chunk at a time, so file size is bounded by the platform's
+     * ingestion limits rather than by client memory.
+     */
+    async upload(input) {
+        const fileName = basename(input.path); // R12 — no directory component crosses the wire.
+        // The size comes from the BORROWED descriptor when there is one, so it
+        // describes the file the caller approved rather than whatever the path
+        // resolves to now.
+        const { size } = input.fd === undefined ? await stat(input.path) : await fstatFd(input.fd);
+        if (size === 0) {
+            throw new ApiError(0, [`${fileName} is empty — there is nothing to upload.`], {
+                code: 'empty-file',
+            });
+        }
+        const contentType = input.contentType ?? contentTypeForFile(fileName);
+        // 1) initialize — the server issues the upload id, the fileRecordId (R4) and
+        //    the chunk size (R5). A 413 here carries the ingestion-limit message.
+        const session = await this.core.request({
+            method: 'POST',
+            path: '/api/v1/files/upload/initialize',
+            body: { fileName, fileSize: size, contentType },
+            schema: SessionSchema,
+        });
+        const chunkSize = session.chunkSize;
+        const totalChunks = session.totalChunks || Math.ceil(size / chunkSize);
+        const retries = input.chunkRetries ?? 2;
+        const retryDelayMs = input.chunkRetryDelayMs ?? 250;
+        // 2) streaming — one call per chunk, 0-based contiguous indices, never an
+        //    empty body. The whole-file hash is accumulated on the way past.
+        const fileHash = createHash('sha256');
+        // Only open the path when no descriptor was handed to us. A borrowed fd is
+        // never re-opened and never closed here — closing it would yank a handle the
+        // caller still owns.
+        const handle = input.fd === undefined ? await open(input.path, 'r') : undefined;
+        const fd = input.fd;
+        try {
+            let bytesSent = 0;
+            for (let chunkIndex = 0; bytesSent < size; chunkIndex++) {
+                const buffer = Buffer.allocUnsafe(Math.min(chunkSize, size - bytesSent));
+                const bytesRead = handle === undefined
+                    ? await readFd(fd, buffer, bytesSent)
+                    : (await handle.read(buffer, 0, buffer.length, bytesSent)).bytesRead;
+                if (bytesRead === 0)
+                    break; // Truncated under us — stop rather than send an empty chunk.
+                const chunk = buffer.subarray(0, bytesRead);
+                fileHash.update(chunk);
+                await this.sendChunk(session.uploadId, chunkIndex, totalChunks, chunk, {
+                    retries,
+                    retryDelayMs,
+                    signal: input.signal,
+                });
+                bytesSent += bytesRead;
+                input.onProgress?.({ fileName, chunkIndex, totalChunks, bytesSent, totalBytes: size });
+            }
+        }
+        finally {
+            await handle?.close();
+        }
+        // 3) complete — echo the server-issued fileRecordId verbatim (R4). `createAs`
+        //    is omitted for the attach flow: HTTP /complete cannot express
+        //    ExistingKnowledge and would silently degrade to Standalone (R2).
+        const completed = await this.core.request({
+            method: 'POST',
+            path: '/api/v1/files/upload/complete',
+            body: {
+                uploadId: session.uploadId,
+                fileRecordId: session.fileRecordId,
+                fileName,
+                fileSize: size,
+                contentType,
+                ...(input.createAs ? { createAs: input.createAs } : {}),
+                ...(input.vaultId ? { vaultId: input.vaultId } : {}),
+                ...(input.title ? { title: input.title } : {}),
+                ...(input.parentKnowledgeId ? { parentKnowledgeId: input.parentKnowledgeId } : {}),
+            },
+            // R6 — the server compares this against SHA-256 lowercase hex.
+            headers: { 'X-File-Hash': fileHash.digest('hex') },
+            schema: CompletedSchema,
+        });
+        return {
+            fileRecordId: completed.fileRecordId,
+            fileName: completed.fileName ?? fileName,
+            size,
+            contentType: completed.contentType ?? contentType,
+        };
+    }
+    /**
+     * PUT one chunk. Retries only what is worth retrying (R8): a 404 means the
+     * session expired or is not ours, so retrying is pointless and misleading —
+     * it propagates immediately and fails the whole file.
+     *
+     * `X-Chunk-Hash` is deliberately NOT sent: the server compares it as base64
+     * MD5 (`ChunkedUploadService.UploadChunkAsync`), not the SHA-256 hex used for
+     * `X-File-Hash`, and it is optional. Whole-file integrity is covered on complete.
+     */
+    async sendChunk(uploadId, chunkIndex, totalChunks, chunk, opts) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                await this.core.rawRequest({
+                    method: 'POST',
+                    path: '/api/v1/files/upload/streaming',
+                    body: chunk,
+                    headers: {
+                        'X-Upload-Id': uploadId,
+                        'X-Chunk-Index': String(chunkIndex),
+                        'X-Total-Chunks': String(totalChunks),
+                    },
+                    schema: z.unknown(),
+                    signal: opts.signal,
+                });
+                return;
+            }
+            catch (e) {
+                if (attempt >= opts.retries || !isRetryableChunkError(e))
+                    throw e;
+                await delay(opts.retryDelayMs * 2 ** attempt);
+            }
+        }
+    }
+}
+//# sourceMappingURL=files.js.map

package/dist/resources/files.js.map

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

package/dist/resources/index.d.ts

@@ -1,6 +1,10 @@
 export { AuthApi } from './auth.js';
+export { ApiKeysApi } from './api-keys.js';
 export { KnowledgeApi } from './knowledge.js';
 export { VaultsApi } from './vaults.js';
 export { SearchApi, type SearchQuery } from './search.js';
 export { AskApi, type AskRequest } from './ask.js';
+export { FilesApi, contentTypeForFile, type UploadInput, type UploadProgress, type UploadedFile, } from './files.js';
+export { PortabilityApi, type PortabilityDialect, type ConflictStrategy, type ExportScopeType, type PortabilitySchema, type ExportScopeInput, type ExportToFileInput, type ExportToFileResult, type ExportJob, type ExportJobPart, type ExportJobStatus, type ImportValidation, type EntityCounts, type ImportOutcome, } from './portability.js';
+export { FederationApi, type FederationPeer, type FederationVaultLink, type FederationRunSummary, type FederationSyncOptionsInput, } from './federation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/resources/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EACL,QAAQ,EACR,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC"}

package/dist/resources/index.js

@@ -1,6 +1,10 @@
 export { AuthApi } from './auth.js';
+export { ApiKeysApi } from './api-keys.js';
 export { KnowledgeApi } from './knowledge.js';
 export { VaultsApi } from './vaults.js';
 export { SearchApi } from './search.js';
 export { AskApi } from './ask.js';
+export { FilesApi, contentTypeForFile, } from './files.js';
+export { PortabilityApi, } from './portability.js';
+export { FederationApi, } from './federation.js';
 //# sourceMappingURL=index.js.map

package/dist/resources/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAmB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAmB,MAAM,UAAU,CAAC;AACnD,OAAO,EACL,QAAQ,EACR,kBAAkB,GAInB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,GAcf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,GAKd,MAAM,iBAAiB,CAAC"}

package/dist/resources/knowledge.d.ts

@@ -7,6 +7,12 @@ export declare class KnowledgeApi {
     create(req: CreateKnowledgeRequest): Promise<KnowledgeDetail>;
     get(id: string): Promise<KnowledgeDetail>;
     update(id: string, req: UpdateKnowledgeRequest): Promise<KnowledgeDetail>;
+    /**
+     * Link an already-uploaded FileRecord to a knowledge item. This is the second
+     * half of the attach flow — `files.upload` completes as Standalone because HTTP
+     * `/complete` cannot express ExistingKnowledge (CLI_KnowledgeAttachUpload R2).
+     */
+    attachFile(knowledgeId: string, fileRecordId: string, displayOrder?: number): Promise<void>;
     remove(id: string): Promise<void>;
     status(id: string): Promise<KnowledgeStatus>;
 }

package/dist/resources/knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/resources/knowledge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,KAAK,EACN,MAAM,gBAAgB,CAAC;AAWxB,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAEvC,IAAI,CAAC,CAAC,GAAE,kBAAuB,GAAG,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAkBlE,MAAM,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IAwBnE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAQnC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IAsBzE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAO7C"}
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/resources/knowledge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,KAAK,EACN,MAAM,gBAAgB,CAAC;AAWxB,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAEvC,IAAI,CAAC,CAAC,GAAE,kBAAuB,GAAG,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAkBlE,MAAM,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IAwBnE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAQnC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IAsB/E;;;;OAIG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS3F,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAO7C"}

package/dist/resources/knowledge.js

@@ -74,6 +74,19 @@ export class KnowledgeApi {
             version: res.version ?? 0,
         };
     }
+    /**
+     * Link an already-uploaded FileRecord to a knowledge item. This is the second
+     * half of the attach flow — `files.upload` completes as Standalone because HTTP
+     * `/complete` cannot express ExistingKnowledge (CLI_KnowledgeAttachUpload R2).
+     */
+    async attachFile(knowledgeId, fileRecordId, displayOrder) {
+        await this.core.request({
+            method: 'POST',
+            path: `/api/v1/knowledge/${encodeURIComponent(knowledgeId)}/attachments`,
+            body: { fileRecordId, ...(displayOrder === undefined ? {} : { displayOrder }) },
+            schema: z.unknown(),
+        });
+    }
     async remove(id) {
         await this.core.request({
             method: 'DELETE',

package/dist/resources/knowledge.js.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../src/resources/knowledge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../src/resources/knowledge.ts"],"names":[],"mappings":"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"}

package/dist/resources/portability.d.ts

@@ -0,0 +1,133 @@
+import type { PortabilityCoreClient, DownloadSpec, DownloadResult } from '../contracts.js';
+export type PortabilityDialect = 'platform' | 'selfhosted';
+export type ConflictStrategy = 'skip' | 'overwrite' | 'merge';
+export type ExportScopeType = 'Tenant' | 'Vault' | 'VaultWithChildren' | 'MultiSelect' | 'SingleItem';
+export interface PortabilitySchema {
+    version: number;
+    minReadableVersion: number;
+    compatibility: string;
+    dialect: PortabilityDialect;
+}
+export interface ExportScopeInput {
+    scopeType: ExportScopeType;
+    vaultIds?: string[];
+    knowledgeItemIds?: string[];
+}
+export interface ExportToFileInput extends ExportScopeInput {
+    mode: 'Light' | 'Full';
+    outPath: string;
+    acknowledgementCopyVersion?: string;
+    onProgress?: (bytesReceived: number, totalBytes?: number) => void;
+}
+export interface ExportToFileResult {
+    path: string;
+    bytes: number;
+    kind: 'json' | 'zip';
+}
+export interface ExportJob {
+    jobId: string;
+    status: string;
+    estimatedItems: number;
+    queuedAt: string;
+}
+export interface ExportJobPart {
+    partNumber: number;
+    downloadUrl: string;
+    sizeBytes: number;
+    fileName: string;
+    itemCount: number;
+}
+export interface ExportJobStatus {
+    jobId: string;
+    status: string;
+    progressPercentage: number;
+    completedAt?: string | null;
+    totalItems: number;
+    errorMessage?: string | null;
+    parts?: ExportJobPart[] | null;
+}
+export interface ImportValidation {
+    isValid: boolean;
+    schemaVersion: number;
+    schemaCompatible: boolean;
+    schemaError?: string | null;
+    sourceEdition?: string | null;
+    totalVaults: number;
+    totalKnowledgeItems: number;
+    totalTopics: number;
+    totalTags: number;
+    totalPersons: number;
+    totalLocations: number;
+    totalEvents: number;
+    totalComments: number;
+    totalFileRecords: number;
+    conflictingVaults: number;
+    conflictingKnowledgeItems: number;
+    conflictingTopics: number;
+    conflictingPersons: number;
+    warnings: string[];
+    errors: string[];
+}
+export interface EntityCounts {
+    created: number;
+    skipped: number;
+    overwritten: number;
+    merged: number;
+}
+export interface ImportOutcome {
+    success: boolean;
+    strategyUsed: number | string;
+    vaults: EntityCounts;
+    knowledgeItems: EntityCounts;
+    topics: EntityCounts;
+    tags: EntityCounts;
+    persons: EntityCounts;
+    locations: EntityCounts;
+    events: EntityCounts;
+    comments: EntityCounts;
+    fileRecords: EntityCounts;
+    junctionsRestored: number;
+    filesBlobFailed: number;
+    warnings: string[];
+    error?: string | null;
+}
+export declare class PortabilityApi {
+    private readonly core;
+    /** Memoized dialect probe — the ONE `GET /schema` preflight (R6). */
+    private schemaProbe?;
+    constructor(core: PortabilityCoreClient);
+    getSchema(): Promise<PortabilitySchema>;
+    private probeSchema;
+    /**
+     * Synchronous export streamed to disk (R1, R4). Light streams the BARE
+     * package JSON byte-identically; Full streams the ZIP. 409 (lock), 413 (use
+     * the job path) and 403 surface as `ApiError` for the caller to map.
+     */
+    exportToFile(input: ExportToFileInput): Promise<ExportToFileResult>;
+    createExportJob(input: ExportScopeInput & {
+        mode: 'Light' | 'Full';
+        acknowledgementCopyVersion?: string;
+    }): Promise<ExportJob>;
+    getExportJob(jobId: string): Promise<ExportJobStatus>;
+    /** Part download over the redirect-safe leg (R3) — the SAS hop carries NO credentials. */
+    downloadExportPart(input: {
+        jobId: string;
+        partNumber: number;
+        outPath: string;
+        onProgress?: DownloadSpec['onProgress'];
+    }): Promise<DownloadResult>;
+    /** Dry-run validation — HTTP 200, central 400-with-envelope and selfhosted bare-422 all PARSE (R2). */
+    validateImport(pkg: unknown): Promise<ImportValidation>;
+    /** JSON import — a 400/422 ImportOutcome is an ANSWER, not an error (R9). Never retried. */
+    importPackage(pkg: unknown, opts: {
+        strategy: ConflictStrategy;
+        targetVaultId?: string;
+    }): Promise<ImportOutcome>;
+    /** ZIP import — multipart field `file` (R6), streamed from disk, no automatic retry. */
+    importZip(input: {
+        path: string;
+        strategy: ConflictStrategy;
+        targetVaultId?: string;
+    }): Promise<ImportOutcome>;
+}
+//# sourceMappingURL=portability.d.ts.map

package/dist/resources/portability.d.ts.map

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