@forgecart/sdk 1.202609201502.0 → 1.202609211357.0

package/dist/admin-types.generated.d.ts

@@ -2127,6 +2127,7 @@ export type EcomInboundEvent = {
     extResourceId?: Maybe<Scalars['String']['output']>;
     id: Scalars['ID']['output'];
     lastErrorCode?: Maybe<Scalars['String']['output']>;
+    platformMessage?: Maybe<Scalars['String']['output']>;
     processedAt?: Maybe<Scalars['DateTime']['output']>;
     providerCode: Scalars['String']['output'];
     status: Scalars['String']['output'];
@@ -2204,6 +2205,7 @@ export type EcomVariantLink = {
     id: Scalars['ID']['output'];
     lastErrorCode?: Maybe<Scalars['String']['output']>;
     lastPushedAt?: Maybe<Scalars['DateTime']['output']>;
+    platformMessage?: Maybe<Scalars['String']['output']>;
     productId?: Maybe<Scalars['ID']['output']>;
     syncState: Scalars['String']['output'];
     updatedAt: Scalars['DateTime']['output'];
@@ -11720,7 +11722,7 @@ export type AdminDeploymentStatusChangedSubscription = {
     deploymentStatusChanged: Pick<Deployment, 'id' | 'type' | 'status' | 'url' | 'errorMessage' | 'instances' | 'lastDeployedAt'>;
 };
 export type EcomConnectionFieldsFragment = Pick<EcomConnection, 'id' | 'createdAt' | 'updatedAt' | 'providerCode' | 'externalAccountId' | 'externalScope' | 'status' | 'statusErrorCode' | 'commerceMode' | 'syncCatalog' | 'syncInventory' | 'ingestOrders' | 'syncCustomers' | 'orchestrateRefunds' | 'inventoryShortfallPolicy' | 'ingestExternalStockAdjustments' | 'defaultStockLocationId' | 'shopCurrencyCode' | 'channelPluginId'>;
-export type EcomInboundEventFieldsFragment = Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'processedAt'>;
+export type EcomInboundEventFieldsFragment = Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'platformMessage' | 'processedAt'>;
 export type EcomConnectionsQueryVariables = Exact<{
     [key: string]: never;
 }>;
@@ -11745,7 +11747,7 @@ export type EcomBlockedInboundEventsQueryVariables = Exact<{
     connectionId: Scalars['ID']['input'];
 }>;
 export type EcomBlockedInboundEventsQuery = {
-    ecomBlockedInboundEvents: Array<Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'processedAt'>>;
+    ecomBlockedInboundEvents: Array<Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'platformMessage' | 'processedAt'>>;
 };
 export type CreateEcomConnectionMutationVariables = Exact<{
     input: CreateEcomConnectionInput;
@@ -11793,14 +11795,14 @@ export type RetryEcomInboundEventMutationVariables = Exact<{
     eventId: Scalars['ID']['input'];
 }>;
 export type RetryEcomInboundEventMutation = {
-    retryEcomInboundEvent: Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'processedAt'>;
+    retryEcomInboundEvent: Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'platformMessage' | 'processedAt'>;
 };
-export type EcomVariantLinkFieldsFragment = Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'attempts' | 'lastPushedAt'>;
+export type EcomVariantLinkFieldsFragment = Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'platformMessage' | 'attempts' | 'lastPushedAt'>;
 export type EcomVariantLinksQueryVariables = Exact<{
     connectionId: Scalars['ID']['input'];
 }>;
 export type EcomVariantLinksQuery = {
-    ecomVariantLinks: Array<Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'attempts' | 'lastPushedAt'>>;
+    ecomVariantLinks: Array<Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'platformMessage' | 'attempts' | 'lastPushedAt'>>;
 };
 export type TriggerEcomBackfillMutationVariables = Exact<{
     connectionId: Scalars['ID']['input'];
@@ -11812,13 +11814,13 @@ export type RetryEcomVariantLinkMutationVariables = Exact<{
     input: RetryEcomVariantLinkInput;
 }>;
 export type RetryEcomVariantLinkMutation = {
-    retryEcomVariantLink: Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'attempts' | 'lastPushedAt'>;
+    retryEcomVariantLink: Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'platformMessage' | 'attempts' | 'lastPushedAt'>;
 };
 export type RelinkEcomVariantMutationVariables = Exact<{
     input: RelinkEcomVariantInput;
 }>;
 export type RelinkEcomVariantMutation = {
-    relinkEcomVariant: Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'attempts' | 'lastPushedAt'>;
+    relinkEcomVariant: Pick<EcomVariantLink, 'id' | 'createdAt' | 'updatedAt' | 'connectionId' | 'productId' | 'variantId' | 'extProductId' | 'extVariantId' | 'extInventoryItemId' | 'syncState' | 'desiredState' | 'lastErrorCode' | 'platformMessage' | 'attempts' | 'lastPushedAt'>;
 };
 export type EcomLocationLinkFieldsFragment = Pick<EcomLocationLink, 'id' | 'stockLocationId' | 'extLocationId' | 'authority'>;
 export type EcomLocationLinksQueryVariables = Exact<{
@@ -11870,7 +11872,7 @@ export type EcomInboundEventsQueryVariables = Exact<{
     connectionId: Scalars['ID']['input'];
 }>;
 export type EcomInboundEventsQuery = {
-    ecomInboundEvents: Array<Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'processedAt'>>;
+    ecomInboundEvents: Array<Pick<EcomInboundEvent, 'id' | 'createdAt' | 'connectionId' | 'providerCode' | 'extEventId' | 'topic' | 'extResourceId' | 'status' | 'attempts' | 'lastErrorCode' | 'platformMessage' | 'processedAt'>>;
 };
 export type EcomOrderLinkQueryVariables = Exact<{
     orderId: Scalars['ID']['input'];

package/dist/client.generated.d.ts

@@ -155,7 +155,7 @@ export declare class BaseGraphQLClient {
      * subscriptions; wrong for mutations: a re-sent create races its own
      * first attempt (observed: activatePlugin re-sent under load — the
      * winner committed, the caller received the loser's duplicate-name
-     * error). With `singleDelivery` the operation arms once a live (ACKed)
+     * error). For a MUTATION the guard arms once a live (ACKed)
      * socket could have carried it; a close while armed fails the operation
      * with WS_MUTATION_DELIVERY_INTERRUPTED instead of silently
      * re-executing it — the in-flight attempt's outcome is genuinely
@@ -163,16 +163,55 @@ export declare class BaseGraphQLClient {
      * BEFORE the first ACK stay retryable, so shouldRetry keeps healing
      * transient non-101 handshake refusals for mutations too.
      *
-     * The operation also carries a HANDSHAKE bound (#2102) — never an
-     * operation-lifetime one. subscribe() IS query() here, so a deadline on
-     * the whole operation would kill every long-lived subscription; the bound
-     * is armed only while the socket has not ACKed, and once it has, the wait
-     * is the server streaming and nothing bounds it.
+     * The operation carries TWO bounds, and KIND is what tells them apart.
+     * The HANDSHAKE bound (#2102) is armed only while the socket has not ACKed
+     * and ends an operation no socket could have carried. The FIRST-VALUE
+     * deadline (#1905) covers the other half of the same hang — an ACKed socket
+     * that simply withholds the reply, which no bound reached: a read gives up
+     * at 10 s, a write at 60 s, and a subscription never, because its first
+     * value may be minutes away by design. It measures the wait for the first
+     * sink callback, never the operation's lifetime, so a connected stream runs
+     * for as long as the server streams it. Both bounds raise the same typed
+     * code, so one consumer branch answers for both.
      */
     private executeWsOperation;
+    /**
+     * A live tail. It is NOT query() any more (#1905): a subscription is the one
+     * kind whose first value may legitimately be minutes away, so it is the one
+     * kind that carries no first-value deadline. The HANDSHAKE bound still
+     * applies — a socket that never ACKed carried no operation, stream or not.
+     */
     subscribe<T>(document: string, variables?: Record<string, unknown>): Observable<T>;
     upload<T>(document: string, variables: Record<string, unknown>): QueryObservable<T>;
     private getPerOperationExtensions;
+    /**
+     * The first-value budget for this operation, or undefined when it carries
+     * none. A get*, not a find*: derived configuration, never a lookup (#1905).
+     *
+     * The OPERATION's declared budget wins over its kind default (#2245): a
+     * kind default sizes the average operation, and one whose server work is
+     * itself bounded in seconds must cover that bound, or the client always
+     * wins the race and hides the server's own fallback behind a transport
+     * error.
+     */
+    private getFirstValueBudgetMs;
+    /**
+     * The name the document declares: `query ChannelPlugins` gives
+     * "ChannelPlugins". Every generated document is a named operation, so the
+     * fallback serves only a hand-written anonymous one — and a timeout that
+     * cannot say WHICH operation stalled is most of a forensic dead end.
+     */
+    private operationNameOf;
+    /**
+     * The ONE typed error both transport bounds raise (#1905). `code` is what
+     * consumers actually read — extractErrorCode / isErrorCode duck-type
+     * response.errors[0].extensions.code (error-utils.ts) — so a bound without
+     * one is invisible to them however loud its message is. `variables` is the
+     * uniform, i18n-ready channel the house error contract ships (codes on the
+     * wire, copy owned by the frontend); `detail` carries whatever attribution
+     * is specific to the bound that raised it, such as #2102's endpoint.
+     */
+    private wsTimeoutError;
     /**
      * Uniform error contract for the sink-level error path. graphql-ws
      * delivers a server ErrorMessage payload as a raw GraphQLError[] —

package/dist/client.generated.js

@@ -15,6 +15,7 @@ exports.clearTransactionToken = clearTransactionToken;
 const rxjs_1 = require("rxjs");
 const graphql_ws_1 = require("graphql-ws");
 const upload_1 = require("./upload");
+const sdk_types_generated_1 = require("./sdk-types.generated");
 class SDKLogger {
     prefix = "[ForgeCartSDK]";
     info(message, data) {
@@ -47,6 +48,63 @@ class QueryObservable extends rxjs_1.Observable {
     }
 }
 exports.QueryObservable = QueryObservable;
+/**
+ * The three GraphQL operation kinds. This is the discriminator the
+ * FIRST-VALUE deadline is scoped by, because only a subscription may
+ * legitimately wait minutes for its first value — so only a subscription
+ * carries no deadline at all (#1905).
+ */
+var WsOperationKind;
+(function (WsOperationKind) {
+    WsOperationKind["QUERY"] = "QUERY";
+    WsOperationKind["MUTATION"] = "MUTATION";
+    WsOperationKind["SUBSCRIPTION"] = "SUBSCRIPTION";
+})(WsOperationKind || (WsOperationKind = {}));
+/**
+ * The transport bounds, in milliseconds (#1905). Module-local on purpose:
+ * they are the SDK's own contract rather than a consumer knob, so nothing
+ * here widens the public surface or moves a tracked .d.ts.
+ *
+ * CONNECTION_ACK bounds the graphql-ws handshake socket-wide. The server
+ * sends connection_ack only after onConnect resolves — up to three DB
+ * round-trips here — so 8 s is about an order of magnitude above a healthy
+ * handshake, and deliberately BELOW the read deadline: a dead socket has
+ * already closed and re-dialled before any consumer gives up on it.
+ *
+ * QUERY_FIRST_VALUE bounds a read. Three independent ceilings put it under
+ * 15 s — the dashboard per-assertion budget, the 15 s this repo already
+ * imposes on a raw WS op under a manufactured held-transaction convoy, and
+ * a healthy full-shell boot at ~1.7 s. 10 s is roughly 20x a healthy admin
+ * read and still leaves e2e margin.
+ *
+ * MUTATION_FIRST_VALUE bounds a write. A write is not idempotent, so failing
+ * one that may have committed is the expensive direction; the house already
+ * accepts that honesty on a CLOSE (WS_MUTATION_DELIVERY_INTERRUPTED), and
+ * silence is weaker evidence than a close. 60 s is above every mutation a UI
+ * flow can await today and still finite, so no spinner spins forever.
+ */
+var WsTimeoutBudgetMs;
+(function (WsTimeoutBudgetMs) {
+    WsTimeoutBudgetMs[WsTimeoutBudgetMs["CONNECTION_ACK"] = 8000] = "CONNECTION_ACK";
+    WsTimeoutBudgetMs[WsTimeoutBudgetMs["QUERY_FIRST_VALUE"] = 10000] = "QUERY_FIRST_VALUE";
+    WsTimeoutBudgetMs[WsTimeoutBudgetMs["MUTATION_FIRST_VALUE"] = 60000] = "MUTATION_FIRST_VALUE";
+})(WsTimeoutBudgetMs || (WsTimeoutBudgetMs = {}));
+/**
+ * The per-OPERATION first-value budgets (#2245). A kind default sizes the
+ * average operation of that kind; an operation that holds the socket for a
+ * BOUNDED piece of server work must cover that work, or the client bound —
+ * armed first, at SEND — wins the race and the server's own degradation
+ * contract becomes unreachable: the packer's 60 s inline budget under an
+ * equal 60 s MUTATION_FIRST_VALUE made every fallback a WEBSOCKET_TIMEOUT.
+ *
+ * Generated from the SDK generator's declarations, where each entry carries
+ * the server constants it covers and a unit test pins it to them. Keyed by
+ * operation NAME — what the transport recovers from the document it is about
+ * to send, and the identity of the server path being bounded.
+ */
+const WS_FIRST_VALUE_BUDGET_MS_BY_OPERATION = {
+    RefreshShippingRateGroups: 90_000,
+};
 // Liveness of each underlying socket, keyed on the WsClient because
 // fork()ed clients share one socket. An operation that existed while its
 // socket was ACK-live may already sit on the server — that is the arming
@@ -124,6 +182,15 @@ class BaseGraphQLClient {
                     headers: this.getHeaders(),
                 }),
                 lazyCloseTimeout: 15_000,
+                // Without this graphql-ws never waits for connection_ack at all: the
+                // option defaults to 0 and the timer is armed only for a finite value
+                // > 0, so a socket whose ack never arrived stayed OPEN forever. No
+                // operation-level bound can repair that — a bound ends one operation,
+                // this ends the dead socket and re-dials. On expiry graphql-ws closes
+                // with CloseCode.ConnectionAcknowledgementTimeout = 4504 (the option's
+                // own doc comment says 4418 and is stale), which is deliberately NOT in
+                // its fatal list, so shouldRetry below keeps healing exactly as before.
+                connectionAckWaitTimeout: WsTimeoutBudgetMs.CONNECTION_ACK,
                 // graphql-ws treats a non-101 upgrade response as FATAL by
                 // default (zero retries) — a fresh handshake landing on a
                 // transient refusal (LB blip, server backlog under load) dies
@@ -277,13 +344,13 @@ class BaseGraphQLClient {
         }
     }
     query(document, variables) {
-        return this.executeWsOperation(document, variables, false);
+        return this.executeWsOperation(document, variables, WsOperationKind.QUERY);
     }
     mutate(document, variables) {
         if (variables && this.containsFiles(variables)) {
             return this.upload(document, variables);
         }
-        return this.executeWsOperation(document, variables, true);
+        return this.executeWsOperation(document, variables, WsOperationKind.MUTATION);
     }
     /**
      * One GraphQL operation over the shared graphql-ws socket.
@@ -293,7 +360,7 @@ class BaseGraphQLClient {
      * subscriptions; wrong for mutations: a re-sent create races its own
      * first attempt (observed: activatePlugin re-sent under load — the
      * winner committed, the caller received the loser's duplicate-name
-     * error). With `singleDelivery` the operation arms once a live (ACKed)
+     * error). For a MUTATION the guard arms once a live (ACKed)
      * socket could have carried it; a close while armed fails the operation
      * with WS_MUTATION_DELIVERY_INTERRUPTED instead of silently
      * re-executing it — the in-flight attempt's outcome is genuinely
@@ -301,15 +368,24 @@ class BaseGraphQLClient {
      * BEFORE the first ACK stay retryable, so shouldRetry keeps healing
      * transient non-101 handshake refusals for mutations too.
      *
-     * The operation also carries a HANDSHAKE bound (#2102) — never an
-     * operation-lifetime one. subscribe() IS query() here, so a deadline on
-     * the whole operation would kill every long-lived subscription; the bound
-     * is armed only while the socket has not ACKed, and once it has, the wait
-     * is the server streaming and nothing bounds it.
+     * The operation carries TWO bounds, and KIND is what tells them apart.
+     * The HANDSHAKE bound (#2102) is armed only while the socket has not ACKed
+     * and ends an operation no socket could have carried. The FIRST-VALUE
+     * deadline (#1905) covers the other half of the same hang — an ACKed socket
+     * that simply withholds the reply, which no bound reached: a read gives up
+     * at 10 s, a write at 60 s, and a subscription never, because its first
+     * value may be minutes away by design. It measures the wait for the first
+     * sink callback, never the operation's lifetime, so a connected stream runs
+     * for as long as the server streams it. Both bounds raise the same typed
+     * code, so one consumer branch answers for both.
      */
-    executeWsOperation(document, variables, singleDelivery) {
+    executeWsOperation(document, variables, kind) {
         return new QueryObservable((subscriber) => {
             const client = this.getWsClient();
+            // A MUTATION property, unchanged in meaning by the kind discriminator
+            // that replaced the boolean this method used to take.
+            const singleDelivery = kind === WsOperationKind.MUTATION;
+            const firstValueBudgetMs = this.getFirstValueBudgetMs(kind, this.operationNameOf(document));
             let disposed = false;
             // Delivery latch: once ANY sink callback has fired, the wire has
             // spoken and a socket close can no longer mean "delivery unknown".
@@ -322,10 +398,23 @@ class BaseGraphQLClient {
             // any handler logic so every interleave is covered.
             let settled = false;
             let connectionTimer;
+            // The FIRST-VALUE deadline (#1905). Its handle is typed the same
+            // runtime-neutral way as the handshake bound's: node hands back a Timeout
+            // object and a browser a number, and the generated client must typecheck
+            // in both without an @types/node-only name.
+            let operationDeadline;
             // This operation's entry in the socket's pending-handshake registry,
             // present for exactly as long as the bound is armed (#2102).
             let pendingEntry;
             const offConnectionEvents = [];
+            // Disarms the first-value deadline. Reached on the first sink callback
+            // and on teardown — the two ways an operation stops waiting for a value.
+            const clearOperationDeadline = () => {
+                if (operationDeadline === undefined)
+                    return;
+                clearTimeout(operationDeadline);
+                operationDeadline = undefined;
+            };
             // Disarms the bound AND deregisters the operation, because those are one
             // fact: a handshake that no longer needs bounding is one dispose() no
             // longer has to settle. Reached on the ACK, on the delivery latch and on
@@ -340,13 +429,50 @@ class BaseGraphQLClient {
                 clearTimeout(connectionTimer);
                 connectionTimer = undefined;
             };
-            // The wire answering IS proof the handshake completed, so the latch and
-            // the handshake bound fall together — and a timer that outlived its
-            // operation would hold the event loop open (a hung test worker).
+            // The wire answering IS proof the handshake completed AND the first value
+            // arrived, so the latch and BOTH bounds fall together — and a timer that
+            // outlived its operation would hold the event loop open (a hung worker).
             const settle = () => {
                 settled = true;
+                clearOperationDeadline();
                 clearConnectionTimeout();
             };
+            // Armed BEFORE the operation is sent, so the budget measures the caller's
+            // own wait rather than a window that opens once graphql-ws gets round to
+            // it. A subscription has no budget and arms nothing at all (#1905).
+            if (firstValueBudgetMs !== undefined) {
+                operationDeadline = setTimeout(() => {
+                    operationDeadline = undefined;
+                    // The #2102 doctrine, for the same reason: unreffed, this bound outlives
+                    // its client and fires under whatever event loop is alive then, so an
+                    // operation with nothing left to report must report NOTHING rather than
+                    // erroring onto whoever happens to be running.
+                    if (disposed || settled || this.disposed || (WS_CONNECTION_STATE.get(client)?.disposed ?? false))
+                        return;
+                    // While an unanswered HANDSHAKE bound is armed and comes due no later
+                    // than this one, it owns the failure: it names the socket that never
+                    // ACKed, which is the more specific fault, and both errors carry the
+                    // same code anyway. At the shipped defaults the two coincide exactly
+                    // (10_000 ms), so without this the winner would be arming order.
+                    if (connectionTimer !== undefined && this.connectionTimeout <= firstValueBudgetMs)
+                        return;
+                    const operationName = this.operationNameOf(document);
+                    this.logger.error("WS operation timed out before its first value", {
+                        operation: operationName,
+                        kind,
+                        timeoutMs: firstValueBudgetMs,
+                    });
+                    // subscriber.error tears the subscription down synchronously, disposing
+                    // the pending graphql-ws operation before its retry loop can re-send
+                    // what this caller has already given up on.
+                    subscriber.error(this.wsTimeoutError(sdk_types_generated_1.SdkErrorCode.WEBSOCKET_TIMEOUT, operationName, kind, firstValueBudgetMs));
+                }, firstValueBudgetMs);
+                // Same unref reasoning as the handshake bound: the deadline must FIRE
+                // while the app is alive without ever being the reason it stays alive.
+                const deadlineHandle = operationDeadline;
+                if (typeof deadlineHandle === "object" && typeof deadlineHandle.unref === "function")
+                    deadlineHandle.unref();
+            }
             const cleanup = client.subscribe({
                 query: document,
                 variables,
@@ -423,8 +549,13 @@ class BaseGraphQLClient {
                         endpoint: this.endpoint,
                         timeoutMs,
                     });
-                    const message = "WS_CONNECTION_TIMEOUT";
-                    subscriber.error(new ClientError({ errors: [{ message, extensions: { endpoint: this.endpoint, timeoutMs } }] }, message));
+                    // Carries the SAME typed code the first-value deadline raises (#1905).
+                    // Every consumer reads extensions.code (extractErrorCode / isErrorCode
+                    // in error-utils.ts) and this error had none, so no guard could branch
+                    // on it however loud the message was. The MESSAGE stays
+                    // WS_CONNECTION_TIMEOUT: the two bounds must remain distinguishable to
+                    // a human reading a log and identical to a consumer reading the code.
+                    subscriber.error(this.wsTimeoutError("WS_CONNECTION_TIMEOUT", this.operationNameOf(document), kind, timeoutMs, { endpoint: this.endpoint, timeoutMs }));
                 }, this.connectionTimeout);
                 // The bound must FIRE while the app is alive, but it must never be the
                 // reason the app stays alive: a pending handshake is something the host
@@ -472,6 +603,7 @@ class BaseGraphQLClient {
             }
             return () => {
                 disposed = true;
+                clearOperationDeadline();
                 clearConnectionTimeout();
                 for (const off of offConnectionEvents)
                     off();
@@ -479,8 +611,14 @@ class BaseGraphQLClient {
             };
         });
     }
+    /**
+     * A live tail. It is NOT query() any more (#1905): a subscription is the one
+     * kind whose first value may legitimately be minutes away, so it is the one
+     * kind that carries no first-value deadline. The HANDSHAKE bound still
+     * applies — a socket that never ACKed carried no operation, stream or not.
+     */
     subscribe(document, variables) {
-        return this.query(document, variables);
+        return this.executeWsOperation(document, variables, WsOperationKind.SUBSCRIPTION);
     }
     upload(document, variables) {
         return new QueryObservable((subscriber) => {
@@ -499,6 +637,56 @@ class BaseGraphQLClient {
             return undefined;
         return { "forgecart-transaction-token": this.transactionToken };
     }
+    /**
+     * The first-value budget for this operation, or undefined when it carries
+     * none. A get*, not a find*: derived configuration, never a lookup (#1905).
+     *
+     * The OPERATION's declared budget wins over its kind default (#2245): a
+     * kind default sizes the average operation, and one whose server work is
+     * itself bounded in seconds must cover that bound, or the client always
+     * wins the race and hides the server's own fallback behind a transport
+     * error.
+     */
+    getFirstValueBudgetMs(kind, operationName) {
+        // A SUBSCRIPTION is the one kind whose first value may legitimately be
+        // minutes away, so it carries no bound and no declaration can give it one.
+        if (kind === WsOperationKind.SUBSCRIPTION)
+            return undefined;
+        const declared = WS_FIRST_VALUE_BUDGET_MS_BY_OPERATION[operationName];
+        if (declared !== undefined)
+            return declared;
+        if (kind === WsOperationKind.QUERY)
+            return WsTimeoutBudgetMs.QUERY_FIRST_VALUE;
+        return WsTimeoutBudgetMs.MUTATION_FIRST_VALUE;
+    }
+    /**
+     * The name the document declares: `query ChannelPlugins` gives
+     * "ChannelPlugins". Every generated document is a named operation, so the
+     * fallback serves only a hand-written anonymous one — and a timeout that
+     * cannot say WHICH operation stalled is most of a forensic dead end.
+     */
+    operationNameOf(document) {
+        const named = /\b(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/.exec(document);
+        return named?.[1] ?? "anonymous";
+    }
+    /**
+     * The ONE typed error both transport bounds raise (#1905). `code` is what
+     * consumers actually read — extractErrorCode / isErrorCode duck-type
+     * response.errors[0].extensions.code (error-utils.ts) — so a bound without
+     * one is invisible to them however loud its message is. `variables` is the
+     * uniform, i18n-ready channel the house error contract ships (codes on the
+     * wire, copy owned by the frontend); `detail` carries whatever attribution
+     * is specific to the bound that raised it, such as #2102's endpoint.
+     */
+    wsTimeoutError(message, operationName, kind, timeoutMs, detail) {
+        const extensions = {
+            ...detail,
+            code: sdk_types_generated_1.SdkErrorCode.WEBSOCKET_TIMEOUT,
+            classification: "TRANSPORT_ERROR",
+            variables: { operationName, kind, timeoutMs: String(timeoutMs) },
+        };
+        return new ClientError({ errors: [{ message, extensions }] }, message);
+    }
     /**
      * Uniform error contract for the sink-level error path. graphql-ws
      * delivers a server ErrorMessage payload as a raw GraphQLError[] —

package/dist/documents.generated.d.ts

@@ -187,7 +187,7 @@ export declare const adminAdminDeploymentStatusChangedDocument = "subscription A
 export declare const adminEcomConnectionsDocument = "query EcomConnections {\n  ecomConnections {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
 export declare const adminEcomConnectionDocument = "query EcomConnection($id: ID!) {\n  ecomConnection(id: $id) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
 export declare const adminEcomSyncHealthDocument = "query EcomSyncHealth($connectionId: ID!) {\n  ecomSyncHealth(connectionId: $connectionId) {\n    connectionId\n    status\n    statusErrorCode\n    lastReconcileAt\n    consecutiveFailureCount\n    cursors\n    blockedEventCount\n    failedEventCount\n    domains {\n      domain\n      pending\n      pushing\n      synced\n      error\n      orphaned\n      archived\n      pendingExternal\n      oldestPendingAgeSeconds\n    }\n  }\n}";
-export declare const adminEcomBlockedInboundEventsDocument = "query EcomBlockedInboundEvents($connectionId: ID!) {\n  ecomBlockedInboundEvents(connectionId: $connectionId) {\n    ...EcomInboundEventFields\n  }\n}\n\nfragment EcomInboundEventFields on EcomInboundEvent {\n  id\n  createdAt\n  connectionId\n  providerCode\n  extEventId\n  topic\n  extResourceId\n  status\n  attempts\n  lastErrorCode\n  processedAt\n}";
+export declare const adminEcomBlockedInboundEventsDocument = "query EcomBlockedInboundEvents($connectionId: ID!) {\n  ecomBlockedInboundEvents(connectionId: $connectionId) {\n    ...EcomInboundEventFields\n  }\n}\n\nfragment EcomInboundEventFields on EcomInboundEvent {\n  id\n  createdAt\n  connectionId\n  providerCode\n  extEventId\n  topic\n  extResourceId\n  status\n  attempts\n  lastErrorCode\n  platformMessage\n  processedAt\n}";
 export declare const adminCreateEcomConnectionDocument = "mutation CreateEcomConnection($input: CreateEcomConnectionInput!) {\n  createEcomConnection(input: $input) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
 export declare const adminUpdateEcomConnectionDocument = "mutation UpdateEcomConnection($input: UpdateEcomConnectionInput!) {\n  updateEcomConnection(input: $input) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
 export declare const adminPauseEcomConnectionDocument = "mutation PauseEcomConnection($id: ID!) {\n  pauseEcomConnection(id: $id) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
@@ -195,11 +195,11 @@ export declare const adminResumeEcomConnectionDocument = "mutation ResumeEcomCon
 export declare const adminDeleteEcomConnectionDocument = "mutation DeleteEcomConnection($id: ID!) {\n  deleteEcomConnection(id: $id) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
 export declare const adminRetryEcomConnectionDocument = "mutation RetryEcomConnection($id: ID!) {\n  retryEcomConnection(id: $id) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
 export declare const adminTriggerEcomReconcileDocument = "mutation TriggerEcomReconcile($connectionId: ID!) {\n  triggerEcomReconcile(connectionId: $connectionId) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
-export declare const adminRetryEcomInboundEventDocument = "mutation RetryEcomInboundEvent($eventId: ID!) {\n  retryEcomInboundEvent(eventId: $eventId) {\n    ...EcomInboundEventFields\n  }\n}\n\nfragment EcomInboundEventFields on EcomInboundEvent {\n  id\n  createdAt\n  connectionId\n  providerCode\n  extEventId\n  topic\n  extResourceId\n  status\n  attempts\n  lastErrorCode\n  processedAt\n}";
-export declare const adminEcomVariantLinksDocument = "query EcomVariantLinks($connectionId: ID!) {\n  ecomVariantLinks(connectionId: $connectionId) {\n    ...EcomVariantLinkFields\n  }\n}\n\nfragment EcomVariantLinkFields on EcomVariantLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  productId\n  variantId\n  extProductId\n  extVariantId\n  extInventoryItemId\n  syncState\n  desiredState\n  lastErrorCode\n  attempts\n  lastPushedAt\n}";
+export declare const adminRetryEcomInboundEventDocument = "mutation RetryEcomInboundEvent($eventId: ID!) {\n  retryEcomInboundEvent(eventId: $eventId) {\n    ...EcomInboundEventFields\n  }\n}\n\nfragment EcomInboundEventFields on EcomInboundEvent {\n  id\n  createdAt\n  connectionId\n  providerCode\n  extEventId\n  topic\n  extResourceId\n  status\n  attempts\n  lastErrorCode\n  platformMessage\n  processedAt\n}";
+export declare const adminEcomVariantLinksDocument = "query EcomVariantLinks($connectionId: ID!) {\n  ecomVariantLinks(connectionId: $connectionId) {\n    ...EcomVariantLinkFields\n  }\n}\n\nfragment EcomVariantLinkFields on EcomVariantLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  productId\n  variantId\n  extProductId\n  extVariantId\n  extInventoryItemId\n  syncState\n  desiredState\n  lastErrorCode\n  platformMessage\n  attempts\n  lastPushedAt\n}";
 export declare const adminTriggerEcomBackfillDocument = "mutation TriggerEcomBackfill($connectionId: ID!) {\n  triggerEcomBackfill(connectionId: $connectionId) {\n    ...EcomConnectionFields\n  }\n}\n\nfragment EcomConnectionFields on EcomConnection {\n  id\n  createdAt\n  updatedAt\n  providerCode\n  externalAccountId\n  externalScope\n  status\n  statusErrorCode\n  commerceMode\n  syncCatalog\n  syncInventory\n  ingestOrders\n  syncCustomers\n  orchestrateRefunds\n  inventoryShortfallPolicy\n  ingestExternalStockAdjustments\n  defaultStockLocationId\n  shopCurrencyCode\n  channelPluginId\n}";
-export declare const adminRetryEcomVariantLinkDocument = "mutation RetryEcomVariantLink($input: RetryEcomVariantLinkInput!) {\n  retryEcomVariantLink(input: $input) {\n    ...EcomVariantLinkFields\n  }\n}\n\nfragment EcomVariantLinkFields on EcomVariantLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  productId\n  variantId\n  extProductId\n  extVariantId\n  extInventoryItemId\n  syncState\n  desiredState\n  lastErrorCode\n  attempts\n  lastPushedAt\n}";
-export declare const adminRelinkEcomVariantDocument = "mutation RelinkEcomVariant($input: RelinkEcomVariantInput!) {\n  relinkEcomVariant(input: $input) {\n    ...EcomVariantLinkFields\n  }\n}\n\nfragment EcomVariantLinkFields on EcomVariantLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  productId\n  variantId\n  extProductId\n  extVariantId\n  extInventoryItemId\n  syncState\n  desiredState\n  lastErrorCode\n  attempts\n  lastPushedAt\n}";
+export declare const adminRetryEcomVariantLinkDocument = "mutation RetryEcomVariantLink($input: RetryEcomVariantLinkInput!) {\n  retryEcomVariantLink(input: $input) {\n    ...EcomVariantLinkFields\n  }\n}\n\nfragment EcomVariantLinkFields on EcomVariantLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  productId\n  variantId\n  extProductId\n  extVariantId\n  extInventoryItemId\n  syncState\n  desiredState\n  lastErrorCode\n  platformMessage\n  attempts\n  lastPushedAt\n}";
+export declare const adminRelinkEcomVariantDocument = "mutation RelinkEcomVariant($input: RelinkEcomVariantInput!) {\n  relinkEcomVariant(input: $input) {\n    ...EcomVariantLinkFields\n  }\n}\n\nfragment EcomVariantLinkFields on EcomVariantLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  productId\n  variantId\n  extProductId\n  extVariantId\n  extInventoryItemId\n  syncState\n  desiredState\n  lastErrorCode\n  platformMessage\n  attempts\n  lastPushedAt\n}";
 export declare const adminEcomLocationLinksDocument = "query EcomLocationLinks($connectionId: ID!) {\n  ecomLocationLinks(connectionId: $connectionId) {\n    ...EcomLocationLinkFields\n  }\n}\n\nfragment EcomLocationLinkFields on EcomLocationLink {\n  id\n  stockLocationId\n  extLocationId\n  authority\n}";
 export declare const adminEcomExternalLocationsDocument = "query EcomExternalLocations($connectionId: ID!) {\n  ecomExternalLocations(connectionId: $connectionId) {\n    extLocationId\n    name\n    active\n  }\n}";
 export declare const adminSetEcomLocationLinksDocument = "mutation SetEcomLocationLinks($input: SetEcomLocationLinksInput!) {\n  setEcomLocationLinks(input: $input) {\n    ...EcomLocationLinkFields\n  }\n}\n\nfragment EcomLocationLinkFields on EcomLocationLink {\n  id\n  stockLocationId\n  extLocationId\n  authority\n}";
@@ -207,7 +207,7 @@ export declare const adminEcomGdprRequestsDocument = "query EcomGdprRequests($co
 export declare const adminCompleteEcomGdprRequestDocument = "mutation CompleteEcomGdprRequest($id: ID!) {\n  completeEcomGdprRequest(id: $id) {\n    ...EcomGdprRequestFields\n  }\n}\n\nfragment EcomGdprRequestFields on EcomGdprRequest {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  providerCode\n  kind\n  status\n  extRequestId\n  extCustomerId\n  customerId\n  subjectEmail\n  extOrderIds\n  dueAt\n  completedAt\n}";
 export declare const adminRefundExternalPaymentDocument = "mutation RefundExternalPayment($input: CreateRefundInput!) {\n  refundExternalPayment(input: $input) {\n    id\n    createdAt\n    updatedAt\n    total\n    reason\n    state\n    transactionId\n    method\n    paymentId\n  }\n}";
 export declare const adminRetryExternalRefundDocument = "mutation RetryExternalRefund($refundId: ID!) {\n  retryExternalRefund(refundId: $refundId) {\n    id\n    createdAt\n    updatedAt\n    total\n    reason\n    state\n    transactionId\n    method\n    paymentId\n  }\n}";
-export declare const adminEcomInboundEventsDocument = "query EcomInboundEvents($connectionId: ID!) {\n  ecomInboundEvents(connectionId: $connectionId) {\n    ...EcomInboundEventFields\n  }\n}\n\nfragment EcomInboundEventFields on EcomInboundEvent {\n  id\n  createdAt\n  connectionId\n  providerCode\n  extEventId\n  topic\n  extResourceId\n  status\n  attempts\n  lastErrorCode\n  processedAt\n}";
+export declare const adminEcomInboundEventsDocument = "query EcomInboundEvents($connectionId: ID!) {\n  ecomInboundEvents(connectionId: $connectionId) {\n    ...EcomInboundEventFields\n  }\n}\n\nfragment EcomInboundEventFields on EcomInboundEvent {\n  id\n  createdAt\n  connectionId\n  providerCode\n  extEventId\n  topic\n  extResourceId\n  status\n  attempts\n  lastErrorCode\n  platformMessage\n  processedAt\n}";
 export declare const adminEcomOrderLinkDocument = "query EcomOrderLink($orderId: ID!) {\n  order(id: $orderId) {\n    id\n    ecomOrderLink {\n      ...EcomOrderLinkFields\n    }\n  }\n}\n\nfragment EcomOrderLinkFields on EcomOrderLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  providerCode\n  orderId\n  extOrderId\n  extOrderNumber\n  source\n  state\n  correlationId\n  financialStatus\n  externalVersion\n  appliedAt\n  lineMap\n}";
 export declare const adminEcomOrderRefundLinksDocument = "query EcomOrderRefundLinks($orderId: ID!) {\n  order(id: $orderId) {\n    id\n    payments {\n      id\n      refunds {\n        id\n        ecomRefundLink {\n          ...EcomRefundLinkFields\n        }\n      }\n    }\n  }\n}\n\nfragment EcomRefundLinkFields on EcomRefundLink {\n  id\n  createdAt\n  updatedAt\n  connectionId\n  providerCode\n  refundId\n  paymentId\n  orderLinkId\n  extRefundId\n  cid\n  direction\n  state\n}";
 export declare const adminAdminEmailLayoutsDocument = "query AdminEmailLayouts {\n  emailLayouts {\n    ...EmailLayoutDetail\n  }\n}\n\nfragment EmailLayoutDetail on EmailLayout {\n  id\n  createdAt\n  updatedAt\n  name\n  bodyMjml\n  source\n  isDefault\n}";

package/dist/documents.generated.js

@@ -6656,6 +6656,7 @@ fragment EcomInboundEventFields on EcomInboundEvent {
   status
   attempts
   lastErrorCode
+  platformMessage
   processedAt
 }`;
 exports.adminCreateEcomConnectionDocument = `mutation CreateEcomConnection($input: CreateEcomConnectionInput!) {
@@ -6864,6 +6865,7 @@ fragment EcomInboundEventFields on EcomInboundEvent {
   status
   attempts
   lastErrorCode
+  platformMessage
   processedAt
 }`;
 exports.adminEcomVariantLinksDocument = `query EcomVariantLinks($connectionId: ID!) {
@@ -6885,6 +6887,7 @@ fragment EcomVariantLinkFields on EcomVariantLink {
   syncState
   desiredState
   lastErrorCode
+  platformMessage
   attempts
   lastPushedAt
 }`;
@@ -6934,6 +6937,7 @@ fragment EcomVariantLinkFields on EcomVariantLink {
   syncState
   desiredState
   lastErrorCode
+  platformMessage
   attempts
   lastPushedAt
 }`;
@@ -6956,6 +6960,7 @@ fragment EcomVariantLinkFields on EcomVariantLink {
   syncState
   desiredState
   lastErrorCode
+  platformMessage
   attempts
   lastPushedAt
 }`;
@@ -7077,6 +7082,7 @@ fragment EcomInboundEventFields on EcomInboundEvent {
   status
   attempts
   lastErrorCode
+  platformMessage
   processedAt
 }`;
 exports.adminEcomOrderLinkDocument = `query EcomOrderLink($orderId: ID!) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/sdk",
-  "version": "1.202609201502.0",
+  "version": "1.202609211357.0",
   "description": "ForgeCart Client SDK",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",