payclaw-mcp

Instructions

Implementation Reference

• src/lib/report-badge.ts:84-148 (handler)

  The handler implementation of reportBadgeNotPresented.

  export async function reportBadgeNotPresented(
    verificationToken: string,
    merchant: string,
    reason: "abandoned" | "merchant_didnt_ask" | "other",
    tripId?: string
  ): Promise<void> {
    const apiUrl = getEnvApiUrl() || DEFAULT_API_URL;
    const key = getStoredConsentKey();
    const installId = getOrCreateInstallId();
  
    try {
      if (key) {
        // Enriched payload: full auth, user-linked, includes install_id
        const res = await fetch(`${apiUrl}/api/badge/report`, {
          method: "POST",
          headers: {
            Authorization: `Bearer ${key}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            verification_token: verificationToken,
            event_type: "badge_not_presented",
            merchant,
            reason,
            install_id: installId,
            ...(tripId && { trip_id: tripId }),
          }),
        });
        if (!res.ok) {
          const body = await res.text().catch(() => "");
          process.stderr.write(
            `[BADGE] reportBadgeNotPresented failed (${res.status}): ${body}\n`
          );
        }
      } else {
        // Anonymous payload: no auth header, install_id only
        const res = await fetch(`${apiUrl}/api/badge/report`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            install_id: installId,
            badge_version: BADGE_VERSION,
            event_type: "badge_not_presented",
            merchant,
            reason,
            agent_type: AGENT_TYPE,
            agent_model: getAgentModel(),
            timestamp: Date.now(),
            ...(tripId && { trip_id: tripId }),
          }),
        });
        if (!res.ok) {
          const body = await res.text().catch(() => "");
          process.stderr.write(
            `[BADGE] anonymous reportBadgeNotPresented failed (${res.status}): ${body}\n`
          );
        }
      }
    } catch (err) {
      // [EC-1] Fire-and-forget but never silent
      process.stderr.write(
        `[BADGE] reportBadgeNotPresented error: ${err instanceof Error ? err.message : err}\n`
      );
    }
  }

• src/index.ts:137-165 (registration)

  The tool registration of kya_reportBadgeNotPresented.

  server.tool(
    "kya_reportBadgeNotPresented",
    `Report that you did NOT present your Badge at a merchant.
  
  Call this when you have a badge but chose not to present it (e.g., abandoned cart, merchant didn't ask).`,
    {
      verification_token: z.string().describe(
        "The verification_token from kya_getAgentIdentity"
      ),
      merchant: z.string().max(200).describe(
        "The merchant where you did not present (e.g., 'starbucks.com')"
      ),
      reason: z
        .enum(["abandoned", "merchant_didnt_ask", "other"])
        .describe("Why you did not present: abandoned, merchant_didnt_ask, other"),
      trip_id: z.string().uuid().optional().describe(
        "Trip ID from kya_getAgentIdentity — links events in this shopping session"
      ),
    },
    async ({ verification_token, merchant, reason, trip_id }) => {
      await reportBadgeNotPresented(verification_token, merchant, reason, trip_id);
      return {
        content: [{
          type: "text",
          text: `✓ Not presented recorded at ${merchant} (${reason})`,
        }],
      };
    }
  );