@tallyui/connector-woocommerce 3.20.0 → 4.0.0
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 +45 -11
- package/dist/index.js +965 -159
- 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 +185 -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,12 +76,25 @@ 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<{
|
|
83
90
|
id: string;
|
|
84
91
|
netMicros?: string; /** The line's discount in its own tax mode (gross when inclusive), as stored. */
|
|
85
92
|
discountMinor?: number;
|
|
93
|
+
taxLines?: ReadonlyArray<{
|
|
94
|
+
rateId?: number;
|
|
95
|
+
compound?: boolean;
|
|
96
|
+
ratePpm: number;
|
|
97
|
+
}>;
|
|
86
98
|
}>;
|
|
87
99
|
fees?: ReadonlyArray<{
|
|
88
100
|
id: string;
|
|
@@ -95,8 +107,10 @@ interface WooLocalOrder {
|
|
|
95
107
|
}
|
|
96
108
|
declare function toWooOrderPayload(envelope: OrderCreateEnvelope, local?: WooLocalOrder, options?: {
|
|
97
109
|
paymentsList?: boolean;
|
|
110
|
+
ledger?: boolean;
|
|
98
111
|
}): {
|
|
99
112
|
payload: Record<string, unknown>;
|
|
113
|
+
money?: WooMoneyCommand[];
|
|
100
114
|
} | {
|
|
101
115
|
error: {
|
|
102
116
|
code: string;
|
|
@@ -111,6 +125,26 @@ declare function createWooCommandTransport(options: WooCommandTransportOptions):
|
|
|
111
125
|
}): Promise<WooTransportOutcome>;
|
|
112
126
|
};
|
|
113
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
|
+
|
|
114
148
|
/**
|
|
115
149
|
* WooCommerce Product RxDB schema.
|
|
116
150
|
* Closely mirrors the WooCommerce REST API product shape.
|
|
@@ -274,4 +308,4 @@ declare function createWooCommerceConnector(): TallyConnector;
|
|
|
274
308
|
*/
|
|
275
309
|
declare const woocommerceConnector: TallyConnector;
|
|
276
310
|
|
|
277
|
-
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 };
|