@shopify/shop-minis-platform 0.13.0 → 0.15.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@shopify/shop-minis-platform",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Shared type definitions for Shop Minis Platform",
   "main": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./package.json": "./package.json",
     "./actions": "./src/actions/index.ts",
     "./events": "./src/events/index.ts"
   },
@@ -20,7 +21,9 @@
   ],
   "dependencies": {},
   "peerDependencies": {},
-  "devDependencies": {},
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
   "author": "Shopify",
   "repository": {
     "type": "git",
@@ -29,6 +32,7 @@
   },
   "scripts": {
     "test": "TZ=UTC jest",
-    "type-check": "tsc --noEmit"
+    "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,
@@ -93,6 +94,8 @@ import {
   ShareSingleResponse,
   RequestPermissionParams,
   RequestPermissionResponse,
+  CheckPermissionParams,
+  CheckPermissionResponse,
   ReportErrorParams,
   ReportFetchParams,
 } from './params'
@@ -235,6 +238,8 @@ export interface ShopActionEvents {
     RequestPermissionParams,
     RequestPermissionResponse
   >
+  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']
+>

package/src/actions/params.ts

@@ -34,6 +34,33 @@ export interface RequestPermissionResponse {
   errorMessage?: string
 }
 
+/**
+ * The current state of a permission for the Mini.
+ *
+ * - `granted`: The user has approved the in-app consent dialog and the OS has granted the permission.
+ * - `denied`: The user has previously denied the permission, either in the in-app consent dialog or at the OS level. The permission can still be requested again.
+ * - `blocked`: The permission is blocked at the OS level. The user must enable it from device settings.
+ * - `undetermined`: The user has not yet been shown the in-app consent dialog for this permission.
+ * - `unavailable`: The permission is not declared in the Mini's manifest, or the feature is not available on this device.
+ *
+ * @publicDocs
+ */
+export type PermissionStatus =
+  | 'granted'
+  | 'denied'
+  | 'blocked'
+  | 'undetermined'
+  | 'unavailable'
+
+export interface CheckPermissionParams {
+  permission: MiniPermission
+}
+
+export interface CheckPermissionResponse {
+  status: PermissionStatus
+  errorMessage?: string
+}
+
 export interface FavoriteParams {
   shopId: string
   productId: string

package/src/actions/scopes.ts

@@ -1,4 +1,4 @@
-import {ShopActionEvents} from '@shopify/shop-minis-platform/actions'
+import {ShopActionEvents} from './actions'
 
 // This enum should always match `MiniScopeEnum` in `shop-types`
 /* eslint-disable @shopify/typescript/prefer-pascal-case-enums */

package/src/types/minis.ts

@@ -1,3 +1,4 @@
+/** @publicDocs */
 export interface SafeAreaInsets {
   top: number
   right: number