@tallyui/connector-woocommerce 3.0.4 → 3.1.1

package/README.md

@@ -35,6 +35,15 @@ The incremental pull can miss an edit: a `modified_after` that over-excludes (in
 - When `wcpos/v2/status` lists `products_id_fast_path` in `capabilities`, the whole catalogue is listed in one request (`per_page=-1` with `_fields=id,date_modified_gmt,stock_quantity,stock_status`) instead of pages of 100; a store that refuses it (a 400) is listed page by page in the same pass.
 - Both listings key on the numeric product id, never the till-local uuid; the adapter's `matchKey` is how the runner finds the till's copy.
 
+## Customers
+
+On WCPOS 1.10.x, `searchCustomers` uses `GET wcpos/v2/customers` with `role=customer`.
+`getCustomer` uses the same route with `include=<id>&per_page=1&role=all`; there is no per-id route.
+`createCustomer` uses `POST wcpos/v2/push/customers`. Create is idempotent per call through the WCPOS mutation id;
+a repeat call after a lost answer uses new ids and gives `invalid` (email exists). There is no automatic retry.
+`emailReceipt` uses `POST wcpos/v2/orders/<id>/email`, optionally saving the email to billing.
+It is not idempotent: each call sends a mail, so don't auto-retry. The cashier needs `access_woocommerce_pos`.
+
 ## Errors
 
 - `ConnectorUnauthorizedError`, from `@tallyui/core` and re-exported here: the store refused the request (401: the token is missing, expired or revoked; 403: signed in but not allowed), or `WooMissingTokenError` (a subclass) was thrown for a missing token. `error.status` is `401` (`code: 'unauthorized'`, sign in again) or `403` (`code: 'forbidden'`, signed in but not allowed: the pull retries on the store schedule; don't sign out).

package/dist/index.d.ts

@@ -1,7 +1,34 @@
-import { OrderCreateEnvelope, CommandResult, ProductTraits, CollectionSync, ReplicationAdapter, ReconcileFeed, CatalogueReconcileAdapter, ConnectorUnauthorizedError, TallyConnector } from '@tallyui/core';
+import { SyncContext, Customer, CustomerInput, OrderCreateEnvelope, CommandResult, ProductTraits, CollectionSync, ReplicationAdapter, ReconcileFeed, CatalogueReconcileAdapter, ConnectorUnauthorizedError, TallyConnector } from '@tallyui/core';
 export { ConnectorUnauthorizedError } from '@tallyui/core';
 import { RxJsonSchema } from 'rxdb';
 
+type WooCustomerRow = {
+    id: number | string;
+    first_name?: string | null;
+    last_name?: string | null;
+    email?: string | null;
+    billing?: {
+        first_name?: string | null;
+        last_name?: string | null;
+        email?: string | null;
+        phone?: string | null;
+        company?: string | null;
+    } | null;
+};
+declare function toWooCustomer(raw: WooCustomerRow): Customer;
+declare function createWooCustomers(options?: {
+    newId?: () => string;
+}): {
+    searchCustomers(context: SyncContext, query: string, options?: {
+        limit?: number;
+    }): Promise<Customer[]>;
+    getCustomer(context: SyncContext, id: string): Promise<Customer | null>;
+    createCustomer(context: SyncContext, input: CustomerInput): Promise<Customer>;
+    emailReceipt(context: SyncContext, orderId: string, email: string, options?: {
+        saveToBilling?: boolean;
+    }): Promise<void>;
+};
+
 type WooTransportOutcome = {
     kind: 'results';
     results: CommandResult[];
@@ -171,4 +198,4 @@ declare function createWooCommerceConnector(): TallyConnector;
  */
 declare const woocommerceConnector: TallyConnector;
 
-export { type WooCommandTransportOptions, WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, WooTokenRefusedError, createWooCommandTransport, createWooCommerceConnector, toWooOrderPayload, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };
+export { type WooCommandTransportOptions, WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, WooTokenRefusedError, createWooCommandTransport, createWooCommerceConnector, createWooCustomers, toWooCustomer, toWooOrderPayload, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };

package/dist/index.js

@@ -592,8 +592,109 @@ function createWooReconcileFeed() {
   return createReconcileFeed({ key: (doc) => doc.uuid, remote: (doc) => doc.id, fetchByIds: wooFetchByIds });
 }
 
+// src/customers.ts
+import { CustomerServiceError } from "@tallyui/core";
+function toWooCustomer(raw) {
+  const customer = { id: String(raw.id), name: String(raw.id) };
+  for (const [key, value] of [
+    ["firstName", raw.first_name || raw.billing?.first_name],
+    ["lastName", raw.last_name || raw.billing?.last_name],
+    ["email", raw.email || raw.billing?.email],
+    ["phone", raw.billing?.phone],
+    ["company", raw.billing?.company]
+  ]) {
+    if (typeof value === "string" && value.length > 0) customer[key] = value;
+  }
+  customer.name = [customer.firstName, customer.lastName].filter(Boolean).join(" ") || customer.company || customer.email || customer.id;
+  return customer;
+}
+function newWooId() {
+  if (!globalThis.crypto?.getRandomValues) throw new Error("connector-woocommerce: no random source");
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+async function customerRequest(context, route, init = {}) {
+  let response;
+  try {
+    response = await fetch(`${context.baseUrl}/${route}`, {
+      ...init,
+      headers: { ...init.headers, ...context.headers },
+      signal: context.signal
+    });
+  } catch (error) {
+    throw new CustomerServiceError("network", error instanceof Error ? error.message : String(error));
+  }
+  if ([401, 403, 426].includes(response.status)) await checkResponse(response);
+  const body = await response.json().catch(() => void 0);
+  if (!response.ok) {
+    const invalid = [400, 404, 422].includes(response.status);
+    throw new CustomerServiceError(invalid ? "invalid" : "server", invalid ? body?.message ?? `HTTP ${response.status}` : `HTTP ${response.status}`);
+  }
+  return { status: response.status, body };
+}
+function createWooCustomers(options) {
+  const newId = options?.newId ?? newWooId;
+  return {
+    async searchCustomers(context, query, options2) {
+      const q = query.trim();
+      if (!q) return [];
+      const params = new URLSearchParams({ search: q, role: "customer", per_page: String(Math.max(1, Math.min(50, options2?.limit ?? 20))) });
+      const { body } = await customerRequest(context, `customers?${params}`, { method: "GET" });
+      if (!Array.isArray(body)) throw new CustomerServiceError("server", "unexpected response");
+      return body.map(toWooCustomer);
+    },
+    async getCustomer(context, id) {
+      if (!/^\d+$/.test(id)) return null;
+      const params = new URLSearchParams({ include: id, per_page: "1", role: "all" });
+      const { body } = await customerRequest(context, `customers?${params}`, { method: "GET" });
+      if (!Array.isArray(body)) throw new CustomerServiceError("server", "unexpected response");
+      const raw = body.find((row) => String(row.id) === id);
+      return raw ? toWooCustomer(raw) : null;
+    },
+    async createCustomer(context, input) {
+      const mutationId = newId();
+      const recordId = newId();
+      const fields = {
+        ...input.email ? { email: input.email } : {},
+        ...input.firstName ? { first_name: input.firstName } : {},
+        ...input.lastName ? { last_name: input.lastName } : {}
+      };
+      const { status, body } = await customerRequest(context, "push/customers", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          mutationId,
+          operation: "create",
+          collection: "customers",
+          recordId,
+          baseRevision: null,
+          payload: { ...fields, billing: {
+            ...fields,
+            ...input.phone ? { phone: input.phone } : {},
+            ...input.company ? { company: input.company } : {}
+          } }
+        })
+      });
+      if (status !== 200 && status !== 201 || !body?.document) throw new CustomerServiceError("server", "unexpected response");
+      return toWooCustomer(body.document);
+    },
+    async emailReceipt(context, orderId, email, options2) {
+      if (!/^[1-9]\d*$/.test(orderId)) throw new CustomerServiceError("invalid", "Invalid order ID");
+      const { status, body } = await customerRequest(context, `orders/${encodeURIComponent(orderId)}/email`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email, ...options2?.saveToBilling ? { save_to: "billing" } : {} })
+      });
+      if (status !== 200 || body?.success !== true) throw new CustomerServiceError("server", "unexpected response");
+    }
+  };
+}
+
 // package.json
-var version = "3.0.4";
+var version = "3.1.1";
 
 // src/commands/transport.ts
 import { minorUnitDigits, moneyFromDecimalString, moneyFromMajor as moneyFromMajor2 } from "@tallyui/core";
@@ -738,8 +839,11 @@ var WooMissingTokenError = class extends ConnectorUnauthorizedError2 {
 };
 function createWooCommerceConnector() {
   const catalogueFeed = createWooReconcileFeed();
+  const customers = createWooCustomers();
   return {
     ...wooConnectorParts,
+    // WCPOS wcpos/v2/customers, push/customers and orders/<id>/email.
+    ...customers,
     replication: {
       // One replication per collection; the reconcile feed is last, so its fetch wins duplicates;
       // duplicates are matched by uuid, the primary key, not the store id (#331). legacyKey
@@ -809,6 +913,8 @@ export {
   WooTokenRefusedError,
   createWooCommandTransport,
   createWooCommerceConnector,
+  createWooCustomers,
+  toWooCustomer,
   toWooOrderPayload,
   wcposClientPart,
   wooCatalogueReconcile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-woocommerce",
-  "version": "3.0.4",
+  "version": "3.1.1",
   "type": "module",
   "description": "WooCommerce connector for Tally UI",
   "main": "./dist/index.js",
@@ -26,10 +26,10 @@
     "directory": "connectors/woocommerce"
   },
   "peerDependencies": {
-    "@tallyui/core": "^3.0.4"
+    "@tallyui/core": "^3.1.1"
   },
   "devDependencies": {
-    "@tallyui/database": "3.0.4",
+    "@tallyui/database": "3.1.1",
     "rxdb": "17.5.0"
   },
   "scripts": {

package/src/customers.ts

@@ -0,0 +1,107 @@
+import { CustomerServiceError, type Customer, type CustomerInput, type SyncContext } from '@tallyui/core';
+import { checkResponse } from './replication/products';
+
+type WooCustomerRow = {
+  id: number | string;
+  first_name?: string | null;
+  last_name?: string | null;
+  email?: string | null;
+  billing?: {
+    first_name?: string | null; last_name?: string | null; email?: string | null;
+    phone?: string | null; company?: string | null;
+  } | null;
+};
+
+export function toWooCustomer(raw: WooCustomerRow): Customer {
+  const customer: Customer = { id: String(raw.id), name: String(raw.id) };
+  for (const [key, value] of [
+    ['firstName', raw.first_name || raw.billing?.first_name],
+    ['lastName', raw.last_name || raw.billing?.last_name],
+    ['email', raw.email || raw.billing?.email],
+    ['phone', raw.billing?.phone], ['company', raw.billing?.company],
+  ] as const) {
+    if (typeof value === 'string' && value.length > 0) customer[key] = value;
+  }
+  customer.name = [customer.firstName, customer.lastName].filter(Boolean).join(' ') || customer.company || customer.email || customer.id;
+  return customer;
+}
+
+function newWooId(): string {
+  if (!globalThis.crypto?.getRandomValues) throw new Error('connector-woocommerce: no random source');
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+async function customerRequest(context: SyncContext, route: string, init: RequestInit = {}) {
+  let response: Response;
+  try {
+    response = await fetch(`${context.baseUrl}/${route}`, {
+      ...init, headers: { ...init.headers, ...context.headers }, signal: context.signal,
+    });
+  } catch (error) {
+    throw new CustomerServiceError('network', error instanceof Error ? error.message : String(error));
+  }
+  if ([401, 403, 426].includes(response.status)) await checkResponse(response);
+  const body = await response.json().catch(() => undefined);
+  if (!response.ok) {
+    const invalid = [400, 404, 422].includes(response.status);
+    throw new CustomerServiceError(invalid ? 'invalid' : 'server', invalid ? body?.message ?? `HTTP ${response.status}` : `HTTP ${response.status}`);
+  }
+  return { status: response.status, body };
+}
+
+export function createWooCustomers(options?: { newId?: () => string }) {
+  const newId = options?.newId ?? newWooId;
+  return {
+    async searchCustomers(context: SyncContext, query: string, options?: { limit?: number }): Promise<Customer[]> {
+      const q = query.trim();
+      if (!q) return [];
+      const params = new URLSearchParams({ search: q, role: 'customer', per_page: String(Math.max(1, Math.min(50, options?.limit ?? 20))) });
+      const { body } = await customerRequest(context, `customers?${params}`, { method: 'GET' });
+      if (!Array.isArray(body)) throw new CustomerServiceError('server', 'unexpected response');
+      return body.map(toWooCustomer);
+    },
+
+    async getCustomer(context: SyncContext, id: string): Promise<Customer | null> {
+      if (!/^\d+$/.test(id)) return null;
+      const params = new URLSearchParams({ include: id, per_page: '1', role: 'all' });
+      const { body } = await customerRequest(context, `customers?${params}`, { method: 'GET' });
+      if (!Array.isArray(body)) throw new CustomerServiceError('server', 'unexpected response');
+      const raw = body.find((row: WooCustomerRow) => String(row.id) === id);
+      return raw ? toWooCustomer(raw) : null;
+    },
+
+    async createCustomer(context: SyncContext, input: CustomerInput): Promise<Customer> {
+      const mutationId = newId();
+      const recordId = newId();
+      const fields = {
+        ...(input.email ? { email: input.email } : {}),
+        ...(input.firstName ? { first_name: input.firstName } : {}),
+        ...(input.lastName ? { last_name: input.lastName } : {}),
+      };
+      const { status, body } = await customerRequest(context, 'push/customers', {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          mutationId, operation: 'create', collection: 'customers', recordId, baseRevision: null,
+          payload: { ...fields, billing: {
+            ...fields, ...(input.phone ? { phone: input.phone } : {}), ...(input.company ? { company: input.company } : {}),
+          } },
+        }),
+      });
+      if ((status !== 200 && status !== 201) || !body?.document) throw new CustomerServiceError('server', 'unexpected response');
+      return toWooCustomer(body.document);
+    },
+
+    async emailReceipt(context: SyncContext, orderId: string, email: string, options?: { saveToBilling?: boolean }): Promise<void> {
+      if (!/^[1-9]\d*$/.test(orderId)) throw new CustomerServiceError('invalid', 'Invalid order ID');
+      const { status, body } = await customerRequest(context, `orders/${encodeURIComponent(orderId)}/email`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, ...(options?.saveToBilling ? { save_to: 'billing' } : {}) }),
+      });
+      if (status !== 200 || body?.success !== true) throw new CustomerServiceError('server', 'unexpected response');
+    },
+  };
+}

package/src/index.ts

@@ -6,6 +6,7 @@ import { wooProductSync } from './sync/products';
 import { wooProductReplication } from './replication/products';
 import { wooCatalogueReconcile } from './reconcile/catalogue';
 import { createWooReconcileFeed, MAX_IDS_PER_REQUEST } from './reconcile/feed';
+import { createWooCustomers } from './customers';
 import { version } from '../package.json';
 
 /** One part of X-WCPOS-Client as WCPOS keeps it: lowercase [a-z0-9._-], at most 32 characters. */
@@ -41,8 +42,11 @@ export class WooMissingTokenError extends ConnectorUnauthorizedError {
 export function createWooCommerceConnector(): TallyConnector {
   // The catalogue reconcile's corrections reach `products` only through this pull adapter (#248).
   const catalogueFeed = createWooReconcileFeed();
+  const customers = createWooCustomers();
   return {
     ...wooConnectorParts,
+    // WCPOS wcpos/v2/customers, push/customers and orders/<id>/email.
+    ...customers,
     replication: {
       // One replication per collection; the reconcile feed is last, so its fetch wins duplicates;
       // duplicates are matched by uuid, the primary key, not the store id (#331). legacyKey
@@ -115,6 +119,7 @@ const wooConnectorParts = {
 export const woocommerceConnector: TallyConnector = createWooCommerceConnector();
 
 // Re-export pieces for advanced usage
+export { createWooCustomers, toWooCustomer } from './customers';
 export { createWooCommandTransport, toWooOrderPayload, type WooCommandTransportOptions } from './commands/transport';
 export { ConnectorUnauthorizedError } from '@tallyui/core';
 export { wooProductSchema } from './schemas/products';