@shopify/app-bridge-types 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

package/dist/shopify.ts

@@ -1,3 +1,5 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
 interface Address {
     /**
      * The customer's primary address.
@@ -141,6 +143,7 @@ export interface AppBridgeElements {
     's-app-nav': SAppNavAttributes;
     'ui-save-bar': UISaveBarAttributes;
     'ui-title-bar': UITitleBarAttributes;
+    's-page': SPageAttributes;
 }
 
 export type AugmentedElement<T extends keyof AugmentedElements> = AugmentedElements[T];
@@ -211,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;
@@ -354,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.
@@ -457,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
@@ -872,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;
@@ -1112,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>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/app-bridge-types",
-  "version": "0.4.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": [