@puffinstudio/fizzyx 0.4.8 → 0.5.0

package/.fizzy.yaml

@@ -21,3 +21,7 @@ oss:
     endpoint:
     region:
     bucket:
+openapi:
+  - input: https://api.d.osuki.dev/docs/openapi.json
+    output: tests/api
+    client: wx

package/README.md

@@ -1,6 +1,6 @@
 # fizzyx
 
-CLI tool for Fizzy board workflow and OSS/S3-compatible storage management.
+CLI tool for Fizzy board workflow, OSS/S3-compatible storage, and OpenAPI client generation.
 
 ## Install
 
@@ -147,6 +147,111 @@ List exact pending files without uploading:
 fizzyx oss status --files
 ```
 
+## OpenAPI Commands
+
+Generate a typed API client from an OpenAPI spec.
+
+### Generate
+
+```sh
+fizzyx openapi generate -i <url|path> -o <dir> -c wx
+```
+
+Options:
+
+| Flag                       | Description                                             |
+| -------------------------- | ------------------------------------------------------- |
+| `-i, --input <url\|path>`  | OpenAPI spec URL or file path (JSON/YAML)               |
+| `-o, --output <dir\|file>` | Output directory (or `.ts` path for custom api name)    |
+| `-c, --client <name>`      | Client target (`wx`)                                    |
+| `--api-name <name>`        | API filename (default: `api.ts`)                        |
+| `--types-name <name>`      | Types filename (default: `types.ts`, `false` to inline) |
+| `--runtime-name <name>`    | Runtime filename (default: `wx-request.ts`)             |
+| `--run <script\|cmd>`      | npm script or shell command after generation            |
+
+If `--input`/`--output`/`--client` are omitted, values from `.fizzy.yaml` `openapi[0]` are used.
+
+Output is 3 files — runtime, types, and tree-shakeable endpoint functions:
+
+```
+src/api/
+  ├── wx-request.ts   # runtime (configure, setToken, onError, request)
+  ├── types.ts        # named interfaces / enums / aliases
+  └── api.ts          # tree-shakeable export functions + param types
+```
+
+### Generated Runtime API
+
+```ts
+import { configure, setToken, onError, initToken } from "./api";
+
+// Setup at app startup
+configure({ baseUrl: "https://api.example.com", storageKey: "myapp_token" });
+
+// Or with custom logger + hooks
+configure({
+	baseUrl: "https://api.example.com",
+	storageKey: "tb_token",
+	logger: { error: myReporter, warn: () => {}, info: () => {}, debug: () => {} },
+	hooks: [
+		{ onError: (ctx) => wx.showToast({ title: ctx.message }) },
+		{ onSuccess: (ctx) => reportAnalytics(ctx) },
+	],
+});
+
+// Token auto-loads from storage. Explicit load if needed:
+await initToken();
+
+// Token persists to storage on set
+setToken("jwt...");
+setToken(null); // logout, clears storage
+```
+
+**Logger vs Hooks:**
+
+- `Logger` controls **output** (console, file, sentry). Default: `console.error/warn/info/debug` with `[fizzyx]` prefix.
+- `RequestHook` fires **business callbacks** at lifecycle points (`onRequest`, `onSuccess`, `onError`). Use for toast, analytics, loading state.
+
+### Generated Endpoint API
+
+Each endpoint is a standalone export function with typed params:
+
+```ts
+import { listPets, createPet, ListPetsQueryParams } from "./api";
+
+// GET with query params
+const pets = await listPets({ query: { limit: 10, status: "available" } });
+
+// POST with body
+const pet = await createPet({ name: "Fluffy" });
+
+// POST without requestBody (no data param generated)
+const result = await someAction();
+```
+
+- No `createApi()` wrapper — tree-shakeable by default
+- Each function exports its param types (`ListPetsQueryParams`, `CreatePetPathParams`)
+- JSDoc comments from OpenAPI `description`/`summary` on endpoints and params
+
+### List Generators
+
+```sh
+fizzyx openapi list
+```
+
+### Config (`.fizzy.yaml`)
+
+```yaml
+openapi:
+  - input: ./openapi.json
+    output: ./src/api
+    client: wx
+    api_name: sdk.ts
+    types_name: types.ts
+    runtime_name: wx-request.ts
+    run: check
+```
+
 ## Config File (`.fizzy.yaml`)
 
 Minimal OSS-only config: