@contentrain/wp-import 0.5.7 → 0.7.0

package/README.md

@@ -37,6 +37,7 @@ const commentsExport = buildCommentsExport(raw, entry_source_map)
 - **UTC dates** — GMT columns preferred, stamped ISO 8601 `Z`.
 - **Pure conversion** — `rawToContentrain` returns a canonical-serialized file map (sorted keys, 2-space indent, trailing newline); writing to disk is the caller's one line.
 - **EntrySourceMap produced at the only place that can know it** — the WP-id → entry-address mapping the comments intake requires.
+- **Only public discussion leaves the site** — `buildCommentsExport` carries comments on published, unprotected entries that are approved or pending (pending lands in the receiver's moderation queue). Comments on drafts, private, scheduled or password-protected entries, any other status (spam, trash, `post-trashed`, a plugin's) and entries the import does not hold, stay behind; `excluded` counts them.
 
 Streaming WXR parse (sax): a 100 MB export holds only its records in memory.
 
@@ -101,6 +102,36 @@ these before claiming a complete migration. ACF field/group records and their
 cross-model parents remain in the content store; route discovery decides which
 records become public pages. Importing configuration does not execute a plugin.
 
+### Site name over REST
+
+`fetchRestRawIR` reads the `/wp-json/` index for the site's name and tagline
+(`RawIR.site.title` / `description`, the store's `site` singleton) and its
+install and public addresses (`base_site_url` / `base_blog_url`). An index that
+does not answer leaves them out.
+
+### Menus over REST
+
+With an Application Password, `fetchRestRawIR` reads the site's menus into
+`RawIR.menus`: classic menus (`/wp/v2/menus` + `/wp/v2/menu-items`, with the
+theme locations each is assigned to) and a block theme's published
+`wp_navigation` posts (links, submenus, page lists, home links). A block menu's
+`locations` are the template-part areas (`header`, `footer`) whose navigation
+block refers to it; an empty navigation block without a `ref` shows the most
+recent published one, as WordPress does. Block menu items have no WordPress id
+and get negative ids; the store claims no `wp_id` for them.
+
+A menu item that is itself a draft, or whose post target is not proven public
+— a draft, pending, private, scheduled or password-protected post, or one this
+import never read (a type outside REST, a listing past a page cap) — is left
+out, fail-closed: its label is often that post's title. Its children move up to the
+nearest kept ancestor; `warnings` gives only the count.
+
+Both need `edit_theme_options`. Without a credential, with a rejected one, or
+with a user who lacks that right, no menus are read and the result's `gaps`
+contains `menus_require_auth` — an empty menu list is never presented as the
+site having none. The `menus` model gains a `locations` field only when the
+source named them.
+
 
 ### Publication and translation identity
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { CommentsExport, EntrySourceMap, HandoffComments, RawIR, SourceDeltaPlan } from "@contentrain/types";
+import { CommentsExport, EntrySourceMap, HandoffComments, RawComment, RawIR, SourceDeltaPlan } from "@contentrain/types";
 import { Readable } from "node:stream";
 
 //#region src/wxr.d.ts
@@ -55,6 +55,24 @@ interface RestImportOptions {
 interface RestImportResult {
   raw: RawIR;
   warnings: string[];
+  /**
+   * Whether the credential was honoured, for callers that must act on it
+   * without reading `warnings`. `none`: no `auth` given. `accepted`: every
+   * listing it unlocks was read with it. `rejected`: at least one was not —
+   * `fell_back` names each (`posts`, `pages`, a CPT's rest base, `comments`,
+   * `comments:hold`), and those came from the public listing instead, or not
+   * at all for `comments:hold`, which has none.
+   */
+  credential: {
+    status: 'none' | 'accepted' | 'rejected';
+    fell_back: string[];
+  };
+  /**
+   * What this rung could not read, as codes a caller can act on (the text is in `warnings`).
+   * `menus_require_auth`: menus and block navigation are only readable with an application password
+   * of a user who may edit theme options — none was given, the site rejected it, or it lacks that right.
+   */
+  gaps: string[];
 }
 declare function fetchRestRawIR(options: RestImportOptions): Promise<RestImportResult>;
 //#endregion
@@ -95,6 +113,16 @@ declare function rawToContentrain(raw: RawIR, opts?: {
 }): ContentrainResult;
 //#endregion
 //#region src/comments.d.ts
+/**
+ * The comments that may leave the source site (see `CommentsExport.comments`). An allowlist, so it
+ * fails closed: a comment travels only when its entry is in this RawIR and public, and its status is
+ * approved (`'1'`, or none) or pending (`'0'`). Everything else is counted in `excluded`: spam, trash,
+ * WordPress's `post-trashed`, a plugin's own status, a post this RawIR does not hold.
+ */
+declare function selectComments(raw: RawIR): {
+  comments: RawComment[];
+  excluded: NonNullable<CommentsExport['excluded']>;
+};
 declare function buildCommentsExport(raw: RawIR, entries: EntrySourceMap, opts?: {
   generated_at?: string;
 }): CommentsExport;
@@ -178,5 +206,5 @@ declare function planSourceDelta(input: PlanSourceDeltaInput): SourceDeltaPlan;
 /** The plan as text, for a dry run: one line per record, then conflicts, unmapped records, redirects and warnings. */
 declare function formatSourceDeltaReport(plan: SourceDeltaPlan): string;
 //#endregion
-export { type ContentrainResult, DEFAULT_IMPORTERS, DEFAULT_TAXONOMIES, type DeltaStore, type ImportReport, PLUGIN_META, type PlanSourceDeltaInput, type RestImportOptions, type RestImportResult, SKIP_TYPES, type UnserializeResult, type WxrParseResult, type WxrStats, buildCommentsExport, canon, fetchRestRawIR, formatSourceDeltaReport, hexId, looksSerialized, parseWxr, phpUnserialize, planSourceDelta, rawToContentrain, slugify, strip, summarizeComments, taxModelId, tryUnserialize };
+export { type ContentrainResult, DEFAULT_IMPORTERS, DEFAULT_TAXONOMIES, type DeltaStore, type ImportReport, PLUGIN_META, type PlanSourceDeltaInput, type RestImportOptions, type RestImportResult, SKIP_TYPES, type UnserializeResult, type WxrParseResult, type WxrStats, buildCommentsExport, canon, fetchRestRawIR, formatSourceDeltaReport, hexId, looksSerialized, parseWxr, phpUnserialize, planSourceDelta, rawToContentrain, selectComments, slugify, strip, summarizeComments, taxModelId, tryUnserialize };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/wxr.ts","../src/rest.ts","../src/contentrain.ts","../src/comments.ts","../src/php-unserialize.ts","../src/core.ts","../src/delta.ts"],"mappings":";;;;UA2BiB,QAAA;EACf,UAAA;IAAc,QAAA;IAAkB,OAAA;IAAiB,MAAA;IAAgB,IAAA;EAAA;EACjE,UAAA;EACA,gBAAA;EACA,MAAA,EAAQ,MAAA;AAAA;AAAA,UAGO,cAAA;EACf,GAAA,EAAK,KAAA;EACL,KAAA,EAAO,QAAA;AAAA;AAAA,iBAiBa,QAAA,CAAS,KAAA,WAAgB,QAAA,EAAU,IAAA;EAAS,IAAA;AAAA,IAAkB,OAAA,CAAQ,cAAA;;;UCtC3E,iBAAA;EACf,MAAA;;EAEA,SAAA,UAAmB,KAAA;EDSI;;;;;;;;ECAvB,IAAA;IAAS,IAAA;IAAc,WAAA;EAAA;EACvB,OAAA;EDGc;AAGhB;;;;ECAE,WAAA;EDCK;;;;ECIL,QAAA;EACA,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,GAAA,EAAK,KAAA;EACL,QAAA;AAAA;AAAA,iBA6CoB,cAAA,CAAe,OAAA,EAAS,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;;;UC/DzD,YAAA;EACf,cAAA;EACA,aAAA;EACA,cAAA;EACA,WAAA,EAAa,MAAA;EACb,UAAA,EAAY,MAAA;EACZ,aAAA;EACA,iBAAA;EACA,MAAA,EAAQ,MAAA;IAAiB,IAAA;IAAc,MAAA;IAAgB,MAAA;IAAgB,OAAA;EAAA;EFJvE;EEMA,OAAA;EFNc;EEQd,kBAAA;EFLe;;;;;;EEYf,yBAAA;AAAA;AAAA,UAGe,iBAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;EAClB,MAAA,EAAQ,YAAA;AAAA;AAAA,iBAoCM,gBAAA,CAAiB,GAAA,EAAK,KAAA,EAAO,IAAA;EAAS,SAAA;AAAA,IAAuB,iBAAA;;;iBChF7D,mBAAA,CAAoB,GAAA,EAAK,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,IAAA;EAAS,YAAA;AAAA,IAA0B,cAAA;AHmB5G;AAAA,iBGJgB,iBAAA,CAAkB,GAAA,EAAK,cAAA,GAAiB,eAAA;;;UCnBvC,iBAAA;EACf,EAAA;EACA,UAAA;EACA,KAAA;EACA,KAAA;AAAA;AAAA,iBAGc,eAAA,CAAgB,CAAA,YAAa,CAAA;AAAA,iBAI7B,cAAA,CAAe,GAAA;;iBAyFf,cAAA,CAAe,CAAA,WAAY,iBAAA;;;cC9F9B,KAAA,GAAS,CAAA;;cAST,KAAA,GAAS,CAAA;;cAcT,KAAA,GAAS,CAAA;;;;;;;;;ALCtB;cK8Ba,UAAA,EAAU,MAAA;;cAIV,WAAA,EAAW,MAAA;;cAOX,UAAA,GAAc,CAAA;AAAA,cAGd,OAAA,GAAW,CAAA;;;;UC3DP,UAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;AAAA;AAAA,UAGH,oBAAA;ENOD;EMLd,KAAA,EAAO,eAAA;ENEO;EMAd,KAAA,EAAO,UAAA;ENA0C;EMEjD,QAAA,GAAW,UAAA;ENDX;;;;;EMOA,UAAA;ENFe;;;;EMOf,SAAA;AAAA;AAAA,cAGW,kBAAA;AAAA,cACA,iBAAA;;;ANQb;;;;;;;;;;iBM8NgB,eAAA,CAAgB,KAAA,EAAO,oBAAA,GAAuB,eAAA;;iBAkC9C,uBAAA,CAAwB,IAAA,EAAM,eAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/wxr.ts","../src/rest.ts","../src/contentrain.ts","../src/comments.ts","../src/php-unserialize.ts","../src/core.ts","../src/delta.ts"],"mappings":";;;;UA2BiB,QAAA;EACf,UAAA;IAAc,QAAA;IAAkB,OAAA;IAAiB,MAAA;IAAgB,IAAA;EAAA;EACjE,UAAA;EACA,gBAAA;EACA,MAAA,EAAQ,MAAA;AAAA;AAAA,UAGO,cAAA;EACf,GAAA,EAAK,KAAA;EACL,KAAA,EAAO,QAAA;AAAA;AAAA,iBAiBa,QAAA,CAAS,KAAA,WAAgB,QAAA,EAAU,IAAA;EAAS,IAAA;AAAA,IAAkB,OAAA,CAAQ,cAAA;;;UCrC3E,iBAAA;EACf,MAAA;;EAEA,SAAA,UAAmB,KAAA;EDQI;;;;;;;;ECCvB,IAAA;IAAS,IAAA;IAAc,WAAA;EAAA;EACvB,OAAA;EDEc;AAGhB;;;;ECCE,WAAA;EDAK;;;;ECKL,QAAA;EACA,IAAA;AAAA;AAAA,UAGe,gBAAA;EACf,GAAA,EAAK,KAAA;EACL,QAAA;EDOkF;;;;;;;;ECElF,UAAA;IAAc,MAAA;IAA0C,SAAA;EAAA;;;AAvC1D;;;EA6CE,IAAA;AAAA;AAAA,iBAkDoB,cAAA,CAAe,OAAA,EAAS,iBAAA,GAAoB,OAAA,CAAQ,gBAAA;;;UCpFzD,YAAA;EACf,cAAA;EACA,aAAA;EACA,cAAA;EACA,WAAA,EAAa,MAAA;EACb,UAAA,EAAY,MAAA;EACZ,aAAA;EACA,iBAAA;EACA,MAAA,EAAQ,MAAA;IAAiB,IAAA;IAAc,MAAA;IAAgB,MAAA;IAAgB,OAAA;EAAA;EFJvE;EEMA,OAAA;EFNc;EEQd,kBAAA;EFLe;;;;;;EEYf,yBAAA;AAAA;AAAA,UAGe,iBAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;EAClB,MAAA,EAAQ,YAAA;AAAA;AAAA,iBAoCM,gBAAA,CAAiB,GAAA,EAAK,KAAA,EAAO,IAAA;EAAS,SAAA;AAAA,IAAuB,iBAAA;;;;;;AF7D7E;;;iBGbgB,cAAA,CAAe,GAAA,EAAK,KAAA;EAAU,QAAA,EAAU,UAAA;EAAc,QAAA,EAAU,WAAA,CAAY,cAAA;AAAA;AAAA,iBAgB5E,mBAAA,CAAoB,GAAA,EAAK,KAAA,EAAO,OAAA,EAAS,cAAA,EAAgB,IAAA;EAAS,YAAA;AAAA,IAA0B,cAAA;;iBAiB5F,iBAAA,CAAkB,GAAA,EAAK,cAAA,GAAiB,eAAA;;;UC3CvC,iBAAA;EACf,EAAA;EACA,UAAA;EACA,KAAA;EACA,KAAA;AAAA;AAAA,iBAGc,eAAA,CAAgB,CAAA,YAAa,CAAA;AAAA,iBAI7B,cAAA,CAAe,GAAA;;iBAyFf,cAAA,CAAe,CAAA,WAAY,iBAAA;;;cC9F9B,KAAA,GAAS,CAAA;;cAST,KAAA,GAAS,CAAA;;cAcT,KAAA,GAAS,CAAA;;;;;;;;;ALCtB;cK8Ba,UAAA,EAAU,MAAA;;cAIV,WAAA,EAAW,MAAA;;cAOX,UAAA,GAAc,CAAA;AAAA,cAGd,OAAA,GAAW,CAAA;;;;UC3DP,UAAA;EACf,KAAA,EAAO,MAAA;EACP,gBAAA,EAAkB,cAAA;AAAA;AAAA,UAGH,oBAAA;ENOD;EMLd,KAAA,EAAO,eAAA;ENEO;EMAd,KAAA,EAAO,UAAA;ENA0C;EMEjD,QAAA,GAAW,UAAA;ENDX;;;;;EMOA,UAAA;ENFe;;;;EMOf,SAAA;AAAA;AAAA,cAGW,kBAAA;AAAA,cACA,iBAAA;;;ANQb;;;;;;;;;;iBM8NgB,eAAA,CAAgB,KAAA,EAAO,oBAAA,GAAuB,eAAA;;iBAkC9C,uBAAA,CAAwB,IAAA,EAAM,eAAA"}