ceejay.shop

When a member buys such an item, CEEJAY deducts the coins and sends a signed request to your server. Your server responds with delivered, failed or pending. If it responded pending, it completes the purchase later with ceejay.shop.completePurchase.

To receive the delivery and check its signature, see Verifying signatures.

Every function takes the same last argument, options: signal, timeoutMs and maxRetries, for that one call. A write also takes idempotencyKey there. Every function can also raise the errors any request can raise, such as a bad key or the rate limit. See Errors and retries.

ceejay.shop.listPurchases

Lists the purchases, and the rewards members earned, that are delivered by your API and are pending fulfilment by your server. A purchase your server responded to with pending is never sent again, so use this list to recover a delivery your server missed.

GET /v1/shop/purchases · requires shop:fulfil · API reference: List shop purchases

Retried by the SDK: Yes. It is a read

Parameters: one object, which can be left out, then options.

Returns the full response, typed as Schemas['ListShopPurchasesResponse']. The purchases are in data, oldest first, and the pagination details are in page.

Each purchase, typed as Schemas['WaitingPurchase']:

A server that polls once a minute uses one of the key's requests per minute.

Errors

Example

const waiting = await ceejay.shop.listPurchases()

for (const purchase of waiting.data) {
  if (purchase.state === 'processing') {
    console.log(`Purchase ${purchase.purchaseId} of ${purchase.item.itemKey} waits until ${purchase.completeBy}`)
  }
}

ceejay.shop.completePurchase

Tells CEEJAY how a purchase ended. delivered marks the purchase delivered. failed refunds the member.

POST /v1/shop/purchases/{purchaseId}/complete · requires shop:fulfil · API reference: Complete a shop delivery

Retried by the SDK: Only with idempotencyKey. Sending the same status again yourself is also safe

Parameters: the purchase, one object, then options.

Options

You have 24 hours. A purchase that is still pending then is refunded by CEEJAY.

Returns the full response, typed as Schemas['CompleteShopPurchaseResponse'].

data contains:

Errors

Idempotency errors are covered in Errors and retries.

A purchase ID that is not a whole number from 1 is never sent: the SDK throws a TypeError. The ID of a test delivery is text, and a test delivery is never completed. So the purchase_id of a delivery has the type "number or text": check that it is a number before you pass it on. Verifying signatures shows how, in the example that responds with pending.

Example

import { CeejayError } from '@communitystudios/ceejay'

try {
  const result = await ceejay.shop.completePurchase(4242, { status: 'delivered' }, { idempotencyKey: 'purchase-4242:delivered' })
  console.log(result.data.status, result.data.alreadyDone ? '(already done)' : '')
} catch (error) {
  if (error instanceof CeejayError && error.code === 'wrong_status') {
    console.log('The purchase had already been refunded')
  } else {
    throw error
  }
}

When you cannot deliver, report failed and the member is refunded:

const result = await ceejay.shop.completePurchase(4242, {
  status: 'failed',
  message: 'The player has no account on this realm',
})

console.log(result.data.status, result.data.refunded)