@nymbalhq/importers 0.3.4 → 0.4.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 nymbal contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,6 @@
1
+ # @nymbalhq/importers
2
+
3
+ The engine behind `nymbal import`: it reads a WooCommerce store and maps its products, categories, customers,
4
+ orders and reviews onto Nymbal.
5
+
6
+ See [Importing from WooCommerce](https://github.com/nymbalhq/nymbal/blob/main/apps/docs/src/content/docs/importing.md).
package/dist/index.d.ts CHANGED
@@ -7,6 +7,24 @@ interface WooCommerceCredentials {
7
7
  consumerSecret: string;
8
8
  }
9
9
  type ImportEntity = 'categories' | 'products' | 'customers' | 'orders' | 'reviews';
10
+ /** Each entity's `since` (`YYYY-MM-DDTHH:MM:SSZ`); `null` reads the entity whole, as a pass that never covered it must. */
11
+ type SinceByEntity = Partial<Record<ImportEntity, string | null>>;
12
+ /** Something a merchant should look at before launch that is not an error: the record was handled, partly. */
13
+ interface ImportWarning {
14
+ phase: string;
15
+ id?: string;
16
+ message: string;
17
+ }
18
+ /** A pass that reached its end: every entity it covered was read from its first page to its last. */
19
+ interface FinishedPass {
20
+ /** When the pass began, not when its last resumed run began. */
21
+ startedAt: string;
22
+ finishedAt: string;
23
+ /** Present for a delta pass. */
24
+ since?: SinceByEntity;
25
+ /** The entities whose loops reached their end within the pass. */
26
+ entities: ImportEntity[];
27
+ }
10
28
  interface WooCommerceImportOptions {
11
29
  credentials: WooCommerceCredentials;
12
30
  entities: ImportEntity[];
@@ -17,6 +35,10 @@ interface WooCommerceImportOptions {
17
35
  projectRoot: string;
18
36
  currency: string;
19
37
  statePath: string;
38
+ /** The stock an item WooCommerce does not count imports with when it is in stock or on backorder; 1000 by default. */
39
+ untrackedStock?: number;
40
+ /** Starts a delta pass on a state whose last pass finished; resolve `last` with `resolveSince`. */
41
+ since?: SinceByEntity;
20
42
  }
21
43
  interface ImportCursor {
22
44
  page: number;
@@ -24,8 +46,16 @@ interface ImportCursor {
24
46
  interface ImportState {
25
47
  source: 'woocommerce';
26
48
  startedAt: string;
49
+ /** When the earliest run whose records the state holds began: the store's own activity is counted from here. */
50
+ rollbackSince: string;
27
51
  phase: ImportEntity | 'connect' | 'enrich' | 'done';
52
+ /**
53
+ * The entities whose loop ran to its end: a later run imports only the selected entities not in it. A delta pass
54
+ * starts it empty and holds there what it has covered.
55
+ */
56
+ finished: ImportEntity[];
28
57
  cursors: Partial<Record<ImportEntity, ImportCursor>>;
58
+ /** The records the import created (not those it only linked): what a rollback removes. */
29
59
  importedIds: {
30
60
  categories: string[];
31
61
  products: string[];
@@ -36,12 +66,33 @@ interface ImportState {
36
66
  wcToNymbalCustomer: Record<string, string>;
37
67
  wcToNymbalProduct: Record<string, string>;
38
68
  wcToNymbalCategory: Record<string, string>;
69
+ wcToNymbalOrder: Record<string, string>;
70
+ wcToNymbalReview: Record<string, string>;
39
71
  errors: Array<{
40
72
  phase: string;
41
73
  id?: string;
42
74
  error: string;
43
75
  }>;
76
+ /** Each once, by phase, id and message. */
77
+ warnings: ImportWarning[];
44
78
  eventsEmitted: number;
79
+ /** The finished passes, oldest first. */
80
+ runs: FinishedPass[];
81
+ /** Set while a delta pass is under way; a run without `since` resumes it. */
82
+ delta?: {
83
+ since: SinceByEntity;
84
+ startedAt: string;
85
+ updated: {
86
+ products: number;
87
+ };
88
+ changedNotUpdated: {
89
+ orders: number;
90
+ };
91
+ /** The products the pass created, kept across a stop: the ones `--ai` enriches when the pass ends. */
92
+ created: {
93
+ products: string[];
94
+ };
95
+ };
45
96
  }
46
97
  interface ImportReport {
47
98
  imported: Record<ImportEntity, number>;
@@ -51,9 +102,34 @@ interface ImportReport {
51
102
  failed: number;
52
103
  };
53
104
  errors: ImportState['errors'];
105
+ warnings: ImportWarning[];
106
+ /** Imported products a delta wrote WooCommerce's changes to. */
107
+ updated: {
108
+ products: number;
109
+ };
110
+ /** Imported orders a delta listed as changed, which are never written again. */
111
+ changedNotUpdated: {
112
+ orders: number;
113
+ };
114
+ /** Present when the run was part of a delta pass: each covered entity's `since`. */
115
+ since?: SinceByEntity;
54
116
  eventsEmitted: number;
55
117
  durationMs: number;
56
118
  }
119
+ /** What a rollback will remove, and what it keeps. */
120
+ interface RollbackPlan {
121
+ remove: Record<ImportEntity, number>;
122
+ /** Image URLs the products to remove hold; their objects stay in media storage. */
123
+ mediaUrls: number;
124
+ /** Customers that were in the store before the import, which it linked its orders to. */
125
+ linkedCustomersKept: number;
126
+ }
127
+ interface RollbackReport extends RollbackPlan {
128
+ removed: Record<ImportEntity, number>;
129
+ /** Records already gone when the rollback reached them. */
130
+ absent: Record<ImportEntity, number>;
131
+ durationMs: number;
132
+ }
57
133
  type ProgressCallback = (event: ProgressEvent) => void;
58
134
  type ProgressEvent = {
59
135
  kind: 'phase';
@@ -69,6 +145,155 @@ type ProgressEvent = {
69
145
  id: string;
70
146
  message: string;
71
147
  };
148
+ /** What a plan reports fields for: each entity, and the variations read for variable products. */
149
+ type PlanEntity = ImportEntity | 'variations';
150
+ type CollisionKind = 'product-slug' | 'sku' | 'category-slug' | 'customer-email' | 'order-number';
151
+ /** What the target store already holds, asked read-only. `customerEmailExists` gets the email lowercased. */
152
+ interface ExistingStoreLookup {
153
+ productSlugExists(slug: string): Promise<boolean>;
154
+ skuExists(sku: string): Promise<boolean>;
155
+ categorySlugExists(slug: string): Promise<boolean>;
156
+ customerEmailExists(email: string): Promise<boolean>;
157
+ orderNumberExists(orderNumber: string): Promise<boolean>;
158
+ }
159
+ interface PlanCollision {
160
+ kind: CollisionKind;
161
+ with: 'source' | 'store';
162
+ /** The clashing slug, SKU or order number; `''` for a customer email, which is personal data. */
163
+ value: string;
164
+ /** WooCommerce ids (a product's for a SKU); a source clash names the record that is imported too. */
165
+ sourceIds: string[];
166
+ outcome: 'refused' | 'links-existing';
167
+ }
168
+ interface ImportPlan {
169
+ /** Origin and path only: no credentials, no query. */
170
+ source: {
171
+ url: string;
172
+ };
173
+ /** `import` is what the import's report will count; `source = import + refused + skipped`. */
174
+ counts: Record<ImportEntity, {
175
+ source: number;
176
+ import: number;
177
+ refused: number;
178
+ skipped: number;
179
+ }>;
180
+ /** Source fields the import never reads, by how many records carry a value for them. */
181
+ unmapped: Record<PlanEntity, Array<{
182
+ field: string;
183
+ records: number;
184
+ }>>;
185
+ collisions: PlanCollision[];
186
+ estimate: {
187
+ requests: {
188
+ api: number;
189
+ images: number;
190
+ };
191
+ meanRequestMs: number;
192
+ writes: number;
193
+ seconds: number;
194
+ };
195
+ wontMigrate: Array<{
196
+ item: string;
197
+ count: number | null;
198
+ why: string;
199
+ }>;
200
+ existingStore: 'checked' | {
201
+ notChecked: string;
202
+ };
203
+ resumeStateFound: boolean;
204
+ }
205
+
206
+ type WeightUnit = 'kg' | 'g' | 'lbs' | 'oz';
207
+ type DimensionUnit = 'm' | 'cm' | 'mm' | 'in' | 'yd';
208
+
209
+ declare class WooCommerceApiError extends Error {
210
+ readonly status: number;
211
+ constructor(status: number, message: string);
212
+ }
213
+ interface WcPage<T> {
214
+ items: T[];
215
+ total: number;
216
+ totalPages: number;
217
+ }
218
+ interface WcVariation {
219
+ id: number;
220
+ sku: string;
221
+ price: string;
222
+ regular_price: string;
223
+ sale_price: string;
224
+ on_sale: boolean;
225
+ date_on_sale_from: string | null;
226
+ date_on_sale_to: string | null;
227
+ /** 'parent' when the variation sells from its parent's stock; it then reports the parent's quantity. */
228
+ manage_stock: boolean | 'parent';
229
+ stock_quantity: number | null;
230
+ stock_status: string;
231
+ backorders: string;
232
+ low_stock_amount: number | null;
233
+ tax_status: string;
234
+ tax_class: string;
235
+ shipping_class: string;
236
+ status: string;
237
+ attributes: Array<{
238
+ id: number;
239
+ name: string;
240
+ option: string;
241
+ }>;
242
+ weight: string;
243
+ dimensions: {
244
+ length: string;
245
+ width: string;
246
+ height: string;
247
+ };
248
+ }
249
+ /** The WooCommerce store's own settings the catalogue is read in. */
250
+ interface WcStoreSettings {
251
+ currency: string;
252
+ weightUnit: WeightUnit;
253
+ dimensionUnit: DimensionUnit;
254
+ lowStockAmount: number;
255
+ }
256
+ interface WooCommerceClientOptions {
257
+ /** The clock each request is timed on (`requestStats`). */
258
+ now?: () => number;
259
+ }
260
+ declare class WooCommerceClient {
261
+ private readonly base;
262
+ private readonly auth;
263
+ private readonly now;
264
+ /** Every request sent so far, retries included, and their summed wall time. */
265
+ readonly requestStats: {
266
+ count: number;
267
+ ms: number;
268
+ };
269
+ constructor(creds: WooCommerceCredentials, opts?: WooCommerceClientOptions);
270
+ healthCheck(): Promise<void>;
271
+ /** A list's total from a one-item page; null when the endpoint refuses, fails, or answers with no list. */
272
+ getTotal(resource: string, params?: Record<string, string>): Promise<number | null>;
273
+ /** The length of an unpaginated list; null when the endpoint refuses, fails, or answers with no list. */
274
+ getListLength(resource: string): Promise<number | null>;
275
+ private getList;
276
+ paginate<T>(resource: string, params?: Record<string, string>, startPage?: number): AsyncGenerator<WcPage<T>>;
277
+ /**
278
+ * The currency (`/settings/general`), units and low-stock amount (`/settings/products`); null when either answer is
279
+ * not a 2xx list of settings carrying them. A key without settings access gets a 401 or 403 here.
280
+ */
281
+ getStoreSettings(): Promise<WcStoreSettings | null>;
282
+ /** A settings group as id → value; null when the answer is not a 2xx list. */
283
+ private getSettingsGroup;
284
+ getProductVariations(productId: number): Promise<WcVariation[]>;
285
+ private buildUrl;
286
+ private request;
287
+ private fetchWithRetry;
288
+ }
289
+
290
+ /** Which image URLs the import may request. */
291
+ interface ImagePolicy {
292
+ /** Every address `host` resolves to; the system resolver's by default. */
293
+ lookup?: (host: string) => Promise<string[]>;
294
+ /** The WooCommerce store's own host name, requested whatever its address (a store on the local network). */
295
+ allowHost?: string;
296
+ }
72
297
 
73
298
  interface WooCommerceImporterDeps {
74
299
  services: ServiceRegistry;
@@ -80,18 +305,297 @@ interface WooCommerceImporterDeps {
80
305
  };
81
306
  /** The store's media storage (`app.platform.media`): every product image is put here. */
82
307
  media: MediaStorage;
308
+ /** Resolves an image host to its addresses for the image policy; the system resolver by default. */
309
+ lookup?: ImagePolicy['lookup'];
83
310
  onProgress?: ProgressCallback;
84
311
  }
312
+ /** Why a store in another currency than the WooCommerce store's is refused, before anything is written. */
313
+ declare function currencyRefusal(sourceCurrency: string, storeCurrency: string): string;
85
314
  declare function runWooCommerceImport(opts: WooCommerceImportOptions, deps: WooCommerceImporterDeps): Promise<ImportReport>;
86
315
 
316
+ /** The time one record's write is assumed to take, until a measured figure replaces it. */
317
+ declare const WRITE_MS = 20;
318
+ type WooCommercePlanOptions = Pick<WooCommerceImportOptions, 'credentials' | 'entities' | 'gdpr' | 'currency' | 'concurrency'>;
319
+ interface WooCommercePlanDeps {
320
+ /** The target store, read-only; null when it could not be opened. */
321
+ existing: ExistingStoreLookup | null;
322
+ onProgress?: ProgressCallback;
323
+ /** The clock requests are timed on; `performance.now` by default. */
324
+ now?: () => number;
325
+ /** Each source record as read, before the plan watches its fields; a variation comes with its product's id. */
326
+ onRecord?: (entity: PlanEntity, record: Record<string, unknown>, parentWcId?: number) => void;
327
+ }
328
+ /**
329
+ * The import, simulated: what it would create, refuse and skip, what it never reads, and what it would cost, without
330
+ * writing anything. Records go through the import's own reads and mappers in id order, the import's order at
331
+ * concurrency 1; the target store is only asked whether it already holds a value.
332
+ */
333
+ declare function planWooCommerceImport(opts: WooCommercePlanOptions, deps: WooCommercePlanDeps): Promise<ImportPlan>;
334
+
335
+ /**
336
+ * Counts the source records brought over since the last `--fresh`: a customer linked to one the store already had is
337
+ * imported, though the rollback set holds only the records the import created.
338
+ */
87
339
  declare function buildReport(state: ImportState, startMs: number): ImportReport;
88
340
  declare function formatReport(report: ImportReport, storeName: string): string;
89
341
  declare function writeReport(report: ImportReport, projectRoot: string, storeName: string): Promise<string>;
90
342
 
343
+ type ImportSinceReason = 'invalid' | 'no-state' | 'no-finished-run' | 'not-finished' | 'fresh';
344
+ /** A `since` that cannot be resolved, or a state a delta cannot start on. */
345
+ declare class ImportSinceError extends Error {
346
+ readonly reason: ImportSinceReason;
347
+ constructor(reason: ImportSinceReason, message: string);
348
+ }
349
+ /**
350
+ * Each entity's `since`: for `last`, the start of the last finished pass that covered it; for a date or a zoned
351
+ * date-time, that instant. An entity no finished pass covered is read whole (`null`) under either: a delta creates only
352
+ * what the maps lack, so reading it whole is safe, and a date could miss what an unfinished pass never read.
353
+ */
354
+ declare function resolveSince(value: string, state: ImportState | null): SinceByEntity;
355
+
356
+ declare function formatPlan(plan: ImportPlan, storeName: string): string;
357
+ /** `nymbal-import-plan.json` and `nymbal-import-plan.md` in `projectRoot`. */
358
+ declare function writePlan(plan: ImportPlan, projectRoot: string, storeName: string): Promise<{
359
+ json: string;
360
+ markdown: string;
361
+ }>;
362
+
363
+ /** A state file that is there but cannot be read as a state: the run stops rather than start again and forget it. */
364
+ declare class ImportStateError extends Error {
365
+ readonly path: string;
366
+ constructor(path: string, reason: string);
367
+ }
368
+ /** A record an import created, appended once its create resolves, with what its import could not carry over. */
369
+ interface JournalEntry {
370
+ entity: ImportEntity;
371
+ id: string;
372
+ wcId: number;
373
+ /** Warning messages about the record, each reported under its entity and WooCommerce id. */
374
+ warnings?: string[];
375
+ /** Messages about the record's images that were not imported, each reported under `media` and its WooCommerce id. */
376
+ mediaWarnings?: string[];
377
+ }
378
+ /** The journal beside the state file: `.nymbal-migration.journal` for `.nymbal-migration.json`. */
379
+ declare function journalPathFor(statePath: string): string;
380
+ /** The saved state with its journal folded in; null only when there is no state file. */
91
381
  declare function loadState(statePath: string): Promise<ImportState | null>;
92
382
  declare function freshState(): ImportState;
383
+ /** Writes beside the target, syncs, then renames over it: the file at the path is always a whole state. */
93
384
  declare function saveState(statePath: string, state: ImportState): Promise<void>;
385
+ declare function appendJournal(statePath: string, entry: JournalEntry): Promise<void>;
386
+ /** Removes the state file and its journal. */
94
387
  declare function deleteState(statePath: string): Promise<void>;
95
388
 
96
- export { buildReport, deleteState, formatReport, freshState, loadState, runWooCommerceImport, saveState, writeReport };
97
- export type { ImportEntity, ImportReport, ImportState, ProgressCallback, ProgressEvent, WooCommerceCredentials, WooCommerceImportOptions, WooCommerceImporterDeps };
389
+ type RollbackRefusal = 'no-state' | 'live-store' | 'not-confirmed';
390
+ /** A rollback that removed nothing: there is no import to take out, the store has moved on, or no one agreed to it. */
391
+ declare class RollbackRefusedError extends Error {
392
+ readonly reason: RollbackRefusal;
393
+ /** For `live-store`: the store's own orders (or imported orders it has acted on) and reviews since the import. */
394
+ readonly orders?: number;
395
+ readonly reviews?: number;
396
+ constructor(reason: RollbackRefusal, message: string, activity?: {
397
+ orders: number;
398
+ reviews: number;
399
+ });
400
+ }
401
+ interface RollbackOptions {
402
+ statePath: string;
403
+ /** Asked once the rollback is allowed and before anything is removed; without it the rollback goes ahead. */
404
+ confirm?: (plan: RollbackPlan) => Promise<boolean>;
405
+ }
406
+ interface RollbackDeps {
407
+ services: ServiceRegistry;
408
+ repos: Repositories;
409
+ onProgress?: ProgressCallback;
410
+ }
411
+ /**
412
+ * Removes every record the imports in this project created, and nothing else, then the state file and its journal.
413
+ * Each removal is journaled as it commits, so a rollback stopped part way resumes where it stopped.
414
+ */
415
+ declare function rollbackImport(opts: RollbackOptions, deps: RollbackDeps): Promise<RollbackReport>;
416
+
417
+ type LighthouseMetric = 'performance' | 'lcpMs' | 'cls' | 'tbtMs' | 'bytes' | 'serverMs';
418
+ type LighthouseSample = {
419
+ ok: true;
420
+ metrics: Record<LighthouseMetric, number | null>;
421
+ lighthouseVersion?: string;
422
+ benchmarkIndex?: number | null;
423
+ } | {
424
+ ok: false;
425
+ reason: string;
426
+ };
427
+ interface LighthouseSide {
428
+ url: string | null;
429
+ runs: LighthouseSample[];
430
+ median: Record<LighthouseMetric, number | null> | null;
431
+ reason: string | null;
432
+ }
433
+ type LighthousePage = 'home' | 'product' | 'category';
434
+ interface LighthousePair {
435
+ page: LighthousePage;
436
+ source: LighthouseSide;
437
+ preview: LighthouseSide;
438
+ }
439
+ interface LighthouseSection {
440
+ lighthouseVersion: string;
441
+ formFactor: 'mobile';
442
+ throttling: 'simulate';
443
+ runs: number;
444
+ benchmarkIndex: number | null;
445
+ pairs: LighthousePair[];
446
+ }
447
+ declare const LIGHTHOUSE_METRICS: readonly LighthouseMetric[];
448
+ /** One Lighthouse result (its JSON output) as a sample: its metrics, or why it measured nothing. */
449
+ declare function readLighthouseResult(lhr: unknown): LighthouseSample;
450
+ /** One side of a pair: per metric, the median over the runs that measured it. */
451
+ declare function summariseSide(url: string | null, runs: LighthouseSample[]): LighthouseSide;
452
+ interface PlannedPair {
453
+ page: LighthousePage;
454
+ source: string | null;
455
+ preview: string | null;
456
+ reason: string | null;
457
+ }
458
+ /**
459
+ * The three pages compared: the store's home against the preview's, and the first listed product and the first
460
+ * category of the redirect map, each one WooCommerce record against its import. Nothing of `sourceUrl` past its path
461
+ * (userinfo, query, hash) reaches a URL.
462
+ */
463
+ declare function lighthousePairs(input: {
464
+ sourceUrl: string;
465
+ storefrontOrigin: string;
466
+ rows: RedirectRow[];
467
+ }): PlannedPair[];
468
+ /** The report's section: the Lighthouse version and benchmark index come from the first run that measured. */
469
+ declare function lighthouseSection(runs: number, pairs: LighthousePair[]): LighthouseSection;
470
+
471
+ type DiffField = 'name' | 'price' | 'variants' | 'images' | 'categories';
472
+ declare const DIFF_FIELDS: readonly DiffField[];
473
+ interface ProductDiff {
474
+ wcId: number;
475
+ slug: string;
476
+ name: string;
477
+ changes: Array<{
478
+ field: DiffField;
479
+ source: string;
480
+ preview: string;
481
+ }>;
482
+ }
483
+ interface RedirectRow {
484
+ from: string;
485
+ to: string;
486
+ status: 301;
487
+ }
488
+ interface Unredirected {
489
+ kind: 'product' | 'category';
490
+ wcId: number;
491
+ reason: string;
492
+ }
493
+ interface PreviewCounts {
494
+ source: number;
495
+ planned: number;
496
+ imported: number;
497
+ refused: number;
498
+ skipped: number;
499
+ /** What the preview's API serves: products and categories only, null for the rest. */
500
+ served: number | null;
501
+ }
502
+ /** What a preview found: the import's counts against what its storefront serves, and where the two differ. */
503
+ interface PreviewReport {
504
+ /** Origin and path only: no credentials, no query. */
505
+ source: {
506
+ url: string;
507
+ };
508
+ generatedAt: string;
509
+ currency: string;
510
+ entities: ImportEntity[];
511
+ counts: Record<ImportEntity, PreviewCounts>;
512
+ errors: ImportReport['errors'];
513
+ warnings: ImportWarning[];
514
+ unmapped: ImportPlan['unmapped'];
515
+ notListed: Array<{
516
+ wcId: number;
517
+ slug: string;
518
+ name: string;
519
+ }>;
520
+ differences: {
521
+ byField: Record<DiffField, number>;
522
+ products: ProductDiff[];
523
+ };
524
+ redirects: {
525
+ rows: number;
526
+ unredirected: Unredirected[];
527
+ duplicates: Array<{
528
+ from: string;
529
+ wcIds: number[];
530
+ }>;
531
+ };
532
+ /** Lighthouse on the source's pages against the preview's; null unless asked for. */
533
+ lighthouse: LighthouseSection | null;
534
+ }
535
+
536
+ type Rec$1 = Record<string, unknown>;
537
+ interface ServedProduct {
538
+ name: string;
539
+ priceRange: {
540
+ minMinor: number;
541
+ maxMinor: number;
542
+ };
543
+ variantCount: number;
544
+ media: unknown[];
545
+ categories: Array<{
546
+ slug: string;
547
+ }>;
548
+ }
549
+ /**
550
+ * The fields where what the preview serves differs from what WooCommerce sells, in the order name, price, variants,
551
+ * images, categories. Prices are compared as exact decimals against the served minor units: a source price the
552
+ * currency cannot hold shows as a difference, in WooCommerce's own digits.
553
+ */
554
+ declare function diffProduct(source: {
555
+ product: Rec$1;
556
+ variations: Rec$1[];
557
+ }, served: ServedProduct, currency: string): ProductDiff['changes'];
558
+
559
+ type Rec = Record<string, unknown>;
560
+ interface RedirectInput {
561
+ /** Every category WooCommerce holds: a category's URL holds its ancestors' slugs. */
562
+ sourceCategories: Rec[];
563
+ categories: Array<{
564
+ source: Rec;
565
+ nymbalSlug: string;
566
+ }>;
567
+ products: Array<{
568
+ source: Rec;
569
+ nymbalSlug: string;
570
+ listed: boolean;
571
+ }>;
572
+ }
573
+ interface Redirects {
574
+ rows: RedirectRow[];
575
+ unredirected: Unredirected[];
576
+ duplicates: Array<{
577
+ from: string;
578
+ wcIds: number[];
579
+ }>;
580
+ }
581
+ /**
582
+ * Each WooCommerce category's and listed product's URL to its Nymbal URL: categories first, then products, each in
583
+ * WooCommerce id order. A URL two records share keeps the first; the later ids are listed as duplicates. A product
584
+ * with no page of its own on the storefront, or served under a plain permalink (a query a host cannot match on a
585
+ * path), gets no row and is listed with the reason.
586
+ */
587
+ declare function buildRedirects(input: RedirectInput): Redirects;
588
+ /** `from,to,status` and a line per row, RFC 4180: a field holding a comma, quote or line break is quoted. */
589
+ declare function formatRedirectsCsv(rows: RedirectRow[]): string;
590
+
591
+ /** The preview report as Markdown: counts, what to review, errors, differences, drafts, redirects, unmapped fields. */
592
+ declare function formatPreviewReport(report: PreviewReport, storeName: string): string;
593
+ /** `nymbal-preview-report.json`, `nymbal-preview-report.md` and `nymbal-redirects.csv` in `projectRoot`. */
594
+ declare function writePreview(report: PreviewReport, rows: RedirectRow[], projectRoot: string, storeName: string): Promise<{
595
+ json: string;
596
+ markdown: string;
597
+ csv: string;
598
+ }>;
599
+
600
+ export { DIFF_FIELDS, ImportSinceError, ImportStateError, LIGHTHOUSE_METRICS, RollbackRefusedError, WRITE_MS, WooCommerceApiError, WooCommerceClient, appendJournal, buildRedirects, buildReport, currencyRefusal, deleteState, diffProduct, formatPlan, formatPreviewReport, formatRedirectsCsv, formatReport, freshState, journalPathFor, lighthousePairs, lighthouseSection, loadState, planWooCommerceImport, readLighthouseResult, resolveSince, rollbackImport, runWooCommerceImport, saveState, summariseSide, writePlan, writePreview, writeReport };
601
+ export type { CollisionKind, DiffField, ExistingStoreLookup, FinishedPass, ImportEntity, ImportPlan, ImportReport, ImportSinceReason, ImportState, ImportWarning, JournalEntry, LighthouseMetric, LighthousePage, LighthousePair, LighthouseSample, LighthouseSection, LighthouseSide, PlanCollision, PlanEntity, PlannedPair, PreviewCounts, PreviewReport, ProductDiff, ProgressCallback, ProgressEvent, RedirectInput, RedirectRow, Redirects, RollbackDeps, RollbackOptions, RollbackPlan, RollbackRefusal, RollbackReport, ServedProduct, SinceByEntity, Unredirected, WooCommerceCredentials, WooCommerceImportOptions, WooCommerceImporterDeps, WooCommercePlanDeps, WooCommercePlanOptions };