@mohasinac/appkit 2.3.0 → 2.3.2

package/dist/contracts/form.d.ts

@@ -0,0 +1,89 @@
+/**
+ * FormFieldRegistry — @mohasinac/appkit/contracts
+ *
+ * Allows consumers to inject extra fields into existing appkit forms without
+ * rebuilding or forking them.
+ *
+ * ## How it works
+ *
+ * 1. Every appkit `*Form` component accepts an optional `extraFields` prop
+ *    typed as `ExtraFormField[]`.
+ * 2. The form renders `extraFields` at a designated slot position (default:
+ *    after the last built-in field, before the submit button).
+ * 3. Consumers may also register fields globally via `registerFormFields()`
+ *    so they are applied to every matching form without prop drilling.
+ *
+ * @example
+ * ```tsx
+ * // In providers.config.ts — register extra fields globally:
+ * import { registerFormFields } from "@mohasinac/appkit/contracts";
+ *
+ * registerFormFields("product", [
+ *   {
+ *     key: "hsn",
+ *     position: "after:price",
+ *     render: ({ value, onChange, disabled }) => (
+ *       <FormField label="HSN Code">
+ *         <input value={value ?? ""} onChange={(e) => onChange(e.target.value)} disabled={disabled} />
+ *       </FormField>
+ *     ),
+ *   },
+ * ]);
+ *
+ * // Or pass directly via prop:
+ * <ProductForm
+ *   product={product}
+ *   onChange={setProduct}
+ *   extraFields={[{ key: "hsn", render: ({ value, onChange }) => <HsnField ... /> }]}
+ * />
+ * ```
+ */
+export interface ExtraFieldRenderArgs<TValue = unknown> {
+    /** Current value for this field key from the parent form state. */
+    value: TValue;
+    /** Call to update this field's value in the parent form state. */
+    onChange: (value: TValue) => void;
+    /** Whether the form is in a read-only / disabled state. */
+    disabled: boolean;
+}
+/**
+ * A single extra field to be injected into an appkit form.
+ *
+ * @typeParam TValue  The type of the field's value. Defaults to `unknown`.
+ */
+export interface ExtraFormField<TValue = unknown> {
+    /**
+     * Unique key for this field — used as the React list key and to look up
+     * the field's value in the form state bag.
+     */
+    key: string;
+    /**
+     * Where to render this field relative to a built-in field.
+     * Format: `"after:<builtInKey>"` | `"before:<builtInKey>"` | `"end"` (default)
+     *
+     * @example "after:price"   — render immediately after the `price` field
+     * @example "before:status" — render immediately before the `status` field
+     * @example "end"           — render after all built-in fields
+     */
+    position?: `after:${string}` | `before:${string}` | "end";
+    /** Render function. Return value is `React.ReactNode` at runtime. */
+    render: (args: ExtraFieldRenderArgs<TValue>) => unknown;
+}
+/**
+ * Register extra fields for a specific form by its form key (e.g. `"product"`,
+ * `"blog"`, `"event"`). Called once in `providers.config.ts`.
+ *
+ * Fields registered here are merged with any `extraFields` passed directly
+ * via props. Props-supplied fields take precedence over registry fields with
+ * the same `key`.
+ */
+export declare function registerFormFields(formKey: string, fields: ExtraFormField[]): void;
+/**
+ * Retrieve registered extra fields for a form, merged with any prop-supplied
+ * fields. Props-supplied fields override registry fields with the same key.
+ */
+export declare function resolveFormFields(formKey: string, propFields?: ExtraFormField[]): ExtraFormField[];
+/** Remove all registered fields for a form key. */
+export declare function removeFormFields(formKey: string): void;
+/** Reset all registered form fields (used in tests). */
+export declare function _resetFormFields(): void;

package/dist/contracts/form.js

@@ -0,0 +1,80 @@
+/**
+ * FormFieldRegistry — @mohasinac/appkit/contracts
+ *
+ * Allows consumers to inject extra fields into existing appkit forms without
+ * rebuilding or forking them.
+ *
+ * ## How it works
+ *
+ * 1. Every appkit `*Form` component accepts an optional `extraFields` prop
+ *    typed as `ExtraFormField[]`.
+ * 2. The form renders `extraFields` at a designated slot position (default:
+ *    after the last built-in field, before the submit button).
+ * 3. Consumers may also register fields globally via `registerFormFields()`
+ *    so they are applied to every matching form without prop drilling.
+ *
+ * @example
+ * ```tsx
+ * // In providers.config.ts — register extra fields globally:
+ * import { registerFormFields } from "@mohasinac/appkit/contracts";
+ *
+ * registerFormFields("product", [
+ *   {
+ *     key: "hsn",
+ *     position: "after:price",
+ *     render: ({ value, onChange, disabled }) => (
+ *       <FormField label="HSN Code">
+ *         <input value={value ?? ""} onChange={(e) => onChange(e.target.value)} disabled={disabled} />
+ *       </FormField>
+ *     ),
+ *   },
+ * ]);
+ *
+ * // Or pass directly via prop:
+ * <ProductForm
+ *   product={product}
+ *   onChange={setProduct}
+ *   extraFields={[{ key: "hsn", render: ({ value, onChange }) => <HsnField ... /> }]}
+ * />
+ * ```
+ */
+// --- Global registry ----------------------------------------------------------
+const _fieldRegistry = new Map();
+/**
+ * Register extra fields for a specific form by its form key (e.g. `"product"`,
+ * `"blog"`, `"event"`). Called once in `providers.config.ts`.
+ *
+ * Fields registered here are merged with any `extraFields` passed directly
+ * via props. Props-supplied fields take precedence over registry fields with
+ * the same `key`.
+ */
+export function registerFormFields(formKey, fields) {
+    const existing = _fieldRegistry.get(formKey) ?? [];
+    // Merge: registry fields + new fields, deduplicated by key (new wins)
+    const merged = [
+        ...existing.filter((f) => !fields.some((nf) => nf.key === f.key)),
+        ...fields,
+    ];
+    _fieldRegistry.set(formKey, merged);
+}
+/**
+ * Retrieve registered extra fields for a form, merged with any prop-supplied
+ * fields. Props-supplied fields override registry fields with the same key.
+ */
+export function resolveFormFields(formKey, propFields) {
+    const registry = _fieldRegistry.get(formKey) ?? [];
+    if (!propFields?.length)
+        return registry;
+    return [
+        ...registry.filter((f) => !propFields.some((pf) => pf.key === f.key)),
+        ...propFields,
+    ];
+}
+/** Remove all registered fields for a form key. */
+export function removeFormFields(formKey) {
+    _fieldRegistry.delete(formKey);
+}
+/** Reset all registered form fields (used in tests). */
+export function _resetFormFields() {
+    _fieldRegistry.clear();
+}

package/dist/contracts/index.d.ts

@@ -0,0 +1,32 @@
+export type { WhereOp, SieveQuery, PagedResult, IReadRepository, IWriteRepository, IRepository, IRealtimeRepository, IDbProvider, } from "./repository";
+export type { AuthPayload, AuthUser, CreateUserInput, IAuthProvider, ISessionProvider, } from "./auth";
+export type { EmailAttachment, EmailOptions, EmailResult, IEmailProvider, } from "./email";
+export type { UploadOptions, StorageFile, IStorageProvider } from "./storage";
+export type { PaymentOrder, PaymentCapture, Refund, IPaymentProvider, } from "./payment";
+export type { ShippingAddress, CreateShipmentInput, Shipment, TrackingEvent, TrackingInfo, ServiceabilityResult, IShippingProvider, } from "./shipping";
+export type { SearchOptions, SearchHit, SearchResult, SuggestOptions, ISearchProvider, } from "./search";
+export type { ICacheProvider, QueueJob, IQueueProvider, EventHandler, IEventBus, } from "./infra";
+export type { IStyleAdapter } from "./style";
+export type { ProviderRegistry } from "./registry";
+export { registerProviders, getProviders, _resetProviders } from "./registry";
+export type { RepositoryLifecycleHooks } from "./repository";
+export { setCollectionHooks, getCollectionHooks, removeCollectionHooks, _resetCollectionHooks, } from "./repository";
+export type { ExtraFormField, ExtraFieldRenderArgs } from "./form";
+export { registerFormFields, resolveFormFields, removeFormFields, _resetFormFields, } from "./form";
+export type { RouteStub, ApiRouteStub, FeatureManifest, FeaturesConfig, } from "./feature";
+export type { SiteConfig, NavItem } from "./config";
+export type { WithTransformOpts, GenericListResponse, TableColumn, ColumnExtensionOpts, LayoutSlots, FeatureExtension, } from "./extend";
+export type { PaginationConfig, StickyConfig, TableConfig, TableViewMode, } from "./table";
+export { DEFAULT_PAGINATION_CONFIG, DEFAULT_STICKY_CONFIG, DEFAULT_TABLE_CONFIG, mergeTableConfig, } from "./table";
+export type { IFieldOps, FieldSentinel } from "./field-ops";
+export { registerFieldOps, serverTimestamp, increment, arrayUnion, arrayRemove, deleteField, } from "./field-ops";
+export type { RealtimeSnapshot, Unsubscribe, IClientRealtimeProvider, } from "./client-realtime";
+export { registerClientRealtimeProvider, getClientRealtimeProvider, } from "./client-realtime";
+export type { IClientAuthProvider } from "./client-auth";
+export { registerClientAuthProvider, getClientAuthProvider, } from "./client-auth";
+export type { AdapterAuthUser, AuthUnsubscribe, IClientSessionAdapter, } from "./client-session";
+export { registerClientSessionAdapter, getClientSessionAdapter, } from "./client-session";
+export type { FilterOption, FilterType, FilterDefinition, SortDefinition, } from "./extend";
+export { mergeFilterDefinitions, mergeSortDefinitions } from "./extend";
+export type { GatewayPaymentResponse, OpenGatewayOptions, IClientPaymentGateway, } from "./client-payment-gateway";
+export { registerClientPaymentGateway, getClientPaymentGateway, getRegisteredPaymentGateways, } from "./client-payment-gateway";

package/dist/contracts/index.js

@@ -0,0 +1,13 @@
+// @mohasinac/contracts
+// Pure TypeScript interfaces and shared types — no concrete code.
+// Every other @mohasinac/* package depends on this package.
+export { registerProviders, getProviders, _resetProviders } from "./registry";
+export { setCollectionHooks, getCollectionHooks, removeCollectionHooks, _resetCollectionHooks, } from "./repository";
+export { registerFormFields, resolveFormFields, removeFormFields, _resetFormFields, } from "./form";
+export { DEFAULT_PAGINATION_CONFIG, DEFAULT_STICKY_CONFIG, DEFAULT_TABLE_CONFIG, mergeTableConfig, } from "./table";
+export { registerFieldOps, serverTimestamp, increment, arrayUnion, arrayRemove, deleteField, } from "./field-ops";
+export { registerClientRealtimeProvider, getClientRealtimeProvider, } from "./client-realtime";
+export { registerClientAuthProvider, getClientAuthProvider, } from "./client-auth";
+export { registerClientSessionAdapter, getClientSessionAdapter, } from "./client-session";
+export { mergeFilterDefinitions, mergeSortDefinitions } from "./extend";
+export { registerClientPaymentGateway, getClientPaymentGateway, getRegisteredPaymentGateways, } from "./client-payment-gateway";

package/dist/contracts/infra.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+}
+/**
+ * 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/dist/contracts/infra.js

@@ -0,0 +1,2 @@
+// --- Infra Interfaces ---------------------------------------------------------
+export {};

package/dist/contracts/payment.d.ts

@@ -0,0 +1,39 @@
+export interface PaymentOrder {
+    id: string;
+    amount: number;
+    currency: string;
+    status: "created" | "attempted" | "paid" | "failed";
+    receipt?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface PaymentCapture {
+    id: string;
+    orderId: string;
+    amount: number;
+    currency: string;
+    status: "captured" | "failed";
+    capturedAt: string;
+}
+export 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.
+ */
+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/dist/contracts/payment.js

@@ -0,0 +1,2 @@
+// --- Payment Shared Types -----------------------------------------------------
+export {};

package/dist/contracts/registry.d.ts

@@ -0,0 +1,26 @@
+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;
+}
+export declare function registerProviders(registry: ProviderRegistry): void;
+export declare function getProviders(): ProviderRegistry;
+export declare function _resetProviders(): void;

package/dist/contracts/registry.js

@@ -0,0 +1,14 @@
+let _registry = null;
+export function registerProviders(registry) {
+    _registry = registry;
+}
+export function getProviders() {
+    if (!_registry) {
+        throw new Error("[contracts] Call registerProviders() before getProviders(). " +
+            "Ensure providers.config.ts is imported at app startup.");
+    }
+    return _registry;
+}
+export function _resetProviders() {
+    _registry = null;
+}

package/dist/contracts/repository.d.ts

@@ -0,0 +1,127 @@
+/** Field comparison operators supported by Sieve-style query strings. */
+export 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.
+ */
+export 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() */
+export interface PagedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+}
+export 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[]>;
+}
+export 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. */
+export 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.
+ */
+export 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, …).
+ */
+export interface IDbProvider {
+    getRepository<T>(collection: string): IRepository<T>;
+}
+/**
+ * Optional lifecycle hooks that can be attached to any `IRepository<T>`.
+ * All hooks are optional. If provided, they are called by the repository
+ * wrapper at the appropriate point in the CRUD lifecycle.
+ *
+ * Register hooks globally via `setRepositoryHooks()` or per-collection via
+ * `setCollectionHooks()`.
+ *
+ * @example
+ * ```ts
+ * // providers.config.ts
+ * import { setRepositoryHooks } from "@mohasinac/appkit/contracts";
+ *
+ * setRepositoryHooks("products", {
+ *   afterRead: (item) => { console.log("read product", item.id); },
+ *   beforeCreate: (data) => ({ ...data, source: "letitrip" }),
+ *   afterUpdate: (item) => myCache.invalidate(`product:${item.id}`),
+ * });
+ * ```
+ */
+export interface RepositoryLifecycleHooks<T> {
+    /**
+     * Called after a successful `findById` or per-item result in `findAll`.
+     * Return value is ignored — use for side-effects only (logging, caching).
+     */
+    afterRead?: (item: T) => void | Promise<void>;
+    /**
+     * Called before `create`. Return the (possibly mutated) data to be persisted.
+     * If not returned, the original data is used unchanged.
+     */
+    beforeCreate?: (data: Omit<T, "id" | "createdAt" | "updatedAt">) => Omit<T, "id" | "createdAt" | "updatedAt"> | Promise<Omit<T, "id" | "createdAt" | "updatedAt">>;
+    /**
+     * Called after a successful `create`. Receives the persisted document.
+     */
+    afterCreate?: (item: T) => void | Promise<void>;
+    /**
+     * Called before `update`. Return the (possibly mutated) partial to be applied.
+     */
+    beforeUpdate?: (id: string, data: Partial<T>) => Partial<T> | Promise<Partial<T>>;
+    /**
+     * Called after a successful `update`. Receives the updated document.
+     */
+    afterUpdate?: (item: T) => void | Promise<void>;
+    /**
+     * Called before `delete`. Return `false` to cancel the deletion.
+     */
+    beforeDelete?: (id: string) => boolean | void | Promise<boolean | void>;
+    /**
+     * Called after a successful `delete`.
+     */
+    afterDelete?: (id: string) => void | Promise<void>;
+}
+/**
+ * Register lifecycle hooks for a specific Firestore collection (or any
+ * collection identifier used by `IDbProvider.getRepository()`).
+ *
+ * @param collection  The collection name (e.g. "products", "orders").
+ * @param hooks       Partial hooks object — only the hooks you provide are applied.
+ */
+export declare function setCollectionHooks<T>(collection: string, hooks: RepositoryLifecycleHooks<T>): void;
+/**
+ * Retrieve registered hooks for a collection, or `undefined` if none are set.
+ */
+export declare function getCollectionHooks<T>(collection: string): RepositoryLifecycleHooks<T> | undefined;
+/** Remove hooks for a collection. */
+export declare function removeCollectionHooks(collection: string): void;
+/** Reset all registered hooks (used in tests). */
+export declare function _resetCollectionHooks(): void;

package/dist/contracts/repository.js

@@ -0,0 +1,28 @@
+// --- Repository Interfaces ----------------------------------------------------
+// Segregated per ISP: features that only read never depend on IWriteRepository.
+// --- Global hooks registry ----------------------------------------------------
+const _hooksRegistry = new Map();
+/**
+ * Register lifecycle hooks for a specific Firestore collection (or any
+ * collection identifier used by `IDbProvider.getRepository()`).
+ *
+ * @param collection  The collection name (e.g. "products", "orders").
+ * @param hooks       Partial hooks object — only the hooks you provide are applied.
+ */
+export function setCollectionHooks(collection, hooks) {
+    _hooksRegistry.set(collection, hooks);
+}
+/**
+ * Retrieve registered hooks for a collection, or `undefined` if none are set.
+ */
+export function getCollectionHooks(collection) {
+    return _hooksRegistry.get(collection);
+}
+/** Remove hooks for a collection. */
+export function removeCollectionHooks(collection) {
+    _hooksRegistry.delete(collection);
+}
+/** Reset all registered hooks (used in tests). */
+export function _resetCollectionHooks() {
+    _hooksRegistry.clear();
+}

package/dist/contracts/search.d.ts

@@ -0,0 +1,44 @@
+export 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[];
+}
+export interface SearchHit<T> {
+    id: string;
+    data: T;
+    score?: number;
+    highlights?: Record<string, string>;
+}
+export interface SearchResult<T> {
+    hits: SearchHit<T>[];
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+    processingTimeMs?: number;
+    facets?: Record<string, Record<string, number>>;
+}
+export interface SuggestOptions {
+    limit?: number;
+    filters?: string;
+}
+/**
+ * Full-text search adapter contract.
+ * Implemented by concrete provider packages (for example, Typesense or Meilisearch).
+ */
+export 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[]>;
+}

package/dist/contracts/search.js

@@ -0,0 +1,2 @@
+// --- Search Shared Types ------------------------------------------------------
+export {};

package/dist/contracts/shipping.d.ts

@@ -0,0 +1,64 @@
+export interface ShippingAddress {
+    name: string;
+    phone: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    state: string;
+    pincode: string;
+    country: string;
+}
+export interface CreateShipmentInput {
+    orderId: string;
+    dimensions: {
+        weight: number;
+        length: number;
+        width: number;
+        height: number;
+    };
+    pickup: ShippingAddress;
+    delivery: ShippingAddress;
+    codAmount?: number;
+    isCod?: boolean;
+}
+export interface Shipment {
+    id: string;
+    trackingId: string;
+    orderId: string;
+    status: string;
+    courier?: string;
+    estimatedDelivery?: string;
+    createdAt: string;
+}
+export interface TrackingEvent {
+    status: string;
+    location: string;
+    timestamp: string;
+    description?: string;
+}
+export interface TrackingInfo {
+    trackingId: string;
+    currentStatus: string;
+    estimatedDelivery?: string;
+    events: TrackingEvent[];
+}
+export 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.
+ */
+export 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>;
+}

package/dist/contracts/shipping.js

@@ -0,0 +1,2 @@
+// --- Shipping Shared Types ----------------------------------------------------
+export {};

package/dist/contracts/storage.d.ts

@@ -0,0 +1,27 @@
+export interface UploadOptions {
+    contentType?: string;
+    cacheControl?: string;
+    /** Make the file publicly accessible (default: true) */
+    isPublic?: boolean;
+    metadata?: Record<string, string>;
+}
+export 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.
+ */
+export 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[]>;
+}

package/dist/contracts/storage.js

@@ -0,0 +1,2 @@
+// --- Storage Shared Types -----------------------------------------------------
+export {};