@ph-cms/client-sdk 0.1.2 → 0.1.4

package/README.md

@@ -8,6 +8,7 @@ This package provides:
 - Auth provider interfaces and implementations
 - React context and hooks for consuming the client in UI code
 - **Integrated React Query support** (from v0.1.1)
+- **Automatic Auth State Management** (from v0.1.3)
 
 ## Installation
 
@@ -15,46 +16,21 @@ This package provides:
 npm install @ph-cms/client-sdk
 ```
 
-> **Note:** `@tanstack/react-query` is a direct dependency from v0.1.1. You no longer need to install it manually unless you use it in your own application code.
+> **Note:** `@tanstack/react-query` is a direct dependency. You no longer need to install it manually unless you use it in your own application code.
 
-If you use the React bindings, ensure you have `react` installed:
+## React Usage
 
-```bash
-npm install react react-dom
-```
-
-If you use Firebase auth integration:
-
-```bash
-npm install firebase
-```
+`PHCMSProvider` automatically includes a `QueryClientProvider` and manages the global authentication state.
 
-## Usage (Core SDK)
+### Basic Setup
 
-```ts
-import { PHCMSClient } from '@ph-cms/client-sdk';
+```tsx
+import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
 
 const client = new PHCMSClient({
   baseURL: 'https://api.example.com',
 });
 
-// Use the modules directly
-const contents = await client.content.list({
-  page: 1,
-  limit: 20,
-});
-```
-
-## React Usage (v0.1.1+)
-
-From version 0.1.1, `PHCMSProvider` automatically includes a `QueryClientProvider`. You don't need to wrap your app with `QueryClientProvider` manually to use PH-CMS hooks.
-
-### Basic Setup
-
-```tsx
-import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
-import { client } from './lib/sdk'; // Your pre-configured client
-
 export function App() {
   return (
     <PHCMSProvider client={client}>
@@ -64,65 +40,96 @@ export function App() {
 }
 ```
 
-### Using Hooks
+### Authentication State (`useAuth`)
+
+From v0.1.3, the `useAuth` hook provides a unified interface for both authentication state and actions.
 
 ```tsx
-import { useContent, useUser } from '@ph-cms/client-sdk';
+import { useAuth } from '@ph-cms/client-sdk';
 
-function MyComponent() {
-  const { data: user, isLoading: userLoading } = useUser();
-  const { data: contents, isLoading: contentLoading } = useContent();
+function ProfileComponent() {
+  const { 
+    user, 
+    isAuthenticated, 
+    isLoading, 
+    login, 
+    logout 
+  } = useAuth();
 
-  if (userLoading || contentLoading) return <div>Loading...</div>;
+  if (isLoading) return <div>Checking auth...</div>;
+
+  if (!isAuthenticated) {
+    return <button onClick={() => login({ email: '...', password: '...' })}>Login</button>;
+  }
 
   return (
     <div>
-      <h1>Hello, {user?.email}</h1>
-      <ul>
-        {contents?.items.map(item => (
-          <li key={item.uid}>{item.title}</li>
-        ))}
-      </ul>
+      <h1>Welcome, {user?.display_name}</h1>
+      <button onClick={() => logout()}>Logout</button>
     </div>
   );
 }
 ```
 
-### Custom QueryClient (Optional)
-
-If your application already uses React Query and you want to share the cache/settings:
+### Using Data Hooks
 
 ```tsx
-import { QueryClient } from '@tanstack/react-query';
-import { PHCMSClient, PHCMSProvider } from '@ph-cms/client-sdk';
+import { useContentList, useContentDetail } from '@ph-cms/client-sdk';
 
-const queryClient = new QueryClient();
-const client = new PHCMSClient({ baseURL: '...' });
+function ContentList() {
+  const { data, isLoading } = useContentList({ limit: 10 });
+
+  if (isLoading) return <div>Loading...</div>;
 
-export function App() {
   return (
-    <PHCMSProvider client={client} queryClient={queryClient}>
-      {/* Both your app and PH-CMS hooks will use the same queryClient */}
-      <YourComponents />
-    </PHCMSProvider>
+    <ul>
+      {data?.content.map(item => (
+        <li key={item.uid}>{item.title}</li>
+      ))}
+    </ul>
   );
 }
 ```
 
-## Admin SDK (@ph-cms/client-sdk-admin)
+## Media & File Upload
 
-For administrative tasks, use `@ph-cms/client-sdk-admin`. It follows the same provider pattern:
+Uploading media files follows a 3-step process: Request a Ticket -> Upload to S3 -> Create/Update Content.
 
-```tsx
-import { PHCMSAdminProvider } from '@ph-cms/client-sdk-admin';
-import { adminClient } from './lib/sdk';
+### Simple Workflow Example
 
-export function App() {
-  return (
-    <PHCMSAdminProvider client={adminClient}>
-      <AdminComponents />
-    </PHCMSAdminProvider>
-  );
+```tsx
+import { useMediaUploadTickets, useUploadToS3, useCreateContent } from '@ph-cms/client-sdk';
+
+function MediaUploader() {
+  const { mutateAsync: getTickets } = useMediaUploadTickets();
+  const { mutateAsync: uploadToS3 } = useUploadToS3();
+  const { mutateAsync: createContent } = useCreateContent();
+
+  const handleFileChange = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0];
+    if (!file) return;
+
+    // Step 1: Get Upload Ticket (Presigned URL)
+    const tickets = await getTickets([{
+      filename: file.name,
+      contentType: file.type,
+      fileSize: file.size,
+    }]);
+
+    const { mediaUid, uploadUrl } = tickets[0];
+
+    // Step 2: Upload File directly to S3
+    await uploadToS3({ url: uploadUrl, file });
+
+    // Step 3: Use the mediaUid to create content
+    await createContent({
+      type: 'post',
+      title: 'Post with image',
+      mediaAttachments: [mediaUid]
+    });
+  };
+
+  return <input type="file" onChange={handleFileChange} />;
 }
 ```
 

package/dist/context.d.ts

@@ -1,10 +1,28 @@
 import React, { ReactNode } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { PHCMSClient } from './client';
+import { UserDto } from '@ph-cms/api-contract';
+export interface PHCMSContextType {
+    client: PHCMSClient;
+    user: UserDto | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+}
 export interface PHCMSProviderProps {
     client: PHCMSClient;
     queryClient?: QueryClient;
     children: ReactNode;
 }
+/**
+ * Root Provider for PH-CMS
+ * Automatically includes QueryClientProvider
+ */
 export declare const PHCMSProvider: React.FC<PHCMSProviderProps>;
+/**
+ * Access the full PH-CMS Context (client, user, auth status)
+ */
+export declare const usePHCMSContext: () => PHCMSContextType;
+/**
+ * Access the PH-CMS Client instance
+ */
 export declare const usePHCMS: () => PHCMSClient;

package/dist/context.js

@@ -33,21 +33,60 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.usePHCMS = exports.PHCMSProvider = void 0;
+exports.usePHCMS = exports.usePHCMSContext = exports.PHCMSProvider = void 0;
 const react_1 = __importStar(require("react"));
 const react_query_1 = require("@tanstack/react-query");
 const PHCMSContext = (0, react_1.createContext)(null);
+/**
+ * Internal component to handle auth state and provide to context
+ */
+const PHCMSInternalProvider = ({ client, children }) => {
+    const { data: user, isLoading, isError } = (0, react_query_1.useQuery)({
+        queryKey: ['auth', 'me'],
+        queryFn: () => client.auth.me(),
+        retry: false,
+        staleTime: 1000 * 60 * 5,
+    });
+    const value = (0, react_1.useMemo)(() => ({
+        client,
+        user: user || null,
+        isAuthenticated: !!user && !isError,
+        isLoading,
+    }), [client, user, isError, isLoading]);
+    return (react_1.default.createElement(PHCMSContext.Provider, { value: value }, children));
+};
+/**
+ * Root Provider for PH-CMS
+ * Automatically includes QueryClientProvider
+ */
 const PHCMSProvider = ({ client, queryClient, children }) => {
-    const internalQueryClient = (0, react_1.useMemo)(() => queryClient ?? new react_query_1.QueryClient(), [queryClient]);
-    return (react_1.default.createElement(PHCMSContext.Provider, { value: { client } },
-        react_1.default.createElement(react_query_1.QueryClientProvider, { client: internalQueryClient }, children)));
+    const internalQueryClient = (0, react_1.useMemo)(() => queryClient ?? new react_query_1.QueryClient({
+        defaultOptions: {
+            queries: {
+                refetchOnWindowFocus: false,
+                retry: false,
+            },
+        },
+    }), [queryClient]);
+    return (react_1.default.createElement(react_query_1.QueryClientProvider, { client: internalQueryClient },
+        react_1.default.createElement(PHCMSInternalProvider, { client: client }, children)));
 };
 exports.PHCMSProvider = PHCMSProvider;
-const usePHCMS = () => {
+/**
+ * Access the full PH-CMS Context (client, user, auth status)
+ */
+const usePHCMSContext = () => {
     const context = (0, react_1.useContext)(PHCMSContext);
     if (!context) {
-        throw new Error('usePHCMS must be used within a PHCMSProvider');
+        throw new Error('usePHCMSContext must be used within a PHCMSProvider');
     }
-    return context.client;
+    return context;
+};
+exports.usePHCMSContext = usePHCMSContext;
+/**
+ * Access the PH-CMS Client instance
+ */
+const usePHCMS = () => {
+    return (0, exports.usePHCMSContext)().client;
 };
 exports.usePHCMS = usePHCMS;

package/dist/hooks/useAuth.d.ts

@@ -1,5 +1,8 @@
-export declare const useLogin: () => import("@tanstack/react-query").UseMutationResult<{
-    refreshToken: string;
+/**
+ * Unified Auth Hook
+ * Returns both the current auth status and the actions
+ */
+export declare const useAuth: () => {
     user: {
         uid: string;
         email: string;
@@ -17,39 +20,148 @@ export declare const useLogin: () => import("@tanstack/react-query").UseMutation
         last_login_at: string | null;
         created_at: string;
         updated_at: string;
-    };
-    accessToken: string;
-}, Error, {
-    email: string;
-    password: string;
-}, unknown>;
-export declare const useLoginWithFirebase: () => import("@tanstack/react-query").UseMutationResult<{
-    refreshToken: string;
-    user: {
-        uid: string;
+    } | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    login: import("@tanstack/react-query").UseMutateAsyncFunction<{
+        refreshToken: string;
+        user: {
+            uid: string;
+            email: string;
+            username: string | null;
+            display_name: string;
+            avatar_url: string | null;
+            phone_number: string | null;
+            email_verified_at: string | null;
+            phone_verified_at: string | null;
+            locale: string;
+            timezone: string;
+            status: string;
+            role: string[];
+            profile_data: Record<string, any>;
+            last_login_at: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        accessToken: string;
+    }, Error, {
+        email: string;
+        password: string;
+    }, unknown>;
+    loginWithFirebase: import("@tanstack/react-query").UseMutateAsyncFunction<{
+        refreshToken: string;
+        user: {
+            uid: string;
+            email: string;
+            username: string | null;
+            display_name: string;
+            avatar_url: string | null;
+            phone_number: string | null;
+            email_verified_at: string | null;
+            phone_verified_at: string | null;
+            locale: string;
+            timezone: string;
+            status: string;
+            role: string[];
+            profile_data: Record<string, any>;
+            last_login_at: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        accessToken: string;
+    }, Error, {
+        idToken: string;
+    }, unknown>;
+    register: import("@tanstack/react-query").UseMutateAsyncFunction<{
+        refreshToken: string;
+        user: {
+            uid: string;
+            email: string;
+            username: string | null;
+            display_name: string;
+            avatar_url: string | null;
+            phone_number: string | null;
+            email_verified_at: string | null;
+            phone_verified_at: string | null;
+            locale: string;
+            timezone: string;
+            status: string;
+            role: string[];
+            profile_data: Record<string, any>;
+            last_login_at: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        accessToken: string;
+    }, Error, {
         email: string;
-        username: string | null;
         display_name: string;
-        avatar_url: string | null;
-        phone_number: string | null;
-        email_verified_at: string | null;
-        phone_verified_at: string | null;
-        locale: string;
-        timezone: string;
-        status: string;
-        role: string[];
-        profile_data: Record<string, any>;
-        last_login_at: string | null;
-        created_at: string;
-        updated_at: string;
-    };
-    accessToken: string;
-}, Error, {
-    idToken: string;
-}, unknown>;
-export declare const useRegister: () => import("@tanstack/react-query").UseMutationResult<{
-    refreshToken: string;
-    user: {
+        username?: string | null | undefined;
+        password?: string | undefined;
+        provider?: string | undefined;
+        provider_subject?: string | undefined;
+        termCodes?: string[] | undefined;
+    }, unknown>;
+    logout: import("@tanstack/react-query").UseMutateAsyncFunction<void, Error, void, unknown>;
+    loginStatus: import("@tanstack/react-query").UseMutationResult<{
+        refreshToken: string;
+        user: {
+            uid: string;
+            email: string;
+            username: string | null;
+            display_name: string;
+            avatar_url: string | null;
+            phone_number: string | null;
+            email_verified_at: string | null;
+            phone_verified_at: string | null;
+            locale: string;
+            timezone: string;
+            status: string;
+            role: string[];
+            profile_data: Record<string, any>;
+            last_login_at: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        accessToken: string;
+    }, Error, {
+        email: string;
+        password: string;
+    }, unknown>;
+    registerStatus: import("@tanstack/react-query").UseMutationResult<{
+        refreshToken: string;
+        user: {
+            uid: string;
+            email: string;
+            username: string | null;
+            display_name: string;
+            avatar_url: string | null;
+            phone_number: string | null;
+            email_verified_at: string | null;
+            phone_verified_at: string | null;
+            locale: string;
+            timezone: string;
+            status: string;
+            role: string[];
+            profile_data: Record<string, any>;
+            last_login_at: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        accessToken: string;
+    }, Error, {
+        email: string;
+        display_name: string;
+        username?: string | null | undefined;
+        password?: string | undefined;
+        provider?: string | undefined;
+        provider_subject?: string | undefined;
+        termCodes?: string[] | undefined;
+    }, unknown>;
+    logoutStatus: import("@tanstack/react-query").UseMutationResult<void, Error, void, unknown>;
+};
+export declare const useUser: () => {
+    data: {
         uid: string;
         email: string;
         username: string | null;
@@ -66,33 +178,37 @@ export declare const useRegister: () => import("@tanstack/react-query").UseMutat
         last_login_at: string | null;
         created_at: string;
         updated_at: string;
-    };
-    accessToken: string;
-}, Error, {
-    email: string;
-    display_name: string;
-    username?: string | null | undefined;
-    password?: string | undefined;
-    provider?: string | undefined;
-    provider_subject?: string | undefined;
-    termCodes?: string[] | undefined;
-}, unknown>;
-export declare const useLogout: () => import("@tanstack/react-query").UseMutationResult<void, Error, void, unknown>;
-export declare const useUser: () => import("@tanstack/react-query").UseQueryResult<{
-    uid: string;
-    email: string;
-    username: string | null;
-    display_name: string;
-    avatar_url: string | null;
-    phone_number: string | null;
-    email_verified_at: string | null;
-    phone_verified_at: string | null;
-    locale: string;
-    timezone: string;
-    status: string;
-    role: string[];
-    profile_data: Record<string, any>;
-    last_login_at: string | null;
-    created_at: string;
-    updated_at: string;
-}, Error>;
+    } | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+};
+export declare const useLogin: () => {
+    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<{
+        refreshToken: string;
+        user: {
+            uid: string;
+            email: string;
+            username: string | null;
+            display_name: string;
+            avatar_url: string | null;
+            phone_number: string | null;
+            email_verified_at: string | null;
+            phone_verified_at: string | null;
+            locale: string;
+            timezone: string;
+            status: string;
+            role: string[];
+            profile_data: Record<string, any>;
+            last_login_at: string | null;
+            created_at: string;
+            updated_at: string;
+        };
+        accessToken: string;
+    }, Error, {
+        email: string;
+        password: string;
+    }, unknown>;
+};
+export declare const useLogout: () => {
+    mutateAsync: import("@tanstack/react-query").UseMutateAsyncFunction<void, Error, void, unknown>;
+};

package/dist/hooks/useAuth.js

@@ -1,62 +1,69 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useUser = exports.useLogout = exports.useRegister = exports.useLoginWithFirebase = exports.useLogin = void 0;
+exports.useLogout = exports.useLogin = exports.useUser = exports.useAuth = void 0;
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("../context");
-const useLogin = () => {
+/**
+ * Unified Auth Hook
+ * Returns both the current auth status and the actions
+ */
+const useAuth = () => {
+    const { user, isAuthenticated, isLoading } = (0, context_1.usePHCMSContext)();
     const client = (0, context_1.usePHCMS)();
     const queryClient = (0, react_query_1.useQueryClient)();
-    return (0, react_query_1.useMutation)({
+    const loginMutation = (0, react_query_1.useMutation)({
         mutationFn: (data) => client.auth.login(data),
-        onSuccess: (data) => {
-            // Invalidate user query to fetch fresh user data
+        onSuccess: () => {
             queryClient.invalidateQueries({ queryKey: ['auth', 'me'] });
         },
     });
-};
-exports.useLogin = useLogin;
-const useLoginWithFirebase = () => {
-    const client = (0, context_1.usePHCMS)();
-    const queryClient = (0, react_query_1.useQueryClient)();
-    return (0, react_query_1.useMutation)({
+    const loginWithFirebaseMutation = (0, react_query_1.useMutation)({
         mutationFn: (data) => client.auth.loginWithFirebase(data),
-        onSuccess: (data) => {
-            // Invalidate user query to fetch fresh user data
+        onSuccess: () => {
             queryClient.invalidateQueries({ queryKey: ['auth', 'me'] });
         },
     });
-};
-exports.useLoginWithFirebase = useLoginWithFirebase;
-const useRegister = () => {
-    const client = (0, context_1.usePHCMS)();
-    const queryClient = (0, react_query_1.useQueryClient)();
-    return (0, react_query_1.useMutation)({
+    const registerMutation = (0, react_query_1.useMutation)({
         mutationFn: (data) => client.auth.register(data),
         onSuccess: () => {
             queryClient.invalidateQueries({ queryKey: ['auth', 'me'] });
         },
     });
-};
-exports.useRegister = useRegister;
-const useLogout = () => {
-    const client = (0, context_1.usePHCMS)();
-    const queryClient = (0, react_query_1.useQueryClient)();
-    return (0, react_query_1.useMutation)({
+    const logoutMutation = (0, react_query_1.useMutation)({
         mutationFn: () => client.auth.logout(),
         onSuccess: () => {
             queryClient.setQueryData(['auth', 'me'], null);
             queryClient.invalidateQueries();
         },
     });
+    return {
+        user,
+        isAuthenticated,
+        isLoading,
+        login: loginMutation.mutateAsync,
+        loginWithFirebase: loginWithFirebaseMutation.mutateAsync,
+        register: registerMutation.mutateAsync,
+        logout: logoutMutation.mutateAsync,
+        // Access to mutation objects for loading/error states if needed
+        loginStatus: loginMutation,
+        registerStatus: registerMutation,
+        logoutStatus: logoutMutation,
+    };
 };
-exports.useLogout = useLogout;
+exports.useAuth = useAuth;
+// Keep individual hooks for backward compatibility or more specific use cases
 const useUser = () => {
-    const client = (0, context_1.usePHCMS)();
-    return (0, react_query_1.useQuery)({
-        queryKey: ['auth', 'me'],
-        queryFn: () => client.auth.me(),
-        retry: false, // Don't retry if 401
-        staleTime: 1000 * 60 * 5, // 5 minutes
-    });
+    const { user, isLoading, isAuthenticated } = (0, context_1.usePHCMSContext)();
+    return { data: user, isLoading, isAuthenticated };
 };
 exports.useUser = useUser;
+const useLogin = () => {
+    const { login } = (0, exports.useAuth)();
+    return { mutateAsync: login };
+};
+exports.useLogin = useLogin;
+const useLogout = () => {
+    const { logout } = (0, exports.useAuth)();
+    return { mutateAsync: logout };
+};
+exports.useLogout = useLogout;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ph-cms/client-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Unified PH-CMS Client SDK (React + Core)",
   "keywords": [],
   "license": "MIT",