@tomato414941/foundation 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/guide.mjs +25 -14
- package/package.json +1 -1
package/guide.mjs
CHANGED
|
@@ -49,19 +49,17 @@ export function guide(connectors) {
|
|
|
49
49
|
' GET /v1/holdings what others have shown you. GET /v1/holdings/<id> one thing, whoever holds it.',
|
|
50
50
|
' GET /v1/holdings/<id>/content reads it; PUT writes it, as editor. Lines point at the id, so renaming changes nothing.', '',
|
|
51
51
|
'GRANTS (what the holder let Foundation use)',
|
|
52
|
-
' PUT /v1/holdings?kind=grant&name=<name>
|
|
53
|
-
'
|
|
54
|
-
' (a short lowercase id: aws, stripe, github, ...); tags are the holder\'s words for grouping (a project, an',
|
|
55
|
-
' environment). Both may be changed later. Set them when you know them: the owner sorts by them.',
|
|
52
|
+
' PUT /v1/holdings?kind=grant&name=<name> body: raw bytes, up to 1MB. A given grant: the same exact name',
|
|
53
|
+
' replaces that value; the answer carries its id.',
|
|
56
54
|
' What you keep for the holder you may read back (an editor line is drawn for you). What the holder kept, or a',
|
|
57
55
|
' service authorized, you may deliver into a command but not read, unless the holder draws you a line.',
|
|
58
56
|
' Do not print delivered values into your context.',
|
|
59
|
-
' GET /v1/holdings?kind=grant every grant: id, name, method (given / authorized / delegated),
|
|
60
|
-
' for a connected one also its service, facts and the variables it yields. &method=
|
|
57
|
+
' GET /v1/holdings?kind=grant every grant: id, name, method (given / authorized / delegated), status;',
|
|
58
|
+
' for a connected one also its service, facts and the variables it yields. &method= and &prefix= narrow it.',
|
|
61
59
|
' GET /v1/holdings?kind=grant&name=<name> one given grant by name: its id and metadata. 404 if no such name.',
|
|
62
60
|
' GET /v1/holdings/<id>/content a given grant\'s bytes, as written; 403 forbidden without a line to it. PUT writes them.',
|
|
63
61
|
' A connected grant has no content to read (405): what it yields is derived when delivered.',
|
|
64
|
-
' PATCH /v1/holdings/<id> {"name"
|
|
62
|
+
' PATCH /v1/holdings/<id> {"name"} a new name for the same thing. DELETE /v1/holdings/<id> removes it (a connected one: see below).',
|
|
65
63
|
' URL-encode the name. A name is any text, which is why it travels as a query and not as a path. Names are 1-200 characters without control characters; case, spaces, slashes and punctuation',
|
|
66
64
|
' remain literal. No normalization, hierarchy, service ownership or automatic renewal is inferred.',
|
|
67
65
|
' The owner can read, rename or delete any saved value. Stored copies survive OAuth disconnection.', '',
|
|
@@ -101,26 +99,39 @@ export function guide(connectors) {
|
|
|
101
99
|
'3. CONNECTING A SERVICE, so that Foundation may obtain credentials there itself. What renews them stays with the',
|
|
102
100
|
' grant, never in a value you can read. Connecting creates one grant, listed with the others.',
|
|
103
101
|
...connectorLines(connectors),
|
|
104
|
-
' POST /v1/requests {"kind":"connect", "input":{"connector":"<id>"
|
|
102
|
+
' POST /v1/requests {"kind":"connect", "input":{"connector":"<id>", "scopes":["<the service\'s scope>", ...]}, "purpose":"...",',
|
|
103
|
+
' "valid_minutes":30} Give the owner the verification_uri.',
|
|
104
|
+
' scopes are the service\'s own names for what the connection may do (see each connector\'s scopes.documentation_url).',
|
|
105
|
+
' Ask for what the work needs; the owner sees each one before agreeing, and decides. Foundation adds only the few',
|
|
106
|
+
' it needs to know who authorized (scopes.base). facts.missing_scopes lists any the service did not grant.',
|
|
107
|
+
' The owner may connect with an OAuth app of their own instead of Foundation\'s (own_client in GET /v1/connectors):',
|
|
108
|
+
' add "client":{"client_id":"<name>","client_secret":"<name>"} naming the given grants that hold its ID and',
|
|
109
|
+
' secret (eBay also "ru_name"). Ask for those with a store request first. The app\'s redirect URL is',
|
|
110
|
+
' <this server>/oauth/<connector id>/callback. With their own app, the owner also decides which scopes can exist.',
|
|
111
|
+
' To reconnect, add "connection_id":"<existing id>" inside input. This updates that connection and keeps its id,',
|
|
112
|
+
' its scopes (add more with scopes) and the app it was made with.',
|
|
113
|
+
' Without connection_id, authorization creates a separate connection, even for the same service user. List and use',
|
|
114
|
+
' an existing connection when no new authorization is needed. Provider consent and revocation may affect several connections.',
|
|
105
115
|
' A connector whose flow is "role" (aws.role) has the owner make a role for Foundation in their own console and',
|
|
106
116
|
' paste its name; nothing of theirs is kept but that name, and each delivery obtains an hour of credentials.',
|
|
107
117
|
' Poll GET /v1/requests/<id> every few seconds until done; result.connection_id identifies the connection.',
|
|
108
|
-
' GET /v1/
|
|
109
|
-
' To use one, deliver it (above) or bind it in http.request (below).
|
|
110
|
-
'
|
|
118
|
+
' GET /v1/holdings?kind=grant lists connected grants with the others: for each, method (authorized / delegated),',
|
|
119
|
+
' service details, facts and the variables it yields. To use one, deliver it (above) or bind it in http.request (below).',
|
|
120
|
+
' DELETE /v1/holdings/<id> {"revoke": true|false} disconnects one (the owner, in a browser); revoke also asks the',
|
|
121
|
+
' service to withdraw what it granted. What was already handed out stays where it went.', '',
|
|
111
122
|
'FUNCTIONS',
|
|
112
123
|
' GET /v1/functions catalog of built-in operations and their invocation endpoints; no arbitrary-code runtime.', '',
|
|
113
124
|
'WHEN IT DOES NOT WORK',
|
|
114
125
|
' GET /v1/requests/<id> one of your requests, and what happened at its page (events).',
|
|
115
126
|
' GET /v1/requests?status=pending your requests. Several may be open at once (up to 10).',
|
|
116
127
|
' events is the raw record, in order: page_opened / page_viewed / connect_started / connect_failed (with a code and',
|
|
117
|
-
' Foundation\'s own message) / connected / stored / denied / cancelled. What was typed is never recorded.',
|
|
128
|
+
' Foundation\'s own message) / connect_review (awaiting confirmation of changes) / connected / stored / denied / cancelled. What was typed is never recorded.',
|
|
118
129
|
' DELETE /v1/requests/<id> cancels it. status is pending / done / denied / cancelled.',
|
|
119
130
|
' Completion and result are fixed until the request expires, even if the resulting resource changes or is removed.',
|
|
120
|
-
' Current connection state is at GET /v1/
|
|
131
|
+
' Current connection state is at GET /v1/holdings?kind=grant. Revoked keys receive 401; their pending requests are cancelled.',
|
|
121
132
|
' Request feedback expires with the request. A done result is a connection_id or the names saved at completion.',
|
|
122
133
|
' Why a registration failed: invalid_values (wrong shape) / invalid_credential (the connector would not take it) /',
|
|
123
|
-
' reconnect_required (the service rejected it) /
|
|
134
|
+
' reconnect_required (the service rejected it) / connection_changed (the target changed). A key approval shows its own events at',
|
|
124
135
|
' GET /v1/requests/<id>: confirmation_required (a wrong code) / confirmation_locked (5 tries).', '',
|
|
125
136
|
'A PLACE FOR FILES (object storage the owner did not have to sign up for)',
|
|
126
137
|
' PUT /v1/holdings?kind=object&name=<key> body is the bytes; the Content-Type you send is what a reader gets back. Up to 25MB.',
|
package/package.json
CHANGED