feat(ramp_sandbox): AI-optimized Ramp Sandbox actions for MCP (PipedreamHQ#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 PipedreamHQ#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 PipedreamHQ#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>

Author: 3 people

components/ramp_sandbox/actions/create-department/create-department.mjs

@@ -0,0 +1,27 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import createDepartment from "@pipedream/ramp/actions/create-department/create-department.mjs";
+
+export default {
+  ...createDepartment,
+  key: "ramp_sandbox-create-department",
+  name: "Create Department",
+  description: "Create a new Ramp Sandbox department (e.g. `Engineering`, `Marketing`). Use this to add an organizational unit before assigning users to it. Returns the new department's `id`, which you can pass to **Update User** to set a user's department, or use to filter **List Transactions** / **List Users**. [See the documentation](https://docs.ramp.com/developer-api/v1/api/departments#post-developer-v1-departments)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  type: "action",
+  props: {
+    ramp,
+    name: {
+      propDefinition: [
+        ramp,
+        "name",
+      ],
+      description: "The name of the new department (e.g. `Engineering`, `Marketing`).",
+    },
+  },
+};

components/ramp_sandbox/actions/create-location/create-location.mjs

@@ -0,0 +1,33 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import createLocation from "@pipedream/ramp/actions/create-location/create-location.mjs";
+
+export default {
+  ...createLocation,
+  key: "ramp_sandbox-create-location",
+  name: "Create Location",
+  description: "Create a new Ramp Sandbox location (e.g. `New York HQ`). Use this to add a site before assigning users to it; the returned `id` can be passed to **Update User** or used to filter **List Transactions** / **List Users**. Associating an entity is optional — set the Entity ID only for multi-entity businesses that scope locations to a specific legal entity. [See the documentation](https://docs.ramp.com/developer-api/v1/api/locations#post-developer-v1-locations)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  type: "action",
+  props: {
+    ramp,
+    name: {
+      propDefinition: [
+        ramp,
+        "name",
+      ],
+      description: "The name of the new location (e.g. `New York HQ`).",
+    },
+    entityId: {
+      type: "string",
+      label: "Entity ID",
+      description: "Optional entity ID (a UUID, e.g. `dff9389a-2819-468e-a220-28e059b23f8e`) to associate with the location. Obtain it from the `entity_id` field returned by **List Locations**, or from your Ramp entities in the API. Only needed for multi-entity businesses.",
+      optional: true,
+    },
+  },
+};

components/ramp_sandbox/actions/create-user-invite/create-user-invite.mjs

@@ -1,12 +1,13 @@
+// x-pd-ai: optimized
 import ramp from "../../ramp_sandbox.app.mjs";
-import createUserInvite from "../../../ramp/actions/create-user-invite/create-user-invite.mjs";
+import createUserInvite from "@pipedream/ramp/actions/create-user-invite/create-user-invite.mjs";
 
 export default {
   ...createUserInvite,
   key: "ramp_sandbox-create-user-invite",
   name: "Create User Invite",
-  description: "Sends out an invite for a new user. [See the documentation](https://docs.ramp.com/developer-api/v1/reference/rest/users#post-developer-v1-users-deferred)",
-  version: "0.0.3",
+  description: "Invite a new person to your Ramp Sandbox organization by email — use this to onboard an employee who doesn't yet have a Ramp Sandbox account. Requires their email, first and last name, and `role` (e.g. `BUSINESS_USER`); department, location, and direct manager are optional. Run **List Departments** and **List Locations** to find valid department/location IDs, and **List Users** to find a direct manager's user ID — each is a Ramp UUID, e.g. `fffe6c22-698f-4dc5-b2b1-b35f86947d90`. This is a deferred operation, so the invited user may not appear in **List Users** immediately; once they do, use **Update User** to change their role, department, location, or manager. [See the documentation](https://docs.ramp.com/developer-api/v1/reference/rest/users#post-developer-v1-users-deferred)",
+  version: "0.0.4",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/ramp_sandbox/actions/get-limit/get-limit.mjs

@@ -0,0 +1,25 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import getLimit from "@pipedream/ramp/actions/get-limit/get-limit.mjs";
+
+export default {
+  ...getLimit,
+  key: "ramp_sandbox-get-limit",
+  name: "Get Limit",
+  description: "Retrieve a single Ramp Sandbox spend limit by ID. Run the **List Limits** action first to find a valid limit ID. Example: given a limit id from **List Limits**, returns the limit's display name, state (e.g. `ACTIVE`), balance, spend program, and spending restrictions. [See the documentation](https://docs.ramp.com/developer-api/v1/api/funds)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    ramp,
+    limitId: {
+      type: "string",
+      label: "Limit ID",
+      description: "The ID of the spend limit to retrieve — a UUID, e.g. `dcd0f7a8-557d-4dc5-bb12-49297c3abfdd`. Run the **List Limits** action to find this value.",
+    },
+  },
+};

components/ramp_sandbox/actions/get-transaction/get-transaction.mjs

@@ -0,0 +1,25 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import getTransaction from "@pipedream/ramp/actions/get-transaction/get-transaction.mjs";
+
+export default {
+  ...getTransaction,
+  key: "ramp_sandbox-get-transaction",
+  name: "Get Transaction",
+  description: "Retrieve a single Ramp Sandbox transaction by ID. Run the **List Transactions** action first to find a valid transaction ID. Example: given a transaction id from **List Transactions**, returns the full transaction — e.g. merchant `Facebook Ads`, amount `$135.00`, category `Advertising`, plus line items and accounting detail. [See the documentation](https://docs.ramp.com/developer-api/v1/api/transactions#get-developer-v1-transactions-transaction-id)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    ramp,
+    transactionId: {
+      type: "string",
+      label: "Transaction ID",
+      description: "The ID of the transaction to retrieve — a UUID, e.g. `c74326d3-a6b3-4a88-9a0c-4b61850784cd`. Run the **List Transactions** action to find this value.",
+    },
+  },
+};

components/ramp_sandbox/actions/get-user/get-user.mjs

@@ -0,0 +1,25 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import getUser from "@pipedream/ramp/actions/get-user/get-user.mjs";
+
+export default {
+  ...getUser,
+  key: "ramp_sandbox-get-user",
+  name: "Get User",
+  description: "Retrieve a single Ramp Sandbox user by ID. Run the **List Users** action first to find a valid user ID. Example: given a user id from **List Users**, returns that user's full record — name, email, role (e.g. `BUSINESS_OWNER`), department id, and location id. [See the documentation](https://docs.ramp.com/developer-api/v1/api/users#get-developer-v1-users-user-id)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    ramp,
+    userId: {
+      type: "string",
+      label: "User ID",
+      description: "The ID of the user to retrieve — a UUID, e.g. `bcc1e4ca-d38a-4cc9-98fc-e6c2066ad0ae`. Run the **List Users** action to find this value.",
+    },
+  },
+};

components/ramp_sandbox/actions/issue-virtual-card/issue-virtual-card.mjs

@@ -1,57 +1,46 @@
+// x-pd-ai: optimized
 import ramp from "../../ramp_sandbox.app.mjs";
-import issueVirtualCard from "../../../ramp/actions/issue-virtual-card/issue-virtual-card.mjs";
+import issueVirtualCard from "@pipedream/ramp/actions/issue-virtual-card/issue-virtual-card.mjs";
 
 export default {
   ...issueVirtualCard,
   key: "ramp_sandbox-issue-virtual-card",
   name: "Issue Virtual Card",
-  description: "Creates a new virtual card for a given user. [See the documentation](https://docs.ramp.com/developer-api/v1/reference/rest/limits#post-developer-v1-limits-deferred)",
-  version: "0.0.4",
+  description: "Issue a new Ramp Sandbox virtual card (spend limit) for a user. Requires a **Virtual Card Name** and the user's ID (run **List Users** to find it). Works two ways: (1) **link to an existing spend program** — set **Link to Existing Spend Program** on and pass a **Spend Program ID** (run **List Spend Programs**), and the program governs the card's restrictions; or (2) **set a custom limit** — leave linking off and pass a **Total Limit per Interval** (e.g. `$500`) and an **Interval** (e.g. `MONTHLY`), optionally a per-transaction cap, allowed/blocked categories, and whether the physical card (**Primary Card Enabled**) and **Reimbursements Enabled** apply. Example: issue a $500/month card by passing a Virtual Card Name (e.g. `Marketing SaaS`), the user's ID, `$500`, and `MONTHLY`. [See the documentation](https://docs.ramp.com/developer-api/v1/reference/rest/limits#post-developer-v1-limits-deferred)",
+  version: "0.1.0",
+  type: "action",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: false,
   },
-  type: "action",
   props: {
+    ...issueVirtualCard.props,
     ramp,
-    displayName: {
-      type: "string",
-      label: "Virtual Card Name",
-      description: "The name of the virtual card",
-    },
     userId: {
       propDefinition: [
         ramp,
         "userId",
       ],
     },
-    linkToSpendProgram: {
-      type: "boolean",
-      label: "Link to Existing Spend Program",
-      description: "Whether to link the card to an existing spend program",
-      reloadProps: true,
-    },
     spendProgramId: {
       propDefinition: [
         ramp,
         "spendProgramId",
       ],
-      hidden: true,
+      description: "The spend program to link the card to — a Ramp UUID, e.g. `e9d30f12-c73a-463b-bc5f-b200396359d2`. Run the **List Spend Programs** action to find valid IDs. Required when **Link to Existing Spend Program** is on; leave empty to set a custom limit.",
     },
     allowedCategories: {
       propDefinition: [
         ramp,
         "allowedCategories",
       ],
-      hidden: true,
     },
     blockedCategories: {
       propDefinition: [
         ramp,
         "blockedCategories",
       ],
-      hidden: true,
     },
   },
 };

components/ramp_sandbox/actions/list-departments/list-departments.mjs

@@ -0,0 +1,32 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import listDepartments from "@pipedream/ramp/actions/list-departments/list-departments.mjs";
+
+export default {
+  ...listDepartments,
+  key: "ramp_sandbox-list-departments",
+  name: "List Departments",
+  description: "Retrieve a list of Ramp Sandbox departments. Use this to find department IDs for other actions such as **Update User** and **List Transactions**. Example: returns `{ id, name }` pairs such as `{ \"id\": \"fffe6c22-698f-4dc5-b2b1-b35f86947d90\", \"name\": \"Engineering\" }` — pass the `id` to **Update User** to set a user's department. Returns one page of up to `pageSize` results (max 100); a `page.next` value in the response means more departments exist beyond this page. [See the documentation](https://docs.ramp.com/developer-api/v1/api/departments#get-developer-v1-departments)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    ramp,
+    pageSize: {
+      propDefinition: [
+        ramp,
+        "pageSize",
+      ],
+    },
+    start: {
+      propDefinition: [
+        ramp,
+        "start",
+      ],
+    },
+  },
+};

components/ramp_sandbox/actions/list-limits/list-limits.mjs

@@ -0,0 +1,39 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import listLimits from "@pipedream/ramp/actions/list-limits/list-limits.mjs";
+
+export default {
+  ...listLimits,
+  key: "ramp_sandbox-list-limits",
+  name: "List Limits",
+  description: "Retrieve a paginated list of Ramp Sandbox spend limits. Returns a compact summary of each limit by default (id, display_name, state, balance, spend_program_id, created_at, is_shareable); use **Get Limit** for the full record, or pass `fields` to include specific extra fields. Use this to find limit IDs for **Get Limit**, **Update Limit**, and **Terminate Limit**. Returns one page of up to `pageSize` results (max 100); a `page.next` value in the response means more limits exist beyond this page. [See the documentation](https://docs.ramp.com/developer-api/v1/api/funds)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    ramp,
+    pageSize: {
+      propDefinition: [
+        ramp,
+        "pageSize",
+      ],
+    },
+    start: {
+      propDefinition: [
+        ramp,
+        "start",
+      ],
+    },
+    fields: {
+      propDefinition: [
+        ramp,
+        "fields",
+      ],
+      description: "Optional list of limit fields to include per record in addition to the compact default (e.g. `cards`, `members`, `spending_restrictions`, `permitted_spend_types`). Leave empty for the compact summary; use **Get Limit** for the complete record.",
+    },
+  },
+};

components/ramp_sandbox/actions/list-locations/list-locations.mjs

@@ -0,0 +1,32 @@
+// x-pd-ai: optimized
+import ramp from "../../ramp_sandbox.app.mjs";
+import listLocations from "@pipedream/ramp/actions/list-locations/list-locations.mjs";
+
+export default {
+  ...listLocations,
+  key: "ramp_sandbox-list-locations",
+  name: "List Locations",
+  description: "Retrieve a list of Ramp Sandbox locations. Use this to find location IDs for other actions such as **Update User** and **List Transactions**. Example: returns objects like `{ \"id\": \"961c6f01-5719-4f4c-8fef-4096a031f32a\", \"name\": \"New York HQ\", \"entity_id\": \"c0e5f8a2-9b1d-4e3a-8f6c-2d7b4a1e9f30\" }` — pass the `id` as the location ID in downstream actions. Returns one page of up to `pageSize` results (max 100); a `page.next` value in the response means more locations exist beyond this page. [See the documentation](https://docs.ramp.com/developer-api/v1/api/locations#get-developer-v1-locations)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    ramp,
+    pageSize: {
+      propDefinition: [
+        ramp,
+        "pageSize",
+      ],
+    },
+    start: {
+      propDefinition: [
+        ramp,
+        "start",
+      ],
+    },
+  },
+};