@mieweb/pulsevault 0.4.1 → 0.5.0

package/protocol/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Pulse upload protocol",
     "description": "The HTTP surface of the Pulse upload protocol, as implemented by @mieweb/pulsevault. Generated from the plugin's route schemas — see PROTOCOL.md for the full contract.",
-    "version": "2.2"
+    "version": "2.3"
   },
   "components": {
     "schemas": {}
@@ -1047,6 +1047,252 @@
           }
         }
       }
+    },
+    "/pulsevault/artifacts/{artifactId}/status": {
+      "get": {
+        "summary": "Where an upload is: uploading, processing or ready",
+        "tags": [
+          "pulsevault"
+        ],
+        "description": "Reports the artifact's state (`unknown`, `uploading`, `processing` while a web-ready conversion rewrites it, `ready`), its kind and `relatedTo`, the bytes received against its declared length, whether the host's `onUploadComplete` has finished (`acknowledged`), and what the host recorded with `recordOutcome` (`outcome`). Runs the `authorize` hook with `phase: \"status\"`; `createCapabilityAuthorize` grants it to the pairing token and to a view token. Never cached.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "token",
+            "required": false,
+            "description": "Optional bearer token (the pairing token or a view token), forwarded to the `authorize` hook as `ctx.token` for browsers that can’t set a header."
+          },
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "in": "path",
+            "name": "artifactId",
+            "required": true,
+            "description": "UUID of the upload to report on."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Where an upload is (PROTOCOL.md §6.5, protocol 2.3): for a page waiting on it, so the host needs no table of its own. Authorized like opening the artifact. Never cached.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "title": "GET /artifacts/<id>/status response",
+                  "description": "Where an upload is (PROTOCOL.md §6.5, protocol 2.3): for a page waiting on it, so the host needs no table of its own. Authorized like opening the artifact. Never cached.",
+                  "type": "object",
+                  "required": [
+                    "artifactId",
+                    "state"
+                  ],
+                  "properties": {
+                    "artifactId": {
+                      "type": "string",
+                      "format": "uuid",
+                      "description": "The artifact asked about."
+                    },
+                    "state": {
+                      "type": "string",
+                      "enum": [
+                        "unknown",
+                        "uploading",
+                        "processing",
+                        "ready"
+                      ],
+                      "description": "`unknown` for an id the server has never seen; `uploading` until the final byte; `processing` while the server converts the bytes for the web; `ready` once the artifact is served."
+                    },
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "video",
+                        "project",
+                        "captions",
+                        "thumbnail"
+                      ],
+                      "description": "Artifact kind. Absent when `state` is `unknown`."
+                    },
+                    "relatedTo": {
+                      "type": "string",
+                      "format": "uuid",
+                      "description": "The video this artifact belongs to, if it declared one."
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "The display name the client sent (`Upload-Metadata.name`), if any."
+                    },
+                    "bytesReceived": {
+                      "type": "number",
+                      "description": "Bytes received so far while `uploading`, or stored once finished, when the server knows."
+                    },
+                    "size": {
+                      "type": "number",
+                      "description": "The upload's declared length, when the server knows."
+                    },
+                    "acknowledged": {
+                      "type": "boolean",
+                      "description": "Whether the host has finished handling the completed upload (its `onUploadComplete` returned)."
+                    },
+                    "outcome": {
+                      "description": "What the host recorded about where the upload went, or why it didn't. Any JSON; absent until the host records one."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`artifactId` is not a valid UUID.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "`artifactId` is not a valid UUID.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorize hook rejected the request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "Authorize hook rejected the request.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pulsevault/artifacts/{artifactId}/poster": {
+      "get": {
+        "summary": "Serve a video's poster frame",
+        "tags": [
+          "pulsevault"
+        ],
+        "description": "Streams or redirects to the finished thumbnail `relatedTo` the video, exactly as `GET /artifacts/:artifactId` would serve it. Runs the `authorize` hook with `phase: \"resolve\"` on the video, so whoever may watch it may see its poster. 404 until the poster has landed.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "token",
+            "required": false,
+            "description": "Optional bearer token for pre-authenticated watch links, forwarded to the `authorize` hook as `ctx.token`."
+          },
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "in": "path",
+            "name": "artifactId",
+            "required": true,
+            "description": "UUID of the video (the pulse's anchor artifact)."
+          }
+        ],
+        "responses": {
+          "400": {
+            "description": "`artifactId` is not a valid UUID.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "`artifactId` is not a valid UUID.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Authorize hook rejected the request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "Authorize hook rejected the request.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The video has no finished poster frame.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "The video has no finished poster frame.",
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "tags": [

package/protocol/schemas/artifact-status.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mieweb/pulsevault/blob/main/protocol/schemas/artifact-status.schema.json",
+  "title": "GET /artifacts/<id>/status response",
+  "description": "Where an upload is (PROTOCOL.md §6.5, protocol 2.3): for a page waiting on it, so the host needs no table of its own. Authorized like opening the artifact. Never cached.",
+  "type": "object",
+  "required": ["artifactId", "state"],
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The artifact asked about."
+    },
+    "state": {
+      "type": "string",
+      "enum": ["unknown", "uploading", "processing", "ready"],
+      "description": "`unknown` for an id the server has never seen; `uploading` until the final byte; `processing` while the server converts the bytes for the web; `ready` once the artifact is served."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["video", "project", "captions", "thumbnail"],
+      "description": "Artifact kind. Absent when `state` is `unknown`."
+    },
+    "relatedTo": {
+      "type": "string",
+      "format": "uuid",
+      "description": "The video this artifact belongs to, if it declared one."
+    },
+    "name": {
+      "type": "string",
+      "description": "The display name the client sent (`Upload-Metadata.name`), if any."
+    },
+    "bytesReceived": {
+      "type": "number",
+      "description": "Bytes received so far while `uploading`, or stored once finished, when the server knows."
+    },
+    "size": {
+      "type": "number",
+      "description": "The upload's declared length, when the server knows."
+    },
+    "acknowledged": {
+      "type": "boolean",
+      "description": "Whether the host has finished handling the completed upload (its `onUploadComplete` returned)."
+    },
+    "outcome": {
+      "description": "What the host recorded about where the upload went, or why it didn't. Any JSON; absent until the host records one."
+    }
+  }
+}

package/protocol/schemas/capability-token.schema.json

@@ -31,6 +31,9 @@
       "type": "string",
       "enum": ["view"],
       "description": "`view` on a read-only view token (§5.5), which only opens artifacts and is signed with a key derived from the secret. Absent on the capability token an upload uses."
+    },
+    "ctx": {
+      "description": "Opaque host data signed into the token (protocol 2.3): who the upload is for, where it goes. The server stores it with the artifact the token creates and hands it back to its own hooks; a client never reads it. Any JSON, at most 1 KiB encoded."
     }
   }
 }