@aspan-corporation/ac-shared 1.2.38 → 1.2.40

package/lib/utils/diary.d.ts

@@ -17,6 +17,11 @@ export declare const TAG_DIARY_PREVIEW = "ac:diary:preview";
 export declare const TAG_DIARY_PHOTO = "ac:diary:photo";
 /** One per embedded audio recording: value is the referenced diary key. */
 export declare const TAG_DIARY_AUDIO = "ac:diary:audio";
+/** One per embedded video: value is the referenced media key. Unlike audio,
+ *  diary videos DO run through the full video pipeline (encode + thumbnail),
+ *  so they get their own tag to keep the photo count accurate rather than
+ *  reusing TAG_DIARY_PHOTO. */
+export declare const TAG_DIARY_VIDEO = "ac:diary:video";
 /** Namespace for body word tokens: `ac:text:<word>`. */
 export declare const TEXT_TOKEN_PREFIX = "ac:text:";
 /**

package/lib/utils/diary.js

@@ -18,6 +18,11 @@ export const TAG_DIARY_PREVIEW = "ac:diary:preview";
 export const TAG_DIARY_PHOTO = "ac:diary:photo";
 /** One per embedded audio recording: value is the referenced diary key. */
 export const TAG_DIARY_AUDIO = "ac:diary:audio";
+/** One per embedded video: value is the referenced media key. Unlike audio,
+ *  diary videos DO run through the full video pipeline (encode + thumbnail),
+ *  so they get their own tag to keep the photo count accurate rather than
+ *  reusing TAG_DIARY_PHOTO. */
+export const TAG_DIARY_VIDEO = "ac:diary:video";
 /** Namespace for body word tokens: `ac:text:<word>`. */
 export const TEXT_TOKEN_PREFIX = "ac:text:";
 /**
@@ -91,14 +96,85 @@ export const parseDiaryKeyDate = (key) => {
 // A small English stop-word set — high-frequency words that add noise and bloat
 // the index without improving recall for a personal diary.
 const STOP_WORDS = new Set([
-    "the", "and", "for", "are", "but", "not", "you", "all", "any", "can", "had",
-    "her", "was", "one", "our", "out", "day", "get", "has", "him", "his", "how",
-    "its", "may", "new", "now", "old", "see", "two", "way", "who", "did", "yes",
-    "his", "she", "they", "them", "this", "that", "with", "have", "from", "your",
-    "were", "been", "their", "what", "when", "then", "than", "into", "just",
-    "like", "over", "also", "back", "after", "would", "could", "there", "here",
-    "about", "which", "while", "these", "those", "where", "very", "much", "some",
-    "such", "only", "more", "most", "will", "well", "went", "going", "got",
+    "the",
+    "and",
+    "for",
+    "are",
+    "but",
+    "not",
+    "you",
+    "all",
+    "any",
+    "can",
+    "had",
+    "her",
+    "was",
+    "one",
+    "our",
+    "out",
+    "day",
+    "get",
+    "has",
+    "him",
+    "his",
+    "how",
+    "its",
+    "may",
+    "new",
+    "now",
+    "old",
+    "see",
+    "two",
+    "way",
+    "who",
+    "did",
+    "yes",
+    "his",
+    "she",
+    "they",
+    "them",
+    "this",
+    "that",
+    "with",
+    "have",
+    "from",
+    "your",
+    "were",
+    "been",
+    "their",
+    "what",
+    "when",
+    "then",
+    "than",
+    "into",
+    "just",
+    "like",
+    "over",
+    "also",
+    "back",
+    "after",
+    "would",
+    "could",
+    "there",
+    "here",
+    "about",
+    "which",
+    "while",
+    "these",
+    "those",
+    "where",
+    "very",
+    "much",
+    "some",
+    "such",
+    "only",
+    "more",
+    "most",
+    "will",
+    "well",
+    "went",
+    "going",
+    "got",
 ]);
 /**
  * Tokenise diary markdown into a deduplicated set of searchable lowercase

package/lib/utils/hintFallback.d.ts

@@ -0,0 +1,14 @@
+export type TagInput = {
+    key: string;
+    value: string;
+};
+/**
+ * Fallback tags from device hints for fields the file's own metadata (EXIF
+ * for photos, ffprobe container tags for videos) didn't provide. The
+ * extracted metadata always wins: a hint is used only when the corresponding
+ * key is absent from `extractedTags`. Only `dateCreated` / `latitude` /
+ * `longitude` are pushed; processMeta derives year/month/day from dateCreated
+ * and reverse-geocodes lat/long into country/region tags exactly as it does
+ * for real metadata. Shared by the image and video meta-extractors.
+ */
+export default function hintFallbackTags(extractedTags: TagInput[], s3Metadata: Record<string, string> | undefined): TagInput[];

package/lib/utils/hintFallback.js

@@ -0,0 +1,51 @@
+// S3 user-metadata keys written by the diary upload-url route when the
+// browser supplied device hints (mobile OSes strip GPS EXIF/ffprobe metadata —
+// and sometimes the date — from files handed to web pages, so the client
+// sends what it knows: the file's own timestamp and, for just-taken photos or
+// videos, the device's current position). S3 lowercases metadata keys, so
+// these are the exact wire names as they come back from HeadObject.
+const HINT_DATE = "hint-date";
+const HINT_LATITUDE = "hint-latitude";
+const HINT_LONGITUDE = "hint-longitude";
+// Number() quirks: Number("") and Number("  ") are 0, not NaN — an empty
+// hint must not turn into a valid coordinate at (0, 0).
+const parseFinite = (value) => {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+/**
+ * Fallback tags from device hints for fields the file's own metadata (EXIF
+ * for photos, ffprobe container tags for videos) didn't provide. The
+ * extracted metadata always wins: a hint is used only when the corresponding
+ * key is absent from `extractedTags`. Only `dateCreated` / `latitude` /
+ * `longitude` are pushed; processMeta derives year/month/day from dateCreated
+ * and reverse-geocodes lat/long into country/region tags exactly as it does
+ * for real metadata. Shared by the image and video meta-extractors.
+ */
+export default function hintFallbackTags(extractedTags, s3Metadata) {
+    if (!s3Metadata)
+        return [];
+    const has = (key) => extractedTags.some((t) => t.key === key);
+    const out = [];
+    if (!has("dateCreated") && s3Metadata[HINT_DATE]) {
+        const d = new Date(s3Metadata[HINT_DATE]);
+        if (!isNaN(d.getTime())) {
+            out.push({ key: "dateCreated", value: d.toISOString() });
+        }
+    }
+    // Coordinates only ever make sense as a pair; note 0 is a valid value
+    // (equator / prime meridian), so presence checks must not be falsy checks.
+    if (!has("latitude") && !has("longitude")) {
+        const lat = parseFinite(s3Metadata[HINT_LATITUDE]);
+        const lon = parseFinite(s3Metadata[HINT_LONGITUDE]);
+        if (lat !== undefined &&
+            lon !== undefined &&
+            Math.abs(lat) <= 90 &&
+            Math.abs(lon) <= 180) {
+            out.push({ key: "latitude", value: String(lat) }, { key: "longitude", value: String(lon) });
+        }
+    }
+    return out;
+}

package/lib/utils/index.d.ts

@@ -5,3 +5,4 @@ export * from "./helpers.js";
 export * from "./processMeta.js";
 export * from "./parseFolderDate.js";
 export * from "./diary.js";
+export { default as hintFallbackTags, type TagInput } from "./hintFallback.js";

package/lib/utils/index.js

@@ -9,3 +9,4 @@ export * from "./helpers.js";
 export * from "./processMeta.js";
 export * from "./parseFolderDate.js";
 export * from "./diary.js";
+export { default as hintFallbackTags } from "./hintFallback.js";

package/lib/utils/processMeta.d.ts

@@ -1,5 +1,15 @@
 import { DynamoDBService, LocationService } from "../services/index.js";
 import { Logger } from "@aws-lambda-powertools/logger";
+/** Indexed tag holding the normalized media type of a meta record. */
+export declare const TAG_MEDIA_TYPE = "ac:tau:type";
+/**
+ * Normalizes a file extension into the coarse media type used for search
+ * filtering. Mirrors the allowlists that already gate pipeline dispatch
+ * (thumbsKey.ts's image/video lists, diary.ts's audio list) — kept as a
+ * single derivation point so the index tag and the dispatch gating never
+ * disagree about what an extension is.
+ */
+export declare const deriveMediaType: (extension: string) => "photo" | "video" | "audio" | undefined;
 type ExtractMetadataParams = {
     id: string;
     meta: Array<{
@@ -20,7 +30,7 @@ type ExtractMetadataParams = {
  * 4. add all old tags that are not present in new tags,
  *
  */
-export declare const processMeta: ({ id, meta, metaTableName, placeIndexName, size, logger, locationService, dynamoDBService }: ExtractMetadataParams) => Promise<void>;
+export declare const processMeta: ({ id, meta, metaTableName, placeIndexName, size, logger, locationService, dynamoDBService, }: ExtractMetadataParams) => Promise<void>;
 /**
  * Parent folder of an S3 key, used as the `folder` GSI partition key on the meta table.
  *

package/lib/utils/processMeta.js

@@ -1,5 +1,24 @@
-import { getKeyExtension } from "./thumbsKey.js";
+import { ALLOWED_EXTENSIONS, ALLOWED_VIDEO_EXTENSIONS, getKeyExtension, } from "./thumbsKey.js";
+import { AUDIO_EXTENSIONS } from "./diary.js";
 import { parseFolderDate } from "./parseFolderDate.js";
+/** Indexed tag holding the normalized media type of a meta record. */
+export const TAG_MEDIA_TYPE = "ac:tau:type";
+/**
+ * Normalizes a file extension into the coarse media type used for search
+ * filtering. Mirrors the allowlists that already gate pipeline dispatch
+ * (thumbsKey.ts's image/video lists, diary.ts's audio list) — kept as a
+ * single derivation point so the index tag and the dispatch gating never
+ * disagree about what an extension is.
+ */
+export const deriveMediaType = (extension) => {
+    if (ALLOWED_VIDEO_EXTENSIONS.includes(extension))
+        return "video";
+    if (AUDIO_EXTENSIONS.includes(extension))
+        return "audio";
+    if (ALLOWED_EXTENSIONS.includes(extension))
+        return "photo";
+    return undefined;
+};
 /**
  * 1. read <id>
  * 2. if <id> doesn't exist then use PutCommand
@@ -7,7 +26,7 @@ import { parseFolderDate } from "./parseFolderDate.js";
  * 4. add all old tags that are not present in new tags,
  *
  */
-export const processMeta = async ({ id, meta, metaTableName, placeIndexName, size, logger, locationService, dynamoDBService }) => {
+export const processMeta = async ({ id, meta, metaTableName, placeIndexName, size, logger, locationService, dynamoDBService, }) => {
     // expand location data
     const latitude = Number(meta.find((tag) => tag.key === "latitude")?.value);
     const longitude = Number(meta.find((tag) => tag.key === "longitude")?.value);
@@ -16,7 +35,7 @@ export const processMeta = async ({ id, meta, metaTableName, placeIndexName, siz
         try {
             const res = await locationService.searchPlaceIndexForPositionCommand({
                 IndexName: placeIndexName,
-                Position: [longitude, latitude]
+                Position: [longitude, latitude],
             });
             if (res?.Results && res?.Results?.length > 0) {
                 geoPositionResult = res?.Results[0];
@@ -27,7 +46,7 @@ export const processMeta = async ({ id, meta, metaTableName, placeIndexName, siz
         }
         catch (error) {
             logger.error("Error fetching geo data", {
-                message: error instanceof Error ? error.message : ""
+                message: error instanceof Error ? error.message : "",
             });
         }
     }
@@ -53,8 +72,12 @@ export const processMeta = async ({ id, meta, metaTableName, placeIndexName, siz
     // Date tags derived from the S3 key path (used when EXIF has no date).
     const keyDateTags = dateCreatedTag ? [] : extractMetaFromKey(id);
     // Sentinel tags — always written so the search index can filter by absence of data.
-    const hasDate = !!(dateCreatedTag || extraDateTags.length > 0 || keyDateTags.length > 0);
+    const hasDate = !!(dateCreatedTag ||
+        extraDateTags.length > 0 ||
+        keyDateTags.length > 0);
     const hasLocation = !!geoPositionResult?.Place?.Country;
+    const extension = id.endsWith("/") ? "" : getKeyExtension(id);
+    const mediaType = deriveMediaType(extension);
     const newTags = [
         ...meta,
         ...extraDateTags,
@@ -62,9 +85,10 @@ export const processMeta = async ({ id, meta, metaTableName, placeIndexName, siz
         ...(id.endsWith("/")
             ? []
             : [
-                { key: "extension", value: getKeyExtension(id) },
+                { key: "extension", value: extension },
                 { key: "size", value: String(size) },
                 { key: "sizeMb", value: String(Math.round(size / 1024 ** 2)) },
+                ...(mediaType ? [{ key: "type", value: mediaType }] : []),
             ]),
         ...(geoPositionResult?.Place?.Label
             ? [{ key: "label", value: geoPositionResult?.Place?.Label }]
@@ -91,15 +115,15 @@ export const processMeta = async ({ id, meta, metaTableName, placeIndexName, siz
         { key: "hasLocation", value: hasLocation ? "true" : "false" },
     ].map((tag) => ({
         key: "ac:tau:" + tag.key,
-        value: tag.value
+        value: tag.value,
     }));
     logger.debug("metaData", { newTags });
     logger.debug("trying to read existing metadata");
     const getResponse = await dynamoDBService.getCommand({
         TableName: metaTableName,
         Key: {
-            id
-        }
+            id,
+        },
     });
     const oldTags = getResponse.Item?.tags;
     logger.debug("existing tags", { getResponse });
@@ -108,17 +132,17 @@ export const processMeta = async ({ id, meta, metaTableName, placeIndexName, siz
     const updateResponse = await dynamoDBService.updateCommand({
         TableName: metaTableName,
         Key: {
-            id
+            id,
         },
         UpdateExpression: "set tags = :tags, #folder = :folder",
         ExpressionAttributeNames: {
-            "#folder": "folder"
+            "#folder": "folder",
         },
         ExpressionAttributeValues: {
             ":tags": reconciledTags,
-            ":folder": deriveFolder(id)
+            ":folder": deriveFolder(id),
         },
-        ReturnValues: "ALL_NEW"
+        ReturnValues: "ALL_NEW",
     });
     logger.debug("sent UpdateCommand", { updateResponse });
 };
@@ -162,7 +186,9 @@ const extractMetaFromKey = (key) => {
     if (!key)
         return [];
     // Look at the parent folder, not the file itself.
-    const parent = key.endsWith("/") ? key : key.slice(0, key.lastIndexOf("/") + 1);
+    const parent = key.endsWith("/")
+        ? key
+        : key.slice(0, key.lastIndexOf("/") + 1);
     const parsed = parseFolderDate(parent);
     if (!parsed)
         return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspan-corporation/ac-shared",
-  "version": "1.2.38",
+  "version": "1.2.40",
   "description": "",
   "keywords": [],
   "exports": {