@shopify/shop-minis-platform 0.14.1 → 0.15.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopify/shop-minis-platform",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "description": "Shared type definitions for Shop Minis Platform",
   "main": "src/index.ts",
   "exports": {
@@ -19,6 +19,11 @@
     "README.md",
     "LICENSE.txt"
   ],
+  "scripts": {
+    "test": "TZ=UTC jest",
+    "type-check": "tsc --noEmit",
+    "typecheck": "pnpm run type-check"
+  },
   "dependencies": {},
   "peerDependencies": {},
   "devDependencies": {
@@ -29,10 +34,5 @@
     "type": "git",
     "url": "https://github.com/Shopify/shop-client.git",
     "directory": "packages/minis/shop-minis-platform"
-  },
-  "scripts": {
-    "test": "TZ=UTC jest",
-    "type-check": "tsc --noEmit",
-    "typecheck": "pnpm run type-check"
   }
-}
+}

package/src/actions/actions.ts

@@ -1,5 +1,6 @@
 import {ProductList} from '../types'
 
+import {InvokeIntentParams, InvokeIntentResponse} from './intents'
 import {
   FollowShopParams,
   UnfollowShopParams,
@@ -240,4 +241,5 @@ export interface ShopActionEvents {
   CHECK_PERMISSION: ShopAction<CheckPermissionParams, CheckPermissionResponse>
   REPORT_ERROR: ShopAction<ReportErrorParams, void>
   REPORT_FETCH: ShopAction<ReportFetchParams, void>
+  INVOKE_INTENT: ShopAction<InvokeIntentParams, InvokeIntentResponse>
 }

package/src/actions/index.ts

@@ -2,3 +2,5 @@ export * from './actions'
 export * from './shared'
 export * from './params'
 export * from './scopes'
+export * from './intents'
+export * from './intent-definitions'

package/src/actions/intent-definitions.ts

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// User Image Intent — create:shop/UserImage
+// ---------------------------------------------------------------------------
+
+export interface CreateUserImageParams {
+  /**
+   * Tag identifying the image in the mini's image library. Required so a
+   * future saved-images intent can surface previously created images by tag.
+   */
+  tag: string
+  /**
+   * If set, skip the source chooser and open this source directly.
+   * When omitted, the host shows a sheet letting the user pick a source.
+   */
+  source?: 'camera' | 'library'
+  /** Which camera to default to when the camera is used. Defaults to 'front'. */
+  camera?: 'front' | 'rear'
+  /**
+   * Cropping configuration. Omit to skip the cropping step — the user's
+   * original photo is returned as-is (capped by `maxSize`).
+   */
+  crop?: {
+    /**
+     * Fixed aspect ratio enforced by the cropper. Omit for free-form crop.
+     * e.g. `{width: 1, height: 1}` for a square, `{width: 16, height: 9}` for widescreen.
+     */
+    aspectRatio?: {width: number; height: number}
+    /** Overlay shape shown to the user. Defaults to 'rectangle'. */
+    shape?: 'rectangle' | 'circle'
+  }
+  /** Max width/height of the output image in pixels. Defaults to 700. */
+  maxSize?: number
+}
+
+export interface CreateUserImageResponse {
+  imageUrl: string
+}
+
+// ---------------------------------------------------------------------------
+// Intent Registry
+// ---------------------------------------------------------------------------
+
+export interface IntentDefinitions {
+  createUserImage: {
+    action: 'create'
+    type: 'shop/UserImage'
+    data: CreateUserImageParams
+    result: CreateUserImageResponse
+  }
+}
+
+export type IntentKey = keyof IntentDefinitions

package/src/actions/intents.ts

@@ -0,0 +1,104 @@
+/**
+ * Generic intent type definitions for Shop Minis.
+ *
+ * These types define the shared contract for intent invocations
+ * across the Minis ecosystem (Mini → Host, Host → Mini, Mini → Mini).
+ */
+
+import type {IntentDefinitions, IntentKey} from './intent-definitions'
+
+// ---------------------------------------------------------------------------
+// Intent query types
+// ---------------------------------------------------------------------------
+
+export interface IntentQueryOptions<TData = unknown> {
+  /** Optional identifier (e.g. a resource GID) for an existing resource */
+  value?: string
+  /** Optional JSON-serializable input payload */
+  data?: TData
+}
+
+/**
+ * Structured description of an intent to invoke.
+ *
+ * Pairs an action verb with a resource type and optional inputs.
+ */
+export interface IntentQuery<
+  TData = unknown,
+> extends IntentQueryOptions<TData> {
+  /** Verb describing the operation (e.g., 'create', 'edit', 'view') */
+  action: string
+  /** MIME-type identifier for the target resource (e.g., 'shop/UserImage') */
+  type: string
+}
+
+/**
+ * Params for the INVOKE_INTENT shop action.
+ */
+export type InvokeIntentParams = IntentQuery<any>
+
+// ---------------------------------------------------------------------------
+// Intent result types
+// ---------------------------------------------------------------------------
+
+export interface IntentResultOk<T> {
+  code: 'ok'
+  data: T
+}
+
+export interface IntentResultError {
+  code: 'error'
+  message: string
+}
+
+export interface IntentResultClosed {
+  code: 'closed'
+}
+
+/**
+ * Discriminated union of all possible intent completion outcomes.
+ * - `'ok'`     — workflow completed successfully with typed result data
+ * - `'error'`  — workflow failed with a message
+ * - `'closed'` — user dismissed without completing
+ */
+export type IntentResult<T = {[key: string]: unknown}> =
+  | IntentResultOk<T>
+  | IntentResultError
+  | IntentResultClosed
+
+/**
+ * Params passed to an individual intent handler.
+ */
+export interface IntentActionParams<TData> {
+  /** Resource identifier (e.g. a Shopify GID), or null for creation flows. */
+  value: string | null
+  /** Optional typed input payload. */
+  data?: TData
+}
+
+/**
+ * A generic type for individual intent implementations.
+ */
+export type IntentAction<TData, TResult> = (
+  params: IntentActionParams<TData>
+) => Promise<IntentResult<TResult>>
+
+/** Untyped intent response used at the INVOKE_INTENT bridge boundary. */
+export type InvokeIntentResponse = IntentResult
+
+// ---------------------------------------------------------------------------
+// Typed intent utilities — leverage IntentDefinitions for per-intent safety
+// ---------------------------------------------------------------------------
+
+/** Type-safe intent query for a registered intent. */
+export type TypedIntentQuery<K extends IntentKey> = IntentQuery<
+  IntentDefinitions[K]['data']
+> & {
+  action: IntentDefinitions[K]['action']
+  type: IntentDefinitions[K]['type']
+}
+
+/** Full typed response for a registered intent, narrowable on `code`. */
+export type TypedIntentResponse<K extends IntentKey> = IntentResult<
+  IntentDefinitions[K]['result']
+>