@abra-promotions/webhooks-for-tapcart 2.0.0-beta.4 → 2.0.0-beta.5

package/README.md

@@ -29,6 +29,55 @@ const MyComponent = ({ useTapcart, tapcartData }) => {
 };
 ```
 
+### Shared helpers for Abra's blocks
+
+Abra's own blocks (Activate, Activate Private, Cart, Banners) import these instead of keeping
+copies:
+
+- `slugify(text)`: Abra's Tapcart metafield key for a promotion title or tag visibility.
+- Promotions: `parsePromotion` (any non-draft promotion, what Abra Activate stores, so a
+  scheduled one turns on at its start date) and `parsePromotionIfActive` (only while ACTIVE or
+  SCHEDULED and within its dates, what the blocks that render it use).
+- Storage (`STORAGE_KEYS` and read/write helpers, all taking the object `useTapcart()` returns):
+  `abra` (`readAbraSession`, `readStoredPromotion`, `readActivePromotion`, `writeAbraSession`),
+  `abra.giftsAdded` (`readGiftsAdded`, `writeGiftsAdded`, `recordGiftAdded`, `clearGiftsAdded`),
+  `abra.selectedGiftVariantIds` and `abra.private-promotion`.
+- Products: `fetchProducts({ ids | handles, storeUrl, storeFrontAccessToken, country, details })`
+  and the `useProducts({ React, ... })` hook. `details` adds titles, variant images and selling
+  plans. A query whose country fails is retried without it.
+- Gifts: `getBxgyGetsCards`, `extractNumericSellingPlanId`, `toGiftPurchaseType`,
+  `resolveGiftSellingPlanId`.
+- Buy X get Y (`bxgy.js`), ported from the abra repo's theme extension (`BxgyDiscount`) so the
+  app agrees with the storefront: `toBxgyLine(s)` turn any cart item shape into one line shape
+  (Abra gift lines, marked by the `__abra` attribute, never count); `areAllBxgyCardsMet`,
+  `getBxgyTimesMet` (gets-side capacity and `maxApplicationsPerOrder`),
+  `wouldAddingTriggerNewBxgyApplication` (product-page price previews), `getBxgyProgress`
+  (banner progress) and the matchers. Cases in `bxgy.test.js` marked "theme:" are the theme's
+  own tests.
+
+### Discount strategies
+
+Every discount family has a strategy (`strategyFor(discount)`, `src/strategies/`) ported from the
+Shopify function that decides what checkout grants (the storefront theme for native Shopify codes
+and display-only rules). Where the theme and a function disagree, the function wins, so the app
+never shows a price or gift checkout won't honor. They all work on one cart-line shape
+(`toCartLines`) and share the entitlement matcher (`matchesEntitledScope`):
+
+- `priceDiscount` — the per-unit discount a product page shows (used by `getBiggestDiscount`,
+  which then applies Shopify's combining rules and tag stacking from `price-selection.js`).
+- `codeApplies` — whether CartBlock keeps the discount code on the cart.
+- `giftAwards` / `giftOptions` / `giftRules` — the gifts granted now and the freeGiftSettings.
+- `progress` — banner numbers (tiers and gifts).
+
+`readActivePromotion` filters the stored promotion's discounts at read time (`eligibility.js`:
+dates, markets, POS-only, bulk codes, customer restrictions). Each test file ports the
+function's and the theme's own cases (marked "function:" / "theme:").
+
+Not handled yet: currency conversion. Thresholds and fixed amounts are compared in the shop's
+currency; every strategy takes `opts.currencyRate` for when the app can get a rate.
+
+Adding an export a block imports means raising `BLOCKS_NEED_PKG` in `scripts/lib/code.mjs`.
+
 ## Requirements
 
 - React 16.8+ (passed in as `React`)