@pfdev/api-types 3.0.0 → 3.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @pfdev/api-types
 
-TypeScript types for PF API V3, directly exported from TypeBox schemas.
+TypeScript types for PF API V3, synced directly from TypeBox schemas in pfapi-fs.
 
 ## Quick Start
 
@@ -13,98 +13,179 @@ npm install @pfdev/api-types
 ### Use in React/React Native
 
 ```typescript
-import type { components, paths } from '@pfdev/api-types';
-
-// Type your API responses
-type SetListResponse = components['schemas']['SetListResponse'];
-type SetDetail = components['schemas']['SetDetail'];
-
-// Type your API calls
-const getSets = async (): Promise<SetListResponse> => {
-  const res = await fetch('/api/v3/sets');
-  return res.json();
-};
-
-const getSet = async (setid: string): Promise<SetDetail> => {
-  const res = await fetch(`/api/v3/sets/${setid}`);
-  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
 
-✅ **Fully Typed** - All API endpoints have TypeScript types  
-✅ **Auto-Generated** - Types come directly from API schemas  
-✅ **Zero Manual Maintenance** - Regenerate when API changes  
-✅ **OpenAPI Standard** - Compatible with any OpenAPI tooling  
-✅ **Free to Publish** - No paid npm account needed  
+✅ **Single Source of Truth** - Types synced from pfapi-fs schemas  
+✅ **Fully Typed** - IDE autocompletion on all API responses  
+✅ **Zero Dependencies** - Only ~5 KB, no runtime overhead  
+✅ **Type Safe** - Catch errors at compile time, not runtime  
+✅ **Free** - No paid npm account needed  
+
+## Publishing Workflow
+
+### Prerequisites
+
+- pfapi-fs available locally (no need to run it)
+- npm installed
 
-## Development
+### Step-by-Step
 
-### Add/Update Types
+#### 1. Make changes in pfapi-fs
 
-When you add new V3 endpoints:
+Add or modify V3 endpoints with TypeBox schemas:
 
-1. Create schemas in `../pfapi-fs/src/routes/v3/{resource}/schemas.ts`
-2. Export the TypeBox schemas
-3. Copy the types to `v3.ts` in this package
-4. Commit and publish
+```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
 
-Example workflow:
 ```bash
-# Backend: Create new endpoint with TypeBox schemas
-# pfapi-fs/src/routes/v3/cards/schemas.ts
-export const CardSchema = Type.Object({ ... })
-export type Card = Static<typeof CardSchema>
+cd ../pfapi-types
+npm version patch  # or minor/major
+```
+
+This automatically:
+- ✅ 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
 
-# Types package: Re-export in v3.ts
-# pfapi-types/v3.ts
-export { CardSchema, type Card } from '...'
+#### 3. Publish to npm
 
-# Publish
-npm version patch
+```bash
 npm publish
 ```
 
-## Publishing
-
-### First Time Only
+Verifies v3.ts changed, then publishes to npm.
 
-1. Create free npm account: https://www.npmjs.com/signup
-2. Login locally: `npm login`
-3. Publish: `npm publish`
+## Manual Type Generation
 
-### Update Existing Package
+To manually regenerate types without versioning:
 
 ```bash
-# Regenerate types from updated API
 npm run generate
+```
 
-# Bump version
-npm version patch  # or minor/major
+## How It Works
 
-# Publish
-npm publish
+### 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
 ```
 
-## Version Mapping
+**No drift possible** — types always match the backend schemas.
 
-- **V3.x.x** - API V3 types
-- **V2.x.x** - (future) API V2 types
+## Version Strategy
+
+- **Major** (3.0.0 → 4.0.0) - Breaking API changes
+- **Minor** (3.0.0 → 3.1.0) - New endpoints/features
+- **Patch** (3.0.0 → 3.0.1) - Bug fixes in types
 
 ## Files
 
+- `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)
-- `v3.ts` - Auto-generated types (run `npm run generate`)
-- `package.json` - npm metadata
-- `SETUP.md` - Detailed setup guide
+
+## Troubleshooting
+
+### "Error: No changes to v3.ts since last tag"
+
+The `preversion` hook prevents versioning if types haven't changed. Make sure:
+- You've made actual changes to V3 schemas in pfapi-fs
+- Run `npm run generate` to test schema sync
+
+### "TypeScript validation failed"
+
+Check that:
+- All TypeBox schemas in pfapi-fs compile
+- Imports are correct in `src/routes/v3/*/schemas.ts`
+
+### "npm ERR! code E404"
+
+Make sure npm is authenticated and you have publish permissions for `@pfdev/api-types`.
+
+## Publishing for the First Time
+
+1. Create free npm account: https://www.npmjs.com/signup
+2. Login: `npm login`
+3. Publish: `npm publish`
 
 ## No Cost
 
 - ✅ npm account: FREE (forever)
 - ✅ Publish to npm: FREE (unlimited public packages)
-- ✅ Type generation: FREE (openapi-typescript is open source)
-
-## Support
-
-See `SETUP.md` for troubleshooting and CI/CD setup.
+- ✅ All tools: FREE (open source)

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.0",
+  "version": "3.0.2",
   "description": "TypeScript types for PF API V3",
   "main": "index.ts",
   "types": "index.ts",
@@ -9,7 +9,10 @@
     "v3.ts"
   ],
   "scripts": {
-    "verify": "tsc --noEmit v3.ts"
+    "verify": "tsc --noEmit v3.ts",
+    "generate": "bash generate-types.sh",
+    "preversion": "npm run generate && git add v3.ts",
+    "prepublishonly": "git diff HEAD v3.ts || (echo 'Error: No changes to v3.ts since last publish' && exit 1)"
   },
   "keywords": [
     "api",

package/v3.ts

@@ -1,11 +1,13 @@
-// V3 API Types
-// Manually exported from backend TypeBox schemas
-// Update this as new V3 endpoints are added
+// Auto-generated from pfapi-fs/src/routes/v3/*/schemas.ts
+// Do not edit manually - run `npm run generate` to update
 
 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' }),
@@ -21,48 +23,66 @@ export const SetListItemSchema = Type.Object({
 
 export type SetListItem = Static<typeof SetListItemSchema>;
 
-export const SetListResponseSchema = Type.Object({
-  data: Type.Array(SetListItemSchema),
-  total: Type.Number({ description: 'Total number of sets' }),
-  count: Type.Number({ description: 'Number of sets returned' })
-});
+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>;
 
-export const RarityCountSchema = Type.Object({
-  rarity: Type.String(),
-  count: Type.Number()
-});
+// 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(),
-  name: Type.String(),
-  printedtotal: Type.Number(),
-  total: Type.Number(),
-  series: Type.String(),
-  releaseddate: Type.String({ format: 'date' }),
-  updatedat: Type.String({ format: 'date-time' }),
-  imgsymbol: Type.String({ format: 'uri' }),
-  imglogo: Type.String({ format: 'uri' }),
-  slug: Type.String(),
-  ptcgocode: Type.Optional(Type.String()),
-  legalities: Type.Optional(Type.Record(Type.String(), Type.String())),
-  current_price: Type.Optional(Type.Number()),
-  change_1d: Type.Optional(Type.Number()),
-  change_7d: Type.Optional(Type.Number()),
-  change_1m: Type.Optional(Type.Number()),
-  change_3m: Type.Optional(Type.Number()),
-  change_6m: Type.Optional(Type.Number()),
-  change_1y: Type.Optional(Type.Number()),
-  rarities: Type.Array(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/PARAMS =============
-
+// 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' })),
@@ -72,9 +92,9 @@ export const SetListQuerySchema = Type.Object({
 
 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>;
-