Promote preview to main (2026-09-28)

acl/activity.json

@@ -31,7 +31,13 @@
       "permission": {
         "src": "read"
       },
-      "params": {},
+      "params": {
+        "files_since": {
+          "type": "object",
+          "required": false,
+          "description": "Web rail only: { \"<hub_id>\": <unix ts> } - per workspace, count files_by_hub only after the last time the user opened its Files tab. Malformed entries are ignored."
+        }
+      },
       "returns": {
         "type": "object",
         "properties": {
@@ -64,6 +70,11 @@
             "type": "integer",
             "description": "Other tab: workspace and team invites, contacts, tickets, access requests and system alerts",
             "example": 1
+          },
+          "files_by_hub": {
+            "type": "array",
+            "description": "Per workspace, NEW files and folders (media.new; not chat attachments, not workspace creation) newer than files_since: [{ hub_id, cnt, last_ts }]. Not added to any total above. [] until mfs_new_by_hub is deployed.",
+            "example": [{ "hub_id": "ac248fb1ac248fb9", "cnt": 3, "last_ts": 1790568840 }]
           }
         }
       },
@@ -234,6 +245,10 @@
             "lastname": { "type": "string" },
             "fullname": { "type": "string" },
             "hub_name": { "type": "string" },
+            "invite_status": {
+              "type": "string",
+              "description": "Workspace invitations only: pending | accepted | declined | expired | invalid. Absent when it could not be resolved; the client then falls back to invite_token alone"
+            },
             "link_label": { "type": "string" },
             "task_title": { "type": "string" },
             "meeting_action": { "type": "string" },
@@ -496,6 +511,38 @@
       }
     },
 
+    "read_contact_event": {
+      "doc": "Mark a single contact_activity row (task, meeting, invitation, etc.) as read for the caller. Stamps yp.contact_activity.dismissed_at only, so the row stays in Activity history with is_read = 1. Removal is dismiss_contact_event / delete_contact_event.",
+      "scope": "hub",
+      "permission": {
+        "src": "read"
+      },
+      "params": {
+        "activity_id": {
+          "type": "integer",
+          "required": true,
+          "description": "The yp.contact_activity row ID to mark read"
+        }
+      },
+      "returns": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "description": "ok on success"
+          },
+          "activity_id": {
+            "type": "integer",
+            "description": "The contact_activity ID"
+          },
+          "dismissed_at": {
+            "type": "integer",
+            "description": "Unix timestamp of the read"
+          }
+        }
+      }
+    },
+
     "dismiss_contact_event": {
       "doc": "Dismiss a single contact_activity row (hub invite, contact invite, etc.) so it no longer appears in the activity feed. Stamps yp.contact_activity.dismissed_at without deleting the underlying audit row.",
       "scope": "hub",
@@ -595,11 +642,12 @@
     },
 
     "bookmark_add": {
-      "doc": "Save one visible Activity item in the caller's personal notification bookmark store. The key is a server-generated SHA-256 activity identity.",
+      "doc": "Save one visible Activity item in the caller's personal notification bookmark store. The key is a server-generated SHA-256 activity identity. The web panel may also send the row itself, kept (when it matches the key) so bookmark_rows can pin it on top.",
       "scope": "hub",
       "permission": { "src": "read" },
       "params": {
-        "bookmark_key": { "type": "string", "required": true }
+        "bookmark_key": { "type": "string", "required": true },
+        "row": { "type": "object", "required": false }
       },
       "returns": {
         "type": "object",
@@ -626,6 +674,16 @@
       }
     },
 
+    "bookmark_rows": {
+      "doc": "The caller's saved Activity items (snapshots stored by bookmark_add), newest first, to pin on top of the panel. Optional bucket scopes to one tab. is_read is always 1: the client uses the live feed row when it has one.",
+      "scope": "hub",
+      "permission": { "src": "read" },
+      "params": {
+        "bucket": { "type": "string", "required": false }
+      },
+      "returns": { "type": "array" }
+    },
+
     "read": {
       "doc": "Mark a rollup as read (advance read pointer) without hiding it. For chat/teamchat/ticket this is identical to dismiss; for media we only advance mfs_ack; for contact this is a no-op (use dismiss to hide).",
       "scope": "hub",

acl/channel.json

@@ -183,6 +183,11 @@
           "type": "number",
           "required": false,
           "doc": "Page number for pagination (default: 1)"
+        },
+        "mark_read": {
+          "type": "number",
+          "required": false,
+          "doc": "0 = list without marking the messages seen (a workspace team chat shown, not read). Default 1."
         }
       },
       "returns": {

acl/hub.json

@@ -176,8 +176,57 @@
       }
     },
 
+    "decline_invite": {
+      "doc": "Turn down a workspace invitation, by the token from its email link or its notification row. Holding the secret is the authorisation, exactly as it is for accept_invite - and this is the less dangerous of the two, since accepting grants access while declining only destroys an invitation. No session is required: an invitation usually goes to somebody with no account, and saying no must not cost them a signup. Never removes membership (that is desk.leave_hub) and refuses any token that is not an ACTIVE hub_invite, so a stale link pressed after joining cannot rewrite how somebody got in. Idempotent - declining twice keeps the first answer and reports the same result.",
+      "scope": "hub",
+      "permission": {
+        "src": "anonymous",
+        "fast_check": "public-api"
+      },
+      "params": {
+        "token": {
+          "type": "string",
+          "required": true,
+          "doc": "The invite token secret from the email link or the notification row"
+        }
+      },
+      "returns": {
+        "status": { "type": "string", "doc": "declined on success; invalid when the token is not a live hub invite; already_used when it was already accepted" },
+        "hub_id": { "type": "string", "doc": "Workspace the invitation was for, when the token resolved one" }
+      }
+    },
+
+    "invitations": {
+      "doc": "Invitations this workspace is still waiting on, plus the ones that were turned down - the Pending Invitations section of the Access panel. One row per person, newest invitation wins. Accepted invitations are absent (those people are members) and so are lapsed ones. Current members are filtered out here rather than in the proc, because membership lives in the workspace database and hub_invitations reads yellow_page.",
+      "scope": "hub",
+      "permission": {
+        "src": "admin"
+      },
+      "params": {},
+      "returns": {
+        "type": "array",
+        "doc": "Pending and declined invitations",
+        "items": {
+          "email":             { "type": "string",  "doc": "Address the invitation was sent to" },
+          "status":            { "type": "string",  "doc": "pending | declined" },
+          "ctime":             { "type": "integer", "doc": "Unix timestamp the invitation was sent" },
+          "permission":        { "type": "number",  "doc": "Privilege bitmask the invitation offers" },
+          "invitee_uid":       { "type": "string",  "doc": "Invitee's Drumee user id, null when they have no account yet" },
+          "invitee_firstname": { "type": "string",  "doc": "Invitee's first name when they have an account" },
+          "invitee_lastname":  { "type": "string",  "doc": "Invitee's last name when they have an account" },
+          "invitee_fullname":  { "type": "string",  "doc": "Invitee's display name when they have an account" },
+          "invitee_avatar":    { "type": "string",  "doc": "Invitee's avatar when they have an account" },
+          "inviter_id":        { "type": "string",  "doc": "Who sent it" },
+          "inviter_firstname": { "type": "string",  "doc": "Inviter's first name" },
+          "inviter_lastname":  { "type": "string",  "doc": "Inviter's last name" },
+          "inviter_fullname":  { "type": "string",  "doc": "Inviter's display name" }
+        }
+      },
+      "errors": []
+    },
+
     "invite": {
-      "doc": "Invite one or more emails into this workspace, branching on area (share-link vs restricted) and drumate status.",
+      "doc": "Invite one or more emails into this workspace. Mints an invitation the recipient answers with Accept or Decline - it does NOT add anybody. An address that already has an account additionally gets a notification row carrying the token; every address gets the email. Membership is written by accept_invite.",
       "scope": "hub",
       "permission": {
         "src": "admin"