Upgrade Guide

​

Install the exact major

pnpm remove @craveup/storefront-sdk
pnpm add --save-exact @craveup/storefront-sdk@2.0.0

​

Replace configuration

// 1.x — remove this configuration.
createStorefrontClient({
  apiKey: process.env.NEXT_PUBLIC_CRAVEUP_API_KEY!,
});

const storefront = createStorefrontClient({
  baseUrl: process.env.NEXT_PUBLIC_CRAVEUP_API_URL!,
  sessionStore,
  getAuthToken: () => customerTokenStore.get(),
});

​

Update methods, arguments, and types

​

Update response handling

​

Update request validation

• Use only takeout, table_side, room_service, or delivery for fulfillment. Set table and room identifiers through cart.setTable() and cart.setRoom() rather than a generic cart patch.
• Use cart.updateOrderTime() for scheduling. cart.update() accepts fulfillment and/or a note, not order-date or order-time fields.
• Send exactly one of amount or percentage to cart.updateGratuity().
• Send a full supported country name such as United States, not US.
• Send table numbers as numeric strings such as "12", not "T-12" or "Patio 3".
• Treat marketplaceId as optional source attribution such as "web" or "mobile"; it is not a location ID.
• For a signed-in shopper who still has a guest-capability cart, use the named { includeCustomerContext: true } request option only when customer-aware discount validation or Stripe customer association is needed. Omit it for a guest; claimed carts use the customer JWT automatically.

​

Required migration

1. Configure the explicit public API origin for the correct environment.
2. Provide a StorefrontSessionStore for { locationId, cartId, accessToken, revision }, scoped by canonical API environment, merchant, and location.
3. Create carts through orderingSessions.start(). Let the SDK persist the returned capability and authoritative revision; do not copy the token into application state or UI props.
4. Let cart methods attach X-Cart-Token, If-Match, and Idempotency-Key. On CART_CONFLICT, refresh and ask the customer to retry; never silently replay intent.
5. Store the merchant-bound customer JWT in versioned, tab-scoped browser storage or expo-secure-store, and clear it on logout.
6. Replace legacy payment calls with checkout.createPaymentIntent() and bounded checkout.getOrderResult() polling; stop reading the removed stripeAccountId response field.
7. Capture a receipt capability from the URL fragment, remove the fragment immediately, and scope storage by environment, merchant, and receipt ID.
8. Register each exact deployed browser origin with Crave. Native apps normally need no CORS registration; Expo web does.
9. Delete the obsolete 1.x client, API-key configuration, wrapper types, adapters, tests, and documentation in the same application change.

​

Verification checklist

• Public bundles contain no private Crave or payment-provider secrets.
• Published merchant, location, menu, product, distance, order-time, and gratuity requests carry no customer JWT.
• Wrong, expired, cross-location, and cross-merchant capabilities are denied.
• Stale revisions return CART_CONFLICT and are not automatically replayed.
• Only completed is treated as checkout success.
• CORS is restricted to the exact deployed storefront origins.
• A clean install, typecheck, production web build or Expo export, and sandbox vertical slice use the exact registry artifact.