@vuevox/sdk 0.1.0 → 0.3.0

package/README.md

@@ -18,10 +18,11 @@ Settings -> Developer API -> Manage API Clients
 
 Create a client, select the scopes it can request, and copy the `client_secret` immediately. VueVox shows each client secret only once.
 
-Available scope:
+Available scopes:
 
 ```text
 hello:read
+spaces:read
 ```
 
 ## Basic Usage
@@ -32,18 +33,47 @@ import { createVueVoxClient } from "@vuevox/sdk";
 const vuevox = createVueVoxClient({
   clientId: process.env.VUEVOX_CLIENT_ID!,
   clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
-  scope: "hello:read",
+  scope: ["hello:read", "spaces:read"],
 });
 
 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.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";
@@ -51,14 +81,14 @@ import { VueVoxApiError, createVueVoxClient } from "@vuevox/sdk";
 const vuevox = createVueVoxClient({
   clientId: process.env.VUEVOX_CLIENT_ID!,
   clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
-  scope: "hello:read",
+  scope: ["hello:read", "spaces:read"],
 });
 
 try {
-  await vuevox.hello();
+  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;
@@ -100,7 +130,7 @@ const vuevox = createVueVoxClient({
   baseUrl: "https://api.vuevox.com",
   clientId: process.env.VUEVOX_CLIENT_ID!,
   clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
-  scope: "hello:read",
+  scope: ["hello:read", "spaces:read"],
 });
 ```
 
@@ -115,3 +145,18 @@ const { data, error } = await vuevox.raw.GET("/v1/hello", {
   },
 });
 ```
+
+## Pagination
+
+List endpoints use cursor pagination.
+
+```ts
+const firstPage = await vuevox.listSpaces({ limit: 50 });
+
+if (firstPage.data.pagination.nextCursor) {
+  const secondPage = await vuevox.listSpaces({
+    limit: 50,
+    cursor: firstPage.data.pagination.nextCursor,
+  });
+}
+```

package/dist/client.d.ts

@@ -1,15 +1,33 @@
 import type { components, paths } from "./generated/schema.js";
 type HelloResponse = components["schemas"]["HelloResponse"];
+type SpacesListResponse = components["schemas"]["SpacesListResponse"];
+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>;
+    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,14 +44,34 @@ 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(listOptions = {}) {
+        const accessToken = await getAccessToken();
+        const { data, error, response } = await raw.GET("/v1/spaces", {
+            params: {
+                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, requestId);
+        }
+        return withMetadata(data, response, requestId);
     }
     return {
         getAccessToken,
         hello,
+        listSpaces,
         raw,
     };
 }
@@ -76,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/generated/schema.d.ts

@@ -44,6 +44,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/spaces": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List organization spaces
+         * @description Returns spaces for the API client's organization using cursor pagination.
+         */
+        get: operations["listSpaces"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -72,6 +92,30 @@ export interface components {
             /** @example Hello world */
             message: string;
         };
+        Space: {
+            /** Format: uuid */
+            id: string;
+            /** @example Sales Team */
+            name: string;
+            /** @example Workspace for inbound sales calls. */
+            description: string | null;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        SpacesListResponse: {
+            data: components["schemas"]["Space"][];
+            pagination: components["schemas"]["CursorPagination"];
+        };
+        CursorPagination: {
+            /** @example 50 */
+            limit: number;
+            /** @example false */
+            hasMore: boolean;
+            /** @description Opaque cursor to pass as cursor on the next request. */
+            nextCursor: string | null;
+        };
         ErrorResponse: {
             error: components["schemas"]["Error"];
         };
@@ -197,4 +241,69 @@ export interface operations {
             };
         };
     };
+    listSpaces: {
+        parameters: {
+            query?: {
+                /** @description Number of spaces to return. Defaults to 50. Maximum is 100. */
+                limit?: number;
+                /** @description Opaque cursor from the previous response's pagination.nextCursor value. */
+                cursor?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Paginated spaces response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SpacesListResponse"];
+                };
+            };
+            /** @description Bearer token is missing, invalid, or expired. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Bearer token does not include the required scope. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Query parameters failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Per-client rate limit exceeded. */
+            429: {
+                headers: {
+                    /** @description Seconds to wait before retrying. */
+                    "Retry-After"?: string;
+                    /** @description Request limit per minute for this API client. */
+                    "X-RateLimit-Limit"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createVueVoxClient } from "./client.js";
-export type { 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.1.0",
+  "version": "0.3.0",
   "description": "TypeScript SDK for the VueVox Developer API.",
   "type": "module",
   "main": "./dist/index.js",