get recent request by id

William Duncan · William Duncan · commit 807b7b6ebb25 · 2023-03-08T09:52:45.000+02:00
diff --git a/README.md b/README.md
@@ -95,6 +95,7 @@ console.log(newsletter._response.status); // 200
    - [`cloudnode.newsletters.unsubscribe(subscription)`](#cloudnodenewslettersunsubscribesubscription)
    - [`cloudnode.token.create(permissions, lifetime, [note])`](#cloudnodetokencreatepermissions-lifetime-note)
    - [`cloudnode.token.get(id)`](#cloudnodetokengetid)
+   - [`cloudnode.token.getRequest(id, request)`](#cloudnodetokengetrequestid-request)
    - [`cloudnode.token.list([limit], [page], [internal])`](#cloudnodetokenlistlimit-page-internal)
    - [`cloudnode.token.listRequests(id, [limit], [page])`](#cloudnodetokenlistrequestsid-limit-page)
    - [`cloudnode.token.revoke(id)`](#cloudnodetokenrevokeid)
@@ -117,6 +118,7 @@ console.log(newsletter._response.status); // 200
    - [Interface: `Cloudnode.PartialToken`](#interface-cloudnodepartialtoken)
    - [Interface: `Cloudnode.Permission`](#interface-cloudnodepermission)
    - [Interface: `Cloudnode.PrimaryEmail`](#interface-cloudnodeprimaryemail)
+   - [Interface: `Cloudnode.Request`](#interface-cloudnoderequest)
    - [Interface: `Cloudnode.ShortRequest`](#interface-cloudnodeshortrequest)
    - [Interface: `Cloudnode.Token`](#interface-cloudnodetoken)
    - [Interface: `Cloudnode.TokenMetadata`](#interface-cloudnodetokenmetadata)
@@ -462,6 +464,23 @@ Get token details
  - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "INTERNAL_SERVER_ERROR"}</code>
  - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "MAINTENANCE"}</code>
 
+<a name="cloudnodetokengetrequestid-request"></a>
+
+### `cloudnode.token.getRequest(id, request)`
+
+Get a recent request by ID
+
+ - `id` <code>string | "current"</code> The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.
+ - `request` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)</code> The ID of the request.
+ - Returns: <code>[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Cloudnode.ApiResponse](#class-cloudnodeapiresponset)&lt;[Cloudnode.Request](#interface-cloudnoderequest)>></code>
+ - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "RESOURCE_NOT_FOUND"}</code>
+ - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "INVALID_DATA"}</code>
+ - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "UNAUTHORIZED"}</code>
+ - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "NO_PERMISSION"}</code>
+ - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "RATE_LIMITED"}</code>
+ - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "INTERNAL_SERVER_ERROR"}</code>
+ - Throws: <code>[Cloudnode.Error](#interface-cloudnodeerror) & {code: "MAINTENANCE"}</code>
+
 <a name="cloudnodetokenlistlimit-page-internal"></a>
 
 ### `cloudnode.token.list([limit], [page], [internal])`
@@ -712,6 +731,27 @@ Your current primary account e-mail address
  - `address` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [null](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null)</code> Your primary e-mail address. May ben null if anonymised.
  - `verified` <code>[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)</code> Whether this e-mail address has been verified
 
+<a name="interface-cloudnoderequest"></a>
+
+### Interface: `Cloudnode.Request`
+
+A request
+
+ - `id` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)</code> The ID of the request
+ - `method` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)</code> The request method (e.g. GET, POST, HEAD, etc.
+ - `scheme` <code>"http" | "https"</code> The URL scheme
+ - `host` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)</code> The requested host name
+ - `url` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)</code> The request URL path
+ - `status` <code>[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)</code> The HTTP status code that was returned to this request
+ - `ip` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)</code> The IP address of the client that made the request (can be both IPv4 and IPv6)
+ - `date` <code>[Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)</code> The time when the request was received
+ - `responseTime` <code>[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)</code> The time in milliseconds that the request took to process
+ - `hasEvents` <code>[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)</code> Whether any server-side error events occurred while processing this request
+ - `requestHeaders` <code>[Record](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | [null](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null)</code> The request headers that were received
+ - `requestBody` <code>[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [null](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null)</code> The request body that was received (likely parsed and formatted as JSON)
+ - `responseHeaders` <code>[Record](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | [null](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null)</code> The headers that were returned by the server
+ - `responseBody` <code>{type: "Buffer", data: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)[]} | [null](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null)</code> The response body that was returned by the server in response to this request
+
 <a name="interface-cloudnodeshortrequest"></a>
 
 ### Interface: `Cloudnode.ShortRequest`
diff --git a/browser/Cloudnode.js b/browser/Cloudnode.js
@@ -336,6 +336,22 @@ class Cloudnode {
         listRequests: async (id, limit = 10, page = 1) => {
             return await this.#sendRequest({ "type": "operation", "description": "Get list of recent requests made with the token", "token": "tokens.get.own.requests", "method": "GET", "path": "/token/:id/requests", "parameters": { "path": { "id": { "description": "The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.", "type": "string | \"current\"", "required": true } }, "query": { "limit": { "description": "The number of requests to return per page. No more than 50.", "default": "10", "type": "number", "required": false }, "page": { "description": "The page number. No more than 2³² (4294967296).", "default": "1", "type": "number", "required": false } } }, "returns": [{ "status": 200, "type": "ShortRequest[]" }, { "status": 404, "type": "Error & {code: \"RESOURCE_NOT_FOUND\"}" }, { "status": 422, "type": "Error & {code: \"INVALID_DATA\"}" }, { "status": 401, "type": "Error & {code: \"UNAUTHORIZED\"}" }, { "status": 403, "type": "Error & {code: \"NO_PERMISSION\"}" }, { "status": 429, "type": "Error & {code: \"RATE_LIMITED\"}" }, { "status": 500, "type": "Error & {code: \"INTERNAL_SERVER_ERROR\"}" }, { "status": 503, "type": "Error & {code: \"MAINTENANCE\"}" }] }, { id: `${id}` }, { limit: `${limit}`, page: `${page}` }, {});
         },
+        /**
+         * Get a recent request by ID
+         * @GET /token/:id/requests/:request
+         * @param id The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.
+         * @param request The ID of the request.
+         * @throws {Cloudnode.Error & {code: "RESOURCE_NOT_FOUND"}}
+         * @throws {Cloudnode.Error & {code: "INVALID_DATA"}}
+         * @throws {Cloudnode.Error & {code: "UNAUTHORIZED"}}
+         * @throws {Cloudnode.Error & {code: "NO_PERMISSION"}}
+         * @throws {Cloudnode.Error & {code: "RATE_LIMITED"}}
+         * @throws {Cloudnode.Error & {code: "INTERNAL_SERVER_ERROR"}}
+         * @throws {Cloudnode.Error & {code: "MAINTENANCE"}}
+         */
+        getRequest: async (id, request) => {
+            return await this.#sendRequest({ "type": "operation", "description": "Get a recent request by ID", "token": "tokens.get.own.requests", "method": "GET", "path": "/token/:id/requests/:request", "parameters": { "path": { "id": { "description": "The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.", "type": "string | \"current\"", "required": true }, "request": { "description": "The ID of the request.", "type": "string", "required": true } } }, "returns": [{ "status": 200, "type": "Request" }, { "status": 404, "type": "Error & {code: \"RESOURCE_NOT_FOUND\"}" }, { "status": 422, "type": "Error & {code: \"INVALID_DATA\"}" }, { "status": 401, "type": "Error & {code: \"UNAUTHORIZED\"}" }, { "status": 403, "type": "Error & {code: \"NO_PERMISSION\"}" }, { "status": 429, "type": "Error & {code: \"RATE_LIMITED\"}" }, { "status": 500, "type": "Error & {code: \"INTERNAL_SERVER_ERROR\"}" }, { "status": 503, "type": "Error & {code: \"MAINTENANCE\"}" }] }, { id: `${id}`, request: `${request}` }, {}, {});
+        },
     };
     tokens = {
         /**
diff --git a/browser/Cloudnode.min.js b/browser/Cloudnode.min.js
diff --git a/schema.json b/schema.json
@@ -404,6 +404,82 @@
           "type": "boolean"
         }
       ]
+    },
+    {
+      "name": "Request",
+      "description": "A request",
+      "fields": [
+        {
+          "name": "id",
+          "description": "The ID of the request",
+          "type": "string"
+        },
+        {
+          "name": "method",
+          "description": "The request method (e.g. GET, POST, HEAD, etc.",
+          "type": "string"
+        },
+        {
+          "name": "scheme",
+          "description": "The URL scheme",
+          "type": "\"http\" | \"https\""
+        },
+        {
+          "name": "host",
+          "description": "The requested host name",
+          "type": "string"
+        },
+        {
+          "name": "url",
+          "description": "The request URL path",
+          "type": "string"
+        },
+        {
+          "name": "status",
+          "description": "The HTTP status code that was returned to this request",
+          "type": "number"
+        },
+        {
+          "name": "ip",
+          "description": "The IP address of the client that made the request (can be both IPv4 and IPv6)",
+          "type": "string"
+        },
+        {
+          "name": "date",
+          "description": "The time when the request was received",
+          "type": "Date"
+        },
+        {
+          "name": "responseTime",
+          "description": "The time in milliseconds that the request took to process",
+          "type": "number"
+        },
+        {
+          "name": "hasEvents",
+          "description": "Whether any server-side error events occurred while processing this request",
+          "type": "boolean"
+        },
+        {
+          "name": "requestHeaders",
+          "description": "The request headers that were received",
+          "type": "Record<string, string> | null"
+        },
+        {
+          "name": "requestBody",
+          "description": "The request body that was received (likely parsed and formatted as JSON)",
+          "type": "string | null"
+        },
+        {
+          "name": "responseHeaders",
+          "description": "The headers that were returned by the server",
+          "type": "Record<string, string> | null"
+        },
+        {
+          "name": "responseBody",
+          "description": "The response body that was returned by the server in response to this request",
+          "type": "{type: \"Buffer\", data: number[]} | null"
+        }
+      ]
     }
   ],
   "operations": {
@@ -753,6 +829,41 @@
               "type": "Error & {code: \"INVALID_DATA\"}"
             }
           ]
+        },
+        "getRequest": {
+          "type": "operation",
+          "description": "Get a recent request by ID",
+          "token": "tokens.get.own.requests",
+          "method": "GET",
+          "path": "/token/:id/requests/:request",
+          "parameters": {
+            "path": {
+              "id": {
+                "description": "The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.",
+                "type": "string | \"current\"",
+                "required": true
+              },
+              "request": {
+                "description": "The ID of the request.",
+                "type": "string",
+                "required": true
+              }
+            }
+          },
+          "returns": [
+            {
+              "status": 200,
+              "type": "Request"
+            },
+            {
+              "status": 404,
+              "type": "Error & {code: \"RESOURCE_NOT_FOUND\"}"
+            },
+            {
+              "status": 422,
+              "type": "Error & {code: \"INVALID_DATA\"}"
+            }
+          ]
         }
       }
     },
diff --git a/src/Cloudnode.d.ts b/src/Cloudnode.d.ts
@@ -172,6 +172,20 @@ declare class Cloudnode {
          * @throws {Cloudnode.Error & {code: "MAINTENANCE"}}
          */
         readonly listRequests: (id: string | "current", limit?: number, page?: number) => Promise<Cloudnode.ApiResponse<Cloudnode.PaginatedData<Cloudnode.ShortRequest[]>>>;
+        /**
+         * Get a recent request by ID
+         * @GET /token/:id/requests/:request
+         * @param id The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.
+         * @param request The ID of the request.
+         * @throws {Cloudnode.Error & {code: "RESOURCE_NOT_FOUND"}}
+         * @throws {Cloudnode.Error & {code: "INVALID_DATA"}}
+         * @throws {Cloudnode.Error & {code: "UNAUTHORIZED"}}
+         * @throws {Cloudnode.Error & {code: "NO_PERMISSION"}}
+         * @throws {Cloudnode.Error & {code: "RATE_LIMITED"}}
+         * @throws {Cloudnode.Error & {code: "INTERNAL_SERVER_ERROR"}}
+         * @throws {Cloudnode.Error & {code: "MAINTENANCE"}}
+         */
+        readonly getRequest: (id: string | "current", request: string) => Promise<Cloudnode.ApiResponse<Cloudnode.Request>>;
     };
     tokens: {
         /**
@@ -662,6 +676,70 @@ declare namespace Cloudnode {
          */
         hasEvents: boolean;
     }
+    /**
+     * A request
+     */
+    interface Request {
+        /**
+         * The ID of the request
+         */
+        id: string;
+        /**
+         * The request method (e.g. GET, POST, HEAD, etc.
+         */
+        method: string;
+        /**
+         * The URL scheme
+         */
+        scheme: "http" | "https";
+        /**
+         * The requested host name
+         */
+        host: string;
+        /**
+         * The request URL path
+         */
+        url: string;
+        /**
+         * The HTTP status code that was returned to this request
+         */
+        status: number;
+        /**
+         * The IP address of the client that made the request (can be both IPv4 and IPv6)
+         */
+        ip: string;
+        /**
+         * The time when the request was received
+         */
+        date: Date;
+        /**
+         * The time in milliseconds that the request took to process
+         */
+        responseTime: number;
+        /**
+         * Whether any server-side error events occurred while processing this request
+         */
+        hasEvents: boolean;
+        /**
+         * The request headers that were received
+         */
+        requestHeaders: Record<string, string> | null;
+        /**
+         * The request body that was received (likely parsed and formatted as JSON)
+         */
+        requestBody: string | null;
+        /**
+         * The headers that were returned by the server
+         */
+        responseHeaders: Record<string, string> | null;
+        /**
+         * The response body that was returned by the server in response to this request
+         */
+        responseBody: {
+            type: "Buffer";
+            data: number[];
+        } | null;
+    }
     /**
      * Paginated response
      */
diff --git a/src/Cloudnode.js b/src/Cloudnode.js
@@ -336,6 +336,22 @@ class Cloudnode {
         listRequests: async (id, limit = 10, page = 1) => {
             return await this.#sendRequest({ "type": "operation", "description": "Get list of recent requests made with the token", "token": "tokens.get.own.requests", "method": "GET", "path": "/token/:id/requests", "parameters": { "path": { "id": { "description": "The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.", "type": "string | \"current\"", "required": true } }, "query": { "limit": { "description": "The number of requests to return per page. No more than 50.", "default": "10", "type": "number", "required": false }, "page": { "description": "The page number. No more than 2³² (4294967296).", "default": "1", "type": "number", "required": false } } }, "returns": [{ "status": 200, "type": "ShortRequest[]" }, { "status": 404, "type": "Error & {code: \"RESOURCE_NOT_FOUND\"}" }, { "status": 422, "type": "Error & {code: \"INVALID_DATA\"}" }, { "status": 401, "type": "Error & {code: \"UNAUTHORIZED\"}" }, { "status": 403, "type": "Error & {code: \"NO_PERMISSION\"}" }, { "status": 429, "type": "Error & {code: \"RATE_LIMITED\"}" }, { "status": 500, "type": "Error & {code: \"INTERNAL_SERVER_ERROR\"}" }, { "status": 503, "type": "Error & {code: \"MAINTENANCE\"}" }] }, { id: `${id}` }, { limit: `${limit}`, page: `${page}` }, {});
         },
+        /**
+         * Get a recent request by ID
+         * @GET /token/:id/requests/:request
+         * @param id The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.
+         * @param request The ID of the request.
+         * @throws {Cloudnode.Error & {code: "RESOURCE_NOT_FOUND"}}
+         * @throws {Cloudnode.Error & {code: "INVALID_DATA"}}
+         * @throws {Cloudnode.Error & {code: "UNAUTHORIZED"}}
+         * @throws {Cloudnode.Error & {code: "NO_PERMISSION"}}
+         * @throws {Cloudnode.Error & {code: "RATE_LIMITED"}}
+         * @throws {Cloudnode.Error & {code: "INTERNAL_SERVER_ERROR"}}
+         * @throws {Cloudnode.Error & {code: "MAINTENANCE"}}
+         */
+        getRequest: async (id, request) => {
+            return await this.#sendRequest({ "type": "operation", "description": "Get a recent request by ID", "token": "tokens.get.own.requests", "method": "GET", "path": "/token/:id/requests/:request", "parameters": { "path": { "id": { "description": "The ID of the token. Specify `current` to get information about the token that was used to authenticate the request.", "type": "string | \"current\"", "required": true }, "request": { "description": "The ID of the request.", "type": "string", "required": true } } }, "returns": [{ "status": 200, "type": "Request" }, { "status": 404, "type": "Error & {code: \"RESOURCE_NOT_FOUND\"}" }, { "status": 422, "type": "Error & {code: \"INVALID_DATA\"}" }, { "status": 401, "type": "Error & {code: \"UNAUTHORIZED\"}" }, { "status": 403, "type": "Error & {code: \"NO_PERMISSION\"}" }, { "status": 429, "type": "Error & {code: \"RATE_LIMITED\"}" }, { "status": 500, "type": "Error & {code: \"INTERNAL_SERVER_ERROR\"}" }, { "status": 503, "type": "Error & {code: \"MAINTENANCE\"}" }] }, { id: `${id}`, request: `${request}` }, {}, {});
+        },
     };
     tokens = {
         /**
diff --git a/src/Cloudnode.ts b/src/Cloudnode.ts
