@structyl/api-client

pnpm add @structyl/api-client axios

// lib/api.ts
import { createApiClient, QueryClient } from '@structyl/api-client';

export const apiClient = createApiClient({
  baseURL: 'https://api.example.com',

  // Inject the Bearer token on every request
  getAuthToken: () => localStorage.getItem('token'),

  // Called automatically when a 401 is received
  refreshToken: async () => {
    const res = await fetch('/api/auth/refresh', { method: 'POST' });
    const { token } = await res.json();
    localStorage.setItem('token', token);
    return token;
  },

  // Called if refresh itself fails (e.g. redirect to login)
  onRefreshError: () => { window.location.href = '/login'; },

  timeout: 10_000,
  headers: { 'X-App-Version': '1.0.0' },
});

export const queryClient = new QueryClient({
  gcTime: 5 * 60_000, // garbage-collect unused entries after 5 min
  onError: (err) => console.error(err),
});

// app/layout.tsx  (or _app.tsx in pages router)
import { ApiProvider } from '@structyl/api-client';
import { apiClient, queryClient } from '@/lib/api';

export default function RootLayout({ children }) {
  return (
    <ApiProvider client={apiClient} queryClient={queryClient}>
      {children}
    </ApiProvider>
  );
}

import { useApiQuery } from '@structyl/api-client';

interface User { id: number; name: string; email: string }

export function UserList() {
  const { data, isLoading, error, refetch } = useApiQuery<User[]>('/users');

  if (isLoading) return <Spinner />;
  if (error)     return <Error message={error.message} />;

  return (
    <>
      {data?.map(user => <UserCard key={user.id} user={user} />)}
      <button onClick={refetch}>Refresh</button>
    </>
  );
}

// Overload 1 — URL is both key and fetcher (most common)
const { data } = useApiQuery<User[]>('/users');

// Overload 2 — Separate key + URL (e.g. key includes variables)
const { data } = useApiQuery<User>(['/users', userId], `/users/${userId}`);

// Overload 3 — Separate key + custom fetcher
const { data } = useApiQuery<User>(
  ['/users', userId],
  (axios) => axios.get(`/users/${userId}`).then(r => r.data),
);

import { useApiMutation } from '@structyl/api-client';

interface CreateUser { name: string; email: string }

function CreateUserForm() {
  const { mutate, mutateAsync, isPending, isError, error, reset } =
    useApiMutation<User, CreateUser>('/users', {
      method: 'POST',

      // Invalidate the /users list cache after success → triggers refetch
      invalidates: [['/users']],

      onSuccess: (user, variables) => {
        toast.success(`Created ${user.name}`);
      },

      onError: (err) => {
        toast.error(err.message);
      },
    });

  return (
    <form onSubmit={e => {
      e.preventDefault();
      const data = new FormData(e.currentTarget);
      mutate({ name: data.get('name'), email: data.get('email') });
    }}>
      <input name="name" />
      <input name="email" />
      <button disabled={isPending}>{isPending ? 'Saving…' : 'Create'}</button>
      {isError && <p>{error?.message} <button onClick={reset}>Dismiss</button></p>}
    </form>
  );
}

const { mutate } = useApiMutation<Post, { id: number; liked: boolean }>(
  '/posts/like',
  {
    method: 'PATCH',
    optimistic: {
      queryKey: ['/posts'],
      updater: (oldPosts, { id, liked }) =>
        oldPosts?.map(p => p.id === id ? { ...p, liked, likeCount: p.likeCount + (liked ? 1 : -1) } : p) ?? [],
    },
    // On error: old posts are automatically restored
    onError: (err) => toast.error('Failed to like — reverted'),
  }
);

// UI responds immediately
mutate({ id: post.id, liked: !post.liked });

function AvatarUpload() {
  const [progress, setProgress] = React.useState(0);

  const { mutate, isPending } = useApiMutation<{ url: string }, FormData>(
    '/upload/avatar',
    {
      method: 'POST',
      onUploadProgress: (pct) => setProgress(pct),
      onSuccess: ({ url }) => updateAvatar(url),
    }
  );

  const onFile = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;
    const fd = new FormData();
    fd.append('file', file);
    mutate(fd);
  };

  return (
    <>
      <input type="file" onChange={onFile} accept="image/*" />
      {isPending && <progress value={progress} max={100} />}
    </>
  );
}

const { data, fetchNextPage } = useInfiniteApiQuery<UserPage>('/users', {
  getNextPageParam: (last, all) =>
    last.hasMore ? all.length : undefined, // page index = array length

  fetchPage: async (pageParam, axios) => {
    const page = pageParam as number ?? 0;
    const res = await axios.get('/users', { params: { offset: page * 20, limit: 20 } });
    return res.data;
  },
});

// app/users/page.tsx  (Server Component)
import { prefetchApiQuery, dehydrate } from '@structyl/api-client/server';
import { apiClient, queryClient } from '@/lib/api';
import { HydrationBoundary } from '@structyl/api-client';
import { UserList } from './UserList';

export default async function UsersPage() {
  // Prefetch on server — populates queryClient cache
  await prefetchApiQuery(queryClient, apiClient, '/users');

  return (
    // Serialize the cache and send to client
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UserList /> {/* renders without a loading state */}
    </HydrationBoundary>
  );
}

// app/users/UserList.tsx  ('use client')
// useApiQuery finds the prefetched data in cache → no loading state
function UserList() {
  const { data } = useApiQuery('/users'); // instant!
  return <>{data?.map(u => <UserCard key={u.id} user={u} />)}</>;
}

// pages/users.tsx
import { prefetchApiQuery, dehydrate } from '@structyl/api-client/server';
import { apiClient, queryClient } from '@/lib/api';

export async function getServerSideProps() {
  await prefetchApiQuery(queryClient, apiClient, '/users');
  return { props: { dehydratedState: dehydrate(queryClient) } };
}

export default function UsersPage({ dehydratedState }) {
  return (
    <HydrationBoundary state={dehydratedState}>
      <UserList />
    </HydrationBoundary>
  );
}

const { instance } = useApiClient();
const res = await instance.get('/download', { responseType: 'blob' });

interface ApiError {
  status: number;  // HTTP status code (0 for network errors)
  message: string; // Human-readable message
  data?: unknown;  // Raw response body from the server, if any
}