@salesforce/lds-runtime-mobile 1.444.0 → 1.446.0

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

@@ -26,6 +26,28 @@ export declare abstract class AbstractResourceRequestActionHandler<ResponseType>
     enqueue(data: ResourceRequest, observabilityContext?: ObservabilityContext): Promise<PendingDraftAction<ResourceRequest>>;
     buildPendingAction(request: ResourceRequest, queue: DraftAction<unknown, unknown>[], observabilityContext?: ObservabilityContext): 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>;

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,20 @@ 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 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;

package/sfdc/types/utils/observabilityContext.d.ts

@@ -0,0 +1,10 @@
+import type { AdapterRequestContext, DmlAdapterRequestContext } from '@luvio/engine';
+import type { ObservabilityContext } from '@salesforce/nimbus-plugin-lds';
+/**
+ * lds-worker-api packs the user action's ObservabilityContext into
+ * `requestContext.requestCorrelator = { observabilityContext }`. This helper
+ * unwraps it for draft-aware adapter wrappers, which forward the context to
+ * the action handler so retry network spans can be parented to the
+ * originating user action.
+ */
+export declare function extractObservabilityContext(requestContext?: AdapterRequestContext | DmlAdapterRequestContext): ObservabilityContext | undefined;