/* * 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. */ // // TypeScript declaration file for the Snowpipe Streaming Node.js SDK. // // This file serves two purposes: // 1. Provides TypeScript/JavaScript users with autocomplete and type checking // 2. Used by TypeDoc (see docs/typedoc.json) to generate API reference HTML // // This file mirrors the public API surface defined in src/*.js. // The CI lint step (`npm run lint`) runs check-types-sync.js which verifies // that this file stays consistent with the JavaScript source. // /** * Create a new streaming ingest client. Each client is tied to a single * database, schema, and pipe. To ingest into multiple pipes, create * multiple clients. * * Either `profilePath` or `properties` must be provided for authentication. * If both are provided, `properties` takes precedence for conflicting keys. * * @param options - Client configuration * @throws StreamingIngestError If client creation fails */ export function createClient(options: { /** A unique name to identify this client instance, used for tracking and debugging purposes. */ clientName: string; /** The name of the Snowflake database where data will be ingested. */ dbName: string; /** The name of the schema within the database. */ schemaName: string; /** The name of the pipe that will be used for streaming ingestion. */ pipeName: string; /** Path to a JSON file containing connection properties and authentication information. */ profilePath?: string; /** Connection properties and authentication information. Common properties include account, user, private_key, url * and application (partner app name for User-Agent; 1–64 visible ASCII chars (0x21–0x7E), * excluding `(`, `)`, `\`; regex: `^[!-'*-\[-\]-~]{1,64}$`). */ properties?: Record; }): Promise; /** * Create a new streaming ingest client in table mode. The pipe name is derived * from the table name by appending "-STREAMING". Each client is tied to a single * database, schema, and (derived) pipe. * * Either `profilePath` or `properties` must be provided for authentication. * If both are provided, `properties` takes precedence for conflicting keys. * * @param options - Client configuration * @throws StreamingIngestError If client creation fails */ export function createTableClient(options: { /** A unique name to identify this client instance, used for tracking and debugging purposes. */ clientName: string; /** The name of the Snowflake database where data will be ingested. */ dbName: string; /** The name of the schema within the database. */ schemaName: string; /** The table name. The pipe name is derived as `${tableName}-STREAMING`. */ tableName: string; /** Path to a JSON file containing connection properties and authentication information. */ profilePath?: string; /** Connection properties and authentication information. */ properties?: Record; }): Promise; /** * A client that is the starting point for using the Streaming Ingest client APIs. * * A single client maps to exactly one account/database/schema/pipe in Snowflake; * however, multiple clients can point to the same account/database/schema/pipe. * Each client contains information for Snowflake authentication and authorization, * and it is used to create one or more StreamingIngestChannel instances for data * ingestion. * * Create instances using the `createClient()` function. */ export class StreamingIngestClient { private constructor(); /** The client name. */ readonly clientName: string; /** The database name. */ readonly dbName: string; /** The schema name. */ readonly schemaName: string; /** The pipe name. */ readonly pipeName: string; /** Whether the client is closed. */ readonly isClosed: boolean; /** The binary input format. One of: "BASE64", "HEX", "UTF-8". */ readonly binaryInputFormat: string; /** * Close the client. If waitForFlush is true, the client waits for all data in every * channel to be flushed to Snowflake before shutting down. * * @param options - Close options * @throws StreamingIngestError If closing the client fails or the timeout is reached */ close(options?: { /** Whether to wait for the flush to complete, defaults to true. */ waitForFlush?: boolean; /** Optional timeout in milliseconds for the flush operation. */ timeoutMs?: number; }): Promise; /** * Open a channel with the given name. The channel is opened on the * database/schema/pipe defined by this client. If the channel already exists, * Snowflake reuses the latest persisted offset token unless a new one is provided. * * @param options - Channel options * @throws StreamingIngestError If opening the channel fails */ openChannel(options: { /** The name of the channel to open. */ name: string; /** Optional offset token to set on the channel. If not provided and this reopens an existing channel, the latest persisted offset token is reused. */ offsetToken?: string; }): Promise<{ /** The opened channel instance. */ channel: StreamingIngestChannel; /** The channel status at the time of opening, or null if not available. */ status: ChannelStatus | null; }>; /** * Get the elastic channel for this client. Elastic channels have no offset * tokens and their lifecycle is tied to the client (there is no close method). * The same instance is returned on repeated calls (singleton). * * @throws StreamingIngestError If the client is closed or the channel cannot be opened */ getElasticChannel(): Promise; /** * Drop a channel by name (server-side removal). * * @param channelName - Name of the channel to drop * @throws StreamingIngestError If dropping the channel fails */ dropChannel(channelName: string): Promise; /** * Get the status of multiple channels. Can fetch status for channels not * opened by this client. * * @param channelNames - Names of channels to query * @throws StreamingIngestError If retrieving statuses fails */ getChannelStatuses(channelNames: string[]): Promise>; /** * Get the latest committed offset tokens for multiple channels. * * @param channelNames - Names of channels to query * @throws StreamingIngestError If retrieving offset tokens fails */ getLatestCommittedOffsetTokens(channelNames: string[]): Promise>; /** * Initiate a flush of the client. Causes all outstanding buffered data to be * flushed to Snowflake. Data can still be accepted by the client after calling * this method — this is an asynchronous call that returns after the flush is * initiated for all channels. * * @throws StreamingIngestError If initiating the flush fails */ initiateFlush(): void; /** * Wait for all buffered data in all channels managed by this client to be flushed * to Snowflake. This method triggers a flush of all pending data across all channels * and waits for the flush operations to complete. * * @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; } /** * A channel for streaming data into a Snowflake table. * * A channel represents a logical stream of data into a single table through a pipe. * Multiple channels can be opened on the same pipe for parallel ingestion. Each channel * maintains its own offset token for exactly-once delivery guarantees. * * Create instances using `client.openChannel()`. */ export class StreamingIngestChannel { private constructor(); /** The channel name. */ readonly channelName: string; /** The database name. */ readonly dbName: string; /** The schema name. */ readonly schemaName: string; /** The pipe name. */ readonly pipeName: string; /** Whether the channel is closed. */ readonly isClosed: boolean; /** The binary input format. One of: "BASE64", "HEX", "UTF-8". */ readonly binaryInputFormat: string; /** * Append a single row into the channel. * * The row is an object with keys as column names and values as column values. * Supported value types: null, undefined, boolean, number, string, BigInt, * Buffer, Uint8Array, Date, Array, and Object. * * @param row - Row data as column-name to value pairs * @param offsetToken - Optional offset token, used to track the ingestion * progress and replay ingestion in case of failures * @throws StreamingIngestError If the row appending fails */ appendRow(row: Record, offsetToken?: string): void; /** * Append multiple rows to the channel. * * Each row is an object with keys as column names and values as column values. * Supported value types: null, undefined, boolean, number, string, BigInt, * Buffer, Uint8Array, Date, Array, and Object. * * @param rows - Array of row objects (column-name to value pairs) * @param startOffsetToken - Optional start offset token of the batch * @param endOffsetToken - Optional end offset token of the batch * @throws TypeError If rows is not an array * @throws StreamingIngestError If the rows appending fails */ appendRows(rows: Record[], startOffsetToken?: string, endOffsetToken?: string): void; /** * Close the channel. * * @param options - Close options * @throws StreamingIngestError If closing the channel fails */ close(options?: { /** Whether to drop the channel on the server, defaults to false. */ drop?: boolean; /** Whether to wait for the flush to complete, defaults to true. */ waitForFlush?: boolean; /** Optional timeout in milliseconds for the flush operation. */ timeoutMs?: number; }): Promise; /** * Initiate a flush of all buffered data for this channel but do not wait for * the flush to complete. Calls to appendRow/appendRows are still allowed on * the channel after calling this method. * * @throws StreamingIngestError If the flush cannot be initiated */ 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; /** * Get the current status of this channel. * * @throws StreamingIngestError If getting the channel status fails */ getChannelStatus(): Promise; /** * Get the latest committed offset token for this channel. * * @returns The latest committed offset token, or null if the channel is brand new * @throws StreamingIngestError If getting the latest committed offset token fails */ getLatestCommittedOffsetToken(): Promise; /** * Wait for a specific offset token to be committed. * * Snowflake commits offset tokens in batches, so the latest committed offset token * may jump past the one you are waiting for. The tokenChecker should handle this * case by doing a range check (greater than or equal) rather than an exact match. * * @param tokenChecker - A callable that receives the latest committed offset token * (which may be null) and should return true when the wait condition is satisfied * @param options - Wait options * @throws StreamingIngestError If waiting for the commit fails * @throws Error If the timeout is reached * @throws TypeError If tokenChecker is not a function * @throws RangeError If timeoutMs is negative */ waitForCommit(tokenChecker: (token: string | null) => boolean, options?: { /** Optional timeout in milliseconds. */ timeoutMs?: number; }): Promise; } /** * 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()`. * 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()`. */ export class StreamingIngestElasticChannel { private constructor(); /** The channel name (always "ELASTIC"). */ readonly channelName: string; /** The database name. */ readonly dbName: string; /** The schema name. */ readonly schemaName: string; /** The pipe name. */ readonly pipeName: string; /** Whether the channel is closed (because the client was closed). */ readonly isClosed: boolean; /** 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, 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[], appendToken: unknown): void; /** * Append a single row into the elastic channel. The returned promise resolves * 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 */ appendRowWithWait(row: Record, appendToken: unknown): Promise; /** * Append multiple rows into the elastic channel. The returned promise resolves * 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 */ appendRowsWithWait(rows: Record[], appendToken: unknown): 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 `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 * the flush to complete. * * @throws StreamingIngestError If the flush cannot be initiated */ 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; /** * Get the current status of this channel. * * @throws StreamingIngestError If getting the channel status fails */ getChannelStatus(): Promise; } /** * Status information for a streaming ingest channel. * * Contains metadata about the channel's current state including the latest * committed offset token, row counts, error information, and processing latency. * Returned by `client.getChannelStatuses()` and `channel.getChannelStatus()`. */ export class ChannelStatus { private constructor(); /** The database name. */ readonly databaseName: string; /** The schema name. */ readonly schemaName: string; /** The pipe name. */ readonly pipeName: string; /** The channel name. */ readonly channelName: string; /** The channel status code. */ readonly statusCode: string; /** The latest committed offset token, or null if the channel is brand new. */ readonly latestCommittedOffsetToken: string | null; /** When the channel was created. */ readonly createdOn: Date | null; /** Total number of rows successfully inserted. */ readonly rowsInsertedCount: number; /** Total number of rows parsed. */ readonly rowsParsedCount: number; /** Total number of rows that encountered errors. */ readonly rowsErrorCount: number; /** Upper bound offset token for the last error, or null if no errors. */ readonly lastErrorOffsetTokenUpperBound: string | null; /** The message of the last error, or null if no errors. */ readonly lastErrorMessage: string | null; /** Timestamp of the last error, or null if no errors. */ readonly lastErrorTimestamp: Date | null; /** Average processing latency in milliseconds, or null if not available. */ readonly serverAvgProcessingLatencyMs: number | null; /** When the status was last refreshed from the server. */ readonly lastRefreshedOn: Date | null; } /** * Error thrown by the Snowpipe Streaming SDK. * * Includes structured error information: an error code, HTTP status code, * and descriptive message. Use `errorCode` and `httpStatusCode` to determine * the appropriate recovery action. */ export class StreamingIngestError extends Error { /** The error code (for example, "ConfigError", "ChannelNotFound"). */ readonly errorCode: string; /** * 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"). */ readonly httpStatusName: string; }