@marianmeres/collection-types 1.7.0 → 1.8.1

package/dist/customer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Customer and Address type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { CustomerData, AddressData } from "@marianmeres/collection-types";
+ * type CustomerModel = Model<CustomerData>;
+ * type AddressModel = Model<AddressData>;
+ * ```
+ */
+/** Customer data field schema */
+export interface CustomerData {
+    /** Customer email */
+    email: string;
+    /** Customer display name */
+    name: string;
+    /** Phone number */
+    phone?: string;
+    /** True if customer has no linked account */
+    guest: boolean;
+    /** Marketing consent */
+    accepts_marketing: boolean;
+    /** Index signature for compatibility with UserData */
+    [key: string]: unknown;
+}
+/** Address data field schema */
+export interface AddressData {
+    /** User-friendly label (e.g., "Home", "Work") */
+    label?: string;
+    /** Recipient name */
+    name: string;
+    /** Street address */
+    street: string;
+    /** City */
+    city: string;
+    /** Postal/ZIP code */
+    postal_code: string;
+    /** Country code or name */
+    country: string;
+    /** Contact phone */
+    phone?: string;
+    /** Whether this is the default address for its type */
+    is_default: boolean;
+    /** Index signature for compatibility with UserData */
+    [key: string]: unknown;
+}
+/** Address type identifier (used as model type in collection) */
+export type AddressType = "shipping" | "billing";
+/** Customer type identifier */
+export type CustomerType = "customer";

package/dist/customer.js

@@ -0,0 +1,12 @@
+/**
+ * Customer and Address type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { CustomerData, AddressData } from "@marianmeres/collection-types";
+ * type CustomerModel = Model<CustomerData>;
+ * type AddressModel = Model<AddressData>;
+ * ```
+ */
+export {};

package/dist/external-domain.d.ts

@@ -0,0 +1,55 @@
+/**
+ * External domain metadata for descriptor collections.
+ *
+ * When using weak relations for cross-domain references, the `related_collection_id`
+ * must point to a valid collection (NOT NULL constraint). We create "descriptor
+ * collections" that contain no models but carry metadata about the external domain.
+ *
+ * UI tooling reads this metadata to understand cross-domain references:
+ * - Check `meta.__external_domain__` to identify descriptor collections
+ * - Use `external_domain` and `external_adapter_prefix` to resolve the target
+ * - The actual foreign model_id is stored in `weak_related_id` on the relation
+ *
+ * @example
+ * ```typescript
+ * import type { ExternalDomainMeta } from "@marianmeres/collection-types";
+ *
+ * // Create a descriptor collection
+ * const extAccount = await sc.createIfNotExists({
+ *   path: "_ext_account",
+ *   types: [],  // no models stored
+ *   is_unlisted: true,
+ *   is_readonly: true,
+ *   meta: {
+ *     __external_domain__: true,
+ *     external_domain: "account",
+ *     external_adapter_prefix: "account_",
+ *     external_collection_path: "account",
+ *     description: "Cross-domain reference to stack-account",
+ *   } satisfies ExternalDomainMeta,
+ * });
+ * ```
+ */
+export interface ExternalDomainMeta {
+    /** Marker flag - always true for descriptor collections */
+    __external_domain__: true;
+    /** External domain name (e.g., "account", "customer", "order") */
+    external_domain: string;
+    /** Table prefix of the external adapter (e.g., "account_", "customer_") */
+    external_adapter_prefix: string;
+    /** Collection path in the external domain (e.g., "account", "customer") */
+    external_collection_path: string;
+    /** Human-readable description */
+    description?: string;
+}
+/**
+ * Type guard to check if collection meta indicates an external domain descriptor.
+ *
+ * @example
+ * ```typescript
+ * if (isExternalDomainMeta(collection.meta)) {
+ *   console.log(`External domain: ${collection.meta.external_domain}`);
+ * }
+ * ```
+ */
+export declare function isExternalDomainMeta(meta: unknown): meta is ExternalDomainMeta;

package/dist/external-domain.js

@@ -0,0 +1,16 @@
+/**
+ * Type guard to check if collection meta indicates an external domain descriptor.
+ *
+ * @example
+ * ```typescript
+ * if (isExternalDomainMeta(collection.meta)) {
+ *   console.log(`External domain: ${collection.meta.external_domain}`);
+ * }
+ * ```
+ */
+export function isExternalDomainMeta(meta) {
+    return (typeof meta === "object" &&
+        meta !== null &&
+        "__external_domain__" in meta &&
+        meta.__external_domain__ === true);
+}

package/dist/mod.d.ts

@@ -26,3 +26,8 @@ export * from "./api.js";
 export * from "./asset.js";
 export * from "./linked-assets.js";
 export * from "./adapter.js";
+export * from "./session.js";
+export * from "./customer.js";
+export * from "./order.js";
+export * from "./payment.js";
+export * from "./external-domain.js";

package/dist/mod.js

@@ -33,3 +33,10 @@ export * from "./asset.js";
 export * from "./linked-assets.js";
 // Adapter (database layer)
 export * from "./adapter.js";
+// E-commerce domain types
+export * from "./session.js";
+export * from "./customer.js";
+export * from "./order.js";
+export * from "./payment.js";
+// Cross-domain reference support
+export * from "./external-domain.js";

package/dist/order.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Order type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { OrderData, OrderEventData } from "@marianmeres/collection-types";
+ * type OrderModel = Model<OrderData>;
+ * type OrderEventModel = Model<OrderEventData>;
+ * ```
+ */
+import type { AddressData } from "./customer.js";
+import type { UUID } from "./utils.js";
+/** Order status progression */
+export type OrderStatus = "pending" | "paid" | "processing" | "shipped" | "delivered" | "cancelled";
+/** Single order line item (snapshot at purchase time) */
+export interface OrderLineItem {
+    /** Product model_id for reference */
+    product_id: UUID;
+    /** Product SKU (snapshot) */
+    sku?: string;
+    /** Product name (snapshot) */
+    name: string;
+    /** Unit price at purchase time (snapshot) */
+    price: number;
+    /** Quantity ordered */
+    quantity: number;
+}
+/** Order price totals */
+export interface OrderTotals {
+    /** Sum of line items before tax/shipping/discounts */
+    subtotal: number;
+    /** Tax amount */
+    tax: number;
+    /** Shipping cost */
+    shipping: number;
+    /** Discount amount */
+    discount: number;
+    /** Final total */
+    total: number;
+}
+/** Order data field schema */
+export interface OrderData {
+    /** Current order status */
+    status: OrderStatus;
+    /** Line items (snapshots) */
+    items: OrderLineItem[];
+    /** Currency code (e.g., "EUR", "USD") */
+    currency: string;
+    /** Price totals */
+    totals: OrderTotals;
+    /** Shipping address (embedded snapshot) */
+    shipping_address: AddressData;
+    /** Billing address (embedded snapshot) */
+    billing_address: AddressData;
+    /** Order notes */
+    notes?: string;
+    /** Index signature for compatibility with UserData */
+    [key: string]: unknown;
+}
+/** Order event types for audit trail */
+export type OrderEventType = "created" | "status_changed" | "payment_added" | "note_added" | "cancelled";
+/** Actor who triggered an order event */
+export interface OrderEventActor {
+    /** Actor type */
+    type: "customer" | "admin" | "system";
+    /** Actor ID (account_id or customer_id) */
+    id?: UUID;
+}
+/** Order event data field schema (audit trail) */
+export interface OrderEventData {
+    /** Type of event */
+    event_type: OrderEventType;
+    /** Previous status (for status_changed) */
+    previous_status?: OrderStatus;
+    /** New status (for status_changed) */
+    new_status?: OrderStatus;
+    /** Who triggered the event */
+    actor: OrderEventActor;
+    /** Additional event details */
+    details?: Record<string, unknown>;
+    /** Index signature for compatibility with UserData */
+    [key: string]: unknown;
+}
+/** Order type identifier */
+export type OrderType = "order";
+/** Order event type identifier */
+export type OrderEventModelType = "event";

package/dist/order.js

@@ -0,0 +1,12 @@
+/**
+ * Order type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { OrderData, OrderEventData } from "@marianmeres/collection-types";
+ * type OrderModel = Model<OrderData>;
+ * type OrderEventModel = Model<OrderEventData>;
+ * ```
+ */
+export {};

package/dist/payment.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Payment type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { PaymentData } from "@marianmeres/collection-types";
+ * type PaymentModel = Model<PaymentData>;
+ * ```
+ */
+import type { UUID } from "./utils.js";
+/** Payment status */
+export type PaymentStatus = "pending" | "completed" | "failed" | "refunded";
+/** Payment data field schema */
+export interface PaymentData {
+    /** Payment provider name (e.g., "paypal", "stripe") */
+    provider: string;
+    /** Current payment status */
+    status: PaymentStatus;
+    /** Payment amount */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Provider-specific reference ID */
+    provider_reference: string;
+    /** Raw provider response data */
+    provider_response?: Record<string, unknown>;
+    /** Index signature for compatibility with UserData */
+    [key: string]: unknown;
+}
+/** Payment type identifier */
+export type PaymentType = "payment";
+/** Result of initiating a payment */
+export interface PaymentIntent {
+    /** Internal payment ID */
+    id: UUID;
+    /** URL to redirect customer for payment */
+    redirect_url: string;
+    /** Provider-specific data */
+    provider_data?: Record<string, unknown>;
+}
+/** Result of capturing/completing a payment */
+export interface PaymentResult {
+    /** Whether capture succeeded */
+    success: boolean;
+    /** Provider reference ID */
+    provider_reference: string;
+    /** Error message if failed */
+    error?: string;
+}
+/** Result of a refund operation */
+export interface RefundResult {
+    /** Whether refund succeeded */
+    success: boolean;
+    /** Refund ID from provider */
+    refund_id?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/** Result of processing a webhook */
+export interface WebhookResult {
+    /** Whether webhook was processed successfully */
+    success: boolean;
+    /** Event type from provider */
+    event_type?: string;
+    /** Related payment ID */
+    payment_id?: UUID;
+    /** Error message if failed */
+    error?: string;
+}

package/dist/payment.js

@@ -0,0 +1,11 @@
+/**
+ * Payment type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { PaymentData } from "@marianmeres/collection-types";
+ * type PaymentModel = Model<PaymentData>;
+ * ```
+ */
+export {};

package/dist/session.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Session and Cart type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { SessionData } from "@marianmeres/collection-types";
+ * type SessionModel = Model<SessionData>;
+ * ```
+ */
+import type { UUID } from "./utils.js";
+/** Single cart item */
+export interface CartItem {
+    /** Product model_id reference */
+    product_id: UUID;
+    /** Quantity in cart */
+    quantity: number;
+}
+/** Cart contents */
+export interface CartData {
+    items: CartItem[];
+}
+/** Session data field schema */
+export interface SessionData {
+    cart: CartData;
+    /** Index signature for compatibility with UserData */
+    [key: string]: unknown;
+}
+/** Session type identifier */
+export type SessionType = "session";

package/dist/session.js

@@ -0,0 +1,11 @@
+/**
+ * Session and Cart type definitions for e-commerce.
+ *
+ * Usage with Model:
+ * ```typescript
+ * import type { Model } from "@marianmeres/collection-types";
+ * import type { SessionData } from "@marianmeres/collection-types";
+ * type SessionModel = Model<SessionData>;
+ * ```
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/collection-types",
-	"version": "1.7.0",
+	"version": "1.8.1",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",