feat(ramp_sandbox): AI-optimized Ramp Sandbox actions for MCP (#21792)

* feat(ramp_sandbox): AI-optimized action set mirroring the Ramp components

Adds 15 AI-optimized Ramp Sandbox actions (users, transactions, spend limits,
departments, locations, spend programs, transfers) — list, get, create, update,
terminate — as demo-API (demo-api.ramp.com) twins of the ramp components shipped
in #21725. Each spreads its ramp base action and overrides key/name/description +
props for the sandbox app.

- Extends @pipedream/ramp ^0.3.0 (the merged base: spend limits on the documented
  /funds API, shared propDefinitions, compact list projection with a `fields` param).
- Adds the `// x-pd-ai: optimized` marker to the app and the two AI-optimized
  pre-existing actions (create-user-invite, upload-receipt); issue-virtual-card is
  left unmarked as it uses dynamic props (not MCP-optimizable).

Validated against the private-registry sandbox suite (evals/ramp_sandbox): 17/17
pass^2 on Sonnet 5 against the published @pipedream/ramp@0.3.0 (one eval quarantined
- a shared-demo-account state flake, not a tool defect).

- create-user-invite: 0.0.3 -> 0.0.4 (marker)
- upload-receipt:     0.0.4 -> 0.0.5 (marker)
- app package.json:   0.1.3 -> 0.2.0 (new actions; dep @pipedream/ramp ^0.1.2 -> ^0.3.0)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(ramp_sandbox): import base ramp actions via the @pipedream/ramp package

Import the base ramp actions and shared constants through the package
(`@pipedream/ramp/actions/...`, `@pipedream/ramp/common/...`) instead of relative
paths that reached into the sibling component dir — matching how the app already
imports `@pipedream/ramp`. The package has no `exports` map, so subpaths resolve
by direct file lookup; verified `pd publish` bundles them and the sandbox suite is
green (17/17 pass^2 on Sonnet 5).

issue-virtual-card 0.0.4 -> 0.0.5 (now changed by the import switch).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(ramp_sandbox): update pnpm-lock.yaml for @pipedream/ramp ^0.3.0

Regenerate the lockfile entry for the bumped @pipedream/ramp dependency so
`pnpm install --frozen-lockfile` (CI) passes. Minimal change — only the
@pipedream/ramp 0.1.2 -> 0.3.0 resolution (importer specifier/version + package
resolution + snapshot key).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(ramp_sandbox): bump sources + sharpen id-prop descriptions (PR review)

- Version bumps for the three sources (0.0.2 -> 0.0.3): they depend on the
  changed ramp_sandbox app.
- Review fixes: add the Ramp UUID format + a concrete example and the source of
  the value to the id-style props that were missing them — entityId
  (create-location); userId + directManagerId (update-user); and the id props on
  get-user, get-transaction, get-limit, terminate-limit. This syncs them with the
  base ramp descriptions.
- list-locations: the returned-record example now shows concrete id + entity_id
  alongside name (was name-only).

Not changed: the trailing period after the [See the documentation](...) link —
the merged ramp base ends the same way, so removing it only in the sandbox (and
only on some actions) would create inconsistency; better as a coordinated
convention sweep across both apps.

Suite green (affected evals 5/10/11/12/14/15/17 pass) on published @pipedream/ramp@0.3.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(ramp_sandbox): mirror ramp 0.4.0 AI-optimization changes

@pipedream/ramp merged its AI-optimization pass (0.4.0). The twins override
description + props, so those changes don't auto-propagate — mirrored here:

- Dep @pipedream/ramp ^0.3.0 -> ^0.4.0 (pulls in the flattened base + removed
  async options, which flow through the app's ...ramp.propDefinitions spread).
- issue-virtual-card: base was flattened (reloadProps/additionalProps removed),
  but the twin still overrode props with the stale dynamic block and had no
  additionalProps of its own -> would have lost limit/interval/etc. Rewrote it to
  inherit the flattened base props (spread) and re-point the 4 app-ref props at
  the sandbox app; added the x-pd-ai marker + expanded description. 0.0.5 -> 0.1.0.
- list-limits/list-transactions/list-users/list-spend-programs: corrected the
  compact-default field lists to match the real projections.
- Removed the trailing period after the doc link on all 15 twin descriptions.
- create-user-invite: expanded the terse description (purpose, required params,
  List X cross-refs, UUID example, deferred gotcha; optionality aligned to schema).
- Changed twins version-bumped; app package.json 0.2.0 -> 0.3.0.

Validated: all 18 twins publish against the 0.4.0 base; pass^2 suite 16 pass /
1 warn (eval 3 over_call_budget, environmental account-growth pagination) / 0 fail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(ramp_sandbox): match descriptions to ramp base + currency-neutral amount

Address CodeRabbit review on #21792 (match sandbox descriptions to the ramp base):
- create-department: expanded the terse description to match ramp (purpose, name
  guidance, Update User / List Transactions / List Users cross-refs).
- create-location: expanded to match ramp (purpose, name required + entityId
  optional for multi-entity businesses, List Locations discovery).
- list-locations: matched ramp's example wording ('objects like ... — pass the id
  as the location ID in downstream actions').
- update-limit: amount is now currency-neutral — 'the currency's smallest
  denomination' (not 'cents'), with USD (50000=$500.00) and JPY (500=¥500)
  examples, aligned with currencyCode's ISO 4217 behavior. NOTE: ramp still says
  'minor units (cents)'; it needs the same fix to stay in sync (follow-up).
- upload-receipt: the twin overrode filePath and dropped format: 'file-ref' (plus
  an outdated description); now inherits the base filePath/syncDir via spread,
  restoring file-ref (URL-or-/tmp-path) and matching ramp. 0.0.5 -> 0.0.6.

Validated: 5 changed actions publish clean; evals 5/13/14 (the eval-covered ones)
pass. issue-virtual-card was a false-positive diff (props inherited via spread).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(ramp_sandbox): update lockfile for @pipedream/ramp ^0.4.0

Match pnpm-lock.yaml to the manifest bump (@pipedream/ramp ^0.3.0 -> ^0.4.0).
0.4.0 is published to npm (latest) with identical deps to 0.3.0, so this is a
surgical key/integrity swap in the importer + package + snapshot entries — no
transitive changes. Fixes ERR_PNPM_OUTDATED_LOCKFILE under --frozen-lockfile.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ramp_sandbox): add explicit type + annotations to issue-virtual-card

The lint rules pipedream/required-properties-type and pipedream/action-annotations
are static — they can't see type/annotations inherited through the ...issueVirtualCard
spread, so CI errored. Added both explicitly (identical to the base values the spread
already provides; no behavior change). Lint now clean (0 errors) on components/ramp_sandbox.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(ramp_sandbox): reset component versions to PR baselines

ramp_sandbox is unmerged, so its components are new-in-PR and shouldn't carry
review-driven bumps. Reset to baselines: 15 actions -> 0.0.1, create-user-invite
-> 0.0.4, upload-receipt -> 0.0.5, app package.json -> 0.2.0. Dependency
@pipedream/ramp stays ^0.4.0 (lockfile unaffected). Descriptions/behavior unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(ramp_sandbox): document required Virtual Card Name in issue-virtual-card

Review: the description omitted displayName (Virtual Card Name), a required input,
and its example was incomplete. Added the Virtual Card Name as a required input +
in the example, and mentioned the Primary Card Enabled / Reimbursements Enabled
toggles for the custom-limit branch.

Did NOT mark primaryCardEnabled/reimbursementsEnabled as 'required': in the merged
base (0.1.0) both are optional:true and run() has no guard requiring them, so
labeling them required would misstate the schema (same mismatch as the earlier
create-user-invite dept/location finding). Description-only; version unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: vetrivigneshwaran <vicky@pipedream.com>