Propose an action

export BOTSHIELD_AGENT_KEY="bs_agent_MeridianConcierge__…"

import { BotShield } from "botshield-sdk";

const client = new BotShield({
  // Required: the package does not default to the production API.
  serverURL: "https://api.botshield.ai/operations",
  security: {
    // Sent verbatim as the Authorization header, so include "Bearer ".
    agentKeyAuth: `Bearer ${process.env.BOTSHIELD_AGENT_KEY}`,
  },
});

curl -X POST https://api.botshield.ai/operations/agentlink/inquire \
  -H "Authorization: Bearer $BOTSHIELD_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "3f1b2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "opaque_id": "OP_QDhs65484684",
    "action": {
      "summary_title": "Refund booking MA-48213 to your Visa ending 4242",
      "summary_detail": { "label": "TOTAL", "value": "$168.45" },
      "category": "travel.refund"
    },
    "ttl_seconds": 600
  }'

import { randomUUID } from "node:crypto";

const requestId = randomUUID(); // persist this with your pending refund

const result = await client.actions.proposeAction({
  requestId,
  opaqueId: "OP_QDhs65484684",
  action: {
    summaryTitle: "Refund booking MA-48213 to your Visa ending 4242",
    summaryDetail: { label: "TOTAL", value: "$168.45" },
    category: "travel.refund",
  },
  ttlSeconds: 600,
});

if (result.data.error) {
  throw new Error(`${result.data.error.statusCode}: ${result.data.error.message}`);
}
const { cardId, ttlAt } = result.data.data!;

{
  "data": {
    "error": {
      "message": "Action category \"payment.authorize\" is not in agent's allowed_action_categories.",
      "statusCode": 403
    }
  }
}

{
  "data": {
    "error": {
      "message": "TRUST Layer rejected the Adaptive Card payload.",
      "statusCode": 422,
      "violations": [
        { "type": "unknown_element_type", "path": "$.body[1]", "severity": "block" },
        { "type": "embedded_url", "path": "$.body[0].facts[2].value", "severity": "block" }
      ]
    }
  }
}

{
  "data": {
    "error": {
      "message": "ttl_seconds (30) is below the floor (60). Below the floor defeats the architectural purpose — the user has not had a real chance to engage.",
      "statusCode": 400,
      "code": "ttl_below_floor",
      "min_ttl_seconds": 60
    }
  }
}

curl --max-time 35 \
  "https://api.botshield.ai/operations/agentlink/check-status?request_id=3f1b2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e&wait_seconds=25" \
  -H "Authorization: Bearer $BOTSHIELD_AGENT_KEY"

async function waitForDecision(requestId: string) {
  for (;;) {
    const result = await client.actions.checkActionStatus(
      { requestId, waitSeconds: 25 },
      { timeoutMs: 35_000 }, // must be longer than waitSeconds
    );
    if (result.data.error) throw new Error(result.data.error.message);

    const state = result.data.data!;
    if (state.status !== "queued") return state; // approved | denied | expired | cancelled
  }
}

const state = await waitForDecision(requestId);
if (state.status === "approved" && state.resolutionJwt) {
  // Verify the proof before you execute. See Proof of Resolution.
}

curl -X POST https://api.botshield.ai/operations/agentlink/cancel \
  -H "Authorization: Bearer $BOTSHIELD_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "3f1b2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "reason": "Customer rebooked instead"
  }'

const result = await client.actions.cancelAction({
  requestId,
  reason: "Customer rebooked instead",
});

if (result.data.error) throw new Error(result.data.error.message);
if (result.data.data!.alreadyResolved) {
  // Too late to cancel: the card is already approved, denied, expired, or cancelled.
}

{
  "data": {
    "data": {
      "status": "cancelled",
      "card_id": "0b9d6c0e-7a57-4c55-9a53-0a1f4c1d2e3f",
      "cancelled_at": "2026-09-21T17:44:02.118Z"
    }
  }
}

{
  "data": {
    "data": {
      "status": "approved",
      "card_id": "0b9d6c0e-7a57-4c55-9a53-0a1f4c1d2e3f",
      "already_resolved": true
    }
  }
}