@aglyn/aglyn 1.0.0-beta.282 → 1.0.0-beta.284

package/src/lib/app-utils/stock-photos/stock-photo-picker-server.js

@@ -0,0 +1,333 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { pluginMediaIngest } from "../../plugin-manager/plugin-media-ingest.js";
+import { stockPhotoProvider, stockPhotoSourceKey } from "../../plugin-manager/stock-photo-provider.js";
+import { normalizeStockPhotoQuery, STOCK_PHOTO_GONE_MESSAGE, stockPhotoHitRefOf, stockPhotoOrientationOf, stockPhotoPickerMediaOf, stockPhotoSafeLink, STOCK_PHOTOS_UNCONFIGURED_MESSAGE, stockPhotosBusyMessage, stockPhotoTargetOf } from "./stock-photo-picker.js";
+/**
+ * The server half of the media picker's Stock photos tab (AGL-4066). The
+ * console's route verifies the caller and hands this the request body with
+ * two doors of its own: {@link StockPhotoPickerServerDeps.authorize}, the
+ * same scope check an upload makes (the member may add files to that
+ * library, the lockdown's uploads gate), and
+ * {@link StockPhotoPickerServerDeps.readMedia}, the stored document. The rest
+ * is here, against core's contracts alone:
+ *
+ * - `status` — whether a library is configured, and its name.
+ * - `search` — the provider's own search, its 24-hour cache and its rate
+ *   limit in charge. A `null` answer (rate-limited, or the library down) is
+ *   `busy`, a state the tab shows, never a 5xx: a library's bad minute is
+ *   not a fault of the console's.
+ * - `preview` — a hit's small copy, as bytes, so no browser loads an
+ *   address at the library.
+ * - `import` — the photo copied into the library through `core.media-ingest`
+ *   as the member, which makes the upload's own checks (access, lockdown,
+ *   structure, takedowns, plan and storage band). A copy the library already
+ *   holds under the photo's source key is placed instead, never stored a
+ *   second time. The credit rides the asset as the AI build writes it:
+ *   `description` "Photo by … on …" and `stockPhoto` with the photographer,
+ *   the photo's page and the license.
+ *
+ * A hit is found again by the search that found it, which the provider
+ * answers from its cache, so the addresses and the credit are always the
+ * provider's own and never what a browser sent.
+ */ /** The largest stored copy a photo may be. */ export const STOCK_PHOTO_IMPORT_MAX_BYTES = 10 * 1024 * 1024;
+/** The largest preview handed to a browser. */ export const STOCK_PHOTO_PREVIEW_MAX_BYTES = 2 * 1024 * 1024;
+/** How long a browser may keep a preview. */ const PREVIEW_CACHE_CONTROL = 'private, max-age=3600';
+/** How long one process keeps a search's photos to find hits again in, before asking the provider. */ export const STOCK_PHOTO_HIT_MEMO_MS = 5 * 60 * 1000;
+/** Searches one process keeps in that memo. */ const HIT_MEMO_SIZE = 50;
+/** The tags a hit shows. */ const HIT_TAGS = 8;
+/** The file extension a stored copy is named with, by type. */ const EXTENSIONS = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/webp': 'webp',
+    'image/gif': 'gif'
+};
+/** A memo of the last {@link HIT_MEMO_SIZE} searches, each kept {@link STOCK_PHOTO_HIT_MEMO_MS}. */ export function createStockPhotoHitMemo(now = Date.now) {
+    const held = new Map();
+    return {
+        get (key) {
+            const entry = held.get(key);
+            if (!entry) return null;
+            if (now() - entry.at > STOCK_PHOTO_HIT_MEMO_MS) {
+                held.delete(key);
+                return null;
+            }
+            return entry.photos;
+        },
+        set (key, photos) {
+            held.delete(key);
+            held.set(key, {
+                at: now(),
+                photos
+            });
+            while(held.size > HIT_MEMO_SIZE)held.delete(held.keys().next().value);
+        }
+    };
+}
+const processMemo = createStockPhotoHitMemo();
+const json = (body, status = 200)=>Response.json(body, {
+        status,
+        headers: {
+            'Cache-Control': 'no-store'
+        }
+    });
+const refused = (status, message)=>json({
+        status: 'refused',
+        message
+    }, status);
+/** The memo's key for a search. */ const memoKey = (provider, ref)=>`${provider.id}\n${ref.orientation}\n${ref.query.toLowerCase()}`;
+/** A provider's hit as the tab shows it. */ export function stockPhotoPickerHitOf(provider, photo, search) {
+    var _photo_tags;
+    const pageUrl = stockPhotoSafeLink(photo.pageUrl);
+    if (!photo.id || !pageUrl || !(photo.width > 0) || !(photo.height > 0)) return null;
+    const credit = provider.credit(photo);
+    const licenseUrl = stockPhotoSafeLink(credit.licenseUrl);
+    const photographerUrl = stockPhotoSafeLink(photo.photographerUrl);
+    return _extends({
+        ref: {
+            query: search.query,
+            orientation: search.orientation,
+            id: photo.id
+        },
+        sourceKey: stockPhotoSourceKey(photo),
+        width: photo.width,
+        height: photo.height,
+        photographer: photo.photographer
+    }, photographerUrl ? {
+        photographerUrl
+    } : {}, {
+        pageUrl,
+        tags: ((_photo_tags = photo.tags) != null ? _photo_tags : []).slice(0, HIT_TAGS)
+    }, photo.alt ? {
+        alt: photo.alt
+    } : {}, {
+        credit: credit.text,
+        license: credit.license,
+        licenseUrl: licenseUrl != null ? licenseUrl : '',
+        attributionRequired: credit.attributionRequired
+    });
+}
+/**
+ * What the stored copy of `photo` is sent to the media library as: the
+ * shape the AI build's copies take, so every stock asset carries one credit.
+ */ export function stockPhotoPickerIngestRequest(input) {
+    var _target_hostId, _EXTENSIONS_bytes_contentType;
+    const { photo, bytes, target } = input;
+    const credit = input.provider.credit(photo);
+    const photographerUrl = stockPhotoSafeLink(photo.photographerUrl);
+    return _extends({
+        hostId: (_target_hostId = target.hostId) != null ? _target_hostId : ''
+    }, target.orgId ? {
+        orgId: target.orgId
+    } : {}, {
+        uid: input.uid,
+        fileName: `${photo.provider}-${photo.id}.${(_EXTENSIONS_bytes_contentType = EXTENSIONS[bytes.contentType]) != null ? _EXTENSIONS_bytes_contentType : 'jpg'}`,
+        contentType: bytes.contentType,
+        bytes: bytes.bytes
+    }, photo.alt ? {
+        alt: photo.alt
+    } : {}, {
+        description: credit.text
+    }, input.folderId ? {
+        folderId: input.folderId
+    } : {}, {
+        stockPhoto: _extends({
+            key: stockPhotoSourceKey(photo),
+            provider: photo.provider,
+            providerLabel: credit.providerLabel,
+            id: photo.id,
+            pageUrl: photo.pageUrl,
+            photographer: photo.photographer
+        }, photographerUrl ? {
+            photographerUrl
+        } : {}, {
+            license: credit.license,
+            licenseUrl: credit.licenseUrl,
+            attributionRequired: credit.attributionRequired,
+            query: input.query
+        })
+    });
+}
+/** The photo `ref` names, found again in its search; `null` when the provider cannot be asked, `false` when it is gone. */ async function findHit(provider, ref, memo, signal) {
+    var _photos_find;
+    const key = memoKey(provider, ref);
+    let photos = memo.get(key);
+    if (!photos) {
+        const answer = await provider.search({
+            query: ref.query,
+            orientation: ref.orientation
+        }, signal ? {
+            signal
+        } : undefined);
+        if (!answer) return null;
+        photos = answer.photos;
+        memo.set(key, photos);
+    }
+    return (_photos_find = photos.find((photo)=>photo.id === ref.id)) != null ? _photos_find : false;
+}
+/** Answers one request of the Stock photos tab. Never throws for the library's sake. */ export async function answerStockPhotoPickerRequest(body, deps) {
+    var _deps_provider, _deps_memo, _deps_ingest, _target_hostId;
+    const record = body != null ? body : {};
+    const action = record['action'];
+    if (action !== 'status' && action !== 'search' && action !== 'preview' && action !== 'import') {
+        return refused(400, 'Unknown request');
+    }
+    const target = stockPhotoTargetOf(record);
+    if (!target) return refused(400, 'Name the site or the workspace whose library to use');
+    const denied = await deps.authorize(target);
+    if (denied) return denied;
+    const provider = ((_deps_provider = deps.provider) != null ? _deps_provider : stockPhotoProvider)();
+    if (!provider) {
+        if (action === 'preview') return new Response(null, {
+            status: 204
+        });
+        return json({
+            status: 'unconfigured',
+            message: STOCK_PHOTOS_UNCONFIGURED_MESSAGE
+        });
+    }
+    const library = {
+        label: provider.label
+    };
+    const memo = (_deps_memo = deps.memo) != null ? _deps_memo : processMemo;
+    const signal = deps.signal;
+    if (action === 'status') return json({
+        status: 'ready',
+        library
+    });
+    if (action === 'search') {
+        const query = normalizeStockPhotoQuery(record['query']);
+        if (!query) return refused(400, 'Type a few words to search for, up to 100 characters');
+        const orientation = stockPhotoOrientationOf(record['orientation']);
+        let answer = null;
+        try {
+            answer = await provider.search({
+                query,
+                orientation
+            }, signal ? {
+                signal
+            } : undefined);
+        } catch (error) {
+            console.warn('stock photos: the search failed', {
+                provider: provider.id,
+                error: String(error).slice(0, 160)
+            });
+        }
+        if (!answer) return json({
+            status: 'busy',
+            message: stockPhotosBusyMessage(provider.label)
+        });
+        memo.set(memoKey(provider, {
+            query,
+            orientation
+        }), answer.photos);
+        const hits = answer.photos.map((photo)=>stockPhotoPickerHitOf(provider, photo, {
+                query,
+                orientation
+            })).filter((hit)=>hit !== null);
+        return json({
+            status: 'ok',
+            library,
+            query,
+            orientation,
+            hits
+        });
+    }
+    const ref = stockPhotoHitRefOf(record['ref']);
+    if (!ref) return refused(400, 'That photo could not be read. Search again and choose it from the results.');
+    let photo = null;
+    try {
+        photo = await findHit(provider, ref, memo, signal);
+    } catch (error) {
+        console.warn('stock photos: a search to find a photo again failed', {
+            provider: provider.id,
+            error: String(error).slice(0, 160)
+        });
+    }
+    if (action === 'preview') {
+        if (!photo || typeof provider.preview !== 'function') return new Response(null, {
+            status: 204
+        });
+        const small = await provider.preview(photo, _extends({
+            maxBytes: STOCK_PHOTO_PREVIEW_MAX_BYTES
+        }, signal ? {
+            signal
+        } : {})).catch(()=>null);
+        if (!small) return new Response(null, {
+            status: 204
+        });
+        return new Response(new Uint8Array(small.bytes), {
+            status: 200,
+            headers: {
+                'Content-Type': small.contentType,
+                'Cache-Control': PREVIEW_CACHE_CONTROL,
+                'X-Content-Type-Options': 'nosniff'
+            }
+        });
+    }
+    // import
+    if (photo === null) return json({
+        status: 'busy',
+        message: stockPhotosBusyMessage(provider.label)
+    });
+    if (photo === false) return json({
+        status: 'gone',
+        message: STOCK_PHOTO_GONE_MESSAGE
+    }, 404);
+    const ingest = ((_deps_ingest = deps.ingest) != null ? _deps_ingest : pluginMediaIngest)();
+    if (!ingest) return refused(503, 'The media library cannot take photos this way right now. Try again in a minute.');
+    const sourceKey = stockPhotoSourceKey(photo);
+    const placed = async (mediaId, reused)=>{
+        const data = await deps.readMedia(target, mediaId);
+        if (!data) return refused(500, 'The photo was stored but could not be read back. It is in the library; choose it there.');
+        return json({
+            status: 'ok',
+            reused,
+            media: stockPhotoPickerMediaOf(mediaId, data)
+        });
+    };
+    const held = await ingest.findStockPhoto(_extends({
+        hostId: (_target_hostId = target.hostId) != null ? _target_hostId : '',
+        sourceKey
+    }, target.orgId ? {
+        orgId: target.orgId
+    } : {}));
+    if (held) return placed(held.mediaId, true);
+    const bytes = await provider.download(photo, _extends({
+        maxBytes: STOCK_PHOTO_IMPORT_MAX_BYTES
+    }, signal ? {
+        signal
+    } : {})).catch(()=>null);
+    if (!bytes) return json({
+        status: 'busy',
+        message: stockPhotosBusyMessage(provider.label)
+    });
+    const folderId = typeof record['folderId'] === 'string' && record['folderId'] ? String(record['folderId']).slice(0, 64) : null;
+    const stored = await ingest.ingest(stockPhotoPickerIngestRequest({
+        provider,
+        target,
+        uid: deps.uid,
+        photo,
+        bytes,
+        query: ref.query,
+        folderId
+    }));
+    if (stored.ok === false) return refused(stored.status >= 400 ? stored.status : 500, stored.reason);
+    return placed(stored.mediaId, false);
+}
+
+//# sourceMappingURL=stock-photo-picker-server.js.map

package/src/lib/app-utils/stock-photos/stock-photo-picker-server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/app-utils/stock-photos/stock-photo-picker-server.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  pluginMediaIngest,\n  type PluginMediaIngest,\n  type PluginMediaIngestRequest,\n} from '../../plugin-manager/plugin-media-ingest'\nimport {\n  stockPhotoProvider,\n  stockPhotoSourceKey,\n  type StockPhoto,\n  type StockPhotoProvider,\n} from '../../plugin-manager/stock-photo-provider'\nimport {\n  normalizeStockPhotoQuery,\n  STOCK_PHOTO_GONE_MESSAGE,\n  stockPhotoHitRefOf,\n  stockPhotoOrientationOf,\n  stockPhotoPickerMediaOf,\n  stockPhotoSafeLink,\n  STOCK_PHOTOS_UNCONFIGURED_MESSAGE,\n  stockPhotosBusyMessage,\n  stockPhotoTargetOf,\n  type StockPhotoHitRef,\n  type StockPhotoImportAnswer,\n  type StockPhotoPickerHit,\n  type StockPhotoPickerTarget,\n  type StockPhotoSearchAnswer,\n  type StockPhotoStatusAnswer,\n} from './stock-photo-picker'\n\n/**\n * The server half of the media picker's Stock photos tab (AGL-4066). The\n * console's route verifies the caller and hands this the request body with\n * two doors of its own: {@link StockPhotoPickerServerDeps.authorize}, the\n * same scope check an upload makes (the member may add files to that\n * library, the lockdown's uploads gate), and\n * {@link StockPhotoPickerServerDeps.readMedia}, the stored document. The rest\n * is here, against core's contracts alone:\n *\n * - `status` — whether a library is configured, and its name.\n * - `search` — the provider's own search, its 24-hour cache and its rate\n *   limit in charge. A `null` answer (rate-limited, or the library down) is\n *   `busy`, a state the tab shows, never a 5xx: a library's bad minute is\n *   not a fault of the console's.\n * - `preview` — a hit's small copy, as bytes, so no browser loads an\n *   address at the library.\n * - `import` — the photo copied into the library through `core.media-ingest`\n *   as the member, which makes the upload's own checks (access, lockdown,\n *   structure, takedowns, plan and storage band). A copy the library already\n *   holds under the photo's source key is placed instead, never stored a\n *   second time. The credit rides the asset as the AI build writes it:\n *   `description` \"Photo by … on …\" and `stockPhoto` with the photographer,\n *   the photo's page and the license.\n *\n * A hit is found again by the search that found it, which the provider\n * answers from its cache, so the addresses and the credit are always the\n * provider's own and never what a browser sent.\n */\n\n/** The largest stored copy a photo may be. */\nexport const STOCK_PHOTO_IMPORT_MAX_BYTES = 10 * 1024 * 1024\n/** The largest preview handed to a browser. */\nexport const STOCK_PHOTO_PREVIEW_MAX_BYTES = 2 * 1024 * 1024\n/** How long a browser may keep a preview. */\nconst PREVIEW_CACHE_CONTROL = 'private, max-age=3600'\n/** How long one process keeps a search's photos to find hits again in, before asking the provider. */\nexport const STOCK_PHOTO_HIT_MEMO_MS = 5 * 60 * 1000\n/** Searches one process keeps in that memo. */\nconst HIT_MEMO_SIZE = 50\n/** The tags a hit shows. */\nconst HIT_TAGS = 8\n/** The file extension a stored copy is named with, by type. */\nconst EXTENSIONS: Readonly<Record<string, string>> = {\n  'image/jpeg': 'jpg',\n  'image/png': 'png',\n  'image/webp': 'webp',\n  'image/gif': 'gif',\n}\n\nexport interface StockPhotoPickerServerDeps {\n  /** The signed-in member. */\n  uid: string\n  /**\n   * `null` when the member may add files to `target`'s library; otherwise\n   * the refusal to answer with (401, 403, 404, 423 …).\n   */\n  authorize(target: StockPhotoPickerTarget): Promise<Response | null>\n  /** The stored media document `mediaId` in `target`'s library, or `null`. */\n  readMedia(target: StockPhotoPickerTarget, mediaId: string): Promise<Record<string, unknown> | null>\n  provider?: () => StockPhotoProvider | null\n  ingest?: () => PluginMediaIngest | null\n  memo?: StockPhotoHitMemo\n  signal?: AbortSignal\n}\n\n/** A process's recent searches, to find a hit again without asking the provider. */\nexport interface StockPhotoHitMemo {\n  get(key: string): StockPhoto[] | null\n  set(key: string, photos: StockPhoto[]): void\n}\n\n/** A memo of the last {@link HIT_MEMO_SIZE} searches, each kept {@link STOCK_PHOTO_HIT_MEMO_MS}. */\nexport function createStockPhotoHitMemo(now: () => number = Date.now): StockPhotoHitMemo {\n  const held = new Map<string, { at: number; photos: StockPhoto[] }>()\n  return {\n    get(key) {\n      const entry = held.get(key)\n      if (!entry) return null\n      if (now() - entry.at > STOCK_PHOTO_HIT_MEMO_MS) {\n        held.delete(key)\n        return null\n      }\n      return entry.photos\n    },\n    set(key, photos) {\n      held.delete(key)\n      held.set(key, { at: now(), photos })\n      while (held.size > HIT_MEMO_SIZE) held.delete(held.keys().next().value as string)\n    },\n  }\n}\n\nconst processMemo = createStockPhotoHitMemo()\n\nconst json = (body: unknown, status = 200): Response =>\n  Response.json(body, { status, headers: { 'Cache-Control': 'no-store' } })\n\nconst refused = (status: number, message: string): Response => json({ status: 'refused', message }, status)\n\n/** The memo's key for a search. */\nconst memoKey = (provider: StockPhotoProvider, ref: Pick<StockPhotoHitRef, 'query' | 'orientation'>) =>\n  `${provider.id}\\n${ref.orientation}\\n${ref.query.toLowerCase()}`\n\n/** A provider's hit as the tab shows it. */\nexport function stockPhotoPickerHitOf(\n  provider: Pick<StockPhotoProvider, 'credit'>,\n  photo: StockPhoto,\n  search: Pick<StockPhotoHitRef, 'query' | 'orientation'>,\n): StockPhotoPickerHit | null {\n  const pageUrl = stockPhotoSafeLink(photo.pageUrl)\n  if (!photo.id || !pageUrl || !(photo.width > 0) || !(photo.height > 0)) return null\n  const credit = provider.credit(photo)\n  const licenseUrl = stockPhotoSafeLink(credit.licenseUrl)\n  const photographerUrl = stockPhotoSafeLink(photo.photographerUrl)\n  return {\n    ref: { query: search.query, orientation: search.orientation, id: photo.id },\n    sourceKey: stockPhotoSourceKey(photo),\n    width: photo.width,\n    height: photo.height,\n    photographer: photo.photographer,\n    ...(photographerUrl ? { photographerUrl } : {}),\n    pageUrl,\n    tags: (photo.tags ?? []).slice(0, HIT_TAGS),\n    ...(photo.alt ? { alt: photo.alt } : {}),\n    credit: credit.text,\n    license: credit.license,\n    licenseUrl: licenseUrl ?? '',\n    attributionRequired: credit.attributionRequired,\n  }\n}\n\n/**\n * What the stored copy of `photo` is sent to the media library as: the\n * shape the AI build's copies take, so every stock asset carries one credit.\n */\nexport function stockPhotoPickerIngestRequest(input: {\n  provider: Pick<StockPhotoProvider, 'credit'>\n  target: StockPhotoPickerTarget\n  uid: string\n  photo: StockPhoto\n  bytes: { bytes: Uint8Array; contentType: string }\n  query: string\n  folderId?: string | null\n}): PluginMediaIngestRequest {\n  const { photo, bytes, target } = input\n  const credit = input.provider.credit(photo)\n  const photographerUrl = stockPhotoSafeLink(photo.photographerUrl)\n  return {\n    hostId: target.hostId ?? '',\n    ...(target.orgId ? { orgId: target.orgId } : {}),\n    uid: input.uid,\n    fileName: `${photo.provider}-${photo.id}.${EXTENSIONS[bytes.contentType] ?? 'jpg'}`,\n    contentType: bytes.contentType,\n    bytes: bytes.bytes,\n    ...(photo.alt ? { alt: photo.alt } : {}),\n    description: credit.text,\n    ...(input.folderId ? { folderId: input.folderId } : {}),\n    stockPhoto: {\n      key: stockPhotoSourceKey(photo),\n      provider: photo.provider,\n      providerLabel: credit.providerLabel,\n      id: photo.id,\n      pageUrl: photo.pageUrl,\n      photographer: photo.photographer,\n      ...(photographerUrl ? { photographerUrl } : {}),\n      license: credit.license,\n      licenseUrl: credit.licenseUrl,\n      attributionRequired: credit.attributionRequired,\n      query: input.query,\n    },\n  }\n}\n\n/** The photo `ref` names, found again in its search; `null` when the provider cannot be asked, `false` when it is gone. */\nasync function findHit(\n  provider: StockPhotoProvider,\n  ref: StockPhotoHitRef,\n  memo: StockPhotoHitMemo,\n  signal?: AbortSignal,\n): Promise<StockPhoto | null | false> {\n  const key = memoKey(provider, ref)\n  let photos = memo.get(key)\n  if (!photos) {\n    const answer = await provider.search({ query: ref.query, orientation: ref.orientation }, signal ? { signal } : undefined)\n    if (!answer) return null\n    photos = answer.photos\n    memo.set(key, photos)\n  }\n  return photos.find((photo) => photo.id === ref.id) ?? false\n}\n\n/** Answers one request of the Stock photos tab. Never throws for the library's sake. */\nexport async function answerStockPhotoPickerRequest(\n  body: unknown,\n  deps: StockPhotoPickerServerDeps,\n): Promise<Response> {\n  const record = (body ?? {}) as Record<string, unknown>\n  const action = record['action']\n  if (action !== 'status' && action !== 'search' && action !== 'preview' && action !== 'import') {\n    return refused(400, 'Unknown request')\n  }\n  const target = stockPhotoTargetOf(record)\n  if (!target) return refused(400, 'Name the site or the workspace whose library to use')\n  const denied = await deps.authorize(target)\n  if (denied) return denied\n\n  const provider = (deps.provider ?? stockPhotoProvider)()\n  if (!provider) {\n    if (action === 'preview') return new Response(null, { status: 204 })\n    return json({ status: 'unconfigured', message: STOCK_PHOTOS_UNCONFIGURED_MESSAGE } satisfies StockPhotoStatusAnswer)\n  }\n  const library = { label: provider.label }\n  const memo = deps.memo ?? processMemo\n  const signal = deps.signal\n\n  if (action === 'status') return json({ status: 'ready', library } satisfies StockPhotoStatusAnswer)\n\n  if (action === 'search') {\n    const query = normalizeStockPhotoQuery(record['query'])\n    if (!query) return refused(400, 'Type a few words to search for, up to 100 characters')\n    const orientation = stockPhotoOrientationOf(record['orientation'])\n    let answer: Awaited<ReturnType<StockPhotoProvider['search']>> = null\n    try {\n      answer = await provider.search({ query, orientation }, signal ? { signal } : undefined)\n    } catch (error) {\n      console.warn('stock photos: the search failed', { provider: provider.id, error: String(error).slice(0, 160) })\n    }\n    if (!answer) return json({ status: 'busy', message: stockPhotosBusyMessage(provider.label) } satisfies StockPhotoSearchAnswer)\n    memo.set(memoKey(provider, { query, orientation }), answer.photos)\n    const hits = answer.photos\n      .map((photo) => stockPhotoPickerHitOf(provider, photo, { query, orientation }))\n      .filter((hit): hit is StockPhotoPickerHit => hit !== null)\n    return json({ status: 'ok', library, query, orientation, hits } satisfies StockPhotoSearchAnswer)\n  }\n\n  const ref = stockPhotoHitRefOf(record['ref'])\n  if (!ref) return refused(400, 'That photo could not be read. Search again and choose it from the results.')\n  let photo: StockPhoto | null | false = null\n  try {\n    photo = await findHit(provider, ref, memo, signal)\n  } catch (error) {\n    console.warn('stock photos: a search to find a photo again failed', { provider: provider.id, error: String(error).slice(0, 160) })\n  }\n\n  if (action === 'preview') {\n    if (!photo || typeof provider.preview !== 'function') return new Response(null, { status: 204 })\n    const small = await provider.preview(photo, { maxBytes: STOCK_PHOTO_PREVIEW_MAX_BYTES, ...(signal ? { signal } : {}) }).catch((): null => null)\n    if (!small) return new Response(null, { status: 204 })\n    return new Response(new Uint8Array(small.bytes), {\n      status: 200,\n      headers: { 'Content-Type': small.contentType, 'Cache-Control': PREVIEW_CACHE_CONTROL, 'X-Content-Type-Options': 'nosniff' },\n    })\n  }\n\n  // import\n  if (photo === null) return json({ status: 'busy', message: stockPhotosBusyMessage(provider.label) } satisfies StockPhotoImportAnswer)\n  if (photo === false) return json({ status: 'gone', message: STOCK_PHOTO_GONE_MESSAGE } satisfies StockPhotoImportAnswer, 404)\n  const ingest = (deps.ingest ?? pluginMediaIngest)()\n  if (!ingest) return refused(503, 'The media library cannot take photos this way right now. Try again in a minute.')\n  const sourceKey = stockPhotoSourceKey(photo)\n  const placed = async (mediaId: string, reused: boolean): Promise<Response> => {\n    const data = await deps.readMedia(target, mediaId)\n    if (!data) return refused(500, 'The photo was stored but could not be read back. It is in the library; choose it there.')\n    return json({ status: 'ok', reused, media: stockPhotoPickerMediaOf(mediaId, data) } satisfies StockPhotoImportAnswer)\n  }\n  const held = await ingest.findStockPhoto({\n    hostId: target.hostId ?? '',\n    sourceKey,\n    ...(target.orgId ? { orgId: target.orgId } : {}),\n  })\n  if (held) return placed(held.mediaId, true)\n  const bytes = await provider\n    .download(photo, { maxBytes: STOCK_PHOTO_IMPORT_MAX_BYTES, ...(signal ? { signal } : {}) })\n    .catch((): null => null)\n  if (!bytes) return json({ status: 'busy', message: stockPhotosBusyMessage(provider.label) } satisfies StockPhotoImportAnswer)\n  const folderId = typeof record['folderId'] === 'string' && record['folderId'] ? String(record['folderId']).slice(0, 64) : null\n  const stored = await ingest.ingest(\n    stockPhotoPickerIngestRequest({ provider, target, uid: deps.uid, photo, bytes, query: ref.query, folderId }),\n  )\n  if (stored.ok === false) return refused(stored.status >= 400 ? stored.status : 500, stored.reason)\n  return placed(stored.mediaId, false)\n}\n"],"names":["pluginMediaIngest","stockPhotoProvider","stockPhotoSourceKey","normalizeStockPhotoQuery","STOCK_PHOTO_GONE_MESSAGE","stockPhotoHitRefOf","stockPhotoOrientationOf","stockPhotoPickerMediaOf","stockPhotoSafeLink","STOCK_PHOTOS_UNCONFIGURED_MESSAGE","stockPhotosBusyMessage","stockPhotoTargetOf","STOCK_PHOTO_IMPORT_MAX_BYTES","STOCK_PHOTO_PREVIEW_MAX_BYTES","PREVIEW_CACHE_CONTROL","STOCK_PHOTO_HIT_MEMO_MS","HIT_MEMO_SIZE","HIT_TAGS","EXTENSIONS","createStockPhotoHitMemo","now","Date","held","Map","get","key","entry","at","delete","photos","set","size","keys","next","value","processMemo","json","body","status","Response","headers","refused","message","memoKey","provider","ref","id","orientation","query","toLowerCase","stockPhotoPickerHitOf","photo","search","pageUrl","width","height","credit","licenseUrl","photographerUrl","sourceKey","photographer","tags","slice","alt","text","license","attributionRequired","stockPhotoPickerIngestRequest","input","target","bytes","hostId","orgId","uid","fileName","contentType","description","folderId","stockPhoto","providerLabel","findHit","memo","signal","answer","undefined","find","answerStockPhotoPickerRequest","deps","record","action","denied","authorize","library","label","error","console","warn","String","hits","map","filter","hit","preview","small","maxBytes","catch","Uint8Array","ingest","placed","mediaId","reused","data","readMedia","media","findStockPhoto","download","stored","ok","reason"],"mappings":"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"}

package/src/lib/app-utils/stock-photos/stock-photo-picker.d.ts

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type StockPhotoOrientation } from '../../plugin-manager/stock-photo-provider';
+/**
+ * STOCK PHOTOS IN THE MEDIA PICKER (AGL-4066): the wire between the
+ * console's media picker and its server route, `/api/media/stock-photos`.
+ *
+ * A person editing a site by hand searches the deployment's stock photo
+ * library from the picker's Stock photos tab and places one. The route asks
+ * core's `core.stock-photos` provider and copies the chosen photo into the
+ * library the picker is filing into through `core.media-ingest`, as the
+ * signed-in member; the placed image is always that copy, never an address
+ * at the library. This module is the shapes both sides agree on, the checks
+ * the server makes on what a browser sends, and the browser's client. It
+ * names no library: the provider's own label comes back in every answer.
+ *
+ * Every request names one library, the target: a site's (`hostId`) or the
+ * workspace's shared one (`orgId`). A hit is named back to the server by
+ * {@link StockPhotoHitRef} — the search that found it and its id — never by
+ * the addresses or the credit, so the server finds the photo again in the
+ * provider's own cached answer and nothing a browser claims about a photo
+ * is stored.
+ */
+/** The console route the picker's Stock photos tab talks to. */
+export declare const STOCK_PHOTO_PICKER_ROUTE = "/api/media/stock-photos";
+/** The library a request searches for and copies into. */
+export type StockPhotoPickerTarget = {
+    hostId: string;
+    orgId?: undefined;
+} | {
+    orgId: string;
+    hostId?: undefined;
+};
+/** The orientations the tab offers, in its order. */
+export declare const STOCK_PHOTO_PICKER_ORIENTATIONS: readonly StockPhotoOrientation[];
+/** How a search result names its photo back to the server. */
+export interface StockPhotoHitRef {
+    /** The search words exactly as searched, after {@link normalizeStockPhotoQuery}. */
+    query: string;
+    orientation: StockPhotoOrientation;
+    /** The library's own id for the photo. */
+    id: string;
+}
+/** One photo a search found, as the tab shows it. */
+export interface StockPhotoPickerHit {
+    ref: StockPhotoHitRef;
+    /** `{provider}:{id}`: what the library reuses an earlier copy by. */
+    sourceKey: string;
+    /** The size of the copy that is stored when the photo is used. */
+    width: number;
+    height: number;
+    photographer: string;
+    photographerUrl?: string;
+    /** The photo's page at the library. */
+    pageUrl: string;
+    /** The library's tags, a few, lowercase. */
+    tags: string[];
+    /** The library's own description of the photo, where it writes one. */
+    alt?: string;
+    /** The sentence the stored copy's description carries: "Photo by … on …". */
+    credit: string;
+    license: string;
+    licenseUrl: string;
+    attributionRequired: boolean;
+}
+/** The library the deployment searches, by the name its terms ask for. */
+export interface StockPhotoPickerLibrary {
+    label: string;
+}
+/** What the tab is told when it opens. */
+export type StockPhotoStatusAnswer = {
+    status: 'ready';
+    library: StockPhotoPickerLibrary;
+} | {
+    status: 'unconfigured';
+    message: string;
+} | {
+    status: 'refused';
+    message: string;
+};
+/** What a search answers. `busy`: the library could not be asked just now. */
+export type StockPhotoSearchAnswer = {
+    status: 'ok';
+    library: StockPhotoPickerLibrary;
+    query: string;
+    orientation: StockPhotoOrientation;
+    hits: StockPhotoPickerHit[];
+} | {
+    status: 'busy';
+    message: string;
+} | {
+    status: 'unconfigured';
+    message: string;
+} | {
+    status: 'refused';
+    message: string;
+};
+/**
+ * A stored asset as the picker places it: the media document's own fields,
+ * the ones a library pick hands on.
+ */
+export interface StockPhotoPickerMedia {
+    $id: string;
+    fileName?: string;
+    contentType?: string;
+    sizeBytes?: number;
+    url?: string;
+    cdnPath?: string;
+    folderId?: string | null;
+    alt?: string;
+    description?: string;
+    width?: number;
+    height?: number;
+    variants?: number[];
+    visibleTo?: string[];
+}
+/** What using a photo answers. `reused`: the library already held a copy, which is placed. */
+export type StockPhotoImportAnswer = {
+    status: 'ok';
+    reused: boolean;
+    media: StockPhotoPickerMedia;
+} | {
+    status: 'busy';
+    message: string;
+} | {
+    status: 'gone';
+    message: string;
+} | {
+    status: 'unconfigured';
+    message: string;
+} | {
+    status: 'refused';
+    message: string;
+};
+/** Said when the deployment has no stock photo library. */
+export declare const STOCK_PHOTOS_UNCONFIGURED_MESSAGE: string;
+/** Said when the library could not be asked, or could not send a photo, just now. */
+export declare function stockPhotosBusyMessage(label: string): string;
+/** Said when the photo is no longer among the search's results. */
+export declare const STOCK_PHOTO_GONE_MESSAGE = "That photo is no longer in the search results. Search again and choose it from the new results.";
+/**
+ * The search words as searched: control characters dropped, runs of space
+ * made one, trimmed. `null` when nothing is left or it is longer than
+ * {@link STOCK_PHOTO_QUERY_MAX_CHARS}.
+ */
+export declare function normalizeStockPhotoQuery(value: unknown): string | null;
+/** An orientation the tab offers, `any` for anything else. */
+export declare function stockPhotoOrientationOf(value: unknown): StockPhotoOrientation;
+/** The library a request names, or `null` when it names none, or both. */
+export declare function stockPhotoTargetOf(body: unknown): StockPhotoPickerTarget | null;
+/** The photo a request names, or `null` when it is not one a search could have found. */
+export declare function stockPhotoHitRefOf(value: unknown): StockPhotoHitRef | null;
+/** `value` when it is an https address, else `undefined`: nothing else is ever linked. */
+export declare function stockPhotoSafeLink(value: unknown): string | undefined;
+/** The fields of a stored media document the picker hands on, from the document. */
+export declare function stockPhotoPickerMediaOf(mediaId: string, data: Record<string, unknown>): StockPhotoPickerMedia;
+/** Posts one JSON request to the route, with whatever credentials the caller adds. */
+export type StockPhotoPickerPost = (body: Record<string, unknown>) => Promise<Response>;
+/** The browser's side of the route, for one library. */
+export interface StockPhotoPickerClient {
+    status(): Promise<StockPhotoStatusAnswer>;
+    search(query: string, orientation: StockPhotoOrientation): Promise<StockPhotoSearchAnswer>;
+    /** The hit's small copy, or `null` when none can be had. */
+    preview(ref: StockPhotoHitRef): Promise<Blob | null>;
+    /** Copies the photo into the library, or finds the copy it holds. */
+    importPhoto(ref: StockPhotoHitRef, options?: {
+        folderId?: string | null;
+    }): Promise<StockPhotoImportAnswer>;
+}
+/**
+ * The client for one library. `post` carries the member's credentials: the
+ * console hands in `authorizedFetch` bound to the route.
+ */
+export declare function createStockPhotoPickerClient(post: StockPhotoPickerPost, target: StockPhotoPickerTarget): StockPhotoPickerClient;