Currently, the process of exporting perks from CiviCRM and adding the updated perk data to donate-neo requires an intermediate step of hand-massaging the export file into valid JSON. This MR adds a (detailed) description of the steps required, along with a little context where available.

service/donate.md

@@ -570,6 +570,71 @@ sequenceDiagram
     donate->>civi: Submits donation and perk info
 ```
 
+### Treating exported perk data
+
+As of 1/16/25, perk data exported from CiviCRM needs to be massaged into valid
+JSON data before it can be used to update the `perks.json` datafile which `donate-neo`
+pulls from. For reference, here are the changes which must be made to the export file
+before it can be used to update the `donate-neo` repo:
+1. The data object exported from CiviCRM is a square-braces array, and is not named;
+to conform to JSON standards it must be wrapped in an object's curly braces and
+must be named "perks". Other extraneous text prepending the array must be removed.
+   a. For example, `(5) [{"foo": "bar"}]` must become `{"perks": [{"foo": "bar"}]}`
+2. Product `id` fields must be expressed as strings, but are exported from CiviCRM as 
+integers. (See [tpo/web/donate-neo/commit/b23e7fdd](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/b23e7fdd59a66658f50ede630ed924b0006a6439).) Wrap all such IDs in quotes.
+   a. For example, `"id": 1` must become `"id": "1"`.
+3. Each "perks" array item contains a child item `product_id.options`. If the perk
+does not have options (such as the sticker pack), CiviCRM will export this field as
+`null`. However, CiviCRM expects `donate-neo` to pass an option SKU along with a perk's
+ID when selected - keeping this field `null` will keep selected perks from being
+recorded in the CRM. (See [tpo/web/donate-neo/commit/65144a42](https://gitlab.torproject.org/tpo/web/donate-neo/-/commit/65144a429e4f132ad64f1479eb8c8c94935897bd).) Therefore, we add
+a mock option SKU in place of `null` in such cases.
+   a. For example, `"product_id.options": null` must become
+   `"product_id.options": ["STI-CKR-00=Sticker"]` (or something similar).
+4. Ensure all prices are expressed in number of cents (`2500`) rather than number of dollars (`25`).
+5. CiviCRM is able to store and serve image files related to perks, but we should serve these
+images from `donate-neo` along with the rest of the site assets. As well, CiviCRM does not
+properly store .pngs with transparency layers, rendering them instead as matte black.
+In order to render and serve these images as intended, we store them as base64-encoded
+strings in the JSON itself, under the key `"product_id.imageForDonateNeo"`. 
+   a. Ensure your string is encoded as a data URI, e.g. beginning with `data:image/png;base64,`.
+6. `product_id.optionsForDonateNeo` is used by `donate-neo` to build out the form UI
+used by the donor to select perk options. It was designed to serve an option-selection
+UI similar to `donate-paleo`'s, in which a given perk might have two options, the
+second dependent on the first.
+For example, a T-shirt perk might come in different cuts, like "Classic" and "Slim
+Fit", but each cut would have separate sizes to pick from.
+Please ensure that `product_id.optionsForDonateNeo` contains data formatted like so:
+
+   ```
+   "product_id.optionsForDonateNeo": {
+     "Classic": {
+       "TSHIRT-PACK-C01": "Small",
+       "TSHIRT-PACK-C02": "Medium",
+       [...]
+       "TSHIRT-PACK-C07": "4XL"
+     }
+   }
+   ```
+
+   Above, `Classic` is the parent option category, `Small` is the child option category,
+   and `TSHIRT-PACK-C01` is the SKU of the perk represented by these options (e.g.,
+   the "Classic-fit small-sized shirt".)
+
+   In the event that the given perk has no options, such as the sticker pack, you must
+   still express the mock option SKU from #3 in this manner, like so:
+
+   ```
+   "product_id.optionsForDonateNeo": {
+     "Classic": {
+       "STI-CKR-00": "Sticker"
+     }
+   },
+   ```
+   `donate-neo` will refrain from visually rendering single-selection option groups, but these must be
+   included so they can be embedded as (hidden) form elements, which are then passed along to
+   CiviCRM.
+
 ### Original design
 
 The original sequence diagram built by @kez in January 2023