flexorch-sdk 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -36,7 +36,9 @@ declare class Dataset {
         _transport: Transport;
     });
     static fromDict(data: Record<string, unknown>, transport: Transport): Dataset;
-    export(format: ExportFormat): Promise<Uint8Array>;
+    export(format: ExportFormat, opts?: {
+        minQuality?: string;
+    }): Promise<Uint8Array>;
     exportToS3(connectorId: string, format: ExportFormat, prefix?: string): Promise<{
         s3Key: string;
         sizeBytes: number;
@@ -67,16 +69,46 @@ declare class Dataset {
         chunksIndexed: number;
         totalChunks: number;
     }>;
+    /** Preview dataset rows. */
+    rows(opts?: {
+        page?: number;
+        pageSize?: number;
+        q?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Quality/privacy profile — only available once status is "ready". */
+    profile(): Promise<Record<string, unknown>>;
+    /** KVKK/GDPR processing transparency report (Pro+ required). */
+    complianceReport(format?: "json" | "pdf"): Promise<Record<string, unknown> | Uint8Array>;
     toString(): string;
 }
 
+interface JobFeedback {
+    id: string;
+    jobId: string;
+    rating: string;
+    issue: string | null;
+    notes: string | null;
+    createdAt: string;
+}
 declare class Job {
     readonly id: string;
     readonly status: string;
     readonly qualityGrade: string | null;
     readonly qualityScore: number | null;
     readonly documentId: string | null;
+    /** Needed by buildDataset() — POST /datasets/build-from-execution/{executionId}. */
+    readonly executionId: number | null;
     readonly hasDataset: boolean;
+    /**
+     * 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 `records`/columns
+     * may be empty. Read from `execution_summary.degraded`; false for jobs
+     * with no execution (e.g. dataset_build). wait() does not throw for a
+     * degraded completion.
+     */
+    readonly degraded: boolean;
     readonly failureReason: string | null;
     private readonly _transport;
     constructor(data: {
@@ -85,7 +117,9 @@ declare class Job {
         qualityGrade: string | null;
         qualityScore: number | null;
         documentId: string | null;
+        executionId: number | null;
         hasDataset: boolean;
+        degraded: boolean;
         failureReason: string | null;
         _transport: Transport;
     });
@@ -95,6 +129,31 @@ declare class Job {
         pollInterval?: number;
     }): Promise<Job>;
     dataset(): Promise<Dataset | null>;
+    /**
+     * 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).
+     */
+    buildDataset(opts?: {
+        name?: string;
+        description?: string;
+        slug?: string;
+        forceRebuild?: boolean;
+        replaceExisting?: boolean;
+    }): Promise<Job>;
     toString(): string;
 }
 
@@ -133,6 +192,20 @@ declare class JobsResource {
         page?: number;
         pageSize?: number;
     }): Promise<Job[]>;
+    /**
+     * 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".
+     */
+    submitFeedback(jobId: string, rating: "up" | "down", opts?: {
+        issue?: string;
+        notes?: string;
+    }): Promise<JobFeedback>;
+    /** Existing feedback for a job, or null if none was submitted. */
+    getFeedback(jobId: string): Promise<JobFeedback | null>;
 }
 
 declare class DatasetsResource {
@@ -142,22 +215,120 @@ declare class DatasetsResource {
     list(opts?: {
         page?: number;
         pageSize?: number;
+        status?: string;
+        sourceExecutionId?: number;
+        sourceDocumentId?: number;
+        q?: string;
     }): Promise<Dataset[]>;
+    /**
+     * 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()`.
+     */
+    buildFromExecution(executionId: number, opts?: {
+        name?: string;
+        description?: string;
+        slug?: string;
+        forceRebuild?: boolean;
+        replaceExisting?: boolean;
+    }): Promise<Job>;
+}
+
+declare class Document {
+    readonly id: string;
+    readonly filename: string;
+    readonly fileExt: string;
+    readonly status: string;
+    readonly storagePath: string;
+    readonly createdAt: string;
+    readonly processingCount: number;
+    readonly latestExecution: Record<string, unknown> | null;
+    readonly dataset: Record<string, unknown> | null;
+    readonly processingHistory: Record<string, unknown>[];
+    readonly relatedDatasets: Record<string, unknown>[];
+    private readonly _transport;
+    constructor(data: {
+        id: string;
+        filename: string;
+        fileExt: string;
+        status: string;
+        storagePath: string;
+        createdAt: string;
+        processingCount: number;
+        latestExecution: Record<string, unknown> | null;
+        dataset: Record<string, unknown> | null;
+        processingHistory: Record<string, unknown>[];
+        relatedDatasets: Record<string, unknown>[];
+        _transport: Transport;
+    });
+    static fromDict(data: Record<string, unknown>, transport: Transport): Document;
+    /**
+     * 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.
+     */
+    reprocess(pipelineConfig?: Record<string, unknown>): Promise<Job>;
+    toString(): string;
+}
+
+declare class DocumentsResource {
+    private readonly _t;
+    constructor(_t: Transport);
+    /** Fetch a single document, including processingHistory and relatedDatasets. */
+    get(documentId: string): Promise<Document>;
+    /** List documents for the current tenant, newest first. */
+    list(opts?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<Document[]>;
 }
 
 interface UsageSnapshot {
     plan: string;
     creditsUsed: number;
-    creditsLimit: number;
-    creditsRemaining: number;
-    resetAt: string;
-    periodStart: string;
-    periodEnd: string;
+    creditsLimit: number | null;
+    creditsRemaining: number | null;
+    isTrial: boolean;
+    trialEndsAt: string | null;
+    trialDaysRemaining: number | null;
+}
+interface UsageHistoryItem {
+    date: string;
+    creditsUsed: number;
+    jobsCount: number;
+}
+interface QualityTrendItem {
+    date: string;
+    avgQualityScore: number;
+    gradeDistribution: Record<string, number>;
+    avgFieldFillRate: number | null;
+    jobCount: number;
+}
+interface RateLimitStatus {
+    plan: string;
+    unlimited: boolean;
+    limit: number | null;
+    used: number | null;
+    remaining: number | null;
+    windowSeconds: number;
+    resetInSeconds: number | null;
 }
 declare class UsageResource {
     private readonly _t;
     constructor(_t: Transport);
     current(): Promise<UsageSnapshot>;
+    /** @param period "7d" | "30d" | "90d". Default: "30d". */
+    history(period?: string): Promise<UsageHistoryItem[]>;
+    /** @param period "7d" | "30d" | "90d". Default: "30d". */
+    qualityTrend(period?: string): Promise<QualityTrendItem[]>;
+    /** Current rate limit configuration and window usage. Does not consume a request slot. */
+    rateLimits(): Promise<RateLimitStatus>;
 }
 
 type WebhookEvent = "dataset.ready" | "job.completed" | "job.failed";
@@ -209,6 +380,28 @@ interface S3ConnectorConfig {
     secretAccessKey: string;
     prefix?: string;
 }
+interface SyncSchedule {
+    id: string;
+    connectorId: string;
+    cronExpression: string;
+    prefixFilter: string | null;
+    isActive: boolean;
+    lastRunAt: string | null;
+    nextRunAt: string | null;
+    createdAt: string;
+}
+interface SyncLog {
+    id: string;
+    scheduleId: string;
+    startedAt: string;
+    completedAt: string | null;
+    filesFound: number;
+    filesNew: number;
+    filesSkipped: number;
+    filesFailed: number;
+    status: string;
+    errorMessage: string | null;
+}
 
 declare class ConnectorsResource {
     private readonly _t;
@@ -218,6 +411,16 @@ declare class ConnectorsResource {
     get(connectorId: string): Promise<Connector>;
     delete(connectorId: string): Promise<void>;
     test(connectorId: string): Promise<ConnectorTestResult>;
+    /** Define a scheduled sync for a connector (Pro+ required). */
+    createSchedule(connectorId: string, cronExpression: string, prefixFilter?: string | null): Promise<SyncSchedule>;
+    /** Active schedules for a connector. */
+    listSchedules(connectorId: string): Promise<SyncSchedule[]>;
+    /** Delete a scheduled sync. */
+    deleteSchedule(connectorId: string, scheduleId: string): Promise<void>;
+    /** Run a schedule immediately instead of waiting for its cron time. */
+    triggerSchedule(connectorId: string, scheduleId: string): Promise<SyncLog>;
+    /** Recent sync run logs for a schedule. */
+    scheduleLogs(connectorId: string, scheduleId: string): Promise<SyncLog[]>;
 }
 
 interface FlexOrchClientOptions {
@@ -231,6 +434,7 @@ interface FlexOrchClientOptions {
 declare class FlexOrchClient {
     readonly jobs: JobsResource;
     readonly datasets: DatasetsResource;
+    readonly documents: DocumentsResource;
     readonly usage: UsageResource;
     readonly webhooks: WebhooksResource;
     readonly connectors: ConnectorsResource;
@@ -399,6 +603,6 @@ declare class FlexOrchReader {
     toString(): string;
 }
 
-declare const version = "0.2.0";
+declare const version = "0.3.0";
 
-export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, FlexOrchReader, FlexOrchRetriever, Job, JobFailedError, JobTimeoutError, NotFoundError, QuotaError, RAGDocument, RateLimitError, type ReaderLoadOptions, type RetrieverOptions, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };
+export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, Document, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, FlexOrchReader, FlexOrchRetriever, Job, JobFailedError, type JobFeedback, JobTimeoutError, NotFoundError, type QualityTrendItem, QuotaError, RAGDocument, RateLimitError, type RateLimitStatus, type ReaderLoadOptions, type RetrieverOptions, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type SyncLog, type SyncSchedule, type UsageHistoryItem, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };

package/dist/index.d.ts

@@ -36,7 +36,9 @@ declare class Dataset {
         _transport: Transport;
     });
     static fromDict(data: Record<string, unknown>, transport: Transport): Dataset;
-    export(format: ExportFormat): Promise<Uint8Array>;
+    export(format: ExportFormat, opts?: {
+        minQuality?: string;
+    }): Promise<Uint8Array>;
     exportToS3(connectorId: string, format: ExportFormat, prefix?: string): Promise<{
         s3Key: string;
         sizeBytes: number;
@@ -67,16 +69,46 @@ declare class Dataset {
         chunksIndexed: number;
         totalChunks: number;
     }>;
+    /** Preview dataset rows. */
+    rows(opts?: {
+        page?: number;
+        pageSize?: number;
+        q?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Quality/privacy profile — only available once status is "ready". */
+    profile(): Promise<Record<string, unknown>>;
+    /** KVKK/GDPR processing transparency report (Pro+ required). */
+    complianceReport(format?: "json" | "pdf"): Promise<Record<string, unknown> | Uint8Array>;
     toString(): string;
 }
 
+interface JobFeedback {
+    id: string;
+    jobId: string;
+    rating: string;
+    issue: string | null;
+    notes: string | null;
+    createdAt: string;
+}
 declare class Job {
     readonly id: string;
     readonly status: string;
     readonly qualityGrade: string | null;
     readonly qualityScore: number | null;
     readonly documentId: string | null;
+    /** Needed by buildDataset() — POST /datasets/build-from-execution/{executionId}. */
+    readonly executionId: number | null;
     readonly hasDataset: boolean;
+    /**
+     * 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 `records`/columns
+     * may be empty. Read from `execution_summary.degraded`; false for jobs
+     * with no execution (e.g. dataset_build). wait() does not throw for a
+     * degraded completion.
+     */
+    readonly degraded: boolean;
     readonly failureReason: string | null;
     private readonly _transport;
     constructor(data: {
@@ -85,7 +117,9 @@ declare class Job {
         qualityGrade: string | null;
         qualityScore: number | null;
         documentId: string | null;
+        executionId: number | null;
         hasDataset: boolean;
+        degraded: boolean;
         failureReason: string | null;
         _transport: Transport;
     });
@@ -95,6 +129,31 @@ declare class Job {
         pollInterval?: number;
     }): Promise<Job>;
     dataset(): Promise<Dataset | null>;
+    /**
+     * 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).
+     */
+    buildDataset(opts?: {
+        name?: string;
+        description?: string;
+        slug?: string;
+        forceRebuild?: boolean;
+        replaceExisting?: boolean;
+    }): Promise<Job>;
     toString(): string;
 }
 
@@ -133,6 +192,20 @@ declare class JobsResource {
         page?: number;
         pageSize?: number;
     }): Promise<Job[]>;
+    /**
+     * 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".
+     */
+    submitFeedback(jobId: string, rating: "up" | "down", opts?: {
+        issue?: string;
+        notes?: string;
+    }): Promise<JobFeedback>;
+    /** Existing feedback for a job, or null if none was submitted. */
+    getFeedback(jobId: string): Promise<JobFeedback | null>;
 }
 
 declare class DatasetsResource {
@@ -142,22 +215,120 @@ declare class DatasetsResource {
     list(opts?: {
         page?: number;
         pageSize?: number;
+        status?: string;
+        sourceExecutionId?: number;
+        sourceDocumentId?: number;
+        q?: string;
     }): Promise<Dataset[]>;
+    /**
+     * 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()`.
+     */
+    buildFromExecution(executionId: number, opts?: {
+        name?: string;
+        description?: string;
+        slug?: string;
+        forceRebuild?: boolean;
+        replaceExisting?: boolean;
+    }): Promise<Job>;
+}
+
+declare class Document {
+    readonly id: string;
+    readonly filename: string;
+    readonly fileExt: string;
+    readonly status: string;
+    readonly storagePath: string;
+    readonly createdAt: string;
+    readonly processingCount: number;
+    readonly latestExecution: Record<string, unknown> | null;
+    readonly dataset: Record<string, unknown> | null;
+    readonly processingHistory: Record<string, unknown>[];
+    readonly relatedDatasets: Record<string, unknown>[];
+    private readonly _transport;
+    constructor(data: {
+        id: string;
+        filename: string;
+        fileExt: string;
+        status: string;
+        storagePath: string;
+        createdAt: string;
+        processingCount: number;
+        latestExecution: Record<string, unknown> | null;
+        dataset: Record<string, unknown> | null;
+        processingHistory: Record<string, unknown>[];
+        relatedDatasets: Record<string, unknown>[];
+        _transport: Transport;
+    });
+    static fromDict(data: Record<string, unknown>, transport: Transport): Document;
+    /**
+     * 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.
+     */
+    reprocess(pipelineConfig?: Record<string, unknown>): Promise<Job>;
+    toString(): string;
+}
+
+declare class DocumentsResource {
+    private readonly _t;
+    constructor(_t: Transport);
+    /** Fetch a single document, including processingHistory and relatedDatasets. */
+    get(documentId: string): Promise<Document>;
+    /** List documents for the current tenant, newest first. */
+    list(opts?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<Document[]>;
 }
 
 interface UsageSnapshot {
     plan: string;
     creditsUsed: number;
-    creditsLimit: number;
-    creditsRemaining: number;
-    resetAt: string;
-    periodStart: string;
-    periodEnd: string;
+    creditsLimit: number | null;
+    creditsRemaining: number | null;
+    isTrial: boolean;
+    trialEndsAt: string | null;
+    trialDaysRemaining: number | null;
+}
+interface UsageHistoryItem {
+    date: string;
+    creditsUsed: number;
+    jobsCount: number;
+}
+interface QualityTrendItem {
+    date: string;
+    avgQualityScore: number;
+    gradeDistribution: Record<string, number>;
+    avgFieldFillRate: number | null;
+    jobCount: number;
+}
+interface RateLimitStatus {
+    plan: string;
+    unlimited: boolean;
+    limit: number | null;
+    used: number | null;
+    remaining: number | null;
+    windowSeconds: number;
+    resetInSeconds: number | null;
 }
 declare class UsageResource {
     private readonly _t;
     constructor(_t: Transport);
     current(): Promise<UsageSnapshot>;
+    /** @param period "7d" | "30d" | "90d". Default: "30d". */
+    history(period?: string): Promise<UsageHistoryItem[]>;
+    /** @param period "7d" | "30d" | "90d". Default: "30d". */
+    qualityTrend(period?: string): Promise<QualityTrendItem[]>;
+    /** Current rate limit configuration and window usage. Does not consume a request slot. */
+    rateLimits(): Promise<RateLimitStatus>;
 }
 
 type WebhookEvent = "dataset.ready" | "job.completed" | "job.failed";
@@ -209,6 +380,28 @@ interface S3ConnectorConfig {
     secretAccessKey: string;
     prefix?: string;
 }
+interface SyncSchedule {
+    id: string;
+    connectorId: string;
+    cronExpression: string;
+    prefixFilter: string | null;
+    isActive: boolean;
+    lastRunAt: string | null;
+    nextRunAt: string | null;
+    createdAt: string;
+}
+interface SyncLog {
+    id: string;
+    scheduleId: string;
+    startedAt: string;
+    completedAt: string | null;
+    filesFound: number;
+    filesNew: number;
+    filesSkipped: number;
+    filesFailed: number;
+    status: string;
+    errorMessage: string | null;
+}
 
 declare class ConnectorsResource {
     private readonly _t;
@@ -218,6 +411,16 @@ declare class ConnectorsResource {
     get(connectorId: string): Promise<Connector>;
     delete(connectorId: string): Promise<void>;
     test(connectorId: string): Promise<ConnectorTestResult>;
+    /** Define a scheduled sync for a connector (Pro+ required). */
+    createSchedule(connectorId: string, cronExpression: string, prefixFilter?: string | null): Promise<SyncSchedule>;
+    /** Active schedules for a connector. */
+    listSchedules(connectorId: string): Promise<SyncSchedule[]>;
+    /** Delete a scheduled sync. */
+    deleteSchedule(connectorId: string, scheduleId: string): Promise<void>;
+    /** Run a schedule immediately instead of waiting for its cron time. */
+    triggerSchedule(connectorId: string, scheduleId: string): Promise<SyncLog>;
+    /** Recent sync run logs for a schedule. */
+    scheduleLogs(connectorId: string, scheduleId: string): Promise<SyncLog[]>;
 }
 
 interface FlexOrchClientOptions {
@@ -231,6 +434,7 @@ interface FlexOrchClientOptions {
 declare class FlexOrchClient {
     readonly jobs: JobsResource;
     readonly datasets: DatasetsResource;
+    readonly documents: DocumentsResource;
     readonly usage: UsageResource;
     readonly webhooks: WebhooksResource;
     readonly connectors: ConnectorsResource;
@@ -399,6 +603,6 @@ declare class FlexOrchReader {
     toString(): string;
 }
 
-declare const version = "0.2.0";
+declare const version = "0.3.0";
 
-export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, FlexOrchReader, FlexOrchRetriever, Job, JobFailedError, JobTimeoutError, NotFoundError, QuotaError, RAGDocument, RateLimitError, type ReaderLoadOptions, type RetrieverOptions, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };
+export { AuthError, Connector, type ConnectorTestResult, type ConnectorType, Dataset, Document, type ExportFormat, FlexOrchClient, type FlexOrchClientOptions, FlexOrchError, FlexOrchReader, FlexOrchRetriever, Job, JobFailedError, type JobFeedback, JobTimeoutError, NotFoundError, type QualityTrendItem, QuotaError, RAGDocument, RateLimitError, type RateLimitStatus, type ReaderLoadOptions, type RetrieverOptions, type S3ConnectorConfig, type SearchFilters, SearchResult, ServerError, type SyncLog, type SyncSchedule, type UsageHistoryItem, type UsageSnapshot, ValidationError, type Webhook, type WebhookEvent, version };