feat: more plugin triggers and methods (#28690)

packages/plugin-core/manifest.json

@@ -7,8 +7,8 @@
   "wasmPath": "dist/plugin.wasm",
   "templates": [
     {
-      "name": "auto-archive-screenshots",
-      "title": "Auto-archive screenshots",
+      "name": "screenshots-smart-album",
+      "title": "Archive screenshots",
       "description": "Archive uploads with \"screenshot\" in the filename and optionally add them to an album",
       "trigger": "AssetCreate",
       "steps": [
@@ -29,6 +29,27 @@
         {
           "method": "immich-plugin-core#assetAddToAlbums",
           "config": {
+            "albumName": "Screenshots",
+            "albumIds": []
+          }
+        }
+      ],
+      "uiHints": ["SmartAlbum"]
+    },
+    {
+      "name": "missing-timezone-smart-album",
+      "title": "Missing timezone",
+      "description": "Automatically create an album for assets without a time zone",
+      "trigger": "AssetMetadataExtraction",
+      "steps": [
+        {
+          "method": "immich-plugin-core#assetMissingTimeZoneFilter",
+          "config": {}
+        },
+        {
+          "method": "immich-plugin-core#assetAddToAlbums",
+          "config": {
+            "albumName": "Missing time zone",
             "albumIds": []
           }
         }
@@ -68,6 +89,24 @@
       },
       "uiHints": ["Filter"]
     },
+    {
+      "name": "assetMissingTimeZoneFilter",
+      "title": "Filter by missing time zone",
+      "description": "Filter assets that have no time zone information",
+      "types": ["AssetV1"],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "inverse": {
+            "type": "boolean",
+            "title": "Inverse",
+            "description": "Missing by default, set to true to filter assets with a time zone",
+            "default": false
+          }
+        }
+      },
+      "uiHints": ["Filter"]
+    },
     {
       "name": "filterFileType",
       "title": "Filter by file type",
@@ -189,6 +228,12 @@
             "array": true,
             "description": "Target album IDs",
             "uiHint": "AlbumId"
+          },
+          "albumName": {
+            "type": "string",
+            "title": "Album name",
+            "array": true,
+            "description": "Use an album with this name if one exists, otherwise create a new one"
           }
         },
         "required": ["albumIds"]

packages/plugin-core/package.json

@@ -13,6 +13,7 @@
   "license": "AGPL-3.0",
   "devDependencies": {
     "@extism/js-pdk": "^1.0.1",
+    "@immich/sdk": "workspace:*",
     "@immich/plugin-sdk": "workspace:*",
     "esbuild": "^0.28.0",
     "typescript": "^6.0.0"

packages/plugin-core/src/index.d.ts

@@ -1,14 +1,20 @@
-// copy from
-// import '@immich/plugin-sdk/host-functions';
+// keep in sync with plugin-sdk/host-functions.ts';
 declare module 'extism:host' {
   interface user {
-    albumAddAssets(ptr: PTR): I64;
+    searchAlbums(ptr: PTR): I64;
+    createAlbum(ptr: PTR): I64;
+    addAssetsToAlbum(ptr: PTR): I64;
     addAssetsToAlbums(ptr: PTR): I64;
   }
 }
 
+// keep in sync with manifest.json
 declare module 'main' {
+  // filters
   export function assetFileFilter(): I32;
+  export function assetMissingTimeZoneFilter(): I32;
+
+  // updates
   export function assetFavorite(): I32;
   export function assetVisibility(): I32;
   export function assetArchive(): I32;

packages/plugin-core/src/index.ts

@@ -1,4 +1,5 @@
-import { AssetStatus, AssetVisibility, WorkflowType, wrapper } from '@immich/plugin-sdk';
+import { wrapper } from '@immich/plugin-sdk';
+import { AssetVisibility, WorkflowType } from '@immich/sdk';
 
 type AssetFileFilterConfig = {
   pattern: string;
@@ -41,6 +42,14 @@ export const assetFileFilter = () => {
   });
 };
 
+export const assetMissingTimeZoneFilter = () => {
+  return wrapper<WorkflowType.AssetV1, { inverse?: boolean }>(({ config, data }) => {
+    const hasTimeZone = !!data.asset?.exifInfo?.timeZone;
+    const needsTimeZone = config.inverse ? true : false;
+    return { workflow: { continue: hasTimeZone === needsTimeZone } };
+  });
+};
+
 export const assetFavorite = () => {
   return wrapper<WorkflowType.AssetV1, { inverse?: boolean }>(({ config, data }) => {
     const target = config.inverse ? false : true;
@@ -89,28 +98,35 @@ export const assetLock = () => {
 };
 
 export const assetTrash = () => {
-  return wrapper<WorkflowType.AssetV1, { inverse?: boolean }>(({ config, data }) => ({
-    changes: {
-      asset: config.inverse
-        ? { deletedAt: null, status: AssetStatus.Active }
-        : { deletedAt: new Date().toISOString(), status: AssetStatus.Trashed },
-    },
-  }));
+  // TODO use trash/untrash host functions
+  return wrapper<WorkflowType.AssetV1, { inverse?: boolean }>(() => ({}));
 };
 
 export const assetAddToAlbums = () => {
-  return wrapper<WorkflowType.AssetV1, { albumIds: string[] }>(({ config, data, functions }) => {
+  return wrapper<WorkflowType.AssetV1, { albumIds: string[]; albumName?: string }>(({ config, data, functions }) => {
+    const assetId = data.asset.id;
+
     if (config.albumIds.length === 0) {
-      // noop
-      return {};
+      if (!config.albumName) {
+        return {};
+      }
+
+      const [existing] = functions.searchAlbums({ name: config.albumName });
+      if (!existing) {
+        const created = functions.createAlbum({ albumName: config.albumName, assetIds: [assetId] });
+        config.albumIds.push(created.id);
+        return {};
+      }
+
+      config.albumIds.push(existing.id);
     }
 
     if (config.albumIds.length === 1) {
-      functions.albumAddAssets(config.albumIds[0], [data.asset.id]);
+      functions.addAssetsToAlbum(config.albumIds[0], [assetId]);
       return {};
     }
 
-    functions.addAssetsToAlbums({ albumIds: config.albumIds, assetIds: [data.asset.id] });
+    functions.addAssetsToAlbums({ albumIds: config.albumIds, assetIds: [assetId] });
     return {};
   });
 };

packages/plugin-sdk/package.json

@@ -2,7 +2,6 @@
   "name": "@immich/plugin-sdk",
   "version": "0.0.0",
   "description": "",
-  "main": "index.js",
   "type": "module",
   "exports": {
     "./host-functions": {
@@ -11,7 +10,8 @@
     },
     ".": {
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {

packages/plugin-sdk/src/enum.ts

@@ -1,33 +0,0 @@
-export enum WorkflowTrigger {
-  AssetCreate = 'AssetCreate',
-  PersonRecognized = 'PersonRecognized',
-}
-
-export enum WorkflowType {
-  AssetV1 = 'AssetV1',
-  AssetPersonV1 = 'AssetPersonV1',
-}
-
-export enum AssetType {
-  Image = 'IMAGE',
-  Video = 'VIDEO',
-  Audio = 'AUDIO',
-  Other = 'OTHER',
-}
-
-export enum AssetStatus {
-  Active = 'active',
-  Trashed = 'trashed',
-  Deleted = 'deleted',
-}
-
-export enum AssetVisibility {
-  Archive = 'archive',
-  Timeline = 'timeline',
-
-  /**
-   * Video part of the LivePhotos and MotionPhotos
-   */
-  Hidden = 'hidden',
-  Locked = 'locked',
-}

packages/plugin-sdk/src/host-functions.ts

@@ -1,15 +1,26 @@
-import { type BulkIdResponseDto, type BulkIdsDto } from '@immich/sdk';
+import {
+  getAllAlbums,
+  type AlbumResponseDto,
+  type BulkIdResponseDto,
+  type BulkIdsDto,
+  type CreateAlbumDto,
+} from '@immich/sdk';
 
 // keep in sync with plugin-core/src/index.d.ts';
 declare module 'extism:host' {
   interface user {
-    albumAddAssets(ptr: PTR): I64;
+    searchAlbums(ptr: PTR): I64;
+    createAlbum(ptr: PTR): I64;
+    addAssetsToAlbum(ptr: PTR): I64;
     addAssetsToAlbums(ptr: PTR): I64;
   }
 }
 
-const host = Host.getFunctions();
-type HostFunctionName = keyof typeof host;
+type AlbumsToAssets = {
+  assetIds: string[];
+  albumIds: string[];
+};
+
 type HostFunctionSuccessResult<T> = { success: true; response: T };
 type HostFunctionErrorResult = {
   success: false;
@@ -20,39 +31,49 @@ type HostFunctionResult<T> =
   | HostFunctionSuccessResult<T>
   | HostFunctionErrorResult;
 
-const call = <T, R>(name: HostFunctionName, authToken: string, args: T) => {
-  const pointer1 = Memory.fromString(JSON.stringify({ authToken, args }));
-  const fn = host[name];
-  const handler = Memory.find(fn(pointer1.offset));
+type QueryParams<T extends (...args: any) => any> = Parameters<T>[0];
+type AlbumSearchDto = QueryParams<typeof getAllAlbums>;
 
-  try {
-    const result = JSON.parse(handler.readString()) as HostFunctionResult<R>;
+export const hostFunctions = (authToken: string) => {
+  const host = Host.getFunctions();
+  type HostFunctionName = keyof typeof host;
 
-    if (result.success) {
-      return result.response;
+  const call = <T, R>(name: HostFunctionName, authToken: string, args: T) => {
+    const pointer1 = Memory.fromString(JSON.stringify({ authToken, args }));
+    const fn = host[name];
+    const handler = Memory.find(fn(pointer1.offset));
+
+    try {
+      const result = JSON.parse(handler.readString()) as HostFunctionResult<R>;
+
+      if (result.success) {
+        return result.response;
+      }
+
+      throw new Error(
+        `Failed to call host function "${String(name)}", received ${result.status} - ${JSON.stringify(result.message)}`,
+      );
+    } finally {
+      handler.free();
+      pointer1.free();
     }
+  };
 
-    throw new Error(
-      `Failed to call host function "${String(name)}", received ${result.status} - ${JSON.stringify(result.message)}`,
-    );
-  } finally {
-    handler.free();
-    pointer1.free();
-  }
+  return {
+    // album
+    searchAlbums: (dto: AlbumSearchDto) =>
+      call<[AlbumSearchDto], AlbumResponseDto[]>('searchAlbums', authToken, [
+        dto,
+      ]),
+    createAlbum: (dto: CreateAlbumDto) =>
+      call<[CreateAlbumDto], AlbumResponseDto>('createAlbum', authToken, [dto]),
+    addAssetsToAlbum: (albumId: string, assetIds: string[]) =>
+      call<[string, BulkIdsDto], BulkIdResponseDto[]>(
+        'addAssetsToAlbum',
+        authToken,
+        [albumId, { ids: assetIds }],
+      ),
+    addAssetsToAlbums: ({ assetIds, albumIds }: AlbumsToAssets) =>
+      call('addAssetsToAlbums', authToken, [{ albumIds, assetIds }]),
+  };
 };
-
-type AlbumsToAssets = {
-  assetIds: string[];
-  albumIds: string[];
-};
-
-export const hostFunctions = (authToken: string) => ({
-  albumAddAssets: (albumId: string, assetIds: string[]) =>
-    call<[string, BulkIdsDto], BulkIdResponseDto[]>(
-      'albumAddAssets',
-      authToken,
-      [albumId, { ids: assetIds }],
-    ),
-  addAssetsToAlbums: ({ assetIds, albumIds }: AlbumsToAssets) =>
-    call('addAssetsToAlbums', authToken, [{ albumIds, assetIds }]),
-});

packages/plugin-sdk/src/index.ts

@@ -1,4 +1,3 @@
-export * from 'src/enum.js';
 export * from 'src/host-functions.js';
 export * from 'src/sdk.js';
 export * from 'src/types.js';

packages/plugin-sdk/src/sdk.ts

@@ -1,9 +1,10 @@
-import type { WorkflowType } from 'src/enum.js';
+import type { WorkflowType } from '@immich/sdk';
 import { hostFunctions } from 'src/host-functions.js';
 import type {
   ConfigValue,
   WorkflowEventPayload,
   WorkflowResponse,
+  WorkflowStepConfig,
 } from 'src/types.js';
 
 export const wrapper = <
@@ -19,19 +20,28 @@ export const wrapper = <
   const input = Host.inputString();
 
   try {
-    const event = JSON.parse(input) as WorkflowEventPayload<T, TConfig>;
-    // const debug = event.workflow.debug ?? false;
+    const payload = JSON.parse(input) as WorkflowEventPayload<T, TConfig>;
+    const event = {
+      ...payload,
+      functions: hostFunctions(payload.workflow.authToken),
+    };
+
+    const eventConfigBefore = JSON.stringify(event.config);
 
     console.debug(
-      `Inputs: trigger=${event.trigger}, event=${event.type}, config=${JSON.stringify(event.config)}`,
+      `Inputs: trigger=${event.trigger}, event=${event.type}, config=${eventConfigBefore}`,
     );
 
-    const response =
-      fn({ ...event, functions: hostFunctions(event.workflow.authToken) }) ??
-      {};
+    const response = fn(event) ?? {};
+
+    // if config changed, notify host
+    const eventConfigAfter = JSON.stringify(event.config);
+    if (!response.config && eventConfigBefore !== eventConfigAfter) {
+      response.config = event.config as WorkflowStepConfig;
+    }
 
     console.debug(
-      `Outputs: workflow=${JSON.stringify(response.workflow)}, changes=${JSON.stringify(response.changes)}, data=${JSON.stringify(response.data)}`,
+      `Outputs: workflow=${JSON.stringify(response.workflow)}, changes=${JSON.stringify(response.changes)}, data=${JSON.stringify(response.data)}, config=${JSON.stringify(response.config)}`,
     );
 
     const output = JSON.stringify(response);

packages/plugin-sdk/src/types.ts

@@ -1,10 +1,4 @@
-import type {
-  AssetStatus,
-  AssetType,
-  AssetVisibility,
-  WorkflowTrigger,
-  WorkflowType,
-} from 'src/enum.js';
+import type { AssetTypeEnum, AssetVisibility, WorkflowType } from '@immich/sdk';
 
 type DeepPartial<T> = T extends Date
   ? T
@@ -21,6 +15,12 @@ export type WorkflowEventMap = {
 
 export type WorkflowEventData<T extends WorkflowType> = WorkflowEventMap[T];
 
+export enum WorkflowTrigger {
+  AssetCreate = 'AssetCreate',
+  AssetMetadataExtraction = 'AssetMetadataExtraction',
+  PersonRecognized = 'PersonRecognized',
+}
+
 export type WorkflowEventPayload<
   T extends WorkflowType = WorkflowType,
   TConfig = WorkflowStepConfig,
@@ -48,6 +48,8 @@ export type WorkflowResponse<T extends WorkflowType = WorkflowType> = {
   changes?: WorkflowChanges<T>;
   /** data to be passed to the next workflow step */
   data?: Record<string, unknown>;
+  /** update step config */
+  config?: WorkflowStepConfig;
 };
 
 export type WorkflowStepConfig = {
@@ -66,7 +68,7 @@ export type AssetV1 = {
   asset: {
     id: string;
     ownerId: string;
-    type: AssetType;
+    type: AssetTypeEnum;
     originalPath: string;
     fileCreatedAt: string;
     fileModifiedAt: string;
@@ -83,7 +85,6 @@ export type AssetV1 = {
     localDateTime: string;
     stackId: string | null;
     duplicateId: string | null;
-    status: AssetStatus;
     visibility: AssetVisibility;
     isEdited: boolean;
     exifInfo: {

packages/sdk/src/fetch-client.ts

@@ -7081,6 +7081,7 @@ export enum WorkflowType {
 }
 export enum WorkflowTrigger {
     AssetCreate = "AssetCreate",
+    AssetMetadataExtraction = "AssetMetadataExtraction",
     PersonRecognized = "PersonRecognized"
 }
 export enum QueueJobStatus {