@pfdev/api-types

TypeScript types for PF API V3, synced directly from TypeBox schemas in pfapi-fs.

Quick Start

Install

npm install @pfdev/api-types

Use in React/React Native

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

✅ 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

Step-by-Step

1. Make changes in pfapi-fs

Add or modify V3 endpoints with TypeBox schemas:

// 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

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

3. Publish to npm

npm publish

Verifies v3.ts changed, then publishes to npm.

Manual Type Generation

To manually regenerate types without versioning:

npm run generate

How It Works

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

• 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)

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)
• ✅ All tools: FREE (open source)