swagger-ts-sdk 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,255 @@
+# Swagger TypeScript SDK
+
+A TypeScript SDK generated from Swagger/OpenAPI specifications, providing a type-safe way to interact with REST APIs.
+
+## Installation
+
+```bash
+npm install swagger-ts-sdk
+# or
+bun add swagger-ts-sdk
+```
+
+## Quick Start
+
+```typescript
+import { SdkClient } from "swagger-ts-sdk";
+import { Api } from "./your-api-schema";
+
+const client = new SdkClient(Api, {
+  baseUrl: "https://api.example.com",
+});
+
+(async () => {
+  const { data, error, status } = await client.greetings.greetingsList();
+  
+  if (error) {
+    console.error("Request failed:", error);
+    return;
+  }
+  
+  console.log("Success:", data);
+})();
+```
+
+## SdkClient API
+
+### Constructor
+
+```typescript
+new SdkClient<T>(ApiClass, options)
+```
+
+#### Parameters
+
+- `ApiClass` - The generated API class from your Swagger schema
+- `options` - Configuration object with the following properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `baseUrl` | `string` | Yes | The base URL for all API requests |
+| `token` | `SdkToken` | No | Bearer token for authentication. Can be a static string or a function that returns the token dynamically. |
+| `onRequestError` | `(error: SdkError) => void` | No | Callback triggered when a request fails |
+| `timeout` | `number` | No | Request timeout in milliseconds. If set, the request will be aborted after the specified duration. |
+
+### Response Format
+
+All API methods return a standardized response object:
+
+```typescript
+{
+  data: T | null;         // The response data on success
+  error: string | null;   // Error message on failure
+  status: number | null;  // HTTP status code
+  abort: () => void;      // Function to abort the request
+}
+```
+
+## SdkError Type
+
+The `SdkError` type represents an error response from the API. It is passed to the `onRequestError` callback when a request fails.
+
+```typescript
+export type SdkError<E = unknown> = {
+  /** Always null for error responses */
+  data: null;
+  /** The error data from the API response */
+  error: E;
+  /** HTTP status code */
+  status: number;
+  /** Whether the request was successful (always false for errors) */
+  ok: boolean;
+  /** HTTP status text */
+  statusText: string;
+  /** Response headers */
+  headers: Headers;
+  /** Optional body content */
+  body?: any;
+};
+```
+
+### Importing SdkError
+
+```typescript
+import { SdkClient, SdkError } from "swagger-ts-sdk";
+```
+
+## Examples
+
+### Basic GET Request
+
+```typescript
+import { SdkClient } from "swagger-ts-sdk";
+import { Api } from "./your-api-schema";
+
+const client = new SdkClient(Api, {
+  baseUrl: "https://api.example.com",
+});
+
+// Get a list of items
+const { data, error, status } = await client.items.itemsList();
+
+if (error) {
+  console.error(`Error (${status}):`, error);
+} else {
+  console.log("Items:", data);
+}
+```
+
+### POST Request with Data
+
+```typescript
+const { data, error, status } = await client.users.usersCreate({
+  body: {
+    name: "John Doe",
+    email: "john@example.com",
+  },
+});
+```
+
+### Using Authentication Token
+
+```typescript
+const client = new SdkClient(Api, {
+  baseUrl: "https://api.example.com",
+  token: "your-bearer-token",
+});
+```
+
+### Dynamic Token (localStorage/sessionStorage)
+
+If your token is stored in localStorage or sessionStorage and may change during the session, pass a function instead of a static string. The function will be called before each request to get the current token.
+
+```typescript
+const client = new SdkClient(Api, {
+  baseUrl: "https://api.example.com",
+  token: () => {
+    // Retrieve token from localStorage/sessionStorage for each request
+    return localStorage.getItem("authToken");
+    // Or use sessionStorage:
+    // return sessionStorage.getItem("authToken");
+  },
+});
+```
+
+This is useful when:
+- The token may expire and be refreshed during the session
+- You want to avoid storing the token in memory
+- Multiple tabs might update the token
+
+### Error Callback
+
+```typescript
+const client = new SdkClient(Api, {
+  baseUrl: "https://api.example.com",
+  onRequestError: (error: SdkError) => {
+    console.error("Request failed!");
+    console.error("Status:", error.status);
+    console.error("Error:", error.error);
+    console.error("Status Text:", error.statusText);
+    
+    // Send to error tracking service
+    // sendToSentry(error);
+  },
+});
+```
+
+### Request Timeout
+
+Set a timeout in milliseconds to automatically abort requests that take too long.
+
+```typescript
+const client = new SdkClient(Api, {
+  baseUrl: "https://api.example.com",
+  timeout: 5000, // 5 seconds
+});
+
+// If the request takes longer than 5 seconds, it will be aborted
+const { data, error, status } = await client.items.itemsList();
+
+if (error === "Request failed" && status === 0) {
+  console.error("Request timed out");
+}
+```
+
+### Abort Request
+
+Each request returns an `abort` function that you can call to cancel the request at any time.
+
+```typescript
+const client = new SdkClient(Api, {
+  baseUrl: "https://api.example.com",
+});
+
+// Make a request and get the abort function
+const request = client.items.itemsList();
+const { data, error, status, abort } = await request;
+
+// Or destructured:
+const { abort: cancelRequest } = await client.items.itemsList();
+
+// Cancel the request if needed
+cancelRequest();
+
+// Or using the abort function from the response
+const response = await client.users.usersList();
+response.abort(); // Cancel the request
+```
+
+**Note:** Once a request is aborted, the response will have `error: "Request aborted"` and `status: 0`.
+
+### Nested API Endpoints
+
+The SDK supports nested API structures:
+
+```typescript
+// For APIs with nested endpoints like api.auth.loginCreate
+const { data, error } = await client.auth.loginCreate({
+  body: {
+    username: "user",
+    password: "pass",
+  },
+});
+```
+
+## Type Safety
+
+The SDK provides full type safety for:
+
+- Request parameters
+- Request body
+- Response data
+- Error types
+
+```typescript
+// Full type inference
+const { data, error, status } = await client.users.usersGetById("123");
+
+// data is typed as User | null
+// error is typed as string | null
+// status is typed as number | null
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,11 +1,44 @@
+/**
+ * Error type returned when an API request fails.
+ * Contains the error data, status code, and other response properties.
+ */
+type SdkError<E = unknown> = {
+    data: null;
+    error: E;
+    status: number;
+    ok: boolean;
+    statusText: string;
+    headers: Headers;
+    body?: any;
+};
+/**
+ * Token type that can be either a static string or a function that returns the token.
+ * Use a function to retrieve the token dynamically from localStorage/sessionStorage
+ * for each request.
+ */
+type SdkToken = string | (() => string | undefined);
 type SdkClientConstructor = new <T extends object>(ApiClass: new (config: {
     baseUrl: string;
     baseApiParams?: any;
+    securityWorker?: any;
+    customFetch?: any;
 }) => T, options: {
     baseUrl: string;
-    /** Token to attach to every request as Bearer auth. */
-    token?: string;
+    /**
+     * Token to attach to every request as Bearer auth.
+     * Can be a static string or a function that returns the token.
+     * Use a function to retrieve the token dynamically from localStorage/sessionStorage
+     * for each request.
+     */
+    token?: SdkToken;
+    /** Callback triggered when a request error occurs. */
+    onRequestError?: (error: SdkError) => void;
+    /**
+     * Request timeout in milliseconds.
+     * If set, the request will be aborted after the specified duration.
+     */
+    timeout?: number;
 }) => T;
 declare const SdkClient: SdkClientConstructor;
 
-export { SdkClient };
+export { SdkClient, type SdkError, type SdkToken };

package/dist/index.js

@@ -1 +1 @@
-var g=class{constructor(o,i){let{baseUrl:u,token:e}=i,n=new o({baseUrl:u,baseApiParams:{headers:{...e&&{Authorization:`Bearer ${e}`}}}});return e&&"setSecurityData"in n&&n.setSecurityData(e),new Proxy(n,{get(l,y){let s=l[y];return typeof s=="object"&&s!==null?new Proxy(s,{get(a,c){let r=a[c];return typeof r=="function"?async(...p)=>{try{let t=await r.apply(a,p);return {data:t.data,error:null,status:t.status}}catch(t){return {data:null,error:t?.error?.message||t?.message||"Request failed",status:t?.status||null}}}:r}}):s}})}};export{g as SdkClient};
+var q=class{constructor(g,T){let{baseUrl:S,token:e,onRequestError:c,timeout:l}=T,y=typeof e=="function"?e:e?()=>e:()=>{},u=new g({baseUrl:S,baseApiParams:{headers:{...e&&{Authorization:`Bearer ${y()}`}}},securityWorker:async()=>{let n=y();return n?{headers:{Authorization:`Bearer ${n}`}}:{}}}),d=typeof e=="string"?e:void 0;return d&&"setSecurityData"in u&&u.setSecurityData(d),new Proxy(u,{get(n,h){let o=n[h];return typeof o=="object"&&o!==null?new Proxy(o,{get(b,w){let i=b[w];return typeof i=="function"?function(...x){let s=new AbortController,a=s.abort.bind(s),r;l&&(r=setTimeout(()=>{s.abort();},l));let f=(async()=>{var m,k;try{let E={...x[0]||{},signal:s.signal},p=await i.apply(b,[E]);return r&&clearTimeout(r),{data:p.data,error:null,status:p.status,abort:a}}catch(t){return r&&clearTimeout(r),(t==null?void 0:t.name)==="AbortError"||(m=t==null?void 0:t.message)!=null&&m.includes("aborted")?{data:null,error:"Request aborted",status:0,abort:a}:(c&&c(t),{data:null,error:((k=t==null?void 0:t.error)==null?void 0:k.message)||(t==null?void 0:t.message)||"Request failed",status:(t==null?void 0:t.status)||null,abort:a})}})();return f.abort=a,f}:i}}):o}})}};export{q as SdkClient};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger-ts-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "author": "codesordinate studio",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,12 @@
   "types": "dist/index.d.ts",
   "module": "dist/index.js",
   "scripts": {
-    "publish-package": " npm publish"
+    "test": "bun test",
+    "tsc": "tsup --watch",
+    "server": "bun run --watch src/example/server-test.ts",
+    "dev": "concurrently \"bun server\" \"bun tsc\"",
+    "package": "tsup",
+    "publish-package": "bun test && bun package && npm publish"
   },
   "repository": {
     "type": "git",
@@ -21,10 +26,15 @@
     }
   },
   "devDependencies": {
-    "@sinclair/typebox": "^0.34.48"
+    "@sinclair/typebox": "^0.34.48",
+    "concurrently": "^9.2.1",
+    "swagger-typescript-api": "^13.2.18"
   },
   "files": [
     "dist",
     "README.md"
-  ]
+  ],
+  "dependencies": {
+    "@codesordinatestudio/lucent": "^1.1.15"
+  }
 }