flexorch-sdk 0.2.3 → 0.3.1

package/dist/index.cjs

@@ -83,11 +83,12 @@ var init_dataset = __esm({
           _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)) {
@@ -139,6 +140,25 @@ var init_dataset = __esm({
           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})`;
       }
@@ -152,6 +172,7 @@ __export(index_exports, {
   AuthError: () => AuthError,
   Connector: () => Connector,
   Dataset: () => Dataset,
+  Document: () => Document,
   FlexOrchClient: () => FlexOrchClient,
   FlexOrchError: () => FlexOrchError,
   FlexOrchReader: () => FlexOrchReader,
@@ -272,6 +293,12 @@ async function parseError(res) {
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+function unwrap(body) {
+  if (body !== null && typeof body === "object" && "data" in body && "error" in body && typeof body["status"] === "string") {
+    return body["data"];
+  }
+  return body;
+}
 var Transport = class {
   baseUrl;
   defaultHeaders;
@@ -285,7 +312,7 @@ var Transport = class {
     this.fetchFn = fetchFn ?? globalThis.fetch.bind(globalThis);
     this.defaultHeaders = {
       "X-API-KEY": apiKey,
-      "User-Agent": "flexorch-sdk-js/0.1.0"
+      "User-Agent": "flexorch-sdk-js/0.3.1"
     };
   }
   url(path, params) {
@@ -326,7 +353,7 @@ var Transport = class {
         if (!ct.includes("application/json")) return null;
         const text = await res.text();
         if (!text.trim()) return null;
-        return JSON.parse(text);
+        return unwrap(JSON.parse(text));
       } catch (err) {
         clearTimeout(timer);
         if (err instanceof FlexOrchError) throw err;
@@ -359,13 +386,27 @@ var Transport = class {
 };
 
 // src/models/job.ts
+function jobFeedbackFromDict(data) {
+  return {
+    id: String(data["id"] ?? ""),
+    jobId: String(data["job_id"] ?? ""),
+    rating: String(data["rating"] ?? ""),
+    issue: data["issue"] ?? null,
+    notes: data["notes"] ?? null,
+    createdAt: String(data["created_at"] ?? "")
+  };
+}
 var Job = class _Job {
   id;
   status;
   qualityGrade;
   qualityScore;
   documentId;
+  /** Needed by buildDataset() — POST /datasets/build-from-execution/{executionId}. */
+  executionId;
   hasDataset;
+  /** Set from `dataset_summary.dataset_id` on a completed dataset_build job's response. */
+  datasetId;
   /**
    * True when the underlying pipeline execution completed but one or more
    * non-critical steps failed (e.g. structured extraction couldn't find a
@@ -384,21 +425,37 @@ var Job = class _Job {
     this.qualityGrade = data.qualityGrade;
     this.qualityScore = data.qualityScore;
     this.documentId = data.documentId;
+    this.executionId = data.executionId;
     this.hasDataset = data.hasDataset;
+    this.datasetId = data.datasetId;
     this.degraded = data.degraded;
     this.failureReason = data.failureReason;
     this._transport = data._transport;
   }
   static fromDict(data, transport) {
-    const quality = data["quality"] ?? {};
     const executionSummary = data["execution_summary"];
+    const processingSummary = data["processing_summary"];
+    const datasetSummary = data["dataset_summary"];
+    let quality = data["quality"];
+    if (!quality && processingSummary) {
+      quality = processingSummary["quality"];
+    }
+    quality = quality ?? {};
+    const executionId = executionSummary?.["execution_id"] ?? processingSummary?.["execution_id"] ?? data["execution_id"] ?? null;
     return new _Job({
       id: String(data["job_id"] ?? data["id"] ?? ""),
       status: String(data["status"] ?? ""),
       qualityGrade: quality["grade"] ?? null,
       qualityScore: quality["score"] ?? null,
       documentId: data["document_id"] ?? null,
-      hasDataset: Boolean(data["has_dataset"] ?? false),
+      executionId,
+      // dataset_summary is only present on a completed dataset_build job's
+      // response — neither has_dataset nor processing_summary is ever set
+      // for that job type, so without this .dataset() always returned null
+      // for the job.buildDataset().wait().dataset() chain even though the
+      // dataset had been built successfully.
+      hasDataset: Boolean(data["has_dataset"] ?? processingSummary?.["has_dataset"] ?? Boolean(datasetSummary) ?? false),
+      datasetId: datasetSummary?.["dataset_id"] ?? null,
       degraded: Boolean(executionSummary?.["degraded"] ?? false),
       failureReason: data["failure_reason"] ?? null,
       _transport: transport
@@ -426,15 +483,56 @@ var Job = class _Job {
     throw new JobTimeoutError(this.id, timeout);
   }
   async dataset() {
+    const { Dataset: Dataset2 } = await Promise.resolve().then(() => (init_dataset(), dataset_exports));
+    if (this.datasetId !== null) {
+      const data2 = await this._transport.get(`/datasets/${this.datasetId}`);
+      return Dataset2.fromDict(data2, this._transport);
+    }
     if (!this.hasDataset) return null;
     const data = await this._transport.get("/datasets", {
       job_id: this.id
     });
     const items = data["items"] ?? [];
     if (items.length === 0) return null;
-    const { Dataset: Dataset2 } = await Promise.resolve().then(() => (init_dataset(), dataset_exports));
     return Dataset2.fromDict(items[0], this._transport);
   }
+  /**
+   * Build a dataset from this job's execution.
+   *
+   * A completed data_process job does not have a dataset yet — building one
+   * is a separate, explicit step (`POST
+   * /datasets/build-from-execution/{executionId}`). Call this after
+   * `.wait()`, then `.wait()` again on the returned dataset_build Job before
+   * calling `.dataset()`:
+   *
+   * ```ts
+   * const job = await client.process("invoice.pdf");
+   * const done = await job.wait();
+   * const dataset = await (await done.buildDataset()).wait().then(j => j.dataset());
+   * ```
+   *
+   * @throws {Error} If this job has no executionId to build a dataset from
+   *   (e.g. it failed, or is itself a dataset_build job).
+   */
+  async buildDataset(opts = {}) {
+    if (!this.executionId) {
+      throw new Error(
+        `Job ${this.id} has no executionId to build a dataset from (job must be a completed data_process job).`
+      );
+    }
+    const body = {
+      force_rebuild: opts.forceRebuild ?? false,
+      replace_existing: opts.replaceExisting ?? false
+    };
+    if (opts.name !== void 0) body["name"] = opts.name;
+    if (opts.description !== void 0) body["description"] = opts.description;
+    if (opts.slug !== void 0) body["slug"] = opts.slug;
+    const data = await this._transport.post(
+      `/datasets/build-from-execution/${this.executionId}`,
+      body
+    );
+    return _Job.fromDict(data, this._transport);
+  }
   toString() {
     return `Job(id=${this.id}, status=${this.status}, grade=${this.qualityGrade})`;
   }
@@ -478,6 +576,15 @@ var SearchResult = class _SearchResult {
 };
 
 // src/resources/jobs.ts
+var VALID_RATINGS = /* @__PURE__ */ new Set(["up", "down"]);
+var VALID_ISSUES = /* @__PURE__ */ new Set([
+  "wrong_doc_type",
+  "missing_fields",
+  "wrong_values",
+  "pii_missed",
+  "pii_over_masked",
+  "other"
+]);
 var JobsResource = class {
   constructor(_t) {
     this._t = _t;
@@ -495,6 +602,34 @@ var JobsResource = class {
     const items = data["items"] ?? [];
     return items.map((item) => Job.fromDict(item, this._t));
   }
+  /**
+   * Submit user feedback for a completed job. Upsert — a second call for the
+   * same job replaces the previous feedback.
+   *
+   * @param rating "up" or "down".
+   * @param opts.issue When rating="down": "wrong_doc_type" | "missing_fields" |
+   *   "wrong_values" | "pii_missed" | "pii_over_masked" | "other".
+   */
+  async submitFeedback(jobId, rating, opts = {}) {
+    if (!VALID_RATINGS.has(rating)) {
+      throw new Error(`Invalid rating "${rating}". Valid: ${[...VALID_RATINGS].join(", ")}`);
+    }
+    if (opts.issue !== void 0 && !VALID_ISSUES.has(opts.issue)) {
+      throw new Error(`Invalid issue "${opts.issue}". Valid: ${[...VALID_ISSUES].join(", ")}`);
+    }
+    const data = await this._t.post(`/jobs/${jobId}/feedback`, {
+      rating,
+      issue: opts.issue ?? null,
+      notes: opts.notes ?? null
+    });
+    return jobFeedbackFromDict(data);
+  }
+  /** Existing feedback for a job, or null if none was submitted. */
+  async getFeedback(jobId) {
+    const data = await this._t.get(`/jobs/${jobId}/feedback`);
+    if (!data) return null;
+    return jobFeedbackFromDict(data);
+  }
 };
 
 // src/resources/datasets.ts
@@ -512,10 +647,121 @@ var DatasetsResource = class {
     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.status !== void 0) params["status"] = opts.status;
+    if (opts.sourceExecutionId !== void 0) params["source_execution_id"] = String(opts.sourceExecutionId);
+    if (opts.sourceDocumentId !== void 0) params["source_document_id"] = String(opts.sourceDocumentId);
+    if (opts.q !== void 0) params["q"] = opts.q;
     const data = await this._t.get("/datasets", params);
     const items = data["items"] ?? [];
     return items.map((item) => Dataset.fromDict(item, this._t));
   }
+  /**
+   * Build a dataset from a completed execution.
+   *
+   * Prefer `Job.buildDataset()` when you already have a Job object — this is
+   * the lower-level call for when you only have an executionId (e.g. from
+   * `Document.latestExecution`).
+   *
+   * @returns A dataset_build Job — call `.wait()` then `.dataset()`.
+   */
+  async buildFromExecution(executionId, opts = {}) {
+    const body = {
+      force_rebuild: opts.forceRebuild ?? false,
+      replace_existing: opts.replaceExisting ?? false
+    };
+    if (opts.name !== void 0) body["name"] = opts.name;
+    if (opts.description !== void 0) body["description"] = opts.description;
+    if (opts.slug !== void 0) body["slug"] = opts.slug;
+    const data = await this._t.post(
+      `/datasets/build-from-execution/${executionId}`,
+      body
+    );
+    return Job.fromDict(data, this._t);
+  }
+};
+
+// src/models/document.ts
+var Document = class _Document {
+  id;
+  filename;
+  fileExt;
+  status;
+  storagePath;
+  createdAt;
+  processingCount;
+  latestExecution;
+  dataset;
+  processingHistory;
+  relatedDatasets;
+  _transport;
+  constructor(data) {
+    this.id = data.id;
+    this.filename = data.filename;
+    this.fileExt = data.fileExt;
+    this.status = data.status;
+    this.storagePath = data.storagePath;
+    this.createdAt = data.createdAt;
+    this.processingCount = data.processingCount;
+    this.latestExecution = data.latestExecution;
+    this.dataset = data.dataset;
+    this.processingHistory = data.processingHistory;
+    this.relatedDatasets = data.relatedDatasets;
+    this._transport = data._transport;
+  }
+  static fromDict(data, transport) {
+    return new _Document({
+      id: String(data["id"] ?? ""),
+      filename: String(data["filename"] ?? ""),
+      fileExt: String(data["file_ext"] ?? ""),
+      status: String(data["status"] ?? ""),
+      storagePath: String(data["storage_path"] ?? ""),
+      createdAt: String(data["created_at"] ?? ""),
+      processingCount: Number(data["processing_count"] ?? 0),
+      latestExecution: data["latest_execution"] ?? null,
+      dataset: data["dataset"] ?? null,
+      processingHistory: data["processing_history"] ?? [],
+      relatedDatasets: data["related_datasets"] ?? [],
+      _transport: transport
+    });
+  }
+  /**
+   * Re-queue this document through the processing pipeline.
+   *
+   * Raises (via the API): 400 DOCUMENT_FILE_NOT_AVAILABLE if the source file
+   * is no longer on disk, or 400 REPROCESS_NOT_SUPPORTED for
+   * connector-sourced (e.g. S3) documents.
+   */
+  async reprocess(pipelineConfig) {
+    const body = {};
+    if (pipelineConfig) body["pipeline_config"] = pipelineConfig;
+    const data = await this._transport.post(`/documents/${this.id}/reprocess`, body);
+    return Job.fromDict(data, this._transport);
+  }
+  toString() {
+    return `Document(id=${this.id}, filename=${this.filename}, status=${this.status})`;
+  }
+};
+
+// src/resources/documents.ts
+var DocumentsResource = class {
+  constructor(_t) {
+    this._t = _t;
+  }
+  _t;
+  /** Fetch a single document, including processingHistory and relatedDatasets. */
+  async get(documentId) {
+    const data = await this._t.get(`/documents/${documentId}`);
+    return Document.fromDict(data, this._t);
+  }
+  /** List documents for the current tenant, newest first. */
+  async list(opts = {}) {
+    const params = {};
+    if (opts.page !== void 0) params["page"] = String(opts.page);
+    if (opts.pageSize !== void 0) params["page_size"] = String(opts.pageSize);
+    const data = await this._t.get("/documents", params);
+    const items = data["items"] ?? [];
+    return items.map((item) => Document.fromDict(item, this._t));
+  }
 };
 
 // src/resources/usage.ts
@@ -525,15 +771,51 @@ var UsageResource = class {
   }
   _t;
   async current() {
-    const data = await this._t.get("/usage/current");
+    const data = await this._t.get("/usage") ?? {};
+    const trial = data["trial"] ?? {};
+    const usage = data["usage"] ?? {};
+    const credits = usage["credits"] ?? {};
+    return {
+      plan: String(data["plan"] ?? ""),
+      creditsUsed: Number(credits["used"] ?? 0),
+      creditsLimit: credits["limit"] ?? null,
+      creditsRemaining: credits["remaining"] ?? null,
+      isTrial: Boolean(trial["is_trial"] ?? false),
+      trialEndsAt: trial["trial_ends_at"] ?? null,
+      trialDaysRemaining: trial["trial_days_remaining"] ?? null
+    };
+  }
+  /** @param period "7d" | "30d" | "90d". Default: "30d". */
+  async history(period = "30d") {
+    const data = await this._t.get("/usage/history", { period });
+    return (data ?? []).map((item) => ({
+      date: String(item["date"] ?? ""),
+      creditsUsed: Number(item["credits_used"] ?? 0),
+      jobsCount: Number(item["jobs_count"] ?? 0)
+    }));
+  }
+  /** @param period "7d" | "30d" | "90d". Default: "30d". */
+  async qualityTrend(period = "30d") {
+    const data = await this._t.get("/usage/quality-trend", { period });
+    return (data ?? []).map((item) => ({
+      date: String(item["date"] ?? ""),
+      avgQualityScore: Number(item["avg_quality_score"] ?? 0),
+      gradeDistribution: item["grade_distribution"] ?? {},
+      avgFieldFillRate: item["avg_field_fill_rate"] ?? null,
+      jobCount: Number(item["job_count"] ?? 0)
+    }));
+  }
+  /** Current rate limit configuration and window usage. Does not consume a request slot. */
+  async rateLimits() {
+    const data = await this._t.get("/usage/rate-limits") ?? {};
     return {
       plan: String(data["plan"] ?? ""),
-      creditsUsed: Number(data["credits_used"] ?? 0),
-      creditsLimit: Number(data["credits_limit"] ?? 0),
-      creditsRemaining: Number(data["credits_remaining"] ?? 0),
-      resetAt: String(data["reset_at"] ?? ""),
-      periodStart: String(data["period_start"] ?? ""),
-      periodEnd: String(data["period_end"] ?? "")
+      unlimited: Boolean(data["unlimited"] ?? false),
+      limit: data["limit"] ?? null,
+      used: data["used"] ?? null,
+      remaining: data["remaining"] ?? null,
+      windowSeconds: Number(data["window_seconds"] ?? 0),
+      resetInSeconds: data["reset_in_seconds"] ?? null
     };
   }
 };
@@ -605,6 +887,32 @@ var Connector = class _Connector {
     return `Connector(id=${this.id}, name=${this.name}, type=${this.type})`;
   }
 };
+function syncScheduleFromDict(data) {
+  return {
+    id: String(data["id"] ?? ""),
+    connectorId: String(data["connector_id"] ?? ""),
+    cronExpression: String(data["cron_expression"] ?? ""),
+    prefixFilter: data["prefix_filter"] ?? null,
+    isActive: Boolean(data["is_active"] ?? true),
+    lastRunAt: data["last_run_at"] ?? null,
+    nextRunAt: data["next_run_at"] ?? null,
+    createdAt: String(data["created_at"] ?? "")
+  };
+}
+function syncLogFromDict(data) {
+  return {
+    id: String(data["id"] ?? ""),
+    scheduleId: String(data["schedule_id"] ?? ""),
+    startedAt: String(data["started_at"] ?? ""),
+    completedAt: data["completed_at"] ?? null,
+    filesFound: Number(data["files_found"] ?? 0),
+    filesNew: Number(data["files_new"] ?? 0),
+    filesSkipped: Number(data["files_skipped"] ?? 0),
+    filesFailed: Number(data["files_failed"] ?? 0),
+    status: String(data["status"] ?? ""),
+    errorMessage: data["error_message"] ?? null
+  };
+}
 
 // src/resources/connectors.ts
 var VALID_TYPES = /* @__PURE__ */ new Set([
@@ -648,13 +956,54 @@ var ConnectorsResource = class {
       message: String(data["message"] ?? "")
     };
   }
+  /** Define a scheduled sync for a connector (Pro+ required). */
+  async createSchedule(connectorId, cronExpression, prefixFilter = null) {
+    const data = await this._t.post(`/connectors/${connectorId}/schedules`, {
+      cron_expression: cronExpression,
+      prefix_filter: prefixFilter
+    });
+    return syncScheduleFromDict(data);
+  }
+  /** Active schedules for a connector. */
+  async listSchedules(connectorId) {
+    const data = await this._t.get(`/connectors/${connectorId}/schedules`);
+    return (data ?? []).map(syncScheduleFromDict);
+  }
+  /** Delete a scheduled sync. */
+  async deleteSchedule(connectorId, scheduleId) {
+    await this._t.delete(`/connectors/${connectorId}/schedules/${scheduleId}`);
+  }
+  /** Run a schedule immediately instead of waiting for its cron time. */
+  async triggerSchedule(connectorId, scheduleId) {
+    const data = await this._t.post(
+      `/connectors/${connectorId}/schedules/${scheduleId}/trigger`
+    );
+    return syncLogFromDict(data);
+  }
+  /** Recent sync run logs for a schedule. */
+  async scheduleLogs(connectorId, scheduleId) {
+    const data = await this._t.get(
+      `/connectors/${connectorId}/schedules/${scheduleId}/logs`
+    );
+    return (data ?? []).map(syncLogFromDict);
+  }
 };
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.flexorch.com/v1";
+function firstJobOrThrow(uploadResponse, filename, transport) {
+  const jobs = uploadResponse["jobs"] ?? [];
+  if (jobs.length > 0) {
+    return Job.fromDict(jobs[0], transport);
+  }
+  const rejected = uploadResponse["rejected"] ?? [];
+  const reason = rejected.length > 0 ? String(rejected[0]["error"]) : "unknown error";
+  throw new ValidationError(`${filename} was rejected: ${reason}`);
+}
 var FlexOrchClient = class {
   jobs;
   datasets;
+  documents;
   usage;
   webhooks;
   connectors;
@@ -676,6 +1025,7 @@ var FlexOrchClient = class {
     );
     this.jobs = new JobsResource(this._transport);
     this.datasets = new DatasetsResource(this._transport);
+    this.documents = new DocumentsResource(this._transport);
     this.usage = new UsageResource(this._transport);
     this.webhooks = new WebhooksResource(this._transport);
     this.connectors = new ConnectorsResource(this._transport);
@@ -693,13 +1043,13 @@ var FlexOrchClient = class {
       chunks.push(chunk);
     }
     const blob = new Blob([Buffer.concat(chunks)], { type: "application/octet-stream" });
-    form.append("file", blob, basename(filePath));
+    form.append("files", blob, basename(filePath));
     form.append("locale", opts.locale ?? "und");
     if (opts.pipelineConfig) {
       form.append("pipeline_config", JSON.stringify(opts.pipelineConfig));
     }
     const data = await this._transport.postForm("/data-process/async", form);
-    return Job.fromDict(data, this._transport);
+    return firstJobOrThrow(data, basename(filePath), this._transport);
   }
   async processMany(filePaths, opts = {}) {
     const jobs = [];
@@ -718,7 +1068,7 @@ var FlexOrchClient = class {
         form.append("pipeline_config", JSON.stringify(opts.pipelineConfig));
       }
       const data = await this._transport.postForm("/data-process/async", form);
-      jobs.push(Job.fromDict(data, this._transport));
+      jobs.push(firstJobOrThrow(data, key, this._transport));
     }
     return jobs;
   }
@@ -925,12 +1275,13 @@ var FlexOrchReader = class {
 };
 
 // src/index.ts
-var version = "0.2.3";
+var version = "0.3.1";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,
   Connector,
   Dataset,
+  Document,
   FlexOrchClient,
   FlexOrchError,
   FlexOrchReader,