@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/sales-call-scoring-configure/scripts/list-competencies.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+
+# List existing Coaching Competencies on the org.
+# Reads EnablementCompetencyDef (setup entity, keyPrefix 1nA) via Tooling API.
+#
+# Output modes (per SKILL.md rule #5 — admin-safe by default):
+#   default   — MasterLabel + IsActive + Scope + Description only.
+#               No record Ids, DeveloperNames, or Template enum keys.
+#   --verbose — Everything the default shows, PLUS DeveloperName, Id, and
+#               SourceCompetencyTemplate. Use when the admin explicitly
+#               asks to debug or share with support.
+#   --json    — Raw record JSON for the calling agent to parse. Never
+#               forward this to the admin directly.
+#
+# Usage:
+#   ./list-competencies.sh <org-alias>
+#   ./list-competencies.sh <org-alias> --verbose
+#   ./list-competencies.sh <org-alias> --json
+
+set -euo pipefail
+
+export NO_COLOR=1
+export FORCE_COLOR=0
+
+ORG_ALIAS="${1:-}"
+FORMAT="${2:-text}"
+
+if [[ -z "$ORG_ALIAS" ]]; then
+  echo "Error: Missing org alias"
+  echo "Usage: $0 <org-alias> [--verbose|--json]"
+  exit 1
+fi
+
+case "$FORMAT" in
+  text|--verbose|--json) ;;
+  *) echo "Error: Unknown flag: $FORMAT (expected --verbose or --json)"; exit 1 ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=shared/auth.sh
+source "$SCRIPT_DIR/shared/auth.sh"
+
+resolve_org_auth "$ORG_ALIAS" || exit 1
+
+QUERY="SELECT Id, DeveloperName, MasterLabel, Description, IsActive, EvaluationScope, SourceCompetencyTemplate FROM EnablementCompetencyDef ORDER BY MasterLabel"
+
+RAW=$(sf data query --target-org "$ORG_ALIAS" --use-tooling-api \
+  --query "$QUERY" --json 2>/dev/null)
+
+# sf can prepend update-available warnings to stdout — extract the JSON body.
+RAW_JSON=$(echo "$RAW" | awk '/^{/,EOF')
+
+if ! echo "$RAW_JSON" | jq -e '.status == 0' >/dev/null 2>&1; then
+  echo "Error: Tooling API query failed:"
+  echo "$RAW" | jq -r '.message // .' 2>/dev/null || echo "$RAW"
+  exit 1
+fi
+RAW="$RAW_JSON"
+
+if [[ "$FORMAT" == "--json" ]]; then
+  echo "$RAW" | jq '.result.records'
+  exit 0
+fi
+
+TOTAL=$(echo "$RAW" | jq -r '.result.totalSize')
+ACTIVE=$(echo "$RAW" | jq -r '[.result.records[] | select(.IsActive == true)] | length')
+
+echo "Coaching Competencies on $ORG_ALIAS"
+echo ""
+echo "   Total: $TOTAL   Active: $ACTIVE / 8 (max)"
+echo ""
+
+if [[ "$TOTAL" == "0" ]]; then
+  echo "   (none configured yet — run install-ootb-competencies.sh to seed the OOTB set)"
+  exit 0
+fi
+
+if [[ "$FORMAT" == "--verbose" ]]; then
+  # Full technical detail — Ids, DeveloperNames, Template enum keys.
+  # Only show this when the admin explicitly asks to debug or share with support.
+  echo "$RAW" | jq -r '.result.records[] |
+    "   \(if .IsActive then "" else "" end)  \(.MasterLabel)
+         Scope:         \(.EvaluationScope)
+         Description:   \(.Description // "(none)")
+         DeveloperName: \(.DeveloperName)\(if .SourceCompetencyTemplate != null and .SourceCompetencyTemplate != "" then "
+         Template:      \(.SourceCompetencyTemplate)" else "" end)
+         Id:            \(.Id)
+    "'
+else
+  # Default admin-safe view — no Ids, DeveloperNames, or Template enum keys.
+  echo "$RAW" | jq -r '.result.records[] |
+    "   \(if .IsActive then "" else "" end)  \(.MasterLabel)
+         Scope:       \(.EvaluationScope)
+         Description: \(.Description // "(none)")
+    "'
+fi

package/skills/sales-call-scoring-configure/scripts/shared/auth.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+# Shared library for org authentication resolution.
+#
+# Two entry points, deliberately separate:
+#
+#   resolve_org_auth <alias>            → validate alias, confirm reachable,
+#                                         confirm HTTPS. Does NOT extract
+#                                         ACCESS_TOKEN. Use this if the caller
+#                                         only ever hits Salesforce through
+#                                         `sf api request rest --target-org`
+#                                         or `sf data query --target-org`,
+#                                         which authenticate via the CLI's own
+#                                         session and never need the raw token
+#                                         in shell scope.
+#
+#   resolve_org_auth_with_token <alias> → does everything above, PLUS extracts
+#                                         and exports ACCESS_TOKEN. Use this
+#                                         ONLY when a caller must embed the
+#                                         token in a request body (e.g. SOAP
+#                                         Metadata API sessionId — see
+#                                         enable-call-scoring.sh).
+#
+# The split exists because passing ACCESS_TOKEN on a curl command line
+# ("curl -H 'Authorization: Bearer $ACCESS_TOKEN' ...") exposes the token in
+# the OS process table (ps / /proc/*/cmdline). Callers that don't strictly
+# need the raw token should not extract it. See W-23934530.
+#
+# Both functions cache results on RESOLVED_ORG_ALIAS so back-to-back invocations
+# in the same shell don't re-hit `sf org display`.
+
+# Common gate — alias validation + reachability + HTTPS. Exports INSTANCE_URL
+# (needed by SOAP callers to build the endpoint). Does NOT export a token.
+resolve_org_auth() {
+  local org_alias="$1"
+
+  if [[ -z "$org_alias" ]]; then
+    echo "Error: Missing org alias"
+    return 1
+  fi
+
+  if [[ ! "$org_alias" =~ ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ ]]; then
+    echo "Invalid org alias: '$org_alias'"
+    return 1
+  fi
+
+  # Cache hit — but re-check HTTPS in case the cached INSTANCE_URL was set by
+  # something other than a prior resolve_org_auth call.
+  if [[ -n "${INSTANCE_URL:-}" && "${RESOLVED_ORG_ALIAS:-}" == "$org_alias" ]]; then
+    if [[ ! "$INSTANCE_URL" =~ ^https:// ]]; then
+      echo "Cached instance URL is not HTTPS: $INSTANCE_URL"
+      echo "   Refusing to authenticate over an insecure connection."
+      return 1
+    fi
+    return 0
+  fi
+
+  # Capture stderr too — some CLI versions emit auth errors there — then strip
+  # any warning lines the sf CLI prepends to stdout before the JSON body.
+  local org_display org_json
+  org_display=$(sf org display --target-org "$org_alias" --json 2>&1)
+  org_json=$(echo "$org_display" | awk '/^{/,EOF')
+
+  INSTANCE_URL=$(echo "$org_json" | jq -r '.result.instanceUrl // empty' 2>/dev/null)
+  if [[ -z "$INSTANCE_URL" ]]; then
+    echo "Cannot connect to org '$org_alias'. Run: sf org login web --alias $org_alias"
+    return 1
+  fi
+
+  if [[ ! "$INSTANCE_URL" =~ ^https:// ]]; then
+    echo "Instance URL is not HTTPS: $INSTANCE_URL"
+    echo "   Refusing to authenticate over an insecure connection."
+    return 1
+  fi
+
+  export INSTANCE_URL
+  RESOLVED_ORG_ALIAS="$org_alias"
+  export RESOLVED_ORG_ALIAS
+  return 0
+}
+
+# Superset — resolve_org_auth + extract ACCESS_TOKEN. Used ONLY by callers
+# that must place the token inside a request body (SOAP sessionId). New code
+# should not use this; prefer `sf api request rest --target-org` instead.
+resolve_org_auth_with_token() {
+  local org_alias="$1"
+
+  resolve_org_auth "$org_alias" || return 1
+
+  # Cache hit on token too.
+  if [[ -n "${ACCESS_TOKEN:-}" && "${ACCESS_TOKEN}" != "null" \
+        && "${RESOLVED_ORG_ALIAS:-}" == "$org_alias" \
+        && "${ACCESS_TOKEN_RESOLVED:-}" == "1" ]]; then
+    return 0
+  fi
+
+  local org_display org_json
+  org_display=$(sf org display --target-org "$org_alias" --json 2>&1)
+  org_json=$(echo "$org_display" | awk '/^{/,EOF')
+
+  ACCESS_TOKEN=$(echo "$org_json" | jq -r '.result.accessToken // empty' 2>/dev/null)
+  if [[ -z "$ACCESS_TOKEN" || "$ACCESS_TOKEN" == "null" || "$ACCESS_TOKEN" == *"REDACTED"* ]]; then
+    # CLI ~2.108+ redacts accessToken in `org display` — fall back to the
+    # dedicated command that always returns the real token.
+    ACCESS_TOKEN=$(echo "y" | sf org auth show-access-token --target-org "$org_alias" --no-prompt --json 2>/dev/null | jq -r '.result.accessToken // empty')
+  fi
+
+  if [[ -z "$ACCESS_TOKEN" || "$ACCESS_TOKEN" == "null" ]]; then
+    echo "Cannot extract access token. Re-authenticate: sf org login web --alias $org_alias"
+    return 1
+  fi
+
+  export ACCESS_TOKEN
+  ACCESS_TOKEN_RESOLVED="1"
+  export ACCESS_TOKEN_RESOLVED
+  return 0
+}

package/skills/sales-call-scoring-configure/scripts/shared/cap.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# Shared cap-diagnosis helpers for the 8-active EnablementCompetencyDef limit.
+#
+# Server-side, EnablementCompetencyDef enforces a hard cap of 8 IsActive=true
+# records per org (CoachingCompetenciesFeature.MAX_ACTIVE_COMPETENCIES). All
+# five write scripts (create-competency, create-custom-competency,
+# toggle-custom-competency, install-ootb-competencies,
+# install-best-practice-competencies) call these helpers to keep the
+# admin-facing cap message identical across the surface.
+#
+# Contract for callers: source this file, then use
+#   query_active_count <ORG_ALIAS>
+#   print_cap_report   <ORG_ALIAS> <CONTEXT>
+#   print_cap_footer_activate_hint <NEW_ID_OR_NAME>
+#
+# CONTEXT is a short human phrase used in the header, e.g.
+#   "creating '$MASTER_LABEL'"     (create paths)
+#   "activating '$REC_LABEL'"      (toggle paths)
+#   "installing OOTB competencies" (installer paths)
+#
+# All queries run through `sf api request rest --target-org` so the org's
+# access token is never passed as curl argv (visible in the process table).
+# Nothing here writes to the org — read-only diagnosis only. The decision to
+# fall back to inactive (custom / installer paths) or refuse outright (toggle
+# path — you can't activate to inactive) is the caller's.
+
+MAX_ACTIVE_COMPETENCIES=8
+CAP_TOOLING_BASE="services/data/v68.0/tooling"
+
+# Return the current active count (or "0" on any failure — callers should
+# treat a query failure as "cannot verify cap" and continue optimistically;
+# the server-side hard cap still protects them).
+query_active_count() {
+  local org_alias="$1"
+  (sf api request rest \
+    "${CAP_TOOLING_BASE}/query/?q=SELECT+COUNT()+FROM+EnablementCompetencyDef+WHERE+IsActive=true" \
+    --target-org "$org_alias" 2>/dev/null || true) \
+    | jq -r '.totalSize // 0' 2>/dev/null || echo "0"
+}
+
+# Print a rich, admin-actionable cap report to stderr. Lists the currently
+# active competencies with their Ids (deactivate command is copy-pasteable)
+# and explains next steps. Caller supplies the context string that goes at
+# the top ("Cap reached while <context>").
+print_cap_report() {
+  local org_alias="$1"
+  local context="$2"
+
+  local list_json
+  list_json=$(sf api request rest \
+    "${CAP_TOOLING_BASE}/query/?q=SELECT+Id,MasterLabel,DeveloperName,SourceCompetencyTemplate+FROM+EnablementCompetencyDef+WHERE+IsActive=true+ORDER+BY+MasterLabel" \
+    --target-org "$org_alias" 2>/dev/null || true)
+
+  {
+    echo ""
+    echo "Warning: Active Coaching Competency cap reached while ${context}."
+    echo ""
+    echo "    Salesforce allows up to ${MAX_ACTIVE_COMPETENCIES} active competencies per org."
+    echo "    This org currently has ${MAX_ACTIVE_COMPETENCIES} active — listed below."
+    echo ""
+    echo "    Currently active:"
+    echo "$list_json" | jq -r '.records[]? | "      • \(.MasterLabel)  (\(.Id))"' 2>/dev/null || echo "      (unable to list — the server-side cap check will still enforce this)"
+    echo ""
+    echo "    To free a slot, deactivate one of the above:"
+    echo "$list_json" | jq -r '.records[0:1][]? | "      ./skills/sales-call-scoring-configure/scripts/toggle-custom-competency.sh <alias> \(.Id) deactivate"' 2>/dev/null
+    echo ""
+  } >&2
+}
+
+# Print the second half of the fallback message (only used by paths that
+# auto-create an inactive record). Explains what just happened and how to
+# flip it on later.
+#
+# Args:
+#   $1 = record identifier the admin can copy-paste (Id preferred,
+#        MasterLabel acceptable)
+print_cap_footer_activate_hint() {
+  local ident="$1"
+  {
+    echo "    The new competency was created INACTIVE so your work isn't blocked."
+    echo "    Once you deactivate an existing competency, activate the new one:"
+    echo ""
+    echo "      ./skills/sales-call-scoring-configure/scripts/toggle-custom-competency.sh <alias> ${ident} activate"
+    echo ""
+  } >&2
+}

package/skills/sales-call-scoring-configure/scripts/shared/soap.sh

@@ -0,0 +1,267 @@
+#!/bin/bash
+# Shared library for SOAP Metadata API response parsing
+#
+# Functions:
+#   redact_token <input> - Redacts session IDs and Bearer tokens from error messages
+#   parse_soap_response <xml> <field> <http_status> - Classifies SOAP responses
+#
+# Returns:
+#   "true" - field is enabled
+#   "false" - field is explicitly disabled or omitted (setting is off)
+#   "AUTH_ERROR:<fault>" - authentication/authorization failure
+#   "TYPE_UNAVAILABLE:<fault>" - org lacks license/edition for this feature
+#   "WRITE_ERROR:<statusCode>[:<message>]" - updateMetadata returned a well-formed
+#       response with <success>false</success> and an <errors> block. The server
+#       accepted the request and reports a specific reason for refusal (e.g.
+#       INSUFFICIENT_ACCESS_OR_READONLY during a provisioning window). Callers
+#       decide whether the statusCode is transient (retryable) or terminal.
+#   "NETWORK_ERROR" - network/service error (empty response, 5xx, malformed XML)
+
+# Redact session IDs and Bearer tokens from error messages
+# Args: $1 = input string
+# Returns: string with tokens replaced by [REDACTED]
+#
+# Salesforce session IDs start with the 15/18-char org id (00D...) followed by
+# '!' and a signature segment that contains '.', '=', '-', '+' in addition to
+# alphanumerics. Match greedily up to the next whitespace or XML tag boundary
+# ('<') so the whole token tail is redacted, not just its leading run.
+redact_token() {
+  local input="$1"
+  printf '%s' "$input" | sed 's/00D[^ <]*/[REDACTED]/g; s/Bearer [^ ]*/Bearer [REDACTED]/g'
+}
+
+# Parse SOAP Metadata API response and classify the result
+# Args:
+#   $1 = raw SOAP XML response
+#   $2 = field name to extract (e.g., "enableEinsteinGptPlatform")
+#   $3 = HTTP status code (e.g., "200", "503")
+# Returns: classification string (see header comments)
+parse_soap_response() {
+  local xml_response="$1"
+  local field_name="$2"
+  local http_status="$3"
+
+  # Validate field_name to prevent regex injection in grep patterns below
+  if [[ ! "$field_name" =~ ^[A-Za-z0-9_]+$ ]]; then
+    echo "NETWORK_ERROR"
+    return 0
+  fi
+
+  # Disable pipefail locally to allow grep failures without aborting
+  local old_opts="$-"
+  set +e
+
+  # An empty response body is always a network error, regardless of status.
+  if [[ -z "$xml_response" ]]; then
+    # Restore pipefail before returning
+    if [[ "$old_opts" =~ e ]]; then set -e; fi
+    echo "NETWORK_ERROR"
+    return 0
+  fi
+
+  # Check for SOAP Fault (auth, permission, or type errors) *before* the
+  # generic non-2xx-status check below — Salesforce commonly returns real
+  # SOAP Faults (invalid session, insufficient access, unlicensed type) with
+  # an HTTP 500 status, so gating on status first would silently reclassify
+  # every such fault as a generic "network/timeout error" and hide the
+  # actual auth/licensing diagnosis from the admin.
+  # Handle both standard and namespace-prefixed faults
+  local fault_code=""
+  if echo "$xml_response" | grep -q "<soapenv:Fault>\\|<sf:Fault>\\|<Fault>"; then
+    # Extract faultcode - try multiple patterns for different namespace conventions
+    fault_code=$(echo "$xml_response" | grep -o "<faultcode>[^<]*</faultcode>" | sed 's/<[^>]*>//g' | head -1)
+    if [[ -z "$fault_code" ]]; then
+      fault_code=$(echo "$xml_response" | grep -o "<sf:faultcode>[^<]*</sf:faultcode>" | sed 's/<[^>]*>//g' | head -1)
+    fi
+    if [[ -z "$fault_code" ]]; then
+      # Handle fully-qualified fault codes like "sf:INVALID_SESSION_ID"
+      fault_code=$(echo "$xml_response" | grep -oE "faultcode>[^<]*</.*faultcode" | sed 's/<[^>]*>//g' | sed 's/.*://' | head -1)
+    fi
+
+    if [[ -n "$fault_code" ]]; then
+      # Extract faultstring for context (will be redacted)
+      local fault_string=""
+      fault_string=$(echo "$xml_response" | grep -o "<faultstring>[^<]*</faultstring>" | sed 's/<[^>]*>//g' | head -1 || echo "")
+      if [[ -z "$fault_string" ]]; then
+        fault_string=$(echo "$xml_response" | grep -o "<sf:faultstring>[^<]*</sf:faultstring>" | sed 's/<[^>]*>//g' | head -1 || echo "")
+      fi
+
+      # Redact tokens from fault string
+      if [[ -n "$fault_string" ]]; then
+        fault_string=$(redact_token "$fault_string")
+      fi
+
+      # Classify by fault type
+      # INVALID_TYPE = org lacks license/edition - distinct from auth failures
+      if echo "$fault_code" | grep -qi "INVALID_TYPE"; then
+        if [[ "$old_opts" =~ e ]]; then set -e; fi
+        echo "TYPE_UNAVAILABLE:${fault_code}${fault_string:+:$fault_string}"
+        return 0
+      fi
+
+      # All other faults are auth/permission errors
+      if [[ "$old_opts" =~ e ]]; then set -e; fi
+      echo "AUTH_ERROR:${fault_code}${fault_string:+:$fault_string}"
+      return 0
+    fi
+  fi
+
+  # No fault matched above — a non-2xx status at this point is a genuine
+  # network/service error (not a classifiable SOAP-level failure).
+  if [[ "$http_status" != "200" && "$http_status" != "201" ]]; then
+    if [[ "$old_opts" =~ e ]]; then set -e; fi
+    echo "NETWORK_ERROR"
+    return 0
+  fi
+
+  # Check if response is valid XML with the expected structure
+  # If it's HTML or malformed XML, treat as network error
+  if ! echo "$xml_response" | grep -q "<readMetadataResponse>\\|<updateMetadataResponse>"; then
+    if [[ "$old_opts" =~ e ]]; then set -e; fi
+    echo "NETWORK_ERROR"
+    return 0
+  fi
+
+  # Check for closing envelope tag - if missing, XML is truncated
+  if ! echo "$xml_response" | grep -q "</soapenv:Envelope>"; then
+    if [[ "$old_opts" =~ e ]]; then set -e; fi
+    echo "NETWORK_ERROR"
+    return 0
+  fi
+
+  # Well-formed updateMetadataResponse with an <errors> block: the server
+  # accepted the request, reports success=false, and names the reason via
+  # <statusCode> (e.g. INSUFFICIENT_ACCESS_OR_READONLY when a dependent field
+  # is temporarily read-only during ECI's async provisioning window — see
+  # W-23968462). Without this branch, the fallback field-value grep below
+  # would find <success>false</success> and collapse to bare "false", losing
+  # the statusCode the admin needs to distinguish transient from terminal.
+  # Scoped to updateMetadataResponse to avoid a false positive on readMetadata
+  # responses that happen to contain an <errors> element in metadata content.
+  if echo "$xml_response" | grep -q "<updateMetadataResponse>" \
+     && echo "$xml_response" | grep -q "<errors>"; then
+    local status_code=""
+    local err_message=""
+    status_code=$(echo "$xml_response" | grep -o "<statusCode>[^<]*</statusCode>" | sed 's/<[^>]*>//g' | head -1)
+    err_message=$(echo "$xml_response" | grep -o "<message>[^<]*</message>" | sed 's/<[^>]*>//g' | head -1)
+    if [[ -n "$err_message" ]]; then
+      err_message=$(redact_token "$err_message")
+    fi
+    if [[ -n "$status_code" ]]; then
+      if [[ "$old_opts" =~ e ]]; then set -e; fi
+      echo "WRITE_ERROR:${status_code}${err_message:+:$err_message}"
+      return 0
+    fi
+  fi
+
+  # Extract field value - try to find <field>true/false</field>
+  # head -1 collapses multi-record responses to the first match so two records
+  # never produce a two-line value that fails the == comparisons below.
+  local field_value=""
+  field_value=$(echo "$xml_response" | grep -o "<${field_name}>[^<]*</${field_name}>" | grep -o "true\\|false" | head -1 || echo "")
+
+  if [[ "$field_value" == "true" ]]; then
+    if [[ "$old_opts" =~ e ]]; then set -e; fi
+    echo "true"
+    return 0
+  fi
+
+  # An update call reporting success=false has no SOAP fault, but the
+  # response still carries an <errors> block (statusCode + message) with the
+  # actual reason — e.g. INSUFFICIENT_ACCESS_OR_READONLY. Surface it instead
+  # of silently collapsing to a bare "false" the caller can't act on.
+  if [[ "$field_name" == "success" && "$field_value" == "false" ]]; then
+    local err_status_code="" err_message=""
+    err_status_code=$(echo "$xml_response" | grep -o "<statusCode>[^<]*</statusCode>" | sed 's/<[^>]*>//g' | head -1)
+    if [[ -z "$err_status_code" ]]; then
+      err_status_code=$(echo "$xml_response" | grep -o "<sf:statusCode>[^<]*</sf:statusCode>" | sed 's/<[^>]*>//g' | head -1)
+    fi
+    err_message=$(echo "$xml_response" | grep -o "<message>[^<]*</message>" | sed 's/<[^>]*>//g' | head -1)
+    if [[ -z "$err_message" ]]; then
+      err_message=$(echo "$xml_response" | grep -o "<sf:message>[^<]*</sf:message>" | sed 's/<[^>]*>//g' | head -1)
+    fi
+    if [[ -n "$err_message" ]]; then
+      err_message=$(redact_token "$err_message")
+    fi
+    if [[ -n "$err_status_code" || -n "$err_message" ]]; then
+      if [[ "$old_opts" =~ e ]]; then set -e; fi
+      echo "UPDATE_REJECTED:${err_status_code:-UNKNOWN}${err_message:+:$err_message}"
+      return 0
+    fi
+  fi
+
+  # If field is explicitly false OR field is omitted entirely, treat as disabled.
+  # Salesforce omits boolean settings fields when they're off rather than
+  # emitting <field>false</field>, so an absent field inside an otherwise valid
+  # readMetadataResponse is the disabled state, not an error.
+  if [[ "$field_value" == "false" ]] || [[ -z "$field_value" ]]; then
+    if [[ "$old_opts" =~ e ]]; then set -e; fi
+    echo "false"
+    return 0
+  fi
+
+  # Shouldn't reach here, but if we do, treat as network error (unexpected response format)
+  if [[ "$old_opts" =~ e ]]; then set -e; fi
+  echo "NETWORK_ERROR"
+  return 0
+}
+
+# Issues one SOAP Metadata API call. Requires $SOAP_ENDPOINT and
+# $CURL_TIMEOUT to be set by the caller (see enable-call-scoring.sh /
+# install-ootb-competencies.sh for the standard setup).
+# Args: $1 = SOAPAction, $2 = request body
+# Body is piped via stdin (-d @-) rather than argv so the SOAP sessionId
+# — which embeds the raw ACCESS_TOKEN — is not visible in the OS process
+# table (ps / /proc/*/cmdline). See W-23934530 / W-23974869.
+soap_call() {
+  local action="$1"
+  local body="$2"
+  # `|| true` — a curl failure (timeout, DNS, refused connection) must not
+  # abort the script via set -e; empty output + empty status here falls
+  # through to parse_soap_response's NETWORK_ERROR classification below.
+  printf '%s' "$body" | curl -s -w '\nHTTPSTATUS:%{http_code}' --max-time "$CURL_TIMEOUT" -X POST "$SOAP_ENDPOINT" \
+    -H "Content-Type: text/xml; charset=utf-8" \
+    -H "SOAPAction: $action" \
+    --data-binary @- 2>/dev/null || true
+}
+
+# Splits a soap_call() response into HTTP status + body and classifies one
+# field via parse_soap_response. Unlike a plain grep, this distinguishes
+# *why* a read/update didn't come back "true": an explicit false/absent
+# field, a SOAP fault (auth/permission), an org that isn't licensed for the
+# type (INVALID_TYPE), or a network/timeout failure.
+# Args: $1 = soap_call() response, $2 = field name
+classify_field() {
+  local combined="$1"
+  local field="$2"
+  local http_status body
+  # `|| true` on the grep — an empty/malformed $combined (curl failure) has
+  # no HTTPSTATUS marker to match, and under pipefail that would otherwise
+  # abort the script instead of yielding an empty status for NETWORK_ERROR.
+  http_status=$( (echo "$combined" | grep -o 'HTTPSTATUS:[0-9]*$' || true) | cut -d: -f2)
+  body=$(echo "$combined" | sed 's/HTTPSTATUS:[0-9]*$//')
+  parse_soap_response "$body" "$field" "$http_status"
+}
+
+# Normalizes a classify_field() result to true/false, or "" for anything
+# that isn't a clean field read (fault/error) — callers that need the fault
+# detail should inspect the raw classification themselves.
+normalize_class() {
+  case "$1" in
+    true|false) echo "$1" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Turns a classify_field() classification into a one-line, token-redacted,
+# admin-safe explanation of why a call failed.
+describe_failure() {
+  case "$1" in
+    AUTH_ERROR:*) echo "authentication/permission error — ${1#AUTH_ERROR:}" ;;
+    TYPE_UNAVAILABLE:*) echo "org isn't licensed for this setting — ${1#TYPE_UNAVAILABLE:}" ;;
+    WRITE_ERROR:*) echo "server refused the change — ${1#WRITE_ERROR:}" ;;
+    NETWORK_ERROR*) echo "network/timeout error reaching Salesforce — try again" ;;
+    false) echo "call succeeded but reported failure (no SOAP fault returned)" ;;
+    *) echo "unexpected response: $1" ;;
+  esac
+}

package/skills/sales-call-scoring-configure/scripts/shared/soql.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# soql.sh — SOQL string-literal escaping.
+#
+# soql_escape RAW → SAFE
+#   Prints RAW with every character that has meaning inside a SOQL string
+#   literal escaped so the caller can wrap the result in single quotes:
+#
+#       WHERE MasterLabel='$(soql_escape "$LABEL")'
+#
+#   Escapes, in order:
+#     \  → \\        (must happen first)
+#     '  → \'
+#
+#   Order matters. If the quote-pass ran first, the backslash-pass would
+#   double-escape the backslash inserted for quotes and re-open the string.
+#
+#   Implemented with sed rather than bash parameter expansion. The natural
+#   "${var//\'/\\\'}" pattern silently emits TWO backslashes in the
+#   replacement because of how backslashes are consumed by both the shell
+#   scanner and the parameter-expansion replacement string. sed sidesteps
+#   that quirk and its escape rules match SOQL's directly.
+
+soql_escape() {
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e "s/'/\\\\'/g"
+}