@remit/api-openapi-spec 0.0.41 → 0.0.43

package/openapi.json

@@ -2323,6 +2323,133 @@
         }
       }
     },
+    "/calendars/{calendarId}/feed": {
+      "get": {
+        "operationId": "CalendarDetailOperations_getCalendarFeed",
+        "description": "Read whether this calendar has a feed address. Absent (404) until one is\nminted. The token is not here: it is stored as a hash, so the only\nmoment it exists in the clear is the answer to the write below.",
+        "parameters": [
+          {
+            "name": "calendarId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/UUID"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RemitImap.CalendarFeedStateResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found error response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        },
+        "x-amazon-apigateway-integration": {
+          "type": "aws_proxy",
+          "httpMethod": "POST",
+          "passthroughBehavior": "when_no_match",
+          "uri": {
+            "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:{{HandlerFunctionName}}/invocations"
+          }
+        }
+      },
+      "put": {
+        "operationId": "CalendarDetailOperations_putCalendarFeed",
+        "description": "Mint the calendar's feed address, or replace the one it has, and answer\nwith the token in the clear. Idempotent in address rather than in value:\none calendar holds one token, so a second call rotates — the previous\nURL stops resolving, which is how a subscription handed to the wrong\nperson is taken back.\n\nThis is the only response that ever carries the plaintext. A client that\ndoes not keep it rotates again.",
+        "parameters": [
+          {
+            "name": "calendarId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/UUID"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RemitImap.CalendarFeedResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found error response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        },
+        "x-amazon-apigateway-integration": {
+          "type": "aws_proxy",
+          "httpMethod": "POST",
+          "passthroughBehavior": "when_no_match",
+          "uri": {
+            "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:{{HandlerFunctionName}}/invocations"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "CalendarDetailOperations_revokeCalendarFeed",
+        "description": "Revoke the calendar's feed address. Every subscribed client starts getting 404 on its next poll. Answered 404 when the calendar has no feed, so a revoke is never reported as having taken something away that was not there.",
+        "parameters": [
+          {
+            "name": "calendarId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/UUID"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Nothing to return. The resource, or the occurrence, is gone."
+          },
+          "404": {
+            "description": "Not found error response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        },
+        "x-amazon-apigateway-integration": {
+          "type": "aws_proxy",
+          "httpMethod": "POST",
+          "passthroughBehavior": "when_no_match",
+          "uri": {
+            "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:{{HandlerFunctionName}}/invocations"
+          }
+        }
+      }
+    },
     "/config": {
       "get": {
         "operationId": "ConfigOperations_getConfig",
@@ -2434,6 +2561,107 @@
         }
       }
     },
+    "/feeds/calendar/{feedToken}.ics": {
+      "get": {
+        "operationId": "CalendarFeedOperations_getCalendarFeedIcal",
+        "description": "Serve a calendar as iCalendar text to whoever holds its secret address\n(issue #1067).\n\nOutside the session-auth surface on purpose: Apple Calendar, Google\nCalendar, Outlook and Thunderbird subscribe to a URL and never sign in,\nso the token in the path is the credential and the only one. It is\ncompared against the stored hash rather than looked up in the clear, and\nan unknown, revoked or malformed token is the same 404 with the same body\n— a subscriber learns whether it still has access, and nothing else.",
+        "parameters": [
+          {
+            "name": "feedToken",
+            "in": "path",
+            "required": true,
+            "description": "The calendar's secret token, base64url. Unconstrained on purpose: a length or pattern here answers an oversize or malformed address with a distinguishable 400, and error-logs the path it was refused for. The handler checks the shape itself and answers the same 404 an unknown token gets.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "If-None-Match",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "If-Modified-Since",
+            "in": "header",
+            "required": false,
+            "description": "HTTP-date a subscriber last saw the calendar at. Ignored when `If-None-Match` also arrives (RFC 9110 13.2.2), and compared at whole seconds, which is the resolution the `Last-Modified` it came from has.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A whole calendar as iCalendar text, for a client that subscribed to the\nsecret address.\n\nRecurring events are the stored masters with their RRULE, not an expansion:\na subscriber renders its own occurrences and expects to keep doing so\nindefinitely, and an expansion would silently end at whatever horizon this\nserver chose.\n\nThe calendar's name travels as the `X-WR-CALNAME` property inside the\nVCALENDAR, which is where Apple Calendar, Google Calendar and Thunderbird\nread it from.",
+            "headers": {
+              "ETag": {
+                "required": true,
+                "description": "Strong entity tag over the bytes being served. A subscriber polls often and sends it back as `If-None-Match`.",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Last-Modified": {
+                "required": true,
+                "description": "HTTP-date the collection was last written, which is stamped by every event write and every event delete. The collection's own timestamp rather than its newest event: deleting the newest event leaves every survivor older than the change, and a validator that moved backwards would tell a subscriber its stale copy is current.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "text/calendar; charset=utf-8": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "304": {
+            "description": "The subscriber already holds these bytes. Answered when `If-None-Match` carries the tag the feed would serve, or when `If-Modified-Since` is not older than the calendar's last change.",
+            "headers": {
+              "ETag": {
+                "required": true,
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Last-Modified": {
+                "required": true,
+                "description": "The same validator a 200 would have carried, so a subscriber that polls by date can keep doing so",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No feed answers to this address. Unknown, revoked and malformed tokens are one answer with one body, so a caller learns nothing about which of the three it sent.",
+            "content": {
+              "text/plain; charset=utf-8": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {}
+        ],
+        "x-amazon-apigateway-integration": {
+          "type": "aws_proxy",
+          "httpMethod": "POST",
+          "passthroughBehavior": "when_no_match",
+          "uri": {
+            "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:{{HandlerFunctionName}}/invocations"
+          }
+        }
+      }
+    },
     "/mailboxes/{mailboxId}/threads": {
       "get": {
         "operationId": "ThreadOperations_listThreads",
@@ -3863,7 +4091,7 @@
     "/threads": {
       "get": {
         "operationId": "UnifiedThreadOperations_listAllThreads",
-        "description": "List threads across all non-muted accounts of the caller, ordered by sentDate desc. Each row carries an attached `accountId` (derived from a mailboxId→accountId map at read time) plus the usual `senderTrust` enrichment; `category` is served from the ThreadMessage row. Served by the `byDate` LSI1 (pk = the caller's account config), so the caller can never see another account config's threads.\n\nINBOX scope: results are filtered to each account's top-level INBOX, matched by exact path `fullPath === \"INBOX\"` (RFC 6154 defines no Inbox special-use). By design this excludes namespaced sub-paths like `INBOX/Receipts` and non-English server primaries — the unified inbox is each account's primary INBOX, not its sub-folders. Soft-deleted rows are also excluded.\n\nMute exclusion: muted accounts and muted mailboxes are excluded. The inbox/mute filter set is rebuilt per page from live state, so muting/unmuting a mailbox mid-pagination takes effect on the next page (never retroactively).\n\nPagination: pass the returned `continuationToken` to fetch the next page; keep paging until it is absent. In the default (INBOX) mode the INBOX/deleted filter is applied after the index read with a bounded read window per request, so a page may return FEWER than `limit` rows while still carrying a `continuationToken` — treat the presence of the token (not a full page) as the \"more results\" signal. No rows are skipped or duplicated across pages.\n\nStarred mode (`starred=true`): served by the `byStarred` LSI4 instead. A star is a marker on the mail rather than on its placement, so the INBOX scope does not apply and a starred thread in Archive is still returned. Excluded are muted and soft-deleted rows as usual, plus the folders a star never surfaces from: Junk, Trash, and Gmail's All Mail (a second copy of everything, whose rows would otherwise double every starred message). All filtering happens in the query, so a page is short only when the results are exhausted. Rows are per mailbox: the same mail filed in two folders is two rows sharing a `threadId`, and a client rendering one row per conversation collapses by `threadId` across the pages it has accumulated.\n\nSearch mode (`query=<text>`): the listing widens past the INBOX scope to every non-muted mailbox of every non-muted account, and returns only rows whose subject or From address matches the text. This is the unscoped search of the daily brief: one query reaching every folder of every account. Whitespace splits the text into terms and every term must match (AND), each against subject OR From. Matching is case-insensitive substring, not tokenized full-text, so it neither stems nor ranks.\n\nSearch scope: every non-muted mailbox EXCEPT Trash. The scope is defined by what it excludes, so anything a server offers that is not on that list is searched — Spam, Drafts and Gmail's virtual folders (All Mail, Starred, Important) included. Spam is deliberately in scope: the point of an unscoped search is that it reaches the folders the user did not think to look in. Combining `query` with `starred=true` searches the starred scope instead.\n\nDuplicates: a virtual folder holds a second copy of mail that also lives in a real folder, so a backend keying a row by its mailbox returns the same message several times — a starred, Important Gmail inbox message four times. The extras are dropped from the response by message identity, keeping the copy in a real folder, so one message is one row. This is done after the read rather than by barring those folders from the scope, because a message whose only stored row sits in one of them would otherwise become unfindable. De-duplication is per page: a duplicate split across a page boundary survives, the same caveat that applies to collapsing by `threadId`. A page may therefore return fewer rows than `limit` while still carrying a `continuationToken`.\n\nSearch mode and pagination: `limit` is a page size over MATCHES, capped server-side at 500. A page may be shorter than `limit` for two reasons — the matches ran out, or duplicates were dropped from it — so treat the presence of a `continuationToken` as the \"more results\" signal rather than a full page. There is no total match count; page until the token is absent.\n\nWhat a row is in search mode: one per message, not one per mailbox. This differs from the starred mode above, where the same mail filed in two folders is two rows sharing a `threadId`. Collapsing by `threadId` is still a client's job if it renders one row per CONVERSATION, since distinct messages in one thread remain distinct rows here.\n\nCallers that omit `query` are unaffected: the INBOX (and starred) listings behave exactly as before.",
+        "description": "List threads across all non-muted accounts of the caller, ordered by sentDate desc. Each row carries an attached `accountId` (derived from a mailboxId→accountId map at read time) plus the usual `senderTrust` enrichment; `category` is served from the ThreadMessage row. Served by the `byDate` LSI1 (pk = the caller's account config), so the caller can never see another account config's threads.\n\nINBOX scope: results are filtered to each account's top-level INBOX, matched by exact path `fullPath === \"INBOX\"` (RFC 6154 defines no Inbox special-use). By design this excludes namespaced sub-paths like `INBOX/Receipts` and non-English server primaries — the unified inbox is each account's primary INBOX, not its sub-folders. Soft-deleted rows are also excluded.\n\nMute exclusion: muted accounts and muted mailboxes are excluded. The inbox/mute filter set is rebuilt per page from live state, so muting/unmuting a mailbox mid-pagination takes effect on the next page (never retroactively).\n\nPagination: pass the returned `continuationToken` to fetch the next page; keep paging until it is absent. In the default (INBOX) mode the INBOX/deleted filter is applied after the index read with a bounded read window per request, so a page may return FEWER than `limit` rows while still carrying a `continuationToken` — treat the presence of the token (not a full page) as the \"more results\" signal. No rows are skipped or duplicated across pages.\n\nStarred mode (`starred=true`): served by the `byStarred` LSI4 instead. A star is a marker on the mail rather than on its placement, so the INBOX scope does not apply and a starred thread in Archive is still returned. Excluded are muted and soft-deleted rows as usual, plus the folders a star never surfaces from: Junk, Trash, and Gmail's All Mail (a second copy of everything, whose rows would otherwise double every starred message). All filtering happens in the query, so a page is short only when the results are exhausted. Rows are per mailbox: the same mail filed in two folders is two rows sharing a `threadId`, and a client rendering one row per conversation collapses by `threadId` across the pages it has accumulated.\n\nSearch mode (`query=<text>`): the listing widens past the INBOX scope to every non-muted mailbox of every non-muted account, and returns only rows whose subject or From address matches the text. This is the unscoped search of the daily brief: one query reaching every folder of every account. Whitespace splits the text into terms and every term must match (AND), each against subject OR From. Matching is case-insensitive substring, not tokenized full-text, so it neither stems nor ranks.\n\nSearch scope: every non-muted mailbox EXCEPT Trash. The scope is defined by what it excludes, so anything a server offers that is not on that list is searched — Spam, Drafts and Gmail's virtual folders (All Mail, Starred, Important) included. Spam is deliberately in scope: the point of an unscoped search is that it reaches the folders the user did not think to look in. Combining `query` with `starred=true` searches the starred scope instead.\n\nDuplicates: a virtual folder holds a second copy of mail that also lives in a real folder, so a backend keying a row by its mailbox returns the same message several times — a starred, Important Gmail inbox message four times. The extras are dropped from the response by message identity, keeping the copy in a real folder, so one message is one row. This is done after the read rather than by barring those folders from the scope, because a message whose only stored row sits in one of them would otherwise become unfindable. De-duplication is per page: a duplicate split across a page boundary survives, the same caveat that applies to collapsing by `threadId`. A page may therefore return fewer rows than `limit` while still carrying a `continuationToken`.\n\nSearch mode and pagination: `limit` is a page size over MATCHES, capped server-side at 500. A page may be shorter than `limit` for two reasons — the matches ran out, or duplicates were dropped from it — so treat the presence of a `continuationToken` as the \"more results\" signal rather than a full page. There is no total match count; page until the token is absent.\n\nWhat a row is in search mode: one per message, not one per mailbox. This differs from the starred mode above, where the same mail filed in two folders is two rows sharing a `threadId`. Collapsing by `threadId` is still a client's job if it renders one row per CONVERSATION, since distinct messages in one thread remain distinct rows here.\n\nCallers that omit `query` are unaffected: the INBOX (and starred) listings behave exactly as before.\n\nRow filters: `category`, `unread` and `attachments` are columns on the ThreadMessage row, so each is a predicate inside the query rather than a pass over what a page returned. They compose with every mode above — INBOX, starred and search alike — and a page therefore comes back full of matches however rare the criterion is. This is what the cross-account collections need: filtering the pages a client happens to have loaded shows an empty list whenever the matching mail sits below the newest page (#308).\n\nCounting: `count=true` answers how many CONVERSATIONS match, over the whole scope and independent of `limit`. `results=false` omits the rows, which is how a header total is read without also paying for a page of mail. Conversations rather than rows because that is what this listing renders: a row is per mailbox, so the same mail filed in two folders is two rows sharing a `threadId`, and clients collapse by it. Counting rows would put a third number beside a list that shows a second one.",
         "parameters": [
           {
             "name": "continuationToken",
@@ -3907,6 +4135,54 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "name": "category",
+            "in": "query",
+            "required": false,
+            "description": "Filter to messages with one of these header-derived categories, as a union over the values given. Applied as a SQL predicate over the whole scope, so a page comes back full of matches however rare the category is. `uncategorized` is one of them — the pending state's name, never the absence of one.",
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/RemitImap.MessageCategory"
+              }
+            }
+          },
+          {
+            "name": "unread",
+            "in": "query",
+            "required": false,
+            "description": "When true, return only unread messages. A column on the row, so it narrows the query rather than the page.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "attachments",
+            "in": "query",
+            "required": false,
+            "description": "When true, return only messages carrying an attachment. A column on the row, so it narrows the query rather than the page.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "count",
+            "in": "query",
+            "required": false,
+            "description": "Include how many messages the listing matches. Counted over the whole scope, independent of `limit`.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "results",
+            "in": "query",
+            "required": false,
+            "description": "Return matching rows. Default true; set false for a count-only response.",
+            "schema": {
+              "type": "boolean"
+            }
           }
         ],
         "responses": {
@@ -3915,26 +4191,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "required": [
-                    "items"
-                  ],
-                  "properties": {
-                    "continuationToken": {
-                      "allOf": [
-                        {
-                          "$ref": "#/components/schemas/String800"
-                        }
-                      ],
-                      "description": "Opaque, server-minted cursor: absent means the first (or last) page, present means resume from here. Echo it back unchanged to fetch the next page. Every listing endpoint that accepts it rejects a token it cannot decode with 400 ValidationError rather than silently restarting from the first page (#136, #172)."
-                    },
-                    "items": {
-                      "type": "array",
-                      "items": {
-                        "$ref": "#/components/schemas/RemitImap.ThreadMessageResponse"
-                      }
-                    }
-                  }
+                  "$ref": "#/components/schemas/RemitImap.ThreadSearchResponse"
                 }
               }
             }
@@ -5343,6 +5600,73 @@
         ],
         "description": "Projection of a VEVENT's STATUS property (RFC 5545 3.8.1.11). A VEVENT with no STATUS projects as `Confirmed`, which is the value RFC 5545 gives an event whose status is unstated."
       },
+      "RemitImap.CalendarFeedResponse": {
+        "type": "object",
+        "required": [
+          "calendarId",
+          "feedToken",
+          "createdAt",
+          "rotatedAt"
+        ],
+        "properties": {
+          "calendarId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "Collection this address serves"
+          },
+          "feedToken": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String512"
+              }
+            ],
+            "description": "The token itself, base64url over 32 random bytes. It is the whole credential: the path `/feeds/calendar/{feedToken}.ics` needs nothing else, which is what lets a client that cannot sign in subscribe."
+          },
+          "createdAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When this calendar first got a feed address"
+          },
+          "rotatedAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the token was last replaced. `0` means it is still the first one."
+          }
+        },
+        "description": "A calendar's secret subscription address, with the token in the clear.\n\nReturned by the write that mints it and nowhere else. Only the hash is\nstored, so a client that loses this value rotates the feed rather than\nreading it back — which is also what makes the read side safe to leave\ntokenless."
+      },
+      "RemitImap.CalendarFeedStateResponse": {
+        "type": "object",
+        "required": [
+          "calendarId",
+          "createdAt",
+          "rotatedAt"
+        ],
+        "properties": {
+          "calendarId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "Collection this address serves"
+          },
+          "createdAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When this calendar first got a feed address"
+          },
+          "rotatedAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the token was last replaced. `0` means it is still the first one."
+          }
+        },
+        "description": "Whether a calendar has a feed address, and how old it is. The token is deliberately absent — it exists in the clear once, in the answer to the write that minted it."
+      },
       "RemitImap.CalendarFreeBusyResponse": {
         "type": "object",
         "required": [
@@ -9371,10 +9695,10 @@
           "count": {
             "type": "integer",
             "format": "int32",
-            "description": "How many messages the query matches, over the whole mailbox and independent of `limit`. Present only when `count=true`. With `senderTrust` or `dkimMismatch` in the query the count is over the enriched window instead, since those are resolved off the row."
+            "description": "How much the query matches, over the whole scope and independent of `limit`.\nPresent only when `count=true`.\n\nEach operation counts what it lists. `searchThreads` lists messages of one\nmailbox and counts messages; with `senderTrust` or `dkimMismatch` in the\nquery that count is over the enriched window instead, since those are\nresolved off the row. `listAllThreads` counts CONVERSATIONS across every\nnon-muted mailbox of every account — a thread holding two matching messages\ncounts once, and so does one message reachable through a real folder and a\nvirtual copy of it — because that is what the cross-account listing renders\nafter collapsing by `threadId`. A count that disagreed with the rows beneath\nit would be a third number for the same set."
           }
         },
-        "description": "Aggregate response for `searchThreads`. Carries the matching rows (`items`), a\npagination `continuationToken`, and an optional `count` of every message the\nquery matches. `items` is omitted when `results=false` (count-only); `count` is\npresent only when `count=true`. Thread-specific so the shared `ResultList<T>`\n(7 endpoints) stays untouched."
+        "description": "Aggregate response for the filterable thread listings — `searchThreads` and\n`listAllThreads`. Carries the matching rows (`items`), a pagination\n`continuationToken`, and an optional `count` of what the query matches.\n`items` is omitted when `results=false` (count-only); `count` is present only\nwhen `count=true`. Thread-specific so the shared `ResultList<T>` (7 endpoints)\nstays untouched.\n\n`listAllThreads` answers with this model rather than `ResultList<T>` for that\nsame reason: it needs the count field and the shared model cannot carry one.\nOne model over both operations rather than a second of the same shape, so a\nclient reading a filtered thread listing reads one response type whether the\nlisting is scoped to a mailbox or spans every account."
       },
       "RemitImap.TrustedFlag": {
         "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/api-openapi-spec",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "Remit API OpenAPI 3 document, generated from TypeSpec.",
   "exports": {
     ".": "./openapi.json",