@narrative.io/data-collaboration-sdk-ts 3.3.0 → 3.4.0

package/README.md

@@ -311,6 +311,80 @@ try {
 }
 ```
 
+### Centralized Error Handling
+
+Instead of repeating `try/catch` normalization at every call site, you can register a
+single `errorTransformer` on the client. It runs once per failed request — for both
+non-2xx responses (as an `HttpError`) and native fetch/network rejections — after the
+`HttpError` (with its parsed `body`) has been built. Whatever it returns is thrown in
+its place, so you can map transport failures onto your own application error types.
+
+The SDK only supplies the mechanism; your application decides what a failure *means*.
+The SDK does not log out, retry, redirect, show a toast, or treat any status as fatal
+on your behalf. A `500`, for example, is not automatically application-fatal — that
+policy is yours to define. This keeps the SDK framework-agnostic: no Vue, Nuxt, Pinia,
+or other UI dependency is involved.
+
+```typescript
+import {
+  NarrativeApi,
+  HttpError,
+  type HttpRequestContext,
+} from '@narrative.io/data-collaboration-sdk-ts';
+
+// Your application's own error types — the SDK does not define these.
+class AuthenticationRequiredError extends Error {}
+class ApiServerError extends Error {}
+
+const narrative = new NarrativeApi({
+  apiKey: process.env.NARRATIVE_API_KEY!,
+  errorTransformer(error: unknown, context: HttpRequestContext) {
+    // Only HTTP responses carry a status; network rejections do not.
+    if (error instanceof HttpError) {
+      const status = error.response.status;
+
+      if (status === 401) {
+        return new AuthenticationRequiredError(
+          `Authentication required for ${context.method} ${context.url}`,
+        );
+      }
+
+      if (status >= 500) {
+        return new ApiServerError(`Server error (${status})`);
+      }
+    }
+
+    // Return `undefined` (or the original `error`) to rethrow it unchanged.
+    return undefined;
+  },
+});
+```
+
+Semantics:
+
+- The transformer runs **exactly once** per failed request, always after the
+  `HttpError` and its parsed `body` are available.
+- **Returning the original `error`** preserves its object identity.
+- **Returning a replacement** causes that value to be thrown instead.
+- **Returning `undefined`** means "rethrow the original error unchanged" — identical
+  to having no transformer.
+- If the **transformer itself throws or rejects**, that error propagates and the
+  transformer is not invoked a second time.
+- `context` intentionally exposes only `method` and `url`. Request bodies and headers
+  (including `Authorization`) are never passed to the transformer.
+
+### Custom `fetch` Implementation
+
+By default the SDK uses `globalThis.fetch`. You can supply your own implementation —
+useful for tests, instrumentation, or non-browser runtimes:
+
+```typescript
+const narrative = new NarrativeApi({
+  apiKey: process.env.NARRATIVE_API_KEY!,
+  fetch: myCustomFetch, // defaults to globalThis.fetch
+});
+```
+
 ## API Reference
 
 For detailed API documentation, please visit the [Narrative.io API Documentation](https://api.narrative.dev).

package/build/base-api.js

@@ -23,6 +23,8 @@ export class BaseApi {
             baseUrl: this.getBaseUrl(),
             headers: this.constructHeaders(),
             responseAs: config.responseAs ?? "json",
+            errorTransformer: config.errorTransformer,
+            fetch: config.fetch,
         });
         if (this.verbose) {
             console.info(`Using environment: ${this.environment}`);

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" | "pending_cancellation" | "cancelled" | "failed";
+export type JobState = "pending" | "scheduled" | "running" | "completed" | "pending_cancellation" | "cancelled" | "failed";
 export interface ForecastResult {
     cost: number;
     datasets: DatasetForecastResponse[];

package/build/http-client.d.ts

@@ -11,9 +11,40 @@
  *   resolves to `null`
  * - throws on any non-2xx status, attaching the {@link Response} and the parsed
  *   body to the error
+ *
+ * An optional {@link HttpErrorTransformer} lets consumers observe or replace the
+ * error before it propagates. It runs for both non-2xx responses and network
+ * rejections, always after the {@link HttpError} (with its parsed body) has been
+ * built. When absent, the original error is thrown unchanged.
  */
 /** How a response body should be returned from a request. */
 export type ResponseAs = "json" | "text" | "response";
+/** HTTP verbs the SDK issues. */
+export type HttpRequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Minimal, side-effect-free description of the request that produced an error.
+ *
+ * Intentionally excludes the request body and headers (including any
+ * `Authorization` header) so an {@link HttpErrorTransformer} cannot leak
+ * credentials or payloads.
+ */
+export interface HttpRequestContext {
+    /** The HTTP verb used for the request. */
+    method: HttpRequestMethod;
+    /** The fully-resolved request URL (base URL joined with the endpoint). */
+    url: string;
+}
+/**
+ * Hook invoked when a request fails, either with an {@link HttpError} (non-2xx)
+ * or a native fetch/network rejection.
+ *
+ * Return the value to throw in place of the original error. Returning the
+ * original `error` preserves its identity. Returning `undefined` means "rethrow
+ * the original error unchanged" — the same as having no transformer. If the
+ * transformer itself throws (or rejects), that error propagates; the transformer
+ * is never invoked a second time for the same request.
+ */
+export type HttpErrorTransformer = (error: unknown, context: HttpRequestContext) => unknown | Promise<unknown>;
 /** Options for constructing an {@link HttpClient}. */
 export interface HttpClientOptions {
     /** Absolute base URL that every request is resolved against. */
@@ -22,6 +53,16 @@ export interface HttpClientOptions {
     headers?: Record<string, string>;
     /** How to interpret response bodies. Defaults to `"json"`. */
     responseAs?: ResponseAs;
+    /**
+     * Optional hook to observe or transform request failures. See
+     * {@link HttpErrorTransformer}.
+     */
+    errorTransformer?: HttpErrorTransformer;
+    /**
+     * Optional `fetch` implementation. Defaults to `globalThis.fetch`, resolved
+     * at call time so the ambient global is honored when this is omitted.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 /**
  * Error thrown for any non-2xx response. Carries the originating
@@ -36,10 +77,25 @@ export declare class HttpClient {
     private readonly baseUrl;
     private readonly headers;
     private readonly responseAs;
+    private readonly errorTransformer?;
+    private readonly fetchImpl?;
     constructor(options: HttpClientOptions);
     get<T>(url: string): Promise<T>;
     post<T>(url: string, data?: unknown): Promise<T>;
     put<T>(url: string, data?: unknown): Promise<T>;
     delete<T>(url: string): Promise<T>;
     private request;
+    /**
+     * Performs the request and parses the response. Throws {@link HttpError} on a
+     * non-2xx status; native fetch/network failures reject as they always have.
+     * All failures are funneled through {@link transformError} by {@link request}.
+     */
+    private send;
+    /**
+     * Runs the configured {@link HttpErrorTransformer}, if any, and returns the
+     * error to throw. Without a transformer, or when the transformer returns
+     * `undefined`, the original error is returned unchanged. A transformer that
+     * throws/rejects propagates its own error (and is not retried).
+     */
+    private transformError;
 }

package/build/http-client.js

@@ -11,6 +11,11 @@
  *   resolves to `null`
  * - throws on any non-2xx status, attaching the {@link Response} and the parsed
  *   body to the error
+ *
+ * An optional {@link HttpErrorTransformer} lets consumers observe or replace the
+ * error before it propagates. It runs for both non-2xx responses and network
+ * rejections, always after the {@link HttpError} (with its parsed body) has been
+ * built. When absent, the original error is thrown unchanged.
  */
 /**
  * Error thrown for any non-2xx response. Carries the originating
@@ -39,9 +44,13 @@ export class HttpClient {
     baseUrl;
     headers;
     responseAs;
+    errorTransformer;
+    fetchImpl;
     constructor(options) {
         this.baseUrl = options.baseUrl;
         this.responseAs = options.responseAs ?? "json";
+        this.errorTransformer = options.errorTransformer;
+        this.fetchImpl = options.fetch;
         this.headers = {
             Accept: "application/json",
             "Content-Type": "application/json",
@@ -61,12 +70,33 @@ export class HttpClient {
         return this.request("DELETE", url);
     }
     async request(method, url, data) {
+        const requestUrl = joinUrl(this.baseUrl, url);
+        try {
+            return await this.send(method, requestUrl, data);
+        }
+        catch (error) {
+            throw await this.transformError(error, {
+                method: method,
+                url: requestUrl,
+            });
+        }
+    }
+    /**
+     * Performs the request and parses the response. Throws {@link HttpError} on a
+     * non-2xx status; native fetch/network failures reject as they always have.
+     * All failures are funneled through {@link transformError} by {@link request}.
+     */
+    async send(method, requestUrl, data) {
         const init = { method, headers: this.headers };
         // Only POST/PUT/PATCH carry a body.
         if (method[0] === "P" && data !== undefined && data !== null) {
             init.body = JSON.stringify(data);
         }
-        const response = await fetch(joinUrl(this.baseUrl, url), init);
+        // Resolve the fetch implementation at call time so the ambient global is
+        // honored when no custom `fetch` was supplied. Invoked as a bare call so
+        // `this` stays undefined, which native fetch requires.
+        const fetchImpl = this.fetchImpl ?? globalThis.fetch;
+        const response = await fetchImpl(requestUrl, init);
         // Return the raw Response untouched when asked.
         if (this.responseAs === "response") {
             if (response.status >= 200 && response.status < 300) {
@@ -83,4 +113,16 @@ export class HttpClient {
         }
         throw new HttpError(response, body);
     }
+    /**
+     * Runs the configured {@link HttpErrorTransformer}, if any, and returns the
+     * error to throw. Without a transformer, or when the transformer returns
+     * `undefined`, the original error is returned unchanged. A transformer that
+     * throws/rejects propagates its own error (and is not retried).
+     */
+    async transformError(error, context) {
+        if (!this.errorTransformer)
+            return error;
+        const transformed = await this.errorTransformer(error, context);
+        return transformed === undefined ? error : transformed;
+    }
 }

package/build/jobs/index.d.ts

@@ -2,7 +2,7 @@ import { BaseApi } from "../base-api";
 import type { ApiRecordsV2 } 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";
-type JobStateFilter = "cancelled" | "completed" | "failed" | "pending" | "pending_cancellation" | "running";
+type JobStateFilter = "cancelled" | "completed" | "failed" | "pending" | "pending_cancellation" | "running" | "scheduled";
 interface GetJobsParameters extends Record<string, string | number | boolean | string[] | undefined> {
     dataset_id?: number;
     per_page?: number;

package/build/jobs/types.d.ts

@@ -39,6 +39,8 @@ interface BaseJob {
     idempotency_key: string;
     created_at: string;
     updated_at: string;
+    attempted_at: string;
+    attempt_version: number;
     ended_at?: string;
     tags?: string[];
     dequeued_at?: string;

package/build/types.d.ts

@@ -1,4 +1,4 @@
-import type { ResponseAs } from "./http-client";
+import type { HttpErrorTransformer, ResponseAs } from "./http-client";
 /**
  * Environment for the API.
  *
@@ -18,6 +18,23 @@ export interface Config {
     headers?: Record<string, string>;
     verbose?: boolean;
     responseAs?: ResponseAs;
+    /**
+     * Optional hook to centrally observe or transform request failures — both
+     * non-2xx responses (as an {@link HttpError}) and native fetch/network
+     * rejections. Return a replacement error to throw, return the original error
+     * to preserve it, or return `undefined` to rethrow it unchanged. With no
+     * transformer configured, errors propagate exactly as before.
+     *
+     * The SDK only supplies the mechanism; the consuming application decides
+     * whether a given failure is local, authentication-related, retryable, or
+     * fatal. A 500, for instance, is not treated as application-fatal here.
+     */
+    errorTransformer?: HttpErrorTransformer;
+    /**
+     * Optional `fetch` implementation, useful for testing and non-browser
+     * runtimes. Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 export interface ApiRecordsV2<T> extends PaginationMetadata {
     records: T[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "3.3.0",
+	"version": "3.4.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",