initiative-plugin-sdk 10.0.1 → 10.1.0

package/manifest.contract.json

@@ -248,6 +248,7 @@
     "fields": 32,
     "parts": 16,
     "actions": 16,
+    "permissions": 16,
     "partNodes": 50,
     "partDepth": 4,
     "facetsPerField": 4,
@@ -426,7 +427,7 @@
         "managed": {
           "type": "boolean",
           "default": false,
-          "description": "Returned by the plug-in's after_connect hook when a flow finishes; it is not typed into the settings form."
+          "description": "Returned by the plug-in's after_connect hook, when a flow finishes or when an admin saves a connection that declares 'after_connect'; it is not typed into the settings form."
         }
       },
       "if": {
@@ -721,12 +722,17 @@
           "items": {
             "ref": "connectionField"
           },
-          "description": "Without a 'flow', what an admin types. With one, only the values the plug-in's after_connect hook returns, and every field is 'managed'. The tokens a flow obtains are held apart from these, under reserved keys the plug-in never declares."
+          "description": "Without a 'flow', what an admin types, and the managed values its 'after_connect' returns. With one, only the values the plug-in's after_connect hook returns, and every field is 'managed'. The tokens a flow obtains are held apart from these, under reserved keys the plug-in never declares."
         },
         "flow": {
           "ref": "connectionFlow",
           "description": "How the connection is established. Initiative runs it: the redirect, the code exchange, refreshing and revoking. The plug-in never holds the vendor client's secret or a refresh token."
         },
+        "after_connect": {
+          "type": "boolean",
+          "default": false,
+          "description": "Static connections without a 'flow', container plug-ins only. True: when an admin saves the connection, Initiative sends what they typed to the plug-in's after_connect hook before storing anything, and stores it with the managed values and account label the hook answers; when the hook refuses, nothing is stored. When the connection is cleared or replaced, Initiative sends the plug-in's revoke hook with the values it held, so it can remove what it made at the vendor."
+        },
         "token": {
           "ref": "connectionToken",
           "description": "How a usable access token is got for this connection. Absent: the tokens the flow stored, refreshed as needed. Static connections only."
@@ -887,7 +893,7 @@
     },
     "webhooks": {
       "type": "object",
-      "description": "The vendor's webhooks, received by Initiative at one address per plug-in on the deployment, '/api/v1/plugin-hooks/<public_id>'. Initiative checks each delivery's signature, drops one it has already delivered, finds the communities it belongs to by a value in its body, and forwards it to the plug-in's webhook hook once for each. A container plug-in's hook receives each delivery; a declarative plug-in maps it with 'events' and 'status' instead.",
+      "description": "The vendor's webhooks, received by Initiative at one address per plug-in on the deployment, '/api/v1/plugin-hooks/<public_id>'. Initiative checks each delivery's signature, drops one it has already delivered, by its id or its body, finds the communities it belongs to by a value in its body, and forwards it to the plug-in's webhook hook once for each. A container plug-in's hook receives each delivery; a declarative plug-in maps it with 'events' and 'status' instead.",
       "required": [
         "verify",
         "dedup",
@@ -903,7 +909,7 @@
           "maxLength": "identifierLength",
           "patternFrom": "headerName",
           "patternForm": "plus",
-          "description": "The header carrying the vendor's id for one delivery, such as 'X-GitHub-Delivery'. A delivery with an id already forwarded to a community is not forwarded to it again."
+          "description": "The header carrying the vendor's id for one delivery, such as 'X-GitHub-Delivery'. A delivery with an id already forwarded to a community, or with the body of one, is not forwarded to it again."
         },
         "route": {
           "ref": "webhookRoute"
@@ -930,7 +936,7 @@
     },
     "webhookVerify": {
       "type": "object",
-      "description": "How a delivery's signature is checked: an HMAC over the raw body under a vendor value.",
+      "description": "How a delivery's signature is checked: an HMAC over the raw body, under a vendor value or under the routed connection's own secret.",
       "required": [
         "scheme",
         "header",
@@ -962,7 +968,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": "urlLength",
-          "description": "The signing secret, as one vendor value: '{vendor.<key>}'."
+          "description": "The signing secret: one vendor value, written '{vendor.<key>}', which signs every community's deliveries; or a managed 'secret' field of the connection 'route' names, written '{<key>}', which that connection's after_connect hook returned. With a connection's secret, a delivery is routed first and checked under the secret of each connection its route value names; one that none of them verifies is refused."
         }
       }
     },
@@ -1103,10 +1109,9 @@
           },
           "description": "Whose credential the call runs on, best first. Read and write only. An endpoint offering only 'member' refuses when that member has connected nothing, rather than quietly acting as the plug-in instead."
         },
-        "admin_only": {
-          "type": "boolean",
-          "default": false,
-          "description": "Only the community's admins read or call this endpoint \u2014 a figure for the community's settings page, say. Anyone who can see where it is used may otherwise."
+        "permission": {
+          "ref": "identifier",
+          "description": "Read and write only. The initiative permission a reader holds, in the initiative it is read in, to read or call this through a widget, an action or a form: one this manifest declares at the initiative level, or 'use'. Absent: whoever can see where it is used. Another plug-in calling it for a member is held to that member's permission, the one named or 'use', where its token is confined to an initiative or else in one this plug-in is placed in; one calling it as the community, to what the community granted it."
         },
         "public": {
           "type": "boolean",
@@ -1229,10 +1234,9 @@
           ],
           "description": "Where the page renders. Declaring both gives it a community-wide entry and an entry inside each initiative."
         },
-        "admin_only": {
-          "type": "boolean",
-          "default": false,
-          "description": "Only the community's admins open this page, whatever roles a placement allows \u2014 a settings page, say. Who else may open a page is chosen in the community, per initiative and per role, not declared here."
+        "permission": {
+          "ref": "identifier",
+          "description": "The permission that opens it, at each level it renders in: one this manifest declares at that level, or 'use'. Absent: 'use'. Who holds it is the community's to decide, never the plug-in's."
         },
         "capabilities": {
           "type": "array",
@@ -1338,6 +1342,10 @@
           },
           "description": "Declarative plug-ins, on a list field: actions offered on each of its elements, by id, each one offered on every item kind this field is. An action run from an element reads that element's 'ref' as 'element'."
         },
+        "permission": {
+          "ref": "identifier",
+          "description": "The initiative permission a reader holds to see it: one this manifest declares at the initiative level, or 'use'. Absent: 'use'."
+        },
         "requires": {
           "ref": "requires"
         }
@@ -1733,6 +1741,10 @@
           "ref": "localizedText",
           "description": "The one line the view editor's Add picker shows beside the name."
         },
+        "permission": {
+          "ref": "identifier",
+          "description": "The initiative permission a reader holds to see it: one this manifest declares at the initiative level, or 'use'. Absent: 'use'."
+        },
         "requires": {
           "ref": "requires"
         }
@@ -1794,16 +1806,60 @@
           "default": false,
           "description": "Also offered in the item's own menu."
         },
-        "admin_only": {
-          "type": "boolean",
-          "default": false,
-          "description": "Only the community's admins run this action, whatever roles a placement allows. Who else may run it is chosen in the community, per initiative and per role, not declared here."
+        "permission": {
+          "ref": "identifier",
+          "description": "The initiative permission a reader holds to run it: one this manifest declares at the initiative level, or 'use'. Absent: 'use'."
         },
         "requires": {
           "ref": "requires"
         }
       }
     },
+    "permission": {
+      "type": "object",
+      "description": "Something the community decides who may do with the plug-in, at one level. Inside an initiative, its roles hold it as they hold a tool's permissions, and its managers and the community's admins always do. At the community level, its admins hold it as they hold the parts of administering the community, and a custom role on the admin rung keeps some of them. The plug-in names a permission and says whether members start with it; who holds it is the community's to decide.",
+      "required": [
+        "id",
+        "name",
+        "level"
+      ],
+      "properties": {
+        "id": {
+          "ref": "identifier",
+          "description": "Unique among this manifest's permissions of its level. 'use' is every plug-in's at each level, declared or not: declaring it names it, and inside an initiative says whether members start with it."
+        },
+        "name": {
+          "ref": "localizedText",
+          "description": "What the community's role pages call it."
+        },
+        "level": {
+          "enum": "surfaceScope",
+          "description": "Where it is held: 'initiative' by an initiative's roles, 'community' by the community's admins."
+        },
+        "members": {
+          "type": "boolean",
+          "default": false,
+          "description": "An initiative permission's only: whether a role holds it where nobody in the community said otherwise. Absent: only the roles the community chooses."
+        }
+      },
+      "if": {
+        "properties": {
+          "level": {
+            "const": "community"
+          }
+        },
+        "required": [
+          "level"
+        ]
+      },
+      "then": {
+        "properties": {
+          "members": {
+            "const": false
+          }
+        }
+      }
+    },
     "change": {
       "type": "object",
       "description": "A change to the plug-in's values on one item or on its install, as a declarative plug-in's 'write' answers it. 'set' writes values by key, as a container's client.metadata.set does; 'upsert' and 'remove' change a list field's elements by their 'ref'. A change gives at least one of the three, and changes each key with only one. Initiative makes it as the install, and holds what is kept to the caps a field's description gives.",
@@ -2881,6 +2937,24 @@
           "ref": "page"
         }
       },
+      "sign_in": {
+        "type": "object",
+        "required": [
+          "page",
+          "return_path"
+        ],
+        "properties": {
+          "page": {
+            "ref": "identifier",
+            "description": "The id of one of this plug-in's pages: the page somebody lands in after signing in at the plug-in's own address. Who may open it is decided as for that page inside Initiative, so somebody signs in only to a place where they could open it there."
+          },
+          "return_path": {
+            "ref": "path",
+            "description": "Where Initiative sends somebody back with an authorization code: this path on the origin the deployment serves the plug-in's pages from. Matched exactly."
+          }
+        },
+        "description": "Sign in with Initiative: people may also open the plug-in at its own address, full-window, signing in with their Initiative account through OpenID Connect's authorization code flow. The ID token carries what the page handoff carries for the place they chose, and renews against Initiative. Needs 'pages'. Absent: the plug-in's pages open only inside Initiative."
+      },
       "dashboards": {
         "type": "array",
         "maxItems": "bundledDashboards",
@@ -2921,6 +2995,14 @@
         },
         "description": "Values the community's admins set on the install, which the plug-in's expressions and its parts' text read. At most {settings}."
       },
+      "permissions": {
+        "type": "array",
+        "maxItems": "permissions",
+        "items": {
+          "ref": "permission"
+        },
+        "description": "What the community decides who may do with this plug-in, at most {permissions}. Every page, field, part, action and endpoint answers to one: the one it names, or 'use' at its level. Absent: 'use' alone, at each level, which inside an initiative members start without."
+      },
       "help": {
         "type": "object",
         "minProperties": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "initiative-plugin-sdk",
-  "version": "10.0.1",
+  "version": "10.1.0",
   "description": "Build a plug-in for Initiative: one typed definition of its endpoints, hooks, schedules, widgets and listing, the server Initiative calls, the client it calls Initiative with, the CLI that builds its manifest, and declarative integrations Initiative runs from the manifest alone.",
   "license": "MIT",
   "type": "module",