Add affiliate attribution to an iOS subscription app

// Swift Package Manager repository URL:
// https://github.com/legitimate-apps/AttribloomKit.git
// Required API: KeychainTokenStore(accountID:) and persisted binding().
// Resolve referrals only after explicit user action and applicable permission.
// See the complete account-scoped examples below.

Implement Attribloom affiliate attribution in this iOS subscription app.

Use https://attribloom.com/agents/ios-affiliate-attribution.md as the source of truth.

Requirements:
1. Do not use device fingerprinting, IDFA, clipboard matching, or a web checkout pixel.
2. After explicit referral input and applicable permission, POST signedClickId or refCode to /v1/app-store/bind and persist the returned appAccountToken in the current app account’s Keychain store.
3. When permission allows, attach the current account’s cached token with Product.PurchaseOption.appAccountToken(token). Never generate a replacement UUID. Never wait for attribution network requests before purchase or reuse another account’s token. Missing evidence must not block purchases, restores or entitlements.
4. Add a server endpoint that forwards Apple's raw signedPayload from App Store Server Notifications v2 to Attribloom's surface-specific ASSN endpoint, signing the exact JSON request bytes with the forwarding secret.
5. Preserve raw bytes and make retries idempotent; do not parse/re-encode Apple's signed JWS before forwarding.
6. Keep all Attribloom secrets server-side. Do not put a forwarding secret in the iOS app.
7. Add tests for token persistence, token reuse across purchases, referral-input errors, and the server forwarder's signature/body invariants.
8. Stop before dashboard/account/campaign/payout operations; list the human setup values I must obtain from Attribloom.

affiliate link / referral code
  -> explicit referral action after applicable permission
  -> POST /v1/app-store/bind            (Attribloom mints the appAccountToken)
  -> persist appAccountToken UUID       (per attributed app account)
  -> StoreKit 2 PurchaseOption.appAccountToken(uuid)
  -> Apple App Store Server Notifications v2
  -> your server receives Apple's raw signedPayload
  -> signed forward to POST /v1/app-store/assn/{surfaceId}
  -> Attribloom verifies Apple's JWS and credits or reverses commission

import AttribloomKit

// Use your app's opaque account key, never an email address. Create a new facade
// when accounts change; do not copy another account's token into this account.
func makeAttribution(for appAccountID: String) -> Attribloom {
    Attribloom(store: KeychainTokenStore(accountID: appAccountID))
}

// Call from an explicit referral-code or user-initiated paste/link action,
// after the permission checks required by your actual integration.
func acceptReferral(
    attribution: Attribloom,
    signedClickId: String? = nil,
    refCode: String? = nil,
    attributionPermitted: Bool
) async -> BindResult? {
    guard attributionPermitted else { return nil }
    do {
        _ = try await attribution.resolveToken(signedClickId: signedClickId, refCode: refCode)
        return try await attribution.binding() // includes a saved optional offer code
    } catch {
        // Offer a referral retry. Keep purchases and entitlement restoration available.
        return nil
    }
}

import AttribloomKit
import StoreKit

// No attribution network request occurs on the purchase path. Pass the facade
// for the current app account. Denied/withdrawn permission means no token option.
func purchaseWithAttribution(
    product: Product,
    attribution: Attribloom,
    attributionPermitted: Bool
) async throws -> Product.PurchaseResult {
    let token = attributionPermitted ? (try? await attribution.appAccountToken()) : nil
    let options: Set<Product.PurchaseOption> = token.map { [.attribloom($0)] } ?? []
    // Handle verification, entitlement delivery and transaction.finish() in your
    // existing purchase-result handler, for both attributed and ordinary purchases.
    return try await product.purchase(options: options)
}

import crypto from "node:crypto";

// Forward EVERY App Store Server Notification v2 your server receives to Attribloom,
// off your critical path (a delivery failure must never affect your own unlock logic).
const SURFACE_ID = process.env.ATTRIBLOOM_SURFACE_ID;        // last path segment of your Forwarding URL
const SECRET = process.env.ATTRIBLOOM_FORWARDING_SECRET;     // server-side only, never in the app

export async function forwardToAttribloom(signedPayload) {
  const ts = Math.floor(Date.now() / 1000).toString();       // unix SECONDS, not ms
  const body = JSON.stringify({ signedPayload });            // Apple's JWS, verbatim, unparsed
  const sig = "sha256=" + crypto
    .createHmac("sha256", SECRET)
    .update(`${ts}.`)   // timestamp + "."
    .update(body)        // then the exact bytes you POST
    .digest("hex");

  // Retries reuse these identical bytes; Attribloom deduplicates by notification UUID.
  return fetch(`https://api.attribloom.com/v1/app-store/assn/${SURFACE_ID}`, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-ea-timestamp": ts,   // unix seconds string
      "x-ea-signature": sig,  // "sha256=" + hex
    },
    body,
  });
}