Merge remote-tracking branch 'origin/main' into feat/yucca-integration

packages/cli/package.json

@@ -25,7 +25,7 @@
     "@types/lodash-es": "^4.17.12",
     "@types/micromatch": "^4.0.9",
     "@types/mock-fs": "^4.13.1",
-    "@types/node": "^24.12.2",
+    "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "^4.0.0",
     "byte-size": "^9.0.0",
     "cli-progress": "^3.12.0",

packages/e2e-auth-server/package.json

@@ -13,5 +13,5 @@
     "oidc-provider": "^9.0.0",
     "tsx": "^4.20.6"
   },
-  "packageManager": "pnpm@10.33.1"
+  "packageManager": "pnpm@10.33.4"
 }

packages/plugin-core/manifest.json

@@ -5,6 +5,58 @@
   "description": "Core workflow capabilities for Immich",
   "author": "Immich Team",
   "wasmPath": "dist/plugin.wasm",
+  "templates": [
+    {
+      "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": [
+        {
+          "method": "immich-plugin-core#assetFileFilter",
+          "config": {
+            "pattern": "screenshot",
+            "matchType": "contains",
+            "caseSensitive": false
+          }
+        },
+        {
+          "method": "immich-plugin-core#assetArchive",
+          "config": {
+            "inverse": false
+          }
+        },
+        {
+          "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": []
+          }
+        }
+      ],
+      "uiHints": ["SmartAlbum"]
+    }
+  ],
   "methods": [
     {
       "name": "assetFileFilter",
@@ -35,7 +87,25 @@
         },
         "required": ["pattern"]
       },
-      "uiHints": ["filter"]
+      "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",
@@ -55,7 +125,7 @@
         },
         "required": ["fileTypes"]
       },
-      "uiHints": ["filter"]
+      "uiHints": ["Filter"]
     },
     {
       "name": "filterPerson",
@@ -69,7 +139,7 @@
             "array": true,
             "title": "Person IDs",
             "description": "List of person to match",
-            "uiHint": "personI"
+            "uiHint": "personId"
           },
           "matchAny": {
             "type": "boolean",
@@ -80,7 +150,7 @@
         },
         "required": ["personIds"]
       },
-      "uiHints": ["filter"]
+      "uiHints": ["Filter"]
     },
     {
       "name": "assetArchive",
@@ -157,7 +227,13 @@
             "title": "Album IDs",
             "array": true,
             "description": "Target album IDs",
-            "uiHint": "albumId"
+            "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"]
@@ -242,14 +318,14 @@
             "type": "string",
             "title": "Album ID",
             "description": "Target album ID",
-            "uiHint": "albumId"
+            "uiHint": "AlbumId"
           },
           "albumIds": {
             "type": "string",
             "title": "Album IDs",
             "description": "Target album IDs",
             "array": true,
-            "uiHint": "albumId"
+            "uiHint": "AlbumId"
           }
         }
       }

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,23 +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(), 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) {
+      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": {
@@ -24,11 +24,12 @@
   "keywords": [],
   "author": "",
   "license": "GNU Affero General Public License version 3",
-  "packageManager": "pnpm@10.30.3",
+  "packageManager": "pnpm@10.33.4",
   "devDependencies": {
     "@extism/js-pdk": "^1.1.1",
-    "@types/node": "^24.11.0",
-    "esbuild": "^0.27.3",
+    "@immich/sdk": "workspace:*",
+    "@types/node": "^24.12.4",
+    "esbuild": "^0.28.0",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.9.3"
   },

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,12 +1,26 @@
+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;
@@ -17,35 +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('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,24 +68,23 @@ export type AssetV1 = {
   asset: {
     id: string;
     ownerId: string;
-    type: AssetType;
+    type: AssetTypeEnum;
     originalPath: string;
-    fileCreatedAt: Date;
-    fileModifiedAt: Date;
+    fileCreatedAt: string;
+    fileModifiedAt: string;
     isFavorite: boolean;
     checksum: Buffer; // sha1 checksum
     livePhotoVideoId: string | null;
-    updatedAt: Date;
-    createdAt: Date;
+    updatedAt: string;
+    createdAt: string;
     originalFileName: string;
     isOffline: boolean;
     libraryId: string | null;
     isExternal: boolean;
-    deletedAt: Date | null;
-    localDateTime: Date;
+    deletedAt: string | null;
+    localDateTime: string;
     stackId: string | null;
     duplicateId: string | null;
-    status: AssetStatus;
     visibility: AssetVisibility;
     isEdited: boolean;
     exifInfo: {
@@ -93,8 +94,8 @@ export type AssetV1 = {
       exifImageHeight: number | null;
       fileSizeInByte: number | null;
       orientation: string | null;
-      dateTimeOriginal: Date | null;
-      modifyDate: Date | null;
+      dateTimeOriginal: string | null;
+      modifyDate: string | null;
       lensModel: string | null;
       fNumber: number | null;
       focalLength: number | null;
@@ -116,7 +117,7 @@ export type AssetV1 = {
       autoStackId: string | null;
       rating: number | null;
       tags: string[] | null;
-      updatedAt: Date | null;
+      updatedAt: string | null;
     } | null;
   };
 };

packages/sdk/package.json

@@ -24,7 +24,7 @@
     "@oazapfts/runtime": "^1.0.2"
   },
   "devDependencies": {
-    "@types/node": "^24.12.2",
+    "@types/node": "^24.12.4",
     "typescript": "^6.0.0"
   }
 }

packages/sdk/src/fetch-client.ts

@@ -1514,6 +1514,30 @@ export type PluginResponseDto = {
     /** Plugin version */
     version: string;
 };
+export type PluginTemplateStepResponseDto = {
+    /** Step configuration */
+    config: {
+        [key: string]: any;
+    } | null;
+    /** Whether the step is enabled */
+    enabled?: boolean;
+    /** Step plugin method */
+    method: string;
+};
+export type PluginTemplateResponseDto = {
+    /** Template description */
+    description: string;
+    /** Template key (unique across all templates) */
+    key: string;
+    /** Workflow steps */
+    steps: PluginTemplateStepResponseDto[];
+    /** Template title */
+    title: string;
+    /** Workflow trigger */
+    trigger: WorkflowTrigger;
+    /** Ui hints, for example "smart-album" */
+    uiHints: string[];
+};
 export type QueueResponseDto = {
     /** Whether the queue is paused */
     isPaused: boolean;
@@ -2590,9 +2614,9 @@ export type TagUpdateDto = {
 };
 export type TimeBucketAssetResponseDto = {
     /** Array of city names extracted from EXIF GPS data */
-    city: (string | null)[];
+    city?: (string | null)[];
     /** Array of country names extracted from EXIF GPS data */
-    country: (string | null)[];
+    country?: (string | null)[];
     /** Array of UTC timestamps when each asset was originally uploaded to Immich */
     createdAt: string[];
     /** Array of video/gif durations in milliseconds (null for static images) */
@@ -3805,18 +3829,22 @@ export function getUserStatisticsAdmin({ id, isFavorite, isTrashed, visibility }
 /**
  * List all albums
  */
-export function getAllAlbums({ assetId, isOwned, isShared }: {
+export function getAllAlbums({ assetId, id, isOwned, isShared, name }: {
     assetId?: string;
+    id?: string;
     isOwned?: boolean;
     isShared?: boolean;
+    name?: string;
 }, opts?: Oazapfts.RequestOpts) {
     return oazapfts.ok(oazapfts.fetchJson<{
         status: 200;
         data: AlbumResponseDto[];
     }>(`/albums${QS.query(QS.explode({
         assetId,
+        id,
         isOwned,
-        isShared
+        isShared,
+        name
     }))}`, {
         ...opts
     }));
@@ -5472,6 +5500,17 @@ export function searchPluginMethods({ description, enabled, id, name, pluginName
         ...opts
     }));
 }
+/**
+ * Retrieve workflow templates
+ */
+export function searchPluginTemplates(opts?: Oazapfts.RequestOpts) {
+    return oazapfts.ok(oazapfts.fetchJson<{
+        status: 200;
+        data: PluginTemplateResponseDto[];
+    }>("/plugins/templates", {
+        ...opts
+    }));
+}
 /**
  * Retrieve a plugin
  */
@@ -7627,6 +7666,7 @@ export enum WorkflowType {
 }
 export enum WorkflowTrigger {
     AssetCreate = "AssetCreate",
+    AssetMetadataExtraction = "AssetMetadataExtraction",
     PersonRecognized = "PersonRecognized"
 }
 export enum QueueJobStatus {
@@ -7692,7 +7732,7 @@ export enum JobName {
     VersionCheck = "VersionCheck",
     OcrQueueAll = "OcrQueueAll",
     Ocr = "Ocr",
-    WorkflowAssetCreate = "WorkflowAssetCreate"
+    WorkflowAssetTrigger = "WorkflowAssetTrigger"
 }
 export enum SearchSuggestionType {
     Country = "country",