hcloud-sdk 17.0.0 → 19.0.0

package/lib/service/high5/wave/s3/index.js

@@ -8,11 +8,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.S3 = void 0;
-const axios_1 = require("axios");
+const axios_1 = __importDefault(require("axios"));
 const package_json_1 = require("../../../../../package.json");
-const Base_1 = require("../../../../Base");
+const Base_1 = __importDefault(require("../../../../Base"));
 const axios_2 = require("../../../../interfaces/axios");
 const sdkVersion = "hcloud-sdk-js/v" + package_json_1.version;
 /**
@@ -27,12 +30,12 @@ class S3 extends Base_1.default {
      * @param waveBucketUrl Public base url to S3 bucket
      * @returns registry.json
      */
-    getCatalogRegistry(waveBucketUrl) {
+    getCatalogRegistry(waveBucketUrl, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const resp = yield axios_1.default.get(`${waveBucketUrl}/catalogs/registry.json`, {
-                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion }),
+                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }),
             });
-            return resp.data;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -40,12 +43,12 @@ class S3 extends Base_1.default {
      * @param waveBucketUrl Public base url to S3 bucket
      * @returns registry.json
      */
-    getEngineRegistry(waveBucketUrl) {
+    getEngineRegistry(waveBucketUrl, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const resp = yield axios_1.default.get(`${waveBucketUrl}/engines/registry.json`, {
-                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion }),
+                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }),
             });
-            return resp.data;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -53,10 +56,12 @@ class S3 extends Base_1.default {
      * @param catalogUrl Public url of the catalog
      * @returns index.json of catalog
      */
-    getCatalog(catalogUrl) {
+    getCatalog(catalogUrl, raw) {
         return __awaiter(this, void 0, void 0, function* () {
-            const resp = yield axios_1.default.get(`${catalogUrl}`, { headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion }) });
-            return resp.data;
+            const resp = yield axios_1.default.get(`${catalogUrl}`, {
+                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }),
+            });
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -64,10 +69,12 @@ class S3 extends Base_1.default {
      * @param catalogUrl Public url of the catalog
      * @returns index.json of catalog
      */
-    getEngine(engineUrl) {
+    getEngine(engineUrl, raw) {
         return __awaiter(this, void 0, void 0, function* () {
-            const resp = yield axios_1.default.get(`${engineUrl}`, { headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion }) });
-            return resp.data;
+            const resp = yield axios_1.default.get(`${engineUrl}`, {
+                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }),
+            });
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -76,12 +83,12 @@ class S3 extends Base_1.default {
      * @param engineVersion Version of the enigne
      * @returns Wildcards.json list of available wildcards
      */
-    getWildcardsOfEngine(engineUrl, engineVersion) {
+    getWildcardsOfEngine(engineUrl, engineVersion, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const resp = yield axios_1.default.get(`${engineUrl.replace("/index.json", "")}/${engineVersion}/wildcards.json`, {
-                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion }),
+                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }),
             });
-            return resp.data;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -90,13 +97,13 @@ class S3 extends Base_1.default {
      * @param version The catalog version
      * @returns StreamNodeSpecification[] | StreamNodeSpecificationWrappedWithEngineVersion an array of all node specification of that catalog version, maybe wrapped in an object with the engine version
      */
-    getCatalogVersion(catalogUrl, version) {
+    getCatalogVersion(catalogUrl, version, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const specificationUrl = catalogUrl.split("/").slice(0, -1).join("/") + "/" + version + "/specification.json";
             const resp = yield axios_1.default.get(specificationUrl, {
-                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion }),
+                headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }),
             });
-            return resp.data;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -105,13 +112,30 @@ class S3 extends Base_1.default {
      * @param version The catalog version
      * @returns string the markdown documentation of the node
      */
-    getNodeDocumentation(catalogUrl, version, nodeName) {
+    getNodeDocumentation(catalogUrl, version, nodeName, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const specificationUrl = catalogUrl.split("/").slice(0, -1).join("/") + `/${version}/docs/${nodeName}.md`;
-            const resp = yield axios_1.default.get(specificationUrl).catch(err => {
+            const resp = yield axios_1.default
+                .get(specificationUrl, { headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }) })
+                .catch(err => {
+                throw new Error(`Node documentation not found: ${err}`);
+            });
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
+        });
+    }
+    /**
+     * Get the catalogs changelog from the S3 bucket
+     * @param catalogUrl Public url of the catalog
+     * @returns string the changelog.json of the node
+     */
+    getChangelog(catalogUrl, raw) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const resp = yield axios_1.default
+                .get(catalogUrl + "changelog.json", { headers: Object.assign(Object.assign({}, axios_2.disableCacheHeaders), { "x-hcloud-user-agent": sdkVersion, Authorization: undefined }) })
+                .catch(err => {
                 throw new Error(`Node documentation not found: ${err}`);
             });
-            return resp.data;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     getEndpoint() {

package/lib/service/idp/guest/index.d.ts

@@ -0,0 +1,42 @@
+import Base, { MaybeRaw } from "../../../Base";
+import { SuccessfulAuth } from "../../../interfaces/idp";
+export declare class IdpGuest extends Base {
+    /**
+     * Creates a new guest user account.
+     *
+     * @param email - The email address of the guest to create.
+     * @param name - The display name of the guest user.
+     * @param emailHMAC - An HMAC signature of the email, used for validation.
+     * @returns A promise resolving to a `SuccessfulAuth` object containing:
+     *   - `user`: The created `User` object.
+     *   - `token`: An authorization token returned by the API.
+     */
+    createGuest<R extends boolean = false>(email: string, name: string, emailHMAC: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, SuccessfulAuth>>;
+    /**
+     * Logs in as an existing guest user.
+     *
+     * @param email - The email address of the guest to log in.
+     * @param emailHMAC - An HMAC signature of the email, used for validation.
+     * @returns A promise resolving to a `SuccessfulAuth` object containing:
+     *   - `user`: The authenticated `User` object.
+     *   - `token`: An authorization token returned by the API.
+     */
+    loginAsGuest<R extends boolean = false>(email: string, emailHMAC: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, SuccessfulAuth>>;
+    /**
+     * Checks whether an email corresponds to a guest account.
+     *
+     * @param email - The email address to check.
+     * @returns A promise resolving to one of:
+     *   - `"no user"` → No user exists with the given email.
+     *   - `"not guest"` → A user exists but is not a guest.
+     *   - `"guest"` → The email belongs to a guest account.
+     */
+    isGuest<R extends boolean = false>(email: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, "no user" | "not guest" | "guest">>;
+    protected getEndpoint(endpoint: string): string;
+}

package/lib/service/idp/guest/index.js

@@ -0,0 +1,69 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdpGuest = void 0;
+const Base_1 = __importDefault(require("../../../Base"));
+class IdpGuest extends Base_1.default {
+    /**
+     * Creates a new guest user account.
+     *
+     * @param email - The email address of the guest to create.
+     * @param name - The display name of the guest user.
+     * @param emailHMAC - An HMAC signature of the email, used for validation.
+     * @returns A promise resolving to a `SuccessfulAuth` object containing:
+     *   - `user`: The created `User` object.
+     *   - `token`: An authorization token returned by the API.
+     */
+    createGuest(email, name, emailHMAC, raw) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const resp = yield this.axios.post(this.getEndpoint("/v1/guest"), { email, name, hmac: emailHMAC });
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw)
+                ? Object.assign(Object.assign({}, resp), { data: { user: resp.data, token: resp.headers.authorization } }) : { user: resp.data, token: resp.headers.authorization });
+        });
+    }
+    /**
+     * Logs in as an existing guest user.
+     *
+     * @param email - The email address of the guest to log in.
+     * @param emailHMAC - An HMAC signature of the email, used for validation.
+     * @returns A promise resolving to a `SuccessfulAuth` object containing:
+     *   - `user`: The authenticated `User` object.
+     *   - `token`: An authorization token returned by the API.
+     */
+    loginAsGuest(email, emailHMAC, raw) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.axios.put(this.getEndpoint("/v1/guest"), { email, hmac: emailHMAC });
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? Object.assign(Object.assign({}, res), { data: { user: res.data, token: res.headers.authorization } }) : { user: res.data, token: res.headers.authorization });
+        });
+    }
+    /**
+     * Checks whether an email corresponds to a guest account.
+     *
+     * @param email - The email address to check.
+     * @returns A promise resolving to one of:
+     *   - `"no user"` → No user exists with the given email.
+     *   - `"not guest"` → A user exists but is not a guest.
+     *   - `"guest"` → The email belongs to a guest account.
+     */
+    isGuest(email, raw) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.axios.get(this.getEndpoint(`/v1/guest/email/${email}`));
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? res : res.data);
+        });
+    }
+    getEndpoint(endpoint) {
+        return `${this.options.server}/api/account${endpoint}`;
+    }
+}
+exports.IdpGuest = IdpGuest;

package/lib/service/idp/index.d.ts

@@ -1,7 +1,8 @@
-import Base from "../../Base";
+import Base, { MaybeRaw } from "../../Base";
 import { Version } from "../../interfaces/global";
 import { PreLoginResponse } from "../../interfaces/idp";
 import { SuccessfulAuth } from "../../interfaces/idp/user/SuccessfulAuth";
+import { IdpGuest } from "./guest";
 import { IdpInternal } from "./internal";
 import { IdpOAuth } from "./oauth";
 import { IdpOrganization } from "./organization";
@@ -28,6 +29,11 @@ export default class Idp extends Base {
      */
     get user(): IdpUser;
     private _user?;
+    /**
+     * Handles everything around a guest
+     */
+    get guest(): IdpGuest;
+    private _guest?;
     /**
      * Handles everything around idp's internal endpoints
      */
@@ -37,7 +43,9 @@ export default class Idp extends Base {
      * Requests the endpoint version
      * @returns Version object
      */
-    version(): Promise<Version>;
+    version<R extends boolean = false>(raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, Version>>;
     /**
      * Authenticates against the identity provider with a given email and password.
      * @param email Email of the user
@@ -45,7 +53,9 @@ export default class Idp extends Base {
      * @param token (optional) token if 2FA-TOTP is enabled
      * @returns SuccessfulAuth object holding the token and the user
      */
-    login(email: string, password: string, token?: string): Promise<SuccessfulAuth>;
+    login<R extends boolean = false>(email: string, password: string, token?: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, SuccessfulAuth>>;
     /**
      * Starts the login process via OIDC
      * @param origin The starting URL of the process. After obtaining the credentials, the user will be redirected back to this url.
@@ -54,14 +64,18 @@ export default class Idp extends Base {
      * @param hint Valid email address of the user that wants to login. Hint must be defined when provider is not.
      * @returns URL that must be accessed via a browser to continue the login process.
      */
-    loginWithOIDC(origin: string, oidcProvider?: string, hint?: string): Promise<string>;
+    loginWithOIDC<R extends boolean = false>(origin: string, oidcProvider?: string, hint?: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, string>>;
     /**
      * Starts the login process via SAML 2.0
      * @param origin The starting URL of the process. After obtaining the credentials, the user will be redirected back to this url.
      * @param email  Email of the user. The email domain will be used to determine the appropriate SAML 2.0 provider to use going forward.
      * @returns URL that must be accessed via a browser to continue the login process.
      */
-    loginWithSAML(origin: string, email: string): Promise<string>;
+    loginWithSAML<R extends boolean = false>(origin: string, email: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, string>>;
     /**
      * Determine if/how the given email can authenticate.
      *
@@ -71,7 +85,9 @@ export default class Idp extends Base {
      * @returns object that dictates if: the user needs to REGISTER; the user needs to VERIFY_EMAIL; the user can LOGIN using this email;
      *          or the authentication process should continue via an EXTERNAL provider that can be found via the location property.
      */
-    preLogin(email: string, origin: string): Promise<PreLoginResponse>;
+    preLogin<R extends boolean = false>(email: string, origin: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, PreLoginResponse>>;
     /**
      * Initiate the password reset process. An email will be sent to the user to move to the next phase.
      *
@@ -79,6 +95,8 @@ export default class Idp extends Base {
      * @param captcha Valid google reCAPTCHAV2
      * @param targetUrl Optional url the link in the mail will point to
      */
-    resetPassword(email: string, captcha: string, targetUrl?: string): Promise<void>;
+    resetPassword<R extends boolean = false>(email: string, captcha: string, targetUrl?: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, void>>;
     protected getEndpoint(endpoint: string): string;
 }

package/lib/service/idp/index.js

@@ -8,8 +8,12 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const Base_1 = require("../../Base");
+const Base_1 = __importDefault(require("../../Base"));
+const guest_1 = require("./guest");
 const internal_1 = require("./internal");
 const oauth_1 = require("./oauth");
 const organization_1 = require("./organization");
@@ -52,6 +56,15 @@ class Idp extends Base_1.default {
         }
         return this._user;
     }
+    /**
+     * Handles everything around a guest
+     */
+    get guest() {
+        if (this._guest === undefined) {
+            this._guest = new guest_1.IdpGuest(this.options, this.axios);
+        }
+        return this._guest;
+    }
     /**
      * Handles everything around idp's internal endpoints
      */
@@ -65,10 +78,10 @@ class Idp extends Base_1.default {
      * Requests the endpoint version
      * @returns Version object
      */
-    version() {
+    version(raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const resp = yield this.axios.get(this.getEndpoint("/v1/version"));
-            return resp.data;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -78,7 +91,7 @@ class Idp extends Base_1.default {
      * @param token (optional) token if 2FA-TOTP is enabled
      * @returns SuccessfulAuth object holding the token and the user
      */
-    login(email, password, token) {
+    login(email, password, token, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             let body = { email: email, password: password };
@@ -90,7 +103,7 @@ class Idp extends Base_1.default {
                 token: ((_a = resp.headers["authorization"]) === null || _a === void 0 ? void 0 : _a.toString()) || "",
                 user: resp.data,
             };
-            return authed;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? Object.assign(Object.assign({}, resp), { data: authed }) : authed);
         });
     }
     /**
@@ -101,7 +114,7 @@ class Idp extends Base_1.default {
      * @param hint Valid email address of the user that wants to login. Hint must be defined when provider is not.
      * @returns URL that must be accessed via a browser to continue the login process.
      */
-    loginWithOIDC(origin, oidcProvider, hint) {
+    loginWithOIDC(origin, oidcProvider, hint, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const resp = yield this.axios.get(this.getEndpoint("/v1/login/oidc"), {
                 params: {
@@ -118,7 +131,7 @@ class Idp extends Base_1.default {
             if (!location) {
                 throw new Error("Location header is undefined.");
             }
-            return location;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : location);
         });
     }
     /**
@@ -127,7 +140,7 @@ class Idp extends Base_1.default {
      * @param email  Email of the user. The email domain will be used to determine the appropriate SAML 2.0 provider to use going forward.
      * @returns URL that must be accessed via a browser to continue the login process.
      */
-    loginWithSAML(origin, email) {
+    loginWithSAML(origin, email, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const resp = yield this.axios.get(this.getEndpoint("/v1/login/saml"), {
                 params: {
@@ -143,7 +156,7 @@ class Idp extends Base_1.default {
             if (!location) {
                 throw new Error("Location header is undefined.");
             }
-            return location;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : location);
         });
     }
     /**
@@ -155,7 +168,7 @@ class Idp extends Base_1.default {
      * @returns object that dictates if: the user needs to REGISTER; the user needs to VERIFY_EMAIL; the user can LOGIN using this email;
      *          or the authentication process should continue via an EXTERNAL provider that can be found via the location property.
      */
-    preLogin(email, origin) {
+    preLogin(email, origin, raw) {
         return __awaiter(this, void 0, void 0, function* () {
             const resp = yield this.axios.get(this.getEndpoint("/v1/login/pre"), {
                 params: {
@@ -163,7 +176,7 @@ class Idp extends Base_1.default {
                     email,
                 },
             });
-            return resp.data;
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : resp.data);
         });
     }
     /**
@@ -173,9 +186,10 @@ class Idp extends Base_1.default {
      * @param captcha Valid google reCAPTCHAV2
      * @param targetUrl Optional url the link in the mail will point to
      */
-    resetPassword(email, captcha, targetUrl) {
+    resetPassword(email, captcha, targetUrl, raw) {
         return __awaiter(this, void 0, void 0, function* () {
-            yield this.axios.post(this.getEndpoint("/v1/login/forgot_password"), { email, captcha, targetUrl });
+            const resp = yield this.axios.post(this.getEndpoint("/v1/login/forgot_password"), { email, captcha, targetUrl });
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw) ? resp : undefined);
         });
     }
     getEndpoint(endpoint) {

package/lib/service/idp/internal/index.d.ts

@@ -1,4 +1,4 @@
-import Base from "../../../Base";
+import Base, { MaybeRaw } from "../../../Base";
 import { User } from "../../../interfaces/idp/user";
 export declare class IdpInternal extends Base {
     /**
@@ -9,9 +9,11 @@ export declare class IdpInternal extends Base {
      * @param orgName Name of the organization
      * @returns the created user and a pat token
      */
-    createAgentUser(orgName: string): Promise<{
+    createAgentUser<R extends boolean = false>(orgName: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, {
         user: User;
         pat: string;
-    }>;
+    }>>;
     protected getEndpoint(endpoint: string): string;
 }

package/lib/service/idp/internal/index.js

@@ -8,9 +8,12 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IdpInternal = void 0;
-const Base_1 = require("../../../Base");
+const Base_1 = __importDefault(require("../../../Base"));
 class IdpInternal extends Base_1.default {
     /**
      * Creates an agent user for an organization.
@@ -20,10 +23,12 @@ class IdpInternal extends Base_1.default {
      * @param orgName Name of the organization
      * @returns the created user and a pat token
      */
-    createAgentUser(orgName) {
+    createAgentUser(orgName, raw) {
         return __awaiter(this, void 0, void 0, function* () {
-            const res = yield this.axios.post(this.getEndpoint(`/internal/v1/org/${orgName}/agent`));
-            return { user: res.data, pat: res.headers.authorization };
+            var _a, _b;
+            const resp = yield this.axios.post(this.getEndpoint(`/internal/v1/org/${orgName}/agent`));
+            return ((raw === null || raw === void 0 ? void 0 : raw.raw)
+                ? Object.assign(Object.assign({}, resp), { data: { user: resp.data, pat: (_a = resp.headers["x-pat-token"]) !== null && _a !== void 0 ? _a : "" } }) : { user: resp.data, pat: (_b = resp.headers["x-pat-token"]) !== null && _b !== void 0 ? _b : "" });
         });
     }
     getEndpoint(endpoint) {

package/lib/service/idp/oauth/device.d.ts

@@ -0,0 +1,131 @@
+import Base, { MaybeRaw } from "../../../Base";
+import { OAuthAppPublicInfo, Scope } from "../../../interfaces/idp";
+import { OAuthDeviceAuthorizationResponse, OAuthDeviceTokenResponse } from "../../../interfaces/idp/oauth/device";
+/**
+ * IdpOAuthDevice
+ *
+ * Client wrapper for OAuth 2.0 Device Authorization Grant (RFC 8628).
+ *
+ * This class provides methods to:
+ * - Initiate a device authorization request
+ * - Validate a user-provided code
+ * - Approve or reject a device authorization
+ * - Exchange a device code for an access token
+ *
+ * All methods support returning either the parsed response body or the raw Axios
+ * response via the `{ raw: true }` option.
+ *
+ * @extends Base
+ */
+export default class IdpOAuthDevice extends Base {
+    /**
+     * Initiates the OAuth Device Authorization flow.
+     *
+     * This endpoint returns a `device_code` and `user_code` which should be:
+     * - Displayed to the user on the device
+     * - Entered by the user on a separate verification page
+     *
+     * @typeParam R - Whether to return the raw Axios response
+     *
+     * @param clientId - OAuth client identifier
+     * @param scope - Optional OAuth scope string (space-delimited)
+     * @param raw - Optional flag to return the raw Axios response
+     *
+     * @returns Device authorization response or raw Axios response
+     */
+    authorize<R extends boolean = false>(clientId: string, scope?: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, OAuthDeviceAuthorizationResponse>>;
+    /**
+     * Validates a user-entered device code.
+     *
+     * This is typically called by the authorization UI after the user enters
+     * the `user_code`. It returns public information about the requesting
+     * application and the requested scopes.
+     *
+     * @typeParam R - Whether to return the raw Axios response
+     *
+     * @param clientId - OAuth client identifier
+     * @param userCode - User-facing verification code
+     * @param raw - Optional flag to return the raw Axios response
+     *
+     * @returns Application public info and requested scopes
+     */
+    validateUserCode<R extends boolean = false>(clientId: string, userCode: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, {
+        app: OAuthAppPublicInfo;
+        scopes: Scope[];
+    }>>;
+    /**
+     * Approves or rejects a device authorization request.
+     *
+     * ⚠️ This endpoint requires an `Authorization` header to be set
+     * on the HCloud instance (e.g., a logged-in user session or access token).
+     *
+     * @typeParam R - Whether to return the raw Axios response
+     *
+     * @param clientId - OAuth client identifier
+     * @param userCode - User-facing verification code
+     * @param status - Authorization decision (`APPROVED` or `REJECTED`)
+     * @param raw - Optional flag to return the raw Axios response
+     *
+     * @throws Error if the Authorization header is not set
+     *
+     * @returns Void response or raw Axios response
+     */
+    decide<R extends boolean = false>(clientId: string, userCode: string, status: "APPROVED" | "REJECTED", raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, void>>;
+    /**
+     * Approves a device authorization request.
+     *
+     * Shorthand for {@link decide} with status `"APPROVED"`.
+     *
+     * @typeParam R - Whether to return the raw Axios response
+     *
+     * @param clientId - OAuth client identifier
+     * @param userCode - User-facing verification code
+     * @param raw - Optional flag to return the raw Axios response
+     *
+     * @returns Void response or raw Axios response
+     */
+    approve<R extends boolean = false>(clientId: string, userCode: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, void>>;
+    /**
+     * Rejects a device authorization request.
+     *
+     * Shorthand for {@link decide} with status `"REJECTED"`.
+     *
+     * @typeParam R - Whether to return the raw Axios response
+     *
+     * @param clientId - OAuth client identifier
+     * @param userCode - User-facing verification code
+     * @param raw - Optional flag to return the raw Axios response
+     *
+     * @returns Void response or raw Axios response
+     */
+    reject<R extends boolean = false>(clientId: string, userCode: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, void>>;
+    /**
+     * Exchanges a device code for an access token.
+     *
+     * This endpoint may return HTTP 400 responses for non-fatal OAuth states
+     * such as `authorization_pending` or `slow_down`. These responses are
+     * returned normally and should be handled by the caller.
+     *
+     * @typeParam R - Whether to return the raw Axios response
+     *
+     * @param clientId - OAuth client identifier
+     * @param deviceCode - Device code obtained from {@link authorize}
+     * @param raw - Optional flag to return the raw Axios response
+     *
+     * @returns Device token response or raw Axios response
+     */
+    token<R extends boolean = false>(clientId: string, deviceCode: string, raw?: {
+        raw: R;
+    }): Promise<MaybeRaw<R, OAuthDeviceTokenResponse>>;
+    protected getEndpoint(endpoint: string): string;
+}