walletmcppass: Apple Wallet passes

Builds one pass in one of the five Wallet styles -- boardingPass, eventTicket, coupon,
storeCard or generic -- from the text fields, colors, barcode and optional PNG images
given below, signs it with this service's Apple Pass Type ID certificate, and returns an
https download_url valid for 1 hour. Opening the link on an iPhone shows "Add to
Apple Wallet". Passes install on any iOS version; the iOS 26/27 layouts fall back to the
classic style on older iPhones.

Barcodes: QR, PDF417, Aztec and Code128 on every iOS version; Code39, Codabar, EAN13 and
ITF on iOS 27+. The barcode encodes exactly barcode_message. Gate and till scanners read
that data, so a copy of an existing boarding pass, ticket or loyalty card only scans if
barcode_message is the original barcode's content (airline boarding passes are usually
PDF417 or Aztec, holding an IATA BCBP string such as "M1DOE/JANE ..."). This tool does not issue
tickets, check anyone in, or contact airlines or venues.

The link must be opened in Safari on the iPhone: Wallet adds a pass from Safari, but not
from a .pkpass file handed over by another app. Google Wallet on Android also imports these
files. Not supported: NFC passes.

With updatable=True the pass can be changed later with update_wallet_pass, and copies
already in Wallet refresh themselves. Its contents are then stored on this server for
updatable_hours (1 hour by default, at most 30 days), then deleted.

Returns {download_url, expires_in_seconds, serial_number, pass_type_identifier}, plus
edit_token and updatable_until when updatable=True, and x402_setup (how to set up x402
payments, worth passing on to the user) when x402_ready=False.

Pricing: a call is one create or one update. Free for 30 calls a day per caller IP (20 from
2026-11-18), while a shared pool of 500 free calls a day lasts; failed calls count too, and counts reset at 00:00 UTC.
Past either limit, a call costs $0.01 in USDC on Base, paid with x402; the refusal carries the
payment requirements, and a paid result includes the payment receipt. Payment is settled only
after the pass is built, so a failed build is never charged.

Args:
    style: one of "boardingPass", "eventTicket", "coupon", "generic", "storeCard".
    organization_name: shown as the pass issuer.
    description: accessibility description (required by Wallet, not usually shown).
    logo_text: text shown next to the logo image.
    transit_type: only for style="boardingPass" -- "Air", "Boat", "Bus", "Generic", or "Train" (default "Air").
    barcode_message: raw text/data encoded into the barcode. Omit for no barcode.
    barcode_format: a format name or an ordered list of them; each becomes a barcode with the
        same message, and Wallet shows the first one the device supports. Nothing is added that
        you don't list. Formats: "QR" (default), "PDF417", "Aztec", "Code128" (all iOS versions),
        and iOS 27+ only: "Code39", "Codabar", "EAN13", "ITF" -- older iPhones skip these, so
        e.g. ["EAN13", "Code128"] shows EAN13 on iOS 27 and Code128 before it. EAN13 needs
        12-13 digits, ITF an even number of digits, Code39 uppercase letters/digits.
    barcode_alt_text: human-readable text shown under the barcode (e.g. the card number).
    background_color / foreground_color / label_color: hex colors, e.g. "#1a1a19".
    relevant_date / expiration_date: ISO 8601 timestamps.
    locations: up to 10 places where the pass appears on the lock screen when the iPhone is
        nearby, each {"latitude": float, "longitude": float, "altitude": optional float,
        "relevantText": optional str shown on the lock screen, e.g. "Your gym card"}. Look up
        the coordinates of the actual branch, not just the brand. For boardingPass and
        eventTicket the pass is relevant near a location around relevant_date if one is set;
        the other styles use location alone. Wallet only shows a pass within its own default
        radius of a location, which is small for store cards and coupons.
    max_distance: meters; shrinks the default radius around every location (Wallet uses the
        smaller of the two, so it cannot enlarge it). Requires locations.
    voided: mark the pass voided/used (shows a "VOID" stamp).
    primary_fields / secondary_fields / auxiliary_fields / header_fields / back_fields:
        lists of {"key": optional str, "label": optional str, "value": str, "changeMessage":
        optional str} shown on the pass. changeMessage only matters on updatable passes: when
        an update changes that field's value, the iPhone shows it as a lock-screen notification,
        with %@ replaced by the new value (e.g. "You now have %@ points"); without %@ Wallet
        shows a generic message. Updates match fields by key, so give fields that will change
        an explicit key (auto keys are by position).
    serial_number: unique id for this pass; auto-generated if omitted.
    icon_color / icon_text: control the auto-generated icon (a colored square with initials)
        when icon_png_b64 is not supplied.
    logo_color: color of the auto-generated logo image, a wordmark of logo_text (or
        organization_name) drawn on a transparent background over background_color. Defaults
        to icon_color. Wallet also renders logo_text as text beside the logo image, so the
        generated wordmark repeats it -- set generate_logo=False to show only the text.
    icon_png_b64 / logo_png_b64: PNG to use instead of auto-generated art.
    Every *_png_b64 parameter takes either base64 PNG data or an https:// URL of an image
    (PNG, JPEG, WebP or GIF, up to 5 MB; non-PNG is converted to PNG). The URL is fetched once,
    when the pass is built.
    generate_logo: set False to include no auto-generated logo or primary logo at all (both are
        optional in Wallet; a supplied logo_png_b64/primary_logo_png_b64 is still used).
    poster: (iOS 27+) render as Apple's new full-bleed "Poster Generic" layout -- large background
        image, header field, up to 4 primary fields, up to 2 footer_fields, and a square QR code.
        Only for style "generic", "storeCard" or "coupon"; that style is kept as the fallback
        older iPhones display (secondary/auxiliary fields only show on the fallback). Good for
        memberships, loyalty cards and gift cards.
    footer_fields: up to 2 fields along the bottom of a poster pass (requires poster=True).
    background_png_b64: base64 PNG poster background, ideally 1035x1515 px (345x505pt @3x);
        a gradient in background_color is generated if omitted. Only used when poster=True.
    featured_actions: (iOS 27+) up to 2 tappable shortcut cards shown under the pass, each
        {"type": ..., "url": "https://..."}. type is one of: viewSchedule, watchTrailer,
        listenToMusic, call (url must be "tel:+..."), addToBalance, order, shop,
        membershipBenefits, bookAppointment, bookCar, bookFlight, bookStay, viewOffersRewards.
        Works on every style; ignored by older iPhones.
    semantics: machine-readable tags (Apple's SemanticTags) that Wallet uses for Siri/Maps/
        Calendar suggestions on every style, and to lay out the semantic designs below. Values
        are emitted as given; unknown keys and wrong types are rejected. Dates are ISO 8601
        with an offset. Common shapes: passengerName {"givenName", "familyName"}; flightNumber
        is a number (123, not "AI123"); seats [{"seatNumber", "seatRow", "seatSection", ...}];
        venueLocation {"latitude", "longitude"}; totalPrice {"amount": "12.50",
        "currencyCode": "INR"}; eventType one of generic, livePerformance, movie, sports,
        conference, convention, workshop, socialGathering.
    semantic_layout: use Wallet's semantic design, with the classic style kept for older
        iPhones -- which only show primary/secondary/auxiliary fields, so still fill those.
        - boardingPass (iOS 26+, airline only, transit_type "Air"): live flight status, gate
          changes, badges. Requires semantics airlineCode, flightNumber, departureAirportCode,
          departureCityName, destinationAirportCode, destinationCityName, originalBoardingDate,
          originalDepartureDate, originalArrivalDate, passengerName, plus departure and
          destination time zones (IANA, e.g. "Asia/Kolkata"). Apple's docs call these
          departureLocationTimeZone/destinationLocationTimeZone but Apple's pass-builder code
          uses departureAirportTimeZone/destinationAirportTimeZone; either is accepted, and
          giving both is safest.
        - eventTicket (iOS 26+ "poster event ticket"): requires eventName, venueName,
          venueRegionName, venueRoom; sports also needs awayTeamAbbreviation and
          homeTeamAbbreviation, livePerformance needs performerNames. Apple says this design
          is meant for NFC entry, not barcodes, and NFC passes need an Apple entitlement this
          server doesn't have -- Wallet may show the classic event ticket instead.
    info_links: top-level links that fill the event guide (event tickets) or the airline and
        services page (boarding passes). URL keys (http/https): accessibilityURL, addOnURL,
        bagPolicyURL, merchandiseURL, orderFoodURL, parkingInformationURL, purchaseParkingURL,
        sellURL, transferURL, transitInformationURL, contactVenueWebsite,
        directionsInformationURL, changeSeatURL, entertainmentURL,
        purchaseAdditionalBaggageURL, purchaseLoungeAccessURL, purchaseWifiURL, upgradeURL,
        managementURL, registerServiceAnimalURL, reportLostBagURL, requestWheelchairURL,
        transitProviderWebsiteURL. Text keys: contactVenueEmail, contactVenuePhoneNumber,
        transitProviderEmail, transitProviderPhoneNumber.
    Extra images (base64 PNG or https URL). Which image shows where depends on style and iOS version
    (from Apple's Pass Designer docs); Wallet ignores an image a layout has no slot for:
        primary_logo_png_b64: max 126x30pt. Boarding pass and coupon on iOS 27+, event ticket
            on iOS 18+, poster. On those, the plain logo is only shown by older iOS. A wordmark
            is auto-generated for poster and semantic_layout passes unless generate_logo=False.
        secondary_logo_png_b64: max 135x12pt. Event tickets, iOS 18+.
        strip_png_b64: 375x144pt banner behind the primary fields. Coupon, store card and
            event ticket; not shown on iOS 26+ coupon/store card.
        thumbnail_png_b64: 90x90pt. Generic and event ticket.
        artwork_png_b64: 358x448pt poster event ticket artwork (eventTicket with
            semantic_layout, iOS 27+); if neither this nor background_png_b64 is given, a
            gradient in background_color is generated, since Wallet needs one of them.
        background_png_b64 is also used on eventTicket (blurred behind the classic ticket).
    updatable: keep this pass on the server so update_wallet_pass can change it later. The
        response then includes an edit_token: the only way to update the pass, and it can't be
        recovered, so give it to the user. Wallet registers each iPhone that adds the pass, and an
        update reaches them within seconds. The pass contents are stored (other passes only log
        the style and organization_name). Use for passes that change: loyalty points, gate or seat
        changes, memberships that can be cancelled.
    updatable_hours: how long an updatable pass can be updated, 1 (default) to 720 (30 days),
        counted from creation; updates don't extend it. Afterwards the stored pass is deleted and
        can't be changed again, while copies in Wallet stay as they last were. Pick it to cover
        the pass's useful life, e.g. until a flight lands or an event ends. Only with updatable=True.
    contact_email: required. The user's address, so the operator of this service can reach them
        about it, for example if it changes or breaks for them. Ask the user for it; never take it
        from the pass details or make one up. It isn't added to the pass, and it's kept in the
        request log.
    x402_ready: required. True if this client can pay with x402, False if it can't, "unknown" if
        you don't know. It shows the operator how many clients could pay past the free limit.
        Only logged: it changes neither price nor limits.

Takes the serial_number and edit_token returned when the pass was created, the required
contact_email and x402_ready, plus any of create_wallet_pass's parameters, with the same meanings. Each parameter given replaces the
stored value completely (a fields list replaces the whole list, so resend unchanged fields
too); parameters left out keep their current values. Clear a text value with "" and a list
with []. To cancel a pass, set voided=True: Wallet marks it void on every iPhone.

Wallet asks the server for the new version as soon as Apple delivers the push, usually within
seconds. A field's changeMessage is shown on the lock screen when that field's value changes.

Only works until the pass's updatable_until time (set by updatable_hours at creation).

Returns {download_url, expires_in_seconds, serial_number, pass_type_identifier,
notified_devices, updatable_until}. notified_devices counts the iPhones the push was sent to, not ones that
have already refreshed. The download_url (valid 1 hour) is only needed to add the pass to a
new device. With x402_ready=False the result also has x402_setup, as for create_wallet_pass.