@vuevox/sdk 0.2.0 → 0.3.0

package/README.md

@@ -37,17 +37,43 @@ const vuevox = createVueVoxClient({
 });
 
 const hello = await vuevox.hello();
-console.log(hello.message);
+console.log(hello.data.message);
+console.log(hello.requestId);
 
 const spaces = await vuevox.listSpaces({ limit: 50 });
-console.log(spaces.data);
+console.log(spaces.data.data);
+console.log(spaces.requestId);
 ```
 
 The SDK requests and caches a short-lived access token using client credentials, then sends it as a bearer token for API calls.
 
+## Request IDs
+
+Every Developer API response includes an `X-Request-Id` header. SDK endpoint methods return response metadata with the response body so you can log that ID for support requests.
+
+```ts
+const spaces = await vuevox.listSpaces({ limit: 50 });
+
+console.log(spaces.requestId);
+console.log(spaces.data.data);
+```
+
+For centralized logging, pass `onResponse`. The hook runs for every SDK-managed HTTP response, including the token request.
+
+```ts
+const vuevox = createVueVoxClient({
+  clientId: process.env.VUEVOX_CLIENT_ID!,
+  clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
+  scope: ["hello:read", "spaces:read"],
+  onResponse: ({ method, path, status, requestId }) => {
+    console.log({ method, path, status, requestId });
+  },
+});
+```
+
 ## Error Handling
 
-API errors throw `VueVoxApiError`.
+API errors throw `VueVoxApiError`. The SDK exposes `error.requestId` from either the response header or error body.
 
 ```ts
 import { VueVoxApiError, createVueVoxClient } from "@vuevox/sdk";
@@ -62,7 +88,7 @@ try {
   await vuevox.listSpaces({ limit: 50 });
 } catch (error) {
   if (error instanceof VueVoxApiError) {
-    console.error(error.status, error.code, error.message);
+    console.error(error.status, error.code, error.message, error.requestId);
   }
 
   throw error;
@@ -127,10 +153,10 @@ List endpoints use cursor pagination.
 ```ts
 const firstPage = await vuevox.listSpaces({ limit: 50 });
 
-if (firstPage.pagination.nextCursor) {
+if (firstPage.data.pagination.nextCursor) {
   const secondPage = await vuevox.listSpaces({
     limit: 50,
-    cursor: firstPage.pagination.nextCursor,
+    cursor: firstPage.data.pagination.nextCursor,
   });
 }
 ```

package/dist/client.d.ts

@@ -5,17 +5,29 @@ export interface ListSpacesOptions {
     limit?: number;
     cursor?: string;
 }
+export interface VueVoxResponseMetadata {
+    requestId?: string;
+    status: number;
+}
+export interface VueVoxApiResponse<T> extends VueVoxResponseMetadata {
+    data: T;
+}
+export interface VueVoxResponseEvent extends VueVoxResponseMetadata {
+    method: string;
+    path: string;
+}
 export interface VueVoxClientOptions {
     baseUrl?: string;
     clientId: string;
     clientSecret: string;
     scope?: string | string[];
     fetch?: typeof fetch;
+    onResponse?: (event: VueVoxResponseEvent) => void;
 }
 export declare function createVueVoxClient(options: VueVoxClientOptions): {
     getAccessToken: () => Promise<string>;
-    hello: () => Promise<HelloResponse>;
-    listSpaces: (options?: ListSpacesOptions) => Promise<SpacesListResponse>;
+    hello: () => Promise<VueVoxApiResponse<HelloResponse>>;
+    listSpaces: (listOptions?: ListSpacesOptions) => Promise<VueVoxApiResponse<SpacesListResponse>>;
     raw: import("openapi-fetch").Client<paths, `${string}/${string}`>;
 };
 export {};

package/dist/client.js

@@ -22,12 +22,14 @@ export function createVueVoxClient(options) {
             }),
         });
         const body = await parseJson(response);
+        const requestId = getRequestId(response, body);
+        notifyResponse(options, "POST", "/oauth/token", response, requestId);
         if (!response.ok) {
             const error = isErrorResponse(body) ? body.error : null;
-            throw new VueVoxApiError(response.status, error?.code ?? "token_request_failed", error?.message ?? "VueVox token request failed.", isErrorResponse(body) ? body : undefined);
+            throw new VueVoxApiError(response.status, error?.code ?? "token_request_failed", error?.message ?? "VueVox token request failed.", isErrorResponse(body) ? body : undefined, requestId);
         }
         if (!isTokenResponse(body)) {
-            throw new VueVoxApiError(response.status, "invalid_token_response", "VueVox returned an invalid token response.");
+            throw new VueVoxApiError(response.status, "invalid_token_response", "VueVox returned an invalid token response.", undefined, requestId);
         }
         cachedToken = {
             accessToken: body.access_token,
@@ -42,25 +44,29 @@ export function createVueVoxClient(options) {
                 Authorization: `Bearer ${accessToken}`,
             },
         });
+        const requestId = getRequestId(response, error);
+        notifyResponse(options, "GET", "/v1/hello", response, requestId);
         if (error) {
-            throw new VueVoxApiError(response.status, error.error.code, error.error.message, error);
+            throw new VueVoxApiError(response.status, error.error.code, error.error.message, error, requestId);
         }
-        return data;
+        return withMetadata(data, response, requestId);
     }
-    async function listSpaces(options = {}) {
+    async function listSpaces(listOptions = {}) {
         const accessToken = await getAccessToken();
         const { data, error, response } = await raw.GET("/v1/spaces", {
             params: {
-                query: options,
+                query: listOptions,
             },
             headers: {
                 Authorization: `Bearer ${accessToken}`,
             },
         });
+        const requestId = getRequestId(response, error);
+        notifyResponse(options, "GET", "/v1/spaces", response, requestId);
         if (error) {
-            throw new VueVoxApiError(response.status, error.error.code, error.error.message, error);
+            throw new VueVoxApiError(response.status, error.error.code, error.error.message, error, requestId);
         }
-        return data;
+        return withMetadata(data, response, requestId);
     }
     return {
         getAccessToken,
@@ -92,3 +98,24 @@ function isTokenResponse(value) {
 function isErrorResponse(value) {
     return Boolean(value && "error" in value);
 }
+function getRequestId(response, body) {
+    return response.headers.get("X-Request-Id") ?? (isErrorBody(body) ? body.error.requestId : undefined);
+}
+function isErrorBody(value) {
+    return Boolean(value && "error" in value);
+}
+function withMetadata(data, response, requestId) {
+    return {
+        data,
+        requestId,
+        status: response.status,
+    };
+}
+function notifyResponse(options, method, path, response, requestId) {
+    options.onResponse?.({
+        method,
+        path,
+        requestId,
+        status: response.status,
+    });
+}

package/dist/errors.d.ts

@@ -3,6 +3,7 @@ export type VueVoxErrorResponse = components["schemas"]["ErrorResponse"];
 export declare class VueVoxApiError extends Error {
     readonly status: number;
     readonly code: string;
+    readonly requestId?: string;
     readonly response?: VueVoxErrorResponse;
-    constructor(status: number, code: string, message: string, response?: VueVoxErrorResponse);
+    constructor(status: number, code: string, message: string, response?: VueVoxErrorResponse, requestId?: string);
 }

package/dist/errors.js

@@ -1,12 +1,14 @@
 export class VueVoxApiError extends Error {
     status;
     code;
+    requestId;
     response;
-    constructor(status, code, message, response) {
+    constructor(status, code, message, response, requestId) {
         super(message);
         this.name = "VueVoxApiError";
         this.status = status;
         this.code = code;
+        this.requestId = requestId ?? response?.error.requestId;
         this.response = response;
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createVueVoxClient } from "./client.js";
-export type { ListSpacesOptions, VueVoxClientOptions } from "./client.js";
+export type { ListSpacesOptions, VueVoxApiResponse, VueVoxClientOptions, VueVoxResponseEvent, VueVoxResponseMetadata, } from "./client.js";
 export { VueVoxApiError } from "./errors.js";
 export type { VueVoxErrorResponse } from "./errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vuevox/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript SDK for the VueVox Developer API.",
   "type": "module",
   "main": "./dist/index.js",