washday-sdk 1.6.32 → 1.6.34

package/CLAUDE.md

@@ -0,0 +1,139 @@
+# CLAUDE.md - washday-sdk
+
+## Purpose
+Guide Claude when working inside `washday-sdk`.
+
+This repo is a **typed client abstraction layer** between frontend apps and backend.
+
+---
+
+## Ecosystem
+
+- `washday-backend` — source of truth, business rules, API
+- `washday-frontend` — main web app
+- `washday-pos-v2` — React Native mobile app (iOS/Android)
+
+Both `washday-frontend` and `washday-pos-v2` consume this SDK. Do not suggest they call the backend directly.
+
+---
+
+## Before Starting Any Task
+
+1. Read `docs/patterns.md` if you haven't in this session
+2. Read the relevant `src/api/<domain>/` files before proposing changes
+3. Never propose changes to code you haven't read
+
+---
+
+## Key File Locations
+
+- `src/api/index.ts` — client aggregator, where all modules are bound
+- `src/api/axiosInstance.ts` — axios config, base URLs, request interceptor
+- `src/interfaces/Api.ts` — `WashdayClientInstance` type (update when adding modules)
+- `src/interfaces/` — entity types (`IOrder`, `ICustomer`, `IProduct`, `IStore`, etc.)
+- `src/utils/apiUtils.ts` — `generateQueryParamsStr()`
+- `src/enum/index.ts` — `PaymentMethodsEnum`, `DiscountCodeTypes`
+
+---
+
+## Core Role of this Repo
+
+- Wrap backend endpoints into typed methods
+- Centralize request logic (auth, headers, errors)
+- Provide a stable contract for frontend apps
+- Ensure consistency across all consumers
+
+---
+
+## Core Principles
+
+- Do NOT introduce backend business logic here
+- Do NOT bypass SDK abstraction
+- Backward compatibility is critical
+- Keep method contracts stable and predictable
+- Prefer additive changes over breaking ones
+
+---
+
+## Context Usage Rules
+
+### When to use backend architecture knowledge
+Use backend context ONLY when:
+- mapping new SDK methods to backend endpoints
+- understanding request/response shapes
+- handling changes in backend contracts
+
+Do NOT:
+- re-design backend logic here
+- duplicate backend rules
+
+### When to use `docs/architecture.md`
+Read it when:
+- you need to understand the full system context (dependency chain, module inventory, auth model, error shape)
+- you are adding a new domain or making structural changes
+
+### When to use `docs/patterns.md`
+Read it when:
+- creating new SDK methods or modules
+- organizing domains or namespaces
+- defining typing, error handling, or compatibility behavior
+- evaluating whether a change is additive or breaking
+
+---
+
+## SDK-Specific Rules
+
+- All frontend apps must consume backend through the SDK
+- Do NOT suggest raw `fetch` or `axios` from consumer apps for endpoints already modeled in the SDK
+- When backend changes → evaluate SDK impact before touching consumer apps
+- Keep endpoint URL details abstracted inside SDK methods — callers never see raw paths
+- Every new method follows the standard shape: `bindMethods()`, explicit `Authorization` header, `generateQueryParamsStr()` for query params, try/catch + re-throw
+
+---
+
+## Typing Policy
+
+- Request params must always be typed explicitly
+- Response types are currently `Promise<any>` — this is a known gap
+- When adding new methods, add explicit response types if the shape is known
+- Do not widen existing types to `any` to make things compile
+
+---
+
+## Testing
+
+- Tests live in `test/`
+- Use Jest with `.call(mockClient, ...)` to bind `this` context
+- Mock `axiosInstance` methods — do not make real HTTP calls in tests
+- Assert the `Authorization` header and URL construction, not just the return value
+
+---
+
+## Before Publishing
+
+- Bump `package.json` version following semver (patch / minor / major)
+- Run `npm run publishVersion` (runs `tsc` + `npm publish`)
+- Breaking changes = major bump — notify consumer app teams before releasing
+
+---
+
+## Expected Response Style
+
+- Focus on API abstraction and typing
+- Keep solutions practical and consistent with existing patterns
+- Avoid generic SDK theory — reference actual patterns in this codebase
+- Prefer concrete examples using real module names and method shapes
+
+---
+
+## Engineering Mindset
+
+Think like:
+- API client designer
+- contract maintainer
+- integration layer owner
+
+Always optimize for:
+- consistency
+- stability
+- clarity

package/dist/api/index.js

@@ -10,7 +10,7 @@ import { getAutomaticDiscountById, getAutomaticDiscounts, getAvailableAutomaticD
 import { createAutomaticDiscount, createDiscountCode } from "./discounts/post";
 import { deleteAutomaticDiscountById, deleteDiscountCodeById, updateAutomaticDiscountById, updateDiscountCodeById } from "./discounts/put";
 import { deleteStoreStaffById } from "./staff/delete";
-import { getStoreStaff, getStoreStaffById } from "./staff/get";
+import { getStoreAssignableStaffs, getStoreStaff, getStoreStaffById } from "./staff/get";
 import { createStoreStaff } from "./staff/post";
 import { updateStoreStaffById, updateStoreStaffStores } from "./staff/put";
 import { getOrderSequence, getPaymentFees, getPickupScheduleCustomersApp, getStoreById, getStoreImages, getStoreReviewLink, getStores, getStoresByIdCustomersApp, getStoresByName } from "./stores/get";
@@ -264,6 +264,7 @@ const WashdayClient = function WashdayClient(apiToken, env = 'PROD', clientId, c
     });
     this.staff = bindMethods(this, {
         getStoreStaff: getStoreStaff,
+        getStoreAssignableStaffs: getStoreAssignableStaffs,
         getStoreStaffById: getStoreStaffById,
         updateStoreStaffById: updateStoreStaffById,
         updateStoreStaffStores: updateStoreStaffStores,

package/dist/api/staff/get.js

@@ -8,6 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 const GET_SET_STAFF = (storeId) => `api/store/${storeId}/staff`;
+const GET_ASSIGNABLE_STAFF = (storeId) => `api/store/${storeId}/assignable-staffs`;
 export const getStoreStaff = function (storeId, queryParams) {
     return __awaiter(this, void 0, void 0, function* () {
         try {
@@ -23,6 +24,22 @@ export const getStoreStaff = function (storeId, queryParams) {
         }
     });
 };
+export const getStoreAssignableStaffs = function (storeId, queryParams) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const config = {
+                headers: { Authorization: `Bearer ${this.apiToken}` }
+            };
+            const suffix = queryParams ? `?${queryParams}` : "";
+            const response = yield this.axiosInstance.get(`${GET_ASSIGNABLE_STAFF(storeId)}${suffix}`, config);
+            return response;
+        }
+        catch (error) {
+            console.error('Error fetching getStoreAssignableStaffs:', error);
+            throw error;
+        }
+    });
+};
 export const getStoreStaffById = function (storeId, staffId) {
     return __awaiter(this, void 0, void 0, function* () {
         try {

package/docs/architecture.md

@@ -0,0 +1,337 @@
+# washday-sdk Architecture
+
+## 1. System Overview
+
+`washday-sdk` is the typed client library that Washday frontend applications use to communicate with `washday-backend`. It is published as an npm package (ESM, TypeScript) and consumed as a dependency by any app that needs to interact with the Washday backend API.
+
+- **Package name**: `washday-sdk`
+- **Current version**: `1.6.33`
+- **Module format**: ESM (`"type": "module"`)
+- **Main entry**: `dist/index.js` (compiled from `src/index.ts`)
+- **Primary export**: `WashdayClient` class + `utils` namespace
+
+Known consumers:
+- `washday-frontend` — main web application
+- `washday-pos-v2` — React Native mobile app (iOS/Android)
+- Any other Washday app that needs backend access
+
+---
+
+## 2. Role in the Architecture
+
+```
+washday-frontend
+washday-pos-v2
+(other apps)
+      │
+      ▼
+ washday-sdk          ← this repo
+      │
+      ▼
+washday-backend       ← source of truth for business rules, entities, payments, integrations
+```
+
+**Ownership boundaries:**
+
+| Layer | Owns |
+|---|---|
+| `washday-backend` | Business rules, entity validation, database, payments, integrations |
+| `washday-sdk` | HTTP client abstraction, typed request/response methods, auth token forwarding, env routing |
+| Frontend apps | UI state, rendering, user interaction, app-specific logic |
+
+Frontend apps **do not** call `washday-backend` directly with raw `fetch` or `axios`. All backend communication goes through `washday-sdk`.
+
+---
+
+## 3. Core Responsibilities
+
+- **Typed API methods**: Every backend endpoint has a corresponding typed method on the client. Callers get predictable parameter shapes and autocomplete.
+- **Centralized auth**: Bearer token is injected into every request from a single place (`this.apiToken`). Apps initialize the client once with a token; individual method calls don't manage auth.
+- **Environment routing**: The client routes requests to the correct backend URL based on the `env` constructor parameter (`DEV`, `STAGE`, `PROD`).
+- **Request tracking**: Every request is stamped with a unique `x-request-id` UUID header at the axios instance level, enabling backend log correlation.
+- **Request cancellation**: List endpoints accept an `AbortSignal` (via `options.signal` or `params.signal`) so consumers can cancel in-flight requests.
+- **File download support**: Export endpoints override `Content-Type` and set `responseType: 'blob'` per-request for binary responses (CSV, XLSX, PDF).
+- **Domain organization**: All methods are grouped into domain namespaces on the client instance (e.g., `client.orders`, `client.customers`), making the API surface discoverable.
+- **Shared calculation utilities**: Complex order total/tax/discount computation logic lives in `src/utils/orders/` to avoid duplication across apps.
+
+---
+
+## 4. Boundaries / Non-Responsibilities
+
+The SDK must **not** own:
+
+- **Backend business rules**: Validation logic, pricing rules, status transition rules — these belong in `washday-backend`. The SDK passes data through; it does not re-implement business logic.
+- **UI logic**: No rendering, no component state, no routing. The SDK is framework-agnostic.
+- **Feature-specific concerns**: App-level flows (checkout wizard steps, POS screen state) are owned by the consuming app, not the SDK.
+- **Duplicate validation**: If `washday-backend` validates an email format or required field, the SDK does not need to re-validate it before sending. Input validation in the SDK should be limited to preventing obviously malformed HTTP requests.
+- **Session management**: The SDK does not manage token lifecycle (refresh, expiry, storage). It receives a token and uses it. The consuming app manages when to acquire or replace the token.
+
+---
+
+## 5. API Consumption Model
+
+### Initialization
+
+```typescript
+import { WashdayClient } from 'washday-sdk';
+
+const client = new WashdayClient(
+  apiToken,       // string (required) — Bearer token
+  env,            // string (optional, default: 'PROD') — 'DEV' | 'STAGE' | 'PROD'
+  clientId,       // string (optional) — sent as x-client-id header
+  clientSecret    // string (optional) — sent as x-client-secret header
+);
+```
+
+### Base URLs by environment
+
+| `env` value | Base URL |
+|---|---|
+| `DEV` | `http://localhost:5555/` |
+| `STAGE` | `https://washday-backend-development.herokuapp.com/` |
+| `PROD` | `https://washday-backend.herokuapp.com/` |
+
+### Request pipeline
+
+1. Consumer calls a method: `client.orders.getList({ storeId, status })`
+2. The method constructs query params using `generateQueryParamsStr()` from `src/utils/apiUtils.ts`
+3. The method sets `Authorization: Bearer <apiToken>` in the request config
+4. The request is sent through the shared `axiosInstance`
+5. The axios request interceptor applies `x-request-id`, `x-client-id`, `x-client-secret`, and overrides `responseType` or `Content-Type` when needed
+6. The response (or error) is returned to the caller
+
+### Auth header injection
+
+Auth is set explicitly per method call, not as an axios default header:
+
+```typescript
+const config = {
+  headers: { Authorization: `Bearer ${this.apiToken}` }
+};
+return await this.axiosInstance.get(`api/v2/order?${queryParams}`, config);
+```
+
+This means every method has direct visibility into how auth is applied, at the cost of some repetition.
+
+### Calling the SDK
+
+```typescript
+// List orders
+const response = await client.orders.getList({ storeId: 'abc', status: 'pending' });
+
+// Get customer
+const customer = await client.customers.getCustomerById('customer-id');
+
+// Create order
+const newOrder = await client.orders.create({ ... });
+
+// With cancellation
+const controller = new AbortController();
+const orders = await client.orders.getList({ storeId: 'abc' }, { signal: controller.signal });
+```
+
+---
+
+## 6. Domain Structure
+
+The client exposes 30+ module namespaces, each mapping to a set of backend endpoints:
+
+### Core Business
+| Namespace | Responsibility |
+|---|---|
+| `client.orders` | Order lifecycle: create, list, update, status transitions, payment lines |
+| `client.customers` | Customer records: CRUD, bulk create |
+| `client.products` | Product catalog: CRUD, pricing, bulk create |
+| `client.stores` | Store configuration: CRUD, settings |
+| `client.sections` | Store sections/zones: CRUD |
+
+### Personnel & Time
+| Namespace | Responsibility |
+|---|---|
+| `client.attendance` | Clock-in/out, history, store reports, export |
+| `client.staff` | Staff management: list, CRUD |
+| `client.users` | User accounts: update, store access, PIN validation |
+
+### Financial & Transactions
+| Namespace | Responsibility |
+|---|---|
+| `client.cashup` | Cash register sessions: CRUD |
+| `client.cashierboxes` | Cashier box tracking: CRUD, movement history |
+| `client.discountCodes` | Discount codes: list, verify, CRUD |
+| `client.automaticDiscount` | Automatic discount rules |
+| `client.cfdi` | Mexican tax invoices (CFDI): list, create, cancel, download |
+| `client.stripe` | Stripe subscription checkout, customer portal |
+
+### Inventory & Supplies
+| Namespace | Responsibility |
+|---|---|
+| `client.inventory` | Stock management: CRUD, stock additions, history |
+| `client.supplies` | Supply tracking: CRUD, stock additions |
+
+### Reporting & Export
+| Namespace | Responsibility |
+|---|---|
+| `client.reports` | Sales, customers, supplies, cashup, payment method statistics |
+| `client.csv` | CSV exports: customers, orders, reports |
+| `client.pdf` | PDF exports: unpaid orders report |
+
+### Logistics & Fulfillment
+| Namespace | Responsibility |
+|---|---|
+| `client.routes` | Delivery routes: create, close, update, order assignment |
+| `client.outsourcedOrders` | External fulfillment orders: CRUD |
+
+### Customer-Facing
+| Namespace | Responsibility |
+|---|---|
+| `client.auth` | Login (token, email, Google, Apple, Facebook, PIN), signup, password |
+| `client.publics` | Public endpoints: order receipts, POS/Hub app config (no auth required) |
+| `client.reviews` | Customer reviews: list, request review |
+
+### Company & Platform
+| Namespace | Responsibility |
+|---|---|
+| `client.companies` | Company settings: get, update, logo, subscription billing, tax info |
+| `client.partners` | Partner accounts: CRUD |
+| `client.countries` | Country reference data |
+| `client.updates` | System update notifications: list, mark as seen |
+
+### Integrations
+| Namespace | Responsibility |
+|---|---|
+| `client.integrations` | MercadoPago OAuth status, OAuth flow |
+| `client.integrations.mercadoPago` | Terminal discovery, import, disconnect, payment attempts |
+
+### Source layout
+
+Each domain follows this file structure under `src/api/<domain>/`:
+
+```
+customers/
+├── index.ts    # re-exports get/post/put/delete modules
+├── get.ts      # GET endpoints
+├── post.ts     # POST endpoints
+├── put.ts      # PUT/PATCH endpoints
+└── delete.ts   # DELETE endpoints
+```
+
+All methods are bound to the client instance in `src/api/index.ts` using a `bindMethods()` utility so they have access to `this.apiToken` and `this.axiosInstance`.
+
+---
+
+## 7. Typing Strategy
+
+### TypeScript configuration
+
+- Strict mode enabled (`"strict": true` in `tsconfig.json`)
+- Target: ES6, module: ESNext
+- All source in `src/`, compiled to `dist/`
+
+### Entity interfaces
+
+Core entity interfaces live in `src/interfaces/`:
+
+| File | Interfaces |
+|---|---|
+| `Order.ts` | `IOrder`, `IOrderProduct`, `IOrderPaymentLines`, `IDeliveryInfo`, `IPickupInfo` |
+| `Customer.ts` | `ICustomer`, `IAddress`, `IPaymentMethod`, `IInvoiceInfo` |
+| `Product.ts` | `IProduct`, `IPriceOption`, `IProductSupplies` |
+| `Store.ts` | `IStore`, `ITax`, `IPaymentConfig`, `IOrderPageConfig`, `IPrintingConfig`, `ISchedule` |
+| `User.ts` | `IUser`, `IStaff` |
+| `Company.ts` | `ICompany` |
+| `Section.ts` | `ISection` |
+| `Attendance.ts` | `IAttendance` |
+| `Permission.ts` | `IPermission` |
+| `Api.ts` | `WashdayClientInstance` — the full client interface with all module namespaces typed |
+
+### Enums
+
+Defined in `src/enum/index.ts`:
+
+```typescript
+enum PaymentMethodsEnum { Cash, Card, Delivery, Transfer }
+enum DiscountCodeTypes { PERCENTAGE, NUMBER, FREE_DELIVERY, BUY_X_GET_Y, FREE_ITEM }
+enum BuyAndGetConditionsTypes { PERCENTAGE, FREE }
+```
+
+### Current limitation: `Promise<any>` returns
+
+Most endpoint methods currently return `Promise<any>`. This means callers do not get typed response shapes — only request parameters are typed. This is a known gap. When adding new methods or updating existing ones, prefer adding explicit response types.
+
+---
+
+## 8. Error Handling Strategy
+
+### Pattern in every endpoint
+
+All methods wrap the axios call in try/catch and re-throw:
+
+```typescript
+try {
+  const config = { headers: { Authorization: `Bearer ${this.apiToken}` } };
+  return await this.axiosInstance.get(`api/some/endpoint`, config);
+} catch (error) {
+  console.error('Washday SDK - Error description:', error);
+  throw error;
+}
+```
+
+The SDK logs to `console.error` and re-throws. It does not swallow errors or transform them into custom error classes.
+
+### Abort/cancel handling
+
+List endpoints detect cancellation explicitly:
+
+```typescript
+} catch (error) {
+  if (error instanceof Error && (error.name === 'AbortError' || error.name === 'CanceledError')) {
+    console.log('Request was cancelled');
+    throw error;
+  }
+  console.error('...', error);
+  throw error;
+}
+```
+
+### What consumers receive
+
+When an error is thrown, it is an axios error with this shape:
+
+```typescript
+error.response          // present if the server replied (4xx, 5xx)
+error.response.status   // HTTP status code
+error.response.data     // backend error body (may contain validation messages)
+
+error.request           // present if request was sent but no response received
+error.message           // network-level error description
+```
+
+Consumers are responsible for distinguishing application errors (`error.response`) from transport errors (no `error.response`).
+
+---
+
+## 9. Versioning / Compatibility
+
+- The SDK uses **semver**. Current version: `1.6.33`.
+- Frontend apps pin to a specific SDK version in their `package.json`. Upgrading requires deliberate action.
+- When `washday-backend` changes a response shape or adds/removes an endpoint, the SDK must be updated and re-published before consuming apps can use the new behavior.
+- There is currently no automated contract generation (e.g., OpenAPI → SDK types). SDK changes are written manually to match backend changes.
+- **Backward-incompatible backend changes** (removed fields, changed response structures) are high risk because frontend apps may be on older SDK versions. Coordinate SDK and backend releases.
+
+**Release flow:**
+
+```
+Update src/ → bump version in package.json → npm run publishVersion (runs tsc + npm publish)
+```
+
+---
+
+## 10. Future Considerations
+
+- **Typed response generics**: Replace `Promise<any>` returns with typed response interfaces (e.g., `Promise<{ data: IOrder[] }>`). This is the highest-impact improvement for catching integration bugs at compile time.
+- **Contract generation**: Generate SDK types automatically from a backend OpenAPI spec or shared schema source to eliminate manual drift.
+- **Shared validation schemas**: Use `joi` (already a dependency) to define shared request schemas that can be validated client-side before sending.
+- **Structured error types**: Introduce a typed `WashdaySDKError` class that normalizes axios error shapes so consumers don't need to understand axios internals.
+- **Observability hooks**: Allow consumers to inject request/response interceptors (e.g., for logging, metrics, or auth token refresh) without forking axios configuration.
+- **Monorepo**: As the ecosystem grows, co-locating `washday-sdk` with shared entity types in a monorepo would reduce the latency between backend changes and SDK updates.
+- **Pagination helpers**: Standardize list endpoint pagination patterns (currently ad-hoc via `pageNum` / `limit` query params).