@djangocfg/ext-base 1.0.0

package/README.md

@@ -0,0 +1,346 @@
+# @djangocfg/ext-base
+
+Base utilities and common code for building DjangoCFG extensions.
+
+**Part of [DjangoCFG](https://djangocfg.com)** — modern Django framework for production-ready SaaS applications.
+
+## What is this?
+
+`@djangocfg/ext-base` is a foundation library for DjangoCFG extensions. It provides:
+
+- **Extension registration system** - automatic extension metadata tracking
+- **Common React hooks** - pagination, infinite scroll, data fetching patterns
+- **Environment utilities** - isDevelopment, isProduction, isStaticBuild helpers
+- **Type-safe context helpers** - factory functions for creating contexts
+- **Logger utilities** - structured logging with tags
+- **Auth integration** - convenient re-exports of useAuth
+- **TypeScript types** - shared types for all extensions
+
+This package is used internally by all official DjangoCFG extensions (newsletter, payments, support, leads, knowbase) and can be used to build your own custom extensions.
+
+## Install
+
+```bash
+pnpm add @djangocfg/ext-base
+```
+
+## Quick Start
+
+### 1. Create extension metadata
+
+```typescript
+// src/config.ts
+import type { ExtensionMetadata } from '@djangocfg/ext-base';
+
+export const extensionConfig: ExtensionMetadata = {
+  name: 'my-extension',
+  version: '1.0.0',
+  author: 'Your Name',
+  displayName: 'My Extension',
+  description: 'Amazing extension functionality',
+  icon: '🚀',
+  license: 'MIT',
+  keywords: ['extension', 'feature'],
+};
+```
+
+### 2. Create your extension provider
+
+```typescript
+// src/contexts/MyExtensionProvider.tsx
+'use client';
+
+import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
+import { extensionConfig } from '../config';
+
+export function MyExtensionProvider({ children }) {
+  return (
+    <ExtensionProvider metadata={extensionConfig}>
+      {/* Your extension contexts here */}
+      {children}
+    </ExtensionProvider>
+  );
+}
+```
+
+### 3. Use in your app
+
+```typescript
+import { MyExtensionProvider } from '@your-org/my-extension/hooks';
+
+export default function RootLayout({ children }) {
+  return (
+    <MyExtensionProvider>
+      {children}
+    </MyExtensionProvider>
+  );
+}
+```
+
+The extension will automatically register itself and log in development mode:
+```
+[ext-base] Extension registered: My Extension v1.0.0
+```
+
+## Core Features
+
+### Environment Configuration
+
+```typescript
+import { isDevelopment, isProduction, isStaticBuild, isClient, isServer } from '@djangocfg/ext-base';
+
+if (isDevelopment) {
+  console.log('Running in development mode');
+}
+
+if (isStaticBuild) {
+  // Special handling for Next.js static export
+}
+```
+
+### API Factory
+
+Create extension API instances with shared authentication in one line:
+
+```typescript
+// src/api/index.ts
+import { API } from './generated/ext_myextension';
+import { createExtensionAPI } from '@djangocfg/ext-base/api';
+
+// That's it! All configuration is handled automatically:
+// - API URL from environment
+// - Static build detection
+// - Shared authentication storage from @djangocfg/api
+export const apiMyExtension = createExtensionAPI(API);
+```
+
+**Before (manual setup):**
+```typescript
+import { API } from './generated/ext_myextension';
+import { api as accountsApi } from '@djangocfg/api';
+
+const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
+const apiUrl = isStaticBuild ? '' : process.env.NEXT_PUBLIC_API_URL || '';
+const storage = (accountsApi as any)._storage;
+
+export const apiMyExtension = new API(apiUrl, { storage });
+```
+
+**After (with factory):**
+```typescript
+import { API } from './generated/ext_myextension';
+import { createExtensionAPI } from '@djangocfg/ext-base/api';
+
+export const apiMyExtension = createExtensionAPI(API);
+```
+
+### Pagination Hooks
+
+```typescript
+import { usePagination, useInfinitePagination } from '@djangocfg/ext-base/hooks';
+
+// Standard pagination
+const { items, page, pageSize, totalPages, goToPage, nextPage, prevPage } = usePagination({
+  keyPrefix: 'articles',
+  fetcher: async (page, pageSize) => {
+    const response = await api.articles.list({ page, page_size: pageSize });
+    return response.data;
+  },
+  initialPage: 1,
+  pageSize: 20,
+});
+
+// Infinite scroll
+const { items, isLoading, hasMore, loadMore } = useInfinitePagination({
+  keyPrefix: 'articles',
+  fetcher: async (page, pageSize) => {
+    const response = await api.articles.list({ page, page_size: pageSize });
+    return response.data;
+  },
+  pageSize: 20,
+});
+```
+
+### Type-Safe Context Creation
+
+```typescript
+import { createExtensionContext } from '@djangocfg/ext-base/hooks';
+
+interface MyContextValue {
+  data: any[];
+  refresh: () => void;
+}
+
+const { Provider, useContext: useMyContext } = createExtensionContext<MyContextValue>({
+  displayName: 'MyContext',
+  errorMessage: 'useMyContext must be used within MyProvider',
+});
+
+// In components
+export function MyComponent() {
+  const { data, refresh } = useMyContext();
+  return <div>{data.length} items</div>;
+}
+```
+
+### Logger
+
+```typescript
+import { createExtensionLogger } from '@djangocfg/ext-base';
+
+const logger = createExtensionLogger({
+  tag: 'my-extension',
+  level: 'info',
+});
+
+logger.info('Extension initialized');
+logger.error('Something went wrong', error);
+logger.success('Operation completed!');
+```
+
+### Auth Integration
+
+```typescript
+import { useAuth } from '@djangocfg/ext-base/auth';
+
+function MyComponent() {
+  const { user, isAuthenticated, login, logout } = useAuth();
+
+  if (!isAuthenticated) {
+    return <button onClick={login}>Login</button>;
+  }
+
+  return <div>Welcome, {user?.email}</div>;
+}
+```
+
+### Error Handling
+
+```typescript
+import { handleError, formatError } from '@djangocfg/ext-base';
+
+try {
+  await someOperation();
+} catch (error) {
+  handleError(error, (formattedError) => {
+    logger.error('Operation failed:', formattedError);
+  });
+}
+```
+
+## Package Exports
+
+### Main entry (`@djangocfg/ext-base`)
+Server-safe exports - can be used in both client and server components:
+- All TypeScript types
+- Environment configuration (isDevelopment, isProduction, etc.)
+- API factory (createExtensionAPI)
+- Logger utilities
+- Error handling utilities
+
+### Hooks entry (`@djangocfg/ext-base/hooks`)
+Client-only exports:
+- `ExtensionProvider` - main provider component
+- `usePagination` - standard pagination hook
+- `useInfinitePagination` - infinite scroll hook
+- `createExtensionContext` - context factory
+
+### Auth entry (`@djangocfg/ext-base/auth`)
+Auth re-exports:
+- `useAuth` - authentication hook
+- `UserProfile` type
+- `AuthContextType` type
+
+### API entry (`@djangocfg/ext-base/api`)
+API utilities:
+- `createExtensionAPI` - API instance factory
+- `getSharedAuthStorage` - Get shared auth storage
+
+## TypeScript Types
+
+```typescript
+import type {
+  // Extension metadata
+  ExtensionMetadata,
+  ExtensionProviderProps,
+
+  // Pagination
+  PaginatedResponse,
+  PaginationParams,
+  PaginationState,
+  InfinitePaginationReturn,
+
+  // Logger
+  ExtensionLogger,
+  LoggerOptions,
+
+  // Errors
+  ExtensionError,
+  ErrorHandler,
+
+  // Context
+  ExtensionContextOptions,
+} from '@djangocfg/ext-base';
+```
+
+## Example: Complete Extension
+
+```typescript
+// config.ts
+export const extensionConfig: ExtensionMetadata = {
+  name: 'blog',
+  version: '1.0.0',
+  author: 'Your Company',
+  displayName: 'Blog',
+  description: 'Blog management system',
+  icon: '📝',
+  keywords: ['blog', 'articles'],
+};
+
+// contexts/BlogProvider.tsx
+'use client';
+
+import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
+import { useInfinitePagination } from '@djangocfg/ext-base/hooks';
+import { createExtensionLogger } from '@djangocfg/ext-base';
+import { extensionConfig } from '../config';
+
+const logger = createExtensionLogger({ tag: 'blog' });
+
+export function BlogProvider({ children }) {
+  const { items, loadMore, hasMore } = useInfinitePagination({
+    keyPrefix: 'blog-articles',
+    fetcher: async (page, pageSize) => {
+      const response = await api.articles.list({ page, page_size: pageSize });
+      return response.data;
+    },
+  });
+
+  logger.info('Blog provider initialized with', items.length, 'articles');
+
+  return (
+    <ExtensionProvider metadata={extensionConfig}>
+      {/* Your contexts here */}
+      {children}
+    </ExtensionProvider>
+  );
+}
+```
+
+## Best Practices
+
+1. **Always use ExtensionProvider** - Wrap your extension with it for proper registration
+2. **Define metadata** - Create a `config.ts` file with complete metadata
+3. **Use provided hooks** - Leverage `usePagination` and `useInfinitePagination`
+4. **Structured logging** - Use `createExtensionLogger` with consistent tags
+5. **Type safety** - Import types from `@djangocfg/ext-base`
+6. **Separate entry points** - Use `/hooks` for client code, main entry for server-safe code
+
+## License
+
+MIT
+
+## Links
+
+- [DjangoCFG Documentation](https://djangocfg.com)
+- [GitHub](https://github.com/markolofsen/django-cfg)

package/dist/api.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/config/env.ts
+process.env.NODE_ENV === "development";
+process.env.NODE_ENV === "production";
+process.env.NODE_ENV === "test";
+var isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === "true";
+var getApiUrl = () => {
+  return process.env.NEXT_PUBLIC_API_URL || "";
+};
+
+// src/api/createExtensionAPI.ts
+function createExtensionAPI(APIClass) {
+  let storage;
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    storage = accountsApi._storage;
+  } catch (error) {
+    storage = void 0;
+  }
+  const apiUrl = isStaticBuild ? "" : getApiUrl();
+  return new APIClass(apiUrl, storage ? { storage } : void 0);
+}
+function getSharedAuthStorage() {
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    return accountsApi._storage;
+  } catch (error) {
+    return void 0;
+  }
+}
+
+exports.createExtensionAPI = createExtensionAPI;
+exports.getSharedAuthStorage = getSharedAuthStorage;

package/dist/api.d.cts

@@ -0,0 +1,35 @@
+/**
+ * Factory for creating extension API instances
+ *
+ * Provides consistent API setup across all extensions with shared authentication
+ */
+/**
+ * Creates an extension API instance with shared authentication storage
+ *
+ * @param APIClass - The generated API class from your extension
+ * @returns Configured API instance with shared auth storage
+ *
+ * @example
+ * ```typescript
+ * // In your extension's api/index.ts
+ * import { API } from './generated/ext_newsletter';
+ * import { createExtensionAPI } from '@djangocfg/ext-base/api';
+ *
+ * export const apiNewsletter = createExtensionAPI(API);
+ * ```
+ */
+declare function createExtensionAPI<T>(APIClass: new (url: string, options?: any) => T): T;
+/**
+ * Get shared authentication storage from accounts API
+ *
+ * @returns Storage instance or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const storage = getSharedAuthStorage();
+ * const api = new API(apiUrl, { storage });
+ * ```
+ */
+declare function getSharedAuthStorage(): any | undefined;
+
+export { createExtensionAPI, getSharedAuthStorage };

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Factory for creating extension API instances
+ *
+ * Provides consistent API setup across all extensions with shared authentication
+ */
+/**
+ * Creates an extension API instance with shared authentication storage
+ *
+ * @param APIClass - The generated API class from your extension
+ * @returns Configured API instance with shared auth storage
+ *
+ * @example
+ * ```typescript
+ * // In your extension's api/index.ts
+ * import { API } from './generated/ext_newsletter';
+ * import { createExtensionAPI } from '@djangocfg/ext-base/api';
+ *
+ * export const apiNewsletter = createExtensionAPI(API);
+ * ```
+ */
+declare function createExtensionAPI<T>(APIClass: new (url: string, options?: any) => T): T;
+/**
+ * Get shared authentication storage from accounts API
+ *
+ * @returns Storage instance or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const storage = getSharedAuthStorage();
+ * const api = new API(apiUrl, { storage });
+ * ```
+ */
+declare function getSharedAuthStorage(): any | undefined;
+
+export { createExtensionAPI, getSharedAuthStorage };

package/dist/api.js

@@ -0,0 +1,2 @@
+export { createExtensionAPI, getSharedAuthStorage } from './chunk-MECBWZG4.js';
+import './chunk-3RG5ZIWI.js';

package/dist/auth.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+var auth = require('@djangocfg/api/auth');
+
+
+
+Object.defineProperty(exports, "useAuth", {
+  enumerable: true,
+  get: function () { return auth.useAuth; }
+});

package/dist/auth.d.cts

@@ -0,0 +1 @@
+export { AuthContextType, UserProfile, useAuth } from '@djangocfg/api/auth';

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export { AuthContextType, UserProfile, useAuth } from '@djangocfg/api/auth';

package/dist/auth.js

@@ -0,0 +1,2 @@
+import './chunk-3RG5ZIWI.js';
+export { useAuth } from '@djangocfg/api/auth';

package/dist/chunk-3RG5ZIWI.js

@@ -0,0 +1,8 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export { __require };

package/dist/chunk-MECBWZG4.js

@@ -0,0 +1,44 @@
+import { __require } from './chunk-3RG5ZIWI.js';
+
+// src/config/env.ts
+var isDevelopment = process.env.NODE_ENV === "development";
+var isProduction = process.env.NODE_ENV === "production";
+var isTest = process.env.NODE_ENV === "test";
+var isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === "true";
+var isClient = typeof window !== "undefined";
+var isServer = !isClient;
+var getApiUrl = () => {
+  return process.env.NEXT_PUBLIC_API_URL || "";
+};
+var env = {
+  isDevelopment,
+  isProduction,
+  isTest,
+  isStaticBuild,
+  isClient,
+  isServer,
+  getApiUrl
+};
+
+// src/api/createExtensionAPI.ts
+function createExtensionAPI(APIClass) {
+  let storage;
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    storage = accountsApi._storage;
+  } catch (error) {
+    storage = void 0;
+  }
+  const apiUrl = isStaticBuild ? "" : getApiUrl();
+  return new APIClass(apiUrl, storage ? { storage } : void 0);
+}
+function getSharedAuthStorage() {
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    return accountsApi._storage;
+  } catch (error) {
+    return void 0;
+  }
+}
+
+export { createExtensionAPI, env, getApiUrl, getSharedAuthStorage, isClient, isDevelopment, isProduction, isServer, isStaticBuild, isTest };

package/dist/chunk-YQGNYUBX.js

@@ -0,0 +1,67 @@
+import { createConsola } from 'consola';
+
+// src/utils/errors.ts
+function isExtensionError(error) {
+  return typeof error === "object" && error !== null && "message" in error && "timestamp" in error;
+}
+function createExtensionError(error, code, details) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    message,
+    code,
+    details,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function formatErrorMessage(error) {
+  if (isExtensionError(error)) {
+    return error.code ? `[${error.code}] ${error.message}` : error.message;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function handleExtensionError(error, logger, callback) {
+  const extensionError = isExtensionError(error) ? error : createExtensionError(error);
+  if (logger) {
+    logger.error("Extension error:", extensionError);
+  }
+  if (callback) {
+    callback(extensionError);
+  }
+}
+var isDevelopment = process.env.NODE_ENV === "development";
+var LEVEL_MAP = {
+  debug: 4,
+  info: 3,
+  warn: 2,
+  error: 1
+};
+function createExtensionLogger(options) {
+  const { tag, level = "info", enabled = true } = options;
+  if (!enabled) {
+    const noop = () => {
+    };
+    return {
+      info: noop,
+      warn: noop,
+      error: noop,
+      debug: noop,
+      success: noop
+    };
+  }
+  const logLevel = isDevelopment ? LEVEL_MAP[level] : LEVEL_MAP.error;
+  const consola = createConsola({
+    level: logLevel
+  }).withTag(tag);
+  return {
+    info: (...args) => consola.info(...args),
+    warn: (...args) => consola.warn(...args),
+    error: (...args) => consola.error(...args),
+    debug: (...args) => consola.debug(...args),
+    success: (...args) => consola.success(...args)
+  };
+}
+
+export { createExtensionError, createExtensionLogger, formatErrorMessage, handleExtensionError, isExtensionError };