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 | Default |
|---|---|---|---|
| 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
- 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); } );