feat(ourmoji): accept timestamp, category, subcategory on admin daily ingest

Lets the home-server agent post entries that reflect when they were generated and match the "Moments → Magic" bucket manually-created Ourmojis use. All three fields are optional; `timestamp` defaults to server-side NOW and must share its calendar date with `date` to keep per-day idempotency sound. `category` / `subcategory` default to `"moments"` / `"magic"` for new entries (in-app submissions pick this up too).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: InfantLab

app/server/api/ourmoji/schemas.ts

@@ -39,11 +39,30 @@ export type DailyOurmojiPayload = z.infer<typeof dailyOurmojiPayloadSchema>;
  * Admin variant — same fields as `dailyOurmojiPayloadSchema` plus a
  * target `userId` so a privileged caller can post on behalf of any
  * user. Used by `POST /api/v1/admin/ourmoji/daily`.
+ *
+ * Additional optional fields let a trusted agent post entries that match
+ * manually-created ones more closely:
+ * - `timestamp` — ISO-8601 datetime when the reading was generated.
+ *   Defaults to server-side NOW when omitted. If its calendar date does
+ *   not match `date`, the request is rejected (keeps idempotency sound).
+ * - `category` / `subcategory` — optional category hierarchy labels
+ *   (e.g. "Moments" / "Magic") written to the top-level columns on
+ *   `entries`, for parity with in-app submissions.
  */
-export const adminDailyOurmojiPayloadSchema =
-  dailyOurmojiPayloadSchema.extend({
+export const adminDailyOurmojiPayloadSchema = dailyOurmojiPayloadSchema
+  .extend({
     userId: z.string().min(1),
-  });
+    timestamp: z.string().datetime({ offset: true }).nullable().optional(),
+    category: z.string().min(1).nullable().optional(),
+    subcategory: z.string().min(1).nullable().optional(),
+  })
+  .refine(
+    (p) => !p.timestamp || p.timestamp.slice(0, 10) === p.date,
+    {
+      message: "timestamp date must match the `date` field (YYYY-MM-DD)",
+      path: ["timestamp"],
+    },
+  );
 
 export type AdminDailyOurmojiPayload = z.infer<
   typeof adminDailyOurmojiPayloadSchema

app/server/api/v1/admin/ourmoji/daily.post.ts

@@ -21,7 +21,10 @@ defineRouteMeta({
     description:
       "Posts a single day's Ourmoji payload for a target user. Intended " +
       "for trusted server-to-server agents authenticated with an admin " +
-      "API key. Idempotent per (userId, date).",
+      "API key. Idempotent per (userId, date). " +
+      "Optional `timestamp` (ISO-8601) defaults to server-side NOW; its " +
+      "calendar date must match `date`. Optional `category` / " +
+      "`subcategory` default to 'moments' / 'magic' for new entries.",
     security: [{ bearerAuth: ["admin:users:write"] }],
     requestBody: {
       required: true,
@@ -52,6 +55,13 @@ defineRouteMeta({
               wheelOfYear: { type: "string", nullable: true },
               wheelCategory: { type: "string", nullable: true },
               timezone: { type: "string" },
+              timestamp: {
+                type: "string",
+                format: "date-time",
+                nullable: true,
+              },
+              category: { type: "string", nullable: true },
+              subcategory: { type: "string", nullable: true },
             },
           },
         },
@@ -133,6 +143,9 @@ export default defineEventHandler(async (event) => {
     wheelCategory: payload.wheelCategory ?? null,
     timezone: payload.timezone,
     source: "api",
+    timestamp: payload.timestamp ?? null,
+    category: payload.category ?? undefined,
+    subcategory: payload.subcategory ?? undefined,
   });
 
   const auth = event.context.auth!;

app/server/services/ourmoji/daily.ts

@@ -22,6 +22,13 @@ import type {
 import { OURMOJI_ENTRY_TYPE } from "~/utils/ourmoji/constants";
 import { ourmojiChildLogger } from "./logger";
 
+/**
+ * Default category/subcategory slugs for Ourmoji entries, matching the
+ * in-app "Moments → Magic" bucket in `categoryDefaults.ts`.
+ */
+const DEFAULT_OURMOJI_CATEGORY = "moments";
+const DEFAULT_OURMOJI_SUBCATEGORY = "magic";
+
 const logger = ourmojiChildLogger("service:daily");
 
 export interface DailyIngestInput {
@@ -36,6 +43,11 @@ export interface DailyIngestInput {
   timezone: string;
   /** Source label — `manual` for in-app submissions, `api` for OpenClaw. */
   source?: "manual" | "api";
+  /** ISO-8601 datetime when the reading was generated. Defaults to NOW. */
+  timestamp?: string | null;
+  /** Optional category hierarchy labels, matching `entries.category`. */
+  category?: string | null;
+  subcategory?: string | null;
 }
 
 /**
@@ -72,6 +84,11 @@ export async function upsertDailyOurmoji(
         timezone: input.timezone,
         source: input.source ?? "api",
         updatedAt: sql`(datetime('now'))`,
+        ...(input.timestamp ? { timestamp: input.timestamp } : {}),
+        ...(input.category !== undefined ? { category: input.category } : {}),
+        ...(input.subcategory !== undefined
+          ? { subcategory: input.subcategory }
+          : {}),
       })
       .where(eq(entries.id, existing.id))
       .returning();
@@ -90,10 +107,12 @@ export async function upsertDailyOurmoji(
     name: "Ourmoji",
     emoji: input.emoji,
     notes: input.reflection,
-    timestamp: `${input.date}T00:00:00Z`,
+    timestamp: input.timestamp ?? new Date().toISOString(),
     timezone: input.timezone,
     data: data as unknown as Record<string, unknown>,
     source: input.source ?? "api",
+    category: input.category ?? DEFAULT_OURMOJI_CATEGORY,
+    subcategory: input.subcategory ?? DEFAULT_OURMOJI_SUBCATEGORY,
   };
 
   const [created] = await db.insert(entries).values(newRow).returning();
@@ -104,15 +123,20 @@ export async function upsertDailyOurmoji(
  * Look up the Ourmoji entry for `userId` on `date` (YYYY-MM-DD), if any.
  *
  * Implementation note: the per-day uniqueness key lives in `data.date`,
- * not in a top-level column. We narrow with a timestamp range first
+ * not in a top-level column. We narrow with a ±1-day timestamp range
  * (cheap, indexed) and then filter rows whose JSON `date` matches.
+ * The widened window accommodates timezone offsets: a local-date entry
+ * stored with a UTC timestamp may fall into the prior or next UTC day.
  */
 export async function findDailyEntry(
   userId: string,
   date: string,
 ): Promise<Entry | undefined> {
-  const dayStart = `${date}T00:00:00Z`;
-  const dayEnd = `${date}T23:59:59Z`;
+  const windowStart = new Date(`${date}T00:00:00Z`);
+  windowStart.setUTCDate(windowStart.getUTCDate() - 1);
+  const windowEnd = new Date(`${date}T23:59:59Z`);
+  windowEnd.setUTCDate(windowEnd.getUTCDate() + 1);
+
   const candidates = await db
     .select()
     .from(entries)
@@ -121,8 +145,8 @@ export async function findDailyEntry(
         eq(entries.userId, userId),
         eq(entries.type, OURMOJI_ENTRY_TYPE),
         isNull(entries.deletedAt),
-        gte(entries.timestamp, dayStart),
-        lte(entries.timestamp, dayEnd),
+        gte(entries.timestamp, windowStart.toISOString()),
+        lte(entries.timestamp, windowEnd.toISOString()),
       ),
     );
   return candidates.find((row) => {
@@ -175,5 +199,7 @@ function rowToDTO(row: Entry): OurmojiDailyCardDTO {
     wheelCategory: data.wheelCategory ?? null,
     timestamp: row.timestamp,
     timezone: row.timezone,
+    category: row.category ?? null,
+    subcategory: row.subcategory ?? null,
   };
 }

app/types/ourmoji.ts

@@ -56,6 +56,8 @@ export interface OurmojiDailyCardDTO {
   wheelCategory: string | null;
   timestamp: string;
   timezone: string;
+  category: string | null;
+  subcategory: string | null;
 }
 
 /** Stats DTO — active runs return only redacted progress. */

docs/modules/ourmoji-agent-setup.md

@@ -108,13 +108,16 @@ curl -X POST https://tada.living/api/v1/admin/ourmoji/daily \
   -d '{
     "userId": "<CASPAR_USER_ID>",
     "date": "2026-04-21",
+    "timestamp": "2026-04-21T08:00:00+01:00",
     "emoji": "🌙",
     "reflection": "The waning gibbous whispers of release.",
     "moonPhase": "Waning Gibbous",
     "moonIllumination": 75,
     "wheelOfYear": "Beltane",
     "wheelCategory": "fire",
-    "timezone": "Europe/London"
+    "timezone": "Europe/London",
+    "category": "moments",
+    "subcategory": "magic"
   }'
 ```
 
@@ -123,14 +126,17 @@ curl -X POST https://tada.living/api/v1/admin/ourmoji/daily \
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `userId` | string | yes | Target user (Caspar or Marian) |
-| `date` | string `YYYY-MM-DD` | yes | Local date the entry belongs to |
+| `date` | string `YYYY-MM-DD` | yes | Local date the entry belongs to; idempotency key |
 | `emoji` | string (1–16 chars) | yes | Drawn from the 23-emoji Sacred Set |
 | `reflection` | string (≤ 5000 chars) | yes | Poetic reflection text |
 | `moonPhase` | string | yes | e.g. "Waning Gibbous" |
 | `moonIllumination` | number 0–100 | no | Percent illuminated |
 | `wheelOfYear` | string | no | e.g. "Beltane", "Samhain" |
 | `wheelCategory` | string | no | e.g. "fire", "water" |
 | `timezone` | string | yes | IANA zone, e.g. "Europe/London" |
+| `timestamp` | string ISO-8601 | no | When the reading was generated. Defaults to server-side NOW. Its calendar date must match `date` |
+| `category` | string | no | Category slug. Defaults to `"moments"` for new Ourmoji entries |
+| `subcategory` | string | no | Subcategory slug. Defaults to `"magic"` for new Ourmoji entries |
 
 ### Idempotency
 
@@ -152,8 +158,10 @@ network failure.
       "moonIllumination": 75,
       "wheelOfYear": "Beltane",
       "wheelCategory": "fire",
-      "timestamp": "2026-04-21T00:00:00Z",
-      "timezone": "Europe/London"
+      "timestamp": "2026-04-21T08:00:00+01:00",
+      "timezone": "Europe/London",
+      "category": "moments",
+      "subcategory": "magic"
     }
   }
 }