@onplo/sdk 0.0.1 → 0.0.2

package/generated/account.d.ts

@@ -379,8 +379,8 @@ export interface paths {
         /**
          * Make an address the one Onplo writes to
          * @description EXACTLY ONE ADDRESS IS THE ONE ONPLO WRITES TO, and marking another unmarks it — the server's
-         *     job, never the caller's, as `updateSignInMethod` does for a Primary key. Only a VERIFIED
-         *     address can be marked, because Onplo never writes to one that is not.
+         *     job, never the caller's, as `updateSignInMethod` does for the Primary sign-in method. Only a
+         *     VERIFIED address can be marked, because Onplo never writes to one that is not.
          */
         patch: operations["updateEmailAddress"];
         trace?: never;
@@ -1465,6 +1465,10 @@ export interface paths {
          * @description A suggestion for the public roadmap, made in your account's name from your personal
          *     environment: the suggestion is the person's, never a company's. An agent may draft one for you
          *     to send, and never sends it itself.
+         *
+         *     IT IS KEPT, AND NOTHING ELSE HAPPENS YET: Onplo reads it, merges duplicates, and lists it as
+         *     an Idea once moderated. Sending the same words twice makes two suggestions; there is no
+         *     idempotency key.
          */
         post: operations["suggestFeature"];
         delete?: never;
@@ -1473,6 +1477,43 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/feature-votes/{future_feature_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /**
+                 * @description A future feature's permanent id, `<app>.feature.<concept>`, as its app's roadmap lists it:
+                 *     `account.feature.family`. Lowercase, dot-separated, never rewritten when the title changes.
+                 */
+                future_feature_id: components["parameters"]["FutureFeatureId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Vote for a future feature
+         * @description Your one vote on a feature an app has decided to build later, cast from your personal
+         *     environment. "ONE PERSON, ONE VOTE — the vote belongs to the account, never to the
+         *     environment": somebody who belongs to twenty companies still has one vote on a feature. An
+         *     agent may draft a vote for you to cast, and never casts it itself.
+         *
+         *     VOTING AGAIN IS THE SAME VOTE. A second vote on the same feature changes nothing and answers
+         *     the vote as it was first cast, so a retry whose answer was lost is never told it already
+         *     voted. There is no second vote to refuse, and so no 409.
+         *
+         *     THE FEATURE IS NAMED BY ITS PERMANENT ID, `<app>.feature.<concept>`, as its app's roadmap
+         *     lists it. An id no app's roadmap lists is refused with a 422 naming `future_feature_id`, and
+         *     no vote is kept.
+         */
+        put: operations["castFeatureVote"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/support-tickets": {
         parameters: {
             query?: never;
@@ -1491,7 +1532,13 @@ export interface paths {
          *
          *     A TICKET SPLITS RATHER THAN BELONGS TO ONE APP: the conversation with you is Communication's,
          *     and the work item is an ordinary task the Projects app renders. Account is the door; neither
-         *     app exists yet to hold the rest.
+         *     app exists yet to hold the rest. UNTIL THEY DO, Account keeps the report as it was sent — the
+         *     app, the page, your words, whether you chose diagnostics, and the environment this credential
+         *     acts in — and that is all: no diagnostic bundle is gathered yet, and nobody answers in a
+         *     conversation yet. Sending the same report twice makes two.
+         *
+         *     A PERSON REPORTS A PROBLEM: the conversation that follows is with you. A machine's or an
+         *     agent's credential is answered 404 `subject_not_person`.
          */
         post: operations["reportProblem"];
         delete?: never;
@@ -1648,9 +1695,9 @@ export interface paths {
         head?: never;
         /**
          * Edit a role
-         * @description Its name, what it grants, how it is held and where it may be granted. What is not sent stays as
-         *     it is. Everyone holding it holds the new bundle from the next request. A built-in role is not
-         *     edited: copy it into a role of the company's own instead.
+         * @description Its name, what it grants, its Role selection on login and where it may be granted. What is not
+         *     sent stays as it is. Everyone holding it holds the new bundle from the next request. A built-in
+         *     role is not edited: copy it into a role of the company's own instead.
          */
         patch: operations["updateRole"];
         trace?: never;
@@ -4401,6 +4448,11 @@ export interface components {
             title: string;
             created_at: components["schemas"]["Timestamp"];
         };
+        FeatureVote: {
+            /** @description The future feature voted for, by its permanent id, `account.feature.family`. */
+            feature_id: string;
+            cast_at: components["schemas"]["Timestamp"];
+        };
         ProblemReport: {
             /** @description The app it happened in, by its id. */
             app: string;
@@ -5261,6 +5313,11 @@ export interface components {
         DataSearchId: components["schemas"]["Id"];
         /** @description The feature's permanent id in Account's feature list. */
         FeatureId: string;
+        /**
+         * @description A future feature's permanent id, `<app>.feature.<concept>`, as its app's roadmap lists it:
+         *     `account.feature.family`. Lowercase, dot-separated, never rewritten when the title changes.
+         */
+        FutureFeatureId: string;
         /** @description One holder's Premium seat of one app. */
         PremiumSeatAssignmentId: components["schemas"]["Id"];
         /** @description An environment's id — here, a company you are a member of. */
@@ -7917,7 +7974,42 @@ export interface operations {
             415: components["responses"]["UnsupportedMediaType"];
             422: components["responses"]["Unprocessable"];
             500: components["responses"]["ServerError"];
-            501: components["responses"]["NotImplemented"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    castFeatureVote: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /**
+                 * @description A future feature's permanent id, `<app>.feature.<concept>`, as its app's roadmap lists it:
+                 *     `account.feature.family`. Lowercase, dot-separated, never rewritten when the title changes.
+                 */
+                future_feature_id: components["parameters"]["FutureFeatureId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Your vote, as it was first cast. */
+            200: {
+                headers: {
+                    "Onplo-Request-Id": components["headers"]["OnploRequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeatureVote"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotAPerson"];
+            413: components["responses"]["ContentTooLarge"];
+            415: components["responses"]["UnsupportedMediaType"];
+            422: components["responses"]["Unprocessable"];
+            500: components["responses"]["ServerError"];
             503: components["responses"]["ServiceUnavailable"];
         };
     };
@@ -7947,11 +8039,11 @@ export interface operations {
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotAPerson"];
             413: components["responses"]["ContentTooLarge"];
             415: components["responses"]["UnsupportedMediaType"];
             422: components["responses"]["Unprocessable"];
             500: components["responses"]["ServerError"];
-            501: components["responses"]["NotImplemented"];
             503: components["responses"]["ServiceUnavailable"];
         };
     };

package/generated/ai.d.ts

@@ -1121,12 +1121,11 @@ export interface paths {
          *     THE AGENT MUST BE ONE YOU MAY USE, in this account environment, and turned on. Anything else
          *     is refused (422 naming `agent_id`).
          *
-         *     A MODEL CALL. Every one passes through the routing layer, which is not built
-         *     (ONPLO-2225). IT ASKS THE MODEL SOMEBODY PICKED, AND ONPLO PICKS NONE (decision 0867): the
+         *     A MODEL CALL. Every one passes through the routing layer (ONPLO-2225).
+         *     IT ASKS THE MODEL SOMEBODY PICKED, AND ONPLO PICKS NONE (decision 0867): the
          *     agent's own, or else your Default provider & model. With none picked, nothing is asked and
-         *     no chat is made: 503 `no_model_picked`, which says where to pick one.
-         *
-         *     **NOT BUILT YET — it answers 501 (ONPLO-1722).**
+         *     no chat is made: 503 `no_model_picked`, which says where to pick one. This said "the routing
+         *     layer, which is not built" and "NOT BUILT YET — it answers 501" until it was served (ONPLO-1722).
          */
         post: operations["startChat"];
         delete?: never;
@@ -1207,9 +1206,8 @@ export interface paths {
          *     not carried on (409 `chat_in_trash`).
          *
          *     A MODEL CALL, as starting one is. No answer leaves nothing behind: 503 `no_model_answered`.
-         *     With no model picked, nothing is asked: 503 `no_model_picked` (decision 0867, rule 3).
-         *
-         *     **NOT BUILT YET — it answers 501 (ONPLO-1722).**
+         *     With no model picked, nothing is asked: 503 `no_model_picked` (decision 0867, rule 3). This
+         *     said "NOT BUILT YET — it answers 501" until it was served (ONPLO-1722).
          */
         post: operations["carryOnChat"];
         delete?: never;
@@ -2614,6 +2612,72 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/machines/{machine_id}/times": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                machine_id: components["parameters"]["MachineId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Set when a machine shows offline, and when its job shows stalled
+         * @description "Offline after 3 missed heartbeats · stalled after 10 min silence", the defaults, "all tunable":
+         *     this is where one machine's own times are set. A machine on a slow line may be given longer before
+         *     it shows offline, and one running long jobs longer before a silent job shows stalled.
+         *
+         *     BOTH ARE SENT EVERY TIME, and each replaces what the machine had. Sending 180 and 600 gives it the
+         *     defaults back. Setting the times it already has changes nothing, and answers it as it is.
+         *
+         *     WHO MAY: whoever may Pause the machine, `ai:machine.suspend`, as the owner ruled (ONPLO-5200). One AI
+         *     was never told about answers 404, as reading it does.
+         */
+        put: operations["setMachineTimes"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/machine-connector/work": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * A machine's waiting work
+         * @description The connector "asks 'is there work for me?', and when there is, hands the job to the AI tool
+         *     already installed and signed in on that machine". This is that question: the jobs given to this
+         *     machine that wait to be picked up, in the order the task service lists them: it promises none.
+         *
+         *     A MACHINE ASKS ONLY FOR ITSELF. It calls as itself, holding the machine-connector credential
+         *     Integrations made when it was connected (ONPLO-4445), so the machine is the caller and no
+         *     permission is asked, as for its heartbeat. A person or an agent asking is refused (403
+         *     `reported_by_a_machine_only`).
+         *
+         *     A PAUSED MACHINE IS GIVEN NO NEW WORK: "Your Pause stops the machine entirely, so it is given no
+         *     new work." While it is paused, `data` is empty and `paused` is `true`, whatever waits under it.
+         *
+         *     AT MOST 100 AT A TIME. The rest are answered once those are picked up.
+         *
+         *     PICKING ONE UP IS NOT HERE: it is still the task service's StartTask, "through its grant". A job's
+         *     progress and cost ride on the heartbeat. Each poll leaves its look on the machine, as every read
+         *     here does (decision 0675).
+         */
+        get: operations["listMachineWork"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/machine-connector/heartbeat": {
         parameters: {
             query?: never;
@@ -4544,18 +4608,17 @@ export interface components {
             /** @description The machine, by the id its record has in Integrations. */
             machine_id: components["schemas"]["Id"];
             /**
-             * @description "Presence from connector heartbeats." Offline after the heartbeats it may miss — three, so 180
-             *     seconds after the last one. Every machine gets those three: no machine has a setting of its
-             *     own for it yet (ONPLO-5200).
+             * @description "Presence from connector heartbeats." Offline once `offline_after_seconds` have passed since
+             *     the last one: 180, three missed heartbeats, until somebody sets the machine's own (ONPLO-5200).
              * @enum {string}
              */
             presence: "online" | "offline";
             /** @description When its last heartbeat arrived, or `null` until the first one. */
             last_seen_at: components["schemas"]["Timestamp"] | null;
             /**
-             * @description `stalled` while a job it is running has not moved for longer than its setting allows — ten
-             *     minutes, for every machine until a machine has a setting of its own (ONPLO-5200) — as its
-             *     last heartbeat reported it. `working` otherwise. Returning such a job to waiting is the task
+             * @description `stalled` while a job it is running has not moved for longer than `stalled_after_seconds` —
+             *     ten minutes until somebody sets the machine's own (ONPLO-5200) — as its last heartbeat
+             *     reported it. `working` otherwise. Returning such a job to waiting is the task
              *     service's, and not this board's.
              * @enum {string}
              */
@@ -4569,8 +4632,29 @@ export interface components {
              *     on the machine, or `null` until it reports one. An estimate: the bill is the subscription's.
              */
             month_cost_estimate: components["schemas"]["Money"] | null;
+            /** @description Seconds after its last heartbeat that it shows offline. 180 until set (`setMachineTimes`). */
+            offline_after_seconds: number;
+            /** @description Seconds a job may go without moving before the machine shows stalled. 600 until set. */
+            stalled_after_seconds: number;
             environment_id: components["schemas"]["Id"];
         };
+        /** @description One machine's own times, both sent every time (ONPLO-5200). 180 and 600 are the defaults. */
+        MachineTimes: {
+            /**
+             * @description Seconds after its last heartbeat that it shows offline. At least 120, two heartbeats, so one
+             *     heartbeat late never shows a machine offline; at most a day.
+             */
+            offline_after_seconds: number;
+            /** @description Seconds a job may go without moving before the machine shows stalled. One minute to a day. */
+            stalled_after_seconds: number;
+        };
+        /** @description The jobs that wait for this machine, or none while it is paused (ONPLO-5202). */
+        MachineWork: {
+            /** @description Whether somebody here paused it. While `true`, `data` is empty. */
+            paused: boolean;
+            /** @description The jobs given to this machine that wait to be picked up, at most 100. */
+            data: components["schemas"]["Job"][];
+        };
         /**
          * @description What the connector reports of its own machine, every 60 seconds. Each heartbeat replaces the last
          *     one whole.
@@ -6861,7 +6945,6 @@ export interface operations {
             415: components["responses"]["UnsupportedMediaType"];
             422: components["responses"]["Unprocessable"];
             500: components["responses"]["ServerError"];
-            501: components["responses"]["NotImplemented"];
             503: components["responses"]["ChatUnavailable"];
         };
     };
@@ -7041,7 +7124,6 @@ export interface operations {
             415: components["responses"]["UnsupportedMediaType"];
             422: components["responses"]["Unprocessable"];
             500: components["responses"]["ServerError"];
-            501: components["responses"]["NotImplemented"];
             503: components["responses"]["ChatUnavailable"];
         };
     };
@@ -9098,6 +9180,83 @@ export interface operations {
             503: components["responses"]["ServiceUnavailable"];
         };
     };
+    setMachineTimes: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                machine_id: components["parameters"]["MachineId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["MachineTimes"];
+            };
+        };
+        responses: {
+            /** @description The machine, judged by its new times. */
+            200: {
+                headers: {
+                    "Onplo-Request-Id": components["headers"]["OnploRequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MachineOnTheBoard"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            413: components["responses"]["ContentTooLarge"];
+            415: components["responses"]["UnsupportedMediaType"];
+            422: components["responses"]["Unprocessable"];
+            500: components["responses"]["ServerError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    listMachineWork: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Its waiting work, or none. */
+            200: {
+                headers: {
+                    "Onplo-Request-Id": components["headers"]["OnploRequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MachineWork"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            /** @description Refused. `reported_by_a_machine_only`: the caller is a person or an agent, and only a machine asks for its own work. The door's own three, as on every other operation: `permission_missing` and `ring_requires_person`, when identity refuses the credential, and `outside_session_scope`, when the act is not within the scope this session declared at sign-in. */
+            403: {
+                headers: {
+                    "Onplo-Request-Id": components["headers"]["OnploRequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["Problem"] & {
+                        /** @enum {unknown} */
+                        code?: "reported_by_a_machine_only" | "permission_missing" | "ring_requires_person" | "outside_session_scope";
+                    };
+                };
+            };
+            413: components["responses"]["ContentTooLarge"];
+            415: components["responses"]["UnsupportedMediaType"];
+            422: components["responses"]["Unprocessable"];
+            500: components["responses"]["ServerError"];
+            503: components["responses"]["TasksUnavailable"];
+        };
+    };
     reportMachineHeartbeat: {
         parameters: {
             query?: never;

package/generated/identity.d.ts

@@ -95,6 +95,45 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Trade an app's one-time code for the person's session
+         * @description THE TOKEN ENDPOINT (RFC 6749 §4.1.3, OpenID Connect Core §3.1.3; architecture decision record
+         *     037). An app that `grantAuthorizationCode` sent back with a code trades it here, once, for:
+         *
+         *     - THE ACCESS TOKEN, which is the person's session, opaque, read by every Onplo service as every
+         *       session is. It records the app it was issued to.
+         *     - THE ID TOKEN, a JWT signed with a key of `readProviderKeySet`, which says who signed in: `iss`,
+         *       `sub` (the person), `aud` (the app), `exp`, `iat`, `auth_time`, `amr` and the `nonce` the app
+         *       sent. It is for the app alone and NO ONPLO SERVICE TAKES IT AS A BEARER.
+         *
+         *     THE CODE IS TRADED ONLY BY THE APP IT WAS HANDED TO: the same `client_id`, the same
+         *     `redirect_uri`, and a `code_verifier` whose SHA-256 is the challenge it was asked with (RFC 7636).
+         *     A CODE SHOWN A SECOND TIME IS REFUSED, AND THE SESSION ITS FIRST TRADE OPENED IS ENDED, because a
+         *     code shown twice is a code somebody else holds.
+         *
+         *     REFUSED AS OAUTH REFUSES (RFC 6749 §5.2), with a 400 and an `error`, so any OAuth client reads
+         *     it: a field missing is `invalid_request`, a grant other than `authorization_code` is
+         *     `unsupported_grant_type`, and a code unknown, expired, spent or shown by another app is
+         *     `invalid_grant`, told apart from nothing.
+         *
+         *     SIGNED OUT, because the code is the proof, and LIMITED by how often it is called (decision 0732).
+         */
+        post: operations["requestTokens"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/passkey-proofs": {
         parameters: {
             query?: never;
@@ -1316,6 +1355,58 @@ export interface components {
                 detail: string;
             }[];
         };
+        /**
+         * @description The trade, as RFC 6749 §4.1.3 names its fields. NONE IS REQUIRED HERE, so a field missing is
+         *     answered as OAuth answers it, `invalid_request`, and never as a 422.
+         */
+        TokenRequest: {
+            /** @description Always `authorization_code`. */
+            grant_type?: string;
+            /** @description The code `grantAuthorizationCode` sent the app back with. */
+            code?: string;
+            /** @description The return address the code was sent to, exactly as the app asked with it. */
+            redirect_uri?: string;
+            /** @description The app, by the id Onplo lists it under. */
+            client_id?: string;
+            /** @description The PKCE verifier whose SHA-256 the app sent as its challenge. */
+            code_verifier?: string;
+        };
+        /** @description The answer, under the names RFC 6749 §5.1 and OpenID Connect Core §3.1.3.3 give it. */
+        Tokens: {
+            /** @description The person's session. Sent as a bearer to every Onplo service. */
+            access_token: string;
+            /**
+             * @description Always `Bearer`.
+             * @enum {string}
+             */
+            token_type: "Bearer";
+            /** @description The seconds until the session ends, twelve hours from the touch at most. */
+            expires_in: number;
+            /** @description Who signed in, signed ES256, for the app alone. Never a bearer. */
+            id_token: string;
+            /** @description The scopes granted, space-separated, as the app asked them. */
+            scope: string;
+        };
+        /** @description OAuth's refusal (RFC 6749 §5.2), so any OAuth client reads it. */
+        TokenRefusal: {
+            /**
+             * @description `invalid_request`: a field is missing. `unsupported_grant_type`: the grant is not
+             *     `authorization_code`. `invalid_grant`: the code is unknown, expired, spent or shown by
+             *     another app.
+             * @enum {string}
+             */
+            error: "invalid_request" | "unsupported_grant_type" | "invalid_grant";
+        };
+        /**
+         * @description A 400 at the token endpoint: OAuth's refusal, or the server's `malformed_request` for a form it
+         *     could not read (a key sent twice). The two never overlap: a refusal carries `error` alone.
+         */
+        TokenRefusedOrUnread: components["schemas"]["TokenRefusal"] | components["schemas"]["TokenFormUnread"];
+        /** @description The server's Problem for a token form it could not read, such as a key sent twice. */
+        TokenFormUnread: components["schemas"]["Problem"] & {
+            /** @enum {unknown} */
+            code?: "malformed_request";
+        };
         /**
          * @description The provider's metadata, under the names OpenID Connect Discovery 1.0 gives them, so any
          *     standard client reads it unchanged. Every list holds only what identity supports.
@@ -1749,6 +1840,51 @@ export interface operations {
             500: components["responses"]["ServerError"];
         };
     };
+    requestTokens: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/x-www-form-urlencoded": components["schemas"]["TokenRequest"];
+            };
+        };
+        responses: {
+            /** @description The session and the ID token. */
+            200: {
+                headers: {
+                    "Onplo-Request-Id": components["headers"]["OnploRequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Tokens"];
+                };
+            };
+            /**
+             * @description OAuth's refusal, its `error` saying which. Or a body the server could not read, before the
+             *     endpoint saw it: the `malformed_request` problem every operation declares on 400, sent as
+             *     `application/problem+json`. One media type is declared because a status carries one.
+             */
+            400: {
+                headers: {
+                    "Onplo-Request-Id": components["headers"]["OnploRequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenRefusedOrUnread"];
+                };
+            };
+            413: components["responses"]["ContentTooLarge"];
+            415: components["responses"]["UnsupportedMediaType"];
+            422: components["responses"]["Unprocessable"];
+            429: components["responses"]["TooManyCalls"];
+            500: components["responses"]["ServerError"];
+            501: components["responses"]["NotImplemented"];
+        };
+    };
     startPasskeyProof: {
         parameters: {
             query?: never;

package/generated/integrations.d.ts

@@ -166,8 +166,8 @@ export interface paths {
         get: operations["listConnections"];
         put?: never;
         /**
-         * Connect a system with an API key, connect a database, a Custom API or an MCP server
-         * @description The four connect flows in which you TYPE the credential. `kind` says which, and each takes
+         * Connect a system with an API key or as an app, connect a database, a Custom API or an MCP server
+         * @description The five connect flows in which you TYPE the credential. `kind` says which, and each takes
          *     the fields of its own configuration block. An OAuth connection is not made here: you grant
          *     access at the provider, so it starts with `POST /connection-authorizations`.
          *
@@ -180,6 +180,10 @@ export interface paths {
          *     signing in with none, a key in a header or a Bearer token (ONPLO-3478). OAuth on the
          *     server's own screen is not made here yet (ONPLO-4032).
          *
+         *     GITHUB IS CONNECTED AS AN APP (`kind: app`, ONPLO-4887): the app's id, its installation's
+         *     id and its private key, which is the credential, and optionally the repositories and the
+         *     permissions the connection is narrowed to. Making it calls nobody, as every connect here.
+         *
          *     THE CREDENTIAL IS WRITE-ONLY. It is visible while you type it and masked for ever after:
          *     it goes to the central vault as an entry in the Keys app, in this same account environment,
          *     and the connection that comes back carries that entry's id and never the value. Changing
@@ -481,14 +485,18 @@ export interface paths {
          *     one in the same Keys entry, so `credential_key_id` does not move, and nothing that uses the
          *     connection has to be redeployed.
          *
-         *     FOR A CONNECTION WHOSE CREDENTIAL YOU TYPED — an API key, a database, a Custom API or an
-         *     outside MCP server. An OAuth connection holds a grant rather than something you typed, and
+         *     FOR A CONNECTION WHOSE CREDENTIAL YOU TYPED — an API key, a database, a Custom API, an
+         *     outside MCP server or an app. An OAuth connection holds a grant rather than something you typed, and
          *     is renewed by reconnecting; this operation refuses it, and refuses a body of another kind,
          *     with `connection_kind_mismatch`.
          *
          *     THE BODY NAMES ITS KIND in `kind`, with the value creating a connection of that kind uses:
-         *     `api_key`, `database`, `custom_api` or `mcp_server`. A body that names no kind, or a kind
-         *     its fields are not, matches none of the four shapes and is refused with the 422.
+         *     `api_key`, `database`, `custom_api`, `mcp_server` or `app`. A body that names no kind, or a
+         *     kind its fields are not, matches none of the five shapes and is refused with the 422.
+         *
+         *     AN APP'S IS ITS PRIVATE KEY, AND ROTATING IT NEEDS NO RECONNECT (ONPLO-4887). GitHub lets an
+         *     app hold more than one key at once: make a new key at GitHub, enter it here, and delete the
+         *     old one at GitHub once the connection says the new one works. It keeps the same Keys entry.
          *
          *     AN MCP SERVER'S IS ITS KEY OR ITS TOKEN, FOR THE SAME ADDRESS, as a Custom API's is: nothing
          *     else is sent, and it keeps the same Keys entry (ONPLO-4031). One that signs in with nothing
@@ -2622,15 +2630,19 @@ export interface components {
         OwnerScope: "personal" | "company";
         /**
          * @description HOW THE CONNECTION PROVES ITSELF, and so which connect flow made it: an OAuth account, an
-         *     API key, a database, a custom API, a sign-up, an outside MCP server, or an app. A property
-         *     of the row, never a separate list.
+         *     API key, a database, a custom API, a sign-up, an outside MCP server, an app, or a role. A
+         *     property of the row, never a separate list.
+         *
+         *     `role` is a cloud account reached by a role Onplo assumes through OIDC federation, so it holds
+         *     no long-lived access key: AWS, given the role's address (its ARN), as a deploy target (ONPLO-4906). The
+         *     catalogue offers it; nothing makes one yet, so no connection carries it.
          *
          *     `app` is a system connected as an app the person made there, signing in as the app and never
          *     as a person: GitHub, given the app's id, the installation's id and the app's private key,
          *     which becomes the connection's Machine secret. Every call signs a token of at most 10 minutes
          *     with that key and trades it for an installation token of one hour, held only in memory
-         *     (ONPLO-4839). The catalogue offers it; nothing makes one yet (ONPLO-4887), so no connection
-         *     carries it.
+         *     (ONPLO-4839). `createConnection` makes one (ONPLO-4887); the trade itself is the vault's and
+         *     is not built yet (ONPLO-5233), so nothing calls through one yet.
          *
          *     `mcp_server` is an outside MCP server: its HTTPS address and a name, signing in with none,
          *     an API key in a header, a Bearer token, or OAuth on the server's own screen. What uses it is
@@ -2649,7 +2661,7 @@ export interface components {
          *     are read with `getCustomApiAddress` (decision 0811); and `POST /connections` makes one.
          * @enum {string}
          */
-        ConnectionKind: "oauth" | "api_key" | "database" | "custom_api" | "sign_up" | "mcp_server" | "app";
+        ConnectionKind: "oauth" | "api_key" | "database" | "custom_api" | "sign_up" | "mcp_server" | "app" | "role";
         /**
          * @description ONE VOCABULARY, used by every app that points at a connection: WORKING · EXPIRING · NOT
          *     WORKING · DISCONNECTED. Those four words are the whole set. `expiring` carries the date it
@@ -3116,6 +3128,63 @@ export interface components {
             /** @description Left out, it is off. */
             sub_processor?: components["schemas"]["SubProcessorTag"];
         };
+        /**
+         * @description A SYSTEM CONNECTED AS AN APP YOU MADE THERE: GitHub (ONPLO-4887). You make a GitHub App in
+         *     your organisation, install it on the repositories it may touch, and hand Onplo the app's
+         *     id, the installation's id and the app's private key. Every call shows at GitHub as the
+         *     app's, never as a person's, so the connection does not leave with whoever made it.
+         *
+         *     NARROWED PER CONNECTION. `repositories` may name fewer repositories than the app is
+         *     installed on, and `permissions` may leave out any the connection does not need. Two
+         *     connections may share one app with different reaches.
+         *
+         *     WHAT IS NOT DONE HERE YET: the call through it. Onplo signs a token of at most 10 minutes
+         *     with the key and trades it at GitHub for a one-hour installation token, held in memory
+         *     only. That trade is the vault's, and is not built yet (ONPLO-5233).
+         */
+        AppConnectionCreate: {
+            /** @enum {string} */
+            kind: "app";
+            /** @description Picked from the catalog. A system that offers no app connection is refused. */
+            system_id: components["schemas"]["Id"];
+            /** @description Left out, it is the system's own name. */
+            name?: components["schemas"]["ConnectionName"];
+            owner_scope: components["schemas"]["OwnerScope"];
+            /** @description Who manages it. Left out, it is you. */
+            owner_person_id?: components["schemas"]["Id"];
+            /**
+             * @description The number GitHub shows on the app's settings page.
+             * @example 123456
+             */
+            app_id: string;
+            /**
+             * @description The number in the address of the app's installation page, for the organisation or
+             *     account it is installed on.
+             * @example 98765432
+             */
+            installation_id: string;
+            /**
+             * @description WRITE-ONLY: the text of the private key file GitHub hands over, a PEM block. It becomes
+             *     the connection's Machine secret in the Keys app and is returned by no operation, to
+             *     anyone.
+             */
+            private_key: string;
+            /**
+             * @description The repositories this connection may touch, as `owner/name`, narrowed from those the
+             *     app is installed on. Left out or empty, all of them. A repository named twice is
+             *     refused (422 naming the field).
+             */
+            repositories?: string[];
+            /**
+             * @description The permissions this connection keeps on, each one of the catalog entry's scopes,
+             *     spelled as the entry spells it. Left out, all of them. One the entry does not list is
+             *     refused (422 naming the field): a permission the app was not made with cannot be
+             *     switched on here. They are answered as the connection's `provider_scopes`.
+             */
+            permissions?: string[];
+            /** @description Left out, it is off. */
+            sub_processor?: components["schemas"]["SubProcessorTag"];
+        };
         /**
          * @description THE KEY, THE TOKEN OR THE PASSWORD — "write-only, vaulted": visible while typing, masked
          *     for ever after. It is stored in the central vault and returned by no operation, to anyone.
@@ -3201,6 +3270,12 @@ export interface components {
             kind: "mcp_server";
             secret: components["schemas"]["CustomApiSecret"];
         };
+        AppCredential: {
+            /** @enum {string} */
+            kind: "app";
+            /** @description The new private key file's text, a PEM block. Write-only, as when it was connected. */
+            private_key: string;
+        };
         /**
          * @description WHERE AN MCP SERVER IS REACHED AND HOW IT SIGNS IN, WHOLE, WITH THE CREDENTIAL TYPED AGAIN.
          *
@@ -5084,7 +5159,7 @@ export interface operations {
         };
         requestBody: {
             content: {
-                "application/json": components["schemas"]["ApiKeyConnectionCreate"] | components["schemas"]["DatabaseConnectionCreate"] | components["schemas"]["CustomApiConnectionCreate"] | components["schemas"]["McpServerConnectionCreate"];
+                "application/json": components["schemas"]["ApiKeyConnectionCreate"] | components["schemas"]["DatabaseConnectionCreate"] | components["schemas"]["CustomApiConnectionCreate"] | components["schemas"]["McpServerConnectionCreate"] | components["schemas"]["AppConnectionCreate"];
             };
         };
         responses: {
@@ -5398,7 +5473,7 @@ export interface operations {
         };
         requestBody: {
             content: {
-                "application/json": components["schemas"]["ApiKeyCredential"] | components["schemas"]["DatabaseCredential"] | components["schemas"]["CustomApiCredential"] | components["schemas"]["McpServerCredential"];
+                "application/json": components["schemas"]["ApiKeyCredential"] | components["schemas"]["DatabaseCredential"] | components["schemas"]["CustomApiCredential"] | components["schemas"]["McpServerCredential"] | components["schemas"]["AppCredential"];
             };
         };
         responses: {

package/generated/keys.d.ts

@@ -20,6 +20,13 @@ export interface paths {
          *
          *     A KEY IN THE TRASH IS LEFT OUT unless `in_trash` asks for the Trash instead.
          *
+         *     THE TRASH ENDS IN ITS GHOSTS (decision 0672). A key deleted for good while a legal hold
+         *     covers it leaves use at once and stays under the Trash filter, after the keys in the Trash,
+         *     carrying `kept_by_legal_hold`. Which are drawn, and for whom, is the deletion service's to
+         *     say (decision 0686): the person a hidden hold names sees no ghost, and is answered exactly
+         *     what a key simply gone would answer. When the deletion service cannot be asked, no ghost is
+         *     drawn and the rest of the Trash is listed.
+         *
          *     A LIST IS REFUSED RATHER THAN CUT SHORT — `reach_too_wide`. The list is drawn from where
          *     your grants sit, and one list covers grants on at most 500 rings and at most 500 single
          *     keys. Somebody granted more than either is answered a 409 and no keys, because a list drawn
@@ -1990,7 +1997,7 @@ export interface paths {
         put?: never;
         /**
          * Attach a key to a flow project or a deploy environment
-         * @description EXPLICIT, PER TARGET, EVERY TIME (decision 0512). A target does not inherit a secret from a
+         * @description EXPLICIT, PER TARGET, EVERY TIME (decision 0512). A key is never attached to a target by the
          *     scope it happens to sit in: somebody with the right to grant it picks the entry and attaches
          *     it to THAT target, and again for the next one. It is a grant the one authorization service
          *     resolves, never a copy of the secret.
@@ -3118,6 +3125,31 @@ export interface components {
              *     leaves it suspended.
              */
             suspended_at: components["schemas"]["Timestamp"] | null;
+            /**
+             * @description "KEPT BY A LEGAL HOLD", AND SINCE WHEN — the line of a ghost row under the Trash filter
+             *     (decision 0672). What is kept is what the glossary calls a Ghost: the key was deleted for
+             *     good while a Compliance legal hold covered it, so it is out of use and erased when the
+             *     hold is released. A ROW CARRYING IT CANNOT BE OPENED, CHANGED, ROTATED, MOVED, REVEALED,
+             *     USED OR RESTORED: every operation on one key answers its id as a key that is not there.
+             *
+             *     THE ONE FIELD OF A KEY THAT MAY BE LEFT OUT, AND IT IS NEVER `null`. It is the deletion
+             *     service's to answer, for whoever is looking, and "a ghost is never shown unasked"
+             *     (decision 0686): so it is present exactly on a ghost this caller may see, which only the
+             *     Trash filter of the list draws. LEFT OUT MEANS ONLY THAT THIS ROW IS NO GHOST.
+             */
+            kept_by_legal_hold?: components["schemas"]["KeptByLegalHold"];
+        };
+        /**
+         * @description A KEY A LEGAL HOLD KEEPS: out of use, unreadable, and erased when the hold is released. It
+         *     names no hold and gives no reason — those are the Compliance app's, for the people allowed
+         *     to see them — and it carries no end date, because a hold has none.
+         */
+        KeptByLegalHold: {
+            /**
+             * @description SINCE WHEN IT IS KEPT: the moment it was deleted for good, never the moment the hold was
+             *     placed (the glossary's Ghost). Every app that points at one key shows this one moment.
+             */
+            since: components["schemas"]["Timestamp"];
         };
         /**
          * @description WHAT PUT A KEY IN THE TRASH, AND ITS NAME AS IT WAS THEN. The name is kept, never looked up:
@@ -4872,7 +4904,10 @@ export interface operations {
                 key_ring_id?: components["schemas"]["Id"];
                 /** @description Only keys of this kind. */
                 kind?: components["schemas"]["KeyKind"];
-                /** @description The Trash instead of the list — the keys waiting out their keep-time. */
+                /**
+                 * @description The Trash instead of the list — the keys waiting out their keep-time, and after them the
+                 *     keys a legal hold keeps, each carrying `kept_by_legal_hold`.
+                 */
                 in_trash?: boolean;
                 /**
                  * @description Only the suspended keys — the Suspended chip. Left out, suspended and unsuspended keys are
@@ -5752,7 +5787,10 @@ export interface operations {
              *     than the freshness window, or there has never been one, and for a credential that is not
              *     a person's signed-in session this is final. Or `device_wiped`. Or
              *     `fill_device_not_managed`: your company fills keys only on its managed devices, and
-             *     Devices did not say this one is managed and compliant.
+             *     Devices did not say this one is managed and compliant. Its `detail` names Devices'
+             *     reason in Devices' own words — `not_enrolled`, `not_compliant`, `unknown`, `stale`,
+             *     `exempt`, `check_in_too_old` or `device_not_there` — or `no_device_named` when this
+             *     session was signed in on no device.
              */
             403: {
                 headers: {

package/generated/storage.d.ts

@@ -4390,6 +4390,9 @@ export interface components {
          *     credential lacks the permission when all that is known is that we could not ask (decision
          *     0553). Every operation can raise it, the ungated ones included: a revoked credential dies on
          *     the next check and that check is the same hop.
+         *
+         *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+         *     ran, and the same request can be sent again.
          */
         ServiceUnavailable: {
             headers: {
@@ -4399,7 +4402,7 @@ export interface components {
             content: {
                 "application/problem+json": components["schemas"]["Problem"] & {
                     /** @enum {unknown} */
-                    code?: "authorization_unavailable";
+                    code?: "authorization_unavailable" | "database_unavailable";
                 };
             };
         };
@@ -4417,6 +4420,9 @@ export interface components {
          *     item, changing a share and ending one are written by the identity service itself. When it
          *     could not be reached, whether the share changed is not known — and sending the same request
          *     again is the same act, never a second share.
+         *
+         *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+         *     ran, and the same request can be sent again.
          */
         IdentityUnavailable: {
             headers: {
@@ -4426,7 +4432,7 @@ export interface components {
             content: {
                 "application/problem+json": components["schemas"]["Problem"] & {
                     /** @enum {unknown} */
-                    code?: "authorization_unavailable" | "identity_unavailable";
+                    code?: "authorization_unavailable" | "identity_unavailable" | "database_unavailable";
                 };
             };
         };
@@ -4455,6 +4461,9 @@ export interface components {
          *     upload's parts and cuts them (ONPLO-2344), hands out the address a file is read from
          *     (ONPLO-2720), and keeps and restores a file's work sessions (ONPLO-2758, ONPLO-2761). The same
          *     request can be sent again; a part already sent stays sent.
+         *
+         *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+         *     ran, and the same request can be sent again.
          */
         ObjectStoreUnavailable: {
             headers: {
@@ -4464,7 +4473,7 @@ export interface components {
             content: {
                 "application/problem+json": components["schemas"]["Problem"] & {
                     /** @enum {unknown} */
-                    code?: "authorization_unavailable" | "object_store_unavailable";
+                    code?: "authorization_unavailable" | "object_store_unavailable" | "database_unavailable";
                 };
             };
         };
@@ -4474,6 +4483,9 @@ export interface components {
          *     (`object_store_unavailable`), or the identity service, which is told a file exists before
          *     anyone can see it (`identity_unavailable`, decision 0635). The upload stays as it was, and
          *     finishing it again is safe.
+         *
+         *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+         *     ran, and the same request can be sent again.
          */
         UploadCompletionUnavailable: {
             headers: {
@@ -4483,7 +4495,7 @@ export interface components {
             content: {
                 "application/problem+json": components["schemas"]["Problem"] & {
                     /** @enum {unknown} */
-                    code?: "authorization_unavailable" | "object_store_unavailable" | "identity_unavailable";
+                    code?: "authorization_unavailable" | "object_store_unavailable" | "identity_unavailable" | "database_unavailable";
                 };
             };
         };
@@ -4494,6 +4506,9 @@ export interface components {
          *     event choices, so there was nothing to answer from and nothing was stored. The same request
          *     can be sent again. The two operations on Storage's own events answer this in place of the
          *     shared `503`.
+         *
+         *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+         *     ran, and the same request can be sent again.
          */
         NotificationsUnavailable: {
             headers: {
@@ -4503,7 +4518,7 @@ export interface components {
             content: {
                 "application/problem+json": components["schemas"]["Problem"] & {
                     /** @enum {unknown} */
-                    code?: "authorization_unavailable" | "notifications_unavailable";
+                    code?: "authorization_unavailable" | "notifications_unavailable" | "database_unavailable";
                 };
             };
         };
@@ -4515,6 +4530,9 @@ export interface components {
          *     is not "not held": no list is answered and no switch is refused in its place. The same
          *     request can be sent again. The two operations on your own Storage features, and the two
          *     on retention, answer this in place of the shared `503`.
+         *
+         *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+         *     ran, and the same request can be sent again.
          */
         AccountUnavailable: {
             headers: {
@@ -4524,7 +4542,7 @@ export interface components {
             content: {
                 "application/problem+json": components["schemas"]["Problem"] & {
                     /** @enum {unknown} */
-                    code?: "authorization_unavailable" | "account_unavailable";
+                    code?: "authorization_unavailable" | "account_unavailable" | "database_unavailable";
                 };
             };
         };
@@ -8622,6 +8640,9 @@ export interface operations {
             /**
              * @description The file store could not be asked for the address (`object_store_unavailable`). Nothing
              *     was counted or spent; the same request can be sent again.
+             *
+             *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+             *     ran, and the same request can be sent again.
              */
             503: {
                 headers: {
@@ -8631,7 +8652,7 @@ export interface operations {
                 content: {
                     "application/problem+json": components["schemas"]["Problem"] & {
                         /** @enum {unknown} */
-                        code?: "object_store_unavailable";
+                        code?: "object_store_unavailable" | "database_unavailable";
                     };
                 };
             };
@@ -8802,6 +8823,9 @@ export interface operations {
             /**
              * @description The file store could not be asked for the address (`object_store_unavailable`). Nothing
              *     was recorded; the same request can be sent again.
+             *
+             *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+             *     ran, and the same request can be sent again.
              */
             503: {
                 headers: {
@@ -8811,7 +8835,7 @@ export interface operations {
                 content: {
                     "application/problem+json": components["schemas"]["Problem"] & {
                         /** @enum {unknown} */
-                        code?: "object_store_unavailable";
+                        code?: "object_store_unavailable" | "database_unavailable";
                     };
                 };
             };
@@ -8882,6 +8906,9 @@ export interface operations {
             /**
              * @description The file store could not be asked for the zip (`object_store_unavailable`). Nothing was
              *     recorded; the same request can be sent again.
+             *
+             *     Or Storage's own database could not be reached — `database_unavailable` (ONPLO-5128). Nothing
+             *     ran, and the same request can be sent again.
              */
             503: {
                 headers: {
@@ -8891,7 +8918,7 @@ export interface operations {
                 content: {
                     "application/problem+json": components["schemas"]["Problem"] & {
                         /** @enum {unknown} */
-                        code?: "object_store_unavailable";
+                        code?: "object_store_unavailable" | "database_unavailable";
                     };
                 };
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onplo/sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "The Onplo SDK: a typed client for Onplo's public API, generated from its OpenAPI contracts.",
   "license": "Apache-2.0",
   "type": "module",