@salesforce/agentic-common 0.1.0

package/dist/event-bus.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Minimal, typed, object-bound event bus. Carries a single event shape `T`.
+ *
+ * Listener errors are isolated: a throwing callback never interrupts `emit()` or other listeners.
+ * `on()` returns an `Unsubscribe` closure so callers don't need to retain the original callback reference.
+ */
+export class EventBus {
+    listeners = new Set();
+    /** Number of currently registered listeners. Useful for leak-check assertions in tests. */
+    get listenerCount() {
+        return this.listeners.size;
+    }
+    /**
+     * Subscribe to events. Returns a function that unregisters this specific callback.
+     * Safe to call the returned function multiple times — subsequent calls are no-ops.
+     */
+    on(callback) {
+        this.listeners.add(callback);
+        return () => {
+            this.listeners.delete(callback);
+        };
+    }
+    /** Emit an event to every registered listener. Listener errors are caught and discarded. */
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Intentional: one bad listener must not break siblings or the emitter.
+            }
+        }
+    }
+    /**
+     * Subscribe to this bus and re-emit every event onto `target`. If `enrich` is supplied, each event is
+     * passed through it before re-emission. Returns an `Unsubscribe` for the internal subscription.
+     */
+    forwardTo(target, enrich) {
+        return this.on((event) => {
+            target.emit(enrich ? enrich(event) : event);
+        });
+    }
+    /** Remove all listeners. Idempotent. */
+    dispose() {
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IACA,SAAS,GAA0B,IAAI,GAAG,EAAE,CAAC;IAE9D,2FAA2F;IAC3F,IAAI,aAAa;QACb,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,EAAE,CAAC,QAA0B;QACzB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACR,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACpC,CAAC,CAAC;IACN,CAAC;IAED,4FAA4F;IAC5F,IAAI,CAAC,KAAQ;QACT,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC;gBACD,QAAQ,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;YAAC,MAAM,CAAC;gBACL,wEAAwE;YAC5E,CAAC;QACL,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAmB,EAAE,MAAwB;QACnD,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE;YACrB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;IACP,CAAC;IAED,wCAAwC;IACxC,OAAO;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACJ"}

package/dist/id-generator.d.ts

@@ -0,0 +1,6 @@
+export interface UniqueIDGenerator {
+    getUniqueId(): string;
+}
+export declare class UUIDGenerator implements UniqueIDGenerator {
+    getUniqueId(): string;
+}

package/dist/id-generator.js

@@ -0,0 +1,11 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { randomUUID } from 'node:crypto';
+export class UUIDGenerator {
+    getUniqueId() {
+        return randomUUID();
+    }
+}
+//# sourceMappingURL=id-generator.js.map

package/dist/id-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.js","sourceRoot":"","sources":["../src/id-generator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAMzC,MAAM,OAAO,aAAa;IACtB,WAAW;QACP,OAAO,UAAU,EAAE,CAAC;IACxB,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Clock, RealClock } from './clock.js';
+export { type OrgConnection, RealOrgConnection } from './connection.js';
+export { type OrgConnectionFactory, RealOrgConnectionFactory } from './connection-factory.js';
+export { getErrorMessage, getErrorMessageWithStack, isAbortError, wrapError } from './error-utils.js';
+export { EventBus, type EventListener, type Unsubscribe } from './event-bus.js';
+export { type UniqueIDGenerator, UUIDGenerator } from './id-generator.js';
+export { LogBus, type LogLevel, type LogRecord } from './log.js';
+export { BackoffRetryer, DEFAULT_RETRY_OPTIONS, NoOpRetryer, type Retryer, type RetryAttemptInfo, type RetryCallbacks, type RetryExhaustedInfo, type RetryOptions, } from './retryer.js';
+export { SfApiEnv } from './sf-api-env.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { Clock, RealClock } from './clock.js';
+export { RealOrgConnection } from './connection.js';
+export { RealOrgConnectionFactory } from './connection-factory.js';
+export { getErrorMessage, getErrorMessageWithStack, isAbortError, wrapError } from './error-utils.js';
+export { EventBus } from './event-bus.js';
+export { UUIDGenerator } from './id-generator.js';
+export { LogBus } from './log.js';
+export { BackoffRetryer, DEFAULT_RETRY_OPTIONS, NoOpRetryer, } from './retryer.js';
+export { SfApiEnv } from './sf-api-env.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAsB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAA6B,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtG,OAAO,EAAE,QAAQ,EAAwC,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAA0B,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAiC,MAAM,UAAU,CAAC;AACjE,OAAO,EACH,cAAc,EACd,qBAAqB,EACrB,WAAW,GAMd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/log.d.ts

@@ -0,0 +1,26 @@
+import { EventBus } from './event-bus.js';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured log record shared across the agentic DX packages.
+ *
+ * Consumers of the SDKs receive `LogRecord`s through an `onLog()` subscription; the SDKs themselves do not
+ * depend on any logging library and do not write to `stdout` / `stderr` directly.
+ */
+export type LogRecord = {
+    level: LogLevel;
+    message: string;
+    timestamp: Date;
+    context?: Record<string, unknown>;
+    error?: Error;
+};
+/**
+ * Typed event bus carrying `LogRecord`s. Adds level-named convenience methods (`debug` / `info` / `warn` /
+ * `error`) that build a record (timestamp + level) and emit it, so emit sites read as
+ * `bus.warn('message', { ctx })` instead of `logWarn(bus, 'message', { ctx })`.
+ */
+export declare class LogBus extends EventBus<LogRecord> {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>, error?: Error): void;
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+}

package/dist/log.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { EventBus } from './event-bus.js';
+/**
+ * Typed event bus carrying `LogRecord`s. Adds level-named convenience methods (`debug` / `info` / `warn` /
+ * `error`) that build a record (timestamp + level) and emit it, so emit sites read as
+ * `bus.warn('message', { ctx })` instead of `logWarn(bus, 'message', { ctx })`.
+ */
+export class LogBus extends EventBus {
+    debug(message, context) {
+        this.emit({ level: 'debug', message, timestamp: new Date(), context });
+    }
+    info(message, context) {
+        this.emit({ level: 'info', message, timestamp: new Date(), context });
+    }
+    warn(message, context, error) {
+        this.emit({ level: 'warn', message, timestamp: new Date(), context, error });
+    }
+    error(message, error, context) {
+        this.emit({ level: 'error', message, timestamp: new Date(), context, error });
+    }
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAkB1C;;;;GAIG;AACH,MAAM,OAAO,MAAO,SAAQ,QAAmB;IAC3C,KAAK,CAAC,OAAe,EAAE,OAAiC;QACpD,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,OAAiC;QACnD,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,OAAiC,EAAE,KAAa;QAClE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,KAAa,EAAE,OAAiC;QACnE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;CACJ"}

package/dist/retryer.d.ts

@@ -0,0 +1,137 @@
+import { Clock } from './clock.js';
+/**
+ * Public retry configuration. The retryer applies exponential backoff with full jitter, optional
+ * server-driven delay hints, and a wall-clock deadline. All fields are optional; defaults are
+ * `DEFAULT_RETRY_OPTIONS`.
+ */
+export type RetryOptions = {
+    /** Total attempts including the first. Default: 3. Must be >= 1. To disable retries, pass `false`. */
+    maxAttempts?: number;
+    /** Initial delay before the first retry, in ms. Default: 100. */
+    initialDelayMs?: number;
+    /** Maximum delay between *computed* exponential-backoff retries, in ms. Default: 2000. */
+    maxDelayMs?: number;
+    /**
+     * Maximum delay accepted from a server-driven hint (e.g. `Retry-After`), in ms. Hints exceeding
+     * this are honored as "do not retry, surface the result" so the caller sees the structured
+     * response instead of the retryer waiting too long. Default: 60000.
+     */
+    maxRetryAfterMs?: number;
+    /** Exponential backoff multiplier. Default: 2. */
+    backoffFactor?: number;
+    /**
+     * Hard ceiling on cumulative wall-clock time across all attempts and inter-attempt sleeps,
+     * in ms. When the next sleep would push past this deadline the loop bails and surfaces the
+     * most recent error / result instead of waiting. Default: `Infinity`.
+     */
+    maxTotalElapsedMs?: number;
+};
+export type ResolvedRetryOptions = Required<RetryOptions>;
+export declare const DEFAULT_RETRY_OPTIONS: ResolvedRetryOptions;
+export declare function resolveRetryOptions(opts?: RetryOptions | false): ResolvedRetryOptions;
+/**
+ * Deterministic exponential backoff ceiling for an attempt number (1-indexed).
+ * `attempt 1 → initialDelayMs`, `attempt 2 → initialDelayMs * factor`, capped at `maxDelayMs`.
+ */
+export declare function computeBackoffCeilingMs(attempt: number, opts: ResolvedRetryOptions): number;
+/**
+ * Apply full jitter: pick a uniform random value in `[0, ceilingMs]`. Spreads concurrent retriers
+ * across the backoff window instead of synchronizing them at the same moment.
+ */
+export declare function applyFullJitter(ceilingMs: number, random: () => number): number;
+/**
+ * Sleep for `ms` milliseconds, honoring an optional `AbortSignal`. Rejects with an
+ * `AbortError`-named error if the signal aborts before the delay elapses.
+ */
+export declare const realSleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+export type RetryAttemptInfo<T> = {
+    /** 1-indexed attempt number that just failed. */
+    attempt: number;
+    /** Jittered or server-driven delay about to be waited. */
+    delayMs: number;
+    /** Set if the attempt threw a retryable error. */
+    error?: unknown;
+    /** Set if the attempt returned a retryable result. */
+    result?: T;
+};
+export type RetryExhaustedInfo<T> = {
+    /** Total attempts made. */
+    attempts: number;
+    /** The final retryable error, if the last attempt threw. */
+    error?: unknown;
+    /** The final retryable result, if the last attempt returned one. */
+    result?: T;
+    /** Why the loop terminated: ran out of attempts, or hit the wall-clock deadline. */
+    reason: 'attempts' | 'deadline';
+};
+/**
+ * Callbacks the caller provides to customize retry behavior for a specific request/response shape.
+ * All are optional — sensible defaults apply (no errors retried, no results retried, no server hints).
+ */
+export type RetryCallbacks<T> = {
+    /** AbortSignal to cancel the loop (propagates immediately on abort). */
+    signal?: AbortSignal;
+    /**
+     * Classify a thrown error as retryable. Return `true` to retry, `false` to propagate.
+     * Default: always `false` (no errors retried).
+     */
+    isRetryableError?: (err: unknown) => boolean;
+    /**
+     * Classify a successful result as retryable (e.g. HTTP 429 / 5xx). Return `true` to retry.
+     * Default: always `false` (all results accepted).
+     */
+    isRetryableResult?: (result: T) => boolean;
+    /**
+     * Extract a server-driven retry delay from a retryable result (e.g. `Retry-After` header).
+     * Return `undefined` to fall back to computed backoff. Return a value > `maxRetryAfterMs`
+     * to signal "don't retry, surface this result to the caller".
+     */
+    getRetryAfterMs?: (result: T) => number | undefined;
+    /** Fired before each retry sleep. Use for telemetry, logging, metrics. */
+    onRetry?: (info: RetryAttemptInfo<T>) => void;
+    /**
+     * Fired when retries are exhausted (final attempt returned a retryable result or threw a
+     * retryable error). Use for "retries exhausted" warnings. Not fired when a non-retryable
+     * result/error terminates the loop.
+     */
+    onExhausted?: (info: RetryExhaustedInfo<T>) => void;
+    /**
+     * Release resources from a retryable result before retrying (e.g. drain HTTP response body
+     * to release the socket). Errors are swallowed — the retry proceeds regardless.
+     */
+    drainResult?: (result: T) => Promise<void>;
+};
+/**
+ * A generic retry executor. Consumers depend on this interface — they never see backoff internals,
+ * sleep functions, or RNG. Those are construction details of the implementation.
+ */
+export interface Retryer {
+    execute<T>(attemptFn: () => Promise<T>, callbacks?: RetryCallbacks<T>): Promise<T>;
+}
+export type BackoffRetryerDeps = {
+    clock: Clock;
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+    random: () => number;
+};
+/**
+ * Retry executor using exponential backoff with full jitter, optional server-driven delay hints,
+ * and a wall-clock deadline. Honors `AbortSignal` at every decision point.
+ *
+ * Domain-specific retry decisions (which errors / status codes are retryable, how to extract a
+ * `Retry-After` value, how to drain a response body, what to log) are passed via `RetryCallbacks`
+ * at the call site — the retryer itself is protocol-agnostic.
+ */
+export declare class BackoffRetryer implements Retryer {
+    private readonly options;
+    private readonly deps;
+    constructor(options?: RetryOptions | false, deps?: Partial<BackoffRetryerDeps>);
+    execute<T>(attemptFn: () => Promise<T>, callbacks?: RetryCallbacks<T>): Promise<T>;
+    private wouldExceedDeadline;
+}
+/**
+ * A pass-through retryer that executes the attempt exactly once with no retry. Use in tests where
+ * retry behavior is irrelevant to the system under test.
+ */
+export declare class NoOpRetryer implements Retryer {
+    execute<T>(attemptFn: () => Promise<T>): Promise<T>;
+}

package/dist/retryer.js

@@ -0,0 +1,175 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Clock, RealClock } from './clock.js';
+import { isAbortError } from './error-utils.js';
+export const DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 3,
+    initialDelayMs: 100,
+    maxDelayMs: 2000,
+    maxRetryAfterMs: 60_000,
+    backoffFactor: 2,
+    maxTotalElapsedMs: Number.POSITIVE_INFINITY,
+};
+export function resolveRetryOptions(opts) {
+    if (opts === false) {
+        return { ...DEFAULT_RETRY_OPTIONS, maxAttempts: 1 };
+    }
+    const maxAttempts = opts?.maxAttempts ?? DEFAULT_RETRY_OPTIONS.maxAttempts;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new Error(`Invalid retry option: maxAttempts must be an integer >= 1 (got ${maxAttempts}). Pass retry: false to disable retries.`);
+    }
+    return {
+        maxAttempts,
+        initialDelayMs: opts?.initialDelayMs ?? DEFAULT_RETRY_OPTIONS.initialDelayMs,
+        maxDelayMs: opts?.maxDelayMs ?? DEFAULT_RETRY_OPTIONS.maxDelayMs,
+        maxRetryAfterMs: opts?.maxRetryAfterMs ?? DEFAULT_RETRY_OPTIONS.maxRetryAfterMs,
+        backoffFactor: opts?.backoffFactor ?? DEFAULT_RETRY_OPTIONS.backoffFactor,
+        maxTotalElapsedMs: opts?.maxTotalElapsedMs ?? DEFAULT_RETRY_OPTIONS.maxTotalElapsedMs,
+    };
+}
+/**
+ * Deterministic exponential backoff ceiling for an attempt number (1-indexed).
+ * `attempt 1 → initialDelayMs`, `attempt 2 → initialDelayMs * factor`, capped at `maxDelayMs`.
+ */
+export function computeBackoffCeilingMs(attempt, opts) {
+    if (attempt < 1) {
+        return 0;
+    }
+    const exponential = opts.initialDelayMs * Math.pow(opts.backoffFactor, attempt - 1);
+    return Math.min(exponential, opts.maxDelayMs);
+}
+/**
+ * Apply full jitter: pick a uniform random value in `[0, ceilingMs]`. Spreads concurrent retriers
+ * across the backoff window instead of synchronizing them at the same moment.
+ */
+export function applyFullJitter(ceilingMs, random) {
+    return Math.floor(random() * (ceilingMs + 1));
+}
+/**
+ * Sleep for `ms` milliseconds, honoring an optional `AbortSignal`. Rejects with an
+ * `AbortError`-named error if the signal aborts before the delay elapses.
+ */
+export const realSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(makeAbortError());
+        return;
+    }
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(makeAbortError());
+    };
+    const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+function makeAbortError() {
+    const err = new Error('Aborted');
+    err.name = 'AbortError';
+    return err;
+}
+/**
+ * Retry executor using exponential backoff with full jitter, optional server-driven delay hints,
+ * and a wall-clock deadline. Honors `AbortSignal` at every decision point.
+ *
+ * Domain-specific retry decisions (which errors / status codes are retryable, how to extract a
+ * `Retry-After` value, how to drain a response body, what to log) are passed via `RetryCallbacks`
+ * at the call site — the retryer itself is protocol-agnostic.
+ */
+export class BackoffRetryer {
+    options;
+    deps;
+    constructor(options, deps) {
+        this.options = resolveRetryOptions(options);
+        this.deps = {
+            clock: deps?.clock ?? new RealClock(),
+            sleep: deps?.sleep ?? realSleep,
+            random: deps?.random ?? Math.random,
+        };
+    }
+    async execute(attemptFn, callbacks = {}) {
+        const { signal, isRetryableError = () => false, isRetryableResult = () => false, getRetryAfterMs, onRetry, onExhausted, drainResult, } = callbacks;
+        const { maxAttempts, maxRetryAfterMs, maxTotalElapsedMs } = this.options;
+        const startMs = this.deps.clock.now().getTime();
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const isLast = attempt === maxAttempts;
+            let result;
+            try {
+                result = await attemptFn();
+            }
+            catch (err) {
+                if (signal?.aborted || isAbortError(err)) {
+                    throw err;
+                }
+                if (!isRetryableError(err) || isLast) {
+                    if (isLast && isRetryableError(err)) {
+                        onExhausted?.({ attempts: attempt, error: err, reason: 'attempts' });
+                    }
+                    throw err;
+                }
+                const delayMs = applyFullJitter(computeBackoffCeilingMs(attempt, this.options), this.deps.random);
+                if (this.wouldExceedDeadline(startMs, delayMs, maxTotalElapsedMs)) {
+                    onExhausted?.({ attempts: attempt, error: err, reason: 'deadline' });
+                    throw err;
+                }
+                lastError = err;
+                onRetry?.({ attempt, delayMs, error: err });
+                await this.deps.sleep(delayMs, signal);
+                continue;
+            }
+            if (!isRetryableResult(result) || isLast) {
+                if (isLast && isRetryableResult(result)) {
+                    onExhausted?.({ attempts: attempt, result, reason: 'attempts' });
+                }
+                return result;
+            }
+            const serverDelayMs = getRetryAfterMs?.(result);
+            if (serverDelayMs !== undefined && serverDelayMs > maxRetryAfterMs) {
+                // Server hinted longer than we're willing to wait — surface the result so the
+                // caller sees the structured error rather than the retryer waiting too long.
+                return result;
+            }
+            // Server-driven hint takes precedence verbatim — no jitter, no `maxDelayMs` clamp
+            // (which bounds *computed* backoff only).
+            const delayMs = serverDelayMs !== undefined
+                ? serverDelayMs
+                : applyFullJitter(computeBackoffCeilingMs(attempt, this.options), this.deps.random);
+            if (this.wouldExceedDeadline(startMs, delayMs, maxTotalElapsedMs)) {
+                onExhausted?.({ attempts: attempt, result, reason: 'deadline' });
+                return result;
+            }
+            onRetry?.({ attempt, delayMs, result });
+            if (drainResult) {
+                try {
+                    await drainResult(result);
+                }
+                catch {
+                    // Resource is gone either way; proceed to the retry sleep.
+                }
+            }
+            await this.deps.sleep(delayMs, signal);
+        }
+        // Loop only exits via return / throw above; this satisfies the type system.
+        throw lastError ?? new Error('Retry loop exited without a response');
+    }
+    wouldExceedDeadline(startMs, delayMs, maxTotalElapsedMs) {
+        if (!Number.isFinite(maxTotalElapsedMs)) {
+            return false;
+        }
+        return this.deps.clock.now().getTime() - startMs + delayMs > maxTotalElapsedMs;
+    }
+}
+/**
+ * A pass-through retryer that executes the attempt exactly once with no retry. Use in tests where
+ * retry behavior is irrelevant to the system under test.
+ */
+export class NoOpRetryer {
+    async execute(attemptFn) {
+        return attemptFn();
+    }
+}
+//# sourceMappingURL=retryer.js.map

package/dist/retryer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryer.js","sourceRoot":"","sources":["../src/retryer.ts"],"names":[],"mappings":"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"}

package/dist/sf-api-env.d.ts

@@ -0,0 +1,21 @@
+export declare enum SfApiEnv {
+    Dev = "dev",
+    Perf = "perf",
+    Prod = "prod",
+    Stage = "stage",
+    Test = "test"
+}
+/**
+ * Infers the Salesforce API environment from an instance URL, with `SF_API_ENV`
+ * as an explicit override.
+ *
+ * Resolution:
+ * 1. If `SF_API_ENV` is set to a valid value, use it.
+ * 2. Otherwise infer from the instance URL:
+ *    - STM patterns → `stage`
+ *    - OrgFarm dev patterns (`.devX.*.pc-rnd.*`) or workspaces (`.crm.dev`) → `dev`
+ *    - OrgFarm perf patterns (`.perfXX.*.pc-rnd.*`) → `perf`
+ *    - OrgFarm test patterns (`.testX.*.pc-rnd.*`) → `test`
+ *    - Everything else (including unrecognized internal URLs) → `prod`
+ */
+export declare function inferSfApiEnv(instanceUrl: string): SfApiEnv;

package/dist/sf-api-env.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export var SfApiEnv;
+(function (SfApiEnv) {
+    SfApiEnv["Dev"] = "dev";
+    SfApiEnv["Perf"] = "perf";
+    SfApiEnv["Prod"] = "prod";
+    SfApiEnv["Stage"] = "stage";
+    SfApiEnv["Test"] = "test";
+})(SfApiEnv || (SfApiEnv = {}));
+/**
+ * Infers the Salesforce API environment from an instance URL, with `SF_API_ENV`
+ * as an explicit override.
+ *
+ * Resolution:
+ * 1. If `SF_API_ENV` is set to a valid value, use it.
+ * 2. Otherwise infer from the instance URL:
+ *    - STM patterns → `stage`
+ *    - OrgFarm dev patterns (`.devX.*.pc-rnd.*`) or workspaces (`.crm.dev`) → `dev`
+ *    - OrgFarm perf patterns (`.perfXX.*.pc-rnd.*`) → `perf`
+ *    - OrgFarm test patterns (`.testX.*.pc-rnd.*`) → `test`
+ *    - Everything else (including unrecognized internal URLs) → `prod`
+ */
+export function inferSfApiEnv(instanceUrl) {
+    const envVar = process.env['SF_API_ENV']?.toLowerCase();
+    if (envVar && Object.values(SfApiEnv).includes(envVar)) {
+        return envVar;
+    }
+    const lower = instanceUrl.toLowerCase();
+    if (lower.includes('stm.salesforce.com') ||
+        lower.includes('stm.force.com') ||
+        lower.includes('.stm.salesforce.ms')) {
+        return SfApiEnv.Stage;
+    }
+    if (isPcRndUrl(lower)) {
+        if (/\.dev[a-z0-9]+\./.test(lower)) {
+            return SfApiEnv.Dev;
+        }
+        if (/\.perf\d\w*\./.test(lower)) {
+            return SfApiEnv.Perf;
+        }
+        if (/\.test\d+\./.test(lower)) {
+            return SfApiEnv.Test;
+        }
+    }
+    if (lower.includes('.crm.dev') || lower.includes('localhost.sfdcdev.') || lower.includes('.internal.')) {
+        return SfApiEnv.Dev;
+    }
+    return SfApiEnv.Prod;
+}
+function isPcRndUrl(lower) {
+    return lower.includes('.pc-rnd.salesforce.com') || lower.includes('.pc-rnd.force.com');
+}
+//# sourceMappingURL=sf-api-env.js.map

package/dist/sf-api-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sf-api-env.js","sourceRoot":"","sources":["../src/sf-api-env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAN,IAAY,QAMX;AAND,WAAY,QAAQ;IAChB,uBAAW,CAAA;IACX,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,2BAAe,CAAA;IACf,yBAAa,CAAA;AACjB,CAAC,EANW,QAAQ,KAAR,QAAQ,QAMnB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IACxD,IAAI,MAAM,IAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,MAAkB,CAAC;IAC9B,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;IACxC,IACI,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACpC,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC;QAC/B,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EACtC,CAAC;QACC,OAAO,QAAQ,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,OAAO,QAAQ,CAAC,GAAG,CAAC;QACxB,CAAC;QACD,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,QAAQ,CAAC,IAAI,CAAC;QACzB,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACrG,OAAO,QAAQ,CAAC,GAAG,CAAC;IACxB,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC;AACzB,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC7B,OAAO,KAAK,CAAC,QAAQ,CAAC,wBAAwB,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;AAC3F,CAAC"}