@shopify/app-bridge-types 0.5.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- [#943](https://github.com/Shopify/extensibility/pull/943) [`9f8ecdb615732364fbdb1c010f385e58b4b5525d`](https://github.com/Shopify/extensibility/commit/9f8ecdb615732364fbdb1c010f385e58b4b5525d) Thanks [@bashu-shopify](https://github.com/bashu-shopify)! - Add theme app extension types to the App Bridge extensions API
+
+  This adds support for theme app extensions (blocks and embeds) in the `shopify.app.extensions()` API response. New types include:
+
+  - `ExtensionType`: `'ui_extension' | 'theme_app_extension'`
+  - `ActivationStatus`: `'active' | 'available' | 'unavailable'`
+  - `ThemeExtensionActivation`: Represents a theme app block or embed
+  - `ThemeAppBlockActivation`: Represents where a block is placed in a theme
+  - `ThemeAppBlockTarget` and `ThemeAppEmbedTarget`: Target location types
+
+  The `ExtensionInfo` interface is now a generic that provides typed activations based on the extension type.
+
+## 0.6.0
+
+### Minor Changes
+
+- [#932](https://github.com/Shopify/extensibility/pull/932) [`e6a8c26486ab44faa524d8041bbdcb3bbb6b1515`](https://github.com/Shopify/extensibility/commit/e6a8c26486ab44faa524d8041bbdcb3bbb6b1515) Thanks [@bashu-shopify](https://github.com/bashu-shopify)! - Add theme app extension types to the App Bridge extensions API
+
+  This adds support for theme app extensions (blocks and embeds) in the `shopify.app.extensions()` API response. New types include:
+
+  - `ExtensionType`: `'ui_extension' | 'theme_app_extension'`
+  - `ActivationStatus`: `'active' | 'available' | 'unavailable'`
+  - `ThemeExtensionActivation`: Represents a theme app block or embed
+  - `ThemeAppBlockActivation`: Represents where a block is placed in a theme
+  - `ThemeAppBlockTarget` and `ThemeAppEmbedTarget`: Target location types
+
+  The `ExtensionInfo` interface is now a generic that provides typed activations based on the extension type.
+
 ## 0.5.3
 
 ### Patch Changes

package/dist/index.d.ts

@@ -20,6 +20,7 @@ import type {
   ProductVariant,
   Collection,
 } from './shopify';
+import {type InternalPolarisApi} from './types';
 
 export {
   ShopifyGlobal,
@@ -37,6 +38,7 @@ export {
 
 declare global {
   var shopify: ShopifyGlobal;
+  var polaris: InternalPolarisApi['global'] | undefined;
 
   // Install property augmentations onto DOM prototypes
   interface HTMLButtonElement extends AugmentedElement<'button'> {}

package/dist/shopify.ts

@@ -1,5 +1,15 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * The availability status of a theme app block or embed.
+ * - 'active': Block/embed is currently present in a theme.
+ * - 'available': Block/embed exists but is not currently active
+ * - 'unavailable': Block/embed exists but is disabled (e.g., via available_if condition)
+ *
+ * Note that if a block is present in a theme but is not available, its status will be 'unavailable'.
+ */
+type ActivationStatus = 'active' | 'available' | 'unavailable';
+
 interface Address {
     /**
      * The customer's primary address.
@@ -68,7 +78,7 @@ interface AdminUser {
 interface AppApi {
     /**
      * The list of extensions from the current app.
-     * @returns A promise that resolves to the array of ExtensionResponse containing extension status information.
+     * @returns A promise that resolves to the array of ExtensionInfo containing extension status information.
      *
      * This array may be empty if the app has no extensions.
      *
@@ -374,32 +384,39 @@ interface ErrorIntentResponse {
 }
 
 /**
- * Represents an activation record for an extension.
- * Contains information about where an extension is activated.
- */
-interface ExtensionActivation {
-    /**
-     * The target identifier for the extension activation.
-     */
-    target: string;
-}
-
-/**
- * Contains the status information for the app's extension.
- * This includes the extension's handle, and activation targets.
+ * Contains the status information for the App's extension.
+ * This includes the extension's handle, activation targets, status, and type.
+ *
+ * @typeParam Type - The extension type, either 'ui_extension' or 'theme_app_extension'.
+ *   When specified, the `activations` field will be typed accordingly:
+ *   - `ExtensionInfo<'ui_extension'>` has `activations: UiExtensionActivation[]`
+ *   - `ExtensionInfo<'theme_app_extension'>` has `activations: ThemeExtensionActivation[]`
  */
-interface ExtensionInfo {
+interface ExtensionInfo<Type extends ExtensionType = ExtensionType> {
     /**
      * The unique identifier for the extension.
      */
     handle: string;
     /**
      * List of activation records for the extension.
-     * Contains information about where the extension is currently activated.
+     * The shape depends on the extension type:
+     * - UI extensions have activations with only `target`
+     * - Theme app extensions have nested activations representing blocks/embeds
+     */
+    activations: Type extends 'ui_extension' ? UiExtensionActivation[] : Type extends 'theme_app_extension' ? ThemeExtensionActivation[] : never;
+    /**
+     * The type of the extension.
      */
-    activations: ExtensionActivation[];
+    type: Type;
 }
 
+/**
+ * The type of extension.
+ * - 'ui_extension' for checkout and customer account extensions
+ * - 'theme_app_extension' for theme app extensions (blocks and embeds)
+ */
+type ExtensionType = 'ui_extension' | 'theme_app_extension';
+
 interface Filters {
     /**
      * Whether to show hidden resources, referring to products that are not published on any sales channels.
@@ -1245,6 +1262,65 @@ interface SupportApi {
 
 type SupportCallback = () => void | Promise<void>;
 
+/**
+ * Represents a theme-specific activation for a block/embed.
+ * Contains the specific placement within a theme.
+ */
+interface ThemeAppBlockActivation {
+    /**
+     * The target identifier for the block/embed placement within the theme.
+     * Example: 'template--product.alternate/main/my_app_product_rating_GPzUYy'
+     */
+    target: string;
+    /**
+     * The theme ID where this block/embed is activated.
+     * Format: gid://shopify/OnlineStoreTheme/{id}
+     */
+    themeId: string;
+}
+
+/**
+ * Target location for theme app blocks.
+ */
+type ThemeAppBlockTarget = 'section';
+
+/**
+ * Target location for theme app embeds.
+ */
+type ThemeAppEmbedTarget = 'head' | 'body' | 'compliance_head';
+
+/**
+ * Represents an activation record for a theme app block or embed.
+ * Each block/embed within a theme app extension has its own handle, status, and activations.
+ */
+interface ThemeExtensionActivation {
+    /**
+     * The target location type for this block/embed.
+     * - 'section' for blocks
+     * - 'head', 'body', or 'compliance_head' for embeds
+     */
+    target: ThemeAppBlockTarget | ThemeAppEmbedTarget;
+    /**
+     * The filename of the block/embed within the theme app extension (without extension).
+     * This is configured by the developer when creating the block file.
+     */
+    handle: string;
+    /**
+     * The developer-configured display name of this block/embed, defined in the block's schema.
+     * @see https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration#schema
+     */
+    name: string;
+    /**
+     * The availability status of this block/embed.
+     */
+    status: ActivationStatus;
+    /**
+     * List of theme-specific activations for this block/embed.
+     * Contains where the block is actually placed within themes.
+     */
+    activations: ThemeAppBlockActivation[];
+}
+
 /**
  * The Toast API provides methods to display Toast notifications in the Shopify admin.
  */
@@ -1297,6 +1373,17 @@ type ToastShow = (message: string, opts?: ToastOptions) => string;
 
 type Tone = 'info' | 'success' | 'warning' | 'critical';
 
+/**
+ * Represents an activation record for a UI extension (checkout, customer account).
+ */
+interface UiExtensionActivation {
+    /**
+     * The target identifier for the extension activation.
+     * Example: 'purchase.thank-you.block.render'
+     */
+    target: string;
+}
+
 export interface UIModalAttributes extends _UIModalAttributes {
     children?: any;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/app-bridge-types",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Companion types library for the Shopify App Bridge script",
   "private": false,
   "publishConfig": {