perspectapi-ts-sdk 6.5.9 → 7.0.1

package/src/v2/client/orders-client.ts

@@ -19,15 +19,49 @@ import type {
 export class OrdersV2Client extends BaseV2Client {
 
   async list(siteName: string, params?: V2OrderListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Order>> {
-    return this.getList<V2Order>(this.sitePath(siteName, 'orders'), params, cachePolicy);
+    return this.getList<V2Order>(
+      this.sitePath(siteName, 'orders'),
+      params,
+      this.withOrderTags(siteName, cachePolicy, {
+        fulfillmentStatus: params?.fulfillment_status,
+      }),
+    );
   }
 
-  async *listAutoPaginated(siteName: string, params?: Omit<V2OrderListParams, 'starting_after' | 'ending_before'>) {
-    yield* this.listAutoPaginate<V2Order>(this.sitePath(siteName, 'orders'), params);
+  async *listAutoPaginated(
+    siteName: string,
+    params?: Omit<V2OrderListParams, 'starting_after' | 'ending_before'>,
+    cachePolicy?: CachePolicy,
+  ) {
+    let startingAfter: string | undefined;
+    let hasMore = true;
+
+    while (hasMore) {
+      const queryParams: V2OrderListParams = { ...(params ?? {}) };
+      if (startingAfter) {
+        queryParams.starting_after = startingAfter;
+      }
+
+      const page = await this.list(siteName, queryParams, cachePolicy);
+      for (const item of page.data) {
+        yield item;
+      }
+
+      hasMore = page.has_more;
+      if (page.data.length > 0) {
+        startingAfter = page.data[page.data.length - 1].id;
+      } else {
+        hasMore = false;
+      }
+    }
   }
 
   async get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Order> {
-    return this.getOne<V2Order>(this.sitePath(siteName, 'orders', id), undefined, cachePolicy);
+    return this.getOne<V2Order>(
+      this.sitePath(siteName, 'orders', id),
+      undefined,
+      this.withOrderTags(siteName, cachePolicy, { id }),
+    );
   }
 
   /**
@@ -47,15 +81,64 @@ export class OrdersV2Client extends BaseV2Client {
     );
   }
 
-  /** Update fulfillment status, tracking number, and/or notes on an order. */
+  /**
+   * Update fulfillment status, tracking number, and/or notes on an order.
+   *
+   * Set `notify_customer: true` when moving the order into a terminal
+   * fulfillment state to send the customer fulfillment email.
+   */
   async updateFulfillment(
     siteName: string,
     id: string,
     data: V2OrderFulfillmentUpdate,
   ): Promise<V2Order> {
-    return this.patchOne<V2Order>(
+    const result = await this.patchOne<V2Order>(
       this.sitePath(siteName, 'orders', `${id}/fulfillment`),
       data,
     );
+    await this.invalidateCache({
+      tags: this.buildOrderTags(siteName, { id }),
+      keys: [this.sitePath(siteName, 'orders', id)],
+    });
+    return result;
+  }
+
+  private withOrderTags(
+    siteName: string,
+    cachePolicy: CachePolicy | undefined,
+    options: { id?: string; fulfillmentStatus?: string | null } = {},
+  ): CachePolicy {
+    const tags = new Set<string>(cachePolicy?.tags ?? []);
+    for (const tag of this.buildOrderTags(siteName, options)) {
+      tags.add(tag);
+    }
+
+    return {
+      ...cachePolicy,
+      tags: Array.from(tags),
+    };
+  }
+
+  private buildOrderTags(
+    siteName: string,
+    options: { id?: string; fulfillmentStatus?: string | null } = {},
+  ): string[] {
+    const tags = new Set<string>(['orders', `orders:site:${siteName}`]);
+    if (options.id) {
+      tags.add(`orders:id:${options.id}`);
+    }
+
+    const fulfillmentStatus = this.normalizeTagPart(options.fulfillmentStatus);
+    if (fulfillmentStatus) {
+      tags.add(`orders:fulfillment:${siteName}:${fulfillmentStatus}`);
+    }
+
+    return Array.from(tags);
+  }
+
+  private normalizeTagPart(value?: string | null): string | null {
+    if (!value) return null;
+    const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+    return normalized || null;
   }
 }

package/src/v2/types.ts

@@ -253,6 +253,7 @@ export interface V2Order extends V2Object {
 
 export interface V2OrderListParams extends V2PaginationParams {
   status?: string;
+  fulfillment_status?: string;
   customer_email?: string;
   date_from?: string;
   date_to?: string;
@@ -327,6 +328,8 @@ export interface V2OrderFulfillmentUpdate {
   fulfillment_status: string;
   tracking_number?: string;
   notes?: string;
+  /** When true, a terminal fulfillment status triggers a customer email. */
+  notify_customer?: boolean;
 }
 
 export interface V2OrderCreateResult extends V2Object {