arky-sdk 0.11.1 → 0.11.3

package/README.md

@@ -10,14 +10,19 @@ npm install arky-sdk
 
 ## Storefront quick start
 
+The current browser contract is `arky-sdk@0.11.3`. Pin that exact version during the coordinated
+prelaunch cutover so the Server, App, and storefront route/header contracts move together:
+
+```bash
+npm install --save-exact arky-sdk@0.11.3
+```
+
 Copy the Store publishable key from Developer and initialize one client:
 
 ```typescript
-import { initialize } from "arky-sdk";
+import { initialize } from "arky-sdk/storefront";
 
-export const arky = initialize(
-  import.meta.env.PUBLIC_ARKY_PUBLISHABLE_KEY,
-);
+export const arky = initialize(import.meta.env.PUBLIC_ARKY_PUBLISHABLE_KEY);
 ```
 
 `initialize` is synchronous. It makes no request and creates no visitor. Production requests use `https://api.arky.io` by default.
@@ -198,7 +203,8 @@ Authorization: Bearer arky_vst_...
 ```
 
 For cart recovery, `cart.get({ id, token })` sends the recovery credential as
-`X-Arky-Cart-Token`. It is never placed in the request URL or body.
+`X-Arky-Cart-Token`. It is never placed in the request URL or body, and the corresponding response
+is private and non-cacheable.
 
 Locale and market headers are omitted when no explicit context is set, allowing the server to use Store defaults.
 
@@ -215,6 +221,13 @@ initialize(publishableKey: string, {
 
 One storefront client always represents one publishable key and one Store. To connect to another Store, initialize a second explicit client with its publishable key.
 
+## Releasing
+
+SDK packages are released only by tagging the current protected `master` commit with the exact
+`v<package.json version>` tag. The `Publish SDK` workflow reruns `npm test` and publishes through
+npm trusted publishing with provenance; configure that workflow as the package's trusted publisher
+instead of storing a long-lived npm token.
+
 ## Admin client
 
 Private operator integrations use the separate Admin client. Personal API tokens must never be exposed in browser code:
@@ -250,7 +263,7 @@ import {
   type ArkyStore,
   type StorefrontDto,
   type StorefrontSetup,
-} from "arky-sdk";
+} from "arky-sdk/storefront";
 import type { Block, Cart, Order, Price, Product, Service } from "arky-sdk";
 
 type StorefrontProduct = StorefrontDto<Product>;
@@ -259,6 +272,19 @@ type StorefrontCart = StorefrontDto<Cart>;
 
 Storefront request types intentionally contain no Store routing ID. Admin request types remain Store-explicit.
 
+## Verification
+
+Run the complete SDK package contract with one command:
+
+```bash
+npm test
+```
+
+It builds the distributable package and runs every SDK contract case. App alone owns cross-repository
+Server compatibility against the exact immutable test Server image digest. Each storefront owns a
+hermetic repo-local build/preview Playwright smoke through its own `npm test`; storefronts never pull
+or run the shared test Server image.
+
 ## Adding an endpoint
 
 When adding SDK methods: