@salesforce/lds-runtime-mobile 1.428.0-dev2 → 1.428.0-dev21

package/sfdc/types/drafts/AbstractResourceRequestActionHandler.d.ts

@@ -25,6 +25,28 @@ export declare abstract class AbstractResourceRequestActionHandler<ResponseType>
     enqueue(data: ResourceRequest): Promise<PendingDraftAction<ResourceRequest>>;
     buildPendingAction(request: ResourceRequest, queue: DraftAction<unknown, unknown>[]): Promise<PendingDraftAction<ResourceRequest>>;
     handleAction(action: DraftAction<ResourceRequest, ResponseType>, actionCompleted: (action: CompletedDraftAction<ResourceRequest, ResponseType>) => Promise<void>, actionErrored: (action: DraftAction<ResourceRequest, ResponseType>, retry: boolean, retryDelayInMs?: number, actionDataChanged?: boolean) => Promise<void>): Promise<ProcessActionResult>;
+    /**
+     * Reads the persisted upload retry-attempt count from the action's durable metadata
+     * bag. The count lives in metadata (rather than in-memory) so it survives app
+     * restarts and queue re-creation — the failure modes that let the unbounded retry
+     * loop run for days.
+     */
+    private getUploadRetryCount;
+    /**
+     * Enforces the upload retry-attempt cap around the queue's `actionErrored` callback.
+     * Both retry paths — a retryable HTTP error and a thrown exception — funnel through
+     * here.
+     *
+     * The entire cap behavior is gated behind `lmr.draft-queue-max-retry-attempts`. When
+     * the gate is CLOSED this is a transparent passthrough: it issues the same
+     * `actionErrored(action, true, ...)` retry the queue made before this change, and
+     * writes no extra metadata. When the gate is OPEN it persists an incremented attempt
+     * count to the action's durable metadata and, once the action has failed
+     * {@link MAX_RETRY_ATTEMPTS} times, transitions it to Error (carrying a
+     * FetchResponse-shaped error that names the failure that exhausted the retries)
+     * instead of scheduling yet another retry.
+     */
+    private retryOrCap;
     handleActionEnqueued(action: PendingDraftAction<ResourceRequest>): Promise<void>;
     handleActionRemoved(action: DraftAction<ResourceRequest, ResponseType>): Promise<void>;
     handleActionReplaced(target: DraftAction<ResourceRequest, ResponseType>, source: DraftAction<ResourceRequest, ResponseType>): Promise<void>;
@@ -38,6 +60,7 @@ export declare abstract class AbstractResourceRequestActionHandler<ResponseType>
     private isActionOfType;
     private handleIdempotencyServerError;
     private isUiApiErrors;
+    private isServerGeneratedError;
     private isBackdatingError;
     getDraftIdsFromAction(action: DraftAction<ResourceRequest, ResponseType>): string[];
     hasIdempotencySupport(): boolean;

package/sfdc/types/drafts/IdempotentWrite.d.ts

@@ -4,6 +4,7 @@ export interface UIApiError {
     message: string | null;
 }
 export declare const enum IdempotentWriteSpecificHttpStatusCode {
+    NoResponse = 0,
     RequestTimeout = 408,
     Conflict = 409,
     BadGateway = 502,

package/sfdc/types/drafts/utils/error.d.ts

@@ -1,4 +1,33 @@
+import type { FetchResponse } from '@luvio/engine';
 /**
  * This function takes an unknown error and normalizes it to an Error object
  */
 export declare function normalizeError(error: unknown): Error;
+/**
+ * Maximum number of times an action's upload will be retried before the action is
+ * transitioned to Error and surfaced to the consumer. Caps the otherwise-unbounded
+ * retry loop that can wedge the single-worker draft queue when an upload fails
+ * deterministically on every dispatch. Only enforced when the
+ * `lmr.draft-queue-max-retry-attempts` gate is open.
+ */
+export declare const MAX_RETRY_ATTEMPTS = 5;
+export declare const MAX_RETRY_ERROR_CODE = "MAX_RETRY_ATTEMPTS_EXCEEDED";
+/**
+ * The two things that can cause an upload attempt to fail and be retried:
+ *  - a non-ok `FetchResponse` returned by the network adapter (the HTTP error path), or
+ *  - an `Error` thrown out of the dispatch and caught by `handleAction` (the catch path;
+ *    the raw caught value is normalized to an `Error` before it reaches here).
+ * Either way the cause is concretely typed — it is never an opaque `unknown`.
+ */
+export type UploadFailure = FetchResponse<unknown> | Error;
+/**
+ * Builds the FetchResponse-shaped error attached to an action that has exhausted its
+ * upload retries. Shaped like a real network error response (status/statusText/ok/
+ * headers/body) so downstream consumers (DraftManager, queue instrumentation) that
+ * read `action.error.status`/`.body`/etc. behave consistently with a server error.
+ *
+ * The failure that caused the final attempt — a non-ok response (HTTP path) or a thrown
+ * error (catch path) — is folded into the body so the surfaced error says WHAT failed,
+ * not merely that the attempt cap was reached.
+ */
+export declare function buildMaxRetryError(lastFailure: UploadFailure): FetchResponse<unknown>;

package/sfdc/types/instrumentation/metrics.d.ts

@@ -10,6 +10,42 @@ export declare function reportGraphqlAdapterError(errorCode: string): void;
 export declare function reportGraphqlQueryInstrumentation(data: QueryInstrumentation): void;
 export declare function incrementGraphQLRefreshUndfined(): void;
 export declare function reportDraftActionEvent(state: 'added' | 'uploading' | 'completed' | 'deleted' | 'updated' | 'failed', draftCount: number, message?: string): void;
+/**
+ * Reports an exception thrown while uploading a draft action. The thrown error is
+ * otherwise swallowed by the upload handler's retry path, leaving the failure
+ * invisible in telemetry; this surfaces it to o11y (log + counter) so a deterministic
+ * upload failure can be diagnosed instead of silently retried forever.
+ *
+ * PII: the device log line carries only the handler id, retry attempt, and the error
+ * NAME (e.g. "TypeError") — never the free-text error message, which can embed record
+ * ids (URL path segments) or server field-validation strings. The full normalized error
+ * (message + stack) is handed only to `ldsMobileInstrumentation.error`, the structured
+ * o11y error pipeline responsible for scrubbing/handling that detail. Also does NOT log
+ * the action's targetId/tag or any request body/field values.
+ */
+export declare function reportDraftActionUploadError(error: unknown, handlerId: string, attempt: number): void;
+export type IdempotencyKeyRotationReason = 'idempotency-error' | 'backdating-collision' | 'merge-actions' | 'generic-400-killswitch';
+/**
+ * Emits a single greppable Splunk log line (and an o11y counter) every time a draft's
+ * Idempotency-Key is rotated — i.e. replaced with a fresh uuid rather than reused on
+ * retry. This is the instrumentation for the WOLI duplicate-record investigation
+ * (@W-23428669): a rotation mid-flight is the mechanism by which an already-committed
+ * write can be re-sent under a new key and duplicated on the server, so recording every
+ * rotation lets us reconstruct, on a future reproduction, exactly where and how often a
+ * key changed for a given draft.
+ *
+ * The message is prefixed with a stable literal ("Idempotency key rotated") so it can be
+ * pulled out of Splunk with a substring match, and carries:
+ *   - draftId: the local (client-synthesized) draft-action target id, so this event can be
+ *     correlated with the other draft-queue events for the same draft. This is NOT a server
+ *     record id or any field value — it is the same local id already surfaced by the queue's
+ *     other lifecycle logs, so it introduces no new PII.
+ *   - reason: which rotation call site fired, to disambiguate the distinct rotation paths.
+ *
+ * @param draftId the local draft-action target id whose key was rotated
+ * @param reason  the rotation call site (see IdempotencyKeyRotationReason)
+ */
+export declare function reportIdempotencyKeyRotated(draftId: string, reason: IdempotencyKeyRotationReason): void;
 export declare function reportDraftQueueState(state: 'started' | 'error' | 'waiting' | 'stopped', draftCount: number): void;
 export declare function reportDraftAwareContentDocumentVersionSynthesizeError(err: unknown): void;
 export declare function reportDraftAwareContentVersionSynthesizeCalls(mimeType: string): void;