@xedo/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,362 @@
+/**
+ * Public, hand-written 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).
+ */
+/** A free-form JSON object returned by the API. */
+type JsonObject = {
+    [key: string]: unknown;
+};
+/** Sort direction shared by every paginated list endpoint. */
+type SortOrder = 'asc' | 'desc';
+/** Result of `GET /v1/ping` — use it to validate an API key end to end. */
+interface PingResult {
+    marketplaceId: number;
+    timestamp: string;
+}
+/** A product from the merchant catalogue (`GET /v1/products`). */
+type Product = JsonObject;
+/** 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;
+/** Computed totals returned by `POST /v1/carts/preview` (nothing persisted). */
+type CheckoutPreview = JsonObject;
+/**
+ * Returned by `POST /v1/carts` and `POST /v1/carts/{publicId}/pay`. Always
+ * carries the hosted `checkoutUrl` to redirect the customer to.
+ */
+interface CheckoutResult extends JsonObject {
+    checkoutUrl: string;
+}
+/** Shared cursor parameters for every paginated list endpoint. */
+interface ListParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Page size (capped by the platform, ~100 max). */
+    perPage?: number;
+    /** Sort direction. */
+    order?: SortOrder;
+    /** Full-text search (3 characters minimum). */
+    search?: string;
+    /** Abort signal for this request. */
+    signal?: AbortSignal;
+}
+interface ProductListParams extends ListParams {
+    sort?: 'id' | 'name' | 'price' | 'createdAt';
+    /** Filter by collection slug. */
+    collection?: string;
+    /** Include variations and combinations (SKUs) in the response. */
+    includeVariations?: boolean;
+    /** Include disabled products (drafts). */
+    includeDisabled?: boolean;
+}
+interface CollectionListParams extends ListParams {
+    sort?: 'id' | 'name' | 'createdAt';
+}
+interface OrderListParams extends ListParams {
+    sort?: 'id' | 'createdAt' | 'amount';
+}
+interface CartListParams extends ListParams {
+    sort?: 'id' | 'createdAt';
+}
+/** Options for single-resource retrieval that supports draft resolution. */
+interface RetrieveOptions {
+    /** Resolve a disabled product (draft) as well. */
+    includeDisabled?: boolean;
+    signal?: AbortSignal;
+}
+/** Options for a plain single-resource retrieval. */
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+/**
+ * One page of a paginated list. The SDK unwraps the API envelope but keeps the
+ * pagination metadata so callers can build their own UIs.
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    /** Total number of rows matching the query, across all pages. */
+    total: number;
+    /** 1-based index of the first row returned. */
+    start: number;
+    /** 1-based index of the last row returned. */
+    end: number;
+}
+/** Rate-limit headers captured from the most recent response. */
+interface RateLimitInfo {
+    limit: number | null;
+    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 {
+    apiKey: string;
+    baseUrl: string;
+    maxRetries: number;
+    timeoutMs: number;
+    fetchImpl: FetchLike;
+}
+interface RequestConfig {
+    query?: Record<string, unknown>;
+    body?: unknown;
+    signal?: AbortSignal;
+    /** Accept header; defaults to `application/json`. */
+    accept?: string;
+}
+type HttpMethod = 'GET' | 'POST';
+/**
+ * Owns the HTTP concern: auth header, query/body serialization, per-request
+ * timeout + abort, automatic 429 retries, envelope parsing and error mapping.
+ * Resources sit on top and never touch `fetch` directly.
+ */
+declare class Transport {
+    private readonly opts;
+    lastRateLimit: RateLimitInfo | null;
+    constructor(opts: TransportOptions);
+    /** Run a request and return the unwrapped `data` payload, typed as `T`. */
+    getData<T>(method: HttpMethod, path: string, config?: RequestConfig): Promise<T>;
+    /** Run a GET list request and return `{ data, total, start, end }`. */
+    getPage<T>(path: string, config?: RequestConfig): Promise<PaginatedResult<T>>;
+    /** Run a request that returns a binary body (e.g. the invoice PDF). */
+    getBinary(method: HttpMethod, path: string, config?: RequestConfig): Promise<ArrayBuffer>;
+    private requestJson;
+    private tryParseJson;
+    private toError;
+    /** Fetch with retry on 429; returns the final {@link Response}. */
+    private execute;
+    private fetchOnce;
+    private buildUrl;
+    private captureRateLimit;
+    private retryDelayMs;
+}
+
+declare abstract class Resource {
+    protected readonly transport: Transport;
+    constructor(transport: Transport);
+}
+
+declare class Carts extends Resource {
+    /**
+     * `GET /v1/carts` — one page of carts. `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>;
+    /** `GET /v1/carts/{publicId}`. */
+    retrieve(publicId: string, opts?: RequestOptions): Promise<Cart>;
+    /** `POST /v1/carts/preview` — compute totals without persisting anything. */
+    preview(input: CheckoutPreviewInput, opts?: RequestOptions): Promise<CheckoutPreview>;
+    /**
+     * `POST /v1/carts` — create the cart (`PENDING_PAYMENT`) and return
+     * `data.checkoutUrl`. On a `502 PAYMENT_INIT_FAILED` the cart is kept; retry
+     * the payment with {@link Carts.pay} (or use {@link Carts.createAndPay}).
+     */
+    create(input: CheckoutCreateInput, opts?: RequestOptions): Promise<CheckoutResult>;
+    /**
+     * `POST /v1/carts/{publicId}/pay` — relaunch payment initialization after a
+     * `502 PAYMENT_INIT_FAILED`.
+     */
+    pay(publicId: string, input: CheckoutRetryPayInput, opts?: RequestOptions): Promise<CheckoutResult>;
+    /**
+     * 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.
+     */
+    createAndPay(input: CheckoutCreateInput, opts?: RequestOptions): Promise<CheckoutResult>;
+}
+
+declare class Collections extends Resource {
+    /** `GET /v1/collections` — one page of collections. */
+    list(params?: CollectionListParams): Promise<PaginatedResult<Collection>>;
+    /** Async iterator over every collection across all pages. */
+    listAll(params?: CollectionListParams): AsyncGenerator<Collection>;
+    /** `GET /v1/collections/{publicId}`. */
+    retrieve(publicId: string, opts?: RequestOptions): Promise<Collection>;
+    /** `GET /v1/collections/by-slug/{slug}`. */
+    retrieveBySlug(slug: string, opts?: RequestOptions): Promise<Collection>;
+}
+
+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/{publicId}`. */
+    retrieve(publicId: string, opts?: RequestOptions): Promise<Order>;
+    /**
+     * `GET /v1/orders/{publicId}/invoice` — the invoice PDF as a binary
+     * `ArrayBuffer` (not JSON). Throws {@link XedoNotFoundError} if the invoice
+     * has not been generated yet.
+     */
+    invoice(publicId: string, opts?: RequestOptions): Promise<ArrayBuffer>;
+}
+
+declare class Products extends Resource {
+    /** `GET /v1/products` — one page of products. */
+    list(params?: ProductListParams): Promise<PaginatedResult<Product>>;
+    /** Async iterator over every product across all pages. */
+    listAll(params?: ProductListParams): AsyncGenerator<Product>;
+    /** `GET /v1/products/{publicId}`. */
+    retrieve(publicId: string, opts?: RetrieveOptions): Promise<Product>;
+    /** `GET /v1/products/by-slug/{slug}`. */
+    retrieveBySlug(slug: string, opts?: RetrieveOptions): Promise<Product>;
+}
+
+interface XedoOptions {
+    /** Developer API key: `xdk_live_…` or `xdk_test_…`. */
+    apiKey: string;
+    /** Override the API base URL. Defaults to the production marketplace URL. */
+    baseUrl?: string;
+    /** Max automatic retries on `429`. Defaults to 4. */
+    maxRetries?: number;
+    /** Per-request timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+    /** Inject a custom fetch (tests, edge runtimes). Defaults to global fetch. */
+    fetch?: FetchLike;
+    /**
+     * Escape hatch to run in a browser. Strongly discouraged: your
+     * `xdk_live_…` key would be exposed in the client bundle.
+     */
+    dangerouslyAllowBrowser?: boolean;
+}
+/**
+ * The Xedo Developer API client. Server-side only — see
+ * `dangerouslyAllowBrowser`.
+ *
+ * ```ts
+ * const xedo = new Xedo({ apiKey: process.env.XEDO_API_KEY! });
+ * const { data } = await xedo.products.list({ perPage: 20 });
+ * ```
+ */
+declare class Xedo {
+    readonly products: Products;
+    readonly collections: Collections;
+    readonly orders: Orders;
+    readonly carts: Carts;
+    private readonly apiKey;
+    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. */
+    ping(opts?: RequestOptions): Promise<PingResult>;
+}
+
+/**
+ * Typed error hierarchy. Every `success: false` response (and every transport
+ * failure) is thrown as a {@link XedoError} or one of its subclasses. Route on
+ * `error.code` (stable, machine-readable), never on `error.message` (French,
+ * subject to change).
+ */
+interface XedoErrorParams {
+    message: string;
+    /** Machine-readable code, e.g. "PRODUCT_NOT_FOUND". */
+    code: string;
+    /** HTTP status (0 for transport/connection errors). */
+    status: number;
+    /** Per-field validation details. */
+    errors?: Record<string, string[]>;
+    /** Extra context (e.g. `cartPublicId` on PAYMENT_INIT_FAILED). */
+    data?: unknown;
+    /** Request id, when the API returns one. */
+    requestId?: string;
+    /** `Retry-After` value in seconds, when present. */
+    retryAfter?: number;
+}
+declare class XedoError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly errors?: Record<string, string[]>;
+    readonly data?: unknown;
+    readonly requestId?: string;
+    constructor(params: XedoErrorParams);
+}
+/** 401 — `MISSING_DEVELOPER_API_KEY`, `INVALID_DEVELOPER_API_KEY`. */
+declare class XedoAuthError extends XedoError {
+}
+/** 400 — bad request / invalid payment configuration. */
+declare class XedoValidationError extends XedoError {
+}
+/** 404 — product, combination, delivery area, cart or generic not found. */
+declare class XedoNotFoundError extends XedoError {
+}
+/** 422 — `INSUFFICIENT_STOCK` (per-product detail in `errors`). */
+declare class XedoStockError extends XedoError {
+}
+/** 409 — `CART_NOT_RETRYABLE`. */
+declare class XedoConflictError extends XedoError {
+}
+/** 429 — `RATE_LIMITED`. Exposes `retryAfter` (seconds). */
+declare class XedoRateLimitError extends XedoError {
+    readonly retryAfter?: number;
+    constructor(params: XedoErrorParams);
+}
+/**
+ * 502 — `PAYMENT_INIT_FAILED`. The cart was kept; relaunch the payment via
+ * `xedo.carts.pay(cartPublicId, …)`. Exposes `cartPublicId`.
+ */
+declare class XedoPaymentInitError extends XedoError {
+    readonly cartPublicId?: string;
+    constructor(params: XedoErrorParams);
+}
+/** Transport-level failure (timeout, network, malformed response). */
+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 };