@shoppexio/storefront 1.0.58 → 1.0.60

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## 1.0.60
+
+- Reject post-purchase `redirectUrl` values that still contain unresolved template placeholders.
+
+## 1.0.59
+
+- Add `redirectUrl` to `checkout()` and `buildCheckoutUrl()` for channel-specific post-purchase returns.
+- Keep `currency` and the post-purchase redirect in the same idempotent invoice-create intent.
+- Publish npm from the public Storefront wrapper and keep the internal CDN implementation private.
+- Correct the cart custom-field and `line_id` examples in the npm and Mintlify documentation.
+
+## 1.0.58
+
+- Add buyer-selected `currency` to `checkout()` and `buildCheckoutUrl()` so quote and invoice creation use the same currency.
+
+## 1.0.57
+
+- Preserve checkout-origin Turnstile challenge details on `buildCheckoutUrl()` errors so headless callers can render the proof and retry.
+
+## 1.0.56
+
+- Retain checkout idempotency keys until invoice-create responses are both parseable and definitive, preventing duplicate orders after truncated response bodies.
+- Expose server-requested Turnstile challenges so official storefront checkout surfaces can collect and resubmit human-verification proofs.
+
+## 1.0.55
+
+- Retain independent checkout idempotency keys for overlapping buyer intents, so an ambiguous response cannot duplicate an earlier invoice when another checkout starts concurrently.
+
+## 1.0.54
+
+- Reuse checkout idempotency keys after ambiguous transport failures, while rotating them after definitive responses or changed buyer intent.
+- Forward optional `storefront_checkout` Turnstile proofs without changing the idempotent create command.
+
+## 1.0.51
+
+- Send a fresh idempotency key for every storefront checkout action so network retries replay safely without reviving an older abandoned cart.
+
+## 1.0.50
+
+- Expose authoritative paid and due amounts in customer order details.
+- Expose volume discounts as a separate buyer-facing price adjustment.
+
+## 1.0.49
+
+- Expose the complete customer-order pricing breakdown, including buyer-paid processing fees.
+
+## 1.0.48
+
+- Preserve Headless customer review scores by exposing the stored `1`, `3`, and `5` sentiment levels.
+- Count the 256-character review limit by visible Unicode characters, including joined emoji.
+
+## 1.0.47
+
+- Add authenticated `orderReview()` and `submitOrderReview()` methods to the Headless Customer SDK.
+- Scope review reads and writes to the signed-in customer's own shop and order.
+
+## 1.0.46
+
+- Headless customer dashboards now expose Shoppex file deliverables as authenticated `downloadIndex` values instead of hosted-portal-only URLs.
+
+## 1.0.45
+
+- Expand `@shoppexio/storefront/customer` from order history to buyer-safe customer portal parity: account settings, support, licenses, wallet checkout handoffs, subscriptions, replacements, loyalty, warranties, favorites, affiliate links, and reseller flows.
+- Validate every new customer response against the shared Shoppex wire contracts.
+- Publish the matching customer portal wire contracts with the SDK release.
+- Keep direct money movement, provider redirects, password/session controls, reseller balance spending, and durable API-key creation behind Shoppex-controlled portal handoffs.
+
+## 1.0.44
+
+- Actually ship the `@shoppexio/storefront/customer` subpath in the published tarball: 1.0.42/1.0.43 documented the entry, but the release pipeline packs `packages/sdk`, whose exports map did not carry it (`ERR_PACKAGE_PATH_NOT_EXPORTED`).
+
+## 1.0.43
+
+- Require an explicit file index for customer downloads so the SDK never guesses which delivered file to return.
+- Expose safe `downloadIndex` descriptors for headless order details.
+- Keep the local customer session when remote logout fails, so revocation can be retried.
+
+## 1.0.42
+
+- Add `@shoppexio/storefront/customer` for custom OTP login, customer details, order history, order details, and downloads.
+- Add opt-in `rememberMe` sessions for up to 30 days.
+- Return safe `downloadIndex` descriptors for delivered files and retain the local session when logout revocation can be retried.
+
+## 0.3.1
+
+- Add `program_enabled` to affiliate validation responses.
+- Clarify disabled affiliate program handling for headless storefronts.
+
+## 0.3.0
+
+- Publish the active Storefront SDK runtime under `@shoppexio/storefront`.
+- Include cart coupon validation types for `{ productId, variantId }`.
+
+## 0.1.1
+
+- Package metadata and release polish.
+
+## 0.1.0
+
+- first public storefront package release
+- typed package entrypoint for the existing Shoppex storefront runtime

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoppex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,235 +1,151 @@
-# Shoppex Storefront SDK
+# @shoppexio/storefront
 
-Build custom storefronts with any framework using the Shoppex SDK.
+Official JavaScript storefront SDK for Shoppex.
 
-## Installation
+Use this package when you want to embed Shoppex products, cart behavior, and hosted checkout into a custom frontend.
 
-### CDN (Recommended for quick start)
+## Good fit
 
-```html
-<script src="https://cdn.shoppex.io/sdk/v0.3/shoppex.umd.js"></script>
-```
-
-Use the moving minor channel for managed updates.
-Simple example: `v0.3` moves to the latest `0.3.x` release.
-
-If you need a locked production rollout, pin an exact version:
+Use this package for:
 
-```html
-<script src="https://cdn.shoppex.io/sdk/<exact-version>/shoppex.umd.js"></script>
-```
-
-`/sdk/latest/` stays available for internal and development usage only.
+- product loading
+- cart state
+- checkout redirects
+- storefront helpers
 
-### npm
+## Install
 
 ```bash
 npm install @shoppexio/storefront
 ```
 
-## Quick Start
-
-```html
-<script src="https://cdn.shoppex.io/sdk/v0.3/shoppex.umd.js"></script>
-<script>
-  // Initialize with your store slug
-  shoppex.init('my-store');
-
-  // Get store info
-  shoppex.getStore().then(function(result) {
-    if (result.success) {
-      console.log('Store:', result.data.name);
-    }
-  });
-
-  // Add product to cart
-  shoppex.addToCart('product-id', 'variant-id', 2);
-
-  // Checkout (redirects to hosted checkout)
-  document.getElementById('checkout-btn').onclick = function() {
-    shoppex.checkout();
-  };
-</script>
-```
+## Quick start
 
-### ES Modules (with async/await)
+```ts
+import shoppex from '@shoppexio/storefront';
 
-```html
-<script type="module">
-  import shoppex from 'https://cdn.shoppex.io/sdk/v0.3/shoppex.esm.js';
-
-  shoppex.init('my-store');
-
-  const store = await shoppex.getStore();
-  const products = await shoppex.getProducts();
-
-  shoppex.addToCart(products.data[0].uniqid, 'default', 1);
-
-  await shoppex.checkout();
-</script>
-```
+shoppex.init('my-store');
 
-## API Reference
-
-### Initialization
-
-```javascript
-// Simple init
-shoppex.init('store-slug');
-
-// With options
-shoppex.init({
-  storeId: 'store-slug',
-  locale: 'de',
-  currency: 'EUR'
+const products = await shoppex.getProducts();
+shoppex.addToCart(products.data?.[0]?.uniqid ?? '', 'default', 1, {
+  custom_fields: {
+    customer_note: 'Gift order',
+  },
 });
+await shoppex.checkout();
 ```
 
-### Store
+Cart items use a stable `line_id`. Use this identifier for cart updates and
+removals because one product can have multiple cart configurations.
 
-```javascript
-const store = await shoppex.getStore();
-// → { success: true, data: { id, name, currency, ... } }
+```ts
+const [line] = shoppex.getCart();
 
-const logoUrl = await shoppex.getStoreLogoUrl();
-const bannerUrl = await shoppex.getStoreBannerUrl();
+if (line) {
+  shoppex.updateCartItem(line.line_id, { quantity: 2 });
+  shoppex.removeFromCart(line.line_id);
+}
 ```
 
-### Products
+## Multi-currency checkout
 
-```javascript
-const products = await shoppex.getProducts();
-// → { success: true, data: [{ uniqid, title, price, images[], variants[], addons[], faqs[], feedback, ... }] }
-//    variants[] mirrors price_variants[] (legacy field); both are present for compatibility.
-//    images[] contains the full product gallery; the first entry is the primary image.
-
-const product = await shoppex.getProduct('product-id-or-slug');
-const categories = await shoppex.getCategories();
-```
+When buyers can select a storefront currency, quote the cart and create the
+invoice with the same currency:
 
-### Cart
+```ts
+const selectedCurrency = 'EUR';
+await shoppex.quoteCart(undefined, selectedCurrency);
 
-```javascript
-// Simple add
-shoppex.addToCart('productId', 'variantId', 2);
-
-// With Shoppex features (addons, custom fields)
-shoppex.addToCart('productId', 'variantId', 1, {
-  addons: [
-    { id: 'addon_gift_wrap', quantity: 1 }
-  ],
-  customFields: {
-    'engraving_text': 'Happy Birthday!'
-  },
-  priceVariantId: 'price_premium'
+const checkoutUrl = await shoppex.buildCheckoutUrl({
+  currency: selectedCurrency,
 });
-
-// Get cart
-const cart = shoppex.getCart();
-const itemCount = shoppex.getCartItemCount();
-
-// Manage cart
-shoppex.removeFromCart('productId', 'variantId');
-shoppex.clearCart();
-
-// Backup/restore (useful for error recovery)
-shoppex.createCartBackup();
-shoppex.restoreCartFromBackup();
 ```
 
-### Checkout
+After a currency change, quote the cart again before checkout. Quote tokens are
+currency-bound; Shoppex rejects a mismatch as
+`errors.checkout.quote_token_stale` instead of creating an invoice for a total
+the buyer did not approve.
 
-```javascript
-// Simple checkout (auto-redirects)
-await shoppex.checkout();
-
-// With coupon
-await shoppex.checkout('SAVE20');
+## Custom customer account
 
-// Get URL without redirecting
-const result = await shoppex.checkout('SAVE20', { autoRedirect: false });
-console.log(result.redirectUrl);
-```
+Build your own OTP login, order history, and download UI without adding a
+merchant API key or custom backend. Headless customer accounts are available on
+every Shoppex plan; only the separate Headless Checkout SDK requires Business:
 
-### Coupons
+```ts
+import { createCustomerClient } from '@shoppexio/storefront/customer';
 
-```javascript
-const result = await shoppex.validateCoupon('SAVE20', {
-  productId: 'product-id',
-  variantId: 'variant-id',
+const customer = createCustomerClient({
+  shop: 'my-store',
+  publishableKey: 'pk_live_your_key',
 });
-// -> { success: true, data: { valid: true, discount: 20, restriction_scope: 'variants' } }
-```
 
-### Affiliate Codes
+await customer.requestOtp('buyer@example.com');
+await customer.verifyOtp('buyer@example.com', '123456', { rememberMe: true });
 
-Affiliate/referral codes are separate from coupon codes. Validate and store them before checkout:
+const orders = await customer.orders();
+const firstOrder = orders.invoices[0];
 
-```javascript
-const affiliate = await shoppex.applyAffiliateCode('creator10');
+if (firstOrder) {
+  const order = await customer.order(firstOrder.uniqid);
 
-if (affiliate.data?.program_enabled === false) {
-  throw new Error('Affiliate program is disabled for this shop');
+  for (const item of order.lineItems) {
+    const instructions = item.deliveryText ?? item.product?.serviceText;
+    console.log(item.deliveryStatus, instructions, item.deliverySummary);
+  }
 }
-
-await shoppex.checkout({
-  coupon: 'SAVE20',
-  affiliateCode: affiliate.data?.affiliate_code,
-});
 ```
 
-### Reviews
-
-```javascript
-const reviews = await shoppex.getShopReviews();
-// → { success: true, data: [{ rating, comment, ... }] }
-```
+The publishable key and current browser origin must be configured under
+**Settings -> Developer -> Headless**. `rememberMe` is opt-in and keeps
+the buyer signed in for up to 30 days.
 
-### Invoices
-
-```javascript
-const invoice = await shoppex.getInvoice('invoice-id');
-const status = await shoppex.getInvoiceStatus('invoice-id');
-```
+The order detail includes delivery status, service instructions, codes, serials,
+notes, links, and file indexes. Delivery content appears only after Shoppex marks
+the item as delivered. Sanitize rich-text delivery instructions before you render
+them as HTML.
 
-### Formatting
+## Coupon validation
 
-```javascript
-const formatter = shoppex.createFormatter('USD', 'en-US');
-formatter.format(29.99); // → "$29.99"
+Use the options form when validating a coupon for a selected product variant:
 
-// Or directly
-shoppex.formatPrice(29.99, 'EUR', 'de-DE'); // → "29,99 €"
+```ts
+const result = await shoppex.validateCoupon('SAVE10', {
+  productId: 'prod_abc123',
+  variantId: 'variant_lifetime',
+});
 ```
 
-## Shoppex Features
-
-The SDK supports Shoppex-specific features not found in competitors:
+Calling `validateCoupon(code)` without options validates against the current SDK cart. Affiliate/referral codes are separate and should use `validateAffiliateCode` or `applyAffiliateCode`. If `program_enabled` is false in an affiliate validation response, the shop-level affiliate program is disabled even if individual links exist.
 
-| Feature | Description |
-|---------|-------------|
-| **Product Addons** | Express shipping, gift wrap, etc. |
-| **Custom Fields** | Customer input (engraving, gift message) |
-| **Price Variants** | Different pricing tiers |
-| **Multiple Gateways** | Stripe, PayPal, Crypto |
+## Live online users
 
-## Browser Support
+The SDK can power a custom live online visitor counter. It provides the data; your storefront renders the badge.
 
-- Chrome 80+
-- Firefox 75+
-- Safari 13+
-- Edge 80+
+```ts
+import shoppex from '@shoppexio/storefront';
 
-## TypeScript
+shoppex.init('my-store');
 
-Full TypeScript support with type definitions included.
+async function refreshLiveUsers() {
+  await shoppex.touchStorefrontPresence();
 
-```typescript
-import shoppex, { Product, CartItem } from '@shoppexio/storefront';
+  const result = await shoppex.getStorefrontOnlineUsers();
+  if (result.success && result.data) {
+    console.log(`${result.data.count} online`);
+  }
+}
 
-const products: Product[] = (await shoppex.getProducts()).data ?? [];
+await refreshLiveUsers();
+setInterval(refreshLiveUsers, 30_000);
 ```
 
-## License
+## Not this package
+
+If you want the authenticated Developer API wrapper for backend integrations, use `@shoppexio/sdk`. Do not ship `@shoppexio/sdk` in a browser bundle; use this Storefront SDK for headless storefronts.
+
+## Docs
 
-MIT
+- Storefront docs: [docs.shoppex.io/sdk/introduction](https://docs.shoppex.io/sdk/introduction)
+- Installation: [docs.shoppex.io/sdk/installation](https://docs.shoppex.io/sdk/installation)
+- Headless customer accounts: [docs.shoppex.io/developers/headless/customer-accounts](https://docs.shoppex.io/developers/headless/customer-accounts)