@mohasinac/contracts 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,832 @@
+/** Field comparison operators supported by Sieve-style query strings. */
+type WhereOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "array-contains" | "in" | "not-in" | "array-contains-any";
+/**
+ * Provider-agnostic query descriptor.
+ * `filters` uses Sieve syntax: "field==value,field2>value2"
+ * DB adapters translate this into native query predicates.
+ */
+interface SieveQuery {
+    /** Sieve filter string, e.g. "status==published,price>100" */
+    filters?: string;
+    /** Field name to sort by */
+    sort?: string;
+    /** Sort direction (default: "asc") */
+    order?: "asc" | "desc";
+    /** 1-based page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 20) */
+    perPage?: number;
+}
+/** Paginated result envelope returned by IReadRepository.findAll() */
+interface PagedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+}
+interface IReadRepository<T> {
+    findById(id: string): Promise<T | null>;
+    findAll(query?: SieveQuery): Promise<PagedResult<T>>;
+    findWhere(field: keyof T, op: WhereOp, value: unknown): Promise<T[]>;
+}
+interface IWriteRepository<T> {
+    create(data: Omit<T, "id" | "createdAt" | "updatedAt">): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<T>;
+    delete(id: string): Promise<void>;
+    batchCreate(items: Array<Omit<T, "id" | "createdAt" | "updatedAt">>): Promise<T[]>;
+    batchDelete(ids: string[]): Promise<void>;
+}
+/** Full CRUD repository — combines read + write. */
+interface IRepository<T> extends IReadRepository<T>, IWriteRepository<T> {
+}
+/**
+ * Repository with real-time subscription support (e.g. Firestore RTDB).
+ * Returns an unsubscribe function from both subscribe methods.
+ */
+interface IRealtimeRepository<T> extends IRepository<T> {
+    subscribe(id: string, cb: (data: T | null) => void): () => void;
+    subscribeWhere(field: keyof T, value: unknown, cb: (items: T[]) => void): () => void;
+}
+/**
+ * Database provider — creates IRepository<T> instances on demand.
+ * Registered once in providers.config.ts; feature packages call
+ * `getProviders().db.getRepository<T>(collection)` so they never
+ * import a concrete adapter (FirebaseRepository, PrismaRepository, …).
+ */
+interface IDbProvider {
+    getRepository<T>(collection: string): IRepository<T>;
+}
+
+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>;
+}
+interface AuthUser {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+    role: string;
+    emailVerified: boolean;
+    disabled: boolean;
+    createdAt: string;
+}
+interface CreateUserInput {
+    email: string;
+    password?: string;
+    displayName?: string;
+    photoURL?: string;
+    role?: string;
+    emailVerified?: boolean;
+}
+/**
+ * Server-side authentication operations.
+ * Implemented by @mohasinac/auth-firebase, @mohasinac/auth-nextauth, @mohasinac/auth-clerk.
+ */
+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.
+ */
+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>;
+}
+
+interface EmailAttachment {
+    filename: string;
+    content: Buffer | string;
+    contentType?: string;
+}
+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>;
+}
+interface EmailResult {
+    id: string;
+    accepted: string[];
+    rejected: string[];
+}
+/**
+ * Transactional email sending contract.
+ * Implemented by @mohasinac/email-resend, @mohasinac/email-nodemailer,
+ * @mohasinac/email-sendgrid, @mohasinac/email-postmark.
+ */
+interface IEmailProvider {
+    send(options: EmailOptions): Promise<EmailResult>;
+    sendBatch(options: EmailOptions[]): Promise<EmailResult[]>;
+}
+
+interface UploadOptions {
+    contentType?: string;
+    cacheControl?: string;
+    /** Make the file publicly accessible (default: true) */
+    isPublic?: boolean;
+    metadata?: Record<string, string>;
+}
+interface StorageFile {
+    path: string;
+    url: string;
+    contentType: string;
+    size: number;
+    updatedAt: string;
+}
+/**
+ * File storage adapter contract.
+ * Implemented by @mohasinac/storage-firebase, @mohasinac/storage-s3,
+ * @mohasinac/storage-cloudinary, @mohasinac/storage-uploadthing.
+ */
+interface IStorageProvider {
+    upload(file: Buffer, path: string, options?: UploadOptions): Promise<StorageFile>;
+    delete(path: string): Promise<void>;
+    getPublicUrl(path: string): string;
+    getSignedUrl(path: string, expiresInSeconds?: number): Promise<string>;
+    copy(from: string, to: string): Promise<StorageFile>;
+    list(prefix: string): Promise<StorageFile[]>;
+}
+
+interface PaymentOrder {
+    id: string;
+    amount: number;
+    currency: string;
+    status: "created" | "attempted" | "paid" | "failed";
+    receipt?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+interface PaymentCapture {
+    id: string;
+    orderId: string;
+    amount: number;
+    currency: string;
+    status: "captured" | "failed";
+    capturedAt: string;
+}
+interface Refund {
+    id: string;
+    paymentId: string;
+    amount: number;
+    currency: string;
+    status: "pending" | "processed" | "failed";
+    reason?: string;
+    createdAt: string;
+}
+/**
+ * Payment gateway adapter contract.
+ * Implemented by @mohasinac/payment-razorpay, @mohasinac/payment-stripe,
+ * @mohasinac/payment-braintree.
+ */
+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>;
+}
+
+interface ShippingAddress {
+    name: string;
+    phone: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    state: string;
+    pincode: string;
+    country: string;
+}
+interface CreateShipmentInput {
+    orderId: string;
+    dimensions: {
+        weight: number;
+        length: number;
+        width: number;
+        height: number;
+    };
+    pickup: ShippingAddress;
+    delivery: ShippingAddress;
+    codAmount?: number;
+    isCod?: boolean;
+}
+interface Shipment {
+    id: string;
+    trackingId: string;
+    orderId: string;
+    status: string;
+    courier?: string;
+    estimatedDelivery?: string;
+    createdAt: string;
+}
+interface TrackingEvent {
+    status: string;
+    location: string;
+    timestamp: string;
+    description?: string;
+}
+interface TrackingInfo {
+    trackingId: string;
+    currentStatus: string;
+    estimatedDelivery?: string;
+    events: TrackingEvent[];
+}
+interface ServiceabilityResult {
+    isServiceable: boolean;
+    couriers: Array<{
+        name: string;
+        estimatedDays: number;
+        rate: number;
+    }>;
+}
+/**
+ * Shipping carrier adapter contract.
+ * Implemented by @mohasinac/shipping-shiprocket, @mohasinac/shipping-shippo,
+ * @mohasinac/shipping-easypost.
+ */
+interface IShippingProvider {
+    createShipment(data: CreateShipmentInput): Promise<Shipment>;
+    trackShipment(trackingId: string): Promise<TrackingInfo>;
+    cancelShipment(shipmentId: string): Promise<void>;
+    checkServiceability(pincode: string, weight: number): Promise<ServiceabilityResult>;
+    generateLabel(shipmentId: string): Promise<ArrayBuffer>;
+}
+
+interface SearchOptions {
+    page?: number;
+    perPage?: number;
+    filters?: string;
+    facets?: string[];
+    sortBy?: string;
+    /** Attributes to include in the result (default: all) */
+    attributesToRetrieve?: string[];
+    /** Attributes to highlight in results */
+    attributesToHighlight?: string[];
+}
+interface SearchHit<T> {
+    id: string;
+    data: T;
+    score?: number;
+    highlights?: Record<string, string>;
+}
+interface SearchResult<T> {
+    hits: SearchHit<T>[];
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+    processingTimeMs?: number;
+    facets?: Record<string, Record<string, number>>;
+}
+interface SuggestOptions {
+    limit?: number;
+    filters?: string;
+}
+/**
+ * Full-text search adapter contract.
+ * Implemented by @mohasinac/search-algolia, @mohasinac/search-typesense,
+ * @mohasinac/search-meilisearch.
+ */
+interface ISearchProvider<T = Record<string, unknown>> {
+    index(id: string, data: T): Promise<void>;
+    indexBatch(items: Array<{
+        id: string;
+        data: T;
+    }>): Promise<void>;
+    remove(id: string): Promise<void>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult<T>>;
+    suggest(query: string, options?: SuggestOptions): Promise<string[]>;
+}
+
+/**
+ * Key-value cache adapter contract.
+ * Implemented by @mohasinac/core (in-memory), Redis, Upstash.
+ */
+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>;
+}
+interface QueueJob<T = unknown> {
+    id: string;
+    type: string;
+    payload: T;
+    attempts: number;
+    maxAttempts: number;
+    scheduledAt: string;
+}
+/**
+ * Background job queue adapter contract.
+ * Implemented by @mohasinac/core (in-memory), BullMQ, Upstash QStash.
+ */
+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>;
+}
+type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
+/**
+ * In-process event bus contract.
+ * Implemented by @mohasinac/core (EventEmitter-based).
+ */
+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;
+}
+
+/**
+ * CSS framework adapter contract.
+ * UI components call cn()/token() through this adapter, making them
+ * CSS-framework-agnostic.
+ *
+ * Implemented by:
+ *   @mohasinac/css-tailwind  — twMerge + clsx
+ *   @mohasinac/css-vanilla   — plain string join
+ *   @mohasinac/css-emotion   — Emotion cx()
+ *   @mohasinac/css-modules   — CSS Modules
+ */
+interface IStyleAdapter {
+    /**
+     * Merges and deduplicates class names.
+     * Equivalent to twMerge(clsx(...)) in Tailwind projects.
+     */
+    cn(...classes: Array<string | undefined | null | false>): string;
+    /**
+     * Resolves a design token name to a CSS custom property reference.
+     * e.g. token("color-primary") → "var(--lir-color-primary)"
+     */
+    token(name: string): string;
+}
+
+/**
+ * The single DI container. Populated once at app startup via registerProviders().
+ * Feature packages access concrete implementations via getProviders() — they
+ * never import a concrete provider directly (Dependency Inversion Principle).
+ */
+interface ProviderRegistry {
+    auth: IAuthProvider;
+    session: ISessionProvider;
+    email: IEmailProvider;
+    storage: IStorageProvider;
+    style: IStyleAdapter;
+    /** Optional — database provider; enables true 2-line API route stubs in feat-* packages */
+    db?: IDbProvider;
+    /** Optional — only required for projects with payment flows */
+    payment?: IPaymentProvider;
+    /** Optional — only required for projects with order shipping */
+    shipping?: IShippingProvider;
+    /** Optional — only required for projects with full-text search */
+    search?: ISearchProvider;
+    /** Optional — falls back to in-memory cache if not provided */
+    cache?: ICacheProvider;
+    /** Optional — falls back to in-memory queue if not provided */
+    queue?: IQueueProvider;
+    /** Optional — falls back to EventEmitter if not provided */
+    eventBus?: IEventBus;
+}
+/**
+ * Call once at app startup (e.g. in providers.config.ts).
+ * Subsequent calls replace the registry — useful in tests.
+ */
+declare function registerProviders(registry: ProviderRegistry): void;
+/**
+ * Returns the registry. Throws if registerProviders() has not been called.
+ * Feature packages call this to resolve concrete implementations.
+ */
+declare function getProviders(): ProviderRegistry;
+/**
+ * Resets the registry — only for use in test environments.
+ * @internal
+ */
+declare function _resetProviders(): void;
+
+/**
+ * Describes a page route stub that the CLI generates when `add <feature>` is run.
+ */
+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.
+ */
+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.
+ */
+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[];
+}
+/**
+ * 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;
+ * ```
+ */
+type FeaturesConfig = Record<string, boolean>;
+
+/**
+ * Brand configuration injected into layout/nav shell components.
+ * Passed as the `config` prop to NavbarLayout, FooterLayout, etc.
+ */
+interface SiteConfig {
+    name: string;
+    tagline?: string;
+    description: string;
+    /** Canonical base URL, e.g. "https://letitrip.in" */
+    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[];
+}
+/**
+ * A single nav item passed to NavbarLayout / Sidebar / BottomNavbar.
+ */
+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;
+}
+
+/**
+ * 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 "@mohasinac/contracts";
+ * 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.
+ */
+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.
+ */
+interface GenericListResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize?: number;
+    perPage?: number;
+    totalPages: number;
+    hasMore?: boolean;
+}
+/**
+ * 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 },
+ * ];
+ */
+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;
+}
+/**
+ * Options accepted by every feature's `buildXxxColumns<T>()` factory.
+ * Allows apps to override individual column renderers and/or append extras.
+ */
+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[];
+}
+/**
+ * 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} /> }}
+ * />
+ */
+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;
+}
+/**
+ * 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 "@mohasinac/contracts";
+ * 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 ?? "" }),
+ * };
+ * ```
+ */
+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>;
+}
+
+/**
+ * Table, pagination and sticky-header configuration types.
+ *
+ * Every table/list view in every feat-* package accepts these config objects.
+ * Apps can spread-merge over the exported defaults to override only what they need:
+ *
+ * @example
+ * // App-level base config (one file, reused everywhere)
+ * import { DEFAULT_TABLE_CONFIG, DEFAULT_PAGINATION_CONFIG } from "@mohasinac/contracts";
+ *
+ * export const myTableConfig: TableConfig = {
+ *   ...DEFAULT_TABLE_CONFIG,
+ *   pageSize: 10,
+ *   showViewToggle: true,
+ * };
+ *
+ * export const myPaginationConfig: PaginationConfig = {
+ *   ...DEFAULT_PAGINATION_CONFIG,
+ *   perPage: 10,
+ *   showPageSizeSelector: true,
+ *   pageSizeOptions: [10, 25, 50],
+ * };
+ *
+ * // In a component
+ * <DataTable tableConfig={myTableConfig} paginationConfig={myPaginationConfig} ... />
+ *
+ * // In a hook
+ * const { products } = useProducts(params, { paginationConfig: myPaginationConfig });
+ */
+/**
+ * Composable pagination configuration.
+ * All fields are optional so apps can spread-merge over the defaults.
+ */
+interface PaginationConfig {
+    /** Items per page sent to the API. Default: 20 */
+    perPage?: number;
+    /** Hard cap on perPage (for page-size selector). Default: 100 */
+    maxPerPage?: number;
+    /** Show a page-size selector UI element. Default: false */
+    showPageSizeSelector?: boolean;
+    /** Options for the page-size selector. Default: [10, 20, 50, 100] */
+    pageSizeOptions?: number[];
+    /** Show first / last page buttons. Default: true */
+    showFirstLast?: boolean;
+    /** Show previous / next buttons. Default: true */
+    showPrevNext?: boolean;
+    /** Max visible page number buttons before ellipsis. Default: 7 */
+    maxVisible?: number;
+    /** Size variant for pagination button sizing. Default: "md" */
+    size?: "sm" | "md" | "lg";
+}
+declare const DEFAULT_PAGINATION_CONFIG: Required<PaginationConfig>;
+/**
+ * Sticky header configuration for data tables.
+ * When `enabled` is true the thead is pinned while the tbody scrolls.
+ */
+interface StickyConfig {
+    /** Pin the header while the body scrolls. Default: false */
+    enabled?: boolean;
+    /** Tailwind `top-*` class applied to the sticky thead. Default: "top-0" */
+    topOffset?: string;
+    /** Max height of the scrollable container. Default: "600px" */
+    maxHeight?: string;
+    /** z-index of the sticky header. Default: 10 */
+    zIndex?: number;
+}
+declare const DEFAULT_STICKY_CONFIG: Required<StickyConfig>;
+/** View mode options for DataTable. */
+type TableViewMode = "table" | "grid" | "list";
+/**
+ * Composable table configuration.
+ * Pass a Partial<TableConfig> to any DataTable / admin-list hook; values are
+ * deep-merged with DEFAULT_TABLE_CONFIG at the use site.
+ */
+interface TableConfig {
+    /** Items shown per page (internal pagination). Default: 20 */
+    pageSize?: number;
+    /** Sticky header behaviour. Default: disabled */
+    sticky?: StickyConfig;
+    /** Alternate row background colour. Default: false */
+    striped?: boolean;
+    /** Enable row checkbox selection. Default: false */
+    selectable?: boolean;
+    /** Show view-mode toggle (table / grid / list). Default: false */
+    showViewToggle?: boolean;
+    /** Default view mode. Default: "table" */
+    defaultViewMode?: TableViewMode;
+    /** Pagination widget configuration. */
+    pagination?: PaginationConfig;
+}
+declare const DEFAULT_TABLE_CONFIG: {
+    pageSize: number;
+    sticky: Required<StickyConfig>;
+    striped: boolean;
+    selectable: boolean;
+    showViewToggle: boolean;
+    defaultViewMode: TableViewMode;
+    pagination: Required<PaginationConfig>;
+};
+/**
+ * Utility: merge a Partial<TableConfig> over the defaults.
+ * Performs a shallow merge at the top level and deep merge for nested objects.
+ */
+declare function mergeTableConfig(override?: Partial<TableConfig>): typeof DEFAULT_TABLE_CONFIG;
+
+export { type ApiRouteStub, type AuthPayload, type AuthUser, type ColumnExtensionOpts, type CreateShipmentInput, type CreateUserInput, DEFAULT_PAGINATION_CONFIG, DEFAULT_STICKY_CONFIG, DEFAULT_TABLE_CONFIG, type EmailAttachment, type EmailOptions, type EmailResult, type EventHandler, type FeatureExtension, type FeatureManifest, type FeaturesConfig, type GenericListResponse, type IAuthProvider, type ICacheProvider, type IDbProvider, type IEmailProvider, type IEventBus, type IPaymentProvider, type IQueueProvider, type IReadRepository, type IRealtimeRepository, type IRepository, type ISearchProvider, type ISessionProvider, type IShippingProvider, type IStorageProvider, type IStyleAdapter, type IWriteRepository, type LayoutSlots, type NavItem, type PagedResult, type PaginationConfig, type PaymentCapture, type PaymentOrder, type ProviderRegistry, type QueueJob, type Refund, type RouteStub, type SearchHit, type SearchOptions, type SearchResult, type ServiceabilityResult, type Shipment, type ShippingAddress, type SieveQuery, type SiteConfig, type StickyConfig, type StorageFile, type SuggestOptions, type TableColumn, type TableConfig, type TableViewMode, type TrackingEvent, type TrackingInfo, type UploadOptions, type WhereOp, type WithTransformOpts, _resetProviders, getProviders, mergeTableConfig, registerProviders };