@salesforce/agentic-common 0.5.0 → 0.6.0

package/README.md

@@ -6,7 +6,8 @@ interface consumed by the other packages in this monorepo.
 
 ## Quick Start
 
-> **Closed source.** This package is published to npm under the [Salesforce Public Code License](../../LICENSE.txt) and is for use by Salesforce only.
+> **Closed source.** This package is published to npm under the [Salesforce Public Code License](../../LICENSE.txt) and
+> is for use by Salesforce only.
 
 ```typescript
 import { EventBus, LogBus } from '@salesforce/agentic-common';
@@ -81,6 +82,35 @@ enum SfApiEnv {
 }
 ```
 
+### `inferSfApiEnv(instanceUrl, options?): SfApiEnv`
+
+Maps a Salesforce instance URL to a `SfApiEnv`. `OrgConnection.getInferredSfApiEnv()` is the typical entry point; direct
+callers use this when they have an `instanceUrl` but not a connection (e.g. building a Salesforce platform MCP URL from
+a token + instance URL).
+
+Resolution order:
+
+1. If `SF_API_ENV` is set to a valid value, return it.
+2. STM patterns → `Stage`.
+3. OrgFarm dev / perf / test sub-segments under `.pc-rnd.` → `Dev` / `Perf` / `Test`.
+4. `.pc-rnd.` host with no recognized sub-segment → `options.pcRndFallback ?? Test`. `.pc-rnd.` is an internal-only
+   OrgFarm domain (by definition not Prod), so the default degrades a future unrecognized sub-segment to a sibling
+   non-prod host rather than leaking traffic from a non-prod org to the Prod servlet.
+5. `.crm.dev` workspaces, `localhost.sfdcdev.`, `.internal.` → `Dev`.
+6. Anything else → `Prod`.
+
+```typescript
+function inferSfApiEnv(instanceUrl: string, options?: { pcRndFallback?: SfApiEnv }): SfApiEnv;
+```
+
+```typescript
+import { SfApiEnv, inferSfApiEnv } from '@salesforce/agentic-common';
+
+inferSfApiEnv('https://myorg.test1.pc-rnd.salesforce.com'); // SfApiEnv.Test
+inferSfApiEnv('https://myorg.qa1.pc-rnd.salesforce.com'); // SfApiEnv.Test (default fallback)
+inferSfApiEnv('https://myorg.qa1.pc-rnd.salesforce.com', { pcRndFallback: SfApiEnv.Prod }); // SfApiEnv.Prod
+```
+
 ### `Clock` / `RealClock`
 
 Abstract time source for dependency injection. Use `RealClock` in production; extend `Clock` in tests for deterministic
@@ -261,8 +291,8 @@ Splits a markdown document into its YAML frontmatter block and body content. Rec
 frontmatter block at the start of a document and normalizes CRLF line endings to LF. When no frontmatter block is
 present, `frontmatter` is `null` and `body` is the full input.
 
-The frontmatter is returned unparsed so callers can choose whether to parse it as YAML, JSON, or treat it as opaque
-text — keeping a YAML runtime out of `@salesforce/agentic-common`.
+The frontmatter is returned unparsed so callers can choose whether to parse it as YAML, JSON, or treat it as opaque text
+— keeping a YAML runtime out of `@salesforce/agentic-common`.
 
 ```typescript
 import { splitFrontmatterAndBody } from '@salesforce/agentic-common';

package/dist/index.d.ts

@@ -7,5 +7,5 @@ export { type UniqueIDGenerator, UUIDGenerator } from './id-generator.js';
 export { LogBus, type LogLevel, type LogRecord } from './log.js';
 export { type FrontmatterSplit, splitFrontmatterAndBody } from './markdown-frontmatter.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';
+export { inferSfApiEnv, SfApiEnv } from './sf-api-env.js';
 export { buildSummaryPrompt } from './summary-prompt.js';

package/dist/index.js

@@ -11,6 +11,6 @@ export { UUIDGenerator } from './id-generator.js';
 export { LogBus } from './log.js';
 export { splitFrontmatterAndBody } from './markdown-frontmatter.js';
 export { BackoffRetryer, DEFAULT_RETRY_OPTIONS, NoOpRetryer, } from './retryer.js';
-export { SfApiEnv } from './sf-api-env.js';
+export { inferSfApiEnv, SfApiEnv } from './sf-api-env.js';
 export { buildSummaryPrompt } from './summary-prompt.js';
 //# sourceMappingURL=index.js.map

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

@@ -16,6 +16,19 @@ export declare enum SfApiEnv {
  *    - 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`
+ *    - `pc-rnd` hosts with no recognized sub-segment → `options.pcRndFallback` (default `test`)
  *    - Everything else (including unrecognized internal URLs) → `prod`
+ *
+ * @param instanceUrl - Salesforce org instance URL.
+ * @param options - Optional resolution overrides.
+ * @param options.pcRndFallback - Environment to return when the URL is a `.pc-rnd.`
+ *   host that does not match a recognized `.devN.` / `.perfN.` / `.testN.` sub-segment.
+ *   Defaults to {@link SfApiEnv.Test}: `.pc-rnd.` is an internal-only OrgFarm domain,
+ *   so by definition not Prod — a future unrecognized sub-segment degrades to a
+ *   sibling non-prod host instead of leaking traffic from a non-prod org to the
+ *   Prod servlet. Callers with a stronger guarantee (e.g. inputs are pre-validated
+ *   to be Prod-class hosts) can pass another value to override.
  */
-export declare function inferSfApiEnv(instanceUrl: string): SfApiEnv;
+export declare function inferSfApiEnv(instanceUrl: string, options?: {
+    pcRndFallback?: SfApiEnv;
+}): SfApiEnv;

package/dist/sf-api-env.js

@@ -21,9 +21,20 @@ export var SfApiEnv;
  *    - 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`
+ *    - `pc-rnd` hosts with no recognized sub-segment → `options.pcRndFallback` (default `test`)
  *    - Everything else (including unrecognized internal URLs) → `prod`
+ *
+ * @param instanceUrl - Salesforce org instance URL.
+ * @param options - Optional resolution overrides.
+ * @param options.pcRndFallback - Environment to return when the URL is a `.pc-rnd.`
+ *   host that does not match a recognized `.devN.` / `.perfN.` / `.testN.` sub-segment.
+ *   Defaults to {@link SfApiEnv.Test}: `.pc-rnd.` is an internal-only OrgFarm domain,
+ *   so by definition not Prod — a future unrecognized sub-segment degrades to a
+ *   sibling non-prod host instead of leaking traffic from a non-prod org to the
+ *   Prod servlet. Callers with a stronger guarantee (e.g. inputs are pre-validated
+ *   to be Prod-class hosts) can pass another value to override.
  */
-export function inferSfApiEnv(instanceUrl) {
+export function inferSfApiEnv(instanceUrl, options) {
     const envVar = process.env['SF_API_ENV']?.toLowerCase();
     if (envVar && Object.values(SfApiEnv).includes(envVar)) {
         return envVar;
@@ -44,6 +55,7 @@ export function inferSfApiEnv(instanceUrl) {
         if (/\.test\d+\./.test(lower)) {
             return SfApiEnv.Test;
         }
+        return options?.pcRndFallback ?? SfApiEnv.Test;
     }
     if (lower.includes('.crm.dev') || lower.includes('localhost.sfdcdev.') || lower.includes('.internal.')) {
         return SfApiEnv.Dev;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/agentic-common",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared primitives and common utilities for the Salesforce agentic DX packages",
   "type": "module",
   "exports": {