@pterodoc/wordpress 0.2.0

package/LICENCE.md

@@ -0,0 +1,10 @@
+Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+Copyright (c) Onyx <hello@onyx.ac> (https://onyx.ac)
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License. You are free to share and adapt this work, including
+commercially, provided you give appropriate attribution and distribute any
+derivative works under the same license.
+
+Full legal text: https://creativecommons.org/licenses/by-sa/4.0/legalcode

package/README.md

@@ -0,0 +1,10 @@
+# @pterodoc/wordpress
+
+The WordPress REST target for [pterodoc](https://github.com/onyx-ac/pterodoc): pages
+identified by parent and slug, media keyed by content hash, and pruning that trashes
+rather than deletes.
+
+You probably want the [`pterodoc`](https://www.npmjs.com/package/pterodoc) package
+instead.
+
+Licensed CC-BY-SA-4.0.

package/lib/client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * A small WordPress REST client, scoped to what publishing needs.
+ *
+ * Authentication is an Application Password over HTTP Basic. `fetch` and the
+ * clock are injectable so the whole sync can be tested without a network.
+ */
+/** Fields needed to compare a remote page with a rendered one. */
+export declare const PAGE_FIELDS = "id,parent,slug,status,link,title,menu_order,template";
+/** Those, plus the content only fetched when a page is about to be compared. */
+export declare const FULL_PAGE_FIELDS = "id,parent,slug,status,link,title,menu_order,template,content,excerpt,meta";
+/** How hard to try again when WordPress is busy. */
+export interface RetryPolicy {
+    /** Extra attempts after the first. */
+    attempts: number;
+    /** Delay before the first retry, doubling after that. */
+    baseDelayMs: number;
+    /** Longest delay to wait, however far the backoff has grown. */
+    maxDelayMs: number;
+}
+/** The retry policy used when a site configures none. */
+export declare const DEFAULT_RETRY: RetryPolicy;
+/** What the client needs to reach a site. */
+export interface WpClientOptions {
+    /** Site origin, without a trailing slash. */
+    baseUrl: string;
+    /** WordPress username. */
+    user?: string;
+    /** An Application Password; display spaces are removed. */
+    appPassword?: string;
+    /** Polylang language code, sent as a `lang` parameter. */
+    lang?: string;
+    /** Send DELETE as POST with an override header, for hosts that block DELETE. */
+    methodOverride?: boolean;
+    /** How hard to retry. */
+    retry?: RetryPolicy;
+    /** Injected for tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Injected for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Called with progress worth seeing under `--verbose`. */
+    log?: (message: string) => void;
+}
+/** One request, before it is sent. */
+interface RequestOptions {
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    /** A multipart body, used for media uploads. */
+    form?: FormData;
+}
+export declare class WpClient {
+    private readonly baseUrl;
+    private readonly user;
+    private readonly appPassword;
+    private readonly lang;
+    private readonly methodOverride;
+    private readonly retry;
+    private readonly doFetch;
+    private readonly sleep;
+    private readonly log;
+    /** How many requests have been made, for the run summary. */
+    requestCount: number;
+    constructor(options: WpClientOptions);
+    /** Headers every request carries. */
+    private headers;
+    /**
+     * Perform one REST call, retrying only what is worth retrying.
+     */
+    request<T = unknown>(method: 'GET' | 'POST' | 'DELETE', path: string, options?: RequestOptions): Promise<{
+        data: T;
+        headers: Headers;
+    }>;
+    /** Follow `X-WP-TotalPages` to the end of a collection. */
+    listAll<T>(path: string, query: Record<string, string | number>): Promise<T[]>;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/lib/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,kEAAkE;AAClE,eAAO,MAAM,WAAW,yDAAyD,CAAC;AAElF,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,8EAAwC,CAAC;AAEtE,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yDAAyD;AACzD,eAAO,MAAM,aAAa,EAAE,WAAoE,CAAC;AAEjG,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yBAAyB;IACzB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,0BAA0B;IAC1B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,2DAA2D;IAC3D,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,sCAAsC;AACtC,UAAU,cAAc;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;IAEhD,6DAA6D;IAC7D,YAAY,SAAK;gBAEL,OAAO,EAAE,eAAe;IAYpC,qCAAqC;IACrC,OAAO,CAAC,OAAO;IASf;;OAEG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAiGzC,2DAA2D;IACrD,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;CAerF"}

package/lib/index.d.ts

@@ -0,0 +1,49 @@
+/** The WordPress target. */
+import { renderNavigationStub } from '@pterodoc/core/render';
+import type { Target, TargetCapabilities } from '@pterodoc/core/target';
+import { type RetryPolicy } from './client';
+import { type WordpressUrlPolicy } from './url';
+/** What WordPress can do. */
+export declare const WORDPRESS_CAPABILITIES: TargetCapabilities;
+/** Content a page holds between being created and being rendered. */
+declare const PLACEHOLDER = "<!-- wp:paragraph -->\n<p>Publishing\u2026</p>\n<!-- /wp:paragraph -->";
+/** How to reach and shape a WordPress site. */
+export interface WordpressTargetOptions {
+    /** Site origin. */
+    url: string;
+    /** Username of the Application Password. */
+    user: string;
+    /** The Application Password. */
+    appPassword: string;
+    /** Where the tree hangs and how versions and locales are addressed. */
+    policy: WordpressUrlPolicy;
+    /** Status applied to every synced page. */
+    status: 'publish' | 'draft' | 'private';
+    /** Page template slug, or empty for the theme default. */
+    template: string;
+    /** Polylang language code. */
+    lang: string;
+    /** Prefix of the slug that identifies uploaded media. */
+    mediaSlugPrefix: string;
+    /** Send DELETE as POST with an override header. */
+    methodOverride: boolean;
+    /** Retry policy. */
+    retry?: RetryPolicy;
+}
+/** Injected so the target can be exercised without a network. */
+export interface WordpressTargetDeps {
+    fetch?: typeof globalThis.fetch;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (message: string) => void;
+}
+/** Create the WordPress target. */
+export declare function createWordpressTarget(options: WordpressTargetOptions, deps?: WordpressTargetDeps): Target;
+export { splitOwnership, hrefFor, prefixSegments } from './url';
+export type { WordpressUrlPolicy } from './url';
+export { WpClient, DEFAULT_RETRY } from './client';
+export { detectPlugin } from './plugin';
+export type { PluginStatus } from './plugin';
+export type { RetryPolicy, WpClientOptions } from './client';
+export { renderNavigationStub };
+export { PLACEHOLDER };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAE5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAOV,MAAM,EACN,kBAAkB,EAEnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAarE,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAEzE,6BAA6B;AAC7B,eAAO,MAAM,sBAAsB,EAAE,kBAUpC,CAAC;AAEF,qEAAqE;AACrE,QAAA,MAAM,WAAW,2EAAsE,CAAC;AAExF,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,mBAAmB;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,2CAA2C;IAC3C,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,cAAc,EAAE,OAAO,CAAC;IACxB,oBAAoB;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,mCAAmC;AACnC,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,IAAI,GAAE,mBAAwB,GAC7B,MAAM,CAwLR;AAED,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAChE,YAAY,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,CAAC"}