@shopify/app-bridge-types 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- [#781](https://github.com/Shopify/extensibility/pull/781) [`e8e0b29249891fd59e7a709b8c6990fa5ae6908b`](https://github.com/Shopify/extensibility/commit/e8e0b29249891fd59e7a709b8c6990fa5ae6908b) Thanks [@charlesdobson](https://github.com/charlesdobson)! - add types for intents.invoke API
+
+## 0.4.0
+
+### Minor Changes
+
+- [#760](https://github.com/Shopify/extensibility/pull/760) [`4f7742e4aacb581a380c76742689dca617c86b6d`](https://github.com/Shopify/extensibility/commit/4f7742e4aacb581a380c76742689dca617c86b6d) Thanks [@Fionoble](https://github.com/Fionoble)! - Add new s-app-\* types
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -13,3 +13,26 @@ You can install Shopify App Bridge Types by using [Yarn](https://yarnpkg.com):
 ```sh
 yarn add --dev @shopify/app-bridge-types
 ```
+
+## Development
+
+### How Types are Generated
+
+The types in this package are automatically generated from the `sandboxes/app-bridge-next` source code:
+
+1. Types are defined in `sandboxes/app-bridge-next/src/features/` 
+2. During build, they're compiled to `sandboxes/app-bridge-next/dist/app-bridge.d.ts`
+3. The build script (`scripts/build.mjs`) processes and copies these types to the `dist` folder
+4. The processed types are then published to npm
+
+### Releasing a New Version
+
+To release a new version of the types package:
+
+1. Make your changes to the type definitions in `sandboxes/app-bridge-next/src/features/`
+2. Run `pnpm changeset` from the root of the repository
+3. Select `@shopify/app-bridge-types` to bump its version
+4. Commit your changes
+5. CI will automatically handle building and publishing the updated package
+
+The automation ensures that the types stay in sync with the app-bridge-next implementation.

package/dist/index.d.ts

@@ -4,11 +4,15 @@ import type {
   AppBridgeElements,
   AppBridgeAttributes,
   UIModalElement as BaseUIModalElement,
+  SAppWindowElement as BaseSAppWindowElement,
   UINavMenuElement as BaseUINavMenuElement,
+  SAppNavElement as BaseSAppNavElement,
   UITitleBarElement as BaseUITitleBarElement,
   UISaveBarElement as BaseUISaveBarElement,
   UIModalAttributes,
+  SAppWindowAttributes,
   UINavMenuAttributes,
+  SAppNavAttributes,
   UITitleBarAttributes,
   UISaveBarAttributes,
   ToastOptions,
@@ -20,7 +24,9 @@ import type {
 export {
   ShopifyGlobal,
   UIModalAttributes,
+  SAppWindowAttributes,
   UINavMenuAttributes,
+  SAppNavAttributes,
   UITitleBarAttributes,
   UISaveBarAttributes,
   ToastOptions,
@@ -37,7 +43,9 @@ declare global {
   interface HTMLAnchorElement extends AugmentedElement<'a'> {}
 
   interface UIModalElement extends BaseUIModalElement {}
+  interface SAppWindowElement extends BaseSAppWindowElement {}
   interface UINavMenuElement extends BaseUINavMenuElement {}
+  interface SAppNavElement extends BaseSAppNavElement {}
   interface UITitleBarElement extends BaseUITitleBarElement {}
   interface UISaveBarElement extends BaseUISaveBarElement {}
 

package/dist/shopify.ts

@@ -1,3 +1,5 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
 interface Address {
     /**
      * The customer's primary address.
@@ -136,10 +138,12 @@ interface AppBridgeConfig {
 
 export interface AppBridgeElements {
     'ui-modal': UIModalAttributes;
+    's-app-window': SAppWindowAttributes;
     'ui-nav-menu': UINavMenuAttributes;
     's-app-nav': SAppNavAttributes;
     'ui-save-bar': UISaveBarAttributes;
     'ui-title-bar': UITitleBarAttributes;
+    's-page': SPageAttributes;
 }
 
 export type AugmentedElement<T extends keyof AugmentedElements> = AugmentedElements[T];
@@ -210,6 +214,13 @@ interface Cart {
  */
 type CartSubscriber = (cart: Cart) => void;
 
+/**
+ * User dismissed or closed the workflow without completing it.
+ */
+interface ClosedIntentResponse {
+    code?: 'closed';
+}
+
 export interface Collection extends Resource {
     availablePublicationCount: number;
     description: string;
@@ -353,6 +364,15 @@ interface _EnvironmentApi {
     pos?: boolean;
 }
 
+/**
+ * Failed intent completion.
+ */
+interface ErrorIntentResponse {
+    code?: 'error';
+    message?: string;
+    issues?: StandardSchemaV1.Issue[];
+}
+
 /**
  * Represents an activation record for an extension.
  * Contains information about where an extension is activated.
@@ -456,10 +476,61 @@ interface Intent {
     finish: Finish;
 }
 
-interface IntentsApi {
+/**
+ * The action to perform on a resource.
+ */
+type IntentAction = 'create' | 'edit';
+
+/**
+ * Activity handle for tracking intent workflow progress.
+ */
+interface IntentActivity {
+    /**
+     * A Promise that resolves when the intent workflow completes, returning the response.
+     */
+    complete?: Promise<IntentResponse>;
+}
+
+interface IntentQuery extends IntentQueryOptions {
+    action: IntentAction;
+    type: IntentType;
+}
+
+/**
+ * Options for invoking intents when using the query string format.
+ */
+interface IntentQueryOptions {
+    /**
+     * The resource identifier for edit actions (e.g., 'gid://shopify/Product/123').
+     */
+    value?: string;
+    /**
+     * Additional data required for certain intent types.
+     * For example:
+     * - Discount creation requires { type: 'amount-off-product' | 'amount-off-order' | 'buy-x-get-y' | 'free-shipping' }
+     * - ProductVariant creation requires { productId: 'gid://shopify/Product/123' }
+     * - Metaobject creation requires { type: 'shopify--color-pattern' }
+     */
+    data?: {
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Result of an intent activity.
+ * Discriminated union representing all possible completion outcomes.
+ */
+type IntentResponse = ClosedIntentResponse | SuccessIntentResponse | ErrorIntentResponse;
+
+interface IntentsApi extends PublicIntentsApi {
     register(callback: (intent: Intent) => void): () => void;
 }
 
+/**
+ * Supported resource types that can be targeted by intents.
+ */
+type IntentType = 'shopify/Article' | 'shopify/Catalog' | 'shopify/Collection' | 'shopify/Customer' | 'shopify/Discount' | 'shopify/Market' | 'shopify/Menu' | 'shopify/MetafieldDefinition' | 'shopify/Metaobject' | 'shopify/MetaobjectDefinition' | 'shopify/Page' | 'shopify/Product' | 'shopify/ProductVariant';
+
 interface LineItem {
     /**
      * Unique id of line item
@@ -871,6 +942,37 @@ enum ProductVariantInventoryPolicy {
 
 type Progress = 'incomplete' | 'partiallyComplete' | 'complete';
 
+/**
+ * Entry point for Shopify intents.
+ *
+ * A unified surface for describing and orchestrating operations. Intents pair
+ * an `action` (verb) with a resource `type` and optional `value` and `data`
+ * to request a workflow.
+ */
+interface PublicIntentsApi {
+    /**
+     * Invoke an intent using the object syntax.
+     *
+     * @param query - Structured intent description, including `action` and `type`.
+     * @returns A promise for an {@link IntentActivity} that completes with an
+     *          {@link IntentResponse}.
+     */
+    invoke?(query: IntentQuery): Promise<IntentActivity>;
+    /**
+     * Invoke an intent using the URL syntax.
+     *
+     * URL format: `action:type[,value][?params]`.
+     *
+     * @param intentURL - Intent in URL form, e.g. `create:shopify/Product` or
+     *                    `edit:shopify/Product,gid://shopify/Product/123?title=Updated` or
+     *                    `edit:gid://shopify/Product/123`.
+     * @param options - Optional supplemental inputs such as `value` or `data`.
+     * @returns A promise for an {@link IntentActivity} that completes with an
+     *          {@link IntentResponse}.
+     */
+    invoke?(intentURL: string, options?: IntentQueryOptions): Promise<IntentActivity>;
+}
+
 interface Resource {
     /** in GraphQL id format, ie 'gid://shopify/Product/1' */
     id: string;
@@ -948,8 +1050,61 @@ export interface SAppNavAttributes {
     children?: any;
 }
 
-export interface SAppNavElement extends HTMLElement {
+interface SAppNavElement_2 extends HTMLElement {
 }
+export type { SAppNavElement_2 as SAppNavElement }
+
+export interface SAppWindowAttributes {
+    /**
+     * A unique identifier for the S-App-Window
+     */
+    id?: string;
+    /**
+     * The URL of the content to display within the S-App-Window.
+     * S-App-Window only supports src-based content (required).
+     */
+    src: string;
+}
+
+interface _SAppWindowElement {
+    /**
+     * Always returns undefined for s-app-window (src-only)
+     */
+    readonly content: undefined;
+    /**
+     * A getter/setter for the s-app-window src URL
+     */
+    src?: string;
+    /**
+     * A getter for the Window object of the s-app-window iframe.
+     * Only accessible when the s-app-window is open.
+     */
+    readonly contentWindow?: Window | null;
+    /**
+     * Shows the s-app-window element
+     */
+    show?(): Promise<void>;
+    /**
+     * Hides the s-app-window element
+     */
+    hide?(): Promise<void>;
+    /**
+     * Toggles the s-app-window element between showing and hidden states
+     */
+    toggle?(): Promise<void>;
+    /**
+     * Add 'show' | 'hide' event listeners.
+     */
+    addEventListener?(type: 'show' | 'hide', listener: EventListenerOrEventListenerObject): void;
+    /**
+     * Remove 'show' | 'hide' event listeners.
+     */
+    removeEventListener?(type: 'show' | 'hide', listener: EventListenerOrEventListenerObject): void;
+}
+
+interface SAppWindowElement_2 extends Omit<HTMLElement, 'addEventListener' | 'removeEventListener'>, Required<Omit<_SAppWindowElement, 'src' | 'contentWindow'>>, Pick<_SAppWindowElement, 'src' | 'contentWindow'> {
+}
+export type { SAppWindowElement_2 as SAppWindowElement }
 
 interface SaveBarApi extends Required<_SaveBarApi> {
 }
@@ -1058,6 +1213,32 @@ export interface ShopifyGlobal {
     app: AppApi;
 }
 
+export interface SPageAttributes {
+    heading?: string;
+    children?: SPageChildren;
+}
+
+interface SPageChildren {
+    primaryAction?: HTMLElement;
+    secondaryActions?: HTMLElement[];
+    breadcrumbActions?: HTMLElement;
+}
+
+export interface SPageElement {
+    heading?: string;
+    children?: SPageChildren;
+}
+
+/**
+ * Successful intent completion.
+ */
+interface SuccessIntentResponse {
+    code?: 'ok';
+    data?: {
+        [key: string]: unknown;
+    };
+}
+
 interface SupportApi {
     registerHandler?: (callback: SupportCallback | null) => Promise<void>;
 }
@@ -1154,7 +1335,7 @@ interface _UIModalElement {
     /**
      * A getter/setter that is used to set modal variant.
      */
-    variant?: Variant;
+    variant?: 'small' | 'base' | 'large' | 'max';
     /**
      * A getter/setter that is used to get the DOM content of the modal
      * element and update the content after the modal has been opened.
@@ -1172,15 +1353,15 @@ interface _UIModalElement {
      */
     readonly contentWindow?: Window | null;
     /**
-     * Shows the save bar element
+     * Shows the modal element
      */
     show?(): Promise<void>;
     /**
-     * Hides the save bar element
+     * Hides the modal element
      */
     hide?(): Promise<void>;
     /**
-     * Toggles the save bar element between the showing and hidden states
+     * Toggles the modal element between the showing and hidden states
      */
     toggle?(): Promise<void>;
     /**
@@ -1341,8 +1522,6 @@ type UserApi = () => Promise<User>;
  */
 type UserResult = 'granted-all' | 'declined-all';
 
-type Variant = 'small' | 'base' | 'large' | 'max';
-
 interface WebVitalsApi {
     onReport?: (callback: WebVitalsCallback | null) => Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/app-bridge-types",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Companion types library for the Shopify App Bridge script",
   "private": false,
   "publishConfig": {
@@ -18,6 +18,7 @@
     "default": "./dist/index.js"
   },
   "devDependencies": {
+    "@standard-schema/spec": "^1.0.0",
     "cjyes": "^0.3.1"
   },
   "files": [