npm - @archiva/archiva-nextjs - Versions diffs - 0.1.4 → 0.1.5 - Mend

@archiva/archiva-nextjs 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @archiva/archiva-nextjs
-Next.js SDK for Archiva - Server Actions and Timeline Component
+Next.js SDK for Archiva - Frontend Token Provider and Timeline Component
 ## Installation
@@ -12,7 +12,9 @@ pnpm add @archiva/archiva-nextjs
 yarn add @archiva/archiva-nextjs
 ```
-## Setup
+## Quick Start
+### 1. Set Environment Variable
 Set the `ARCHIVA_SECRET_KEY` environment variable in your `.env.local` file:
@@ -20,152 +22,349 @@ Set the `ARCHIVA_SECRET_KEY` environment variable in your `.env.local` file:
 ARCHIVA_SECRET_KEY=pk_test_xxxxx
 ```
-## Usage
+**Important:** This should be a valid Archiva API key. The SDK uses this to mint short-lived frontend tokens securely on the server.
+### 2. Create Token Endpoint Route
-### ArchivaProvider (Client Component)
+Create a Next.js API route to handle frontend token requests. This route will be called by the SDK to fetch short-lived tokens.
-Wrap your application (or specific routes) with the ArchivaProvider component. The provider makes the API key available to child components via React context:
+**File:** `app/api/archiva/frontend-token/route.ts`
 ```tsx
-import { ArchivaProvider } from '@archiva/archiva-nextjs';
+import { GET } from '@archiva/archiva-nextjs/server';
-export default function Layout({ children }) {
-  // API key can be passed as prop, or it will use ARCHIVA_SECRET_KEY env var
-  return (
-    <ArchivaProvider apiKey="pk_test_xxxxx">
-      {children}
-    </ArchivaProvider>
-  );
-}
+// Export the GET handler - that's it!
+export { GET };
 ```
-**Note:** If you don't pass an `apiKey` prop, the provider will use the `ARCHIVA_SECRET_KEY` environment variable. The Timeline component and server actions will automatically use the API key from the provider context.
+Or with custom configuration:
-### Server Actions
+```tsx
+import { createFrontendTokenRoute } from '@archiva/archiva-nextjs/server';
-#### loadEvents
+export const GET = createFrontendTokenRoute({
+  apiBaseUrl: process.env.ARCHIVA_API_URL, // Optional: defaults to https://api.archiva.app
+});
+```
+### 3. Wrap Your App with ArchivaProvider
+Wrap your application layout with the `ArchivaProvider` component. This is a **server component** that validates your `ARCHIVA_SECRET_KEY` and provides the token management context to client components.
-Load audit events with filtering and pagination:
+**File:** `app/layout.tsx`
 ```tsx
-import { loadEvents } from '@archiva/archiva-nextjs';
-// In a Server Component or Server Action
-const events = await loadEvents({
-  entityId: 'entity_123',
-  actorId: 'actor_456',
-  entityType: 'invoice',
-  limit: 25,
-  cursor: 'optional_cursor',
-});
+import { ArchivaProvider } from '@archiva/archiva-nextjs/react';
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <ArchivaProvider>
+          {children}
+        </ArchivaProvider>
+      </body>
+    </html>
+  );
+}
 ```
-#### createEvent
+**Important:** Always import `ArchivaProvider` from `@archiva/archiva-nextjs/react` (not from the root package). This ensures the import is server-safe and won't trigger RSC errors.
-Create a single audit event:
+With custom configuration:
 ```tsx
-import { createEvent } from '@archiva/archiva-nextjs';
-const result = await createEvent({
-  action: 'update',
-  entityType: 'invoice',
-  entityId: 'inv_123',
-  actorType: 'user',
-  actorId: 'usr_123',
-  actorDisplay: 'John Doe',
-  occurredAt: new Date().toISOString(),
-  source: 'web',
-  context: {
-    requestId: 'req_123',
-  },
-  changes: [
-    {
-      op: 'set',
-      path: 'status',
-      before: 'draft',
-      after: 'sent',
-    },
-  ],
-});
+import { ArchivaProvider } from '@archiva/archiva-nextjs/react';
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <ArchivaProvider
+          apiBaseUrl="https://api.archiva.app"
+          tokenEndpoint="/api/archiva/frontend-token"
+          projectId="proj_123" // Optional: for project-scoped tokens
+        >
+          {children}
+        </ArchivaProvider>
+      </body>
+    </html>
+  );
+}
 ```
-#### createEvents (Bulk)
+### 4. Use the Timeline Component
-Create multiple events at once:
+Now you can use the `Timeline` component in any client component. It will automatically:
+- Fetch short-lived frontend tokens
+- Call the Archiva API directly (no proxy routes needed)
+- Handle token refresh automatically
+- Retry on 401/403 errors
+**File:** `app/invoice/[id]/page.tsx`
 ```tsx
-import { createEvents } from '@archiva/archiva-nextjs';
+'use client';
+import { Timeline } from '@archiva/archiva-nextjs/react/client';
-const result = await createEvents([
-  {
-    action: 'create',
-    entityType: 'invoice',
-    entityId: 'inv_123',
-    // ... other fields
-  },
-  {
-    action: 'update',
-    entityType: 'invoice',
-    entityId: 'inv_123',
-    // ... other fields
-  },
-]);
+export default function InvoicePage({ params }: { params: { id: string } }) {
+  return (
+    <div>
+      <h1>Invoice {params.id}</h1>
+      <Timeline
+        entityId={params.id}
+        entityType="invoice"
+        initialLimit={25}
+      />
+    </div>
+  );
+}
 ```
-### Timeline Component (Client Component)
+**Note:** Client components like `Timeline` and `useArchiva` must be imported from `@archiva/archiva-nextjs/react/client` to ensure proper client/server code splitting.
-Display a timeline of audit events. The Timeline component automatically uses the API key from the ArchivaProvider context:
+## How It Works
+The SDK implements a Clerk-style provider pattern with short-lived frontend tokens:
+1. **Server Component (`ArchivaProvider`)**: Validates `ARCHIVA_SECRET_KEY` exists (never exposes it to the client)
+2. **Client Component (`ArchivaProviderClient`)**: Manages token lifecycle:
+   - Fetches tokens from your `/api/archiva/frontend-token` route
+   - Caches tokens in memory
+   - Auto-refreshes 30 seconds before expiry
+   - Handles 401/403 errors with automatic retry
+3. **Timeline Component**: Uses tokens to call Archiva API directly
+### Token Flow
+```
+Client Component → useArchiva().getToken()
+  ↓
+ArchivaProviderClient checks cache
+  ↓
+If expired/absent → GET /api/archiva/frontend-token
+  ↓
+Your route → POST /v1/frontend-tokens (Archiva API)
+  ↓
+Server mints JWT (90s expiry)
+  ↓
+Token returned → Cached → Used for API calls
+```
+## Advanced Usage
+### Using the `useArchiva` Hook
+Access the Archiva context directly in your components:
 ```tsx
 'use client';
-import { Timeline } from '@archiva/archiva-nextjs';
+import { useArchiva } from '@archiva/archiva-nextjs/react/client';
+export function CustomTimeline({ entityId }: { entityId: string }) {
+  const { apiBaseUrl, getToken, forceRefreshToken } = useArchiva();
+  const [events, setEvents] = React.useState([]);
+  React.useEffect(() => {
+    async function loadEvents() {
+      const token = await getToken();
+      const response = await fetch(`${apiBaseUrl}/api/events?entityId=${entityId}`, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      });
+      if (!response.ok) {
+        // SDK automatically handles 401/403 with retry
+        throw new Error('Failed to load events');
+      }
+      const data = await response.json();
+      setEvents(data.items);
+    }
+    loadEvents();
+  }, [entityId, apiBaseUrl, getToken]);
-export function InvoiceTimeline({ invoiceId }: { invoiceId: string }) {
   return (
-    <Timeline
-      entityId={invoiceId}
-      entityType="invoice"
-      initialLimit={25}
-    />
+    <div>
+      {events.map((event) => (
+        <div key={event.id}>{event.action}</div>
+      ))}
+    </div>
   );
 }
 ```
-**Note:** The Timeline component must be used within an `ArchivaProvider`. It no longer requires an `apiKey` prop as it gets the API key from the provider context.
+### Manual Token Refresh
+Force a token refresh if needed:
+```tsx
+'use client';
+import { useArchiva } from '@archiva/archiva-nextjs/react/client';
+export function RefreshButton() {
+  const { forceRefreshToken } = useArchiva();
+  const handleRefresh = async () => {
+    try {
+      const newToken = await forceRefreshToken();
+      console.log('Token refreshed:', newToken);
+    } catch (error) {
+      console.error('Failed to refresh token:', error);
+    }
+  };
+  return <button onClick={handleRefresh}>Refresh Token</button>;
+}
+```
+### Project-Scoped Tokens
+If you want tokens scoped to a specific project, pass `projectId` to the provider:
+```tsx
+<ArchivaProvider projectId="proj_123">
+  {children}
+</ArchivaProvider>
+```
+Or pass it as a query parameter to your token endpoint:
+```tsx
+// GET /api/archiva/frontend-token?projectId=proj_123
+```
 ## API Reference
-### LoadEventsParams
+### ArchivaProvider Props
+```ts
+type ArchivaProviderProps = {
+  children: ReactNode;
+  apiBaseUrl?: string; // Default: 'https://api.archiva.app'
+  tokenEndpoint?: string; // Default: '/api/archiva/frontend-token'
+  projectId?: string; // Optional: for project-scoped tokens
+};
+```
+### Timeline Props
 ```ts
-type LoadEventsParams = {
+type TimelineProps = {
   entityId?: string;
   actorId?: string;
   entityType?: string;
-  limit?: number;
-  cursor?: string;
+  initialLimit?: number; // Default: 25
+  className?: string;
+  emptyMessage?: string; // Default: 'No events yet.'
 };
 ```
-### CreateEventInput
+### useArchiva Hook
 ```ts
-type CreateEventInput = {
-  action: string;
-  entityType: string;
-  entityId: string;
-  actorType?: string;
-  actorId?: string;
-  actorDisplay?: string;
-  occurredAt?: string;
-  source?: string;
-  context?: Record<string, unknown>;
-  changes?: EventChange[];
+type ArchivaContextValue = {
+  apiBaseUrl: string;
+  getToken: () => Promise<string>;
+  forceRefreshToken: () => Promise<string>;
+  projectId?: string;
 };
 ```
+## Security
+- **No secrets in client bundles**: `ARCHIVA_SECRET_KEY` is only used on the server
+- **Short-lived tokens**: Tokens expire in 90 seconds
+- **Automatic refresh**: Tokens refresh 30 seconds before expiry
+- **Scope enforcement**: Tokens require `timeline:read` scope
+- **Project scoping**: Tokens can be scoped to specific projects
+## Import Paths
+The SDK provides explicit entrypoints to ensure proper server/client code splitting:
+### Server Components (e.g., `app/layout.tsx`)
+```tsx
+// ✅ Correct - Server-safe import
+import { ArchivaProvider } from '@archiva/archiva-nextjs/react';
+```
+### Client Components
+```tsx
+'use client';
+// ✅ Correct - Client-only imports
+import { Timeline, useArchiva } from '@archiva/archiva-nextjs/react/client';
+```
+### Server Routes (e.g., `app/api/archiva/frontend-token/route.ts`)
+```tsx
+// ✅ Correct - Server utilities
+import { GET } from '@archiva/archiva-nextjs/server';
+```
+### Why Separate Entrypoints?
+Next.js App Router requires strict separation between server and client code. The SDK splits exports to prevent RSC errors:
+- `@archiva/archiva-nextjs/react` - Server-safe exports (ArchivaProvider only)
+- `@archiva/archiva-nextjs/react/client` - Client-only exports (Timeline, useArchiva)
+- `@archiva/archiva-nextjs/server` - Server utilities (route handlers)
+**Important:** Do NOT import client components from the root package or from `/react` in Server Components, as this will trigger RSC errors.
+## Backward Compatibility
+Legacy exports are still available from the root package for backward compatibility, but they are deprecated:
+```tsx
+// ⚠️ Legacy (deprecated - may cause RSC errors in Server Components)
+import { ArchivaProvider, Timeline } from '@archiva/archiva-nextjs';
+```
+For new projects, always use the explicit entrypoints shown above.
+## Troubleshooting
+### "ARCHIVA_SECRET_KEY not configured"
+Make sure you've set `ARCHIVA_SECRET_KEY` in your `.env.local` file and restarted your Next.js dev server.
+### "useArchivaContext must be used within an ArchivaProvider"
+Wrap your component tree with `<ArchivaProvider>`. The provider must be a server component in your layout.
+### Token endpoint returns 401
+Verify that:
+1. `ARCHIVA_SECRET_KEY` is set correctly
+2. The API key is valid and active
+3. Your token endpoint route is correctly set up
+### Timeline shows "Error: Failed to fetch frontend token"
+Check that:
+1. Your `/api/archiva/frontend-token` route exists
+2. The route handler is exported correctly
+3. `ARCHIVA_SECRET_KEY` is accessible to the route handler
 ## License
 MIT

package/dist/chunk-OSBJW2ZH.mjs ADDED Viewed

@@ -0,0 +1,157 @@
+import {
+  ArchivaContext
+} from "./chunk-XZUDW4PU.mjs";
+// src/react/ArchivaProvider.tsx
+import "server-only";
+// src/react/internal/ArchivaProviderClient.tsx
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+function ArchivaProviderClient({
+  children,
+  apiBaseUrl,
+  tokenEndpoint,
+  projectId
+}) {
+  const [tokenCache, setTokenCache] = React.useState(null);
+  const [isRefreshing, setIsRefreshing] = React.useState(false);
+  const refreshTimeoutRef = React.useRef(null);
+  React.useEffect(() => {
+    return () => {
+      if (refreshTimeoutRef.current) {
+        clearTimeout(refreshTimeoutRef.current);
+      }
+    };
+  }, []);
+  const fetchToken = React.useCallback(async () => {
+    const baseUrl = tokenEndpoint.startsWith("http") ? tokenEndpoint : typeof window !== "undefined" ? `${window.location.origin}${tokenEndpoint}` : `${apiBaseUrl}${tokenEndpoint}`;
+    const url = new URL(baseUrl);
+    if (projectId) {
+      url.searchParams.set("projectId", projectId);
+    }
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      credentials: "include"
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Failed to fetch token" }));
+      throw new Error(error.error || "Failed to fetch frontend token");
+    }
+    const data = await response.json();
+    if (!data.token || !data.expiresAt) {
+      throw new Error("Invalid token response");
+    }
+    return data.token;
+  }, [tokenEndpoint, projectId, apiBaseUrl]);
+  const getToken = React.useCallback(async () => {
+    const now = Math.floor(Date.now() / 1e3);
+    if (tokenCache && tokenCache.expiresAt > now + 30) {
+      return tokenCache.token;
+    }
+    if (isRefreshing) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      return getToken();
+    }
+    setIsRefreshing(true);
+    try {
+      const token = await fetchToken();
+      const expiresAt = getTokenExpiry(token);
+      if (!expiresAt) {
+        throw new Error("Failed to parse token expiry");
+      }
+      const newCache = { token, expiresAt };
+      setTokenCache(newCache);
+      const refreshIn = Math.max(0, expiresAt - now - 30) * 1e3;
+      if (refreshTimeoutRef.current) {
+        clearTimeout(refreshTimeoutRef.current);
+      }
+      refreshTimeoutRef.current = setTimeout(() => {
+        setTokenCache(null);
+      }, refreshIn);
+      return token;
+    } finally {
+      setIsRefreshing(false);
+    }
+  }, [tokenCache, isRefreshing, fetchToken]);
+  const forceRefreshToken = React.useCallback(async () => {
+    setTokenCache(null);
+    if (refreshTimeoutRef.current) {
+      clearTimeout(refreshTimeoutRef.current);
+      refreshTimeoutRef.current = null;
+    }
+    setIsRefreshing(true);
+    try {
+      const token = await fetchToken();
+      const expiresAt = getTokenExpiry(token);
+      if (!expiresAt) {
+        throw new Error("Failed to parse token expiry");
+      }
+      const newCache = { token, expiresAt };
+      setTokenCache(newCache);
+      const now = Math.floor(Date.now() / 1e3);
+      const refreshIn = Math.max(0, expiresAt - now - 30) * 1e3;
+      if (refreshTimeoutRef.current) {
+        clearTimeout(refreshTimeoutRef.current);
+      }
+      refreshTimeoutRef.current = setTimeout(() => {
+        setTokenCache(null);
+      }, refreshIn);
+      return token;
+    } finally {
+      setIsRefreshing(false);
+    }
+  }, [fetchToken]);
+  const value = React.useMemo(
+    () => ({
+      apiBaseUrl,
+      getToken,
+      forceRefreshToken,
+      projectId
+    }),
+    [apiBaseUrl, getToken, forceRefreshToken, projectId]
+  );
+  return /* @__PURE__ */ jsx(ArchivaContext.Provider, { value, children });
+}
+function getTokenExpiry(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return null;
+    }
+    const payload = JSON.parse(
+      atob(parts[1].replace(/-/g, "+").replace(/_/g, "/"))
+    );
+    return payload.exp;
+  } catch {
+    return null;
+  }
+}
+// src/react/ArchivaProvider.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+function ArchivaProvider({
+  children,
+  apiBaseUrl = "https://api.archiva.app",
+  tokenEndpoint = "/api/archiva/frontend-token",
+  projectId
+}) {
+  if (!process.env.ARCHIVA_SECRET_KEY) {
+    throw new Error(
+      "ARCHIVA_SECRET_KEY environment variable is required. Set it in your .env.local file."
+    );
+  }
+  return /* @__PURE__ */ jsx2(
+    ArchivaProviderClient,
+    {
+      apiBaseUrl,
+      tokenEndpoint,
+      projectId,
+      children
+    }
+  );
+}
+export {
+  ArchivaProvider
+};

package/dist/chunk-XZUDW4PU.mjs ADDED Viewed

@@ -0,0 +1,15 @@
+// src/react/context.tsx
+import * as React from "react";
+var ArchivaContext = React.createContext(void 0);
+function useArchivaContext() {
+  const context = React.useContext(ArchivaContext);
+  if (context === void 0) {
+    throw new Error("useArchivaContext must be used within an ArchivaProvider");
+  }
+  return context;
+}
+export {
+  ArchivaContext,
+  useArchivaContext
+};