@bagelink/sdk 1.8.28 → 1.8.32

package/README.md

@@ -1,64 +1,95 @@
-# @bagelink/vue
+# @bagelink/sdk
 
-Features:
+OpenAPI-based TypeScript SDK generator with Vue 3 composables.
 
-- Build with [unbuild](https://github.com/unjs/unbuild)
-- File-to-file transpilation via [mkdist](https://github.com/unjs/mkdist)
-- Playground with [vite](https://vitejs.dev/)
+## Features
 
-## Usage
+- 🚀 Generate type-safe SDKs from OpenAPI specifications
+- 🎯 Enhanced responses - array + metadata in one object
+- 🔐 Built-in authentication support
+- 🎨 FastAPI/Pydantic error parsing
+- 📡 SSE/Stream support with type safety
+- ⚡ Request state management composables
+- 🔧 Flexible configuration with interceptors
 
-Use component globally
+## Installation
 
-```ts
-// src/main.ts
-import { createApp } from 'vue';
-import { BagelVue } from '@bagel/vue';
+```bash
+pnpm add @bagelink/sdk
+```
 
-import App from './App.vue';
+## Quick Start
 
-const BagelConfig = {
-  host: '/api',
-  onError: (err: any) => {
-    // handle error
-    // example:
-    // useToast().error(`${$t('anErrorOccurred')}: ${err?.response?.data?.detail || err.message}`);
-  },
-};
+### 1. Generate SDK
+
+```bash
+# From OpenAPI spec
+VITE_BAGEL_BASE_URL=https://api.example.com bun run bin/index.ts .bagelink
+```
 
-const app = createApp(App);
-app.use(head as Plugin);
+### 2. Initialize
 
-app.mount('#app');
+```typescript
+import { createApi } from './.bagelink/api'
+
+createApi({
+  baseURL: '/api',
+  withCredentials: true
+})
 ```
 
-Import component
+### 3. Use
+
+```typescript
+import { useApi } from './.bagelink/api'
+
+const api = useApi()
+const users = await api.users.get()
 
-```vue
-<script setup lang="ts">
-import { useBagel } from '@bagel/vue';
+// Array operations
+for (const user of users) {
+  console.log(user.name)
+}
 
-const bagel = useBagel();
-</script>
+// Metadata
+console.log(users.totalCount, users.page)
 
-<!-- OR -->
-<script lang="ts">
-export default defineComponent({
-  onMounted() {
-    console.log(this.$bagel.host)
+// Raw access
+console.log(users.$raw.headers)
+```
+
+## Configuration
+
+```typescript
+createApi({
+  baseURL: '/api',
+  withCredentials: true,
+  auth: {
+    getToken: () => localStorage.getItem('token'),
+    onUnauthorized: () => router.push('/login')
   },
-});
-</script>
-
-<!-- OR -->
-<template>
-	<div>
-		{{ $bagel.host }}
-	</div>
-</template>
+  onError: (error) => {
+    console.error(error.message)
+    if (error.fields) {
+      // Handle validation errors
+    }
+  },
+  interceptors: {
+    request: (config) => {
+      // Modify request
+      return config
+    }
+  }
+})
 ```
 
+## State Management
+
+```typescript
+import { useApiRequest } from './.bagelink/api'
 
-## License
+const { loading, error, data, execute } = useApiRequest(
+  () => api.users.get()
+)
+```
 
-MIT

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 const axios$1 = require('axios');
+const vue = require('vue');
 
 function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
 
@@ -638,7 +639,11 @@ function generateAxiosFunction(method, formattedPath, allParams, responseTypeStr
   if (allParams === "undefined") {
     allParams = "";
   }
-  let axiosFunction = `async (${allParams})${responseTypeStr} => {`;
+  const apiResponseType = responseTypeStr.replace(
+    /Promise<AxiosResponse<(.+)>>/,
+    "Promise<ApiResponse<$1>>"
+  );
+  let axiosFunction = `async (${allParams})${apiResponseType} => {`;
   const paramStr = parameters.config?.params ? `params: {${parameters.config.params}}` : "";
   if (requestBodyPayload === "formData") {
     if (allParams.includes("file: File")) {
@@ -646,20 +651,24 @@ function generateAxiosFunction(method, formattedPath, allParams, responseTypeStr
         const formData = new FormData()
         formData.append('file', file)
 		formData.append('upload', file)
-        return axios.${method}(${formattedPath}, formData, {
+        const response = await axios.${method}(${formattedPath}, formData, {
             headers: { 'Content-Type': 'multipart/form-data' },
             onUploadProgress: options?.onUploadProgress${paramStr ? `, ${paramStr}` : ""}
-        })`;
+        })
+        return ApiResponse.create(response.data, response)`;
     } else {
       axiosFunction += `
-        return axios.${method}(${formattedPath}, formData, {
+        const response = await axios.${method}(${formattedPath}, formData, {
             headers: { 'Content-Type': 'multipart/form-data' }${paramStr ? `, ${paramStr}` : ""}
-        })`;
+        })
+        return ApiResponse.create(response.data, response)`;
     }
   } else {
     const configParams = paramStr ? `, { ${paramStr} }` : "";
     const bodyVar = requestBodyPayload || "{}";
-    axiosFunction += `return axios.${method}(${formattedPath}${["get", "delete"].includes(method) ? configParams : `, ${bodyVar}${configParams}`})`;
+    axiosFunction += `
+        const response = await axios.${method}(${formattedPath}${["get", "delete"].includes(method) ? configParams : `, ${bodyVar}${configParams}`})
+        return ApiResponse.create(response.data, response)`;
   }
   axiosFunction += "}";
   return axiosFunction;
@@ -818,6 +827,7 @@ function generateFunctions(paths, baseUrl) {
     }, body);
   }
   let tsString = "";
+  const apiObjectEntries = [];
   for (const [parent, object] of Object.entries(body)) {
     tsString += `
 /**
@@ -825,7 +835,16 @@ function generateFunctions(paths, baseUrl) {
  */
 export const ${parent} = ${JSON.stringify(object, void 0, 2)};
 `;
+    apiObjectEntries.push(parent);
   }
+  tsString += `
+/**
+ * Aggregated API object containing all endpoints
+ */
+export const api = {
+${apiObjectEntries.map((name) => `	${name},`).join("\n")}
+};
+`;
   Object.entries(functionsInventory).forEach(([key, value]) => {
     tsString = tsString.replace(`"${key}"`, value);
   });
@@ -901,11 +920,27 @@ function generateStreamEventTypeDefinitions() {
 function fileTemplate(tsString, typeForImport, baseURL) {
   const streamTypeDefs = generateStreamEventTypeDefinitions();
   const hasStreamEndpoints = Object.keys(streamEventTypes).length > 0;
-  const streamImports = hasStreamEndpoints ? `import { createSSEStreamPost, StreamController, type SSEStreamOptions } from '@bagelink/sdk';` : "";
+  const streamImports = hasStreamEndpoints ? `createSSEStreamPost, createSSEStream, StreamController, type SSEStreamOptions,` : "";
   const templateCode = `import ax from 'axios';
 import type { AxiosResponse } from 'axios';
 import type { ${typeForImport.join(", ")} } from './types.d';
-${streamImports}
+import {
+	ApiResponse,
+	parseApiError,
+	formatFieldErrors,
+	useApiRequest,
+	useCancellableRequest,
+	${streamImports}
+	type ApiConfig,
+	type ParsedError,
+	type FastAPIValidationError,
+	type FastAPIErrorResponse,
+	type ResponseMetadata,
+	type ApiRequestState,
+	type RequestInterceptor,
+	type ResponseInterceptor
+} from '@bagelink/sdk';
+import { ref, type Ref } from 'vue';
 
 /**
  * Options for file upload operations
@@ -920,14 +955,154 @@ export interface UploadOptions {
 }
 
 ${streamTypeDefs}
+
 /**
  * Configured axios instance for API requests
- * @example
- * // Making a direct request with the axios instance
- * const response = await axios.get('/some-endpoint');
  */
 export const axios = ax.create({baseURL: '${baseURL}', withCredentials: true});
-${tsString}`;
+
+${tsString}
+
+// ============================================================================
+// API Instance & Configuration
+// ============================================================================
+
+/**
+ * Last response metadata (accessible via useApi().$lastResponse)
+ */
+const lastResponse = ref<AxiosResponse | null>(null)
+
+/**
+ * API instance type with enhanced response objects
+ */
+type ApiInstance = typeof api & {
+	$raw: typeof api
+	$lastResponse: Ref<AxiosResponse | null>
+	$axios: typeof axios
+	$ApiResponse: typeof ApiResponse
+}
+
+// Global state
+let apiConfig: ApiConfig | null = null
+let apiInstance: ApiInstance | null = null
+
+/**
+ * Create and configure the API instance
+ * @param config - API configuration options
+ * @returns Configured API instance
+ */
+export function createApi(config: ApiConfig = {}): ApiInstance {
+	// Store config
+	apiConfig = config
+
+	// Configure axios defaults
+	if (config.baseURL) {
+		axios.defaults.baseURL = config.baseURL
+	}
+	if (config.withCredentials !== undefined) {
+		axios.defaults.withCredentials = config.withCredentials
+	}
+	if (config.axiosConfig) {
+		Object.assign(axios.defaults, config.axiosConfig)
+	}
+
+	// Clear existing interceptors
+	axios.interceptors.request.clear()
+	axios.interceptors.response.clear()
+
+	// Setup auth interceptor
+	if (config.auth) {
+		axios.interceptors.request.use(async (reqConfig) => {
+			const token = await config.auth!.getToken?.()
+			if (token) {
+				const prefix = config.auth!.tokenPrefix ?? 'Bearer'
+				reqConfig.headers.Authorization = \`\${prefix} \${token}\`
+			}
+			return reqConfig
+		})
+	}
+
+	// Setup custom request interceptor
+	if (config.interceptors?.request) {
+		axios.interceptors.request.use(config.interceptors.request)
+	}
+
+	// Setup response interceptor for error handling
+	axios.interceptors.response.use(
+		(response) => {
+			// Store last response for metadata access
+			lastResponse.value = response
+			
+			// Apply custom response interceptor if provided
+			if (config.interceptors?.response) {
+				return config.interceptors.response(response)
+			}
+			return response
+		},
+		async (error) => {
+			// Handle 401 Unauthorized
+			if (error.response?.status === 401) {
+				await config.auth?.onUnauthorized?.()
+			}
+
+			// Parse and handle error
+			const parsedError = parseApiError(error)
+			config.onError?.(parsedError, error)
+
+			throw error
+		}
+	)
+
+	// API already returns ApiResponse directly!
+	// Just add the special properties
+	apiInstance = {
+		...api,
+		$raw: api,
+		$lastResponse: lastResponse,
+		$axios: axios,
+		$ApiResponse: ApiResponse
+	} as ApiInstance
+
+	return apiInstance
+}
+
+/**
+ * Access the configured API instance
+ * @returns API instance with enhanced response objects
+ * @throws Error if createApi hasn't been called
+ */
+export function useApi(): ApiInstance {
+	if (!apiInstance) {
+		throw new Error(
+			'API not initialized. Call createApi() first.\\n\\n' +
+			'Example:\\n' +
+			'import { createApi } from \\'./generated/api\\'\\n' +
+			'createApi({ baseURL: \\'/api\\' })'
+		)
+	}
+	return apiInstance
+}
+
+// ============================================================================
+// Re-export utilities for convenience
+// ============================================================================
+
+export {
+	parseApiError,
+	formatFieldErrors,
+	useApiRequest,
+	useCancellableRequest,
+	ApiResponse,
+	type ApiConfig,
+	type ParsedError,
+	type ResponseMetadata,
+	type ApiRequestState,
+	type FastAPIValidationError,
+	type FastAPIErrorResponse,
+	type RequestInterceptor,
+	type ResponseInterceptor
+}
+`;
   return templateCode.replace(/"([^"]+)":/g, "$1:");
 }
 
@@ -1249,6 +1424,238 @@ function formatAPIErrorMessage(err) {
   return `An error occurred (Status ${status}): ${error.message || "Unknown error"}`;
 }
 
+class ApiResponse extends Array {
+  /** Raw axios response */
+  $raw;
+  /** Total number of items (from x-total-count header) */
+  totalCount;
+  /** Current page number (from x-page header) */
+  page;
+  /** Items per page (from x-per-page header) */
+  perPage;
+  /** Total number of pages (calculated) */
+  totalPages;
+  /** Rate limit remaining (from x-ratelimit-remaining header) */
+  rateLimit;
+  /** Rate limit reset timestamp (from x-ratelimit-reset header) */
+  rateLimitReset;
+  /** All response metadata */
+  $metadata;
+  constructor(data, response) {
+    super();
+    if (Array.isArray(data)) {
+      this.push(...data);
+      if (response) {
+        this.$raw = response;
+        this.$metadata = ApiResponse.parseMetadataStatic(response);
+        this.totalCount = this.$metadata.totalCount;
+        this.page = this.$metadata.page;
+        this.perPage = this.$metadata.perPage;
+        this.totalPages = this.$metadata.totalPages;
+        this.rateLimit = this.$metadata.rateLimit;
+        this.rateLimitReset = this.$metadata.rateLimitReset;
+      }
+    }
+  }
+  /**
+   * Create an ApiResponse from data and response
+   * Factory method to handle both arrays and objects
+   */
+  static create(data, response) {
+    if (!Array.isArray(data)) {
+      const obj = Object.assign(/* @__PURE__ */ Object.create(null), data);
+      obj.$raw = response;
+      obj.$metadata = ApiResponse.parseMetadataStatic(response);
+      obj.totalCount = obj.$metadata.totalCount;
+      obj.page = obj.$metadata.page;
+      obj.perPage = obj.$metadata.perPage;
+      obj.totalPages = obj.$metadata.totalPages;
+      obj.rateLimit = obj.$metadata.rateLimit;
+      obj.rateLimitReset = obj.$metadata.rateLimitReset;
+      obj.getHeader = (name) => response?.headers[name.toLowerCase()];
+      obj.hasPagination = obj.totalCount !== void 0 || obj.page !== void 0;
+      obj.hasNextPage = obj.page && obj.totalPages ? obj.page < obj.totalPages : false;
+      obj.hasPrevPage = obj.page ? obj.page > 1 : false;
+      return obj;
+    }
+    const instance = new ApiResponse(data, response);
+    return instance;
+  }
+  static parseMetadataStatic(response) {
+    const { headers } = response;
+    const metadata = {};
+    if (headers["x-total-count"]) {
+      metadata.totalCount = Number(headers["x-total-count"]);
+    }
+    if (headers["x-page"]) {
+      metadata.page = Number(headers["x-page"]);
+    }
+    if (headers["x-per-page"]) {
+      metadata.perPage = Number(headers["x-per-page"]);
+    }
+    if (metadata.totalCount && metadata.perPage) {
+      metadata.totalPages = Math.ceil(metadata.totalCount / metadata.perPage);
+    }
+    if (headers["x-ratelimit-remaining"] || headers["x-rate-limit-remaining"]) {
+      metadata.rateLimit = Number(
+        headers["x-ratelimit-remaining"] || headers["x-rate-limit-remaining"]
+      );
+    }
+    if (headers["x-ratelimit-reset"] || headers["x-rate-limit-reset"]) {
+      metadata.rateLimitReset = Number(
+        headers["x-ratelimit-reset"] || headers["x-rate-limit-reset"]
+      );
+    }
+    Object.keys(headers).forEach((key) => {
+      if (key.startsWith("x-") && !metadata[key]) {
+        metadata[key] = headers[key];
+      }
+    });
+    return metadata;
+  }
+  getHeader(name) {
+    return this.$raw.headers[name.toLowerCase()];
+  }
+  get hasPagination() {
+    return this.totalCount !== void 0 || this.page !== void 0;
+  }
+  get hasNextPage() {
+    if (!this.page || !this.totalPages) return false;
+    return this.page < this.totalPages;
+  }
+  get hasPrevPage() {
+    if (!this.page) return false;
+    return this.page > 1;
+  }
+}
+function parseApiError(error) {
+  const axiosError = error;
+  if (!axiosError.response?.data) {
+    return {
+      message: axiosError.message || "An unexpected error occurred",
+      raw: error
+    };
+  }
+  const { detail } = axiosError.response.data;
+  if (typeof detail === "string") {
+    return {
+      message: detail,
+      raw: error
+    };
+  }
+  if (Array.isArray(detail)) {
+    const fields = {};
+    const messages = [];
+    for (const err of detail) {
+      const fieldPath = err.loc.slice(1).join(".");
+      const message = err.msg;
+      if (fieldPath) {
+        if (!fields[fieldPath]) {
+          fields[fieldPath] = [];
+        }
+        fields[fieldPath].push(message);
+      }
+      messages.push(fieldPath ? `${fieldPath}: ${message}` : message);
+    }
+    return {
+      message: messages.join("; "),
+      fields,
+      raw: error
+    };
+  }
+  return {
+    message: "An error occurred",
+    raw: error
+  };
+}
+function formatFieldErrors(fields) {
+  return Object.entries(fields).map(([field, errors]) => `${field}: ${errors.join(", ")}`).join("\n");
+}
+function useApiRequest(requestFn, options = {}) {
+  const loading = vue.ref(false);
+  const error = vue.ref(null);
+  const data = vue.ref(null);
+  const execute = async () => {
+    loading.value = true;
+    error.value = null;
+    try {
+      const result = await requestFn();
+      data.value = result;
+      return result;
+    } catch (e) {
+      error.value = parseApiError(e);
+      return null;
+    } finally {
+      loading.value = false;
+    }
+  };
+  const reset = () => {
+    loading.value = false;
+    error.value = null;
+    data.value = null;
+  };
+  if (options.immediate) {
+    execute();
+  }
+  return { loading, error, data, execute, reset };
+}
+function useCancellableRequest(requestFn) {
+  const controller = vue.ref(null);
+  const loading = vue.ref(false);
+  const error = vue.ref(null);
+  const data = vue.ref(null);
+  const execute = async () => {
+    controller.value?.abort();
+    controller.value = new AbortController();
+    loading.value = true;
+    error.value = null;
+    try {
+      const result = await requestFn(controller.value.signal);
+      data.value = result;
+      return result;
+    } catch (e) {
+      if (e.name !== "AbortError" && e.name !== "CanceledError") {
+        error.value = parseApiError(e);
+      }
+      return null;
+    } finally {
+      loading.value = false;
+    }
+  };
+  const cancel = () => {
+    controller.value?.abort();
+    loading.value = false;
+  };
+  const reset = () => {
+    cancel();
+    error.value = null;
+    data.value = null;
+  };
+  return { loading, error, data, execute, cancel, reset };
+}
+function wrapApiForDirectReturn(apiObj) {
+  if (typeof apiObj === "function") {
+    return async (...args) => {
+      const result = await apiObj(...args);
+      if (result && typeof result === "object" && "data" in result && "status" in result) {
+        return ApiResponse.create(result.data, result);
+      }
+      return result;
+    };
+  }
+  if (typeof apiObj === "object" && apiObj !== null) {
+    const wrapped = {};
+    for (const key in apiObj) {
+      if (key === "stream") {
+        wrapped[key] = apiObj[key];
+      } else {
+        wrapped[key] = wrapApiForDirectReturn(apiObj[key]);
+      }
+    }
+    return wrapped;
+  }
+  return apiObj;
+}
 const axios = axios__default.create({
   withCredentials: true
 });
@@ -1496,6 +1903,7 @@ class Bagel {
   }
 }
 
+exports.ApiResponse = ApiResponse;
 exports.Bagel = Bagel;
 exports.StreamController = StreamController;
 exports.createSSEStream = createSSEStream;
@@ -1504,8 +1912,13 @@ exports.dereference = dereference;
 exports.extractSSEEventInfo = extractSSEEventInfo;
 exports.extractSSEEventTypes = extractSSEEventTypes;
 exports.formatAPIErrorMessage = formatAPIErrorMessage;
+exports.formatFieldErrors = formatFieldErrors;
 exports.getPath = getPath;
 exports.isReferenceObject = isReferenceObject;
 exports.isSSEStream = isSSEStream;
 exports.isSchemaObject = isSchemaObject;
 exports.openAPI = index;
+exports.parseApiError = parseApiError;
+exports.useApiRequest = useApiRequest;
+exports.useCancellableRequest = useCancellableRequest;
+exports.wrapApiForDirectReturn = wrapApiForDirectReturn;