@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/requests/manual-controllers-routes-documentation.js

@@ -1079,9 +1079,13 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.POST],
         summary: 'Start connecting a third-party account',
-        description: 'Begins an outbound connection to the named provider so this application can later act as the connected account. The '
-            + 'opposite direction from social sign-in, which uses a vendor to identify a person. An application that declares no '
-            + 'connectable provider answers with a "not connectable" error rather than a missing route, which names why.',
+        description: 'Begins an outbound connection so this application can later act as the connected account. The path names a '
+            + 'provider ref, and the grant belongs to that ref\u2019s CONNECTION: a ref the application declares as a member of a '
+            + 'shared connection (`providers.sharedConnections`) connects the one connection its base ref owns, so connecting '
+            + 'through any member and through the base produce the same single grant. With `addScopes` it grows the stored '
+            + 'connection instead of connecting afresh. The opposite direction from social sign-in, which uses a vendor to '
+            + 'identify a person. An application that declares no connectable provider answers with a "not connectable" error '
+            + 'rather than a missing route, which names why.',
         authentication: BEARER,
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The provider authorization URL to navigate to.'),
@@ -1118,7 +1122,8 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.POST],
         summary: 'Store a typed credential for a provider',
-        description: 'For a vendor whose credential is TYPED rather than granted. Takes one value per slot the provider declares as '
+        description: 'For a vendor whose credential is TYPED rather than granted. Stored under the ref\u2019s connection, like a granted '
+            + 'one. Takes one value per slot the provider declares as '
             + 'identifying an account, and refuses any name the provider did not declare — so a caller cannot invent a slot, '
             + 'and cannot write an account token into the slot holding the application\u2019s own registration. Values are '
             + 'sealed by the write door; the request is the only place they exist in plaintext.',
@@ -1131,7 +1136,9 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.GET],
         summary: 'What can be connected',
-        description: 'Lists the providers this application declares as connectable, with the owner scopes each one admits and whether it '
+        description: 'Lists what this application declares as connectable, ONE entry per connection: a shared connection\u2019s members '
+            + 'are folded into its base ref\u2019s entry, which names every ref it serves in `servesRefs`, and a ref declared in no '
+            + 'shared connection is its own connection. Each entry carries the owner scopes it admits and whether it '
             + 'carries an authorization flow. Answers the question the stored-credential list cannot: a person with nothing '
             + 'connected has an empty list and no way to learn what they might connect. Admissibility is a recorded decision per '
             + 'provider, so this reports a decision rather than inspecting a vendor.',
@@ -1144,7 +1151,8 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         group: CONNECTIONS,
         methods: [HttpMethod.GET],
         summary: 'A short-lived access token for your own connected account',
-        description: 'Resolves the caller\u2019s OWN grant for a provider and returns its access token, renewed if the vendor\u2019s expiry '
+        description: 'Resolves the caller\u2019s OWN grant for a provider \u2014 the grant of that ref\u2019s connection, so a member of a shared '
+            + 'connection answers with the one grant its base holds \u2014 and returns its access token, renewed if the vendor\u2019s expiry '
             + 'has passed \u2014 the one credential a browser may be handed, because a vendor\u2019s own picker authorizes as the '
             + 'signed-in user and cannot open without it. Never the refresh token; never another owner\u2019s account. Each '
             + 'hand-out is recorded as a USE of the credential, so revoking or erasing the connection is visible against '
@@ -1154,6 +1162,22 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The access token, with its expiry and granted scopes when the vendor stated them.'),
     },
+    [ManualControllerRouteKey.PROVIDER_CONNECTION_LIST]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: CONNECTIONS,
+        methods: [HttpMethod.GET],
+        summary: 'The connections an owner holds',
+        description: 'One entry per CONNECTION the owner (`ownerScope` = USER for the caller\u2019s own, ORGANIZATION with `ownerId` for a '
+            + 'tenant the caller administers) has stored a credential under \u2014 never one per provider ref, because several refs '
+            + 'of one vendor share one grant. Each entry names the refs the connection serves, the scopes its consent has '
+            + 'accumulated (read from the sealed grant; no token is returned), its validation state, and the credential rows it '
+            + 'is made of. Disconnecting is the credential resource\u2019s own DELETE of those rows, which authorizes, may ask '
+            + 'for step-up, records who revoked, and withdraws the grant at a vendor that accepts a withdrawal. An organization\u2019s '
+            + 'connections are listed only for a caller holding the role the organization credential list itself requires.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The owner\u2019s connections, one entry each.'),
+    },
     [ManualControllerRouteKey.PROVIDER_OPERATION_EXECUTE]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: CONNECTIONS,
@@ -1329,6 +1353,20 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The caller\'s resolved feature set.'),
     },
+    [ManualControllerRouteKey.SUBMISSION_CHALLENGE_PROOF_OF_WORK]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'Get a proof-of-work challenge for a public submission',
+        description: 'A signed, expiring SHA-256 puzzle. When the application protects a public form (the contact form) with a captcha, a '
+            + 'submission must carry an answer in the `x-submission-challenge-response` header: either a token from the consented '
+            + 'captcha vendor, or the solution to this challenge. Find the number whose SHA-256 of `salt + number` equals '
+            + '`challenge`, then send `{"kind":"proof_of_work","challenge":<this object>,"number":<n>}` as that header. A '
+            + 'solution is accepted once, before the salt\'s expiry. Nothing about the caller is stored or sent to a third party.',
+        authentication: PUBLIC,
+        authenticationSummary: 'No credential. A visitor who has not signed in needs a challenge to submit a public form.',
+        successStatus: ok('The challenge: algorithm, salt (carrying its expiry), challenge hash, the largest number to try, and its signature.'),
+    },
     [ManualControllerRouteKey.CHARTS_DATA]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: RUNTIME,
@@ -1369,6 +1407,68 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The provider-call summary for the window.'),
     },
+    [ManualControllerRouteKey.MODEL_COST_SUMMARY]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Summarize model cost per case, organization, agent or model over a window',
+        description: 'Totals, for a window, what the application\'s model calls cost: grouped by case, organization, agent or model, per currency, '
+            + 'with the tokens each group consumed and the exact cost rounded up once per total. Calls made outside any unit of work, and '
+            + 'calls no registered price covered, are counted apart so a gap is visible rather than folded into a total. A case summary '
+            + 'also reports the expert review time recorded on each case, or says that none is recorded. Application administrators only '
+            + '(super-administrator or billing manager): it is the application\'s internal cost data. A window covers at most a year. POST '
+            + 'because the case filter is a list of references. To invoice a month, list the model-cost period aggregates instead and link '
+            + 'the one the invoice bills.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The model-cost summary for the window.'),
+    },
+    [ManualControllerRouteKey.AGENT_WORK_OVERRIDE_RATE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Report how often experts overrode what an agent proposed, over a window',
+        description: 'Counts, for a window, the decisions people took on agents\' proposals, grouped by agent, tool, case or decider: accepted as '
+            + 'proposed, accepted after a change, and rejected. The override rate is the changed and rejected decisions over all three. '
+            + 'Decisions nobody took (the window lapsed, the work was withdrawn, or the requester lost their access) are counted apart and '
+            + 'never enter the rate. It reads the decision records only, never their content. An organization administrator reads their '
+            + 'own organization; an application super-administrator may read any, or all. A window covers at most a year.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The override rate per group for the window.'),
+    },
+    [ManualControllerRouteKey.AGENT_WORK_EVALUATION_EXPORT]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Export an organization\'s decisions on one agent\'s proposals as an evaluation dataset',
+        description: 'Exports, for one organization, one agent and a window, the decisions its people took on that agent\'s proposals, as JSON '
+            + 'Lines: one object per decision, with no decider and no organization. The record\'s own identifiers (the decision, the '
+            + 'case, the run, the task, the work product, the decider, the organization) are replaced by pseudonyms wherever they '
+            + 'appear, including inside kept content; any other value in the kept proposal or final version is exported as the '
+            + 'organization kept it. The proposal and the final version are included only when the organization kept them. Cases the organization walled off '
+            + 'are left out, and a case of a privileged kind goes only with its client\'s recorded consent. The export is refused, and '
+            + 'the refusal recorded, unless the organization holds an active export authorisation; every export is recorded on its '
+            + 'ledger and in the audit trail. An organization administrator for their own organization, or an application '
+            + 'super-administrator.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The dataset, and the id of its ledger entry.'),
+    },
+    [ManualControllerRouteKey.RETENTION_ENFORCEMENT_EVIDENCE]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List the retention enforcement records of the sweep runs in a window',
+        description: 'Returns, for a closed window, every record the retention-class sweep wrote: one per run and per resource bound to a retention '
+            + 'class, with the class, the period the run applied, the cutoff, how many rows it deleted and the window of their retention '
+            + 'start, how many a legal hold kept, and whether the run completed, deferred work to the next run, failed or skipped the '
+            + 'resource. A failed run has a record too. The records hold counts and instants only, so the answer names no person and no '
+            + 'deleted row.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The retention enforcement records for the window.'),
+    },
     [ManualControllerRouteKey.USAGE_FLUSH_EVIDENCE]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: RUNTIME,
@@ -1403,10 +1503,11 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         methods: [HttpMethod.GET],
         summary: 'Read the flow and actor systems a client may render',
         description: 'The metadata and renderable graph for every flow or actor system this application exposes to its frontends — what '
-            + 'exists, what it is called, and how it is shaped.',
+            + 'exists, what it is called, and how it is shaped — and the autonomous agents the application declares, by reference '
+            + 'and actor system: the only values an organization OAuth client may be bound to.',
         authentication: BEARER,
         authenticationSummary: BEARER_CREDENTIAL,
-        successStatus: ok('The visible flow and actor systems.'),
+        successStatus: ok('The visible flow and actor systems, and the declared autonomous agents.'),
     },
     [ManualControllerRouteKey.FLOWS_ACTORS_HISTORY]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
@@ -1419,6 +1520,44 @@ export const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION = {
         authenticationSummary: BEARER_CREDENTIAL,
         successStatus: ok('The caller\'s conversation, or confirmation that it was cleared.'),
     },
+    [ManualControllerRouteKey.FLOWS_ACTORS_DECISIONS]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List the decisions waiting on me',
+        description: 'The pending decisions an agent is waiting on that the caller may act on, across every conversation: their own, those '
+            + 'assigned to them, and those routed to a role they hold in the decision\'s organization. Each is a decision card — the '
+            + 'call being asked for, its deadline, its route and what the caller may do — and never the conversation behind it. '
+            + 'Every row is re-checked against the same rule an act is, so the list never shows a decision the caller could not act on.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The decision cards.'),
+    },
+    [ManualControllerRouteKey.FLOWS_ACTORS_DECISION_ACT]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.POST],
+        summary: 'Answer, reassign, claim, unclaim or escalate a decision',
+        description: 'Acts on one pending decision. `answer` approves or denies the call, optionally with edited arguments; the work then '
+            + 'runs as the person who raised it, with their access as it stands now. `reassign` and `escalate` move it to another '
+            + 'person, who must be able to answer it; `claim` takes a role-routed decision for yourself and `unclaim` gives it back. '
+            + 'A decision that does not exist, is settled, or is not routed to the caller all answer the same way.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('What the act came to.'),
+    },
+    [ManualControllerRouteKey.FLOWS_ACTORS_DECISION_CANDIDATES]: {
+        publication: ManualControllerRoutePublication.PUBLISHED,
+        group: RUNTIME,
+        methods: [HttpMethod.GET],
+        summary: 'List who a decision may be moved to',
+        description: 'The people in the decision\'s organization who could answer it, for a caller who may reassign or escalate it. Each is '
+            + 'checked against the same rule a move is, so choosing one of them is never refused for who they are. A decision the '
+            + 'caller may not move answers the same way as one that does not exist.',
+        authentication: BEARER,
+        authenticationSummary: BEARER_CREDENTIAL,
+        successStatus: ok('The people it may be moved to.'),
+    },
     [ManualControllerRouteKey.ANALYTICS_EVENTS]: {
         publication: ManualControllerRoutePublication.PUBLISHED,
         group: RUNTIME,