Tip jar namespace

Reference for the tip jar: the tip page, tip checkout and the tip's status after Stripe returns the tipper.

Let visitors tip the board any amount at or above a minimum. board.tipJar reads the board's tip jar for the tip page, starts an embedded Stripe checkout for a tip, and reads the tip's status when Stripe returns the tipper. Each board has at most one tip jar. All three methods work with the publishable key alone; no board-user session is needed.

The tip page path is BOARD_PATHS.tip (/tip) from @cavuno/board/paths, the tip role in the board's route manifest. The types are TipJar, TipJarCheckoutBody, TipJarCheckout and TipJarCheckoutStatus. For the page flow, see Tip jar.

`board.tipJar.get()`

1get(options?: FetchOptions): Promise<TipJar>

The board's tip jar: object: 'tip_jar', name, description (plain text), descriptionHtml (sanitized HTML, or null), currency, minimumCents (the smallest tip checkout takes: the board's minimum, or Stripe's smallest charge in the currency), suggestedCents (three amounts, smallest first), allowNote, noteMaxLength (280), thankYouMessage, tipCount and url, the tip page path from the board's route manifest.

tipCount is a number only when the board shows the number of tips; otherwise it is null. It counts paid tips: a tip refunded in full or disputed leaves the count.

1const jar = await board.tipJar.get();
2const amounts = jar.suggestedCents; // e.g. [300, 500, 1000]

A board with no tip jar, or an archived one, is tip_jar_not_found (404): hide the tip page and its links.

`board.tipJar.checkout()`

1checkout(body: TipJarCheckoutBody, options?: FetchOptions): Promise<TipJarCheckout>

Body: amountCents (minor units of the tip jar's currency, at least minimumCents), note (plain text up to 280 characters; send it only when allowNote is true), returnPath (the relative path Stripe returns the tipper to, with session_id appended; defaults to the tip page) and website, a honeypot field to render hidden and leave empty.

Returns object: 'tip_jar_checkout', status: 'open' and an embedded Stripe Checkout mount kit: sessionId, clientSecret, stripeAccountId and publishableKey. Mount it with loadStripe(publishableKey, { stripeAccount: stripeAccountId }) and initEmbeddedCheckout({ clientSecret }). The session expires after 30 minutes. The tip is a payment on the board's connected Stripe account; Stripe collects the tipper's email, filled in for a signed-in board user. The mount kit fields are null only when the honeypot was filled and nothing was recorded.

1const kit = await board.tipJar.checkout({
2  amountCents: 500,
3  note: 'Thanks for the weekly roundup!',
4});

Works with the publishable key alone or with a board-user token.

`board.tipJar.getCheckout()`

1getCheckout(sessionId: string, options?: FetchOptions): Promise<TipJarCheckoutStatus>

After Stripe returns the tipper with session_id: object: 'tip_jar_checkout_status', status (processing until the payment clears, then paid), amountCents, currency, receiptEmail and thankYouMessage. Poll for a few seconds with cache: 'no-store'.

receiptEmail is masked, like m•••@gmail.com, because the session id sits in a URL that can be shared. It is null until the tip is paid.

1const result = await board.tipJar.getCheckout(sessionId, { cache: 'no-store' });
2if (result.status === 'paid') {
3  console.log(result.thankYouMessage, result.receiptEmail);
4}

Errors

get returns tip_jar_not_found (404). checkout returns tip_amount_below_minimum (400, with details.minimumCents), tip_amount_invalid (400), tip_note_not_allowed (400), tip_note_too_long (400), tip_jar_not_found (404), stripe_not_connected (409), rate_limited (429) and rate_limit_unavailable (503). getCheckout with an unknown session is tip_checkout_not_found (404).

The Board API never returns other tippers' emails or notes.