@tallyui/connector-vendure 3.0.2 → 3.0.4

package/README.md

@@ -5,3 +5,13 @@
 Requests with expired or rejected credentials reject with `ConnectorUnauthorizedError`, defined in `@tallyui/core` and re-exported by this connector. `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); a signed-out Vendure session is always `401`.
 
 Sign-in itself rejects with `SignInError`.
+
+## Customers
+
+`searchCustomers`, `createCustomer` and `getCustomer` are online only and run in the session's channel, selected by the `vendure-token` header.
+
+The till's administrator needs `ReadCustomer` to search and look up customers, and `CreateCustomer` to create them. Without these permissions, the calls reject with `ConnectorUnauthorizedError` status `403`.
+
+A duplicate email rejects with `CustomerServiceError` code `invalid`. The vendurepos walk-in customer is left out of search results.
+
+Vendure's `CreateCustomerInput` requires `firstName` and `lastName`; leaving them out fails GraphQL input validation (recorded on Vendure 3.7.3). So `createCustomer` with only an email sends both as `''`, which Vendure 3.7.3 accepts: it creates the customer with empty names, and the till shows its email as the name.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConnectorAuth, ProductTraits, CollectionSync, ReplicationAdapter, StockReconcileAdapter, SyncContext, StoreSettingsChoice, StoreSettings, TallyConnector } from '@tallyui/core';
+import { ConnectorAuth, ProductTraits, CollectionSync, ReplicationAdapter, StockReconcileAdapter, SyncContext, StoreSettingsChoice, StoreSettings, CustomerInput, Customer, TallyConnector } from '@tallyui/core';
 export { ConnectorUnauthorizedError } from '@tallyui/core';
 import { RxJsonSchema } from 'rxdb';
 
@@ -101,6 +101,19 @@ declare function vendureGlobalStockSettings(context: SyncContext): Promise<{
     outOfStockThreshold: number;
 }>;
 
+declare function toVendureCustomer(raw: {
+    id: string;
+    firstName?: string | null;
+    lastName?: string | null;
+    emailAddress?: string | null;
+    phoneNumber?: string | null;
+}): Customer;
+declare function searchVendureCustomers(context: SyncContext, query: string, options?: {
+    limit?: number;
+}): Promise<Customer[]>;
+declare function createVendureCustomer(context: SyncContext, input: CustomerInput): Promise<Customer>;
+declare function getVendureCustomer(context: SyncContext, id: string): Promise<Customer | null>;
+
 /**
  * Vendure connector for Tally UI. Build one per store session, anew on each sign-in or store change:
  * each instance owns its reconcile feed, whose queued work must never reach another store's database (#307).
@@ -138,4 +151,4 @@ declare const createVendureConnector: (options?: {
  */
 declare const vendureConnector: TallyConnector;
 
-export { VendureTimezoneConfigError, createVendureConnector, createVendureProductReplication, createVendureVariantFeedReplication, vendureAuth, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureSignIn, vendureStockReconcile, vendureStoreSettings };
+export { VendureTimezoneConfigError, createVendureConnector, createVendureCustomer, createVendureProductReplication, createVendureVariantFeedReplication, getVendureCustomer, searchVendureCustomers, toVendureCustomer, vendureAuth, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureSignIn, vendureStockReconcile, vendureStoreSettings };

package/dist/index.js

@@ -871,6 +871,79 @@ var vendureStoreSettings = async (context, _choice) => {
   };
 };
 
+// src/customers.ts
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError5, CustomerServiceError } from "@tallyui/core";
+var WALK_IN_EMAIL = "walk-in@vendurepos.local";
+var SEARCH_QUERY = `query Search($q: String!, $take: Int!) {
+  customers(options: {
+    filter: { emailAddress: { contains: $q }, firstName: { contains: $q }, lastName: { contains: $q } },
+    filterOperator: OR, take: $take, sort: { lastName: ASC }
+  }) {
+    totalItems
+    items { id firstName lastName emailAddress phoneNumber }
+  }
+}`;
+var CREATE_QUERY = `mutation Create($input: CreateCustomerInput!) {
+  createCustomer(input: $input) {
+    __typename
+    ... on Customer { id firstName lastName emailAddress phoneNumber }
+    ... on ErrorResult { errorCode message }
+  }
+}`;
+var GET_QUERY = `query One($id: ID!) {
+  customer(id: $id) { id firstName lastName emailAddress phoneNumber }
+}`;
+function toVendureCustomer(raw) {
+  const customer = { id: raw.id, name: raw.id };
+  for (const [key, value] of [
+    ["firstName", raw.firstName],
+    ["lastName", raw.lastName],
+    ["email", raw.emailAddress],
+    ["phone", raw.phoneNumber]
+  ]) {
+    if (typeof value === "string" && value.length > 0) customer[key] = value;
+  }
+  customer.name = [customer.firstName, customer.lastName].filter(Boolean).join(" ") || customer.email || customer.id;
+  return customer;
+}
+async function searchVendureCustomers(context, query2, options) {
+  const q = query2.trim();
+  if (!q) return [];
+  const take = Math.max(1, Math.min(50, options?.limit ?? 20));
+  const body = await customerGql(context, SEARCH_QUERY, { q, take });
+  const items = body?.data?.customers?.items;
+  if (!Array.isArray(items)) throw new CustomerServiceError("server", "unexpected response");
+  return items.filter((raw) => raw.emailAddress !== WALK_IN_EMAIL).map(toVendureCustomer);
+}
+async function createVendureCustomer(context, input) {
+  const variables = { input: {
+    emailAddress: input.email,
+    firstName: input.firstName ?? "",
+    lastName: input.lastName ?? "",
+    ...input.phone ? { phoneNumber: input.phone } : {}
+  } };
+  const body = await customerGql(context, CREATE_QUERY, variables);
+  const result = body?.data?.createCustomer;
+  if (result?.__typename === "Customer") return toVendureCustomer(result);
+  if (result?.__typename && result.message) throw new CustomerServiceError("invalid", result.message);
+  throw new CustomerServiceError("server", "unexpected response");
+}
+async function customerGql(context, query2, variables) {
+  try {
+    return await gql2(context, query2, variables);
+  } catch (error) {
+    if (error instanceof ConnectorUnauthorizedError5) throw error;
+    throw new CustomerServiceError(error instanceof Error && error.message.startsWith("Vendure ") ? "server" : "network", error instanceof Error ? error.message : String(error));
+  }
+}
+async function getVendureCustomer(context, id) {
+  const body = await customerGql(context, GET_QUERY, { id });
+  const raw = body?.data?.customer;
+  if (raw === null) return null;
+  if (typeof raw?.id !== "string") throw new CustomerServiceError("server", "unexpected response");
+  return toVendureCustomer(raw);
+}
+
 // src/global-settings.ts
 var GLOBAL_SETTINGS_QUERY = `
   query GlobalStockSettings {
@@ -883,7 +956,7 @@ async function vendureGlobalStockSettings(context) {
 }
 
 // src/index.ts
-import { ConnectorUnauthorizedError as ConnectorUnauthorizedError5 } from "@tallyui/core";
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError6 } from "@tallyui/core";
 var VENDURE_IDS_PER_REQUEST = 1e3;
 var createVendureConnector = (options = {}) => {
   const idFeed = createReconcileFeed({ fetchByIds: createFetchByIds(options.barcodeField) });
@@ -923,17 +996,25 @@ var createVendureConnector = (options = {}) => {
       prices: { fetchPages: fetchPages2, fingerprint, enqueue: idFeed.enqueue, refetchBatchSize: VENDURE_IDS_PER_REQUEST }
     },
     storeSettings: vendureStoreSettings,
+    // Needs the administrator's ReadCustomer permission (and CreateCustomer to create).
+    searchCustomers: searchVendureCustomers,
+    createCustomer: createVendureCustomer,
+    getCustomer: getVendureCustomer,
     // Re-reads a restored session's capabilities; with an API key and no sign-in, the only reader.
     capabilities: (context) => readVendureCapabilities(context.baseUrl, context.headers, { signal: context.signal })
   };
 };
 var vendureConnector = createVendureConnector();
 export {
-  ConnectorUnauthorizedError5 as ConnectorUnauthorizedError,
+  ConnectorUnauthorizedError6 as ConnectorUnauthorizedError,
   VendureTimezoneConfigError,
   createVendureConnector,
+  createVendureCustomer,
   createVendureProductReplication,
   createVendureVariantFeedReplication,
+  getVendureCustomer,
+  searchVendureCustomers,
+  toVendureCustomer,
   vendureAuth,
   vendureConnector,
   vendureGlobalStockSettings,

package/package.json

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

package/src/__tests__/fixtures/customers/1a-customers-search-matches.json

@@ -0,0 +1,43 @@
+{
+  "query": "query Search($q: String!, $take: Int!) {\n  customers(options: {\n    filter: { emailAddress: { contains: $q }, firstName: { contains: $q }, lastName: { contains: $q } },\n    filterOperator: OR, take: $take, sort: { lastName: ASC }\n  }) {\n    totalItems\n    items { id createdAt updatedAt title firstName lastName emailAddress phoneNumber customFields }\n  }\n}",
+  "variables": {
+    "q": "ada",
+    "take": 20
+  },
+  "httpStatus": 200,
+  "response": {
+    "data": {
+      "customers": {
+        "totalItems": 2,
+        "items": [
+          {
+            "id": "3",
+            "createdAt": "2026-10-06T01:13:57.519Z",
+            "updatedAt": "2026-10-06T01:13:57.519Z",
+            "title": null,
+            "firstName": "Adam",
+            "lastName": "Fixture",
+            "emailAddress": "adam.fixture@example.com",
+            "phoneNumber": null,
+            "customFields": {
+              "__entityId__": 3
+            }
+          },
+          {
+            "id": "2",
+            "createdAt": "2026-10-06T01:13:57.496Z",
+            "updatedAt": "2026-10-06T01:13:57.496Z",
+            "title": null,
+            "firstName": "Ada",
+            "lastName": "Lovelace",
+            "emailAddress": "ada.fixture@example.com",
+            "phoneNumber": "+44 20 7946 0001",
+            "customFields": {
+              "__entityId__": 2
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/src/__tests__/fixtures/customers/1b-customers-search-none.json

@@ -0,0 +1,16 @@
+{
+  "query": "query Search($q: String!, $take: Int!) {\n  customers(options: {\n    filter: { emailAddress: { contains: $q }, firstName: { contains: $q }, lastName: { contains: $q } },\n    filterOperator: OR, take: $take, sort: { lastName: ASC }\n  }) {\n    totalItems\n    items { id createdAt updatedAt title firstName lastName emailAddress phoneNumber customFields }\n  }\n}",
+  "variables": {
+    "q": "zzqqxx",
+    "take": 20
+  },
+  "httpStatus": 200,
+  "response": {
+    "data": {
+      "customers": {
+        "totalItems": 0,
+        "items": []
+      }
+    }
+  }
+}

package/src/__tests__/fixtures/customers/2a-createCustomer-success.json

@@ -0,0 +1,30 @@
+{
+  "query": "mutation Create($input: CreateCustomerInput!) {\n  createCustomer(input: $input) {\n    __typename\n    ... on Customer { id createdAt updatedAt title firstName lastName emailAddress phoneNumber customFields }\n    ... on ErrorResult { errorCode message }\n  }\n}",
+  "variables": {
+    "input": {
+      "firstName": "Ada",
+      "lastName": "Lovelace",
+      "emailAddress": "ada.fixture@example.com",
+      "phoneNumber": "+44 20 7946 0001"
+    }
+  },
+  "httpStatus": 200,
+  "response": {
+    "data": {
+      "createCustomer": {
+        "__typename": "Customer",
+        "id": "2",
+        "createdAt": "2026-10-06T01:13:57.496Z",
+        "updatedAt": "2026-10-06T01:13:57.496Z",
+        "title": null,
+        "firstName": "Ada",
+        "lastName": "Lovelace",
+        "emailAddress": "ada.fixture@example.com",
+        "phoneNumber": "+44 20 7946 0001",
+        "customFields": {
+          "__entityId__": 2
+        }
+      }
+    }
+  }
+}

package/src/__tests__/fixtures/customers/2b-createCustomer-duplicate-email.json

@@ -0,0 +1,20 @@
+{
+  "query": "mutation Create($input: CreateCustomerInput!) {\n  createCustomer(input: $input) {\n    __typename\n    ... on Customer { id createdAt updatedAt title firstName lastName emailAddress phoneNumber customFields }\n    ... on ErrorResult { errorCode message }\n  }\n}",
+  "variables": {
+    "input": {
+      "firstName": "Ada",
+      "lastName": "Again",
+      "emailAddress": "ada.fixture@example.com"
+    }
+  },
+  "httpStatus": 200,
+  "response": {
+    "data": {
+      "createCustomer": {
+        "__typename": "EmailAddressConflictError",
+        "errorCode": "EMAIL_ADDRESS_CONFLICT_ERROR",
+        "message": "The email address is not available."
+      }
+    }
+  }
+}

package/src/__tests__/fixtures/customers/3-customer-with-addresses.json

@@ -0,0 +1,49 @@
+{
+  "query": "query One($id: ID!) {\n  customer(id: $id) {\n    id createdAt updatedAt title firstName lastName emailAddress phoneNumber customFields\n    addresses { id fullName company streetLine1 streetLine2 city province postalCode country { code name } phoneNumber defaultShippingAddress defaultBillingAddress }\n    user { id identifier verified }\n    groups { id name }\n  }\n}",
+  "variables": {
+    "id": "2"
+  },
+  "httpStatus": 200,
+  "response": {
+    "data": {
+      "customer": {
+        "id": "2",
+        "createdAt": "2026-10-06T01:13:57.496Z",
+        "updatedAt": "2026-10-06T01:13:57.496Z",
+        "title": null,
+        "firstName": "Ada",
+        "lastName": "Lovelace",
+        "emailAddress": "ada.fixture@example.com",
+        "phoneNumber": "+44 20 7946 0001",
+        "customFields": {
+          "__entityId__": 2
+        },
+        "addresses": [
+          {
+            "id": "1",
+            "fullName": "Ada Lovelace",
+            "company": "",
+            "streetLine1": "12 Fixture Street",
+            "streetLine2": "",
+            "city": "London",
+            "province": "",
+            "postalCode": "N1 1AA",
+            "country": {
+              "code": "DE",
+              "name": "Germany"
+            },
+            "phoneNumber": "",
+            "defaultShippingAddress": true,
+            "defaultBillingAddress": true
+          }
+        ],
+        "user": {
+          "id": "2",
+          "identifier": "ada.fixture@example.com",
+          "verified": false
+        },
+        "groups": []
+      }
+    }
+  }
+}

package/src/customers.ts

@@ -0,0 +1,76 @@
+import { ConnectorUnauthorizedError, CustomerServiceError, type Customer, type CustomerInput, type SyncContext } from '@tallyui/core';
+import { gql } from './replication/products';
+
+// The vendurepos plugin's walk-in customer is never a person to attach to a sale.
+const WALK_IN_EMAIL = 'walk-in@vendurepos.local';
+
+const SEARCH_QUERY = `query Search($q: String!, $take: Int!) {
+  customers(options: {
+    filter: { emailAddress: { contains: $q }, firstName: { contains: $q }, lastName: { contains: $q } },
+    filterOperator: OR, take: $take, sort: { lastName: ASC }
+  }) {
+    totalItems
+    items { id firstName lastName emailAddress phoneNumber }
+  }
+}`;
+const CREATE_QUERY = `mutation Create($input: CreateCustomerInput!) {
+  createCustomer(input: $input) {
+    __typename
+    ... on Customer { id firstName lastName emailAddress phoneNumber }
+    ... on ErrorResult { errorCode message }
+  }
+}`;
+const GET_QUERY = `query One($id: ID!) {
+  customer(id: $id) { id firstName lastName emailAddress phoneNumber }
+}`;
+
+export function toVendureCustomer(raw: { id: string; firstName?: string | null; lastName?: string | null; emailAddress?: string | null; phoneNumber?: string | null }): Customer {
+  const customer: Customer = { id: raw.id, name: raw.id };
+  for (const [key, value] of [
+    ['firstName', raw.firstName], ['lastName', raw.lastName],
+    ['email', raw.emailAddress], ['phone', raw.phoneNumber],
+  ] as const) {
+    if (typeof value === 'string' && value.length > 0) customer[key] = value;
+  }
+  customer.name = [customer.firstName, customer.lastName].filter(Boolean).join(' ') || customer.email || customer.id;
+  return customer;
+}
+
+export async function searchVendureCustomers(context: SyncContext, query: string, options?: { limit?: number }): Promise<Customer[]> {
+  const q = query.trim();
+  if (!q) return [];
+  const take = Math.max(1, Math.min(50, options?.limit ?? 20));
+  const body = await customerGql(context, SEARCH_QUERY, { q, take });
+  const items = body?.data?.customers?.items;
+  if (!Array.isArray(items)) throw new CustomerServiceError('server', 'unexpected response');
+  return items.filter((raw) => raw.emailAddress !== WALK_IN_EMAIL).map(toVendureCustomer);
+}
+
+export async function createVendureCustomer(context: SyncContext, input: CustomerInput): Promise<Customer> {
+  const variables = { input: {
+    emailAddress: input.email, firstName: input.firstName ?? '', lastName: input.lastName ?? '',
+    ...(input.phone ? { phoneNumber: input.phone } : {}),
+  } };
+  const body = await customerGql(context, CREATE_QUERY, variables);
+  const result = body?.data?.createCustomer;
+  if (result?.__typename === 'Customer') return toVendureCustomer(result);
+  if (result?.__typename && result.message) throw new CustomerServiceError('invalid', result.message);
+  throw new CustomerServiceError('server', 'unexpected response');
+}
+
+async function customerGql(context: SyncContext, query: string, variables: Record<string, unknown>): Promise<any> {
+  try {
+    return await gql(context, query, variables);
+  } catch (error) {
+    if (error instanceof ConnectorUnauthorizedError) throw error;
+    throw new CustomerServiceError(error instanceof Error && error.message.startsWith('Vendure ') ? 'server' : 'network', error instanceof Error ? error.message : String(error));
+  }
+}
+
+export async function getVendureCustomer(context: SyncContext, id: string): Promise<Customer | null> {
+  const body = await customerGql(context, GET_QUERY, { id });
+  const raw = body?.data?.customer;
+  if (raw === null) return null;
+  if (typeof raw?.id !== 'string') throw new CustomerServiceError('server', 'unexpected response');
+  return toVendureCustomer(raw);
+}

package/src/index.ts

@@ -12,6 +12,7 @@ import { createFetchByIds, fetchPages, variantIds } from './reconcile/ids';
 import { fetchPages as fetchPricePages, fingerprint as priceFingerprint } from './reconcile/prices';
 import { vendureStoreSettings } from './store-settings';
 import { vendureGlobalStockSettings } from './global-settings';
+import { searchVendureCustomers, createVendureCustomer, getVendureCustomer } from './customers';
 
 /** Ids per fetchByIds request: it sends the reconcile feed's whole chunk (at most 1,000 ids, ADR-060) in one query. */
 const VENDURE_IDS_PER_REQUEST = 1000;
@@ -86,6 +87,11 @@ export const createVendureConnector = (options: {
 
     storeSettings: vendureStoreSettings,
 
+    // Needs the administrator's ReadCustomer permission (and CreateCustomer to create).
+    searchCustomers: searchVendureCustomers,
+    createCustomer: createVendureCustomer,
+    getCustomer: getVendureCustomer,
+
     // Re-reads a restored session's capabilities; with an API key and no sign-in, the only reader.
     capabilities: (context) => readVendureCapabilities(context.baseUrl, context.headers, { signal: context.signal }),
   };
@@ -107,6 +113,7 @@ export { createVendureVariantFeedReplication } from './replication/variant-feed'
 export { vendureStockReconcile } from './reconcile/stock';
 export { vendureStoreSettings } from './store-settings';
 export { vendureGlobalStockSettings } from './global-settings';
+export { searchVendureCustomers, createVendureCustomer, getVendureCustomer, toVendureCustomer } from './customers';
 
 export { ConnectorUnauthorizedError } from '@tallyui/core';
 export { VendureTimezoneConfigError } from './replication/products';