@mohasinac/appkit 2.1.3 → 2.3.0

package/src/contracts/auth.ts

@@ -1,63 +0,0 @@
-// ─── Auth Shared Types ────────────────────────────────────────────────────────
-
-export interface AuthPayload {
-  uid: string;
-  email: string | null;
-  /** Application-level role string, e.g. "admin" | "seller" | "user" */
-  role: string;
-  emailVerified: boolean;
-  /** Any extra custom claims stored on the token */
-  claims?: Record<string, unknown>;
-}
-
-export interface AuthUser {
-  uid: string;
-  email: string | null;
-  displayName: string | null;
-  photoURL: string | null;
-  role: string;
-  emailVerified: boolean;
-  disabled: boolean;
-  createdAt: string; // ISO-8601
-}
-
-export interface CreateUserInput {
-  email: string;
-  password?: string;
-  displayName?: string;
-  photoURL?: string;
-  role?: string;
-  emailVerified?: boolean;
-}
-
-// ─── Auth Interfaces ──────────────────────────────────────────────────────────
-
-/**
- * Server-side authentication operations.
- * Implemented by @mohasinac/auth-firebase, @mohasinac/auth-nextauth, @mohasinac/auth-clerk.
- */
-export interface IAuthProvider {
-  verifyToken(token: string): Promise<AuthPayload>;
-  createCustomToken(
-    uid: string,
-    claims?: Record<string, unknown>,
-  ): Promise<string>;
-  getUser(uid: string): Promise<AuthUser | null>;
-  createUser(data: CreateUserInput): Promise<AuthUser>;
-  updateUser(uid: string, data: Partial<CreateUserInput>): Promise<AuthUser>;
-  deleteUser(uid: string): Promise<void>;
-  revokeTokens(uid: string): Promise<void>;
-}
-
-/**
- * Session cookie management (HTTP-only, server-side).
- * Implemented alongside IAuthProvider by the same auth package.
- */
-export interface ISessionProvider {
-  /** Creates a session cookie value from a verified auth payload. */
-  createSession(payload: AuthPayload): Promise<string>;
-  /** Verifies a session cookie and returns the auth payload. */
-  verifySession(cookie: string): Promise<AuthPayload>;
-  /** Invalidates a session cookie. */
-  destroySession(cookie: string): Promise<void>;
-}

package/src/contracts/config.ts

@@ -1,58 +0,0 @@
-// ─── Site Config ─────────────────────────────────────────────────────────────
-
-/**
- * Brand configuration injected into layout/nav shell components.
- * Passed as the `config` prop to NavbarLayout, FooterLayout, etc.
- */
-export interface SiteConfig {
-  name: string;
-  tagline?: string;
-  description: string;
-  /** Canonical base URL, e.g. "https://example.com" */
-  url: string;
-  logoUrl: string;
-  logoAlt?: string;
-  email: {
-    /** Address used as the "from" field in transactional emails */
-    fromAddress: string;
-    supportAddress: string;
-  };
-  phone?: string;
-  address?: string;
-  social?: {
-    twitter?: string;
-    instagram?: string;
-    facebook?: string;
-    youtube?: string;
-    linkedin?: string;
-    whatsapp?: string;
-  };
-  /** ISO 4217 currency code used site-wide, e.g. "INR" */
-  currency?: string;
-  /** BCP 47 locale tag for default locale, e.g. "en" */
-  defaultLocale?: string;
-  /** Supported locales */
-  locales?: string[];
-}
-
-// ─── Navigation ───────────────────────────────────────────────────────────────
-
-/**
- * A single nav item passed to NavbarLayout / Sidebar / BottomNavbar.
- */
-export interface NavItem {
-  /** Display label (translation key or literal string) */
-  label: string;
-  /** Route href */
-  href: string;
-  /** Icon name / component key */
-  icon?: string;
-  /** Nested items for dropdown / accordion menus */
-  children?: NavItem[];
-  /** If true, item is only shown to admin users */
-  adminOnly?: boolean;
-  /** If true, item is only shown when the user is authenticated */
-  authOnly?: boolean;
-  /** Open link in a new tab */
-  external?: boolean;
-}

package/src/contracts/email.ts

@@ -1,37 +0,0 @@
-// ─── Email Shared Types ───────────────────────────────────────────────────────
-
-export interface EmailAttachment {
-  filename: string;
-  content: Buffer | string;
-  contentType?: string;
-}
-
-export interface EmailOptions {
-  to: string | string[];
-  subject: string;
-  html: string;
-  text?: string;
-  /** Defaults to SiteConfig.email.fromAddress if omitted. */
-  from?: string;
-  replyTo?: string;
-  attachments?: EmailAttachment[];
-  headers?: Record<string, string>;
-}
-
-export interface EmailResult {
-  id: string;
-  accepted: string[];
-  rejected: string[];
-}
-
-// ─── Email Interface ──────────────────────────────────────────────────────────
-
-/**
- * Transactional email sending contract.
- * Implemented by @mohasinac/email-resend, @mohasinac/email-nodemailer,
- * @mohasinac/email-sendgrid, @mohasinac/email-postmark.
- */
-export interface IEmailProvider {
-  send(options: EmailOptions): Promise<EmailResult>;
-  sendBatch(options: EmailOptions[]): Promise<EmailResult[]>;
-}

package/src/contracts/extend.ts

@@ -1,195 +0,0 @@
-/**
- * Utility types for schema/type extensibility across feat-* packages.
- *
- * ## Three-layer extensibility model
- *
- * Every feat-* package exports:
- *   1. **Schema**   — a base Zod object (`xxxSchema`). Extend with `.extend({...})`.
- *   2. **Columns**  — a `xxxAdminColumns` array + `buildXxxColumns()` factory.
- *   3. **Slots**    — render-prop overrides accepted by all list/detail views.
- *
- * Assemble all three into a single `FeatureExtension` descriptor and pass it
- * to the hook AND the view component:
- *
- * @example
- * ```ts
- * // 1. Declare the extension (one file per feature in your app)
- * import { productItemSchema, buildProductColumns } from "@mohasinac/feat-products";
- * import type { FeatureExtension } from "./";
- * import type { ProductItem } from "@mohasinac/feat-products";
- * import { z } from "zod";
- *
- * interface ProductDocument extends ProductItem { brand: string }
- *
- * export const productExt: FeatureExtension<ProductItem, ProductDocument> = {
- *   schema: productItemSchema.extend({ brand: z.string() }),
- *   columns: buildProductColumns<ProductDocument>({
- *     extras: [{ key: "brand", header: "Brand", render: (p) => p.brand }],
- *   }),
- *   slots: { renderCard: (p) => <MyBrandCard product={p} /> },
- *   transform: (raw) => ({ ...raw, brand: raw.attributes?.brand ?? "" }),
- * };
- *
- * // 2. Hook
- * const { products } = useProducts<ProductDocument>(params, productExt);
- *
- * // 3. View
- * <ProductGrid products={products} {...productExt.slots} />
- * ```
- */
-
-/**
- * Options mixin for hooks that support an optional per-item transform.
- * The transform maps the API's base type to a richer app-level type.
- */
-export interface WithTransformOpts<Base, Target extends Base = Base> {
-  /**
-   * Map each API item (BaseType) to a richer app-level type (Target).
-   * Called once per item after the query resolves.
-   */
-  transform?: (item: Base) => Target;
-}
-
-/**
- * Convenience helper: build a response type for list endpoints that mirrors
- * the package's standard list-response shape but with a generic item type.
- */
-export interface GenericListResponse<T> {
-  items: T[];
-  total: number;
-  page: number;
-  pageSize?: number;
-  perPage?: number;
-  totalPages: number;
-  hasMore?: boolean;
-}
-
-// ─── Table column type (shared across feat packages) ─────────────────────────
-
-/**
- * A single column definition for data tables.
- * Defined here in contracts so feat-* packages can export default column sets
- * without cross-importing each other.
- *
- * @example
- * // feat-products can export default product columns
- * export const productAdminColumns: TableColumn<ProductItem>[] = [...];
- *
- * // Consumer app extends with their richer type
- * const columns: TableColumn<ProductDocument>[] = [
- *   ...productAdminColumns as TableColumn<ProductDocument>[],
- *   { key: "brand", header: "Brand", render: (p) => p.brand },
- * ];
- */
-export interface TableColumn<T = Record<string, unknown>> {
-  /** Field key (used for sorting, cell lookup) */
-  key: string;
-  /** Column header label */
-  header: string;
-  /** Whether clicking the header fires an onSort callback */
-  sortable?: boolean;
-  /** Custom cell renderer. Return value is rendered as-is (React.ReactNode in JSX context). */
-  render?: (row: T) => unknown;
-  /** Additional className for the `<th>` and `<td>` */
-  className?: string;
-  /** CSS width / Tailwind width class applied to the column. */
-  width?: string;
-  /** Hide this column from the rendered table (keeps it in the array for export) */
-  hidden?: boolean;
-}
-
-// ─── Column extension helper ──────────────────────────────────────────────────
-
-/**
- * Options accepted by every feature's `buildXxxColumns<T>()` factory.
- * Allows apps to override individual column renderers and/or append extras.
- */
-export interface ColumnExtensionOpts<T> {
-  /**
-   * Keyed partial overrides merged into the matching base column.
-   * Only the provided fields are replaced; the rest of the base column is kept.
-   */
-  overrides?: Partial<Record<string, Partial<TableColumn<T>>>>;
-  /** Additional columns appended after the base set. */
-  extras?: TableColumn<T>[];
-  /** Omit columns by key from the final list. */
-  omit?: string[];
-}
-
-// ─── Layout slots ─────────────────────────────────────────────────────────────
-
-/**
- * Render-prop slots accepted by every feature's list/detail view component.
- * Only the slots you provide are used; the rest fall back to the package default.
- *
- * All return types are `unknown` here (no React dep in contracts).
- * In practice each package narrows them to `React.ReactNode`.
- *
- * @example
- * // Override only the card renderer
- * <BlogListView
- *   posts={posts}
- *   slots={{ renderCard: (post) => <FeaturedBlogCard post={post} /> }}
- * />
- */
-export interface LayoutSlots<T> {
-  /** Replace the default card used inside grid/card-list views. */
-  renderCard?: (item: T, index: number) => unknown;
-  /** Replace the default table row (used when the view renders a table). */
-  renderRow?: (item: T, index: number) => unknown;
-  /** Replace the empty-state UI shown when there are no items. */
-  renderEmptyState?: () => unknown;
-  /** Replace the header area (title bar, action buttons, filter summary). */
-  renderHeader?: (meta: { total: number }) => unknown;
-  /** Replace the footer area (pagination, load-more button). */
-  renderFooter?: (meta: { page: number; totalPages: number }) => unknown;
-}
-
-// ─── Unified Feature Extension descriptor ────────────────────────────────────
-
-/**
- * The single object an app passes to customise one feature.
- * Contains schema, columns, layout slots, and item transform — all optional.
- *
- * Every feat-* hook accepts `FeatureExtension` as its second argument (the
- * `opts` parameter).  Every feat-* list view accepts `slots` prop destructured
- * from this object.
- *
- * @typeParam TBase     — The base interface exported by the feat-* package
- *                        (e.g. `ProductItem`, `BlogPost`).
- * @typeParam TExtended — Your app-level interface that extends TBase
- *                        (e.g. `ProductDocument`). Defaults to TBase.
- *
- * @example
- * ```ts
- * import { productItemSchema, buildProductColumns } from "@mohasinac/feat-products";
- * import type { FeatureExtension } from "./";
- * import type { ProductItem } from "@mohasinac/feat-products";
- * import { z } from "zod";
- *
- * interface ProductDocument extends ProductItem { brand: string }
- *
- * export const productExt: FeatureExtension<ProductItem, ProductDocument> = {
- *   schema: productItemSchema.extend({ brand: z.string() }),
- *   columns: buildProductColumns<ProductDocument>({
- *     extras: [{ key: "brand", header: "Brand", render: (p) => p.brand }],
- *   }),
- *   slots: { renderCard: (p) => <MyBrandCard product={p} /> },
- *   transform: (raw) => ({ ...raw, brand: raw.attributes?.brand ?? "" }),
- * };
- * ```
- */
-export interface FeatureExtension<TBase, TExtended extends TBase = TBase>
-  extends WithTransformOpts<TBase, TExtended> {
-  /**
-   * Extended Zod schema. Use the package's base schema with `.extend({...})`.
-   * Typed as `unknown` here so contracts stays Zod-free; at runtime it is a
-   * `ZodObject` or `ZodEffects`.
-   */
-  schema?: unknown;
-  /** Merged admin table columns. Use the package's `buildXxxColumns()` helper. */
-  columns?: TableColumn<TExtended>[];
-  /** Render-prop slot overrides for list/detail view components. */
-  slots?: LayoutSlots<TExtended>;
-}
-

package/src/contracts/feature.ts

@@ -1,60 +0,0 @@
-// ─── Feature Manifest ─────────────────────────────────────────────────────────
-
-/**
- * Describes a page route stub that the CLI generates when `add <feature>` is run.
- */
-export interface RouteStub {
-  /** Next.js route segment, e.g. "[locale]/events" */
-  segment: string;
-  exports: {
-    /** Default export name from the feature package */
-    default: string;
-    /** generateMetadata export name, if applicable */
-    generateMetadata?: string;
-  };
-  /** If true, the CLI wraps the stub in admin-only protection comments */
-  adminOnly?: boolean;
-}
-
-/**
- * Describes an API route stub that the CLI generates.
- */
-export interface ApiRouteStub {
-  /** Next.js route segment, e.g. "api/events/[id]" */
-  segment: string;
-  methods: Array<"GET" | "POST" | "PATCH" | "PUT" | "DELETE">;
-}
-
-/**
- * The contract between a feature package and @mohasinac/cli.
- * Every feat-* package exports a `manifest` object satisfying this interface.
- */
-export interface FeatureManifest {
-  /** Unique feature identifier, matches FeaturesConfig key */
-  name: string;
-  /** next-intl namespace key for this feature's messages */
-  i18nNamespace: string;
-  /** Environment variable keys required by this feature (documentation only) */
-  envKeys: string[];
-  /** Page route stubs generated by CLI on install */
-  routes: RouteStub[];
-  /** API route stubs generated by CLI on install */
-  apiRoutes: ApiRouteStub[];
-}
-
-// ─── Features Config ──────────────────────────────────────────────────────────
-
-/**
- * Shape of features.config.ts in consumer projects.
- * Keys are feature names; values are booleans (enabled/disabled).
- *
- * @example
- * ```ts
- * export default {
- *   auth: true,
- *   events: true,
- *   auctions: false,
- * } satisfies FeaturesConfig;
- * ```
- */
-export type FeaturesConfig = Record<string, boolean>;

package/src/contracts/index.ts

@@ -1,122 +0,0 @@
-// @mohasinac/contracts
-// Pure TypeScript interfaces and shared types — no concrete code.
-// Every other @mohasinac/* package depends on this package.
-
-// Repository
-export type {
-  WhereOp,
-  SieveQuery,
-  PagedResult,
-  IReadRepository,
-  IWriteRepository,
-  IRepository,
-  IRealtimeRepository,
-  IDbProvider,
-} from "./repository";
-
-// Auth
-export type {
-  AuthPayload,
-  AuthUser,
-  CreateUserInput,
-  IAuthProvider,
-  ISessionProvider,
-} from "./auth";
-
-// Email
-export type {
-  EmailAttachment,
-  EmailOptions,
-  EmailResult,
-  IEmailProvider,
-} from "./email";
-
-// Storage
-export type {
-  UploadOptions,
-  StorageFile,
-  IStorageProvider,
-} from "./storage";
-
-// Payment
-export type {
-  PaymentOrder,
-  PaymentCapture,
-  Refund,
-  IPaymentProvider,
-} from "./payment";
-
-// Shipping
-export type {
-  ShippingAddress,
-  CreateShipmentInput,
-  Shipment,
-  TrackingEvent,
-  TrackingInfo,
-  ServiceabilityResult,
-  IShippingProvider,
-} from "./shipping";
-
-// Search
-export type {
-  SearchOptions,
-  SearchHit,
-  SearchResult,
-  SuggestOptions,
-  ISearchProvider,
-} from "./search";
-
-// Infra (Cache, Queue, EventBus)
-export type {
-  ICacheProvider,
-  QueueJob,
-  IQueueProvider,
-  EventHandler,
-  IEventBus,
-} from "./infra";
-
-// Style
-export type { IStyleAdapter } from "./style";
-
-// Registry
-export type { ProviderRegistry } from "./registry";
-export {
-  registerProviders,
-  getProviders,
-  _resetProviders,
-} from "./registry";
-
-// Feature manifest
-export type {
-  RouteStub,
-  ApiRouteStub,
-  FeatureManifest,
-  FeaturesConfig,
-} from "./feature";
-
-// Site config
-export type { SiteConfig, NavItem } from "./config";
-
-// Extensibility utilities
-export type {
-  WithTransformOpts,
-  GenericListResponse,
-  TableColumn,
-  ColumnExtensionOpts,
-  LayoutSlots,
-  FeatureExtension,
-} from "./extend";
-
-// Table / Pagination / Sticky config
-export type {
-  PaginationConfig,
-  StickyConfig,
-  TableConfig,
-  TableViewMode,
-} from "./table";
-export {
-  DEFAULT_PAGINATION_CONFIG,
-  DEFAULT_STICKY_CONFIG,
-  DEFAULT_TABLE_CONFIG,
-  mergeTableConfig,
-} from "./table";

package/src/contracts/infra.ts

@@ -1,50 +0,0 @@
-// ─── Infra Interfaces ─────────────────────────────────────────────────────────
-
-/**
- * Key-value cache adapter contract.
- * Implemented by @mohasinac/core (in-memory), Redis, Upstash.
- */
-export interface ICacheProvider {
-  get<T>(key: string): Promise<T | null>;
-  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
-  delete(key: string): Promise<void>;
-  clear(prefix?: string): Promise<void>;
-  has(key: string): Promise<boolean>;
-}
-
-export interface QueueJob<T = unknown> {
-  id: string;
-  type: string;
-  payload: T;
-  attempts: number;
-  maxAttempts: number;
-  scheduledAt: string; // ISO-8601
-}
-
-/**
- * Background job queue adapter contract.
- * Implemented by @mohasinac/core (in-memory), BullMQ, Upstash QStash.
- */
-export interface IQueueProvider {
-  enqueue<T>(
-    type: string,
-    payload: T,
-    options?: { delayMs?: number; maxAttempts?: number },
-  ): Promise<QueueJob<T>>;
-  process<T>(type: string, handler: (job: QueueJob<T>) => Promise<void>): void;
-  cancel(jobId: string): Promise<void>;
-  getJob<T>(jobId: string): Promise<QueueJob<T> | null>;
-}
-
-export type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
-
-/**
- * In-process event bus contract.
- * Implemented by @mohasinac/core (EventEmitter-based).
- */
-export interface IEventBus {
-  on<T>(event: string, handler: EventHandler<T>): void;
-  off<T>(event: string, handler: EventHandler<T>): void;
-  emit<T>(event: string, payload: T): void;
-  once<T>(event: string, handler: EventHandler<T>): void;
-}

package/src/contracts/payment.ts

@@ -1,50 +0,0 @@
-// ─── Payment Shared Types ─────────────────────────────────────────────────────
-
-export interface PaymentOrder {
-  id: string;
-  amount: number;
-  currency: string;
-  status: "created" | "attempted" | "paid" | "failed";
-  receipt?: string;
-  metadata?: Record<string, unknown>;
-  createdAt: string; // ISO-8601
-}
-
-export interface PaymentCapture {
-  id: string;
-  orderId: string;
-  amount: number;
-  currency: string;
-  status: "captured" | "failed";
-  capturedAt: string; // ISO-8601
-}
-
-export interface Refund {
-  id: string;
-  paymentId: string;
-  amount: number;
-  currency: string;
-  status: "pending" | "processed" | "failed";
-  reason?: string;
-  createdAt: string; // ISO-8601
-}
-
-// ─── Payment Interface ────────────────────────────────────────────────────────
-
-/**
- * Payment gateway adapter contract.
- * Implemented by @mohasinac/payment-razorpay, @mohasinac/payment-stripe,
- * @mohasinac/payment-braintree.
- */
-export interface IPaymentProvider {
-  createOrder(
-    amount: number,
-    currency: string,
-    metadata?: Record<string, unknown>,
-  ): Promise<PaymentOrder>;
-  /** Returns true if the webhook signature is valid. */
-  verifyWebhook(payload: string, signature: string): boolean;
-  capturePayment(orderId: string): Promise<PaymentCapture>;
-  refund(paymentId: string, amount?: number): Promise<Refund>;
-  getOrder(orderId: string): Promise<PaymentOrder>;
-}

package/src/contracts/registry.ts

@@ -1,44 +0,0 @@
-import type { IAuthProvider, ISessionProvider } from "./auth";
-import type { IEmailProvider } from "./email";
-import type { IStorageProvider } from "./storage";
-import type { IPaymentProvider } from "./payment";
-import type { IShippingProvider } from "./shipping";
-import type { ISearchProvider } from "./search";
-import type { ICacheProvider, IQueueProvider, IEventBus } from "./infra";
-import type { IStyleAdapter } from "./style";
-import type { IDbProvider } from "./repository";
-
-export interface ProviderRegistry {
-  auth: IAuthProvider;
-  session: ISessionProvider;
-  email: IEmailProvider;
-  storage: IStorageProvider;
-  style: IStyleAdapter;
-  db?: IDbProvider;
-  payment?: IPaymentProvider;
-  shipping?: IShippingProvider;
-  search?: ISearchProvider;
-  cache?: ICacheProvider;
-  queue?: IQueueProvider;
-  eventBus?: IEventBus;
-}
-
-let _registry: ProviderRegistry | null = null;
-
-export function registerProviders(registry: ProviderRegistry): void {
-  _registry = registry;
-}
-
-export function getProviders(): ProviderRegistry {
-  if (!_registry) {
-    throw new Error(
-      "[contracts] Call registerProviders() before getProviders(). " +
-        "Ensure providers.config.ts is imported at app startup.",
-    );
-  }
-  return _registry;
-}
-
-export function _resetProviders(): void {
-  _registry = null;
-}