kya_reportBadgePresented

Report badge presentation to a merchant for transaction recording in the kyaLabs system. Use after merging checkoutPatch into checkout payload to track shopping sessions.

Instructions

Report that you presented your Badge to a merchant. Call this immediately after merging the checkoutPatch into a checkout payload. Required for kyaLabs to record the trip.

When Extended Auth is enabled, kyaLabs checks back 7 seconds later. Otherwise, call kya_reportBadgeOutcome when you know the result.

Input Schema

TableJSON Schema

Name	Required	Description
`verification_token`	Yes	The verification_token returned by kya_getAgentIdentity
`merchant`	No	The merchant name (e.g., 'starbucks.com'). Provide merchantUrl or merchant.
`merchantUrl`	No	The merchant base URL (e.g., 'https://starbucks.com'). Preferred over merchant.
`context`	No	Optional: in what state you presented (arrival, addtocart, checkout, other)
`checkoutSessionId`	No	UCP checkout session ID if available
`trip_id`	No	Trip ID from kya_getAgentIdentity — links events in this shopping session

Implementation Reference

src/lib/report-badge-presented-handler.ts:16-46 (handler)

The handler function for kya_reportBadgePresented that logs the badge presentation.

export async function handleReportBadgePresented(
  verification_token: string,
  merchant: string,
  context?: "arrival" | "addtocart" | "checkout" | "other",
  checkoutSessionId?: string,
  tripId?: string
): Promise<{ content: Array<{ type: "text"; text: string }> }> {
  onIdentityPresented(verification_token, merchant, tripId);
  await reportBadgePresented(verification_token, merchant, context, checkoutSessionId, tripId);
  return {
    content: [
      {
        type: "text",
        text: JSON.stringify({ recorded: true }),
      },
      {
        type: "text",
        text: [
          `✓ Badge presentation logged at ${merchant}`,
          ``,
          `  Token:    ${verification_token.slice(0, 10)}**`,
          `  Merchant: ${merchant}`,
          `  Status:   Tracking — outcome will be recorded`,
          ``,
          `Now include your badge token in the Authorization header:`,
          `  Authorization: Bearer ${verification_token}`,
        ].join("\n"),
      },
    ],
  };
}

src/index.ts:66-103 (registration)

MCP tool registration for kya_reportBadgePresented in src/index.ts.

server.tool(
  "kya_reportBadgePresented",
  `Report that you presented your Badge to a merchant. Call this immediately after merging the checkoutPatch into a checkout payload. Required for kyaLabs to record the trip.

When Extended Auth is enabled, kyaLabs checks back 7 seconds later. Otherwise, call kya_reportBadgeOutcome when you know the result.`,
  {
    verification_token: z.string().describe(
      "The verification_token returned by kya_getAgentIdentity"
    ),
    merchant: z.string().max(200).optional().describe(
      "The merchant name (e.g., 'starbucks.com'). Provide merchantUrl or merchant."
    ),
    merchantUrl: z.string().max(500).optional().describe(
      "The merchant base URL (e.g., 'https://starbucks.com'). Preferred over merchant."
    ),
    context: z
      .enum(["arrival", "addtocart", "checkout", "other"])
      .optional()
      .describe(
        "Optional: in what state you presented (arrival, addtocart, checkout, other)"
      ),
    checkoutSessionId: z.string().optional().describe(
      "UCP checkout session ID if available"
    ),
    trip_id: z.string().uuid().optional().describe(
      "Trip ID from kya_getAgentIdentity — links events in this shopping session"
    ),
  },
  async ({ verification_token, merchant, merchantUrl, context, checkoutSessionId, trip_id }) => {
    const resolvedMerchant = merchantUrl || merchant;
    if (!resolvedMerchant) {
      return {
        content: [{ type: "text" as const, text: "✗ Error: merchantUrl or merchant is required." }],
      };
    }
    return handleReportBadgePresented(verification_token, resolvedMerchant, context, checkoutSessionId, trip_id);
  }
);

payclaw-mcp