@expresscsv/sdk 0.1.14 → 0.1.16

package/README.md

@@ -83,6 +83,116 @@ importer.open({
 });
 ```
 
+### Webhook Payload Structure
+
+Each chunk is delivered as a JSON `POST` (or whichever method you configured) to your endpoint. The request body has this shape:
+
+```typescript
+interface WebhookPayload {
+  /** Imported records for this chunk, matching your schema */
+  records: Record<string, unknown>[];
+  /** 0-based index of the current chunk */
+  chunkIndex: number;
+  /** Total number of chunks in this delivery */
+  totalChunks: number;
+  /** Total number of records across all chunks */
+  totalRecords: number;
+  /** Present only if you passed `metadata` in `WebhookConfig` */
+  metadata?: Record<string, unknown>;
+  /** Delivery context added by ExpressCSV */
+  delivery: {
+    publishableKey: string;
+    environmentName: string;
+    environmentType: string;
+    teamSlug: string;
+    importIdentifier: string;
+    deliveryId: string;
+    timestamp: string; // ISO 8601
+  };
+}
+```
+
+Example payload:
+
+```json
+{
+  "records": [
+    { "name": "Alice Johnson", "email": "alice@example.com", "age": 32 },
+    { "name": "Bob Smith", "email": "bob@example.com", "age": 45 }
+  ],
+  "chunkIndex": 0,
+  "totalChunks": 3,
+  "totalRecords": 2500,
+  "metadata": {
+    "source": "web-app",
+    "userId": "user-123"
+  },
+  "delivery": {
+    "publishableKey": "pk_live_abc123",
+    "environmentName": "Production",
+    "environmentType": "production",
+    "teamSlug": "my-team",
+    "importIdentifier": "user-import",
+    "deliveryId": "del_abc123",
+    "timestamp": "2026-03-02T14:30:00.000Z"
+  }
+}
+```
+
+The request includes a `Content-Type: application/json` header plus any custom `headers` you specified in `WebhookConfig`.
+
+### Handling Webhooks on Your Server
+
+Your endpoint should return a **2xx** status code to acknowledge each chunk. Non-2xx responses trigger the following retry behaviour:
+
+- **5xx** and **429** responses are retried automatically (up to 5 attempts per chunk).
+- **4xx** responses (except 429) are treated as permanent failures and are **not** retried.
+
+Chunks are delivered **serially** — the next chunk is only sent after the previous one succeeds.
+
+Below is a minimal Express.js example:
+
+```typescript
+import express from "express";
+
+const app = express();
+app.use(express.json());
+
+app.post("/webhooks/csv-import", async (req, res) => {
+  const token = req.headers.authorization;
+  if (token !== "Bearer your-api-token") {
+    return res.status(401).json({ error: "Unauthorized" });
+  }
+
+  const { records, chunkIndex, totalChunks, totalRecords, metadata, delivery } =
+    req.body;
+
+  try {
+    // Process the records — e.g. insert into your database
+    await db.insertMany("users", records);
+
+    console.log(
+      `Chunk ${chunkIndex + 1}/${totalChunks} processed ` +
+        `(${records.length} records, delivery ${delivery.deliveryId})`
+    );
+
+    res.status(200).json({ success: true });
+  } catch (error) {
+    // Return 500 so ExpressCSV retries this chunk
+    console.error("Failed to process chunk:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+app.listen(3000);
+```
+
+**Tips:**
+
+- Use `delivery.deliveryId` and `chunkIndex` to **deduplicate** retried chunks (the same chunk may be delivered more than once on retry).
+- Use `chunkIndex` and `totalChunks` to track progress and know when the full import is complete (`chunkIndex === totalChunks - 1` for the last chunk).
+- Store `metadata` alongside imported records if you need to correlate the import with a specific user or action in your app.
+
 ### Combined Local Callback and Webhook
 
 You can use both `onData` and `webhook` simultaneously:

package/dist/index.d.cts

@@ -1281,6 +1281,11 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      * Chunks data using SDK-determined chunk size (independent of customer's chunkSize)
      */
     private deliverToWebhook;
+    /**
+     * Poll the delivery status endpoint until the delivery reaches a terminal state
+     * ('success' or 'failed'), or until the timeout is exceeded.
+     */
+    private pollDeliveryStatus;
     /**
      * Send a single chunk to backend webhook API with retry logic
      */
@@ -2852,6 +2857,13 @@ declare interface ExpressCSVLocale {
         matched: string;
         unmatched: string;
         custom: string;
+        nextDisabledUpload: string;
+        nextDisabledSelectSheet: string;
+        nextDisabledSelectHeader: string;
+        nextDisabledMatchColumns: string;
+        nextDisabledMatchOptions: string;
+        nextDisabledReviewValidating: string;
+        nextDisabledReviewInvalid: string;
     };
     widget: {
         title: string;
@@ -3878,6 +3890,13 @@ export declare interface WebhookConfig {
     retries?: number;
     /** Arbitrary developer-provided metadata */
     metadata?: Record<string, unknown>;
+    /**
+     * Whether to wait for the delivery service to confirm the webhook was
+     * successfully received before considering the import complete.
+     * When false, the import completes as soon as all chunks are queued.
+     * Default: true
+     */
+    awaitWebhookArrival?: boolean;
 }
 
 /**

package/dist/index.d.mts

@@ -1281,6 +1281,11 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      * Chunks data using SDK-determined chunk size (independent of customer's chunkSize)
      */
     private deliverToWebhook;
+    /**
+     * Poll the delivery status endpoint until the delivery reaches a terminal state
+     * ('success' or 'failed'), or until the timeout is exceeded.
+     */
+    private pollDeliveryStatus;
     /**
      * Send a single chunk to backend webhook API with retry logic
      */
@@ -2852,6 +2857,13 @@ declare interface ExpressCSVLocale {
         matched: string;
         unmatched: string;
         custom: string;
+        nextDisabledUpload: string;
+        nextDisabledSelectSheet: string;
+        nextDisabledSelectHeader: string;
+        nextDisabledMatchColumns: string;
+        nextDisabledMatchOptions: string;
+        nextDisabledReviewValidating: string;
+        nextDisabledReviewInvalid: string;
     };
     widget: {
         title: string;
@@ -3878,6 +3890,13 @@ export declare interface WebhookConfig {
     retries?: number;
     /** Arbitrary developer-provided metadata */
     metadata?: Record<string, unknown>;
+    /**
+     * Whether to wait for the delivery service to confirm the webhook was
+     * successfully received before considering the import complete.
+     * When false, the import completes as soon as all chunks are queued.
+     * Default: true
+     */
+    awaitWebhookArrival?: boolean;
 }
 
 /**

package/dist/index.d.ts

@@ -1281,6 +1281,11 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      * Chunks data using SDK-determined chunk size (independent of customer's chunkSize)
      */
     private deliverToWebhook;
+    /**
+     * Poll the delivery status endpoint until the delivery reaches a terminal state
+     * ('success' or 'failed'), or until the timeout is exceeded.
+     */
+    private pollDeliveryStatus;
     /**
      * Send a single chunk to backend webhook API with retry logic
      */
@@ -2852,6 +2857,13 @@ declare interface ExpressCSVLocale {
         matched: string;
         unmatched: string;
         custom: string;
+        nextDisabledUpload: string;
+        nextDisabledSelectSheet: string;
+        nextDisabledSelectHeader: string;
+        nextDisabledMatchColumns: string;
+        nextDisabledMatchOptions: string;
+        nextDisabledReviewValidating: string;
+        nextDisabledReviewInvalid: string;
     };
     widget: {
         title: string;
@@ -3878,6 +3890,13 @@ export declare interface WebhookConfig {
     retries?: number;
     /** Arbitrary developer-provided metadata */
     metadata?: Record<string, unknown>;
+    /**
+     * Whether to wait for the delivery service to confirm the webhook was
+     * successfully received before considering the import complete.
+     * When false, the import completes as soon as all chunks are queued.
+     * Default: true
+     */
+    awaitWebhookArrival?: boolean;
 }
 
 /**