Enrich JSDoc for Platform APIs property descriptions, 2025-10

Port enriched JSDoc descriptions from checkout-web to ui-extensions
2025-10. Covers Analytics, Extension, Localization, Metafields,
Session Token, Settings, Shop, Storage, and Storefront APIs.

Every description verified against the 2025-10 TypeScript types.

Partially closes shop/issues-learn#1046

Made-with: Cursor

Author: SteveSill

packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts

@@ -22,14 +22,11 @@ import type {SubscribableSignalLike} from '../../shared';
 export type {ApiVersion, Capability} from '../../../../shared';
 
 /**
- * A key-value storage object for the extension.
- *
- * Stored data is available only to this specific extension
- * and any of its instances.
- *
- * The storage backend is implemented with `localStorage` and
- * should persist across the buyer's checkout session.
- * However, data persistence isn't guaranteed.
+ * Persists key-value data across the buyer's session for a specific extension.
+ * Use storage to save preferences, dismiss states, or cached data that should
+ * survive page reloads without requiring a backend call. Stored data is only
+ * available to this specific extension. The storage backend is implemented with
+ * `localStorage` and data persistence isn't guaranteed.
  */
 export interface Storage {
   /**
@@ -50,13 +47,15 @@ export interface Storage {
   write(key: string, data: any): Promise<void>;
 
   /**
-   * Delete stored data by key.
+   * Deletes a previously stored value by key.
    */
   delete(key: string): Promise<void>;
 }
 
 /**
- * The meta information about an extension target.
+ * Metadata about the running extension, including its API version, target,
+ * capabilities, and editor context. Use this to read configuration details or
+ * conditionally render content based on where the extension is running.
  */
 export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   /**
@@ -130,6 +129,11 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   version?: string;
 }
 
+/**
+ * Information about the editor environment when an extension is rendered
+ * inside the editor. The value is `undefined` when the extension is not
+ * rendering in an editor.
+ */
 export interface Editor {
   /**
    * Indicates whether the extension is rendering in the [checkout editor](https://shopify.dev/docs/apps/checkout). Always `'checkout'`.
@@ -294,9 +298,9 @@ export type Version = string;
 export type CheckoutToken = string;
 
 /**
- * This returns a translated string matching a key in a locale file.
- *
- * @example translate("banner.title")
+ * Translates a key from your extension's locale files into a localized string.
+ * Supports interpolation with placeholder replacements and pluralization
+ * via the special `count` option.
  */
 export interface I18nTranslate {
   <ReplacementType = string>(
@@ -307,6 +311,11 @@ export interface I18nTranslate {
     : (string | ReplacementType)[];
 }
 
+/**
+ * Utilities for translating strings, formatting currencies, numbers,
+ * and dates according to the buyer's locale. Use the I18n API alongside
+ * the Localization API to build fully localized extensions.
+ */
 export interface I18n {
   /**
    * Returns a localized number.
@@ -389,6 +398,11 @@ export interface Market {
   handle: string;
 }
 
+/**
+ * The buyer's language, country, and locale context. Properties on this
+ * interface are subscribable and update automatically when the buyer's
+ * locale changes.
+ */
 export interface Localization {
   /**
    * The currency that the buyer sees for money amounts in the checkout. Use this value to format prices and totals in the buyer's expected currency.
@@ -540,7 +554,9 @@ export interface BuyerJourneyStep {
 /** @publicDocs */
 export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
-   * The methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   * Tracks custom events and sends visitor information to
+   * [Web Pixels](https://shopify.dev/docs/apps/marketing). Use `publish()` to emit events
+   * and `visitor()` to submit buyer contact details.
    */
   analytics: Analytics;
 
@@ -640,7 +656,9 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   discountAllocations: SubscribableSignalLike<CartDiscountAllocation[]>;
 
   /**
-   * The meta information about the extension.
+   * Metadata about the running extension, including the current target, API version,
+   * capabilities, and editor context. Use this to conditionally render content
+   * based on where the extension is running.
    */
   extension: Extension<Target>;
 
@@ -658,12 +676,10 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   extensionPoint: Target;
 
   /**
-   * Utilities for translating content and formatting values according to the current
+   * Utilities for translating strings, formatting currencies, numbers, and dates
+   * according to the buyer's locale. Use alongside
    * [`localization`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization)
-   * of the checkout.
-   *
-   * Refer to [`localization` examples](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization#examples)
-   * for more information.
+   * to build fully localized extensions.
    */
   i18n: I18n;
 
@@ -673,10 +689,10 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   lines: SubscribableSignalLike<CartLine[]>;
 
   /**
-   * The details about the location, language, and currency of the customer. For utilities to easily
-   * format and translate content based on these details, you can use the
+   * The buyer's language, country, currency, and timezone context. For
+   * formatting and translation helpers, use
    * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization#standardapi-propertydetail-i18n)
-   * object instead.
+   * instead.
    */
   localization: Localization;
 
@@ -760,18 +776,19 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   billingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
-  /** The shop where the checkout is taking place. */
+  /**
+   * The store where the checkout is taking place, including the shop name,
+   * primary domain, `.myshopify.com` subdomain, and globally-unique ID.
+   */
   shop: Shop;
 
   /**
-   * The key-value storage for the extension.
-   *
-   * It uses `localStorage` and should persist across the customer's current checkout session.
+   * Key-value storage that persists across page loads within the current checkout
+   * session. Data is shared across all activated extension targets of this
+   * extension.
    *
-   * > Caution: Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout.
-   *
-   * Data is shared across all activated extension targets of this extension. In versions 2023-07 and earlier,
-   * each activated extension target had its own storage.
+   * > Caution: Data persistence isn't guaranteed and storage is cleared when the
+   * buyer starts a new checkout.
    */
   storage: Storage;
 
@@ -802,6 +819,12 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   localizedFields?: SubscribableSignalLike<LocalizedField[]>;
 }
 
+/**
+ * Authenticates requests between your extension and your app backend.
+ * Use session tokens to verify the identity of the customer and the shop
+ * context when making server-side API calls. The token is a signed JWT
+ * that contains claims such as the customer ID, shop domain, and expiration.
+ */
 export interface SessionToken {
   /**
    * Requests a session token that hasn't expired. You should call this method every
@@ -929,6 +952,10 @@ export interface AppliedGiftCard {
   balance: Money;
 }
 
+/**
+ * Metadata about the merchant's store, including its name, primary
+ * domain, `.myshopify.com` subdomain, and globally-unique ID.
+ */
 export interface Shop {
   /**
    * A globally-unique identifier for the shop in the format `gid://shopify/Shop/<id>`.
@@ -1567,14 +1594,20 @@ export type ExtensionSettings = Record<
   string | number | boolean | undefined
 >;
 
+/**
+ * Tracks custom events and sends visitor information to
+ * [Web Pixels](https://shopify.dev/docs/apps/marketing). Use `publish()` to emit events
+ * and `visitor()` to submit buyer contact details.
+ */
 export interface Analytics {
   /**
-   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
+   * Publishes a custom event to [Web Pixels](https://shopify.dev/docs/apps/marketing).
+   * Returns `true` when the event is successfully dispatched.
    */
   publish(name: string, data: Record<string, unknown>): Promise<boolean>;
 
   /**
-   * A method for capturing details about a visitor on the online store.
+   * Submits buyer contact details for attribution and analytics purposes.
    */
   visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
 }