Confirm a step with a tap

import { randomUUID } from "node:crypto";
import { EndstateClient, secretKey } from "@endstate-sdk/core";
import { isEndstateApiError } from "@endstate-sdk/core/errors";

const endstate = new EndstateClient({
  apiKey: secretKey(process.env.ENDSTATE_API_KEY),
});

export async function openListingConfirm(unitId: string, listingId: string) {
  const intent = await endstate.tapIntents.create({
    rule: "own",
    unitId,
    action: { type: "listing.confirm", reference: listingId },
    useWithin: 300,
    redirectUrl: `https://app.example.com/listings/${listingId}/confirm`,
    display: { title: "Confirm your listing" },
  });
  await db.listings.setTapIntent(listingId, intent.id);
  return { tapIntentId: intent.id, tapCode: intent.tapCode };
}

export async function waitForApproval(tapIntentId: string) {
  let current = await endstate.tapIntents.get(tapIntentId);
  while (current.status === "pending") {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    current = await endstate.tapIntents.get(tapIntentId);
  }
  return current;
}

export async function consumeAndPublish(tapIntentId: string) {
  const listing = await db.listings.findByTapIntent(tapIntentId);
  if (!listing) return;

  // The unique insert decides which handler acts. A loser stops here.
  const claim = await db.tapIntentClaims.insertIfAbsent({
    tapIntentId,
    idempotencyKey: randomUUID(),
  });
  if (!claim) return;

  await finishClaim(claim, listing.id);
}

// The refusals that can never turn into a success for this claim.
const FINAL_REFUSALS = new Set([
  "tap_intent.already_consumed",
  "tap_intent.action_mismatch",
  "tap_intent.canceled",
  "tap_intent.expired",
  "tap_intent.not_found",
]);

// Also run this for claims left unfinished by a crash or an error, with the stored key.
export async function finishClaim(
  claim: { tapIntentId: string; idempotencyKey: string },
  listingId: string,
) {
  try {
    await endstate.tapIntents.consume(
      claim.tapIntentId,
      { action: { type: "listing.confirm", reference: listingId } },
      { idempotencyKey: claim.idempotencyKey },
    );
  } catch (error) {
    // Anything else may have consumed, or may still succeed: keep the claim and retry with its key.
    if (!isEndstateApiError(error) || !FINAL_REFUSALS.has(error.code)) {
      throw error;
    }
    // Expired, canceled or consumed by a request that is not this claim: do not act.
    await db.tapIntentClaims.markRefused(claim.tapIntentId, error.code);
    return;
  }
  await publishListing(listingId);
  await db.tapIntentClaims.markDone(claim.tapIntentId);
}

{
  "id": "tapi_3f9c1b7a2d4e4f60a1b2c3d4e5f60718",
  "status": "approved",
  "redirect_url": "https://app.example.com/listings/8271/confirm?tap_intent=tapi_3f9c1b7a2d4e4f60a1b2c3d4e5f60718"
}

import { isEndstateApiError } from "@endstate-sdk/core/errors";

async function openTapIntentIds(unitId: string, listingId: string) {
  try {
    await endstate.tapIntents.create({
      rule: "own",
      unitId,
      action: { type: "listing.confirm", reference: listingId },
    });
    return [];
  } catch (error) {
    if (!isEndstateApiError(error)) throw error;
    if (error.code !== "tap_intent.too_many_open") throw error;

    const details = error.response.error.details as
      | { tap_intent_ids?: string[] }
      | undefined;
    return details?.tap_intent_ids ?? [];
  }
}

{
  "tap_intents": [
    {
      "id": "tapi_3f9c1b7a2d4e4f60a1b2c3d4e5f60718",
      "status": "approved",
      "rule": "own",
      "unit_id": "6f1d2c3b-4a59-4e68-9f70-8a1b2c3d4e5f",
      "action": { "type": "listing.confirm", "reference": "listing_8271" },
      "redirect_url": "https://app.example.com/listings/8271/confirm",
      "display": { "title": "Confirm your listing" },
      "code_required": true,
      "scan": {
        "id": "0b8e6a54-93c2-4d17-8f5e-2a1b3c4d5e6f",
        "scanned_at": "2026-11-10T17:03:40.000Z"
      },
      "created_at": "2026-11-10T17:02:11.000Z",
      "expires_at": "2026-11-10T17:07:11.000Z",
      "approved_at": "2026-11-10T17:04:02.000Z",
      "use_by": "2026-11-10T17:09:02.000Z",
      "consumed_at": null,
      "canceled_at": null
    }
  ]
}

import type { components } from "@endstate-sdk/core/types";
import { parseWebhook, verifyWebhook } from "@endstate-sdk/core/webhooks";

type TapIntentData = components["schemas"]["TapIntent"];

export async function POST(request: Request) {
  const rawBody = await request.text();
  const { id } = await verifyWebhook(
    rawBody,
    request.headers,
    process.env.WEBHOOK_SECRET!,
  );
  if (await alreadyHandled(id)) return new Response(null, { status: 200 });

  const event = parseWebhook<TapIntentData>(rawBody);
  if (event.type === "tap_intent.approved") {
    await consumeAndPublish(event.data.id);
  }
  if (event.type === "tap_intent.canceled") {
    await releaseListing(event.data.action.reference);
  }
  return new Response(null, { status: 200 });
}