snowpipe-streaming 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snowpipe-streaming",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Snowflake Streaming Ingest SDK for Node.js",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -27,11 +27,11 @@
     "typedoc": "^0.28.19"
   },
   "optionalDependencies": {
-    "snowpipe-streaming-linux-x64-gnu": "1.7.0",
-    "snowpipe-streaming-linux-x64-musl": "1.7.0",
-    "snowpipe-streaming-linux-arm64-gnu": "1.7.0",
-    "snowpipe-streaming-linux-arm64-musl": "1.7.0",
-    "snowpipe-streaming-darwin-arm64": "1.7.0",
-    "snowpipe-streaming-win32-x64-msvc": "1.7.0"
+    "snowpipe-streaming-linux-x64-gnu": "1.8.0",
+    "snowpipe-streaming-linux-x64-musl": "1.8.0",
+    "snowpipe-streaming-linux-arm64-gnu": "1.8.0",
+    "snowpipe-streaming-linux-arm64-musl": "1.8.0",
+    "snowpipe-streaming-darwin-arm64": "1.8.0",
+    "snowpipe-streaming-win32-x64-msvc": "1.8.0"
   }
 }

package/src/client.js

@@ -124,6 +124,9 @@ class StreamingIngestClient {
       // Cache the in-flight promise so concurrent callers share one open and one
       // instance. The pending-futures map is shared between the FFI callbacks and
       // the channel wrapper (the JS side owns per-message-ack promise resolution).
+      // No client-level callback registry to publish into (unlike Java/Python), so a
+      // failed open leaves nothing behind — the ack state is only reachable via the
+      // channel returned on success.
       this._elasticChannelPromise = (async () => {
         const pendingFutures = new Map();
         const ackState = new ElasticChannelAckState(pendingFutures);
@@ -133,7 +136,7 @@ class StreamingIngestClient {
         // Plug the native handle in before exposing the channel so the ack
         // state can drive `invalidateChannel` from JS on detected anomalies.
         ackState.setNativeChannel(nativeChannel);
-        return new StreamingIngestElasticChannel(nativeChannel, pendingFutures);
+        return new StreamingIngestElasticChannel(nativeChannel, pendingFutures, ackState);
       })().catch((e) => {
         // Don't cache failures (e.g. closed client, transient open error) so a retry can re-open.
         this._elasticChannelPromise = null;

package/src/elastic_channel.js

@@ -18,23 +18,44 @@
 const { callFFI, StreamingIngestError } = require("./errors.js");
 const { ChannelStatus } = require("./channel_status.js");
 const { serializeRowsToNdjson } = require("./row_serializer.js");
+const { LOG_PREFIX } = require("./log.js");
+
+// Default for the appendToken parameter, used to tell "caller omitted the argument" apart from
+// "caller passed a token" — including an explicit null, which is a valid token value meaning
+// "leave this append untracked". appendToken is required but nullable (matching Java's positional
+// parameter and Python's default-less argument), so opting out has to be spelled out as null
+// rather than achieved by leaving the argument off. Checked in _appendRowsInternal, which every
+// public append funnels through: a forwarded-but-omitted argument arrives as undefined, and a
+// default parameter applies to undefined however it got there.
+const APPEND_TOKEN_OMITTED = Symbol("appendTokenOmitted");
 
 /**
  * Elastic channel for streaming data into a Snowflake table.
  *
  * Unlike a regular channel, an elastic channel has no offset tokens and its
- * lifecycle is tied to the client (no close method). appendRow/appendRows return
- * a Promise that resolves when Snowflake acknowledges the rows.
+ * lifecycle is tied to the client (no close method). Appends come in two
+ * flavours: fire-and-forget appendRow/appendRows return nothing, while
+ * appendRowWithWait/appendRowsWithWait return a Promise that resolves when
+ * Snowflake acknowledges the rows. All four take a required (but nullable)
+ * caller-supplied append token and register the append for both handlers, so
+ * setErrorHandler and setSuccessHandler report the append tokens of appends that
+ * failed or were acknowledged after their call returned. An append given a null
+ * token is not tracked for either handler — the WithWait variants' promise still
+ * settles.
  *
  * Created via {@link StreamingIngestClient#getElasticChannel}, not directly.
  */
 class StreamingIngestElasticChannel {
   /**
    * @param {object} nativeChannel - Internal JsElasticChannel from FFI
-   * @param {Map<number, {resolve: Function, reject: Function}>} pendingFutures
-   *   Pending-promise map shared with the mark-complete callback wired into FFI.
+   * @param {Map<number, {resolve: Function, reject: Function, appendToken?: *}>} pendingFutures
+   *   Pending-promise map shared with the mark-complete callback wired into FFI;
+   *   an entry carries the caller-supplied append token of its append only when one
+   *   was supplied.
+   * @param {import("./mark_complete_callback.js").ElasticChannelAckState} ackState
+   *   Acknowledgement state that owns the customer error and success handlers.
    */
-  constructor(nativeChannel, pendingFutures) {
+  constructor(nativeChannel, pendingFutures, ackState) {
     if (!(nativeChannel && typeof nativeChannel === "object")) {
       throw new TypeError(
         "StreamingIngestElasticChannel cannot be instantiated directly. " +
@@ -43,6 +64,13 @@ class StreamingIngestElasticChannel {
     }
     this._native = nativeChannel;
     this._pendingFutures = pendingFutures;
+    this._ackState = ackState;
+    // Per-channel future id counter; the wrapper allocates ids so it can register
+    // the promise before the row becomes ack-eligible. The single-threaded event
+    // loop makes the plain increment safe. The id is a JS number (a safe integer,
+    // exact to 2^53) marshaled to the Rust i64.
+    // Starts at 1; 0 is reserved as the "no future id" sentinel, matching the other SDKs.
+    this._nextFutureId = 1;
   }
 
   /** @returns {string} The channel name (always "ELASTIC") */
@@ -79,50 +107,149 @@ class StreamingIngestElasticChannel {
   }
 
   /**
-   * Append a single row into the elastic channel.
+   * Append a single row into the elastic channel without waiting for the
+   * acknowledgement (fire-and-forget): returns as soon as the row is buffered.
+   * The append is still registered for both handlers, so its outcome is reported
+   * through {@link #setErrorHandler} or {@link #setSuccessHandler} (keyed by
+   * appendToken), just not through a promise. Use {@link #appendRowWithWait} when you need
+   * one to await.
+   *
    * @param {Object} row - Row data as column-name to value pairs
+   * @param {*} appendToken - Required caller-supplied opaque id for this append,
+   *   handed back to the error handler if it fails asynchronously, or to the
+   *   success handler once it is acknowledged. Any value is accepted, but the
+   *   argument itself is mandatory: pass null explicitly to leave the append
+   *   untracked for both handlers. The token is retained in memory until the
+   *   append is acknowledged, so a large object raises the memory footprint of
+   *   in-flight appends — prefer a small value.
+   * @returns {void}
+   * @throws {TypeError} If row is null or undefined, or appendToken is omitted
+   * @throws {StreamingIngestError} If the append fails synchronously
+   */
+  appendRow(row, appendToken) {
+    if (row == null) {
+      throw new TypeError("row must not be null");
+    }
+    this.appendRows([row], appendToken);
+  }
+
+  /**
+   * Append multiple rows into the elastic channel without waiting for the
+   * acknowledgement (fire-and-forget): returns as soon as the rows are buffered.
+   * The append is still registered for both handlers, so its outcome is reported
+   * through {@link #setErrorHandler} or {@link #setSuccessHandler} (keyed by
+   * appendToken), just not through a promise. Use {@link #appendRowsWithWait} when you need
+   * one to await.
+   *
+   * @param {Object[]} rows - Array of row objects
+   * @param {*} appendToken - Required caller-supplied opaque id for this batch,
+   *   handed back to the error handler if it fails asynchronously, or to the
+   *   success handler once it is acknowledged. Any value is accepted, but the
+   *   argument itself is mandatory: pass null explicitly to leave the append
+   *   untracked for both handlers. The token is retained in memory until the
+   *   append is acknowledged, so a large object raises the memory footprint of
+   *   in-flight appends — prefer a small value.
+   * @returns {void}
+   * @throws {TypeError} If rows is null, undefined, or not an array, or appendToken
+   *   is omitted
+   * @throws {StreamingIngestError} If the append fails synchronously
+   */
+  appendRows(rows, appendToken) {
+    // The append is registered like any other, so its failure still reaches the
+    // error handler; the caller just never sees the promise. The no-op catch is
+    // what keeps that rejection from being reported as an unhandledRejection on
+    // a promise nobody is left holding. Synchronous failures (bad arguments,
+    // closed channel, serialization) still throw out of this call, matching the
+    // other SDKs' fire-and-forget variants.
+    this._appendRowsInternal(rows, appendToken).catch(() => {});
+  }
+
+  /**
+   * Append a single row into the elastic channel and wait for Snowflake to
+   * acknowledge it. If an error handler is registered it also fires on an
+   * asynchronous failure — dual delivery.
+   *
+   * @param {Object} row - Row data as column-name to value pairs
+   * @param {*} appendToken - Required caller-supplied opaque id for this append,
+   *   handed back to the error handler if it fails asynchronously, or to the
+   *   success handler once it is acknowledged. Any value is accepted, but the
+   *   argument itself is mandatory: pass null explicitly to leave the append
+   *   untracked for both handlers. The token is retained in memory until the
+   *   append is acknowledged, so a large object raises the memory footprint of
+   *   in-flight appends — prefer a small value.
    * @returns {Promise<void>} Resolves when Snowflake acknowledges the row
+   * @throws {TypeError} If row is null or undefined, or appendToken is omitted
    */
-  async appendRow(row) {
+  async appendRowWithWait(row, appendToken) {
     if (row == null) {
       throw new TypeError("row must not be null");
     }
-    return this.appendRows([row]);
+    return this.appendRowsWithWait([row], appendToken);
+  }
+
+  /**
+   * Append multiple rows into the elastic channel and wait for Snowflake to
+   * acknowledge the batch. If an error handler is registered it also fires on an
+   * asynchronous failure — dual delivery.
+   *
+   * @param {Object[]} rows - Array of row objects
+   * @param {*} appendToken - Required caller-supplied opaque id for this batch,
+   *   handed back to the error handler if it fails asynchronously, or to the
+   *   success handler once it is acknowledged. Any value is accepted, but the
+   *   argument itself is mandatory: pass null explicitly to leave the append
+   *   untracked for both handlers. The token is retained in memory until the
+   *   append is acknowledged, so a large object raises the memory footprint of
+   *   in-flight appends — prefer a small value.
+   * @returns {Promise<void>} Resolves when Snowflake acknowledges the batch
+   * @throws {TypeError} If rows is not an array, or appendToken is omitted
+   */
+  async appendRowsWithWait(rows, appendToken) {
+    return this._appendRowsInternal(rows, appendToken);
   }
 
   /**
-   * Append multiple rows into the elastic channel.
+   * Shared append path behind both the fire-and-forget and the WithWait
+   * variants. Always registers the append for acknowledgement so the error
+   * handler fires on failure regardless of variant; the fire-and-forget callers
+   * simply discard the returned promise.
    *
-   * The native call is synchronous: it buffers the rows and returns a future id,
-   * which is registered in the shared pending map before returning to the event
-   * loop. The Promise resolves later when the mark-complete callback fires with
-   * the server acknowledgement (or rejects on error / channel invalidation).
+   * The wrapper allocates the future id and registers its promise in the shared
+   * pending map before the synchronous native append, so the ack can never
+   * precede registration. The Promise resolves later when the mark-complete
+   * callback fires with the server acknowledgement (or rejects on error).
+   *
+   * Throws rather than rejects by design: argument, serialization, and
+   * native-append failures leave the fire-and-forget callers at the call site
+   * (as in Java/Python) instead of vanishing into their discarded promise. The
+   * WithWait callers see them as a rejection, since those methods are `async`.
+   * Only a post-return failure travels on the returned promise.
    *
    * @param {Object[]} rows - Array of row objects
+   * @param {*} appendToken - Required (but nullable) caller-supplied opaque id for
+   *   this batch. Omitting it — here or in the public method that forwarded to this
+   *   one — is a TypeError; null is the way to opt out of handler tracking.
    * @returns {Promise<void>} Resolves when Snowflake acknowledges the batch
    */
-  async appendRows(rows) {
+  _appendRowsInternal(rows, appendToken = APPEND_TOKEN_OMITTED) {
     if (rows == null) {
       throw new TypeError("rows must not be null");
     }
     if (!Array.isArray(rows)) {
       throw new TypeError("rows must be an array");
     }
+    if (appendToken === APPEND_TOKEN_OMITTED) {
+      throw new TypeError("appendToken is required; pass null to leave the append untracked");
+    }
     // Empty arrays are validated by the Rust core, which throws a proper error.
     const buffer =
       rows.length === 0 ? Buffer.alloc(0) : serializeRowsToNdjson(rows, this.binaryInputFormat);
-    let futureId;
-    try {
-      futureId = Number(this._native.appendRows(buffer, rows.length));
-    } catch (e) {
-      throw StreamingIngestError.from(e);
-    }
 
-    // Build the promise out-of-line so we can stash {resolve, reject} into the
-    // shared map synchronously — the single-threaded event loop guarantees this
-    // happens-before any queued threadsafe-function callback runs. Map and
-    // resolve are then visible to mark_complete_callback.js (the JS owner of
-    // resolution) and the invalidate-all path on channel teardown.
+    // Allocate the id and register the promise BEFORE the native append, so the
+    // row cannot become ack-eligible before its promise is in the pending map.
+    // Building the promise out-of-line lets us stash {resolve, reject, appendToken}
+    // into the shared map synchronously; the single-threaded event loop guarantees
+    // this happens-before any queued threadsafe-function callback runs.
+    const futureId = this._nextFutureId++;
     let resolveFn;
     let rejectFn;
     const promise = new Promise((resolve, reject) => {
@@ -130,26 +257,128 @@ class StreamingIngestElasticChannel {
       rejectFn = reject;
     });
     const previous = this._pendingFutures.get(futureId);
-    this._pendingFutures.set(futureId, { resolve: resolveFn, reject: rejectFn });
+    const entry = { resolve: resolveFn, reject: rejectFn };
+    // Track the append token only when the caller supplied one; a null/undefined
+    // token means this append is invisible to the error handler, though a WithWait
+    // promise still rejects. Mirrors Java's nullable PendingAppend.appendToken.
+    if (appendToken != null) {
+      entry.appendToken = appendToken;
+    }
+    this._pendingFutures.set(futureId, entry);
     if (previous !== undefined) {
-      // Mirrors Java/Python: a duplicate future id from Rust means the SDK
-      // and the core have drifted, which is fatal. Reject the displaced
-      // promise, invalidate the channel, and throw to the caller so the
-      // new promise we just stashed isn't left hanging either.
+      // Monotonic per-channel ids make this a should-never-happen invariant.
       const errMsg = `Duplicate future_id=${futureId} in pendingFutures`;
       const err = new StreamingIngestError("Fatal", errMsg, 500, "Internal Server Error");
       previous.reject(err);
+      // Displaced promise was already handed to its owner (or discarded by a
+      // fire-and-forget append), so its failure is asynchronous from their view;
+      // the current call throws instead, where the caller still holds its own
+      // appendToken. An untracked displaced append has no token to report. No
+      // request id: this is our own duplicate-id invariant, not a Snowflake response.
+      if (previous.appendToken != null) {
+        this._ackState.fireErrorHandler([previous.appendToken], err, null, null);
+      }
       try {
         this._native.invalidateChannel(errMsg);
       } catch (invErr) {
         // eslint-disable-next-line no-console
-        console.error("Elastic channel invalidate_channel FFI call failed:", invErr);
+        console.error(`${LOG_PREFIX} Elastic channel invalidate_channel FFI call failed:`, invErr);
       }
       throw err;
     }
+
+    try {
+      this._native.appendRows(buffer, rows.length, futureId);
+    } catch (e) {
+      // Never enqueued (not ack-eligible), so no ack can arrive; drop the promise.
+      this._pendingFutures.delete(futureId);
+      throw StreamingIngestError.from(e);
+    }
     return promise;
   }
 
+  /**
+   * Register (or replace) a handler invoked when appends fail *asynchronously*,
+   * i.e. after the append call already returned. Fires once per failure event
+   * with a single {@link ErrorDetail} bundling the append tokens that failed
+   * together (a server-ack batch, or every in-flight append on invalidation) and
+   * their common error, so callers need not await each promise. Both append
+   * flavours are covered: it is the only failure signal for the fire-and-forget
+   * ones, and an additional one for the WithWait ones, whose promise still
+   * rejects. Only appends given an append token appear, and tokens are opaque and
+   * not deduplicated. Synchronous failures (closed channel, serialization, bad
+   * arguments) throw from the append call and never reach the handler. A handler
+   * that throws is caught and logged.
+   *
+   * The handler runs inline on the tick that drains a server acknowledgement. It
+   * must therefore return quickly and do no heavy or blocking work: no synchronous
+   * blocking calls, no busy loops, no long CPU-bound work. Do only cheap
+   * bookkeeping inline (e.g. record the failed tokens) and hand any real work to a
+   * worker thread or your own queue — blocking here blocks the event loop, which
+   * stalls acknowledgements (and append/flush completion) for every channel on this
+   * client and the rest of your application with them. The SDK logs a warning when
+   * a handler runs slowly.
+   *
+   * @param {(detail: import("./error_detail.js").ErrorDetail) => void} handler
+   * @throws {TypeError} If handler is not a function, or declares more than one
+   *   parameter (it is called with a single {@link ErrorDetail})
+   */
+  setErrorHandler(handler) {
+    if (typeof handler !== "function") {
+      throw new TypeError("handler must be a function");
+    }
+    // Reject the (appendTokens, error) two-argument shape: such a handler would
+    // silently see `undefined` as its second argument. `> 1` rather than `!== 1`
+    // keeps zero-arg, rest-parameter (length 0) and default-parameter handlers
+    // valid.
+    if (handler.length > 1) {
+      throw new TypeError(
+        `handler must take a single ErrorDetail argument, but declares ${handler.length} parameters`,
+      );
+    }
+    this._ackState.setErrorHandler(handler);
+  }
+
+  /**
+   * Register (or replace) a handler invoked when appends are acknowledged by
+   * Snowflake. Fires once per successful ack batch with a single
+   * {@link SuccessDetail} bundling the append tokens acknowledged together, so
+   * callers need not await each promise. Both append flavours are covered: it is
+   * the only success signal for the fire-and-forget ones, and an additional one
+   * for the WithWait ones, whose promise still resolves. Purely opt-in — without a
+   * registered handler nothing is collected. Only appends given an append token
+   * appear, and tokens are opaque and not deduplicated. A handler that throws is
+   * caught and logged.
+   *
+   * Like the error handler, this runs inline on the tick that drains a server
+   * acknowledgement. It must therefore return quickly and do no heavy or blocking
+   * work: no synchronous blocking calls, no busy loops, no long CPU-bound work. Do
+   * only cheap bookkeeping inline (e.g. record the tokens) and hand any real work to
+   * a worker thread or your own queue — blocking here blocks the event loop, which
+   * stalls acknowledgements (and append/flush completion) for every channel on this
+   * client and the rest of your application with them. The SDK logs a warning when a
+   * handler runs slowly.
+   *
+   * @param {(detail: import("./success_detail.js").SuccessDetail) => void} handler
+   * @throws {TypeError} If handler is not a function, or declares more than one
+   *   parameter (it is called with a single {@link SuccessDetail})
+   */
+  setSuccessHandler(handler) {
+    if (typeof handler !== "function") {
+      throw new TypeError("handler must be a function");
+    }
+    // Same arity guard as setErrorHandler: a multi-parameter handler would
+    // silently see `undefined` beyond the first argument. `> 1` rather than
+    // `!== 1` keeps zero-arg, rest-parameter (length 0) and default-parameter
+    // handlers valid.
+    if (handler.length > 1) {
+      throw new TypeError(
+        `handler must take a single SuccessDetail argument, but declares ${handler.length} parameters`,
+      );
+    }
+    this._ackState.setSuccessHandler(handler);
+  }
+
   /**
    * Trigger a flush of this channel (non-blocking).
    * @throws {StreamingIngestError} If the flush cannot be initiated
@@ -162,6 +391,15 @@ class StreamingIngestElasticChannel {
     }
   }
 
+  /**
+   * Wait for this channel to flush.
+   * @param {{timeoutMs?: number}} [options]
+   * @returns {Promise<void>}
+   */
+  async waitForFlush(options) {
+    return callFFI(() => this._native.waitForFlush(options?.timeoutMs));
+  }
+
   /**
    * Get the current status of this channel.
    * @returns {Promise<ChannelStatus>}

package/src/error_detail.js

@@ -0,0 +1,95 @@
+// Copyright 2026 Snowflake Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+"use strict";
+
+/**
+ * The payload handed to an elastic-channel error handler (registered via
+ * {@link StreamingIngestElasticChannel#setErrorHandler}) when appends fail
+ * asynchronously.
+ *
+ * Delivered once per failure event, carrying the caller-supplied append tokens
+ * of every append that failed together under a common error — a whole
+ * server-ack error batch, or every tracked in-flight append on channel
+ * invalidation.
+ *
+ * Instances are created by the SDK and deeply frozen — both the object and its
+ * `appendTokens` array — so a handler cannot mutate what a sibling handler or a
+ * later log statement will read. Handlers only read this type, so new fields can
+ * be added over time without breaking them. Port of Java's `ErrorDetail`
+ * (immutable `Iterable`) and Python's frozen `ErrorDetail` dataclass (immutable
+ * tuple).
+ */
+class ErrorDetail {
+  /**
+   * @param {unknown[]} appendTokens - The opaque, caller-supplied append tokens of
+   *   the appends that failed with `error`. Never empty; a token reused across
+   *   appends appears once per failed append (not deduplicated). Frozen here, so
+   *   callers must pass an array they are handing over.
+   * @param {import("./errors.js").StreamingIngestError} error - The error that
+   *   rejected the failing appends.
+   * @param {string | null} requestId - The Snowflake request id of the server
+   *   response that failed these appends, for support escalation. Null when the
+   *   failure did not come from a server response (channel invalidation, or a
+   *   local protocol inconsistency detected by the SDK).
+   * @param {number} retryCount - How many retries the failing request had already
+   *   made: 0 when the first attempt failed, N when the SDK retried N times before
+   *   giving up.
+   *
+   *   **Use this to decide whether these rows may be duplicated in the table.** A retry
+   *   re-sends the same rowset, and the SDK retries whenever it cannot tell that the
+   *   previous attempt failed -- a timeout or a 5xx may mean the rows were never
+   *   processed, or that they were processed and only the response was lost. `0` means
+   *   the SDK sent this rowset once and introduced no duplicate; `> 0` means it sent it
+   *   more than once and an earlier attempt may already have been applied, so the rows
+   *   may appear more than once. Reconcile or de-duplicate downstream if you need
+   *   exactly-once. The signal is conservative: it counts every re-send, including an
+   *   authentication refresh, which is rejected before the rows are processed and so
+   *   cannot have duplicated anything -- `> 0` means "a duplicate is possible", not
+   *   "a duplicate happened". `0` means the SDK introduced no duplicate of its own, not
+   *   that the rows are absent from the table.
+   *
+   *   **Whenever `requestId` is null, neither field tells you whether the rows
+   *   arrived.** A null id means the SDK failed this append itself rather than relaying
+   *   a server response — channel or client invalidation, a close or drop, or an
+   *   internal fault — and all of those fail every append still in flight, locally and
+   *   immediately. That includes appends whose request had already gone to Snowflake and
+   *   may still be applied after this handler runs. The accompanying `retryCount` of 0
+   *   says only that the SDK sent the rowset once; it is not a statement that Snowflake
+   *   rejected it. The SDK cannot resolve this for you — the append has to be failed
+   *   when the channel goes away, and the in-flight request's outcome is not known at
+   *   that point — so reconcile against the table if you need to know. (Some null-id
+   *   failures never reached the network at all, such as a payload the SDK could not
+   *   serialize, so a null id spans both "definitely not applied" and "possibly
+   *   applied", which is why it cannot answer the question.)
+   *
+   *   Read it only when `requestId` is non-null: a failure with no originating request
+   *   reports 0 too. With the request id this names the exact attempt server-side — the
+   *   SDK sends both as the `requestId` and `retryCount` query params on every request.
+   */
+  constructor(appendTokens, error, requestId, retryCount) {
+    // Freeze the array as well as the instance: `Object.freeze(this)` alone would
+    // still let a handler push into or reorder appendTokens. Only the array
+    // itself is frozen, not the tokens inside it — those are the caller's own
+    // opaque objects and are handed back untouched.
+    this.appendTokens = Object.freeze(appendTokens);
+    this.error = error;
+    this.requestId = requestId;
+    this.retryCount = retryCount;
+    Object.freeze(this);
+  }
+}
+
+module.exports = { ErrorDetail };

package/src/errors.js

@@ -36,17 +36,30 @@
 class StreamingIngestError extends Error {
   /**
    * Create a StreamingIngestError.
+   *
+   * `message` (and therefore `stack` / `console.error`) is the decorated form
+   * `{errorCode}: {detail} (HTTP {code} {name})`. Pass the Rust/SDK detail as
+   * `message`; read it back from {@link StreamingIngestError#detail}.
+   *
    * @param {string} errorCode - The error code (e.g., "ConfigError", "ChannelNotFound")
-   * @param {string} message - The error message
+   * @param {string} message - The undecorated error detail
    * @param {number} httpStatusCode - HTTP status code indicating error category
    * @param {string} httpStatusName - HTTP status name (e.g., "Bad Request")
    */
   constructor(errorCode, message, httpStatusCode, httpStatusName) {
-    super(message);
+    // V8 bakes `name` + `message` into `stack` at construct time, and
+    // `console.error` / pino print that stack — not `toString()`. Put the
+    // decorated text on `message` so logging cannot drop error-code / HTTP status.
+    const statusName = httpStatusName != null ? httpStatusName : "Unknown";
+    const detail = message != null ? String(message) : "";
+    const decorated = `${errorCode}: ${detail} (HTTP ${httpStatusCode} ${statusName})`;
+    super(decorated);
     this.name = "StreamingIngestError";
+    this.message = decorated;
     this.errorCode = errorCode;
     this.httpStatusCode = httpStatusCode;
-    this.httpStatusName = httpStatusName;
+    this.httpStatusName = statusName;
+    this.detail = detail;
   }
 
   /**
@@ -67,7 +80,7 @@ class StreamingIngestError extends Error {
           data.error_code,
           data.message,
           data.http_status_code,
-          data.http_status_name || "Unknown",
+          data.http_status_name,
         );
       }
     } catch {
@@ -78,10 +91,10 @@ class StreamingIngestError extends Error {
 
   /**
    * Returns a string representation of the error.
-   * @returns {string} Formatted error string
+   * @returns {string} Decorated error string, without the `StreamingIngestError:` prefix
    */
   toString() {
-    return `${this.errorCode}: ${this.message} (HTTP ${this.httpStatusCode} ${this.httpStatusName})`;
+    return this.message;
   }
 }
 

package/src/index.d.ts

@@ -327,13 +327,135 @@ export class StreamingIngestChannel {
   }): Promise<void>;
 }
 
+/**
+ * The payload handed to an elastic-channel error handler (registered via
+ * `StreamingIngestElasticChannel.setErrorHandler`) when appends fail
+ * asynchronously.
+ *
+ * Delivered once per failure event, carrying the caller-supplied append tokens of
+ * every append that failed together under a common `error` — a whole server-ack
+ * error batch, or every tracked in-flight append on channel invalidation.
+ *
+ * Instances are created by the SDK and frozen; handlers only read this type, so
+ * new fields can be added over time without breaking them.
+ */
+export class ErrorDetail {
+  private constructor();
+
+  /**
+   * The opaque, caller-supplied append tokens of the appends that failed with
+   * `error`. Never empty; a token reused across appends appears once per failed
+   * append (not deduplicated). Frozen at construction — the array itself cannot
+   * be modified, though the tokens inside it are the caller's own objects.
+   */
+  readonly appendTokens: readonly unknown[];
+  /** The error that rejected the failing appends. */
+  readonly error: StreamingIngestError;
+  /**
+   * The Snowflake request id of the server response that failed these appends,
+   * for support escalation. Null when the failure did not come from a server
+   * response — channel invalidation, or a protocol inconsistency the SDK detected
+   * on its own.
+   */
+  readonly requestId: string | null;
+  /**
+   * How many retries the failing request had already made: 0 when the first
+   * attempt failed, N when the SDK retried N times before giving up.
+   *
+   * **Use this to decide whether these rows may be duplicated in the table.** A retry
+   * re-sends the same rowset, and the SDK retries whenever it cannot tell that the
+   * previous attempt failed — a timeout or a 5xx may mean the rows were never processed,
+   * or that they were processed and only the response was lost. `0` means the SDK sent
+   * this rowset once and introduced no duplicate; `> 0` means it sent it more than once
+   * and an earlier attempt may already have been applied, so the rows may appear more
+   * than once. Reconcile or de-duplicate downstream if you need exactly-once.
+   *
+   * The signal is conservative: it counts every re-send, including an authentication
+   * refresh, which is rejected before the rows are processed and so cannot have
+   * duplicated anything. `> 0` means "a duplicate is possible", not "a duplicate
+   * happened". `0` means the SDK introduced no duplicate of its own, not that the rows
+   * are absent from the table.
+   *
+   * **Whenever `requestId` is null, neither field tells you whether the rows arrived.** A
+   * null id means the SDK failed this append itself rather than relaying a server response
+   * — channel or client invalidation, a close or drop, or an internal fault — and all of
+   * those fail every append still in flight, locally and immediately. That includes appends
+   * whose request had already gone to Snowflake and may still be applied after this handler
+   * runs. The accompanying `retryCount` of 0 says only that the SDK sent the rowset once;
+   * it is not a statement that Snowflake rejected it. Reconcile against the table if you
+   * need to know whether those rows landed.
+   *
+   * Read it only when `requestId` is non-null: a failure with no originating request
+   * reports 0 too. With the request id this names the exact attempt server-side — the
+   * SDK sends both as query params on every request.
+   */
+  readonly retryCount: number;
+}
+
+/**
+ * The payload handed to an elastic-channel success handler (registered via
+ * `StreamingIngestElasticChannel.setSuccessHandler`) when appends are
+ * acknowledged by Snowflake.
+ *
+ * Delivered once per successful acknowledgement, carrying the caller-supplied
+ * append tokens of every append acked together in that server-ack batch. There is
+ * no error field — unlike `ErrorDetail`, there is nothing to explain.
+ *
+ * Instances are created by the SDK and frozen; handlers only read this type, so
+ * new fields can be added over time without breaking them.
+ */
+export class SuccessDetail {
+  private constructor();
+
+  /**
+   * The opaque, caller-supplied append tokens of the appends that were
+   * acknowledged together. Never empty; a token reused across appends appears once
+   * per acknowledged append (not deduplicated). Frozen at construction — the array
+   * itself cannot be modified, though the tokens inside it are the caller's own
+   * objects.
+   */
+  readonly appendTokens: readonly unknown[];
+  /**
+   * The Snowflake request id of the server response that acknowledged these
+   * appends, for support escalation.
+   */
+  readonly requestId: string;
+  /**
+   * How many retries that request took: 0 when the first attempt was acknowledged,
+   * N when the SDK retried N times before Snowflake accepted it.
+   *
+   * **Use this to decide whether these rows may be duplicated in the table.** A retry
+   * re-sends the same rowset, and the SDK retries whenever it cannot tell that the
+   * previous attempt failed — a timeout or a 5xx may mean the rows were never processed,
+   * or that they were processed and only the response was lost. `0` means the SDK sent
+   * this rowset once and introduced no duplicate; `> 0` means it sent it more than once
+   * and an earlier attempt may already have been applied, so the rows may appear more
+   * than once. Reconcile or de-duplicate downstream if you need exactly-once.
+   *
+   * The signal is conservative: it counts every re-send, including an authentication
+   * refresh, which is rejected before the rows are processed and so cannot have
+   * duplicated anything. `> 0` means "a duplicate is possible", not "a duplicate
+   * happened".
+   *
+   * Read it only when `requestId` is non-null: an acknowledgement with no originating
+   * request reports 0 too. A steadily non-zero count also means the SDK is absorbing
+   * retries on your behalf.
+   */
+  readonly retryCount: number;
+}
+
 /**
  * An elastic channel for streaming data into a Snowflake table.
  *
  * Unlike a regular channel, an elastic channel has no offset tokens and its
  * lifecycle is tied to the client — there is no close method, and the same
  * instance is returned on repeated calls to `client.getElasticChannel()`.
- * `appendRow`/`appendRows` resolve when Snowflake acknowledges the rows.
+ * Appends come in two flavours: fire-and-forget `appendRow`/`appendRows` return
+ * nothing, while `appendRowWithWait`/`appendRowsWithWait` return a promise that
+ * resolves when Snowflake acknowledges the rows. Every append must carry an opaque
+ * `appendToken` — required, but nullable — handed back to the handler registered via
+ * `setErrorHandler` when that append fails asynchronously, or to `setSuccessHandler`
+ * when it is acknowledged; pass `null` to opt that append out of both handlers.
  *
  * Create instances using `client.getElasticChannel()`.
  */
@@ -353,24 +475,119 @@ export class StreamingIngestElasticChannel {
   /** The binary input format. One of: "BASE64", "HEX", "UTF-8". */
   readonly binaryInputFormat: string;
 
+  /**
+   * Append a single row into the elastic channel without waiting for the
+   * acknowledgement (fire-and-forget). The append is still registered for the
+   * error handler, so an asynchronous failure is reported through
+   * `setErrorHandler` (keyed by `appendToken`), just not through a promise. Use
+   * `appendRowWithWait` when you need one to await.
+   *
+   * @param row - Row data as column-name to value pairs
+   * @param appendToken - Required caller-supplied opaque id for this append, handed
+   *   to the `setErrorHandler` handler on asynchronous failure, or to the
+   *   `setSuccessHandler` handler on acknowledgement. Not sent to Snowflake; any
+   *   value (including `""`) is valid. The argument is mandatory: pass `null`
+   *   explicitly to leave the append untracked for both handlers. The token is
+   *   retained in memory until the append is acknowledged, so a large object raises
+   *   the memory footprint of in-flight appends — prefer a small value.
+   * @throws TypeError If row is null or undefined
+   * @throws StreamingIngestError If the row appending fails synchronously
+   */
+  appendRow(row: Record<string, any>, appendToken: unknown): void;
+
+  /**
+   * Append multiple rows into the elastic channel without waiting for the
+   * acknowledgement (fire-and-forget). The append is still registered for the
+   * error handler, so an asynchronous failure is reported through
+   * `setErrorHandler` (keyed by `appendToken`), just not through a promise. Use
+   * `appendRowsWithWait` when you need one to await.
+   *
+   * @param rows - Array of row objects (column-name to value pairs)
+   * @param appendToken - Required caller-supplied opaque id for this batch, handed
+   *   to the `setErrorHandler` handler on asynchronous failure, or to the
+   *   `setSuccessHandler` handler on acknowledgement. Not sent to Snowflake; any
+   *   value (including `""`) is valid. The argument is mandatory: pass `null`
+   *   explicitly to leave the append untracked for both handlers. The token is
+   *   retained in memory until the append is acknowledged, so a large object raises
+   *   the memory footprint of in-flight appends — prefer a small value.
+   * @throws TypeError If rows is not an array
+   * @throws StreamingIngestError If the rows appending fails synchronously
+   */
+  appendRows(rows: Record<string, any>[], appendToken: unknown): void;
+
   /**
    * Append a single row into the elastic channel. The returned promise resolves
-   * when Snowflake acknowledges the row.
+   * when Snowflake acknowledges the row. If an error handler is registered it
+   * also fires on an asynchronous failure — dual delivery.
    *
    * @param row - Row data as column-name to value pairs
+   * @param appendToken - Required caller-supplied opaque id for this append, handed
+   *   to the `setErrorHandler` handler on asynchronous failure, or to the
+   *   `setSuccessHandler` handler on acknowledgement. Not sent to Snowflake; any
+   *   value (including `""`) is valid. The argument is mandatory: pass `null`
+   *   explicitly to leave the append untracked for both handlers. The token is
+   *   retained in memory until the append is acknowledged, so a large object raises
+   *   the memory footprint of in-flight appends — prefer a small value.
    * @throws StreamingIngestError If the row appending fails
    */
-  appendRow(row: Record<string, any>): Promise<void>;
+  appendRowWithWait(row: Record<string, any>, appendToken: unknown): Promise<void>;
 
   /**
    * Append multiple rows into the elastic channel. The returned promise resolves
-   * when Snowflake acknowledges the batch.
+   * when Snowflake acknowledges the batch. If an error handler is registered it
+   * also fires on an asynchronous failure — dual delivery.
    *
    * @param rows - Array of row objects (column-name to value pairs)
+   * @param appendToken - Required caller-supplied opaque id for this batch, handed
+   *   to the `setErrorHandler` handler on asynchronous failure, or to the
+   *   `setSuccessHandler` handler on acknowledgement. Not sent to Snowflake; any
+   *   value (including `""`) is valid. The argument is mandatory: pass `null`
+   *   explicitly to leave the append untracked for both handlers. The token is
+   *   retained in memory until the append is acknowledged, so a large object raises
+   *   the memory footprint of in-flight appends — prefer a small value.
    * @throws TypeError If rows is not an array
    * @throws StreamingIngestError If the rows appending fails
    */
-  appendRows(rows: Record<string, any>[]): Promise<void>;
+  appendRowsWithWait(rows: Record<string, any>[], appendToken: unknown): Promise<void>;
+
+  /**
+   * Register (or replace) a handler invoked when appends fail *asynchronously*,
+   * i.e. after the append call already returned. Fires once per failure event
+   * with a single {@link ErrorDetail} bundling the `appendToken`s that failed
+   * together (a server-ack batch, or every in-flight append on invalidation) and
+   * their common error, so callers need not await each promise. Both append
+   * flavours are covered: it is the only failure signal for the fire-and-forget
+   * ones, and an additional one for the `WithWait` ones, whose promise still
+   * rejects. Only appends given an `appendToken` appear, and tokens are opaque and
+   * not deduplicated. Synchronous failures (closed channel, serialization, bad
+   * arguments) throw from the append call and never reach the handler. A handler
+   * that throws is caught and logged.
+   *
+   * @param handler - Called with one {@link ErrorDetail} per failure event
+   * @throws TypeError If handler is not a function, or declares more than one
+   *   parameter (it is called with a single {@link ErrorDetail})
+   */
+  setErrorHandler(handler: (detail: ErrorDetail) => void): void;
+
+  /**
+   * Register (or replace) a handler invoked when appends are acknowledged by
+   * Snowflake. Fires once per successful ack batch with a single
+   * {@link SuccessDetail} bundling the `appendToken`s acknowledged together, so
+   * callers need not await each promise. Both append flavours are covered: it is
+   * the only success signal for the fire-and-forget ones, and an additional one for
+   * the `WithWait` ones, whose promise still resolves. Purely opt-in — without a
+   * registered handler nothing is collected. Only appends given an `appendToken`
+   * appear, and tokens are opaque and not deduplicated. A handler that throws is
+   * caught and logged.
+   *
+   * Like the error handler, this runs on the acknowledgement path, so a slow
+   * handler delays subsequent acknowledgements — keep it short.
+   *
+   * @param handler - Called with one {@link SuccessDetail} per successful ack batch
+   * @throws TypeError If handler is not a function, or declares more than one
+   *   parameter (it is called with a single {@link SuccessDetail})
+   */
+  setSuccessHandler(handler: (detail: SuccessDetail) => void): void;
 
   /**
    * Initiate a flush of all buffered data for this channel but do not wait for
@@ -380,6 +597,18 @@ export class StreamingIngestElasticChannel {
    */
   initiateFlush(): void;
 
+  /**
+   * Wait for all buffered data in this channel to be flushed to Snowflake.
+   *
+   * @param options - Wait options
+   * @throws StreamingIngestError If waiting for the flush fails
+   * @throws Error If the timeout is reached
+   */
+  waitForFlush(options?: {
+    /** Optional timeout in milliseconds. */
+    timeoutMs?: number;
+  }): Promise<void>;
+
   /**
    * Get the current status of this channel.
    *
@@ -440,8 +669,16 @@ export class ChannelStatus {
 export class StreamingIngestError extends Error {
   /** The error code (for example, "ConfigError", "ChannelNotFound"). */
   readonly errorCode: string;
-  /** The error message. Inherited from `Error`; redeclared for autodoc visibility. */
+  /**
+   * Decorated error message: `{errorCode}: {detail} (HTTP {code} {name})`.
+   * Inherited from `Error`; this is what `stack` / `console.error` print.
+   */
   readonly message: string;
+  /**
+   * Original detail passed to the constructor, without error-code / HTTP-status
+   * decoration. Analog of Java `SFException#getDetailMessage()`.
+   */
+  readonly detail: string;
   /** HTTP status code indicating error category. */
   readonly httpStatusCode: number;
   /** HTTP status name (for example, "Bad Request"). */

package/src/index.js

@@ -27,6 +27,8 @@ const {
 } = require("./client.js");
 const { StreamingIngestChannel } = require("./channel.js");
 const { StreamingIngestElasticChannel } = require("./elastic_channel.js");
+const { ErrorDetail } = require("./error_detail.js");
+const { SuccessDetail } = require("./success_detail.js");
 
 // Load native addon and bootstrap the Rust runtime
 const native = loadNativeAddon();
@@ -52,6 +54,8 @@ module.exports = {
   StreamingIngestElasticChannel,
   StreamingIngestError,
   StreamingIngestErrorCode,
+  ErrorDetail,
+  SuccessDetail,
   ChannelStatus,
   // E2E testing only - available when compiled with e2e_test feature
   registerMockRoute: native.registerMockRoute,

package/src/loader.js

@@ -20,7 +20,7 @@
 const path = require("node:path");
 const fs = require("node:fs");
 
-const LOG_PREFIX = "[snowpipe-streaming]";
+const { LOG_PREFIX } = require("./log.js");
 
 // Verbose loader breadcrumbs are gated on SS_LOG_LEVEL=debug|trace, matching
 // the env var the Rust core and Java/Python SDKs already use (see

package/src/log.js

@@ -0,0 +1,27 @@
+// Copyright 2026 Snowflake Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+"use strict";
+
+/**
+ * Prefix for every line this SDK writes to stderr, so SDK output is
+ * attributable in a customer's log stream. Used by the native-addon loader and
+ * by the elastic channel's acknowledgement path, which are the only places the
+ * SDK logs on its own (everything else surfaces as a thrown or rejected
+ * StreamingIngestError).
+ */
+const LOG_PREFIX = "[snowpipe-streaming]";
+
+module.exports = { LOG_PREFIX };

package/src/mark_complete_callback.js

@@ -32,6 +32,14 @@
 // directly — same end state, driven from JS.
 
 const { StreamingIngestError } = require("./errors.js");
+const { ErrorDetail } = require("./error_detail.js");
+const { SuccessDetail } = require("./success_detail.js");
+const { LOG_PREFIX } = require("./log.js");
+
+// A handler runs inline on the acknowledgement tick, so blocking it stalls the whole event loop —
+// every channel on this client, and the rest of the application. Warn past this many milliseconds.
+// Timing uses the global `performance` (Node >= 16; this package requires >= 20), like `Buffer`.
+const SLOW_HANDLER_WARN_THRESHOLD_MILLIS = 200;
 
 function buildError(success, errorCode, message, httpStatusCode, httpStatusName) {
   if (success) {
@@ -52,12 +60,23 @@ function buildError(success, errorCode, message, httpStatusCode, httpStatusName)
  * for JS-driven invalidation. The native reference is plugged in after the
  * channel is opened (chicken-and-egg: these callbacks are passed *into* the
  * open call, so they exist before the native handle does).
+ *
+ * Also owns the customer error handler, invoked once per failure event with a
+ * single {@link ErrorDetail} carrying the append tokens of every append that
+ * failed under a common error, and the customer success handler, invoked once per
+ * successful server-ack batch with a single {@link SuccessDetail} carrying that
+ * batch's append tokens. Tokens are opaque and optional, so only entries
+ * that carry one are reported. This class is elastic-only, so the append token
+ * rides on the pending-map value; Java/Python need a parallel token map because
+ * their callback also serves regular channels.
  */
 class ElasticChannelAckState {
   constructor(pendingFutures) {
     this._pendingFutures = pendingFutures;
     this._invalidated = false;
     this._nativeChannel = null;
+    this._errorHandler = null;
+    this._successHandler = null;
     this.markComplete = this._markComplete.bind(this);
     this.invalidateAll = this._invalidateAll.bind(this);
   }
@@ -67,8 +86,149 @@ class ElasticChannelAckState {
     this._nativeChannel = nativeChannel;
   }
 
+  /**
+   * Register (or replace) the customer error handler. The argument is validated
+   * by `StreamingIngestElasticChannel.setErrorHandler`.
+   */
+  setErrorHandler(handler) {
+    this._errorHandler = handler;
+  }
+
+  /**
+   * Register (or replace) the customer success handler. The argument is validated
+   * by `StreamingIngestElasticChannel.setSuccessHandler`.
+   */
+  setSuccessHandler(handler) {
+    this._successHandler = handler;
+  }
+
+  /**
+   * Invoke the error handler once for a batch of append tokens that failed with a
+   * common error. Both are bundled into the single {@link ErrorDetail} the handler
+   * takes (mirroring Java's and Python's `ErrorDetail`), so new fields can be
+   * added later without changing the handler signature. No-op without a handler
+   * or on an empty batch. A throwing handler is caught and logged so it can't
+   * break the acknowledgement path.
+   *
+   * @param {unknown[]} appendTokens - Opaque append tokens of the appends that failed together.
+   * @param {StreamingIngestError} error - The error that failed them.
+   * @param {string | null} requestId - Snowflake request id of the failing response, or null.
+   * @param {number} retryCount - How many retries that request took; 0 with a null id, where it
+   *   carries no meaning.
+   */
+  fireErrorHandler(appendTokens, error, requestId, retryCount) {
+    if (this._errorHandler === null || appendTokens == null || appendTokens.length === 0) {
+      return;
+    }
+    const start = performance.now();
+    try {
+      this._errorHandler(new ErrorDetail(appendTokens, error, requestId, retryCount));
+    } catch (handlerErr) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `${LOG_PREFIX} Elastic channel error handler threw for ` +
+          `appendTokens=[${appendTokens.join(", ")}]; ignoring.`,
+        handlerErr,
+      );
+    } finally {
+      this._logHandlerDuration("error", start, appendTokens.length);
+    }
+  }
+
+  /**
+   * Warn when a handler invocation crossed {@link SLOW_HANDLER_WARN_THRESHOLD_MILLIS}.
+   * It runs inline on the event-loop tick that drains the Rust acknowledgement, so
+   * blocking it stalls this client's acknowledgements and everything else on the
+   * loop. Only the slow case is logged — a per-invocation line would fire once per
+   * acknowledgement batch, effectively once per append on a busy pipe.
+   *
+   * @param {string} handlerKind - "error" or "success", for the log message.
+   * @param {number} start - `performance.now()` captured before invoking the handler.
+   * @param {number} appendTokenCount - how many append tokens the invocation carried.
+   */
+  _logHandlerDuration(handlerKind, start, appendTokenCount) {
+    const elapsedMillis = performance.now() - start;
+    if (elapsedMillis >= SLOW_HANDLER_WARN_THRESHOLD_MILLIS) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `${LOG_PREFIX} Elastic channel ${handlerKind} handler took ` +
+          `${elapsedMillis.toFixed(1)} ms for ${appendTokenCount} appendToken(s); it is blocking ` +
+          `the event loop — offload heavy work to a worker thread or your own queue.`,
+      );
+    }
+  }
+
+  /**
+   * Invoke the success handler once for a batch of append tokens acknowledged
+   * together. They are bundled into the single {@link SuccessDetail} the handler
+   * takes, so new fields can be added later without changing the handler
+   * signature. No-op without a handler or on an empty batch. A throwing handler is
+   * caught and logged so it can't break the acknowledgement path.
+   *
+   * @param {unknown[]} appendTokens - Opaque append tokens of the appends acknowledged together.
+   * @param {string | null} requestId - Snowflake request id of the acking response, or null.
+   * @param {number} retryCount - How many retries that request took.
+   */
+  fireSuccessHandler(appendTokens, requestId, retryCount) {
+    if (requestId === null || requestId === undefined) {
+      // SuccessDetail.requestId is declared non-null: an acknowledgement can only come from a
+      // request Snowflake answered. Reaching here means the FFI bridge dropped the field. Log it
+      // rather than withhold the customer's notification over a support-escalation value.
+      // eslint-disable-next-line no-console
+      console.error(
+        `${LOG_PREFIX} Elastic channel success ack carried no requestId for appendTokens=` +
+          `${appendTokens}; this is an SDK defect, the acknowledgement itself is still reported.`,
+      );
+    }
+    if (this._successHandler === null || appendTokens.length === 0) {
+      return;
+    }
+    const start = performance.now();
+    try {
+      this._successHandler(new SuccessDetail(appendTokens, requestId, retryCount));
+    } catch (handlerErr) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `${LOG_PREFIX} Elastic channel success handler threw for ` +
+          `appendTokens=[${appendTokens.join(", ")}]; ignoring.`,
+        handlerErr,
+      );
+    } finally {
+      this._logHandlerDuration("success", start, appendTokens.length);
+    }
+  }
+
+  /**
+   * Reject and clear every pending promise, returning the append tokens of the
+   * appends that carried one so the handler can be fired once the whole loop is
+   * done. Untracked appends (no append token) reject without being reported.
+   */
+  _rejectAllPending(error) {
+    const appendTokens = [];
+    for (const pending of this._pendingFutures.values()) {
+      pending.reject(error);
+      if (pending.appendToken != null) {
+        appendTokens.push(pending.appendToken);
+      }
+    }
+    this._pendingFutures.clear();
+    return appendTokens;
+  }
+
   _markComplete(payload) {
-    const { futureIdRanges, success, errorCode, message, httpStatusCode, httpStatusName } = payload;
+    const {
+      futureIdRanges,
+      success,
+      errorCode,
+      message,
+      httpStatusCode,
+      httpStatusName,
+      // requestId defaults to null (not undefined) so a missing native field still honors the
+      // declared `string | null` contract. retryCount defaults to 0: it is a plain number, and a
+      // null requestId is what marks the pair absent.
+      requestId = null,
+      retryCount = 0,
+    } = payload;
 
     if (futureIdRanges.length % 2 !== 0) {
       const errMsg = `future_id_ranges has odd length ${futureIdRanges.length}, expected even (flattened [min, max] pairs)`;
@@ -81,6 +241,8 @@ class ElasticChannelAckState {
     const error = buildError(success, errorCode, message, httpStatusCode, httpStatusName);
 
     const missingIds = [];
+    const errorTokensToNotify = [];
+    const successTokensToNotify = [];
     for (let i = 0; i < futureIdRanges.length; i += 2) {
       const min = Number(futureIdRanges[i]);
       const max = Number(futureIdRanges[i + 1]);
@@ -93,12 +255,27 @@ class ElasticChannelAckState {
         this._pendingFutures.delete(fid);
         if (error) {
           pending.reject(error);
+          // Only appends the caller gave an append token are surfaced to the handler.
+          if (pending.appendToken != null) {
+            errorTokensToNotify.push(pending.appendToken);
+          }
         } else {
           pending.resolve();
+          // Same rule on the success side: an untracked append has nothing to report.
+          if (pending.appendToken != null) {
+            successTokensToNotify.push(pending.appendToken);
+          }
         }
       }
     }
 
+    // Fire once after the resolve/reject loop, so a slow or throwing handler can't
+    // delay or skip a sibling append. Mirrors Java firing outside the ack lock.
+    // A batch is wholly successful or wholly failed, so only one of these fires.
+    // Both carry the request id, and retry count, of the response that drove this ack.
+    this.fireErrorHandler(errorTokensToNotify, error, requestId, retryCount);
+    this.fireSuccessHandler(successTokensToNotify, requestId, retryCount);
+
     // `_invalidated` gate matches Java/Python: after invalidateAll has run,
     // the map is empty and further mark-complete callbacks for in-flight
     // batches are expected to find nothing — don't escalate that to fatal.
@@ -120,10 +297,11 @@ class ElasticChannelAckState {
         payload.httpStatusCode,
         payload.httpStatusName,
       ) || new StreamingIngestError("Fatal", "Elastic channel invalidated", 409, "Conflict");
-    for (const pending of this._pendingFutures.values()) {
-      pending.reject(error);
-    }
-    this._pendingFutures.clear();
+    // No request id: invalidation fails every in-flight append at once and is not
+    // attributable to the one server response any of them was waiting on. Same in-flight race as
+    // the close/drop path below: an append whose request was already on the wire is failed here and
+    // that request may still be applied, which the ErrorDetail contract covers via the null id.
+    this.fireErrorHandler(this._rejectAllPending(error), error, null, 0);
   }
 
   /**
@@ -132,25 +310,32 @@ class ElasticChannelAckState {
    * via `_invalidated`. Promises are rejected first so the user observation
    * doesn't depend on the FFI call succeeding; the native invalidate is
    * best-effort — Rust will fire `invalidateAll` on its next informer
-   * tick, which finds an empty map and is a no-op.
+   * tick, which finds an empty map and is a no-op. The error handler fires last,
+   * after both the rejections and the FFI call, with no request id — the error is
+   * ours, not a Snowflake response.
    */
   _invalidateLocally(error) {
     if (this._invalidated) {
       return;
     }
     this._invalidated = true;
-    for (const pending of this._pendingFutures.values()) {
-      pending.reject(error);
-    }
-    this._pendingFutures.clear();
+    const errorTokensToNotify = this._rejectAllPending(error);
     if (this._nativeChannel) {
       try {
-        this._nativeChannel.invalidateChannel(error.message);
+        this._nativeChannel.invalidateChannel(error.detail);
       } catch (invErr) {
         // eslint-disable-next-line no-console
-        console.error("Elastic channel invalidate_channel FFI call failed:", invErr);
+        console.error(`${LOG_PREFIX} Elastic channel invalidate_channel FFI call failed:`, invErr);
       }
     }
+    // Races with an in-flight request, and reports the pessimistic side of it. An append whose
+    // request is already on the wire is failed here locally; if it then lands, the rows are in the
+    // table even though the customer was told the append failed. The handler reports a null
+    // requestId and retryCount 0, which per the ErrorDetail contract reads as "the SDK sent this
+    // once, so it introduced no duplicate" -- true, but not a claim that the rows are absent.
+    // Nothing here can close the race: the promise has to be settled at close time and the
+    // request's outcome is not knowable yet. A caller needing certainty must reconcile downstream.
+    this.fireErrorHandler(errorTokensToNotify, error, null, 0);
   }
 }
 

package/src/success_detail.js

@@ -0,0 +1,73 @@
+// Copyright 2026 Snowflake Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+"use strict";
+
+/**
+ * The payload handed to an elastic-channel success handler (registered via
+ * {@link StreamingIngestElasticChannel#setSuccessHandler}) when appends are
+ * acknowledged by Snowflake.
+ *
+ * Delivered once per successful acknowledgement, carrying the caller-supplied
+ * append tokens of every append that was acked together in that server-ack
+ * batch. There is no error field — the counterpart to {@link ErrorDetail}, whose
+ * `error` explains a failure, has nothing to explain.
+ *
+ * Instances are created by the SDK and deeply frozen — both the object and its
+ * `appendTokens` array — so a handler cannot mutate what a sibling handler or a
+ * later log statement will read. Handlers only read this type, so new fields can
+ * be added over time without breaking them.
+ */
+class SuccessDetail {
+  /**
+   * @param {unknown[]} appendTokens - The opaque, caller-supplied append tokens of
+   *   the appends that were acknowledged together. Never empty; a token reused
+   *   across appends appears once per acknowledged append (not deduplicated).
+   *   Frozen here, so callers must pass an array they are handing over.
+   * @param {string} requestId - The Snowflake request id of the server response that
+   *   acknowledged these appends, for support escalation.
+   * @param {number} retryCount - How many retries that request took: 0 when the
+   *   first attempt was acknowledged, N when the SDK retried N times before
+   *   Snowflake accepted it.
+   *
+   *   **Use this to decide whether these rows may be duplicated in the table.** A retry
+   *   re-sends the same rowset, and the SDK retries whenever it cannot tell that the
+   *   previous attempt failed -- a timeout or a 5xx may mean the rows were never
+   *   processed, or that they were processed and only the response was lost. `0` means
+   *   the SDK sent this rowset once and introduced no duplicate; `> 0` means it sent it
+   *   more than once and an earlier attempt may already have been applied, so the rows
+   *   may appear more than once. Reconcile or de-duplicate downstream if you need
+   *   exactly-once. The signal is conservative: it counts every re-send, including an
+   *   authentication refresh, which is rejected before the rows are processed and so
+   *   cannot have duplicated anything -- `> 0` means "a duplicate is possible", not
+   *   "a duplicate happened".
+   *
+   *   Read it only when `requestId` is non-null: an acknowledgement with no originating
+   *   request reports 0 too. A steadily non-zero count also means the SDK is absorbing
+   *   retries on your behalf.
+   */
+  constructor(appendTokens, requestId, retryCount) {
+    // Freeze the array as well as the instance: `Object.freeze(this)` alone would
+    // still let a handler push into or reorder appendTokens. Only the array
+    // itself is frozen, not the tokens inside it — those are the caller's own
+    // opaque objects and are handed back untouched.
+    this.appendTokens = Object.freeze(appendTokens);
+    this.requestId = requestId;
+    this.retryCount = retryCount;
+    Object.freeze(this);
+  }
+}
+
+module.exports = { SuccessDetail };