@salesforce/agentic-common 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were last updated on March 24, 2026, and constitute a legally binding agreement between you and Salesforce. If you do not agree to these Terms of Use, do not install or use the Software. The Software may link to third-party software components licensed under various open source licenses ("Open Source Components"). These Terms of Use pertain solely to Salesforce's proprietary code in the Software. It does not alter or extend any rights or obligations regarding the Open Source Components. For clarity, your use of the Open Source Components is governed by the terms of the applicable open source license(s). You are solely responsible for complying with the terms and conditions of those open source licenses.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free copyright license to reproduce, revocable, publicly display, publicly perform, sublicense, and distribute the Software and derivative works subject to these Terms. These Terms shall be included in all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce reserves all rights, title, and interest in and to all intellectual property subsisting in the Software. No rights are granted to you hereunder other than as expressly set forth herein. Users residing in countries on the United States Office of Foreign Assets Control sanction list, or which are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you are responsible. The Software may contain bugs, errors and incompatibilities and is made available on an AS IS basis without support, updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or discontinue, the Software (or any part thereof) with or without notice. You agree that Salesforce shall not be liable to you or to any third party for any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or proceeding made or brought against Salesforce by a third party arising out of or accruing from (a) your use of the Software, and (b) any application you develop with the Software that infringes any copyright, trademark, trade secret, trade dress, patent, or other intellectual property right of any person or defames any person or violates their rights of publicity or privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce from any damages, attorney fees, and costs finally awarded against Salesforce as a result of, or for any amounts paid by Salesforce under a settlement approved by you in writing of, a Claim Against Salesforce, provided Salesforce (x) promptly gives you written notice of the Claim Against Salesforce, (y) gives you sole control of the defense and settlement of the Claim Against Salesforce (except that you may not settle any Claim Against Salesforce unless it unconditionally releases Salesforce of all liability), and (z) gives you all reasonable assistance, at your expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA, OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of the State of California, without regard to its conflicts of laws rules. Each party hereby consents to the exclusive jurisdiction of the state and federal courts located in San Francisco County, California to adjudicate any dispute arising out of or relating to these Terms of Use and the download, installation, and/or use of the Software. Except as expressly stated herein, these Terms of Use constitute the entire agreement between the parties, and supersede all prior and contemporaneous agreements, proposals, or representations, written or oral, concerning their subject matter. No modification, amendment, or waiver of any provision of these Terms of Use shall be effective unless it is by an update to these Terms of Use that Salesforce makes available, or is in writing and signed by the party against whom the modification, amendment, or waiver is to be asserted.
+
+Data Privacy: Salesforce may collect, process, and store device, system, and other information related to your use of the Software. This information includes, but is not limited to, IP address, user metrics, and other data ("Usage Data"). Salesforce may use Usage Data for analytics, product development, and marketing purposes. You acknowledge that files generated in conjunction with the Software may contain sensitive or confidential data, and you are solely responsible for anonymizing and protecting such data.

package/README.md

@@ -0,0 +1,262 @@
+# @salesforce/agentic-common
+
+Shared primitives and common utilities for the Salesforce agentic DX packages. Provides a typed event bus, clock
+abstraction, ID generation, error utilities, log record shape, thin log-emit helpers, and a Salesforce org connection
+interface consumed by the other packages in this monorepo.
+
+## Quick Start
+
+> This package is not yet published to npm. See [DEVELOPING.md](../../DEVELOPING.md) to build from source.
+
+```typescript
+import { EventBus, LogBus } from '@salesforce/agentic-common';
+
+type MyEvent = { type: 'hello'; name: string };
+
+const bus = new EventBus<MyEvent>();
+const unsubscribe = bus.on((event) => {
+  console.log(`hello, ${event.name}`);
+});
+
+bus.emit({ type: 'hello', name: 'world' });
+
+unsubscribe();
+bus.dispose();
+
+const logs = new LogBus();
+logs.on((record) => console.log(`[${record.level}] ${record.message}`));
+logs.info('ready', { agentId: 'a1' });
+```
+
+## API Reference
+
+### `OrgConnection` / `RealOrgConnection`
+
+Interface for making authenticated HTTP requests to a Salesforce org, carrying identity metadata alongside transport
+capabilities. `RealOrgConnection` is the production implementation backed by `@salesforce/core`.
+
+```typescript
+interface OrgConnection {
+  request<T>(opts: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    body?: string;
+    headers?: { [name: string]: string };
+  }): Promise<T>;
+
+  getAccessToken(): string;
+  getInstanceUrl(): string;
+  getUsername(): string;
+  getOrgId(): string;
+  getOrgAliasOrUsername(): string;
+  getInferredSfApiEnv(): SfApiEnv;
+}
+```
+
+### `OrgConnectionFactory` / `RealOrgConnectionFactory`
+
+Factory for creating authenticated `OrgConnection` instances. `RealOrgConnectionFactory` is the production
+implementation backed by `@salesforce/core`.
+
+```typescript
+interface OrgConnectionFactory {
+  createFromOrgAliasOrUsername(orgAliasOrUsername: string): Promise<OrgConnection>;
+  createFromTargetOrg(options?: { projectRoot?: string }): Promise<OrgConnection>;
+  createFromCredentials(accessToken: string, instanceUrl: string): Promise<OrgConnection>;
+}
+```
+
+### `SfApiEnv`
+
+Enum of Salesforce API environments used for gateway routing. Consumers access the inferred value via
+`OrgConnection.getInferredSfApiEnv()` which uses the instance URL and the `SF_API_ENV` environment variable override.
+
+```typescript
+enum SfApiEnv {
+  Dev = 'dev',
+  Perf = 'perf',
+  Prod = 'prod',
+  Stage = 'stage',
+  Test = 'test',
+}
+```
+
+### `Clock` / `RealClock`
+
+Abstract time source for dependency injection. Use `RealClock` in production; extend `Clock` in tests for deterministic
+time control.
+
+```typescript
+abstract class Clock {
+  abstract now(): Date;
+  // Default: returns ts + 1ms. Override for test scenarios needing different stepping.
+  nextAfter(ts: Date): Date;
+}
+
+class RealClock extends Clock {
+  now(): Date; // returns new Date()
+}
+```
+
+### `getErrorMessage(err: unknown): string`
+
+Safely extracts a message string from any thrown value — `Error` instances, error-like objects with a `message`
+property, or arbitrary values (coerced via `String()`).
+
+```typescript
+import { getErrorMessage } from '@salesforce/agentic-common';
+
+try { ... } catch (err) {
+  console.error(getErrorMessage(err));
+}
+```
+
+### `isAbortError(err: unknown): boolean`
+
+Returns true for either platform shape of an abort signal error: the DOM `AbortError` (`err.name === 'AbortError'`, e.g.
+from `AbortController.abort()` against `fetch` / `undici.request`) or the Node `ABORT_ERR` (`err.code === 'ABORT_ERR'`).
+Useful in retry loops and error handlers that need to distinguish caller-initiated cancellation from transport failures.
+
+```typescript
+import { isAbortError } from '@salesforce/agentic-common';
+
+try {
+  await someAsyncWork(signal);
+} catch (err) {
+  if (isAbortError(err)) return; // caller cancelled; not an error to surface
+  throw err;
+}
+```
+
+### `UniqueIDGenerator` / `UUIDGenerator`
+
+Interface + default implementation for generating unique identifiers. Tests can inject deterministic implementations.
+
+```typescript
+interface UniqueIDGenerator {
+  getUniqueId(): string;
+}
+
+class UUIDGenerator implements UniqueIDGenerator {
+  getUniqueId(): string; // wraps crypto.randomUUID()
+}
+```
+
+### `EventBus<T>`
+
+A minimal, typed event bus. One type parameter, one emission channel. Error-isolated (a throwing listener never breaks
+`emit` or other listeners).
+
+```typescript
+class EventBus<T> {
+  readonly listenerCount: number;
+
+  on(callback: EventListener<T>): Unsubscribe;
+  emit(event: T): void;
+  forwardTo(target: EventBus<T>, enrich?: (event: T) => T): Unsubscribe;
+  dispose(): void;
+}
+
+type EventListener<T> = (event: T) => void;
+type Unsubscribe = () => void;
+```
+
+| Method                 | Description                                                                                         |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `on(callback)`         | Subscribe. Returns an `Unsubscribe` function — no need to hold the callback reference for removal.  |
+| `emit(event)`          | Deliver to all listeners. Listener errors are caught and ignored so one bad listener can't cascade. |
+| `forwardTo(target, ?)` | Subscribe to this bus and re-emit every event onto `target`. Optional `enrich` transforms events.   |
+| `dispose()`            | Remove all listeners. Safe to call multiple times.                                                  |
+| `listenerCount`        | Current listener count (useful for leak-check assertions in tests).                                 |
+
+### `LogRecord` / `LogBus`
+
+`LogRecord` is the structured log shape used across packages. `LogBus` extends `EventBus<LogRecord>` with level-named
+convenience methods so emit sites read as `bus.warn('msg', { ctx })` instead of repeating the
+`{ level, message, timestamp, ... }` literal.
+
+```typescript
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+type LogRecord = {
+  level: LogLevel;
+  message: string;
+  timestamp: Date;
+  context?: Record<string, unknown>;
+  error?: Error;
+};
+
+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;
+}
+```
+
+### `Retryer` / `BackoffRetryer` / `NoOpRetryer`
+
+Generic retry orchestration. Consumers depend on the `Retryer` interface and supply per-call decisions (which errors /
+results are retryable, how to extract a server-driven `Retry-After`, what to log) via callbacks. Backoff timing,
+jittering, deadline enforcement, and abort handling are construction details of `BackoffRetryer` — invisible to the
+caller.
+
+```typescript
+interface Retryer {
+  execute<T>(attemptFn: () => Promise<T>, callbacks?: RetryCallbacks<T>): Promise<T>;
+}
+
+type RetryOptions = {
+  maxAttempts?: number; // Default: 3 (>= 1)
+  initialDelayMs?: number; // Default: 100
+  maxDelayMs?: number; // Default: 2000 (caps *computed* backoff only)
+  maxRetryAfterMs?: number; // Default: 60_000 (caps *server-driven* hints only)
+  backoffFactor?: number; // Default: 2
+  maxTotalElapsedMs?: number; // Default: Infinity
+};
+
+type RetryCallbacks<T> = {
+  signal?: AbortSignal;
+  isRetryableError?: (err: unknown) => boolean;
+  isRetryableResult?: (result: T) => boolean;
+  getRetryAfterMs?: (result: T) => number | undefined;
+  onRetry?: (info: { attempt: number; delayMs: number; error?: unknown; result?: T }) => void;
+  onExhausted?: (info: { attempts: number; error?: unknown; result?: T; reason: 'attempts' | 'deadline' }) => void;
+  drainResult?: (result: T) => Promise<void>;
+};
+```
+
+Use `BackoffRetryer` in production:
+
+```typescript
+import { BackoffRetryer } from '@salesforce/agentic-common';
+
+const retryer = new BackoffRetryer({ maxAttempts: 3, initialDelayMs: 100 });
+const response = await retryer.execute(() => fetch(url), {
+  isRetryableError: (err) => (err as { code?: string }).code === 'ECONNRESET',
+  isRetryableResult: (res) => res.status >= 500,
+  onRetry: ({ attempt, delayMs }) => log.warn(`retry ${attempt} in ${delayMs}ms`),
+});
+```
+
+Use `NoOpRetryer` in tests where retry behavior is irrelevant:
+
+```typescript
+import { NoOpRetryer } from '@salesforce/agentic-common';
+
+const client = new SomeClient(opts, { retryer: new NoOpRetryer() });
+```
+
+### `getErrorMessageWithStack(err: unknown): string`
+
+Like `getErrorMessage`, but returns the full stack trace for `Error` instances.
+
+### `wrapError(err: unknown, message: string): Error`
+
+Creates a new `Error` with a prefixed message and the original error as `cause`.
+
+## Development
+
+See [DEVELOPING.md](../../DEVELOPING.md) for build-from-source setup, scripts, and monorepo commands.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for implementation notes.

package/dist/clock.d.ts

@@ -0,0 +1,12 @@
+export declare abstract class Clock {
+    abstract now(): Date;
+    /**
+     * Returns a `Date` strictly after the given timestamp. The default implementation adds one
+     * millisecond, which is enough for ordering invariants in storage layers that sort by
+     * `createdAt`. Override if you need different stepping behavior in a test.
+     */
+    nextAfter(ts: Date): Date;
+}
+export declare class RealClock extends Clock {
+    now(): Date;
+}

package/dist/clock.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export class Clock {
+    /**
+     * Returns a `Date` strictly after the given timestamp. The default implementation adds one
+     * millisecond, which is enough for ordering invariants in storage layers that sort by
+     * `createdAt`. Override if you need different stepping behavior in a test.
+     */
+    nextAfter(ts) {
+        return new Date(ts.getTime() + 1);
+    }
+}
+export class RealClock extends Clock {
+    now() {
+        return new Date();
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAgB,KAAK;IAGvB;;;;OAIG;IACI,SAAS,CAAC,EAAQ;QACrB,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;IACtC,CAAC;CACJ;AAED,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,GAAG;QACN,OAAO,IAAI,IAAI,EAAE,CAAC;IACtB,CAAC;CACJ"}

package/dist/connection-factory.d.ts

@@ -0,0 +1,59 @@
+import type { OrgConnection } from './connection.js';
+/**
+ * Factory for creating authenticated {@link OrgConnection} instances to Salesforce orgs.
+ *
+ * Each method authenticates against the org, verifies the token is valid, and returns
+ * a ready-to-use connection with full identity metadata (orgId, username, instanceUrl).
+ */
+export interface OrgConnectionFactory {
+    /**
+     * Creates a connection by looking up stored auth for a specific org alias or username.
+     *
+     * Resolves the alias to a username (if it is an alias), loads the locally-stored
+     * auth credentials, and verifies the token via a lightweight refresh call.
+     *
+     * @param orgAliasOrUsername - An org alias (e.g. `"my-dev-org"`) or a full username
+     *   (e.g. `"user@example.org"`). Aliases are resolved via the SF CLI alias store.
+     */
+    createFromOrgAliasOrUsername(orgAliasOrUsername: string): Promise<OrgConnection>;
+    /**
+     * Creates a connection to the current target org, using the same resolution logic
+     * as the `sf` CLI:
+     *
+     * 1. If `projectRoot` is provided and is within a Salesforce DX project, uses the
+     *    project-local `target-org` from `.sf/config.json`.
+     * 2. Otherwise falls back to the machine-global `target-org` config value.
+     *
+     * Throws if no target org is configured at either level.
+     *
+     * @param options.projectRoot - A path within a Salesforce DX project. Used to locate
+     *   the project root and read its local config. If omitted or not within a project,
+     *   only the global default is consulted.
+     */
+    createFromTargetOrg(options?: {
+        projectRoot?: string;
+    }): Promise<OrgConnection>;
+    /**
+     * Creates a connection from a raw access token and instance URL (no local auth store).
+     *
+     * Useful for CI environments or programmatic access where credentials are provided
+     * via environment variables rather than the SF CLI keychain. Internally calls the
+     * Salesforce `/services/oauth2/userinfo` endpoint to resolve the username and orgId
+     * from the token.
+     *
+     * @param accessToken - A valid Salesforce OAuth access token.
+     * @param instanceUrl - The org's instance URL (e.g. `"https://myorg.my.salesforce.com"`).
+     */
+    createFromCredentials(accessToken: string, instanceUrl: string): Promise<OrgConnection>;
+}
+/**
+ * Production implementation of {@link OrgConnectionFactory} backed by `@salesforce/core`.
+ */
+export declare class RealOrgConnectionFactory implements OrgConnectionFactory {
+    createFromOrgAliasOrUsername(orgAliasOrUsername: string): Promise<OrgConnection>;
+    createFromTargetOrg(options?: {
+        projectRoot?: string;
+    }): Promise<OrgConnection>;
+    createFromCredentials(accessToken: string, instanceUrl: string): Promise<OrgConnection>;
+    private resolveAlias;
+}

package/dist/connection-factory.js

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { AuthInfo as SfCoreAuthInfo, ConfigAggregator, Connection as SfCoreConnection, OrgConfigProperties, SfProject, StateAggregator, } from '@salesforce/core';
+import { RealOrgConnection } from './connection.js';
+import { wrapError } from './error-utils.js';
+/**
+ * Production implementation of {@link OrgConnectionFactory} backed by `@salesforce/core`.
+ */
+export class RealOrgConnectionFactory {
+    async createFromOrgAliasOrUsername(orgAliasOrUsername) {
+        try {
+            const username = await this.resolveAlias(orgAliasOrUsername);
+            const authInfo = await SfCoreAuthInfo.create({ username });
+            const sfConn = await SfCoreConnection.create({ authInfo });
+            // refreshAuth will throw if the access token is invalid.
+            await sfConn.refreshAuth();
+            const fields = sfConn.getConnectionOptions();
+            if (!fields.accessToken || !fields.instanceUrl) {
+                throw new Error('Missing accessToken or instanceUrl. Try re-authenticating.');
+            }
+            const orgId = authInfo.getFields(true).orgId;
+            if (!orgId) {
+                throw new Error('Missing orgId. Try re-authenticating.');
+            }
+            return new RealOrgConnection(sfConn, fields.accessToken, fields.instanceUrl, username, orgId, orgAliasOrUsername);
+        }
+        catch (err) {
+            throw wrapError(err, `Failed to establish connection for "${orgAliasOrUsername}".`);
+        }
+    }
+    async createFromTargetOrg(options) {
+        if (options?.projectRoot) {
+            try {
+                const projectPath = await SfProject.resolveProjectPath(options.projectRoot);
+                const projectAggregator = await ConfigAggregator.create({ projectPath });
+                const info = projectAggregator.getInfo(OrgConfigProperties.TARGET_ORG);
+                const aliasOrUsername = typeof info.value === 'string' ? info.value : undefined;
+                if (aliasOrUsername && info.isLocal()) {
+                    return this.createFromOrgAliasOrUsername(aliasOrUsername);
+                }
+            }
+            catch {
+                // Not in an SFDX project or config read failure — fall through to global default.
+            }
+        }
+        const aggregator = await ConfigAggregator.create();
+        const aliasOrUsername = aggregator.getPropertyValue(OrgConfigProperties.TARGET_ORG);
+        if (!aliasOrUsername) {
+            throw new Error('No default org is configured. Set a default with `sf org login ... --set-default-org` or set the `target-org` config value.');
+        }
+        return this.createFromOrgAliasOrUsername(aliasOrUsername);
+    }
+    async createFromCredentials(accessToken, instanceUrl) {
+        try {
+            const authInfo = await SfCoreAuthInfo.create({
+                accessTokenOptions: { accessToken, instanceUrl },
+            });
+            const sfConn = await SfCoreConnection.create({ authInfo });
+            // Fail fast: issues a lightweight GET to verify the token is valid.
+            await sfConn.refreshAuth();
+            const username = authInfo.getUsername();
+            const orgId = authInfo.getFields(true).orgId;
+            if (!username) {
+                throw new Error('Could not determine username from credentials.');
+            }
+            if (!orgId) {
+                throw new Error('Could not determine orgId from credentials.');
+            }
+            return new RealOrgConnection(sfConn, accessToken, instanceUrl, username, orgId, username);
+        }
+        catch (err) {
+            throw wrapError(err, `Failed to establish connection for ${instanceUrl}.`);
+        }
+    }
+    async resolveAlias(orgAliasOrUsername) {
+        const stateAggregator = await StateAggregator.getInstance();
+        return stateAggregator.aliases.resolveUsername(orgAliasOrUsername) ?? orgAliasOrUsername;
+    }
+}
+//# sourceMappingURL=connection-factory.js.map

package/dist/connection-factory.js.map

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

package/dist/connection.d.ts

@@ -0,0 +1,50 @@
+import { Connection as SfCoreConnection } from '@salesforce/core';
+import { type SfApiEnv } from './sf-api-env.js';
+/**
+ * Interface for making authenticated HTTP requests to a Salesforce org.
+ * Carries identity metadata (orgId, username) alongside transport capabilities.
+ */
+export interface OrgConnection {
+    request<T>(opts: {
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        url: string;
+        body?: string;
+        headers?: {
+            [name: string]: string;
+        };
+    }): Promise<T>;
+    getAccessToken(): string;
+    getInstanceUrl(): string;
+    getUsername(): string;
+    getOrgId(): string;
+    getOrgAliasOrUsername(): string;
+    getInferredSfApiEnv(): SfApiEnv;
+}
+/**
+ * Production implementation of {@link OrgConnection} backed by `@salesforce/core`.
+ *
+ * Instances are created via {@link OrgConnectionFactory} — the constructor is not public.
+ */
+export declare class RealOrgConnection implements OrgConnection {
+    private readonly sfConnection;
+    private accessToken;
+    private readonly instanceUrl;
+    private readonly username;
+    private readonly orgId;
+    private readonly orgAliasOrUsername;
+    constructor(sfConnection: SfCoreConnection, accessToken: string, instanceUrl: string, username: string, orgId: string, orgAliasOrUsername: string);
+    getAccessToken(): string;
+    getInstanceUrl(): string;
+    getUsername(): string;
+    getOrgId(): string;
+    getOrgAliasOrUsername(): string;
+    getInferredSfApiEnv(): SfApiEnv;
+    request<T>(opts: {
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        url: string;
+        body?: string;
+        headers?: {
+            [name: string]: string;
+        };
+    }): Promise<T>;
+}

package/dist/connection.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { Connection as SfCoreConnection } from '@salesforce/core';
+import { inferSfApiEnv } from './sf-api-env.js';
+/**
+ * Production implementation of {@link OrgConnection} backed by `@salesforce/core`.
+ *
+ * Instances are created via {@link OrgConnectionFactory} — the constructor is not public.
+ */
+export class RealOrgConnection {
+    sfConnection;
+    accessToken;
+    instanceUrl;
+    username;
+    orgId;
+    orgAliasOrUsername;
+    constructor(sfConnection, accessToken, instanceUrl, username, orgId, orgAliasOrUsername) {
+        this.sfConnection = sfConnection;
+        this.accessToken = accessToken;
+        this.instanceUrl = instanceUrl;
+        this.username = username;
+        this.orgId = orgId;
+        this.orgAliasOrUsername = orgAliasOrUsername;
+        sfConnection.on('refresh', (newToken) => {
+            this.accessToken = newToken;
+        });
+    }
+    getAccessToken() {
+        return this.accessToken;
+    }
+    getInstanceUrl() {
+        return this.instanceUrl;
+    }
+    getUsername() {
+        return this.username;
+    }
+    getOrgId() {
+        return this.orgId;
+    }
+    getOrgAliasOrUsername() {
+        return this.orgAliasOrUsername;
+    }
+    getInferredSfApiEnv() {
+        return inferSfApiEnv(this.instanceUrl);
+    }
+    async request(opts) {
+        return this.sfConnection.request({
+            method: opts.method,
+            url: opts.url,
+            body: opts.body,
+            headers: opts.headers,
+        });
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAiB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAsB/D;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IACT,YAAY,CAAmB;IACxC,WAAW,CAAS;IACX,WAAW,CAAS;IACpB,QAAQ,CAAS;IACjB,KAAK,CAAS;IACd,kBAAkB,CAAS;IAE5C,YACI,YAA8B,EAC9B,WAAmB,EACnB,WAAmB,EACnB,QAAgB,EAChB,KAAa,EACb,kBAA0B;QAE1B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAE7C,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,QAAgB,EAAE,EAAE;YAC5C,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC;QAChC,CAAC,CAAC,CAAC;IACP,CAAC;IAED,cAAc;QACV,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED,cAAc;QACV,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED,WAAW;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED,QAAQ;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,qBAAqB;QACjB,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACnC,CAAC;IAED,mBAAmB;QACf,OAAO,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,IAKhB;QACG,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAAI;YAChC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;SACxB,CAAC,CAAC;IACP,CAAC;CACJ"}

package/dist/error-utils.d.ts

@@ -0,0 +1,9 @@
+export declare function getErrorMessage(err: unknown): string;
+/**
+ * Returns true if the value is an abort signal error from either platform shape:
+ * - DOM `AbortError` (e.g. `AbortController.abort()` against `fetch`/`undici.request`)
+ * - Node `ABORT_ERR` (`code === 'ABORT_ERR'`)
+ */
+export declare function isAbortError(err: unknown): boolean;
+export declare function getErrorMessageWithStack(err: unknown): string;
+export declare function wrapError(err: unknown, message: string): Error;

package/dist/error-utils.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export function getErrorMessage(err) {
+    return err instanceof Error || (typeof err === 'object' && err !== null && 'message' in err)
+        ? String(err.message)
+        : String(err);
+}
+/**
+ * Returns true if the value is an abort signal error from either platform shape:
+ * - DOM `AbortError` (e.g. `AbortController.abort()` against `fetch`/`undici.request`)
+ * - Node `ABORT_ERR` (`code === 'ABORT_ERR'`)
+ */
+export function isAbortError(err) {
+    if (typeof err !== 'object' || err === null) {
+        return false;
+    }
+    const name = err.name;
+    const code = err.code;
+    return name === 'AbortError' || code === 'ABORT_ERR';
+}
+export function getErrorMessageWithStack(err) {
+    if (err instanceof Error && err.stack) {
+        return err.stack;
+    }
+    return getErrorMessage(err);
+}
+export function wrapError(err, message) {
+    return new Error(`${message}\n${getErrorMessageWithStack(err)}`, { cause: err });
+}
+//# sourceMappingURL=error-utils.js.map

package/dist/error-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.js","sourceRoot":"","sources":["../src/error-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,eAAe,CAAC,GAAY;IACxC,OAAO,GAAG,YAAY,KAAK,IAAI,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,SAAS,IAAI,GAAG,CAAC;QACxF,CAAC,CAAC,MAAM,CAAE,GAA4B,CAAC,OAAO,CAAC;QAC/C,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACrC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAC;IAC9C,MAAM,IAAI,GAAI,GAA0B,CAAC,IAAI,CAAC;IAC9C,OAAO,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,WAAW,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACjD,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QACpC,OAAO,GAAG,CAAC,KAAK,CAAC;IACrB,CAAC;IACD,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAY,EAAE,OAAe;IACnD,OAAO,IAAI,KAAK,CAAC,GAAG,OAAO,KAAK,wBAAwB,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;AACrF,CAAC"}

package/dist/event-bus.d.ts

@@ -0,0 +1,27 @@
+export type EventListener<T> = (event: T) => void;
+export type Unsubscribe = () => void;
+/**
+ * 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 declare class EventBus<T> {
+    private readonly listeners;
+    /** Number of currently registered listeners. Useful for leak-check assertions in tests. */
+    get listenerCount(): number;
+    /**
+     * 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: EventListener<T>): Unsubscribe;
+    /** Emit an event to every registered listener. Listener errors are caught and discarded. */
+    emit(event: T): void;
+    /**
+     * 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: EventBus<T>, enrich?: (event: T) => T): Unsubscribe;
+    /** Remove all listeners. Idempotent. */
+    dispose(): void;
+}