@malawistore/store-sdk 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -4,7 +4,51 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.0] - 2026-11-04
+
+### Added
+
+- Bulk admin writes: `products.bulkCreate()`, `products.bulkUpdate()`,
+  `products.bulkDelete()`, `variants.createBulk()`, `variants.updateBulk()`,
+  and `inventory.setStockBulk()`. Every method accepts `atomic`, `dryRun`,
+  and an optional `idempotencyKey`.
+- Bulk shopper writes: `cart.addItems()` (returns per-line results plus the
+  full updated cart), `wishlist.addBulk()`, and `wishlist.removeBulk()`.
+- Product gallery admin endpoints: `products.listImages()`,
+  `products.uploadImages()` (multi-file), `products.deleteImage()`, and
+  `products.setPrimaryImage()`.
+- `inventory.getStockByVariants()` batch availability read.
+- `reviews.listMine()` and `reviews.listMinePage()` for the caller's review
+  history.
+- `products.list()` / `listPage()` accept `ids` to restrict the page.
+- `BulkOptions`, `BulkResult`, `BulkResponse`, `BulkSummary`, and the new
+  bulk/gallery wire types are exported.
+
+### Fixed
+
+- `users.get()` now calls `GET /admin/users/{id}`. The previous `/users/{id}`
+  route does not exist (owners use `users.me()`; lookups are admin-only).
+- `ApiErrorCode` now includes `BULK_LIMIT_EXCEEDED`, `DUPLICATE_ITEM`, and
+  `IDEMPOTENCY_CONFLICT`.
+
+## [0.1.3] - 2026-10-29
+
+### Added
+
+- `cart.getPage()` with line filters (`q`, `product_id`, `variant_id`), sorting,
+  and paging metadata; cart totals still cover every line.
+- `orders.listPage()` with status/currency/date/total filters and sorting.
+- `wishlist.listPage()` with product search, category filtering, and sorting.
+- Review filters and paging through `reviews.summary(productId, params)`.
+- `ListCartParams`, `ListOrdersParams`, `ListWishlistParams`,
+  `ListReviewsParams`, and `CartResponse` wire types.
+
+### Changed
+
+- Storefront and shopper lists default to 12 rows per page; the admin user
+  directory still defaults to 20. Every page remains capped at 100.
+- Existing `list()`, `get()`, and `summary()` methods now accept the same
+  optional query parameters without changing their return shapes.
 
 ## [0.1.1] - 2026-10-28
 

package/README.md

@@ -115,14 +115,14 @@ several parallel queries does not rotate the token multiple times.
 | `store.auth`          | Register, login, refresh, logout, email verification, password reset |
 | `store.users`         | Current account, user lookup, role management (admin)               |
 | `store.categories`    | Taxonomy reads, admin CRUD, image upload                            |
-| `store.products`      | Catalog reads, admin CRUD, image upload                             |
-| `store.variants`      | SKU reads and admin CRUD                                            |
-| `store.cart`          | Get, add, update quantity, remove, clear                            |
-| `store.inventory`     | Stock lookup and admin set/reserve/release/confirm                  |
+| `store.products`      | Catalog reads, admin CRUD, bulk writes, image + gallery upload      |
+| `store.variants`      | SKU reads, admin CRUD, bulk create/update                           |
+| `store.cart`          | Get, add (single or bulk), update quantity, remove, clear           |
+| `store.inventory`     | Stock lookup (single or batch), bulk set, reserve/release/confirm   |
 | `store.orders`        | Checkout, list, get, cancel                                         |
 | `store.payments`      | Stripe payment intents and hosted Checkout sessions                 |
-| `store.wishlist`      | List, add, remove                                                   |
-| `store.reviews`       | Product summary, create, edit, delete, admin moderation             |
+| `store.wishlist`      | List, add, remove, bulk heart/unheart                               |
+| `store.reviews`       | Product summary, own history, create, edit, delete, moderation      |
 
 ### Auth
 
@@ -160,6 +160,9 @@ console.log(detail.product.price_cents); // 12500 → K125.00
 console.log(detail.variants);            // sellable SKUs
 
 const skus = await store.variants.list(detail.product.id);
+
+// Fetch a specific set of products (e.g. a "recently viewed" rail)
+const picked = await store.products.list({ ids: [id1, id2, id3] });
 ```
 
 For paginated grids use `listPage()`, which returns `{ data, meta }`:
@@ -183,8 +186,37 @@ page.meta; // page, limit, offset, total, total_pages, has_next, has_prev
 
 Categories support `q`, `parent_id`, `root_only`, `has_products`, `sort`,
 `page`, `limit` and `offset` through `categories.list()` or
-`categories.listPage()`. `page` wins over `offset`; the API defaults to 20
-rows and caps a page at 100.
+`categories.listPage()`. `page` wins over `offset`; storefront and shopper
+lists (products, carts, categories, orders, reviews and wishlists) default to
+12 rows. Every page is capped at 100.
+
+The shopper lists expose the same paging envelope:
+
+```ts
+const cart = await store.cart.getPage({ page: 1, sort: "newest" });
+cart.data.items; // current page; subtotal still covers the whole cart
+cart.meta;       // line-level page counters
+
+const orders = await store.orders.listPage({
+  status: "paid",
+  created_after: "2026-01-01",
+  sort: "total_desc",
+});
+const wishlist = await store.wishlist.listPage({ q: "oil", sort: "price_asc" });
+
+const reviews = await store.reviews.summary(productId, {
+  rating: 5,
+  sort: "highest",
+  page: 1,
+  limit: 12,
+});
+reviews.meta; // filtered review page counters
+
+// The caller's own review history (with product context)
+const mine = await store.reviews.listMine({ sort: "newest" });
+const minePage = await store.reviews.listMinePage({ page: 1, limit: 12 });
+minePage.meta;
+```
 
 Variant rows include `available` (on-hand minus reservations) and `in_stock`,
 both in the product detail and `/products/:id/variants` responses.
@@ -198,6 +230,18 @@ tambala; the API converts those at charge time.
 ```ts
 await store.cart.addItem({ product_id: "…", qty: 2 });
 await store.cart.addItem({ product_id: "…", variant_id: "…", qty: 1 });
+
+// Batch add: per-line results plus the full updated cart
+const bulk = await store.cart.addItems({
+  atomic: true,
+  items: [
+    { product_id: "…", qty: 2 },
+    { product_id: "…", variant_id: "…", qty: 1 },
+  ],
+});
+bulk.results; // [{ index, id, status, data, error? }]
+bulk.cart;    // no follow-up GET needed
+
 await store.cart.setQty("cart-line-id", 3);
 await store.cart.removeItem("cart-line-id");
 
@@ -231,6 +275,10 @@ await store.wishlist.add(productId);
 const wishlist = await store.wishlist.list();
 await store.wishlist.remove(productId); // product ID, not row ID
 
+// Batch heart / unheart (idempotent; already-hearted rows succeed)
+await store.wishlist.addBulk({ productIds: [id1, id2] });
+await store.wishlist.removeBulk({ ids: [id1, id2], dryRun: false });
+
 const summary = await store.reviews.summary(productId);
 await store.reviews.create(productId, { rating: 5, title: "Great", body: "…" });
 await store.reviews.update(reviewId, { rating: 4 });
@@ -256,6 +304,38 @@ await store.inventory.setStock({ product_id: product.id, qty: 50 });
 await store.users.setRole(userId, { role: "admin" });
 await store.reviews.deleteAny(reviewId); // moderation
 
+// Bulk product + variant + stock writes. Per-item failures stay inside
+// the 200 envelope; atomic rolls the whole batch back.
+await store.products.bulkCreate({ items: [draft1, draft2] });
+await store.products.bulkUpdate({
+  updates: [{ id: productId, patch: { is_active: false } }],
+});
+await store.products.bulkDelete({ ids: [id1, id2], dryRun: true });
+
+await store.variants.createBulk(product.id, { items: [sku1, sku2] });
+await store.variants.updateBulk({
+  updates: [{ id: skuId, patch: { price_cents: 2500 } }],
+});
+
+await store.inventory.setStockBulk({
+  atomic: true,
+  items: [
+    { product_id: id1, qty: 50 },
+    { product_id: id1, variant_id: skuId, qty: 20 },
+  ],
+});
+
+// Batch availability read; unknown ids land in `notFound`
+const stock = await store.inventory.getStockByVariants([skuId, otherSkuId]);
+stock.stock;
+stock.notFound;
+
+// Bulk writes accept an optional replay-safe key (24h window)
+await store.products.bulkCreate({
+  idempotencyKey: "catalog-import-2026-11-04",
+  items: [draft1, draft2],
+});
+
 // Admin user directory: filters + pagination
 const users = await store.users.list({ role: "customer", q: "aisha", sort: "newest" });
 const page = await store.users.listPage({ email_verified: false, page: 1, limit: 50 });
@@ -272,6 +352,12 @@ Cloudinary finishes. The method resolves as soon as the job is accepted.
 const file = fileInput.files![0];
 await store.products.uploadImage(productId, file);
 
+// Gallery: list, batch upload, reorder/primary, delete
+const images = await store.products.listImages(productId);
+await store.products.uploadImages(productId, [file, otherFile]); // up to 20
+await store.products.setPrimaryImage(productId, images[0].id);
+await store.products.deleteImage(productId, images[0].id);
+
 // Node: wrap a Buffer
 import { readFile } from "node:fs/promises";
 const data = await readFile("./photo.jpg");

package/dist/index.cjs

@@ -433,6 +433,11 @@ var AuthResource = class {
   }
 };
 
+// src/headers.ts
+function idempotencyHeaders(key) {
+  return key ? { "Idempotency-Key": key } : void 0;
+}
+
 // src/path.ts
 function segment(value) {
   return encodeURIComponent(value);
@@ -444,9 +449,34 @@ var CartResource = class {
     this.http = http;
   }
   http;
-  /** Active cart, created empty on first use. */
-  get() {
-    return this.http.request("GET", "/cart");
+  /** Active cart, created empty on first use (paging meta is dropped). */
+  get(params = {}) {
+    return this.http.request("GET", "/cart", {
+      query: {
+        q: params.q,
+        product_id: params.product_id,
+        variant_id: params.variant_id,
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      }
+    });
+  }
+  /** Same as `get`, plus the `meta` paging counters. */
+  getPage(params = {}) {
+    return this.http.request("GET", "/cart", {
+      query: {
+        q: params.q,
+        product_id: params.product_id,
+        variant_id: params.variant_id,
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      },
+      unwrap: false
+    });
   }
   /** Validates against the catalog and snapshots the current price. */
   addItem(input) {
@@ -455,6 +485,22 @@ var CartResource = class {
       retry: false
     });
   }
+  /**
+   * Adds up to MAX_BULK_ITEMS lines in one request. Per-line results carry
+   * the written line, plus the full updated cart.
+   */
+  addItems(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "POST",
+      "/cart/items/bulk",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
   /** `qty: 0` removes the line. */
   setQty(itemId, qty) {
     return this.http.request(
@@ -477,12 +523,11 @@ var CartResource = class {
 };
 
 // src/upload.ts
-function createUploadForm(file, field = "file") {
-  const form = new FormData();
+function appendFile(form, file, field) {
   if (typeof Blob !== "undefined" && file instanceof Blob) {
     const name = typeof File !== "undefined" && file instanceof File ? file.name : "upload";
     form.append(field, file, name);
-    return form;
+    return;
   }
   if (typeof file !== "object" || file === null || !("data" in file) || typeof file.name !== "string") {
     throw new TypeError(
@@ -493,6 +538,19 @@ function createUploadForm(file, field = "file") {
     type: file.type ?? "application/octet-stream"
   });
   form.append(field, blob, file.name);
+}
+function createUploadForm(file, field = "file") {
+  const form = new FormData();
+  appendFile(form, file, field);
+  return form;
+}
+function createUploadFormMany(files, field = "files") {
+  const list = Array.isArray(files) ? files : [files];
+  if (list.length === 0) {
+    throw new TypeError("At least one UploadFile is required");
+  }
+  const form = new FormData();
+  for (const file of list) appendFile(form, file, field);
   return form;
 }
 
@@ -597,6 +655,21 @@ var InventoryResource = class {
       }
     });
   }
+  /**
+   * Reads availability for up to MAX_BULK_ITEMS variants in one request.
+   * Unknown ids are returned in `notFound` instead of failing.
+   */
+  getStockByVariants(variantIds) {
+    return this.http.request(
+      "GET",
+      "/admin/inventory/stock",
+      {
+        query: {
+          variantIds: Array.isArray(variantIds) ? variantIds : [variantIds]
+        }
+      }
+    );
+  }
   /** Upserts the on-hand quantity (restocking). */
   setStock(input) {
     return this.http.request("POST", "/admin/inventory/stock", {
@@ -604,6 +677,19 @@ var InventoryResource = class {
       retry: false
     });
   }
+  /** Sets on-hand stock for many SKUs; `atomic` commits all or none. */
+  setStockBulk(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "POST",
+      "/admin/inventory/stock/bulk",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
   /** Holds all lines atomically; one short line fails the whole order. */
   reserve(input) {
     return this.http.request(
@@ -645,9 +731,40 @@ var OrdersResource = class {
       retry: false
     });
   }
-  /** Newest first. */
-  list() {
-    return this.http.request("GET", "/orders");
+  /** Newest first (paging meta is dropped). */
+  list(params = {}) {
+    return this.http.request("GET", "/orders", {
+      query: {
+        status: params.status,
+        currency: params.currency,
+        created_after: params.created_after,
+        created_before: params.created_before,
+        min_total_cents: params.min_total_cents,
+        max_total_cents: params.max_total_cents,
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      }
+    });
+  }
+  /** Same filters as `list`, plus the `meta` paging counters. */
+  listPage(params = {}) {
+    return this.http.request("GET", "/orders", {
+      query: {
+        status: params.status,
+        currency: params.currency,
+        created_after: params.created_after,
+        created_before: params.created_before,
+        min_total_cents: params.min_total_cents,
+        max_total_cents: params.max_total_cents,
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      },
+      unwrap: false
+    });
   }
   get(id) {
     return this.http.request("GET", `/orders/${segment(id)}`);
@@ -701,6 +818,7 @@ var ProductsResource = class {
     return this.http.request("GET", "/products", {
       query: {
         q: params.q,
+        ids: params.ids,
         category_id: params.category_id,
         category_slug: params.category_slug,
         min_price_cents: params.min_price_cents,
@@ -724,6 +842,7 @@ var ProductsResource = class {
     return this.http.request("GET", "/products", {
       query: {
         q: params.q,
+        ids: params.ids,
         category_id: params.category_id,
         category_slug: params.category_slug,
         min_price_cents: params.min_price_cents,
@@ -789,6 +908,86 @@ var ProductsResource = class {
       { form: createUploadForm(file), retry: false }
     );
   }
+  /**
+   * Admin only. Creates products in bulk. Per-item failures stay inside
+   * the 200 envelope; `atomic` rolls the whole batch back.
+   */
+  bulkCreate(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "POST",
+      "/admin/products/bulk",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
+  /** Admin only. Applies one partial patch per product id. */
+  bulkUpdate(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "PATCH",
+      "/admin/products/bulk",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
+  /**
+   * Admin only. POST rather than DELETE so the id list can travel in JSON.
+   * `dryRun` reports `wouldDelete` without writing.
+   */
+  bulkDelete(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "POST",
+      "/admin/products/bulk-delete",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
+  /** Admin only. Gallery rows, including uploads still queued (empty url). */
+  async listImages(id) {
+    const result = await this.http.request(
+      "GET",
+      `/admin/products/${segment(id)}/images`
+    );
+    return result.images;
+  }
+  /**
+   * Admin only. Multipart with repeated `files` parts (up to 20 per
+   * request). Each accepted file is queued asynchronously (HTTP 202).
+   */
+  async uploadImages(id, files) {
+    return this.http.request(
+      "POST",
+      `/admin/products/${segment(id)}/images`,
+      { form: createUploadFormMany(files), retry: false }
+    );
+  }
+  /** Admin only. Promotes the next ready image when the primary is deleted. */
+  deleteImage(id, imageId) {
+    return this.http.request(
+      "DELETE",
+      `/admin/products/${segment(id)}/images/${segment(imageId)}`,
+      { retry: false }
+    );
+  }
+  /** Admin only. Points the storefront primary image at one gallery row. */
+  setPrimaryImage(id, imageId) {
+    return this.http.request(
+      "PUT",
+      `/admin/products/${segment(id)}/images/${segment(imageId)}/primary`,
+      { retry: false }
+    );
+  }
 };
 
 // src/resources/reviews.ts
@@ -797,14 +996,47 @@ var ReviewsResource = class {
     this.http = http;
   }
   http;
-  /** Public aggregate plus the newest reviews for a product. */
-  summary(productId) {
+  /** Public aggregate plus one filtered review page (`summary.meta`). */
+  summary(productId, params = {}) {
     return this.http.request(
       "GET",
       `/products/${segment(productId)}/reviews`,
-      { skipAuth: true }
+      {
+        query: {
+          q: params.q,
+          rating: params.rating,
+          sort: params.sort,
+          page: params.page,
+          limit: params.limit,
+          offset: params.offset
+        },
+        skipAuth: true
+      }
     );
   }
+  /** The caller's own reviews with product context (paging meta dropped). */
+  listMine(params = {}) {
+    return this.http.request("GET", "/reviews/me", {
+      query: {
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      }
+    });
+  }
+  /** Same as `listMine`, plus the `meta` paging counters. */
+  listMinePage(params = {}) {
+    return this.http.request("GET", "/reviews/me", {
+      query: {
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      },
+      unwrap: false
+    });
+  }
   /** One review per user per product. */
   create(productId, input) {
     return this.http.request(
@@ -849,8 +1081,9 @@ var UsersResource = class {
   me() {
     return this.http.request("GET", "/users/me");
   }
+  /** Admin only. There is no public `GET /users/{id}` — owners use `me()`. */
   get(id) {
-    return this.http.request("GET", `/users/${segment(id)}`);
+    return this.http.request("GET", `/admin/users/${segment(id)}`);
   }
   /** Admin only. User directory without envelope metadata. */
   list(params = {}) {
@@ -930,6 +1163,32 @@ var VariantsResource = class {
       { retry: false }
     );
   }
+  /** Admin only. Creates up to MAX_BULK_ITEMS SKUs for one product. */
+  createBulk(productId, input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "POST",
+      `/products/${segment(productId)}/variants/bulk`,
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
+  /** Admin only. Applies one partial patch per variant id. */
+  updateBulk(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "PATCH",
+      "/admin/variants/bulk",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
 };
 
 // src/resources/wishlist.ts
@@ -938,9 +1197,32 @@ var WishlistResource = class {
     this.http = http;
   }
   http;
-  /** Newest first. */
-  list() {
-    return this.http.request("GET", "/wishlist");
+  /** Newest first (paging meta is dropped). */
+  list(params = {}) {
+    return this.http.request("GET", "/wishlist", {
+      query: {
+        q: params.q,
+        category_id: params.category_id,
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      }
+    });
+  }
+  /** Same filters as `list`, plus the `meta` paging counters. */
+  listPage(params = {}) {
+    return this.http.request("GET", "/wishlist", {
+      query: {
+        q: params.q,
+        category_id: params.category_id,
+        sort: params.sort,
+        page: params.page,
+        limit: params.limit,
+        offset: params.offset
+      },
+      unwrap: false
+    });
   }
   /** Idempotent: re-hearting succeeds silently. */
   add(productId) {
@@ -957,6 +1239,35 @@ var WishlistResource = class {
       { retry: false }
     );
   }
+  /** Hearts up to MAX_BULK_ITEMS products; already-hearted rows succeed. */
+  addBulk(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "POST",
+      "/wishlist/bulk",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
+  /**
+   * Unhearts by product id. `dryRun` reports `wouldDelete` without
+   * writing; already-removed rows succeed.
+   */
+  removeBulk(input) {
+    const { idempotencyKey, ...body } = input;
+    return this.http.request(
+      "POST",
+      "/wishlist/bulk-delete",
+      {
+        body,
+        headers: idempotencyHeaders(idempotencyKey),
+        retry: false
+      }
+    );
+  }
 };
 
 // src/client.ts
@@ -1118,6 +1429,7 @@ exports.MalawiStoreError = MalawiStoreError;
 exports.buildQuery = buildQuery;
 exports.constructStripeEvent = constructStripeEvent;
 exports.createUploadForm = createUploadForm;
+exports.createUploadFormMany = createUploadFormMany;
 exports.isMalawiStoreError = isMalawiStoreError;
 exports.verifyStripeSignature = verifyStripeSignature;
 //# sourceMappingURL=index.cjs.map