@narrative.io/data-collaboration-sdk-ts 2.105.0 → 2.106.0

package/build/forecast/types.d.ts

@@ -72,7 +72,7 @@ export interface ForecastDimensions {
     distinct_counts: string[];
     group_by?: string;
 }
-export type JobState = "pending" | "running" | "completed" | "cancelled" | "failed";
+export type JobState = "pending" | "running" | "completed" | "pending_cancellation" | "cancelled" | "failed";
 export interface ForecastResult {
     cost: number;
     datasets: DatasetForecastResponse[];

package/build/jobs/index.d.ts

@@ -1,6 +1,7 @@
 import { BaseApi } from "../base-api";
 import type { ApiRecords } from "../types";
-import type { ColumnDetails, DatasetsCalculateColumnStatsJob, DatasetsDeleteTableJob, DatasetsDeliverDataJob, DatasetsSampleJob, DeleteInput, DeliverInput, ExplainInput, ExplainJob, ExplainOutput, ForecastInput, ForecastJob, Job, JobRequestSource, JobRequestSourceApiUser, JobRequestSourceProcess, MaterializedViewInput, MaterializedViewJob, MaterializedViewOutput, ModelInferenceRunInput, ModelInferenceRunJob, ModelInferenceRunJobResult, ModelsDeliverModelInput, ModelsDeliverModelJob, ModelTrainingRunInput, ModelTrainingRunJob, SampleInput, StatsInput } from "./types";
+import type { CalculateAffectedRowsInput, CalculateAffectedRowsJob, CollectAccessRulesBillingDataInput, CollectAccessRulesBillingDataJob, CollectAccessRulesBillingDataResult, ColumnDetails, ColumnStatDataType, CostsInput, CostsJob, CreateTableInput, DatasetsCalculateColumnStatsJob, DatasetsCreateTableJob, DatasetsDeleteTableJob, DatasetsDeliverDataJob, DatasetsEnforceRowTtlRetentionPolicyJob, DatasetsEnforceTableTtlRetentionPolicyJob, DatasetsExecuteDmlJob, DatasetsExecuteSelectJob, DatasetsSampleJob, DatasetsSuggestMappingsJob, DatasetsTruncateTableJob, DeleteInput, DeliverInput, EnabledColumnStatFlags, EnforceRowTtlRetentionPolicyInput, EnforceTableTtlRetentionPolicyInput, ExecuteDmlInput, ExecuteDmlResult, ExecuteSelectInput, ExecuteSelectResult, ExplainInput, ExplainJob, ExplainOutput, ForecastInput, ForecastInternalJob, ForecastJob, HealthCheckJob, Job, JobExecutionCluster, JobRequestSource, JobRequestSourceApiUser, JobRequestSourceProcess, JobType, KnownJob, MaterializedViewInput, MaterializedViewJob, MaterializedViewOutput, MaterializedViewRowStats, ModelInferenceRunInput, ModelInferenceRunJob, ModelInferenceRunJobResult, ModelsDeliverModelInput, ModelsDeliverModelJob, ModelsTrainClassifierJob, ModelTrainingRunInput, ModelTrainingRunJob, RefreshMaterializedViewResult, SampleInput, StatsInput, StatsInputV2, SuggestMappingsInput, SuggestMappingsResult, TruncateTableInput } from "./types";
+import { isKnownJob, KNOWN_JOB_TYPES } from "./types";
 interface GetJobsParameters extends Record<string, string | number | boolean | undefined> {
     dataset_id?: number;
     per_page?: number;
@@ -31,4 +32,4 @@ declare class JobsApi extends BaseApi {
      */
     cancelJob(jobId: string): Promise<void>;
 }
-export { type ColumnDetails, type DatasetsCalculateColumnStatsJob, type DatasetsDeleteTableJob, type DatasetsDeliverDataJob, type DatasetsSampleJob, type DeleteInput, type DeliverInput, type ExplainInput, type ExplainJob, type ExplainOutput, type ForecastInput, type ForecastJob, type GetJobsParameters, type Job, type JobRequestSource, type JobRequestSourceApiUser, type JobRequestSourceProcess, JobsApi, type MaterializedViewInput, type MaterializedViewJob, type MaterializedViewOutput, type ModelInferenceRunInput, type ModelInferenceRunJob, type ModelInferenceRunJobResult, type ModelsDeliverModelInput, type ModelsDeliverModelJob, type ModelTrainingRunInput, type ModelTrainingRunJob, type SampleInput, type StatsInput, };
+export { type CalculateAffectedRowsInput, type CalculateAffectedRowsJob, type CollectAccessRulesBillingDataInput, type CollectAccessRulesBillingDataJob, type CollectAccessRulesBillingDataResult, type ColumnDetails, type ColumnStatDataType, type CostsInput, type CostsJob, type CreateTableInput, type DatasetsCalculateColumnStatsJob, type DatasetsCreateTableJob, type DatasetsDeleteTableJob, type DatasetsDeliverDataJob, type DatasetsEnforceRowTtlRetentionPolicyJob, type DatasetsEnforceTableTtlRetentionPolicyJob, type DatasetsExecuteDmlJob, type DatasetsExecuteSelectJob, type DatasetsSampleJob, type DatasetsSuggestMappingsJob, type DatasetsTruncateTableJob, type DeleteInput, type DeliverInput, type EnabledColumnStatFlags, type EnforceRowTtlRetentionPolicyInput, type EnforceTableTtlRetentionPolicyInput, type ExecuteDmlInput, type ExecuteDmlResult, type ExecuteSelectInput, type ExecuteSelectResult, type ExplainInput, type ExplainJob, type ExplainOutput, type ForecastInput, type ForecastInternalJob, type ForecastJob, type GetJobsParameters, type HealthCheckJob, isKnownJob, type Job, type JobExecutionCluster, type JobRequestSource, type JobRequestSourceApiUser, type JobRequestSourceProcess, JobsApi, type JobType, KNOWN_JOB_TYPES, type KnownJob, type MaterializedViewInput, type MaterializedViewJob, type MaterializedViewOutput, type MaterializedViewRowStats, type ModelInferenceRunInput, type ModelInferenceRunJob, type ModelInferenceRunJobResult, type ModelsDeliverModelInput, type ModelsDeliverModelJob, type ModelsTrainClassifierJob, type ModelTrainingRunInput, type ModelTrainingRunJob, type RefreshMaterializedViewResult, type SampleInput, type StatsInput, type StatsInputV2, type SuggestMappingsInput, type SuggestMappingsResult, type TruncateTableInput, };

package/build/jobs/index.js

@@ -1,4 +1,5 @@
 import { BaseApi } from "../base-api";
+import { isKnownJob, KNOWN_JOB_TYPES } from "./types";
 const resourceName = "jobs";
 /**
  * @module JobsApi
@@ -29,4 +30,4 @@ class JobsApi extends BaseApi {
         await this.post(`${resourceName}/${jobId}/request-cancellation`);
     }
 }
-export { JobsApi, };
+export { isKnownJob, JobsApi, KNOWN_JOB_TYPES, };

package/build/jobs/types.d.ts

@@ -1,26 +1,40 @@
 import type { ForecastResult, JobState } from "src/forecast";
 import type { DataStreamPurchaseDetails, ForecastDimensions, MarketplaceForecastDetails } from "src/forecast/types";
 import type { NqlBudget } from "src/nql/types";
-export type JobType = "forecast" | "nql-forecast" | "materialize-view" | "datasets_calculate_column_stats" | "datasets_delete_table" | "datasets_deliver_data" | "datasets_sample" | "models_deliver_model" | "models_train_classifier" | "model_training_run" | "model_inference_run";
-export interface JobRequestSource {
-    type: string;
+/**
+ * Every job type the backend can persist and return from the /jobs API.
+ * The backend's `Job.Type` is an open string, so treat this list as the
+ * known set rather than a closed enum — see {@link UnknownJob}.
+ */
+export declare const KNOWN_JOB_TYPES: readonly ["forecast", "forecast-internal", "nql-forecast", "costs", "materialize-view", "materialized_views_collect_access_rules_billing_data", "datasets_calculate_affected_rows", "datasets_calculate_column_stats", "datasets_create_table", "datasets_delete_table", "datasets_deliver_data", "datasets_enforce_row_ttl_retention_policy", "datasets_enforce_table_ttl_retention_policy", "datasets_execute_dml", "datasets_execute_select", "datasets_sample", "datasets_suggest_mappings", "datasets_truncate_table", "health_check", "model_inference_run", "model_training_run", "models_deliver_model", "models_train_classifier"];
+export type JobType = (typeof KNOWN_JOB_TYPES)[number];
+export type JobExecutionCluster = "shared" | "dedicated";
+export interface JobRequestSourceApiUser {
+    type: "api_user";
     company_id: number;
     user_id: number;
 }
-export interface JobRequestSourceApiUser {
-    company_id: string;
-    user_id: string;
-}
 export interface JobRequestSourceProcess {
+    type: "process";
     name: string;
 }
+export type JobRequestSource = JobRequestSourceApiUser | JobRequestSourceProcess;
 interface BaseJob {
     job_id: string;
     type: JobType;
+    company_id: number;
     request_source: JobRequestSource;
     data_plane_id?: string;
     compute_pool_id?: string;
     state: JobState;
+    execution_cluster: JobExecutionCluster;
+    /**
+     * The job type actually executed on the data plane. Multiple business-level
+     * types (e.g. `datasets_calculate_affected_rows`, `datasets_sample`) can map
+     * to a single operator type (`datasets_execute_select`); otherwise it equals
+     * `type`.
+     */
+    operator_type: string;
     executor?: string;
     idempotency_key: string;
     created_at: string;
@@ -37,7 +51,12 @@ export interface ForecastInput {
 }
 export interface ForecastJob extends BaseJob {
     type: "forecast";
-    input: ExplainInput;
+    input: ForecastInput;
+    result?: ForecastResult;
+}
+export interface ForecastInternalJob extends BaseJob {
+    type: "forecast-internal";
+    input: ForecastInput;
     result?: ForecastResult;
 }
 export interface ExplainInput {
@@ -53,6 +72,16 @@ export interface ExplainJob extends BaseJob {
     input: ExplainInput;
     result?: ExplainOutput;
 }
+export interface CostsInput {
+    as_of?: string;
+    /** Subscription purchase details; shape mirrors the marketplace subscription model. */
+    details: unknown;
+}
+export interface CostsJob extends BaseJob {
+    type: "costs";
+    input: CostsInput;
+    result?: unknown;
+}
 export interface MaterializedViewInput {
     nql: string;
     compiled_nql: string;
@@ -67,6 +96,19 @@ export interface MaterializedViewInput {
         };
     };
 }
+export interface MaterializedViewRowStats {
+    affected_rows: number;
+    inserted_rows: number;
+    updated_rows: number;
+    deleted_rows: number;
+}
+/** Result shape reported by data planes completing a refresh. */
+export interface RefreshMaterializedViewResult {
+    type: "refresh_materialized_view";
+    snapshot_id: string;
+    row_stats?: MaterializedViewRowStats;
+}
+/** Legacy result shape produced by the Spark executor. */
 export interface MaterializedViewOutput {
     success: {
         result: {
@@ -80,10 +122,56 @@ export interface MaterializedViewOutput {
 export interface MaterializedViewJob extends BaseJob {
     type: "materialize-view";
     input: MaterializedViewInput;
-    result?: MaterializedViewOutput;
+    result?: MaterializedViewOutput | RefreshMaterializedViewResult;
+}
+export interface CollectAccessRulesBillingDataInput {
+    dataset_id?: number;
+    nio_last_modified_at: string;
+    compiled_query: string;
+    refresh_job_id: string;
+}
+export interface CollectAccessRulesBillingDataResult {
+    sources: Array<{
+        access_rule_id: number;
+        rows: number;
+        price_per_row: unknown;
+    }>;
+}
+export interface CollectAccessRulesBillingDataJob extends BaseJob {
+    type: "materialized_views_collect_access_rules_billing_data";
+    input: CollectAccessRulesBillingDataInput;
+    result?: CollectAccessRulesBillingDataResult;
+}
+export interface CalculateAffectedRowsInput {
+    dataset_id: number;
+    compiled_sql: string;
+}
+export interface CalculateAffectedRowsJob extends BaseJob {
+    type: "datasets_calculate_affected_rows";
+    input: CalculateAffectedRowsInput;
+    /** Runs on the `datasets_execute_select` operator, so the stored result is select-shaped. */
+    result?: ExecuteSelectResult;
+}
+export interface CreateTableInput {
+    dataset_id: number;
+    compiled_sql: string;
+}
+export interface DatasetsCreateTableJob extends BaseJob {
+    type: "datasets_create_table";
+    input: CreateTableInput;
+    result?: unknown;
+}
+export interface TruncateTableInput {
+    dataset_id: number;
+}
+export interface DatasetsTruncateTableJob extends BaseJob {
+    type: "datasets_truncate_table";
+    input: TruncateTableInput;
+    result?: unknown;
 }
 export interface DeleteInput {
     external_id: string;
+    is_narrative_managed?: boolean;
 }
 export type DeleteResult = unknown;
 export interface DatasetsDeleteTableJob extends BaseJob {
@@ -92,9 +180,9 @@ export interface DatasetsDeleteTableJob extends BaseJob {
     result?: DeleteResult;
 }
 export interface DeliverInput {
-    app_id: string;
-    connection_id: string;
-    dataset_id: string;
+    app_id?: string;
+    connection_id?: string;
+    dataset_id: number;
     external_id: string;
     snapshot_id?: string;
     maintenance_window_predicate?: string;
@@ -105,8 +193,56 @@ export interface DatasetsDeliverDataJob extends BaseJob {
     input: DeliverInput;
     result?: DeliverResult;
 }
+export interface EnforceRowTtlRetentionPolicyInput {
+    dataset_id: number;
+    sql: string[];
+}
+export interface DatasetsEnforceRowTtlRetentionPolicyJob extends BaseJob {
+    type: "datasets_enforce_row_ttl_retention_policy";
+    input: EnforceRowTtlRetentionPolicyInput;
+    result?: unknown;
+}
+export interface EnforceTableTtlRetentionPolicyInput {
+    dataset_id: number;
+    dataset_external_id?: string;
+}
+export interface DatasetsEnforceTableTtlRetentionPolicyJob extends BaseJob {
+    type: "datasets_enforce_table_ttl_retention_policy";
+    input: EnforceTableTtlRetentionPolicyInput;
+    result?: unknown;
+}
+export interface ExecuteDmlInput {
+    dataset_id: number;
+    nql: string;
+    compiled_sql: string;
+    nio_last_modified_at?: string;
+}
+export interface ExecuteDmlResult {
+    affected_rows: number;
+    inserted_rows: number;
+    updated_rows: number;
+    deleted_rows: number;
+}
+export interface DatasetsExecuteDmlJob extends BaseJob {
+    type: "datasets_execute_dml";
+    input: ExecuteDmlInput;
+    result?: ExecuteDmlResult;
+}
+export interface ExecuteSelectInput {
+    compiled_sql: string;
+}
+export interface ExecuteSelectResult {
+    rows: Array<{
+        values: Record<string, unknown>;
+    }>;
+}
+export interface DatasetsExecuteSelectJob extends BaseJob {
+    type: "datasets_execute_select";
+    input: ExecuteSelectInput;
+    result?: ExecuteSelectResult;
+}
 export interface SampleInput {
-    dataset_id: string;
+    dataset_id: number;
 }
 export type SampleResult = unknown;
 export interface DatasetsSampleJob extends BaseJob {
@@ -114,24 +250,63 @@ export interface DatasetsSampleJob extends BaseJob {
     input: SampleInput;
     result?: SampleResult;
 }
+export interface SuggestMappingsInput {
+    dataset_id: number;
+}
+export interface SuggestMappingsResult {
+    result: string;
+}
+export interface DatasetsSuggestMappingsJob extends BaseJob {
+    type: "datasets_suggest_mappings";
+    input: SuggestMappingsInput;
+    result?: SuggestMappingsResult;
+}
+export type ColumnStatDataType = "boolean" | "double" | "long" | "string" | "timestamp_tz" | "array" | "object";
+export interface EnabledColumnStatFlags {
+    nan_value_count?: boolean;
+    null_value_count?: boolean;
+    value_count?: boolean;
+    lower_bound?: boolean;
+    upper_bound?: boolean;
+    column_stored_bytes?: boolean;
+    approx_count_distinct?: boolean;
+    count_distinct?: boolean;
+    histogram?: boolean;
+    mean?: boolean;
+    standard_deviation?: boolean;
+    completeness?: boolean;
+    observed_types?: boolean;
+}
 export interface ColumnDetails {
-    data_type: string;
+    data_type: ColumnStatDataType;
+    enabled_column_stats?: EnabledColumnStatFlags;
 }
 export interface StatsInput {
-    dataset_id: string;
+    dataset_id: number;
     enabled_column_stats?: Record<string, ColumnDetails>;
 }
+/** V2 input ships pre-compiled SQL instead of a column configuration. */
+export interface StatsInputV2 {
+    dataset_id: number;
+    compiled_sql: string;
+}
 export type StatsResult = unknown;
 export interface DatasetsCalculateColumnStatsJob extends BaseJob {
     type: "datasets_calculate_column_stats";
-    input: StatsInput;
+    input: StatsInput | StatsInputV2;
     result?: StatsResult;
 }
+export interface HealthCheckJob extends BaseJob {
+    type: "health_check";
+    input: unknown;
+    /** Compute pool health check report. */
+    result?: unknown;
+}
 export interface ModelTrainingRunInput {
-    company_id: string;
+    company_id: number;
     connections?: unknown[];
     custom_axolotl_config_override?: unknown;
-    dataset_id: string;
+    dataset_id: number;
     instance_type: string;
     base_model_id: string;
     base_model_repository: string;
@@ -148,7 +323,7 @@ export interface ModelTrainingRunJob extends BaseJob {
     result?: ModelTrainingRunResult;
 }
 export interface ModelsDeliverModelInput {
-    company_id: string;
+    company_id: number;
     app_id: string;
     connection_id: string;
     profile_id: string;
@@ -163,13 +338,10 @@ export interface ModelsDeliverModelJob extends BaseJob {
     input: ModelsDeliverModelInput;
     result?: ModelsDeliverModelResult;
 }
-export interface UnknownJob extends BaseJob {
-    input: unknown;
-    result?: unknown;
-}
 export interface ModelsTrainClassifierJob extends BaseJob {
     type: "models_train_classifier";
-    result: ModelsTrainClassifierResults;
+    input: unknown;
+    result?: ModelsTrainClassifierResults;
 }
 export interface ModelInferenceRunInput {
     model: string;
@@ -191,14 +363,40 @@ export interface ModelInferenceRunJobResult {
         prompt_tokens: number;
         completion_tokens: number;
     };
-    structured_output: unknown;
+    structured_output?: unknown;
+    tool_calls?: unknown[];
+    stop_reason?: string;
 }
 export interface ModelInferenceRunJob extends BaseJob {
     type: "model_inference_run";
     input: ModelInferenceRunInput;
     result?: ModelInferenceRunJobResult;
 }
-export type Job = ForecastJob | ExplainJob | MaterializedViewJob | DatasetsDeleteTableJob | DatasetsDeliverDataJob | DatasetsSampleJob | DatasetsCalculateColumnStatsJob | ModelTrainingRunJob | ModelsDeliverModelJob | ModelsTrainClassifierJob | ModelInferenceRunJob | UnknownJob;
+/**
+ * Fallback for job types the SDK does not know about yet — the backend's
+ * job type is an open string, so new types can appear without an SDK release.
+ */
+export interface UnknownJob extends Omit<BaseJob, "type"> {
+    type: string;
+    input: unknown;
+    result?: unknown;
+}
+/** Discriminated union over every job type the SDK knows about. */
+export type KnownJob = ForecastJob | ForecastInternalJob | ExplainJob | CostsJob | MaterializedViewJob | CollectAccessRulesBillingDataJob | CalculateAffectedRowsJob | DatasetsCalculateColumnStatsJob | DatasetsCreateTableJob | DatasetsDeleteTableJob | DatasetsDeliverDataJob | DatasetsEnforceRowTtlRetentionPolicyJob | DatasetsEnforceTableTtlRetentionPolicyJob | DatasetsExecuteDmlJob | DatasetsExecuteSelectJob | DatasetsSampleJob | DatasetsSuggestMappingsJob | DatasetsTruncateTableJob | HealthCheckJob | ModelInferenceRunJob | ModelTrainingRunJob | ModelsDeliverModelJob | ModelsTrainClassifierJob;
+export type Job = KnownJob | UnknownJob;
+/**
+ * Narrows a job to the discriminated union of known types, enabling
+ * exhaustive `switch (job.type)` handling in consumers:
+ *
+ * ```ts
+ * if (isKnownJob(job)) {
+ *   switch (job.type) {
+ *     case "forecast": // job is ForecastJob
+ *   }
+ * }
+ * ```
+ */
+export declare function isKnownJob(job: Job): job is KnownJob;
 export interface ModelsTrainClassifierTrainingSummary {
     total_features: number;
     feature_types: Record<"text" | "categorical" | "embedding" | "numeric", number>;

package/build/jobs/types.js

@@ -1 +1,45 @@
-export {};
+/**
+ * Every job type the backend can persist and return from the /jobs API.
+ * The backend's `Job.Type` is an open string, so treat this list as the
+ * known set rather than a closed enum — see {@link UnknownJob}.
+ */
+export const KNOWN_JOB_TYPES = [
+    "forecast",
+    "forecast-internal",
+    "nql-forecast",
+    "costs",
+    "materialize-view",
+    "materialized_views_collect_access_rules_billing_data",
+    "datasets_calculate_affected_rows",
+    "datasets_calculate_column_stats",
+    "datasets_create_table",
+    "datasets_delete_table",
+    "datasets_deliver_data",
+    "datasets_enforce_row_ttl_retention_policy",
+    "datasets_enforce_table_ttl_retention_policy",
+    "datasets_execute_dml",
+    "datasets_execute_select",
+    "datasets_sample",
+    "datasets_suggest_mappings",
+    "datasets_truncate_table",
+    "health_check",
+    "model_inference_run",
+    "model_training_run",
+    "models_deliver_model",
+    "models_train_classifier",
+];
+/**
+ * Narrows a job to the discriminated union of known types, enabling
+ * exhaustive `switch (job.type)` handling in consumers:
+ *
+ * ```ts
+ * if (isKnownJob(job)) {
+ *   switch (job.type) {
+ *     case "forecast": // job is ForecastJob
+ *   }
+ * }
+ * ```
+ */
+export function isKnownJob(job) {
+    return KNOWN_JOB_TYPES.includes(job.type);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "2.105.0",
+	"version": "2.106.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -25,18 +25,18 @@
 	"author": "",
 	"license": "ISC",
 	"devDependencies": {
-		"@babel/core": "7.29.0",
-		"@babel/preset-env": "7.29.5",
-		"@babel/preset-typescript": "7.28.5",
+		"@babel/core": "7.29.7",
+		"@babel/preset-env": "7.29.7",
+		"@babel/preset-typescript": "7.29.7",
 		"@biomejs/biome": "2.4.15",
 		"@commitlint/cli": "21.0.1",
 		"@commitlint/config-conventional": "21.0.1",
 		"@types/jest": "30.0.0",
-		"@types/json-schema": "^7.0.15",
+		"@types/json-schema": "7.0.15",
 		"babel-jest": "30.4.1",
 		"jest": "30.4.2",
-		"lefthook": "2.1.6",
-		"ts-jest": "29.4.9"
+		"lefthook": "2.1.8",
+		"ts-jest": "29.4.11"
 	},
 	"dependencies": {
 		"mande": "2.0.9",