@tallyui/connector-woocommerce 3.20.1 → 4.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -3
- package/dist/index.d.ts +40 -11
- package/dist/index.js +943 -156
- package/package.json +4 -5
- package/src/closures.ts +184 -0
- package/src/commands/http.ts +37 -0
- package/src/commands/register-transport.ts +212 -0
- package/src/commands/transport.ts +167 -74
- package/src/currency-symbols.ts +166 -0
- package/src/customers.ts +29 -14
- package/src/index.ts +8 -2
- package/src/orders.ts +59 -10
- package/src/payment-methods.ts +4 -3
- package/src/registers.ts +55 -0
- package/src/replication/products.ts +7 -3
- package/src/schemas/products.ts +7 -2
- package/src/store-settings.ts +71 -25
- package/src/traits/product.ts +2 -0
- package/src/unauthorized.ts +8 -0
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
|
|
10
10
|
`auth.getHeaders({ token })` sends the WCPOS access token as `Authorization: Bearer <token>`, together with the POS marker `X-WCPOS: 1`. Without a token it throws `WooMissingTokenError`. WooCommerce consumer keys are not supported.
|
|
11
11
|
|
|
12
|
-
It also sends `X-WCPOS-Protocol:
|
|
12
|
+
It also sends `X-WCPOS-Protocol: 3`, which WCPOS 2.0.4 requires of POS requests (a lower value gets HTTP 426 `wcpos_update_required`), and `X-WCPOS-Client: tallyui/<connector version>` (lowercase `[a-z0-9._-]`, at most 32 characters), which WCPOS uses only for consent-gated telemetry.
|
|
13
13
|
|
|
14
14
|
## Product pull
|
|
15
15
|
|
|
@@ -40,13 +40,17 @@ The incremental pull can miss an edit: a `modified_after` that over-excludes (in
|
|
|
40
40
|
`readWooCapabilities` (the connector's `capabilities`) runs when the till signs in or restores a session. The app keeps the result with the session.
|
|
41
41
|
- **`GET wcpos/v2/stores`** gives the tax rounding (`tax_round_at_subtotal`). A failed or malformed read returns `undefined`: nothing new is known, and the stored capabilities stay.
|
|
42
42
|
- **`GET wcpos/v2/status`.** The strings in its `capabilities` decide two fields:
|
|
43
|
-
- `order_create_v5`
|
|
43
|
+
- `order_create_v5` makes `orderCreate` 8 when the coupons gate passes, else 5; with a `capabilities` list that lacks it, `orderCreate` is 3. Only the TallyUI fork of the plugin advertises it. When `/status` answers with no `capabilities` list at all (stock WCPOS 1.10.x), the `/site` version decides instead: a plain `1.10.N` with N ≥ 20 gives 7 (never 8: no tax address), anything else gives 3. A plain `2.0.N` with N ≥ 4 whose `capabilities` list lacks `order_create_v5` (or that has no list) gets 6 (never 7 or 8: no note or tax address proven). A failed `/status` read gives 3.
|
|
44
44
|
- `order_payments_list` sets `multiplePayments`.
|
|
45
|
-
- **`GET wcpos/v2/site`.** Its `wcpos_version` decides `coupons` (ADR-077, ruling R3). It is true only for woocommerce-pos 1.9.0 or later; a 1.9.0 pre-release does not count. Any failed or unclear read gives false, and the till then refuses to apply a coupon.
|
|
45
|
+
- **`GET wcpos/v2/site`.** Its `wcpos_version` decides `coupons` (ADR-077, ruling R3). It is true only for woocommerce-pos 1.9.0 or later; a 1.9.0 pre-release does not count. Any failed or unclear read gives false, and the till then refuses to apply a coupon. On a store with no `capabilities` list it also decides `orderCreate` (above).
|
|
46
46
|
- **`lineTax`** is always `{ none: true, classes: true }`.
|
|
47
47
|
- **Unauthorised reads.** A 401 or 403 from `/stores` or `/status` throws `ConnectorUnauthorizedError`. A 401 or 403 from `/site` only closes the coupon gate.
|
|
48
48
|
- **`products_id_fast_path`** is read by the reconcile pass, not here (see Reconciliation).
|
|
49
49
|
|
|
50
|
+
## Order push on WCPOS 2.0
|
|
51
|
+
|
|
52
|
+
On a 2.0.x store (`ledgerPayments`, or `/site` `wcpos_version` 2 or later, read once per transport) the sale is pushed `pending` with no money keys, then paid with one `POST orders/<id>/payments` per payment (`pos_cash` with `tendered`, or `pos_card`), each sent with the revision the last answer gave; a free sale is closed with `POST orders/<id>/close`. The sale counts as applied only after the last of those calls succeeds. A retry replays the push by its mutation id and each payment by its id. A money call the store refuses is rejected with a message naming the order it created, since that order now exists unpaid. On 1.10.x and the fork, the push body is unchanged.
|
|
53
|
+
|
|
50
54
|
## Customers
|
|
51
55
|
|
|
52
56
|
On WCPOS 1.10.x, `searchCustomers` uses `GET wcpos/v2/customers` with `role=customer`.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import { SyncContext, ServerCapabilities, StoreSettings, Customer, CustomerPage, CustomerInput, CustomerPatch, TallyConnector, StoreOrder, OrderCreateEnvelope, CommandResult, ReconcileFeed, CatalogueReconcileAdapter, ProductTraits, CollectionSync, ReplicationAdapter, ConnectorUnauthorizedError } from '@tallyui/core';
|
|
2
|
-
export { ConnectorUnauthorizedError } from '@tallyui/core';
|
|
1
|
+
import { SyncContext, ServerCapabilities, StoreSettings, Customer, CustomerPage, CustomerInput, CustomerPatch, TallyConnector, StoreOrder, OrderCreateEnvelope, CommandResult, RegisterCommandEnvelope, ApproverCredentials, ReconcileFeed, CatalogueReconcileAdapter, ProductTraits, CollectionSync, ReplicationAdapter, ConnectorUnauthorizedError } from '@tallyui/core';
|
|
2
|
+
export { ApproverCredentials, ConnectorUnauthorizedError } from '@tallyui/core';
|
|
3
3
|
import { RxJsonSchema } from 'rxdb';
|
|
4
4
|
|
|
5
|
-
/** The highest order.create version the WooCommerce transport maps without coupons: v4's net discounts, and v5's fees, shipping and custom lines (WCPOS push/orders; orders #146, #161).
|
|
5
|
+
/** The highest order.create version the WooCommerce transport maps without coupons: v4's net discounts, and v5's fees, shipping and custom lines (WCPOS push/orders; orders #146, #161). A store with coupons gets 8 (`WOO_TAX_ADDRESS_ORDER_CREATE_VERSION`): 6 adds coupons (ADR-077 d4a-woo), 7 the note, 8 the tax address. */
|
|
6
6
|
declare const WOO_ORDER_CREATE_VERSION = 5;
|
|
7
7
|
/** Version 7 is version 6 plus the sale note (ADR-083), mapped to WooCommerce's customer_note; a store takes it wherever it takes 6. Version 6 is version 5 plus coupons: it needs both order_create_v5 and the coupons gate. */
|
|
8
8
|
declare const WOO_NOTE_ORDER_CREATE_VERSION = 7;
|
|
@@ -15,19 +15,18 @@ type WooCustomerRow = {
|
|
|
15
15
|
last_name?: string | null;
|
|
16
16
|
email?: string | null;
|
|
17
17
|
date_created_gmt?: string | null;
|
|
18
|
-
billing?:
|
|
19
|
-
|
|
20
|
-
last_name?: string | null;
|
|
21
|
-
email?: string | null;
|
|
22
|
-
phone?: string | null;
|
|
23
|
-
company?: string | null;
|
|
24
|
-
} | null;
|
|
18
|
+
billing?: WooAddressRow | null;
|
|
19
|
+
shipping?: Omit<WooAddressRow, 'email'> | null;
|
|
25
20
|
meta_data?: {
|
|
26
21
|
key?: string;
|
|
27
22
|
value?: unknown;
|
|
28
23
|
}[];
|
|
29
24
|
_rxdb_revision?: unknown;
|
|
30
25
|
};
|
|
26
|
+
declare const WOO_ADDRESS: readonly [readonly ["first_name", "firstName"], readonly ["last_name", "lastName"], readonly ["company", "company"], readonly ["address_1", "address1"], readonly ["address_2", "address2"], readonly ["city", "city"], readonly ["postcode", "postcode"], readonly ["country", "country"], readonly ["state", "state"], readonly ["email", "email"], readonly ["phone", "phone"]];
|
|
27
|
+
type WooAddressRow = {
|
|
28
|
+
[key in (typeof WOO_ADDRESS)[number][0]]?: string | null;
|
|
29
|
+
};
|
|
31
30
|
declare function toWooCustomer(raw: WooCustomerRow): Customer;
|
|
32
31
|
declare function createWooCustomers(options?: {
|
|
33
32
|
newId?: () => string;
|
|
@@ -77,6 +76,14 @@ interface WooCommandTransportOptions {
|
|
|
77
76
|
/** True when the store passes the coupons gate (`ServerCapabilities.coupons`, ADR-077 R2/R3). Read at push time;
|
|
78
77
|
* absent means closed, so a sale still carrying coupons is refused with `coupon_invalid` and no request is made. */
|
|
79
78
|
acceptsCoupons?: boolean | (() => boolean | Promise<boolean>);
|
|
79
|
+
/** True for a WCPOS 2.0.x store, whose push carries no money: the sale is pushed `pending`, then paid through the
|
|
80
|
+
* payment ledger. Read at push time; absent, the transport reads `/site` once and decides from `wcpos_version`. */
|
|
81
|
+
ledgerPayments?: boolean | (() => boolean | Promise<boolean>);
|
|
82
|
+
}
|
|
83
|
+
/** A money command for the ledger, sent with the order revision it was built against. */
|
|
84
|
+
interface WooMoneyCommand {
|
|
85
|
+
path: 'payments' | 'close';
|
|
86
|
+
body: Record<string, unknown>;
|
|
80
87
|
}
|
|
81
88
|
interface WooLocalOrder {
|
|
82
89
|
lines: ReadonlyArray<{
|
|
@@ -100,8 +107,10 @@ interface WooLocalOrder {
|
|
|
100
107
|
}
|
|
101
108
|
declare function toWooOrderPayload(envelope: OrderCreateEnvelope, local?: WooLocalOrder, options?: {
|
|
102
109
|
paymentsList?: boolean;
|
|
110
|
+
ledger?: boolean;
|
|
103
111
|
}): {
|
|
104
112
|
payload: Record<string, unknown>;
|
|
113
|
+
money?: WooMoneyCommand[];
|
|
105
114
|
} | {
|
|
106
115
|
error: {
|
|
107
116
|
code: string;
|
|
@@ -116,6 +125,26 @@ declare function createWooCommandTransport(options: WooCommandTransportOptions):
|
|
|
116
125
|
}): Promise<WooTransportOutcome>;
|
|
117
126
|
};
|
|
118
127
|
|
|
128
|
+
interface WooRegisterTransportOptions extends Pick<WooCommandTransportOptions, 'baseUrl' | 'getHeaders' | 'fetch' | 'timeoutMs'> {
|
|
129
|
+
/** The store currency, read once per `send`. */
|
|
130
|
+
currency: string | (() => string | Promise<string>);
|
|
131
|
+
}
|
|
132
|
+
declare function createWooRegisterTransport(options: WooRegisterTransportOptions): {
|
|
133
|
+
send(batch: RegisterCommandEnvelope[]): Promise<WooTransportOutcome>;
|
|
134
|
+
};
|
|
135
|
+
/** Asks WCPOS 2.0.4 to approve a counted session (Sessions_Controller.php:309-325): the session is moved to counting first. */
|
|
136
|
+
declare function wooApproveSession(context: SyncContext, input: {
|
|
137
|
+
sessionId: string;
|
|
138
|
+
credentials: ApproverCredentials;
|
|
139
|
+
counted: Record<string, number>;
|
|
140
|
+
currency: string;
|
|
141
|
+
}): Promise<{
|
|
142
|
+
approval: string;
|
|
143
|
+
approvedBy: string;
|
|
144
|
+
} | {
|
|
145
|
+
refused: 'override_refused' | 'not_counting';
|
|
146
|
+
}>;
|
|
147
|
+
|
|
119
148
|
/**
|
|
120
149
|
* WooCommerce Product RxDB schema.
|
|
121
150
|
* Closely mirrors the WooCommerce REST API product shape.
|
|
@@ -279,4 +308,4 @@ declare function createWooCommerceConnector(): TallyConnector;
|
|
|
279
308
|
*/
|
|
280
309
|
declare const woocommerceConnector: TallyConnector;
|
|
281
310
|
|
|
282
|
-
export { WOO_NOTE_ORDER_CREATE_VERSION, WOO_ORDER_CREATE_VERSION, type WooCommandTransportOptions, WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, WooTokenRefusedError, createWooCommandTransport, createWooCommerceConnector, createWooCouponFeed, createWooCustomers, createWooOrders, readWooCapabilities, toCouponDocument, toWooCustomer, toWooOrderPayload, toWooStoreOrder, wcposClientPart, wooCatalogueReconcile, wooCouponFingerprint, wooCouponReconcile, wooCouponSchema, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, wooStoreSettings, woocommerceConnector };
|
|
311
|
+
export { WOO_NOTE_ORDER_CREATE_VERSION, WOO_ORDER_CREATE_VERSION, type WooCommandTransportOptions, WooDateFilterError, WooMissingTokenError, WooMissingUuidError, type WooRegisterTransportOptions, WooTillUpdateRequiredError, WooTokenRefusedError, createWooCommandTransport, createWooCommerceConnector, createWooCouponFeed, createWooCustomers, createWooOrders, createWooRegisterTransport, readWooCapabilities, toCouponDocument, toWooCustomer, toWooOrderPayload, toWooStoreOrder, wcposClientPart, wooApproveSession, wooCatalogueReconcile, wooCouponFingerprint, wooCouponReconcile, wooCouponSchema, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, wooStoreSettings, woocommerceConnector };
|