@frockbot/configuration-core 0.3.10 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/configuration-core",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/connection-core": "0.3.10",
-    "@frockbot/kernel-composition": "0.3.10"
+    "@frockbot/connection-core": "0.3.11",
+    "@frockbot/kernel-composition": "0.3.11"
   },
   "devDependencies": {
     "@types/bun": "1.3.6",

package/src/bot-identity.test.ts

@@ -182,4 +182,40 @@ describe("bot/set-profile", () => {
       ),
     ).toEqual({ name: "Housework" });
   });
+
+  test("pins with an instant and unpins with the empty string", () => {
+    const at = "2026-09-03T10:15:00.000Z";
+    expect(
+      decodeBotSettingsViewV1(settings({ name: "Housework", pinnedAt: at })),
+    ).toMatchObject({ profile: { pinnedAt: at } });
+    expect(() =>
+      decodeBotSettingsViewV1(
+        settings({ name: "Housework", pinnedAt: "whenever" }),
+      ),
+    ).toThrow("profile.pinnedAt is invalid");
+
+    const current: BotProfile = { name: "Housework", pinnedAt: at };
+    // A later save must not reshuffle the pinned row: the instant is durable,
+    // so only an explicit change moves it.
+    expect(
+      applyBotProfilePatchV1(current, { title: "Chief" }, "user").pinnedAt,
+    ).toBe(at);
+    expect(applyBotProfilePatchV1(current, { pinnedAt: "" }, "user")).toEqual({
+      name: "Housework",
+    });
+    expect(
+      applyBotProfilePatchV1({ name: "Housework" }, { pinnedAt: at }, "user")
+        .pinnedAt,
+    ).toBe(at);
+    expect(() =>
+      decodeConfigurationCommandV1({
+        schemaVersion: 1,
+        type: "bot/set-profile",
+        commandId: "command-1",
+        botId: "primary",
+        expectedRevision: 3,
+        profile: { pinnedAt: "soon" },
+      }),
+    ).toThrow("profile.pinnedAt is invalid");
+  });
 });

package/src/index.ts

@@ -99,6 +99,12 @@ export interface BotProfile {
   namedBy?: BotNameProvenanceV1;
   /** Keeps the Bot out of the default sidebar list without archiving it. */
   hiddenFromSidebar?: boolean;
+  /**
+   * When the User pinned this Bot, as an ISO 8601 instant. Absent means not
+   * pinned. The instant rather than a flag, so the pinned row keeps a stable
+   * order — earliest pin first — without a second ordering field.
+   */
+  pinnedAt?: string;
 }
 
 /**
@@ -112,6 +118,8 @@ export interface BotProfilePatchV1 {
   description?: string;
   title?: string;
   hiddenFromSidebar?: boolean;
+  /** An ISO 8601 instant pins the Bot; the empty string unpins it. */
+  pinnedAt?: string;
 }
 
 export interface BotNotificationPolicy {
@@ -1065,6 +1073,7 @@ const BOT_PROFILE_OPTIONAL_FIELDS = [
   "title",
   "namedBy",
   "hiddenFromSidebar",
+  "pinnedAt",
 ] as const;
 
 function botProfile(value: unknown): BotProfile {
@@ -1096,9 +1105,21 @@ function botProfile(value: unknown): BotProfile {
             "profile.hiddenFromSidebar",
           ),
         }),
+    ...(profile.pinnedAt === undefined
+      ? {}
+      : { pinnedAt: profileTimestamp(profile.pinnedAt, "profile.pinnedAt") }),
   };
 }
 
+/** An ISO 8601 instant a profile field carries. Never a duration or a count. */
+function profileTimestamp(value: unknown, label: string): string {
+  const candidate = text(value, label, 64);
+  if (!Number.isFinite(Date.parse(candidate))) {
+    throw new ConfigurationDecodeError(`${label} is invalid`);
+  }
+  return candidate;
+}
+
 /**
  * A patch field that carries text: a non-empty string sets it, and the empty
  * string clears it. A partial update has no other way to say "remove this".
@@ -1123,7 +1144,7 @@ function botProfilePatch(value: unknown): BotProfilePatchV1 {
     value,
     "profile",
     [],
-    ["name", "label", "description", "title", "hiddenFromSidebar"],
+    ["name", "label", "description", "title", "hiddenFromSidebar", "pinnedAt"],
   );
   if (Reflect.ownKeys(patch).length === 0) {
     throw new ConfigurationDecodeError("profile has invalid fields");
@@ -1148,6 +1169,15 @@ function botProfilePatch(value: unknown): BotProfilePatchV1 {
             "profile.hiddenFromSidebar",
           ),
         }),
+    // An instant pins; the empty string unpins, the same way text clears.
+    ...(patch.pinnedAt === undefined
+      ? {}
+      : {
+          pinnedAt:
+            patchText(patch.pinnedAt, "profile.pinnedAt", 64) === ""
+              ? ""
+              : profileTimestamp(patch.pinnedAt, "profile.pinnedAt"),
+        }),
   };
 }
 
@@ -1167,7 +1197,7 @@ export function applyBotProfilePatchV1(
     next.name = patch.name;
     next.namedBy = namedBy;
   }
-  for (const key of ["label", "description", "title"] as const) {
+  for (const key of ["label", "description", "title", "pinnedAt"] as const) {
     const value = patch[key];
     if (value === undefined) continue;
     if (value === "") delete next[key];