@pfdev/api-types 3.0.1 → 3.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @pfdev/api-types
 
-TypeScript types for PF API V3, auto-generated from the OpenAPI specification.
+TypeScript types for PF API V3, synced directly from TypeBox schemas in pfapi-fs.
 
 ## Quick Start
 
@@ -13,28 +13,67 @@ npm install @pfdev/api-types
 ### Use in React/React Native
 
 ```typescript
-import type { paths } from '@pfdev/api-types';
-
-type GetSetsResponse = paths['/api/v3/sets/']['get']['responses'][200]['content']['application/json'];
-type GetSetParams = paths['/api/v3/sets/{id}']['get']['parameters']['path'];
-
-// Fully typed API calls
-const getSets = async (): Promise<GetSetsResponse> => {
-  const res = await fetch('/api/v3/sets');
-  return res.json();
-};
-
-const getSet = async (id: string): Promise<any> => {
-  const res = await fetch(`/api/v3/sets/${id}`);
-  return res.json();
-};
+import { useState, useEffect } from 'react';
+import type { SetDetail } from '@pfdev/api-types';
+
+function SetDisplay({ setId }: { setId: string }) {
+  const [set, setSet] = useState<SetDetail | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const fetchSet = async () => {
+      const response = await fetch(`/api/v3/sets/${setId}`);
+      const data: SetDetail = await response.json();
+      setSet(data);
+      setLoading(false);
+    };
+
+    fetchSet();
+  }, [setId]);
+
+  if (loading) return <div>Loading...</div>;
+  if (!set) return <div>Not found</div>;
+
+  return (
+    <div>
+      <h1>{set.name}</h1>
+      <p>Series: {set.series}</p>
+      <p>Released: {set.releaseddate}</p>
+      <img src={set.imglogo} alt={set.name} />
+      
+      {set.current_price && (
+        <p>Current Price: ${set.current_price}</p>
+      )}
+
+      <div>
+        <p>7-day change: {set.change_7d}%</p>
+        <p>1-year change: {set.change_1y}%</p>
+      </div>
+
+      <h3>Rarity Distribution</h3>
+      <ul>
+        {set.rarities.map((rarity) => (
+          <li key={rarity.rarity}>
+            {rarity.rarity}: {rarity.count} cards
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
 ```
 
+**Benefits:**
+- ✅ Full IDE autocomplete on `set.` properties
+- ✅ Type errors caught at compile time
+- ✅ Optional fields properly typed (e.g., `current_price?: number`)
+- ✅ Nested types fully typed (e.g., `rarities: RarityCount[]`)
+
 ## Features
 
-✅ **Auto-Generated** - Types sync directly from the API's OpenAPI spec  
+✅ **Single Source of Truth** - Types synced from pfapi-fs schemas  
 ✅ **Fully Typed** - IDE autocompletion on all API responses  
-✅ **Zero Dependencies** - Only ~10 KB, no runtime overhead  
+✅ **Zero Dependencies** - Only ~5 KB, no runtime overhead  
 ✅ **Type Safe** - Catch errors at compile time, not runtime  
 ✅ **Free** - No paid npm account needed  
 
@@ -42,19 +81,26 @@ const getSet = async (id: string): Promise<any> => {
 
 ### Prerequisites
 
-- pfapi-fs running locally (the backend API)
+- pfapi-fs available locally (no need to run it)
 - npm installed
 
 ### Step-by-Step
 
 #### 1. Make changes in pfapi-fs
 
-```bash
-cd ../pfapi-fs
-npm run dev  # Start the API on https://127.0.0.1:5000
-```
+Add or modify V3 endpoints with TypeBox schemas:
 
-Add or modify V3 endpoints with TypeBox schemas in `src/routes/v3/{resource}/schemas.ts`.
+```typescript
+// pfapi-fs/src/routes/v3/sets/schemas.ts
+export const SetDetailSchema = Type.Object({
+  setid: Type.String(),
+  name: Type.String(),
+  series: Type.String(),
+  // ... more fields
+});
+
+export type SetDetail = Static<typeof SetDetailSchema>;
+```
 
 #### 2. Bump version and generate types
 
@@ -64,11 +110,11 @@ npm version patch  # or minor/major
 ```
 
 This automatically:
-- ✅ Fetches the OpenAPI spec from https://127.0.0.1:5000/docs/json
-- ✅ Runs `openapi-typescript` to generate v3.ts
-- ✅ Stages the generated file with git
-- ✅ Bumps the version number (3.0.0 → 3.0.1)
-- ✅ Creates a git tag
+- ✅ Syncs TypeBox schemas from `../pfapi-fs/src/routes/v3/*/schemas.ts`
+- ✅ Validates with TypeScript
+- ✅ Stages v3.ts with git
+- ✅ Bumps version (3.0.0 → 3.0.1)
+- ✅ Creates git tag
 
 #### 3. Publish to npm
 
@@ -76,7 +122,7 @@ This automatically:
 npm publish
 ```
 
-This verifies v3.ts was actually changed, then publishes to npm.
+Verifies v3.ts changed, then publishes to npm.
 
 ## Manual Type Generation
 
@@ -86,11 +132,20 @@ To manually regenerate types without versioning:
 npm run generate
 ```
 
-By default, it uses `https://127.0.0.1:5000` (local dev). Specify a different API URL:
+## How It Works
 
-```bash
-npm run generate https://api.example.com
+### Single Source of Truth
 ```
+pfapi-fs/src/routes/v3/sets/schemas.ts  ← Edit here
+           ↓
+         npm run generate
+           ↓
+pfapi-types/v3.ts                       ← Auto-synced
+           ↓
+Consumer imports
+```
+
+**No drift possible** — types always match the backend schemas.
 
 ## Version Strategy
 
@@ -98,26 +153,9 @@ npm run generate https://api.example.com
 - **Minor** (3.0.0 → 3.1.0) - New endpoints/features
 - **Patch** (3.0.0 → 3.0.1) - Bug fixes in types
 
-## How It Works
-
-### Old Approach (Manual)
-1. Edit schemas in pfapi-fs
-2. Manually copy to pfapi-types/v3.ts
-3. Bump version
-4. Publish
-
-**Problem**: Easy to forget steps, schema drift between packages.
-
-### New Approach (Automated)
-1. Edit schemas in pfapi-fs
-2. Run `npm version patch` (auto-generates and stages)
-3. Publish
-
-**Benefit**: Types always sync with the API spec, no manual copying.
-
 ## Files
 
-- `generate-types.sh` - Script that fetches the OpenAPI spec and generates types
+- `generate-types.sh` - Script that syncs TypeBox schemas from pfapi-fs
 - `package.json` - npm metadata with automated scripts
 - `v3.ts` - Auto-generated types (do not edit manually)
 - `index.ts` - Main entry point (re-exports v3.ts)
@@ -127,16 +165,14 @@ npm run generate https://api.example.com
 ### "Error: No changes to v3.ts since last tag"
 
 The `preversion` hook prevents versioning if types haven't changed. Make sure:
-- pfapi-fs API is running on https://127.0.0.1:5000
-- You've made actual changes to V3 endpoints
-- Run `npm run generate` to test type generation
+- You've made actual changes to V3 schemas in pfapi-fs
+- Run `npm run generate` to test schema sync
 
-### "Connection refused" when generating
+### "TypeScript validation failed"
 
-Ensure pfapi-fs is running:
-```bash
-cd ../pfapi-fs && npm run dev
-```
+Check that:
+- All TypeBox schemas in pfapi-fs compile
+- Imports are correct in `src/routes/v3/*/schemas.ts`
 
 ### "npm ERR! code E404"
 

package/index.ts

@@ -1,2 +1,2 @@
-// Re-export all V3 API types
+// Re-export all V3 API types synced from pfapi-fs
 export * from './v3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pfdev/api-types",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "TypeScript types for PF API V3",
   "main": "index.ts",
   "types": "index.ts",

package/v3.ts

@@ -1,365 +1,100 @@
-/**
- * This file was auto-generated by openapi-typescript.
- * Do not make direct changes to the file.
- */
+// Auto-generated from pfapi-fs/src/routes/v3/*/schemas.ts
+// Do not edit manually - run `npm run generate` to update
 
-export interface paths {
-    "/api/v3/sets/": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /** @description List all sets with optional filtering */
-        get: {
-            parameters: {
-                query?: {
-                    /** @description Search by set name */
-                    search?: string;
-                    /** @description Filter by series */
-                    series?: string;
-                    limit?: number;
-                    offset?: number;
-                };
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Paginated list of Pokemon card sets */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @description Array of sets */
-                            data: {
-                                /** @description Unique set identifier */
-                                setid: string;
-                                /** @description Set name */
-                                name: string;
-                                /** @description Pokemon series */
-                                series: string;
-                                /**
-                                 * Format: date
-                                 * @description Release date
-                                 */
-                                releaseddate: string;
-                                /**
-                                 * Format: uri
-                                 * @description Symbol image URL
-                                 */
-                                imgsymbol: string;
-                                /**
-                                 * Format: uri
-                                 * @description Logo image URL
-                                 */
-                                imglogo: string;
-                                /** @description Total cards in set */
-                                printedtotal: number;
-                                /** @description Current market price */
-                                current_price?: number;
-                                /** @description 7-day price change % */
-                                change_7d?: number;
-                                /** @description URL-friendly slug */
-                                slug: string;
-                            }[];
-                            /** @description Total number of sets available */
-                            total: number;
-                            /** @description Number of sets returned in this response */
-                            count: number;
-                        };
-                    };
-                };
-                /** @description Default Response */
-                500: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            error: string;
-                            message: string;
-                        };
-                    };
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/api/v3/sets/{id}": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /** @description Get single set details by ID or slug */
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    /** @description Set ID or slug */
-                    setid: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Detailed information about a Pokemon card set */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @description Unique set identifier */
-                            setid: string;
-                            /** @description Set name */
-                            name: string;
-                            /** @description Total cards printed (official) */
-                            printedtotal: number;
-                            /** @description Total unique cards in set */
-                            total: number;
-                            /** @description Pokemon series name */
-                            series: string;
-                            /**
-                             * Format: date
-                             * @description Release date
-                             */
-                            releaseddate: string;
-                            /**
-                             * Format: date-time
-                             * @description Last update timestamp
-                             */
-                            updatedat: string;
-                            /**
-                             * Format: uri
-                             * @description Set symbol image URL
-                             */
-                            imgsymbol: string;
-                            /**
-                             * Format: uri
-                             * @description Set logo image URL
-                             */
-                            imglogo: string;
-                            /** @description URL-friendly identifier */
-                            slug: string;
-                            /** @description Pokemon TCG Live code (if available) */
-                            ptcgocode?: string;
-                            /** @description Format legalities */
-                            legalities?: {
-                                [key: string]: string;
-                            };
-                            /** @description Current market price */
-                            current_price?: number;
-                            /** @description 1-day price change % */
-                            change_1d?: number;
-                            /** @description 7-day price change % */
-                            change_7d?: number;
-                            /** @description 30-day price change % */
-                            change_1m?: number;
-                            /** @description 90-day price change % */
-                            change_3m?: number;
-                            /** @description 180-day price change % */
-                            change_6m?: number;
-                            /** @description 1-year price change % */
-                            change_1y?: number;
-                            /** @description Card rarity distribution */
-                            rarities: {
-                                /** @description Rarity level */
-                                rarity: string;
-                                /** @description Number of cards with this rarity */
-                                count: number;
-                            }[];
-                        };
-                    };
-                };
-                /** @description Default Response */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            error: string;
-                            message: string;
-                        };
-                    };
-                };
-                /** @description Default Response */
-                500: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            error: string;
-                            message: string;
-                        };
-                    };
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Default Response */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/redis": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Default Response */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/debug-sentry": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Default Response */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/pool-status": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path?: never;
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Default Response */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-            };
-        };
-        put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-}
-export type webhooks = Record<string, never>;
-export interface components {
-    schemas: never;
-    responses: never;
-    parameters: never;
-    requestBodies: never;
-    headers: never;
-    pathItems: never;
-}
-export type $defs = Record<string, never>;
-export type operations = Record<string, never>;
+import { Static, Type } from '@sinclair/typebox';
+
+
+// ============= SETS =============
+
+
+// Response for list of sets
+export const SetListItemSchema = Type.Object({
+  setid: Type.String({ description: 'Unique set identifier' }),
+  name: Type.String({ description: 'Set name' }),
+  series: Type.String({ description: 'Pokemon series' }),
+  releaseddate: Type.String({ format: 'date', description: 'Release date' }),
+  imgsymbol: Type.String({ format: 'uri', description: 'Symbol image URL' }),
+  imglogo: Type.String({ format: 'uri', description: 'Logo image URL' }),
+  printedtotal: Type.Number({ description: 'Total cards in set' }),
+  current_price: Type.Optional(Type.Number({ description: 'Current market price' })),
+  change_7d: Type.Optional(Type.Number({ description: '7-day price change %' })),
+  slug: Type.String({ description: 'URL-friendly slug' })
+});
+
+export type SetListItem = Static<typeof SetListItemSchema>;
+
+export const SetListResponseSchema = Type.Object(
+  {
+    data: Type.Array(SetListItemSchema, { description: 'Array of sets' }),
+    total: Type.Number({ description: 'Total number of sets available' }),
+    count: Type.Number({ description: 'Number of sets returned in this response' })
+  },
+  {
+    title: 'SetListResponse',
+    description: 'Paginated list of Pokemon card sets'
+  }
+);
+
+export type SetListResponse = Static<typeof SetListResponseSchema>;
+
+// Response for set details
+export const RarityCountSchema = Type.Object(
+  {
+    rarity: Type.String({ description: 'Rarity level' }),
+    count: Type.Number({ description: 'Number of cards with this rarity' })
+  },
+  {
+    title: 'RarityCount',
+    description: 'Card rarity distribution in a set'
+  }
+);
+
+export type RarityCount = Static<typeof RarityCountSchema>;
+
+export const SetDetailSchema = Type.Object(
+  {
+    setid: Type.String({ description: 'Unique set identifier' }),
+    name: Type.String({ description: 'Set name' }),
+    printedtotal: Type.Number({ description: 'Total cards printed (official)' }),
+    total: Type.Number({ description: 'Total unique cards in set' }),
+    series: Type.String({ description: 'Pokemon series name' }),
+    releaseddate: Type.String({ format: 'date', description: 'Release date' }),
+    updatedat: Type.String({ format: 'date-time', description: 'Last update timestamp' }),
+    imgsymbol: Type.String({ format: 'uri', description: 'Set symbol image URL' }),
+    imglogo: Type.String({ format: 'uri', description: 'Set logo image URL' }),
+    slug: Type.String({ description: 'URL-friendly identifier' }),
+    ptcgocode: Type.Optional(Type.String({ description: 'Pokemon TCG Live code (if available)' })),
+    legalities: Type.Optional(Type.Record(Type.String(), Type.String(), { description: 'Format legalities' })),
+    current_price: Type.Optional(Type.Number({ description: 'Current market price' })),
+    change_1d: Type.Optional(Type.Number({ description: '1-day price change %' })),
+    change_7d: Type.Optional(Type.Number({ description: '7-day price change %' })),
+    change_1m: Type.Optional(Type.Number({ description: '30-day price change %' })),
+    change_3m: Type.Optional(Type.Number({ description: '90-day price change %' })),
+    change_6m: Type.Optional(Type.Number({ description: '180-day price change %' })),
+    change_1y: Type.Optional(Type.Number({ description: '1-year price change %' })),
+    rarities: Type.Array(RarityCountSchema, { description: 'Card rarity distribution' })
+  },
+  {
+    title: 'SetDetail',
+    description: 'Detailed information about a Pokemon card set'
+  }
+);
+
+export type SetDetail = Static<typeof SetDetailSchema>;
+
+// Query parameters
+export const SetListQuerySchema = Type.Object({
+  search: Type.Optional(Type.String({ description: 'Search by set name' })),
+  series: Type.Optional(Type.String({ description: 'Filter by series' })),
+  limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 20 })),
+  offset: Type.Optional(Type.Number({ minimum: 0, default: 0 }))
+});
+
+export type SetListQuery = Static<typeof SetListQuerySchema>;
+
+// Path parameters
+export const SetDetailParamSchema = Type.Object({
+  setid: Type.String({ description: 'Set ID or slug' })
+});
+
+export type SetDetailParam = Static<typeof SetDetailParamSchema>;