@xedo/sdk 0.1.0 → 0.2.3

package/dist/index.d.ts

@@ -1,41 +1,823 @@
+interface components {
+    schemas: {
+        DevApiErrorEnvelopeDto: {
+            /** @example false */
+            success: boolean;
+            /**
+             * @description Stable machine-readable error code. Safe to switch on in client code.
+             * @example PRODUCT_NOT_FOUND
+             */
+            code: string;
+            /**
+             * @description Human-readable error message, translated when applicable.
+             * @example Product not found
+             */
+            message: string;
+            /**
+             * @description Field-level validation errors, present when the error stems from input validation.
+             * @example {
+             *       "name": [
+             *         "name should not be empty"
+             *       ]
+             *     }
+             */
+            errors?: Record<string, never>;
+            /**
+             * @description Contextual data attached to the error. For example, a PAYMENT_INIT_FAILED response carries the `cartPublicId` of the created cart so the payment can be retried via POST /v1/carts/{publicId}/pay.
+             * @example {
+             *       "cartPublicId": "CART-XPK39ZQA01"
+             *     }
+             */
+            data?: Record<string, never>;
+        };
+        DevApiSuccessEnvelopeDto: {
+            /** @example true */
+            success: boolean;
+            data: Record<string, never>;
+        };
+        PingPayload: {
+            /** @example 42 */
+            marketplaceId: number;
+            /** @example 2026-05-26T13:14:15.000Z */
+            timestamp: string;
+        };
+        DevApiPaginatedEnvelopeDto: {
+            /** @example true */
+            success: boolean;
+            data: unknown[][];
+            /**
+             * @description Total rows matching the query
+             * @example 42
+             */
+            total: number;
+            /**
+             * @description Index (1-based) of the first row returned
+             * @example 1
+             */
+            start: number;
+            /**
+             * @description Index (1-based) of the last row returned
+             * @example 10
+             */
+            end: number;
+        };
+        DevApiProductCollectionDto: {
+            /** @example Fast food */
+            name: string;
+            /** @example fast-food */
+            slug: string;
+        };
+        DevApiProductGalleryMediaDto: {
+            /** @example 1 */
+            id: number;
+            /** @example https://cdn.xedoapp.com/products/gallery/abc.jpg */
+            publicUrl: string;
+            /**
+             * @example image
+             * @enum {string}
+             */
+            type: "image" | "video";
+            /** @example Burger close-up */
+            altText?: string;
+        };
+        DevApiProductVariationOptionDto: {
+            /** @example OPT_ABC123 */
+            publicId: string;
+            /** @example XL */
+            name: string;
+            /** @example 500 */
+            priceAdjustment?: number;
+            /**
+             * @example fixed
+             * @enum {string}
+             */
+            priceAdjustmentType?: "fixed" | "percentage";
+            galleryMedias: components["schemas"]["DevApiProductGalleryMediaDto"][];
+        };
+        DevApiProductVariationDto: {
+            /** @example VAR_ABC123 */
+            publicId: string;
+            /** @example Taille */
+            variationTypeName: string;
+            options: components["schemas"]["DevApiProductVariationOptionDto"][];
+        };
+        DevApiProductCombinationDto: {
+            /** @example COMB_ABC123 */
+            publicId: string;
+            /**
+             * @description Public ids of the options forming this combination.
+             * @example [
+             *       "OPT_ABC123",
+             *       "OPT_DEF456"
+             *     ]
+             */
+            optionPublicIds: string[];
+            /** @example 10 */
+            stockQuantity: number;
+            /** @example 500 */
+            priceAdjustment?: number;
+            /**
+             * @example fixed
+             * @enum {string}
+             */
+            priceAdjustmentType?: "fixed" | "percentage";
+        };
+        DevApiProductDto: {
+            /** @example 6528412905 */
+            publicId: string;
+            /** @example Burger */
+            name: string;
+            /** @example burger */
+            slug: string;
+            /** @example 10.5 */
+            price: number;
+            /** @example Delicious beef burger. */
+            description?: string;
+            /** @example https://cdn.xedoapp.com/products/cover/abc.jpg */
+            coverUrl?: string | null;
+            /** @example true */
+            enabled: boolean;
+            collection: components["schemas"]["DevApiProductCollectionDto"];
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            updatedAt: string;
+            /** @example Nutritional information */
+            productSheet?: string;
+            /** @example 100 */
+            stockQuantity: number;
+            /** @example true */
+            trackStock: boolean;
+            /** @example false */
+            allowBackorder: boolean;
+            /** @example 10 */
+            lowStockThreshold?: number | null;
+            /**
+             * @description Percentage paid online for split payment. Null falls back to the marketplace default.
+             * @example 30
+             */
+            splitOnlinePaymentPercentage?: number | null;
+            /** @description Product gallery (image / video). Returned on detail endpoints. */
+            galleryMedias?: components["schemas"]["DevApiProductGalleryMediaDto"][];
+            /** @description Variations (e.g. Size, Color) and their options. */
+            variations?: components["schemas"]["DevApiProductVariationDto"][];
+            /** @description Combinations (SKUs) with per-combination stock and pricing. */
+            combinations?: components["schemas"]["DevApiProductCombinationDto"][];
+        };
+        DevApiCollectionDto: {
+            /** @example 9023748120 */
+            publicId: string;
+            /** @example Fast food */
+            name: string;
+            /** @example fast-food */
+            slug: string;
+            /** @example Quick bites & street food. */
+            description?: string;
+            /** @example https://cdn.xedoapp.com/collections/cover/abc.jpg */
+            coverUrl?: string | null;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            updatedAt: string;
+        };
+        DevApiOrderCustomerDto: {
+            /** @example Jean */
+            firstName?: string;
+            /** @example Kouassi */
+            lastName?: string;
+            /** @example jean@example.com */
+            email?: string;
+            /** @example +225 07 12 34 56 78 */
+            phone?: string;
+        };
+        DevApiOrderPaymentDto: {
+            /** @example PAY-2024-001 */
+            reference: string;
+            /** @example 125000 */
+            amount: number;
+            /**
+             * @description Online portion amount (split payment only).
+             * @example 37500
+             */
+            onlineAmount?: number | null;
+            /**
+             * @example success
+             * @enum {string}
+             */
+            status: "pending" | "processing" | "success" | "failed";
+            /**
+             * @example external_wallet
+             * @enum {string}
+             */
+            method: "external_wallet" | "loyalty_card" | "pay_on_delivery" | "split_payment";
+        };
+        DevApiOrderListItemDto: {
+            /**
+             * @description Order internal id
+             * @example 1
+             */
+            id: number;
+            /**
+             * @description Public id (cart publicId).
+             * @example ORD-XPK39ZQA01
+             */
+            publicId: string;
+            customer: components["schemas"]["DevApiOrderCustomerDto"];
+            /** @example 5 */
+            itemsCount: number;
+            /** @example 125000 */
+            orderAmount: number;
+            /** @example 1000 */
+            deliveryCost: number;
+            payment: components["schemas"]["DevApiOrderPaymentDto"];
+            /** @enum {string|null} */
+            deliveryType?: "DELIVERY" | "PICKUP" | null;
+            /** @enum {string|null} */
+            orderStatus?: "PREPARING" | "IN_DELIVERY" | "DELIVERED" | "READY_FOR_PICKUP" | "PICKED_UP" | null;
+            /**
+             * @description Developer-supplied metadata attached at cart creation.
+             * @example {
+             *       "internalOrderId": "ORD-12345"
+             *     }
+             */
+            meta?: Record<string, never> | null;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            updatedAt: string;
+        };
+        DevApiOrderItemCombinationDto: {
+            /** @example SKU-XL-RED */
+            sku: string;
+            /**
+             * @example [
+             *       "XL",
+             *       "Red"
+             *     ]
+             */
+            optionNames: string[];
+            /** @example 500 */
+            priceAdjustment?: number;
+            /**
+             * @example fixed
+             * @enum {string}
+             */
+            priceAdjustmentType?: "fixed" | "percentage";
+        };
+        DevApiOrderItemDto: {
+            /**
+             * @description Cart item internal id
+             * @example 1
+             */
+            id: number;
+            /** @example 283 */
+            productId: number;
+            /** @example Samsung Galaxy A54 */
+            name: string;
+            /** @example samsung-galaxy-a54 */
+            slug: string;
+            /** @example 125000 */
+            price: number;
+            /** @example 1 */
+            quantity: number;
+            /** @example 125000 */
+            lineTotal: number;
+            /** @example https://cdn.xedoapp.com/products/cover/abc.jpg */
+            coverUrl?: string | null;
+            /** @example COMB_ABC123 */
+            combinationPublicId?: string;
+            combination?: components["schemas"]["DevApiOrderItemCombinationDto"];
+        };
+        DevApiOrderTotalsDto: {
+            /** @example 125000 */
+            subtotal: number;
+            /** @example 1000 */
+            deliveryFees: number;
+            /** @example 126000 */
+            total: number;
+        };
+        DevApiOrderDeliveryInfoDto: {
+            /** @example 1 */
+            areaId: number;
+            /** @example Cocody, Angré 7ème tranche */
+            areaName: string;
+            /** @example 1000 */
+            deliveryCost: number;
+        };
+        DevApiOrderDeliveryDto: {
+            /**
+             * @example DELIVERY
+             * @enum {string}
+             */
+            deliveryType: "DELIVERY" | "PICKUP";
+            deliveryInfo?: components["schemas"]["DevApiOrderDeliveryInfoDto"] | null;
+            /** @example Appeler 30 minutes avant la livraison */
+            additionalDetails?: string | null;
+            /**
+             * @example PREPARING
+             * @enum {string}
+             */
+            orderStatus: "PREPARING" | "IN_DELIVERY" | "DELIVERED" | "READY_FOR_PICKUP" | "PICKED_UP";
+        };
+        DevApiOrderDetailDto: {
+            /**
+             * @description Order internal id
+             * @example 1
+             */
+            id: number;
+            /** @example ORD-XPK39ZQA01 */
+            publicId: string;
+            /**
+             * @example PAYMENT_COMPLETED
+             * @enum {string}
+             */
+            status: "DRAFT" | "PENDING_PAYMENT" | "ABANDONED" | "PAYMENT_FAILED" | "PAYMENT_COMPLETED";
+            customer: components["schemas"]["DevApiOrderCustomerDto"];
+            items: components["schemas"]["DevApiOrderItemDto"][];
+            totals: components["schemas"]["DevApiOrderTotalsDto"];
+            payment: components["schemas"]["DevApiOrderPaymentDto"];
+            delivery?: components["schemas"]["DevApiOrderDeliveryDto"] | null;
+            /**
+             * @description Developer-supplied metadata attached at cart creation.
+             * @example {
+             *       "internalOrderId": "ORD-12345"
+             *     }
+             */
+            meta?: Record<string, never> | null;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            updatedAt: string;
+        };
+        DevApiCartCustomerDto: {
+            /** @example Jean */
+            firstName?: string;
+            /** @example Kouassi */
+            lastName?: string;
+            /** @example jean@example.com */
+            email?: string;
+            /** @example +225 07 12 34 56 78 */
+            phone?: string;
+        };
+        DevApiCartListItemDto: {
+            /**
+             * @description Cart internal id
+             * @example 1
+             */
+            id: number;
+            /** @example CART-XPK39ZQA01 */
+            publicId: string;
+            customer: components["schemas"]["DevApiCartCustomerDto"];
+            /** @example 5 */
+            itemsCount: number;
+            /** @example 125000 */
+            cartAmount: number;
+            /** @example 1000 */
+            deliveryCost: number;
+            /** @enum {string} */
+            status: "PENDING_PAYMENT" | "ABANDONED" | "PAYMENT_FAILED" | "PAYMENT_COMPLETED";
+            /** @enum {string|null} */
+            deliveryType?: "DELIVERY" | "PICKUP" | null;
+            /** @enum {string|null} */
+            orderStatus?: "PREPARING" | "IN_DELIVERY" | "DELIVERED" | "READY_FOR_PICKUP" | "PICKED_UP" | null;
+            /**
+             * @description Developer-supplied metadata attached at cart creation.
+             * @example {
+             *       "internalOrderId": "ORD-12345"
+             *     }
+             */
+            meta?: Record<string, never> | null;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            updatedAt: string;
+        };
+        DevApiCartItemCombinationDto: {
+            /** @example SKU-XL-RED */
+            sku: string;
+            /**
+             * @example [
+             *       "XL",
+             *       "Red"
+             *     ]
+             */
+            optionNames: string[];
+            /** @example 500 */
+            priceAdjustment?: number;
+            /**
+             * @example fixed
+             * @enum {string}
+             */
+            priceAdjustmentType?: "fixed" | "percentage";
+        };
+        DevApiCartItemDto: {
+            /**
+             * @description Cart item internal id
+             * @example 1
+             */
+            id: number;
+            /** @example 283 */
+            productId: number;
+            /** @example Samsung Galaxy A54 */
+            name: string;
+            /** @example samsung-galaxy-a54 */
+            slug: string;
+            /** @example 125000 */
+            price: number;
+            /** @example 1 */
+            quantity: number;
+            /** @example 125000 */
+            lineTotal: number;
+            /** @example https://cdn.xedoapp.com/products/cover/abc.jpg */
+            coverUrl?: string | null;
+            /** @example COMB_ABC123 */
+            combinationPublicId?: string;
+            combination?: components["schemas"]["DevApiCartItemCombinationDto"];
+        };
+        DevApiCartTotalsDto: {
+            /** @example 125000 */
+            subtotal: number;
+            /** @example 1000 */
+            deliveryFees: number;
+            /** @example 126000 */
+            total: number;
+        };
+        DevApiCartDeliveryInfoDto: {
+            /** @example 1 */
+            areaId: number;
+            /** @example Cocody, Angré 7ème tranche */
+            areaName: string;
+            /** @example 1000 */
+            deliveryCost: number;
+        };
+        DevApiCartDeliveryDto: {
+            /**
+             * @example DELIVERY
+             * @enum {string}
+             */
+            deliveryType: "DELIVERY" | "PICKUP";
+            deliveryInfo?: components["schemas"]["DevApiCartDeliveryInfoDto"] | null;
+            /** @example Appeler 30 minutes avant */
+            additionalDetails?: string | null;
+            /**
+             * @example PREPARING
+             * @enum {string}
+             */
+            orderStatus: "PREPARING" | "IN_DELIVERY" | "DELIVERED" | "READY_FOR_PICKUP" | "PICKED_UP";
+        };
+        DevApiCartDetailDto: {
+            /**
+             * @description Cart internal id
+             * @example 1
+             */
+            id: number;
+            /** @example CART-XPK39ZQA01 */
+            publicId: string;
+            /** @enum {string} */
+            status: "PENDING_PAYMENT" | "ABANDONED" | "PAYMENT_FAILED" | "PAYMENT_COMPLETED";
+            customer: components["schemas"]["DevApiCartCustomerDto"];
+            items: components["schemas"]["DevApiCartItemDto"][];
+            totals: components["schemas"]["DevApiCartTotalsDto"];
+            delivery?: components["schemas"]["DevApiCartDeliveryDto"] | null;
+            /**
+             * @description Developer-supplied metadata attached at cart creation.
+             * @example {
+             *       "internalOrderId": "ORD-12345"
+             *     }
+             */
+            meta?: Record<string, never> | null;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            updatedAt: string;
+        };
+        DevApiCheckoutPreviewResponseDto: {
+            /** @example 250000 */
+            subtotal: number;
+            /** @example 1000 */
+            deliveryCost: number;
+            /** @example 251000 */
+            total: number;
+            /**
+             * @description Set only when paymentMethod = split_payment.
+             * @example 150000
+             */
+            onlineAmount?: number | null;
+            /**
+             * @description Set only when paymentMethod = split_payment.
+             * @example 101000
+             */
+            onDeliveryAmount?: number | null;
+        };
+        DevApiCheckoutItemDto: {
+            /** @example 9023748120 */
+            publicProductId: string;
+            /** @example 2 */
+            quantity: number;
+            /** @example COMB_ABC123 */
+            combinationPublicId?: string;
+        };
+        DevApiCheckoutDeliveryDto: {
+            /**
+             * @example DELIVERY
+             * @enum {string}
+             */
+            deliveryType: "DELIVERY" | "PICKUP";
+            /**
+             * @description Required when deliveryType = DELIVERY.
+             * @example 1
+             */
+            deliveryAreaId?: number;
+        };
+        DevApiCheckoutPreviewDto: {
+            items: components["schemas"]["DevApiCheckoutItemDto"][];
+            delivery: components["schemas"]["DevApiCheckoutDeliveryDto"];
+            /**
+             * @example external_wallet
+             * @enum {string}
+             */
+            paymentMethod: "external_wallet" | "split_payment";
+        };
+        DevApiCheckoutTotalsDto: {
+            /** @example 250000 */
+            subtotal: number;
+            /** @example 1000 */
+            deliveryCost: number;
+            /** @example 251000 */
+            total: number;
+            /** @example 150000 */
+            onlineAmount?: number | null;
+            /** @example 101000 */
+            onDeliveryAmount?: number | null;
+        };
+        DevApiCheckoutPaymentDto: {
+            /** @example PAY-XPK39ZQA01 */
+            reference: string;
+            /** @example pending */
+            status: string;
+        };
+        DevApiCheckoutCreateResponseDto: {
+            /** @example CART-XPK39ZQA01 */
+            publicId: string;
+            /** @example PENDING_PAYMENT */
+            status: string;
+            totals: components["schemas"]["DevApiCheckoutTotalsDto"];
+            payment: components["schemas"]["DevApiCheckoutPaymentDto"];
+            /** @example https://checkout.moneroo.io/abc-def */
+            checkoutUrl: string;
+        };
+        DevApiCheckoutCustomerDto: {
+            /** @example Jean */
+            firstName: string;
+            /** @example Kouassi */
+            lastName: string;
+            /** @example jean@example.com */
+            email: string;
+            /** @example +225 07 12 34 56 78 */
+            phone: string;
+        };
+        DevApiCheckoutCreateDto: {
+            customer: components["schemas"]["DevApiCheckoutCustomerDto"];
+            items: components["schemas"]["DevApiCheckoutItemDto"][];
+            delivery: components["schemas"]["DevApiCheckoutDeliveryDto"];
+            /**
+             * @example external_wallet
+             * @enum {string}
+             */
+            paymentMethod: "external_wallet" | "split_payment";
+            /**
+             * @description URL to redirect the customer to after the payment provider checkout. Must be HTTPS.
+             * @example https://my-app.com/after-checkout
+             */
+            returnUrl: string;
+            /** @example Appeler 30 min avant */
+            additionalDetails?: string;
+            /**
+             * @description Free-form JSON payload returned as-is in every cart/order response. Use it to attach your own identifiers (e.g. internalOrderId).
+             * @example {
+             *       "internalOrderId": "ORD-12345",
+             *       "source": "mobile-app"
+             *     }
+             */
+            meta?: Record<string, never>;
+        };
+        DevApiCheckoutRetryPayResponseDto: {
+            payment: components["schemas"]["DevApiCheckoutPaymentDto"];
+            /** @example https://checkout.moneroo.io/abc-def */
+            checkoutUrl: string;
+        };
+        DevApiCheckoutRetryPayDto: {
+            /** @example https://my-app.com/after-checkout */
+            returnUrl: string;
+        };
+        DevApiDeliveryAreaDto: {
+            /**
+             * @description Identifier to pass as `delivery.deliveryAreaId` when creating a cart.
+             * @example 1
+             */
+            id: number;
+            /** @example Cocody */
+            name: string;
+            /**
+             * @description Delivery cost for this area.
+             * @example 1000
+             */
+            deliveryCost: number;
+        };
+        DevApiBusinessCategoryDto: {
+            /** @example 3 */
+            id: number;
+            /** @example Restauration */
+            name: string;
+        };
+        DevApiMarketplaceProfileDto: {
+            /** @example ma-boutique */
+            slug: string;
+            /** @example true */
+            enabled: boolean;
+            businessCategory?: components["schemas"]["DevApiBusinessCategoryDto"] | null;
+            /** @example +225 07 12 34 56 78 */
+            whatsappPhoneNumber?: string | null;
+            /** @example true */
+            enablePayOnDelivery: boolean;
+            /** @example true */
+            enableSplitPayment: boolean;
+            /**
+             * @description Default percentage paid online for split payment. Null if split payment is disabled.
+             * @example 30
+             */
+            defaultOnlineSplitPaymentPercentage?: number | null;
+            /**
+             * @description Whether the delivery cost is paid online or on delivery in a split payment.
+             * @example on_delivery
+             * @enum {string}
+             */
+            splitPaymentDeliveryCostHandling: "online" | "on_delivery";
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @example 2026-05-26T13:14:15.000Z
+             */
+            updatedAt: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
 /**
- * Public, hand-written type surface for the Xedo SDK.
+ * Public type surface for the Xedo SDK.
  *
  * The Xedo Developer API returns its resource payloads inside a generic
- * envelope (`{ success, data }`). The entity payloads themselves are described
- * loosely in `openapi.json` (`type: object`), so we expose them as open
- * JSON objects here and keep the precise, validated shapes for the checkout
- * inputs — which the API does constrain. The generated mirror of the spec
- * lives in `./generated.ts` (do not edit by hand).
+ * envelope (`{ success, data }`). Since the API v1 spec now describes every
+ * entity in detail, these public types are derived directly from the generated
+ * mirror of `openapi.json` (`./generated.ts`, do not edit by hand) so they stay
+ * in sync on every `npm run generate`. Only cross-cutting helpers (pagination,
+ * list params, rate-limit) are hand-written here.
  */
-/** A free-form JSON object returned by the API. */
+
+type Schemas = components['schemas'];
+/** A free-form JSON object (e.g. the developer-supplied `meta` payload). */
 type JsonObject = {
     [key: string]: unknown;
 };
+/**
+ * `meta` is a free-form JSON object, but openapi-typescript renders the spec's
+ * loose `object` as `Record<string, never>`. Swap it back to {@link JsonObject}.
+ */
+type WithMeta<T> = Omit<T, 'meta'> & {
+    meta?: JsonObject | null;
+};
 /** Sort direction shared by every paginated list endpoint. */
 type SortOrder = 'asc' | 'desc';
+/** Lifecycle status of an order. */
+type OrderStatus = Schemas['DevApiOrderDetailDto']['status'];
+/** Lifecycle status of a cart (orders that are not yet paid). */
+type CartStatus = Schemas['DevApiCartDetailDto']['status'];
+/** Fulfillment status once an order is being prepared/shipped. */
+type FulfillmentStatus = Schemas['DevApiOrderDeliveryDto']['orderStatus'];
+/** Delivery mode of a cart/order. */
+type DeliveryType = Schemas['DevApiOrderDeliveryDto']['deliveryType'];
+/** Payment status of an order. */
+type PaymentStatus = Schemas['DevApiOrderPaymentDto']['status'];
+/** Payment method as reported on a paid order (read side). */
+type OrderPaymentMethod = Schemas['DevApiOrderPaymentDto']['method'];
+/** How a per-option/combination price is adjusted. */
+type PriceAdjustmentType = NonNullable<Schemas['DevApiProductCombinationDto']['priceAdjustmentType']>;
+/** Gallery media kind. */
+type MediaType = Schemas['DevApiProductGalleryMediaDto']['type'];
 /** Result of `GET /v1/ping` — use it to validate an API key end to end. */
-interface PingResult {
-    marketplaceId: number;
-    timestamp: string;
-}
+type PingResult = Schemas['PingPayload'];
+/** The lightweight collection reference embedded on a product. */
+type ProductCollection = Schemas['DevApiProductCollectionDto'];
+/** A gallery image or video attached to a product/variation option. */
+type ProductGalleryMedia = Schemas['DevApiProductGalleryMediaDto'];
+/** One selectable option (e.g. "XL") of a product variation. */
+type ProductVariationOption = Schemas['DevApiProductVariationOptionDto'];
+/** A product variation axis (e.g. "Size") and its options. */
+type ProductVariation = Schemas['DevApiProductVariationDto'];
+/** A combination (SKU) with its own stock and pricing. */
+type ProductCombination = Schemas['DevApiProductCombinationDto'];
 /** A product from the merchant catalogue (`GET /v1/products`). */
-type Product = JsonObject;
+type Product = Schemas['DevApiProductDto'];
 /** A collection / category of products (`GET /v1/collections`). */
-type Collection = JsonObject;
-/** A paid order (`GET /v1/orders`). */
-type Order = JsonObject;
-/** A cart (`GET /v1/carts`). `DRAFT` carts are never exposed by the API. */
-type Cart = JsonObject;
+type Collection = Schemas['DevApiCollectionDto'];
+/** Customer details attached to an order. */
+type OrderCustomer = Schemas['DevApiOrderCustomerDto'];
+/** Payment details of a paid order. */
+type OrderPayment = Schemas['DevApiOrderPaymentDto'];
+/** A single line item of an order. */
+type OrderItem = Schemas['DevApiOrderItemDto'];
+/** Computed monetary totals of an order. */
+type OrderTotals = Schemas['DevApiOrderTotalsDto'];
+/** Delivery information of an order. */
+type OrderDelivery = Schemas['DevApiOrderDeliveryDto'];
+/** A row in `GET /v1/orders` (summary). */
+type OrderListItem = WithMeta<Schemas['DevApiOrderListItemDto']>;
+/** A full order from `GET /v1/orders/{publicId}`. */
+type Order = WithMeta<Schemas['DevApiOrderDetailDto']>;
+/** Customer details attached to a cart. */
+type CartCustomer = Schemas['DevApiCartCustomerDto'];
+/** A single line item of a cart. */
+type CartItem = Schemas['DevApiCartItemDto'];
+/** Computed monetary totals of a cart. */
+type CartTotals = Schemas['DevApiCartTotalsDto'];
+/** Delivery information of a cart. */
+type CartDelivery = Schemas['DevApiCartDeliveryDto'];
+/** A row in `GET /v1/carts` (summary). `DRAFT` carts are never exposed. */
+type CartListItem = WithMeta<Schemas['DevApiCartListItemDto']>;
+/** A full cart from `GET /v1/carts/{publicId}`. `DRAFT` carts are never exposed. */
+type Cart = WithMeta<Schemas['DevApiCartDetailDto']>;
 /** Computed totals returned by `POST /v1/carts/preview` (nothing persisted). */
-type CheckoutPreview = JsonObject;
+type CheckoutPreview = Schemas['DevApiCheckoutPreviewResponseDto'];
+/** Totals carried on a created cart. */
+type CheckoutTotals = Schemas['DevApiCheckoutTotalsDto'];
+/** Payment handle carried on a created cart. */
+type CheckoutPayment = Schemas['DevApiCheckoutPaymentDto'];
 /**
- * Returned by `POST /v1/carts` and `POST /v1/carts/{publicId}/pay`. Always
- * carries the hosted `checkoutUrl` to redirect the customer to.
+ * Returned by `POST /v1/carts`. Always carries the hosted `checkoutUrl` to
+ * redirect the customer to.
  */
-interface CheckoutResult extends JsonObject {
-    checkoutUrl: string;
-}
+type CheckoutResult = Schemas['DevApiCheckoutCreateResponseDto'];
+/** Returned by `POST /v1/carts/{publicId}/pay`. */
+type CheckoutRetryResult = Schemas['DevApiCheckoutRetryPayResponseDto'];
+/** A delivery area (`GET /v1/delivery-areas`). */
+type DeliveryArea = Schemas['DevApiDeliveryAreaDto'];
+/** The merchant's business category. */
+type BusinessCategory = Schemas['DevApiBusinessCategoryDto'];
+/** The marketplace profile (`GET /v1/marketplace`). */
+type MarketplaceProfile = Schemas['DevApiMarketplaceProfileDto'];
+type CheckoutItem = Schemas['DevApiCheckoutItemDto'];
+type CheckoutDelivery = Schemas['DevApiCheckoutDeliveryDto'];
+type CheckoutCustomer = Schemas['DevApiCheckoutCustomerDto'];
+/** Payment method accepted when creating a cart (write side). */
+type PaymentMethod = Schemas['DevApiCheckoutCreateDto']['paymentMethod'];
+type CheckoutPreviewInput = Schemas['DevApiCheckoutPreviewDto'];
+type CheckoutCreateInput = WithMeta<Schemas['DevApiCheckoutCreateDto']>;
+type CheckoutRetryPayInput = Schemas['DevApiCheckoutRetryPayDto'];
 /** Shared cursor parameters for every paginated list endpoint. */
 interface ListParams {
     /** Page number (1-based). */
@@ -96,46 +878,6 @@ interface RateLimitInfo {
     remaining: number | null;
     reset: number | null;
 }
-interface CheckoutItem {
-    /** e.g. "PRD-XPK39ZQA01". */
-    publicProductId: string;
-    /** Quantity, >= 1. */
-    quantity: number;
-    /** SKU public id, when the product has variations. */
-    combinationPublicId?: string;
-}
-interface CheckoutDelivery {
-    deliveryType: 'DELIVERY' | 'PICKUP';
-    /** Required when `deliveryType === 'DELIVERY'`. */
-    deliveryAreaId?: number;
-}
-interface CheckoutCustomer {
-    firstName: string;
-    lastName: string;
-    email: string;
-    phone: string;
-}
-type PaymentMethod = 'external_wallet' | 'split_payment';
-interface CheckoutPreviewInput {
-    items: CheckoutItem[];
-    delivery: CheckoutDelivery;
-    paymentMethod: PaymentMethod;
-}
-interface CheckoutCreateInput extends CheckoutPreviewInput {
-    customer: CheckoutCustomer;
-    /** HTTPS is mandatory. */
-    returnUrl: string;
-    additionalDetails?: string;
-    /**
-     * Free JSON payload echoed back, unchanged, in every cart/order response.
-     * Use it to correlate a Xedo order with your own state (`internalOrderId`,
-     * `source`, `templateId`, …).
-     */
-    meta?: Record<string, unknown>;
-}
-interface CheckoutRetryPayInput {
-    returnUrl: string;
-}
 
 type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
 interface TransportOptions {
@@ -186,12 +928,12 @@ declare abstract class Resource {
 
 declare class Carts extends Resource {
     /**
-     * `GET /v1/carts` — one page of carts. `DRAFT` carts are never exposed by
-     * the API.
+     * `GET /v1/carts` — one page of carts (summary rows). `DRAFT` carts are
+     * never exposed by the API.
      */
-    list(params?: CartListParams): Promise<PaginatedResult<Cart>>;
-    /** Async iterator over every cart across all pages. */
-    listAll(params?: CartListParams): AsyncGenerator<Cart>;
+    list(params?: CartListParams): Promise<PaginatedResult<CartListItem>>;
+    /** Async iterator over every cart (summary row) across all pages. */
+    listAll(params?: CartListParams): AsyncGenerator<CartListItem>;
     /** `GET /v1/carts/{publicId}`. */
     retrieve(publicId: string, opts?: RequestOptions): Promise<Cart>;
     /** `POST /v1/carts/preview` — compute totals without persisting anything. */
@@ -206,14 +948,18 @@ declare class Carts extends Resource {
      * `POST /v1/carts/{publicId}/pay` — relaunch payment initialization after a
      * `502 PAYMENT_INIT_FAILED`.
      */
-    pay(publicId: string, input: CheckoutRetryPayInput, opts?: RequestOptions): Promise<CheckoutResult>;
+    pay(publicId: string, input: CheckoutRetryPayInput, opts?: RequestOptions): Promise<CheckoutRetryResult>;
     /**
      * Convenience wrapper around the 502 checkout flow: create the cart, and if
      * the payment provider could not be reached (`PAYMENT_INIT_FAILED`), retry
      * `pay()` once with the same `returnUrl`. Stays transparent — it logs the
      * code and never swallows a definitive failure.
+     *
+     * Returns a {@link CheckoutResult} on the happy path, or a
+     * {@link CheckoutRetryResult} when the retry succeeded — both carry
+     * `checkoutUrl` and `payment`.
      */
-    createAndPay(input: CheckoutCreateInput, opts?: RequestOptions): Promise<CheckoutResult>;
+    createAndPay(input: CheckoutCreateInput, opts?: RequestOptions): Promise<CheckoutResult | CheckoutRetryResult>;
 }
 
 declare class Collections extends Resource {
@@ -227,11 +973,27 @@ declare class Collections extends Resource {
     retrieveBySlug(slug: string, opts?: RequestOptions): Promise<Collection>;
 }
 
+declare class DeliveryAreas extends Resource {
+    /**
+     * `GET /v1/delivery-areas` — every delivery area configured by the merchant.
+     * Use a returned `id` as `delivery.deliveryAreaId` when creating a cart.
+     */
+    list(opts?: RequestOptions): Promise<DeliveryArea[]>;
+}
+
+declare class Marketplace extends Resource {
+    /**
+     * `GET /v1/marketplace` — the merchant's marketplace profile: enabled
+     * payment methods, split-payment configuration, business category, …
+     */
+    retrieve(opts?: RequestOptions): Promise<MarketplaceProfile>;
+}
+
 declare class Orders extends Resource {
-    /** `GET /v1/orders` — one page of paid orders. */
-    list(params?: OrderListParams): Promise<PaginatedResult<Order>>;
-    /** Async iterator over every order across all pages. */
-    listAll(params?: OrderListParams): AsyncGenerator<Order>;
+    /** `GET /v1/orders` — one page of paid orders (summary rows). */
+    list(params?: OrderListParams): Promise<PaginatedResult<OrderListItem>>;
+    /** Async iterator over every order (summary row) across all pages. */
+    listAll(params?: OrderListParams): AsyncGenerator<OrderListItem>;
     /** `GET /v1/orders/{publicId}`. */
     retrieve(publicId: string, opts?: RequestOptions): Promise<Order>;
     /**
@@ -254,9 +1016,13 @@ declare class Products extends Resource {
 }
 
 interface XedoOptions {
-    /** Developer API key: `xdk_live_…` or `xdk_test_…`. */
+    /** Developer API key: an opaque `xdk_…` string. */
     apiKey: string;
-    /** Override the API base URL. Defaults to the production marketplace URL. */
+    /**
+     * Override the API base URL. Defaults to the production marketplace URL.
+     * The base URL alone selects Production vs Sandbox — the key is opaque and
+     * carries no environment. See https://developers.xedoapp.com/introduction/environments
+     */
     baseUrl?: string;
     /** Max automatic retries on `429`. Defaults to 4. */
     maxRetries?: number;
@@ -266,7 +1032,7 @@ interface XedoOptions {
     fetch?: FetchLike;
     /**
      * Escape hatch to run in a browser. Strongly discouraged: your
-     * `xdk_live_…` key would be exposed in the client bundle.
+     * `xdk_…` key would be exposed in the client bundle.
      */
     dangerouslyAllowBrowser?: boolean;
 }
@@ -284,14 +1050,10 @@ declare class Xedo {
     readonly collections: Collections;
     readonly orders: Orders;
     readonly carts: Carts;
-    private readonly apiKey;
+    readonly deliveryAreas: DeliveryAreas;
+    readonly marketplace: Marketplace;
     private readonly transport;
     constructor(options: XedoOptions);
-    /**
-     * The environment inferred from the key prefix. The rest of the key is
-     * treated as opaque.
-     */
-    get environment(): 'test' | 'live' | 'unknown';
     /** Rate-limit headers from the most recent response, for monitoring. */
     get lastRateLimit(): RateLimitInfo | null;
     /** `GET /v1/ping` — validate the API key end to end. */
@@ -359,4 +1121,4 @@ declare class XedoPaymentInitError extends XedoError {
 declare class XedoConnectionError extends XedoError {
 }
 
-export { type Cart, type CartListParams, type CheckoutCreateInput, type CheckoutCustomer, type CheckoutDelivery, type CheckoutItem, type CheckoutPreview, type CheckoutPreviewInput, type CheckoutResult, type CheckoutRetryPayInput, type Collection, type CollectionListParams, type FetchLike, type JsonObject, type ListParams, type Order, type OrderListParams, type PaginatedResult, type PaymentMethod, type PingResult, type Product, type ProductListParams, type RateLimitInfo, type RequestOptions, type RetrieveOptions, type SortOrder, Xedo, XedoAuthError, XedoConflictError, XedoConnectionError, XedoError, type XedoErrorParams, XedoNotFoundError, type XedoOptions, XedoPaymentInitError, XedoRateLimitError, XedoStockError, XedoValidationError };
+export { type BusinessCategory, type Cart, type CartCustomer, type CartDelivery, type CartItem, type CartListItem, type CartListParams, type CartStatus, type CartTotals, type CheckoutCreateInput, type CheckoutCustomer, type CheckoutDelivery, type CheckoutItem, type CheckoutPayment, type CheckoutPreview, type CheckoutPreviewInput, type CheckoutResult, type CheckoutRetryPayInput, type CheckoutRetryResult, type CheckoutTotals, type Collection, type CollectionListParams, type DeliveryArea, type DeliveryType, type FetchLike, type FulfillmentStatus, type JsonObject, type ListParams, type MarketplaceProfile, type MediaType, type Order, type OrderCustomer, type OrderDelivery, type OrderItem, type OrderListItem, type OrderListParams, type OrderPayment, type OrderPaymentMethod, type OrderStatus, type OrderTotals, type PaginatedResult, type PaymentMethod, type PaymentStatus, type PingResult, type PriceAdjustmentType, type Product, type ProductCollection, type ProductCombination, type ProductGalleryMedia, type ProductListParams, type ProductVariation, type ProductVariationOption, type RateLimitInfo, type RequestOptions, type RetrieveOptions, type SortOrder, Xedo, XedoAuthError, XedoConflictError, XedoConnectionError, XedoError, type XedoErrorParams, XedoNotFoundError, type XedoOptions, XedoPaymentInitError, XedoRateLimitError, XedoStockError, XedoValidationError };