@pfdev/api-types 3.0.0

package/README.md

@@ -0,0 +1,110 @@
+# @pfdev/api-types
+
+TypeScript types for PF API V3, directly exported from TypeBox schemas.
+
+## Quick Start
+
+### Install
+
+```bash
+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();
+};
+```
+
+## 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  
+
+## Development
+
+### Add/Update Types
+
+When you add new V3 endpoints:
+
+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
+
+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>
+
+# Types package: Re-export in v3.ts
+# pfapi-types/v3.ts
+export { CardSchema, type Card } from '...'
+
+# Publish
+npm version patch
+npm publish
+```
+
+## Publishing
+
+### First Time Only
+
+1. Create free npm account: https://www.npmjs.com/signup
+2. Login locally: `npm login`
+3. Publish: `npm publish`
+
+### Update Existing Package
+
+```bash
+# Regenerate types from updated API
+npm run generate
+
+# Bump version
+npm version patch  # or minor/major
+
+# Publish
+npm publish
+```
+
+## Version Mapping
+
+- **V3.x.x** - API V3 types
+- **V2.x.x** - (future) API V2 types
+
+## Files
+
+- `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
+
+## 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.

package/index.ts

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

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@pfdev/api-types",
+  "version": "3.0.0",
+  "description": "TypeScript types for PF API V3",
+  "main": "index.ts",
+  "types": "index.ts",
+  "files": [
+    "index.ts",
+    "v3.ts"
+  ],
+  "scripts": {
+    "verify": "tsc --noEmit v3.ts"
+  },
+  "keywords": [
+    "api",
+    "types",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@sinclair/typebox": "^0.34.52",
+    "typescript": "^7.0.2"
+  }
+}

package/v3.ts

@@ -0,0 +1,80 @@
+// V3 API Types
+// Manually exported from backend TypeBox schemas
+// Update this as new V3 endpoints are added
+
+import { Static, Type } from '@sinclair/typebox';
+
+// ============= 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),
+  total: Type.Number({ description: 'Total number of sets' }),
+  count: Type.Number({ description: 'Number of sets returned' })
+});
+
+export type SetListResponse = Static<typeof SetListResponseSchema>;
+
+export const RarityCountSchema = Type.Object({
+  rarity: Type.String(),
+  count: Type.Number()
+});
+
+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 type SetDetail = Static<typeof SetDetailSchema>;
+
+// ============= QUERY/PARAMS =============
+
+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>;
+
+export const SetDetailParamSchema = Type.Object({
+  setid: Type.String({ description: 'Set ID or slug' })
+});
+
+export type SetDetailParam = Static<typeof SetDetailParamSchema>;
+