@malawistore/store-sdk 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@ type QueryParams = Record<string, QueryValue>;
 declare function buildQuery(query?: QueryParams): string;
 
 /** Machine-readable error codes emitted by the API. */
-type ApiErrorCode = "NOT_FOUND" | "VALIDATION_ERROR" | "UNAUTHORIZED" | "FORBIDDEN" | "CONFLICT" | "RATE_LIMITED" | "INTERNAL";
+type ApiErrorCode = "NOT_FOUND" | "VALIDATION_ERROR" | "UNAUTHORIZED" | "FORBIDDEN" | "CONFLICT" | "RATE_LIMITED" | "INTERNAL" | "BULK_LIMIT_EXCEEDED" | "DUPLICATE_ITEM" | "IDEMPOTENCY_CONFLICT";
 /** Error codes that can originate inside the SDK itself. */
 type ClientErrorCode = "NETWORK_ERROR" | "TIMEOUT" | "ABORTED" | "PARSE_ERROR";
 type ErrorCode = ApiErrorCode | ClientErrorCode;
@@ -32,7 +32,7 @@ interface StatusResponse {
 interface PageParams {
     /** 1-based page. Wins over `offset` when both are sent. */
     page?: number;
-    /** Page size. The API defaults to 20 and caps at 100. */
+    /** Page size. Storefront/shopper lists default to 12; admin user lists default to 20. Capped at 100. */
     limit?: number;
     /** Number of rows to skip. */
     offset?: number;
@@ -52,6 +52,51 @@ interface Paginated<T> {
     data: T[];
     meta: PaginationMeta;
 }
+/** One item's outcome inside a bulk response. */
+type BulkItemStatus = "ok" | "error" | "rolled_back";
+/** Machine-readable per-item failure. */
+interface BulkItemError {
+    code: ApiErrorCode;
+    message: string;
+}
+/** Per-item bulk outcome. `index` lines the result up with the request. */
+interface BulkResult<T> {
+    index: number;
+    /** Request line identity (row id, or `product_id|variant_id` for cart lines). */
+    id?: string;
+    status: BulkItemStatus;
+    data?: T;
+    error?: BulkItemError;
+    /** Customer writes: the row already existed / was already gone. */
+    alreadyExists?: boolean;
+    alreadyRemoved?: boolean;
+    /** Dry runs: the row would have been deleted; `blockers` explains refusals. */
+    wouldDelete?: boolean;
+    blockers?: string[];
+}
+/** Standard bulk envelope payload. */
+interface BulkResponse<T> {
+    results: BulkResult<T>[];
+    summary: BulkSummary;
+}
+/** Batch counters. Anything not `ok` (error or rolled_back) counts as failed. */
+interface BulkSummary {
+    total: number;
+    succeeded: number;
+    failed: number;
+}
+/** Shared options for every bulk write. */
+interface BulkOptions {
+    /** All lines commit, or the batch rolls back on the first failure. */
+    atomic?: boolean;
+    /** Replay-safe request key (sent as `Idempotency-Key`, 24h window). */
+    idempotencyKey?: string;
+}
+/** Bulk writes that can validate without writing. */
+interface DryRunOptions extends BulkOptions {
+    /** Validate and project the outcome without writing. */
+    dryRun?: boolean;
+}
 
 type Role = "admin" | "customer";
 /** Issued by register, login, and refresh. */
@@ -183,10 +228,12 @@ interface ProductVariantView {
     available: number;
     in_stock: boolean;
 }
-/** The storefront product page: product plus its sellable SKUs. */
+/** The storefront product page: product, its sellable SKUs, and gallery. */
 interface ProductDetail {
     product: Product;
     variants: ProductVariantView[];
+    /** Gallery rows; queued uploads (empty url) are excluded. */
+    images: ProductImage[];
 }
 type ProductSort = "name_asc" | "name_desc" | "price_asc" | "price_desc" | "newest" | "oldest" | "rating_asc" | "rating_desc" | "relevance";
 interface ListProductsParams extends PageParams {
@@ -196,6 +243,8 @@ interface ListProductsParams extends PageParams {
      * full-text finds nothing.
      */
     q?: string;
+    /** Restrict to specific product ids (comma separated or repeated). */
+    ids?: string[];
     category_id?: string;
     category_slug?: string;
     min_price_cents?: number;
@@ -237,6 +286,43 @@ interface UpdateProductInput {
     /** Unfile the product. Slugs are immutable. */
     clear_category?: boolean;
 }
+/** One product gallery image. `is_primary` mirrors the product's image_url. */
+interface ProductImage {
+    id: string;
+    /** Empty while the upload is still queued. */
+    url: string;
+    position: number;
+    is_primary: boolean;
+    /** ISO-8601 timestamp. */
+    created_at: string;
+}
+/** Raw payload of the admin gallery list. */
+interface ProductImageList {
+    images: ProductImage[];
+}
+/** Result of queuing a multi-file gallery upload (HTTP 202). */
+interface UploadImagesResponse {
+    status: string;
+    queued: number;
+    failed: number;
+}
+interface BulkCreateProductsInput extends DryRunOptions {
+    items: CreateProductInput[];
+}
+interface BulkUpdateProductItem {
+    id: string;
+    patch: UpdateProductInput;
+}
+interface BulkUpdateProductsInput extends DryRunOptions {
+    updates: BulkUpdateProductItem[];
+}
+interface BulkDeleteProductsInput extends DryRunOptions {
+    ids: string[];
+}
+type BulkProductResult = BulkResult<Product>;
+type BulkCreateProductsResponse = BulkResponse<Product>;
+type BulkUpdateProductsResponse = BulkResponse<Product>;
+type BulkDeleteProductsResponse = BulkResponse<never>;
 
 /** A sellable SKU. Prices are absolute USD cents. */
 interface Variant {
@@ -262,6 +348,18 @@ interface UpdateVariantInput {
     price_cents?: number;
     is_active?: boolean;
 }
+interface BulkCreateVariantsInput extends DryRunOptions {
+    items: CreateVariantInput[];
+}
+interface BulkUpdateVariantItem {
+    id: string;
+    patch: UpdateVariantInput;
+}
+interface BulkUpdateVariantsInput extends DryRunOptions {
+    updates: BulkUpdateVariantItem[];
+}
+type BulkCreateVariantsResponse = BulkResponse<Variant>;
+type BulkUpdateVariantsResponse = BulkResponse<Variant>;
 
 /** One cart row. Variant fields are empty for simple products. */
 interface CartLine {
@@ -290,6 +388,32 @@ interface AddCartItemInput {
     variant_id?: string;
     qty: number;
 }
+interface BulkAddCartItemsInput extends BulkOptions {
+    items: AddCartItemInput[];
+}
+/**
+ * Bulk add result: per-line outcomes plus the full updated cart, so no
+ * follow-up GET is needed.
+ */
+interface BulkAddCartItemsResponse extends BulkResponse<CartLine> {
+    cart: Cart;
+}
+type CartSort = "oldest" | "newest" | "name_asc" | "name_desc" | "price_asc" | "price_desc" | "qty_asc" | "qty_desc";
+interface ListCartParams extends PageParams {
+    /** Case-insensitive substring over line name and SKU. */
+    q?: string;
+    product_id?: string;
+    variant_id?: string;
+    sort?: CartSort;
+}
+/**
+ * Raw paged cart envelope returned by `getPage`. `data.subtotal_cents`
+ * always covers the whole cart; `meta` counts cart lines.
+ */
+interface CartResponse {
+    data: Cart;
+    meta: PaginationMeta;
+}
 
 interface Stock {
     product_id: string;
@@ -307,6 +431,21 @@ interface SetStockInput {
     variant_id?: string;
     qty: number;
 }
+/** One line of a batch restock. Stock is keyed by product + variant. */
+interface BulkSetStockItemInput {
+    product_id: string;
+    variant_id?: string;
+    qty: number;
+}
+interface BulkSetStockInput extends BulkOptions {
+    items: BulkSetStockItemInput[];
+}
+type BulkSetStockResponse = BulkResponse<Stock>;
+/** Batch availability read: rows plus ids that did not resolve. */
+interface BulkStockResponse {
+    stock: Stock[];
+    notFound: string[];
+}
 interface ReserveLineInput {
     product_id: string;
     variant_id?: string;
@@ -340,6 +479,20 @@ interface Order {
     /** ISO-8601 timestamp. */
     created_at: string;
 }
+type OrderSort = "newest" | "oldest" | "total_asc" | "total_desc";
+interface ListOrdersParams extends PageParams {
+    status?: OrderStatus;
+    currency?: string;
+    /** RFC3339 or YYYY-MM-DD. */
+    created_after?: string;
+    /** RFC3339 or YYYY-MM-DD; a date-only value includes the whole day. */
+    created_before?: string;
+    min_total_cents?: number;
+    max_total_cents?: number;
+    sort?: OrderSort;
+}
+/** Raw paged orders envelope returned by `listPage`. */
+type OrderListResponse = Paginated<Order>;
 
 type PaymentStatus = "pending" | "succeeded" | "failed" | "cancelled";
 /**
@@ -383,6 +536,25 @@ interface WishlistItem {
     /** ISO-8601 timestamp. */
     added_at: string;
 }
+type WishlistSort = "newest" | "oldest" | "name_asc" | "name_desc" | "price_asc" | "price_desc";
+interface ListWishlistParams extends PageParams {
+    /** Case-insensitive substring over product name and slug. */
+    q?: string;
+    category_id?: string;
+    sort?: WishlistSort;
+}
+/** Raw paged wishlist envelope returned by `listPage`. */
+type WishlistListResponse = Paginated<WishlistItem>;
+/** Body of `POST /wishlist/bulk` (the field is camelCase on the wire). */
+interface BulkAddWishlistInput extends BulkOptions {
+    productIds: string[];
+}
+/** Body of `POST /wishlist/bulk-delete` (product ids, not wishlist row ids). */
+interface BulkRemoveWishlistInput extends DryRunOptions {
+    ids: string[];
+}
+type BulkAddWishlistResponse = BulkResponse<WishlistItem>;
+type BulkRemoveWishlistResponse = BulkResponse<never>;
 
 interface Review {
     id: string;
@@ -400,6 +572,16 @@ interface ReviewSummary {
     average: number;
     count: number;
     reviews: Review[];
+    /** Counters for the filtered review page (average/count are unfiltered). */
+    meta: PaginationMeta;
+}
+type ReviewSort = "newest" | "oldest" | "highest" | "lowest";
+interface ListReviewsParams extends PageParams {
+    /** Case-insensitive substring over title, body and author. */
+    q?: string;
+    /** Only this rating (1-5). */
+    rating?: number;
+    sort?: ReviewSort;
 }
 interface CreateReviewInput {
     /** 1–5. */
@@ -412,6 +594,32 @@ interface UpdateReviewInput {
     title?: string;
     body?: string;
 }
+/** Catalog context attached to a review in the caller's own history. */
+interface MyReviewProduct {
+    id: string;
+    name: string;
+    slug: string;
+    image_url?: string;
+}
+/** One of the caller's reviews, with product context. */
+interface MyReview {
+    id: string;
+    user_id: string;
+    product_id: string;
+    rating: number;
+    title: string;
+    body: string;
+    /** ISO-8601 timestamp. */
+    created_at: string;
+    /** ISO-8601 timestamp. */
+    updated_at: string;
+    product: MyReviewProduct;
+}
+interface ListMyReviewsParams extends PageParams {
+    sort?: ReviewSort;
+}
+/** Raw paged envelope returned by `listMinePage`. */
+type MyReviewsResponse = Paginated<MyReview>;
 
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 interface RetryOptions {
@@ -539,10 +747,17 @@ declare class AuthResource {
 declare class CartResource {
     private readonly http;
     constructor(http: HttpClient);
-    /** Active cart, created empty on first use. */
-    get(): Promise<Cart>;
+    /** Active cart, created empty on first use (paging meta is dropped). */
+    get(params?: ListCartParams): Promise<Cart>;
+    /** Same as `get`, plus the `meta` paging counters. */
+    getPage(params?: ListCartParams): Promise<CartResponse>;
     /** Validates against the catalog and snapshots the current price. */
     addItem(input: AddCartItemInput): Promise<Cart>;
+    /**
+     * Adds up to MAX_BULK_ITEMS lines in one request. Per-line results carry
+     * the written line, plus the full updated cart.
+     */
+    addItems(input: BulkAddCartItemsInput): Promise<BulkAddCartItemsResponse>;
     /** `qty: 0` removes the line. */
     setQty(itemId: string, qty: number): Promise<Cart>;
     removeItem(itemId: string): Promise<Cart>;
@@ -561,8 +776,10 @@ type UploadFile = Blob | {
     name: string;
     type?: string;
 };
-/** Builds the `file` part expected by the admin image endpoints. */
+/** Builds the single `file` part expected by the admin image endpoints. */
 declare function createUploadForm(file: UploadFile, field?: string): FormData;
+/** Builds repeated `files` parts for the gallery upload endpoint. */
+declare function createUploadFormMany(files: UploadFile | UploadFile[], field?: string): FormData;
 
 declare class CategoriesResource {
     private readonly http;
@@ -591,8 +808,15 @@ declare class InventoryResource {
     private readonly http;
     constructor(http: HttpClient);
     getStock(params: GetStockParams): Promise<Stock>;
+    /**
+     * Reads availability for up to MAX_BULK_ITEMS variants in one request.
+     * Unknown ids are returned in `notFound` instead of failing.
+     */
+    getStockByVariants(variantIds: string | string[]): Promise<BulkStockResponse>;
     /** Upserts the on-hand quantity (restocking). */
     setStock(input: SetStockInput): Promise<Stock>;
+    /** Sets on-hand stock for many SKUs; `atomic` commits all or none. */
+    setStockBulk(input: BulkSetStockInput): Promise<BulkSetStockResponse>;
     /** Holds all lines atomically; one short line fails the whole order. */
     reserve(input: ReserveStockInput): Promise<StatusResponse>;
     /** Idempotent. */
@@ -610,8 +834,10 @@ declare class OrdersResource {
      * the cart.
      */
     checkout(): Promise<Order>;
-    /** Newest first. */
-    list(): Promise<Order[]>;
+    /** Newest first (paging meta is dropped). */
+    list(params?: ListOrdersParams): Promise<Order[]>;
+    /** Same filters as `list`, plus the `meta` paging counters. */
+    listPage(params?: ListOrdersParams): Promise<OrderListResponse>;
     get(id: string): Promise<Order>;
     /** Pending orders only; releases the stock hold. */
     cancel(id: string): Promise<Order>;
@@ -651,13 +877,40 @@ declare class ProductsResource {
     delete(id: string): Promise<void>;
     /** Admin only. Queues an async Cloudinary upload (HTTP 202). */
     uploadImage(id: string, file: UploadFile): Promise<StatusResponse>;
+    /**
+     * Admin only. Creates products in bulk. Per-item failures stay inside
+     * the 200 envelope; `atomic` rolls the whole batch back.
+     */
+    bulkCreate(input: BulkCreateProductsInput): Promise<BulkCreateProductsResponse>;
+    /** Admin only. Applies one partial patch per product id. */
+    bulkUpdate(input: BulkUpdateProductsInput): Promise<BulkUpdateProductsResponse>;
+    /**
+     * Admin only. POST rather than DELETE so the id list can travel in JSON.
+     * `dryRun` reports `wouldDelete` without writing.
+     */
+    bulkDelete(input: BulkDeleteProductsInput): Promise<BulkDeleteProductsResponse>;
+    /** Admin only. Gallery rows, including uploads still queued (empty url). */
+    listImages(id: string): Promise<ProductImage[]>;
+    /**
+     * Admin only. Multipart with repeated `files` parts (up to 20 per
+     * request). Each accepted file is queued asynchronously (HTTP 202).
+     */
+    uploadImages(id: string, files: UploadFile | UploadFile[]): Promise<UploadImagesResponse>;
+    /** Admin only. Promotes the next ready image when the primary is deleted. */
+    deleteImage(id: string, imageId: string): Promise<void>;
+    /** Admin only. Points the storefront primary image at one gallery row. */
+    setPrimaryImage(id: string, imageId: string): Promise<Product>;
 }
 
 declare class ReviewsResource {
     private readonly http;
     constructor(http: HttpClient);
-    /** Public aggregate plus the newest reviews for a product. */
-    summary(productId: string): Promise<ReviewSummary>;
+    /** Public aggregate plus one filtered review page (`summary.meta`). */
+    summary(productId: string, params?: ListReviewsParams): Promise<ReviewSummary>;
+    /** The caller's own reviews with product context (paging meta dropped). */
+    listMine(params?: ListMyReviewsParams): Promise<MyReview[]>;
+    /** Same as `listMine`, plus the `meta` paging counters. */
+    listMinePage(params?: ListMyReviewsParams): Promise<MyReviewsResponse>;
     /** One review per user per product. */
     create(productId: string, input: CreateReviewInput): Promise<Review>;
     /** Edits the caller's own review. */
@@ -673,6 +926,7 @@ declare class UsersResource {
     constructor(http: HttpClient);
     /** The caller's own account, read from the JWT. */
     me(): Promise<User>;
+    /** Admin only. There is no public `GET /users/{id}` — owners use `me()`. */
     get(id: string): Promise<User>;
     /** Admin only. User directory without envelope metadata. */
     list(params?: ListUsersParams): Promise<User[]>;
@@ -692,18 +946,31 @@ declare class VariantsResource {
     update(id: string, input: UpdateVariantInput): Promise<Variant>;
     /** Admin only. */
     delete(id: string): Promise<void>;
+    /** Admin only. Creates up to MAX_BULK_ITEMS SKUs for one product. */
+    createBulk(productId: string, input: BulkCreateVariantsInput): Promise<BulkCreateVariantsResponse>;
+    /** Admin only. Applies one partial patch per variant id. */
+    updateBulk(input: BulkUpdateVariantsInput): Promise<BulkUpdateVariantsResponse>;
 }
 
 /** Requires authentication. */
 declare class WishlistResource {
     private readonly http;
     constructor(http: HttpClient);
-    /** Newest first. */
-    list(): Promise<WishlistItem[]>;
+    /** Newest first (paging meta is dropped). */
+    list(params?: ListWishlistParams): Promise<WishlistItem[]>;
+    /** Same filters as `list`, plus the `meta` paging counters. */
+    listPage(params?: ListWishlistParams): Promise<WishlistListResponse>;
     /** Idempotent: re-hearting succeeds silently. */
     add(productId: string): Promise<WishlistItem>;
     /** `productId`, not the wishlist row ID. */
     remove(productId: string): Promise<StatusResponse>;
+    /** Hearts up to MAX_BULK_ITEMS products; already-hearted rows succeed. */
+    addBulk(input: BulkAddWishlistInput): Promise<BulkAddWishlistResponse>;
+    /**
+     * Unhearts by product id. `dryRun` reports `wouldDelete` without
+     * writing; already-removed rows succeed.
+     */
+    removeBulk(input: BulkRemoveWishlistInput): Promise<BulkRemoveWishlistResponse>;
 }
 
 /**
@@ -819,4 +1086,4 @@ declare function verifyStripeSignature(options: VerifyStripeSignatureOptions): P
  */
 declare function constructStripeEvent<T = Record<string, unknown>>(options: VerifyStripeSignatureOptions): Promise<StripeEvent<T>>;
 
-export { type AddCartItemInput, type ApiEnvelope, type ApiErrorCode, type ApiErrorEnvelope, type AuthStatusResponse, type Cart, type CartLine, type Category, type CategoryListResponse, type CategorySort, type CheckoutSession, type ClientErrorCode, type CreateCategoryInput, type CreateProductInput, type CreateReviewInput, type CreateVariantInput, type ErrorCode, type FetchLike, type GetStockParams, type HealthResponse, type ListCategoriesParams, type ListProductsParams, type ListUsersParams, type LoginInput, MalawiStore, MalawiStoreError, type MalawiStoreErrorInit, type MalawiStoreOptions, type Order, type OrderLine, type OrderStatus, type PageParams, type Paginated, type PaginationMeta, type PasswordResetInput, type Payment, type PaymentStatus, type Product, type ProductDetail, type ProductListResponse, type ProductSort, type ProductVariantView, type QueryParams, type QueryScalar, type QueryValue, type RegisterInput, type RequestOptions, type ReserveLineInput, type ReserveStockInput, type RetryOptions, type Review, type ReviewSummary, type Role, type SetRoleInput, type SetStockInput, type StatusResponse, type Stock, type StripeEvent, type TokenPair, type TokenState, type UpdateCategoryInput, type UpdateProductInput, type UpdateReviewInput, type UpdateVariantInput, type UploadData, type UploadFile, type User, type UserListResponse, type UserSort, type Variant, type VerifyEmailInput, type VerifyStripeSignatureOptions, type WishlistItem, type WishlistProduct, buildQuery, constructStripeEvent, createUploadForm, isMalawiStoreError, verifyStripeSignature };
+export { type AddCartItemInput, type ApiEnvelope, type ApiErrorCode, type ApiErrorEnvelope, type AuthStatusResponse, type BulkAddCartItemsInput, type BulkAddCartItemsResponse, type BulkAddWishlistInput, type BulkAddWishlistResponse, type BulkCreateProductsInput, type BulkCreateProductsResponse, type BulkCreateVariantsInput, type BulkCreateVariantsResponse, type BulkDeleteProductsInput, type BulkDeleteProductsResponse, type BulkItemError, type BulkItemStatus, type BulkOptions, type BulkProductResult, type BulkRemoveWishlistInput, type BulkRemoveWishlistResponse, type BulkResponse, type BulkResult, type BulkSetStockInput, type BulkSetStockItemInput, type BulkSetStockResponse, type BulkStockResponse, type BulkSummary, type BulkUpdateProductItem, type BulkUpdateProductsInput, type BulkUpdateProductsResponse, type BulkUpdateVariantItem, type BulkUpdateVariantsInput, type BulkUpdateVariantsResponse, type Cart, type CartLine, type CartResponse, type CartSort, type Category, type CategoryListResponse, type CategorySort, type CheckoutSession, type ClientErrorCode, type CreateCategoryInput, type CreateProductInput, type CreateReviewInput, type CreateVariantInput, type DryRunOptions, type ErrorCode, type FetchLike, type GetStockParams, type HealthResponse, type ListCartParams, type ListCategoriesParams, type ListMyReviewsParams, type ListOrdersParams, type ListProductsParams, type ListReviewsParams, type ListUsersParams, type ListWishlistParams, type LoginInput, MalawiStore, MalawiStoreError, type MalawiStoreErrorInit, type MalawiStoreOptions, type MyReview, type MyReviewProduct, type MyReviewsResponse, type Order, type OrderLine, type OrderListResponse, type OrderSort, type OrderStatus, type PageParams, type Paginated, type PaginationMeta, type PasswordResetInput, type Payment, type PaymentStatus, type Product, type ProductDetail, type ProductImage, type ProductImageList, type ProductListResponse, type ProductSort, type ProductVariantView, type QueryParams, type QueryScalar, type QueryValue, type RegisterInput, type RequestOptions, type ReserveLineInput, type ReserveStockInput, type RetryOptions, type Review, type ReviewSort, type ReviewSummary, type Role, type SetRoleInput, type SetStockInput, type StatusResponse, type Stock, type StripeEvent, type TokenPair, type TokenState, type UpdateCategoryInput, type UpdateProductInput, type UpdateReviewInput, type UpdateVariantInput, type UploadData, type UploadFile, type UploadImagesResponse, type User, type UserListResponse, type UserSort, type Variant, type VerifyEmailInput, type VerifyStripeSignatureOptions, type WishlistItem, type WishlistListResponse, type WishlistProduct, type WishlistSort, buildQuery, constructStripeEvent, createUploadForm, createUploadFormMany, isMalawiStoreError, verifyStripeSignature };