@qzsy/rag-sdk

TypeScript/JavaScript SDK for the ragflow-ingestion integration machine API (/api/integration/v1/*).

Business systems use App Key + Biz User (+ Tenant / End User) to upload corpora, query jobs, list ingested documents, and run retrieval tests.

Install

npm install @qzsy/rag-sdk

Requires Node.js 22+ (monorepo) or modern browser for isomorphic fetch.

Quick start

import { RagflowIngestionClient } from '@qzsy/rag-sdk';

const client = new RagflowIngestionClient({
  baseUrl: 'https://your-ingestion-host:28080',
  appKey: 'app_xxx',
  bizUserId: 'biz-user-1',
  tenantKey: 'ten_xxx',      // multi-tenant only
  endUserId: 'student-001',  // required for upload / retrieval / documents
});

const app = await client.getApp();
console.log(app.mode, app.dataset_id);

const job = await client.upload({
  files: [
    { data: await readFile('sample.pdf'), filename: 'sample.pdf' },
  ],
});
console.log(job.id);

（Node 示例：import { readFile } from 'node:fs/promises'。浏览器可用 File / Blob。）

Browser upload with upload token

Issue a short-lived token on your server (holds App Key), then upload from the browser without exposing keys:

// Server
const { upload_token } = await client.createUploadToken({ end_user_id: 'student-001' });

// Browser (token only)
await client.upload({
  uploadToken: upload_token,
  files: [{ data: fileBlob, filename: file.name }],
});

Upload token only authorizes POST /ingest/upload. Progress, dedup, and jobs still require App Key on the server.

Supported file formats

Server allowlist (also exported from the SDK for client-side validation):

import {
  isSupportedFilename,
  isAudioFilename,
  filterSupportedFilenames,
  SUPPORTED_FILE_HINT,
} from '@qzsy/rag-sdk';

if (!isSupportedFilename(file.name)) {
  throw new Error(`unsupported: ${file.name} (${SUPPORTED_FILE_HINT})`);
}

// Audio: .mp3 / .wav / .aac / .flac / .ogg — passthrough to RAGFlow ASR (chunk_method=audio)
if (isAudioFilename(file.name)) {
  // ensure RAGFlow tenant has Speech2Text (ASR) configured
}

Documents: PDF, Word, PPT, Markdown, TXT, spreadsheets (.xlsx/.xls/.csv), images, audio (see above). Retrieval returns transcribed text chunks like other documents.

API surface (v0.2.5)

Full coverage of /api/integration/v1/* machine routes (see docs/ragflow-ingestion_api.md route table).

| Group | Methods | |-------|---------| | App / tenant | getApp, listTenants, createTenant, resolve | | Shared library | sharedJoin, sharedMembers | | Upload | createUploadToken, upload, getUploadStatus, startUploadDedupCheck, getUploadDedupCheck | | Archive | presignArchive, archiveIngestFromObject | | Jobs | listJobs, getJob, cancelJob | | Documents | listDocuments, listUploads, getDocument, getDocumentDownloads | | Virtual FS | fsTree（limit/offset 文档分页）, fsSearch（全局搜索，v0.2.5+）, fsCreateFolder, fsUpdateFolder, fsDeleteFolder, fsGetDocument, fsUpdateDocument, fsDeleteDocument | | Retrieval / RAG | retrievalTest, ragRetrieve, getRagChunk, getChunkImage, getRagPageImage |

// fs/tree pagination (maps to ?limit=&offset=)
const page = await client.fsTree({ path: '/', enrich: false, limit: 50, offset: 0 });
console.log(page.total_documents, page.documents.length);

// fs/search — global file lookup across all virtual folders
const hits = await client.fsSearch({ q: '通汕', limit: 50 });
console.log(hits.total, hits.documents.map((d) => d.path));

API surface (v0.1.0 legacy)

v0.1.0 covered the upload / jobs / documents / retrieval core; v0.2.0 adds shared join, dedup-check, cancel, fs/*, and image/chunk helpers.

Full HTTP contract: see docs/ragflow-ingestion_api.md in the ragflow-ingestion repository.

Errors

Failed responses throw IngestionApiError with status and message.

Publishing (maintainers)

Global registry may point to a mirror; this package publishes to registry.npmjs.org.

1. Create an npm Access Token (type Automation or Publish) with rights on @qzsy.
2. Set the token (do not commit it):

$env:NPM_TOKEN = "npm_xxxxxxxx"

3. Publish from repo root (auto-picks Node 22 if pnpm is bound to an older Node):

$env:NPM_TOKEN = "npm_xxxxxxxx"
pnpm publish:sdk
# preview only: pnpm publish:sdk -- --dry-run

If pnpm still complains about Node version, run directly:

node scripts/run-node22.mjs scripts/publish-sdk.mjs

Script: scripts/publish-sdk.mjs (checks token, npm whoami, build, npm publish to registry.npmjs.org).

License

MIT