flexorch-sdk 0.2.2 → 0.3.0

package/README.md

@@ -24,6 +24,7 @@ npm install flexorch-sdk
 
 ```typescript
 import { FlexOrchClient } from "flexorch-sdk";
+import * as fs from "node:fs/promises";
 
 const client = new FlexOrchClient(process.env.FLEXORCH_API_KEY);
 
@@ -32,7 +33,11 @@ const done = await job.wait();
 
 console.log(`Grade: ${done.qualityGrade}  Score: ${done.qualityScore}`);
 
-const dataset = await done.dataset();
+// Building a dataset is a separate, explicit step — a completed job doesn't
+// have one until you build it (lets you build one dataset from several jobs,
+// or re-run with forceRebuild: true).
+const built = await done.buildDataset();
+const dataset = await (await built.wait()).dataset();
 if (dataset) {
   const bytes = await dataset.export("jsonl");
   await fs.writeFile("output.jsonl", bytes);
@@ -52,17 +57,27 @@ The API key is read from `FLEXORCH_API_KEY` if not passed explicitly.
 | Word | `.docx` |
 | Plain text | `.txt` |
 | Markdown | `.md` |
+| Spreadsheets | `.xlsx` |
+| Email | `.eml`, `.msg` |
+| Images (OCR) | `.jpg`, `.png`, `.tiff` |
+| Web | `.html`, `.htm` |
 
 ---
 
 ## Export formats
 
-| Format | Value |
-|--------|-------|
-| JSON Lines | `"jsonl"` |
-| CSV | `"csv"` |
-| Parquet | `"parquet"` |
-| Excel | `"xlsx"` |
+`"json"` · `"jsonl"` · `"csv"` · `"parquet"` · `"md"` · `"xml"` · `"xlsx"` · `"rag"` · `"hf"`
+
+```typescript
+const bytes = await dataset.export("jsonl");
+await fs.writeFile("output.jsonl", bytes);
+
+// rag chunks, only A/B-grade
+const chunks = await dataset.export("rag", { minQuality: "B" });
+```
+
+The `"rag"` format produces LlamaIndex/LangChain-compatible chunks with metadata.
+The `"hf"` format is a zip archive readable with `datasets.load_from_disk()`.
 
 ---
 
@@ -71,13 +86,13 @@ The API key is read from `FLEXORCH_API_KEY` if not passed explicitly.
 ### `new FlexOrchClient(apiKeyOrOptions?)`
 
 ```typescript
-const client = new FlexOrchClient("sk-...");
+const client = new FlexOrchClient("dfx_...");
 // or
 const client = new FlexOrchClient({
-  apiKey: "sk-...",
-  baseUrl: "https://api.flexorch.com",  // default
-  timeout: 30_000,                       // ms, default 30 s
-  maxRetries: 3,                         // default 3
+  apiKey: "dfx_...",
+  baseUrl: "https://api.flexorch.com/v1",  // default
+  timeout: 30,                              // seconds, default 30
+  maxRetries: 3,                            // default 3
 });
 ```
 
@@ -87,7 +102,7 @@ Upload a single file and create a processing job.
 
 ```typescript
 const job = await client.process("invoice.pdf", {
-  locale: "tr",          // BCP-47 locale hint
+  locale: "tr",          // BCP-47 locale hint; "und" = all PII detectors (default)
   pipelineConfig: {},    // optional pipeline overrides
 });
 ```
@@ -96,7 +111,7 @@ Returns a `Job` instance.
 
 ### `client.processMany(files, options?)`
 
-Batch-process multiple files. Returns `Job[]`.
+Batch-process multiple files sequentially. Returns `Job[]`.
 
 ```typescript
 const jobs = await client.processMany(["a.pdf", "b.pdf"], { locale: "en" });
@@ -104,7 +119,7 @@ const jobs = await client.processMany(["a.pdf", "b.pdf"], { locale: "en" });
 
 ### `client.processFromS3(connectorId, keys, options?)`
 
-Import files from S3 via a registered connector. Returns `Job[]`.
+Import files from a registered S3 connector. Returns `Job[]`.
 
 ```typescript
 const jobs = await client.processFromS3(conn.id, ["folder/doc.pdf"], { locale: "de" });
@@ -112,12 +127,16 @@ const jobs = await client.processFromS3(conn.id, ["folder/doc.pdf"], { locale: "
 
 ### `client.search(query, options?)`
 
-Semantic search across all indexed datasets.
+Semantic search across all indexed datasets (Pro+ plan required).
 
 ```typescript
-const results = await client.search("net payment terms", { topK: 5 });
+const results = await client.search("net payment terms", {
+  topK: 5,
+  mode: "auto",  // "auto" | "semantic" | "hybrid" | "structured"
+  filters: { documentType: "invoice", language: "de", qualityGrade: "A", piiMasked: true },
+});
 for (const r of results) {
-  console.log(r.score, r.text);
+  console.log(r.score, r.datasetId, r.text);
 }
 ```
 
@@ -128,24 +147,45 @@ for (const r of results) {
 | Method | Description |
 |--------|-------------|
 | `job.wait(options?)` | Poll until done. Resolves with a completed `Job`. |
-| `job.dataset()` | Fetch the resulting `Dataset` (null if none). |
+| `job.dataset()` | Fetch the dataset built from this job (`null` if none built yet). |
+| `job.buildDataset(options?)` | Build a dataset from this job's execution. Returns a `dataset_build` `Job` — `wait()` it, then call `.dataset()`. |
+
+`wait` options: `{ timeout?: number (seconds), pollInterval?: number (seconds) }`
 
-`wait` options: `{ timeout?: number (seconds), pollInterval?: number (ms) }`
+`buildDataset` options: `{ name?, description?, slug?, forceRebuild?: boolean, replaceExisting?: boolean }`. Throws if the job has no `executionId` (e.g. it failed, or is itself a `dataset_build` job).
 
 Throws `JobFailedError` if the job fails, `JobTimeoutError` if timeout is exceeded.
 
+Key properties: `id`, `status`, `qualityGrade`, `qualityScore`, `documentId`, `executionId`, `hasDataset`, `degraded`, `failureReason`.
+
+`degraded` is `true` when the underlying pipeline execution completed but one or more non-critical steps failed (e.g. structured extraction couldn't find a table in the document). The job still succeeds — PII detection and quality scoring results are still meaningful — but the resulting dataset's records/columns may be empty. `wait()` does not throw for a degraded completion.
+
 ---
 
 ### `Dataset`
 
 | Method | Description |
 |--------|-------------|
-| `dataset.export(format)` | Download dataset as `Buffer`. |
-| `dataset.exportToS3(connectorId, format, prefix?)` | Push export to S3. |
-| `dataset.index()` | Trigger vector indexing. |
+| `dataset.export(format, options?)` | Download dataset as `Uint8Array`. `options.minQuality` only applies to `format="rag"`. |
+| `dataset.exportToS3(connectorId, format, prefix?)` | Push export directly to S3. |
+| `dataset.rows(options?)` | Preview rows — `{ page?, pageSize?, q? }`. |
+| `dataset.profile()` | Quality/privacy profile (grade distribution, PII findings). |
+| `dataset.complianceReport(format?)` | KVKK/GDPR transparency report (Pro+ required). `"json"` (default) or `"pdf"`. |
+| `dataset.index()` | Trigger semantic indexing (Pro+ required). |
 | `dataset.indexStatus()` | Poll index build status. |
+| `dataset.chunks(options?)` | List RAG chunks (Pro+ required). |
+
+Key properties: `id`, `name`, `slug`, `status`, `rowCount`, `createdAt`, `availableFormats`.
 
-Key properties: `id`, `name`, `slug`, `rowCount`, `status`, `qualityGrade`, `qualityScore`, `piiCount`, `createdAt`.
+---
+
+### `client.documents`
+
+```typescript
+await client.documents.list({ page: 1, pageSize: 20 });
+const doc = await client.documents.get(id);  // includes processingHistory, relatedDatasets
+const job = await doc.reprocess();           // re-queue through the pipeline
+```
 
 ---
 
@@ -167,25 +207,41 @@ await client.connectors.get(id);
 await client.connectors.delete(id);
 ```
 
-Supported connector types: `"s3"`. (`"gcs"` and `"azure_blob"` coming in a future release.)
+Connector types: `"s3"` · `"gcs"` · `"azure_blob"` · `"google_drive"` (file sources) and `"pgvector_external"` · `"pinecone"` · `"qdrant"` (vector destinations for dataset indexing).
+
+#### Scheduled sync (Pro+)
+
+```typescript
+const schedule = await client.connectors.createSchedule(conn.id, "0 2 * * *", "invoices/");
+await client.connectors.listSchedules(conn.id);
+await client.connectors.triggerSchedule(conn.id, schedule.id);  // run now
+await client.connectors.scheduleLogs(conn.id, schedule.id);
+await client.connectors.deleteSchedule(conn.id, schedule.id);
+```
 
 ---
 
 ### `client.jobs` / `client.datasets` / `client.usage` / `client.webhooks`
 
 ```typescript
-await client.jobs.list();
+await client.jobs.list({ page: 1, pageSize: 20 });
 await client.jobs.get(id);
-await client.jobs.cancel(id);
+await client.jobs.submitFeedback(id, "down", { issue: "missing_fields", notes: "PO number not extracted" });
+await client.jobs.getFeedback(id);  // null if not submitted
 
 await client.datasets.list();
 await client.datasets.get(id);
-await client.datasets.delete(id);
+await client.datasets.buildFromExecution(executionId, { name: "my-dataset" });  // prefer job.buildDataset() if you have a Job
+
+const usage = await client.usage.current();
+console.log(`${usage.creditsUsed} / ${usage.creditsLimit} credits used (plan: ${usage.plan})`);
+if (usage.isTrial) console.log(`${usage.trialDaysRemaining} trial days left`);
 
-const snap = await client.usage.current();
-// { periodStart, periodEnd, documentsProcessed, documentsLimit, planTier }
+await client.usage.history("30d");       // daily credits + job counts
+await client.usage.qualityTrend("30d");  // daily avg quality score
+await client.usage.rateLimits();         // current window usage, doesn't consume a slot
 
-await client.webhooks.create("https://example.com/hook", ["job.completed"]);
+await client.webhooks.register("https://example.com/hook", ["dataset.ready"]);
 await client.webhooks.list();
 await client.webhooks.delete(id);
 ```
@@ -213,7 +269,7 @@ try {
   if (err instanceof JobFailedError) {
     console.error(`Job ${err.jobId} failed: ${err.failureReason}`);
   } else if (err instanceof QuotaError) {
-    console.error("Monthly document quota exceeded");
+    console.error("Credit limit reached or trial expired");
   } else if (err instanceof RateLimitError) {
     console.error(`Rate limited — retry after ${err.retryAfter}s`);
   } else {
@@ -222,7 +278,7 @@ try {
 }
 ```
 
-All SDK errors extend `FlexOrchError`. HTTP 4xx/5xx responses map to typed error classes automatically.
+All SDK errors extend `FlexOrchError`. HTTP 4xx/5xx responses map to typed error classes automatically. `429`/`5xx` are retried with exponential backoff (up to `maxRetries` attempts).
 
 ---
 
@@ -231,8 +287,8 @@ All SDK errors extend `FlexOrchError`. HTTP 4xx/5xx responses map to typed error
 | Option | Env var | Default |
 |--------|---------|---------|
 | `apiKey` | `FLEXORCH_API_KEY` | — |
-| `baseUrl` | `FLEXORCH_BASE_URL` | `https://api.flexorch.com` |
-| `timeout` | — | `30000` ms |
+| `baseUrl` | — | `https://api.flexorch.com/v1` |
+| `timeout` | — | `30` seconds |
 | `maxRetries` | — | `3` |
 
 ---
@@ -241,7 +297,7 @@ All SDK errors extend `FlexOrchError`. HTTP 4xx/5xx responses map to typed error
 
 | File | Description |
 |------|-------------|
-| [basic-process.ts](examples/basic-process.ts) | Process a single PDF, export JSONL |
+| [basic-process.ts](examples/basic-process.ts) | Process a single PDF, build a dataset, export JSONL |
 | [batch-process.ts](examples/batch-process.ts) | Process a directory, collect datasets |
 | [s3-import.ts](examples/s3-import.ts) | Register S3 connector, import, export back |
 
@@ -252,7 +308,7 @@ All SDK errors extend `FlexOrchError`. HTTP 4xx/5xx responses map to typed error
 ```bash
 npm install
 npm run build     # ESM + CJS + .d.ts
-npm test          # 36 tests via vitest
+npm test          # vitest
 npm run typecheck # tsc --noEmit
 ```
 

package/dist/{chunk-35RGZSFP.js → chunk-4KCMMRD7.js}

@@ -43,11 +43,12 @@ var Dataset = class _Dataset {
       _transport: transport
     });
   }
-  async export(format) {
+  async export(format, opts = {}) {
     if (!SUPPORTED_FORMATS.has(format)) {
       throw new Error(`Unsupported format "${format}". Choose from: ${[...SUPPORTED_FORMATS].sort().join(", ")}`);
     }
-    return this._transport.getBytes(`/datasets/${this.id}/export`, { format });
+    const params = opts.minQuality !== void 0 ? { min_quality: opts.minQuality } : void 0;
+    return this._transport.getBytes(`/datasets/${this.id}/export/${format}`, params);
   }
   async exportToS3(connectorId, format, prefix = "") {
     if (!SUPPORTED_FORMATS.has(format)) {
@@ -99,6 +100,25 @@ var Dataset = class _Dataset {
       totalChunks: Number(data["total_chunks"] ?? 0)
     };
   }
+  /** Preview dataset rows. */
+  async rows(opts = {}) {
+    const params = {};
+    if (opts.page !== void 0) params["page"] = String(opts.page);
+    if (opts.pageSize !== void 0) params["page_size"] = String(opts.pageSize);
+    if (opts.q !== void 0) params["q"] = opts.q;
+    return await this._transport.get(`/datasets/${this.id}/rows`, params) ?? {};
+  }
+  /** Quality/privacy profile — only available once status is "ready". */
+  async profile() {
+    return await this._transport.get(`/datasets/${this.id}/profile`) ?? {};
+  }
+  /** KVKK/GDPR processing transparency report (Pro+ required). */
+  async complianceReport(format = "json") {
+    if (format === "pdf") {
+      return this._transport.getBytes(`/datasets/${this.id}/compliance-report`, { format: "pdf" });
+    }
+    return await this._transport.get(`/datasets/${this.id}/compliance-report`, { format }) ?? {};
+  }
   toString() {
     return `Dataset(id=${this.id}, name=${this.name}, rows=${this.rowCount}, status=${this.status})`;
   }

package/dist/{dataset-PP755LIW.js → dataset-E7EXJETI.js}

@@ -1,6 +1,6 @@
 import {
   Dataset
-} from "./chunk-35RGZSFP.js";
+} from "./chunk-4KCMMRD7.js";
 export {
   Dataset
 };