@vuevox/sdk 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @vuevox/sdk
+
+TypeScript SDK for the VueVox Developer API.
+
+## Install
+
+```bash
+npm install @vuevox/sdk
+```
+
+## Create API Credentials
+
+In VueVox, open:
+
+```text
+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:
+
+```text
+hello:read
+```
+
+## Basic Usage
+
+```ts
+import { createVueVoxClient } from "@vuevox/sdk";
+
+const vuevox = createVueVoxClient({
+  clientId: process.env.VUEVOX_CLIENT_ID!,
+  clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
+  scope: "hello:read",
+});
+
+const hello = await vuevox.hello();
+console.log(hello.message);
+```
+
+The SDK requests and caches a short-lived access token using client credentials, then sends it as a bearer token for API calls.
+
+## Error Handling
+
+API errors throw `VueVoxApiError`.
+
+```ts
+import { VueVoxApiError, createVueVoxClient } from "@vuevox/sdk";
+
+const vuevox = createVueVoxClient({
+  clientId: process.env.VUEVOX_CLIENT_ID!,
+  clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
+  scope: "hello:read",
+});
+
+try {
+  await vuevox.hello();
+} catch (error) {
+  if (error instanceof VueVoxApiError) {
+    console.error(error.status, error.code, error.message);
+  }
+
+  throw error;
+}
+```
+
+Common API error codes:
+
+```text
+missing_token
+invalid_token
+invalid_client
+invalid_scope
+insufficient_scope
+rate_limited
+```
+
+## Token Behavior
+
+The SDK:
+
+- Requests tokens using client credentials.
+- Caches the access token in memory.
+- Refreshes the token before expiry.
+- Never stores credentials or tokens on disk.
+
+## Base URL
+
+The SDK defaults to:
+
+```text
+https://api.vuevox.com
+```
+
+If VueVox support gives you a custom API base URL, pass it explicitly:
+
+```ts
+const vuevox = createVueVoxClient({
+  baseUrl: "https://api.vuevox.com",
+  clientId: process.env.VUEVOX_CLIENT_ID!,
+  clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
+  scope: "hello:read",
+});
+```
+
+## Lower-Level Calls
+
+For advanced integrations, `raw` exposes a typed lower-level API client.
+
+```ts
+const { data, error } = await vuevox.raw.GET("/v1/hello", {
+  headers: {
+    Authorization: `Bearer ${await vuevox.getAccessToken()}`,
+  },
+});
+```

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import type { components, paths } from "./generated/schema.js";
+type HelloResponse = components["schemas"]["HelloResponse"];
+export interface VueVoxClientOptions {
+    baseUrl?: string;
+    clientId: string;
+    clientSecret: string;
+    scope?: string | string[];
+    fetch?: typeof fetch;
+}
+export declare function createVueVoxClient(options: VueVoxClientOptions): {
+    getAccessToken: () => Promise<string>;
+    hello: () => Promise<HelloResponse>;
+    raw: import("openapi-fetch").Client<paths, `${string}/${string}`>;
+};
+export {};

package/dist/client.js

@@ -0,0 +1,78 @@
+import createClient from "openapi-fetch";
+import { VueVoxApiError } from "./errors.js";
+export function createVueVoxClient(options) {
+    const baseUrl = trimTrailingSlash(options.baseUrl ?? "https://api.vuevox.com");
+    const fetchFn = options.fetch ?? fetch;
+    const raw = createClient({ baseUrl, fetch: fetchFn });
+    let cachedToken = null;
+    async function getAccessToken() {
+        if (cachedToken && Date.now() < cachedToken.expiresAt - 30_000) {
+            return cachedToken.accessToken;
+        }
+        const response = await fetchFn(`${baseUrl}/oauth/token`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                grant_type: "client_credentials",
+                client_id: options.clientId,
+                client_secret: options.clientSecret,
+                scope: formatScope(options.scope),
+            }),
+        });
+        const body = await parseJson(response);
+        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);
+        }
+        if (!isTokenResponse(body)) {
+            throw new VueVoxApiError(response.status, "invalid_token_response", "VueVox returned an invalid token response.");
+        }
+        cachedToken = {
+            accessToken: body.access_token,
+            expiresAt: Date.now() + body.expires_in * 1000,
+        };
+        return cachedToken.accessToken;
+    }
+    async function hello() {
+        const accessToken = await getAccessToken();
+        const { data, error, response } = await raw.GET("/v1/hello", {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+        });
+        if (error) {
+            throw new VueVoxApiError(response.status, error.error.code, error.error.message, error);
+        }
+        return data;
+    }
+    return {
+        getAccessToken,
+        hello,
+        raw,
+    };
+}
+function formatScope(scope) {
+    if (Array.isArray(scope)) {
+        return scope.join(" ");
+    }
+    return scope;
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+async function parseJson(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+function isTokenResponse(value) {
+    return Boolean(value && "access_token" in value);
+}
+function isErrorResponse(value) {
+    return Boolean(value && "error" in value);
+}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+import type { components } from "./generated/schema.js";
+export type VueVoxErrorResponse = components["schemas"]["ErrorResponse"];
+export declare class VueVoxApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly response?: VueVoxErrorResponse;
+    constructor(status: number, code: string, message: string, response?: VueVoxErrorResponse);
+}

package/dist/errors.js

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

package/dist/generated/schema.d.ts

@@ -0,0 +1,200 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/oauth/token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create an access token
+         * @description Issues a short-lived bearer token using OAuth client credentials.
+         */
+        post: operations["createAccessToken"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/hello": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Return a hello world message
+         * @description Protected starter endpoint for validating developer API authentication and SDK wiring.
+         */
+        get: operations["getHello"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        TokenRequest: {
+            /** @enum {string} */
+            grant_type: "client_credentials";
+            client_id: string;
+            client_secret: string;
+            /**
+             * @description Space-separated scopes requested for the access token.
+             * @example hello:read
+             */
+            scope?: string;
+        };
+        TokenResponse: {
+            access_token: string;
+            /** @enum {string} */
+            token_type: "Bearer";
+            /** @example 3600 */
+            expires_in: number;
+            /** @example hello:read */
+            scope: string;
+        };
+        HelloResponse: {
+            /** @example Hello world */
+            message: string;
+        };
+        ErrorResponse: {
+            error: components["schemas"]["Error"];
+        };
+        Error: {
+            /** @example invalid_token */
+            code: string;
+            /** @example Bearer token is invalid or expired. */
+            message: string;
+            /** @example req_123 */
+            requestId: string;
+            details?: {
+                [key: string]: unknown;
+            };
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    createAccessToken: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TokenRequest"];
+            };
+        };
+        responses: {
+            /** @description Access token issued. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenResponse"];
+                };
+            };
+            /** @description Requested scope is not allowed. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Client authentication failed. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Request body failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    getHello: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Hello response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HelloResponse"];
+                };
+            };
+            /** @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 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

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

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createVueVoxClient } from "./client.js";
+export { VueVoxApiError } from "./errors.js";

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vuevox/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the VueVox Developer API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "vuevox",
+    "sdk",
+    "api",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc --outDir dist && mkdir -p dist/generated && cp src/generated/schema.d.ts dist/generated/schema.d.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run --access public"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.14.0"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.10.1",
+    "typescript": "^5.9.3"
+  }
+}