@remit/api-openapi-spec 0.0.40 → 0.0.42

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",
@@ -5343,6 +5571,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": [
@@ -5795,7 +6090,8 @@
         "type": "object",
         "required": [
           "accountConfig",
-          "accounts"
+          "accounts",
+          "semanticSearchEnabled"
         ],
         "properties": {
           "accountConfig": {
@@ -5820,6 +6116,10 @@
               }
             ],
             "description": "Absent unless a configuration import is still waiting on folders IMAP has not produced yet (#1021). Nothing polls a separate route for it."
+          },
+          "semanticSearchEnabled": {
+            "type": "boolean",
+            "description": "Whether this instance stores a vector for every message — SEARCH_EMBEDDING_PROVIDER is anything but `off`. False is a setting an operator turns on (`remit semantic on`), not a failure: the Organize semantic widen and semantic (anchor) filters read stored vectors and have none, so they render an off state rather than an empty result. It rides the config read because it is a property of the deployment, not of a query (#1068)."
           }
         },
         "description": "Full configuration description including accounts"

package/package.json

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